value.hpp

Go to the documentation of this file.

/// \file jsonv/value.hpp
///
/// Copyright (c) 2012-2020 by Travis Gockel. All rights reserved.
///
/// This program is free software: you can redistribute it and/or modify it under the terms of the Apache License
/// as published by the Apache Software Foundation, either version 2 of the License, or (at your option) any later
/// version.
///
/// \author Travis Gockel (travis@gockelhut.com)
#pragma once
 
#include <jsonv/config.hpp>
#include <jsonv/kind.hpp>
#include <string_view>
#include <jsonv/detail/basic_view.hpp>
 
#include <compare>
#include <cstddef>
#include <cstdint>
#include <initializer_list>
#include <iosfwd>
#include <iterator>
#include <functional>
#include <stdexcept>
#include <string>
#include <type_traits>
#include <utility>
 
namespace jsonv
{
 
class path;
class value;
class object_node_handle;
 
namespace detail
{
 
class object_impl;
class array_impl;
class string_impl;
struct value_access;
 
union value_storage
{
    object_impl* object;
    array_impl*  array;
    string_impl* string;
    int64_t      integer;
    double       decimal;
    bool         boolean;
};
 
/// The longest string a \c value holds in itself rather than in a block of its own.
inline constexpr std::size_t value_inline_string_capacity = 14U;
 
/// The \c string_length of a \c kind::string whose text is in a block of its own.
inline constexpr unsigned char value_string_out_of_line = 0xffU;
 
/// How a \c value lays out everything but a string short enough to keep in itself.
struct value_words
{
    jsonv::kind   kind;
    /// For a \c kind::string, \c value_string_out_of_line; ignored otherwise.
    unsigned char string_length;
    value_storage data;
};
 
/// How a \c value lays out a string of at most \c value_inline_string_capacity bytes.
struct value_short_string
{
    jsonv::kind   kind;
    unsigned char string_length;
    char          text[value_inline_string_capacity];
};
 
/// The 16 bytes of a \c value. Both layouts start with the same \c kind and \c string_length, so those can be read
/// through \c words whichever layout is in use. Both have trivial default constructors, so assigning to either one
/// makes it the one in use.
union value_representation
{
    value_words        words;
    value_short_string short_string;
 
    constexpr value_representation() :
            words{ jsonv::kind::null, 0U, { .object = nullptr } }
    { }
};
 
static_assert(sizeof(value_representation) == 16U, "a value is 16 bytes");
 
}
 
/// \defgroup Value
/// JSON \ref value instances.
///
/// The side-effect-free parts of this API -- the predicates, the accessors, the constant lookups and everything which
/// returns a freshly built \ref value -- are \c JSONV_NODISCARD. Calling one and dropping the result does nothing at
/// all, so the compiler says so. The accessors which create on demand (non-`const` \ref value::path and
/// \ref value::operator[] for an object key) and the mutators are deliberately left alone, since discarding those is
/// how they are normally used.
/// \{
 
/// Get a string representation of the given \c value.
JSONV_NODISCARD JSONV_PUBLIC std::string to_string(const value&);
 
/// Thrown from various \c value methods when attempting to perform an operation which is not valid for the \c kind of
/// value.
class JSONV_PUBLIC kind_error :
        public std::logic_error
{
public:
    explicit kind_error(const std::string& description);
 
    virtual ~kind_error() noexcept;
};
 
/// Represents a single JSON value, which can be any one of a potential \c kind, each behaving slightly differently.
/// Instances will vary their behavior based on their kind -- functions will throw a \c kind_error if the operation does
/// not apply to the value's kind. For example, it does not make sense to call \c find on an \c integer.
///
///  - \c kind::null
///    You cannot do anything with this...it is just null.
///  - \c kind::boolean
///    These values can be \c true or \c false.
///  - \c kind::integer
///    A numeric value which can be added, subtracted and all the other things you would expect.
///  - \c kind::decimal
///    Floating-point values should be considered "more general" than integers -- you may request an integer value as a
///    decimal, but you cannot request a decimal as an integer, even when doing so would not require rounding. The
///    literal \c 20.0 will always have \c kind::decimal.
///  - \c kind::string
///    A UTF-8 encoded string, read through the \c std::string_view which \c as_string returns. Some random functions
///    work in the cases where it makes sense (for example: \c empty and \c size), but in general, string manipulation
///    should be done after calling \c as_string. A string of up to 14 bytes is kept in the \c value itself, and a longer
///    one in a single allocation of its own.
///  - \c kind::array
///    An array behaves like a \c std::vector: its elements are contiguous, growing it may move them all, and inserting
///    or erasing shifts the elements after the position. Element references are invalidated when \c std::vector's
///    would be. The elements share one allocation with the array's size and capacity, and an empty array may hold no
///    allocation at all. If you feel the documentation is lacking, read this:
///    http://en.cppreference.com/w/cpp/container/vector.
///  - \c kind::object
///    An object behaves like a \c std::flat_map: its members are kept sorted by key in one contiguous array, so it
///    iterates in key order, looking a key up is a binary search, and inserting or erasing shifts the members after
///    the position and invalidates iterators and references to them. Dereferencing an \c object_iterator gives an
///    \c object_reference, a proxy like \c std::flat_map::reference. The members share one allocation with the
///    object's size and capacity, and an empty object may hold no allocation at all. If you feel the documentation is
///    lacking, read this: http://en.cppreference.com/w/cpp/container/flat_map. This library follows the recommendation in RFC 7159
///    to not allow for duplicate keys because most other libraries can not deal with it. It would also make the AST
///    significantly more painful.
///
/// \see http://json.org/
/// \see http://tools.ietf.org/html/rfc7159
class JSONV_PUBLIC value
{
public:
    typedef std::size_t    size_type;
    typedef std::ptrdiff_t difference_type;
 
    /** The base type for iterating over array values. **/
    template <typename T, typename TArrayView>
    struct basic_array_iterator
    {
    public:
        using iterator_category = std::random_access_iterator_tag;
        using value_type = T;
        using difference_type = std::ptrdiff_t;
        using pointer = T*;
        using reference = T&;
        basic_array_iterator() :
                _owner(0),
                _index(0)
        { }
 
        basic_array_iterator(TArrayView* owner, size_type index) :
                _owner(owner),
                _index(index)
        { }
 
        template <typename U, typename UArrayView>
        basic_array_iterator(const basic_array_iterator<U, UArrayView>& source,
                             typename std::enable_if<std::is_convertible<U*, T*>::value>::type* = 0
                            ) :
                _owner(source._owner),
                _index(source._index)
        { }
 
        basic_array_iterator& operator++()
        {
            ++_index;
            return *this;
        }
 
