An extremely fast parser and formatter of standardized date-times.
Date and time formats cause a lot of confusion and interoperability problems on the Internet. This document addresses many of the problems encountered and makes recommendations to improve consistency and interoperability when representing and using date and time in Internet protocols.
This project's goal it to do one thing and to do it right; make it easy to handle Date and Time on the Internet: Timestamps and W3C Date and Time Formats in Java.
- No external dependencies, minimalistic JAR
- Apache license
- Configurable validator, formatter and parser within the boundaries of the specification
- Correct time-zone handling
- High test coverage
- Very high performance
| Implementation | Parse | Format |
|---|---|---|
| java.util (Java 7) * | 742 850 parse/sec | 1 837 811 format/sec |
| java.time (Java 8) | 545 333 parse/sec | 2 101 431 format/sec |
| Apache FastDateUtils * | 1 076 995 parse/sec | 1 989 163 format/sec |
| Internet Time Utility | 15 569 458 parse/sec | 12 726 932 format/sec |
- Single hard-coded format. Lenient parsing would require multiple patterns to be attempted (4-6).
Your milage may vary. The tests are included in this repository.
// Parse a string
final OffsetDateTime dateTime = ITU.parseDateTime("2012-12-27T19:07:22.123456789-03:00");
// Format with no fraction digits
final String formatted = ITU.formatUtc(dateTime); // 2012-12-27T22:07:22Z
// Format with microsecond precision
final String formattedMicro = ITU.formatUtcMicro(dateTime); // 2012-12-27T22:07:22.123457ZWhy this little project?
There are an endless amount of APIs with non-standard date/time exchange, and the goal of this project is to make it a no-brainer to do-the-right-thing(c).
Why the performance optimized version?
Some projects use epoch time-stamps for date-time exchange, and from a performance perspective this may make sense in some cases. With this project one can do-the-right-thing and maintain performance in date-time handling.
What is wrong with epoch timestamps?
- It is not human-readable, so debugging and direct manipulation is harder
- Limited resolution and/or time-range available
- Unclear resolution and/or time-range
RFC-3339 is a subset/profile defined by W3C of the formats defined in ISO-8601, to simplify date and time exhange in modern Internet protocols.
Typical formats include:
2017-12-27T23:45:32Z- No fractional seconds, UTC/Zulu time2017-12-27T23:45:32.999Z- Millisecond fractions, UTC/Zulu time2017-12-27T23:45:32.999999Z- Microsecond fractions, UTC/Zulu time2017-12-27T23:45:32.999999999Z- Nanosecond fractions, UTC/Zulu time2017-12-27T18:45:32-05:00- No fractional seconds, EST time2017-12-27T18:45:32.999-05:00- Millisecond fractions, EST time2017-12-27T18:45:32.999999-05:00- Microsecond fractions, EST time2017-12-27T18:45:32.999999999-05:00- Nanosecond fractions, EST time
Date and Time Formats is a note, meaning it is not endorsed, but it still serves as a sane subset of ISO-8601, just like RFC-3339.
Typical formats include:
2017-12-27T23:45Z- Minute resolution, UTC/Zulu time2017-12-27- Date only, no timezone (like someones birthday)2017-12- Year and month only. Like an expiry date.
For the sake of avoiding data integrity issues, this library will not allow offset of -00:00.
Such offset is described in RFC3339 section 4.3., named "Unknown Local Offset Convention". Such offset is explicitly prohibited in ISO-8601 as well.
If the time in UTC is known, but the offset to local time is unknown, this can be represented with an offset of "-00:00". This differs semantically from an offset of "Z" or "+00:00", which imply that UTC is the preferred reference point for the specified time.
Since Java's java.time classes do not support storing leap seconds, ITU will throw a LeapSecondException if one is encountered to signal that this is a leap second. The exception can then be queried for the second-value. Storing such values is not possible in a java.time.OffsetDateTime, the 60 is therefore abandoned and the date-time will use 59 instead of 60.