[/
    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/cppalliance/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.

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]