BDE 4.14.0 Production release
Loading...
Searching...
No Matches
bdlt_iso8601util.h
Go to the documentation of this file.
1/// @file bdlt_iso8601util.h
2///
3/// The content of this file has been pre-processed for Doxygen.
4///
5
6
7// bdlt_iso8601util.h -*-C++-*-
8#ifndef INCLUDED_BDLT_ISO8601UTIL
9#define INCLUDED_BDLT_ISO8601UTIL
10
11#include <bsls_ident.h>
12BSLS_IDENT("$Id: $")
13
14/// @defgroup bdlt_iso8601util bdlt_iso8601util
15/// @brief Provide conversions between date/time objects and ISO 8601 strings.
16/// @addtogroup bdl
17/// @{
18/// @addtogroup bdlt
19/// @{
20/// @addtogroup bdlt_iso8601util
21/// @{
22///
23/// <h1> Outline </h1>
24/// * <a href="#bdlt_iso8601util-purpose"> Purpose</a>
25/// * <a href="#bdlt_iso8601util-classes"> Classes </a>
26/// * <a href="#bdlt_iso8601util-description"> Description </a>
27/// * <a href="#bdlt_iso8601util-terminology"> Terminology </a>
28/// * <a href="#bdlt_iso8601util-iso-8601-string-generation"> ISO 8601 String Generation </a>
29/// * <a href="#bdlt_iso8601util-configuration"> Configuration </a>
30/// * <a href="#bdlt_iso8601util-iso-8601-string-parsing"> ISO 8601 String Parsing </a>
31/// * <a href="#bdlt_iso8601util-zone-designators"> Zone Designators </a>
32/// * <a href="#bdlt_iso8601util-fractional-seconds"> Fractional Seconds </a>
33/// * <a href="#bdlt_iso8601util-leap-seconds"> Leap Seconds </a>
34/// * <a href="#bdlt_iso8601util-the-time-24-00"> The Time 24:00 </a>
35/// * <a href="#bdlt_iso8601util-summary-of-supported-iso-8601-representations"> Summary of Supported ISO 8601 Representations </a>
36/// * <a href="#bdlt_iso8601util-summary-of-supported-iso-8601-duration-representations"> Summary of Supported ISO 8601 Duration Representations </a>
37/// * <a href="#bdlt_iso8601util-usage"> Usage </a>
38/// * <a href="#bdlt_iso8601util-example-1-basic-bdlt-iso8601util-usage"> Example 1: Basic bdlt::Iso8601Util Usage </a>
39/// * <a href="#bdlt_iso8601util-example-2-configuring-iso-8601-string-generation"> Example 2: Configuring ISO 8601 String Generation </a>
40///
41/// # Purpose {#bdlt_iso8601util-purpose}
42/// Provide conversions between date/time objects and ISO 8601 strings.
43///
44/// # Classes {#bdlt_iso8601util-classes}
45///
46/// - bdlt::Iso8601Util: namespace for ISO 8601 date/time conversion functions
47///
48/// @see bdlt_iso8601utilconfiguration
49///
50/// # Description {#bdlt_iso8601util-description}
51/// This component provides a namespace, `bdlt::Iso8601Util`,
52/// containing functions that convert `bsls` timeinterval and `bdlt` date, time,
53/// and datetime objects to and from ("generate" and "parse", respectively)
54/// corresponding string representations that are compliant with the ISO 8601
55/// standard. The version of the ISO 8601 standard that is the basis for this
56/// component can be found at:
57/// @code
58/// http://dotat.at/tmp/ISO_8601-2004_E.pdf
59/// @endcode
60/// In general terms, `Iso8601Util` functions support what ISO 8601 refers to as
61/// *complete* *representations* in *extended* *format*. We first present a
62/// brief overview before delving into the details of the ISO 8601
63/// representations that are supported for each of the relevant vocabulary
64/// types.
65///
66/// Each function that *generates* ISO 8601 strings (named `generate` and
67/// `generateRaw`) takes an object and a `char *` buffer, `bsl::string`, or
68/// `bsl::ostream`, and writes an ISO 8601 representation of the object to the
69/// buffer, string, or stream. The "raw" functions are distinguished from their
70/// non-"raw" counterparts in three respects:
71///
72/// * The length of the `char *` buffer is not supplied to the `generateRaw`
73/// functions.
74/// * The `generateRaw` functions do not output a null terminator.
75/// * The `generate` functions that provide an `ptrdiff_t bufferLength`
76/// parameter truncate the generated output to `bufferLength` characters.
77/// (Neither the `generateRaw` functions nor the `generate` functions taking
78/// `bsl::string` or `bsl::ostream` do any truncation of their generated
79/// output.)
80///
81/// Since the generate functions always succeed, no status value is returned.
82/// Instead, either the number of characters output to the `char *` buffer or
83/// string, or a reference to the stream, is returned. (Note that the
84/// generating functions also take an optional `bdlt::Iso8601UtilConfiguration`
85/// object, which is discussed shortly.)
86///
87/// Each function that *parses* ISO 8601 strings (named `parse`) take the
88/// address of a target object and a `const char *` (paired with a `length`
89/// argument) or `bsl::string_view`, and loads the object with the result of
90/// parsing the character string. Since parsing can fail, the parse functions
91/// return an `int` status value (0 for success and a non-zero value for
92/// failure). Note that, besides elementary syntactical considerations, the
93/// validity of parsed strings are subject to the semantic constraints imposed
94/// by the various `isValid*` class methods, (i.e., `Date::isValidYearMonthDay`,
95/// `Time::isValid`, etc.).
96///
97/// ## Terminology {#bdlt_iso8601util-terminology}
98///
99///
100/// As this component concerns ISO 8601, some terms from that specification are
101/// used liberally in what follows. Two ISO 8601 terms of particular note are
102/// *zone* *designator* and *fractional* *second*.
103///
104/// An ISO 8601 *zone* *designator* corresponds to what other `bdlt` components
105/// commonly refer to as a timezone offset (or simply as an offset; e.g., see
106/// @ref bdlt_datetimetz ). For example, the ISO 8601 string
107/// `2002-03-17T15:46:00+04:00` has a zone designator of `+04:00`, indicating a
108/// timezone 4 hours ahead of UTC.
109///
110/// An ISO 8601 *fractional* *second* corresponds to, for example, the
111/// combined `millisecond` and `microsecond` attributes of a `bdlt::Time`
112/// object, or the combined `millisecond` and `microsecond` attributes of a
113/// `bdlt::Datetime` object. For example, the `Time` value (and ISO 8601
114/// string) `15:46:09.330000` has a `millisecond` attribute value of 330 and a
115/// `microsecond` attribute of 0 (i.e., a fractional second of .33).
116///
117/// ## ISO 8601 String Generation {#bdlt_iso8601util-iso-8601-string-generation}
118///
119///
120/// Strings produced by the `generate` and `generateRaw` functions are a
121/// straightforward transposition of the attributes of the source value into an
122/// appropriate ISO 8601 format, and are best illustrated by a few examples.
123/// Note that for `Datetime` and `DatetimeTz`, the fractional second is
124/// generated with the precision specified in the configuration. Also note that
125/// for `Time` and `TimeTz`, the fractional second is generated with the
126/// precision specified in the configuration up to a maximum precision of 6.
127/// @code
128/// +--------------------------------------+---------------------------------+
129/// | Object Value | Generated ISO 8601 String |
130/// | | (using default configuration) |
131/// +======================================+=================================+
132/// | bsls::TimeInterval(1000, 3000000) | PT16M40.003S |
133/// +--------------------------------------+---------------------------------+
134/// | Date(2002, 03, 17) | 2002-03-17 |
135/// +--------------------------------------+---------------------------------+
136/// | Time(15, 46, 09, 330) | 15:46:09.330 |
137/// +--------------------------------------+---------------------------------+
138/// | Datetime(Date(2002, 03, 17) | |
139/// | Time(15, 46, 09, 330)) | 2002-03-17T15:46:09.330 |
140/// +--------------------------------------+---------------------------------+
141/// | DateTz(Date(2002, 03, 17), -120) | 2002-03-17-02:00 [*] |
142/// +--------------------------------------+---------------------------------+
143/// | TimeTz(Time(15, 46, 09, 330), 270) | 15:46:09.330+04:30 |
144/// +--------------------------------------+---------------------------------+
145/// | DatetimeTz(Datetime( | |
146/// | Date(2002, 03, 17), | |
147/// | Time(15, 46, 09, 330)), | |
148/// | 0) | 2002-03-17T15:46:09.330+00:00 |
149/// +--------------------------------------+---------------------------------+
150/// @endcode
151/// [*] Note that the ISO 8601 specification does not have an equivalent to
152/// `bdlt::DateTz`.
153///
154/// ### Configuration {#bdlt_iso8601util-configuration}
155///
156///
157/// The `generate` and `generateRaw` functions provide an optional configuration
158/// parameter. This optional parameter, of type `Iso8601UtilConfiguration`,
159/// enables configuration of four aspects of ISO 8601 string generation:
160///
161/// * The decimal sign to use in fractional seconds: `.` or `,`.
162/// * The precision of the fractional seconds.
163/// * Whether `:` is optional in zone designators.
164/// * Whether `Z` is output for the zone designator instead of `+00:00` (UTC).
165///
166/// `Iso8601UtilConfiguration` has four attributes that directly correspond to
167/// these aspects. In addition, for generate methods that are not supplied with
168/// a configuration argument, a process-wide configuration takes effect. See
169/// @ref bdlt_iso8601utilconfiguration for details.
170///
171/// ## ISO 8601 String Parsing {#bdlt_iso8601util-iso-8601-string-parsing}
172///
173///
174/// The `parse` functions accept *all* strings that are produced by the generate
175/// functions. In addition, the parse functions accept some variation in the
176/// generated strings, the details of which are discussed next. Note that the
177/// parse methods are not configurable like the generate methods (i.e., via an
178/// optional `Iso8601UtilConfiguration` argument). Moreover, the process-wide
179/// configuration has no effect on parsing either. Instead, the parse methods
180/// automatically accept `.` or `,` as the decimal sign in fractional seconds,
181/// and treat `+00:00`, `+0000`, `Z`, and `z` as equivalent zone designators
182/// (all denoting UTC).
183///
184/// Parsing in `Relaxed` mode accepts "relaxed" ISO 8601 format that is a
185/// superset of the strict ISO 8601 format, meaning this function will parse
186/// ISO 8601 values as well as supporting some common variations. Currently
187/// this allows a SPACE character to be used as an alternative separator between
188/// date and time elements (where strict ISO 8601 requires a `T`), but the set
189/// of extensions may grow in the future. `Relaxed` parsing is done by
190/// specifying the relaxed option using the `Iso8601UtilParseConfiguration` type
191/// and passing it to the `parse` functions. There are also `parseRelaxed`
192/// functions which are now deprecated.
193///
194/// ### Zone Designators {#bdlt_iso8601util-zone-designators}
195///
196///
197/// The zone designator is optional, and can be present when parsing for *any*
198/// type other than bsls::TimeInterval, i.e., even for `Date`, `Time`, and
199/// `Datetime`. If a zone designator is parsed for a `Date`, it must be valid,
200/// so it can affect the status value that is returned in that case, but it is
201/// otherwise ignored. For `Time` and `Datetime`, any zone designator present
202/// in the parsed string will affect the resulting object value (unless the zone
203/// designator denotes UTC) because the result is converted to UTC. If the zone
204/// designator is absent, it is treated as if `+00:00` were specified:
205/// @code
206/// +------------------------------------+-----------------------------------+
207/// | Parsed ISO 8601 String | Result Object Value |
208/// +====================================+===================================+
209/// | 2002-03-17-02:00 | Date(2002, 03, 17) |
210/// | | # zone designator ignored |
211/// +------------------------------------+-----------------------------------+
212/// | 2002-03-17-02:65 | Date: parsing fails |
213/// | | # invalid zone designator |
214/// +------------------------------------+-----------------------------------+
215/// | 15:46:09.330+04:30 | Time(11, 16, 09, 330) |
216/// | | # converted to UTC |
217/// +------------------------------------+-----------------------------------+
218/// | 15:46:09.330+04:30 | TimeTz(Time(15, 46, 09, 330), |
219/// | | 270) |
220/// +------------------------------------+-----------------------------------+
221/// | 15:46:09.330 | TimeTz(Time(15, 46, 09, 330), |
222/// | | 0) |
223/// | | # implied '+00:00' |
224/// +------------------------------------+-----------------------------------+
225/// | 2002-03-17T23:46:09.222-05:00 | Datetime(Date(2002, 03, 18), |
226/// | | Time(04, 46, 09, 222)) |
227/// | | # carry into 'day' attribute |
228/// | | # when converted to UTC |
229/// +------------------------------------+-----------------------------------+
230/// @endcode
231/// There is also the `basic` format, which may be specified when parsing by
232/// using the `bdlt::Iso8601UtilParseConfiguration` type, in which case there
233/// are to be no `-`s in the `Date` and no `:`s in the `Time`. The `:` in the
234/// time zone is always optional, whether in basic or default format.
235/// @code
236/// +------------------------------------+-----------------------------------+
237/// | Parsed Basic ISO 8601 String | Result Object Value |
238/// +====================================+===================================+
239/// | 20020317-0200 | Date(2002, 03, 17) |
240/// | | # zone designator ignored |
241/// +------------------------------------+-----------------------------------+
242/// | 20020317-0265 | Date: parsing fails |
243/// | | # invalid zone designator |
244/// +------------------------------------+-----------------------------------+
245/// | 154609.330+0430 | Time(11, 16, 09, 330) |
246/// | | # converted to UTC |
247/// +------------------------------------+-----------------------------------+
248/// | 154609.330+0430 | TimeTz(Time(15, 46, 09, 330), |
249/// | | 270) |
250/// +------------------------------------+-----------------------------------+
251/// | 154609.330 | TimeTz(Time(15, 46, 09, 330), |
252/// | | 0) |
253/// | | # implied '+00:00' |
254/// +------------------------------------+-----------------------------------+
255/// | 20020317T234609.222-0500 | Datetime(Date(2002, 03, 18), |
256/// | | Time(04, 46, 09, 222)) |
257/// | | # carry into 'day' attribute |
258/// | | # when converted to UTC |
259/// +------------------------------------+-----------------------------------+
260/// @endcode
261/// In the last example above, the conversion to UTC incurs a carry into the
262/// `day` attribute of the `Date` component of the resulting `Datetime` value.
263/// Note that if such a carry causes an underflow or overflow at the extreme
264/// ends of the valid range of dates (0001/01/01 and 9999/12/31), then parsing
265/// for `Datetime` fails.
266///
267/// ### Fractional Seconds {#bdlt_iso8601util-fractional-seconds}
268///
269///
270/// The fractional second is optional. When the fractional second is absent, it
271/// is treated as if `.0` were specified. When the fractional second is
272/// present, it can have one or more digits (i.e., it can contain more than
273/// six). For `Datetime`, `DatetimeTz`, `Time`, and `TimeTz`, if more than six
274/// digits are included in the fractional second, values are rounded to a full
275/// microsecond; i.e., values greater than or equal to .5 microseconds are
276/// rounded up. For `bsls::TimeInterval`, if more than nine digits are included
277/// in the fractional second, values are rounded to a full nanosecond; i.e.,
278/// values greater than or equal to .5 microseconds are rounded up. These
279/// roundings may incur a carry of one second into the `second` attribute:
280/// @code
281/// +--------------------------------------+---------------------------------+
282/// | Parsed ISO 8601 String | Result Object Value |
283/// +======================================+=================================+
284/// | 15:46:09.1 | Time(15, 46, 09, 100) |
285/// +--------------------------------------+---------------------------------+
286/// | 15:46:09-05:00 | TimeTz(Time(15, 46, 09, 000), |
287/// | | -300) |
288/// | | # implied '.0' |
289/// +--------------------------------------+---------------------------------+
290/// | 15:46:09.99999949 | Time(15, 46, 09, 999, 999) |
291/// | | # truncate last two digits |
292/// +--------------------------------------+---------------------------------+
293/// | 15:46:09.9999995 | Time(15, 46, 10, 000, 000) |
294/// | | # round up and carry |
295/// +--------------------------------------+---------------------------------+
296/// @endcode
297/// Note that, for `Datetime` and `DatetimeTz`, if a carry due to rounding of
298/// the fractional second would cause an overflow at the extreme upper end of
299/// the valid range of dates (i.e., 9999/12/31), then parsing would fail.
300///
301/// ### Leap Seconds {#bdlt_iso8601util-leap-seconds}
302///
303///
304/// Leap seconds are not representable by `bdlt::Time` or `bdlt::Datetime`.
305/// Hence, they are not produced by any of the `Iso8601Util` generate functions.
306/// However, positive leap seconds *are* supported by the parse functions. A
307/// leap second is recognized when the value parsed for the `second` attribute
308/// of a `Time` is 60 -- regardless of the values parsed for the `hour`,
309/// `minute`, `millisecond`, and `microsecond` attributes. Note that this
310/// behavior is more generous than that afforded by the ISO 8601 specification
311/// (which indicates that a positive leap second can only be represented as
312/// "23:59:60Z").
313///
314/// When a leap second is detected during parsing of an ISO 8601 string, the
315/// `second` attribute is taken to be 59, so that the value of the `Time` object
316/// can be validly set; then an additional second is added to the object. Note
317/// that the possible carry incurred by a leap second (i.e., when loading the
318/// result of parsing into a `Datetime` or `DatetimeTz` object) has the same
319/// potential for overflow as may occur with fractional seconds that are rounded
320/// up (although in admittedly pathological cases).
321///
322/// ### The Time 24:00 {#bdlt_iso8601util-the-time-24-00}
323///
324///
325/// According to the ISO 8601 specification, the time 24:00 is interpreted as
326/// midnight, i.e., the last instant of a day. However, this concept is not
327/// supported by `bdlt`. Although 24:00 is *representable* by `bdlt`, i.e., as
328/// the default value for `bdlt::Time`, `Time(24, 0)` does *not* represent
329/// midnight when it is the value for the "time" attribute of a `Datetime` (or
330/// `DatetimeTz`) object. For example:
331/// @code
332/// bdlt::Datetime notMidnight =
333/// bdlt::Datetime(bdlt::Date(2002, 03, 17), bdlt::Time(24, 0, 0));
334///
335/// notMidnight.addSeconds(1);
336/// assert(notMidnight ==
337/// bdlt::Datetime(bdlt::Date(2002, 03, 17), bdlt::Time( 0, 0, 1));
338/// @endcode
339/// It is important to be aware of this peculiarity of `Datetime` (and
340/// `DatetimeTz`) as it relates to ISO 8601.
341///
342/// The following table shows some examples of parsing an ISO 8601 string
343/// containing "24:00". Note that parsing fails if the zone designator is not
344/// equivalent to "+00:00" when the time 24:00 is encountered:
345/// @code
346/// +------------------------------------+-----------------------------------+
347/// | Parsed ISO 8601 String | Result Object Value |
348/// +====================================+===================================+
349/// | 24:00:00.000000 | Time(24, 0, 0, 0) |
350/// | | # preserve default 'Time' value |
351/// +------------------------------------+-----------------------------------+
352/// | 24:00:00.000000-04:00 | TimeTz: parsing fails |
353/// | | # zone designator not UTC |
354/// +------------------------------------+-----------------------------------+
355/// | 0001-01-01T24:00:00.000000 | Datetime(Date(0001, 01, 01), |
356/// | | Time(24, 0, 0, 0)) |
357/// | | # preserve 'Datetime' default |
358/// | | # value |
359/// +------------------------------------+-----------------------------------+
360/// | 2002-03-17T24:00:00.000000 | Datetime(Date(2002, 03, 17), |
361/// | | Time(24, 0, 0, 0)) |
362/// | | # preserve default 'Time' value |
363/// +------------------------------------+-----------------------------------+
364/// @endcode
365/// An `hour` attribute value of 24 is also "preserved" by the generate
366/// functions provided by this component:
367/// @code
368/// +------------------------------------+-----------------------------------+
369/// | Source Object Value | Generated ISO 8601 String |
370/// +====================================+===================================+
371/// | Time(24, 0, 0, 0) | 24:00:00.000 |
372/// +------------------------------------+-----------------------------------+
373/// | Datetime(Date(2002, 03, 17), | 2002-03-17T24:00:00.000 |
374/// | Time(24, 0, 0, 0)) | |
375/// +------------------------------------+-----------------------------------+
376/// @endcode
377///
378/// ### Summary of Supported ISO 8601 Representations {#bdlt_iso8601util-summary-of-supported-iso-8601-representations}
379///
380///
381/// The syntax description below summarizes the ISO 8601 string representations
382/// supported by this component. Although not quoted (for readability),
383/// `[+-:.,TtZz]` are literal characters that can occur in ISO 8601 strings.
384/// Furthermore, for clarity, the (rarely used) lowercase `t` and `z` characters
385/// are omitted from the specifications below, as well as from the
386/// function-level documentation. The characters `[YMDhms]` each denote a
387/// decimal digit, `{}` brackets optional elements, `()` is used for grouping,
388/// and `|` separates alternatives:
389/// @code
390/// <Generated Date> ::= <DATE>
391///
392/// <Parsed Date> ::= <Parsed DateTz>
393///
394/// <Generated DateTz> ::= <DATE><ZONE>
395///
396/// <Parsed DateTz> ::= <DATE>{<ZONE>}
397///
398/// <Generated Time> ::= <TIME FLEXIBLE>
399///
400/// <Parsed Time> ::= <Parsed TimeTz>
401///
402/// <Generated TimeTz> ::= <TIME FLEXIBLE><ZONE>
403///
404/// <Parsed TimeTz> ::= <TIME FLEXIBLE>{<ZONE>}
405///
406/// <Generated Datetime> ::= <DATE>T<TIME FLEXIBLE>
407///
408/// <Parsed Datetime> ::= <Parsed DatetimeTz>
409///
410/// <Generated DatetimeTz> ::= <DATE>T<TIME FLEXIBLE><ZONE>
411///
412/// <Parsed DatetimeTz> ::= <DATE>(T|t)<TIME FLEXIBLE>{<ZONE>}
413/// (Default)
414///
415/// <Parsed DatetimeTz> ::= <DATE>(T|t| )<TIME FLEXIBLE>{<ZONE>}
416/// (Relaxed)
417///
418/// <DATE> (Default) ::= YYYY-MM-DD
419///
420/// <DATE> (Basic) ::= YYYYMMDD
421///
422/// <TIME FLEXIBLE> (Default) ::= hh:mm:ss{(.|,)s+} # one or more digits in
423/// # the fractional second
424///
425/// <TIME FLEXIBLE> (Basic) ::= hhmmss{(.|,)s+} # one or more digits in the
426/// # fractional second
427///
428/// <ZONE> ::= (+|-)hh{:}mm|Z # zone designator (':' is
429/// # optional whether default
430/// # or basic)
431/// @endcode
432///
433/// ### Summary of Supported ISO 8601 Duration Representations {#bdlt_iso8601util-summary-of-supported-iso-8601-duration-representations}
434///
435///
436/// The syntax description below summarizes the ISO 8601 string representations
437/// for durations supported by this component. Although not quoted (for
438/// readability), `[.,PWDTHMS]` are literal characters that can occur in ISO
439/// 8601 strings. The characters `[wdhms]` each denote a decimal digit, `{}`
440/// brackets optional elements, `()` is used for grouping, and `|` separates
441/// alternatives:
442/// @code
443/// <Date Duration> ::= {w+W}{d+D}
444///
445/// <Time Duration> ::= T{h+H}{m+M}{s+{(.|,)s+}S} # must contain
446/// # at least one
447/// # optional field
448/// # (i.e. "T" is
449/// # not valid)
450///
451/// <Generated Duration> ::= P<Date Duration><Time Duration> # all values
452/// # guaranteed to
453/// # be less than
454/// # their modulus
455/// # (weeks can be
456/// # be up to 14
457/// # digits), and
458/// # it must
459/// # contain the
460/// # seconds
461/// # portion
462///
463/// <Parsed Duration> ::= P<Date Duration>{<Time Duration>} # must contain
464/// # at least one
465/// # optional field
466/// # in <Date
467/// # Duration> or
468/// # must contain
469/// # a <Time
470/// # Duration>
471/// # (i.e. "P" is
472/// # not valid)
473/// @endcode
474///
475/// ## Usage {#bdlt_iso8601util-usage}
476///
477///
478/// This section illustrates intended use of this component.
479///
480/// ### Example 1: Basic bdlt::Iso8601Util Usage {#bdlt_iso8601util-example-1-basic-bdlt-iso8601util-usage}
481///
482///
483/// This example demonstrates basic use of one `generate` function and two
484/// `parse` functions.
485///
486/// First, we construct a few objects that are prerequisites for this and the
487/// following example:
488/// @code
489/// const bdlt::Date date(2005, 1, 31); // 2005/01/31
490/// const bdlt::Time time(8, 59, 59, 123); // 08:59:59.123
491/// const int tzOffset = 240; // +04:00 (four hours west of UTC)
492/// @endcode
493/// Then, we construct a `bdlt::DatetimeTz` object for which a corresponding ISO
494/// 8601-compliant string will be generated shortly:
495/// @code
496/// const bdlt::DatetimeTz sourceDatetimeTz(bdlt::Datetime(date, time),
497/// tzOffset);
498/// @endcode
499/// For comparison with the ISO 8601 string generated below, note that streaming
500/// the value of `sourceDatetimeTz` to `stdout`:
501/// @code
502/// bsl::cout << sourceDatetimeTz << bsl::endl;
503/// @endcode
504/// produces:
505/// @code
506/// 31JAN2005_08:59:59.123000+0400
507/// @endcode
508/// Next, we use a `generate` function to produce an ISO 8601-compliant string
509/// for `sourceDatetimeTz`, writing the output to a `bsl::ostringstream`, and
510/// assert that both the return value and the string that is produced are as
511/// expected:
512/// @code
513/// bsl::ostringstream oss;
514/// const bsl::ostream& ret =
515/// bdlt::Iso8601Util::generate(oss, sourceDatetimeTz);
516/// assert(&oss == &ret);
517///
518/// const bsl::string iso8601 = oss.str();
519/// assert(iso8601 == "2005-01-31T08:59:59.123+04:00");
520/// @endcode
521/// For comparison, see the output that was produced by the streaming operator
522/// above.
523///
524/// Now, we parse the string that was just produced, loading the result of the
525/// parse into a second `bdlt::DatetimeTz` object, and assert that the parse was
526/// successful and that the target object has the same value as that of the
527/// original (i.e., `sourceDatetimeTz`):
528/// @code
529/// bdlt::DatetimeTz targetDatetimeTz;
530///
531/// int rc = bdlt::Iso8601Util::parse(&targetDatetimeTz,
532/// iso8601.c_str(),
533/// static_cast<int>(iso8601.length()));
534/// assert( 0 == rc);
535/// assert(sourceDatetimeTz == targetDatetimeTz);
536/// @endcode
537/// Finally, we parse the `iso8601` string a second time, this time loading the
538/// result into a `bdlt::Datetime` object (instead of a `bdlt::DatetimeTz`):
539/// @code
540/// bdlt::Datetime targetDatetime;
541///
542/// rc = bdlt::Iso8601Util::parse(&targetDatetime,
543/// iso8601.c_str(),
544/// static_cast<int>(iso8601.length()));
545/// assert( 0 == rc);
546/// assert(sourceDatetimeTz.utcDatetime() == targetDatetime);
547/// @endcode
548/// Note that this time the value of the target object has been converted to
549/// UTC.
550///
551/// ### Example 2: Configuring ISO 8601 String Generation {#bdlt_iso8601util-example-2-configuring-iso-8601-string-generation}
552///
553///
554/// This example demonstrates use of a `bdlt::Iso8601UtilConfiguration` object
555/// to influence the format of the ISO 8601 strings that are generated by this
556/// component by passing that configuration object to `generate`. We also take
557/// this opportunity to illustrate the flavor of the `generate` functions that
558/// outputs to a `char *` buffer of a specified length.
559///
560/// First, we construct a `bdlt::TimeTz` object for which a corresponding ISO
561/// 8601-compliant string will be generated shortly:
562/// @code
563/// const bdlt::TimeTz sourceTimeTz(time, tzOffset);
564/// @endcode
565/// For comparison with the ISO 8601 string generated below, note that streaming
566/// the value of `sourceTimeTz` to `stdout`:
567/// @code
568/// bsl::cout << sourceTimeTz << bsl::endl;
569/// @endcode
570/// produces:
571/// @code
572/// 08:59:59.123+0400
573/// @endcode
574/// Then, we construct the `bdlt::Iso8601UtilConfiguration` object that
575/// indicates how we would like to affect the generated output ISO 8601 string.
576/// In this case, we want to use `,` as the decimal sign (in fractional seconds)
577/// and omit the `:` in zone designators:
578/// @code
579/// bdlt::Iso8601UtilConfiguration configuration;
580/// configuration.setOmitColonInZoneDesignator(true);
581/// configuration.setUseCommaForDecimalSign(true);
582/// @endcode
583/// Next, we define the `char *` buffer that will be used to stored the
584/// generated string. A buffer of size `bdlt::Iso8601Util::k_TIMETZ_STRLEN + 1`
585/// is large enough to hold any string generated by this component for a
586/// `bdlt::TimeTz` object, including a null terminator:
587/// @code
588/// const int BUFLEN = bdlt::Iso8601Util::k_TIMETZ_STRLEN + 1;
589/// char buffer[BUFLEN];
590/// @endcode
591/// Then, we use a `generate` function that accepts our `configuration` to
592/// produce an ISO 8601-compliant string for `sourceTimeTz`, this time writing
593/// the output to a `char *` buffer, and assert that both the return value and
594/// the string that is produced are as expected. Note that in comparing the
595/// return value against `BUFLEN - 5` we account for the omission of the `:`
596/// from the zone designator, and also for the fact that, although a null
597/// terminator was generated, it is not included in the character count returned
598/// by `generate`. Also note that we use `bsl::strcmp` to compare the resulting
599/// string knowing that we supplied a buffer having sufficient capacity to
600/// accommodate a null terminator:
601/// @code
602/// rc = bdlt::Iso8601Util::generate(buffer,
603/// BUFLEN,
604/// sourceTimeTz,
605/// configuration);
606/// assert(BUFLEN - 5 == rc);
607/// assert( 0 == bsl::strcmp(buffer, "08:59:59,123+0400"));
608/// @endcode
609/// For comparison, see the output that was produced by the streaming operator
610/// above.
611///
612/// Next, we parse the string that was just produced, loading the result of the
613/// parse into a second `bdlt::TimeTz` object, and assert that the parse was
614/// successful and that the target object has the same value as that of the
615/// original (i.e., `sourceTimeTz`). Note that `BUFLEN - 5` is passed and *not*
616/// `BUFLEN` because the former indicates the correct number of characters in
617/// `buffer` that we wish to parse:
618/// @code
619/// bdlt::TimeTz targetTimeTz;
620///
621/// rc = bdlt::Iso8601Util::parse(&targetTimeTz, buffer, BUFLEN - 5);
622///
623/// assert( 0 == rc);
624/// assert(sourceTimeTz == targetTimeTz);
625/// @endcode
626/// Then, we parse the string in `buffer` a second time, this time loading the
627/// result into a `bdlt::Time` object (instead of a `bdlt::TimeTz`):
628/// @code
629/// bdlt::Time targetTime;
630///
631/// rc = bdlt::Iso8601Util::parse(&targetTime, buffer, BUFLEN - 5);
632/// assert( 0 == rc);
633/// assert(sourceTimeTz.utcTime() == targetTime);
634/// @endcode
635/// Note that this time the value of the target object has been converted to
636/// UTC.
637///
638/// Finally, we modify the `configuration` to display the `bdlt::TimeTz` without
639/// fractional seconds:
640/// @code
641/// configuration.setFractionalSecondPrecision(0);
642/// rc = bdlt::Iso8601Util::generate(buffer,
643/// BUFLEN,
644/// sourceTimeTz,
645/// configuration);
646/// assert(BUFLEN - 9 == rc);
647/// assert( 0 == bsl::strcmp(buffer, "08:59:59+0400"));
648/// @endcode
649/// @}
650/** @} */
651/** @} */
652
653/** @addtogroup bdl
654 * @{
655 */
656/** @addtogroup bdlt
657 * @{
658 */
659/** @addtogroup bdlt_iso8601util
660 * @{
661 */
662
663#include <bdlscm_version.h>
664
665#include <bdlt_date.h>
666#include <bdlt_datetime.h>
667#include <bdlt_datetimetz.h>
668#include <bdlt_datetz.h>
669#include <bdlt_iso8601utilconfiguration.h>
670#include <bdlt_iso8601utilparseconfiguration.h>
671#include <bdlt_time.h>
672#include <bdlt_timetz.h>
673
674#include <bdlb_variant.h>
675
676#include <bslmf_assert.h>
677#include <bslmf_issame.h>
678
679#include <bsls_assert.h>
680#include <bsls_deprecatefeature.h>
681#include <bsls_libraryfeatures.h>
682#include <bsls_types.h>
683
684#include <bsl_cstddef.h>
685#include <bsl_ostream.h>
686#include <bsl_string.h>
687
688#include <string>
689
690
691namespace bsls {
692
693class TimeInterval;
694
695} // close namespace bsls
696
697#define BDLT_ISO8601UTIL_DEPRECATE_GENERATE \
698 BSLS_DEPRECATE_FEATURE("bdl", \
699 "generate", \
700 "use overload with GenerateConfiguration")
701
702#define BDLT_ISO8601UTIL_DEPRECATE_GENERATE_ORDER \
703 BSLS_DEPRECATE_FEATURE("bdl", \
704 "generate", \
705 "use overload with length before object")
706
707#define BDLT_ISO8601UTIL_DEPRECATE_GENERATERAW \
708 BSLS_DEPRECATE_FEATURE("bdl", \
709 "generateRaw", \
710 "use overload with GenerateConfiguration")
711
712#define BDLT_ISO8601UTIL_DEPRECATE_PARSERELAXED \
713 BSLS_DEPRECATE_FEATURE("bdl", \
714 "parseRelaxed", \
715 "use parse with ParseConfiguration")
716
717namespace bdlt {
718
719
720 // ==================
721 // struct Iso8601Util
722 // ==================
723
724/// This `struct` provides a namespace for a suite of pure functions that
725/// perform conversions between objects of `bdlt` vocabulary type and their
726/// ISO 8601 representations. Each `generate` and `generateRaw` method
727/// takes a `bdlt` object (of type `Date`, `DateTz`, `Time`, `TimeTz`,
728/// `Datetime`, or `DatetimeTz`) and outputs its corresponding ISO 8601
729/// representation to a user-supplied character buffer or `bsl::ostream`.
730/// The `parse` methods effect the opposite conversion in that they populate
731/// a `bdlt` object from the result of parsing an ISO 8601 representation.
732struct Iso8601Util {
733
734 private:
735 // PRIVATE CLASS METHODS
736
737 /// Return a default configured configuration object.
738 static Iso8601UtilConfiguration defaultConfiguration();
739
740 public:
741 // TYPES
742
743 // This enumeration defines fixed lengths for the ISO 8601
744 // representations of date, time, and datetime values. Note that these
745 // constants do *not* account for the null terminator that may be
746 // produced by the `generate` functions taking a `bufferLength`
747 // argument.
748 enum {
749
750 k_DATE_STRLEN = 10, // `bdlt::Date`
751 k_DATETZ_STRLEN = 16, // `bdlt::DateTz`
752
753 k_TIME_STRLEN = 15, // `bdlt::Time`
754 k_TIMETZ_STRLEN = 21, // `bdlt::TimeTz`
755
756 k_DATETIME_STRLEN = 26, // `bdlt::Datetime`
757 k_DATETIMETZ_STRLEN = 32, // `bdlt::DatetimeTz`
758
759 k_TIMEINTERVAL_STRLEN = 38, // `bsls::TimeInterval`
760
761 k_MAX_STRLEN = k_TIMEINTERVAL_STRLEN
762
763#ifndef BDE_OMIT_INTERNAL_DEPRECATED
764 , BDEPU_DATE_STRLEN = k_DATE_STRLEN
765 , BDEPU_DATETIME_STRLEN = k_DATETIME_STRLEN
766 , BDEPU_DATETIMETZ_STRLEN = k_DATETIMETZ_STRLEN
767 , BDEPU_DATETZ_STRLEN = k_DATETZ_STRLEN
768 , BDEPU_TIME_STRLEN = k_TIME_STRLEN
769 , BDEPU_TIMETZ_STRLEN = k_TIMETZ_STRLEN
770 , BDEPU_MAX_DATETIME_STRLEN = k_MAX_STRLEN
771
772 , DATE_STRLEN = k_DATE_STRLEN
773 , DATETIME_STRLEN = k_DATETIME_STRLEN
774 , DATETIMETZ_STRLEN = k_DATETIMETZ_STRLEN
775 , DATETZ_STRLEN = k_DATETZ_STRLEN
776 , TIME_STRLEN = k_TIME_STRLEN
777 , TIMETZ_STRLEN = k_TIMETZ_STRLEN
778 , MAX_DATETIME_STRLEN = k_MAX_STRLEN
779#endif // BDE_OMIT_INTERNAL_DEPRECATED
780 };
781
782 typedef bsl::ptrdiff_t ssize_t;
783
784 typedef Iso8601UtilConfiguration Configuration;
785
786 /// Configuration for string generation.
787 typedef Iso8601UtilConfiguration GenerateConfiguration;
788
789 /// Configuration for string parsing.
790 typedef Iso8601UtilParseConfiguration ParseConfiguration;
791
792 /// `DateOrDateTz` is a convenient alias for
793 /// `bdlb::Variant2<Date, DateTz>`.
794 typedef bdlb::Variant2<Date, DateTz> DateOrDateTz;
795
796 /// `TimeOrTimeTz` is a convenient alias for
797 /// `bdlb::Variant2<Time, TimeTz>`.
798 typedef bdlb::Variant2<Time, TimeTz> TimeOrTimeTz;
799
800 /// `DatetimeOrDatetimeTz` is a convenient alias for
801 /// `bdlb::Variant2<Datetime, DatetimeTz>`.
802 typedef bdlb::Variant2<Datetime, DatetimeTz> DatetimeOrDatetimeTz;
803
804 // CLASS METHODS
805
806 static int generate(char *buffer,
807 ssize_t bufferLength,
808 const bsls::TimeInterval& object);
809 static int generate(char *buffer,
810 ssize_t bufferLength,
811 const bsls::TimeInterval& object,
812 const GenerateConfiguration& configuration);
813 static int generate(char *buffer,
814 ssize_t bufferLength,
815 const Date& object);
816 static int generate(char *buffer,
817 ssize_t bufferLength,
818 const Date& object,
819 const GenerateConfiguration& configuration);
820 static int generate(char *buffer,
821 ssize_t bufferLength,
822 const Time& object);
823 static int generate(char *buffer,
824 ssize_t bufferLength,
825 const Time& object,
826 const GenerateConfiguration& configuration);
827 static int generate(char *buffer,
828 ssize_t bufferLength,
829 const Datetime& object);
830 static int generate(char *buffer,
831 ssize_t bufferLength,
832 const Datetime& object,
833 const GenerateConfiguration& configuration);
834 static int generate(char *buffer,
835 ssize_t bufferLength,
836 const DateTz& object);
837 static int generate(char *buffer,
838 ssize_t bufferLength,
839 const DateTz& object,
840 const GenerateConfiguration& configuration);
841 static int generate(char *buffer,
842 ssize_t bufferLength,
843 const TimeTz& object);
844 static int generate(char *buffer,
845 ssize_t bufferLength,
846 const TimeTz& object,
847 const GenerateConfiguration& configuration);
848 static int generate(char *buffer,
849 ssize_t bufferLength,
850 const DatetimeTz& object);
851 static int generate(char *buffer,
852 ssize_t bufferLength,
853 const DatetimeTz& object,
854 const GenerateConfiguration& configuration);
855 static int generate(char *buffer,
856 ssize_t bufferLength,
857 const DateOrDateTz& object);
858 static int generate(char *buffer,
859 ssize_t bufferLength,
860 const DateOrDateTz& object,
861 const GenerateConfiguration& configuration);
862 static int generate(char *buffer,
863 ssize_t bufferLength,
864 const TimeOrTimeTz& object);
865 static int generate(char *buffer,
866 ssize_t bufferLength,
867 const TimeOrTimeTz& object,
868 const GenerateConfiguration& configuration);
869 static int generate(char *buffer,
870 ssize_t bufferLength,
871 const DatetimeOrDatetimeTz& object);
872 static int generate(char *buffer,
873 ssize_t bufferLength,
874 const DatetimeOrDatetimeTz& object,
875 const GenerateConfiguration& configuration);
876
877 static int generate(bsl::string *string,
878 const bsls::TimeInterval& object);
879 static int generate(bsl::string *string,
880 const bsls::TimeInterval& object,
881 const GenerateConfiguration& configuration);
882 static int generate(bsl::string *string,
883 const Date& object);
884 static int generate(bsl::string *string,
885 const Date& object,
886 const GenerateConfiguration& configuration);
887 static int generate(bsl::string *string,
888 const Time& object);
889 static int generate(bsl::string *string,
890 const Time& object,
891 const GenerateConfiguration& configuration);
892 static int generate(bsl::string *string,
893 const Datetime& object);
894 static int generate(bsl::string *string,
895 const Datetime& object,
896 const GenerateConfiguration& configuration);
897 static int generate(bsl::string *string,
898 const DateTz& object);
899 static int generate(bsl::string *string,
900 const DateTz& object,
901 const GenerateConfiguration& configuration);
902 static int generate(bsl::string *string,
903 const TimeTz& object);
904 static int generate(bsl::string *string,
905 const TimeTz& object,
906 const GenerateConfiguration& configuration);
907 static int generate(bsl::string *string,
908 const DatetimeTz& object);
909 static int generate(bsl::string *string,
910 const DatetimeTz& object,
911 const GenerateConfiguration& configuration);
912 static int generate(bsl::string *string,
913 const DateOrDateTz& object);
914 static int generate(bsl::string *string,
915 const DateOrDateTz& object,
916 const GenerateConfiguration& configuration);
917 static int generate(bsl::string *string,
918 const TimeOrTimeTz& object);
919 static int generate(bsl::string *string,
920 const TimeOrTimeTz& object,
921 const GenerateConfiguration& configuration);
922 static int generate(bsl::string *string,
923 const DatetimeOrDatetimeTz& object);
924 static int generate(bsl::string *string,
925 const DatetimeOrDatetimeTz& object,
926 const GenerateConfiguration& configuration);
927 static int generate(std::string *string,
928 const bsls::TimeInterval& object);
929 static int generate(std::string *string,
930 const bsls::TimeInterval& object,
931 const GenerateConfiguration& configuration);
932 static int generate(std::string *string,
933 const Date& object);
934 static int generate(std::string *string,
935 const Date& object,
936 const GenerateConfiguration& configuration);
937 static int generate(std::string *string,
938 const Time& object);
939 static int generate(std::string *string,
940 const Time& object,
941 const GenerateConfiguration& configuration);
942 static int generate(std::string *string,
943 const Datetime& object);
944 static int generate(std::string *string,
945 const Datetime& object,
946 const GenerateConfiguration& configuration);
947 static int generate(std::string *string,
948 const DateTz& object);
949 static int generate(std::string *string,
950 const DateTz& object,
951 const GenerateConfiguration& configuration);
952 static int generate(std::string *string,
953 const TimeTz& object);
954 static int generate(std::string *string,
955 const TimeTz& object,
956 const GenerateConfiguration& configuration);
957 static int generate(std::string *string,
958 const DatetimeTz& object);
959 static int generate(std::string *string,
960 const DatetimeTz& object,
961 const GenerateConfiguration& configuration);
962 static int generate(std::string *string,
963 const DateOrDateTz& object);
964 static int generate(std::string *string,
965 const DateOrDateTz& object,
966 const GenerateConfiguration& configuration);
967 static int generate(std::string *string,
968 const TimeOrTimeTz& object);
969 static int generate(std::string *string,
970 const TimeOrTimeTz& object,
971 const GenerateConfiguration& configuration);
972 static int generate(std::string *string,
973 const DatetimeOrDatetimeTz& object);
974 /// Write the ISO 8601 representation of the specified `object` to the
975 /// specified `buffer` of the specified `bufferLength` (in bytes),
976 /// truncating (if necessary) to `bufferLength`. Optionally specify a
977 /// `configuration` to affect the format of the generated string. If
978 /// `configuration` is not supplied, the process-wide default value
979 /// `Iso8601UtilConfiguration::defaultConfiguration()` is used. Return
980 /// the number of characters in the formatted string before truncation
981 /// (not counting a null terminator). If `bufferLength` indicates
982 /// sufficient capacity, `buffer` is null terminated. The behavior is
983 /// undefined unless `0 <= bufferLength`. Note that a buffer of size
984 /// `k_MAX_STRLEN + 1` is large enough to hold any string generated by
985 /// this component (counting a null terminator, if any).
986 static int generate(std::string *string,
987 const DatetimeOrDatetimeTz& object,
988 const GenerateConfiguration& configuration);
989
990#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
991 static int generate(std::pmr::string *string,
992 const bsls::TimeInterval& object);
993 static int generate(std::pmr::string *string,
994 const bsls::TimeInterval& object,
995 const GenerateConfiguration& configuration);
996 static int generate(std::pmr::string *string,
997 const Date& object);
998 static int generate(std::pmr::string *string,
999 const Date& object,
1000 const GenerateConfiguration& configuration);
1001 static int generate(std::pmr::string *string,
1002 const Time& object);
1003 static int generate(std::pmr::string *string,
1004 const Time& object,
1005 const GenerateConfiguration& configuration);
1006 static int generate(std::pmr::string *string,
1007 const Datetime& object);
1008 static int generate(std::pmr::string *string,
1009 const Datetime& object,
1010 const GenerateConfiguration& configuration);
1011 static int generate(std::pmr::string *string,
1012 const DateTz& object);
1013 static int generate(std::pmr::string *string,
1014 const DateTz& object,
1015 const GenerateConfiguration& configuration);
1016 static int generate(std::pmr::string *string,
1017 const TimeTz& object);
1018 static int generate(std::pmr::string *string,
1019 const TimeTz& object,
1020 const GenerateConfiguration& configuration);
1021 static int generate(std::pmr::string *string,
1022 const DatetimeTz& object);
1023 static int generate(std::pmr::string *string,
1024 const DatetimeTz& object,
1025 const GenerateConfiguration& configuration);
1026 static int generate(std::pmr::string *string,
1027 const DateOrDateTz& object);
1028 static int generate(std::pmr::string *string,
1029 const DateOrDateTz& object,
1030 const GenerateConfiguration& configuration);
1031 static int generate(std::pmr::string *string,
1032 const TimeOrTimeTz& object);
1033 static int generate(std::pmr::string *string,
1034 const TimeOrTimeTz& object,
1035 const GenerateConfiguration& configuration);
1036 static int generate(std::pmr::string *string,
1037 const DatetimeOrDatetimeTz& object);
1038 /// Load the ISO 8601 representation of the specified `object` into the
1039 /// specified `string` of type `bsl::string`, `std::string`, or
1040 /// `std::pmr::string`. Optionally specify a `configuration` to affect
1041 /// the format of the generated string. If `configuration` is not
1042 /// supplied, the process-wide default value
1043 /// `Iso8601UtilConfiguration::defaultConfiguration()` is used. Return
1044 /// the number of characters in the formatted string. The previous
1045 /// contents of `string` (if any) are discarded.
1046 static int generate(std::pmr::string *string,
1047 const DatetimeOrDatetimeTz& object,
1048 const GenerateConfiguration& configuration);
1049#endif
1050
1051 /// Write the ISO 8601 representation of the specified `object` to the
1052 /// specified `stream`. Optionally specify a `configuration` to affect
1053 /// the format of the generated string. If `configuration` is not
1054 /// supplied, the process-wide default value
1055 /// `Iso8601UtilConfiguration::defaultConfiguration()` is used. Return
1056 /// a reference to `stream`. Note that `stream` is not null terminated.
1057 static bsl::ostream& generate(
1058 bsl::ostream& stream,
1059 const bsls::TimeInterval& object);
1060 static bsl::ostream& generate(
1061 bsl::ostream& stream,
1062 const bsls::TimeInterval& object,
1063 const GenerateConfiguration& configuration);
1064 static bsl::ostream& generate(
1065 bsl::ostream& stream,
1066 const Date& object);
1067 static bsl::ostream& generate(
1068 bsl::ostream& stream,
1069 const Date& object,
1070 const GenerateConfiguration& configuration);
1071 static bsl::ostream& generate(
1072 bsl::ostream& stream,
1073 const Time& object);
1074 static bsl::ostream& generate(
1075 bsl::ostream& stream,
1076 const Time& object,
1077 const GenerateConfiguration& configuration);
1078 static bsl::ostream& generate(
1079 bsl::ostream& stream,
1080 const Datetime& object);
1081 static bsl::ostream& generate(
1082 bsl::ostream& stream,
1083 const Datetime& object,
1084 const GenerateConfiguration& configuration);
1085 static bsl::ostream& generate(
1086 bsl::ostream& stream,
1087 const DateTz& object);
1088 static bsl::ostream& generate(
1089 bsl::ostream& stream,
1090 const DateTz& object,
1091 const GenerateConfiguration& configuration);
1092 static bsl::ostream& generate(
1093 bsl::ostream& stream,
1094 const TimeTz& object);
1095 static bsl::ostream& generate(
1096 bsl::ostream& stream,
1097 const TimeTz& object,
1098 const GenerateConfiguration& configuration);
1099 static bsl::ostream& generate(
1100 bsl::ostream& stream,
1101 const DatetimeTz& object);
1102 static bsl::ostream& generate(
1103 bsl::ostream& stream,
1104 const DatetimeTz& object,
1105 const GenerateConfiguration& configuration);
1106 static bsl::ostream& generate(
1107 bsl::ostream& stream,
1108 const DateOrDateTz& object);
1109 static bsl::ostream& generate(
1110 bsl::ostream& stream,
1111 const DateOrDateTz& object,
1112 const GenerateConfiguration& configuration);
1113 static bsl::ostream& generate(
1114 bsl::ostream& stream,
1115 const TimeOrTimeTz& object);
1116 static bsl::ostream& generate(
1117 bsl::ostream& stream,
1118 const TimeOrTimeTz& object,
1119 const GenerateConfiguration& configuration);
1120 static bsl::ostream& generate(
1121 bsl::ostream& stream,
1122 const DatetimeOrDatetimeTz& object);
1123 static bsl::ostream& generate(
1124 bsl::ostream& stream,
1125 const DatetimeOrDatetimeTz& object,
1126 const GenerateConfiguration& configuration);
1127
1128 static int generateRaw(char *buffer,
1129 const bsls::TimeInterval& object);
1130 static int generateRaw(char *buffer,
1131 const bsls::TimeInterval& object,
1132 const GenerateConfiguration& configuration);
1133 static int generateRaw(char *buffer,
1134 const Date& object);
1135 static int generateRaw(char *buffer,
1136 const Date& object,
1137 const GenerateConfiguration& configuration);
1138 static int generateRaw(char *buffer,
1139 const Time& object);
1140 static int generateRaw(char *buffer,
1141 const Time& object,
1142 const GenerateConfiguration& configuration);
1143 static int generateRaw(char *buffer,
1144 const Datetime& object);
1145 static int generateRaw(char *buffer,
1146 const Datetime& object,
1147 const GenerateConfiguration& configuration);
1148 static int generateRaw(char *buffer,
1149 const DateTz& object);
1150 static int generateRaw(char *buffer,
1151 const DateTz& object,
1152 const GenerateConfiguration& configuration);
1153 static int generateRaw(char *buffer,
1154 const TimeTz& object);
1155 static int generateRaw(char *buffer,
1156 const TimeTz& object,
1157 const GenerateConfiguration& configuration);
1158 static int generateRaw(char *buffer,
1159 const DatetimeTz& object);
1160 static int generateRaw(char *buffer,
1161 const DatetimeTz& object,
1162 const GenerateConfiguration& configuration);
1163 static int generateRaw(char *buffer,
1164 const DateOrDateTz& object);
1165 static int generateRaw(char *buffer,
1166 const DateOrDateTz& object,
1167 const GenerateConfiguration& configuration);
1168 static int generateRaw(char *buffer,
1169 const TimeOrTimeTz& object);
1170 static int generateRaw(char *buffer,
1171 const TimeOrTimeTz& object,
1172 const GenerateConfiguration& configuration);
1173 static int generateRaw(char *buffer,
1174 const DatetimeOrDatetimeTz& object);
1175 /// Write the ISO 8601 representation of the specified `object` to the
1176 /// specified `buffer`. Optionally specify a `configuration` to affect
1177 /// the format of the generated string. If `configuration` is not
1178 /// supplied, the process-wide default value
1179 /// `Iso8601UtilConfiguration::defaultConfiguration()` is used. Return
1180 /// the number of characters in the formatted string. `buffer` is not
1181 /// null terminated. The behavior is undefined unless `buffer` has
1182 /// sufficient capacity. Note that a buffer of size `k_MAX_STRLEN + 1`
1183 /// is large enough to hold any string generated by this component
1184 /// (counting a null terminator, if any).
1185 static int generateRaw(char *buffer,
1186 const DatetimeOrDatetimeTz& object,
1187 const GenerateConfiguration& configuration);
1188
1189 /// Parse the specified initial `length` characters of the specified ISO
1190 /// 8601 `string` as a `bsls::TimeInterval` value, and load the value
1191 /// into the specified `result`. Return 0 on success, and a non-zero
1192 /// value (with no effect) otherwise. `string` is assumed to be of the
1193 /// form:
1194 /// @code
1195 /// <Parsed Duration>
1196 /// @endcode
1197 /// See "Summary of Supported ISO 8601 Duration Representations" for a
1198 /// complete description of this format.
1199 ///
1200 /// *Exactly* `length` characters are parsed; parsing will fail if a
1201 /// proper prefix of `string` matches the expected format, but the
1202 /// entire `length` characters do not. If an optional fractional second
1203 /// having more than nine digits is present in `string`, it is rounded
1204 /// to the nearest value in nanoseconds. The behavior is undefined
1205 /// unless `0 <= length`.
1206 static int parse(bsls::TimeInterval *result,
1207 const char *string,
1208 ssize_t length);
1209
1210 /// Parse the specified initial `length` characters of the specified ISO
1211 /// 8601 `string` as a `Date` value, and load the value into the
1212 /// specified `result`, using the optionally specified `configuration`.
1213 /// Return 0 on success, and a non-zero value (with no effect)
1214 /// otherwise. `string` is assumed to be of the form:
1215 /// @code
1216 /// Default: YYYY-MM-DD{(+|-)hh{:}mm|Z}
1217 /// Basic: YYYYMMDD{(+|-)hh{:}mm|Z}
1218 /// @endcode
1219 /// *Exactly* `length` characters are parsed; parsing will fail if a
1220 /// proper prefix of `string` matches the expected format, but the
1221 /// entire `length` characters do not. If the optional zone designator
1222 /// is present in `string`, it is parsed but ignored. The behavior is
1223 /// undefined unless `0 <= length`.
1224 static int parse(Date *result,
1225 const char *string,
1226 ssize_t length,
1227 ParseConfiguration configuration = ParseConfiguration());
1228
1229 /// Parse the specified initial `length` characters of the specified ISO
1230 /// 8601 `string` as a `Time` value, and load the value into the
1231 /// specified `result`, using the optionally specified `configuration`.
1232 /// Return 0 on success, and a non-zero value (with no effect)
1233 /// otherwise. `string` is assumed to be of the form:
1234 /// @code
1235 /// Default: hh:mm:ss{(.|,)s+}{(+|-)hh{:}mm|Z}
1236 /// Basic: hhmmss{(.|,)s+}{(+|-)hh{:}mm|Z}
1237 /// @endcode
1238 /// *Exactly* `length` characters are parsed; parsing will fail if a
1239 /// proper prefix of `string` matches the expected format, but the
1240 /// entire `length` characters do not. If an optional fractional second
1241 /// having more than six digits is present in `string`, it is rounded to
1242 /// the nearest value in microseconds. If the optional zone designator
1243 /// is present in `string`, the resulting `Time` value is converted to
1244 /// the equivalent UTC time; if the zone designator is absent, UTC is
1245 /// assumed. If a leap second is detected (i.e., the parsed value of
1246 /// the `second` attribute is 60; see {Leap Seconds}), the `second`
1247 /// attribute is taken to be 59, then an additional second is added to
1248 /// `result` at the end. If the "hh:mm:ss" portion of `string` is
1249 /// "24:00:00", then the fractional second must be absent or 0, and the
1250 /// zone designator must be absent or indicate UTC. The behavior is
1251 /// undefined unless `0 <= length`.
1252 static int parse(Time *result,
1253 const char *string,
1254 ssize_t length,
1255 ParseConfiguration configuration = ParseConfiguration());
1256
1257 /// Parse the specified initial `length` characters of the specified ISO
1258 /// 8601 `string` as a `Datetime` value, and load the value into the
1259 /// specified `result`, using the optionally specified `configuration`.
1260 /// Return 0 on success, and a non-zero value (with no effect)
1261 /// otherwise. `string` is assumed to be of the form:
1262 /// @code
1263 /// Default: YYYY-MM-DDThh:mm:ss{(.|,)s+}{(+|-)hh{:}mm|Z}
1264 /// Basic: YYYYMMDDThhmmss{(.|,)s+}{(+|-)hh{:}mm|Z}
1265 /// @endcode
1266 /// *Exactly* `length` characters are parsed; parsing will fail if a
1267 /// proper prefix of `string` matches the expected format, but the
1268 /// entire `length` characters do not. If an optional fractional second
1269 /// having more than six digits is present in `string`, it is rounded to
1270 /// the nearest value in microseconds. If the optional zone designator
1271 /// is present in `string`, the resulting `Datetime` value is converted
1272 /// to the equivalent UTC value; if the zone designator is absent, UTC
1273 /// is assumed. If a leap second is detected (i.e., the parsed value of
1274 /// the `second` attribute is 60; see {Leap Seconds}), the `second`
1275 /// attribute is taken to be 59, then an additional second is added to
1276 /// `result` at the end. If the "hh:mm:ss" portion of `string` is
1277 /// "24:00:00", then the fractional second must be absent or 0, and the
1278 /// zone designator must be absent or indicate UTC. The behavior is
1279 /// undefined unless `0 <= length`.
1280 static int parse(Datetime *result,
1281 const char *string,
1282 ssize_t length,
1283 ParseConfiguration configuration = ParseConfiguration());
1284
1285 /// Parse the specified initial `length` characters of the specified ISO
1286 /// 8601 `string` as a `DateTz` value, and load the value into the
1287 /// specified `result`, using the optionally specified `configuration`.
1288 /// Return 0 on success, and a non-zero value (with no effect)
1289 /// otherwise. `string` is assumed to be of the form:
1290 /// @code
1291 /// Default: YYYY-MM-DD{(+|-)hh{:}mm|Z}
1292 /// Basic: YYYYMMDD{(+|-)hh{:}mm|Z}
1293 /// @endcode
1294 /// *Exactly* `length` characters are parsed; parsing will fail if a
1295 /// proper prefix of `string` matches the expected format, but the
1296 /// entire `length` characters do not. If the optional zone designator
1297 /// is not present in `string`, UTC is assumed. The behavior is
1298 /// undefined unless `0 <= length`.
1299 static int parse(DateTz *result,
1300 const char *string,
1301 ssize_t length,
1302 ParseConfiguration configuration = ParseConfiguration());
1303
1304 /// Parse the specified initial `length` characters of the specified ISO
1305 /// 8601 `string` as a `TimeTz` value, and load the value into the
1306 /// specified `result`, using the optionally specified `configuration`.
1307 /// Return 0 on success, and a non-zero value (with no effect)
1308 /// otherwise. `string` is assumed to be of the form:
1309 /// @code
1310 /// Default: hh:mm:ss{(.|,)s+}{(+|-)hh{:}mm|Z}
1311 /// Basic: hhmmss{(.|,)s+}{(+|-)hh{:}mm|Z}
1312 /// @endcode
1313 /// *Exactly* `length` characters are parsed; parsing will fail if a
1314 /// proper prefix of `string` matches the expected format, but the
1315 /// entire `length` characters do not. If an optional fractional second
1316 /// having more than six digits is present in `string`, it is rounded to
1317 /// the nearest value in microseconds. If the optional zone designator
1318 /// is not present in `string`, UTC is assumed. If a leap second is
1319 /// detected (i.e., the parsed value of the `second` attribute is 60;
1320 /// see {Leap Seconds}), the `second` attribute is taken to be 59, then
1321 /// an additional second is added to `result` at the end. If the
1322 /// "hh:mm:ss" portion of `string` is "24:00:00", then the fractional
1323 /// second must be absent or 0, and the zone designator must be absent
1324 /// or indicate UTC. The behavior is undefined unless `0 <= length`.
1325 static int parse(TimeTz *result,
1326 const char *string,
1327 ssize_t length,
1328 ParseConfiguration configuration = ParseConfiguration());
1329
1330 /// Parse the specified initial `length` characters of the specified ISO
1331 /// 8601 `string` as a `DatetimeTz` value, and load the value into the
1332 /// specified `result`, using the optionally specified `configuration`.
1333 /// Return 0 on success, and a non-zero value (with no effect)
1334 /// otherwise. `string` is assumed to be of the form:
1335 /// @code
1336 /// Default: YYYY-MM-DDThh:mm:ss{(.|,)s+}{(+|-)hh{:}mm|Z}
1337 /// Basic: YYYYMMDDThhmmss{(.|,)s+}{(+|-)hh{:}mm|Z}
1338 /// @endcode
1339 /// *Exactly* `length` characters are parsed; parsing will fail if a
1340 /// proper prefix of `string` matches the expected format, but the
1341 /// entire `length` characters do not. If an optional fractional second
1342 /// having more than six digits is present in `string`, it is rounded to
1343 /// the nearest value in microseconds. If the optional zone designator
1344 /// is not present in `string`, UTC is assumed. If a leap second is
1345 /// detected (i.e., the parsed value of the `second` attribute is 60;
1346 /// see {Leap Seconds}), the `second` attribute is taken to be 59, then
1347 /// an additional second is added to `result` at the end. If the
1348 /// "hh:mm:ss" portion of `string` is "24:00:00", then the fractional
1349 /// second must be absent or 0, and the zone designator must be absent
1350 /// or indicate UTC. The behavior is undefined unless `0 <= length`.
1351 static int parse(DatetimeTz *result,
1352 const char *string,
1353 ssize_t length,
1354 ParseConfiguration configuration = ParseConfiguration());
1355
1356 /// Parse the specified initial `length` characters of the specified ISO
1357 /// 8601 `string` as a `Date` or `DateTz` value, depending on the
1358 /// presence of a zone designator, and load the value into the specified
1359 /// `result`, using the optionally specified `configuration`. Return 0
1360 /// on success, and a non-zero value (with no effect) otherwise.
1361 /// `string` is assumed to be of the form:
1362 /// @code
1363 /// Default: YYYY-MM-DD{(+|-)hh{:}mm|Z}
1364 /// Basic: YYYYMMDD{(+|-)hh{:}mm|Z}
1365 /// @endcode
1366 /// *Exactly* `length` characters are parsed; parsing will fail if a
1367 /// proper prefix of `string` matches the expected format, but the
1368 /// entire `length` characters do not. If the optional zone designator
1369 /// is present in the `string`, the input is parsed as a `DateTz` value,
1370 /// and as a `Date` value otherwise. The behavior is undefined unless
1371 /// `0 <= length`.
1372 static int parse(DateOrDateTz *result,
1373 const char *string,
1374 ssize_t length,
1375 ParseConfiguration configuration = ParseConfiguration());
1376
1377 /// Parse the specified initial `length` characters of the specified ISO
1378 /// 8601 `string` as a `Time` or `TimeTz` value, depending on the
1379 /// presence of a zone designator, and load the value into the specified
1380 /// `result`, using the optionally specified `configuration`. Return 0
1381 /// on success, and a non-zero value (with no effect) otherwise.
1382 /// `string` is assumed to be of the form:
1383 /// @code
1384 /// Default: hh:mm:ss{(.|,)s+}{(+|-)hh{:}mm|Z}
1385 /// Basic: hhmmss{(.|,)s+}{(+|-)hh{:}mm|Z}
1386 /// @endcode
1387 /// *Exactly* `length` characters are parsed; parsing will fail if a
1388 /// proper prefix of `string` matches the expected format, but the
1389 /// entire `length` characters do not. If an optional fractional second
1390 /// having more than six digits is present in `string`, it is rounded to
1391 /// the nearest value in microseconds. If the optional zone designator
1392 /// is present in the `string`, the input is parsed as a `TimeTz` value,
1393 /// and as a `Time` value otherwise. If a leap second is detected
1394 /// (i.e., the parsed value of the `second` attribute is 60; see {Leap
1395 /// Seconds}), the `second` attribute is taken to be 59, then an
1396 /// additional second is added to `result` at the end. If the
1397 /// "hh:mm:ss" portion of `string` is "24:00:00", then the fractional
1398 /// second must be absent or 0, and the zone designator must be absent
1399 /// or indicate UTC. The behavior is undefined unless `0 <= length`.
1400 static int parse(TimeOrTimeTz *result,
1401 const char *string,
1402 ssize_t length,
1403 ParseConfiguration configuration = ParseConfiguration());
1404
1405 /// Parse the specified initial `length` characters of the specified ISO
1406 /// 8601 `string` as a `Datetime` or `DatetimeTz` value, depending on
1407 /// the presence of a zone designator, and load the value into the
1408 /// specified `result`, using the optionally specified `configuration`.
1409 /// Return 0 on success, and a non-zero value (with no effect)
1410 /// otherwise. `string` is assumed to be of the form:
1411 /// @code
1412 /// Default: YYYY-MM-DDThh:mm:ss{(.|,)s+}{(+|-)hh{:}mm|Z}
1413 /// Basic: YYYYMMDDThhmmss{(.|,)s+}{(+|-)hh{:}mm|Z}
1414 /// @endcode
1415 /// *Exactly* `length` characters are parsed; parsing will fail if a
1416 /// proper prefix of `string` matches the expected format, but the
1417 /// entire `length` characters do not. If an optional fractional second
1418 /// having more than six digits is present in `string`, it is rounded to
1419 /// the nearest value in microseconds. If the optional zone designator
1420 /// is present in the `string`, the input is parsed as a `DatetimeTz`
1421 /// value, and as a `Datetime` value otherwise. If a leap second is
1422 /// detected (i.e., the parsed value of the `second` attribute is 60;
1423 /// see {Leap Seconds}), the `second` attribute is taken to be 59, then
1424 /// an additional second is added to `result` at the end. If the
1425 /// "hh:mm:ss" portion of `string` is "24:00:00", then the fractional
1426 /// second must be absent or 0, and the zone designator must be absent
1427 /// or indicate UTC. The behavior is undefined unless `0 <= length`.
1428 static int parse(DatetimeOrDatetimeTz *result,
1429 const char *string,
1430 ssize_t length,
1431 ParseConfiguration configuration =
1432 ParseConfiguration());
1433
1434 /// Parse the specified ISO 8601 `string` as a `bsls::TimeInterval`
1435 /// value, and load the value into the specified `result`. Return 0 on
1436 /// success, and a non-zero value (with no effect) otherwise. `string`
1437 /// is assumed to be of the form:
1438 /// @code
1439 /// <Parsed Duration>
1440 /// @endcode
1441 /// See "Summary of Supported ISO 8601 Duration Representations" for a
1442 /// complete description of this format.
1443 ///
1444 /// *Exactly* `string.length()` characters are parsed; parsing will fail
1445 /// if a proper prefix of `string` matches the expected format, but the
1446 /// entire `string.length()` characters do not. If an optional
1447 /// fractional second having more than nine digits is present in
1448 /// `string`, it is rounded to the nearest value in nanoseconds. The
1449 /// behavior is undefined unless `0 <= length`.
1450 static int parse(bsls::TimeInterval *result,
1451 const bsl::string_view& string);
1452
1453 /// Parse the specified ISO 8601 `string` as a `Date` value, and load
1454 /// the value into the specified `result`, using the optionally
1455 /// specified `configuration`. Return 0 on success, and a non-zero
1456 /// value (with no effect) otherwise. `string` is assumed to be of the
1457 /// form:
1458 /// @code
1459 /// Default: YYYY-MM-DD{(+|-)hh{:}mm|Z}
1460 /// Basic: YYYYMMDD{(+|-)hh{:}mm|Z}
1461 /// @endcode
1462 /// *Exactly* `string.length()` characters are parsed; parsing will fail
1463 /// if a proper prefix of `string` matches the expected format, but the
1464 /// entire `string.length()` characters do not. If the optional zone
1465 /// designator is present in `string`, it is parsed but ignored. The
1466 /// behavior is undefined unless `string.data()` is non-null.
1467 static int parse(Date *result,
1468 const bsl::string_view& string,
1469 ParseConfiguration configuration =
1470 ParseConfiguration());
1471
1472 /// Parse the specified ISO 8601 `string` as a `Time` value, and load
1473 /// the value into the specified `result`, using the optionally
1474 /// specified `configuration`. Return 0 on success, and a non-zero
1475 /// value (with no effect) otherwise. `string` is assumed to be of the
1476 /// form:
1477 /// @code
1478 /// Default: hh:mm:ss{(.|,)s+}{(+|-)hh{:}mm|Z}
1479 /// Basic: hhmmss{(.|,)s+}{(+|-)hh{:}mm|Z}
1480 /// @endcode
1481 /// *Exactly* `string.length()` characters are parsed; parsing will fail
1482 /// if a proper prefix of `string` matches the expected format, but the
1483 /// entire `string.length()` characters do not. If an optional
1484 /// fractional second having more than six digits is present in
1485 /// `string`, it is rounded to the nearest value in microseconds. If
1486 /// the optional zone designator is present in `string`, the resulting
1487 /// `Time` value is converted to the equivalent UTC time; if the zone
1488 /// designator is absent, UTC is assumed. If a leap second is detected
1489 /// (i.e., the parsed value of the `second` attribute is 60; see {Leap
1490 /// Seconds}), the `second` attribute is taken to be 59, then an
1491 /// additional second is added to `result` at the end. If the
1492 /// "hh:mm:ss" portion of `string` is "24:00:00", then the fractional
1493 /// second must be absent or 0, and the zone designator must be absent
1494 /// or indicate UTC. The behavior is undefined unless `string.data()`
1495 /// is non-null.
1496 static int parse(Time *result,
1497 const bsl::string_view& string,
1498 ParseConfiguration configuration =
1499 ParseConfiguration());
1500
1501 /// Parse the specified ISO 8601 `string` as a `Datetime` value, and
1502 /// load the value into the specified `result`, using the optionally
1503 /// specified `configuration`. Return 0 on success, and a non-zero
1504 /// value (with no effect) otherwise. `string` is assumed to be of the
1505 /// form:
1506 /// @code
1507 /// Default: YYYY-MM-DDThh:mm:ss{(.|,)s+}{(+|-)hh{:}mm|Z}
1508 /// Basic: YYYYMMDDThhmmss{(.|,)s+}{(+|-)hh{:}mm|Z}
1509 /// @endcode
1510 /// *Exactly* `string.length()` characters are parsed; parsing will fail
1511 /// if a proper prefix of `string` matches the expected format, but the
1512 /// entire `string.length()` characters do not. If an optional
1513 /// fractional second having more than six digits is present in
1514 /// `string`, it is rounded to the nearest value in microseconds. If
1515 /// the optional zone designator is present in `string`, the resulting
1516 /// `Datetime` value is converted to the equivalent UTC value; if the
1517 /// zone designator is absent, UTC is assumed. If a leap second is
1518 /// detected (i.e., the parsed value of the `second` attribute is 60;
1519 /// see {Leap Seconds}), the `second` attribute is taken to be 59, then
1520 /// an additional second is added to `result` at the end. If the
1521 /// "hh:mm:ss" portion of `string` is "24:00:00", then the fractional
1522 /// second must be absent or 0, and the zone designator must be absent
1523 /// or indicate UTC. The behavior is undefined unless `string.data()`
1524 /// is non-null.
1525 static int parse(Datetime *result,
1526 const bsl::string_view& string,
1527 ParseConfiguration configuration =
1528 ParseConfiguration());
1529
1530 /// Parse the specified ISO 8601 `string` as a `DateTz` value, and load
1531 /// the value into the specified `result`, using the optionally
1532 /// specified `configuration`. Return 0 on success, and a non-zero
1533 /// value (with no effect) otherwise. `string` is assumed to be of the
1534 /// form:
1535 /// @code
1536 /// Default: YYYY-MM-DD{(+|-)hh{:}mm|Z}
1537 /// Basic: YYYYMMDD{(+|-)hh{:}mm|Z}
1538 /// @endcode
1539 /// *Exactly* `string.length()` characters are parsed; parsing will fail
1540 /// if a proper prefix of `string` matches the expected format, but the
1541 /// entire `string.length()` characters do not. If the optional zone
1542 /// designator is not present in `string`, UTC is assumed. The behavior
1543 /// is undefined unless `string.data()` is non-null.
1544 static int parse(DateTz *result,
1545 const bsl::string_view& string,
1546 ParseConfiguration configuration =
1547 ParseConfiguration());
1548
1549 /// Parse the specified ISO 8601 `string` as a `TimeTz` value, and load
1550 /// the value into the specified `result`, using the optionally
1551 /// specified `configuration`. Return 0 on success, and a non-zero
1552 /// value (with no effect) otherwise. `string` is assumed to be of the
1553 /// form:
1554 /// @code
1555 /// Default: hh:mm:ss{(.|,)s+}{(+|-)hh{:}mm|Z}
1556 /// Basic: hhmmss{(.|,)s+}{(+|-)hh{:}mm|Z}
1557 /// @endcode
1558 /// *Exactly* `string.length()` characters are parsed; parsing will fail
1559 /// if a proper prefix of `string` matches the expected format, but the
1560 /// entire `string.length()` characters do not. If an optional
1561 /// fractional second having more than six digits is present in
1562 /// `string`, it is rounded to the nearest value in microseconds. If
1563 /// the optional zone designator is not present in `string`, UTC is
1564 /// assumed. If a leap second is detected (i.e., the parsed value of
1565 /// the `second` attribute is 60; see {Leap Seconds}), the `second`
1566 /// attribute is taken to be 59, then an additional second is added to
1567 /// `result` at the end. If the "hh:mm:ss" portion of `string` is
1568 /// "24:00:00", then the fractional second must be absent or 0, and the
1569 /// zone designator must be absent or indicate UTC. The behavior is
1570 /// undefined unless `string.data()` is non-null.
1571 static int parse(TimeTz *result,
1572 const bsl::string_view& string,
1573 ParseConfiguration configuration =
1574 ParseConfiguration());
1575
1576 /// Parse the specified ISO 8601 `string` as a `DatetimeTz` value, and
1577 /// load the value into the specified `result`, using the optionally
1578 /// specified `configuration`. Return 0 on success, and a non-zero
1579 /// value (with no effect) otherwise. `string` is assumed to be of the
1580 /// form:
1581 /// @code
1582 /// Default: YYYY-MM-DDThh:mm:ss{(.|,)s+}{(+|-)hh{:}mm|Z}
1583 /// Basic: YYYYMMDDThhmmss{(.|,)s+}{(+|-)hh{:}mm|Z}
1584 /// @endcode
1585 /// *Exactly* `string.length()` characters are parsed; parsing will fail
1586 /// if a proper prefix of `string` matches the expected format, but the
1587 /// entire `string.length()` characters do not. If an optional
1588 /// fractional second having more than six digits is present in
1589 /// `string`, it is rounded to the nearest value in microseconds. If
1590 /// the optional zone designator is not present in `string`, UTC is
1591 /// assumed. If a leap second is detected (i.e., the parsed value of
1592 /// the `second` attribute is 60; see {Leap Seconds}), the `second`
1593 /// attribute is taken to be 59, then an additional second is added to
1594 /// `result` at the end. If the "hh:mm:ss" portion of `string` is
1595 /// "24:00:00", then the fractional second must be absent or 0, and the
1596 /// zone designator must be absent or indicate UTC. The behavior is
1597 /// undefined unless `string.data()` is non-null.
1598 static int parse(DatetimeTz *result,
1599 const bsl::string_view& string,
1600 ParseConfiguration configuration =
1601 ParseConfiguration());
1602
1603 /// Parse the specified ISO 8601 `string` as a `Date` or `DateTz` value,
1604 /// depending on the presence of a zone designator, and load the value
1605 /// into the specified `result`, using the optionally specified
1606 /// `configuration`. Return 0 on success, and a non-zero value (with no
1607 /// effect) otherwise. `string` is assumed to be of the form:
1608 /// @code
1609 /// Default: YYYY-MM-DD{(+|-)hh{:}mm|Z}
1610 /// Basic: YYYYMMDD{(+|-)hh{:}mm|Z}
1611 /// @endcode
1612 /// *Exactly* `string.length()` characters are parsed; parsing will fail
1613 /// if a proper prefix of `string` matches the expected format, but the
1614 /// entire `string.length()` characters do not. If the optional zone
1615 /// designator is present in the `string`, the input is parsed as a
1616 /// `DateTz` value, and as a `Date` value otherwise. The behavior is
1617 /// undefined unless `string.data()` is non-null.
1618 static int parse(DateOrDateTz *result,
1619 const bsl::string_view& string,
1620 ParseConfiguration configuration =
1621 ParseConfiguration());
1622
1623 /// Parse the specified ISO 8601 `string` as a `Time` or `TimeTz` value,
1624 /// depending on the presence of a zone designator, and load the value
1625 /// into the specified `result`, using the optionally specified
1626 /// `configuration`. Return 0 on success, and a non-zero value (with no
1627 /// effect) otherwise. `string` is assumed to be of the form:
1628 /// @code
1629 /// Default: hh:mm:ss{(.|,)s+}{(+|-)hh{:}mm|Z}
1630 /// Basic: hhmmss{(.|,)s+}{(+|-)hh{:}mm|Z}
1631 /// @endcode
1632 /// *Exactly* `string.length()` characters are parsed; parsing will fail
1633 /// if a proper prefix of `string` matches the expected format, but the
1634 /// entire `string.length()` characters do not. If an optional
1635 /// fractional second having more than six digits is present in
1636 /// `string`, it is rounded to the nearest value in microseconds. If
1637 /// the optional zone designator is present in the `string`, the input
1638 /// is parsed as a `TimeTz` value, and as a `Time` value otherwise. If
1639 /// a leap second is detected (i.e., the parsed value of the `second`
1640 /// attribute is 60; see {Leap Seconds}), the `second` attribute is
1641 /// taken to be 59, then an additional second is added to `result` at
1642 /// the end. If the "hh:mm:ss" portion of `string` is "24:00:00", then
1643 /// the fractional second must be absent or 0, and the zone designator
1644 /// must be absent or indicate UTC. The behavior is undefined unless
1645 /// `string.data()` is non-null.
1646 static int parse(TimeOrTimeTz *result,
1647 const bsl::string_view& string,
1648 ParseConfiguration configuration =
1649 ParseConfiguration());
1650
1651 /// Parse the specified ISO 8601 `string` as a `Datetime` or
1652 /// `DatetimeTz` value, depending on the presence of a zone designator,
1653 /// and load the value into the specified `result`, using the optionally
1654 /// specified `configuration`. Return 0 on success, and a non-zero
1655 /// value (with no effect) otherwise. `string` is assumed to be of the
1656 /// form:
1657 /// @code
1658 /// Default: YYYY-MM-DDThh:mm:ss{(.|,)s+}{(+|-)hh{:}mm|Z}
1659 /// Basic: YYYYMMDDThhmmss{(.|,)s+}{(+|-)hh{:}mm|Z}
1660 /// @endcode
1661 /// *Exactly* `string.length()` characters are parsed; parsing will fail
1662 /// if a proper prefix of `string` matches the expected format, but the
1663 /// entire `string.length()` characters do not. If an optional
1664 /// fractional second having more than six digits is present in
1665 /// `string`, it is rounded to the nearest value in microseconds. If
1666 /// the optional zone designator is present in the `string`, the input
1667 /// is parsed as a `DatetimeTz` value, and as a `Datetime` value
1668 /// otherwise. If a leap second is detected (i.e., the parsed value of
1669 /// the `second` attribute is 60; see {Leap Seconds}), the `second`
1670 /// attribute is taken to be 59, then an additional second is added to
1671 /// `result` at the end. If the "hh:mm:ss" portion of `string` is
1672 /// "24:00:00", then the fractional second must be absent or 0, and the
1673 /// zone designator must be absent or indicate UTC. The behavior is
1674 /// undefined unless `string.data()` is non-null.
1675 static int parse(DatetimeOrDatetimeTz *result,
1676 const bsl::string_view& string,
1677 ParseConfiguration configuration =
1678 ParseConfiguration());
1679
1680#ifndef BDE_OMIT_INTERNAL_DEPRECATED
1681 // DEPRECATED METHODS
1682 BDLT_ISO8601UTIL_DEPRECATE_PARSERELAXED
1683 /// @deprecated Use @ref parse` with `configuration.relaxed() == true
1684 /// instead.
1685 ///
1686 /// Parse the specified initial `length` characters of the specified
1687 /// "relaxed" ISO 8601 `string` as a `Datetime` value, and load the
1688 /// value into the specified `result`. Return 0 on success, and a
1689 /// non-zero value (with no effect) otherwise. `string` is assumed to
1690 /// be of the form:
1691 /// @code
1692 /// YYYY-MM-DD(T| )hh:mm:ss{(.|,)s+}{(+|-)hh{:}mm|Z}
1693 /// @endcode
1694 /// The "relaxed" format parsed by this function is a superset of the
1695 /// strict ISO 8601 format, currently allowing a SPACE character to be
1696 /// used as a separated (where ISO 8601 requires a `T`). *Exactly*
1697 /// `length` characters are parsed; parsing will fail if a proper prefix
1698 /// of `string` matches the expected format, but the entire `length`
1699 /// characters do not. If an optional fractional second having more
1700 /// than six digits is present in `string`, it is rounded to the nearest
1701 /// value in microseconds. If the optional zone designator is present
1702 /// in `string`, the resulting `Datetime` value is converted to the
1703 /// equivalent UTC value; if the zone designator is absent, UTC is
1704 /// assumed. If a leap second is detected (i.e., the parsed value of
1705 /// the `second` attribute is 60; see {Leap Seconds}), the `second`
1706 /// attribute is taken to be 59, then an additional second is added to
1707 /// `result` at the end. If the "hh:mm:ss" portion of `string` is
1708 /// "24:00:00", then the fractional second must be absent or 0, and the
1709 /// zone designator must be absent or indicate UTC. The behavior is
1710 /// undefined unless `0 <= length`.
1711 static int parseRelaxed(Datetime *result,
1712 const char *string,
1713 ssize_t length);
1714
1715 BDLT_ISO8601UTIL_DEPRECATE_PARSERELAXED
1716 /// @deprecated Use @ref parse` with `configuration.relaxed() == true
1717 /// instead.
1718 ///
1719 /// Parse the specified initial `length` characters of the specified
1720 /// "relaxed" ISO 8601 `string` as a `DatetimeTz` value, and load the
1721 /// value into the specified `result`. Return 0 on success, and a
1722 /// non-zero value (with no effect) otherwise. `string` is assumed to
1723 /// be of the form:
1724 /// @code
1725 /// YYYY-MM-DD(T| )hh:mm:ss{(.|,)s+}{(+|-)hh{:}mm|Z}
1726 /// @endcode
1727 /// The "relaxed" format parsed by this function is a superset of the
1728 /// strict ISO 8601 format, currently allowing a SPACE character to be
1729 /// used as a separated (where ISO 8601 requires a `T`). *Exactly*
1730 /// `length` characters are parsed; parsing will fail if a proper prefix
1731 /// of `string` matches the expected format, but the entire `length`
1732 /// characters do not. If an optional fractional second having more
1733 /// than six digits is present in `string`, it is rounded to the nearest
1734 /// value in microseconds. If the optional zone designator is not
1735 /// present in `string`, UTC is assumed. If a leap second is detected
1736 /// (i.e., the parsed value of the `second` attribute is 60; see {Leap
1737 /// Seconds}), the `second` attribute is taken to be 59, then an
1738 /// additional second is added to `result` at the end. If the
1739 /// "hh:mm:ss" portion of `string` is "24:00:00", then the fractional
1740 /// second must be absent or 0, and the zone designator must be absent
1741 /// or indicate UTC. The behavior is undefined unless `0 <= length`.
1742 static int parseRelaxed(DatetimeTz *result,
1743 const char *string,
1744 ssize_t length);
1745
1746 BDLT_ISO8601UTIL_DEPRECATE_PARSERELAXED
1747 /// @deprecated Use @ref parse` with `configuration.relaxed() == true
1748 /// instead.
1749 ///
1750 /// Parse the specified initial `length` characters of the specified
1751 /// "relaxed" ISO 8601 `string` as a `Datetime` or `DatetimeTz` value,
1752 /// depending on the presence of a zone designator, and load the value
1753 /// into the specified `result`. Return 0 on success, and a non-zero
1754 /// value (with no effect) otherwise. `string` is assumed to be of the
1755 /// form:
1756 /// @code
1757 /// YYYY-MM-DD(T| )hh:mm:ss{(.|,)s+}{(+|-)hh{:}mm|Z}
1758 /// @endcode
1759 /// The "relaxed" format parsed by this function is a superset of the
1760 /// strict ISO 8601 format, currently allowing a SPACE character to be
1761 /// used as a separated (where ISO 8601 requires a `T`). *Exactly*
1762 /// `length` characters are parsed; parsing will fail if a proper prefix
1763 /// of `string` matches the expected format, but the entire `length`
1764 /// characters do not. If an optional fractional second having more
1765 /// than six digits is present in `string`, it is rounded to the nearest
1766 /// value in microseconds. If the optional zone designator is present
1767 /// in the `string`, the input is parsed as a `DatetimeTz` value, and as
1768 /// a `Datetime` value otherwise. If a leap second is detected (i.e.,
1769 /// the parsed value of the `second` attribute is 60; see {Leap
1770 /// Seconds}), the `second` attribute is taken to be 59, then an
1771 /// additional second is added to `result` at the end. If the
1772 /// "hh:mm:ss" portion of `string` is "24:00:00", then the fractional
1773 /// second must be absent or 0, and the zone designator must be absent
1774 /// or indicate UTC. The behavior is undefined unless `0 <= length`.
1775 static int parseRelaxed(DatetimeOrDatetimeTz *result,
1776 const char *string,
1777 ssize_t length);
1778
1779 BDLT_ISO8601UTIL_DEPRECATE_PARSERELAXED
1780 /// @deprecated Use @ref parse` with `configuration.relaxed() == true
1781 /// instead.
1782 ///
1783 /// Parse the specified "relaxed" ISO 8601 `string` as a `Datetime`
1784 /// value, and load the value into the specified `result`. Return 0 on
1785 /// success, and a non-zero value (with no effect) otherwise. `string`
1786 /// is assumed to be of the form:
1787 /// @code
1788 /// YYYY-MM-DD(T| )hh:mm:ss{(.|,)s+}{(+|-)hh{:}mm|Z}
1789 /// @endcode
1790 /// The "relaxed" format parsed by this function is a superset of the
1791 /// strict ISO 8601 format, currently allowing a SPACE character to be
1792 /// used as a separated (where ISO 8601 requires a `T`). *Exactly*
1793 /// `string.length()` characters are parsed; parsing will fail if a
1794 /// proper prefix of `string` matches the expected format, but the
1795 /// entire `string.length()` characters do not. If an optional
1796 /// fractional second having more than six digits is present in
1797 /// `string`, it is rounded to the nearest value in microseconds. If
1798 /// the optional zone designator is present in `string`, the resulting
1799 /// `Datetime` value is converted to the equivalent UTC value; if the
1800 /// zone designator is absent, UTC is assumed. If a leap second is
1801 /// detected (i.e., the parsed value of the `second` attribute is 60;
1802 /// see {Leap Seconds}), the `second` attribute is taken to be 59, then
1803 /// an additional second is added to `result` at the end. If the
1804 /// "hh:mm:ss" portion of `string` is "24:00:00", then the fractional
1805 /// second must be absent or 0, and the zone designator must be absent
1806 /// or indicate UTC. The behavior is undefined unless `string.data()`
1807 /// is non-null.
1808 static int parseRelaxed(Datetime *result, const bsl::string_view& string);
1809
1810 BDLT_ISO8601UTIL_DEPRECATE_PARSERELAXED
1811 /// @deprecated Use @ref parse` with `configuration.relaxed() == true
1812 /// instead.
1813 ///
1814 /// Parse the specified "relaxed" ISO 8601 `string` as a `DatetimeTz`
1815 /// value, and load the value into the specified `result`. Return 0 on
1816 /// success, and a non-zero value (with no effect) otherwise. `string`
1817 /// is assumed to be of the form:
1818 /// @code
1819 /// YYYY-MM-DD(T| )hh:mm:ss{(.|,)s+}{(+|-)hh{:}mm|Z}
1820 /// @endcode
1821 /// The "relaxed" format parsed by this function is a superset of the
1822 /// strict ISO 8601 format, currently allowing a SPACE character to be
1823 /// used as a separated (where ISO 8601 requires a `T`). *Exactly*
1824 /// `string.length()` characters are parsed; parsing will fail if a
1825 /// proper prefix of `string` matches the expected format, but the
1826 /// entire `string.length()` characters do not. If an optional
1827 /// fractional second having more than six digits is present in
1828 /// `string`, it is rounded to the nearest value in microseconds. If
1829 /// the optional zone designator is not present in `string`, UTC is
1830 /// assumed. If a leap second is detected (i.e., the parsed value of
1831 /// the `second` attribute is 60; see {Leap Seconds}), the `second`
1832 /// attribute is taken to be 59, then an additional second is added to
1833 /// `result` at the end. If the "hh:mm:ss" portion of `string` is
1834 /// "24:00:00", then the fractional second must be absent or 0, and the
1835 /// zone designator must be absent or indicate UTC. The behavior is
1836 /// undefined unless `string.data()` is non-null.
1837 static int parseRelaxed(DatetimeTz *result,
1838 const bsl::string_view& string);
1839
1840 BDLT_ISO8601UTIL_DEPRECATE_PARSERELAXED
1841 /// @deprecated Use @ref parse` with `configuration.relaxed() == true
1842 /// instead.
1843 ///
1844 static int parseRelaxed(DatetimeOrDatetimeTz *result,
1845 const bsl::string_view& string);
1846
1847 BDLT_ISO8601UTIL_DEPRECATE_GENERATE_ORDER
1848 static int generate(char *buffer,
1849 const Date& object,
1850 ssize_t bufferLength);
1851 BDLT_ISO8601UTIL_DEPRECATE_GENERATE_ORDER
1852 static int generate(char *buffer,
1853 const Time& object,
1854 ssize_t bufferLength);
1855 BDLT_ISO8601UTIL_DEPRECATE_GENERATE_ORDER
1856 static int generate(char *buffer,
1857 const Datetime& object,
1858 ssize_t bufferLength);
1859 BDLT_ISO8601UTIL_DEPRECATE_GENERATE_ORDER
1860 static int generate(char *buffer,
1861 const DateTz& object,
1862 ssize_t bufferLength);
1863 /// Parse the specified "relaxed" ISO 8601 `string` as a `Datetime` or
1864 /// `DatetimeTz` value, depending on the presence of a zone designator,
1865 /// and load the value into the specified `result`. Return 0 on
1866 /// success, and a non-zero value (with no effect) otherwise. `string`
1867 /// is assumed to be of the form:
1868 /// @code
1869 /// YYYY-MM-DD(T| )hh:mm:ss{(.|,)s+}{(+|-)hh{:}mm|Z}
1870 /// @endcode
1871 /// The "relaxed" format parsed by this function is a superset of the
1872 /// strict ISO 8601 format, currently allowing a SPACE character to be
1873 /// used as a separated (where ISO 8601 requires a `T`). *Exactly*
1874 /// `string.length()` characters are parsed; parsing will fail if a
1875 /// proper prefix of `string` matches the expected format, but the
1876 /// entire `string.length()` characters do not. If an optional
1877 /// fractional second having more than six digits is present in
1878 /// `string`, it is rounded to the nearest value in microseconds. If
1879 /// the optional zone designator is present in the `string`, the input
1880 /// is parsed as a `DatetimeTz` value, and as a `Datetime` value
1881 /// otherwise. If a leap second is detected (i.e., the parsed value of
1882 /// the `second` attribute is 60; see {Leap Seconds}), the `second`
1883 /// attribute is taken to be 59, then an additional second is added to
1884 /// `result` at the end. If the "hh:mm:ss" portion of `string` is
1885 /// "24:00:00", then the fractional second must be absent or 0, and the
1886 /// zone designator must be absent or indicate UTC. The behavior is
1887 /// undefined unless `string.data()` is non-null.
1888 BDLT_ISO8601UTIL_DEPRECATE_GENERATE_ORDER
1889 static int generate(char *buffer,
1890 const TimeTz& object,
1891 ssize_t bufferLength);
1892 BDLT_ISO8601UTIL_DEPRECATE_GENERATE_ORDER
1893 static int generate(char *buffer,
1894 const DatetimeTz& object,
1895 ssize_t bufferLength);
1896
1897 BDLT_ISO8601UTIL_DEPRECATE_GENERATE
1898 static int generate(char *buffer,
1899 const DateTz& object,
1900 ssize_t bufferLength,
1901 bool useZAbbreviationForUtc);
1902 /// @deprecated Use the overloads taking the `bufferLength` argument
1903 /// *before* the `object` argument instead.
1904 BDLT_ISO8601UTIL_DEPRECATE_GENERATE
1905 static int generate(char *buffer,
1906 const TimeTz& object,
1907 ssize_t bufferLength,
1908 bool useZAbbreviationForUtc);
1909 BDLT_ISO8601UTIL_DEPRECATE_GENERATE
1910 /// @deprecated Use the overloads taking an `Iso8601UtilConfiguration`
1911 /// object instead.
1912 static int generate(char *buffer,
1913 const DatetimeTz& object,
1914 ssize_t bufferLength,
1915 bool useZAbbreviationForUtc);
1916
1917 BDLT_ISO8601UTIL_DEPRECATE_GENERATE
1918 static bsl::ostream& generate(bsl::ostream& stream,
1919 const DateTz& object,
1920 bool useZAbbreviationForUtc);
1921 BDLT_ISO8601UTIL_DEPRECATE_GENERATE
1922 static bsl::ostream& generate(bsl::ostream& stream,
1923 const TimeTz& object,
1924 bool useZAbbreviationForUtc);
1925 BDLT_ISO8601UTIL_DEPRECATE_GENERATE
1926 /// @deprecated Use the overloads taking an `Iso8601UtilConfiguration`
1927 /// object instead.
1928 static bsl::ostream& generate(bsl::ostream& stream,
1929 const DatetimeTz& object,
1930 bool useZAbbreviationForUtc);
1931
1932 BDLT_ISO8601UTIL_DEPRECATE_GENERATERAW
1933 static int generateRaw(char *buffer,
1934 const DateTz& object,
1935 bool useZAbbreviationForUtc);
1936 BDLT_ISO8601UTIL_DEPRECATE_GENERATERAW
1937 static int generateRaw(char *buffer,
1938 const TimeTz& object,
1939 bool useZAbbreviationForUtc);
1940 BDLT_ISO8601UTIL_DEPRECATE_GENERATERAW
1941 /// @deprecated Use the overloads taking an `Iso8601UtilConfiguration`
1942 /// object instead.
1943 static int generateRaw(char *buffer,
1944 const DatetimeTz& object,
1945 bool useZAbbreviationForUtc);
1946
1947#endif // BDE_OMIT_INTERNAL_DEPRECATED
1948};
1949
1950// ============================================================================
1951// INLINE DEFINITIONS
1952// ============================================================================
1953
1954 // ------------------
1955 // struct Iso8601Util
1956 // ------------------
1957
1958// PRIVATE CLASS METHODS
1959inline
1960Iso8601UtilConfiguration Iso8601Util::defaultConfiguration()
1961{
1962 return Iso8601UtilConfiguration::defaultConfiguration();
1963}
1964
1965// CLASS METHODS
1966inline
1967int Iso8601Util::generate(char *buffer,
1968 ssize_t bufferLength,
1969 const bsls::TimeInterval& object)
1970{
1971 BSLS_ASSERT_SAFE(buffer);
1972 BSLS_ASSERT_SAFE(0 <= bufferLength);
1973
1974 return generate(buffer,
1975 bufferLength,
1976 object,
1977 defaultConfiguration());
1978}
1979
1980inline
1981int Iso8601Util::generate(char *buffer,
1982 ssize_t bufferLength,
1983 const Date& object)
1984{
1985 BSLS_ASSERT_SAFE(buffer);
1986 BSLS_ASSERT_SAFE(0 <= bufferLength);
1987
1988 return generate(buffer,
1989 bufferLength,
1990 object,
1991 defaultConfiguration());
1992}
1993
1994inline
1995int Iso8601Util::generate(char *buffer,
1996 ssize_t bufferLength,
1997 const Time& object)
1998{
1999 BSLS_ASSERT_SAFE(buffer);
2000 BSLS_ASSERT_SAFE(0 <= bufferLength);
2001
2002 return generate(buffer,
2003 bufferLength,
2004 object,
2005 defaultConfiguration());
2006}
2007
2008inline
2009int
2010Iso8601Util::generate(char *buffer,
2011 ssize_t bufferLength,
2012 const Datetime& object)
2013{
2014 BSLS_ASSERT_SAFE(buffer);
2015 BSLS_ASSERT_SAFE(0 <= bufferLength);
2016
2017 return generate(buffer,
2018 bufferLength,
2019 object,
2020 defaultConfiguration());
2021}
2022
2023inline
2024int Iso8601Util::generate(char *buffer,
2025 ssize_t bufferLength,
2026 const DateTz& object)
2027{
2028 BSLS_ASSERT_SAFE(buffer);
2029 BSLS_ASSERT_SAFE(0 <= bufferLength);
2030
2031 return generate(buffer,
2032 bufferLength,
2033 object,
2034 defaultConfiguration());
2035}
2036
2037inline
2038int Iso8601Util::generate(char *buffer,
2039 ssize_t bufferLength,
2040 const TimeTz& object)
2041{
2042 BSLS_ASSERT_SAFE(buffer);
2043 BSLS_ASSERT_SAFE(0 <= bufferLength);
2044
2045 return generate(buffer,
2046 bufferLength,
2047 object,
2048 defaultConfiguration());
2049}
2050
2051inline
2052int
2053Iso8601Util::generate(char *buffer,
2054 ssize_t bufferLength,
2055 const DatetimeTz& object)
2056{
2057 BSLS_ASSERT_SAFE(buffer);
2058 BSLS_ASSERT_SAFE(0 <= bufferLength);
2059
2060 return generate(buffer,
2061 bufferLength,
2062 object,
2063 defaultConfiguration());
2064}
2065
2066inline
2067int Iso8601Util::generate(char *buffer,
2068 ssize_t bufferLength,
2069 const DateOrDateTz& object)
2070{
2071 BSLS_ASSERT_SAFE(buffer);
2072 BSLS_ASSERT_SAFE(0 <= bufferLength);
2073
2074 return generate(buffer,
2075 bufferLength,
2076 object,
2077 defaultConfiguration());
2078}
2079
2080inline
2081int Iso8601Util::generate(char *buffer,
2082 ssize_t bufferLength,
2083 const TimeOrTimeTz& object)
2084{
2085 BSLS_ASSERT_SAFE(buffer);
2086 BSLS_ASSERT_SAFE(0 <= bufferLength);
2087
2088 return generate(buffer,
2089 bufferLength,
2090 object,
2091 defaultConfiguration());
2092}
2093
2094inline
2095int Iso8601Util::generate(char *buffer,
2096 ssize_t bufferLength,
2097 const DatetimeOrDatetimeTz& object)
2098{
2099 BSLS_ASSERT_SAFE(buffer);
2100 BSLS_ASSERT_SAFE(0 <= bufferLength);
2101
2102 return generate(buffer,
2103 bufferLength,
2104 object,
2105 defaultConfiguration());
2106}
2107
2108inline
2109int Iso8601Util::generate(bsl::string *string,
2110 const bsls::TimeInterval& object)
2111{
2112 return generate(string, object, defaultConfiguration());
2113}
2114
2115inline
2116int Iso8601Util::generate(bsl::string *string, const Date& object)
2117{
2118 return generate(string, object, defaultConfiguration());
2119}
2120
2121inline
2122int Iso8601Util::generate(bsl::string *string, const Time& object)
2123{
2124 return generate(string, object, defaultConfiguration());
2125}
2126
2127inline
2128int Iso8601Util::generate(bsl::string *string, const Datetime& object)
2129{
2130 return generate(string, object, defaultConfiguration());
2131}
2132
2133inline
2134int Iso8601Util::generate(bsl::string *string, const DateTz& object)
2135{
2136 return generate(string, object, defaultConfiguration());
2137}
2138
2139inline
2140int Iso8601Util::generate(bsl::string *string, const TimeTz& object)
2141{
2142 return generate(string, object, defaultConfiguration());
2143}
2144
2145inline
2146int Iso8601Util::generate(bsl::string *string, const DatetimeTz& object)
2147{
2148 return generate(string, object, defaultConfiguration());
2149}
2150
2151inline
2152int Iso8601Util::generate(bsl::string *string, const DateOrDateTz& object)
2153{
2154 return generate(string, object, defaultConfiguration());
2155}
2156
2157inline
2158int Iso8601Util::generate(bsl::string *string, const TimeOrTimeTz& object)
2159{
2160 return generate(string, object, defaultConfiguration());
2161}
2162
2163inline
2164int Iso8601Util::generate(bsl::string *string,
2165 const DatetimeOrDatetimeTz& object)
2166{
2167 return generate(string, object, defaultConfiguration());
2168}
2169
2170inline
2171int Iso8601Util::generate(std::string *string,
2172 const bsls::TimeInterval& object)
2173{
2174 return generate(string, object, defaultConfiguration());
2175}
2176
2177inline
2178int Iso8601Util::generate(std::string *string, const Date& object)
2179{
2180 return generate(string, object, defaultConfiguration());
2181}
2182
2183inline
2184int Iso8601Util::generate(std::string *string, const Time& object)
2185{
2186 return generate(string, object, defaultConfiguration());
2187}
2188
2189inline
2190int Iso8601Util::generate(std::string *string, const Datetime& object)
2191{
2192 return generate(string, object, defaultConfiguration());
2193}
2194
2195inline
2196int Iso8601Util::generate(std::string *string, const DateTz& object)
2197{
2198 return generate(string, object, defaultConfiguration());
2199}
2200
2201inline
2202int Iso8601Util::generate(std::string *string, const TimeTz& object)
2203{
2204 return generate(string, object, defaultConfiguration());
2205}
2206
2207inline
2208int Iso8601Util::generate(std::string *string, const DatetimeTz& object)
2209{
2210 return generate(string, object, defaultConfiguration());
2211}
2212
2213inline
2214int Iso8601Util::generate(std::string *string, const DateOrDateTz& object)
2215{
2216 return generate(string, object, defaultConfiguration());
2217}
2218
2219inline
2220int Iso8601Util::generate(std::string *string, const TimeOrTimeTz& object)
2221{
2222 return generate(string, object, defaultConfiguration());
2223}
2224
2225inline
2226int Iso8601Util::generate(std::string *string,
2227 const DatetimeOrDatetimeTz& object)
2228{
2229 return generate(string, object, defaultConfiguration());
2230}
2231
2232#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
2233inline
2234int Iso8601Util::generate(std::pmr::string *string,
2235 const bsls::TimeInterval& object)
2236{
2237 return generate(string, object, defaultConfiguration());
2238}
2239
2240inline
2241int Iso8601Util::generate(std::pmr::string *string, const Date& object)
2242{
2243 return generate(string, object, defaultConfiguration());
2244}
2245
2246inline
2247int Iso8601Util::generate(std::pmr::string *string, const Time& object)
2248{
2249 return generate(string, object, defaultConfiguration());
2250}
2251
2252inline
2253int Iso8601Util::generate(std::pmr::string *string, const Datetime& object)
2254{
2255 return generate(string, object, defaultConfiguration());
2256}
2257
2258inline
2259int Iso8601Util::generate(std::pmr::string *string, const DateTz& object)
2260{
2261 return generate(string, object, defaultConfiguration());
2262}
2263
2264inline
2265int Iso8601Util::generate(std::pmr::string *string, const TimeTz& object)
2266{
2267 return generate(string, object, defaultConfiguration());
2268}
2269
2270inline
2271int Iso8601Util::generate(std::pmr::string *string, const DatetimeTz& object)
2272{
2273 return generate(string, object, defaultConfiguration());
2274}
2275
2276inline
2277int Iso8601Util::generate(std::pmr::string *string, const DateOrDateTz& object)
2278{
2279 return generate(string, object, defaultConfiguration());
2280}
2281
2282inline
2283int Iso8601Util::generate(std::pmr::string *string, const TimeOrTimeTz& object)
2284{
2285 return generate(string, object, defaultConfiguration());
2286}
2287
2288inline
2289int Iso8601Util::generate(std::pmr::string *string,
2290 const DatetimeOrDatetimeTz& object)
2291{
2292 return generate(string, object, defaultConfiguration());
2293}
2294#endif
2295
2296inline
2297bsl::ostream& Iso8601Util::generate(bsl::ostream& stream,
2298 const bsls::TimeInterval& object)
2299{
2300 return generate(stream,
2301 object,
2302 defaultConfiguration());
2303}
2304
2305inline
2306bsl::ostream& Iso8601Util::generate(
2307 bsl::ostream& stream,
2308 const bsls::TimeInterval& object,
2309 const GenerateConfiguration& configuration)
2310{
2311 char buffer[k_TIMEINTERVAL_STRLEN + 1];
2312
2313 const int len = generate(buffer,
2314 k_TIMEINTERVAL_STRLEN,
2315 object,
2316 configuration);
2317 BSLS_ASSERT_SAFE(k_TIMEINTERVAL_STRLEN >= len);
2318
2319 return stream.write(buffer, len);
2320}
2321
2322inline
2323bsl::ostream& Iso8601Util::generate(bsl::ostream& stream, const Date& object)
2324{
2325 return generate(stream,
2326 object,
2327 defaultConfiguration());
2328}
2329
2330inline
2331bsl::ostream& Iso8601Util::generate(
2332 bsl::ostream& stream,
2333 const Date& object,
2334 const GenerateConfiguration& configuration)
2335{
2336 char buffer[k_DATE_STRLEN + 1];
2337
2338 const int len = generate(buffer, k_DATE_STRLEN, object, configuration);
2339 BSLS_ASSERT_SAFE(k_DATE_STRLEN >= len);
2340
2341 return stream.write(buffer, len);
2342}
2343
2344inline
2345bsl::ostream& Iso8601Util::generate(bsl::ostream& stream, const Time& object)
2346{
2347 return generate(stream,
2348 object,
2349 defaultConfiguration());
2350}
2351
2352inline
2353bsl::ostream& Iso8601Util::generate(
2354 bsl::ostream& stream,
2355 const Time& object,
2356 const GenerateConfiguration& configuration)
2357{
2358 char buffer[k_TIME_STRLEN + 1];
2359
2360 const int len = generate(buffer, k_TIME_STRLEN, object, configuration);
2361 BSLS_ASSERT_SAFE(k_TIME_STRLEN >= len);
2362
2363 return stream.write(buffer, len);
2364}
2365
2366inline
2367bsl::ostream&
2368Iso8601Util::generate(bsl::ostream& stream, const Datetime& object)
2369{
2370 return generate(stream,
2371 object,
2372 defaultConfiguration());
2373}
2374
2375inline
2376bsl::ostream& Iso8601Util::generate(
2377 bsl::ostream& stream,
2378 const Datetime& object,
2379 const GenerateConfiguration& configuration)
2380{
2381 char buffer[k_DATETIME_STRLEN + 1];
2382
2383 const int len = generate(buffer, k_DATETIME_STRLEN, object, configuration);
2384 BSLS_ASSERT_SAFE(k_DATETIME_STRLEN >= len);
2385
2386 return stream.write(buffer, len);
2387}
2388
2389inline
2390bsl::ostream& Iso8601Util::generate(bsl::ostream& stream, const DateTz& object)
2391{
2392 return generate(stream,
2393 object,
2394 defaultConfiguration());
2395}
2396
2397inline
2398bsl::ostream& Iso8601Util::generate(
2399 bsl::ostream& stream,
2400 const DateTz& object,
2401 const GenerateConfiguration& configuration)
2402{
2403 char buffer[k_DATETZ_STRLEN + 1];
2404
2405 const int len = generate(buffer, k_DATETZ_STRLEN, object, configuration);
2406 BSLS_ASSERT_SAFE(k_DATETZ_STRLEN >= len);
2407
2408 return stream.write(buffer, len);
2409}
2410
2411inline
2412bsl::ostream& Iso8601Util::generate(bsl::ostream& stream, const TimeTz& object)
2413{
2414 return generate(stream,
2415 object,
2416 defaultConfiguration());
2417}
2418
2419inline
2420bsl::ostream& Iso8601Util::generate(
2421 bsl::ostream& stream,
2422 const TimeTz& object,
2423 const GenerateConfiguration& configuration)
2424{
2425 char buffer[k_TIMETZ_STRLEN + 1];
2426
2427 const int len = generate(buffer, k_TIMETZ_STRLEN, object, configuration);
2428 BSLS_ASSERT_SAFE(k_TIMETZ_STRLEN >= len);
2429
2430 return stream.write(buffer, len);
2431}
2432
2433inline
2434bsl::ostream&
2435Iso8601Util::generate(bsl::ostream& stream, const DatetimeTz& object)
2436{
2437 return generate(stream,
2438 object,
2439 defaultConfiguration());
2440}
2441
2442inline
2443bsl::ostream& Iso8601Util::generate(
2444 bsl::ostream& stream,
2445 const DatetimeTz& object,
2446 const GenerateConfiguration& configuration)
2447{
2448 char buffer[k_DATETIMETZ_STRLEN + 1];
2449
2450 const int len = generate(buffer,
2451 k_DATETIMETZ_STRLEN,
2452 object,
2453 configuration);
2454 BSLS_ASSERT_SAFE(k_DATETIMETZ_STRLEN >= len);
2455
2456 return stream.write(buffer, len);
2457}
2458
2459inline
2460bsl::ostream&
2461Iso8601Util::generate(bsl::ostream& stream, const DateOrDateTz& object)
2462{
2463 return generate(stream,
2464 object,
2465 defaultConfiguration());
2466}
2467
2468inline
2469bsl::ostream& Iso8601Util::generate(
2470 bsl::ostream& stream,
2471 const DateOrDateTz& object,
2472 const GenerateConfiguration& configuration)
2473{
2474 char buffer[k_DATETZ_STRLEN + 1];
2475
2476 const int len = generate(buffer,
2477 k_DATETZ_STRLEN,
2478 object,
2479 configuration);
2480 BSLS_ASSERT_SAFE(k_DATETZ_STRLEN >= len);
2481
2482 return stream.write(buffer, len);
2483}
2484
2485inline
2486bsl::ostream&
2487Iso8601Util::generate(bsl::ostream& stream, const TimeOrTimeTz& object)
2488{
2489 return generate(stream,
2490 object,
2491 defaultConfiguration());
2492}
2493
2494inline
2495bsl::ostream& Iso8601Util::generate(
2496 bsl::ostream& stream,
2497 const TimeOrTimeTz& object,
2498 const GenerateConfiguration& configuration)
2499{
2500 char buffer[k_TIMETZ_STRLEN + 1];
2501
2502 const int len = generate(buffer,
2503 k_TIMETZ_STRLEN,
2504 object,
2505 configuration);
2506 BSLS_ASSERT_SAFE(k_TIMETZ_STRLEN >= len);
2507
2508 return stream.write(buffer, len);
2509}
2510
2511inline
2512bsl::ostream&
2513Iso8601Util::generate(bsl::ostream& stream, const DatetimeOrDatetimeTz& object)
2514{
2515 return generate(stream,
2516 object,
2517 defaultConfiguration());
2518}
2519
2520inline
2521bsl::ostream& Iso8601Util::generate(
2522 bsl::ostream& stream,
2523 const DatetimeOrDatetimeTz& object,
2524 const GenerateConfiguration& configuration)
2525{
2526 char buffer[k_DATETIMETZ_STRLEN + 1];
2527
2528 const int len = generate(buffer,
2529 k_DATETIMETZ_STRLEN,
2530 object,
2531 configuration);
2532 BSLS_ASSERT_SAFE(k_DATETIMETZ_STRLEN >= len);
2533
2534 return stream.write(buffer, len);
2535}
2536
2537inline
2538int Iso8601Util::generateRaw(char *buffer, const bsls::TimeInterval& object)
2539{
2540 BSLS_ASSERT_SAFE(buffer);
2541
2542 return generateRaw(buffer,
2543 object,
2544 defaultConfiguration());
2545}
2546
2547inline
2548int Iso8601Util::generateRaw(char *buffer, const Date& object)
2549{
2550 BSLS_ASSERT_SAFE(buffer);
2551
2552 return generateRaw(buffer,
2553 object,
2554 defaultConfiguration());
2555}
2556
2557inline
2558int Iso8601Util::generateRaw(char *buffer, const Time& object)
2559{
2560 BSLS_ASSERT_SAFE(buffer);
2561
2562 return generateRaw(buffer,
2563 object,
2564 defaultConfiguration());
2565}
2566
2567inline
2568int Iso8601Util::generateRaw(char *buffer, const Datetime& object)
2569{
2570 BSLS_ASSERT_SAFE(buffer);
2571
2572 return generateRaw(buffer,
2573 object,
2574 defaultConfiguration());
2575}
2576
2577inline
2578int Iso8601Util::generateRaw(char *buffer, const DateTz& object)
2579{
2580 BSLS_ASSERT_SAFE(buffer);
2581
2582 return generateRaw(buffer,
2583 object,
2584 defaultConfiguration());
2585}
2586
2587inline
2588int Iso8601Util::generateRaw(char *buffer, const TimeTz& object)
2589{
2590 BSLS_ASSERT_SAFE(buffer);
2591
2592 return generateRaw(buffer,
2593 object,
2594 defaultConfiguration());
2595}
2596
2597inline
2598int Iso8601Util::generateRaw(char *buffer, const DatetimeTz& object)
2599{
2600 BSLS_ASSERT_SAFE(buffer);
2601
2602 return generateRaw(buffer,
2603 object,
2604 defaultConfiguration());
2605}
2606
2607inline
2608int Iso8601Util::generateRaw(char *buffer, const DateOrDateTz& object)
2609{
2610 BSLS_ASSERT_SAFE(buffer);
2611
2612 return generateRaw(buffer,
2613 object,
2614 defaultConfiguration());
2615}
2616
2617inline
2618int Iso8601Util::generateRaw(char *buffer, const TimeOrTimeTz& object)
2619{
2620 BSLS_ASSERT_SAFE(buffer);
2621
2622 return generateRaw(buffer,
2623 object,
2624 defaultConfiguration());
2625}
2626
2627inline
2628int Iso8601Util::generateRaw(char *buffer, const DatetimeOrDatetimeTz& object)
2629{
2630 BSLS_ASSERT_SAFE(buffer);
2631
2632 return generateRaw(buffer,
2633 object,
2634 defaultConfiguration());
2635}
2636
2637inline
2638int Iso8601Util::parse(bsls::TimeInterval *result,
2639 const bsl::string_view& string)
2640{
2641 BSLS_ASSERT_SAFE(string.data());
2642
2643 return parse(result, string.data(), string.length());
2644}
2645
2646inline
2647int Iso8601Util::parse(Date *result,
2648 const bsl::string_view& string,
2649 ParseConfiguration configuration)
2650{
2651 BSLS_ASSERT_SAFE(string.data());
2652
2653 return parse(result, string.data(), string.length(), configuration);
2654}
2655
2656inline
2657int Iso8601Util::parse(Time *result,
2658 const bsl::string_view& string,
2659 ParseConfiguration configuration)
2660{
2661 BSLS_ASSERT_SAFE(string.data());
2662
2663 return parse(result, string.data(), string.length(), configuration);
2664}
2665
2666inline
2667int Iso8601Util::parse(Datetime *result,
2668 const bsl::string_view& string,
2669 ParseConfiguration configuration)
2670{
2671 BSLS_ASSERT_SAFE(string.data());
2672
2673 return parse(result, string.data(), string.length(), configuration);
2674}
2675
2676inline
2677int Iso8601Util::parse(DateTz *result,
2678 const bsl::string_view& string,
2679 ParseConfiguration configuration)
2680{
2681 BSLS_ASSERT_SAFE(string.data());
2682
2683 return parse(result, string.data(), string.length(), configuration);
2684}
2685
2686inline
2687int Iso8601Util::parse(TimeTz *result,
2688 const bsl::string_view& string,
2689 ParseConfiguration configuration)
2690{
2691 BSLS_ASSERT_SAFE(string.data());
2692
2693 return parse(result, string.data(), string.length(), configuration);
2694}
2695
2696inline
2697int Iso8601Util::parse(DatetimeTz *result,
2698 const bsl::string_view& string,
2699 ParseConfiguration configuration)
2700{
2701 BSLS_ASSERT_SAFE(string.data());
2702
2703 return parse(result, string.data(), string.length(), configuration);
2704}
2705
2706inline
2707int Iso8601Util::parse(DateOrDateTz *result,
2708 const bsl::string_view& string,
2709 ParseConfiguration configuration)
2710{
2711 BSLS_ASSERT_SAFE(string.data());
2712
2713 return parse(result, string.data(), string.length(), configuration);
2714}
2715
2716inline
2717int Iso8601Util::parse(TimeOrTimeTz *result,
2718 const bsl::string_view& string,
2719 ParseConfiguration configuration)
2720{
2721 BSLS_ASSERT_SAFE(string.data());
2722
2723 return parse(result, string.data(), string.length(), configuration);
2724}
2725
2726inline
2727int Iso8601Util::parse(DatetimeOrDatetimeTz *result,
2728 const bsl::string_view& string,
2729 ParseConfiguration configuration)
2730{
2731 BSLS_ASSERT_SAFE(string.data());
2732
2733 return parse(result, string.data(), string.length(), configuration);
2734}
2735
2736#ifndef BDE_OMIT_INTERNAL_DEPRECATED
2737// DEPRECATED METHODS
2738inline
2739int Iso8601Util::parseRelaxed(Datetime *result, const bsl::string_view& string)
2740{
2741 BSLS_ASSERT_SAFE(string.data());
2742
2743 return parseRelaxed(result,
2744 string.data(),
2745 string.length());
2746}
2747
2748inline
2749int Iso8601Util::parseRelaxed(DatetimeTz *result,
2750 const bsl::string_view& string)
2751{
2752 BSLS_ASSERT_SAFE(string.data());
2753
2754 return parseRelaxed(result,
2755 string.data(),
2756 string.length());
2757}
2758
2759inline
2760int Iso8601Util::parseRelaxed(DatetimeOrDatetimeTz *result,
2761 const bsl::string_view& string)
2762{
2763 BSLS_ASSERT_SAFE(string.data());
2764
2765 return parseRelaxed(result,
2766 string.data(),
2767 string.length());
2768}
2769
2770inline
2771int Iso8601Util::generate(char *buffer,
2772 const Date& object,
2773 ssize_t bufferLength)
2774{
2775 return generate(buffer, bufferLength, object);
2776}
2777
2778inline
2779int Iso8601Util::generate(char *buffer,
2780 const Time& object,
2781 ssize_t bufferLength)
2782{
2783 return generate(buffer, bufferLength, object);
2784}
2785
2786inline
2787int Iso8601Util::generate(char *buffer,
2788 const Datetime& object,
2789 ssize_t bufferLength)
2790{
2791 return generate(buffer, bufferLength, object);
2792}
2793
2794inline
2795int Iso8601Util::generate(char *buffer,
2796 const DateTz& object,
2797 ssize_t bufferLength)
2798{
2799 return generate(buffer, bufferLength, object);
2800}
2801
2802inline
2803int Iso8601Util::generate(char *buffer,
2804 const TimeTz& object,
2805 ssize_t bufferLength)
2806{
2807 return generate(buffer, bufferLength, object);
2808}
2809
2810inline
2811int Iso8601Util::generate(char *buffer,
2812 const DatetimeTz& object,
2813 ssize_t bufferLength)
2814{
2815 return generate(buffer, bufferLength, object);
2816}
2817
2818inline
2819int Iso8601Util::generate(char *buffer,
2820 const DateTz& object,
2821 ssize_t bufferLength,
2822 bool useZAbbreviationForUtc)
2823{
2824 Iso8601UtilConfiguration configuration = defaultConfiguration();
2825 configuration.setUseZAbbreviationForUtc(useZAbbreviationForUtc);
2826
2827 return generate(buffer, bufferLength, object, configuration);
2828}
2829
2830inline
2831int Iso8601Util::generate(char *buffer,
2832 const TimeTz& object,
2833 ssize_t bufferLength,
2834 bool useZAbbreviationForUtc)
2835{
2836 Iso8601UtilConfiguration configuration = defaultConfiguration();
2837 configuration.setUseZAbbreviationForUtc(useZAbbreviationForUtc);
2838
2839 return generate(buffer, bufferLength, object, configuration);
2840}
2841
2842inline
2843int Iso8601Util::generate(char *buffer,
2844 const DatetimeTz& object,
2845 ssize_t bufferLength,
2846 bool useZAbbreviationForUtc)
2847{
2848 Iso8601UtilConfiguration configuration = defaultConfiguration();
2849 configuration.setUseZAbbreviationForUtc(useZAbbreviationForUtc);
2850
2851 return generate(buffer, bufferLength, object, configuration);
2852}
2853
2854inline
2855bsl::ostream& Iso8601Util::generate(bsl::ostream& stream,
2856 const DateTz& object,
2857 bool useZAbbreviationForUtc)
2858{
2859 Iso8601UtilConfiguration configuration = defaultConfiguration();
2860 configuration.setUseZAbbreviationForUtc(useZAbbreviationForUtc);
2861
2862 return generate(stream, object, configuration);
2863}
2864
2865inline
2866bsl::ostream& Iso8601Util::generate(bsl::ostream& stream,
2867 const TimeTz& object,
2868 bool useZAbbreviationForUtc)
2869{
2870 Iso8601UtilConfiguration configuration = defaultConfiguration();
2871 configuration.setUseZAbbreviationForUtc(useZAbbreviationForUtc);
2872
2873 return generate(stream, object, configuration);
2874}
2875
2876inline
2877bsl::ostream& Iso8601Util::generate(bsl::ostream& stream,
2878 const DatetimeTz& object,
2879 bool useZAbbreviationForUtc)
2880{
2881 Iso8601UtilConfiguration configuration = defaultConfiguration();
2882 configuration.setUseZAbbreviationForUtc(useZAbbreviationForUtc);
2883
2884 return generate(stream, object, configuration);
2885}
2886
2887inline
2888int Iso8601Util::generateRaw(char *buffer,
2889 const DateTz& object,
2890 bool useZAbbreviationForUtc)
2891{
2892 Iso8601UtilConfiguration configuration = defaultConfiguration();
2893 configuration.setUseZAbbreviationForUtc(useZAbbreviationForUtc);
2894
2895 return generateRaw(buffer, object, configuration);
2896}
2897
2898inline
2899int Iso8601Util::generateRaw(char *buffer,
2900 const TimeTz& object,
2901 bool useZAbbreviationForUtc)
2902{
2903 Iso8601UtilConfiguration configuration = defaultConfiguration();
2904 configuration.setUseZAbbreviationForUtc(useZAbbreviationForUtc);
2905
2906 return generateRaw(buffer, object, configuration);
2907}
2908
2909inline
2910int Iso8601Util::generateRaw(char *buffer,
2911 const DatetimeTz& object,
2912 bool useZAbbreviationForUtc)
2913{
2914 Iso8601UtilConfiguration configuration = defaultConfiguration();
2915 configuration.setUseZAbbreviationForUtc(useZAbbreviationForUtc);
2916
2917 return generateRaw(buffer, object, configuration);
2918}
2919#endif // BDE_OMIT_INTERNAL_DEPRECATED
2920
2921} // close package namespace
2922
2923
2924#endif
2925
2926// ----------------------------------------------------------------------------
2927// Copyright 2016 Bloomberg Finance L.P.
2928//
2929// Licensed under the Apache License, Version 2.0 (the "License");
2930// you may not use this file except in compliance with the License.
2931// You may obtain a copy of the License at
2932//
2933// http://www.apache.org/licenses/LICENSE-2.0
2934//
2935// Unless required by applicable law or agreed to in writing, software
2936// distributed under the License is distributed on an "AS IS" BASIS,
2937// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
2938// See the License for the specific language governing permissions and
2939// limitations under the License.
2940// ----------------------------- END-OF-FILE ----------------------------------
2941
2942/** @} */
2943/** @} */
2944/** @} */
bdlb_variant.h
bdlt_date.h
bdlt_datetime.h
bdlt_datetimetz.h
bdlt_datetz.h
bdlt_iso8601utilconfiguration.h
bdlt_iso8601utilparseconfiguration.h
bdlt_time.h
bdlt_timetz.h
bslmf_assert.h
bslmf_issame.h
bsls_assert.h
bsls_deprecatefeature.h
bsls_ident.h
bsls_libraryfeatures.h
bsls_types.h
bdlb::Variant2
Definition bdlb_variant.h:2514
bdlt::DateTz
Definition bdlt_datetz.h:162
bdlt::Date
Definition bdlt_date.h:294
bdlt::DatetimeTz
Definition bdlt_datetimetz.h:308
bdlt::Datetime
Definition bdlt_datetime.h:331
bdlt::Iso8601UtilConfiguration
Definition bdlt_iso8601utilconfiguration.h:225
bdlt::Iso8601UtilConfiguration::setUseZAbbreviationForUtc
void setUseZAbbreviationForUtc(bool value)
bdlt::Iso8601UtilConfiguration::defaultConfiguration
static Iso8601UtilConfiguration defaultConfiguration()
Definition bdlt_iso8601utilconfiguration.h:407
bdlt::Iso8601UtilParseConfiguration
Definition bdlt_iso8601utilparseconfiguration.h:158
bdlt::TimeTz
Definition bdlt_timetz.h:190
bdlt::Time
Definition bdlt_time.h:196
bsl::basic_string_view
Definition bslstl_stringview.h:441
bsl::basic_string
Definition bslstl_string.h:1281
bsls::TimeInterval
Definition bsls_timeinterval.h:301
BDLT_ISO8601UTIL_DEPRECATE_GENERATE
#define BDLT_ISO8601UTIL_DEPRECATE_GENERATE
Definition bdlt_iso8601util.h:697
BDLT_ISO8601UTIL_DEPRECATE_GENERATERAW
#define BDLT_ISO8601UTIL_DEPRECATE_GENERATERAW
Definition bdlt_iso8601util.h:707
BDLT_ISO8601UTIL_DEPRECATE_PARSERELAXED
#define BDLT_ISO8601UTIL_DEPRECATE_PARSERELAXED
Definition bdlt_iso8601util.h:712
BDLT_ISO8601UTIL_DEPRECATE_GENERATE_ORDER
#define BDLT_ISO8601UTIL_DEPRECATE_GENERATE_ORDER
Definition bdlt_iso8601util.h:702
BSLS_ASSERT_SAFE
#define BSLS_ASSERT_SAFE(X)
Definition bsls_assert.h:1762
BSLS_IDENT
#define BSLS_IDENT(str)
Definition bsls_ident.h:195
bdlt
Definition bbldc_basicisma30360.h:112
bsls
Definition bdlt_iso8601util.h:691
bdlt::Iso8601Util
Definition bdlt_iso8601util.h:732
bdlt::Iso8601Util::generate
static int generate(std::string *string, const Date &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generateRaw
static int generateRaw(char *buffer, const TimeOrTimeTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generate
static int generate(bsl::string *string, const DateTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::parseRelaxed
static BDLT_ISO8601UTIL_DEPRECATE_PARSERELAXED int parseRelaxed(DatetimeOrDatetimeTz *result, const char *string, ssize_t length)
bdlt::Iso8601Util::generate
static int generate(std::string *string, const DatetimeTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::Configuration
Iso8601UtilConfiguration Configuration
Definition bdlt_iso8601util.h:784
bdlt::Iso8601Util::generateRaw
static int generateRaw(char *buffer, const Time &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::parse
static int parse(DatetimeTz *result, const char *string, ssize_t length, ParseConfiguration configuration=ParseConfiguration())
bdlt::Iso8601Util::generate
static int generate(bsl::string *string, const DatetimeTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generate
static int generate(char *buffer, ssize_t bufferLength, const DatetimeOrDatetimeTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::parse
static int parse(Time *result, const char *string, ssize_t length, ParseConfiguration configuration=ParseConfiguration())
bdlt::Iso8601Util::parse
static int parse(Date *result, const char *string, ssize_t length, ParseConfiguration configuration=ParseConfiguration())
bdlt::Iso8601Util::parse
static int parse(Datetime *result, const char *string, ssize_t length, ParseConfiguration configuration=ParseConfiguration())
bdlt::Iso8601Util::generateRaw
static int generateRaw(char *buffer, const DatetimeOrDatetimeTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::ParseConfiguration
Iso8601UtilParseConfiguration ParseConfiguration
Configuration for string parsing.
Definition bdlt_iso8601util.h:790
bdlt::Iso8601Util::generate
static int generate(char *buffer, ssize_t bufferLength, const Datetime &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::BDEPU_DATETIME_STRLEN
@ BDEPU_DATETIME_STRLEN
Definition bdlt_iso8601util.h:765
bdlt::Iso8601Util::k_DATETZ_STRLEN
@ k_DATETZ_STRLEN
Definition bdlt_iso8601util.h:751
bdlt::Iso8601Util::k_DATE_STRLEN
@ k_DATE_STRLEN
Definition bdlt_iso8601util.h:750
bdlt::Iso8601Util::BDEPU_MAX_DATETIME_STRLEN
@ BDEPU_MAX_DATETIME_STRLEN
Definition bdlt_iso8601util.h:770
bdlt::Iso8601Util::k_TIME_STRLEN
@ k_TIME_STRLEN
Definition bdlt_iso8601util.h:753
bdlt::Iso8601Util::TIMETZ_STRLEN
@ TIMETZ_STRLEN
Definition bdlt_iso8601util.h:777
bdlt::Iso8601Util::BDEPU_DATETIMETZ_STRLEN
@ BDEPU_DATETIMETZ_STRLEN
Definition bdlt_iso8601util.h:766
bdlt::Iso8601Util::DATETIMETZ_STRLEN
@ DATETIMETZ_STRLEN
Definition bdlt_iso8601util.h:774
bdlt::Iso8601Util::DATETZ_STRLEN
@ DATETZ_STRLEN
Definition bdlt_iso8601util.h:775
bdlt::Iso8601Util::k_DATETIMETZ_STRLEN
@ k_DATETIMETZ_STRLEN
Definition bdlt_iso8601util.h:757
bdlt::Iso8601Util::k_TIMEINTERVAL_STRLEN
@ k_TIMEINTERVAL_STRLEN
Definition bdlt_iso8601util.h:759
bdlt::Iso8601Util::BDEPU_TIMETZ_STRLEN
@ BDEPU_TIMETZ_STRLEN
Definition bdlt_iso8601util.h:769
bdlt::Iso8601Util::k_MAX_STRLEN
@ k_MAX_STRLEN
Definition bdlt_iso8601util.h:761
bdlt::Iso8601Util::BDEPU_DATE_STRLEN
@ BDEPU_DATE_STRLEN
Definition bdlt_iso8601util.h:764
bdlt::Iso8601Util::DATE_STRLEN
@ DATE_STRLEN
Definition bdlt_iso8601util.h:772
bdlt::Iso8601Util::MAX_DATETIME_STRLEN
@ MAX_DATETIME_STRLEN
Definition bdlt_iso8601util.h:778
bdlt::Iso8601Util::TIME_STRLEN
@ TIME_STRLEN
Definition bdlt_iso8601util.h:776
bdlt::Iso8601Util::BDEPU_TIME_STRLEN
@ BDEPU_TIME_STRLEN
Definition bdlt_iso8601util.h:768
bdlt::Iso8601Util::k_TIMETZ_STRLEN
@ k_TIMETZ_STRLEN
Definition bdlt_iso8601util.h:754
bdlt::Iso8601Util::DATETIME_STRLEN
@ DATETIME_STRLEN
Definition bdlt_iso8601util.h:773
bdlt::Iso8601Util::BDEPU_DATETZ_STRLEN
@ BDEPU_DATETZ_STRLEN
Definition bdlt_iso8601util.h:767
bdlt::Iso8601Util::k_DATETIME_STRLEN
@ k_DATETIME_STRLEN
Definition bdlt_iso8601util.h:756
bdlt::Iso8601Util::generate
static int generate(char *buffer, ssize_t bufferLength, const Date &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generate
static int generate(std::string *string, const Datetime &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generate
static int generate(bsl::string *string, const bsls::TimeInterval &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generate
static int generate(bsl::string *string, const DateOrDateTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generate
static int generate(bsl::string *string, const TimeOrTimeTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::TimeOrTimeTz
bdlb::Variant2< Time, TimeTz > TimeOrTimeTz
Definition bdlt_iso8601util.h:798
bdlt::Iso8601Util::generate
static int generate(char *buffer, ssize_t bufferLength, const Time &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generate
static int generate(char *buffer, ssize_t bufferLength, const DateOrDateTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generate
static int generate(bsl::string *string, const Datetime &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generate
static int generate(std::string *string, const TimeOrTimeTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::ssize_t
bsl::ptrdiff_t ssize_t
Definition bdlt_iso8601util.h:782
bdlt::Iso8601Util::GenerateConfiguration
Iso8601UtilConfiguration GenerateConfiguration
Configuration for string generation.
Definition bdlt_iso8601util.h:787
bdlt::Iso8601Util::generateRaw
static int generateRaw(char *buffer, const bsls::TimeInterval &object)
Definition bdlt_iso8601util.h:2538
bdlt::Iso8601Util::generate
static int generate(std::string *string, const bsls::TimeInterval &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::parse
static int parse(TimeTz *result, const char *string, ssize_t length, ParseConfiguration configuration=ParseConfiguration())
bdlt::Iso8601Util::generate
static int generate(bsl::string *string, const DatetimeOrDatetimeTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::DatetimeOrDatetimeTz
bdlb::Variant2< Datetime, DatetimeTz > DatetimeOrDatetimeTz
Definition bdlt_iso8601util.h:802
bdlt::Iso8601Util::parse
static int parse(DateTz *result, const char *string, ssize_t length, ParseConfiguration configuration=ParseConfiguration())
bdlt::Iso8601Util::generate
static int generate(std::string *string, const TimeTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generate
static int generate(char *buffer, ssize_t bufferLength, const DatetimeTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generateRaw
static int generateRaw(char *buffer, const TimeTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generate
static int generate(std::string *string, const DatetimeOrDatetimeTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generate
static int generate(std::string *string, const DateTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generateRaw
static int generateRaw(char *buffer, const bsls::TimeInterval &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::parseRelaxed
static BDLT_ISO8601UTIL_DEPRECATE_PARSERELAXED int parseRelaxed(Datetime *result, const char *string, ssize_t length)
bdlt::Iso8601Util::generate
static int generate(char *buffer, ssize_t bufferLength, const TimeOrTimeTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::parseRelaxed
static BDLT_ISO8601UTIL_DEPRECATE_PARSERELAXED int parseRelaxed(DatetimeTz *result, const char *string, ssize_t length)
bdlt::Iso8601Util::generate
static int generate(char *buffer, ssize_t bufferLength, const TimeTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generateRaw
static int generateRaw(char *buffer, const Date &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generate
static int generate(char *buffer, ssize_t bufferLength, const DateTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generate
static int generate(std::string *string, const Time &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::parse
static int parse(TimeOrTimeTz *result, const char *string, ssize_t length, ParseConfiguration configuration=ParseConfiguration())
bdlt::Iso8601Util::DateOrDateTz
bdlb::Variant2< Date, DateTz > DateOrDateTz
Definition bdlt_iso8601util.h:794
bdlt::Iso8601Util::generateRaw
static int generateRaw(char *buffer, const DateOrDateTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generateRaw
static int generateRaw(char *buffer, const DatetimeTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generate
static int generate(bsl::string *string, const Time &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generateRaw
static int generateRaw(char *buffer, const DateTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generate
static int generate(bsl::string *string, const Date &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::parse
static int parse(DateOrDateTz *result, const char *string, ssize_t length, ParseConfiguration configuration=ParseConfiguration())
bdlt::Iso8601Util::generateRaw
static int generateRaw(char *buffer, const Datetime &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generate
static int generate(bsl::string *string, const TimeTz &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::parse
static int parse(bsls::TimeInterval *result, const char *string, ssize_t length)
bdlt::Iso8601Util::generate
static int generate(char *buffer, ssize_t bufferLength, const bsls::TimeInterval &object, const GenerateConfiguration &configuration)
bdlt::Iso8601Util::generate
static int generate(char *buffer, ssize_t bufferLength, const bsls::TimeInterval &object)
Definition bdlt_iso8601util.h:1967
bdlt::Iso8601Util::parse
static int parse(DatetimeOrDatetimeTz *result, const char *string, ssize_t length, ParseConfiguration configuration=ParseConfiguration())
bdlt::Iso8601Util::generate
static int generate(std::string *string, const DateOrDateTz &object, const GenerateConfiguration &configuration)