baljsn_datumutil.h

Go to the documentation of this file.

/// @file baljsn_datumutil.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// baljsn_datumutil.h                                                 -*-C++-*-
#ifndef INCLUDED_BALJSN_DATUMUTIL
#define INCLUDED_BALJSN_DATUMUTIL
 
#include <bsls_ident.h>
BSLS_IDENT("$Id$ $CSID$")
 
/// @defgroup baljsn_datumutil baljsn_datumutil
/// @brief  Provide utilities converting between `bdld::Datum` and JSON data.
/// @addtogroup bal
/// @{
/// @addtogroup baljsn
/// @{
/// @addtogroup baljsn_datumutil
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#baljsn_datumutil-purpose"> Purpose</a>
/// * <a href="#baljsn_datumutil-classes"> Classes </a>
/// * <a href="#baljsn_datumutil-description"> Description </a>
///   * <a href="#baljsn_datumutil-mapping-data-types-between-datum-and-json"> Mapping Data Types between Datum and JSON </a>
///   * <a href="#baljsn_datumutil-supported-types"> Supported Types </a>
///   * <a href="#baljsn_datumutil-usage"> Usage </a>
///     * <a href="#baljsn_datumutil-example-1-encode-a-json-string"> Example 1: Encode (and decode) Datum to (and from) a JSON string. </a>
///     * <a href="#baljsn_datumutil-example-2-converting-json-to-datum"> Example 2: Converting JSON to Datum </a>
///
/// # Purpose {#baljsn_datumutil-purpose}
/// Provide utilities converting between `bdld::Datum` and JSON data.
///
/// # Classes {#baljsn_datumutil-classes}
///
/// -  baljsn::DatumUtil: utilities converting between `bdld::Datum` and JSON data
///
/// # Description {#baljsn_datumutil-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 {#baljsn_datumutil-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.  Note that
/// `DatumUtil` uses a *more permissive* parser for numerical values than the
/// strict JSON standard specifies.  In particular, it is possible to parse
/// `NaN`, `Inf`, or `Infinity` into the corresponding singular `double` values
/// even though the JSON standard does not permit this, so applications should
/// be ready to handle these kinds of values.  Also note that the `encode`
/// routines do not encode these singular `double` values in these parseable
/// formats.  Singular `double` values will be rendered as strings (e.g., "+inf"
/// or "nan") if the `strictTypes` encoding configuration is `false`, and will
/// result generate an encoding error if `strictTypes` is `true`.
///
/// 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 @ref baljsn_datumutil-supported-types ), 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).
/// Enabling the `strictTypes` option verifies that the types in encoded JSON
/// fields can be decoded back into `Datum` fields of equal value.  So, for
/// example, enabling `strictTypes` will result in `encode` producing a positive
/// return status if one of the encoded types is an `int`, because decoding the
/// resulting JSON will produce a `double`.  The `strictTypes` option does not,
/// however, verify that a Datum map contains unique keys.  For `double` fields,
/// `strictTypes` will result in `encode` returning a positive value if a
/// singular `double` value is encountered, such as a NaN or Infinity.
///
/// 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 (including duplicate keys).  Duplicate keys will be rendered
/// in an encoded JSON, even if `strictTypes` checking is enabled.  Note that a
/// Datum map containing duplicate keys is typically an error (the result of a
/// incorrectly constructed Datum), but the public interface for Datum does not
/// disallow creating such a `Datum` object.
///
/// ## Supported Types {#baljsn_datumutil-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`).
///
/// @code
/// 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 [1]
/// 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
/// e_DATETIME            yes        string      e_STRING       no
/// e_DATETIME_INTERVAL   yes        string      e_STRING       no
/// e_INTEGER64           yes        number      e_DOUBLE       no
/// e_USERDEFINED         no         N/A         N/A            no
/// e_BINARY              no         N/A         N/A            no
/// e_DECIMAL64 [2]       yes        number      e_STRING       no
///
/// dataType              JSON-able  JSON type   decode type    strictTypes ok?
/// --------              ---------  ---------   -----------    ---------------
/// e_ARRAY               yes        array       e_ARRAY        yes
/// e_MAP                 yes        map         e_MAP          yes
/// e_INT_MAP             no         N/A         N/A            no
///
/// [1] Singular double values (e.g., inf and nan) are not permitted if
///    strictTypes is 'true', and will be rendered as strings if 'strictTypes'
///    is 'false'.
/// [2] 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 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).
/// @endcode
/// * *dataType* - the `Datum` type value returned by the `type()`
/// * *JSON-able* - whether the type can be `encode`d by this component.
/// * *JSON type* - the JSON type used to `encode` this value, if supported.
/// * *decode type* - the `Datum` type this `encode`d value would be
///    `decode`d into.
/// * *strictTypes ok?* - `encode` will return 0 on success even if
///   `options->strictTypes()` is `true`.
///
/// ## Usage {#baljsn_datumutil-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: Encode (and decode) Datum to (and from) a JSON string. {#baljsn_datumutil-example-1-encode-a-json-string}
///
///
/// The following example illustrates encoding a `Datum` as a JSON string and
/// then decoding that JSON string back into a `Datum` object.
///
/// First, we create our `Datum` object, using the `bdld::DatumMaker` utility:
/// @code
/// bsls::AlignedBuffer<8 * 1024>      buffer;
/// bdlma::BufferedSequentialAllocator bsa(buffer.buffer(), sizeof(buffer));
/// bdld::DatumMaker                   m(&bsa);
///
/// bdld::Datum books = m.a(m.m("Author", "Ann Leckie",
///                             "Title", "Ancillary Justice"),
///                         m.m("Author", "John Scalzi",
///                             "Title", "Redshirts"));
/// @endcode
/// Then, we convert the `books` `Datum` to formatted JSON:
/// @code
/// baljsn::DatumEncoderOptions bookOptions;
/// bookOptions.setEncodingStyle(baljsn::EncodingStyle::e_PRETTY);
/// bookOptions.setSpacesPerLevel(4);
/// bsl::string booksJSON(&bsa);
///
/// int rc = baljsn::DatumUtil::encode(&booksJSON, books, bookOptions);
/// if (0 != rc) {
///     // handle error
/// }
/// @endcode
/// Next, we compare the result to the JSON we expect:
/// @code
/// const bsl::string EXPECTED_BOOKS_JSON = "[\n"
///     "    {\n"
///     "        \"Author\": \"Ann Leckie\",\n"
///     "        \"Title\": \"Ancillary Justice\"\n"
///     "    },\n"
///     "    {\n"
///     "        \"Author\": \"John Scalzi\",\n"
///     "        \"Title\": \"Redshirts\"\n"
///     "    }\n"
///     "]";
///
/// assert(EXPECTED_BOOKS_JSON == booksJSON);
/// @endcode
/// Finally, we can decode the `booksJSON` and make sure we got the same value
/// back:
/// @code
/// bdld::ManagedDatum decodedBooks;
/// rc = baljsn::DatumUtil::decode(&decodedBooks, booksJSON);
/// if (0 != rc) {
///     // handle error
/// }
/// assert(*decodedBooks == books);
/// @endcode
/// ### Example 2: Converting JSON to Datum {#baljsn_datumutil-example-2-converting-json-to-datum}
///
///
/// The following example illustrates decoding a string into a `Datum` object.
///
/// First, we create the JSON source, in both plain and formatted forms:
/// @code
/// const bsl::string plainFamilyJSON = "["
///                              "{\"firstName\":\"Homer\","
///                              "\"age\":34}"
///                              ",{\"firstName\":\"Marge\","
///                              "\"age\":34}"
///                              ",{\"firstName\":\"Bart\","
///                              "\"age\":10}"
///                              ",{\"firstName\":\"Lisa\","
///                              "\"age\":8}"
///                              ",{\"firstName\":\"Maggie\","
///                              "\"age\":1}"
///                              "]";
///
/// // Note that whitespace formatting is unimportant as long as the result is
/// // legal JSON.  This will generate the same 'Datum' as the single-line form
/// // above.
/// const bsl::string formattedFamilyJSON =
///                                     "[\n"
///                                     "    {\n"
///                                     "        \"firstName\": \"Homer\",\n"
///                                     "        \"age\": 34\n"
///                                     "    },\n"
///                                     "    {\n"
///                                     "        \"firstName\": \"Marge\",\n"
///                                     "        \"age\": 34\n"
///                                     "    },\n"
///                                     "    {\n"
///                                     "        \"firstName\": \"Bart\",\n"
///                                     "        \"age\": 10\n"
///                                     "    },\n"
///                                     "    {\n"
///                                     "        \"firstName\": \"Lisa\",\n"
///                                     "        \"age\": 8\n"
///                                     "    },\n"
///                                     "    {\n"
///                                     "        \"firstName\": \"Maggie\",\n"
///                                     "        \"age\": 1\n"
///                                     "    }\n"
///                                     "]";
/// @endcode
/// Then, we convert the single-line `string` to a `Datum`:
/// @code
/// bdld::ManagedDatum family;
/// rc = baljsn::DatumUtil::decode(&family, plainFamilyJSON);
/// if (0 != rc) {
///     // handle error
/// }
/// @endcode
/// Next, we convert the formatted `string` to another `Datum` and make sure
/// that the results match:
/// @code
/// bdld::ManagedDatum family2;
/// rc = baljsn::DatumUtil::decode(&family2, formattedFamilyJSON);
/// if (0 != rc) {
///     // handle error
/// }
/// assert(family == family2);
/// @endcode
/// Finally, we make sure that the structure of the resulting datum is as we
/// expect.
/// @code
/// assert(family->isArray());
/// assert(5 == family->theArray().length());
///
/// const bdld::DatumArrayRef &familyArray = family->theArray();
/// assert(5 == familyArray.length());
///
/// const bdld::Datum &lisa = familyArray[3];
///
/// assert(lisa.isMap());
/// assert(2         == lisa.theMap().size());
/// assert("Lisa"    == lisa.theMap().find("firstName")->theString());
/// assert(8         == lisa.theMap().find("age")->theDouble());
/// @endcode
/// Notice that the `type` of "age" is `double`, since "age" was encoded as a
/// number, and `double` is the supported representation of a JSON number (see
/// @ref baljsn_datumutil-supported-types ).
/// @}
/** @} */
/** @} */
 
