baljsn_encoderoptions

Detailed Description

Outline

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

Purpose

Provide an attribute class for specifying JSON encoding options.

Classes

• baljsn::EncoderOptions: options for encoding objects in the JSON format

See also

baljsn_encoder, baljsn_decoderoptions

Description

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

Attributes

Name                Type           Default         Simple Constraints
------------------  -----------    -------         ------------------
encodingStyle       EncodingStyle  e_COMPACT       none
initialIndentLevel  int            0               >= 0
spacesPerLevel      int            0               >= 0
encodeEmptyArrays   bool           false           none
encodeNullElements  bool           false           none
encodeInfAndNaNAsStrings
                    bool           false           none
encodeQuotedDecimal64
                    bool           true            none
datetimeFractionalSecondPrecision
                    int            3               >= 0 and <= 6
maxFloatPrecision   int            0               >= 1 and <= 9  or 0
maxDoublePrecision  int            0               >= 1 and <= 17 or 0

• encodingStyle: encoding style used to encode the JSON data.
• initialIndentLevel: Initial indent level for the topmost element.
• spacesPerLevel: spaces per additional indent level.
• encodeEmptyArrays: option specifying if empty arrays should be encoded (empty arrays occurring as selections of choices are always encoded).
• encodeNullElements: option specifying if null elements should be encoded.
• encodeInfAndNaNAsStrings: JSON does not provide a way to encode these values as they are not numbers. This option provides a way to encode these values. Although the resulting output is a valid JSON document, decoders expecting floating point numbers to be encoded only as numbers will fail to decode. Users of this option must therefore exercise caution and ensure that if this option is used then the parser decoding the generated JSON can handle doubles as strings.
• encodeQuotedDecimal64: option specifying a way to encode Decimal64 values. If the encodeQuotedDecimal64 attribute value is true (the default), the Decimal64 values will be encoded quoted, and otherwise they will be encoded as numbers. Encoding a Decimal64 as a JSON number will frequently result in it being later decoded as a 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).
• datetimeFractionalSecondPrecision: option specifying the number of decimal places used for seconds when encoding Datetime and DatetimeTz.
• maxFloatPrecision: [DEPRECATED] option specifying the maximum number of decimal places used to encode each float value. When 0 (the default value) the encoder will use the minimum that is necessary to restore the binary value into a float. We recommend against setting this option: the option was provided prior to the current default behavior (of choosing the shortest presentation that can be restored to the original value) being available.
• maxDoublePrecision: [DEPRECATED] option specifying the maximum number of decimal places used to encode each double value. When 0 (the default value) the encoder will use the minimum that is necessary to restore the binary value into a double. We recommend against setting this option: the option was provided prior to the current default behavior (of choosing the shortest presentation that can be restored to the original value) being available.

Implementation Note

This file was generated from a script and was subsequently modified to add documentation and to make other changes. The steps to generate and update this file can be found in the doc/generating_codec_options.txt file.

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 objects in the JSON format. This example shows how to create and populate an options object.

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

const int  INITIAL_INDENT_LEVEL      = 1;
const int  SPACES_PER_LEVEL          = 4;
const bool ENCODE_EMPTY_ARRAYS       = true;
const bool ENCODE_NULL_ELEMENTS      = true;
const bool ENCODE_INF_NAN_AS_STRINGS = true;
const int  DATETIME_PRECISION        = 6;
const int  FLOAT_PRECISION           = 3;
const int  DOUBLE_PRECISION          = 9;
const bool ENCODE_QUOTED_DECIMAL64   = false;
 
baljsn::EncoderOptions options;
assert(0     == options.initialIndentLevel());
assert(0     == options.spacesPerLevel());
assert(baljsn::EncoderOptions::e_COMPACT == options.encodingStyle());
assert(false == options.encodeEmptyArrays());
assert(false == options.encodeNullElements());
assert(false == options.encodeInfAndNaNAsStrings());
assert(3     == options.datetimeFractionalSecondPrecision());
assert(0     == options.maxFloatPrecision());
assert(0     == options.maxDoublePrecision());
assert(true  == options.encodeQuotedDecimal64());

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

options.setEncodingStyle(baljsn::EncodingStyle::e_PRETTY);
assert(baljsn::EncoderOptions::e_PRETTY == options.encodingStyle());
 
options.setInitialIndentLevel(INITIAL_INDENT_LEVEL);
assert(INITIAL_INDENT_LEVEL == options.initialIndentLevel());
 
options.setSpacesPerLevel(SPACES_PER_LEVEL);
assert(SPACES_PER_LEVEL == options.spacesPerLevel());
 
options.setEncodeEmptyArrays(ENCODE_EMPTY_ARRAYS);
assert(ENCODE_EMPTY_ARRAYS == options.encodeEmptyArrays());
 
options.setEncodeNullElements(ENCODE_NULL_ELEMENTS);
assert(ENCODE_NULL_ELEMENTS == options.encodeNullElements());
 
options.setEncodeInfAndNaNAsStrings(ENCODE_INF_NAN_AS_STRINGS);
assert(ENCODE_INF_NAN_AS_STRINGS == options.encodeInfAndNaNAsStrings());
 
options.setDatetimeFractionalSecondPrecision(DATETIME_PRECISION);
assert(DATETIME_PRECISION == options.datetimeFractionalSecondPrecision());
 
options.setMaxFloatPrecision(FLOAT_PRECISION);
assert(FLOAT_PRECISION == options.maxFloatPrecision());
 
options.setMaxDoublePrecision(DOUBLE_PRECISION);
assert(DOUBLE_PRECISION == options.maxDoublePrecision());
 
options.setEncodeQuotedDecimal64(ENCODE_QUOTED_DECIMAL64);
ASSERT(ENCODE_QUOTED_DECIMAL64 == options.encodeQuotedDecimal64());