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.
SyntaxExamplelocal_microsec_clock(...)
Return Type:
local_date_time
Parameter:
time_zone_ptrtime_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_ptrtime_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.
SyntaxDescriptionExamplelocal_date_time(...)
Parameters:
posix_time::ptime
time_zone_ptrThe 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
boolThe 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_OPTIONSThe 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_ptrSpecial 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);AccessorsSyntaxDescriptionExampletime_zone_ptr zone()Returns associated time_zone object via a time_zone_ptrbool 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-5ptime 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-5local_time_in(...)
Return Type:
local_date_time
Parameters:
time_zone_ptr
time_durationReturns 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-5bool is_infinity() constReturns true if local_date_time is either positive or negative infinitylocal_date_time ldt(pos_infin);
ldt.is_infinity(); // --> truebool is_neg_infinity() constReturns true if local_date_time is negative infinitylocal_date_time ldt(neg_infin);
ldt.is_neg_infinity(); // --> truebool is_pos_infinity() constReturns true if local_date_time is positive infinitylocal_date_time ldt(neg_infin);
ldt.is_pos_infinity(); // --> truebool is_not_a_date_time() constReturns true if value is not a datelocal_date_time ldt(not_a_date_time);
ldt.is_not_a_date_time(); // --> truebool is_special() constReturns true if local_date_time is any special_valuelocal_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(); // --> falseOperatorsSyntaxDescriptionExampleoperator<<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 operatorsldt1 == ldt2, etcoperator+, 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), etcoperator+, operator+=,
operator-, operator-=Addition, subtraction, and shortcut operators for local_date_time and time_duration.ldt + hours(5), etcStruct tm FunctionsFunction for converting a local_date_time object to a tm struct is provided.SyntaxDescriptionExampletm 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_isddst => 1 */