json.h

/***
 * Copyright (C) Microsoft. All rights reserved.
 * Licensed under the MIT license. See LICENSE.txt file in the project root for full license information.
 *
 * =+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+
 *
 * HTTP Library: JSON parser and writer
 *
 * For the latest on this and related APIs, please see: https://github.com/Microsoft/cpprestsdk
 *
 * =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 ****/
#pragma once

#ifndef CASA_JSON_H
#define CASA_JSON_H

#include "cpprest/asyncrt_utils.h"
#include "cpprest/details/basic_types.h"
#include <cstdint>
#include <memory>
#include <sstream>
#include <string>
#include <unordered_map>
#include <vector>

namespace web
{
/// Library for parsing and serializing JSON values to and from C++ types.
namespace json
{
// Various forward declarations.
namespace details
{
class _Value;
class _Number;
class _Null;
class _Boolean;
class _String;
class _Object;
class _Array;
template<typename CharType>
class JSON_Parser;
} // namespace details

namespace details
{
extern bool g_keep_json_object_unsorted;
}

/// <summary>
/// Preserve the order of the name/value pairs when parsing a JSON object.
/// The default is false, which can yield better performance.
/// </summary>
/// <param name="keep_order"><c>true</c> if ordering should be preserved when parsing, <c>false</c> otherwise.</param>
/// <remarks>Note this is a global setting and affects all JSON parsing done.</remarks>
void _ASYNCRTIMP __cdecl keep_object_element_order(bool keep_order);

#ifdef _WIN32
#ifdef _DEBUG
#define ENABLE_JSON_VALUE_VISUALIZER
#endif
#endif

class number;
class array;
class object;

/// <summary>
/// A JSON value represented as a C++ class.
/// </summary>
class value
{
public:
    /// <summary>
    /// This enumeration represents the various kinds of JSON values.
    /// </summary>
    enum value_type
    {
        /// Number value
        Number,
        /// Boolean value
        Boolean,
        /// String value
        String,
        /// Object value
        Object,
        /// Array value
        Array,
        /// Null value
        Null
    };

    /// <summary>
    /// Constructor creating a null value
    /// </summary>
    _ASYNCRTIMP value();

    /// <summary>
    /// Constructor creating a JSON number value
    /// </summary>
    /// <param name="value">The C++ value to create a JSON value from</param>
    _ASYNCRTIMP value(int32_t value);

    /// <summary>
    /// Constructor creating a JSON number value
    /// </summary>
    /// <param name="value">The C++ value to create a JSON value from</param>
    _ASYNCRTIMP value(uint32_t value);

    /// <summary>
    /// Constructor creating a JSON number value
    /// </summary>
    /// <param name="value">The C++ value to create a JSON value from</param>
    _ASYNCRTIMP value(int64_t value);

    /// <summary>
    /// Constructor creating a JSON number value
    /// </summary>
    /// <param name="value">The C++ value to create a JSON value from</param>
    _ASYNCRTIMP value(uint64_t value);

    /// <summary>
    /// Constructor creating a JSON number value
    /// </summary>
    /// <param name="value">The C++ value to create a JSON value from</param>
    _ASYNCRTIMP value(double value);

    /// <summary>
    /// Constructor creating a JSON Boolean value
    /// </summary>
    /// <param name="value">The C++ value to create a JSON value from</param>
    _ASYNCRTIMP explicit value(bool value);

    /// <summary>
    /// Constructor creating a JSON string value
    /// </summary>
    /// <param name="value">The C++ value to create a JSON value from, a C++ STL string of the platform-native character
    /// width</param> <remarks> This constructor has O(n) performance because it tries to determine if specified string
    /// has characters that should be properly escaped in JSON. <remarks>
    _ASYNCRTIMP explicit value(utility::string_t value);

    /// <summary>
    /// Constructor creating a JSON string value specifying if the string contains characters to escape
    /// </summary>
    /// <param name="value">The C++ value to create a JSON value from, a C++ STL string of the platform-native character
    /// width</param> <param name="has_escape_chars">Whether <paramref name="value" /> contains characters that should
    /// be escaped in JSON value</param> <remarks> This constructor has O(1) performance.
    /// </remarks>
    _ASYNCRTIMP explicit value(utility::string_t value, bool has_escape_chars);

