HumanTime (A grabbag of wonderful things. 1.8.1 API)

java.lang.Object
- com.eaio.util.text.HumanTime

All Implemented Interfaces:

Externalizable, Serializable, Cloneable, Comparable<HumanTime>
```
public class HumanTime
extends Object
implements Externalizable, Comparable<HumanTime>, Cloneable
```
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 5084 2012-08-09 19:11:04Z johann $

Author:

Johann Burkard

See Also:
eval(CharSequence), approximately(CharSequence), Date Formatting and Parsing for Humans in Java with HumanTime, Serialized Form

Constructor Summary

Constructors
Constructor and Description

HumanTime()
No-argument Constructor for HumanTime.

HumanTime(long delta)
Constructor for HumanTime.

Constructors
Constructor and Description
`HumanTime()` No-argument Constructor for HumanTime.
`HumanTime(long delta)` Constructor for HumanTime.

Method Summary

Methods
Modifier and Type	Method and Description
`static String`	`approximately(CharSequence in)` Parses and formats the given char sequence, potentially removing some data to make the output easier to understand.
`static String`	`approximately(long l)` Formats the given time delta, preserving all data.
`Object`	`clone()` Deep-clones this object.
`int`	`compareTo(HumanTime t)` Compares this HumanTime to another HumanTime.
`HumanTime`	`d()` Adds one day to the time delta.
`HumanTime`	`d(int n)` Adds n days to the time delta.
`boolean`	`equals(Object obj)`
`static HumanTime`	`eval(CharSequence s)` Parses a `CharSequence` argument and returns a `HumanTime` instance.
`static String`	`exactly(CharSequence in)` Parses and formats the given char sequence, preserving all data.
`static String`	`exactly(long l)` Formats the given time delta, preserving all data.
`String`	`getApproximately()` Returns an approximate, human-formatted representation of the time delta.
`<T extends Appendable> T`	`getApproximately(T a)` Appends an approximate, human-formatted representation of the time delta to the given `Appendable` object.
`long`	`getDelta()` Returns the time delta.
`String`	`getExactly()` Returns a human-formatted representation of the time delta.
`<T extends Appendable> T`	`getExactly(T a)` Appends a human-formatted representation of the time delta to the given `Appendable` object.
`HumanTime`	`h()` Adds one hour to the time delta.
`HumanTime`	`h(int n)` Adds n hours to the time delta.
`int`	`hashCode()` Returns a 32-bit representation of the time delta.
`HumanTime`	`m()` Adds one month to the time delta.
`HumanTime`	`m(int n)` Adds n months to the time delta.
`HumanTime`	`ms()` Adds one millisecond to the time delta.
`HumanTime`	`ms(int n)` Adds n milliseconds to the time delta.
`void`	`readExternal(ObjectInput in)`
`HumanTime`	`s()` Adds one second to the time delta.
`HumanTime`	`s(int n)` Adds n seconds to the time delta.
`String`	`toString()` Returns a String representation of this.
`void`	`writeExternal(ObjectOutput out)`
`HumanTime`	`y()` Adds one year to the time delta.
`HumanTime`	`y(int n)` Adds n years to the time delta.

Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

- 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
  - 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
    
    See Also:
    Object.equals(java.lang.Object)
  - hashCode
```
public int hashCode()
```
    Returns a 32-bit representation of the time delta.
    
    Overrides:
    
    hashCode in class Object
    
    See Also:
    Object.hashCode()
  - toString
```
public String toString()
```
    Returns a String representation of this.
    The output is identical to getExactly().
    
    Overrides:
    
    toString in class Object
    
    Returns:
    a String, never null
    See Also:
    Object.toString(), getExactly()
  - compareTo
```
public int compareTo(HumanTime t)
```
    Compares this HumanTime to another HumanTime.
    
    Specified by:
    
    compareTo in interface Comparable<HumanTime>
    
    Parameters:
    t - the other instance, may not be null
    
    Returns:
    which one is greater
  - clone
```
public Object clone()
             throws CloneNotSupportedException
```
    Deep-clones this object.
    
    Overrides:
    
    clone in class Object
    
    Throws:
    
    CloneNotSupportedException
    See Also:
    Object.clone()
  - readExternal
```
public void readExternal(ObjectInput in)
                  throws IOException
```
    Specified by:
    
    readExternal in interface Externalizable
    
    Throws:
    
    IOException
    See Also:
    Externalizable.readExternal(java.io.ObjectInput)
  - writeExternal
```
public void writeExternal(ObjectOutput out)
                   throws IOException
```
    Specified by:
    
    writeExternal in interface Externalizable
    
    Throws:
    
    IOException
    See Also:
    Externalizable.writeExternal(java.io.ObjectOutput)

Class HumanTime

Using HumanTime

HumanTime format

HumanTime examples

Implementation details

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

HumanTime

HumanTime

Method Detail

eval

exactly

exactly

approximately

approximately

y

y

d

d

h

h

m

m

s

s

ms

ms

getExactly

getExactly

getApproximately

getApproximately

getDelta

equals

hashCode

toString

compareTo

clone

readExternal

writeExternal