[/
    Copyright (c) 2023 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
]

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


[section 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.

The first advice is to use one of the library-provided conversions, rather
then providing a custom one, unless the resulting format is undesirable. If
the library deduces the wrong conversion category, you can opt out by
specialising the relevant trait to inherit from `std::false_type`.

If library-provided conversions are suitable for you, you have the option to
use direct conversions. This also puts the requirement of being default
constructible on many of your types.

The next thing to consider is whether your conversions are intended for
internal use, or whether your users are not members of your team. If your users
are external, then they will ultimately determine the conditions in which these
conversions will be used. Conversely, for internal libraries and applications,
you have the full control of usage conditions.

If your users are external, they and not you decide whether throwing exceptions
is acceptable. So, in this case it is better to use non-throwing `tag_invoke`
overloads. In addition, for customising conversion of composite types, always
use `tag_invoke` overload with 2 context parameters. This will allow correct
context propagation to elements of composites. This will also allow propagation
of exceptions from conversion of elements.

Finally, it is worth mentioning that due to the ability to provide conversions
to JSON containers without a binary dependency on the library, you don't have
to push such dependency on your users. This is particularly relevant for
libraries for which interoperation with Boost.JSON is only ancillary.

[endsect]