    /// <summary>
    /// Constructor creating a JSON string value
    /// </summary>
    /// <param name="value">The C++ value to create a JSON value from, a C++ STL string of the platform-native character
    /// width</param> <remarks> <para> This constructor has O(n) performance because it tries to determine if specified
    /// string has characters that should be properly escaped in JSON.
    /// </para>
    /// <para>
    /// This constructor exists in order to avoid string literals matching another constructor,
    /// as is very likely. For example, conversion to bool does not require a user-defined conversion,
    /// and will therefore match first, which means that the JSON value turns up as a boolean.
    /// </para>
    /// </remarks>
    _ASYNCRTIMP explicit value(const utility::char_t* value);

    /// <summary>
    /// Constructor creating a JSON string value
    /// </summary>
    /// <param name="value">The C++ value to create a JSON value from, a C++ STL string of the platform-native character
    /// width</param> <param name="has_escape_chars">Whether <paramref name="value" /> contains characters <remarks>
    /// <para>
    /// This overload has O(1) performance.
    /// </para>
    /// <para>
    /// This constructor exists in order to avoid string literals matching another constructor,
    /// as is very likely. For example, conversion to bool does not require a user-defined conversion,
    /// and will therefore match first, which means that the JSON value turns up as a boolean.
    /// </para>
    /// </remarks>
    _ASYNCRTIMP explicit value(const utility::char_t* value, bool has_escape_chars);

    /// <summary>
    /// Copy constructor
    /// </summary>
    _ASYNCRTIMP value(const value&);

    /// <summary>
    /// Move constructor
    /// </summary>
    _ASYNCRTIMP value(value&&) CPPREST_NOEXCEPT;

    /// <summary>
    /// Assignment operator.
    /// </summary>
    /// <returns>The JSON value object that contains the result of the assignment.</returns>
    _ASYNCRTIMP value& operator=(const value&);

    /// <summary>
    /// Move assignment operator.
    /// </summary>
    /// <returns>The JSON value object that contains the result of the assignment.</returns>
    _ASYNCRTIMP value& operator=(value&&) CPPREST_NOEXCEPT;

    // Static factories

    /// <summary>
    /// Creates a null value
    /// </summary>
    /// <returns>A JSON null value</returns>
    static _ASYNCRTIMP value __cdecl null();

    /// <summary>
    /// Creates a number value
    /// </summary>
    /// <param name="value">The C++ value to create a JSON value from</param>
    /// <returns>A JSON number value</returns>
    static _ASYNCRTIMP value __cdecl number(double value);

    /// <summary>
    /// Creates a number value
    /// </summary>
    /// <param name="value">The C++ value to create a JSON value from</param>
    /// <returns>A JSON number value</returns>
    static _ASYNCRTIMP value __cdecl number(int32_t value);

    /// <summary>
    /// Creates a number value
    /// </summary>
    /// <param name="value">The C++ value to create a JSON value from</param>
    /// <returns>A JSON number value</returns>
    static _ASYNCRTIMP value __cdecl number(uint32_t value);

    /// <summary>
    /// Creates a number value
    /// </summary>
    /// <param name="value">The C++ value to create a JSON value from</param>
    /// <returns>A JSON number value</returns>
    static _ASYNCRTIMP value __cdecl number(int64_t value);

    /// <summary>
    /// Creates a number value
    /// </summary>
    /// <param name="value">The C++ value to create a JSON value from</param>
    /// <returns>A JSON number value</returns>
    static _ASYNCRTIMP value __cdecl number(uint64_t value);

    /// <summary>
    /// Creates a Boolean value
    /// </summary>
    /// <param name="value">The C++ value to create a JSON value from</param>
    /// <returns>A JSON Boolean value</returns>
    static _ASYNCRTIMP value __cdecl boolean(bool value);

    /// <summary>
    /// Creates a string value
    /// </summary>
    /// <param name="value">The C++ value to create a JSON value from</param>
    /// <returns>A JSON string value</returns>
    /// <remarks>
    /// This overload has O(n) performance because it tries to determine if
    /// specified string has characters that should be properly escaped in JSON.
    /// </remarks>
    static _ASYNCRTIMP value __cdecl string(utility::string_t value);

    /// <summary>
    /// Creates a string value specifying if the string contains characters to escape
    /// </summary>
    /// <param name="value">The C++ value to create a JSON value from</param>
    /// <param name="has_escape_chars">Whether <paramref name="value" /> contains characters
    /// that should be escaped in JSON value</param>
    /// <returns>A JSON string value</returns>
    /// <remarks>
    /// This overload has O(1) performance.
    /// </remarks>
    static _ASYNCRTIMP value __cdecl string(utility::string_t value, bool has_escape_chars);

#ifdef _WIN32
private:
    // Only used internally by JSON parser.
    static _ASYNCRTIMP value __cdecl string(const std::string& value);

public:
#endif

    /// <summary>
    /// Creates an object value
    /// </summary>
    /// <param name="keep_order">Whether to preserve the original order of the fields</param>
    /// <returns>An empty JSON object value</returns>
    static _ASYNCRTIMP json::value __cdecl object(bool keep_order = false);

    /// <summary>
    /// Creates an object value from a collection of field/values
    /// </summary>
    /// <param name="fields">Field names associated with JSON values</param>
    /// <param name="keep_order">Whether to preserve the original order of the fields</param>
    /// <returns>A non-empty JSON object value</returns>
    static _ASYNCRTIMP json::value __cdecl object(std::vector<std::pair<::utility::string_t, value>> fields,
                                                  bool keep_order = false);

    /// <summary>
    /// Creates an empty JSON array
    /// </summary>
    /// <returns>An empty JSON array value</returns>
    static _ASYNCRTIMP json::value __cdecl array();

    /// <summary>
    /// Creates a JSON array
    /// </summary>
    /// <param name="size">The initial number of elements of the JSON value</param>
    /// <returns>A JSON array value</returns>
    static _ASYNCRTIMP json::value __cdecl array(size_t size);

    /// <summary>
    /// Creates a JSON array
    /// </summary>
    /// <param name="elements">A vector of JSON values</param>
    /// <returns>A JSON array value</returns>
    static _ASYNCRTIMP json::value __cdecl array(std::vector<value> elements);

    /// <summary>
    /// Accesses the type of JSON value the current value instance is
    /// </summary>
    /// <returns>The value's type</returns>
    _ASYNCRTIMP json::value::value_type type() const;

    /// <summary>
    /// Is the current value a null value?
    /// </summary>
    /// <returns><c>true</c> if the value is a null value, <c>false</c> otherwise</returns>
    bool is_null() const { return type() == Null; };

    /// <summary>
    /// Is the current value a number value?
    /// </summary>
    /// <returns><c>true</c> if the value is a number value, <c>false</c> otherwise</returns>
    bool is_number() const { return type() == Number; }

    /// <summary>
    /// Is the current value represented as an integer number value?
    /// </summary>
    /// <remarks>
    /// Note that if a json value is a number but represented as a double it can still
    /// be retrieved as a integer using as_integer(), however the value will be truncated.
    /// </remarks>
    /// <returns><c>true</c> if the value is an integer value, <c>false</c> otherwise.</returns>
    _ASYNCRTIMP bool is_integer() const;

    /// <summary>
    /// Is the current value represented as an double number value?
    /// </summary>
    /// <remarks>
    /// Note that if a json value is a number but represented as a int it can still
    /// be retrieved as a double using as_double().
    /// </remarks>
    /// <returns><c>true</c> if the value is an double value, <c>false</c> otherwise.</returns>
    _ASYNCRTIMP bool is_double() const;

    /// <summary>
    /// Is the current value a Boolean value?
    /// </summary>
    /// <returns><c>true</c> if the value is a Boolean value, <c>false</c> otherwise</returns>
    bool is_boolean() const { return type() == Boolean; }

    /// <summary>
    /// Is the current value a string value?
    /// </summary>
    /// <returns><c>true</c> if the value is a string value, <c>false</c> otherwise</returns>
    bool is_string() const { return type() == String; }

    /// <summary>
    /// Is the current value an array?
    /// </summary>
    /// <returns><c>true</c> if the value is an array, <c>false</c> otherwise</returns>
    bool is_array() const { return type() == Array; }

    /// <summary>
    /// Is the current value an object?
    /// </summary>
    /// <returns><c>true</c> if the value is an object, <c>false</c> otherwise</returns>
    bool is_object() const { return type() == Object; }

    /// <summary>
    /// Gets the number of children of the value.
    /// </summary>
    /// <returns>The number of children. 0 for all non-composites.</returns>
    size_t size() const;

    /// <summary>
    /// Parses a string and construct a JSON value.
    /// </summary>
    /// <param name="value">The C++ value to create a JSON value from, a C++ STL double-byte string</param>
    _ASYNCRTIMP static value __cdecl parse(const utility::string_t& value);

