= `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:

<<default_memory_resource,default resource>>, an implementation-defined instance which always uses the equivalent of global operator new and delete.

Name

{ref_memory_resource}

{ref_polymorphic_allocator}

A smart pointer through which a {ref_memory_resource} is managed and

The default memory resource uses the global `operator new` and `operator delete` to allocate memory. This resource is not reference counted and has a non-trivial deallocate function. All default-constructed <<ref_storage_ptr>> objects reference the same memory resource:

The <<ref_monotonic_resource>> optimizes this memory allocation pattern by allocating increasingly large blocks of global memory internally and parceling those blocks out in smaller pieces to fulfill allocation requests. It has a trivial deallocate function. The monotonic resource does not actually deallocate memory until the resource is destroyed. Thus, it is ideally suited for the use-case where JSON is parsed, and the resulting value is then inspected but not modified.

The resource to use when constructing values may be specified in calls to <<ref_parse>> as shown here:

A <<ref_static_resource>> constructs from a caller-provided buffer, and satisfies all memory allocation requests from the buffer. Once the buffer is exhausted, subsequent calls to allocate throw the exception `std::bad_alloc`. The resource offers a simple invariant: dynamic heap allocations are never performed.

The function <<ref_get_null_resource>> returns a global instance of the null resource. This resource offers a simple invariant: all calls to allocate will throw the exception `std::bad_alloc`. An instance of the null resource can be used to make parsing guarantee that allocations from the heap are never made. This is explored in more detail in a later section.

The containers <<ref_array>>, <<ref_object>>, and <<ref_value>> all propagate the memory resource they were constructed with to child elements:

It is important to note that <<ref_storage_ptr>> supports both shared-ownership and reference lifetime models. Construction from a memory resource pointer does not transfer ownership:

Shared ownership is achieved using the function <<ref_make_shared_resource>>, which creates a new, reference-counted memory resource using a dynamic memory allocation and returns it as a <<ref_storage_ptr>>: