Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. — Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

PrevUpHomeNext

Local Time

Time Zone (abstract)
Posix Time Zone
Time Zone Database
Custom Time Zone
Local Date Time
Local Time Period

Local Time System

Introduction -- Usage Examples

Introduction

The library supports 4 main extensions for the management of local times. This includes

local_date_time -- locally adjusted time point
posix_time_zone -- time zone defined by posix string (eg: "EST10EDT,M10.5.0,M3.5.0/03")
time_zone_database -- get time zones by region from .csv file (eg: America/New York)
time_zone -- abstract time zone interface

Together, these extensions define a time system adjusted for recording times related to a specific earth location. This time system utilizes all the features and benefits of the posix_time system (see posix_time for full details). It uses a time_zone object which contains all the necessary data/rules to enable adjustments to and from various time zones. The time_zone objects used in date_time are handled via a boost::shared_ptr<boost::local_time::time_zone>.

The phrase "wall-clock" refers to the time that would be shown on a wall clock in a particular time zone at any point in time. Local_time uses a time zone object to account for differences in time zones and daylight savings adjustments. For example: While 5:00 pm, October 10, 2004 in Sydney Australia occurs at exactly the same instant as 3:00 am, October 10, 2004 in New York USA, it is a 14 hour difference in wall-clock times. However, a point in time just one day later will result in a 16 hour difference in wall-clock time due to daylight savings adjustments in both time zones. The local_time system tracks these by means of a time point, stored as UTC, and time_zone objects that contain all the necessary data to correctly calculate wall-clock times.

Usage Examples

Example Description
Simple Time Zone Side by side examples of Time Zone usage. Both custom_time_zone and posix_time_zone are shown.
Daylight Savings Calc Rules Simple example showing the creation of all five dst_calc_rule types.
Seconds Since Epoch Example that calculates the total seconds elapsed since the epoch (1970-Jan-01) utilizing local_date_time.

Time Zone (abstract)

Introduction -- Header -- Construction -- Accessors

Introduction

The time_zone_base class is an abstract base class template for representing time zones. Time zones are a set of data and rules that provide information about a time zone. The date_time library handles time_zones by means of a boost::shared_ptr<time_zone_base>. A user's custom time zone class will work in the date_time library by means of this shared_ptr.

For convienience, the time_zone_base class is typedef'd as time_zone. All references in the documentation to time_zone, are referring to this typedef.

Header

The time_zone_base class is defined in the header: 

#include "boost/date_time/time_zone_base.hpp"

Construction

A default constructor is provided in the time_zone_base class. There are no private data members in this base class to initialize.

Template parameters are time_type (typically posix_time::ptime) and CharT (defaults to char).

Accessors

All of the accessors listed here are pure virtual functions.

Syntax Description 
string_type dst_zone_abbrev();
 Returns the daylight savings abbreviation for the represented time zone. 
string_type std_zone_abbrev();
 Returns the standard abbreviation for the represented time zone. 
string_type dst_zone_name();
 Returns the daylight savings name for the represented time zone. 
string_type std_zone_name();
 Returns the standard name for the represented time zone. 
bool has_dst();
 Returns true if this time zone does not make a daylight savings shift. 
time_type dst_local_start_time(year_type);
 The date and time daylight savings time begins in given year. 
time_type dst_local_end_time(year_type);
 The date and time daylight savings time ends in given year. 
time_duration_type base_utc_offset();
 The amount of time offset from UTC (typically in hours). 
time_duration_type dst_offset();
 The amount of time shifted during daylight savings. 
std::string to_posix_string();
 Returns a posix time zone string representation of this time_zone_base object. For a detailed description of a posix time zone string see posix_time_zone.

Posix Time Zone

Introduction -- Important Notes -- Header -- Construction -- Accessors

Introduction

A posix_time_zone object is a set of data and rules that provide information about a time zone. Information such as the offset from UTC, it's name and abbreviation, as well as daylight savings rules, called dst_calc_rules. These rules are stored as a boost::shared_ptr<dst_calc_rules>.

As a convenience, a typedef for shared_ptr<dst_calc_rules> is provided. 

typedef boost::shared_ptr<dst_calc_rules> local_time::dst_calc_rule_ptr;

