Wednesday, November 30, 2011

Version 1.1.3 (stable) of the Time2 Library brings a new utility

A new version of the Time2 Library is available at and

This new release comes with a small utility for scanning dates and times in arbitrary formats. Here is a quick usage example:

String pattern = 
  "\\S+ (\\S+) (\\d+) (\\d\\d):(\\d\\d):(\\d\\d) \S+ (\\d\\d\\d\\d)";
int[] groups = {6, 1, 2, 3, 4, 5};
String[] months = 
     {"Jan", "Feb", "Mar", "Apr", "May", "Jun", 
      "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"};
DateTimeScanner scanner = new DateTimeScanner(pattern, groups);
TimeIndex time = scanner.scan("Wed Nov 30 12:29:23 CET 2010");
assertEquals("2010-11-30 12:29:23", time.toString());

Monday, October 10, 2011

Version 1.1.2 (stable) of the Time2 Library supports ISO 8601

A new version of the Time2 Library is available at and

This new release brings improved support for the representation of dates and times as defined by the ISO 8601:2004 standard. Basic and extended date and time strings are allowed. In the extended format, the current time, as I'm writing, is represented as 2011-10-10T12:42:53Z. The Z indicates UTC time. The same time in the basic format is written 20111010T124253Z. Because time zones and daylight savings time are irrelevant in the Time2 Library, the Z letter can be omitted.

When using the extended format, the T separating date and time can be replaced with a blank. So the example can also be represented as 2011-10-10 12:42:53, arguably nicer on the eye. This more natural format is used by Time2.toString().

Local times can be specified using a time zone offset. For example, I am writing this from Switzerland, where the time zone is CEST, 2 hours ahead of UTC. In the ISO 8601:2004 standard, this can be written 2011-10-10T14:42:53-02.

There are some exotic features in the ISO 8601 standard. Some of them, like leap seconds or the use of hour 24 for midnight, are supported. Others, like week dates and ordinal dates are not.

Monday, October 3, 2011

Why make it complicated when you can make it impossible?

Dates and times may be quite familiar but when you need to do something with them, especially in software, you are confronted with a glorious mess. To get an idea, spend a few moments on the subject in Wikipedia, Google, or the Java documentation. Here are some of the things you will find.

There is no year zero, except when there is one...

If you are a historian, there is no year 0. The year AD 1 immediately follows the year 1 BC (see Anno Domini in Wikipedia). On the other hand, if you are an astronomer, there is a year 0 (see Astronomical year numbering in Wikipedia). In the ISO 8601 international standard for representing dates and times, years are represented by four digits from 0000 to 9999. So, if you are following the standard, there is a year 0. But with XML, there is a problem. XML time was inspired by an early version of ISO 8601 and disallows year 0. Fortunately, this is likely to change in the future to agree with more recent versions of ISO 8601. See XML Schema Part 2: Datatypes Second Edition from W3C.

If you have an ancestor born on October 10, 1582, stick to the ISO standard!

In some countries, October 15, 1582 immediately followed October 4 (see Gregorian calendar in Wikipedia). The ISO 8601 international standard states that every date must be consecutive and that dates before October 15 1582 can be used by mutual agreement when exchanging information. So, under the standard, there would have been no hole between October 4 and 15, 1582, and your ancestor would have been born on an existing day.

Some minutes have 61 seconds

Nowadays, time is measured with atomic clocks (see Coordinated Universal Time (UTC) in Wikipedia). Atomic time does not exactly match the earth's rotation and a so-called leap second can be added or substracted from UTC at the end of June or December to avoid the discrepancy growing beyond a second. So, minutes have 59, 60, or 61 seconds. For more information on leap seconds, consult Date and Time on the Internet: Timestamps (RFC3339) at the IETF, and Leap Seconds at the US Naval Observatory. Note because it is not known long in advance when one will be introduced, leap seconds cannot be programmed in software.

Avoid the Dutch calendar between 1909 and 1937

When using local time, time zones and daylight savings time are issues to consider. The fact that most methods of the Java Date class are deprecated shows that getting such things right is not straightforward. Calendar and Joda Time are better, but their complexity can be seen as further proof that dates and times are messy. The ISO 8601 standard attempts to sidestep the whole question by not supporting time zones at all. Time is either local or expressed as an offset from UTC. But even then, there is a problem. The offset used by the ISO standard is in hours and minutes. But there are known cases where this is not sufficient. Here is a quote from RFC 3339:


