[/
    Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)

    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/cppalliance/json
]

[/-----------------------------------------------------------------------------]

[section:uses_allocator Uses-allocator construction]

To support code bases which are already using polymorphic allocators,
the containers in this library support __std_uses_allocator__ construction.
For __array__, __object__, __string__, and __value__:

* The nested type `allocator_type` is an alias for a __polymorphic_allocator__

* All eligible constructors which accept __storage_ptr__ will also accept
    an instance of __polymorphic_allocator__ in the same argument position.

* The member function `get_allocator` returns an instance of
    __polymorphic_allocator__ constructed from the __memory_resource__
    used by the container. Ownership of this memory resource is not
    transferred.

Practically, this means that when a library container type is used in a
standard container that uses a polymorphic allocator, the allocator will
propagate to the JSON type. For example:

[doc_uses_allocator_1]

Library containers can be constructed from polymorphic allocators:

[doc_uses_allocator_2]

The polymorphic allocator is propagated recursively.
Child elements of child elements will use the same memory
resource as the parent.

[endsect]