A posix_time_zone is unique in that the object is created from a Posix time zone string (IEEE Std 1003.1). A POSIX time zone string takes the form of:


      "std offset dst [offset],start[/time],end[/time]" (w/no spaces).

'std' specifies the abbrev of the time zone. 'offset' is the offset from UTC. 'dst' specifies the abbrev of the time zone during daylight savings time. The second offset is how many hours changed during DST. 'start' and 'end' are the dates when DST goes into (and out of) effect. 'offset' takes the form of:


      [+|-]hh[:mm[:ss]] {h=0-23, m/s=0-59}

'time' and 'offset' take the same form. 'start' and 'end' can be one of three forms:


      Mm.w.d {month=1-12, week=1-5 (5 is always last), day=0-6}
      Jn {n=1-365 Feb29 is never counted}
      n {n=0-365 Feb29 is counted in leap years}

Exceptions will be thrown under the following conditions:

  • An exception will be thrown for an invalid date spec (see date class).
  • A boost::local_time::bad_offset exception will be thrown for:
  • A DST start or end offset that is negative or more than 24 hours.
  • A UTC zone that is greater than +14 or less than -12 hours.
  • A boost::local_time::bad_adjustment exception will be thrown for a DST adjustment that is 24 hours or more (positive or negative)

As stated above, the 'offset' and '/time' portions of the string are not required. If they are not given they default to 01:00 for 'offset', and 02:00 for both occurrences of '/time'.

Some examples are:


      "PST-8PDT01:00:00,M4.1.0/02:00:00,M10.1.0/02:00:00"
      "PST-8PDT,M4.1.0,M10.1.0"

These two are actually the same specification (defaults were used in the second string). This zone lies eight hours west of GMT and makes a one hour shift forward during daylight savings time. Daylight savings for this zone starts on the first Sunday of April at 2am, and ends on the first Sunday of October at 2am.


      "MST-7"

This zone is as simple as it gets. This zone lies seven hours west of GMT and has no daylight savings.


      "EST10EDT,M10.5.0,M3.5.0/03"

This string describes the time zone for Sydney Australia. It lies ten hours east of GMT and makes a one hour shift forward during daylight savings. Being located in the southern hemisphere, daylight savings begins on the last Sunday in October at 2am and ends on the last Sunday in March at 3am.


      "FST+3FDT02:00,J60/00,J304/02"

This specification describes a fictitious zone that lies three hours east of GMT. It makes a two hour shift forward for daylight savings which begins on March 1st at midnight, and ends on October 31st at 2am. The 'J' designation in the start/end specs signifies that counting starts at one and February 29th is never counted.


      "FST+3FDT,59,304"

This specification is significant because of the '59'. The lack of 'J' for the start and end dates, indicates that the Julian day-count begins at zero and ends at 365. If you do the math, you'll see that allows for a total of 366 days. This is fine in leap years, but in non-leap years '59' (Feb-29) does not exist. This will construct a valid posix_time_zone object but an exception will be thrown if the date of '59' is accessed in a non-leap year. Ex: 

posix_time_zone leap_day(std::string("FST+3FDT,59,304"));
leap_day.dst_local_start_time(2004); // ok
leap_day.dst_local_start_time(2003); // Exception thrown

The posix_time_zone objects are used via a boost::shared_ptr<local_time::time_zone_base>. As a convenience, a typedef for boost::shared_ptr<local_time::time_zone_base> is provided: 

typedef boost::shared_ptr<time_zone_base> local_time::time_zone_ptr;

See Simple time zone for a side by side example of time_zone and posix_time_zone usage.

Important Notes

  • posix_time_zone objects use the standard and daylight savings abbreviations in place of the full names (see Accessors below).
  • 'Jn' and 'n' date specifications can not be mixed in a specification string. Ex: "FST+3FDT,59,J304"
  • 'n' date specification of 59 represents Feb-29. Do not attempt to access in a non-leap year or an exception will be thrown.

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

Syntax Example 
posix_time_zone(std::string)
 
std::string nyc("EST-5EDT,M4.1.0,M10.5.0");
time_zone_ptr zone(new posix_time_zone(nyc));

Accessors

Syntax Description
Example
 
std::string dst_zone_abbrev()
 Returns the daylight savings abbreviation for the represented time zone. 
