BDE 4.14.0 Production release
Loading...
Searching...
No Matches
baltzo_dstpolicy.h
Go to the documentation of this file.
1/// @file baltzo_dstpolicy.h
2///
3/// The content of this file has been pre-processed for Doxygen.
4///
5
6
7// baltzo_dstpolicy.h -*-C++-*-
8#ifndef INCLUDED_BALTZO_DSTPOLICY
9#define INCLUDED_BALTZO_DSTPOLICY
10
11#include <bsls_ident.h>
12BSLS_IDENT("$Id: $")
13
14/// @defgroup baltzo_dstpolicy baltzo_dstpolicy
15/// @brief Enumerate the set of daylight-saving time (DST) policy values.
16/// @addtogroup bal
17/// @{
18/// @addtogroup baltzo
19/// @{
20/// @addtogroup baltzo_dstpolicy
21/// @{
22///
23/// <h1> Outline </h1>
24/// * <a href="#baltzo_dstpolicy-purpose"> Purpose</a>
25/// * <a href="#baltzo_dstpolicy-classes"> Classes </a>
26/// * <a href="#baltzo_dstpolicy-description"> Description </a>
27/// * <a href="#baltzo_dstpolicy-enumerators"> Enumerators </a>
28/// * <a href="#baltzo_dstpolicy-usage"> Usage </a>
29/// * <a href="#baltzo_dstpolicy-example-1-basic-syntax"> Example 1: Basic Syntax </a>
30///
31/// # Purpose {#baltzo_dstpolicy-purpose}
32/// Enumerate the set of daylight-saving time (DST) policy values.
33///
34/// # Classes {#baltzo_dstpolicy-classes}
35///
36/// - baltzo::DstPolicy: namespace for a daylight-saving time policy `enum`
37///
38/// @see baltzo_localtimevalidity, baltzo_timezoneutil
39///
40/// # Description {#baltzo_dstpolicy-description}
41/// This component provides a namespace for the `enum` type
42/// `baltzo::DstPolicy::Enum`, which enumerates the set of policies for
43/// interpreting whether an associated local time is a daylight-saving time
44/// value. A `baltzo::DstPolicy` is particularly important when interpreting a
45/// local time that is not associated with a UTC offset (e.g., a
46/// `bdlt::Datetime` object), as such a representation may be ambiguous or
47/// invalid (see @ref baltzo_localtimevalidity ).
48///
49/// ## Enumerators {#baltzo_dstpolicy-enumerators}
50///
51///
52/// @code
53/// Name Description
54/// ------------- ---------------------------------------------------
55/// e_DST Local time is interpreted as daylight-saving time.
56///
57/// e_STANDARD Local time is interpreted as standard time.
58///
59/// e_UNSPECIFIED Local time is interpreted as either daylight-saving time or
60/// standard time (as appropriate).
61/// @endcode
62///
63/// ## Usage {#baltzo_dstpolicy-usage}
64///
65///
66/// This section illustrates intended use of this component.
67///
68/// ### Example 1: Basic Syntax {#baltzo_dstpolicy-example-1-basic-syntax}
69///
70///
71/// The following snippets of code provide a simple illustration of using
72/// `baltzo::DstPolicy`.
73///
74/// First, we create a variable `value` of type `baltzo::DstPolicy::Enum` and
75/// initialize it with the enumerator value
76/// `baltzo::DstPolicy::e_STANDARD`:
77/// @code
78/// baltzo::DstPolicy::Enum value = baltzo::DstPolicy::e_STANDARD;
79/// @endcode
80/// Now, we store the address of its ASCII representation in a pointer variable,
81/// `asciiValue`, of type `const char *`:
82/// @code
83/// const char *asciiValue = baltzo::DstPolicy::toAscii(value);
84/// assert(0 == bsl::strcmp(asciiValue, "STANDARD"));
85/// @endcode
86/// Finally, we print `value` to `bsl::cout`.
87/// @code
88/// bsl::cout << value << bsl::endl;
89/// @endcode
90/// This statement produces the following output on `stdout`:
91/// @code
92/// STANDARD
93/// @endcode
94/// @}
95/** @} */
96/** @} */
97
98/** @addtogroup bal
99 * @{
100 */
101/** @addtogroup baltzo
102 * @{
103 */
104/** @addtogroup baltzo_dstpolicy
105 * @{
106 */
107
108#include <balscm_version.h>
109
110#include <bsl_iosfwd.h>
111
112
113namespace baltzo {
114 // ================
115 // struct DstPolicy
116 // ================
117
118/// This `struct` provides a namespace for enumerating the set of policies
119/// for interpreting whether a local time is a daylight-saving time. See
120/// `Enum` in the TYPES sub-section for details.
121///
122/// This class:
123/// * supports a complete set of *enumeration* operations
124/// - except for `bdex` serialization
125/// * is `const` *thread-safe*
126/// For terminology see @ref bsldoc_glossary .
127struct DstPolicy {
128
129 public:
130 // TYPES
131 enum Enum {
132 e_DST, // Local time is interpreted as daylight-saving
133 // time.
134
135 e_STANDARD, // Local time is interpreted as standard time.
136
137 e_UNSPECIFIED // Local time is interpreted as either
138 // daylight-saving time or standard time (as
139 // appropriate).
140
141#ifndef BDE_OMIT_INTERNAL_DEPRECATED
148#endif // BDE_OMIT_INTERNAL_DEPRECATED
149
150 };
151
152 public:
153 // CLASS METHODS
154
155 /// Write the string representation of the specified enumeration `value`
156 /// to the specified output `stream`, and return a reference to
157 /// `stream`. Optionally specify an initial indentation `level`, whose
158 /// absolute value is incremented recursively for nested objects. If
159 /// `level` is specified, optionally specify `spacesPerLevel`, whose
160 /// absolute value indicates the number of spaces per indentation level
161 /// for this and all of its nested objects. If `level` is negative,
162 /// suppress indentation of the first line. If `spacesPerLevel` is
163 /// negative, format the entire output on one line, suppressing all but
164 /// the initial indentation (as governed by `level`). See `toAscii` for
165 /// what constitutes the string representation of a `DstPolicy::Enum`
166 /// value.
167 static bsl::ostream& print(bsl::ostream& stream,
168 DstPolicy::Enum value,
169 int level = 0,
170 int spacesPerLevel = 4);
171
172 /// Return the non-modifiable string representation corresponding to the
173 /// specified enumeration `value`, if it exists, and a unique (error)
174 /// string otherwise. The string representation of `value` matches its
175 /// corresponding enumerator name with the "e_" prefix elided. For
176 /// example:
177 /// @code
178 /// bsl::cout << DstPolicy::toAscii(DstPolicy::e_STANDARD);
179 /// @endcode
180 /// will print the following on standard output:
181 /// @code
182 /// STANDARD
183 /// @endcode
184 /// Note that specifying a `value` that does not match any of the
185 /// enumerators will result in a string representation that is distinct
186 /// from any of those corresponding to the enumerators, but is otherwise
187 /// unspecified.
188 static const char *toAscii(DstPolicy::Enum value);
189};
190
191// FREE OPERATORS
192
193/// Write the string representation of the specified enumeration `value` to
194/// the specified output `stream` in a single-line format, and return a
195/// reference to `stream`. See `toAscii` for what constitutes the string
196/// representation of a `baltzo::DstPolicy::Enum` value. Note that this
197/// method has the same behavior as
198/// @code
199/// baltzo::DstPolicy::print(stream, value, 0, -1);
200/// @endcode
201bsl::ostream& operator<<(bsl::ostream& stream, DstPolicy::Enum value);
202
203} // close package namespace
204
205// ============================================================================
206// INLINE DEFINITIONS
207// ============================================================================
208
209 // ----------------
210 // struct DstPolicy
211 // ----------------
212
213// FREE OPERATORS
214inline
215bsl::ostream& baltzo::operator<<(bsl::ostream& stream, DstPolicy::Enum value)
216{
217 return DstPolicy::print(stream, value, 0, -1);
218}
219
220
221
222#endif
223
224// ----------------------------------------------------------------------------
225// Copyright 2015 Bloomberg Finance L.P.
226//
227// Licensed under the Apache License, Version 2.0 (the "License");
228// you may not use this file except in compliance with the License.
229// You may obtain a copy of the License at
230//
231// http://www.apache.org/licenses/LICENSE-2.0
232//
233// Unless required by applicable law or agreed to in writing, software
234// distributed under the License is distributed on an "AS IS" BASIS,
235// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
236// See the License for the specific language governing permissions and
237// limitations under the License.
238// ----------------------------- END-OF-FILE ----------------------------------
239
240/** @} */
241/** @} */
242/** @} */
#define BSLS_IDENT(str)
Definition bsls_ident.h:195
Definition baltzo_datafileloader.h:263
bsl::ostream & operator<<(bsl::ostream &stream, DstPolicy::Enum value)
Definition baltzo_dstpolicy.h:127
Enum
Definition baltzo_dstpolicy.h:131
@ BAETZO_DST
Definition baltzo_dstpolicy.h:145
@ e_DST
Definition baltzo_dstpolicy.h:132
@ BALTZO_DST
Definition baltzo_dstpolicy.h:142
@ BALTZO_UNSPECIFIED
Definition baltzo_dstpolicy.h:144
@ BAETZO_UNSPECIFIED
Definition baltzo_dstpolicy.h:147
@ BAETZO_STANDARD
Definition baltzo_dstpolicy.h:146
@ e_STANDARD
Definition baltzo_dstpolicy.h:135
@ BALTZO_STANDARD
Definition baltzo_dstpolicy.h:143
@ e_UNSPECIFIED
Definition baltzo_dstpolicy.h:137
static const char * toAscii(DstPolicy::Enum value)
static bsl::ostream & print(bsl::ostream &stream, DstPolicy::Enum value, int level=0, int spacesPerLevel=4)