value_to.hpp

100.0% Lines (9/0/9) 98.6% List of functions (365/0/370)

[ ] prev/next file

value_to.hpp

f(x) Functions (370)

Function Calls Lines Blocks

Line	Hits	Source Code
1		//
2		// Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
3		// Copyright (c) 2020 Krystian Stasiowski (sdkrystian@gmail.com)
4		// Copyright (c) 2022 Dmitry Arkhipov (grisumbras@gmail.com)
5		//
6		// Distributed under the Boost Software License, Version 1.0. (See accompanying
7		// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
8		//
9		// Official repository: https://github.com/boostorg/json
10		//
11
12		#ifndef BOOST_JSON_VALUE_TO_HPP
13		#define BOOST_JSON_VALUE_TO_HPP
14
15		#include <boost/core/detail/static_assert.hpp>
16		#include <boost/json/detail/value_to.hpp>
17
18		namespace boost {
19		namespace json {
20
21		/** Convert a @ref value to an object of type `T`.
22
23		This function attempts to convert a @ref value to `T` using
24
25		- one of @ref value's accessors, or
26		- a library-provided generic conversion, or
27		- a user-provided overload of `tag_invoke`.
28
29		In order to perform the conversion the function selects an appropriate
30		implementation based on the types `T` and `Context` (if provided).
31
32		1. If `Context` is available and is not `std::tuple<C...>`
33
34		a. check if `use_category<T, Context>::value` is not
35		@ref conversion_category::unknown; otherwise
36
37		b. check if a `tag_invoke` overload from the list below that takes a
38		`Context const&` exists.
39
40		2. Otherwise, if `Context` is available, and is `std::tuple<C...>` repeat
41		steps 1 and 2 recursively for every `C` until either
42		step 1.a or 1.b succeeds for some `C`.
43
44		3. Failing that,
45
46		a. check if `use_category<T>::value` is not
47		@ref conversion_category::unknown; otherwise
48
49		b. check if a `tag_invoke` overload from the list below that takes only
50		2 parameters exists; otherwise
51
52		c. check if `T` is one of @ref value, @ref array, @ref object,
53		or @ref string; otherwise
54
55		d. check if `T` matches one of the categories of types described in the
56		table "Conversion categories" in \<\<Value Conversion>> section.
57
58		These steps determine both the appropriate category of conversion for `T`,
59		and, if necessary, the effective context `C` that will be used for
60		conversion. If the category is selected on steps 1.a, 3.a, 3.c,
61		or 3.d, the library provides a suitable conversion implementation.
62		If the category is selected on steps 2.b or 3.b, then a
63		user-provided `tag_invoke` overload is used.
64
65		The overloads of `tag_invoke` that will be considered by this function
66		are in the following list. Overloads that appear higher in the list have
67		higher priority.
68
69		@code
70		template< class FullContext >
71		result<T> tag_invoke( try_value_to_tag<T>, const value&, const Context&, const FullContext& );
72
73		template< class FullContext >
74		T tag_invoke( value_to_tag<T>, const value&, const Context&, const FullContext& );
75
76		result<T> tag_invoke( try_value_to_tag<T>, const value&, const Context& );
77
78		T tag_invoke( value_to_tag<T>, const value&, const Context& );
79
80		result<T> tag_invoke( try_value_to_tag<T>, const value& );
81
82		T tag_invoke( value_to_tag<T>, const value& );
83		@endcode
84
85		For `tag_invoke` overloads that take a parameter of type `value_to_tag<T>`
86		the object returned by a call to that overload is returned by the function
87		as the result of the conversion. For overloads that take a parameter of
88		type `try_value_to_tag<T>` if the returned `result` contains a value, that
89		value is returned as the result of the conversion. Otherwise, an exception
90		of type @ref boost::system::system_error that stores the error is thrown.
91
92		The `ctx` argument can be used either as a tag type to provide conversions
93		for third-party types, or to pass extra data to the conversion function.
94
95		Overload (3) is deleted and participates in overload resolution
96		only when `U` is not @ref value. The overload exists to prevent unintented
97		creation of temporary @ref value instances, e.g.
98
99		@code
100		auto flag = value_to<bool>(true);
101		@endcode
102
103		@par Constraints
104		@code
105		! std::is_reference< T >::value
106		@endcode
107
108		@par Exception Safety
109		Strong guarantee.
110
111		@tparam T The type to convert to.
112
113		@tparam Context The type of context passed to the conversion function.
114
115		@returns `jv` converted to `T`.
116
117		@param jv The @ref value to convert.
118
119		@param ctx Context passed to the conversion function.
120
121		@see @ref try_value_to, @ref value_from,
122		<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1895r0.pdf">
123		tag_invoke: A general pattern for supporting customisable functions</a>
124
125		@{
126		*/
127		template< class T, class Context >
128		T
129	410x	value_to( value const& jv, Context const& ctx )
130		{
131		BOOST_CORE_STATIC_ASSERT( ! std::is_reference<T>::value );
132		using bare_T = detail::remove_cvref<T>;
133		using cat = detail::value_to_category<Context, bare_T>;
134	410x	return detail::value_to_impl( cat(), value_to_tag<bare_T>(), jv, ctx );
135		}
136
137		/// Overload
138		template<class T>
139		T
140	131x	value_to(const value& jv)
141		{
142	192x	return value_to<T>( jv, detail::no_context() );
143		}
144
145		/// Overload
146		template<class T, class U
147		#ifndef BOOST_JSON_DOCS
148		, class = typename std::enable_if<!std::is_same<U, value>::value>::type
149		#endif
150		>
151		T
152		value_to(U const& jv) = delete;
153		/// @}
154
155		/** Convert a @ref value to a @ref boost::system::result.
156
157		This function attempts to convert a @ref value to `result<T>` using
158
159		- one of @ref value's accessors, or
160		- a library-provided generic conversion, or
161		- a user-provided overload of `tag_invoke`.
162
163		In order to perform the conversion the function selects an appropriate
164		implementation based on the types `T` and `Context` (if provided).
165
166		1. If `Context` is available and is not `std::tuple<C...>`
167
168		a. check if `use_category<T, Context>::value` is not
169		@ref conversion_category::unknown; otherwise
170
171		b. check if a `tag_invoke` overload from the list below that takes a
172		`Context const&` exists.
173
174		2. Otherwise, if `Context` is available, and is `std::tuple<C...>` repeat
175		steps 1 and 2 recursively for every `C` until either
176		step 1.a or 1.b succeeds for some `C`.
177
178		3. Failing that,
179
180		a. check if `use_category<T>::value` is not
181		@ref conversion_category::unknown; otherwise
182
183		b. check if a `tag_invoke` overload from the list below that takes only
184		2 parameters exists; otherwise
185
186		c. check if `T` is one of @ref value, @ref array, @ref object,
187		or @ref string; otherwise
188
189		d. check if `T` matches one of the categories of types described in the
190		table "Conversion categories" in \<\<Value Conversion>> section.
191
192		These steps determine both the appropriate category of conversion for `T`,
193		and, if necessary, the effective context `C` that will be used for
194		conversion. If the category is selected on steps 1.a, 3.a, 3.c,
195		or 3.d, the library provides a suitable conversion implementation.
196		If the category is selected on steps 2.b or 3.b, then a
197		user-provided `tag_invoke` overload is used.
198
199		The overloads of `tag_invoke` that will be considered by this function
200		are in the following list. Overloads that appear higher in the list have
201		higher priority.
202
203		@code
204		template< class FullContext >
205		result<T> tag_invoke( try_value_to_tag<T>, const value&, const Context&, const FullContext& );
206
207		template< class FullContext >
208		T tag_invoke( value_to_tag<T>, const value&, const Context&, const FullContext& );
209
210		result<T> tag_invoke( try_value_to_tag<T>, const value&, const Context& );
211
212		T tag_invoke( value_to_tag<T>, const value&, const Context& );
213
214		result<T> tag_invoke( try_value_to_tag<T>, const value& );
215
216		T tag_invoke( value_to_tag<T>, const value& );
217		@endcode
218
219		For `tag_invoke` overloads that take a parameter of type
220		`try_value_to_tag<T>` the object returned by a call to that overload is
221		returned by the function as the result of the conversion. For overloads
222		that take a parameter of type `value_to_tag<T>` the returned object is
223		wrapped with a `result<T>`.
224
225		If an error occurs during conversion, the result will store the error code
226		associated with the error. If an exception is thrown, the function will
227		attempt to retrieve the associated error code and return it, otherwise it
228		will return @ref error::exception, unless the exception type is
229		@ref std::bad_alloc, which will be allowed to propagate.
230
231		The `ctx` argument can be used either as a tag type to provide conversions
232		for third-party types, or to pass extra data to the conversion function.
233
234		@par Constraints
235		@code
236		! std::is_reference< T >::value
237		@endcode
238
239		@par Exception Safety
240		Strong guarantee.
241
242		@tparam T The type to convert to.
243		@tparam Context The type of context passed to the conversion function.
244
245		@param jv The @ref value to convert.
246		@param ctx Context passed to the conversion function.
247
248		@returns `jv` converted to `result<T>`.
249
250		@see @ref value_to_tag, @ref value_to, @ref value_from,
251		[tag_invoke: A general pattern for supporting customisable functions](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1895r0.pdf).
252
253		@{
254		*/
255		template< class T, class Context >
256		typename result_for<T, value>::type
257	3763x	try_value_to( value const& jv, Context const& ctx )
258		{
259		BOOST_CORE_STATIC_ASSERT( ! std::is_reference<T>::value );
260		using bare_T = detail::remove_cvref<T>;
261		using cat = detail::value_to_category<Context, bare_T>;
262	3573x	return detail::value_to_impl(
263	3757x	cat(), try_value_to_tag<bare_T>(), jv, ctx );
264		}
265
266		/// Overload
267		template<class T>
268		typename result_for<T, value>::type
269	130x	try_value_to(const value& jv)
270		{
271	163x	return try_value_to<T>( jv, detail::no_context() );
272		}
273		/// @}
274
275		/** Determine if a @ref value can be converted to `T`.
276
277		If @ref value can be converted to `T` via a
278		call to @ref value_to, the static data member `value`
279		is defined as `true`. Otherwise, `value` is
280		defined as `false`.
281
282		@see @ref value_to
283		*/
284		#ifdef BOOST_JSON_DOCS
285		template<class T>
286		using has_value_to = __see_below__;
287		#else
288		template<class T>
289		using has_value_to = detail::can_convert<
290		detail::remove_cvref<T>, detail::value_to_conversion>;
291		#endif
292
293		} // namespace json
294		} // namespace boost
295
296		#endif
297