mirror of
https://github.com/boostorg/json.git
synced 2026-01-27 06:52:14 +00:00
41 lines
2.0 KiB
Plaintext
41 lines
2.0 KiB
Plaintext
////
|
|
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
|
|
////
|
|
|
|
= 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.
|