Module com.erudika.para.core
Package com.erudika.para.core.utils

Class HumanTime

java.lang.Object
com.erudika.para.core.utils.HumanTime
All Implemented Interfaces:
Externalizable, Serializable, Comparable<HumanTime>
public final class HumanTime extends Object implements Externalizable, Comparable<HumanTime>
HumanTime parses and formats time deltas for easier reading by humans. It can format time information without losing information but its main purpose is to generate more easily understood approximations. Using HumanTime

Use HumanTime by creating an instance that contains the time delta (HumanTime(long)), create an empty instance through (HumanTime()) and set the delta using the y(), d(), h(), s() and ms() methods or parse a CharSequence representation (eval(CharSequence)). Parsing ignores whitespace and is case insensitive.

HumanTime format

HumanTime will format time deltas in years ("y"), days ("d"), hours ("h"), minutes ("m"), seconds ("s") and milliseconds ("ms"), separated by a blank character. For approximate representations, the time delta will be round up or down if necessary.

HumanTime examples
  • HumanTime.eval("1 d 1d 2m 3m").getExactly() = "2 d 5 m"
  • HumanTime.eval("2m8d2h4m").getExactly() = "8 d 2 h 6 m"
  • HumanTime.approximately("2 d 8 h 20 m 50 s") = "2 d 8 h"
  • HumanTime.approximately("55m") = "1 h"
Implementation details
  • The time delta can only be increased.
  • Instances of this class are thread safe.
  • Getters using the Java Beans naming conventions are provided for use in environments like JSP or with expression languages like OGNL. See getApproximately() and getExactly().
  • To keep things simple, a year consists of 365 days.
Version:
$Id: HumanTime.java 3906 2011-05-21 13:56:05Z johann $
Author:
Johann Burkard
See Also:

  • Constructor Details

    • HumanTime

      public HumanTime()
      No-argument Constructor for HumanTime.

      Equivalent to calling new HumanTime(0L).

    • HumanTime

      public HumanTime(long delta)
      Constructor for HumanTime.
      Parameters:
      delta - the initial time delta, interpreted as a positive number

  • Method Details

    • eval

      public static HumanTime eval(CharSequence s)
      Parses a CharSequence argument and returns a HumanTime instance.
      Parameters:
      s - the char sequence, may not be null
      Returns:
      an instance, never null

    • exactly

      public static String exactly(CharSequence in)
      Parses and formats the given char sequence, preserving all data.

      Equivalent to eval(in).getExactly()

      Parameters:
      in - the char sequence, may not be null
      Returns:
      a formatted String, never null

    • exactly

      public static String exactly(long l)
      Formats the given time delta, preserving all data.

      Equivalent to new HumanTime(in).getExactly()

      Parameters:
      l - the time delta
      Returns:
      a formatted String, never null

    • approximately

      public static String approximately(CharSequence in)
      Parses and formats the given char sequence, potentially removing some data to make the output easier to understand.

      Equivalent to eval(in).getApproximately()

      Parameters:
      in - the char sequence, may not be null
      Returns:
      a formatted String, never null

    • approximately

      public static String approximately(long l)
      Formats the given time delta, preserving all data.

      Equivalent to new HumanTime(l).getApproximately()

      Parameters:
      l - the time delta
      Returns:
      a formatted String, never null

    • y

      public HumanTime y()
      Adds one year to the time delta.
      Returns:
      this HumanTime object

    • y

      public HumanTime y(int n)
      Adds n years to the time delta.
      Parameters:
      n - n
      Returns:
      this HumanTime object

    • d

      public HumanTime d()
      Adds one day to the time delta.
      Returns:
      this HumanTime object

    • d

      public HumanTime d(int n)
      Adds n days to the time delta.
      Parameters:
      n - n
      Returns:
      this HumanTime object

    • h

      public HumanTime h()
      Adds one hour to the time delta.
      Returns:
      this HumanTime object

    • h

      public HumanTime h(int n)
      Adds n hours to the time delta.
      Parameters:
      n - n
      Returns:
      this HumanTime object

    • m

      public HumanTime m()
      Adds one month to the time delta.
      Returns:
      this HumanTime object

    • m

      public HumanTime m(int n)
      Adds n months to the time delta.
      Parameters:
      n - n
      Returns:
      this HumanTime object

    • s

      public HumanTime s()
      Adds one second to the time delta.
      Returns:
      this HumanTime object

    • s

      public HumanTime s(int n)
      Adds n seconds to the time delta.
      Parameters:
      n - seconds
      Returns:
      this HumanTime object

    • ms

      public HumanTime ms()
      Adds one millisecond to the time delta.
      Returns:
      this HumanTime object

    • ms

      public HumanTime ms(int n)
      Adds n milliseconds to the time delta.
      Parameters:
      n - n
      Returns:
      this HumanTime object

    • getExactly

      public String getExactly()
      Returns a human-formatted representation of the time delta.
      Returns:
      a formatted representation of the time delta, never null

    • getExactly

      public <T extends Appendable> T getExactly(T a)
      Appends a human-formatted representation of the time delta to the given Appendable object.
      Type Parameters:
      T - the return type
      Parameters:
      a - the Appendable object, may not be null
      Returns:
      the given Appendable object, never null

    • getApproximately

      public String getApproximately()
      Returns an approximate, human-formatted representation of the time delta.
      Returns:
      a formatted representation of the time delta, never null

    • getApproximately

      public <T extends Appendable> T getApproximately(T a)
      Appends an approximate, human-formatted representation of the time delta to the given Appendable object.
      Type Parameters:
      T - the return type
      Parameters:
      a - the Appendable object, may not be null
      Returns:
      the given Appendable object, never null

    • getDelta

      public long getDelta()
      Returns the time delta.
      Returns:
      the time delta

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • compareTo

      public int compareTo(HumanTime t)
      Specified by:
      compareTo in interface Comparable<HumanTime>

    • readExternal

      public void readExternal(ObjectInput in) throws IOException
      Specified by:
      readExternal in interface Externalizable
      Throws:
      IOException

    • writeExternal

      public void writeExternal(ObjectOutput out) throws IOException
      Specified by:
      writeExternal in interface Externalizable
      Throws:
      IOException