Skip to content

Latest commit

 

History

History
95 lines (70 loc) · 5.26 KB

README.md

File metadata and controls

95 lines (70 loc) · 5.26 KB
Raw

Internet Time Utility

Maven Central Hex.pm Coverage StatusBuild Status Codacy Badge

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.

Features

  • 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

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.

Example use

// 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.123457Z

Q & A

Why 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

What is RFC-3339?

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 time
  • 2017-12-27T23:45:32.999Z - Millisecond fractions, UTC/Zulu time
  • 2017-12-27T23:45:32.999999Z - Microsecond fractions, UTC/Zulu time
  • 2017-12-27T23:45:32.999999999Z - Nanosecond fractions, UTC/Zulu time
  • 2017-12-27T18:45:32-05:00 - No fractional seconds, EST time
  • 2017-12-27T18:45:32.999-05:00 - Millisecond fractions, EST time
  • 2017-12-27T18:45:32.999999-05:00 - Microsecond fractions, EST time
  • 2017-12-27T18:45:32.999999999-05:00 - Nanosecond fractions, EST time

What is W3C - Date and Time Formats

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 time
  • 2017-12-27 - Date only, no timezone (like someones birthday)
  • 2017-12 - Year and month only. Like an expiry date.

Limitations

Local offset

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.

Leap second parsing

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.