Component baljsn_datumencoderoptions [Package baljsn]

Provide an attribute class for specifying Datum<->JSON options. More...

Namespaces
namespace	baljsn

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Attributes
  • Usage
    • Example 1: Creating and Populating an Options Object

Purpose:

Provide an attribute class for specifying Datum<->JSON options.

Classes:

baljsn::DatumEncoderOptions

options for JSON encoding Datum objects

See also:

Component baljsn_datumutil

Description:

This component provides a single, simply constrained (value-semantic) attribute class, baljsn::DatumEncoderOptions, that is used to specify options for encoding Datum objects in the JSON format (see baljsn::DatumUtil).

Attributes:

  Name                Type           Default         Simple Constraints
  ------------------  -----------    -------         ------------------
  strictTypes         bool           false           none
  encodingStyle       EncodingStyle  e_COMPACT       none
  encodeQuotedDecimal64
                      bool           true            none
  initialIndentLevel  int            0               >= 0
  spacesPerLevel      int            0               >= 0

• strictTypes: whether type-checking is performed to make sure encoded types conform to the strict set of types that JSON can represent (and can thus be decoded back to the same types of Datum values) (['string', double, bool, null, array, map]).
• encodingStyle: encoding style used to encode the JSON data.
• encodeQuotedDecimal64: option specifying a way to encode Decimal64 values. If the encodeQuotedDecimal64 attribute in the DatumEncoderOptions is true (the default), the Decimal64 values will be encoded as strings, otherwise they will be encoded as numbers. Encoding a Decimal64 as a JSON numbers will frequently result it being later decoded as binary floating point number, and in the process losing digits of precision that were the point of using the Decimal64 type in the first place. Care should be taken when setting this option to false (though it may be useful when communicating with endpoints that are known to correctly handle high precision JSON numbers).
• initialIndentLevel: Initial indent level for the topmost element.
• spacesPerLevel: spaces per additional indent level.

Usage:

This section illustrates intended use of this component.

Example 1: Creating and Populating an Options Object:

This component is designed to be used at a higher level to set the options for encoding Datum objects in the JSON format. This example shows how to create and populate an options object.

First, we default-construct a baljsn::DatumEncoderOptions object:

  const bool STRICT_TYPES             = true;
  const int  INITIAL_INDENT_LEVEL     = 1;
  const int  SPACES_PER_LEVEL         = 4;
  const bool ENCODE_QUOTED_DECIMAL64  = false;

  baljsn::DatumEncoderOptions options;
  assert(false == options.strictTypes());
  assert(0     == options.initialIndentLevel());
  assert(0     == options.spacesPerLevel());
  assert(baljsn::EncodingStyle::e_COMPACT == options.encodingStyle());
  assert(true  == options.encodeQuotedDecimal64());

Next, we populate that object to check strict types and encode in a pretty format using a pre-defined initial indent level and spaces per level:

  options.setStrictTypes(STRICT_TYPES);
  assert(true == options.strictTypes());

  options.setEncodingStyle(baljsn::EncodingStyle::e_PRETTY);
  assert(baljsn::EncodingStyle::e_PRETTY == options.encodingStyle());

  options.setEncodeQuotedDecimal64(ENCODE_QUOTED_DECIMAL64);
  ASSERT(ENCODE_QUOTED_DECIMAL64 == options.encodeQuotedDecimal64());

  options.setInitialIndentLevel(INITIAL_INDENT_LEVEL);
  assert(INITIAL_INDENT_LEVEL == options.initialIndentLevel());

  options.setSpacesPerLevel(SPACES_PER_LEVEL);
  assert(SPACES_PER_LEVEL == options.spacesPerLevel());