        basic_array_iterator operator++(int)
        {
            basic_array_iterator clone = *this;
            ++*this;
            return clone;
        }
 
        basic_array_iterator& operator--()
        {
            --_index;
            return *this;
        }
 
        basic_array_iterator operator--(int)
        {
            basic_array_iterator clone = *this;
            --*this;
            return clone;
        }
 
        template <typename U, typename UArrayView>
        JSONV_NODISCARD
        bool operator==(const basic_array_iterator<U, UArrayView>& other) const
        {
            return _owner == other._owner && _index == other._index;
        }
 
        template <typename U, typename UArrayView>
        JSONV_NODISCARD
        bool operator!=(const basic_array_iterator<U, UArrayView>& other) const
        {
            return !operator==(other);
        }
 
        JSONV_NODISCARD
        T& operator*() const
        {
            return _owner->operator[](_index);
        }
 
        JSONV_NODISCARD
        T* operator->() const
        {
            return &_owner->operator[](_index);
        }
 
        basic_array_iterator& operator+=(size_type n)
        {
            _index += n;
            return *this;
        }
 
        JSONV_NODISCARD
        basic_array_iterator operator+(size_type n) const
        {
            basic_array_iterator clone = *this;
            clone += n;
            return clone;
        }
 
        basic_array_iterator& operator-=(size_type n)
        {
            _index -= n;
            return *this;
        }
 
        JSONV_NODISCARD
        basic_array_iterator operator-(size_type n) const
        {
            basic_array_iterator clone = *this;
            clone -= n;
            return clone;
        }
 
        JSONV_NODISCARD
        difference_type operator-(const basic_array_iterator& other) const
        {
            return difference_type(_index) - difference_type(other._index);
        }
 
        JSONV_NODISCARD
        bool operator<(const basic_array_iterator& rhs) const
        {
            return _index < rhs._index;
        }
 
        JSONV_NODISCARD
        bool operator<=(const basic_array_iterator& rhs) const
        {
            return _index <= rhs._index;
        }
 
        JSONV_NODISCARD
        bool operator>(const basic_array_iterator& rhs) const
        {
            return _index > rhs._index;
        }
 
        JSONV_NODISCARD
        bool operator>=(const basic_array_iterator& rhs) const
        {
            return _index >= rhs._index;
        }
 
        JSONV_NODISCARD
        T& operator[](size_type n) const
        {
            return _owner->operator[](_index + n);
        }
    private:
        template <typename U, typename UArrayView>
        friend struct basic_array_iterator;
 
        friend class value;
 
    private:
        TArrayView* _owner;
        size_type   _index;
    };
 
    /** The \c array_iterator is applicable when \c kind is \c kind::array. It allows you to use algorithms as if
     *  a \c value was a normal sequence container.
    **/
    typedef basic_array_iterator<value, value>                       array_iterator;
    typedef basic_array_iterator<const value, const value>           const_array_iterator;
 
    /** If \c kind is \c kind::array, an \c array_view allows you to access a value as a sequence container. This is
     *  most useful for range-based for loops.
    **/
    typedef detail::basic_view<array_iterator, const_array_iterator>               array_view;
    typedef detail::basic_view<const_array_iterator>                               const_array_view;
    typedef detail::basic_owning_view<value, array_iterator, const_array_iterator> owning_array_view;
 
    /** The type of value stored when \c kind is \c kind::object, as an owning pair. Iterating an object does not give
     *  references to this type: members are stored sorted by key in contiguous memory, and an iterator gives an
     *  \ref object_reference instead. Converting one into this type copies the member, so it has to be asked for.
    **/
    typedef std::pair<const std::string, value>                        object_value_type;
 
    /** What dereferencing an \c object_iterator (\c TValue of \c value) or a \c const_object_iterator
     *  (\c TValue of `const value`) gives: references to the key and value of one member. Like the \c reference of
     *  \c std::flat_map, it is a proxy returned by value, so `auto& m : obj.as_object()` does not compile -- write
     *  `auto&& m`, `const auto& m` or `auto&& [key, val]`. The key is always \c const, since changing it would break
     *  the order members are kept in.
     *
     *  The conversion to \ref object_value_type is \c explicit because it copies the value. A loop written as
     *  `const value::object_value_type& m : obj.as_object()` -- which before members were stored contiguously bound
     *  straight to the member -- would otherwise still compile and deep-copy every one of them.
    **/
    template <typename TValue>
    struct basic_object_reference
    {
    public:
        /// The type of \ref first, as in \c std::pair, which this stands in for.
        using first_type  = const std::string;
 
        /// The type of \ref second, as in \c std::pair.
        using second_type = TValue;
 
    public:
        /// The key of the member.
        const std::string& first;
 
        /// The value of the member.
        TValue&            second;
 
    public:
        /// Refer to \a key and \a val.
        basic_object_reference(const std::string& key, TValue& val) noexcept :
                first(key),
                second(val)
        { }
 
        /// Refer to the key and value of \a pair.
        basic_object_reference(std::conditional_t<std::is_const_v<TValue>, const object_value_type&, object_value_type&>
                               pair
                              ) noexcept :
                first(pair.first),
                second(pair.second)
        { }
 
        /// This allows conversion from an \c object_reference to a \c const_object_reference.
        template <typename UValue,
                  typename = std::enable_if_t<   !std::is_same_v<UValue, TValue>
                                              && std::is_convertible_v<UValue&, TValue&>
                                             >
                 >
        basic_object_reference(const basic_object_reference<UValue>& source) noexcept :
                first(source.first),
                second(source.second)
        { }
 
        /// Copy the member into an \ref object_value_type.
        ///
        /// \tparam TPair Always \ref object_value_type. It is a parameter so that nothing names that pair until the
        ///  conversion is used: MSVC instantiates a type a template's body names when it reads the body, and here that
        ///  is before \c value is complete.
        template <typename TPair, typename = std::enable_if_t<std::is_same_v<TPair, object_value_type>>>
        JSONV_NODISCARD
        explicit operator TPair() const
        {
            return TPair(first, second);
        }
    };
 
    /** \see basic_object_reference **/
    typedef basic_object_reference<value>       object_reference;
 
    /** \see basic_object_reference **/
    typedef basic_object_reference<const value> const_object_reference;
 
    /** The base iterator type for iterating over object types. It is a random-access iterator over the members of an
     *  object, which are kept sorted by key, and dereferences to a \ref basic_object_reference. Like
     *  \c std::vector<bool>::iterator, it gives \c std::random_access_iterator_tag as its \c iterator_category although
     *  its \c reference is a proxy: the functions which dispatch on the category, like \c std::prev and
     *  \c std::advance, need it to step backward or jump.
     *
     *  Like the iterators of a \c std::vector, these are invalidated by inserting into or erasing from the object.
    **/
    template <typename TValue, typename TMember>
    struct basic_object_iterator
    {
    public:
        /// What this models in C++20 terms: a random-access iterator, whose \c reference may be a proxy.
        using iterator_concept  = std::random_access_iterator_tag;
 
        /// What this gives the functions which dispatch on the category. \see basic_object_iterator
        using iterator_category = std::random_access_iterator_tag;
        using value_type        = object_value_type;
        using difference_type   = std::ptrdiff_t;
        using reference         = basic_object_reference<TValue>;
 
        /// What \c operator-> returns: it holds the \c reference, so `iter->first` and `iter->second` work.
        struct pointer
        {
            /// The member the iterator was at.
            reference ref;
 
            /// The member the iterator was at, for the built-in \c -> to reach into.
            const reference* operator->() const noexcept
            {
                return &ref;
            }
        };
 
    public:
        basic_object_iterator() noexcept :
                _member(nullptr)
        { }
 
        /** This allows conversion from an \c object_iterator to a \c const_object_iterator. **/
        template <typename UValue,
                  typename UMember,
                  typename = std::enable_if_t<   !std::is_same_v<UMember, TMember>
                                              && std::is_convertible_v<UMember*, TMember*>
                                             >
                 >
        basic_object_iterator(const basic_object_iterator<UValue, UMember>& source) noexcept :
                _member(source._member)
        { }
 
        basic_object_iterator& operator++() noexcept
        {
            ++_member;
            return *this;
        }
 
        basic_object_iterator operator++(int) noexcept
        {
            basic_object_iterator clone(*this);
            ++_member;
            return clone;
        }
 
        basic_object_iterator& operator--() noexcept
        {
            --_member;
            return *this;
        }
 
        basic_object_iterator operator--(int) noexcept
        {
            basic_object_iterator clone(*this);
            --_member;
            return clone;
        }
 
        basic_object_iterator& operator+=(difference_type n) noexcept
        {
            _member += n;
            return *this;
        }
 
        basic_object_iterator& operator-=(difference_type n) noexcept
        {
            _member -= n;
            return *this;
        }
 
        JSONV_NODISCARD
        basic_object_iterator operator+(difference_type n) const noexcept
        {
            return basic_object_iterator(_member + n);
        }
 
        JSONV_NODISCARD
        friend basic_object_iterator operator+(difference_type n, const basic_object_iterator& iter) noexcept
        {
            return iter + n;
        }
 
        JSONV_NODISCARD
        basic_object_iterator operator-(difference_type n) const noexcept
        {
            return basic_object_iterator(_member - n);
        }
 
        template <typename UValue, typename UMember>
        JSONV_NODISCARD
        difference_type operator-(const basic_object_iterator<UValue, UMember>& other) const noexcept
        {
            return _member - other._member;
        }
 
        template <typename UValue, typename UMember>
        JSONV_NODISCARD
        bool operator==(const basic_object_iterator<UValue, UMember>& other) const noexcept
        {
            return _member == other._member;
        }
 
        template <typename UValue, typename UMember>
        JSONV_NODISCARD
        auto operator<=>(const basic_object_iterator<UValue, UMember>& other) const noexcept
        {
            return _member <=> other._member;
        }
 
        JSONV_NODISCARD
        reference operator*() const noexcept
        {
            return reference(_member->first, _member->second);
        }
 
        JSONV_NODISCARD
        pointer operator->() const noexcept
        {
            return pointer{ **this };
        }
 
        JSONV_NODISCARD
        reference operator[](difference_type n) const noexcept
        {
            return *(*this + n);
        }
 
    private:
        template <typename UValue, typename UMember>
        friend struct basic_object_iterator;
 
        friend class value;
 
        explicit basic_object_iterator(TMember* member) noexcept :
                _member(member)
        { }
 
    private:
        TMember* _member;
    };
 
    /** The \c object_iterator is applicable when \c kind is \c kind::object. It allows you to use algorithms as if
     *  a \c value was a normal associative container.
    **/
    typedef basic_object_iterator<value,       std::pair<std::string, value>>       object_iterator;
    typedef basic_object_iterator<const value, const std::pair<std::string, value>> const_object_iterator;
 
    /** If \c kind is \c kind::object, an \c object_view allows you to access a value as an associative container.
     *  This is most useful for range-based for loops.
    **/
    typedef detail::basic_view<object_iterator, const_object_iterator>               object_view;
    typedef detail::basic_view<const_object_iterator>                                const_object_view;
    typedef detail::basic_owning_view<value, object_iterator, const_object_iterator> owning_object_view;
 
    /// Type returned from \c insert operations when this has \ref kind::object. It is generally compatible with the
    /// \c insert_return_type of \c std::map, with the notable lack of \c node.
    ///
    /// \see insert
    struct object_insert_return_type final
    {
        /// The position of the inserted member or the member with the duplicate key.
        const_object_iterator position;
 
        /// Did the insert operation perform an insert? A value of \c false indicates there was a key already present
        /// with the same name.
        bool inserted;
    };
 
public:
    /** Default-construct this to null. **/
    constexpr value() = default;
 
    /// The nullptr overload will fail to compile -- use \c jsonv::null if you want a \c kind::null.
    value(std::nullptr_t) = delete;
 
    /** Copy the contents of \a source into a new instance. **/
    value(const value& source);
 
    /** Create a \c kind::string with the given \a value. **/
    value(const std::string& value);
 
    /** Create a \c kind::string with the given \a value. **/
    value(const std::string_view& value);
 
    /// Create a \c kind::string with the given \a value.
    ///
    /// \param value The value to create with. This must be null-terminated.
    value(const char* value);
 
    /// Create a \c kind::string with the given \a value. Keep in mind that it will be converted to and stored as a
    /// UTF-8 encoded string.
    ///
    /// \throws std::range_error if \a value is not valid UTF-16, such as when it holds an unpaired surrogate or, where
    ///  \c wchar_t is 32 bits, a code unit above 0xFFFF.
    value(const std::wstring& value);
 
    /** Create a \c kind::string with the given \a value. Keep in mind that it will be converted to and stored as a
     *  UTF-8 encoded string.
     *
     *  \param value The value to create with. This must be null-terminated.
     *  \throws std::range_error if \a value is not valid UTF-16, such as when it holds an unpaired surrogate or, where
     *   \c wchar_t is 32 bits, a code unit above 0xFFFF.
    **/
    value(const wchar_t* value);
 
    /** Create a \c kind::integer with the given \a value. **/
    value(int64_t value);
 
    /** Create a \c kind::decimal with the given \a value. **/
    value(double value);
 