    /// <summary>
    /// Attempts to parse a string and construct a JSON value.
    /// </summary>
    /// <param name="value">The C++ value to create a JSON value from, a C++ STL double-byte string</param>
    /// <param name="errorCode">If parsing fails, the error code is greater than 0</param>
    /// <returns>The parsed object. Returns web::json::value::null if failed</returns>
    _ASYNCRTIMP static value __cdecl parse(const utility::string_t& value, std::error_code& errorCode);

    /// <summary>
    /// Serializes the current JSON value to a C++ string.
    /// </summary>
    /// <returns>A string representation of the value</returns>
    _ASYNCRTIMP utility::string_t serialize() const;

    /// <summary>
    /// Serializes the current JSON value to a C++ string.
    /// </summary>
    /// <returns>A string representation of the value</returns>
    CASABLANCA_DEPRECATED("This API is deprecated and has been renamed to avoid confusion with as_string(), use "
                          "::web::json::value::serialize() instead.")
    _ASYNCRTIMP utility::string_t to_string() const;

    /// <summary>
    /// Parses a JSON value from the contents of an input stream using the native platform character width.
    /// </summary>
    /// <param name="input">The stream to read the JSON value from</param>
    /// <returns>The JSON value object created from the input stream.</returns>
    _ASYNCRTIMP static value __cdecl parse(utility::istream_t& input);

    /// <summary>
    /// Parses a JSON value from the contents of an input stream using the native platform character width.
    /// </summary>
    /// <param name="input">The stream to read the JSON value from</param>
    /// <param name="errorCode">If parsing fails, the error code is greater than 0</param>
    /// <returns>The parsed object. Returns web::json::value::null if failed</returns>
    _ASYNCRTIMP static value __cdecl parse(utility::istream_t& input, std::error_code& errorCode);

    /// <summary>
    /// Writes the current JSON value to a stream with the native platform character width.
    /// </summary>
    /// <param name="stream">The stream that the JSON string representation should be written to.</param>
    _ASYNCRTIMP void serialize(utility::ostream_t& stream) const;

#ifdef _WIN32
    /// <summary>
    /// Parses a JSON value from the contents of a single-byte (UTF8) stream.
    /// </summary>
    /// <param name="stream">The stream to read the JSON value from</param>
    _ASYNCRTIMP static value __cdecl parse(std::istream& stream);

    /// <summary>
    /// Parses a JSON value from the contents of a single-byte (UTF8) stream.
    /// </summary>
    /// <param name="stream">The stream to read the JSON value from</param>
    /// <param name="errorCode">If parsing fails, the error code is greater than 0</param>
    /// <returns>The parsed object. Returns web::json::value::null if failed</returns>
    _ASYNCRTIMP static value __cdecl parse(std::istream& stream, std::error_code& error);

    /// <summary>
    /// Serializes the content of the value into a single-byte (UTF8) stream.
    /// </summary>
    /// <param name="stream">The stream that the JSON string representation should be written to.</param>
    _ASYNCRTIMP void serialize(std::ostream& stream) const;
#endif

    /// <summary>
    /// Converts the JSON value to a C++ double, if and only if it is a number value.
    /// Throws <see cref="json_exception"/>  if the value is not a number
    /// </summary>
    /// <returns>A double representation of the value</returns>
    _ASYNCRTIMP double as_double() const;

    /// <summary>
    /// Converts the JSON value to a C++ integer, if and only if it is a number value.
    /// Throws <see cref="json_exception"/> if the value is not a number
    /// </summary>
    /// <returns>An integer representation of the value</returns>
    _ASYNCRTIMP int as_integer() const;

    /// <summary>
    /// Converts the JSON value to a number class, if and only if it is a number value.
    /// Throws <see cref="json_exception"/>  if the value is not a number
    /// </summary>
    /// <returns>An instance of number class</returns>
    _ASYNCRTIMP const json::number& as_number() const;

    /// <summary>
    /// Converts the JSON value to a C++ bool, if and only if it is a Boolean value.
    /// </summary>
    /// <returns>A C++ bool representation of the value</returns>
    _ASYNCRTIMP bool as_bool() const;

    /// <summary>
    /// Converts the JSON value to a json array, if and only if it is an array value.
    /// </summary>
    /// <remarks>The returned <c>json::array</c> should have the same or shorter lifetime as <c>this</c></remarks>
    /// <returns>An array representation of the value</returns>
    _ASYNCRTIMP json::array& as_array();

    /// <summary>
    /// Converts the JSON value to a json array, if and only if it is an array value.
    /// </summary>
    /// <remarks>The returned <c>json::array</c> should have the same or shorter lifetime as <c>this</c></remarks>
    /// <returns>An array representation of the value</returns>
    _ASYNCRTIMP const json::array& as_array() const;

