Boost C++ Libraries

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.