Component baltzo_localdatetime [Package baltzo]

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

Namespaces
namespace	baltzo

---

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:

Component 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" ]