    /// <summary>
    /// Converts the JSON value to a json object, if and only if it is an object value.
    /// </summary>
    /// <returns>An object representation of the value</returns>
    _ASYNCRTIMP json::object& as_object();

    /// <summary>
    /// Converts the JSON value to a json object, if and only if it is an object value.
    /// </summary>
    /// <returns>An object representation of the value</returns>
    _ASYNCRTIMP const json::object& as_object() const;

    /// <summary>
    /// Converts the JSON value to a C++ STL string, if and only if it is a string value.
    /// </summary>
    /// <returns>A C++ STL string representation of the value</returns>
    _ASYNCRTIMP const utility::string_t& as_string() const;

    /// <summary>
    /// Compares two JSON values for equality.
    /// </summary>
    /// <param name="other">The JSON value to compare with.</param>
    /// <returns>True if the values are equal.</returns>
    _ASYNCRTIMP bool operator==(const value& other) const;

    /// <summary>
    /// Compares two JSON values for inequality.
    /// </summary>
    /// <param name="other">The JSON value to compare with.</param>
    /// <returns>True if the values are unequal.</returns>
    bool operator!=(const value& other) const { return !((*this) == other); }

    /// <summary>
    /// Tests for the presence of a field.
    /// </summary>
    /// <param name="key">The name of the field</param>
    /// <returns>True if the field exists, false otherwise.</returns>
    bool has_field(const utility::string_t& key) const;

    /// <summary>
    /// Tests for the presence of a number field
    /// </summary>
    /// <param name="key">The name of the field</param>
    /// <returns>True if the field exists, false otherwise.</returns>
    _ASYNCRTIMP bool has_number_field(const utility::string_t& key) const;

    /// <summary>
    /// Tests for the presence of an integer field
    /// </summary>
    /// <param name="key">The name of the field</param>
    /// <returns>True if the field exists, false otherwise.</returns>
    _ASYNCRTIMP bool has_integer_field(const utility::string_t& key) const;

    /// <summary>
    /// Tests for the presence of a double field
    /// </summary>
    /// <param name="key">The name of the field</param>
    /// <returns>True if the field exists, false otherwise.</returns>
    _ASYNCRTIMP bool has_double_field(const utility::string_t& key) const;

    /// <summary>
    /// Tests for the presence of a boolean field
    /// </summary>
    /// <param name="key">The name of the field</param>
    /// <returns>True if the field exists, false otherwise.</returns>
    _ASYNCRTIMP bool has_boolean_field(const utility::string_t& key) const;

    /// <summary>
    /// Tests for the presence of a string field
    /// </summary>
    /// <param name="key">The name of the field</param>
    /// <returns>True if the field exists, false otherwise.</returns>
    _ASYNCRTIMP bool has_string_field(const utility::string_t& key) const;

    /// <summary>
    /// Tests for the presence of an array field
    /// </summary>
    /// <param name="key">The name of the field</param>
    /// <returns>True if the field exists, false otherwise.</returns>
    _ASYNCRTIMP bool has_array_field(const utility::string_t& key) const;

    /// <summary>
    /// Tests for the presence of an object field
    /// </summary>
    /// <param name="key">The name of the field</param>
    /// <returns>True if the field exists, false otherwise.</returns>
    _ASYNCRTIMP bool has_object_field(const utility::string_t& key) const;

    /// <summary>
    /// Accesses a field of a JSON object.
    /// </summary>
    /// <param name="key">The name of the field</param>
    /// <returns>The value kept in the field; null if the field does not exist</returns>
    CASABLANCA_DEPRECATED(
        "This API is deprecated and will be removed in a future release, use json::value::at() instead.")
    value get(const utility::string_t& key) const;

    /// <summary>
    /// Erases an element of a JSON array. Throws if index is out of bounds.
    /// </summary>
    /// <param name="index">The index of the element to erase in the JSON array.</param>
    _ASYNCRTIMP void erase(size_t index);

    /// <summary>
    /// Erases an element of a JSON object. Throws if the key doesn't exist.
    /// </summary>
    /// <param name="key">The key of the element to erase in the JSON object.</param>
    _ASYNCRTIMP void erase(const utility::string_t& key);

    /// <summary>
    /// Accesses an element of a JSON array. Throws when index out of bounds.
    /// </summary>
    /// <param name="index">The index of an element in the JSON array.</param>
    /// <returns>A reference to the value.</returns>
    _ASYNCRTIMP json::value& at(size_t index);

