baltzo_localdatetime

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Attributes
  • Usage
    • Example 1: Creation and Use of a baltzo::LocalDatetime Object

Purpose

Provide an attribute class for time-zone-aware datetime values.

Classes

• baltzo::LocalDatetime: time-zone-aware datetime type

See also

bdlt_datetimetz

Description

This component provides a single, unconstrained (value-semantic) attribute class, baltzo::LocalDatetime, that is used to encapsulate a date, time, offset from UTC (Coordinated Universal Time), and a time zone (string) identifier. The date, time, and offset from UTC are contained within a bdlt::DatetimeTz object, which together represents a wall-clock time in a given time zone. This component differs from bdlt_datetimetz in that it provides, as part of the value, a string identifier for the corresponding time zone.

Attributes

Name          Type               Default
----------    ---------------    ----------------------------------
datetimeTz    bdlt::DatetimeTz   January 1, 0001, 24:00:00.000+0000
timeZoneId    bsl::string        ""

• datetimeTz: date, time, and offset from UTC of the local time.
• timeZoneId: unique identifier representing the local time zone.

For example, in New York on January 1, 2011, at 10 a.m. the local offset from UTC is -5 hours, and a standard time zone identifier for New York is "America/New_York". We can represent this information using a baltzo::LocalDatetime object whose datetimeTz attribute is "01JAN2011_10:00:00.000-0005" and whose timeZoneId attribute is "America/New_York".

Note that it is up to the user to ensure that the datetimeTz and timeZoneId attributes are consistent as the baltzo::LocalDatetime object itself does not maintain any invariants with respect to their values.

Usage

This section illustrates intended use of this component.

Example 1: Creation and Use of a baltzo::LocalDatetime Object

First, we default-construct a baltzo::LocalDatetime object:

baltzo::LocalDatetime localDatetime;

Next, we update the time referred to by localDatetime to the New York time "December 25, 2009, 11:00" with the time-zone identifier set to "America/New_York":

bdlt::Datetime   datetime(2009, 12, 25, 11, 00, 00);
bdlt::DatetimeTz datetimeTz(datetime, -5 * 60);  // offset is specified
                                                 // in minutes from UTC
bsl::string      timeZoneId("America/New_York");
localDatetime.setDatetimeTz(datetimeTz);
localDatetime.setTimeZoneId(timeZoneId);
 
assert(datetimeTz == localDatetime.datetimeTz());
assert(timeZoneId == localDatetime.timeZoneId());

Now, we change the time-zone identifier to another string, for example "Europe/Berlin":

bsl::string anotherTimeZoneId("Europe/Berlin");
localDatetime.setTimeZoneId(anotherTimeZoneId);
 
assert(datetimeTz        == localDatetime.datetimeTz());
assert(anotherTimeZoneId == localDatetime.timeZoneId());

Finally, we stream localDatetime to bsl::cout:

bsl::cout << localDatetime << bsl::endl;

This statement produces the following output on stdout:

[ 25DEC2009_11:00:00.000-0500 "Europe/Berlin" ]