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

Class 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:
    eval(CharSequence), approximately(CharSequence), Date Formatting and Parsing for Humans in Java with HumanTime, Serialized Form

    • Constructor Detail

      • 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 Detail

      • 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

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object