////
Copyright (c) 2022 Dmitry Arkhipov (grisumbras@yandex.ru)

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/boostorg/json
////

= 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.

[NOTE]
<<ref_value_to>> does not have a similar parameter, as <<ref_value>> is not
created.

As the conversion result is set via an output parameter of type `value&`, the
intended <<ref_storage_ptr>> is correctly propagated. But users still should
take care to not create temporaries using the default {ref_memory_resource} by
accident.

For example, consider this alternative implementation of `tag_invoke` for
`ip_address` from the section <<custom_conversions>>.

```
void
tag_invoke( const value_from_tag&, value& jv, ip_address const& addr )
{
    jv = array{ b[0], b[1], b[2], b[3] };
}
```

This implementation explicitly creates an <<ref_array>> rather than relying on
assignment from an initializer list. But the array uses default
{ref_memory_resource}, not the one used by `jv`.

To avoid creating such temporaries with an incorrect {ref_memory_resource},
using <<ref_value>>'s member functions <<ref_value_emplace_array>>,
<<ref_value_emplace_object>>, and <<ref_value_emplace_string>> can be helpful.