GCC Code Coverage Report

Directory: libs/json/include/boost/json/
File: value_to.hpp
Date: 2025-12-23 17:35:06
Exec Total Coverage
Lines: 9 9 100.0%
Functions: 362 367 98.6%
Branches: 2 2 100.0%
Line Branch Exec Source
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/json/detail/value_to.hpp>
16
17 namespace boost {
18 namespace json {
19
20 /** Convert a @ref value to an object of type `T`.
21
22 This function attempts to convert a @ref value
23 to `T` using
24
25 @li one of @ref value's accessors, or
26
27 @li a library-provided generic conversion, or
28
29 @li a user-provided overload of `tag_invoke`.
30
31 Out of the box the function supports types satisfying
32 <a href="https://en.cppreference.com/w/cpp/named_req/SequenceContainer"><em>SequenceContainer</em></a>,
33 arrays, arithmetic types, `bool`, `std::tuple`, `std::pair`,
34 `std::variant`, `std::optional`, `std::monostate`, and `std::nullopt_t`.
35
36 Conversion of other types is done by calling an overload of `tag_invoke`
37 found by argument-dependent lookup. Its signature should be similar to:
38
39 @code
40 template< class FullContext >
41 T tag_invoke( value_to_tag<T>, const value&, const Context& , const FullContext& );
42 @endcode
43
44 or
45
46 @code
47 T tag_invoke( value_to_tag<T>, const value&, const Context& );
48 @endcode
49
50 or
51
52 @code
53 result<T> tag_invoke( value_to_tag<T>, const value& );
54 @endcode
55
56 The overloads are checked for existence in that order and the first that
57 matches will be selected. <br>
58
59 The object returned by the function call is returned by @ref value_to as
60 the result of the conversion. <br>
61
62 The `ctx` argument can be used either as a tag type to provide conversions
63 for third-party types, or to pass extra data to the conversion function.
64
65 @par Constraints
66 @code
67 ! std::is_reference< T >::value
68 @endcode
69
70 @par Exception Safety
71 Strong guarantee.
72
73 @tparam T The type to convert to.
74
75 @tparam Context The type of context passed to the conversion function.
76
77 @returns `jv` converted to `result<T>`.
78
79 @param jv The @ref value to convert.
80
81 @param ctx Context passed to the conversion function.
82
83 @see @ref value_to_tag, @ref value_from,
84 <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1895r0.pdf">
85 tag_invoke: A general pattern for supporting customisable functions</a>
86 */
87 template< class T, class Context >
88 T
89 808 value_to( value const& jv, Context const& ctx )
90 {
91 BOOST_STATIC_ASSERT(! std::is_reference<T>::value);
92 using bare_T = detail::remove_cvref<T>;
93 BOOST_STATIC_ASSERT(detail::conversion_round_trips<
94 Context, bare_T, detail::value_to_conversion>::value);
95 using cat = detail::value_to_category<Context, bare_T>;
96 808 return detail::value_to_impl( cat(), value_to_tag<bare_T>(), jv, ctx );
97 }
98
99 /** Convert a @ref value to an object of type `T`.
100
101 This function attempts to convert a @ref value
102 to `T` using
103
104 @li one of @ref value's accessors, or
105
106 @li a library-provided generic conversion, or
107
108 @li a user-provided overload of `tag_invoke`.
109
110 Out of the box the function supports types satisfying
111 <a href="https://en.cppreference.com/w/cpp/named_req/SequenceContainer"><em>SequenceContainer</em></a>,
112 arrays, arithmetic types, `bool`, `std::tuple`, `std::pair`,
113 `std::variant`, `std::optional`, `std::monostate`, and `std::nullopt_t`.
114
115 Conversion of other types is done by calling an overload of `tag_invoke`
116 found by argument-dependent lookup. Its signature should be similar to:
117
118 @code
119 T tag_invoke( value_to_tag<T>, const value& );
120 @endcode
121
122 The object returned by the function call is
123 returned by @ref value_to as the result of the
124 conversion.
125
126 @par Constraints
127 @code
128 ! std::is_reference< T >::value
129 @endcode
130
131 @par Exception Safety
132 Strong guarantee.
133
134 @tparam T The type to convert to.
135
136 @returns `jv` converted to `T`.
137
138 @param jv The @ref value to convert.
139
140 @see @ref value_to_tag, @ref value_from,
141 <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1895r0.pdf">
142 tag_invoke: A general pattern for supporting customisable functions</a>
143 */
144 template<class T>
145 T
146 249 value_to(const value& jv)
147 {
148
1/1
✓ Branch 1 taken 103 times.
 371 return value_to<T>( jv, detail::no_context() );
149 }
150
151 /** Convert a @ref value to a `boost::system::result<T>`.
152
153 This function attempts to convert a @ref value
154 to `result<T>` using
155
156 @li one of @ref value's accessors, or
157
158 @li a library-provided generic conversion, or
159
160 @li a user-provided overload of `tag_invoke`.
161
162 Out of the box the function supports types satisfying
163 <a href="https://en.cppreference.com/w/cpp/named_req/SequenceContainer"><em>SequenceContainer</em></a>,
164 arrays, arithmetic types, `bool`, `std::tuple`, `std::pair`,
165 `std::variant`, `std::optional`, `std::monostate`, and `std::nullopt_t`.
166
167 Conversion of other types is done by calling an overload of `tag_invoke`
168 found by argument-dependent lookup. Its signature should be similar to:
169
170 @code
171 template< class FullContext >
172 result<T> tag_invoke( try_value_to_tag<T>, const value&, const Context& , const FullContext& );
173 @endcode
174
175 or
176
177 @code
178 result<T> tag_invoke( try_value_to_tag<T>, const value&, const Context& );
179 @endcode
180
181 or
182
183 @code
184 result<T> tag_invoke( try_value_to_tag<T>, const value& );
185 @endcode
186
187 The overloads are checked for existence in that order and the first that
188 matches will be selected. <br>
189
190 If an error occurs during conversion, the result will store the error code
191 associated with the error. If an exception is thrown, the function will
192 attempt to retrieve the associated error code and return it, otherwise it
193 will return `error::exception`, unless the exception type is
194 `std::bad_alloc`, which will be allowed to propagate. <br>
195
196 The `ctx` argument can be used either as a tag type to provide conversions
197 for third-party types, or to pass extra data to the conversion function.
198
199 @par Constraints
200 @code
201 ! std::is_reference< T >::value
202 @endcode
203
204 @par Exception Safety
205 Strong guarantee.
206
207 @tparam T The type to convert to.
208
209 @tparam Context The type of context passed to the conversion function.
210
211 @param jv The @ref value to convert.
212
213 @param ctx Context passed to the conversion function.
214
215 @returns `jv` converted to `result<T>`.
216
217 @see @ref value_to_tag, @ref value_to, @ref value_from,
218 <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1895r0.pdf">
219 tag_invoke: A general pattern for supporting customisable functions</a>
220 */
221 template< class T, class Context >
222 typename result_for<T, value>::type
223 7486 try_value_to( value const& jv, Context const& ctx )
224 {
225 BOOST_STATIC_ASSERT(! std::is_reference<T>::value);
226 using bare_T = detail::remove_cvref<T>;
227 BOOST_STATIC_ASSERT(detail::conversion_round_trips<
228 Context, bare_T, detail::value_to_conversion>::value);
229 using cat = detail::value_to_category<Context, bare_T>;
230 7106 return detail::value_to_impl(
231 7474 cat(), try_value_to_tag<bare_T>(), jv, ctx );
232 }
233
234 /** Convert a @ref value to a `boost::system::result<T>`.
235
236 This function attempts to convert a @ref value
237 to `result<T>` using
238
239 @li one of @ref value's accessors, or
240
241 @li a library-provided generic conversion, or
242
243 @li a user-provided overload of `tag_invoke`.
244
245 Out of the box the function supports types satisfying
246 <a href="https://en.cppreference.com/w/cpp/named_req/SequenceContainer"><em>SequenceContainer</em></a>,
247 arrays, arithmetic types, `bool`, `std::tuple`, `std::pair`,
248 `std::variant`, `std::optional`, `std::monostate`, and `std::nullopt_t`.
249
250 Conversion of other types is done by calling an overload of `tag_invoke`
251 found by argument-dependent lookup. Its signature should be similar to:
252
253 @code
254 result<T> tag_invoke( try_value_to_tag<T>, const value& );
255 @endcode
256
257 If an error occurs during conversion, the result will store the error code
258 associated with the error. If an exception is thrown, the function will
259 attempt to retrieve the associated error code and return it, otherwise it
260 will return `error::exception`, unless the exception type is
261 `std::bad_alloc`, which will be allowed to propagate.
262
263 @par Constraints
264 @code
265 ! std::is_reference< T >::value
266 @endcode
267
268 @par Exception Safety
269 Strong guarantee.
270
271 @tparam T The type to convert to.
272
273 @param jv The @ref value to convert.
274
275 @returns `jv` converted to `result<T>`.
276
277 @see @ref value_to_tag, @ref value_to, @ref value_from,
278 <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1895r0.pdf">
279 tag_invoke: A general pattern for supporting customisable functions</a>
280 */
281 template<class T>
282 typename result_for<T, value>::type
283 130 try_value_to(const value& jv)
284 {
285
1/1
✓ Branch 1 taken 4 times.
 163 return try_value_to<T>( jv, detail::no_context() );
286 }
287
288 /** Convert a @ref value to an object of type `T`.
289
290 This overload is **deleted** and participates in overload resolution only
291 when `U` is not @ref value. The overload exists to prevent unintented
292 creation of temporary @ref value instances, e.g.
293
294 @code
295 auto flag = value_to<bool>(true);
296 @endcode
297 */
298 template<class T, class U
299 #ifndef BOOST_JSON_DOCS
300 , class = typename std::enable_if<!std::is_same<U, value>::value>::type
301 #endif
302 >
303 T
304 value_to(U const& jv) = delete;
305
306 /** Determine a @ref value can be converted to `T`.
307
308 If @ref value can be converted to `T` via a
309 call to @ref value_to, the static data member `value`
310 is defined as `true`. Otherwise, `value` is
311 defined as `false`.
312
313 @see @ref value_to
314 */
315 #ifdef BOOST_JSON_DOCS
316 template<class T>
317 using has_value_to = __see_below__;
318 #else
319 template<class T>
320 using has_value_to = detail::can_convert<
321 detail::remove_cvref<T>, detail::value_to_conversion>;
322 #endif
323
324 } // namespace json
325 } // namespace boost
326
327 #endif
328