date_time/data

# Generating

https://github.com/fmidev/smartmet-timezones/tree/master/bin provided
a method to generate the content, which uses an unlicence, so it was
copied into this repository for posterity and future use.

    ./create_date_time_zoneinfo.sh > date_time_zonespec.csv

# Compatibility

The current version is IANA 2025b.

Previous versions of the data file (IANA 2016c) had short and long special
names but only for America/Chicago, America/Denver, America/Los_Angeles,
America/New_York, America/Phoenix, but time zones like America/Detroit,
America/Fort_Wayne, America/Indiana/Petersburg, etc... did not; when
regenerating for IANA 2025b the short and long names became identical
for those previously mentions time zones.

# File Format

The csv file containing the zone_specs used by the 
boost::local_time::tz_database is intended to be customized by the 
library user. When customizing this file (or creating your own) the 
file must follow a specific format.

This first line is expected to contain column headings and is therefore 
not processed by the tz_database.

Each record (line) must have eleven fields. Some of those fields can 
be empty. Every field (even empty ones) must be enclosed in double-quotes. 
Ex:
  "America/Phoenix" <- string enclosed in quotes
  ""                <- empty field

Some fields represent a length of time. The format of these fields must be: 
  "{+|-}hh:mm[:ss]" <- length-of-time format
Where the plus or minus is mandatory and the seconds are optional.

Since some time zones do not use daylight savings it is not always necessary 
for every field in a zone_spec to contain a value. All zone_specs must have 
at least ID and GMT offset. Zones that use daylight savings must have all 
fields filled except: STD ABBR, STD NAME, DST NAME. You should take note 
that DST ABBR is mandatory for zones that use daylight savings (see field 
descriptions for further details).


********* Fields and their description/details ********* 

* ID 
        Contains the identifying string for the zone_spec. Any string will
        do as long as it's unique. No two ID's can be the same. 

* STD ABBR
* STD NAME
* DST ABBR
* DST NAME
        These four are all the names and abbreviations used by the time 
        zone being described. While any string will do in these fields, 
        care should be taken. These fields hold the strings that will be 
        used in the output of many of the local_time classes. 
        Ex:
        time_zone nyc = tz_db.time_zone_from_region("America/New_York");
        local_time ny_time(date(2004, Aug, 30), IS_DST, nyc);
        cout << ny_time.to_long_string() << endl;
        // 2004-Aug-30 00:00:00 Eastern Daylight Time
        cout << ny_time.to_short_string() << endl;
        // 2004-Aug-30 00:00:00 EDT
        
        NOTE: The exact format/function names may vary - see local_time 
        documentation for further details.

* GMT offset
        This is the number of hours added to utc to get the local time 
        before any daylight savings adjustments are made. Some examples 
        are: America/New_York offset -5 hours, & Africa/Cairo offset +2 hours.
        The format must follow the length-of-time format described above.

* DST adjustment
        The amount of time added to gmt_offset when daylight savings is in 
        effect. The format must follow the length-of-time format described
        above.

#####################################################################
##### TODO: more rule capabilities are needed - this portion of #####
##### the tz_database is incomplete                             ##### 
#####################################################################
* DST Start Date rule
        This is a specially formatted string that describes the day of year
        in which the transition take place. It holds three fields of it's own,
        separated by semicolons. 
        * The first field indicates the "nth" weekday of the month. The
                possible values are: 1 (first), 2 (second), 3 (third), 
                4 (fourth), 5 (fifth), and -1 (last).
        * The second field indicates the day-of-week from 0-6 (Sun=0).
        * The third field indicates the month from 1-12 (Jan=1).
        
        Examples are: "-1;5;9"="Last Friday of September", 
        "2;1;3"="Second Monday of March"

* Start time
        Start time is the number of hours past midnight, on the day of the
        start transition, the transition takes place. More simply put, the 
        time of day the transition is made (in 24 hours format). The format
        must follow the length-of-time format described above with the 
        exception that it must always be positive.

* DST End date rule
        See DST Start date rule. The difference here is this is the day 
        daylight savings ends (transition to STD).
* End time
        Same as Start time.