    /// <summary>
    /// Accesses an element of a JSON array. Throws when index out of bounds.
    /// </summary>
    /// <param name="index">The index of an element in the JSON array.</param>
    /// <returns>A reference to the value.</returns>
    _ASYNCRTIMP const json::value& at(size_t index) const;

    /// <summary>
    /// Accesses an element of a JSON object. If the key doesn't exist, this method throws.
    /// </summary>
    /// <param name="key">The key of an element in the JSON object.</param>
    /// <returns>If the key exists, a reference to the value.</returns>
    _ASYNCRTIMP json::value& at(const utility::string_t& key);

    /// <summary>
    /// Accesses an element of a JSON object. If the key doesn't exist, this method throws.
    /// </summary>
    /// <param name="key">The key of an element in the JSON object.</param>
    /// <returns>If the key exists, a reference to the value.</returns>
    _ASYNCRTIMP const json::value& at(const utility::string_t& key) const;

    /// <summary>
    /// Accesses a field of a JSON object.
    /// </summary>
    /// <param name="key">The name of the field</param>
    /// <returns>A reference to the value kept in the field.</returns>
    _ASYNCRTIMP value& operator[](const utility::string_t& key);

#ifdef _WIN32
private:
    // Only used internally by JSON parser
    _ASYNCRTIMP value& operator[](const std::string& key)
    {
        // JSON object stores its field map as a unordered_map of string_t, so this conversion is hard to avoid
        return operator[](utility::conversions::to_string_t(key));
    }

public:
#endif

    /// <summary>
    /// Accesses an element of a JSON array.
    /// </summary>
    /// <param name="index">The index of an element in the JSON array</param>
    /// <returns>The value kept at the array index; null if outside the boundaries of the array</returns>
    CASABLANCA_DEPRECATED(
        "This API is deprecated and will be removed in a future release, use json::value::at() instead.")
    value get(size_t index) const;

    /// <summary>
    /// Accesses an element of a JSON array.
    /// </summary>
    /// <param name="index">The index of an element in the JSON array.</param>
    /// <returns>A reference to the value kept in the field.</returns>
    _ASYNCRTIMP value& operator[](size_t index);

private:
    friend class web::json::details::_Object;
    friend class web::json::details::_Array;
    template<typename CharType>
    friend class web::json::details::JSON_Parser;

#ifdef _WIN32
    /// <summary>
    /// Writes the current JSON value as a double-byte string to a string instance.
    /// </summary>
    /// <param name="string">The string that the JSON representation should be written to.</param>
    _ASYNCRTIMP void format(std::basic_string<utf16char>& string) const;
#endif
    /// <summary>
    /// Serializes the content of the value into a string instance in UTF8 format
    /// </summary>
    /// <param name="string">The string that the JSON representation should be written to</param>
    _ASYNCRTIMP void format(std::basic_string<char>& string) const;

#ifdef ENABLE_JSON_VALUE_VISUALIZER
    explicit value(std::unique_ptr<details::_Value> v, value_type kind) : m_value(std::move(v)), m_kind(kind)
#else
    explicit value(std::unique_ptr<details::_Value> v) : m_value(std::move(v))
#endif
    {
    }

    std::unique_ptr<details::_Value> m_value;
#ifdef ENABLE_JSON_VALUE_VISUALIZER
    value_type m_kind;
#endif
};

/// <summary>
/// A single exception type to represent errors in parsing, converting, and accessing
/// elements of JSON values.
/// </summary>
class json_exception : public std::exception
{
private:
    std::string _message;

public:
    json_exception(const char* const message) : _message(message) {}
#ifdef _UTF16_STRINGS
    json_exception(const wchar_t* const message) : _message(utility::conversions::utf16_to_utf8(message)) {}
#endif // _UTF16_STRINGS
    json_exception(std::string&& message) : _message(std::move(message)) {}

    // Must be narrow string because it derives from std::exception
    const char* what() const CPPREST_NOEXCEPT { return _message.c_str(); }
};

namespace details
{
enum json_error
{
    left_over_character_in_stream = 1,
    malformed_array_literal,
    malformed_comment,
    malformed_literal,
    malformed_object_literal,
    malformed_numeric_literal,
    malformed_string_literal,
    malformed_token,
    mismatched_brances,
    nesting,
    unexpected_token
};

class json_error_category_impl : public std::error_category
{
public:
    virtual const char* name() const CPPREST_NOEXCEPT override { return "json"; }

