Date Formatting and Parsing for Humans in Java with HumanTime

Posted 2008-10-07 in Java by Johann.

Many applications deal with time. For example by

• printing how long a task will take,
• logging timing information or
• letting users enter time intervals.

For a programmer, the system time in milliseconds is the fastest and easiest way to work with time.

The problem is that understanding and working with milliseconds is easy for computers, but not for humans.

HumanTime changes this.

HumanTime formats and parses time in a way that is easier to read and understand.

Examples

81299 ms versus 1 m 21 s
1222940000 ms versus 14 d 3 h

Which time representation is easier to understand?

Applications that do this well include Jenkins and Twitter:

Get HumanTime

Download HumanTime and the test case.

HumanTime has no dependencies besides Java 5. As usual, the code is released under the MIT License (OSI certified).

Using HumanTime

After downloading HumanTime, create a package called com.eaio.util.text and put HumanTime.java there. You’re done.

Formatting Time

There are two ways to display time in a human-readable format: An approximate and an exact representation. You should use the approximate representation unless you are sure the user is interested in the exact time.

// You’ve found that the job will take 56720083 milliseconds
LOG.info("This job will take " + HumanTime.approximately(56720083L));
// Prints "This job will take 15 h 45 m"

An exactly method is provided for the exact representation.

// You’ve found that the job will take 56720083 milliseconds
LOG.info("This job will take exactly " + HumanTime.exactly(28391L));
// Prints "This job will take exactly 15 h 45 m 20 s 83 ms"

Parsing Time

HumanTime also parses time from user input. The input can contain the time symbols y, d, h, s and ms. Whitespace is ignored, times are cumulative and parsing is case insensitive. An example:

HumanTime t = HumanTime.eval("29 m 30m 100 ms");
LOG.info(t.getApproximately()); // Will print "1 h"
// Or simply use
LOG.info(HumanTime.approximately("29 m 30m 100 ms"));

Other HumanTime Properties

HumanTime instances are thread-safe and can be serialized. In addition to the methods described above, HumanTime instances can also be created directly and modified through the d(), d(int n), h(), h(int n) methods which add one day, n days, one hour and n hours respectively.

Summary

Working with time in a way that is easy for computers is not always easy to understand for humans. HumanTime makes time easier to read and understand.

4 comments