<commit_before>// baljsn_datumutil.h                                                 -*-C++-*-
#ifndef INCLUDED_BALJSN_DATUMUTIL
#define INCLUDED_BALJSN_DATUMUTIL

#include <bsls_ident.h>
BSLS_IDENT("$Id$ $CSID$")

//@PURPOSE: Provide utilities converting between 'bdld::Datum' and JSON data.
//
//@CLASSES:
//  baljsn::DatumUtil: utilities converting between 'bdld::Datum' and JSON data
//
//@DESCRIPTION: This component provides a struct, 'baljsn::DatumUtil', that is
// a namespace for a suite of functions that convert a 'bdld::Datum' into a
// JSON string, and back.
//
///Mapping Data Types between Datum and JSON
///-----------------------------------------
// While most scalar types supported by 'Datum' can be encoded into a JSON
// string, only the subset of types represented natively in JSON -- number
// (represented in C++ as a 'double'), 'string', 'bool', 'null', array, and map
// types -- will be populated in a Datum decoded from a JSON string.  If one
// were to encode a Datum containing a type not natively supported by JSON, if
// that JSON string were decoded back into a Datum object, the resulting Datum
// would not be equal to the original value.  For example, a Datum containing
// an integer would be encoded into a JSON number, and then decoded back into a
// Datum using 'double' to represent that number.
//
// Clients wishing to ensure that encoding and then decoding results in a Datum
// equal to the original value, should use only Datum types natively supported
// in JSON (see {'Supported Types'} below).  To verify that encoded JSON fields
// can be decoded back into Datum fields of of equal value, clients can supply
// the 'strictTypes' option (see {'DatumEncoderOptions'}) to 'encode'.  A call
// to 'encode' with 'strictTypes' as 'true' will return a positive value if the
// encoded 'Datum' contained a type not natively supported in JSON.
//
// The order of key/value pairs in objects in textual JSON passed to 'decode'
// is preserved in the decoded 'Datum'.  If multiple entries with the same
// 'key' are present in an object, 'decode' will return the *first* such value.
//
// The order of key/value pairs ('DatumMapEntry') in 'Datum' objects passed to
// 'encode' will be preserved in the resulting 'JSON', and all keys/value pairs
// will be present.  'strictTypes' checking does not alter the behavior for
// duplicate keys in maps.  They are allowed whether 'strictTypes' is 'true' or
// 'false'.
//
///Supported Types
///---------------
// The table below describes the set of types that a 'Datum' may be, whether it
// can be 'encode'd to JSON, and, if so, which JSON type will be 'decode'd if
// the value is read back in.
//
// The 'encode' routines will return a negative (error) status if the input
// 'datum' contains any field that is not 'JSON-able' in this table.
//
// If the 'DatumEncoderOptions' parameter is passed to an 'encode' routine and
// its 'strictTypes' field is 'true', then 'encode' will return a positive
// value if any value is encoded where the 'dataType' and 'decode type' columns
// in this table are different (and therefore the 'strictTypes ok?' column is
// 'no').
//
//..
//  dataType              JSON-able  JSON type   decode type    strictTypes ok?
//  --------              ---------  ---------   -----------    ---------------
//  e_NIL                 yes        null        e_NIL          yes
//  e_INTEGER             yes        number      e_DOUBLE       no
//  e_DOUBLE              yes        number      e_DOUBLE       yes
//  e_STRING              yes        string      e_STRING       yes
//  e_BOOLEAN             yes        bool        e_BOOLEAN      yes
//  e_ERROR               no         N/A         N/A            no
//  e_DATE                yes        string      e_STRING       no
//  e_TIME                yes        string      e_STRING       no<commit_msg>Add multi-key datum map caveats, and quotes around Datum<commit_after>// baljsn_datumutil.h                                                 -*-C++-*-
#ifndef INCLUDED_BALJSN_DATUMUTIL
#define INCLUDED_BALJSN_DATUMUTIL

#include <bsls_ident.h>
BSLS_IDENT("$Id$ $CSID$")