    virtual std::string message(int ev) const override
    {
        switch (ev)
        {
            case json_error::left_over_character_in_stream:
                return "Left-over characters in stream after parsing a JSON value";
            case json_error::malformed_array_literal: return "Malformed array literal";
            case json_error::malformed_comment: return "Malformed comment";
            case json_error::malformed_literal: return "Malformed literal";
            case json_error::malformed_object_literal: return "Malformed object literal";
            case json_error::malformed_numeric_literal: return "Malformed numeric literal";
            case json_error::malformed_string_literal: return "Malformed string literal";
            case json_error::malformed_token: return "Malformed token";
            case json_error::mismatched_brances: return "Mismatched braces";
            case json_error::nesting: return "Nesting too deep";
            case json_error::unexpected_token: return "Unexpected token";
            default: return "Unknown json error";
        }
    }
};

const json_error_category_impl& json_error_category();
} // namespace details

/// <summary>
/// A JSON array represented as a C++ class.
/// </summary>
class array
{
    typedef std::vector<json::value> storage_type;

public:
    typedef storage_type::iterator iterator;
    typedef storage_type::const_iterator const_iterator;
    typedef storage_type::reverse_iterator reverse_iterator;
    typedef storage_type::const_reverse_iterator const_reverse_iterator;
    typedef storage_type::size_type size_type;

private:
    array() : m_elements() {}
    array(size_type size) : m_elements(size) {}
    array(storage_type elements) : m_elements(std::move(elements)) {}

public:
    /// <summary>
    /// Gets the beginning iterator element of the array
    /// </summary>
    /// <returns>An <c>iterator</c> to the beginning of the JSON array.</returns>
    iterator begin() { return m_elements.begin(); }

    /// <summary>
    /// Gets the beginning const iterator element of the array.
    /// </summary>
    /// <returns>A <c>const_iterator</c> to the beginning of the JSON array.</returns>
    const_iterator begin() const { return m_elements.cbegin(); }

    /// <summary>
    /// Gets the end iterator element of the array
    /// </summary>
    /// <returns>An <c>iterator</c> to the end of the JSON array.</returns>
    iterator end() { return m_elements.end(); }

    /// <summary>
    /// Gets the end const iterator element of the array.
    /// </summary>
    /// <returns>A <c>const_iterator</c> to the end of the JSON array.</returns>
    const_iterator end() const { return m_elements.cend(); }

    /// <summary>
    /// Gets the beginning reverse iterator element of the array
    /// </summary>
    /// <returns>An <c>reverse_iterator</c> to the beginning of the JSON array.</returns>
    reverse_iterator rbegin() { return m_elements.rbegin(); }

    /// <summary>
    /// Gets the beginning const reverse iterator element of the array
    /// </summary>
    /// <returns>An <c>const_reverse_iterator</c> to the beginning of the JSON array.</returns>
    const_reverse_iterator rbegin() const { return m_elements.rbegin(); }

    /// <summary>
    /// Gets the end reverse iterator element of the array
    /// </summary>
    /// <returns>An <c>reverse_iterator</c> to the end of the JSON array.</returns>
    reverse_iterator rend() { return m_elements.rend(); }

    /// <summary>
    /// Gets the end const reverse iterator element of the array
    /// </summary>
    /// <returns>An <c>const_reverse_iterator</c> to the end of the JSON array.</returns>
    const_reverse_iterator rend() const { return m_elements.crend(); }

    /// <summary>
    /// Gets the beginning const iterator element of the array.
    /// </summary>
    /// <returns>A <c>const_iterator</c> to the beginning of the JSON array.</returns>
    const_iterator cbegin() const { return m_elements.cbegin(); }

    /// <summary>
    /// Gets the end const iterator element of the array.
    /// </summary>
    /// <returns>A <c>const_iterator</c> to the end of the JSON array.</returns>
    const_iterator cend() const { return m_elements.cend(); }

    /// <summary>
    /// Gets the beginning const reverse iterator element of the array.
    /// </summary>
    /// <returns>A <c>const_reverse_iterator</c> to the beginning of the JSON array.</returns>
    const_reverse_iterator crbegin() const { return m_elements.crbegin(); }

    /// <summary>
    /// Gets the end const reverse iterator element of the array.
    /// </summary>
    /// <returns>A <c>const_reverse_iterator</c> to the end of the JSON array.</returns>
    const_reverse_iterator crend() const { return m_elements.crend(); }

