baljsn_decoderoptionsutil

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Modes
  • Usage
    • Example 1: Setting baljsn::DecoderOptions for Strictness

Purpose

Provide a utility for configuring baljsn::DecoderOptions.

Classes

• baljsn::DecoderOptionsUtil: utility for setting baljsn::DecoderOptions

See also

baljsn_decoder, baljsn_decoderoptions

Description

This component provides a struct of utility functions, baljsn::DecoderOptionsUtil, for configuring baljsn::DecoderOptions object. In particular, this utility can be used to set the combination of options needed for strict compliance with the JSON grammar (see Strict Conformance . This utility can also be used to set a baljsn::DecoderOptions object to its default state.

Modes

When a default constructed baljsn::DecoderOptions object is passed to the decode methods of a baljsn::Decoder, several convenient variances from the JSON grammar are tolerated in the JSON document without causing failure. Specifically:

validateInputIsUtf8              false
allowConsecutiveSeparators       true
allowFormFeedAsWhitespace        true
allowUnescapedControlCharacters  true

See Attributes for examples. Should any of these variances be unacceptable, then one can flip individual options. Strict compliance (see bdljsn_jsontestsuiteutil ) with the JSON grammar requires that each option named above be flipped to the opposite value:

validateInputIsUtf8              true
allowConsecutiveSeparators       false
allowFormFeedAsWhitespace        false
allowUnescapedControlCharacters  false

This utility defines the mode baljsn::DecoderOptionsUtil::e_STRICT_20240423 to allow all four options to be set with a single call.

Note that baljsn::DecoderOptions defines other options besides the four cited above. Those are not changed by setting the baljsn::DecoderOptionsUtil::e_STRICT_20240423 combination but are set when setting the options object using baljsn::DecoderOptionsUtil::e_DEFAULT.

Usage

This section illustrates intended use of this component.

Example 1: Setting baljsn::DecoderOptions for Strictness

Every call to one of the (non-deprecated) decode functions of baljsn::Decoder requires the user to provide a baljsn::DecoderOptions object that allows the user to fine-tune the rules used when decoding the JSON document. The setMode function of this utility provides a convenient way to set the option attributes to a combination that is deemed "strict" (i.e., strictly complying with the rules of the JSON grammar).

First, create a baljsn::DecoderOptions object:

baljsn::DecoderOptions options;

Now, set the option values for strict compliance:

baljsn::DecoderOptionsUtil::setMode(
                            &options,
                            baljsn::DecoderOptionsUtil::e_STRICT_20240423);

Finally, should there be a need, options can be adjusted to a laxer set of rules by adjusting individual attributes or, if the original set of default attributes is needed, by using setMode:

baljsn::DecoderOptionsUtil::setMode(&options,
                                    baljsn::DecoderOptionsUtil::e_DEFAULT);