-
Notifications
You must be signed in to change notification settings - Fork 96
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
bee57b4
commit 0a7860f
Showing
2 changed files
with
43 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,42 @@ | ||
[/ | ||
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/cppalliance/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`. | ||
|
||
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 extra functionality. | ||
|
||
[endsect] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters