Introduction -- Header -- Construction -- Accessors -- Data File Details Introduction The local_time system depends on the ability to store time zone information. Our Time Zone Database (tz_database) is a means of permanently storing that data. The specifications for many time zones (377 at this time) are provided. These specifications are based on data found in the zoneinfo datebase. The specifications are stored in the file:libs/date_time/data/date_time_zonespec.csv. While this file already contains specifications for many time zones, it's real intent is for the user to modify it by adding (or removing) time zones to fit their application. See Data File Details to learn how this is accomplished. Header The inclusion of a single header will bring in all boost::local_time types, functions, and IO operators. #include "boost/date_time/local_time/local_time.hpp" Construction The only constructor takes no arguments and creates an empty database. It is up to the user to populate the database. This is typically achieved by loading the desired datafile, but can also be accomplished by means of the add_record(...) function (see the Accessors table). A local_time::data_not_accessible exception will be thrown if given zonespec file cannot be found. local_time::bad_field_count exception will be thrown if the number of fields in given zonespec file is incorrect. Syntax Description tz_database() Constructor creates an empty database. tz_database tz_db; bool load_from_file(std::string) Parameter is path to a time zone spec csv file (see Data File Details for details on the contents of this file). This function populates the database with time zone records found in the zone spec file. A local_time::data_not_accessible exception will be thrown if given zonespec file cannot be found. local_time::bad_field_count exception will be thrown if the number of fields in given zonespec file is incorrect. tz_database tz_db; tz_db.load_from_file("./date_time_zonespec.csv"); Accessors Syntax Description Example bool tz_db.add_record(std::string id, time_zone_ptr tz); Adds a time_zone, or a posix_time_zone, to the database. ID is the region name for this zone (Ex: "America/Phoenix"). time_zone_ptr zone( new posix_time_zone("PST-8PDT,M4.1.0,M10.1.0") ); std::string id("America/West_Coast"); tz_db.add_record(id, zone); time_zone_ptr tz_db.time_zone_from_region(string id); Returns a time_zone, via a time_zone_ptr, that matches the region listed in the data file. A null pointer is returned if no match is found. time_zone_ptr nyc = tz_db.time_zone_from_region("America/New_York"); vector<string> tz_db.region_list(); Returns a vector of strings that holds all the region ID strings from the database. std::vector<std::string> regions; regions = tz_db.region_list(); Data File Details Field Description/Details 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). Field 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. 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, and 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. NOTE: 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.