nyc_zone_sh_ptr->dst_zone_abbrev(); // "EDT"
std::string std_zone_abbrev()
 Returns the standard abbreviation for the represented time zone. 
nyc_zone_sh_ptr->std_zone_abbrev(); // "EST"
std::string dst_zone_name()
 Returns the daylight savings ABBREVIATION for the represented time zone. 
nyc_zone_sh_ptr->dst_zone_name(); // "EDT"
std::string std_zone_name()
 Returns the standard ABBREVIATION for the represented time zone. 
nyc_zone_sh_ptr->std_zone_name(); // "EST"
bool has_dst()
 Returns true when time_zone's shared_ptr to dst_calc_rules is not NULL. 
nyc_zone_sh_ptr->has_dst(); // true
phx_zone_sh_ptr->has_dst(); // false
ptime dst_local_start_time(greg_year)
 The date and time daylight savings time begins in given year. Returns not_a_date_time if this zone has no daylight savings. 
nyc_zone_sh_ptr->dst_local_start_time(2004);
// 2004-Apr-04 02:00
ptime dst_local_end_time(greg_year)
 The date and time daylight savings time ends in given year. Returns not_a_date_time if this zone has no daylight savings. 
nyc_zone_sh_ptr->dst_local_end_time(2004);
// 2004-Oct-31 02:00
time_duration base_utc_offset()
 The amount of time offset from UTC (typically in hours). 
nyc_zone_sh_ptr->base_utc_offset(); // -05:00
posix_time::time_duration dst_offset()
 The amount of time shifted during daylight savings. 
nyc_zone_sh_ptr->dst_offset(); // 01:00
std::string to_posix_string()
 Returns a posix time zone string representation of this time_zone_base object. Depending on how the time_zone object was created, the date-spec format of the string will be in either 'M' notation or 'n' notation. Every possible date-spec that can be represented in 'J' notation can also be represented in 'n' notation. The reverse is not true so only 'n' notation is used for these types of date-specs. For a detailed description of a posix time zone string see posix_time_zone. 
nyc_zone_sh_ptr->to_posix_string();
// "EST-05EDT+01,M4.1.0/02:00,M10.5.0/02:00"
phx_zone_sh_ptr->to_posix_string();
// "MST-07"

Time Zone Database

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.

    1. 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).
    2. The second field indicates the day-of-week from 0-6 (Sun=0).
    3. 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.

Custom Time Zone

Introduction -- Header -- Construction -- Accessors -- Dependent Types

Introduction

A custom_time_zone object is a set of data and rules that provide information about a time zone. Information such as the offset from UTC, it's name and abbreviation, as well as daylight savings rules, called dst_calc_rules. These rules are handled via a boost::shared_ptr<dst_calc_rules>. Not all time zones utilize daylight savings, therefore, time_zone objects can be used with a NULL-assigned shared_ptr.

As a convenience, a typedef for shared_ptr<dst_calc_rules> is provided. 

typedef boost::shared_ptr<dst_calc_rules> local_time::dst_calc_rule_ptr;

The time_zone objects are used via a boost::shared_ptr<local_time::time_zone>. As a convenience, a typedef for boost::shared_ptr<local_time::time_zone> is provided: 

typedef boost::shared_ptr<time_zone> local_time::time_zone_ptr;

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

Construction of a custom_time_zone is dependent on four objects: a time_duration, a time_zone_names, a dst_adjustment_offsets, and a shared_ptr to a dst_calc_rule.

Syntax Example 
custom_time_zone(...)
  Parameters:
    names, 
    gmt_offset, 
    dst_offsets, 
    dst_rules
See simple_time_zone example for time_zone usage

Accessors

Syntax Description
Example
 
std::string dst_zone_abbrev()
 Returns the daylight savings abbreviation for the represented time zone. 
nyc_zone_sh_ptr->dst_zone_abbrev();
// "EDT"
std::string std_zone_abbrev()
 Returns the standard abbreviation for the represented time zone. 
nyc_zone_sh_ptr->std_zone_abbrev();
// "EST"
std::string dst_zone_name()
 Returns the daylight savings name for the represented time zone. 
