introduction

this article describes a simple .net api for using the zoneinfo database, which is also known as the tz database or olson database.

i hope you find it useful :)

background

i have been developing a web site which schedules meetings and events across multiple time zones for more than a year now.

i previously used the .net publicdomain library discussed in another codeproject article but had a number of issues including:

• just not working for australia
• it seems to hard code in the tz database rather than reading it from the file system; therefore if you need to update the database you need to wait for the source code to be updated
• the library seems to have a lot of other things in it which i just don't need (which is not a major issue though)

one of the big things i wanted was to have an api which ad the latest tz database and off i go.

i am not a big fan of reinventing the wheel so if this library just isn't needed please let me know :)

using the code

talking a fairly agile approach to this i have just implemented the apis which i have needed.

the interface itself is extremely simple and hopefully is well illustrated by the examples below:

loading the data

// load all the files
database.loadfiles(@"c:\src\trunk\timezonetest\tzdata");

before you start to use any of the functions, you need to make sure that the database of files are loaded.

right now .tab files in the timeinfo distribution are not loaded but they are needed for the current set of apis.

getting the local time somewhere else

// iterate through all the zone strings
foreach (string zonename in database.getzonenames())
{
    zone z = database.getzone(zonename);

    console.writeline("zone: " + z.name
                        + "\n\thas a local date time of "
                        + z.now.tostring()
                        + "\n\twhich is a gmt offset of "
                        + z.getutcoffset(z.now).tostring());
}

the sample above gets all the time zones names and then gets the corresponding zoneinfo.zone instance.

from this instance you get do a number of things like getting the local time in that zone and its current utc offset.

zone: europe/malta
        has a local date time of 8/04/2008 9:40:52 am
        which is a gmt offset of 02:00:00
zone: europe/minsk
        has a local date time of 8/04/2008 10:40:52 am
        which is a gmt offset of 03:00:00
zone: europe/monaco
        has a local date time of 8/04/2008 9:40:52 am
        which is a gmt offset of 02:00:00
zone: europe/moscow
        has a local date time of 8/04/2008 11:40:52 am
        which is a gmt offset of 04:00:00 

convert times between time zones

// what is the time in sao paulo when it is new years day in melbourne?
zone melbtz = database.getzone("australia/melbourne");
zone sptz = database.getzone("america/sao_paulo");

datetime melbtime = new datetime(2009, 1, 1, 0, 0, 0, datetimekind.local);
datetime utctime = melbtz.converttoutc(melbtime);
datetime sptime = sptz.converttolocal(utctime);

console.writeline("melbourne " + melbtime.tostring()
                  + "\nsao paulo " + sptime.tostring()
                  + "\nutc " + utctime.tostring());

one of the most useful features of the api is the ability to convert arbitrary dates between time zones. a lot of timezone apis only really know what the utc offset is right now, not 6 months from now.

melbourne 1/01/2009 12:00:00 am
sao paulo 31/12/2008 11:00:00 am
utc 31/12/2008 1:00:00 pm

offset cut-over windows

// what are all the timezone cutover windows for melbourne in the last few years?
list<datetime> dates =
         melbtz.getcutoverwindows(
                     new datetime(2007, 1, 1, 0, 0, 0, datetimekind.local),
                     new datetime(2009, 12, 31, 23, 59, 59, datetimekind.local));

console.writeline("printing cutovers between 1/1/2007 - 31/12/2009");
foreach (datetime dt in dates)
{
     console.writeline("\t" + dt.tostring());
}

this functionality may seem useless ... until you actually need it.

if you store dates in the database in utc and need to convert them to the local time of the user you need to apply a utc offset. what happens if the day light offset changes within this window? well, you can know if this is the case rather than assuming that it doesn't matter.

printing cutovers between 1/1/2007 - 31/12/2009
        30/03/2007 2:00:00 am
        27/10/2007 2:00:00 am
        6/04/2008 2:00:00 am
        5/10/2008 2:00:00 am
        5/04/2009 2:00:00 am
        4/10/2009 2:00:00 am  

points of interest

the code seems to work well for australia and the other zones i have tested this with. i am sure as more people use it in different scenarios it will continue to mature.

one thing i did notice was just how un-standard the format of the tz database was with respect to tab and space delimiting of fields ... the code has a number of hacks unfortunately to compensate this.

history

there are still a number of things to be done including:

- handling of link entries in the files. the current format allows for backward compatibility in the old names. this is not hard to do and will happen soon (or if someone needs it).

more information

check out the latest version of the code at http://www.codeplex.com/zoneinfo.

if you have any issues please log it there and i will look at any changes which need to get done.