Component bdlt_fixutilconfiguration [Package bdlt]

Provide an attribute class to configure FIX string generation. More...

Namespaces
namespace	bdlt

---

Detailed Description

Outline

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

Purpose:

Provide an attribute class to configure FIX string generation.

Classes:

bdlt::FixUtilConfiguration

configuration for FIX strings

See also:

Component bdlt_fixutil

Description:

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

Attributes:

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

• fractionalSecondPrecision: number of digits used to represent fractional seconds; must be in the range 0 .. 6.
• useZAbbreviationForUtc: true if Z should be used for the timezone offset 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 FIX String Generation:

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

  const bdlt::DatetimeTz datetimeTz(
                             bdlt::Datetime(2005, 1, 31, 8, 59, 59, 123), 0);

my::FixUtil produces, by default, the following string (which is a valid FIX string):

  20050131-08:59:59.123+00:00

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

  20050131-08:59:59.123000Z

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

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

  bdlt::FixUtilConfiguration configuration;
  assert( configuration.fractionalSecondPrecision() == 3);
  assert(!configuration.useZAbbreviationForUtc());

Then, we modify configuration to indicate that we want to use 6 digits of precision in the fractional seconds:

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

Finally, we modify configuration to indicate that we want to use Z as an abbreviation for UTC:

  configuration.setUseZAbbreviationForUtc(true);
  assert( configuration.fractionalSecondPrecision() == 6);
  assert( configuration.useZAbbreviationForUtc());

Our configuration object can now be supplied to my::FixUtil 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::FixUtilConfiguration configuration =
                          bdlt::FixUtilConfiguration::defaultConfiguration();
  assert(bdlt::FixUtilConfiguration() == configuration);
  assert( configuration.fractionalSecondPrecision() == 3);
  assert(!configuration.useZAbbreviationForUtc());

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

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

Then, we modify configuration to display milliseconds:

  configuration.setFractionalSecondPrecision(6);
  assert( configuration.fractionalSecondPrecision() == 6);
  assert( configuration.useZAbbreviationForUtc());

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

  bdlt::FixUtilConfiguration::setDefaultConfiguration(configuration);

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

  const bdlt::FixUtilConfiguration newConfiguration =
                      bdlt::FixUtilConfiguration::defaultConfiguration();
  assert( newConfiguration.fractionalSecondPrecision() == 6);
  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.