    /// <summary>
    /// Deletes an element of the JSON array.
    /// </summary>
    /// <param name="position">A const_iterator to the element to delete.</param>
    /// <returns>Iterator to the new location of the element following the erased element.</returns>
    /// <remarks>GCC doesn't support erase with const_iterator on vector yet. In the future this should be
    /// changed.</remarks>
    iterator erase(iterator position) { return m_elements.erase(position); }

    /// <summary>
    /// Deletes the element at an index of the JSON array.
    /// </summary>
    /// <param name="index">The index of the element to delete.</param>
    void erase(size_type index)
    {
        if (index >= m_elements.size())
        {
            throw json_exception("index out of bounds");
        }
        m_elements.erase(m_elements.begin() + index);
    }

    /// <summary>
    /// Accesses an element of a JSON array. Throws when index out of bounds.
    /// </summary>
    /// <param name="index">The index of an element in the JSON array.</param>
    /// <returns>A reference to the value kept in the field.</returns>
    json::value& at(size_type index)
    {
        if (index >= m_elements.size()) throw json_exception("index out of bounds");

        return m_elements[index];
    }

    /// <summary>
    /// Accesses an element of a JSON array. Throws when index out of bounds.
    /// </summary>
    /// <param name="index">The index of an element in the JSON array.</param>
    /// <returns>A reference to the value kept in the field.</returns>
    const json::value& at(size_type index) const
    {
        if (index >= m_elements.size()) throw json_exception("index out of bounds");

        return m_elements[index];
    }

    /// <summary>
    /// Accesses an element of a JSON array.
    /// </summary>
    /// <param name="index">The index of an element in the JSON array.</param>
    /// <returns>A reference to the value kept in the field.</returns>
    json::value& operator[](size_type index)
    {
        msl::safeint3::SafeInt<size_type> nMinSize(index);
        nMinSize += 1;
        msl::safeint3::SafeInt<size_type> nlastSize(m_elements.size());
        if (nlastSize < nMinSize) m_elements.resize(nMinSize);

        return m_elements[index];
    }

    /// <summary>
    /// Gets the number of elements of the array.
    /// </summary>
    /// <returns>The number of elements.</returns>
    size_type size() const { return m_elements.size(); }

private:
    storage_type m_elements;

    friend class details::_Array;
    template<typename CharType>
    friend class json::details::JSON_Parser;
};

/// <summary>
/// A JSON object represented as a C++ class.
/// </summary>
class object
{
    typedef std::vector<std::pair<utility::string_t, json::value>> storage_type;

public:
    typedef storage_type::iterator iterator;
    typedef storage_type::const_iterator const_iterator;
    typedef storage_type::reverse_iterator reverse_iterator;
    typedef storage_type::const_reverse_iterator const_reverse_iterator;
    typedef storage_type::size_type size_type;

private:
    object(bool keep_order = false) : m_elements(), m_keep_order(keep_order) {}
    object(storage_type elements, bool keep_order = false) : m_elements(std::move(elements)), m_keep_order(keep_order)
    {
        if (!keep_order)
        {
            sort(m_elements.begin(), m_elements.end(), compare_pairs);
        }
    }

public:
    /// <summary>
    /// Gets the beginning iterator element of the object
    /// </summary>
    /// <returns>An <c>iterator</c> to the beginning of the JSON object.</returns>
    iterator begin() { return m_elements.begin(); }

    /// <summary>
    /// Gets the beginning const iterator element of the object.
    /// </summary>
    /// <returns>A <c>const_iterator</c> to the beginning of the JSON object.</returns>
    const_iterator begin() const { return m_elements.cbegin(); }

    /// <summary>
    /// Gets the end iterator element of the object
    /// </summary>
    /// <returns>An <c>iterator</c> to the end of the JSON object.</returns>
    iterator end() { return m_elements.end(); }

    /// <summary>
    /// Gets the end const iterator element of the object.
    /// </summary>
    /// <returns>A <c>const_iterator</c> to the end of the JSON object.</returns>
    const_iterator end() const { return m_elements.cend(); }

    /// <summary>
    /// Gets the beginning reverse iterator element of the object
    /// </summary>
    /// <returns>An <c>reverse_iterator</c> to the beginning of the JSON object.</returns>
    reverse_iterator rbegin() { return m_elements.rbegin(); }

    /// <summary>
    /// Gets the beginning const reverse iterator element of the object
    /// </summary>
    /// <returns>An <c>const_reverse_iterator</c> to the beginning of the JSON object.</returns>
    const_reverse_iterator rbegin() const { return m_elements.rbegin(); }