value_to

`value_to`

Convert a value to an object of type T.

Synopsis

Defined in header <boost/json/value_to.hpp>.

template<
    class T,
    class Context>
T
value_to(
    value const& jv,
    Context const& ctx); (1)

template<
    class T>
T
value_to(
    const value& jv); (2)

template<
    class T,
    class U>
T
value_to(
    U const& jv) = delete; (3)

Description

This function attempts to convert a value to T using

one of value's accessors, or
a library-provided generic conversion, or
a user-provided overload of tag_invoke.

In order to perform the conversion the function selects an appropriate implementation based on the types T and Context (if provided).

If Context is available and is not std::tuple<C...>
1. check if use_category<T, Context>::value is not conversion_category::unknown; otherwise
2. check if a tag_invoke overload from the list below that takes a Context const& exists.
Otherwise, if Context is available, and is std::tuple<C...> repeat steps 1 and 2 recursively for every C until either step 1.a or 1.b succeeds for some C.
Failing that,
1. check if use_category<T>::value is not conversion_category::unknown; otherwise
2. check if a tag_invoke overload from the list below that takes only 2 parameters exists; otherwise
3. check if T is one of value, array, object, or string; otherwise
4. check if T matches one of the categories of types described in the table "Conversion categories" in Value Conversion section.

These steps determine both the appropriate category of conversion for T, and, if necessary, the effective context C that will be used for conversion. If the category is selected on steps 1.a, 3.a, 3.c, or 3.d, the library provides a suitable conversion implementation. If the category is selected on steps 2.b or 3.b, then a user-provided tag_invoke overload is used.

The overloads of tag_invoke that will be considered by this function are in the following list. Overloads that appear higher in the list have higher priority.

template< class FullContext >
result<T> tag_invoke( try_value_to_tag<T>, const value&, const Context&, const FullContext& );

template< class FullContext >
T tag_invoke( value_to_tag<T>, const value&, const Context&, const FullContext& );

result<T> tag_invoke( try_value_to_tag<T>, const value&, const Context& );

T tag_invoke( value_to_tag<T>, const value&, const Context& );

result<T> tag_invoke( try_value_to_tag<T>, const value& );

T tag_invoke( value_to_tag<T>, const value& );

For tag_invoke overloads that take a parameter of type value_to_tag<T> the object returned by a call to that overload is returned by the function as the result of the conversion. For overloads that take a parameter of type try_value_to_tag<T> if the returned result contains a value, that value is returned as the result of the conversion. Otherwise, an exception of type boost::system::system_error that stores the error is thrown.

The ctx argument can be used either as a tag type to provide conversions for third-party types, or to pass extra data to the conversion function.

Overload (3) is deleted and participates in overload resolution only when U is not value. The overload exists to prevent unintented creation of temporary value instances, e.g.

auto flag = value_to<bool>(true);

Constraints

! std::is_reference< T >::value

Exception Safety

Strong guarantee.

Template Parameters

Type Description

Type	Description
`T`	The type to convert to.
`Context`	The type of context passed to the conversion function.

T

The type to convert to.

Context

The type of context passed to the conversion function.

Return Value

jv converted to T.

Parameters

Name Description

Name	Description
`jv`	The `value` to convert.
`ctx`	Context passed to the conversion function.

jv

The value to convert.

ctx

Context passed to the conversion function.