baltzo_localtimevalidity

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

baltzo_localtimedescriptor, 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