    /** Create a \c kind::decimal with the given \a value. **/
    value(float value);
 
    /** Create a \c kind::boolean with the given \a value. **/
    value(bool value);
 
    #define JSONV_VALUE_INTEGER_ALTERNATIVE_CTOR_PROTO_GENERATOR(type_)              \
        value(type_ val);
    JSONV_INTEGER_ALTERNATES_LIST(JSONV_VALUE_INTEGER_ALTERNATIVE_CTOR_PROTO_GENERATOR)
    #undef JSONV_VALUE_INTEGER_ALTERNATIVE_CTOR_PROTO_GENERATOR
 
    /** Destruction will never throw. **/
    ~value() noexcept;
 
    /** Copy-assigns \c source to this.
     *
     *  If an exception is thrown during the copy, it is propagated out. This instance will remain unchanged.
    **/
    value& operator=(const value& source);
 
    /** Move-construct this instance, leaving \a source as a null value. **/
    value(value&& source) noexcept;
 
    /** Move-assigns \c source to this, leaving \a source as a null value.
     *
     *  Unlike a copy, this will never throw.
    **/
    value& operator=(value&& source) noexcept;
 
    /** Get this value as a string. The view is into this \c value, so it is good until the value changes or goes away:
     *  `auto text = parse(input).as_string();` leaves \c text referring to a destroyed temporary. Make a
     *  \c std::string from it to keep the text, or to get a NUL-terminated \c c_str.
     *
     *  \throws kind_error if this value does not represent a string.
    **/
    JSONV_NODISCARD
    std::string_view as_string() const;
 
    /** Tests if this \c kind is \c kind::string. **/
    JSONV_NODISCARD
    bool is_string() const;
 
    /** The same as \c as_string. It is your responsibility to ensure the \c value instance remains valid.
     *
     *  \throws kind_error if this value does not represent a string.
    **/
    JSONV_NODISCARD
    std::string_view as_string_view() const &;
 
    /** Get this value as a wide string. Keep in mind that this is slower than \c as_string, as the text is stored as
     *  UTF-8 and has to be converted. The result is UTF-16 even where \c wchar_t is 32 bits, so a code point outside
     *  the BMP takes a surrogate pair there too.
     *
     *  \throws kind_error if this value does not represent a string.
     *  \throws std::range_error if the stored string is not valid UTF-8.
    **/
    JSONV_NODISCARD
    std::wstring as_wstring() const;
 
    /** Get this value as an integer.
     *
     *  \throws kind_error if this value does not represent an integer.
    **/
    JSONV_NODISCARD
    int64_t as_integer() const;
 
    /** Tests if this \c kind is \c kind::integer. **/
    JSONV_NODISCARD
    bool is_integer() const;
 
    /** Get this value as a decimal. If the value's underlying kind is actually an integer type, cast the integer to a
     *  double before returning. This ignores the potential loss of precision.
     *
     *  \throws kind_error if this value does not represent a decimal or integer.
    **/
    JSONV_NODISCARD
    double as_decimal() const;
 
    /** Tests if this \c kind is \c kind::integer or \c kind::decimal. **/
    JSONV_NODISCARD
    bool is_decimal() const;
 
    /** Get this value as a boolean.
     *
     *  \throws kind_error if this value does not represent a boolean.
    **/
    JSONV_NODISCARD
    bool as_boolean() const;
 
    /** Tests if this \c kind is \c kind::boolean. **/
    JSONV_NODISCARD
    bool is_boolean() const;
 
    /** Tests if this \c kind is \c kind::array. **/
    JSONV_NODISCARD
    bool is_array() const;
 
    /** Tests if this \c kind is \c kind::object. **/
    JSONV_NODISCARD
    bool is_object() const;
 
    /** Tests if this \c kind is \c kind::null. **/
    JSONV_NODISCARD
    bool is_null() const;
 
    /** Resets this value to null. **/
    void clear();
 
    /** Get this value's kind. **/
    JSONV_NODISCARD
    inline jsonv::kind kind() const
    {
        return _repr.words.kind;
    }
 
    /// \{
 
    /** Get the value specified by the path \a p.
     *
     *  \throws std::out_of_range if any path along the chain did not exist.
     *  \throws kind_error if the path traversal is not valid for the value (for example: if the path specifies an array
     *                     index when the value is a string).
     *  \throws std::invalid_argument if a \c std::string_view was specified that did not have a valid specification
     *                                (see \c path::create).
    **/
    value&       at_path(const path& p);
    value&       at_path(std::string_view p);
    value&       at_path(size_type   p);
    JSONV_NODISCARD
    const value& at_path(const path& p) const;
    JSONV_NODISCARD
    const value& at_path(std::string_view p) const;
    JSONV_NODISCARD
    const value& at_path(size_type   p) const;
    /// \}
 
    /// \{
 
    /** Similar to \c count, but walks the given path \a p to determine its presence.
     *
     *  \returns \c 1 if the path finds an element; \c 0 if there is no such path in the tree.
     *
     *  \throws std::invalid_argument if a \c std::string_view was specified that did not have a valid specification
     *                                (see \c path::create).
    **/
    JSONV_NODISCARD
    size_type count_path(const path& p) const;
    JSONV_NODISCARD
    size_type count_path(std::string_view p) const;
    JSONV_NODISCARD
    size_type count_path(size_type   p) const;
    /// \}
 
    /// \{
 
    /** Get or create the value specified by the path \a p. This is the moral equivalent to \c operator[] for paths. If
     *  no value exists at the path, a new one is created as the default (\c null) value. If any path along the way
     *  either does not exist or is \c null, it is created for you, based on the \e implications of the specification
     *  \a p. Unlike \c at_path, which will throw if accessing a non-existent key of an \c object or going past the end
     *  of an \c array, this will simply create that path and fill in the blanks with \c null values.
     *
     *  \throws kind_error if the path traversal is not valid for the value (for example: if the path specifies an array
     *                     index when the value is a string).
     *  \throws std::invalid_argument if a \c std::string_view was specified that did not have a valid specification
     *                                (see \c path::create).
     *  \throws std::length_error if the path has an array index which no array can hold, such as the largest
     *                            \c std::size_t.
     *  \throws std::bad_alloc if there is not enough memory to create what the path needs.
     *
     *  If this throws, for any reason, \c *this is left as it was. What the path needs is built apart from the tree and
     *  added to it in a single step at the end, so there is no partial result: a \c null does not become \c [] and a
     *  key on the way to the failing index is not created. A path which already exists is only followed, with nothing
     *  allocated.
     *
     *  \see at_path
    **/
    value& path(const path& p);
    value& path(std::string_view p);
    value& path(size_type   p);
    /// \}
 
