= 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:
= `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:
= `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:
= `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>>:
When accessing a number contained within a <<ref_value>>, the function used must match the value's <<ref_kind>> exactly; no conversions will be performed. For example if `as_double` is called on a <<ref_value>> that contains a `std::uint64_t`, an exception is thrown. Similarly, the function `if_double` will return `nullptr` and calling `get_double` will result in undefined behavior:
An empty array 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:
Serialization is the process where a JSON document represented in memory by a <<ref_value>> is turned into a sequence of characters. The library provides the following free functions and types for serialization:
In cases where you know that a <<ref_value>> contains a number but don't know its <<ref_kind>>, `value::to_number` can be used to convert the <<ref_value>> to an arithmetic type:
These `tag_invoke` overloads take an extra `as_string` parameter, which disambiguates this specific representation of `ip_address` from all other potential representations. In order to take advantage of them one needs to pass an `as_string` object to <<ref_value_from>> or <<ref_value_to>> as the last argument:
The library provides non-throwing conversions for all the categories of types it supports with <<ref_value_to>>. If a user wants to use it with custom types, an overload of `tag_invoke` of this form needs to be provided:
The library also allows changing and adding deeply nested elements. The function <<ref_value_set_at_pointer>> traverses the value similarly to <<ref_value_at_pointer>>, but additionally, it can create missing elements in certain cases:
If the <<ref_value>> does not contain a number, or if the conversion is to an integer type `T` and the number cannot be represented exactly by `T`, the conversion will fail. Otherwise, the result is the number converted to `T` as-if by `static_cast`:
When a two element initializer list is nested within an enclosing initializer list, it is unclear whether it represents an <<ref_array>> or an <<ref_object>>:
The specific behavior is controlled by an optional parameter of type <<ref_set_pointer_options>>. For example, here's the same example with a different option: