= Accessing Deeply Nested Elements In order to allow conveniently retrieving and changing deeply nested elements of <<ref_value>> objects the library implements https://datatracker.ietf.org/doc/html/rfc6901[RFC 6901 (JSON Pointer)]:
= Numbers JSON numbers are represented using `std::int64_t`, `std::uint64_t`, and `double`. When a <<ref_value>> is constructed from an unsigned integer, its <<ref_kind>> will be `kind::uint64`. Likewise, a <<ref_value>> constructed from a signed integer will have `kind::int64`, or `kind::double_` if constructed from a floating-point type:
= Custom Conversions Boost.JSON uses two mechanisms to customize conversion between <<ref_value>> and user types. One mechanism involves specializing type traits. The other one is more powerful and requires defining overloads of `tag_invoke`. Both mechanisms will be further explained in this section.
= Direct Conversion For large inputs parsing into the library's containers followed by conversion via <<ref_value_to>> (or vice versa <<ref_value_from>> followed by serialization from a <<ref_value>>) might be prohibitively expensive. For these cases the library provides components that allow parsing directly into and serializing directly from user-provided objects.
= `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:
= Non-Throwing Conversions For the case where throwing exceptions is undesirable, Boost.JSON also provides a non-throwing version of <<ref_value_to>>, the function template <<ref_try_value_to>>.It returns {ref_result}, a specialised variant that either holds a value or an {ref_error_code}.
= Avoiding Physical Dependency Some users, particularly library authors, may wish to provide conversions between their types and <<ref_value>>, but at the same time would prefer to avoid having their library depend on Boost.JSON. This is possible to achieve with the help of a few forward declarations.
= Allocation Control As <<ref_value_from>> creates a <<ref_value>> object, users may want to control the way memory is allocated for it. For this reason the function has an optional <<ref_storage_ptr>> parameter, that is used to set the {ref_memory_resource} for the result.
= `value` JSON documents are represented in memory as instances of <<ref_value>>: a {req_Regular} type which satisfies {req_DefaultConstructible}, {req_CopyConstructible}, {req_CopyAssignable}, {req_MoveConstructible}, {req_MoveAssignable}, and many of the requirements of allocator-aware containers. It is implemented as a https://en.wikipedia.org/wiki/Tagged_union[__variant__] internally, and can dynamically store any of the six defined JSON value types:
= `array` A <<ref_value>> stores an instance of <<ref_array>> as the underlying representation for a JSON array. Instances of the __array__ type function identically to a {std_vector} of <<ref_value>>. Additionally, all values inserted into the container will use the same <<ref_storage_ptr>> as the container itself.
= `storage_ptr` Variable-length containers in this library all use dynamically allocated memory to store their contents. Callers can gain control over the strategy used for allocation by specifying a <<ref_storage_ptr>> in select constructors and function parameter lists. A <<ref_storage_ptr>> has these properties:
= Uses-allocator Construction To support code bases which are already using polymorphic allocators, the containers in this library support {std_uses_allocator} construction. For <<ref_array>>, <<ref_object>>, <<ref_string>>, and <<ref_value>>:
= Input/Output The library provides parsing and serialization algorithms to transform JSON to and from the <<ref_value>> container as needed. This is accomplished through free functions and classes, described as follows.
= Value Conversion While the <<ref_value>> container makes it easy to create ad-hoc structures, often it is necessary to convert between JSON and user-defined types or types from the standard library.