= 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:
= Conversion Customization Guidelines With so many options, it can be hard to choose the best way to customise conversion for your type. In this section, we will discuss those options and suggest which to choose when.
= Contextual Conversions Previously in this section we've been assuming that there is a particular fitting JSON representation for a type. But this is not always the case. Often one needs to represent particular value with JSON of certain format in one situation and with another format in a different situation. This can be achieved with Boost.JSON by providing an extra argument---context.
= 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:
= Background The first version of allocators in C++ defined the named requirement {req_Allocator}, and made each standard container a class template parameterized on the allocator type. For example, here is the declaration for {std_vector}: