mirror of
https://github.com/boostorg/json.git
synced 2026-01-26 18:42:16 +00:00
96 lines
3.1 KiB
Plaintext
96 lines
3.1 KiB
Plaintext
////
|
|
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.
|