    /** Swap the value this instance represents with \a other. **/
    void swap(value& other) noexcept;
 
    /** Compares two JSON values for equality. Two JSON values are equal if and only if all of the following conditions
     *  apply:
     *
     *   1. They have the same valid value for \c kind, where \c kind::integer and \c kind::decimal count as the same.
     *      - If \c kind is invalid (memory corruption), then two JSON values are \e not equal, even if they have been
     *        corrupted in the same way and even if they share \c this (a corrupt object is not equal to itself).
     *   2. The kind comparison is also equal:
     *      - Two null values are always equivalent.
     *      - string, integer and boolean follow the classic rules for their type.
     *      - decimals compare exactly, with signed zeros equal and all NaNs equal (see \c compare).
     *      - an integer and a decimal are equal only when the decimal holds exactly that integer (see \c compare).
     *      - objects are equal if they have the same keys and values corresponding with the same key are also equal.
     *      - arrays are equal if they have the same length and the values at each index are also equal.
     *
     *  \note
     *  The rules for equality are based on Python \c dict and \c list.
    **/
    JSONV_NODISCARD
    bool operator==(const value& other) const;
 
    /** Compares two JSON values for inequality. The rules for inequality are the exact opposite of equality.
    **/
    JSONV_NODISCARD
    bool operator!=(const value& other) const;
 
    /** Used to build a strict-ordering of JSON values. When comparing values of the same kind, the ordering should
     *  align with your intuition. When comparing values of different kinds, some arbitrary rules were created based on
     *  how "complicated" the author thought the type to be.
     *
     *   - null: less than everything but null, which it is equal to.
     *   - boolean: false is less than true.
     *   - integer, decimal: compared by their exact numeric value. An integer is never converted to a decimal to
     *     compare it with one, so \c 9007199254740993 is greater than the decimal \c 9007199254740992.0 even though
     *     converting it would round to that decimal. Decimal comparison is exact, without an epsilon tolerance. Signed
     *     zeros compare equal to each other and to the integer \c 0; infinities follow numeric order. All NaNs compare
     *     equal to each other and greater than every other number, regardless of sign or payload.
     *   - string: compared lexicographically by character code (with basic char strings and non-ASCII encoding, this
     *     might lead to surprising results)
     *   - array: compared lexicographically by elements (recursively following this same technique)
     *   - object: entries in the object are sorted and compared lexicographically, first by key then by value
     *
     *  \returns A negative number if this is less than other by the rules stated above; 0 if this is equal to other; a
     *           positive number otherwise. Only the sign is meaningful: strings and object keys pass on the result of
     *           \c std::string::compare, which need not be -1 or 1.
    **/
    JSONV_NODISCARD
    int compare(const value& other) const;
 
    JSONV_NODISCARD
    bool operator< (const value& other) const;
    JSONV_NODISCARD
    bool operator> (const value& other) const;
    JSONV_NODISCARD
    bool operator<=(const value& other) const;
    JSONV_NODISCARD
    bool operator>=(const value& other) const;
 
    /// Output this value to a stream, through an \c ostream_encoder. The stream's format flags, width, fill and locale
    /// do not change the text written.
    friend std::ostream& operator<<(std::ostream& stream, const value& val);
 
    /// Get a string representation of the given \c value.
    friend std::string to_string(const value&);
 
    /// \{
 
    /// Get an iterator to the beginning of this array.
    ///
    /// \throws kind_error if the kind is not an array.
    JSONV_NODISCARD
    array_iterator       begin_array();
    JSONV_NODISCARD
    const_array_iterator begin_array() const;
    /// \}
 
    /// \{
 
    /// Get an iterator to the end of this array.
    ///
    /// \throws kind_error if the kind is not an array.
    JSONV_NODISCARD
    array_iterator       end_array();
    JSONV_NODISCARD
    const_array_iterator end_array() const;
    /// \}
 
    /// \{
 
    /// View this instance as an array.
    ///
    /// \throws kind_error if the kind is not an array.
    JSONV_NODISCARD
    array_view        as_array() &;
    JSONV_NODISCARD
    const_array_view  as_array() const &;
    JSONV_NODISCARD
    owning_array_view as_array() &&;
    /// \}
 
    /// \{
 
    /// Get the value in this array at the given \a idx. The overloads which accept an \c int are required to resolve
    /// the type ambiguity of the literal \c 0 between a size_type and a char*.
    ///
    /// \throws kind_error if the kind is not an array.
    value&              operator[](size_type idx);
    JSONV_NODISCARD
    const value&        operator[](size_type idx) const;
    inline value&       operator[](int       idx)       { return operator[](size_type(idx)); }
    JSONV_NODISCARD
    inline const value& operator[](int       idx) const { return operator[](size_type(idx)); }
    /// \}
 
    /// \{
 
    /// Get the value in this array at the given \a idx.
    ///
    /// \throws kind_error if the kind is not an array.
    /// \throws std::out_of_range if the provided \a idx is above \c size.
    ///
    value&       at(size_type idx);
    JSONV_NODISCARD
    const value& at(size_type idx) const;
    /// \}
 
    /// \{
 
    /// Push \a item to the back of this array.
    ///
    /// \throws kind_error if the kind is not an array.
    void push_back(value&&      item);
    void push_back(const value& item);
    /// \}
 
    /// Pop an item off the back of this array.
    ///
    /// \throws kind_error if the kind is not an array.
    /// \throws std::logic_error if the array is empty.
    void pop_back();
 
    /// Insert an item into \a position on this array.
    ///
    /// \throws kind_error if the kind is not an array.
    array_iterator insert(const_array_iterator position, value item);
 
    /// Insert the range defined by [\a first, \a last) at \a position in this array.
    ///
    /// \throws kind_error if the kind is not an array.
    template <typename TForwardIterator>
    array_iterator insert(const_array_iterator position, TForwardIterator first, TForwardIterator last)
    {
        difference_type orig_offset = std::distance(const_array_iterator(begin_array()), position);
 
        for (difference_type offset = orig_offset ; first != last; ++first, ++offset)
            insert(begin_array() + offset, *first);
        return begin_array() + orig_offset;
    }
 
    /// Assign \a count elements to this array with \a val.
    ///
    /// \throws kind_error if the kind is not an array.
    void assign(size_type count, const value& val);
 
    /// Assign the contents of range [\a first, \a last) to this array.
    ///
    /// \throws kind_error if the kind is not an array.
    template <typename TForwardIterator>
    void assign(TForwardIterator first, TForwardIterator last)
    {
        resize(std::distance(first, last), value());
        auto iter = begin_array();
        while (first != last)
        {
            *iter = *first;
            ++iter;
            ++first;
        }
    }
 