This represents the same instant of time as noon, January 1, 1937,
Netherlands time. Standard time in the Netherlands was exactly 19
minutes and 32.13 seconds ahead of UTC by law from 1909-05-01 through
1937-06-30. This time zone cannot be represented exactly using the
HH:MM format, and this timestamp uses the closest representable UTC

The Y2.038K problem

If you thought the year 2000 problem was interesting, then you will like 2038, when the Unix clock will wrap around. Such problems and many facts about dates and times are documented in Gilbert Healton's The Best of Dates, The Worst Of Dates.

Time and the Time2 Library

When I wrote the Time2 Library, I was looking for something lightweight to represent dates and the time of day. Dates and times are only a small part of what the library does and I did not want to spend too much time on time. But I was not happy with Java's Date because it is mostly deprecated. Other possible solutions were not exactly lightweight. So I decided to write my own solution and to keep it simple, with the requirement to implement part of the ISO 8601 specification (ignoring durations and intervals): all years between 0000 and 9999 valid, no hole in October 1582, no support for time zones and daylight savings time, but tolerance for time zone offsets and leap seconds (the last two things are still on the to-do list.)

Wednesday, September 21, 2011

Version 1.1.1 (stable) of the Time2 Library released

A new version of the Time2 Library is available at and

This release brings improved time comparisons. Previously it was not possible to compare times from different domains. Now, when domain differs, times are converted automatically.

When resolutions differ, the time with the lowest resolution is converted to the one with the highest resolution. For example comparing a Day to a Year will compare the day to the implicit default day of the year (which is January 1).

When resolutions do not differ, the times are converted to the unrestricted time domain for their resolution. For example a Workday and a ThirdFriday are both converted to a Day before comparing.

These semantics are not meaningful for all possible time domains. Users of "exotic" time domains should consider writing a subclass of Time2 and override the compareTo method.

Thursday, September 1, 2011

StockChart: combining the Time2 Library with JFreeChart

A demo package for the Time2 library was released on September 1. It includes StockChart, a program to create price and volume charts for stocks. For this it relies heavily on JFreeChart, a flexible and powerful Java library for drawing charts. Charts can be saved as PNG images or as vector graphics in SVG files, thanks to Apache Batik.

The demo uses example files from Foo & Bar, Inc (trading symbol FBI), a company invented for the occasion. Here is a PNG chart produced by the demo:


Clicking on the image shows the SVG version of the chart. If your browser supports SVG (like Firefox) you will be able to scale the image by resizing the window without reducing the picture quality.

The demo can be downloaded from SourceForge or from the project website.

As noted in the chart title, FBI quotes have not been adjusted for stock splits.
The halving of the price on March 18 looks suspiciously like a 2:1 ("two for one") split. A future version of the demo will take care of this problem.

Monday, August 22, 2011

Version 1.1.0 (stable) of the Time2 Library released

A new version of the Time2 Library is available at and I have clarified the rule on nulls. In one sentence, it is illegal to put a null into a time series unless null was defined as the representative of missing values for the type. The rule was already present in previous versions, but it is now better documented, and also covers Filler callbacks.

Unlike announced in my previous post, the new version number is 1.1.0 and not 1.0.1. Increasing the medium version number signals the presence of incompatible modifications, in this case the addition of a throws clause to two (rarely used) methods of TimeIndexable. Details are available in the release notes included in the software.

With this release, the software leaves beta status and is now stable.

Coming soon is a little demo of time series with graphics!

Wednesday, August 17, 2011

Version 1.0.0 (beta) of Time2 Library released

A slightly modified version of the Time2 Library is available at and I have added a README file and release notes. The names of distribution files now include version numbers.

Version 1.0.1 is expected for next week. It will come without the "beta" qualifier.

Monday, July 25, 2011

Welcome to the Time Series Software blog !

This blog is for notes and short articles about the Time2 Library, a piece of Java software I wrote and released ten days ago as an open source project. There will also be more general material related to time series software and applications.