baljsn_datumencoderoptions

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

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());