README.zone_spec_csv_file
1
2The csv file containing the zone_specs used by the
3boost::local_time::tz_database is intended to be customized by the
4library user. When customizing this file (or creating your own) the
5file must follow a specific format.
6
7This first line is expected to contain column headings and is therefore
8not processed by the tz_database.
9
10Each record (line) must have eleven fields. Some of those fields can
11be empty. Every field (even empty ones) must be enclosed in double-quotes.
12Ex:
13 "America/Phoenix" <- string enclosed in quotes
14 "" <- empty field
15
16Some fields represent a length of time. The format of these fields must be:
17 "{+|-}hh:mm[:ss]" <- length-of-time format
18Where the plus or minus is mandatory and the seconds are optional.
19
20Since some time zones do not use daylight savings it is not always necessary
21for every field in a zone_spec to contain a value. All zone_specs must have
22at least ID and GMT offset. Zones that use daylight savings must have all
23fields filled except: STD ABBR, STD NAME, DST NAME. You should take note
24that DST ABBR is mandatory for zones that use daylight savings (see field
25descriptions for further details).
26
27
28********* Fields and their description/details *********
29
30* ID
31 Contains the identifying string for the zone_spec. Any string will
32 do as long as it's unique. No two ID's can be the same.
33
34* STD ABBR
35* STD NAME
36* DST ABBR
37* DST NAME
38 These four are all the names and abbreviations used by the time
39 zone being described. While any string will do in these fields,
40 care should be taken. These fields hold the strings that will be
41 used in the output of many of the local_time classes.
42 Ex:
43 time_zone nyc = tz_db.time_zone_from_region("America/New_York");
44 local_time ny_time(date(2004, Aug, 30), IS_DST, nyc);
45 cout << ny_time.to_long_string() << endl;
46 // 2004-Aug-30 00:00:00 Eastern Daylight Time
47 cout << ny_time.to_short_string() << endl;
48 // 2004-Aug-30 00:00:00 EDT
49
50 NOTE: The exact format/function names may vary - see local_time
51 documentation for further details.
52
53* GMT offset
54 This is the number of hours added to utc to get the local time
55 before any daylight savings adjustments are made. Some examples
56 are: America/New_York offset -5 hours, & Africa/Cairo offset +2 hours.
57 The format must follow the length-of-time format described above.
58
59* DST adjustment
60 The amount of time added to gmt_offset when daylight savings is in
61 effect. The format must follow the length-of-time format described
62 above.
63
64#####################################################################
65##### TODO: more rule capabilities are needed - this portion of #####
66##### the tz_database is incomplete #####
67#####################################################################
68* DST Start Date rule
69 This is a specially formatted string that describes the day of year
70 in which the transition take place. It holds three fields of it's own,
71 separated by semicolons.
72 * The first field indicates the "nth" weekday of the month. The
73 possible values are: 1 (first), 2 (second), 3 (third),
74 4 (fourth), 5 (fifth), and -1 (last).
75 * The second field indicates the day-of-week from 0-6 (Sun=0).
76 * The third field indicates the month from 1-12 (Jan=1).
77
78 Examples are: "-1;5;9"="Last Friday of September",
79 "2;1;3"="Second Monday of March"
80
81* Start time
82 Start time is the number of hours past midnight, on the day of the
83 start transition, the transition takes place. More simply put, the
84 time of day the transition is made (in 24 hours format). The format
85 must follow the length-of-time format described above with the
86 exception that it must always be positive.
87
88* DST End date rule
89 See DST Start date rule. The difference here is this is the day
90 daylight savings ends (transition to STD).
91* End time
92 Same as Start time.
93