baljsn_encoderoptions Component

Provide an attribute class for specifying JSON encoding options. More...

Namespaces
namespace	baljsn

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:: Component baljsn_encoder, Component 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());

Component baljsn_encoderoptions [Package baljsn]

Namespaces

Detailed Description

Component baljsn_encoderoptions
[Package baljsn]