//@PURPOSE: Provide utilities converting between 'bdld::Datum' and JSON data.
//
//@CLASSES:
//  baljsn::DatumUtil: utilities converting between 'bdld::Datum' and JSON data
//
//@DESCRIPTION: This component provides a struct, 'baljsn::DatumUtil', that is
// a namespace for a suite of functions that convert a 'bdld::Datum' into a
// JSON string, and back.
//
///Mapping Data Types between 'Datum' and JSON
///-----------------------------------------
// While most scalar types supported by 'Datum' can be encoded into a JSON
// string, only the subset of types represented natively in JSON -- number
// (represented in C++ as a 'double'), 'string', 'bool', 'null', array, and map
// types -- will be populated in a 'Datum' decoded from a JSON string.  If one
// were to encode a 'Datum' containing a type not natively supported by JSON,
// if that JSON string were decoded back into a 'Datum' object, the resulting
// Datum would not be equal to the original value.  For example, a 'Datum'
// containing an integer would be encoded into a JSON number, and then decoded
// back into a 'Datum' using 'double' to represent that number.
//
// Clients wishing to ensure that encoding and then decoding results in a Datum
// equal to the original value should use only 'Datum' types natively supported
// in JSON (see {'Supported Types'} below), and ensure that duplicate keys are
// not present in the source 'Datum' (duplicate keys in a 'Datum' map are
// typically an error, but the interface does allow them to be created).  To
// verify that encoded JSON fields can be decoded back into 'Datum' fields of
// of equal value, clients can supply the 'strictTypes' option (see
// {'DatumEncoderOptions'}) to 'encode'.  A call to 'encode' with 'strictTypes'
// as 'true' will return a positive value if the encoded 'Datum' contained a
// type not natively supported in JSON.
//
// The order of key/value pairs in objects in textual JSON passed to 'decode'
// is preserved in the decoded 'Datum'.  If multiple entries with the same
// 'key' are present in an object, 'decode' will return the *first* such value.
//
// The order of key/value pairs ('DatumMapEntry') in 'Datum' objects passed to
// 'encode' will be preserved in the resulting 'JSON', and all keys/value pairs
// will be present.  'strictTypes' checking does not alter the behavior for
// duplicate keys in maps.  They are allowed whether 'strictTypes' is 'true' or
// 'false'.  Note that a 'Datum' map contraining duplicate keys is typically an
// error (the result of an incorrectly constructed 'Datum'), but the public
// interface for 'Datum' does not disallow creating such a 'Datum' object.
//
///Supported Types
///---------------
// The table below describes the set of types that a 'Datum' may be, whether it
// can be 'encode'd to JSON, and, if so, which JSON type will be 'decode'd if
// the value is read back in.
//
// The 'encode' routines will return a negative (error) status if the input
// 'datum' contains any field that is not 'JSON-able' in this table.
//
// If the 'DatumEncoderOptions' parameter is passed to an 'encode' routine and
// its 'strictTypes' field is 'true', then 'encode' will return a positive
// value if any value is encoded where the 'dataType' and 'decode type' columns
// in this table are different (and therefore the 'strictTypes ok?' column is
// 'no').
//
//..
//  dataType              JSON-able  JSON type   decode type    strictTypes ok?
//  --------              ---------  ---------   -----------    ---------------
//  e_NIL                 yes        null        e_NIL          yes
//  e_INTEGER             yes        number      e_DOUBLE       no
//  e_DOUBLE              yes        number      e_DOUBLE       yes
//  e_STRING              yes        string      e_STRING       yes
//  e_BOOLEAN             yes        bool        e_BOOLEAN      yes
//  e_ERROR               no         N/A         N/A            no
//  e_DATE                yes        string      e_STRING       no
//  e_TIME                yes        string      e_STRING       no
{'fraction_non_alphanumeric': 0.11537524366471735, 'fraction_numerical': 0.0, 'mean_word_length': 2.2459470146302887, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4024078', 'n_tokens_mistral': 2222, 'n_tokens_neox': 2182, 'n_words': 1069}