/** @addtogroup bal
 * @{
 */
/** @addtogroup baljsn
 * @{
 */
/** @addtogroup baljsn_datumutil
 * @{
 */
 
#include <balscm_version.h>
 
#include <baljsn_datumdecoderoptions.h>
#include <baljsn_datumencoderoptions.h>
 
#include <bdld_datum.h>
#include <bdld_manageddatum.h>
#include <bdlsb_fixedmeminstreambuf.h>
 
#include <bsls_libraryfeatures.h>
 
#include <bsl_iosfwd.h>
#include <bsl_streambuf.h>
#include <bsl_string.h>
#include <bsl_string_view.h>
 
#include <string>
 
 
namespace baljsn {
 
class SimpleFormatter;
 
                              // ================
                              // struct DatumUtil
                              // ================
 
/// This `struct` provides a namespace for a suite of functions that convert
/// between a JSON formated string and a `bdld::Datum`.
///
/// See @ref baljsn_datumutil 
struct DatumUtil {
 
    // CLASS METHODS
 
    /// Decode the specified `json` into the specified `result`.  If the
    /// optionally specified `errorStream` is non-null, a description of any
    /// errors that occur during parsing will be output to this stream.  If
    /// the optionally specified `options` argument is not present, treat it
    /// as a default-constructed `DatumDecoderOptions`.  Return 0 on
    /// success, and a negative value if `json` could not be decoded (either
    /// because it is ill-formed, or if a constraint imposed by `option` is
    /// violated).  An error status will be returned if `json` contains
    /// arrays or objects that are nested beyond a depth configured by
    /// `options.maxNestedDepth()`.  The mapping of types in JSON to the
    /// types supported by `Datum` is described in @ref baljsn_datumutil-supported-types .
    static int decode(bdld::ManagedDatum         *result,
                      const bsl::string_view&     json);
    static int decode(bdld::ManagedDatum         *result,
                      const bsl::string_view&     json,
                      const DatumDecoderOptions&  options);
    static int decode(bdld::ManagedDatum         *result,
                      bsl::ostream               *errorStream,
                      const bsl::string_view&     json);
    static int decode(bdld::ManagedDatum         *result,
                      bsl::ostream               *errorStream,
                      const bsl::string_view&     json,
                      const DatumDecoderOptions&  options);
 
    /// Decode the JSON string provided by the specified `jsonBuffer` into
    /// the specified `result`.  If the optionally specified `errorStream`
    /// is non-null, a description of any errors that occur during parsing
    /// will be output to this stream.  If the optionally specified
    /// `options` argument is not present, treat it as a default-constructed
    /// `DatumDecoderOptions`.  Return 0 on success, and a negative value if
    /// `json` could not be decoded (either because it is ill-formed, or if
    /// a constraint imposed by `option` is violated).  An error status will
    /// be returned if `json` contains arrays or objects that are nested
    /// beyond a depth configured by `options.maxNestedDepth()`.  The
    /// mapping of types in JSON to the types supported by `Datum` is
    /// described in @ref baljsn_datumutil-supported-types .
    static int decode(bdld::ManagedDatum         *result,
                      bsl::streambuf             *jsonBuffer);
    static int decode(bdld::ManagedDatum         *result,
                      bsl::streambuf             *jsonBuffer,
                      const DatumDecoderOptions&  options);
    static int decode(bdld::ManagedDatum         *result,
                      bsl::ostream               *errorStream,
                      bsl::streambuf             *jsonBuffer);
    static int decode(bdld::ManagedDatum         *result,
                      bsl::ostream               *errorStream,
                      bsl::streambuf             *jsonBuffer,
                      const DatumDecoderOptions&  options);
 
    /// Encode the specified `datum` as a JSON string, and load the
    /// specified `result` with the encoded JSON string.  Return 0 on
    /// success, and a negative value if `datum` could not be encoded (with
    /// no effect on `result`).  If the optionally specified `options`
    /// argument is not present, treat it as a default-constructed
    /// `DatumEncoderOptions`.  If `options.strictTypes` is `true` and a
    /// type that is not supported by JSON, or a singular double value
    /// (e.g., NaN or infinity) is being encoded (see @ref baljsn_datumutil-supported-types )
    /// return a positive value, but also populate `result` with an encoded
    /// JSON string (i.e., the value of `result` is the same regardless of
    /// the `strictTypes` option, but if `strictTypes` is `true` a non-zero
    /// positive status will be returned).  The mapping of types supported
    /// by `Datum` to JSON types is described in @ref baljsn_datumutil-supported-types .
    static int encode(bsl::string         *result,
                      const bdld::Datum&   datum);
    static int encode(std::string         *result,
                      const bdld::Datum&   datum);
#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
    static int encode(std::pmr::string   *result,
                      const bdld::Datum&  datum);
#endif
    static int encode(bsl::string                *result,
                      const bdld::Datum&          datum,
                      const DatumEncoderOptions&  options);
    static int encode(std::string                *result,
                      const bdld::Datum&          datum,
                      const DatumEncoderOptions&  options);
#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
    static int encode(std::pmr::string           *result,
                      const bdld::Datum&          datum,
                      const DatumEncoderOptions&  options);
#endif
 
    /// Encode the specified `datum` as a JSON string, and write it into the
    /// specified `stream`.  Return 0 on success, and a negative value if
    /// `datum` could not be encoded (which may leave a partial JSON
    /// sequence on the `stream`).  If the optionally specified `options`
    /// argument is not present, treat it as a default-constructed
    /// `DatumEncoderOptions`.  If `options.strictTypes` is `true` and a
    /// type that is not supported by JSON, or a singular double value
    /// (e.g., NaN or infinity) is being encoded (see @ref baljsn_datumutil-supported-types )
    /// return a positive value, but also populate `result` with an encoded
    /// JSON string (i.e., the value of `result` is the same regardless of
    /// the `strictTypes` option, but if `strictTypes` is `true` a non-zero
    /// positive status will be returned).  The mapping of types supported
    /// by `Datum` to JSON types is described in @ref baljsn_datumutil-supported-types .
    static int encode(bsl::ostream&              stream,
                      const bdld::Datum&         datum);
    static int encode(bsl::ostream&              stream,
                      const bdld::Datum&         datum,
                      const DatumEncoderOptions& options);
};
 
// ============================================================================
//                            INLINE DEFINITIONS
// ============================================================================
 
// CLASS METHODS
 
inline
int DatumUtil::decode(bdld::ManagedDatum         *result,
                      const bsl::string_view&     json,
                      const DatumDecoderOptions&  options)
{
    bdlsb::FixedMemInStreamBuf buffer(json.data(), json.length());
    return decode(result, 0, &buffer, options);
}
 
inline
int DatumUtil::decode(bdld::ManagedDatum       *result,
                      const bsl::string_view&   json)
{
    return decode(result, json, DatumDecoderOptions());
}
 
inline
int DatumUtil::decode(bdld::ManagedDatum         *result,
                      bsl::ostream               *errorStream,
                      const bsl::string_view&     json,
                      const DatumDecoderOptions&  options)
{
    bdlsb::FixedMemInStreamBuf buffer(json.data(), json.length());
    return decode(result, errorStream, &buffer, options);
}
 
inline
int DatumUtil::decode(bdld::ManagedDatum         *result,
                      bsl::ostream               *errorStream,
                      const bsl::string_view&     json)
{
    return decode(result, errorStream, json, DatumDecoderOptions());
}
 
inline
int DatumUtil::decode(bdld::ManagedDatum         *result,
                      bsl::streambuf             *jsonBuffer,
                      const DatumDecoderOptions&  options)
{
    return decode(result, 0, jsonBuffer, options);
}
 
inline
int DatumUtil::decode(bdld::ManagedDatum         *result,
                      bsl::streambuf             *jsonBuffer)
{
    return decode(result, 0, jsonBuffer, DatumDecoderOptions());
}
 
inline
int DatumUtil::decode(bdld::ManagedDatum         *result,
                      bsl::ostream               *errorStream,
                      bsl::streambuf             *jsonBuffer)
{
    return decode(result, errorStream, jsonBuffer, DatumDecoderOptions());
}
 
inline
int DatumUtil::encode(bsl::string *result, const bdld::Datum& datum)
{
    return encode(result, datum, DatumEncoderOptions());
}
 
inline
int DatumUtil::encode(std::string *result, const bdld::Datum& datum)
{
    return encode(result, datum, DatumEncoderOptions());
}
 
#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
inline
int DatumUtil::encode(std::pmr::string   *result,
                      const bdld::Datum&  datum)
{
    return encode(result, datum, DatumEncoderOptions());
}
#endif
 
inline
int DatumUtil::encode(bsl::ostream& stream, const bdld::Datum& datum)
{
    return encode(stream, datum, DatumEncoderOptions());
}
 
 
}  // close package namespace
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2020 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------
 
/** @} */
/** @} */
/** @} */