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