nyc_zone_sh_ptr->dst_zone_name(); 
// "Eastern Daylight Time"
std::string std_zone_name()
 Returns the standard name for the represented time zone. 
nyc_zone_sh_ptr->std_zone_name();
// "Eastern Standard Time"
bool has_dst()
 Returns true when custom_time_zone's shared_ptr to dst_calc_rules is not NULL. 
nyc_zone_sh_ptr->has_dst();
// true
phx_zone_sh_ptr->has_dst();
// false
dst_local_start_time(...)
  Return Type:
    ptime
  Parameter:
    greg_year
 The date and time daylight savings time begins in given year. Returns not_a_date_time if this zone has no daylight savings. 
nyc_ptr->dst_local_start_time(2004);
// 2004-Apr-04 02:00
dst_local_end_time(...)
  Return Type:
    ptime
  Parameter:
    greg_year
 The date and time daylight savings time ends in given year. Returns not_a_date_time if this zone has no daylight savings. 
nyc_ptr->dst_local_end_time(2004);
// 2004-Oct-31 02:00
time_duration base_utc_offset()
 The amount of time offset from UTC (typically in hours). 
nyc_ptr->base_utc_offset();
// -05:00
time_duration dst_offset()
 The amount of time shifted during daylight savings. 
nyc_zone_sh_ptr->dst_offset();
// 01:00
std::string to_posix_string()
 Returns a posix time zone string representation of this time_zone object. Depending on how the time_zone object was created, the date-spec format of the string will be in either 'M' notation or 'n' notation. Every possible date-spec that can be represented in 'J' notation can also be represented in 'n' notation. The reverse is not true so only 'n' notation is used for these types of date-specs. For a detailed description of a posix time zone string see posix_time_zone. 
nyc_ptr->to_posix_string();
// "EST-05EDT+01,M4.1.0/02:00,M10.5.0/02:00"
phx_ptr->to_posix_string();
// "MST-07"

Dependent Types

Time Zone Names -- Dst Adjustment Offsets -- Daylight Savings Calc Rules

Time Zone Names

The time_zone_names_base type is an immutable template class of four strings. One each for the name and abbreviation in standard time and daylight savings time. The time_zone_names type is a typedef of time_zone_names_base<char>.

Syntax Description
Example
 
time_zone_names(...)
  Parameters:
    string std_name
    string std_abbrev
    string dst_name
    string dst_abbrev
 The only constructor, all four strings must be provided. 
string sn("Eastern Standard Time");
string sa("EST");
string dn("Eastern Daylight Time");
string da("EDT");
time_zone_names nyc_names(sn, sa, 
                          dn, da);
std::string std_zone_name()
 Returns the standard zone name 
nyc_names.std_zone_name();
// "Eastern Standard Time"
std::string std_zone_abbrev()
 Returns the standard zone abbreviation 
nyc_names.std_zone_abbrev();
// "EST"
std::string dst_zone_name()
 Returns the daylight savings zone name 
nyc_names.std_zone_name();
// "Eastern Daylight Time"
std::string dst_zone_abbrev()
 Returns the daylight savings zone abbreviation 
nyc_names.std_zone_abbrev();
// "EDT"

Dst Adjustment Offsets

The dst_adjustment_offsets type is a collection of three time_duration objects.

Syntax Description
Example
 
dst_adjustment_offsets(...)
  Parameters:
    time_duration dst_adjust
    time_duration start_offset
    time_duration end_offset
 The first time_duration is the daylight savings adjustment. The second is the time which daylight savings starts on the start day. The third is the time daylight savings ends on the ending day. 
dst_adjustment_offsets(hours(1), 
                       hours(2), 
                       hours(2));

Daylight Savings Calc Rules

Daylight savings calc rules, named dst_calc_rules, are a series of objects that group appropriate date_generators together to form rule sets. The individual rules objects are used via dst_calc_rule_ptr.

For a complete example of all five dst_calc_rule types, see: calc_rules example.

Syntax Description 
partial_date_dst_rule(...)
  Parameters:
    start_rule
    end_rule
 Both the start and end rules are of type gregorian::partial_date. 
first_last_dst_rule(...)
  Parameters:
    start_rule
    end_rule
 The DST start rule is of type gregorian::first_day_of_the_week_in_month and the end rule is of type gregorian::last_day_of_the_week_in_month. 