    /// Assign the given \a items to this array.
    ///
    /// \throws kind_error if the kind is not an array.
    void assign(std::initializer_list<value> items);
 
    /// Reserve at least \a count elements in the array.
    ///
    /// \throws kind_error if the kind is not an array.
    void reserve(size_type count);
 
    /// Resize the length of this array to \a count items. If the resize creates new elements, fill those newly-created
    /// elements with \a val.
    ///
    /// \throws kind_error if the kind is not an array.
    void resize(size_type count, const value& val = value());
 
    /// Erase the item at this array's \a position.
    ///
    /// \throws kind_error if the kind is not an array.
    array_iterator erase(const_array_iterator position);
 
    /// Erase the range [\a first, \a last) from this array.
    ///
    /// \throws kind_error if the kind is not an array.
    array_iterator erase(const_array_iterator first, const_array_iterator last);
 
    /// \{
 
    /** Get an iterator to the first key-value pair in this object.
     *
     *  \throws kind_error if the kind is not an object.
    **/
    JSONV_NODISCARD
    object_iterator       begin_object();
    JSONV_NODISCARD
    const_object_iterator begin_object() const;
    /// \}
 
    /// \{
 
    /** Get an iterator to the one past the end of this object.
     *
     *  \throws kind_error if the kind is not an object.
    **/
    JSONV_NODISCARD
    object_iterator       end_object();
    JSONV_NODISCARD
    const_object_iterator end_object() const;
    /// \}
 
    /// \{
 
    /** View this instance as an object.
     *
     *  \throws kind_error if the kind is not an object.
    **/
    JSONV_NODISCARD
    object_view        as_object() &;
    JSONV_NODISCARD
    const_object_view  as_object() const &;
    JSONV_NODISCARD
    owning_object_view as_object() &&;
    /// \}
 
    /// \{
 
    /** Get the value associated with the given \a key of this object. If the \a key does not exist, it will be created.
     *  Creating it invalidates iterators and references as \ref insert does.
     *
     *  \throws kind_error if the kind is not an object.
    **/
    value& operator[](const std::string& key);
    value& operator[](std::string&& key);
    value& operator[](const std::wstring& key);
    /// \}
 
    /// \{
 
    /** Get the value associated with the given \a key of this object.
     *
     *  \throws kind_error if the kind is not an object.
     *  \throws std::out_of_range if the \a key is not in this object.
    **/
    value& at(const std::string& key);
    value& at(const std::wstring& key);
    JSONV_NODISCARD
    const value& at(const std::string& key) const;
    JSONV_NODISCARD
    const value& at(const std::wstring& key) const;
    /// \}
 
    /// \{
 
    /** Check if the given \a key exists in this object.
     *
     *  \throws kind_error if the kind is not an object.
    **/
    JSONV_NODISCARD
    size_type count(const std::string& key) const;
    JSONV_NODISCARD
    size_type count(const std::wstring& key) const;
    /// \}
 
    /// \{
 
    /** Attempt to locate a key-value pair with the provided \a key in this object.
     *
     *  \throws kind_error if the kind is not an object.
    **/
    JSONV_NODISCARD
    object_iterator       find(const std::string& key);
    JSONV_NODISCARD
    object_iterator       find(const std::wstring& key);
    JSONV_NODISCARD
    const_object_iterator find(const std::string& key)  const;
    JSONV_NODISCARD
    const_object_iterator find(const std::wstring& key) const;
    /// \}
 
    /// \{
 
    /// Insert \a pair into this object, unless an element with an equivalent key is already present.
    ///
    /// Inserting invalidates every iterator and reference to a member at or after the position inserted at, and every
    /// one of them if the object has to grow.
    ///
    /// \returns A pair whose \c first refers to the newly-inserted element (or the element which shares the key) and
    ///  whose \c second is \c true if the insertion took place.
    /// \throws kind_error if the kind is not an object.
    std::pair<object_iterator, bool> insert(std::pair<std::string, value>  pair);
    std::pair<object_iterator, bool> insert(std::pair<std::wstring, value> pair);
    /// \}
 
    /// \{
 
    /// Insert \a pair into this object, unless an element with an equivalent key is already present. If \a hint is
    /// where the key goes -- every member before it has a lesser key and \a hint itself a greater one -- the key is not
    /// searched for. A \a hint of \ref end_object for a key greater than every one present appends in amortized
    /// constant time; any other insertion shifts the members after it. A wrong \a hint costs a binary search.
    ///
    /// Inserting invalidates every iterator and reference to a member at or after the position inserted at, and every
    /// one of them if the object has to grow.
    ///
    /// \returns An iterator to the newly-inserted element (or the element which shares the key).
    /// \throws kind_error if the kind is not an object.
    object_iterator insert(const_object_iterator hint, std::pair<std::string, value>  pair);
    object_iterator insert(const_object_iterator hint, std::pair<std::wstring, value> pair);
    /// \}
 
    /// Insert range defined by [\a first, \a last) into this object. Each element is hinted just past the previous one,
    /// so a source in ascending key order needs no searching, and one whose keys all sort after what this object holds
    /// is appended in amortized constant time per element. Any element which does not go at the end shifts the
    /// members after it.
    ///
    /// Inserting invalidates every iterator and reference to a member at or after the position inserted at, and every
    /// one of them if the object has to grow.
    ///
    /// \throws kind_error if the kind is not an object.
    template <typename TForwardIterator>
    void insert(TForwardIterator first, TForwardIterator last)
    {
        // Each element is hinted just past the one before it, which is right for any ascending source -- most
        // importantly one building a fresh object, where that is the end. Reading end_object() also rejects a
        // non-object when the range is empty.
        const_object_iterator hint = end_object();
        for ( ; first != last; ++first)
            hint = insert(hint, *first) + 1;
    }
 
    /// Insert the contents of \a handle. If \a handle is empty, this does nothing. If the insertion succeeds, \a handle
    /// is moved from and left empty; otherwise it retains ownership of the element.
    ///
    /// Inserting invalidates every iterator and reference to a member at or after the position inserted at, and every
    /// one of them if the object has to grow.
    ///
    /// \returns If \a handle is empty, \c inserted is \c false and \c position is `end_object()`. If the insertion took
    ///  place, \c inserted is \c true and \c position points to the inserted element. If the insertion was attempted
    ///  but failed, \c inserted is \c false and \c position points to an element with a key equivalent to
    ///  `handle.key()`.
    /// \throws kind_error if the kind is not an object.
    object_insert_return_type insert(object_node_handle&& handle);
 
