////
Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
Copyright (c) 2025 Dmitry Arkhipov (grisumbras@yandex.ru)

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
////

[#dom_object]
= `object`
A <<ref_value>> stores an instance of <<ref_object>> as the underlying
representation for a JSON object. Instances of the <<ref_object>> type are
associative containers holding key and value pairs, where the key is
a <<ref_string_view>> and the mapped type is a <<ref_value>>. These containers
are modelled after standard maps with these properties:

* The elements are stored contiguously as instances of <<ref_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 {ref_memory_resource} as the container
  itself.

An empty object may be constructed without incurring any memory allocations
using the <<default_memory_resource,default memory resource>>.
A <<ref_storage_ptr>> can also be explicitly specified:

[source]
----
include::../../../test/snippets.cpp[tag=snippet_objects_1,indent=0]
----

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:

[source]
----
include::../../../test/snippets.cpp[tag=snippet_objects_2,indent=0]
----

Alternatively, elements may be inserted after construction:

[source]
----
include::../../../test/snippets.cpp[tag=snippet_objects_3,indent=0]
----

Similar to the `std` counterpart, elements may be accessed directly by their
key with bounds checking using <<ref_object_at>>, or without bounds checking
using <<ref_object_operator_lb_rb>> which creates a null element if the key
does not already exist:

[source]
----
include::../../../test/snippets.cpp[tag=snippet_objects_4,indent=0]
----

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:

[source]
----
include::../../../test/snippets.cpp[tag=snippet_objects_5,indent=0]
----

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 <<ref_object>>.

As with `std::pair`, the <<ref_key_value_pair>> type can be used with
structured bindings in {cpp}17. Specializations of `std::tuple_size`,
`std::tuple_element`, and overloads of <<ref_get>> are all provided for this
purpose.

== Formatted Output

When an <<ref_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.