last_last_dst_rule(...)
  Parameters:
    start_rule
    end_rule
 Both the start and end rules are of type gregorian::last_day_of_the_week_in_month. 
nth_last_dst_rule(...)
  Parameters:
    start_rule
    end_rule
 The DST start rule is of type gregorian::nth_day_of_the_week_in_month and the end rule is of type gregorian::last_day_of_the_week_in_month. 
nth_kday_dst_rule(...)
  Parameters:
    start_rule
    end_rule)
(see note* below)
 Both rules are of type gregorian::nth_day_of_the_week_in_month.

* Note: The name "nth_kday_dst_rule" is a bit cryptic. Therefore, a more descriptive name, "nth_day_of_the_week_in_month_dst_rule", is also provided.

Local Date Time

Introduction -- Header -- Construct From Clock -- Construction -- Accessors -- Operators -- Struct tm Functions

Introduction

A local_date_time object is a point in time and an associated time zone. The time is represented internally as UTC.

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"

Construct From Clock

Creation of a local_date_time object from clock is possible with either second, or sub second resolution.

Syntax Example 
local_microsec_clock(...)
  Return Type:
    local_date_time
  Parameter:
    time_zone_ptr
 
time_zone_ptr zone(
  new posix_time_zone("MST-07")
);
local_date_time ldt = 
  local_microsec_clock::local_time(
    zone);
 
local_sec_clock(...)
  Return Type:
    local_date_time 
  Parameter:
    time_zone_ptr
 
time_zone_ptr zone(
  new posix_time_zone("MST-07")
);
local_date_time ldt = 
  local_sec_clock::local_time(zone);

Construction

Construction of a local_date_time object can be done with a ptime and a time_zone_ptr where the ptime represents UTC time. Construction with a wall-clock representation takes the form of a date, a time_duration, a time_zone_ptr, and a fourth parameter that addresses the following complication.

Construction from a wall-clock rep may result in differing shifts for a particular time zone, depending on daylight savings rules for that zone. This means it is also possible to create a local_date_time with a non-existent, or duplicated, UTC representation. These cases occur during the forward shift in time that is the transition into daylight savings and during the backward shift that is the transition out of daylight savings. The user has two options for handling these cases: a bool flag that states if the time is daylight savings, or an enum that states what to do when either of these cases are encountered.

The bool flag is ignored when the given time_zone has no daylight savings specification. When the daylight savings status of a given time label is calculated and it does not match the flag, a local_time::dst_not_valid exception is thrown. If a time label is invalid (does not exist), a local_time::time_label_invalid exception is thrown.

There are two elements in the local_date_time::DST_CALC_OPTIONS enum: EXCEPTION_ON_ERROR and NOT_DATE_TIME_ON_ERROR. The possible exceptions thrown are a local_time::ambiguous_result or a local_time::time_label_invalid. The NOT_DATE_TIME_ON_ERROR sets the time value to the special value local_time::not_a_date_time in the event of either a invalid or an ambiguous time label.

Syntax Description
Example
 
local_date_time(...)
  Parameters:
    posix_time::ptime
    time_zone_ptr
 The given time is expected to be UTC. Therefore, the given time will be adjusted according to the offset described in the time zone. 
// 3am, 2004-Nov-05 local time
ptime pt(date(2004,Nov,5), 
         hours(10));
time_zone_ptr zone(
  new posix_time_zone("MST-07"));
local_date_time az(pt, zone);
local_date_time(...)
  Parameters:
    date
    time_duration 
    time_zone_ptr
    bool
 The passed time information understood to be in the passed tz. The DST flag must be passed to indicate whether the time is in daylight savings or not. May throw a dst_not_valid or time_label_invalid exception. 
date d(2004,Nov,5);
time_duration td(5,0,0,0);
string z("PST-8PDT,M4.1.0,M10.1.0")
time_zone_ptr zone(
  new posix_time_zone(z));
local_date_time nyc(d, td, 
                    zone, false);
local_date_time(...)
  Parameters:
    date
    time_duration
    time_zone_ptr
    DST_CALC_OPTIONS
 The passed time information understood to be in the passed tz. The DST flag is calculated according to the specified rule. May throw a ambiguous_result or time_label_invalid exception. 
