bdlt_iso8601utilconfiguration

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Attributes
  • Default Configuration
  • Usage
    • Example 1: Configuring ISO 8601 String Generation
    • Example 2: Setting the Process-Wide Default Configuration

Purpose

Provide an attribute class to configure ISO 8601 string generation.

Classes

• bdlt::Iso8601UtilConfiguration: configuration for ISO 8601 strings

See also

bdlt_iso8601util, bdlt_iso8601utilparseconfiguration

Description

This component provides an unconstrained (value-semantic) attribute class, bdlt::Iso8601UtilConfiguration, that may be used to configure various aspects of generated ISO 8601 strings.

Attributes

           Name             Type   Default
-------------------------   ----   -------
fractionalSecondPrecision   int     3
omitColonInZoneDesignator   bool    false
useCommaForDecimalSign      bool    false
useZAbbreviationForUtc      bool    false

• fractionalSecondPrecision: number of digits used to represent fractional seconds; must be in the range 0 .. 6.
• omitColonInZoneDesignator: true if : should be omitted from zone designators.
• useCommaForDecimalSign: true if , should be used as the decimal sign in fractional seconds; otherwise, . should be used.
• useZAbbreviationForUtc: true if Z should be used for the zone designator instead of +00:00 (specific to UTC).

Default Configuration

This component also provides a (process-wide) default configuration that may be set and retrieved via the setDefaultConfiguration and defaultConfiguration class methods, respectively. See Usage Example 2 for further details.

Usage

This section illustrates intended use of this component.

Example 1: Configuring ISO 8601 String Generation

This example demonstrates creation of a bdlt::Iso8601UtilConfiguration object that may be used to influence the format of the output produced by a hypothetical utility, my::Iso8601Util, that generates and parses ISO 8601 strings for bdlt vocabulary types (see bdlt_iso8601util , which provides just such functionality). In particular, suppose that given a sample bdlt::TimeTz object:

const bdlt::TimeTz timeTz(bdlt::Time(8, 59, 59, 123), 240);

my::Iso8601Util produces, by default, the following (valid) ISO 8601 string:

08:59:59.123+04:00

However, we would like to produce the following (also valid) ISO 8601 string instead:

08:59:59,123+0400

bdlt::Iso8601UtilConfiguration can be used to obtain the desired result assuming that my::Iso8601Util uses bdlt::Iso8601UtilConfiguration to affect the format of generated strings in this fashion (e.g., again see bdlt_iso8601util ).

First, we construct a bdlt::Iso8601UtilConfiguration object that has the default value:

bdlt::Iso8601UtilConfiguration configuration;
assert( configuration.fractionalSecondPrecision() == 3);
assert(!configuration.omitColonInZoneDesignator());
assert(!configuration.useCommaForDecimalSign());
assert(!configuration.useZAbbreviationForUtc());

Then, we modify configuration to indicate that we want to use , as the decimal sign (in fractional seconds):

configuration.setUseCommaForDecimalSign(true);
assert( configuration.fractionalSecondPrecision() == 3);
assert(!configuration.omitColonInZoneDesignator());
assert( configuration.useCommaForDecimalSign());
assert(!configuration.useZAbbreviationForUtc());

Finally, we modify configuration to indicate that we want to omit the : in zone designators:

configuration.setOmitColonInZoneDesignator(true);
assert( configuration.fractionalSecondPrecision() == 3);
assert( configuration.omitColonInZoneDesignator());
assert( configuration.useCommaForDecimalSign());
assert(!configuration.useZAbbreviationForUtc());

Our configuration object can now be supplied to my::Iso8601Util to produce the desired result.

Example 2: Setting the Process-Wide Default Configuration

This example demonstrates how to establish the process-wide default configuration.

First, we retrieve the default configuration in effect at process start-up and note that it has the default-constructed value:

bdlt::Iso8601UtilConfiguration configuration =
                    bdlt::Iso8601UtilConfiguration::defaultConfiguration();
assert(bdlt::Iso8601UtilConfiguration() == configuration);
assert( configuration.fractionalSecondPrecision() == 3);
assert(!configuration.omitColonInZoneDesignator());
assert(!configuration.useCommaForDecimalSign());
assert(!configuration.useZAbbreviationForUtc());

Next, we modify configuration to indicate that we want to output Z when the zone designator is UTC (i.e., instead of +00:00):

configuration.setUseZAbbreviationForUtc(true);
assert( configuration.fractionalSecondPrecision() == 3);
assert(!configuration.omitColonInZoneDesignator());
assert(!configuration.useCommaForDecimalSign());
assert( configuration.useZAbbreviationForUtc());

Then, we modify configuration to display milliseconds:

configuration.setFractionalSecondPrecision(6);
assert( configuration.fractionalSecondPrecision() == 6);
assert(!configuration.omitColonInZoneDesignator());
assert(!configuration.useCommaForDecimalSign());
assert( configuration.useZAbbreviationForUtc());

Now, we set the default configuration to the value of our configuration object:

bdlt::Iso8601UtilConfiguration::setDefaultConfiguration(configuration);

Finally, we verify that the default configuration was updated as expected:

const bdlt::Iso8601UtilConfiguration newConfiguration =
                    bdlt::Iso8601UtilConfiguration::defaultConfiguration();
assert( newConfiguration.fractionalSecondPrecision() == 6);
assert(!newConfiguration.omitColonInZoneDesignator());
assert(!newConfiguration.useCommaForDecimalSign());
assert( newConfiguration.useZAbbreviationForUtc());

Note that the expected usage is that the process-wide configuration will be established once, early in main, and not changed throughout the lifetime of a process.