    /// If \a handle is an empty node handle, does nothing and returns \ref end_object. Otherwise, inserts the element
    /// owned by \a handle into the container, if the container doesn't already contain an element with a key equivalent
    /// to `handle.key()` and returns the iterator pointing to the element with key equivalent to `handle.key()`. If the
    /// insertion succeeds, \a handle is moved from, otherwise it retains ownership of the element. \a hint works as it
    /// does for \ref insert of a pair.
    ///
    /// Inserting invalidates every iterator and reference to a member at or after the position inserted at, and every
    /// one of them if the object has to grow.
    ///
    /// \returns An iterator pointing to an element with a key equivalent to `handle.key()` if \a handle was not empty.
    ///  If \a handle was empty, `end_object()`.
    /// \throws kind_error if the kind is not an object.
    object_iterator insert(const_object_iterator hint, object_node_handle&& handle);
 
    /// \{
 
    /// Insert \a items into this object.
    ///
    /// Inserting invalidates every iterator and reference to a member at or after the position inserted at, and every
    /// one of them if the object has to grow.
    ///
    /// \throws kind_error if the kind is not an object.
    void insert(std::initializer_list<std::pair<std::string, value>>  items);
    void insert(std::initializer_list<std::pair<std::wstring, value>> items);
    /// \}
 
    /// \{
 
    /// Construct an element from \a key and \a val and insert it into this object. If an element with an equivalent
    /// key is already present, the insertion does not happen and the existing element is not overwritten.
    ///
    /// \note
    /// \a key is taken by value, so a call which does not insert has still built and destroyed it. Prefer
    /// \ref try_emplace when collisions are expected.
    ///
    /// Inserting invalidates every iterator and reference to a member at or after the position inserted at, and every
    /// one of them if the object has to grow.
    ///
    /// \returns A pair whose \c first refers to the newly-inserted element (or the element which shares the key) and
    ///  whose \c second is \c true if the insertion took place.
    /// \throws kind_error if the kind is not an object.
    ///
    /// \see insert
    /// \see try_emplace
    std::pair<object_iterator, bool> emplace(std::string         key, value val);
    std::pair<object_iterator, bool> emplace(const std::wstring& key, value val);
    /// \}
 
    /// \{
 
    /// Insert \a val with the given \a key into this object, but only if no element with an equivalent key is already
    /// present. Unlike \ref emplace, \a key is not copied when the key is already present.
    ///
    /// \note
    /// \a val is taken by value, so a caller who passes `std::move(x)` has moved from \c x by the time this function
    /// is entered whether or not the insertion happens. It is the key which is spared, not \a val.
    ///
    /// Inserting invalidates every iterator and reference to a member at or after the position inserted at, and every
    /// one of them if the object has to grow.
    ///
    /// \returns A pair whose \c first refers to the newly-inserted element (or the element which shares the key) and
    ///  whose \c second is \c true if the insertion took place.
    /// \throws kind_error if the kind is not an object.
    ///
    /// \see insert
    /// \see insert_or_assign
    std::pair<object_iterator, bool> try_emplace(const std::string&  key, value val);
    std::pair<object_iterator, bool> try_emplace(const std::wstring& key, value val);
    /// \}
 
    /// \{
 
    /// Insert \a val with the given \a key into this object if no element with an equivalent key is present;
    /// otherwise, assign \a val to the existing element. Unlike \ref try_emplace, \a val is stored either way.
    ///
    /// \returns A pair whose \c first refers to the inserted or assigned element and whose \c second is \c true if an
    ///  insertion took place and \c false if an assignment took place. Unlike \ref insert, a \c second of \c false
    ///  does \e not mean the operation failed -- this function always modifies the object.
    /// \throws kind_error if the kind is not an object.
    ///
    /// An insertion invalidates iterators and references as \ref insert does; an assignment invalidates none.
    ///
    /// \see insert
    /// \see try_emplace
    std::pair<object_iterator, bool> insert_or_assign(const std::string&  key, value val);
    std::pair<object_iterator, bool> insert_or_assign(const std::wstring& key, value val);
    /// \}
 
    /// \{
 
    /// Erase the item with the given \a key.
    ///
    /// Erasing invalidates every iterator and reference to a member at or after the position erased from.
    ///
    /// \returns 1 if \a key was erased; 0 if it did not.
    /// \throws kind_error if the kind is not an object.
    size_type erase(const std::string&  key);
    size_type erase(const std::wstring& key);
    /// \}
 
    /// Erase the item at the given \a position.
    ///
    /// Erasing invalidates every iterator and reference to a member at or after the position erased from.
    ///
    /// \returns An iterator to the member which followed the erased one.
    /// \throws kind_error if the kind is not an object.
    object_iterator erase(const_object_iterator position);
 
    /// Erase the range defined by [\a first, \a last).
    ///
    /// Erasing invalidates every iterator and reference to a member at or after the position erased from.
    ///
    /// \returns An iterator to the member which followed the erased range.
    /// \throws kind_error if the kind is not an object.
    object_iterator erase(const_object_iterator first, const_object_iterator last);
 
    /// Move the key and value of the member at \a position into a node handle, erase the member, and return the handle.
    ///
    /// Erasing invalidates every iterator and reference to a member at or after the position erased from.
    ///
    /// \throws kind_error if the kind is not an object.
    object_node_handle extract(const_object_iterator position);
 
    /// \{
 
    /// If the container has an element with the given \a key, moves its key and value into a node handle, erases it,
    /// and returns the handle. Otherwise, returns an empty node handle.
    ///
    /// Erasing invalidates every iterator and reference to a member at or after the position erased from.
    ///
    /// \throws kind_error if the kind is not an object.
    object_node_handle extract(const std::string&  key);
    object_node_handle extract(const std::wstring& key);
    /// \}
 
    /** Is the underlying structure empty?
     *
     *   - object: Are there no keys?
     *   - array: Are there no values?
     *   - string: Is the string 0 length?
     *   - null: true (always)
     *   - all other types: false (always)
     *
     *  \throws nothing
    **/
    JSONV_NODISCARD
    bool empty() const noexcept;
 
    /** Get the number of items in this value.
     *
     *   - object: The number of key/value pairs.
     *   - array: The number of values.
     *   - string: The number of code points in the string (including \c \\0 values and counting multi-byte encodings as
     *             more than one value).
     *
     *  \throws kind_error if the kind is not an object, array or string.
    **/
    JSONV_NODISCARD
    size_type size() const;
 
    /** \addtogroup Algorithm
     *  \{
    **/
 
    /** Run a function over the values of this instance. The behavior of this function is different, depending on the
     *  \c kind. For scalar kinds (\c kind::integer, \c kind::null, etc), \a func is called once with the value. If this
     *  is \c kind::array, \c func is called for every value in the array and the output will be an array with each
     *  element transformed by \a func. If this is \c kind::object, the result will be an object with each key
     *  transformed by \a func.
     *
     *  \param func The function to apply to the element or elements of this instance.
    **/
    JSONV_NODISCARD
    value map(const std::function<value (const value&)>& func) const&;
 