date d(2004,Nov,5);
time_duration td(5,0,0,0);
string z("PST-8PDT,M4.1.0,M10.1.0")
time_zone_ptr zone(
  new posix_time_zone(z));
local_date_time nyc(d, td, zone, 
  NOT_DATE_TIME_ON_ERROR);
local_date_time(local_date_time);
 Copy Constructor. 
local_date_time az_2(az);
local_date_time(...)
  Parameters:
    special_values
    time_zone_ptr
 Special Values constructor. 
time_zone_ptr zone(
  new posix_time_zone("MST-07")
);
local_date_time nadt(not_a_date_time, 
                     zone);
// default NULL time_zone_ptr
local_date_time nadt(pos_infin);

Accessors

Syntax Description
Example
 
time_zone_ptr zone()
 Returns associated time_zone object via a time_zone_ptr 




bool is_dst()

Determines if time value is in DST for associated zone.



 




ptime utc_time()

Converts the local time value to a UTC value.





ptime pt(date(2004,Nov,5), 
         hours(10));
time_zone_ptr zone(
  new posix_time_zone("MST-07"));
local_date_time az(pt, zone);
az.utc_time(); // 10am 2004-Nov-5

            




ptime local_time()

Returns the local time for this object (Wall-clock).



ptime pt(date(2004,Nov,5), 
         hours(10));
time_zone_ptr zone(
  new posix_time_zone("MST-07"));
local_date_time az(pt, zone);
az.utc_time(); // 10am 2004-Nov-5
az.local_time(); // 3am 2004-Nov-5




local_time_in(...)
  Return Type:
    local_date_time 
  Parameters:
    time_zone_ptr
    time_duration

Returns a local_date_time representing the same UTC time as calling object, plus optional time_duration, with given time zone.





local_date_time nyc = az.local_time_in(nyc_zone);
// nyc == 7am 2004-Nov-5

            




bool is_infinity() const

Returns true if local_date_time is either positive or negative infinity



local_date_time ldt(pos_infin); 
ldt.is_infinity(); // --> true




bool is_neg_infinity() const

Returns true if local_date_time is negative infinity



local_date_time ldt(neg_infin);
ldt.is_neg_infinity(); // --> true




bool is_pos_infinity() const

Returns true if local_date_time is positive infinity



local_date_time ldt(neg_infin); 
ldt.is_pos_infinity(); // --> true




bool is_not_a_date_time() const

Returns true if value is not a date



local_date_time ldt(not_a_date_time);
ldt.is_not_a_date_time(); // --> true




bool is_special() const

Returns true if local_date_time is any special_value




local_date_time ldt(pos_infin); 
local_date_time ldt2(not_a_date_time);
time_zone_ptr 
  mst(new posix_time_zone("MST-07"));
local_date_time 
  ldt3(local_sec_clock::local_time(mst));
ldt.is_special(); // --> true
ldt2.is_special(); // --> true
ldt3.is_special(); // --> false






  



Operators










Syntax
Description



Example






operator<<

Output streaming operator. This operator is part of the v1.33 IO addition to date_time. For complete details on this feature see Date Time IO. The default output is shown in this example.



