baltzo_localtimevalidity.h

Go to the documentation of this file.

/// @file baltzo_localtimevalidity.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// baltzo_localtimevalidity.h                                         -*-C++-*-
#ifndef INCLUDED_BALTZO_LOCALTIMEVALIDITY
#define INCLUDED_BALTZO_LOCALTIMEVALIDITY
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup baltzo_localtimevalidity baltzo_localtimevalidity
/// @brief  Enumerate the set of local time validity codes.
/// @addtogroup bal
/// @{
/// @addtogroup baltzo
/// @{
/// @addtogroup baltzo_localtimevalidity
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#baltzo_localtimevalidity-purpose"> Purpose</a>
/// * <a href="#baltzo_localtimevalidity-classes"> Classes </a>
/// * <a href="#baltzo_localtimevalidity-description"> Description </a>
///   * <a href="#baltzo_localtimevalidity-enumerators"> Enumerators </a>
///   * <a href="#baltzo_localtimevalidity-usage"> Usage </a>
///     * <a href="#baltzo_localtimevalidity-example-1-basic-syntax"> Example 1: Basic Syntax </a>
///
/// # Purpose {#baltzo_localtimevalidity-purpose}
/// Enumerate the set of local time validity codes.
///
/// # Classes {#baltzo_localtimevalidity-classes}
///
/// -  baltzo::LocalTimeValidity: namespace for local time validity `enum`
///
/// @see  baltzo_localtimedescriptor, baltzo_timezoneutil
///
/// # Description {#baltzo_localtimevalidity-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 {#baltzo_localtimevalidity-enumerators}
///
///
/// @code
/// 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*.
/// @endcode
/// For example, consider the following purported New York local times and their
/// corresponding `baltzo::LocalTimeValidity::Enum` values:
/// @code
/// 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
/// @endcode
/// 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 {#baltzo_localtimevalidity-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: Basic Syntax {#baltzo_localtimevalidity-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`:
/// @code
/// baltzo::LocalTimeValidity::Enum value =
///                               baltzo::LocalTimeValidity::e_VALID_AMBIGUOUS;
/// @endcode
/// Now, we store a pointer to its ASCII representation in a variable
/// `asciiValue` of type `const char *`:
/// @code
/// const char *asciiValue = baltzo::LocalTimeValidity::toAscii(value);
/// assert(0 == bsl::strcmp(asciiValue, "VALID_AMBIGUOUS"));
/// @endcode
/// Finally, we print `value` to `bsl::cout`.
/// @code
/// bsl::cout << value << bsl::endl;
/// @endcode
/// This statement produces the following output on `stdout`:
/// @code
/// VALID_AMBIGUOUS
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bal
 * @{
 */
/** @addtogroup baltzo
 * @{
 */
/** @addtogroup baltzo_localtimevalidity
 * @{
 */
 
#include <balscm_version.h>
 
#include <bsl_iosfwd.h>
 
 
namespace baltzo {
                          // ========================
                          // struct LocalTimeValidity
                          // ========================
 
/// This `struct` provides a namespace for enumerating the set of validity
/// codes that can be attributed to local time values.  See `Enum` in the
/// TYPES sub-section for details.
///
/// This class:
/// * supports a complete set of *enumeration* operations
///   - except for `bdex` serialization
/// For terminology see @ref bsldoc_glossary .
///
/// See @ref baltzo_localtimevalidity 
struct LocalTimeValidity {
 
  public:
    // TYPES
    enum Enum {
        e_VALID_UNIQUE,     // Local time is *valid* and *unique*.
        e_VALID_AMBIGUOUS,  // Local time is *valid*, but *ambiguous*.
        e_INVALID           // Local time is *invalid*.
 
#ifndef BDE_OMIT_INTERNAL_DEPRECATED
      , BAETZO_VALID_UNIQUE    = e_VALID_UNIQUE
      , BAETZO_VALID_AMBIGUOUS = e_VALID_AMBIGUOUS
      , BAETZO_INVALID         = e_INVALID
#endif  // BDE_OMIT_INTERNAL_DEPRECATED
 
    };
 
  public:
    // CLASS METHODS
 
    /// Write the string representation of the specified enumeration `value`
    /// to the specified output `stream`, and return a reference to
    /// `stream`.  Optionally specify an initial indentation `level`, whose
    /// absolute value is incremented recursively for nested objects.  If
    /// `level` is specified, optionally specify `spacesPerLevel`, whose
    /// absolute value indicates the number of spaces per indentation level
    /// for this and all of its nested objects.  If `level` is negative,
    /// suppress indentation of the first line.  If `spacesPerLevel` is
    /// negative, format the entire output on one line, suppressing all but
    /// the initial indentation (as governed by `level`).  See `toAscii` for
    /// what constitutes the string representation of a
    /// `LocalTimeValidity::Enum` value.
    static bsl::ostream& print(bsl::ostream& stream,
                               Enum          value,
                               int           level          = 0,
                               int           spacesPerLevel = 4);
 
    /// Return the non-modifiable string representation corresponding to the
    /// specified enumeration `value`, if it exists, and a unique (error)
    /// string otherwise.  The string representation of `value` matches its
    /// corresponding enumerator name with the "e_" prefix elided.  For
    /// example:
    /// @code
    /// bsl::cout << LocalTimeValidity::toAscii(
    ///                                 LocalTimeValidity::e_VALID_UNIQUE);
    /// @endcode
    /// will print the following on standard output:
    /// @code
    /// VALID_UNIQUE
    /// @endcode 
    /// 
    /// \note Note that   specifying a `value` that does not match any of the
    /// enumerators will result in a string representation that is distinct
    /// from any of those corresponding to the enumerators, but is otherwise
    /// unspecified.
    static const char *toAscii(Enum value);
};
 
// FREE OPERATORS
 
/// Write the string representation of the specified enumeration `value` to
/// the specified output `stream` in a single-line format, and return a
/// reference to `stream`.  See `toAscii` for what constitutes the string
/// representation of a `baltzo::LocalTimeValidity::Enum` value.  
/// 
/// \note Note that   this method has the same behavior as
/// @code
/// baltzo::LocalTimeValidity::print(stream, value, 0, -1);
/// @endcode
bsl::ostream& operator<<(bsl::ostream& stream, LocalTimeValidity::Enum value);
 
}  // close package namespace
 
// ============================================================================
//                            INLINE DEFINITIONS
// ============================================================================
 
                          // ------------------------
                          // struct LocalTimeValidity
                          // ------------------------
 
// FREE OPERATORS
inline
bsl::ostream& baltzo::operator<<(bsl::ostream&           stream,
                                 LocalTimeValidity::Enum value)
{
    return LocalTimeValidity::print(stream, value, 0, -1);
}
 
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2015 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------
 
/** @} */
/** @} */
/** @} */