User avatar admin

Translation uploaded
Conversion Traits
Conversion Traits转换特征
06/05/2026
User avatar admin

Translation uploaded
= Custom Conversions Boost.JSON uses two mechanisms to customize conversion between <<ref_value>> and user types. One mechanism involves specializing type traits. The other one is more powerful and requires defining overloads of `tag_invoke`. Both mechanisms will be further explained in this section.
= Custom Conversions Boost.JSON uses two mechanisms to customize conversion between <<ref_value>> and user types. One mechanism involves specializing type traits. The other one is more powerful and requires defining overloads of `tag_invoke`. Both mechanisms will be further explained in this section.自定义转换 Boost.JSON 提供了两种机制用于自定义 &lt;<ref_value>&gt; 与用户类型之间的转换。一种机制涉及特化类型特征（type traits）。另一种机制更强大，需要定义`tag_invoke`的重载。本节将进一步解释这两种机制。</ref_value>
06/05/2026
User avatar admin

Resource updated
File “doc/pages/conversion/custom_zh_Hans.adoc” was added. 06/05/2026
User avatar admin

String added in the repository
Users can freely combine types with custom conversions with types with library-provided conversions. The library handles them correctly:
Users can freely combine types with custom conversions with types with library-provided conversions. The library handles them correctly:
06/05/2026
User avatar admin

String added in the repository
Since the type being converted is embedded into the function's signature, user-provided overloads are visible to argument-dependent lookup and will be candidates when a conversion is performed:
Since the type being converted is embedded into the function's signature, user-provided overloads are visible to argument-dependent lookup and will be candidates when a conversion is performed:
06/05/2026
User avatar admin

String added in the repository
If we implemented conversion for `user_ns::ip_address` manually with this approach, it would look like this:
If we implemented conversion for `user_ns::ip_address` manually with this approach, it would look like this:
06/05/2026
User avatar admin

String added in the repository
``` T tag_invoke( const value_to_tag< T >&, const value& ); ```
``` T tag_invoke( const value_to_tag< T >&, const value& ); ```
06/05/2026
User avatar admin

String added in the repository
While overloads of `tag_invoke` called by <<ref_value_to>> take the form:
While overloads of `tag_invoke` called by <<ref_value_to>> take the form:
06/05/2026
User avatar admin

String added in the repository
``` void tag_invoke( const value_from_tag&, value&, T ); ```
``` void tag_invoke( const value_from_tag&, value&, T ); ```
06/05/2026
User avatar admin

String added in the repository
Overloads of `tag_invoke` called by <<ref_value_from>> take the form:
Overloads of `tag_invoke` called by <<ref_value_from>> take the form:
06/05/2026
User avatar admin

String added in the repository
This has the effect of finding user-provided `tag_invoke` overloads, even if they are declared (lexically) after the definition of the calling function.
This has the effect of finding user-provided `tag_invoke` overloads, even if they are declared (lexically) after the definition of the calling function.
06/05/2026
User avatar admin

String added in the repository
template such as `value_to_tag<T>`) so that its http://eel.is/c++draft/basic.lookup.argdep#2[associated namespaces and entities] are examined when name lookup is performed.
template such as `value_to_tag<T>`) so that its http://eel.is/c++draft/basic.lookup.argdep#2[associated namespaces and entities] are examined when name lookup is performed.
06/05/2026
User avatar admin

String added in the repository
embed the user-defined type into the arguments list (e.g. by using a tag type
embed the user-defined type into the arguments list (e.g. by using a tag type
06/05/2026
User avatar admin

String added in the repository
customization point, and
customization point, and
06/05/2026
User avatar admin

String added in the repository
discard candidates that are unrelated to that particular
discard candidates that are unrelated to that particular
06/05/2026
User avatar admin

String added in the repository
The second, more powerful approach, is to provide the conversion implementation yourself. With Boost.JSON this is done by defining an overload of `tag_invoke` function (the benefits of this mechanism are outlined in http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1895r0.pdf[C++ proposal P1895]. In essence, `tag_invoke` provides a uniform interface for defining customization points by using argument-dependent lookup to find a viable overload from the point at which it is called. As the name suggests, a tag type is passed as an argument in order to:
The second, more powerful approach, is to provide the conversion implementation yourself. With Boost.JSON this is done by defining an overload of `tag_invoke` function (the benefits of this mechanism are outlined in http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1895r0.pdf[C++ proposal P1895]. In essence, `tag_invoke` provides a uniform interface for defining customization points by using argument-dependent lookup to find a viable overload from the point at which it is called. As the name suggests, a tag type is passed as an argument in order to:
06/05/2026
User avatar admin

String added in the repository
`tag_invoke` Overloads
`tag_invoke` Overloads
06/05/2026
User avatar admin

String added in the repository
It exposes both a sequence API and a tuple API. But converting from <<ref_value>> to `user_ns::ip_address` would not be able to use implementation for sequences, since those are constructed empty and then populated one element at a time, while `ip_address` has a fixed size of 4. The tuple conversion would fit, though. The only problem is that <<ref_is_tuple_like>> has a lower priority than <<ref_is_sequence_like>>. In order to circumvent this, the user only needs to specialize <<ref_is_sequence_like>> to not match `ip_address`.
It exposes both a sequence API and a tuple API. But converting from <<ref_value>> to `user_ns::ip_address` would not be able to use implementation for sequences, since those are constructed empty and then populated one element at a time, while `ip_address` has a fixed size of 4. The tuple conversion would fit, though. The only problem is that <<ref_is_tuple_like>> has a lower priority than <<ref_is_sequence_like>>. In order to circumvent this, the user only needs to specialize <<ref_is_sequence_like>> to not match `ip_address`.
06/05/2026
User avatar admin

String added in the repository
Consider this type:
Consider this type:
06/05/2026
User avatar admin

String added in the repository
Previously a number of conversion type traits, like <<ref_is_tuple_like>> or <<ref_is_sequence_like>>, were introduced. The library tries the traits one after another and uses the implementation that corresponds to the first matching trait. In some cases, though, a type would match a trait with a higher priority, but the user intends for it to belong to a lower priority category. If this happens the user can specialize the trait that's not supposed to match for that type to be an equivalent of `std::false_type`.
Previously a number of conversion type traits, like <<ref_is_tuple_like>> or <<ref_is_sequence_like>>, were introduced. The library tries the traits one after another and uses the implementation that corresponds to the first matching trait. In some cases, though, a type would match a trait with a higher priority, but the user intends for it to belong to a lower priority category. If this happens the user can specialize the trait that's not supposed to match for that type to be an equivalent of `std::false_type`.
06/05/2026

Search