time_zone_ptr zone(new posix_time_zone("MST-07");
local_date_time ldt(date(2005,Jul,4),
                    hours(20), 
                    false);
std::cout << ldt << std::endl;
// "2005-Jul-04 20:00:00 MST"
          




operator>>

Input streaming operator. This operator is part of the v1.33 IO addition to date_time. For complete details on this feature see Date Time IO. At this time, local_date_time objects can only be streamed in with a Posix Time Zone string. A complete description of a Posix Time Zone string can be found in the documentation for the posix_time_zone class.



stringstream ss;
ss.str("2005-Jul-04 20:00:00 MST-07");
ss >> ldt;
          




operator==, operator!=,
operator>, operator<,
operator>=, operator<=

A full complement of comparison operators



ldt1 == ldt2, etc




operator+, operator+=,
operator-, operator-=

Addition, subtraction, and shortcut operators for local_date_time and date duration types. These include: days, months, and years.



ldt + days(5), etc




operator+, operator+=,
operator-, operator-=

Addition, subtraction, and shortcut operators for local_date_time and time_duration.



ldt + hours(5), etc






Struct tm Functions


Function for converting a local_date_time object to a tm struct is provided.










Syntax
Description



Example






tm to_tm(local_date_time)

A function for converting a local_date_time object to a tm struct.





// 6am, 2005-Jul-05 local time
std::string z("EST-05EDT,M4.1.0,M10.1.0");
ptime pt(date(2005,Jul,5), 
         hours(10));
time_zone_ptr zone( new posix_time_zone(z));
local_date_time ldt(pt, zone);
tm ldt_tm = to_tm(ldt);
/* tm_year => 105
   tm_mon  => 6
   tm_mday => 5
   tm_wday => 2 (Tuesday)
   tm_yday => 185
   tm_hour => 6
   tm_min  => 0
   tm_sec  => 0
   tm_isdst => 1 */

	  










Local Time Period

Introduction --
  Header --
  Construction --
  Accessors --
  Operators

Introduction



    The class boost::local_time::local_time_period provides direct representation for ranges between two local times. Periods provide the ability to simplify some types of calculations by simplifying the conditional logic of the program. 
  



    A period that is created with beginning and end points being equal, or with a duration of zero, is known as a zero length period. Zero length periods are considered invalid (it is perfectly legal to construct an invalid period). For these periods, the last point will always be one unit less that the begin point.
  



Header



    


#include "boost/date_time/local_time/local_time.hpp" //include all types plus i/o
or
#include "boost/date_time/local_time/local_time_types.hpp" //no i/o just types



  



Construction



    










Syntax
Description



Example






local_time_period(...)
  Parameters:
    local_date_time beginning
    local_date_time end

 Create a period as [begin, end). If end is <= begin then the period will be defined as invalid.





time_zone_ptr 
  zone(new posix_time_zone("MST-07"));
local_date_time 
  beg(ptime(date(2005,Jan,1),hours(0)), zone);
local_date_time 
  end(ptime(date(2005,Feb,1),hours(0)), zone);
// period for the entire month of Jan 2005
local_time_period ltp(beg, end);

	    




local_time_period(...)
  Parameters:
    local_date_time beginning
    time_duration length

Create a period as [begin, begin+len) where end would be begin+len. If len is <= zero then the period will be defined as invalid.





time_zone_ptr 
  zone(new posix_time_zone("MST-07"));
local_date_time 
  beg(ptime(date(2005,Jan,1),hours(0)), zone);
// period for the whole day of 2005-Jan-01
local_time_period ltp(beg, hours(24));

	    




local_time_period(local_time_period rhs)

Copy constructor



local_time_period ltp1(ltp);






  



Accessors



    










Syntax
Description



Example






local_date_time begin()

Return first local_date_time of the period.





time_zone_ptr 
  zone(new posix_time_zone("MST-07"));
local_date_time 
  ldt((ptime(date(2005,Jan,1)),hours(0)), zone);
local_time_period ltp(ldt, hours(2));
ltp.begin(); // => 2005-Jan-01 00:00:00

	    




local_date_time last()

Return last local_date_time in the period





time_zone_ptr 
  zone(new posix_time_zone("MST-07"));
local_date_time 
  ldt((ptime(date(2005,Jan,1),hours(0))), zone);
local_time_period ltp(ldt, hours(2));
ltp.last(); // => 2005-Jan-01 01:59:59.999999999

	    




local_date_time end()

Return one past the last in period





time_zone_ptr 
  zone(new posix_time_zone("MST-07"));
local_date_time 
  ldt((ptime(date(2005,Jan,1),hours(0))), zone);
local_time_period ltp(ldt, hours(2));
ltp.end(); // => 2005-Jan-01 02:00:00

	    




time_duration length()

Return the length of the local_time period.





time_zone_ptr 
  zone(new posix_time_zone("MST-07"));
local_date_time 
  ldt((ptime(date(2005,Jan,1),hours(0))), zone);
local_time_period ltp(ldt, hours(2));
ltp.length(); // => 02:00:00

	    




bool is_null()

True if period is not well formed. eg: end less than or equal to begin.





time_zone_ptr 
  zone(new posix_time_zone("MST-07"));
local_date_time 
  beg((ptime(date(2005,Feb,1),hours(0))), zone);
local_date_time 
  end((ptime(date(2005,Jan,1),hours(0))), zone);
local_time_period ltp(beg, end);
ltp.is_null(); // => true

	    




bool contains(local_date_time)

True if local_date_time is within the period. Zero length periods cannot contain any points



time_zone_ptr 
  zone(new posix_time_zone("MST-07"));
local_date_time 
  beg((ptime(date(2005,Jan,1),hours(0))), zone);
local_date_time 
  end((ptime(date(2005,Feb,1),hours(0))), zone);
local_time_period jan_mst(beg, end);

local_date_time 
ldt((ptime(date(2005,Jan,15),hours(12))), zone);
jan_mst.contains(ldt); // => true

local_time_period zero(beg, beg);
zero.contains(beg); // false




bool contains(local_time_period)

True if period is within the period



// using jan_mst period from previous example

local_date_time 
  beg((ptime(date(2005,Jan,7),hours(0))), zone);
local_time_period ltp(beg, hours(24));

jan_mst.contains(ltp); // => true




bool intersects(local_time_period)

 True if periods overlap



// using jan_mst period from previous example

local_date_time 
  beg((ptime(date(2005,Jan,7),hours(0))), zone);
local_date_time 
  end((ptime(date(2005,Feb,7),hours(0))), zone);
local_time_period ltp(beg, end);

jan_mst.intersects(ltp); // => true




local_time_period intersection(local_time_period)

Calculate the intersection of 2 periods. Null if no intersection.



// using jan_mst period from previous example

local_date_time 
  beg((ptime(date(2005,Jan,7),hours(0))), zone);
local_date_time 
  end((ptime(date(2005,Feb,7),hours(0))), zone);
local_time_period ltp(beg, end);

local_time_period res(jan_mst.intersection(ltp));
// res => 2005-Jan-07 00:00:00 through
// 2005-Jan-31 23:59:59.999999999 (inclusive)




local_time_period merge(local_time_period)

Returns union of two periods. Null if no intersection.



// using jan_mst period from previous example

local_date_time 
  beg((ptime(date(2005,Jan,7),hours(0))), zone);
local_date_time 
  end((ptime(date(2005,Feb,7),hours(0))), zone);
local_time_period ltp(beg, end);

local_time_period res(jan_mst.merge(ltp));
// res => 2005-Jan-07 00:00:00 through
// 2005-Feb-06 23:59:59.999999999 (inclusive)




local_time_period span(local_time_period)

Combines two periods and any gap between them such that begin = min(p1.begin, p2.begin) and end = max(p1.end , p2.end).



// using jan_mst period from previous example

local_date_time 
  beg((ptime(date(2005,Mar,1),hours(0))), zone);
local_date_time 
  end((ptime(date(2005,Apr,1),hours(0))), zone);
local_time_period mar_mst(beg, end);

local_time_period res(jan_mst.span(mar_mst));
// res => 2005-Jan-01 00:00:00 through
// 2005-Mar-31 23:59:59.999999999 (inclusive)




void shift(time_duration)

Add duration to both begin and end.



local_date_time 
  beg((ptime(date(2005,Mar,1),hours(0))), zone);
local_date_time 
  end((ptime(date(2005,Apr,1),hours(0))), zone);
local_time_period mar_mst(beg, end);

mar_mst.shift(hours(48));
// mar_mst => 2005-Mar-03 00:00:00 through
// 2005-Apr-02 23:59:59.999999999 (inclusive)






  



Operators



    










Syntax
Description



Example






operator==, operator!=

Equality operators. Periods are equal if ltp1.begin == ltp2.begin && ltp1.last == ltp2.last



if (ltp1 == ltp2) {...




operator<

Ordering with no overlap. True if ltp1.end() less than ltp2.begin()



if (ltp1 < ltp2) {...




operator>

Ordering with no overlap. True if ltp1.begin() greater than ltp2.end()



if (ltp1 > ltp2) {... etc




operator<=, operator>=

Defined in terms of the other operators.



 






  






Copyright © 2001-2005 CrystalClear Software, Inc
Subject to the Boost Software License, Version 1.0. (See accompanying file
    LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)







PrevUpHomeNext