Component baltzo_localtimevalidity [Package baltzo]

Enumerate the set of local time validity codes. More...

Namespaces
namespace	baltzo

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Enumerators
  • Usage
    • Example 1: Basic Syntax

Purpose:

Enumerate the set of local time validity codes.

Classes:

baltzo::LocalTimeValidity

namespace for local time validity enum

See also:

Component baltzo_localtimedescriptor, Component baltzo_timezoneutil

Description:

This component provides a namespace, baltzo::LocalTimeValidity, for the enum type baltzo::LocalTimeValidity::Enum, which enumerates the set of validity codes that can be attributed to a local time. Due to the vagaries of time zones, and transitions among daylight-saving time and standard time, a particular representation of local clock time may be deemed to be strictly invalid, or (uniquely or ambiguously) valid.

Enumerators:

  Name               Description
  -----------------  ---------------------------------------
  e_VALID_UNIQUE     Local time is *valid* and *unique*.
  e_VALID_AMBIGUOUS  Local time is *valid*, but *ambiguous*.
  e_INVALID          Local time is *invalid*.

For example, consider the following purported New York local times and their corresponding baltzo::LocalTimeValidity::Enum values:

  New York Local Time     Validity Code
  -------------------     ----------------------
  Jan  1, 2010 2:30am     e_VALID_UNIQUE
  Mar 14, 2010 2:30am     e_INVALID
  Nov  7, 2010 1:30am     e_VALID_AMBIGUOUS

On January 1, 2010 in New York, Eastern Standard Time (EST) was in effect and the transition to Eastern Daylight-Saving Time (EDT) was still weeks away; "Jan 1, 2010 2:30am" is a patently valid -- and unique -- New York local time. The transition to EDT in New York in 2010 occurred on March 14 as of 2:00am EST, or more precisely, as of 7:00am UTC (which would have been 2:00am EST, but became 3:00am EDT). Consequently, "Mar 14, 2010 2:30am" is an invalid New York local time, since clocks were advanced by one hour as of 2:00am EST. The change from EDT back to EST in New York in 2010 occurred on November 7 as of 2:00am EDT. Due to this transition, "Nov 7, 2010 1:30am" is a valid New York local time. However, that local time is ambiguous because it corresponds to two possible clock times, 1:30am EDT and 1:30am EST, since clocks were regressed by one hour as of 2:00am EDT (7:00am UTC).

Usage:

This section illustrates intended use of this component.

Example 1: Basic Syntax:

The following snippets of code provide a simple illustration of baltzo::LocalTimeValidity usage.

First, we create a variable value of type baltzo::LocalTimeValidity::Enum and initialize it with the enumerator value baltzo::LocalTimeValidity::e_VALID_AMBIGUOUS:

  baltzo::LocalTimeValidity::Enum value =
                                baltzo::LocalTimeValidity::e_VALID_AMBIGUOUS;

Now, we store a pointer to its ASCII representation in a variable asciiValue of type const char *:

  const char *asciiValue = baltzo::LocalTimeValidity::toAscii(value);
  assert(0 == bsl::strcmp(asciiValue, "VALID_AMBIGUOUS"));

Finally, we print value to bsl::cout.

  bsl::cout << value << bsl::endl;

This statement produces the following output on stdout:

  VALID_AMBIGUOUS