[/
    Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)

    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

    Official repository: https://github.com/boostorg/json
]

[/-----------------------------------------------------------------------------]

[section object]

A __value__ stores an instance of __object__ as the underlying representation
for a JSON object . Instances of the __object__ type are associative
containers holding key and value pairs, where the key is a __string_view__
and the mapped type is a __value__. These containers are modelled after
standard maps with these properties:

* The elements are stored contiguously as instances of __key_value_pair__.

* Iterators are ordinary pointers, and may become invalidated on insertions
  and removals.

* The order of insertions is preserved, as long as there are no removals.

* All inserted values will use the same __memory_resource__ as the container itself.

An empty object may be constructed without incurring any memory allocations
using the __default_memory_resource__. A __storage_ptr__ can also be explicitly
specified:

[snippet_objects_1]

Initializer lists consisting of two-element key value pairs can be used
to construct objects with initial contents. These constructors may allocate
memory and throw:

[snippet_objects_2]

Alternatively, elements may be inserted after construction:

[snippet_objects_3]

Similar to the `std` counterpart, elements may be accessed directly
by their key with bounds checking using
[link json.ref.boost__json__object.at.overload1 `at`],
or without bounds checking using
[link json.ref.boost__json__object.operator__lb__rb_ `operator[]`]
which creates a null element if the key does not already exist:

[snippet_objects_4]

Internally, the container computes a hash table over the keys
so that the complexity of lookups is in constant time, on average.

[warning
    Unlike traditional node based containers like `std::set`, there is no
    guarantee of reference stability or iterator stability on insertions
    and erasures.
]

For example:

[snippet_objects_5]

Using `arr` after adding another value to `obj` results in undefined behavior.

For the complete listing of all available member functions and nested
types, see the reference page for __object__.

As with `std::pair`, the __key_value_pair__ type
can be used with structured bindings in C++17.
Specializations of `std::tuple_size`, `std::tuple_element`,
and overloads of __get__ are all provided for this purpose.

[heading Formatted Output]

When an __object__ is formatted to a __std_ostream__, the result is a valid
JSON. That is, the object will be output with curly braces and a comma
separated list of key/value pairs, as per the JSON specification.

[endsect]