    /** Run a function over the values of this instance. The behavior of this function is different, depending on the
     *  \c kind. For scalar kinds (\c kind::integer, \c kind::null, etc), \a func is called once with the value. If this
     *  is \c kind::array, \c func is called for every value in the array and the output will be an array with each
     *  element transformed by \a func. If this is \c kind::object, the result will be an object with each key
     *  transformed by \a func.
     *
     *  \param func The function to apply to the element or elements of this instance.
     *
     *  \note
     *  This version of \c map provides only a basic exception-safety guarantee. If an exception is thrown while
     *  transforming a non-scalar \c kind, there is no rollback action, so \c this is left in a usable, but
     *  \e unpredictable state. If you need a strong exception guarantee, use the constant reference version of \c map.
    **/
    JSONV_NODISCARD
    value map(const std::function<value (value)>& func) &&;
 
    /** \} **/
 
private:
    friend JSONV_PUBLIC value array();
    friend JSONV_PUBLIC value object();
    friend struct detail::value_access;
 
private:
    detail::value_representation _repr;
};
 
/** An instance with \c kind::null. This is intended to be used for convenience and readability (as opposed to using the
 *  default constructor of \c value.
**/
JSONV_PUBLIC extern const value null;
 
/** A user-defined literal for parsing JSON. Uses the default (non-strict) \c parse_options.
 *
 *  \code
 *  R"({
 *    "taco": "cat",
 *    "burrito": "dog",
 *    "whatever": [ "goes", "here", 1, 2, 3, 4 ]
 *  })"_json;
 *  \endcode
**/
JSONV_NODISCARD JSONV_PUBLIC value operator""_json(const char* str, std::size_t len);
 
/** Swap the values \a a and \a b. **/
JSONV_PUBLIC void swap(value& a, value& b) noexcept;
 
/** Create an empty array value. **/
JSONV_NODISCARD JSONV_PUBLIC value array();
 
/** Create an array value from the given source. **/
JSONV_NODISCARD JSONV_PUBLIC value array(std::initializer_list<value> source);
 
/** Create an array with contents defined by range [\a first, \a last). **/
template <typename TForwardIterator>
value array(TForwardIterator first, TForwardIterator last)
{
    value arr = array();
    arr.assign(first, last);
    return arr;
}
 
/** Create an empty object. **/
JSONV_NODISCARD JSONV_PUBLIC value object();
 
/** Create an object with key-value pairs from the given \a source. **/
JSONV_NODISCARD JSONV_PUBLIC value object(std::initializer_list<std::pair<std::string, value>>  source);
JSONV_NODISCARD JSONV_PUBLIC value object(std::initializer_list<std::pair<std::wstring, value>> source);
 
/** Create an object whose contents are defined by range [\a first, \a last). **/
template <typename TForwardIterator>
value object(TForwardIterator first, TForwardIterator last)
{
    value obj = object();
    obj.insert(first, last);
    return obj;
}
 
/// A <a href="http://en.cppreference.com/w/cpp/container/node_handle">node handle</a> used when a value is
/// \ref kind::object to access elements of the object in potentially destructive manner. This makes it possible to
/// modify the contents of a node extracted from an object, and then re-insert it without having to copy the element.
class JSONV_PUBLIC object_node_handle final
{
public:
    /// The key type of the object.
    using key_type = std::string;
 
    /// The mapped type of the object.
    using mapped_type = value;
 
public:
    explicit object_node_handle() noexcept :
            _has_value(false)
    { }
 
    /// Take over the element owned by \a src, if any. \a src is left \ref empty.
    object_node_handle(object_node_handle&& src) noexcept;
 
    /// Release the element this handle owns, if any, and take over the one owned by \a src, if any. \a src is left
    /// \ref empty. Self-assignment has no effect.
    object_node_handle& operator=(object_node_handle&& src) noexcept;
 
    ~object_node_handle() noexcept;
 
    /// \returns \c true if the node handle is empty; \c false if otherwise.
    JSONV_NODISCARD
    bool empty() const noexcept { return !_has_value; }
 
    /// \returns \c false if the node handle is empty; \c true if otherwise.
    JSONV_NODISCARD
    explicit operator bool() const noexcept { return _has_value; }
 
    /// Returns a non-const reference to the \ref key_type member of the element.
    ///
    /// \throws std::invalid_argument if the node handle is \ref empty.
    key_type& key() const;
 
    /// Returns a non-const reference to the \ref mapped_type member of the element.
    ///
    /// \throws std::invalid_argument if the node handle is \ref empty.
    mapped_type& mapped() const;
 
private:
    enum class purposeful_construction
    { };
 
    explicit object_node_handle(purposeful_construction, key_type, mapped_type) noexcept;
 
    friend class value;
 
private:
    bool                _has_value;
    mutable key_type    _key;
    mutable mapped_type _value;
};
 
/// \}
 
}
 
namespace std
{
 
/// Explicit specialization of \c std::hash for \c jsonv::value types so you can store a \c value in an unordered
/// container. Values which compare equal hash equal. Since an integer compares equal to the decimal of the same number,
/// both \c kind::integer and \c kind::decimal hash through \c value::as_decimal: \c value(2) and \c value(2.0) share a
/// hash, as do distinct integers past 2^53 which convert to the same \c double. All NaNs share a hash. For aggregate
/// kinds \c array and \c object, hashing visits every sub-element recursively. This might be expensive, but is required
/// when storing multiple values with similar layouts in a set (which is the most common use case).
template <>
struct JSONV_PUBLIC hash<jsonv::value>
{
    JSONV_NODISCARD
    std::size_t operator()(const jsonv::value& val) const noexcept;
};
 
/// A member reference and an owning member have \c jsonv::value::const_object_reference in common: both convert to it.
/// This is what makes the object iterators, whose \c reference is a proxy, model \c std::random_access_iterator.
template <typename TValue, template <typename> class TQual, template <typename> class UQual>
struct basic_common_reference<jsonv::value::basic_object_reference<TValue>,
                              jsonv::value::object_value_type,
                              TQual,
                              UQual
                             >
{
    using type = jsonv::value::const_object_reference;
};
 
/// The same, with the arguments the other way around.
template <typename TValue, template <typename> class TQual, template <typename> class UQual>
struct basic_common_reference<jsonv::value::object_value_type,
                              jsonv::value::basic_object_reference<TValue>,
                              TQual,
                              UQual
                             >
{
    using type = jsonv::value::const_object_reference;
};
 
}