bdlt_iso8601utilconfiguration Component

Provide an attribute class to configure ISO 8601 string generation. More...

Namespaces
namespace	bdlt

Detailed Description

Outline

Purpose
Classes
Description

Purpose:: Provide an attribute class to configure ISO 8601 string generation.

Classes:

bdlt::Iso8601UtilConfiguration

configuration for ISO 8601 strings

See also:: Component bdlt_iso8601util

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.

Component bdlt_iso8601utilconfiguration [Package bdlt]

Namespaces

Detailed Description

Component bdlt_iso8601utilconfiguration
[Package bdlt]