Front Haul Interface Library update to third seed code contribution
[o-du/phy.git] / fhi_lib / test / common / json.hpp
1 /*
2     __ _____ _____ _____
3  __|  |   __|     |   | |  JSON for Modern C++
4 |  |  |__   |  |  | | | |  version 2.1.1
5 |_____|_____|_____|_|___|  https://github.com/nlohmann/json
6
7 Licensed under the MIT License <http://opensource.org/licenses/MIT>.
8 Copyright (c) 2013-2017 Niels Lohmann <http://nlohmann.me>.
9
10 Permission is hereby  granted, free of charge, to any  person obtaining a copy
11 of this software and associated  documentation files (the "Software"), to deal
12 in the Software  without restriction, including without  limitation the rights
13 to  use, copy,  modify, merge,  publish, distribute,  sublicense, and/or  sell
14 copies  of  the Software,  and  to  permit persons  to  whom  the Software  is
15 furnished to do so, subject to the following conditions:
16
17 The above copyright notice and this permission notice shall be included in all
18 copies or substantial portions of the Software.
19
20 THE SOFTWARE  IS PROVIDED "AS  IS", WITHOUT WARRANTY  OF ANY KIND,  EXPRESS OR
21 IMPLIED,  INCLUDING BUT  NOT  LIMITED TO  THE  WARRANTIES OF  MERCHANTABILITY,
22 FITNESS FOR  A PARTICULAR PURPOSE AND  NONINFRINGEMENT. IN NO EVENT  SHALL THE
23 AUTHORS  OR COPYRIGHT  HOLDERS  BE  LIABLE FOR  ANY  CLAIM,  DAMAGES OR  OTHER
24 LIABILITY, WHETHER IN AN ACTION OF  CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25 OUT OF OR IN CONNECTION WITH THE SOFTWARE  OR THE USE OR OTHER DEALINGS IN THE
26 SOFTWARE.
27 */
28
29 #ifndef NLOHMANN_JSON_HPP
30 #define NLOHMANN_JSON_HPP
31
32 #include <algorithm> // all_of, copy, fill, find, for_each, none_of, remove, reverse, transform
33 #include <array> // array
34 #include <cassert> // assert
35 #include <cctype> // isdigit
36 #include <ciso646> // and, not, or
37 #include <cmath> // isfinite, labs, ldexp, signbit
38 #include <cstddef> // nullptr_t, ptrdiff_t, size_t
39 #include <cstdint> // int64_t, uint64_t
40 #include <cstdlib> // abort, strtod, strtof, strtold, strtoul, strtoll, strtoull
41 #include <cstring> // strlen
42 #include <forward_list> // forward_list
43 #include <functional> // function, hash, less
44 #include <initializer_list> // initializer_list
45 #include <iomanip> // setw
46 #include <iostream> // istream, ostream
47 #include <iterator> // advance, begin, back_inserter, bidirectional_iterator_tag, distance, end, inserter, iterator, iterator_traits, next, random_access_iterator_tag, reverse_iterator
48 #include <limits> // numeric_limits
49 #include <locale> // locale
50 #include <map> // map
51 #include <memory> // addressof, allocator, allocator_traits, unique_ptr
52 #include <numeric> // accumulate
53 #include <sstream> // stringstream
54 #include <stdexcept> // domain_error, invalid_argument, out_of_range
55 #include <string> // getline, stoi, string, to_string
56 #include <type_traits> // add_pointer, conditional, decay, enable_if, false_type, integral_constant, is_arithmetic, is_base_of, is_const, is_constructible, is_convertible, is_default_constructible, is_enum, is_floating_point, is_integral, is_nothrow_move_assignable, is_nothrow_move_constructible, is_pointer, is_reference, is_same, is_scalar, is_signed, remove_const, remove_cv, remove_pointer, remove_reference, true_type, underlying_type
57 #include <utility> // declval, forward, make_pair, move, pair, swap
58 #include <vector> // vector
59
60 // allow for portable deprecation warnings
61 #if defined(__clang__) || defined(__GNUC__) || defined(__GNUG__)
62     #define JSON_DEPRECATED __attribute__((deprecated))
63 #elif defined(_MSC_VER)
64     #define JSON_DEPRECATED __declspec(deprecated)
65 #else
66     #define JSON_DEPRECATED
67 #endif
68
69 // allow to disable exceptions
70 #if not defined(JSON_NOEXCEPTION) || defined(__EXCEPTIONS)
71     #define JSON_THROW(exception) throw exception
72     #define JSON_TRY try
73     #define JSON_CATCH(exception) catch(exception)
74 #else
75     #define JSON_THROW(exception) std::abort()
76     #define JSON_TRY if(true)
77     #define JSON_CATCH(exception) if(false)
78 #endif
79
80 /*!
81 @brief namespace for Niels Lohmann
82 @see https://github.com/nlohmann
83 @since version 1.0.0
84 */
85 namespace nlohmann
86 {
87
88 /*!
89 @brief unnamed namespace with internal helper functions
90
91 This namespace collects some functions that could not be defined inside the
92 @ref basic_json class.
93
94 @since version 2.1.0
95 */
96 namespace detail
97 {
98 ///////////////////////////
99 // JSON type enumeration //
100 ///////////////////////////
101
102 /*!
103 @brief the JSON type enumeration
104
105 This enumeration collects the different JSON types. It is internally used to
106 distinguish the stored values, and the functions @ref basic_json::is_null(),
107 @ref basic_json::is_object(), @ref basic_json::is_array(),
108 @ref basic_json::is_string(), @ref basic_json::is_boolean(),
109 @ref basic_json::is_number() (with @ref basic_json::is_number_integer(),
110 @ref basic_json::is_number_unsigned(), and @ref basic_json::is_number_float()),
111 @ref basic_json::is_discarded(), @ref basic_json::is_primitive(), and
112 @ref basic_json::is_structured() rely on it.
113
114 @note There are three enumeration entries (number_integer, number_unsigned, and
115 number_float), because the library distinguishes these three types for numbers:
116 @ref basic_json::number_unsigned_t is used for unsigned integers,
117 @ref basic_json::number_integer_t is used for signed integers, and
118 @ref basic_json::number_float_t is used for floating-point numbers or to
119 approximate integers which do not fit in the limits of their respective type.
120
121 @sa @ref basic_json::basic_json(const value_t value_type) -- create a JSON
122 value with the default value for a given type
123
124 @since version 1.0.0
125 */
126 enum class value_t : uint8_t
127 {
128     null,            ///< null value
129     object,          ///< object (unordered set of name/value pairs)
130     array,           ///< array (ordered collection of values)
131     string,          ///< string value
132     boolean,         ///< boolean value
133     number_integer,  ///< number value (signed integer)
134     number_unsigned, ///< number value (unsigned integer)
135     number_float,    ///< number value (floating-point)
136     discarded        ///< discarded by the the parser callback function
137 };
138
139 /*!
140 @brief comparison operator for JSON types
141
142 Returns an ordering that is similar to Python:
143 - order: null < boolean < number < object < array < string
144 - furthermore, each type is not smaller than itself
145
146 @since version 1.0.0
147 */
148 inline bool operator<(const value_t lhs, const value_t rhs) noexcept
149 {
150     static constexpr std::array<uint8_t, 8> order = {{
151             0, // null
152             3, // object
153             4, // array
154             5, // string
155             1, // boolean
156             2, // integer
157             2, // unsigned
158             2, // float
159         }
160     };
161
162     // discarded values are not comparable
163     if (lhs == value_t::discarded or rhs == value_t::discarded)
164     {
165         return false;
166     }
167
168     return order[static_cast<std::size_t>(lhs)] <
169            order[static_cast<std::size_t>(rhs)];
170 }
171
172
173 /////////////
174 // helpers //
175 /////////////
176
177 // alias templates to reduce boilerplate
178 template<bool B, typename T = void>
179 using enable_if_t = typename std::enable_if<B, T>::type;
180
181 template<typename T>
182 using uncvref_t = typename std::remove_cv<typename std::remove_reference<T>::type>::type;
183
184 // taken from http://stackoverflow.com/a/26936864/266378
185 template<typename T>
186 using is_unscoped_enum =
187     std::integral_constant<bool, std::is_convertible<T, int>::value and
188     std::is_enum<T>::value>;
189
190 /*
191 Implementation of two C++17 constructs: conjunction, negation. This is needed
192 to avoid evaluating all the traits in a condition
193
194 For example: not std::is_same<void, T>::value and has_value_type<T>::value
195 will not compile when T = void (on MSVC at least). Whereas
196 conjunction<negation<std::is_same<void, T>>, has_value_type<T>>::value will
197 stop evaluating if negation<...>::value == false
198
199 Please note that those constructs must be used with caution, since symbols can
200 become very long quickly (which can slow down compilation and cause MSVC
201 internal compiler errors). Only use it when you have to (see example ahead).
202 */
203 template<class...> struct conjunction : std::true_type {};
204 template<class B1> struct conjunction<B1> : B1 {};
205 template<class B1, class... Bn>
206 struct conjunction<B1, Bn...> : std::conditional<bool(B1::value), conjunction<Bn...>, B1>::type {};
207
208 template<class B> struct negation : std::integral_constant < bool, !B::value > {};
209
210 // dispatch utility (taken from ranges-v3)
211 template<unsigned N> struct priority_tag : priority_tag < N - 1 > {};
212 template<> struct priority_tag<0> {};
213
214
215 //////////////////
216 // constructors //
217 //////////////////
218
219 template<value_t> struct external_constructor;
220
221 template<>
222 struct external_constructor<value_t::boolean>
223 {
224     template<typename BasicJsonType>
225     static void construct(BasicJsonType& j, typename BasicJsonType::boolean_t b) noexcept
226     {
227         j.m_type = value_t::boolean;
228         j.m_value = b;
229         j.assert_invariant();
230     }
231 };
232
233 template<>
234 struct external_constructor<value_t::string>
235 {
236     template<typename BasicJsonType>
237     static void construct(BasicJsonType& j, const typename BasicJsonType::string_t& s)
238     {
239         j.m_type = value_t::string;
240         j.m_value = s;
241         j.assert_invariant();
242     }
243 };
244
245 template<>
246 struct external_constructor<value_t::number_float>
247 {
248     template<typename BasicJsonType>
249     static void construct(BasicJsonType& j, typename BasicJsonType::number_float_t val) noexcept
250     {
251         // replace infinity and NAN by null
252         if (not std::isfinite(val))
253         {
254             j = BasicJsonType{};
255         }
256         else
257         {
258             j.m_type = value_t::number_float;
259             j.m_value = val;
260         }
261         j.assert_invariant();
262     }
263 };
264
265 template<>
266 struct external_constructor<value_t::number_unsigned>
267 {
268     template<typename BasicJsonType>
269     static void construct(BasicJsonType& j, typename BasicJsonType::number_unsigned_t val) noexcept
270     {
271         j.m_type = value_t::number_unsigned;
272         j.m_value = val;
273         j.assert_invariant();
274     }
275 };
276
277 template<>
278 struct external_constructor<value_t::number_integer>
279 {
280     template<typename BasicJsonType>
281     static void construct(BasicJsonType& j, typename BasicJsonType::number_integer_t val) noexcept
282     {
283         j.m_type = value_t::number_integer;
284         j.m_value = val;
285         j.assert_invariant();
286     }
287 };
288
289 template<>
290 struct external_constructor<value_t::array>
291 {
292     template<typename BasicJsonType>
293     static void construct(BasicJsonType& j, const typename BasicJsonType::array_t& arr)
294     {
295         j.m_type = value_t::array;
296         j.m_value = arr;
297         j.assert_invariant();
298     }
299
300     template<typename BasicJsonType, typename CompatibleArrayType,
301              enable_if_t<not std::is_same<CompatibleArrayType,
302                                           typename BasicJsonType::array_t>::value,
303                          int> = 0>
304     static void construct(BasicJsonType& j, const CompatibleArrayType& arr)
305     {
306         using std::begin;
307         using std::end;
308         j.m_type = value_t::array;
309         j.m_value.array = j.template create<typename BasicJsonType::array_t>(begin(arr), end(arr));
310         j.assert_invariant();
311     }
312 };
313
314 template<>
315 struct external_constructor<value_t::object>
316 {
317     template<typename BasicJsonType>
318     static void construct(BasicJsonType& j, const typename BasicJsonType::object_t& obj)
319     {
320         j.m_type = value_t::object;
321         j.m_value = obj;
322         j.assert_invariant();
323     }
324
325     template<typename BasicJsonType, typename CompatibleObjectType,
326              enable_if_t<not std::is_same<CompatibleObjectType,
327                                           typename BasicJsonType::object_t>::value,
328                          int> = 0>
329     static void construct(BasicJsonType& j, const CompatibleObjectType& obj)
330     {
331         using std::begin;
332         using std::end;
333
334         j.m_type = value_t::object;
335         j.m_value.object = j.template create<typename BasicJsonType::object_t>(begin(obj), end(obj));
336         j.assert_invariant();
337     }
338 };
339
340
341 ////////////////////////
342 // has_/is_ functions //
343 ////////////////////////
344
345 /*!
346 @brief Helper to determine whether there's a key_type for T.
347
348 This helper is used to tell associative containers apart from other containers
349 such as sequence containers. For instance, `std::map` passes the test as it
350 contains a `mapped_type`, whereas `std::vector` fails the test.
351
352 @sa http://stackoverflow.com/a/7728728/266378
353 @since version 1.0.0, overworked in version 2.0.6
354 */
355 #define NLOHMANN_JSON_HAS_HELPER(type)                                        \
356     template<typename T> struct has_##type {                                  \
357     private:                                                                  \
358         template<typename U, typename = typename U::type>                     \
359         static int detect(U &&);                                              \
360         static void detect(...);                                              \
361     public:                                                                   \
362         static constexpr bool value =                                         \
363                 std::is_integral<decltype(detect(std::declval<T>()))>::value; \
364     }
365
366 NLOHMANN_JSON_HAS_HELPER(mapped_type);
367 NLOHMANN_JSON_HAS_HELPER(key_type);
368 NLOHMANN_JSON_HAS_HELPER(value_type);
369 NLOHMANN_JSON_HAS_HELPER(iterator);
370
371 #undef NLOHMANN_JSON_HAS_HELPER
372
373
374 template<bool B, class RealType, class CompatibleObjectType>
375 struct is_compatible_object_type_impl : std::false_type {};
376
377 template<class RealType, class CompatibleObjectType>
378 struct is_compatible_object_type_impl<true, RealType, CompatibleObjectType>
379 {
380     static constexpr auto value =
381         std::is_constructible<typename RealType::key_type,
382         typename CompatibleObjectType::key_type>::value and
383         std::is_constructible<typename RealType::mapped_type,
384         typename CompatibleObjectType::mapped_type>::value;
385 };
386
387 template<class BasicJsonType, class CompatibleObjectType>
388 struct is_compatible_object_type
389 {
390     static auto constexpr value = is_compatible_object_type_impl <
391                                   conjunction<negation<std::is_same<void, CompatibleObjectType>>,
392                                   has_mapped_type<CompatibleObjectType>,
393                                   has_key_type<CompatibleObjectType>>::value,
394                                   typename BasicJsonType::object_t, CompatibleObjectType >::value;
395 };
396
397 template<typename BasicJsonType, typename T>
398 struct is_basic_json_nested_type
399 {
400     static auto constexpr value = std::is_same<T, typename BasicJsonType::iterator>::value or
401                                   std::is_same<T, typename BasicJsonType::const_iterator>::value or
402                                   std::is_same<T, typename BasicJsonType::reverse_iterator>::value or
403                                   std::is_same<T, typename BasicJsonType::const_reverse_iterator>::value or
404                                   std::is_same<T, typename BasicJsonType::json_pointer>::value;
405 };
406
407 template<class BasicJsonType, class CompatibleArrayType>
408 struct is_compatible_array_type
409 {
410     static auto constexpr value =
411         conjunction<negation<std::is_same<void, CompatibleArrayType>>,
412         negation<is_compatible_object_type<
413         BasicJsonType, CompatibleArrayType>>,
414         negation<std::is_constructible<typename BasicJsonType::string_t,
415         CompatibleArrayType>>,
416         negation<is_basic_json_nested_type<BasicJsonType, CompatibleArrayType>>,
417         has_value_type<CompatibleArrayType>,
418         has_iterator<CompatibleArrayType>>::value;
419 };
420
421 template<bool, typename, typename>
422 struct is_compatible_integer_type_impl : std::false_type {};
423
424 template<typename RealIntegerType, typename CompatibleNumberIntegerType>
425 struct is_compatible_integer_type_impl<true, RealIntegerType, CompatibleNumberIntegerType>
426 {
427     // is there an assert somewhere on overflows?
428     using RealLimits = std::numeric_limits<RealIntegerType>;
429     using CompatibleLimits = std::numeric_limits<CompatibleNumberIntegerType>;
430
431     static constexpr auto value =
432         std::is_constructible<RealIntegerType,
433         CompatibleNumberIntegerType>::value and
434         CompatibleLimits::is_integer and
435         RealLimits::is_signed == CompatibleLimits::is_signed;
436 };
437
438 template<typename RealIntegerType, typename CompatibleNumberIntegerType>
439 struct is_compatible_integer_type
440 {
441     static constexpr auto value =
442         is_compatible_integer_type_impl <
443         std::is_integral<CompatibleNumberIntegerType>::value and
444         not std::is_same<bool, CompatibleNumberIntegerType>::value,
445         RealIntegerType, CompatibleNumberIntegerType > ::value;
446 };
447
448
449 // trait checking if JSONSerializer<T>::from_json(json const&, udt&) exists
450 template<typename BasicJsonType, typename T>
451 struct has_from_json
452 {
453   private:
454     // also check the return type of from_json
455     template<typename U, typename = enable_if_t<std::is_same<void, decltype(uncvref_t<U>::from_json(
456                  std::declval<BasicJsonType>(), std::declval<T&>()))>::value>>
457     static int detect(U&&);
458     static void detect(...);
459
460   public:
461     static constexpr bool value = std::is_integral<decltype(
462                                       detect(std::declval<typename BasicJsonType::template json_serializer<T, void > >()))>::value;
463 };
464
465 // This trait checks if JSONSerializer<T>::from_json(json const&) exists
466 // this overload is used for non-default-constructible user-defined-types
467 template<typename BasicJsonType, typename T>
468 struct has_non_default_from_json
469 {
470   private:
471     template <
472         typename U,
473         typename = enable_if_t<std::is_same<
474                                    T, decltype(uncvref_t<U>::from_json(std::declval<BasicJsonType>()))>::value >>
475     static int detect(U&&);
476     static void detect(...);
477
478   public:
479     static constexpr bool value = std::is_integral<decltype(detect(
480                                       std::declval<typename BasicJsonType::template json_serializer<T, void> >()))>::value;
481 };
482
483 // This trait checks if BasicJsonType::json_serializer<T>::to_json exists
484 template<typename BasicJsonType, typename T>
485 struct has_to_json
486 {
487   private:
488     template<typename U, typename = decltype(uncvref_t<U>::to_json(
489                  std::declval<BasicJsonType&>(), std::declval<T>()))>
490     static int detect(U&&);
491     static void detect(...);
492
493   public:
494     static constexpr bool value = std::is_integral<decltype(detect(
495                                       std::declval<typename BasicJsonType::template json_serializer<T, void> >()))>::value;
496 };
497
498
499 /////////////
500 // to_json //
501 /////////////
502
503 template<typename BasicJsonType, typename T, enable_if_t<
504              std::is_same<T, typename BasicJsonType::boolean_t>::value, int> = 0>
505 void to_json(BasicJsonType& j, T b) noexcept
506 {
507     external_constructor<value_t::boolean>::construct(j, b);
508 }
509
510 template<typename BasicJsonType, typename CompatibleString,
511          enable_if_t<std::is_constructible<typename BasicJsonType::string_t,
512                      CompatibleString>::value, int> = 0>
513 void to_json(BasicJsonType& j, const CompatibleString& s)
514 {
515     external_constructor<value_t::string>::construct(j, s);
516 }
517
518 template<typename BasicJsonType, typename FloatType,
519          enable_if_t<std::is_floating_point<FloatType>::value, int> = 0>
520 void to_json(BasicJsonType& j, FloatType val) noexcept
521 {
522     external_constructor<value_t::number_float>::construct(j, static_cast<typename BasicJsonType::number_float_t>(val));
523 }
524
525 template <
526     typename BasicJsonType, typename CompatibleNumberUnsignedType,
527     enable_if_t<is_compatible_integer_type<typename BasicJsonType::number_unsigned_t,
528                 CompatibleNumberUnsignedType>::value, int> = 0 >
529 void to_json(BasicJsonType& j, CompatibleNumberUnsignedType val) noexcept
530 {
531     external_constructor<value_t::number_unsigned>::construct(j, static_cast<typename BasicJsonType::number_unsigned_t>(val));
532 }
533
534 template <
535     typename BasicJsonType, typename CompatibleNumberIntegerType,
536     enable_if_t<is_compatible_integer_type<typename BasicJsonType::number_integer_t,
537                 CompatibleNumberIntegerType>::value, int> = 0 >
538 void to_json(BasicJsonType& j, CompatibleNumberIntegerType val) noexcept
539 {
540     external_constructor<value_t::number_integer>::construct(j, static_cast<typename BasicJsonType::number_integer_t>(val));
541 }
542
543 template<typename BasicJsonType, typename UnscopedEnumType,
544          enable_if_t<is_unscoped_enum<UnscopedEnumType>::value, int> = 0>
545 void to_json(BasicJsonType& j, UnscopedEnumType e) noexcept
546 {
547     external_constructor<value_t::number_integer>::construct(j, e);
548 }
549
550 template <
551     typename BasicJsonType, typename CompatibleArrayType,
552     enable_if_t <
553         is_compatible_array_type<BasicJsonType, CompatibleArrayType>::value or
554         std::is_same<typename BasicJsonType::array_t, CompatibleArrayType>::value,
555         int > = 0 >
556 void to_json(BasicJsonType& j, const  CompatibleArrayType& arr)
557 {
558     external_constructor<value_t::array>::construct(j, arr);
559 }
560
561 template <
562     typename BasicJsonType, typename CompatibleObjectType,
563     enable_if_t<is_compatible_object_type<BasicJsonType, CompatibleObjectType>::value,
564                 int> = 0 >
565 void to_json(BasicJsonType& j, const  CompatibleObjectType& arr)
566 {
567     external_constructor<value_t::object>::construct(j, arr);
568 }
569
570
571 ///////////////
572 // from_json //
573 ///////////////
574
575 // overloads for basic_json template parameters
576 template<typename BasicJsonType, typename ArithmeticType,
577          enable_if_t<std::is_arithmetic<ArithmeticType>::value and
578                      not std::is_same<ArithmeticType,
579                                       typename BasicJsonType::boolean_t>::value,
580                      int> = 0>
581 void get_arithmetic_value(const BasicJsonType& j, ArithmeticType& val)
582 {
583     switch (static_cast<value_t>(j))
584     {
585         case value_t::number_unsigned:
586         {
587             val = static_cast<ArithmeticType>(
588                       *j.template get_ptr<const typename BasicJsonType::number_unsigned_t*>());
589             break;
590         }
591         case value_t::number_integer:
592         {
593             val = static_cast<ArithmeticType>(
594                       *j.template get_ptr<const typename BasicJsonType::number_integer_t*>());
595             break;
596         }
597         case value_t::number_float:
598         {
599             val = static_cast<ArithmeticType>(
600                       *j.template get_ptr<const typename BasicJsonType::number_float_t*>());
601             break;
602         }
603         default:
604         {
605             JSON_THROW(
606                 std::domain_error("type must be number, but is " + j.type_name()));
607         }
608     }
609 }
610
611 template<typename BasicJsonType>
612 void from_json(const BasicJsonType& j, typename BasicJsonType::boolean_t& b)
613 {
614     if (not j.is_boolean())
615     {
616         JSON_THROW(std::domain_error("type must be boolean, but is " + j.type_name()));
617     }
618     b = *j.template get_ptr<const typename BasicJsonType::boolean_t*>();
619 }
620
621 template<typename BasicJsonType>
622 void from_json(const BasicJsonType& j, typename BasicJsonType::string_t& s)
623 {
624     if (not j.is_string())
625     {
626         JSON_THROW(std::domain_error("type must be string, but is " + j.type_name()));
627     }
628     s = *j.template get_ptr<const typename BasicJsonType::string_t*>();
629 }
630
631 template<typename BasicJsonType>
632 void from_json(const BasicJsonType& j, typename BasicJsonType::number_float_t& val)
633 {
634     get_arithmetic_value(j, val);
635 }
636
637 template<typename BasicJsonType>
638 void from_json(const BasicJsonType& j, typename BasicJsonType::number_unsigned_t& val)
639 {
640     get_arithmetic_value(j, val);
641 }
642
643 template<typename BasicJsonType>
644 void from_json(const BasicJsonType& j, typename BasicJsonType::number_integer_t& val)
645 {
646     get_arithmetic_value(j, val);
647 }
648
649 template<typename BasicJsonType, typename UnscopedEnumType,
650          enable_if_t<is_unscoped_enum<UnscopedEnumType>::value, int> = 0>
651 void from_json(const BasicJsonType& j, UnscopedEnumType& e)
652 {
653     typename std::underlying_type<UnscopedEnumType>::type val;
654     get_arithmetic_value(j, val);
655     e = static_cast<UnscopedEnumType>(val);
656 }
657
658 template<typename BasicJsonType>
659 void from_json(const BasicJsonType& j, typename BasicJsonType::array_t& arr)
660 {
661     if (not j.is_array())
662     {
663         JSON_THROW(std::domain_error("type must be array, but is " + j.type_name()));
664     }
665     arr = *j.template get_ptr<const typename BasicJsonType::array_t*>();
666 }
667
668 // forward_list doesn't have an insert method
669 template<typename BasicJsonType, typename T, typename Allocator>
670 void from_json(const BasicJsonType& j, std::forward_list<T, Allocator>& l)
671 {
672     // do not perform the check when user wants to retrieve jsons
673     // (except when it's null.. ?)
674     if (j.is_null())
675     {
676         JSON_THROW(std::domain_error("type must be array, but is " + j.type_name()));
677     }
678     if (not std::is_same<T, BasicJsonType>::value)
679     {
680         if (not j.is_array())
681         {
682             JSON_THROW(std::domain_error("type must be array, but is " + j.type_name()));
683         }
684     }
685     for (auto it = j.rbegin(), end = j.rend(); it != end; ++it)
686     {
687         l.push_front(it->template get<T>());
688     }
689 }
690
691 template<typename BasicJsonType, typename CompatibleArrayType>
692 void from_json_array_impl(const BasicJsonType& j, CompatibleArrayType& arr, priority_tag<0>)
693 {
694     using std::begin;
695     using std::end;
696
697     std::transform(j.begin(), j.end(),
698                    std::inserter(arr, end(arr)), [](const BasicJsonType & i)
699     {
700         // get<BasicJsonType>() returns *this, this won't call a from_json
701         // method when value_type is BasicJsonType
702         return i.template get<typename CompatibleArrayType::value_type>();
703     });
704 }
705
706 template<typename BasicJsonType, typename CompatibleArrayType>
707 auto from_json_array_impl(const BasicJsonType& j, CompatibleArrayType& arr, priority_tag<1>)
708 -> decltype(
709     arr.reserve(std::declval<typename CompatibleArrayType::size_type>()),
710     void())
711 {
712     using std::begin;
713     using std::end;
714
715     arr.reserve(j.size());
716     std::transform(
717         j.begin(), j.end(), std::inserter(arr, end(arr)), [](const BasicJsonType & i)
718     {
719         // get<BasicJsonType>() returns *this, this won't call a from_json
720         // method when value_type is BasicJsonType
721         return i.template get<typename CompatibleArrayType::value_type>();
722     });
723 }
724
725 template<typename BasicJsonType, typename CompatibleArrayType,
726          enable_if_t<is_compatible_array_type<BasicJsonType, CompatibleArrayType>::value and
727                      not std::is_same<typename BasicJsonType::array_t, CompatibleArrayType>::value, int> = 0>
728 void from_json(const BasicJsonType& j, CompatibleArrayType& arr)
729 {
730     if (j.is_null())
731     {
732         JSON_THROW(std::domain_error("type must be array, but is " + j.type_name()));
733     }
734
735     // when T == BasicJsonType, do not check if value_t is correct
736     if (not std::is_same<typename CompatibleArrayType::value_type, BasicJsonType>::value)
737     {
738         if (not j.is_array())
739         {
740             JSON_THROW(std::domain_error("type must be array, but is " + j.type_name()));
741         }
742     }
743     from_json_array_impl(j, arr, priority_tag<1> {});
744 }
745
746 template<typename BasicJsonType, typename CompatibleObjectType,
747          enable_if_t<is_compatible_object_type<BasicJsonType, CompatibleObjectType>::value, int> = 0>
748 void from_json(const BasicJsonType& j, CompatibleObjectType& obj)
749 {
750     if (not j.is_object())
751     {
752         JSON_THROW(std::domain_error("type must be object, but is " + j.type_name()));
753     }
754
755     auto inner_object = j.template get_ptr<const typename BasicJsonType::object_t*>();
756     using std::begin;
757     using std::end;
758     // we could avoid the assignment, but this might require a for loop, which
759     // might be less efficient than the container constructor for some
760     // containers (would it?)
761     obj = CompatibleObjectType(begin(*inner_object), end(*inner_object));
762 }
763
764 // overload for arithmetic types, not chosen for basic_json template arguments
765 // (BooleanType, etc..); note: Is it really necessary to provide explicit
766 // overloads for boolean_t etc. in case of a custom BooleanType which is not
767 // an arithmetic type?
768 template<typename BasicJsonType, typename ArithmeticType,
769          enable_if_t <
770              std::is_arithmetic<ArithmeticType>::value and
771              not std::is_same<ArithmeticType, typename BasicJsonType::number_unsigned_t>::value and
772              not std::is_same<ArithmeticType, typename BasicJsonType::number_integer_t>::value and
773              not std::is_same<ArithmeticType, typename BasicJsonType::number_float_t>::value and
774              not std::is_same<ArithmeticType, typename BasicJsonType::boolean_t>::value,
775              int> = 0>
776 void from_json(const BasicJsonType& j, ArithmeticType& val)
777 {
778     switch (static_cast<value_t>(j))
779     {
780         case value_t::number_unsigned:
781         {
782             val = static_cast<ArithmeticType>(*j.template get_ptr<const typename BasicJsonType::number_unsigned_t*>());
783             break;
784         }
785         case value_t::number_integer:
786         {
787             val = static_cast<ArithmeticType>(*j.template get_ptr<const typename BasicJsonType::number_integer_t*>());
788             break;
789         }
790         case value_t::number_float:
791         {
792             val = static_cast<ArithmeticType>(*j.template get_ptr<const typename BasicJsonType::number_float_t*>());
793             break;
794         }
795         case value_t::boolean:
796         {
797             val = static_cast<ArithmeticType>(*j.template get_ptr<const typename BasicJsonType::boolean_t*>());
798             break;
799         }
800         default:
801         {
802             JSON_THROW(std::domain_error("type must be number, but is " + j.type_name()));
803         }
804     }
805 }
806
807 struct to_json_fn
808 {
809   private:
810     template<typename BasicJsonType, typename T>
811     auto call(BasicJsonType& j, T&& val, priority_tag<1>) const noexcept(noexcept(to_json(j, std::forward<T>(val))))
812     -> decltype(to_json(j, std::forward<T>(val)), void())
813     {
814         return to_json(j, std::forward<T>(val));
815     }
816
817     template<typename BasicJsonType, typename T>
818     void call(BasicJsonType&, T&&, priority_tag<0>) const noexcept
819     {
820         static_assert(sizeof(BasicJsonType) == 0,
821                       "could not find to_json() method in T's namespace");
822     }
823
824   public:
825     template<typename BasicJsonType, typename T>
826     void operator()(BasicJsonType& j, T&& val) const
827     noexcept(noexcept(std::declval<to_json_fn>().call(j, std::forward<T>(val), priority_tag<1> {})))
828     {
829         return call(j, std::forward<T>(val), priority_tag<1> {});
830     }
831 };
832
833 struct from_json_fn
834 {
835   private:
836     template<typename BasicJsonType, typename T>
837     auto call(const BasicJsonType& j, T& val, priority_tag<1>) const
838     noexcept(noexcept(from_json(j, val)))
839     -> decltype(from_json(j, val), void())
840     {
841         return from_json(j, val);
842     }
843
844     template<typename BasicJsonType, typename T>
845     void call(const BasicJsonType&, T&, priority_tag<0>) const noexcept
846     {
847         static_assert(sizeof(BasicJsonType) == 0,
848                       "could not find from_json() method in T's namespace");
849     }
850
851   public:
852     template<typename BasicJsonType, typename T>
853     void operator()(const BasicJsonType& j, T& val) const
854     noexcept(noexcept(std::declval<from_json_fn>().call(j, val, priority_tag<1> {})))
855     {
856         return call(j, val, priority_tag<1> {});
857     }
858 };
859
860 // taken from ranges-v3
861 template<typename T>
862 struct static_const
863 {
864     static constexpr T value{};
865 };
866
867 template<typename T>
868 constexpr T static_const<T>::value;
869 } // namespace detail
870
871
872 /// namespace to hold default `to_json` / `from_json` functions
873 namespace
874 {
875 constexpr const auto& to_json = detail::static_const<detail::to_json_fn>::value;
876 constexpr const auto& from_json = detail::static_const<detail::from_json_fn>::value;
877 }
878
879
880 /*!
881 @brief default JSONSerializer template argument
882
883 This serializer ignores the template arguments and uses ADL
884 ([argument-dependent lookup](http://en.cppreference.com/w/cpp/language/adl))
885 for serialization.
886 */
887 template<typename = void, typename = void>
888 struct adl_serializer
889 {
890     /*!
891     @brief convert a JSON value to any value type
892
893     This function is usually called by the `get()` function of the
894     @ref basic_json class (either explicit or via conversion operators).
895
896     @param[in] j         JSON value to read from
897     @param[in,out] val  value to write to
898     */
899     template<typename BasicJsonType, typename ValueType>
900     static void from_json(BasicJsonType&& j, ValueType& val) noexcept(
901         noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), val)))
902     {
903         ::nlohmann::from_json(std::forward<BasicJsonType>(j), val);
904     }
905
906     /*!
907     @brief convert any value type to a JSON value
908
909     This function is usually called by the constructors of the @ref basic_json
910     class.
911
912     @param[in,out] j  JSON value to write to
913     @param[in] val     value to read from
914     */
915     template<typename BasicJsonType, typename ValueType>
916     static void to_json(BasicJsonType& j, ValueType&& val) noexcept(
917         noexcept(::nlohmann::to_json(j, std::forward<ValueType>(val))))
918     {
919         ::nlohmann::to_json(j, std::forward<ValueType>(val));
920     }
921 };
922
923
924 /*!
925 @brief a class to store JSON values
926
927 @tparam ObjectType type for JSON objects (`std::map` by default; will be used
928 in @ref object_t)
929 @tparam ArrayType type for JSON arrays (`std::vector` by default; will be used
930 in @ref array_t)
931 @tparam StringType type for JSON strings and object keys (`std::string` by
932 default; will be used in @ref string_t)
933 @tparam BooleanType type for JSON booleans (`bool` by default; will be used
934 in @ref boolean_t)
935 @tparam NumberIntegerType type for JSON integer numbers (`int64_t` by
936 default; will be used in @ref number_integer_t)
937 @tparam NumberUnsignedType type for JSON unsigned integer numbers (@c
938 `uint64_t` by default; will be used in @ref number_unsigned_t)
939 @tparam NumberFloatType type for JSON floating-point numbers (`double` by
940 default; will be used in @ref number_float_t)
941 @tparam AllocatorType type of the allocator to use (`std::allocator` by
942 default)
943 @tparam JSONSerializer the serializer to resolve internal calls to `to_json()`
944 and `from_json()` (@ref adl_serializer by default)
945
946 @requirement The class satisfies the following concept requirements:
947 - Basic
948  - [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible):
949    JSON values can be default constructed. The result will be a JSON null
950    value.
951  - [MoveConstructible](http://en.cppreference.com/w/cpp/concept/MoveConstructible):
952    A JSON value can be constructed from an rvalue argument.
953  - [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible):
954    A JSON value can be copy-constructed from an lvalue expression.
955  - [MoveAssignable](http://en.cppreference.com/w/cpp/concept/MoveAssignable):
956    A JSON value van be assigned from an rvalue argument.
957  - [CopyAssignable](http://en.cppreference.com/w/cpp/concept/CopyAssignable):
958    A JSON value can be copy-assigned from an lvalue expression.
959  - [Destructible](http://en.cppreference.com/w/cpp/concept/Destructible):
960    JSON values can be destructed.
961 - Layout
962  - [StandardLayoutType](http://en.cppreference.com/w/cpp/concept/StandardLayoutType):
963    JSON values have
964    [standard layout](http://en.cppreference.com/w/cpp/language/data_members#Standard_layout):
965    All non-static data members are private and standard layout types, the
966    class has no virtual functions or (virtual) base classes.
967 - Library-wide
968  - [EqualityComparable](http://en.cppreference.com/w/cpp/concept/EqualityComparable):
969    JSON values can be compared with `==`, see @ref
970    operator==(const_reference,const_reference).
971  - [LessThanComparable](http://en.cppreference.com/w/cpp/concept/LessThanComparable):
972    JSON values can be compared with `<`, see @ref
973    operator<(const_reference,const_reference).
974  - [Swappable](http://en.cppreference.com/w/cpp/concept/Swappable):
975    Any JSON lvalue or rvalue of can be swapped with any lvalue or rvalue of
976    other compatible types, using unqualified function call @ref swap().
977  - [NullablePointer](http://en.cppreference.com/w/cpp/concept/NullablePointer):
978    JSON values can be compared against `std::nullptr_t` objects which are used
979    to model the `null` value.
980 - Container
981  - [Container](http://en.cppreference.com/w/cpp/concept/Container):
982    JSON values can be used like STL containers and provide iterator access.
983  - [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer);
984    JSON values can be used like STL containers and provide reverse iterator
985    access.
986
987 @invariant The member variables @a m_value and @a m_type have the following
988 relationship:
989 - If `m_type == value_t::object`, then `m_value.object != nullptr`.
990 - If `m_type == value_t::array`, then `m_value.array != nullptr`.
991 - If `m_type == value_t::string`, then `m_value.string != nullptr`.
992 The invariants are checked by member function assert_invariant().
993
994 @internal
995 @note ObjectType trick from http://stackoverflow.com/a/9860911
996 @endinternal
997
998 @see [RFC 7159: The JavaScript Object Notation (JSON) Data Interchange
999 Format](http://rfc7159.net/rfc7159)
1000
1001 @since version 1.0.0
1002
1003 @nosubgrouping
1004 */
1005 template <
1006     template<typename U, typename V, typename... Args> class ObjectType = std::map,
1007     template<typename U, typename... Args> class ArrayType = std::vector,
1008     class StringType = std::string,
1009     class BooleanType = bool,
1010     class NumberIntegerType = std::int64_t,
1011     class NumberUnsignedType = std::uint64_t,
1012     class NumberFloatType = double,
1013     template<typename U> class AllocatorType = std::allocator,
1014     template<typename T, typename SFINAE = void> class JSONSerializer = adl_serializer
1015     >
1016 class basic_json
1017 {
1018   private:
1019     template<detail::value_t> friend struct detail::external_constructor;
1020     /// workaround type for MSVC
1021     using basic_json_t = basic_json<ObjectType, ArrayType, StringType,
1022           BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType,
1023           AllocatorType, JSONSerializer>;
1024
1025   public:
1026     using value_t = detail::value_t;
1027     // forward declarations
1028     template<typename U> class iter_impl;
1029     template<typename Base> class json_reverse_iterator;
1030     class json_pointer;
1031     template<typename T, typename SFINAE>
1032     using json_serializer = JSONSerializer<T, SFINAE>;
1033
1034     /////////////////////
1035     // container types //
1036     /////////////////////
1037
1038     /// @name container types
1039     /// The canonic container types to use @ref basic_json like any other STL
1040     /// container.
1041     /// @{
1042
1043     /// the type of elements in a basic_json container
1044     using value_type = basic_json;
1045
1046     /// the type of an element reference
1047     using reference = value_type&;
1048     /// the type of an element const reference
1049     using const_reference = const value_type&;
1050
1051     /// a type to represent differences between iterators
1052     using difference_type = std::ptrdiff_t;
1053     /// a type to represent container sizes
1054     using size_type = std::size_t;
1055
1056     /// the allocator type
1057     using allocator_type = AllocatorType<basic_json>;
1058
1059     /// the type of an element pointer
1060     using pointer = typename std::allocator_traits<allocator_type>::pointer;
1061     /// the type of an element const pointer
1062     using const_pointer = typename std::allocator_traits<allocator_type>::const_pointer;
1063
1064     /// an iterator for a basic_json container
1065     using iterator = iter_impl<basic_json>;
1066     /// a const iterator for a basic_json container
1067     using const_iterator = iter_impl<const basic_json>;
1068     /// a reverse iterator for a basic_json container
1069     using reverse_iterator = json_reverse_iterator<typename basic_json::iterator>;
1070     /// a const reverse iterator for a basic_json container
1071     using const_reverse_iterator = json_reverse_iterator<typename basic_json::const_iterator>;
1072
1073     /// @}
1074
1075
1076     /*!
1077     @brief returns the allocator associated with the container
1078     */
1079     static allocator_type get_allocator()
1080     {
1081         return allocator_type();
1082     }
1083
1084     /*!
1085     @brief returns version information on the library
1086
1087     This function returns a JSON object with information about the library,
1088     including the version number and information on the platform and compiler.
1089
1090     @return JSON object holding version information
1091     key         | description
1092     ----------- | ---------------
1093     `compiler`  | Information on the used compiler. It is an object with the following keys: `c++` (the used C++ standard), `family` (the compiler family; possible values are `clang`, `icc`, `gcc`, `ilecpp`, `msvc`, `pgcpp`, `sunpro`, and `unknown`), and `version` (the compiler version).
1094     `copyright` | The copyright line for the library as string.
1095     `name`      | The name of the library as string.
1096     `platform`  | The used platform as string. Possible values are `win32`, `linux`, `apple`, `unix`, and `unknown`.
1097     `url`       | The URL of the project as string.
1098     `version`   | The version of the library. It is an object with the following keys: `major`, `minor`, and `patch` as defined by [Semantic Versioning](http://semver.org), and `string` (the version string).
1099
1100     @liveexample{The following code shows an example output of the `meta()`
1101     function.,meta}
1102
1103     @complexity Constant.
1104
1105     @since 2.1.0
1106     */
1107     static basic_json meta()
1108     {
1109         basic_json result;
1110
1111         result["copyright"] = "(C) 2013-2017 Niels Lohmann";
1112         result["name"] = "JSON for Modern C++";
1113         result["url"] = "https://github.com/nlohmann/json";
1114         result["version"] =
1115         {
1116             {"string", "2.1.1"},
1117             {"major", 2},
1118             {"minor", 1},
1119             {"patch", 1}
1120         };
1121
1122 #ifdef _WIN32
1123         result["platform"] = "win32";
1124 #elif defined __linux__
1125         result["platform"] = "linux";
1126 #elif defined __APPLE__
1127         result["platform"] = "apple";
1128 #elif defined __unix__
1129         result["platform"] = "unix";
1130 #else
1131         result["platform"] = "unknown";
1132 #endif
1133
1134 #if defined(__clang__)
1135         result["compiler"] = {{"family", "clang"}, {"version", __clang_version__}};
1136 #elif defined(__ICC) || defined(__INTEL_COMPILER)
1137         result["compiler"] = {{"family", "icc"}, {"version", __INTEL_COMPILER}};
1138 #elif defined(__GNUC__) || defined(__GNUG__)
1139         result["compiler"] = {{"family", "gcc"}, {"version", std::to_string(__GNUC__) + "." + std::to_string(__GNUC_MINOR__) + "." + std::to_string(__GNUC_PATCHLEVEL__)}};
1140 #elif defined(__HP_cc) || defined(__HP_aCC)
1141         result["compiler"] = "hp"
1142 #elif defined(__IBMCPP__)
1143         result["compiler"] = {{"family", "ilecpp"}, {"version", __IBMCPP__}};
1144 #elif defined(_MSC_VER)
1145         result["compiler"] = {{"family", "msvc"}, {"version", _MSC_VER}};
1146 #elif defined(__PGI)
1147         result["compiler"] = {{"family", "pgcpp"}, {"version", __PGI}};
1148 #elif defined(__SUNPRO_CC)
1149         result["compiler"] = {{"family", "sunpro"}, {"version", __SUNPRO_CC}};
1150 #else
1151         result["compiler"] = {{"family", "unknown"}, {"version", "unknown"}};
1152 #endif
1153
1154 #ifdef __cplusplus
1155         result["compiler"]["c++"] = std::to_string(__cplusplus);
1156 #else
1157         result["compiler"]["c++"] = "unknown";
1158 #endif
1159         return result;
1160     }
1161
1162
1163     ///////////////////////////
1164     // JSON value data types //
1165     ///////////////////////////
1166
1167     /// @name JSON value data types
1168     /// The data types to store a JSON value. These types are derived from
1169     /// the template arguments passed to class @ref basic_json.
1170     /// @{
1171
1172     /*!
1173     @brief a type for an object
1174
1175     [RFC 7159](http://rfc7159.net/rfc7159) describes JSON objects as follows:
1176     > An object is an unordered collection of zero or more name/value pairs,
1177     > where a name is a string and a value is a string, number, boolean, null,
1178     > object, or array.
1179
1180     To store objects in C++, a type is defined by the template parameters
1181     described below.
1182
1183     @tparam ObjectType  the container to store objects (e.g., `std::map` or
1184     `std::unordered_map`)
1185     @tparam StringType the type of the keys or names (e.g., `std::string`).
1186     The comparison function `std::less<StringType>` is used to order elements
1187     inside the container.
1188     @tparam AllocatorType the allocator to use for objects (e.g.,
1189     `std::allocator`)
1190
1191     #### Default type
1192
1193     With the default values for @a ObjectType (`std::map`), @a StringType
1194     (`std::string`), and @a AllocatorType (`std::allocator`), the default
1195     value for @a object_t is:
1196
1197     @code {.cpp}
1198     std::map<
1199       std::string, // key_type
1200       basic_json, // value_type
1201       std::less<std::string>, // key_compare
1202       std::allocator<std::pair<const std::string, basic_json>> // allocator_type
1203     >
1204     @endcode
1205
1206     #### Behavior
1207
1208     The choice of @a object_t influences the behavior of the JSON class. With
1209     the default type, objects have the following behavior:
1210
1211     - When all names are unique, objects will be interoperable in the sense
1212       that all software implementations receiving that object will agree on
1213       the name-value mappings.
1214     - When the names within an object are not unique, later stored name/value
1215       pairs overwrite previously stored name/value pairs, leaving the used
1216       names unique. For instance, `{"key": 1}` and `{"key": 2, "key": 1}` will
1217       be treated as equal and both stored as `{"key": 1}`.
1218     - Internally, name/value pairs are stored in lexicographical order of the
1219       names. Objects will also be serialized (see @ref dump) in this order.
1220       For instance, `{"b": 1, "a": 2}` and `{"a": 2, "b": 1}` will be stored
1221       and serialized as `{"a": 2, "b": 1}`.
1222     - When comparing objects, the order of the name/value pairs is irrelevant.
1223       This makes objects interoperable in the sense that they will not be
1224       affected by these differences. For instance, `{"b": 1, "a": 2}` and
1225       `{"a": 2, "b": 1}` will be treated as equal.
1226
1227     #### Limits
1228
1229     [RFC 7159](http://rfc7159.net/rfc7159) specifies:
1230     > An implementation may set limits on the maximum depth of nesting.
1231
1232     In this class, the object's limit of nesting is not constraint explicitly.
1233     However, a maximum depth of nesting may be introduced by the compiler or
1234     runtime environment. A theoretical limit can be queried by calling the
1235     @ref max_size function of a JSON object.
1236
1237     #### Storage
1238
1239     Objects are stored as pointers in a @ref basic_json type. That is, for any
1240     access to object values, a pointer of type `object_t*` must be
1241     dereferenced.
1242
1243     @sa @ref array_t -- type for an array value
1244
1245     @since version 1.0.0
1246
1247     @note The order name/value pairs are added to the object is *not*
1248     preserved by the library. Therefore, iterating an object may return
1249     name/value pairs in a different order than they were originally stored. In
1250     fact, keys will be traversed in alphabetical order as `std::map` with
1251     `std::less` is used by default. Please note this behavior conforms to [RFC
1252     7159](http://rfc7159.net/rfc7159), because any order implements the
1253     specified "unordered" nature of JSON objects.
1254     */
1255     using object_t = ObjectType<StringType,
1256           basic_json,
1257           std::less<StringType>,
1258           AllocatorType<std::pair<const StringType,
1259           basic_json>>>;
1260
1261     /*!
1262     @brief a type for an array
1263
1264     [RFC 7159](http://rfc7159.net/rfc7159) describes JSON arrays as follows:
1265     > An array is an ordered sequence of zero or more values.
1266
1267     To store objects in C++, a type is defined by the template parameters
1268     explained below.
1269
1270     @tparam ArrayType  container type to store arrays (e.g., `std::vector` or
1271     `std::list`)
1272     @tparam AllocatorType allocator to use for arrays (e.g., `std::allocator`)
1273
1274     #### Default type
1275
1276     With the default values for @a ArrayType (`std::vector`) and @a
1277     AllocatorType (`std::allocator`), the default value for @a array_t is:
1278
1279     @code {.cpp}
1280     std::vector<
1281       basic_json, // value_type
1282       std::allocator<basic_json> // allocator_type
1283     >
1284     @endcode
1285
1286     #### Limits
1287
1288     [RFC 7159](http://rfc7159.net/rfc7159) specifies:
1289     > An implementation may set limits on the maximum depth of nesting.
1290
1291     In this class, the array's limit of nesting is not constraint explicitly.
1292     However, a maximum depth of nesting may be introduced by the compiler or
1293     runtime environment. A theoretical limit can be queried by calling the
1294     @ref max_size function of a JSON array.
1295
1296     #### Storage
1297
1298     Arrays are stored as pointers in a @ref basic_json type. That is, for any
1299     access to array values, a pointer of type `array_t*` must be dereferenced.
1300
1301     @sa @ref object_t -- type for an object value
1302
1303     @since version 1.0.0
1304     */
1305     using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;
1306
1307     /*!
1308     @brief a type for a string
1309
1310     [RFC 7159](http://rfc7159.net/rfc7159) describes JSON strings as follows:
1311     > A string is a sequence of zero or more Unicode characters.
1312
1313     To store objects in C++, a type is defined by the template parameter
1314     described below. Unicode values are split by the JSON class into
1315     byte-sized characters during deserialization.
1316
1317     @tparam StringType  the container to store strings (e.g., `std::string`).
1318     Note this container is used for keys/names in objects, see @ref object_t.
1319
1320     #### Default type
1321
1322     With the default values for @a StringType (`std::string`), the default
1323     value for @a string_t is:
1324
1325     @code {.cpp}
1326     std::string
1327     @endcode
1328
1329     #### Encoding
1330
1331     Strings are stored in UTF-8 encoding. Therefore, functions like
1332     `std::string::size()` or `std::string::length()` return the number of
1333     bytes in the string rather than the number of characters or glyphs.
1334
1335     #### String comparison
1336
1337     [RFC 7159](http://rfc7159.net/rfc7159) states:
1338     > Software implementations are typically required to test names of object
1339     > members for equality. Implementations that transform the textual
1340     > representation into sequences of Unicode code units and then perform the
1341     > comparison numerically, code unit by code unit, are interoperable in the
1342     > sense that implementations will agree in all cases on equality or
1343     > inequality of two strings. For example, implementations that compare
1344     > strings with escaped characters unconverted may incorrectly find that
1345     > `"a\\b"` and `"a\u005Cb"` are not equal.
1346
1347     This implementation is interoperable as it does compare strings code unit
1348     by code unit.
1349
1350     #### Storage
1351
1352     String values are stored as pointers in a @ref basic_json type. That is,
1353     for any access to string values, a pointer of type `string_t*` must be
1354     dereferenced.
1355
1356     @since version 1.0.0
1357     */
1358     using string_t = StringType;
1359
1360     /*!
1361     @brief a type for a boolean
1362
1363     [RFC 7159](http://rfc7159.net/rfc7159) implicitly describes a boolean as a
1364     type which differentiates the two literals `true` and `false`.
1365
1366     To store objects in C++, a type is defined by the template parameter @a
1367     BooleanType which chooses the type to use.
1368
1369     #### Default type
1370
1371     With the default values for @a BooleanType (`bool`), the default value for
1372     @a boolean_t is:
1373
1374     @code {.cpp}
1375     bool
1376     @endcode
1377
1378     #### Storage
1379
1380     Boolean values are stored directly inside a @ref basic_json type.
1381
1382     @since version 1.0.0
1383     */
1384     using boolean_t = BooleanType;
1385
1386     /*!
1387     @brief a type for a number (integer)
1388
1389     [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
1390     > The representation of numbers is similar to that used in most
1391     > programming languages. A number is represented in base 10 using decimal
1392     > digits. It contains an integer component that may be prefixed with an
1393     > optional minus sign, which may be followed by a fraction part and/or an
1394     > exponent part. Leading zeros are not allowed. (...) Numeric values that
1395     > cannot be represented in the grammar below (such as Infinity and NaN)
1396     > are not permitted.
1397
1398     This description includes both integer and floating-point numbers.
1399     However, C++ allows more precise storage if it is known whether the number
1400     is a signed integer, an unsigned integer or a floating-point number.
1401     Therefore, three different types, @ref number_integer_t, @ref
1402     number_unsigned_t and @ref number_float_t are used.
1403
1404     To store integer numbers in C++, a type is defined by the template
1405     parameter @a NumberIntegerType which chooses the type to use.
1406
1407     #### Default type
1408
1409     With the default values for @a NumberIntegerType (`int64_t`), the default
1410     value for @a number_integer_t is:
1411
1412     @code {.cpp}
1413     int64_t
1414     @endcode
1415
1416     #### Default behavior
1417
1418     - The restrictions about leading zeros is not enforced in C++. Instead,
1419       leading zeros in integer literals lead to an interpretation as octal
1420       number. Internally, the value will be stored as decimal number. For
1421       instance, the C++ integer literal `010` will be serialized to `8`.
1422       During deserialization, leading zeros yield an error.
1423     - Not-a-number (NaN) values will be serialized to `null`.
1424
1425     #### Limits
1426
1427     [RFC 7159](http://rfc7159.net/rfc7159) specifies:
1428     > An implementation may set limits on the range and precision of numbers.
1429
1430     When the default type is used, the maximal integer number that can be
1431     stored is `9223372036854775807` (INT64_MAX) and the minimal integer number
1432     that can be stored is `-9223372036854775808` (INT64_MIN). Integer numbers
1433     that are out of range will yield over/underflow when used in a
1434     constructor. During deserialization, too large or small integer numbers
1435     will be automatically be stored as @ref number_unsigned_t or @ref
1436     number_float_t.
1437
1438     [RFC 7159](http://rfc7159.net/rfc7159) further states:
1439     > Note that when such software is used, numbers that are integers and are
1440     > in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
1441     > that implementations will agree exactly on their numeric values.
1442
1443     As this range is a subrange of the exactly supported range [INT64_MIN,
1444     INT64_MAX], this class's integer type is interoperable.
1445
1446     #### Storage
1447
1448     Integer number values are stored directly inside a @ref basic_json type.
1449
1450     @sa @ref number_float_t -- type for number values (floating-point)
1451
1452     @sa @ref number_unsigned_t -- type for number values (unsigned integer)
1453
1454     @since version 1.0.0
1455     */
1456     using number_integer_t = NumberIntegerType;
1457
1458     /*!
1459     @brief a type for a number (unsigned)
1460
1461     [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
1462     > The representation of numbers is similar to that used in most
1463     > programming languages. A number is represented in base 10 using decimal
1464     > digits. It contains an integer component that may be prefixed with an
1465     > optional minus sign, which may be followed by a fraction part and/or an
1466     > exponent part. Leading zeros are not allowed. (...) Numeric values that
1467     > cannot be represented in the grammar below (such as Infinity and NaN)
1468     > are not permitted.
1469
1470     This description includes both integer and floating-point numbers.
1471     However, C++ allows more precise storage if it is known whether the number
1472     is a signed integer, an unsigned integer or a floating-point number.
1473     Therefore, three different types, @ref number_integer_t, @ref
1474     number_unsigned_t and @ref number_float_t are used.
1475
1476     To store unsigned integer numbers in C++, a type is defined by the
1477     template parameter @a NumberUnsignedType which chooses the type to use.
1478
1479     #### Default type
1480
1481     With the default values for @a NumberUnsignedType (`uint64_t`), the
1482     default value for @a number_unsigned_t is:
1483
1484     @code {.cpp}
1485     uint64_t
1486     @endcode
1487
1488     #### Default behavior
1489
1490     - The restrictions about leading zeros is not enforced in C++. Instead,
1491       leading zeros in integer literals lead to an interpretation as octal
1492       number. Internally, the value will be stored as decimal number. For
1493       instance, the C++ integer literal `010` will be serialized to `8`.
1494       During deserialization, leading zeros yield an error.
1495     - Not-a-number (NaN) values will be serialized to `null`.
1496
1497     #### Limits
1498
1499     [RFC 7159](http://rfc7159.net/rfc7159) specifies:
1500     > An implementation may set limits on the range and precision of numbers.
1501
1502     When the default type is used, the maximal integer number that can be
1503     stored is `18446744073709551615` (UINT64_MAX) and the minimal integer
1504     number that can be stored is `0`. Integer numbers that are out of range
1505     will yield over/underflow when used in a constructor. During
1506     deserialization, too large or small integer numbers will be automatically
1507     be stored as @ref number_integer_t or @ref number_float_t.
1508
1509     [RFC 7159](http://rfc7159.net/rfc7159) further states:
1510     > Note that when such software is used, numbers that are integers and are
1511     > in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
1512     > that implementations will agree exactly on their numeric values.
1513
1514     As this range is a subrange (when considered in conjunction with the
1515     number_integer_t type) of the exactly supported range [0, UINT64_MAX],
1516     this class's integer type is interoperable.
1517
1518     #### Storage
1519
1520     Integer number values are stored directly inside a @ref basic_json type.
1521
1522     @sa @ref number_float_t -- type for number values (floating-point)
1523     @sa @ref number_integer_t -- type for number values (integer)
1524
1525     @since version 2.0.0
1526     */
1527     using number_unsigned_t = NumberUnsignedType;
1528
1529     /*!
1530     @brief a type for a number (floating-point)
1531
1532     [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
1533     > The representation of numbers is similar to that used in most
1534     > programming languages. A number is represented in base 10 using decimal
1535     > digits. It contains an integer component that may be prefixed with an
1536     > optional minus sign, which may be followed by a fraction part and/or an
1537     > exponent part. Leading zeros are not allowed. (...) Numeric values that
1538     > cannot be represented in the grammar below (such as Infinity and NaN)
1539     > are not permitted.
1540
1541     This description includes both integer and floating-point numbers.
1542     However, C++ allows more precise storage if it is known whether the number
1543     is a signed integer, an unsigned integer or a floating-point number.
1544     Therefore, three different types, @ref number_integer_t, @ref
1545     number_unsigned_t and @ref number_float_t are used.
1546
1547     To store floating-point numbers in C++, a type is defined by the template
1548     parameter @a NumberFloatType which chooses the type to use.
1549
1550     #### Default type
1551
1552     With the default values for @a NumberFloatType (`double`), the default
1553     value for @a number_float_t is:
1554
1555     @code {.cpp}
1556     double
1557     @endcode
1558
1559     #### Default behavior
1560
1561     - The restrictions about leading zeros is not enforced in C++. Instead,
1562       leading zeros in floating-point literals will be ignored. Internally,
1563       the value will be stored as decimal number. For instance, the C++
1564       floating-point literal `01.2` will be serialized to `1.2`. During
1565       deserialization, leading zeros yield an error.
1566     - Not-a-number (NaN) values will be serialized to `null`.
1567
1568     #### Limits
1569
1570     [RFC 7159](http://rfc7159.net/rfc7159) states:
1571     > This specification allows implementations to set limits on the range and
1572     > precision of numbers accepted. Since software that implements IEEE
1573     > 754-2008 binary64 (double precision) numbers is generally available and
1574     > widely used, good interoperability can be achieved by implementations
1575     > that expect no more precision or range than these provide, in the sense
1576     > that implementations will approximate JSON numbers within the expected
1577     > precision.
1578
1579     This implementation does exactly follow this approach, as it uses double
1580     precision floating-point numbers. Note values smaller than
1581     `-1.79769313486232e+308` and values greater than `1.79769313486232e+308`
1582     will be stored as NaN internally and be serialized to `null`.
1583
1584     #### Storage
1585
1586     Floating-point number values are stored directly inside a @ref basic_json
1587     type.
1588
1589     @sa @ref number_integer_t -- type for number values (integer)
1590
1591     @sa @ref number_unsigned_t -- type for number values (unsigned integer)
1592
1593     @since version 1.0.0
1594     */
1595     using number_float_t = NumberFloatType;
1596
1597     /// @}
1598
1599   private:
1600
1601     /// helper for exception-safe object creation
1602     template<typename T, typename... Args>
1603     static T* create(Args&& ... args)
1604     {
1605         AllocatorType<T> alloc;
1606         auto deleter = [&](T * object)
1607         {
1608             alloc.deallocate(object, 1);
1609         };
1610         std::unique_ptr<T, decltype(deleter)> object(alloc.allocate(1), deleter);
1611         alloc.construct(object.get(), std::forward<Args>(args)...);
1612         assert(object != nullptr);
1613         return object.release();
1614     }
1615
1616     ////////////////////////
1617     // JSON value storage //
1618     ////////////////////////
1619
1620     /*!
1621     @brief a JSON value
1622
1623     The actual storage for a JSON value of the @ref basic_json class. This
1624     union combines the different storage types for the JSON value types
1625     defined in @ref value_t.
1626
1627     JSON type | value_t type    | used type
1628     --------- | --------------- | ------------------------
1629     object    | object          | pointer to @ref object_t
1630     array     | array           | pointer to @ref array_t
1631     string    | string          | pointer to @ref string_t
1632     boolean   | boolean         | @ref boolean_t
1633     number    | number_integer  | @ref number_integer_t
1634     number    | number_unsigned | @ref number_unsigned_t
1635     number    | number_float    | @ref number_float_t
1636     null      | null            | *no value is stored*
1637
1638     @note Variable-length types (objects, arrays, and strings) are stored as
1639     pointers. The size of the union should not exceed 64 bits if the default
1640     value types are used.
1641
1642     @since version 1.0.0
1643     */
1644     union json_value
1645     {
1646         /// object (stored with pointer to save storage)
1647         object_t* object;
1648         /// array (stored with pointer to save storage)
1649         array_t* array;
1650         /// string (stored with pointer to save storage)
1651         string_t* string;
1652         /// boolean
1653         boolean_t boolean;
1654         /// number (integer)
1655         number_integer_t number_integer;
1656         /// number (unsigned integer)
1657         number_unsigned_t number_unsigned;
1658         /// number (floating-point)
1659         number_float_t number_float;
1660
1661         /// default constructor (for null values)
1662         json_value() = default;
1663         /// constructor for booleans
1664         json_value(boolean_t v) noexcept : boolean(v) {}
1665         /// constructor for numbers (integer)
1666         json_value(number_integer_t v) noexcept : number_integer(v) {}
1667         /// constructor for numbers (unsigned)
1668         json_value(number_unsigned_t v) noexcept : number_unsigned(v) {}
1669         /// constructor for numbers (floating-point)
1670         json_value(number_float_t v) noexcept : number_float(v) {}
1671         /// constructor for empty values of a given type
1672         json_value(value_t t)
1673         {
1674             switch (t)
1675             {
1676                 case value_t::object:
1677                 {
1678                     object = create<object_t>();
1679                     break;
1680                 }
1681
1682                 case value_t::array:
1683                 {
1684                     array = create<array_t>();
1685                     break;
1686                 }
1687
1688                 case value_t::string:
1689                 {
1690                     string = create<string_t>("");
1691                     break;
1692                 }
1693
1694                 case value_t::boolean:
1695                 {
1696                     boolean = boolean_t(false);
1697                     break;
1698                 }
1699
1700                 case value_t::number_integer:
1701                 {
1702                     number_integer = number_integer_t(0);
1703                     break;
1704                 }
1705
1706                 case value_t::number_unsigned:
1707                 {
1708                     number_unsigned = number_unsigned_t(0);
1709                     break;
1710                 }
1711
1712                 case value_t::number_float:
1713                 {
1714                     number_float = number_float_t(0.0);
1715                     break;
1716                 }
1717
1718                 case value_t::null:
1719                 {
1720                     break;
1721                 }
1722
1723                 default:
1724                 {
1725                     if (t == value_t::null)
1726                     {
1727                         JSON_THROW(std::domain_error("961c151d2e87f2686a955a9be24d316f1362bf21 2.1.1")); // LCOV_EXCL_LINE
1728                     }
1729                     break;
1730                 }
1731             }
1732         }
1733
1734         /// constructor for strings
1735         json_value(const string_t& value)
1736         {
1737             string = create<string_t>(value);
1738         }
1739
1740         /// constructor for objects
1741         json_value(const object_t& value)
1742         {
1743             object = create<object_t>(value);
1744         }
1745
1746         /// constructor for arrays
1747         json_value(const array_t& value)
1748         {
1749             array = create<array_t>(value);
1750         }
1751     };
1752
1753     /*!
1754     @brief checks the class invariants
1755
1756     This function asserts the class invariants. It needs to be called at the
1757     end of every constructor to make sure that created objects respect the
1758     invariant. Furthermore, it has to be called each time the type of a JSON
1759     value is changed, because the invariant expresses a relationship between
1760     @a m_type and @a m_value.
1761     */
1762     void assert_invariant() const
1763     {
1764         assert(m_type != value_t::object or m_value.object != nullptr);
1765         assert(m_type != value_t::array or m_value.array != nullptr);
1766         assert(m_type != value_t::string or m_value.string != nullptr);
1767     }
1768
1769   public:
1770     //////////////////////////
1771     // JSON parser callback //
1772     //////////////////////////
1773
1774     /*!
1775     @brief JSON callback events
1776
1777     This enumeration lists the parser events that can trigger calling a
1778     callback function of type @ref parser_callback_t during parsing.
1779
1780     @image html callback_events.png "Example when certain parse events are triggered"
1781
1782     @since version 1.0.0
1783     */
1784     enum class parse_event_t : uint8_t
1785     {
1786         /// the parser read `{` and started to process a JSON object
1787         object_start,
1788         /// the parser read `}` and finished processing a JSON object
1789         object_end,
1790         /// the parser read `[` and started to process a JSON array
1791         array_start,
1792         /// the parser read `]` and finished processing a JSON array
1793         array_end,
1794         /// the parser read a key of a value in an object
1795         key,
1796         /// the parser finished reading a JSON value
1797         value
1798     };
1799
1800     /*!
1801     @brief per-element parser callback type
1802
1803     With a parser callback function, the result of parsing a JSON text can be
1804     influenced. When passed to @ref parse(std::istream&, const
1805     parser_callback_t) or @ref parse(const CharT, const parser_callback_t),
1806     it is called on certain events (passed as @ref parse_event_t via parameter
1807     @a event) with a set recursion depth @a depth and context JSON value
1808     @a parsed. The return value of the callback function is a boolean
1809     indicating whether the element that emitted the callback shall be kept or
1810     not.
1811
1812     We distinguish six scenarios (determined by the event type) in which the
1813     callback function can be called. The following table describes the values
1814     of the parameters @a depth, @a event, and @a parsed.
1815
1816     parameter @a event | description | parameter @a depth | parameter @a parsed
1817     ------------------ | ----------- | ------------------ | -------------------
1818     parse_event_t::object_start | the parser read `{` and started to process a JSON object | depth of the parent of the JSON object | a JSON value with type discarded
1819     parse_event_t::key | the parser read a key of a value in an object | depth of the currently parsed JSON object | a JSON string containing the key
1820     parse_event_t::object_end | the parser read `}` and finished processing a JSON object | depth of the parent of the JSON object | the parsed JSON object
1821     parse_event_t::array_start | the parser read `[` and started to process a JSON array | depth of the parent of the JSON array | a JSON value with type discarded
1822     parse_event_t::array_end | the parser read `]` and finished processing a JSON array | depth of the parent of the JSON array | the parsed JSON array
1823     parse_event_t::value | the parser finished reading a JSON value | depth of the value | the parsed JSON value
1824
1825     @image html callback_events.png "Example when certain parse events are triggered"
1826
1827     Discarding a value (i.e., returning `false`) has different effects
1828     depending on the context in which function was called:
1829
1830     - Discarded values in structured types are skipped. That is, the parser
1831       will behave as if the discarded value was never read.
1832     - In case a value outside a structured type is skipped, it is replaced
1833       with `null`. This case happens if the top-level element is skipped.
1834
1835     @param[in] depth  the depth of the recursion during parsing
1836
1837     @param[in] event  an event of type parse_event_t indicating the context in
1838     the callback function has been called
1839
1840     @param[in,out] parsed  the current intermediate parse result; note that
1841     writing to this value has no effect for parse_event_t::key events
1842
1843     @return Whether the JSON value which called the function during parsing
1844     should be kept (`true`) or not (`false`). In the latter case, it is either
1845     skipped completely or replaced by an empty discarded object.
1846
1847     @sa @ref parse(std::istream&, parser_callback_t) or
1848     @ref parse(const CharT, const parser_callback_t) for examples
1849
1850     @since version 1.0.0
1851     */
1852     using parser_callback_t = std::function<bool(int depth,
1853                               parse_event_t event,
1854                               basic_json& parsed)>;
1855
1856
1857     //////////////////
1858     // constructors //
1859     //////////////////
1860
1861     /// @name constructors and destructors
1862     /// Constructors of class @ref basic_json, copy/move constructor, copy
1863     /// assignment, static functions creating objects, and the destructor.
1864     /// @{
1865
1866     /*!
1867     @brief create an empty value with a given type
1868
1869     Create an empty JSON value with a given type. The value will be default
1870     initialized with an empty value which depends on the type:
1871
1872     Value type  | initial value
1873     ----------- | -------------
1874     null        | `null`
1875     boolean     | `false`
1876     string      | `""`
1877     number      | `0`
1878     object      | `{}`
1879     array       | `[]`
1880
1881     @param[in] value_type  the type of the value to create
1882
1883     @complexity Constant.
1884
1885     @throw std::bad_alloc if allocation for object, array, or string value
1886     fails
1887
1888     @liveexample{The following code shows the constructor for different @ref
1889     value_t values,basic_json__value_t}
1890
1891     @since version 1.0.0
1892     */
1893     basic_json(const value_t value_type)
1894         : m_type(value_type), m_value(value_type)
1895     {
1896         assert_invariant();
1897     }
1898
1899     /*!
1900     @brief create a null object
1901
1902     Create a `null` JSON value. It either takes a null pointer as parameter
1903     (explicitly creating `null`) or no parameter (implicitly creating `null`).
1904     The passed null pointer itself is not read -- it is only used to choose
1905     the right constructor.
1906
1907     @complexity Constant.
1908
1909     @exceptionsafety No-throw guarantee: this constructor never throws
1910     exceptions.
1911
1912     @liveexample{The following code shows the constructor with and without a
1913     null pointer parameter.,basic_json__nullptr_t}
1914
1915     @since version 1.0.0
1916     */
1917     basic_json(std::nullptr_t = nullptr) noexcept
1918         : basic_json(value_t::null)
1919     {
1920         assert_invariant();
1921     }
1922
1923     /*!
1924     @brief create a JSON value
1925
1926     This is a "catch all" constructor for all compatible JSON types; that is,
1927     types for which a `to_json()` method exsits. The constructor forwards the
1928     parameter @a val to that method (to `json_serializer<U>::to_json` method
1929     with `U = uncvref_t<CompatibleType>`, to be exact).
1930
1931     Template type @a CompatibleType includes, but is not limited to, the
1932     following types:
1933     - **arrays**: @ref array_t and all kinds of compatible containers such as
1934       `std::vector`, `std::deque`, `std::list`, `std::forward_list`,
1935       `std::array`, `std::set`, `std::unordered_set`, `std::multiset`, and
1936       `unordered_multiset` with a `value_type` from which a @ref basic_json
1937       value can be constructed.
1938     - **objects**: @ref object_t and all kinds of compatible associative
1939       containers such as `std::map`, `std::unordered_map`, `std::multimap`,
1940       and `std::unordered_multimap` with a `key_type` compatible to
1941       @ref string_t and a `value_type` from which a @ref basic_json value can
1942       be constructed.
1943     - **strings**: @ref string_t, string literals, and all compatible string
1944       containers can be used.
1945     - **numbers**: @ref number_integer_t, @ref number_unsigned_t,
1946       @ref number_float_t, and all convertible number types such as `int`,
1947       `size_t`, `int64_t`, `float` or `double` can be used.
1948     - **boolean**: @ref boolean_t / `bool` can be used.
1949
1950     See the examples below.
1951
1952     @tparam CompatibleType a type such that:
1953     - @a CompatibleType is not derived from `std::istream`,
1954     - @a CompatibleType is not @ref basic_json (to avoid hijacking copy/move
1955          constructors),
1956     - @a CompatibleType is not a @ref basic_json nested type (e.g.,
1957          @ref json_pointer, @ref iterator, etc ...)
1958     - @ref @ref json_serializer<U> has a
1959          `to_json(basic_json_t&, CompatibleType&&)` method
1960
1961     @tparam U = `uncvref_t<CompatibleType>`
1962
1963     @param[in] val the value to be forwarded
1964
1965     @complexity Usually linear in the size of the passed @a val, also
1966                 depending on the implementation of the called `to_json()`
1967                 method.
1968
1969     @throw what `json_serializer<U>::to_json()` throws
1970
1971     @liveexample{The following code shows the constructor with several
1972     compatible types.,basic_json__CompatibleType}
1973
1974     @since version 2.1.0
1975     */
1976     template<typename CompatibleType, typename U = detail::uncvref_t<CompatibleType>,
1977              detail::enable_if_t<not std::is_base_of<std::istream, U>::value and
1978                                  not std::is_same<U, basic_json_t>::value and
1979                                  not detail::is_basic_json_nested_type<
1980                                      basic_json_t, U>::value and
1981                                  detail::has_to_json<basic_json, U>::value,
1982                                  int> = 0>
1983     basic_json(CompatibleType && val) noexcept(noexcept(JSONSerializer<U>::to_json(
1984                 std::declval<basic_json_t&>(), std::forward<CompatibleType>(val))))
1985     {
1986         JSONSerializer<U>::to_json(*this, std::forward<CompatibleType>(val));
1987         assert_invariant();
1988     }
1989
1990     /*!
1991     @brief create a container (array or object) from an initializer list
1992
1993     Creates a JSON value of type array or object from the passed initializer
1994     list @a init. In case @a type_deduction is `true` (default), the type of
1995     the JSON value to be created is deducted from the initializer list @a init
1996     according to the following rules:
1997
1998     1. If the list is empty, an empty JSON object value `{}` is created.
1999     2. If the list consists of pairs whose first element is a string, a JSON
2000        object value is created where the first elements of the pairs are
2001        treated as keys and the second elements are as values.
2002     3. In all other cases, an array is created.
2003
2004     The rules aim to create the best fit between a C++ initializer list and
2005     JSON values. The rationale is as follows:
2006
2007     1. The empty initializer list is written as `{}` which is exactly an empty
2008        JSON object.
2009     2. C++ has now way of describing mapped types other than to list a list of
2010        pairs. As JSON requires that keys must be of type string, rule 2 is the
2011        weakest constraint one can pose on initializer lists to interpret them
2012        as an object.
2013     3. In all other cases, the initializer list could not be interpreted as
2014        JSON object type, so interpreting it as JSON array type is safe.
2015
2016     With the rules described above, the following JSON values cannot be
2017     expressed by an initializer list:
2018
2019     - the empty array (`[]`): use @ref array(std::initializer_list<basic_json>)
2020       with an empty initializer list in this case
2021     - arrays whose elements satisfy rule 2: use @ref
2022       array(std::initializer_list<basic_json>) with the same initializer list
2023       in this case
2024
2025     @note When used without parentheses around an empty initializer list, @ref
2026     basic_json() is called instead of this function, yielding the JSON null
2027     value.
2028
2029     @param[in] init  initializer list with JSON values
2030
2031     @param[in] type_deduction internal parameter; when set to `true`, the type
2032     of the JSON value is deducted from the initializer list @a init; when set
2033     to `false`, the type provided via @a manual_type is forced. This mode is
2034     used by the functions @ref array(std::initializer_list<basic_json>) and
2035     @ref object(std::initializer_list<basic_json>).
2036
2037     @param[in] manual_type internal parameter; when @a type_deduction is set
2038     to `false`, the created JSON value will use the provided type (only @ref
2039     value_t::array and @ref value_t::object are valid); when @a type_deduction
2040     is set to `true`, this parameter has no effect
2041
2042     @throw std::domain_error if @a type_deduction is `false`, @a manual_type
2043     is `value_t::object`, but @a init contains an element which is not a pair
2044     whose first element is a string; example: `"cannot create object from
2045     initializer list"`
2046
2047     @complexity Linear in the size of the initializer list @a init.
2048
2049     @liveexample{The example below shows how JSON values are created from
2050     initializer lists.,basic_json__list_init_t}
2051
2052     @sa @ref array(std::initializer_list<basic_json>) -- create a JSON array
2053     value from an initializer list
2054     @sa @ref object(std::initializer_list<basic_json>) -- create a JSON object
2055     value from an initializer list
2056
2057     @since version 1.0.0
2058     */
2059     basic_json(std::initializer_list<basic_json> init,
2060                bool type_deduction = true,
2061                value_t manual_type = value_t::array)
2062     {
2063         // check if each element is an array with two elements whose first
2064         // element is a string
2065         bool is_an_object = std::all_of(init.begin(), init.end(),
2066                                         [](const basic_json & element)
2067         {
2068             return element.is_array() and element.size() == 2 and element[0].is_string();
2069         });
2070
2071         // adjust type if type deduction is not wanted
2072         if (not type_deduction)
2073         {
2074             // if array is wanted, do not create an object though possible
2075             if (manual_type == value_t::array)
2076             {
2077                 is_an_object = false;
2078             }
2079
2080             // if object is wanted but impossible, throw an exception
2081             if (manual_type == value_t::object and not is_an_object)
2082             {
2083                 JSON_THROW(std::domain_error("cannot create object from initializer list"));
2084             }
2085         }
2086
2087         if (is_an_object)
2088         {
2089             // the initializer list is a list of pairs -> create object
2090             m_type = value_t::object;
2091             m_value = value_t::object;
2092
2093             std::for_each(init.begin(), init.end(), [this](const basic_json & element)
2094             {
2095                 m_value.object->emplace(*(element[0].m_value.string), element[1]);
2096             });
2097         }
2098         else
2099         {
2100             // the initializer list describes an array -> create array
2101             m_type = value_t::array;
2102             m_value.array = create<array_t>(init);
2103         }
2104
2105         assert_invariant();
2106     }
2107
2108     /*!
2109     @brief explicitly create an array from an initializer list
2110
2111     Creates a JSON array value from a given initializer list. That is, given a
2112     list of values `a, b, c`, creates the JSON value `[a, b, c]`. If the
2113     initializer list is empty, the empty array `[]` is created.
2114
2115     @note This function is only needed to express two edge cases that cannot
2116     be realized with the initializer list constructor (@ref
2117     basic_json(std::initializer_list<basic_json>, bool, value_t)). These cases
2118     are:
2119     1. creating an array whose elements are all pairs whose first element is a
2120     string -- in this case, the initializer list constructor would create an
2121     object, taking the first elements as keys
2122     2. creating an empty array -- passing the empty initializer list to the
2123     initializer list constructor yields an empty object
2124
2125     @param[in] init  initializer list with JSON values to create an array from
2126     (optional)
2127
2128     @return JSON array value
2129
2130     @complexity Linear in the size of @a init.
2131
2132     @liveexample{The following code shows an example for the `array`
2133     function.,array}
2134
2135     @sa @ref basic_json(std::initializer_list<basic_json>, bool, value_t) --
2136     create a JSON value from an initializer list
2137     @sa @ref object(std::initializer_list<basic_json>) -- create a JSON object
2138     value from an initializer list
2139
2140     @since version 1.0.0
2141     */
2142     static basic_json array(std::initializer_list<basic_json> init =
2143                                 std::initializer_list<basic_json>())
2144     {
2145         return basic_json(init, false, value_t::array);
2146     }
2147
2148     /*!
2149     @brief explicitly create an object from an initializer list
2150
2151     Creates a JSON object value from a given initializer list. The initializer
2152     lists elements must be pairs, and their first elements must be strings. If
2153     the initializer list is empty, the empty object `{}` is created.
2154
2155     @note This function is only added for symmetry reasons. In contrast to the
2156     related function @ref array(std::initializer_list<basic_json>), there are
2157     no cases which can only be expressed by this function. That is, any
2158     initializer list @a init can also be passed to the initializer list
2159     constructor @ref basic_json(std::initializer_list<basic_json>, bool,
2160     value_t).
2161
2162     @param[in] init  initializer list to create an object from (optional)
2163
2164     @return JSON object value
2165
2166     @throw std::domain_error if @a init is not a pair whose first elements are
2167     strings; thrown by
2168     @ref basic_json(std::initializer_list<basic_json>, bool, value_t)
2169
2170     @complexity Linear in the size of @a init.
2171
2172     @liveexample{The following code shows an example for the `object`
2173     function.,object}
2174
2175     @sa @ref basic_json(std::initializer_list<basic_json>, bool, value_t) --
2176     create a JSON value from an initializer list
2177     @sa @ref array(std::initializer_list<basic_json>) -- create a JSON array
2178     value from an initializer list
2179
2180     @since version 1.0.0
2181     */
2182     static basic_json object(std::initializer_list<basic_json> init =
2183                                  std::initializer_list<basic_json>())
2184     {
2185         return basic_json(init, false, value_t::object);
2186     }
2187
2188     /*!
2189     @brief construct an array with count copies of given value
2190
2191     Constructs a JSON array value by creating @a cnt copies of a passed value.
2192     In case @a cnt is `0`, an empty array is created. As postcondition,
2193     `std::distance(begin(),end()) == cnt` holds.
2194
2195     @param[in] cnt  the number of JSON copies of @a val to create
2196     @param[in] val  the JSON value to copy
2197
2198     @complexity Linear in @a cnt.
2199
2200     @liveexample{The following code shows examples for the @ref
2201     basic_json(size_type\, const basic_json&)
2202     constructor.,basic_json__size_type_basic_json}
2203
2204     @since version 1.0.0
2205     */
2206     basic_json(size_type cnt, const basic_json& val)
2207         : m_type(value_t::array)
2208     {
2209         m_value.array = create<array_t>(cnt, val);
2210         assert_invariant();
2211     }
2212
2213     /*!
2214     @brief construct a JSON container given an iterator range
2215
2216     Constructs the JSON value with the contents of the range `[first, last)`.
2217     The semantics depends on the different types a JSON value can have:
2218     - In case of primitive types (number, boolean, or string), @a first must
2219       be `begin()` and @a last must be `end()`. In this case, the value is
2220       copied. Otherwise, std::out_of_range is thrown.
2221     - In case of structured types (array, object), the constructor behaves as
2222       similar versions for `std::vector`.
2223     - In case of a null type, std::domain_error is thrown.
2224
2225     @tparam InputIT an input iterator type (@ref iterator or @ref
2226     const_iterator)
2227
2228     @param[in] first begin of the range to copy from (included)
2229     @param[in] last end of the range to copy from (excluded)
2230
2231     @pre Iterators @a first and @a last must be initialized. **This
2232          precondition is enforced with an assertion.**
2233
2234     @throw std::domain_error if iterators are not compatible; that is, do not
2235     belong to the same JSON value; example: `"iterators are not compatible"`
2236     @throw std::out_of_range if iterators are for a primitive type (number,
2237     boolean, or string) where an out of range error can be detected easily;
2238     example: `"iterators out of range"`
2239     @throw std::bad_alloc if allocation for object, array, or string fails
2240     @throw std::domain_error if called with a null value; example: `"cannot
2241     use construct with iterators from null"`
2242
2243     @complexity Linear in distance between @a first and @a last.
2244
2245     @liveexample{The example below shows several ways to create JSON values by
2246     specifying a subrange with iterators.,basic_json__InputIt_InputIt}
2247
2248     @since version 1.0.0
2249     */
2250     template<class InputIT, typename std::enable_if<
2251                  std::is_same<InputIT, typename basic_json_t::iterator>::value or
2252                  std::is_same<InputIT, typename basic_json_t::const_iterator>::value, int>::type = 0>
2253     basic_json(InputIT first, InputIT last)
2254     {
2255         assert(first.m_object != nullptr);
2256         assert(last.m_object != nullptr);
2257
2258         // make sure iterator fits the current value
2259         if (first.m_object != last.m_object)
2260         {
2261             JSON_THROW(std::domain_error("iterators are not compatible"));
2262         }
2263
2264         // copy type from first iterator
2265         m_type = first.m_object->m_type;
2266
2267         // check if iterator range is complete for primitive values
2268         switch (m_type)
2269         {
2270             case value_t::boolean:
2271             case value_t::number_float:
2272             case value_t::number_integer:
2273             case value_t::number_unsigned:
2274             case value_t::string:
2275             {
2276                 if (not first.m_it.primitive_iterator.is_begin() or not last.m_it.primitive_iterator.is_end())
2277                 {
2278                     JSON_THROW(std::out_of_range("iterators out of range"));
2279                 }
2280                 break;
2281             }
2282
2283             default:
2284             {
2285                 break;
2286             }
2287         }
2288
2289         switch (m_type)
2290         {
2291             case value_t::number_integer:
2292             {
2293                 m_value.number_integer = first.m_object->m_value.number_integer;
2294                 break;
2295             }
2296
2297             case value_t::number_unsigned:
2298             {
2299                 m_value.number_unsigned = first.m_object->m_value.number_unsigned;
2300                 break;
2301             }
2302
2303             case value_t::number_float:
2304             {
2305                 m_value.number_float = first.m_object->m_value.number_float;
2306                 break;
2307             }
2308
2309             case value_t::boolean:
2310             {
2311                 m_value.boolean = first.m_object->m_value.boolean;
2312                 break;
2313             }
2314
2315             case value_t::string:
2316             {
2317                 m_value = *first.m_object->m_value.string;
2318                 break;
2319             }
2320
2321             case value_t::object:
2322             {
2323                 m_value.object = create<object_t>(first.m_it.object_iterator,
2324                                                   last.m_it.object_iterator);
2325                 break;
2326             }
2327
2328             case value_t::array:
2329             {
2330                 m_value.array = create<array_t>(first.m_it.array_iterator,
2331                                                 last.m_it.array_iterator);
2332                 break;
2333             }
2334
2335             default:
2336             {
2337                 JSON_THROW(std::domain_error("cannot use construct with iterators from " + first.m_object->type_name()));
2338             }
2339         }
2340
2341         assert_invariant();
2342     }
2343
2344     /*!
2345     @brief construct a JSON value given an input stream
2346
2347     @param[in,out] i  stream to read a serialized JSON value from
2348     @param[in] cb a parser callback function of type @ref parser_callback_t
2349     which is used to control the deserialization by filtering unwanted values
2350     (optional)
2351
2352     @complexity Linear in the length of the input. The parser is a predictive
2353     LL(1) parser. The complexity can be higher if the parser callback function
2354     @a cb has a super-linear complexity.
2355
2356     @note A UTF-8 byte order mark is silently ignored.
2357
2358     @deprecated This constructor is deprecated and will be removed in version
2359       3.0.0 to unify the interface of the library. Deserialization will be
2360       done by stream operators or by calling one of the `parse` functions,
2361       e.g. @ref parse(std::istream&, const parser_callback_t). That is, calls
2362       like `json j(i);` for an input stream @a i need to be replaced by
2363       `json j = json::parse(i);`. See the example below.
2364
2365     @liveexample{The example below demonstrates constructing a JSON value from
2366     a `std::stringstream` with and without callback
2367     function.,basic_json__istream}
2368
2369     @since version 2.0.0, deprecated in version 2.0.3, to be removed in
2370            version 3.0.0
2371     */
2372     JSON_DEPRECATED
2373     explicit basic_json(std::istream& i, const parser_callback_t cb = nullptr)
2374     {
2375         *this = parser(i, cb).parse();
2376         assert_invariant();
2377     }
2378
2379     ///////////////////////////////////////
2380     // other constructors and destructor //
2381     ///////////////////////////////////////
2382
2383     /*!
2384     @brief copy constructor
2385
2386     Creates a copy of a given JSON value.
2387
2388     @param[in] other  the JSON value to copy
2389
2390     @complexity Linear in the size of @a other.
2391
2392     @requirement This function helps `basic_json` satisfying the
2393     [Container](http://en.cppreference.com/w/cpp/concept/Container)
2394     requirements:
2395     - The complexity is linear.
2396     - As postcondition, it holds: `other == basic_json(other)`.
2397
2398     @throw std::bad_alloc if allocation for object, array, or string fails.
2399
2400     @liveexample{The following code shows an example for the copy
2401     constructor.,basic_json__basic_json}
2402
2403     @since version 1.0.0
2404     */
2405     basic_json(const basic_json& other)
2406         : m_type(other.m_type)
2407     {
2408         // check of passed value is valid
2409         other.assert_invariant();
2410
2411         switch (m_type)
2412         {
2413             case value_t::object:
2414             {
2415                 m_value = *other.m_value.object;
2416                 break;
2417             }
2418
2419             case value_t::array:
2420             {
2421                 m_value = *other.m_value.array;
2422                 break;
2423             }
2424
2425             case value_t::string:
2426             {
2427                 m_value = *other.m_value.string;
2428                 break;
2429             }
2430
2431             case value_t::boolean:
2432             {
2433                 m_value = other.m_value.boolean;
2434                 break;
2435             }
2436
2437             case value_t::number_integer:
2438             {
2439                 m_value = other.m_value.number_integer;
2440                 break;
2441             }
2442
2443             case value_t::number_unsigned:
2444             {
2445                 m_value = other.m_value.number_unsigned;
2446                 break;
2447             }
2448
2449             case value_t::number_float:
2450             {
2451                 m_value = other.m_value.number_float;
2452                 break;
2453             }
2454
2455             default:
2456             {
2457                 break;
2458             }
2459         }
2460
2461         assert_invariant();
2462     }
2463
2464     /*!
2465     @brief move constructor
2466
2467     Move constructor. Constructs a JSON value with the contents of the given
2468     value @a other using move semantics. It "steals" the resources from @a
2469     other and leaves it as JSON null value.
2470
2471     @param[in,out] other  value to move to this object
2472
2473     @post @a other is a JSON null value
2474
2475     @complexity Constant.
2476
2477     @liveexample{The code below shows the move constructor explicitly called
2478     via std::move.,basic_json__moveconstructor}
2479
2480     @since version 1.0.0
2481     */
2482     basic_json(basic_json&& other) noexcept
2483         : m_type(std::move(other.m_type)),
2484           m_value(std::move(other.m_value))
2485     {
2486         // check that passed value is valid
2487         other.assert_invariant();
2488
2489         // invalidate payload
2490         other.m_type = value_t::null;
2491         other.m_value = {};
2492
2493         assert_invariant();
2494     }
2495
2496     /*!
2497     @brief copy assignment
2498
2499     Copy assignment operator. Copies a JSON value via the "copy and swap"
2500     strategy: It is expressed in terms of the copy constructor, destructor,
2501     and the swap() member function.
2502
2503     @param[in] other  value to copy from
2504
2505     @complexity Linear.
2506
2507     @requirement This function helps `basic_json` satisfying the
2508     [Container](http://en.cppreference.com/w/cpp/concept/Container)
2509     requirements:
2510     - The complexity is linear.
2511
2512     @liveexample{The code below shows and example for the copy assignment. It
2513     creates a copy of value `a` which is then swapped with `b`. Finally\, the
2514     copy of `a` (which is the null value after the swap) is
2515     destroyed.,basic_json__copyassignment}
2516
2517     @since version 1.0.0
2518     */
2519     reference& operator=(basic_json other) noexcept (
2520         std::is_nothrow_move_constructible<value_t>::value and
2521         std::is_nothrow_move_assignable<value_t>::value and
2522         std::is_nothrow_move_constructible<json_value>::value and
2523         std::is_nothrow_move_assignable<json_value>::value
2524     )
2525     {
2526         // check that passed value is valid
2527         other.assert_invariant();
2528
2529         using std::swap;
2530         swap(m_type, other.m_type);
2531         swap(m_value, other.m_value);
2532
2533         assert_invariant();
2534         return *this;
2535     }
2536
2537     /*!
2538     @brief destructor
2539
2540     Destroys the JSON value and frees all allocated memory.
2541
2542     @complexity Linear.
2543
2544     @requirement This function helps `basic_json` satisfying the
2545     [Container](http://en.cppreference.com/w/cpp/concept/Container)
2546     requirements:
2547     - The complexity is linear.
2548     - All stored elements are destroyed and all memory is freed.
2549
2550     @since version 1.0.0
2551     */
2552     ~basic_json()
2553     {
2554         assert_invariant();
2555
2556         switch (m_type)
2557         {
2558             case value_t::object:
2559             {
2560                 AllocatorType<object_t> alloc;
2561                 alloc.destroy(m_value.object);
2562                 alloc.deallocate(m_value.object, 1);
2563                 break;
2564             }
2565
2566             case value_t::array:
2567             {
2568                 AllocatorType<array_t> alloc;
2569                 alloc.destroy(m_value.array);
2570                 alloc.deallocate(m_value.array, 1);
2571                 break;
2572             }
2573
2574             case value_t::string:
2575             {
2576                 AllocatorType<string_t> alloc;
2577                 alloc.destroy(m_value.string);
2578                 alloc.deallocate(m_value.string, 1);
2579                 break;
2580             }
2581
2582             default:
2583             {
2584                 // all other types need no specific destructor
2585                 break;
2586             }
2587         }
2588     }
2589
2590     /// @}
2591
2592   public:
2593     ///////////////////////
2594     // object inspection //
2595     ///////////////////////
2596
2597     /// @name object inspection
2598     /// Functions to inspect the type of a JSON value.
2599     /// @{
2600
2601     /*!
2602     @brief serialization
2603
2604     Serialization function for JSON values. The function tries to mimic
2605     Python's `json.dumps()` function, and currently supports its @a indent
2606     parameter.
2607
2608     @param[in] indent If indent is nonnegative, then array elements and object
2609     members will be pretty-printed with that indent level. An indent level of
2610     `0` will only insert newlines. `-1` (the default) selects the most compact
2611     representation.
2612
2613     @return string containing the serialization of the JSON value
2614
2615     @complexity Linear.
2616
2617     @liveexample{The following example shows the effect of different @a indent
2618     parameters to the result of the serialization.,dump}
2619
2620     @see https://docs.python.org/2/library/json.html#json.dump
2621
2622     @since version 1.0.0
2623     */
2624     string_t dump(const int indent = -1) const
2625     {
2626         std::stringstream ss;
2627
2628         if (indent >= 0)
2629         {
2630             dump(ss, true, static_cast<unsigned int>(indent));
2631         }
2632         else
2633         {
2634             dump(ss, false, 0);
2635         }
2636
2637         return ss.str();
2638     }
2639
2640     /*!
2641     @brief return the type of the JSON value (explicit)
2642
2643     Return the type of the JSON value as a value from the @ref value_t
2644     enumeration.
2645
2646     @return the type of the JSON value
2647
2648     @complexity Constant.
2649
2650     @exceptionsafety No-throw guarantee: this member function never throws
2651     exceptions.
2652
2653     @liveexample{The following code exemplifies `type()` for all JSON
2654     types.,type}
2655
2656     @since version 1.0.0
2657     */
2658     constexpr value_t type() const noexcept
2659     {
2660         return m_type;
2661     }
2662
2663     /*!
2664     @brief return whether type is primitive
2665
2666     This function returns true iff the JSON type is primitive (string, number,
2667     boolean, or null).
2668
2669     @return `true` if type is primitive (string, number, boolean, or null),
2670     `false` otherwise.
2671
2672     @complexity Constant.
2673
2674     @exceptionsafety No-throw guarantee: this member function never throws
2675     exceptions.
2676
2677     @liveexample{The following code exemplifies `is_primitive()` for all JSON
2678     types.,is_primitive}
2679
2680     @sa @ref is_structured() -- returns whether JSON value is structured
2681     @sa @ref is_null() -- returns whether JSON value is `null`
2682     @sa @ref is_string() -- returns whether JSON value is a string
2683     @sa @ref is_boolean() -- returns whether JSON value is a boolean
2684     @sa @ref is_number() -- returns whether JSON value is a number
2685
2686     @since version 1.0.0
2687     */
2688     constexpr bool is_primitive() const noexcept
2689     {
2690         return is_null() or is_string() or is_boolean() or is_number();
2691     }
2692
2693     /*!
2694     @brief return whether type is structured
2695
2696     This function returns true iff the JSON type is structured (array or
2697     object).
2698
2699     @return `true` if type is structured (array or object), `false` otherwise.
2700
2701     @complexity Constant.
2702
2703     @exceptionsafety No-throw guarantee: this member function never throws
2704     exceptions.
2705
2706     @liveexample{The following code exemplifies `is_structured()` for all JSON
2707     types.,is_structured}
2708
2709     @sa @ref is_primitive() -- returns whether value is primitive
2710     @sa @ref is_array() -- returns whether value is an array
2711     @sa @ref is_object() -- returns whether value is an object
2712
2713     @since version 1.0.0
2714     */
2715     constexpr bool is_structured() const noexcept
2716     {
2717         return is_array() or is_object();
2718     }
2719
2720     /*!
2721     @brief return whether value is null
2722
2723     This function returns true iff the JSON value is null.
2724
2725     @return `true` if type is null, `false` otherwise.
2726
2727     @complexity Constant.
2728
2729     @exceptionsafety No-throw guarantee: this member function never throws
2730     exceptions.
2731
2732     @liveexample{The following code exemplifies `is_null()` for all JSON
2733     types.,is_null}
2734
2735     @since version 1.0.0
2736     */
2737     constexpr bool is_null() const noexcept
2738     {
2739         return m_type == value_t::null;
2740     }
2741
2742     /*!
2743     @brief return whether value is a boolean
2744
2745     This function returns true iff the JSON value is a boolean.
2746
2747     @return `true` if type is boolean, `false` otherwise.
2748
2749     @complexity Constant.
2750
2751     @exceptionsafety No-throw guarantee: this member function never throws
2752     exceptions.
2753
2754     @liveexample{The following code exemplifies `is_boolean()` for all JSON
2755     types.,is_boolean}
2756
2757     @since version 1.0.0
2758     */
2759     constexpr bool is_boolean() const noexcept
2760     {
2761         return m_type == value_t::boolean;
2762     }
2763
2764     /*!
2765     @brief return whether value is a number
2766
2767     This function returns true iff the JSON value is a number. This includes
2768     both integer and floating-point values.
2769
2770     @return `true` if type is number (regardless whether integer, unsigned
2771     integer or floating-type), `false` otherwise.
2772
2773     @complexity Constant.
2774
2775     @exceptionsafety No-throw guarantee: this member function never throws
2776     exceptions.
2777
2778     @liveexample{The following code exemplifies `is_number()` for all JSON
2779     types.,is_number}
2780
2781     @sa @ref is_number_integer() -- check if value is an integer or unsigned
2782     integer number
2783     @sa @ref is_number_unsigned() -- check if value is an unsigned integer
2784     number
2785     @sa @ref is_number_float() -- check if value is a floating-point number
2786
2787     @since version 1.0.0
2788     */
2789     constexpr bool is_number() const noexcept
2790     {
2791         return is_number_integer() or is_number_float();
2792     }
2793
2794     /*!
2795     @brief return whether value is an integer number
2796
2797     This function returns true iff the JSON value is an integer or unsigned
2798     integer number. This excludes floating-point values.
2799
2800     @return `true` if type is an integer or unsigned integer number, `false`
2801     otherwise.
2802
2803     @complexity Constant.
2804
2805     @exceptionsafety No-throw guarantee: this member function never throws
2806     exceptions.
2807
2808     @liveexample{The following code exemplifies `is_number_integer()` for all
2809     JSON types.,is_number_integer}
2810
2811     @sa @ref is_number() -- check if value is a number
2812     @sa @ref is_number_unsigned() -- check if value is an unsigned integer
2813     number
2814     @sa @ref is_number_float() -- check if value is a floating-point number
2815
2816     @since version 1.0.0
2817     */
2818     constexpr bool is_number_integer() const noexcept
2819     {
2820         return m_type == value_t::number_integer or m_type == value_t::number_unsigned;
2821     }
2822
2823     /*!
2824     @brief return whether value is an unsigned integer number
2825
2826     This function returns true iff the JSON value is an unsigned integer
2827     number. This excludes floating-point and (signed) integer values.
2828
2829     @return `true` if type is an unsigned integer number, `false` otherwise.
2830
2831     @complexity Constant.
2832
2833     @exceptionsafety No-throw guarantee: this member function never throws
2834     exceptions.
2835
2836     @liveexample{The following code exemplifies `is_number_unsigned()` for all
2837     JSON types.,is_number_unsigned}
2838
2839     @sa @ref is_number() -- check if value is a number
2840     @sa @ref is_number_integer() -- check if value is an integer or unsigned
2841     integer number
2842     @sa @ref is_number_float() -- check if value is a floating-point number
2843
2844     @since version 2.0.0
2845     */
2846     constexpr bool is_number_unsigned() const noexcept
2847     {
2848         return m_type == value_t::number_unsigned;
2849     }
2850
2851     /*!
2852     @brief return whether value is a floating-point number
2853
2854     This function returns true iff the JSON value is a floating-point number.
2855     This excludes integer and unsigned integer values.
2856
2857     @return `true` if type is a floating-point number, `false` otherwise.
2858
2859     @complexity Constant.
2860
2861     @exceptionsafety No-throw guarantee: this member function never throws
2862     exceptions.
2863
2864     @liveexample{The following code exemplifies `is_number_float()` for all
2865     JSON types.,is_number_float}
2866
2867     @sa @ref is_number() -- check if value is number
2868     @sa @ref is_number_integer() -- check if value is an integer number
2869     @sa @ref is_number_unsigned() -- check if value is an unsigned integer
2870     number
2871
2872     @since version 1.0.0
2873     */
2874     constexpr bool is_number_float() const noexcept
2875     {
2876         return m_type == value_t::number_float;
2877     }
2878
2879     /*!
2880     @brief return whether value is an object
2881
2882     This function returns true iff the JSON value is an object.
2883
2884     @return `true` if type is object, `false` otherwise.
2885
2886     @complexity Constant.
2887
2888     @exceptionsafety No-throw guarantee: this member function never throws
2889     exceptions.
2890
2891     @liveexample{The following code exemplifies `is_object()` for all JSON
2892     types.,is_object}
2893
2894     @since version 1.0.0
2895     */
2896     constexpr bool is_object() const noexcept
2897     {
2898         return m_type == value_t::object;
2899     }
2900
2901     /*!
2902     @brief return whether value is an array
2903
2904     This function returns true iff the JSON value is an array.
2905
2906     @return `true` if type is array, `false` otherwise.
2907
2908     @complexity Constant.
2909
2910     @exceptionsafety No-throw guarantee: this member function never throws
2911     exceptions.
2912
2913     @liveexample{The following code exemplifies `is_array()` for all JSON
2914     types.,is_array}
2915
2916     @since version 1.0.0
2917     */
2918     constexpr bool is_array() const noexcept
2919     {
2920         return m_type == value_t::array;
2921     }
2922
2923     /*!
2924     @brief return whether value is a string
2925
2926     This function returns true iff the JSON value is a string.
2927
2928     @return `true` if type is string, `false` otherwise.
2929
2930     @complexity Constant.
2931
2932     @exceptionsafety No-throw guarantee: this member function never throws
2933     exceptions.
2934
2935     @liveexample{The following code exemplifies `is_string()` for all JSON
2936     types.,is_string}
2937
2938     @since version 1.0.0
2939     */
2940     constexpr bool is_string() const noexcept
2941     {
2942         return m_type == value_t::string;
2943     }
2944
2945     /*!
2946     @brief return whether value is discarded
2947
2948     This function returns true iff the JSON value was discarded during parsing
2949     with a callback function (see @ref parser_callback_t).
2950
2951     @note This function will always be `false` for JSON values after parsing.
2952     That is, discarded values can only occur during parsing, but will be
2953     removed when inside a structured value or replaced by null in other cases.
2954
2955     @return `true` if type is discarded, `false` otherwise.
2956
2957     @complexity Constant.
2958
2959     @exceptionsafety No-throw guarantee: this member function never throws
2960     exceptions.
2961
2962     @liveexample{The following code exemplifies `is_discarded()` for all JSON
2963     types.,is_discarded}
2964
2965     @since version 1.0.0
2966     */
2967     constexpr bool is_discarded() const noexcept
2968     {
2969         return m_type == value_t::discarded;
2970     }
2971
2972     /*!
2973     @brief return the type of the JSON value (implicit)
2974
2975     Implicitly return the type of the JSON value as a value from the @ref
2976     value_t enumeration.
2977
2978     @return the type of the JSON value
2979
2980     @complexity Constant.
2981
2982     @exceptionsafety No-throw guarantee: this member function never throws
2983     exceptions.
2984
2985     @liveexample{The following code exemplifies the @ref value_t operator for
2986     all JSON types.,operator__value_t}
2987
2988     @since version 1.0.0
2989     */
2990     constexpr operator value_t() const noexcept
2991     {
2992         return m_type;
2993     }
2994
2995     /// @}
2996
2997   private:
2998     //////////////////
2999     // value access //
3000     //////////////////
3001
3002     /// get a boolean (explicit)
3003     boolean_t get_impl(boolean_t* /*unused*/) const
3004     {
3005         if (is_boolean())
3006         {
3007             return m_value.boolean;
3008         }
3009
3010         JSON_THROW(std::domain_error("type must be boolean, but is " + type_name()));
3011     }
3012
3013     /// get a pointer to the value (object)
3014     object_t* get_impl_ptr(object_t* /*unused*/) noexcept
3015     {
3016         return is_object() ? m_value.object : nullptr;
3017     }
3018
3019     /// get a pointer to the value (object)
3020     constexpr const object_t* get_impl_ptr(const object_t* /*unused*/) const noexcept
3021     {
3022         return is_object() ? m_value.object : nullptr;
3023     }
3024
3025     /// get a pointer to the value (array)
3026     array_t* get_impl_ptr(array_t* /*unused*/) noexcept
3027     {
3028         return is_array() ? m_value.array : nullptr;
3029     }
3030
3031     /// get a pointer to the value (array)
3032     constexpr const array_t* get_impl_ptr(const array_t* /*unused*/) const noexcept
3033     {
3034         return is_array() ? m_value.array : nullptr;
3035     }
3036
3037     /// get a pointer to the value (string)
3038     string_t* get_impl_ptr(string_t* /*unused*/) noexcept
3039     {
3040         return is_string() ? m_value.string : nullptr;
3041     }
3042
3043     /// get a pointer to the value (string)
3044     constexpr const string_t* get_impl_ptr(const string_t* /*unused*/) const noexcept
3045     {
3046         return is_string() ? m_value.string : nullptr;
3047     }
3048
3049     /// get a pointer to the value (boolean)
3050     boolean_t* get_impl_ptr(boolean_t* /*unused*/) noexcept
3051     {
3052         return is_boolean() ? &m_value.boolean : nullptr;
3053     }
3054
3055     /// get a pointer to the value (boolean)
3056     constexpr const boolean_t* get_impl_ptr(const boolean_t* /*unused*/) const noexcept
3057     {
3058         return is_boolean() ? &m_value.boolean : nullptr;
3059     }
3060
3061     /// get a pointer to the value (integer number)
3062     number_integer_t* get_impl_ptr(number_integer_t* /*unused*/) noexcept
3063     {
3064         return is_number_integer() ? &m_value.number_integer : nullptr;
3065     }
3066
3067     /// get a pointer to the value (integer number)
3068     constexpr const number_integer_t* get_impl_ptr(const number_integer_t* /*unused*/) const noexcept
3069     {
3070         return is_number_integer() ? &m_value.number_integer : nullptr;
3071     }
3072
3073     /// get a pointer to the value (unsigned number)
3074     number_unsigned_t* get_impl_ptr(number_unsigned_t* /*unused*/) noexcept
3075     {
3076         return is_number_unsigned() ? &m_value.number_unsigned : nullptr;
3077     }
3078
3079     /// get a pointer to the value (unsigned number)
3080     constexpr const number_unsigned_t* get_impl_ptr(const number_unsigned_t* /*unused*/) const noexcept
3081     {
3082         return is_number_unsigned() ? &m_value.number_unsigned : nullptr;
3083     }
3084
3085     /// get a pointer to the value (floating-point number)
3086     number_float_t* get_impl_ptr(number_float_t* /*unused*/) noexcept
3087     {
3088         return is_number_float() ? &m_value.number_float : nullptr;
3089     }
3090
3091     /// get a pointer to the value (floating-point number)
3092     constexpr const number_float_t* get_impl_ptr(const number_float_t* /*unused*/) const noexcept
3093     {
3094         return is_number_float() ? &m_value.number_float : nullptr;
3095     }
3096
3097     /*!
3098     @brief helper function to implement get_ref()
3099
3100     This funcion helps to implement get_ref() without code duplication for
3101     const and non-const overloads
3102
3103     @tparam ThisType will be deduced as `basic_json` or `const basic_json`
3104
3105     @throw std::domain_error if ReferenceType does not match underlying value
3106     type of the current JSON
3107     */
3108     template<typename ReferenceType, typename ThisType>
3109     static ReferenceType get_ref_impl(ThisType& obj)
3110     {
3111         // helper type
3112         using PointerType = typename std::add_pointer<ReferenceType>::type;
3113
3114         // delegate the call to get_ptr<>()
3115         auto ptr = obj.template get_ptr<PointerType>();
3116
3117         if (ptr != nullptr)
3118         {
3119             return *ptr;
3120         }
3121
3122         JSON_THROW(std::domain_error("incompatible ReferenceType for get_ref, actual type is " +
3123                                      obj.type_name()));
3124     }
3125
3126   public:
3127     /// @name value access
3128     /// Direct access to the stored value of a JSON value.
3129     /// @{
3130
3131     /*!
3132     @brief get special-case overload
3133
3134     This overloads avoids a lot of template boilerplate, it can be seen as the
3135     identity method
3136
3137     @tparam BasicJsonType == @ref basic_json
3138
3139     @return a copy of *this
3140
3141     @complexity Constant.
3142
3143     @since version 2.1.0
3144     */
3145     template <
3146         typename BasicJsonType,
3147         detail::enable_if_t<std::is_same<typename std::remove_const<BasicJsonType>::type,
3148                                          basic_json_t>::value,
3149                             int> = 0 >
3150     basic_json get() const
3151     {
3152         return *this;
3153     }
3154
3155     /*!
3156     @brief get a value (explicit)
3157
3158     Explicit type conversion between the JSON value and a compatible value
3159     which is [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible)
3160     and [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible).
3161     The value is converted by calling the @ref json_serializer<ValueType>
3162     `from_json()` method.
3163
3164     The function is equivalent to executing
3165     @code {.cpp}
3166     ValueType ret;
3167     JSONSerializer<ValueType>::from_json(*this, ret);
3168     return ret;
3169     @endcode
3170
3171     This overloads is chosen if:
3172     - @a ValueType is not @ref basic_json,
3173     - @ref json_serializer<ValueType> has a `from_json()` method of the form
3174       `void from_json(const @ref basic_json&, ValueType&)`, and
3175     - @ref json_serializer<ValueType> does not have a `from_json()` method of
3176       the form `ValueType from_json(const @ref basic_json&)`
3177
3178     @tparam ValueTypeCV the provided value type
3179     @tparam ValueType the returned value type
3180
3181     @return copy of the JSON value, converted to @a ValueType
3182
3183     @throw what @ref json_serializer<ValueType> `from_json()` method throws
3184
3185     @liveexample{The example below shows several conversions from JSON values
3186     to other types. There a few things to note: (1) Floating-point numbers can
3187     be converted to integers\, (2) A JSON array can be converted to a standard
3188     `std::vector<short>`\, (3) A JSON object can be converted to C++
3189     associative containers such as `std::unordered_map<std::string\,
3190     json>`.,get__ValueType_const}
3191
3192     @since version 2.1.0
3193     */
3194     template <
3195         typename ValueTypeCV,
3196         typename ValueType = detail::uncvref_t<ValueTypeCV>,
3197         detail::enable_if_t <
3198             not std::is_same<basic_json_t, ValueType>::value and
3199             detail::has_from_json<basic_json_t, ValueType>::value and
3200             not detail::has_non_default_from_json<basic_json_t, ValueType>::value,
3201             int > = 0 >
3202     ValueType get() const noexcept(noexcept(
3203                                        JSONSerializer<ValueType>::from_json(std::declval<const basic_json_t&>(), std::declval<ValueType&>())))
3204     {
3205         // we cannot static_assert on ValueTypeCV being non-const, because
3206         // there is support for get<const basic_json_t>(), which is why we
3207         // still need the uncvref
3208         static_assert(not std::is_reference<ValueTypeCV>::value,
3209                       "get() cannot be used with reference types, you might want to use get_ref()");
3210         static_assert(std::is_default_constructible<ValueType>::value,
3211                       "types must be DefaultConstructible when used with get()");
3212
3213         ValueType ret;
3214         JSONSerializer<ValueType>::from_json(*this, ret);
3215         return ret;
3216     }
3217
3218     /*!
3219     @brief get a value (explicit); special case
3220
3221     Explicit type conversion between the JSON value and a compatible value
3222     which is **not** [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible)
3223     and **not** [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible).
3224     The value is converted by calling the @ref json_serializer<ValueType>
3225     `from_json()` method.
3226
3227     The function is equivalent to executing
3228     @code {.cpp}
3229     return JSONSerializer<ValueTypeCV>::from_json(*this);
3230     @endcode
3231
3232     This overloads is chosen if:
3233     - @a ValueType is not @ref basic_json and
3234     - @ref json_serializer<ValueType> has a `from_json()` method of the form
3235       `ValueType from_json(const @ref basic_json&)`
3236
3237     @note If @ref json_serializer<ValueType> has both overloads of
3238     `from_json()`, this one is chosen.
3239
3240     @tparam ValueTypeCV the provided value type
3241     @tparam ValueType the returned value type
3242
3243     @return copy of the JSON value, converted to @a ValueType
3244
3245     @throw what @ref json_serializer<ValueType> `from_json()` method throws
3246
3247     @since version 2.1.0
3248     */
3249     template <
3250         typename ValueTypeCV,
3251         typename ValueType = detail::uncvref_t<ValueTypeCV>,
3252         detail::enable_if_t<not std::is_same<basic_json_t, ValueType>::value and
3253                             detail::has_non_default_from_json<basic_json_t,
3254                                     ValueType>::value, int> = 0 >
3255     ValueType get() const noexcept(noexcept(
3256                                        JSONSerializer<ValueTypeCV>::from_json(std::declval<const basic_json_t&>())))
3257     {
3258         static_assert(not std::is_reference<ValueTypeCV>::value,
3259                       "get() cannot be used with reference types, you might want to use get_ref()");
3260         return JSONSerializer<ValueTypeCV>::from_json(*this);
3261     }
3262
3263     /*!
3264     @brief get a pointer value (explicit)
3265
3266     Explicit pointer access to the internally stored JSON value. No copies are
3267     made.
3268
3269     @warning The pointer becomes invalid if the underlying JSON object
3270     changes.
3271
3272     @tparam PointerType pointer type; must be a pointer to @ref array_t, @ref
3273     object_t, @ref string_t, @ref boolean_t, @ref number_integer_t,
3274     @ref number_unsigned_t, or @ref number_float_t.
3275
3276     @return pointer to the internally stored JSON value if the requested
3277     pointer type @a PointerType fits to the JSON value; `nullptr` otherwise
3278
3279     @complexity Constant.
3280
3281     @liveexample{The example below shows how pointers to internal values of a
3282     JSON value can be requested. Note that no type conversions are made and a
3283     `nullptr` is returned if the value and the requested pointer type does not
3284     match.,get__PointerType}
3285
3286     @sa @ref get_ptr() for explicit pointer-member access
3287
3288     @since version 1.0.0
3289     */
3290     template<typename PointerType, typename std::enable_if<
3291                  std::is_pointer<PointerType>::value, int>::type = 0>
3292     PointerType get() noexcept
3293     {
3294         // delegate the call to get_ptr
3295         return get_ptr<PointerType>();
3296     }
3297
3298     /*!
3299     @brief get a pointer value (explicit)
3300     @copydoc get()
3301     */
3302     template<typename PointerType, typename std::enable_if<
3303                  std::is_pointer<PointerType>::value, int>::type = 0>
3304     constexpr const PointerType get() const noexcept
3305     {
3306         // delegate the call to get_ptr
3307         return get_ptr<PointerType>();
3308     }
3309
3310     /*!
3311     @brief get a pointer value (implicit)
3312
3313     Implicit pointer access to the internally stored JSON value. No copies are
3314     made.
3315
3316     @warning Writing data to the pointee of the result yields an undefined
3317     state.
3318
3319     @tparam PointerType pointer type; must be a pointer to @ref array_t, @ref
3320     object_t, @ref string_t, @ref boolean_t, @ref number_integer_t,
3321     @ref number_unsigned_t, or @ref number_float_t. Enforced by a static
3322     assertion.
3323
3324     @return pointer to the internally stored JSON value if the requested
3325     pointer type @a PointerType fits to the JSON value; `nullptr` otherwise
3326
3327     @complexity Constant.
3328
3329     @liveexample{The example below shows how pointers to internal values of a
3330     JSON value can be requested. Note that no type conversions are made and a
3331     `nullptr` is returned if the value and the requested pointer type does not
3332     match.,get_ptr}
3333
3334     @since version 1.0.0
3335     */
3336     template<typename PointerType, typename std::enable_if<
3337                  std::is_pointer<PointerType>::value, int>::type = 0>
3338     PointerType get_ptr() noexcept
3339     {
3340         // get the type of the PointerType (remove pointer and const)
3341         using pointee_t = typename std::remove_const<typename
3342                           std::remove_pointer<typename
3343                           std::remove_const<PointerType>::type>::type>::type;
3344         // make sure the type matches the allowed types
3345         static_assert(
3346             std::is_same<object_t, pointee_t>::value
3347             or std::is_same<array_t, pointee_t>::value
3348             or std::is_same<string_t, pointee_t>::value
3349             or std::is_same<boolean_t, pointee_t>::value
3350             or std::is_same<number_integer_t, pointee_t>::value
3351             or std::is_same<number_unsigned_t, pointee_t>::value
3352             or std::is_same<number_float_t, pointee_t>::value
3353             , "incompatible pointer type");
3354
3355         // delegate the call to get_impl_ptr<>()
3356         return get_impl_ptr(static_cast<PointerType>(nullptr));
3357     }
3358
3359     /*!
3360     @brief get a pointer value (implicit)
3361     @copydoc get_ptr()
3362     */
3363     template<typename PointerType, typename std::enable_if<
3364                  std::is_pointer<PointerType>::value and
3365                  std::is_const<typename std::remove_pointer<PointerType>::type>::value, int>::type = 0>
3366     constexpr const PointerType get_ptr() const noexcept
3367     {
3368         // get the type of the PointerType (remove pointer and const)
3369         using pointee_t = typename std::remove_const<typename
3370                           std::remove_pointer<typename
3371                           std::remove_const<PointerType>::type>::type>::type;
3372         // make sure the type matches the allowed types
3373         static_assert(
3374             std::is_same<object_t, pointee_t>::value
3375             or std::is_same<array_t, pointee_t>::value
3376             or std::is_same<string_t, pointee_t>::value
3377             or std::is_same<boolean_t, pointee_t>::value
3378             or std::is_same<number_integer_t, pointee_t>::value
3379             or std::is_same<number_unsigned_t, pointee_t>::value
3380             or std::is_same<number_float_t, pointee_t>::value
3381             , "incompatible pointer type");
3382
3383         // delegate the call to get_impl_ptr<>() const
3384         return get_impl_ptr(static_cast<const PointerType>(nullptr));
3385     }
3386
3387     /*!
3388     @brief get a reference value (implicit)
3389
3390     Implicit reference access to the internally stored JSON value. No copies
3391     are made.
3392
3393     @warning Writing data to the referee of the result yields an undefined
3394     state.
3395
3396     @tparam ReferenceType reference type; must be a reference to @ref array_t,
3397     @ref object_t, @ref string_t, @ref boolean_t, @ref number_integer_t, or
3398     @ref number_float_t. Enforced by static assertion.
3399
3400     @return reference to the internally stored JSON value if the requested
3401     reference type @a ReferenceType fits to the JSON value; throws
3402     std::domain_error otherwise
3403
3404     @throw std::domain_error in case passed type @a ReferenceType is
3405     incompatible with the stored JSON value
3406
3407     @complexity Constant.
3408
3409     @liveexample{The example shows several calls to `get_ref()`.,get_ref}
3410
3411     @since version 1.1.0
3412     */
3413     template<typename ReferenceType, typename std::enable_if<
3414                  std::is_reference<ReferenceType>::value, int>::type = 0>
3415     ReferenceType get_ref()
3416     {
3417         // delegate call to get_ref_impl
3418         return get_ref_impl<ReferenceType>(*this);
3419     }
3420
3421     /*!
3422     @brief get a reference value (implicit)
3423     @copydoc get_ref()
3424     */
3425     template<typename ReferenceType, typename std::enable_if<
3426                  std::is_reference<ReferenceType>::value and
3427                  std::is_const<typename std::remove_reference<ReferenceType>::type>::value, int>::type = 0>
3428     ReferenceType get_ref() const
3429     {
3430         // delegate call to get_ref_impl
3431         return get_ref_impl<ReferenceType>(*this);
3432     }
3433
3434     /*!
3435     @brief get a value (implicit)
3436
3437     Implicit type conversion between the JSON value and a compatible value.
3438     The call is realized by calling @ref get() const.
3439
3440     @tparam ValueType non-pointer type compatible to the JSON value, for
3441     instance `int` for JSON integer numbers, `bool` for JSON booleans, or
3442     `std::vector` types for JSON arrays. The character type of @ref string_t
3443     as well as an initializer list of this type is excluded to avoid
3444     ambiguities as these types implicitly convert to `std::string`.
3445
3446     @return copy of the JSON value, converted to type @a ValueType
3447
3448     @throw std::domain_error in case passed type @a ValueType is incompatible
3449     to JSON, thrown by @ref get() const
3450
3451     @complexity Linear in the size of the JSON value.
3452
3453     @liveexample{The example below shows several conversions from JSON values
3454     to other types. There a few things to note: (1) Floating-point numbers can
3455     be converted to integers\, (2) A JSON array can be converted to a standard
3456     `std::vector<short>`\, (3) A JSON object can be converted to C++
3457     associative containers such as `std::unordered_map<std::string\,
3458     json>`.,operator__ValueType}
3459
3460     @since version 1.0.0
3461     */
3462     template < typename ValueType, typename std::enable_if <
3463                    not std::is_pointer<ValueType>::value and
3464                    not std::is_same<ValueType, typename string_t::value_type>::value
3465 #ifndef _MSC_VER  // fix for issue #167 operator<< ambiguity under VS2015
3466                    and not std::is_same<ValueType, std::initializer_list<typename string_t::value_type>>::value
3467 #endif
3468                    , int >::type = 0 >
3469     operator ValueType() const
3470     {
3471         // delegate the call to get<>() const
3472         return get<ValueType>();
3473     }
3474
3475     /// @}
3476
3477
3478     ////////////////////
3479     // element access //
3480     ////////////////////
3481
3482     /// @name element access
3483     /// Access to the JSON value.
3484     /// @{
3485
3486     /*!
3487     @brief access specified array element with bounds checking
3488
3489     Returns a reference to the element at specified location @a idx, with
3490     bounds checking.
3491
3492     @param[in] idx  index of the element to access
3493
3494     @return reference to the element at index @a idx
3495
3496     @throw std::domain_error if the JSON value is not an array; example:
3497     `"cannot use at() with string"`
3498     @throw std::out_of_range if the index @a idx is out of range of the array;
3499     that is, `idx >= size()`; example: `"array index 7 is out of range"`
3500
3501     @complexity Constant.
3502
3503     @liveexample{The example below shows how array elements can be read and
3504     written using `at()`.,at__size_type}
3505
3506     @since version 1.0.0
3507     */
3508     reference at(size_type idx)
3509     {
3510         // at only works for arrays
3511         if (is_array())
3512         {
3513             JSON_TRY
3514             {
3515                 return m_value.array->at(idx);
3516             }
3517             JSON_CATCH (std::out_of_range&)
3518             {
3519                 // create better exception explanation
3520                 JSON_THROW(std::out_of_range("array index " + std::to_string(idx) + " is out of range"));
3521             }
3522         }
3523         else
3524         {
3525             JSON_THROW(std::domain_error("cannot use at() with " + type_name()));
3526         }
3527     }
3528
3529     /*!
3530     @brief access specified array element with bounds checking
3531
3532     Returns a const reference to the element at specified location @a idx,
3533     with bounds checking.
3534
3535     @param[in] idx  index of the element to access
3536
3537     @return const reference to the element at index @a idx
3538
3539     @throw std::domain_error if the JSON value is not an array; example:
3540     `"cannot use at() with string"`
3541     @throw std::out_of_range if the index @a idx is out of range of the array;
3542     that is, `idx >= size()`; example: `"array index 7 is out of range"`
3543
3544     @complexity Constant.
3545
3546     @liveexample{The example below shows how array elements can be read using
3547     `at()`.,at__size_type_const}
3548
3549     @since version 1.0.0
3550     */
3551     const_reference at(size_type idx) const
3552     {
3553         // at only works for arrays
3554         if (is_array())
3555         {
3556             JSON_TRY
3557             {
3558                 return m_value.array->at(idx);
3559             }
3560             JSON_CATCH (std::out_of_range&)
3561             {
3562                 // create better exception explanation
3563                 JSON_THROW(std::out_of_range("array index " + std::to_string(idx) + " is out of range"));
3564             }
3565         }
3566         else
3567         {
3568             JSON_THROW(std::domain_error("cannot use at() with " + type_name()));
3569         }
3570     }
3571
3572     /*!
3573     @brief access specified object element with bounds checking
3574
3575     Returns a reference to the element at with specified key @a key, with
3576     bounds checking.
3577
3578     @param[in] key  key of the element to access
3579
3580     @return reference to the element at key @a key
3581
3582     @throw std::domain_error if the JSON value is not an object; example:
3583     `"cannot use at() with boolean"`
3584     @throw std::out_of_range if the key @a key is is not stored in the object;
3585     that is, `find(key) == end()`; example: `"key "the fast" not found"`
3586
3587     @complexity Logarithmic in the size of the container.
3588
3589     @liveexample{The example below shows how object elements can be read and
3590     written using `at()`.,at__object_t_key_type}
3591
3592     @sa @ref operator[](const typename object_t::key_type&) for unchecked
3593     access by reference
3594     @sa @ref value() for access by value with a default value
3595
3596     @since version 1.0.0
3597     */
3598     reference at(const typename object_t::key_type& key)
3599     {
3600         // at only works for objects
3601         if (is_object())
3602         {
3603             JSON_TRY
3604             {
3605                 return m_value.object->at(key);
3606             }
3607             JSON_CATCH (std::out_of_range&)
3608             {
3609                 // create better exception explanation
3610                 JSON_THROW(std::out_of_range("key '" + key + "' not found"));
3611             }
3612         }
3613         else
3614         {
3615             JSON_THROW(std::domain_error("cannot use at() with " + type_name()));
3616         }
3617     }
3618
3619     /*!
3620     @brief access specified object element with bounds checking
3621
3622     Returns a const reference to the element at with specified key @a key,
3623     with bounds checking.
3624
3625     @param[in] key  key of the element to access
3626
3627     @return const reference to the element at key @a key
3628
3629     @throw std::domain_error if the JSON value is not an object; example:
3630     `"cannot use at() with boolean"`
3631     @throw std::out_of_range if the key @a key is is not stored in the object;
3632     that is, `find(key) == end()`; example: `"key "the fast" not found"`
3633
3634     @complexity Logarithmic in the size of the container.
3635
3636     @liveexample{The example below shows how object elements can be read using
3637     `at()`.,at__object_t_key_type_const}
3638
3639     @sa @ref operator[](const typename object_t::key_type&) for unchecked
3640     access by reference
3641     @sa @ref value() for access by value with a default value
3642
3643     @since version 1.0.0
3644     */
3645     const_reference at(const typename object_t::key_type& key) const
3646     {
3647         // at only works for objects
3648         if (is_object())
3649         {
3650             JSON_TRY
3651             {
3652                 return m_value.object->at(key);
3653             }
3654             JSON_CATCH (std::out_of_range&)
3655             {
3656                 // create better exception explanation
3657                 JSON_THROW(std::out_of_range("key '" + key + "' not found"));
3658             }
3659         }
3660         else
3661         {
3662             JSON_THROW(std::domain_error("cannot use at() with " + type_name()));
3663         }
3664     }
3665
3666     /*!
3667     @brief access specified array element
3668
3669     Returns a reference to the element at specified location @a idx.
3670
3671     @note If @a idx is beyond the range of the array (i.e., `idx >= size()`),
3672     then the array is silently filled up with `null` values to make `idx` a
3673     valid reference to the last stored element.
3674
3675     @param[in] idx  index of the element to access
3676
3677     @return reference to the element at index @a idx
3678
3679     @throw std::domain_error if JSON is not an array or null; example:
3680     `"cannot use operator[] with string"`
3681
3682     @complexity Constant if @a idx is in the range of the array. Otherwise
3683     linear in `idx - size()`.
3684
3685     @liveexample{The example below shows how array elements can be read and
3686     written using `[]` operator. Note the addition of `null`
3687     values.,operatorarray__size_type}
3688
3689     @since version 1.0.0
3690     */
3691     reference operator[](size_type idx)
3692     {
3693         // implicitly convert null value to an empty array
3694         if (is_null())
3695         {
3696             m_type = value_t::array;
3697             m_value.array = create<array_t>();
3698             assert_invariant();
3699         }
3700
3701         // operator[] only works for arrays
3702         if (is_array())
3703         {
3704             // fill up array with null values if given idx is outside range
3705             if (idx >= m_value.array->size())
3706             {
3707                 m_value.array->insert(m_value.array->end(),
3708                                       idx - m_value.array->size() + 1,
3709                                       basic_json());
3710             }
3711
3712             return m_value.array->operator[](idx);
3713         }
3714
3715         JSON_THROW(std::domain_error("cannot use operator[] with " + type_name()));
3716     }
3717
3718     /*!
3719     @brief access specified array element
3720
3721     Returns a const reference to the element at specified location @a idx.
3722
3723     @param[in] idx  index of the element to access
3724
3725     @return const reference to the element at index @a idx
3726
3727     @throw std::domain_error if JSON is not an array; example: `"cannot use
3728     operator[] with null"`
3729
3730     @complexity Constant.
3731
3732     @liveexample{The example below shows how array elements can be read using
3733     the `[]` operator.,operatorarray__size_type_const}
3734
3735     @since version 1.0.0
3736     */
3737     const_reference operator[](size_type idx) const
3738     {
3739         // const operator[] only works for arrays
3740         if (is_array())
3741         {
3742             return m_value.array->operator[](idx);
3743         }
3744
3745         JSON_THROW(std::domain_error("cannot use operator[] with " + type_name()));
3746     }
3747
3748     /*!
3749     @brief access specified object element
3750
3751     Returns a reference to the element at with specified key @a key.
3752
3753     @note If @a key is not found in the object, then it is silently added to
3754     the object and filled with a `null` value to make `key` a valid reference.
3755     In case the value was `null` before, it is converted to an object.
3756
3757     @param[in] key  key of the element to access
3758
3759     @return reference to the element at key @a key
3760
3761     @throw std::domain_error if JSON is not an object or null; example:
3762     `"cannot use operator[] with string"`
3763
3764     @complexity Logarithmic in the size of the container.
3765
3766     @liveexample{The example below shows how object elements can be read and
3767     written using the `[]` operator.,operatorarray__key_type}
3768
3769     @sa @ref at(const typename object_t::key_type&) for access by reference
3770     with range checking
3771     @sa @ref value() for access by value with a default value
3772
3773     @since version 1.0.0
3774     */
3775     reference operator[](const typename object_t::key_type& key)
3776     {
3777         // implicitly convert null value to an empty object
3778         if (is_null())
3779         {
3780             m_type = value_t::object;
3781             m_value.object = create<object_t>();
3782             assert_invariant();
3783         }
3784
3785         // operator[] only works for objects
3786         if (is_object())
3787         {
3788             return m_value.object->operator[](key);
3789         }
3790
3791         JSON_THROW(std::domain_error("cannot use operator[] with " + type_name()));
3792     }
3793
3794     /*!
3795     @brief read-only access specified object element
3796
3797     Returns a const reference to the element at with specified key @a key. No
3798     bounds checking is performed.
3799
3800     @warning If the element with key @a key does not exist, the behavior is
3801     undefined.
3802
3803     @param[in] key  key of the element to access
3804
3805     @return const reference to the element at key @a key
3806
3807     @pre The element with key @a key must exist. **This precondition is
3808          enforced with an assertion.**
3809
3810     @throw std::domain_error if JSON is not an object; example: `"cannot use
3811     operator[] with null"`
3812
3813     @complexity Logarithmic in the size of the container.
3814
3815     @liveexample{The example below shows how object elements can be read using
3816     the `[]` operator.,operatorarray__key_type_const}
3817
3818     @sa @ref at(const typename object_t::key_type&) for access by reference
3819     with range checking
3820     @sa @ref value() for access by value with a default value
3821
3822     @since version 1.0.0
3823     */
3824     const_reference operator[](const typename object_t::key_type& key) const
3825     {
3826         // const operator[] only works for objects
3827         if (is_object())
3828         {
3829             assert(m_value.object->find(key) != m_value.object->end());
3830             return m_value.object->find(key)->second;
3831         }
3832
3833         JSON_THROW(std::domain_error("cannot use operator[] with " + type_name()));
3834     }
3835
3836     /*!
3837     @brief access specified object element
3838
3839     Returns a reference to the element at with specified key @a key.
3840
3841     @note If @a key is not found in the object, then it is silently added to
3842     the object and filled with a `null` value to make `key` a valid reference.
3843     In case the value was `null` before, it is converted to an object.
3844
3845     @param[in] key  key of the element to access
3846
3847     @return reference to the element at key @a key
3848
3849     @throw std::domain_error if JSON is not an object or null; example:
3850     `"cannot use operator[] with string"`
3851
3852     @complexity Logarithmic in the size of the container.
3853
3854     @liveexample{The example below shows how object elements can be read and
3855     written using the `[]` operator.,operatorarray__key_type}
3856
3857     @sa @ref at(const typename object_t::key_type&) for access by reference
3858     with range checking
3859     @sa @ref value() for access by value with a default value
3860
3861     @since version 1.0.0
3862     */
3863     template<typename T, std::size_t n>
3864     reference operator[](T * (&key)[n])
3865     {
3866         return operator[](static_cast<const T>(key));
3867     }
3868
3869     /*!
3870     @brief read-only access specified object element
3871
3872     Returns a const reference to the element at with specified key @a key. No
3873     bounds checking is performed.
3874
3875     @warning If the element with key @a key does not exist, the behavior is
3876     undefined.
3877
3878     @note This function is required for compatibility reasons with Clang.
3879
3880     @param[in] key  key of the element to access
3881
3882     @return const reference to the element at key @a key
3883
3884     @throw std::domain_error if JSON is not an object; example: `"cannot use
3885     operator[] with null"`
3886
3887     @complexity Logarithmic in the size of the container.
3888
3889     @liveexample{The example below shows how object elements can be read using
3890     the `[]` operator.,operatorarray__key_type_const}
3891
3892     @sa @ref at(const typename object_t::key_type&) for access by reference
3893     with range checking
3894     @sa @ref value() for access by value with a default value
3895
3896     @since version 1.0.0
3897     */
3898     template<typename T, std::size_t n>
3899     const_reference operator[](T * (&key)[n]) const
3900     {
3901         return operator[](static_cast<const T>(key));
3902     }
3903
3904     /*!
3905     @brief access specified object element
3906
3907     Returns a reference to the element at with specified key @a key.
3908
3909     @note If @a key is not found in the object, then it is silently added to
3910     the object and filled with a `null` value to make `key` a valid reference.
3911     In case the value was `null` before, it is converted to an object.
3912
3913     @param[in] key  key of the element to access
3914
3915     @return reference to the element at key @a key
3916
3917     @throw std::domain_error if JSON is not an object or null; example:
3918     `"cannot use operator[] with string"`
3919
3920     @complexity Logarithmic in the size of the container.
3921
3922     @liveexample{The example below shows how object elements can be read and
3923     written using the `[]` operator.,operatorarray__key_type}
3924
3925     @sa @ref at(const typename object_t::key_type&) for access by reference
3926     with range checking
3927     @sa @ref value() for access by value with a default value
3928
3929     @since version 1.1.0
3930     */
3931     template<typename T>
3932     reference operator[](T* key)
3933     {
3934         // implicitly convert null to object
3935         if (is_null())
3936         {
3937             m_type = value_t::object;
3938             m_value = value_t::object;
3939             assert_invariant();
3940         }
3941
3942         // at only works for objects
3943         if (is_object())
3944         {
3945             return m_value.object->operator[](key);
3946         }
3947
3948         JSON_THROW(std::domain_error("cannot use operator[] with " + type_name()));
3949     }
3950
3951     /*!
3952     @brief read-only access specified object element
3953
3954     Returns a const reference to the element at with specified key @a key. No
3955     bounds checking is performed.
3956
3957     @warning If the element with key @a key does not exist, the behavior is
3958     undefined.
3959
3960     @param[in] key  key of the element to access
3961
3962     @return const reference to the element at key @a key
3963
3964     @pre The element with key @a key must exist. **This precondition is
3965          enforced with an assertion.**
3966
3967     @throw std::domain_error if JSON is not an object; example: `"cannot use
3968     operator[] with null"`
3969
3970     @complexity Logarithmic in the size of the container.
3971
3972     @liveexample{The example below shows how object elements can be read using
3973     the `[]` operator.,operatorarray__key_type_const}
3974
3975     @sa @ref at(const typename object_t::key_type&) for access by reference
3976     with range checking
3977     @sa @ref value() for access by value with a default value
3978
3979     @since version 1.1.0
3980     */
3981     template<typename T>
3982     const_reference operator[](T* key) const
3983     {
3984         // at only works for objects
3985         if (is_object())
3986         {
3987             assert(m_value.object->find(key) != m_value.object->end());
3988             return m_value.object->find(key)->second;
3989         }
3990
3991         JSON_THROW(std::domain_error("cannot use operator[] with " + type_name()));
3992     }
3993
3994     /*!
3995     @brief access specified object element with default value
3996
3997     Returns either a copy of an object's element at the specified key @a key
3998     or a given default value if no element with key @a key exists.
3999
4000     The function is basically equivalent to executing
4001     @code {.cpp}
4002     try {
4003         return at(key);
4004     } catch(std::out_of_range) {
4005         return default_value;
4006     }
4007     @endcode
4008
4009     @note Unlike @ref at(const typename object_t::key_type&), this function
4010     does not throw if the given key @a key was not found.
4011
4012     @note Unlike @ref operator[](const typename object_t::key_type& key), this
4013     function does not implicitly add an element to the position defined by @a
4014     key. This function is furthermore also applicable to const objects.
4015
4016     @param[in] key  key of the element to access
4017     @param[in] default_value  the value to return if @a key is not found
4018
4019     @tparam ValueType type compatible to JSON values, for instance `int` for
4020     JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
4021     JSON arrays. Note the type of the expected value at @a key and the default
4022     value @a default_value must be compatible.
4023
4024     @return copy of the element at key @a key or @a default_value if @a key
4025     is not found
4026
4027     @throw std::domain_error if JSON is not an object; example: `"cannot use
4028     value() with null"`
4029
4030     @complexity Logarithmic in the size of the container.
4031
4032     @liveexample{The example below shows how object elements can be queried
4033     with a default value.,basic_json__value}
4034
4035     @sa @ref at(const typename object_t::key_type&) for access by reference
4036     with range checking
4037     @sa @ref operator[](const typename object_t::key_type&) for unchecked
4038     access by reference
4039
4040     @since version 1.0.0
4041     */
4042     template<class ValueType, typename std::enable_if<
4043                  std::is_convertible<basic_json_t, ValueType>::value, int>::type = 0>
4044     ValueType value(const typename object_t::key_type& key, ValueType default_value) const
4045     {
4046         // at only works for objects
4047         if (is_object())
4048         {
4049             // if key is found, return value and given default value otherwise
4050             const auto it = find(key);
4051             if (it != end())
4052             {
4053                 return *it;
4054             }
4055
4056             return default_value;
4057         }
4058         else
4059         {
4060             JSON_THROW(std::domain_error("cannot use value() with " + type_name()));
4061         }
4062     }
4063
4064     /*!
4065     @brief overload for a default value of type const char*
4066     @copydoc basic_json::value(const typename object_t::key_type&, ValueType) const
4067     */
4068     string_t value(const typename object_t::key_type& key, const char* default_value) const
4069     {
4070         return value(key, string_t(default_value));
4071     }
4072
4073     /*!
4074     @brief access specified object element via JSON Pointer with default value
4075
4076     Returns either a copy of an object's element at the specified key @a key
4077     or a given default value if no element with key @a key exists.
4078
4079     The function is basically equivalent to executing
4080     @code {.cpp}
4081     try {
4082         return at(ptr);
4083     } catch(std::out_of_range) {
4084         return default_value;
4085     }
4086     @endcode
4087
4088     @note Unlike @ref at(const json_pointer&), this function does not throw
4089     if the given key @a key was not found.
4090
4091     @param[in] ptr  a JSON pointer to the element to access
4092     @param[in] default_value  the value to return if @a ptr found no value
4093
4094     @tparam ValueType type compatible to JSON values, for instance `int` for
4095     JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
4096     JSON arrays. Note the type of the expected value at @a key and the default
4097     value @a default_value must be compatible.
4098
4099     @return copy of the element at key @a key or @a default_value if @a key
4100     is not found
4101
4102     @throw std::domain_error if JSON is not an object; example: `"cannot use
4103     value() with null"`
4104
4105     @complexity Logarithmic in the size of the container.
4106
4107     @liveexample{The example below shows how object elements can be queried
4108     with a default value.,basic_json__value_ptr}
4109
4110     @sa @ref operator[](const json_pointer&) for unchecked access by reference
4111
4112     @since version 2.0.2
4113     */
4114     template<class ValueType, typename std::enable_if<
4115                  std::is_convertible<basic_json_t, ValueType>::value, int>::type = 0>
4116     ValueType value(const json_pointer& ptr, ValueType default_value) const
4117     {
4118         // at only works for objects
4119         if (is_object())
4120         {
4121             // if pointer resolves a value, return it or use default value
4122             JSON_TRY
4123             {
4124                 return ptr.get_checked(this);
4125             }
4126             JSON_CATCH (std::out_of_range&)
4127             {
4128                 return default_value;
4129             }
4130         }
4131
4132         JSON_THROW(std::domain_error("cannot use value() with " + type_name()));
4133     }
4134
4135     /*!
4136     @brief overload for a default value of type const char*
4137     @copydoc basic_json::value(const json_pointer&, ValueType) const
4138     */
4139     string_t value(const json_pointer& ptr, const char* default_value) const
4140     {
4141         return value(ptr, string_t(default_value));
4142     }
4143
4144     /*!
4145     @brief access the first element
4146
4147     Returns a reference to the first element in the container. For a JSON
4148     container `c`, the expression `c.front()` is equivalent to `*c.begin()`.
4149
4150     @return In case of a structured type (array or object), a reference to the
4151     first element is returned. In case of number, string, or boolean values, a
4152     reference to the value is returned.
4153
4154     @complexity Constant.
4155
4156     @pre The JSON value must not be `null` (would throw `std::out_of_range`)
4157     or an empty array or object (undefined behavior, **guarded by
4158     assertions**).
4159     @post The JSON value remains unchanged.
4160
4161     @throw std::out_of_range when called on `null` value
4162
4163     @liveexample{The following code shows an example for `front()`.,front}
4164
4165     @sa @ref back() -- access the last element
4166
4167     @since version 1.0.0
4168     */
4169     reference front()
4170     {
4171         return *begin();
4172     }
4173
4174     /*!
4175     @copydoc basic_json::front()
4176     */
4177     const_reference front() const
4178     {
4179         return *cbegin();
4180     }
4181
4182     /*!
4183     @brief access the last element
4184
4185     Returns a reference to the last element in the container. For a JSON
4186     container `c`, the expression `c.back()` is equivalent to
4187     @code {.cpp}
4188     auto tmp = c.end();
4189     --tmp;
4190     return *tmp;
4191     @endcode
4192
4193     @return In case of a structured type (array or object), a reference to the
4194     last element is returned. In case of number, string, or boolean values, a
4195     reference to the value is returned.
4196
4197     @complexity Constant.
4198
4199     @pre The JSON value must not be `null` (would throw `std::out_of_range`)
4200     or an empty array or object (undefined behavior, **guarded by
4201     assertions**).
4202     @post The JSON value remains unchanged.
4203
4204     @throw std::out_of_range when called on `null` value.
4205
4206     @liveexample{The following code shows an example for `back()`.,back}
4207
4208     @sa @ref front() -- access the first element
4209
4210     @since version 1.0.0
4211     */
4212     reference back()
4213     {
4214         auto tmp = end();
4215         --tmp;
4216         return *tmp;
4217     }
4218
4219     /*!
4220     @copydoc basic_json::back()
4221     */
4222     const_reference back() const
4223     {
4224         auto tmp = cend();
4225         --tmp;
4226         return *tmp;
4227     }
4228
4229     /*!
4230     @brief remove element given an iterator
4231
4232     Removes the element specified by iterator @a pos. The iterator @a pos must
4233     be valid and dereferenceable. Thus the `end()` iterator (which is valid,
4234     but is not dereferenceable) cannot be used as a value for @a pos.
4235
4236     If called on a primitive type other than `null`, the resulting JSON value
4237     will be `null`.
4238
4239     @param[in] pos iterator to the element to remove
4240     @return Iterator following the last removed element. If the iterator @a
4241     pos refers to the last element, the `end()` iterator is returned.
4242
4243     @tparam IteratorType an @ref iterator or @ref const_iterator
4244
4245     @post Invalidates iterators and references at or after the point of the
4246     erase, including the `end()` iterator.
4247
4248     @throw std::domain_error if called on a `null` value; example: `"cannot
4249     use erase() with null"`
4250     @throw std::domain_error if called on an iterator which does not belong to
4251     the current JSON value; example: `"iterator does not fit current value"`
4252     @throw std::out_of_range if called on a primitive type with invalid
4253     iterator (i.e., any iterator which is not `begin()`); example: `"iterator
4254     out of range"`
4255
4256     @complexity The complexity depends on the type:
4257     - objects: amortized constant
4258     - arrays: linear in distance between @a pos and the end of the container
4259     - strings: linear in the length of the string
4260     - other types: constant
4261
4262     @liveexample{The example shows the result of `erase()` for different JSON
4263     types.,erase__IteratorType}
4264
4265     @sa @ref erase(IteratorType, IteratorType) -- removes the elements in
4266     the given range
4267     @sa @ref erase(const typename object_t::key_type&) -- removes the element
4268     from an object at the given key
4269     @sa @ref erase(const size_type) -- removes the element from an array at
4270     the given index
4271
4272     @since version 1.0.0
4273     */
4274     template<class IteratorType, typename std::enable_if<
4275                  std::is_same<IteratorType, typename basic_json_t::iterator>::value or
4276                  std::is_same<IteratorType, typename basic_json_t::const_iterator>::value, int>::type
4277              = 0>
4278     IteratorType erase(IteratorType pos)
4279     {
4280         // make sure iterator fits the current value
4281         if (this != pos.m_object)
4282         {
4283             JSON_THROW(std::domain_error("iterator does not fit current value"));
4284         }
4285
4286         IteratorType result = end();
4287
4288         switch (m_type)
4289         {
4290             case value_t::boolean:
4291             case value_t::number_float:
4292             case value_t::number_integer:
4293             case value_t::number_unsigned:
4294             case value_t::string:
4295             {
4296                 if (not pos.m_it.primitive_iterator.is_begin())
4297                 {
4298                     JSON_THROW(std::out_of_range("iterator out of range"));
4299                 }
4300
4301                 if (is_string())
4302                 {
4303                     AllocatorType<string_t> alloc;
4304                     alloc.destroy(m_value.string);
4305                     alloc.deallocate(m_value.string, 1);
4306                     m_value.string = nullptr;
4307                 }
4308
4309                 m_type = value_t::null;
4310                 assert_invariant();
4311                 break;
4312             }
4313
4314             case value_t::object:
4315             {
4316                 result.m_it.object_iterator = m_value.object->erase(pos.m_it.object_iterator);
4317                 break;
4318             }
4319
4320             case value_t::array:
4321             {
4322                 result.m_it.array_iterator = m_value.array->erase(pos.m_it.array_iterator);
4323                 break;
4324             }
4325
4326             default:
4327             {
4328                 JSON_THROW(std::domain_error("cannot use erase() with " + type_name()));
4329             }
4330         }
4331
4332         return result;
4333     }
4334
4335     /*!
4336     @brief remove elements given an iterator range
4337
4338     Removes the element specified by the range `[first; last)`. The iterator
4339     @a first does not need to be dereferenceable if `first == last`: erasing
4340     an empty range is a no-op.
4341
4342     If called on a primitive type other than `null`, the resulting JSON value
4343     will be `null`.
4344
4345     @param[in] first iterator to the beginning of the range to remove
4346     @param[in] last iterator past the end of the range to remove
4347     @return Iterator following the last removed element. If the iterator @a
4348     second refers to the last element, the `end()` iterator is returned.
4349
4350     @tparam IteratorType an @ref iterator or @ref const_iterator
4351
4352     @post Invalidates iterators and references at or after the point of the
4353     erase, including the `end()` iterator.
4354
4355     @throw std::domain_error if called on a `null` value; example: `"cannot
4356     use erase() with null"`
4357     @throw std::domain_error if called on iterators which does not belong to
4358     the current JSON value; example: `"iterators do not fit current value"`
4359     @throw std::out_of_range if called on a primitive type with invalid
4360     iterators (i.e., if `first != begin()` and `last != end()`); example:
4361     `"iterators out of range"`
4362
4363     @complexity The complexity depends on the type:
4364     - objects: `log(size()) + std::distance(first, last)`
4365     - arrays: linear in the distance between @a first and @a last, plus linear
4366       in the distance between @a last and end of the container
4367     - strings: linear in the length of the string
4368     - other types: constant
4369
4370     @liveexample{The example shows the result of `erase()` for different JSON
4371     types.,erase__IteratorType_IteratorType}
4372
4373     @sa @ref erase(IteratorType) -- removes the element at a given position
4374     @sa @ref erase(const typename object_t::key_type&) -- removes the element
4375     from an object at the given key
4376     @sa @ref erase(const size_type) -- removes the element from an array at
4377     the given index
4378
4379     @since version 1.0.0
4380     */
4381     template<class IteratorType, typename std::enable_if<
4382                  std::is_same<IteratorType, typename basic_json_t::iterator>::value or
4383                  std::is_same<IteratorType, typename basic_json_t::const_iterator>::value, int>::type
4384              = 0>
4385     IteratorType erase(IteratorType first, IteratorType last)
4386     {
4387         // make sure iterator fits the current value
4388         if (this != first.m_object or this != last.m_object)
4389         {
4390             JSON_THROW(std::domain_error("iterators do not fit current value"));
4391         }
4392
4393         IteratorType result = end();
4394
4395         switch (m_type)
4396         {
4397             case value_t::boolean:
4398             case value_t::number_float:
4399             case value_t::number_integer:
4400             case value_t::number_unsigned:
4401             case value_t::string:
4402             {
4403                 if (not first.m_it.primitive_iterator.is_begin() or not last.m_it.primitive_iterator.is_end())
4404                 {
4405                     JSON_THROW(std::out_of_range("iterators out of range"));
4406                 }
4407
4408                 if (is_string())
4409                 {
4410                     AllocatorType<string_t> alloc;
4411                     alloc.destroy(m_value.string);
4412                     alloc.deallocate(m_value.string, 1);
4413                     m_value.string = nullptr;
4414                 }
4415
4416                 m_type = value_t::null;
4417                 assert_invariant();
4418                 break;
4419             }
4420
4421             case value_t::object:
4422             {
4423                 result.m_it.object_iterator = m_value.object->erase(first.m_it.object_iterator,
4424                                               last.m_it.object_iterator);
4425                 break;
4426             }
4427
4428             case value_t::array:
4429             {
4430                 result.m_it.array_iterator = m_value.array->erase(first.m_it.array_iterator,
4431                                              last.m_it.array_iterator);
4432                 break;
4433             }
4434
4435             default:
4436             {
4437                 JSON_THROW(std::domain_error("cannot use erase() with " + type_name()));
4438             }
4439         }
4440
4441         return result;
4442     }
4443
4444     /*!
4445     @brief remove element from a JSON object given a key
4446
4447     Removes elements from a JSON object with the key value @a key.
4448
4449     @param[in] key value of the elements to remove
4450
4451     @return Number of elements removed. If @a ObjectType is the default
4452     `std::map` type, the return value will always be `0` (@a key was not
4453     found) or `1` (@a key was found).
4454
4455     @post References and iterators to the erased elements are invalidated.
4456     Other references and iterators are not affected.
4457
4458     @throw std::domain_error when called on a type other than JSON object;
4459     example: `"cannot use erase() with null"`
4460
4461     @complexity `log(size()) + count(key)`
4462
4463     @liveexample{The example shows the effect of `erase()`.,erase__key_type}
4464
4465     @sa @ref erase(IteratorType) -- removes the element at a given position
4466     @sa @ref erase(IteratorType, IteratorType) -- removes the elements in
4467     the given range
4468     @sa @ref erase(const size_type) -- removes the element from an array at
4469     the given index
4470
4471     @since version 1.0.0
4472     */
4473     size_type erase(const typename object_t::key_type& key)
4474     {
4475         // this erase only works for objects
4476         if (is_object())
4477         {
4478             return m_value.object->erase(key);
4479         }
4480
4481         JSON_THROW(std::domain_error("cannot use erase() with " + type_name()));
4482     }
4483
4484     /*!
4485     @brief remove element from a JSON array given an index
4486
4487     Removes element from a JSON array at the index @a idx.
4488
4489     @param[in] idx index of the element to remove
4490
4491     @throw std::domain_error when called on a type other than JSON array;
4492     example: `"cannot use erase() with null"`
4493     @throw std::out_of_range when `idx >= size()`; example: `"array index 17
4494     is out of range"`
4495
4496     @complexity Linear in distance between @a idx and the end of the container.
4497
4498     @liveexample{The example shows the effect of `erase()`.,erase__size_type}
4499
4500     @sa @ref erase(IteratorType) -- removes the element at a given position
4501     @sa @ref erase(IteratorType, IteratorType) -- removes the elements in
4502     the given range
4503     @sa @ref erase(const typename object_t::key_type&) -- removes the element
4504     from an object at the given key
4505
4506     @since version 1.0.0
4507     */
4508     void erase(const size_type idx)
4509     {
4510         // this erase only works for arrays
4511         if (is_array())
4512         {
4513             if (idx >= size())
4514             {
4515                 JSON_THROW(std::out_of_range("array index " + std::to_string(idx) + " is out of range"));
4516             }
4517
4518             m_value.array->erase(m_value.array->begin() + static_cast<difference_type>(idx));
4519         }
4520         else
4521         {
4522             JSON_THROW(std::domain_error("cannot use erase() with " + type_name()));
4523         }
4524     }
4525
4526     /// @}
4527
4528
4529     ////////////
4530     // lookup //
4531     ////////////
4532
4533     /// @name lookup
4534     /// @{
4535
4536     /*!
4537     @brief find an element in a JSON object
4538
4539     Finds an element in a JSON object with key equivalent to @a key. If the
4540     element is not found or the JSON value is not an object, end() is
4541     returned.
4542
4543     @note This method always returns @ref end() when executed on a JSON type
4544           that is not an object.
4545
4546     @param[in] key key value of the element to search for
4547
4548     @return Iterator to an element with key equivalent to @a key. If no such
4549     element is found or the JSON value is not an object, past-the-end (see
4550     @ref end()) iterator is returned.
4551
4552     @complexity Logarithmic in the size of the JSON object.
4553
4554     @liveexample{The example shows how `find()` is used.,find__key_type}
4555
4556     @since version 1.0.0
4557     */
4558     iterator find(typename object_t::key_type key)
4559     {
4560         auto result = end();
4561
4562         if (is_object())
4563         {
4564             result.m_it.object_iterator = m_value.object->find(key);
4565         }
4566
4567         return result;
4568     }
4569
4570     /*!
4571     @brief find an element in a JSON object
4572     @copydoc find(typename object_t::key_type)
4573     */
4574     const_iterator find(typename object_t::key_type key) const
4575     {
4576         auto result = cend();
4577
4578         if (is_object())
4579         {
4580             result.m_it.object_iterator = m_value.object->find(key);
4581         }
4582
4583         return result;
4584     }
4585
4586     /*!
4587     @brief returns the number of occurrences of a key in a JSON object
4588
4589     Returns the number of elements with key @a key. If ObjectType is the
4590     default `std::map` type, the return value will always be `0` (@a key was
4591     not found) or `1` (@a key was found).
4592
4593     @note This method always returns `0` when executed on a JSON type that is
4594           not an object.
4595
4596     @param[in] key key value of the element to count
4597
4598     @return Number of elements with key @a key. If the JSON value is not an
4599     object, the return value will be `0`.
4600
4601     @complexity Logarithmic in the size of the JSON object.
4602
4603     @liveexample{The example shows how `count()` is used.,count}
4604
4605     @since version 1.0.0
4606     */
4607     size_type count(typename object_t::key_type key) const
4608     {
4609         // return 0 for all nonobject types
4610         return is_object() ? m_value.object->count(key) : 0;
4611     }
4612
4613     /// @}
4614
4615
4616     ///////////////
4617     // iterators //
4618     ///////////////
4619
4620     /// @name iterators
4621     /// @{
4622
4623     /*!
4624     @brief returns an iterator to the first element
4625
4626     Returns an iterator to the first element.
4627
4628     @image html range-begin-end.svg "Illustration from cppreference.com"
4629
4630     @return iterator to the first element
4631
4632     @complexity Constant.
4633
4634     @requirement This function helps `basic_json` satisfying the
4635     [Container](http://en.cppreference.com/w/cpp/concept/Container)
4636     requirements:
4637     - The complexity is constant.
4638
4639     @liveexample{The following code shows an example for `begin()`.,begin}
4640
4641     @sa @ref cbegin() -- returns a const iterator to the beginning
4642     @sa @ref end() -- returns an iterator to the end
4643     @sa @ref cend() -- returns a const iterator to the end
4644
4645     @since version 1.0.0
4646     */
4647     iterator begin() noexcept
4648     {
4649         iterator result(this);
4650         result.set_begin();
4651         return result;
4652     }
4653
4654     /*!
4655     @copydoc basic_json::cbegin()
4656     */
4657     const_iterator begin() const noexcept
4658     {
4659         return cbegin();
4660     }
4661
4662     /*!
4663     @brief returns a const iterator to the first element
4664
4665     Returns a const iterator to the first element.
4666
4667     @image html range-begin-end.svg "Illustration from cppreference.com"
4668
4669     @return const iterator to the first element
4670
4671     @complexity Constant.
4672
4673     @requirement This function helps `basic_json` satisfying the
4674     [Container](http://en.cppreference.com/w/cpp/concept/Container)
4675     requirements:
4676     - The complexity is constant.
4677     - Has the semantics of `const_cast<const basic_json&>(*this).begin()`.
4678
4679     @liveexample{The following code shows an example for `cbegin()`.,cbegin}
4680
4681     @sa @ref begin() -- returns an iterator to the beginning
4682     @sa @ref end() -- returns an iterator to the end
4683     @sa @ref cend() -- returns a const iterator to the end
4684
4685     @since version 1.0.0
4686     */
4687     const_iterator cbegin() const noexcept
4688     {
4689         const_iterator result(this);
4690         result.set_begin();
4691         return result;
4692     }
4693
4694     /*!
4695     @brief returns an iterator to one past the last element
4696
4697     Returns an iterator to one past the last element.
4698
4699     @image html range-begin-end.svg "Illustration from cppreference.com"
4700
4701     @return iterator one past the last element
4702
4703     @complexity Constant.
4704
4705     @requirement This function helps `basic_json` satisfying the
4706     [Container](http://en.cppreference.com/w/cpp/concept/Container)
4707     requirements:
4708     - The complexity is constant.
4709
4710     @liveexample{The following code shows an example for `end()`.,end}
4711
4712     @sa @ref cend() -- returns a const iterator to the end
4713     @sa @ref begin() -- returns an iterator to the beginning
4714     @sa @ref cbegin() -- returns a const iterator to the beginning
4715
4716     @since version 1.0.0
4717     */
4718     iterator end() noexcept
4719     {
4720         iterator result(this);
4721         result.set_end();
4722         return result;
4723     }
4724
4725     /*!
4726     @copydoc basic_json::cend()
4727     */
4728     const_iterator end() const noexcept
4729     {
4730         return cend();
4731     }
4732
4733     /*!
4734     @brief returns a const iterator to one past the last element
4735
4736     Returns a const iterator to one past the last element.
4737
4738     @image html range-begin-end.svg "Illustration from cppreference.com"
4739
4740     @return const iterator one past the last element
4741
4742     @complexity Constant.
4743
4744     @requirement This function helps `basic_json` satisfying the
4745     [Container](http://en.cppreference.com/w/cpp/concept/Container)
4746     requirements:
4747     - The complexity is constant.
4748     - Has the semantics of `const_cast<const basic_json&>(*this).end()`.
4749
4750     @liveexample{The following code shows an example for `cend()`.,cend}
4751
4752     @sa @ref end() -- returns an iterator to the end
4753     @sa @ref begin() -- returns an iterator to the beginning
4754     @sa @ref cbegin() -- returns a const iterator to the beginning
4755
4756     @since version 1.0.0
4757     */
4758     const_iterator cend() const noexcept
4759     {
4760         const_iterator result(this);
4761         result.set_end();
4762         return result;
4763     }
4764
4765     /*!
4766     @brief returns an iterator to the reverse-beginning
4767
4768     Returns an iterator to the reverse-beginning; that is, the last element.
4769
4770     @image html range-rbegin-rend.svg "Illustration from cppreference.com"
4771
4772     @complexity Constant.
4773
4774     @requirement This function helps `basic_json` satisfying the
4775     [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
4776     requirements:
4777     - The complexity is constant.
4778     - Has the semantics of `reverse_iterator(end())`.
4779
4780     @liveexample{The following code shows an example for `rbegin()`.,rbegin}
4781
4782     @sa @ref crbegin() -- returns a const reverse iterator to the beginning
4783     @sa @ref rend() -- returns a reverse iterator to the end
4784     @sa @ref crend() -- returns a const reverse iterator to the end
4785
4786     @since version 1.0.0
4787     */
4788     reverse_iterator rbegin() noexcept
4789     {
4790         return reverse_iterator(end());
4791     }
4792
4793     /*!
4794     @copydoc basic_json::crbegin()
4795     */
4796     const_reverse_iterator rbegin() const noexcept
4797     {
4798         return crbegin();
4799     }
4800
4801     /*!
4802     @brief returns an iterator to the reverse-end
4803
4804     Returns an iterator to the reverse-end; that is, one before the first
4805     element.
4806
4807     @image html range-rbegin-rend.svg "Illustration from cppreference.com"
4808
4809     @complexity Constant.
4810
4811     @requirement This function helps `basic_json` satisfying the
4812     [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
4813     requirements:
4814     - The complexity is constant.
4815     - Has the semantics of `reverse_iterator(begin())`.
4816
4817     @liveexample{The following code shows an example for `rend()`.,rend}
4818
4819     @sa @ref crend() -- returns a const reverse iterator to the end
4820     @sa @ref rbegin() -- returns a reverse iterator to the beginning
4821     @sa @ref crbegin() -- returns a const reverse iterator to the beginning
4822
4823     @since version 1.0.0
4824     */
4825     reverse_iterator rend() noexcept
4826     {
4827         return reverse_iterator(begin());
4828     }
4829
4830     /*!
4831     @copydoc basic_json::crend()
4832     */
4833     const_reverse_iterator rend() const noexcept
4834     {
4835         return crend();
4836     }
4837
4838     /*!
4839     @brief returns a const reverse iterator to the last element
4840
4841     Returns a const iterator to the reverse-beginning; that is, the last
4842     element.
4843
4844     @image html range-rbegin-rend.svg "Illustration from cppreference.com"
4845
4846     @complexity Constant.
4847
4848     @requirement This function helps `basic_json` satisfying the
4849     [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
4850     requirements:
4851     - The complexity is constant.
4852     - Has the semantics of `const_cast<const basic_json&>(*this).rbegin()`.
4853
4854     @liveexample{The following code shows an example for `crbegin()`.,crbegin}
4855
4856     @sa @ref rbegin() -- returns a reverse iterator to the beginning
4857     @sa @ref rend() -- returns a reverse iterator to the end
4858     @sa @ref crend() -- returns a const reverse iterator to the end
4859
4860     @since version 1.0.0
4861     */
4862     const_reverse_iterator crbegin() const noexcept
4863     {
4864         return const_reverse_iterator(cend());
4865     }
4866
4867     /*!
4868     @brief returns a const reverse iterator to one before the first
4869
4870     Returns a const reverse iterator to the reverse-end; that is, one before
4871     the first element.
4872
4873     @image html range-rbegin-rend.svg "Illustration from cppreference.com"
4874
4875     @complexity Constant.
4876
4877     @requirement This function helps `basic_json` satisfying the
4878     [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
4879     requirements:
4880     - The complexity is constant.
4881     - Has the semantics of `const_cast<const basic_json&>(*this).rend()`.
4882
4883     @liveexample{The following code shows an example for `crend()`.,crend}
4884
4885     @sa @ref rend() -- returns a reverse iterator to the end
4886     @sa @ref rbegin() -- returns a reverse iterator to the beginning
4887     @sa @ref crbegin() -- returns a const reverse iterator to the beginning
4888
4889     @since version 1.0.0
4890     */
4891     const_reverse_iterator crend() const noexcept
4892     {
4893         return const_reverse_iterator(cbegin());
4894     }
4895
4896   private:
4897     // forward declaration
4898     template<typename IteratorType> class iteration_proxy;
4899
4900   public:
4901     /*!
4902     @brief wrapper to access iterator member functions in range-based for
4903
4904     This function allows to access @ref iterator::key() and @ref
4905     iterator::value() during range-based for loops. In these loops, a
4906     reference to the JSON values is returned, so there is no access to the
4907     underlying iterator.
4908
4909     @note The name of this function is not yet final and may change in the
4910     future.
4911     */
4912     static iteration_proxy<iterator> iterator_wrapper(reference cont)
4913     {
4914         return iteration_proxy<iterator>(cont);
4915     }
4916
4917     /*!
4918     @copydoc iterator_wrapper(reference)
4919     */
4920     static iteration_proxy<const_iterator> iterator_wrapper(const_reference cont)
4921     {
4922         return iteration_proxy<const_iterator>(cont);
4923     }
4924
4925     /// @}
4926
4927
4928     //////////////
4929     // capacity //
4930     //////////////
4931
4932     /// @name capacity
4933     /// @{
4934
4935     /*!
4936     @brief checks whether the container is empty
4937
4938     Checks if a JSON value has no elements.
4939
4940     @return The return value depends on the different types and is
4941             defined as follows:
4942             Value type  | return value
4943             ----------- | -------------
4944             null        | `true`
4945             boolean     | `false`
4946             string      | `false`
4947             number      | `false`
4948             object      | result of function `object_t::empty()`
4949             array       | result of function `array_t::empty()`
4950
4951     @note This function does not return whether a string stored as JSON value
4952     is empty - it returns whether the JSON container itself is empty which is
4953     false in the case of a string.
4954
4955     @complexity Constant, as long as @ref array_t and @ref object_t satisfy
4956     the Container concept; that is, their `empty()` functions have constant
4957     complexity.
4958
4959     @requirement This function helps `basic_json` satisfying the
4960     [Container](http://en.cppreference.com/w/cpp/concept/Container)
4961     requirements:
4962     - The complexity is constant.
4963     - Has the semantics of `begin() == end()`.
4964
4965     @liveexample{The following code uses `empty()` to check if a JSON
4966     object contains any elements.,empty}
4967
4968     @sa @ref size() -- returns the number of elements
4969
4970     @since version 1.0.0
4971     */
4972     bool empty() const noexcept
4973     {
4974         switch (m_type)
4975         {
4976             case value_t::null:
4977             {
4978                 // null values are empty
4979                 return true;
4980             }
4981
4982             case value_t::array:
4983             {
4984                 // delegate call to array_t::empty()
4985                 return m_value.array->empty();
4986             }
4987
4988             case value_t::object:
4989             {
4990                 // delegate call to object_t::empty()
4991                 return m_value.object->empty();
4992             }
4993
4994             default:
4995             {
4996                 // all other types are nonempty
4997                 return false;
4998             }
4999         }
5000     }
5001
5002     /*!
5003     @brief returns the number of elements
5004
5005     Returns the number of elements in a JSON value.
5006
5007     @return The return value depends on the different types and is
5008             defined as follows:
5009             Value type  | return value
5010             ----------- | -------------
5011             null        | `0`
5012             boolean     | `1`
5013             string      | `1`
5014             number      | `1`
5015             object      | result of function object_t::size()
5016             array       | result of function array_t::size()
5017
5018     @note This function does not return the length of a string stored as JSON
5019     value - it returns the number of elements in the JSON value which is 1 in
5020     the case of a string.
5021
5022     @complexity Constant, as long as @ref array_t and @ref object_t satisfy
5023     the Container concept; that is, their size() functions have constant
5024     complexity.
5025
5026     @requirement This function helps `basic_json` satisfying the
5027     [Container](http://en.cppreference.com/w/cpp/concept/Container)
5028     requirements:
5029     - The complexity is constant.
5030     - Has the semantics of `std::distance(begin(), end())`.
5031
5032     @liveexample{The following code calls `size()` on the different value
5033     types.,size}
5034
5035     @sa @ref empty() -- checks whether the container is empty
5036     @sa @ref max_size() -- returns the maximal number of elements
5037
5038     @since version 1.0.0
5039     */
5040     size_type size() const noexcept
5041     {
5042         switch (m_type)
5043         {
5044             case value_t::null:
5045             {
5046                 // null values are empty
5047                 return 0;
5048             }
5049
5050             case value_t::array:
5051             {
5052                 // delegate call to array_t::size()
5053                 return m_value.array->size();
5054             }
5055
5056             case value_t::object:
5057             {
5058                 // delegate call to object_t::size()
5059                 return m_value.object->size();
5060             }
5061
5062             default:
5063             {
5064                 // all other types have size 1
5065                 return 1;
5066             }
5067         }
5068     }
5069
5070     /*!
5071     @brief returns the maximum possible number of elements
5072
5073     Returns the maximum number of elements a JSON value is able to hold due to
5074     system or library implementation limitations, i.e. `std::distance(begin(),
5075     end())` for the JSON value.
5076
5077     @return The return value depends on the different types and is
5078             defined as follows:
5079             Value type  | return value
5080             ----------- | -------------
5081             null        | `0` (same as `size()`)
5082             boolean     | `1` (same as `size()`)
5083             string      | `1` (same as `size()`)
5084             number      | `1` (same as `size()`)
5085             object      | result of function `object_t::max_size()`
5086             array       | result of function `array_t::max_size()`
5087
5088     @complexity Constant, as long as @ref array_t and @ref object_t satisfy
5089     the Container concept; that is, their `max_size()` functions have constant
5090     complexity.
5091
5092     @requirement This function helps `basic_json` satisfying the
5093     [Container](http://en.cppreference.com/w/cpp/concept/Container)
5094     requirements:
5095     - The complexity is constant.
5096     - Has the semantics of returning `b.size()` where `b` is the largest
5097       possible JSON value.
5098
5099     @liveexample{The following code calls `max_size()` on the different value
5100     types. Note the output is implementation specific.,max_size}
5101
5102     @sa @ref size() -- returns the number of elements
5103
5104     @since version 1.0.0
5105     */
5106     size_type max_size() const noexcept
5107     {
5108         switch (m_type)
5109         {
5110             case value_t::array:
5111             {
5112                 // delegate call to array_t::max_size()
5113                 return m_value.array->max_size();
5114             }
5115
5116             case value_t::object:
5117             {
5118                 // delegate call to object_t::max_size()
5119                 return m_value.object->max_size();
5120             }
5121
5122             default:
5123             {
5124                 // all other types have max_size() == size()
5125                 return size();
5126             }
5127         }
5128     }
5129
5130     /// @}
5131
5132
5133     ///////////////
5134     // modifiers //
5135     ///////////////
5136
5137     /// @name modifiers
5138     /// @{
5139
5140     /*!
5141     @brief clears the contents
5142
5143     Clears the content of a JSON value and resets it to the default value as
5144     if @ref basic_json(value_t) would have been called:
5145
5146     Value type  | initial value
5147     ----------- | -------------
5148     null        | `null`
5149     boolean     | `false`
5150     string      | `""`
5151     number      | `0`
5152     object      | `{}`
5153     array       | `[]`
5154
5155     @complexity Linear in the size of the JSON value.
5156
5157     @liveexample{The example below shows the effect of `clear()` to different
5158     JSON types.,clear}
5159
5160     @since version 1.0.0
5161     */
5162     void clear() noexcept
5163     {
5164         switch (m_type)
5165         {
5166             case value_t::number_integer:
5167             {
5168                 m_value.number_integer = 0;
5169                 break;
5170             }
5171
5172             case value_t::number_unsigned:
5173             {
5174                 m_value.number_unsigned = 0;
5175                 break;
5176             }
5177
5178             case value_t::number_float:
5179             {
5180                 m_value.number_float = 0.0;
5181                 break;
5182             }
5183
5184             case value_t::boolean:
5185             {
5186                 m_value.boolean = false;
5187                 break;
5188             }
5189
5190             case value_t::string:
5191             {
5192                 m_value.string->clear();
5193                 break;
5194             }
5195
5196             case value_t::array:
5197             {
5198                 m_value.array->clear();
5199                 break;
5200             }
5201
5202             case value_t::object:
5203             {
5204                 m_value.object->clear();
5205                 break;
5206             }
5207
5208             default:
5209             {
5210                 break;
5211             }
5212         }
5213     }
5214
5215     /*!
5216     @brief add an object to an array
5217
5218     Appends the given element @a val to the end of the JSON value. If the
5219     function is called on a JSON null value, an empty array is created before
5220     appending @a val.
5221
5222     @param[in] val the value to add to the JSON array
5223
5224     @throw std::domain_error when called on a type other than JSON array or
5225     null; example: `"cannot use push_back() with number"`
5226
5227     @complexity Amortized constant.
5228
5229     @liveexample{The example shows how `push_back()` and `+=` can be used to
5230     add elements to a JSON array. Note how the `null` value was silently
5231     converted to a JSON array.,push_back}
5232
5233     @since version 1.0.0
5234     */
5235     void push_back(basic_json&& val)
5236     {
5237         // push_back only works for null objects or arrays
5238         if (not(is_null() or is_array()))
5239         {
5240             JSON_THROW(std::domain_error("cannot use push_back() with " + type_name()));
5241         }
5242
5243         // transform null object into an array
5244         if (is_null())
5245         {
5246             m_type = value_t::array;
5247             m_value = value_t::array;
5248             assert_invariant();
5249         }
5250
5251         // add element to array (move semantics)
5252         m_value.array->push_back(std::move(val));
5253         // invalidate object
5254         val.m_type = value_t::null;
5255     }
5256
5257     /*!
5258     @brief add an object to an array
5259     @copydoc push_back(basic_json&&)
5260     */
5261     reference operator+=(basic_json&& val)
5262     {
5263         push_back(std::move(val));
5264         return *this;
5265     }
5266
5267     /*!
5268     @brief add an object to an array
5269     @copydoc push_back(basic_json&&)
5270     */
5271     void push_back(const basic_json& val)
5272     {
5273         // push_back only works for null objects or arrays
5274         if (not(is_null() or is_array()))
5275         {
5276             JSON_THROW(std::domain_error("cannot use push_back() with " + type_name()));
5277         }
5278
5279         // transform null object into an array
5280         if (is_null())
5281         {
5282             m_type = value_t::array;
5283             m_value = value_t::array;
5284             assert_invariant();
5285         }
5286
5287         // add element to array
5288         m_value.array->push_back(val);
5289     }
5290
5291     /*!
5292     @brief add an object to an array
5293     @copydoc push_back(basic_json&&)
5294     */
5295     reference operator+=(const basic_json& val)
5296     {
5297         push_back(val);
5298         return *this;
5299     }
5300
5301     /*!
5302     @brief add an object to an object
5303
5304     Inserts the given element @a val to the JSON object. If the function is
5305     called on a JSON null value, an empty object is created before inserting
5306     @a val.
5307
5308     @param[in] val the value to add to the JSON object
5309
5310     @throw std::domain_error when called on a type other than JSON object or
5311     null; example: `"cannot use push_back() with number"`
5312
5313     @complexity Logarithmic in the size of the container, O(log(`size()`)).
5314
5315     @liveexample{The example shows how `push_back()` and `+=` can be used to
5316     add elements to a JSON object. Note how the `null` value was silently
5317     converted to a JSON object.,push_back__object_t__value}
5318
5319     @since version 1.0.0
5320     */
5321     void push_back(const typename object_t::value_type& val)
5322     {
5323         // push_back only works for null objects or objects
5324         if (not(is_null() or is_object()))
5325         {
5326             JSON_THROW(std::domain_error("cannot use push_back() with " + type_name()));
5327         }
5328
5329         // transform null object into an object
5330         if (is_null())
5331         {
5332             m_type = value_t::object;
5333             m_value = value_t::object;
5334             assert_invariant();
5335         }
5336
5337         // add element to array
5338         m_value.object->insert(val);
5339     }
5340
5341     /*!
5342     @brief add an object to an object
5343     @copydoc push_back(const typename object_t::value_type&)
5344     */
5345     reference operator+=(const typename object_t::value_type& val)
5346     {
5347         push_back(val);
5348         return *this;
5349     }
5350
5351     /*!
5352     @brief add an object to an object
5353
5354     This function allows to use `push_back` with an initializer list. In case
5355
5356     1. the current value is an object,
5357     2. the initializer list @a init contains only two elements, and
5358     3. the first element of @a init is a string,
5359
5360     @a init is converted into an object element and added using
5361     @ref push_back(const typename object_t::value_type&). Otherwise, @a init
5362     is converted to a JSON value and added using @ref push_back(basic_json&&).
5363
5364     @param init  an initializer list
5365
5366     @complexity Linear in the size of the initializer list @a init.
5367
5368     @note This function is required to resolve an ambiguous overload error,
5369           because pairs like `{"key", "value"}` can be both interpreted as
5370           `object_t::value_type` or `std::initializer_list<basic_json>`, see
5371           https://github.com/nlohmann/json/issues/235 for more information.
5372
5373     @liveexample{The example shows how initializer lists are treated as
5374     objects when possible.,push_back__initializer_list}
5375     */
5376     void push_back(std::initializer_list<basic_json> init)
5377     {
5378         if (is_object() and init.size() == 2 and init.begin()->is_string())
5379         {
5380             const string_t key = *init.begin();
5381             push_back(typename object_t::value_type(key, *(init.begin() + 1)));
5382         }
5383         else
5384         {
5385             push_back(basic_json(init));
5386         }
5387     }
5388
5389     /*!
5390     @brief add an object to an object
5391     @copydoc push_back(std::initializer_list<basic_json>)
5392     */
5393     reference operator+=(std::initializer_list<basic_json> init)
5394     {
5395         push_back(init);
5396         return *this;
5397     }
5398
5399     /*!
5400     @brief add an object to an array
5401
5402     Creates a JSON value from the passed parameters @a args to the end of the
5403     JSON value. If the function is called on a JSON null value, an empty array
5404     is created before appending the value created from @a args.
5405
5406     @param[in] args arguments to forward to a constructor of @ref basic_json
5407     @tparam Args compatible types to create a @ref basic_json object
5408
5409     @throw std::domain_error when called on a type other than JSON array or
5410     null; example: `"cannot use emplace_back() with number"`
5411
5412     @complexity Amortized constant.
5413
5414     @liveexample{The example shows how `push_back()` can be used to add
5415     elements to a JSON array. Note how the `null` value was silently converted
5416     to a JSON array.,emplace_back}
5417
5418     @since version 2.0.8
5419     */
5420     template<class... Args>
5421     void emplace_back(Args&& ... args)
5422     {
5423         // emplace_back only works for null objects or arrays
5424         if (not(is_null() or is_array()))
5425         {
5426             JSON_THROW(std::domain_error("cannot use emplace_back() with " + type_name()));
5427         }
5428
5429         // transform null object into an array
5430         if (is_null())
5431         {
5432             m_type = value_t::array;
5433             m_value = value_t::array;
5434             assert_invariant();
5435         }
5436
5437         // add element to array (perfect forwarding)
5438         m_value.array->emplace_back(std::forward<Args>(args)...);
5439     }
5440
5441     /*!
5442     @brief add an object to an object if key does not exist
5443
5444     Inserts a new element into a JSON object constructed in-place with the
5445     given @a args if there is no element with the key in the container. If the
5446     function is called on a JSON null value, an empty object is created before
5447     appending the value created from @a args.
5448
5449     @param[in] args arguments to forward to a constructor of @ref basic_json
5450     @tparam Args compatible types to create a @ref basic_json object
5451
5452     @return a pair consisting of an iterator to the inserted element, or the
5453             already-existing element if no insertion happened, and a bool
5454             denoting whether the insertion took place.
5455
5456     @throw std::domain_error when called on a type other than JSON object or
5457     null; example: `"cannot use emplace() with number"`
5458
5459     @complexity Logarithmic in the size of the container, O(log(`size()`)).
5460
5461     @liveexample{The example shows how `emplace()` can be used to add elements
5462     to a JSON object. Note how the `null` value was silently converted to a
5463     JSON object. Further note how no value is added if there was already one
5464     value stored with the same key.,emplace}
5465
5466     @since version 2.0.8
5467     */
5468     template<class... Args>
5469     std::pair<iterator, bool> emplace(Args&& ... args)
5470     {
5471         // emplace only works for null objects or arrays
5472         if (not(is_null() or is_object()))
5473         {
5474             JSON_THROW(std::domain_error("cannot use emplace() with " + type_name()));
5475         }
5476
5477         // transform null object into an object
5478         if (is_null())
5479         {
5480             m_type = value_t::object;
5481             m_value = value_t::object;
5482             assert_invariant();
5483         }
5484
5485         // add element to array (perfect forwarding)
5486         auto res = m_value.object->emplace(std::forward<Args>(args)...);
5487         // create result iterator and set iterator to the result of emplace
5488         auto it = begin();
5489         it.m_it.object_iterator = res.first;
5490
5491         // return pair of iterator and boolean
5492         return {it, res.second};
5493     }
5494
5495     /*!
5496     @brief inserts element
5497
5498     Inserts element @a val before iterator @a pos.
5499
5500     @param[in] pos iterator before which the content will be inserted; may be
5501     the end() iterator
5502     @param[in] val element to insert
5503     @return iterator pointing to the inserted @a val.
5504
5505     @throw std::domain_error if called on JSON values other than arrays;
5506     example: `"cannot use insert() with string"`
5507     @throw std::domain_error if @a pos is not an iterator of *this; example:
5508     `"iterator does not fit current value"`
5509
5510     @complexity Constant plus linear in the distance between @a pos and end of
5511     the container.
5512
5513     @liveexample{The example shows how `insert()` is used.,insert}
5514
5515     @since version 1.0.0
5516     */
5517     iterator insert(const_iterator pos, const basic_json& val)
5518     {
5519         // insert only works for arrays
5520         if (is_array())
5521         {
5522             // check if iterator pos fits to this JSON value
5523             if (pos.m_object != this)
5524             {
5525                 JSON_THROW(std::domain_error("iterator does not fit current value"));
5526             }
5527
5528             // insert to array and return iterator
5529             iterator result(this);
5530             result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, val);
5531             return result;
5532         }
5533
5534         JSON_THROW(std::domain_error("cannot use insert() with " + type_name()));
5535     }
5536
5537     /*!
5538     @brief inserts element
5539     @copydoc insert(const_iterator, const basic_json&)
5540     */
5541     iterator insert(const_iterator pos, basic_json&& val)
5542     {
5543         return insert(pos, val);
5544     }
5545
5546     /*!
5547     @brief inserts elements
5548
5549     Inserts @a cnt copies of @a val before iterator @a pos.
5550
5551     @param[in] pos iterator before which the content will be inserted; may be
5552     the end() iterator
5553     @param[in] cnt number of copies of @a val to insert
5554     @param[in] val element to insert
5555     @return iterator pointing to the first element inserted, or @a pos if
5556     `cnt==0`
5557
5558     @throw std::domain_error if called on JSON values other than arrays;
5559     example: `"cannot use insert() with string"`
5560     @throw std::domain_error if @a pos is not an iterator of *this; example:
5561     `"iterator does not fit current value"`
5562
5563     @complexity Linear in @a cnt plus linear in the distance between @a pos
5564     and end of the container.
5565
5566     @liveexample{The example shows how `insert()` is used.,insert__count}
5567
5568     @since version 1.0.0
5569     */
5570     iterator insert(const_iterator pos, size_type cnt, const basic_json& val)
5571     {
5572         // insert only works for arrays
5573         if (is_array())
5574         {
5575             // check if iterator pos fits to this JSON value
5576             if (pos.m_object != this)
5577             {
5578                 JSON_THROW(std::domain_error("iterator does not fit current value"));
5579             }
5580
5581             // insert to array and return iterator
5582             iterator result(this);
5583             result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, cnt, val);
5584             return result;
5585         }
5586
5587         JSON_THROW(std::domain_error("cannot use insert() with " + type_name()));
5588     }
5589
5590     /*!
5591     @brief inserts elements
5592
5593     Inserts elements from range `[first, last)` before iterator @a pos.
5594
5595     @param[in] pos iterator before which the content will be inserted; may be
5596     the end() iterator
5597     @param[in] first begin of the range of elements to insert
5598     @param[in] last end of the range of elements to insert
5599
5600     @throw std::domain_error if called on JSON values other than arrays;
5601     example: `"cannot use insert() with string"`
5602     @throw std::domain_error if @a pos is not an iterator of *this; example:
5603     `"iterator does not fit current value"`
5604     @throw std::domain_error if @a first and @a last do not belong to the same
5605     JSON value; example: `"iterators do not fit"`
5606     @throw std::domain_error if @a first or @a last are iterators into
5607     container for which insert is called; example: `"passed iterators may not
5608     belong to container"`
5609
5610     @return iterator pointing to the first element inserted, or @a pos if
5611     `first==last`
5612
5613     @complexity Linear in `std::distance(first, last)` plus linear in the
5614     distance between @a pos and end of the container.
5615
5616     @liveexample{The example shows how `insert()` is used.,insert__range}
5617
5618     @since version 1.0.0
5619     */
5620     iterator insert(const_iterator pos, const_iterator first, const_iterator last)
5621     {
5622         // insert only works for arrays
5623         if (not is_array())
5624         {
5625             JSON_THROW(std::domain_error("cannot use insert() with " + type_name()));
5626         }
5627
5628         // check if iterator pos fits to this JSON value
5629         if (pos.m_object != this)
5630         {
5631             JSON_THROW(std::domain_error("iterator does not fit current value"));
5632         }
5633
5634         // check if range iterators belong to the same JSON object
5635         if (first.m_object != last.m_object)
5636         {
5637             JSON_THROW(std::domain_error("iterators do not fit"));
5638         }
5639
5640         if (first.m_object == this or last.m_object == this)
5641         {
5642             JSON_THROW(std::domain_error("passed iterators may not belong to container"));
5643         }
5644
5645         // insert to array and return iterator
5646         iterator result(this);
5647         result.m_it.array_iterator = m_value.array->insert(
5648                                          pos.m_it.array_iterator,
5649                                          first.m_it.array_iterator,
5650                                          last.m_it.array_iterator);
5651         return result;
5652     }
5653
5654     /*!
5655     @brief inserts elements
5656
5657     Inserts elements from initializer list @a ilist before iterator @a pos.
5658
5659     @param[in] pos iterator before which the content will be inserted; may be
5660     the end() iterator
5661     @param[in] ilist initializer list to insert the values from
5662
5663     @throw std::domain_error if called on JSON values other than arrays;
5664     example: `"cannot use insert() with string"`
5665     @throw std::domain_error if @a pos is not an iterator of *this; example:
5666     `"iterator does not fit current value"`
5667
5668     @return iterator pointing to the first element inserted, or @a pos if
5669     `ilist` is empty
5670
5671     @complexity Linear in `ilist.size()` plus linear in the distance between
5672     @a pos and end of the container.
5673
5674     @liveexample{The example shows how `insert()` is used.,insert__ilist}
5675
5676     @since version 1.0.0
5677     */
5678     iterator insert(const_iterator pos, std::initializer_list<basic_json> ilist)
5679     {
5680         // insert only works for arrays
5681         if (not is_array())
5682         {
5683             JSON_THROW(std::domain_error("cannot use insert() with " + type_name()));
5684         }
5685
5686         // check if iterator pos fits to this JSON value
5687         if (pos.m_object != this)
5688         {
5689             JSON_THROW(std::domain_error("iterator does not fit current value"));
5690         }
5691
5692         // insert to array and return iterator
5693         iterator result(this);
5694         result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, ilist);
5695         return result;
5696     }
5697
5698     /*!
5699     @brief exchanges the values
5700
5701     Exchanges the contents of the JSON value with those of @a other. Does not
5702     invoke any move, copy, or swap operations on individual elements. All
5703     iterators and references remain valid. The past-the-end iterator is
5704     invalidated.
5705
5706     @param[in,out] other JSON value to exchange the contents with
5707
5708     @complexity Constant.
5709
5710     @liveexample{The example below shows how JSON values can be swapped with
5711     `swap()`.,swap__reference}
5712
5713     @since version 1.0.0
5714     */
5715     void swap(reference other) noexcept (
5716         std::is_nothrow_move_constructible<value_t>::value and
5717         std::is_nothrow_move_assignable<value_t>::value and
5718         std::is_nothrow_move_constructible<json_value>::value and
5719         std::is_nothrow_move_assignable<json_value>::value
5720     )
5721     {
5722         std::swap(m_type, other.m_type);
5723         std::swap(m_value, other.m_value);
5724         assert_invariant();
5725     }
5726
5727     /*!
5728     @brief exchanges the values
5729
5730     Exchanges the contents of a JSON array with those of @a other. Does not
5731     invoke any move, copy, or swap operations on individual elements. All
5732     iterators and references remain valid. The past-the-end iterator is
5733     invalidated.
5734
5735     @param[in,out] other array to exchange the contents with
5736
5737     @throw std::domain_error when JSON value is not an array; example:
5738     `"cannot use swap() with string"`
5739
5740     @complexity Constant.
5741
5742     @liveexample{The example below shows how arrays can be swapped with
5743     `swap()`.,swap__array_t}
5744
5745     @since version 1.0.0
5746     */
5747     void swap(array_t& other)
5748     {
5749         // swap only works for arrays
5750         if (is_array())
5751         {
5752             std::swap(*(m_value.array), other);
5753         }
5754         else
5755         {
5756             JSON_THROW(std::domain_error("cannot use swap() with " + type_name()));
5757         }
5758     }
5759
5760     /*!
5761     @brief exchanges the values
5762
5763     Exchanges the contents of a JSON object with those of @a other. Does not
5764     invoke any move, copy, or swap operations on individual elements. All
5765     iterators and references remain valid. The past-the-end iterator is
5766     invalidated.
5767
5768     @param[in,out] other object to exchange the contents with
5769
5770     @throw std::domain_error when JSON value is not an object; example:
5771     `"cannot use swap() with string"`
5772
5773     @complexity Constant.
5774
5775     @liveexample{The example below shows how objects can be swapped with
5776     `swap()`.,swap__object_t}
5777
5778     @since version 1.0.0
5779     */
5780     void swap(object_t& other)
5781     {
5782         // swap only works for objects
5783         if (is_object())
5784         {
5785             std::swap(*(m_value.object), other);
5786         }
5787         else
5788         {
5789             JSON_THROW(std::domain_error("cannot use swap() with " + type_name()));
5790         }
5791     }
5792
5793     /*!
5794     @brief exchanges the values
5795
5796     Exchanges the contents of a JSON string with those of @a other. Does not
5797     invoke any move, copy, or swap operations on individual elements. All
5798     iterators and references remain valid. The past-the-end iterator is
5799     invalidated.
5800
5801     @param[in,out] other string to exchange the contents with
5802
5803     @throw std::domain_error when JSON value is not a string; example: `"cannot
5804     use swap() with boolean"`
5805
5806     @complexity Constant.
5807
5808     @liveexample{The example below shows how strings can be swapped with
5809     `swap()`.,swap__string_t}
5810
5811     @since version 1.0.0
5812     */
5813     void swap(string_t& other)
5814     {
5815         // swap only works for strings
5816         if (is_string())
5817         {
5818             std::swap(*(m_value.string), other);
5819         }
5820         else
5821         {
5822             JSON_THROW(std::domain_error("cannot use swap() with " + type_name()));
5823         }
5824     }
5825
5826     /// @}
5827
5828   public:
5829     //////////////////////////////////////////
5830     // lexicographical comparison operators //
5831     //////////////////////////////////////////
5832
5833     /// @name lexicographical comparison operators
5834     /// @{
5835
5836     /*!
5837     @brief comparison: equal
5838
5839     Compares two JSON values for equality according to the following rules:
5840     - Two JSON values are equal if (1) they are from the same type and (2)
5841       their stored values are the same.
5842     - Integer and floating-point numbers are automatically converted before
5843       comparison. Floating-point numbers are compared indirectly: two
5844       floating-point numbers `f1` and `f2` are considered equal if neither
5845       `f1 > f2` nor `f2 > f1` holds.
5846     - Two JSON null values are equal.
5847
5848     @param[in] lhs  first JSON value to consider
5849     @param[in] rhs  second JSON value to consider
5850     @return whether the values @a lhs and @a rhs are equal
5851
5852     @complexity Linear.
5853
5854     @liveexample{The example demonstrates comparing several JSON
5855     types.,operator__equal}
5856
5857     @since version 1.0.0
5858     */
5859     friend bool operator==(const_reference lhs, const_reference rhs) noexcept
5860     {
5861         const auto lhs_type = lhs.type();
5862         const auto rhs_type = rhs.type();
5863
5864         if (lhs_type == rhs_type)
5865         {
5866             switch (lhs_type)
5867             {
5868                 case value_t::array:
5869                 {
5870                     return *lhs.m_value.array == *rhs.m_value.array;
5871                 }
5872                 case value_t::object:
5873                 {
5874                     return *lhs.m_value.object == *rhs.m_value.object;
5875                 }
5876                 case value_t::null:
5877                 {
5878                     return true;
5879                 }
5880                 case value_t::string:
5881                 {
5882                     return *lhs.m_value.string == *rhs.m_value.string;
5883                 }
5884                 case value_t::boolean:
5885                 {
5886                     return lhs.m_value.boolean == rhs.m_value.boolean;
5887                 }
5888                 case value_t::number_integer:
5889                 {
5890                     return lhs.m_value.number_integer == rhs.m_value.number_integer;
5891                 }
5892                 case value_t::number_unsigned:
5893                 {
5894                     return lhs.m_value.number_unsigned == rhs.m_value.number_unsigned;
5895                 }
5896                 case value_t::number_float:
5897                 {
5898                     return lhs.m_value.number_float == rhs.m_value.number_float;
5899                 }
5900                 default:
5901                 {
5902                     return false;
5903                 }
5904             }
5905         }
5906         else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_float)
5907         {
5908             return static_cast<number_float_t>(lhs.m_value.number_integer) == rhs.m_value.number_float;
5909         }
5910         else if (lhs_type == value_t::number_float and rhs_type == value_t::number_integer)
5911         {
5912             return lhs.m_value.number_float == static_cast<number_float_t>(rhs.m_value.number_integer);
5913         }
5914         else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_float)
5915         {
5916             return static_cast<number_float_t>(lhs.m_value.number_unsigned) == rhs.m_value.number_float;
5917         }
5918         else if (lhs_type == value_t::number_float and rhs_type == value_t::number_unsigned)
5919         {
5920             return lhs.m_value.number_float == static_cast<number_float_t>(rhs.m_value.number_unsigned);
5921         }
5922         else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_integer)
5923         {
5924             return static_cast<number_integer_t>(lhs.m_value.number_unsigned) == rhs.m_value.number_integer;
5925         }
5926         else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_unsigned)
5927         {
5928             return lhs.m_value.number_integer == static_cast<number_integer_t>(rhs.m_value.number_unsigned);
5929         }
5930
5931         return false;
5932     }
5933
5934     /*!
5935     @brief comparison: equal
5936     @copydoc operator==(const_reference, const_reference)
5937     */
5938     template<typename ScalarType, typename std::enable_if<
5939                  std::is_scalar<ScalarType>::value, int>::type = 0>
5940     friend bool operator==(const_reference lhs, const ScalarType rhs) noexcept
5941     {
5942         return (lhs == basic_json(rhs));
5943     }
5944
5945     /*!
5946     @brief comparison: equal
5947     @copydoc operator==(const_reference, const_reference)
5948     */
5949     template<typename ScalarType, typename std::enable_if<
5950                  std::is_scalar<ScalarType>::value, int>::type = 0>
5951     friend bool operator==(const ScalarType lhs, const_reference rhs) noexcept
5952     {
5953         return (basic_json(lhs) == rhs);
5954     }
5955
5956     /*!
5957     @brief comparison: not equal
5958
5959     Compares two JSON values for inequality by calculating `not (lhs == rhs)`.
5960
5961     @param[in] lhs  first JSON value to consider
5962     @param[in] rhs  second JSON value to consider
5963     @return whether the values @a lhs and @a rhs are not equal
5964
5965     @complexity Linear.
5966
5967     @liveexample{The example demonstrates comparing several JSON
5968     types.,operator__notequal}
5969
5970     @since version 1.0.0
5971     */
5972     friend bool operator!=(const_reference lhs, const_reference rhs) noexcept
5973     {
5974         return not (lhs == rhs);
5975     }
5976
5977     /*!
5978     @brief comparison: not equal
5979     @copydoc operator!=(const_reference, const_reference)
5980     */
5981     template<typename ScalarType, typename std::enable_if<
5982                  std::is_scalar<ScalarType>::value, int>::type = 0>
5983     friend bool operator!=(const_reference lhs, const ScalarType rhs) noexcept
5984     {
5985         return (lhs != basic_json(rhs));
5986     }
5987
5988     /*!
5989     @brief comparison: not equal
5990     @copydoc operator!=(const_reference, const_reference)
5991     */
5992     template<typename ScalarType, typename std::enable_if<
5993                  std::is_scalar<ScalarType>::value, int>::type = 0>
5994     friend bool operator!=(const ScalarType lhs, const_reference rhs) noexcept
5995     {
5996         return (basic_json(lhs) != rhs);
5997     }
5998
5999     /*!
6000     @brief comparison: less than
6001
6002     Compares whether one JSON value @a lhs is less than another JSON value @a
6003     rhs according to the following rules:
6004     - If @a lhs and @a rhs have the same type, the values are compared using
6005       the default `<` operator.
6006     - Integer and floating-point numbers are automatically converted before
6007       comparison
6008     - In case @a lhs and @a rhs have different types, the values are ignored
6009       and the order of the types is considered, see
6010       @ref operator<(const value_t, const value_t).
6011
6012     @param[in] lhs  first JSON value to consider
6013     @param[in] rhs  second JSON value to consider
6014     @return whether @a lhs is less than @a rhs
6015
6016     @complexity Linear.
6017
6018     @liveexample{The example demonstrates comparing several JSON
6019     types.,operator__less}
6020
6021     @since version 1.0.0
6022     */
6023     friend bool operator<(const_reference lhs, const_reference rhs) noexcept
6024     {
6025         const auto lhs_type = lhs.type();
6026         const auto rhs_type = rhs.type();
6027
6028         if (lhs_type == rhs_type)
6029         {
6030             switch (lhs_type)
6031             {
6032                 case value_t::array:
6033                 {
6034                     return *lhs.m_value.array < *rhs.m_value.array;
6035                 }
6036                 case value_t::object:
6037                 {
6038                     return *lhs.m_value.object < *rhs.m_value.object;
6039                 }
6040                 case value_t::null:
6041                 {
6042                     return false;
6043                 }
6044                 case value_t::string:
6045                 {
6046                     return *lhs.m_value.string < *rhs.m_value.string;
6047                 }
6048                 case value_t::boolean:
6049                 {
6050                     return lhs.m_value.boolean < rhs.m_value.boolean;
6051                 }
6052                 case value_t::number_integer:
6053                 {
6054                     return lhs.m_value.number_integer < rhs.m_value.number_integer;
6055                 }
6056                 case value_t::number_unsigned:
6057                 {
6058                     return lhs.m_value.number_unsigned < rhs.m_value.number_unsigned;
6059                 }
6060                 case value_t::number_float:
6061                 {
6062                     return lhs.m_value.number_float < rhs.m_value.number_float;
6063                 }
6064                 default:
6065                 {
6066                     return false;
6067                 }
6068             }
6069         }
6070         else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_float)
6071         {
6072             return static_cast<number_float_t>(lhs.m_value.number_integer) < rhs.m_value.number_float;
6073         }
6074         else if (lhs_type == value_t::number_float and rhs_type == value_t::number_integer)
6075         {
6076             return lhs.m_value.number_float < static_cast<number_float_t>(rhs.m_value.number_integer);
6077         }
6078         else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_float)
6079         {
6080             return static_cast<number_float_t>(lhs.m_value.number_unsigned) < rhs.m_value.number_float;
6081         }
6082         else if (lhs_type == value_t::number_float and rhs_type == value_t::number_unsigned)
6083         {
6084             return lhs.m_value.number_float < static_cast<number_float_t>(rhs.m_value.number_unsigned);
6085         }
6086         else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_unsigned)
6087         {
6088             return lhs.m_value.number_integer < static_cast<number_integer_t>(rhs.m_value.number_unsigned);
6089         }
6090         else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_integer)
6091         {
6092             return static_cast<number_integer_t>(lhs.m_value.number_unsigned) < rhs.m_value.number_integer;
6093         }
6094
6095         // We only reach this line if we cannot compare values. In that case,
6096         // we compare types. Note we have to call the operator explicitly,
6097         // because MSVC has problems otherwise.
6098         return operator<(lhs_type, rhs_type);
6099     }
6100
6101     /*!
6102     @brief comparison: less than or equal
6103
6104     Compares whether one JSON value @a lhs is less than or equal to another
6105     JSON value by calculating `not (rhs < lhs)`.
6106
6107     @param[in] lhs  first JSON value to consider
6108     @param[in] rhs  second JSON value to consider
6109     @return whether @a lhs is less than or equal to @a rhs
6110
6111     @complexity Linear.
6112
6113     @liveexample{The example demonstrates comparing several JSON
6114     types.,operator__greater}
6115
6116     @since version 1.0.0
6117     */
6118     friend bool operator<=(const_reference lhs, const_reference rhs) noexcept
6119     {
6120         return not (rhs < lhs);
6121     }
6122
6123     /*!
6124     @brief comparison: greater than
6125
6126     Compares whether one JSON value @a lhs is greater than another
6127     JSON value by calculating `not (lhs <= rhs)`.
6128
6129     @param[in] lhs  first JSON value to consider
6130     @param[in] rhs  second JSON value to consider
6131     @return whether @a lhs is greater than to @a rhs
6132
6133     @complexity Linear.
6134
6135     @liveexample{The example demonstrates comparing several JSON
6136     types.,operator__lessequal}
6137
6138     @since version 1.0.0
6139     */
6140     friend bool operator>(const_reference lhs, const_reference rhs) noexcept
6141     {
6142         return not (lhs <= rhs);
6143     }
6144
6145     /*!
6146     @brief comparison: greater than or equal
6147
6148     Compares whether one JSON value @a lhs is greater than or equal to another
6149     JSON value by calculating `not (lhs < rhs)`.
6150
6151     @param[in] lhs  first JSON value to consider
6152     @param[in] rhs  second JSON value to consider
6153     @return whether @a lhs is greater than or equal to @a rhs
6154
6155     @complexity Linear.
6156
6157     @liveexample{The example demonstrates comparing several JSON
6158     types.,operator__greaterequal}
6159
6160     @since version 1.0.0
6161     */
6162     friend bool operator>=(const_reference lhs, const_reference rhs) noexcept
6163     {
6164         return not (lhs < rhs);
6165     }
6166
6167     /// @}
6168
6169
6170     ///////////////////
6171     // serialization //
6172     ///////////////////
6173
6174     /// @name serialization
6175     /// @{
6176
6177     /*!
6178     @brief serialize to stream
6179
6180     Serialize the given JSON value @a j to the output stream @a o. The JSON
6181     value will be serialized using the @ref dump member function. The
6182     indentation of the output can be controlled with the member variable
6183     `width` of the output stream @a o. For instance, using the manipulator
6184     `std::setw(4)` on @a o sets the indentation level to `4` and the
6185     serialization result is the same as calling `dump(4)`.
6186
6187     @param[in,out] o  stream to serialize to
6188     @param[in] j  JSON value to serialize
6189
6190     @return the stream @a o
6191
6192     @complexity Linear.
6193
6194     @liveexample{The example below shows the serialization with different
6195     parameters to `width` to adjust the indentation level.,operator_serialize}
6196
6197     @since version 1.0.0
6198     */
6199     friend std::ostream& operator<<(std::ostream& o, const basic_json& j)
6200     {
6201         // read width member and use it as indentation parameter if nonzero
6202         const bool pretty_print = (o.width() > 0);
6203         const auto indentation = (pretty_print ? o.width() : 0);
6204
6205         // reset width to 0 for subsequent calls to this stream
6206         o.width(0);
6207
6208         // do the actual serialization
6209         j.dump(o, pretty_print, static_cast<unsigned int>(indentation));
6210
6211         return o;
6212     }
6213
6214     /*!
6215     @brief serialize to stream
6216     @copydoc operator<<(std::ostream&, const basic_json&)
6217     */
6218     friend std::ostream& operator>>(const basic_json& j, std::ostream& o)
6219     {
6220         return o << j;
6221     }
6222
6223     /// @}
6224
6225
6226     /////////////////////
6227     // deserialization //
6228     /////////////////////
6229
6230     /// @name deserialization
6231     /// @{
6232
6233     /*!
6234     @brief deserialize from an array
6235
6236     This function reads from an array of 1-byte values.
6237
6238     @pre Each element of the container has a size of 1 byte. Violating this
6239     precondition yields undefined behavior. **This precondition is enforced
6240     with a static assertion.**
6241
6242     @param[in] array  array to read from
6243     @param[in] cb  a parser callback function of type @ref parser_callback_t
6244     which is used to control the deserialization by filtering unwanted values
6245     (optional)
6246
6247     @return result of the deserialization
6248
6249     @complexity Linear in the length of the input. The parser is a predictive
6250     LL(1) parser. The complexity can be higher if the parser callback function
6251     @a cb has a super-linear complexity.
6252
6253     @note A UTF-8 byte order mark is silently ignored.
6254
6255     @liveexample{The example below demonstrates the `parse()` function reading
6256     from an array.,parse__array__parser_callback_t}
6257
6258     @since version 2.0.3
6259     */
6260     template<class T, std::size_t N>
6261     static basic_json parse(T (&array)[N],
6262                             const parser_callback_t cb = nullptr)
6263     {
6264         // delegate the call to the iterator-range parse overload
6265         return parse(std::begin(array), std::end(array), cb);
6266     }
6267
6268     /*!
6269     @brief deserialize from string literal
6270
6271     @tparam CharT character/literal type with size of 1 byte
6272     @param[in] s  string literal to read a serialized JSON value from
6273     @param[in] cb a parser callback function of type @ref parser_callback_t
6274     which is used to control the deserialization by filtering unwanted values
6275     (optional)
6276
6277     @return result of the deserialization
6278
6279     @complexity Linear in the length of the input. The parser is a predictive
6280     LL(1) parser. The complexity can be higher if the parser callback function
6281     @a cb has a super-linear complexity.
6282
6283     @note A UTF-8 byte order mark is silently ignored.
6284     @note String containers like `std::string` or @ref string_t can be parsed
6285           with @ref parse(const ContiguousContainer&, const parser_callback_t)
6286
6287     @liveexample{The example below demonstrates the `parse()` function with
6288     and without callback function.,parse__string__parser_callback_t}
6289
6290     @sa @ref parse(std::istream&, const parser_callback_t) for a version that
6291     reads from an input stream
6292
6293     @since version 1.0.0 (originally for @ref string_t)
6294     */
6295     template<typename CharT, typename std::enable_if<
6296                  std::is_pointer<CharT>::value and
6297                  std::is_integral<typename std::remove_pointer<CharT>::type>::value and
6298                  sizeof(typename std::remove_pointer<CharT>::type) == 1, int>::type = 0>
6299     static basic_json parse(const CharT s,
6300                             const parser_callback_t cb = nullptr)
6301     {
6302         return parser(reinterpret_cast<const char*>(s), cb).parse();
6303     }
6304
6305     /*!
6306     @brief deserialize from stream
6307
6308     @param[in,out] i  stream to read a serialized JSON value from
6309     @param[in] cb a parser callback function of type @ref parser_callback_t
6310     which is used to control the deserialization by filtering unwanted values
6311     (optional)
6312
6313     @return result of the deserialization
6314
6315     @complexity Linear in the length of the input. The parser is a predictive
6316     LL(1) parser. The complexity can be higher if the parser callback function
6317     @a cb has a super-linear complexity.
6318
6319     @note A UTF-8 byte order mark is silently ignored.
6320
6321     @liveexample{The example below demonstrates the `parse()` function with
6322     and without callback function.,parse__istream__parser_callback_t}
6323
6324     @sa @ref parse(const CharT, const parser_callback_t) for a version
6325     that reads from a string
6326
6327     @since version 1.0.0
6328     */
6329     static basic_json parse(std::istream& i,
6330                             const parser_callback_t cb = nullptr)
6331     {
6332         return parser(i, cb).parse();
6333     }
6334
6335     /*!
6336     @copydoc parse(std::istream&, const parser_callback_t)
6337     */
6338     static basic_json parse(std::istream&& i,
6339                             const parser_callback_t cb = nullptr)
6340     {
6341         return parser(i, cb).parse();
6342     }
6343
6344     /*!
6345     @brief deserialize from an iterator range with contiguous storage
6346
6347     This function reads from an iterator range of a container with contiguous
6348     storage of 1-byte values. Compatible container types include
6349     `std::vector`, `std::string`, `std::array`, `std::valarray`, and
6350     `std::initializer_list`. Furthermore, C-style arrays can be used with
6351     `std::begin()`/`std::end()`. User-defined containers can be used as long
6352     as they implement random-access iterators and a contiguous storage.
6353
6354     @pre The iterator range is contiguous. Violating this precondition yields
6355     undefined behavior. **This precondition is enforced with an assertion.**
6356     @pre Each element in the range has a size of 1 byte. Violating this
6357     precondition yields undefined behavior. **This precondition is enforced
6358     with a static assertion.**
6359
6360     @warning There is no way to enforce all preconditions at compile-time. If
6361              the function is called with noncompliant iterators and with
6362              assertions switched off, the behavior is undefined and will most
6363              likely yield segmentation violation.
6364
6365     @tparam IteratorType iterator of container with contiguous storage
6366     @param[in] first  begin of the range to parse (included)
6367     @param[in] last  end of the range to parse (excluded)
6368     @param[in] cb  a parser callback function of type @ref parser_callback_t
6369     which is used to control the deserialization by filtering unwanted values
6370     (optional)
6371
6372     @return result of the deserialization
6373
6374     @complexity Linear in the length of the input. The parser is a predictive
6375     LL(1) parser. The complexity can be higher if the parser callback function
6376     @a cb has a super-linear complexity.
6377
6378     @note A UTF-8 byte order mark is silently ignored.
6379
6380     @liveexample{The example below demonstrates the `parse()` function reading
6381     from an iterator range.,parse__iteratortype__parser_callback_t}
6382
6383     @since version 2.0.3
6384     */
6385     template<class IteratorType, typename std::enable_if<
6386                  std::is_base_of<
6387                      std::random_access_iterator_tag,
6388                      typename std::iterator_traits<IteratorType>::iterator_category>::value, int>::type = 0>
6389     static basic_json parse(IteratorType first, IteratorType last,
6390                             const parser_callback_t cb = nullptr)
6391     {
6392         // assertion to check that the iterator range is indeed contiguous,
6393         // see http://stackoverflow.com/a/35008842/266378 for more discussion
6394         assert(std::accumulate(first, last, std::pair<bool, int>(true, 0),
6395                                [&first](std::pair<bool, int> res, decltype(*first) val)
6396         {
6397             res.first &= (val == *(std::next(std::addressof(*first), res.second++)));
6398             return res;
6399         }).first);
6400
6401         // assertion to check that each element is 1 byte long
6402         static_assert(sizeof(typename std::iterator_traits<IteratorType>::value_type) == 1,
6403                       "each element in the iterator range must have the size of 1 byte");
6404
6405         // if iterator range is empty, create a parser with an empty string
6406         // to generate "unexpected EOF" error message
6407         if (std::distance(first, last) <= 0)
6408         {
6409             return parser("").parse();
6410         }
6411
6412         return parser(first, last, cb).parse();
6413     }
6414
6415     /*!
6416     @brief deserialize from a container with contiguous storage
6417
6418     This function reads from a container with contiguous storage of 1-byte
6419     values. Compatible container types include `std::vector`, `std::string`,
6420     `std::array`, and `std::initializer_list`. User-defined containers can be
6421     used as long as they implement random-access iterators and a contiguous
6422     storage.
6423
6424     @pre The container storage is contiguous. Violating this precondition
6425     yields undefined behavior. **This precondition is enforced with an
6426     assertion.**
6427     @pre Each element of the container has a size of 1 byte. Violating this
6428     precondition yields undefined behavior. **This precondition is enforced
6429     with a static assertion.**
6430
6431     @warning There is no way to enforce all preconditions at compile-time. If
6432              the function is called with a noncompliant container and with
6433              assertions switched off, the behavior is undefined and will most
6434              likely yield segmentation violation.
6435
6436     @tparam ContiguousContainer container type with contiguous storage
6437     @param[in] c  container to read from
6438     @param[in] cb  a parser callback function of type @ref parser_callback_t
6439     which is used to control the deserialization by filtering unwanted values
6440     (optional)
6441
6442     @return result of the deserialization
6443
6444     @complexity Linear in the length of the input. The parser is a predictive
6445     LL(1) parser. The complexity can be higher if the parser callback function
6446     @a cb has a super-linear complexity.
6447
6448     @note A UTF-8 byte order mark is silently ignored.
6449
6450     @liveexample{The example below demonstrates the `parse()` function reading
6451     from a contiguous container.,parse__contiguouscontainer__parser_callback_t}
6452
6453     @since version 2.0.3
6454     */
6455     template<class ContiguousContainer, typename std::enable_if<
6456                  not std::is_pointer<ContiguousContainer>::value and
6457                  std::is_base_of<
6458                      std::random_access_iterator_tag,
6459                      typename std::iterator_traits<decltype(std::begin(std::declval<ContiguousContainer const>()))>::iterator_category>::value
6460                  , int>::type = 0>
6461     static basic_json parse(const ContiguousContainer& c,
6462                             const parser_callback_t cb = nullptr)
6463     {
6464         // delegate the call to the iterator-range parse overload
6465         return parse(std::begin(c), std::end(c), cb);
6466     }
6467
6468     /*!
6469     @brief deserialize from stream
6470
6471     Deserializes an input stream to a JSON value.
6472
6473     @param[in,out] i  input stream to read a serialized JSON value from
6474     @param[in,out] j  JSON value to write the deserialized input to
6475
6476     @throw std::invalid_argument in case of parse errors
6477
6478     @complexity Linear in the length of the input. The parser is a predictive
6479     LL(1) parser.
6480
6481     @note A UTF-8 byte order mark is silently ignored.
6482
6483     @liveexample{The example below shows how a JSON value is constructed by
6484     reading a serialization from a stream.,operator_deserialize}
6485
6486     @sa parse(std::istream&, const parser_callback_t) for a variant with a
6487     parser callback function to filter values while parsing
6488
6489     @since version 1.0.0
6490     */
6491     friend std::istream& operator<<(basic_json& j, std::istream& i)
6492     {
6493         j = parser(i).parse();
6494         return i;
6495     }
6496
6497     /*!
6498     @brief deserialize from stream
6499     @copydoc operator<<(basic_json&, std::istream&)
6500     */
6501     friend std::istream& operator>>(std::istream& i, basic_json& j)
6502     {
6503         j = parser(i).parse();
6504         return i;
6505     }
6506
6507     /// @}
6508
6509     //////////////////////////////////////////
6510     // binary serialization/deserialization //
6511     //////////////////////////////////////////
6512
6513     /// @name binary serialization/deserialization support
6514     /// @{
6515
6516   private:
6517     /*!
6518     @note Some code in the switch cases has been copied, because otherwise
6519           copilers would complain about implicit fallthrough and there is no
6520           portable attribute to mute such warnings.
6521     */
6522     template<typename T>
6523     static void add_to_vector(std::vector<uint8_t>& vec, size_t bytes, const T number)
6524     {
6525         assert(bytes == 1 or bytes == 2 or bytes == 4 or bytes == 8);
6526
6527         switch (bytes)
6528         {
6529             case 8:
6530             {
6531                 vec.push_back(static_cast<uint8_t>((static_cast<uint64_t>(number) >> 070) & 0xff));
6532                 vec.push_back(static_cast<uint8_t>((static_cast<uint64_t>(number) >> 060) & 0xff));
6533                 vec.push_back(static_cast<uint8_t>((static_cast<uint64_t>(number) >> 050) & 0xff));
6534                 vec.push_back(static_cast<uint8_t>((static_cast<uint64_t>(number) >> 040) & 0xff));
6535                 vec.push_back(static_cast<uint8_t>((number >> 030) & 0xff));
6536                 vec.push_back(static_cast<uint8_t>((number >> 020) & 0xff));
6537                 vec.push_back(static_cast<uint8_t>((number >> 010) & 0xff));
6538                 vec.push_back(static_cast<uint8_t>(number & 0xff));
6539                 break;
6540             }
6541
6542             case 4:
6543             {
6544                 vec.push_back(static_cast<uint8_t>((number >> 030) & 0xff));
6545                 vec.push_back(static_cast<uint8_t>((number >> 020) & 0xff));
6546                 vec.push_back(static_cast<uint8_t>((number >> 010) & 0xff));
6547                 vec.push_back(static_cast<uint8_t>(number & 0xff));
6548                 break;
6549             }
6550
6551             case 2:
6552             {
6553                 vec.push_back(static_cast<uint8_t>((number >> 010) & 0xff));
6554                 vec.push_back(static_cast<uint8_t>(number & 0xff));
6555                 break;
6556             }
6557
6558             case 1:
6559             {
6560                 vec.push_back(static_cast<uint8_t>(number & 0xff));
6561                 break;
6562             }
6563         }
6564     }
6565
6566     /*!
6567     @brief take sufficient bytes from a vector to fill an integer variable
6568
6569     In the context of binary serialization formats, we need to read several
6570     bytes from a byte vector and combine them to multi-byte integral data
6571     types.
6572
6573     @param[in] vec  byte vector to read from
6574     @param[in] current_index  the position in the vector after which to read
6575
6576     @return the next sizeof(T) bytes from @a vec, in reverse order as T
6577
6578     @tparam T the integral return type
6579
6580     @throw std::out_of_range if there are less than sizeof(T)+1 bytes in the
6581            vector @a vec to read
6582
6583     In the for loop, the bytes from the vector are copied in reverse order into
6584     the return value. In the figures below, let sizeof(T)=4 and `i` be the loop
6585     variable.
6586
6587     Precondition:
6588
6589     vec:   |   |   | a | b | c | d |      T: |   |   |   |   |
6590                  ^               ^             ^                ^
6591            current_index         i            ptr        sizeof(T)
6592
6593     Postcondition:
6594
6595     vec:   |   |   | a | b | c | d |      T: | d | c | b | a |
6596                  ^   ^                                     ^
6597                  |   i                                    ptr
6598            current_index
6599
6600     @sa Code adapted from <http://stackoverflow.com/a/41031865/266378>.
6601     */
6602     template<typename T>
6603     static T get_from_vector(const std::vector<uint8_t>& vec, const size_t current_index)
6604     {
6605         if (current_index + sizeof(T) + 1 > vec.size())
6606         {
6607             JSON_THROW(std::out_of_range("cannot read " + std::to_string(sizeof(T)) + " bytes from vector"));
6608         }
6609
6610         T result;
6611         auto* ptr = reinterpret_cast<uint8_t*>(&result);
6612         for (size_t i = 0; i < sizeof(T); ++i)
6613         {
6614             *ptr++ = vec[current_index + sizeof(T) - i];
6615         }
6616         return result;
6617     }
6618
6619     /*!
6620     @brief create a MessagePack serialization of a given JSON value
6621
6622     This is a straightforward implementation of the MessagePack specification.
6623
6624     @param[in] j  JSON value to serialize
6625     @param[in,out] v  byte vector to write the serialization to
6626
6627     @sa https://github.com/msgpack/msgpack/blob/master/spec.md
6628     */
6629     static void to_msgpack_internal(const basic_json& j, std::vector<uint8_t>& v)
6630     {
6631         switch (j.type())
6632         {
6633             case value_t::null:
6634             {
6635                 // nil
6636                 v.push_back(0xc0);
6637                 break;
6638             }
6639
6640             case value_t::boolean:
6641             {
6642                 // true and false
6643                 v.push_back(j.m_value.boolean ? 0xc3 : 0xc2);
6644                 break;
6645             }
6646
6647             case value_t::number_integer:
6648             {
6649                 if (j.m_value.number_integer >= 0)
6650                 {
6651                     // MessagePack does not differentiate between positive
6652                     // signed integers and unsigned integers. Therefore, we
6653                     // used the code from the value_t::number_unsigned case
6654                     // here.
6655                     if (j.m_value.number_unsigned < 128)
6656                     {
6657                         // positive fixnum
6658                         add_to_vector(v, 1, j.m_value.number_unsigned);
6659                     }
6660                     else if (j.m_value.number_unsigned <= std::numeric_limits<uint8_t>::max())
6661                     {
6662                         // uint 8
6663                         v.push_back(0xcc);
6664                         add_to_vector(v, 1, j.m_value.number_unsigned);
6665                     }
6666                     else if (j.m_value.number_unsigned <= std::numeric_limits<uint16_t>::max())
6667                     {
6668                         // uint 16
6669                         v.push_back(0xcd);
6670                         add_to_vector(v, 2, j.m_value.number_unsigned);
6671                     }
6672                     else if (j.m_value.number_unsigned <= std::numeric_limits<uint32_t>::max())
6673                     {
6674                         // uint 32
6675                         v.push_back(0xce);
6676                         add_to_vector(v, 4, j.m_value.number_unsigned);
6677                     }
6678                     else if (j.m_value.number_unsigned <= std::numeric_limits<uint64_t>::max())
6679                     {
6680                         // uint 64
6681                         v.push_back(0xcf);
6682                         add_to_vector(v, 8, j.m_value.number_unsigned);
6683                     }
6684                 }
6685                 else
6686                 {
6687                     if (j.m_value.number_integer >= -32)
6688                     {
6689                         // negative fixnum
6690                         add_to_vector(v, 1, j.m_value.number_integer);
6691                     }
6692                     else if (j.m_value.number_integer >= std::numeric_limits<int8_t>::min() and j.m_value.number_integer <= std::numeric_limits<int8_t>::max())
6693                     {
6694                         // int 8
6695                         v.push_back(0xd0);
6696                         add_to_vector(v, 1, j.m_value.number_integer);
6697                     }
6698                     else if (j.m_value.number_integer >= std::numeric_limits<int16_t>::min() and j.m_value.number_integer <= std::numeric_limits<int16_t>::max())
6699                     {
6700                         // int 16
6701                         v.push_back(0xd1);
6702                         add_to_vector(v, 2, j.m_value.number_integer);
6703                     }
6704                     else if (j.m_value.number_integer >= std::numeric_limits<int32_t>::min() and j.m_value.number_integer <= std::numeric_limits<int32_t>::max())
6705                     {
6706                         // int 32
6707                         v.push_back(0xd2);
6708                         add_to_vector(v, 4, j.m_value.number_integer);
6709                     }
6710                     else if (j.m_value.number_integer >= std::numeric_limits<int64_t>::min() and j.m_value.number_integer <= std::numeric_limits<int64_t>::max())
6711                     {
6712                         // int 64
6713                         v.push_back(0xd3);
6714                         add_to_vector(v, 8, j.m_value.number_integer);
6715                     }
6716                 }
6717                 break;
6718             }
6719
6720             case value_t::number_unsigned:
6721             {
6722                 if (j.m_value.number_unsigned < 128)
6723                 {
6724                     // positive fixnum
6725                     add_to_vector(v, 1, j.m_value.number_unsigned);
6726                 }
6727                 else if (j.m_value.number_unsigned <= std::numeric_limits<uint8_t>::max())
6728                 {
6729                     // uint 8
6730                     v.push_back(0xcc);
6731                     add_to_vector(v, 1, j.m_value.number_unsigned);
6732                 }
6733                 else if (j.m_value.number_unsigned <= std::numeric_limits<uint16_t>::max())
6734                 {
6735                     // uint 16
6736                     v.push_back(0xcd);
6737                     add_to_vector(v, 2, j.m_value.number_unsigned);
6738                 }
6739                 else if (j.m_value.number_unsigned <= std::numeric_limits<uint32_t>::max())
6740                 {
6741                     // uint 32
6742                     v.push_back(0xce);
6743                     add_to_vector(v, 4, j.m_value.number_unsigned);
6744                 }
6745                 else if (j.m_value.number_unsigned <= std::numeric_limits<uint64_t>::max())
6746                 {
6747                     // uint 64
6748                     v.push_back(0xcf);
6749                     add_to_vector(v, 8, j.m_value.number_unsigned);
6750                 }
6751                 break;
6752             }
6753
6754             case value_t::number_float:
6755             {
6756                 // float 64
6757                 v.push_back(0xcb);
6758                 const auto* helper = reinterpret_cast<const uint8_t*>(&(j.m_value.number_float));
6759                 for (size_t i = 0; i < 8; ++i)
6760                 {
6761                     v.push_back(helper[7 - i]);
6762                 }
6763                 break;
6764             }
6765
6766             case value_t::string:
6767             {
6768                 const auto N = j.m_value.string->size();
6769                 if (N <= 31)
6770                 {
6771                     // fixstr
6772                     v.push_back(static_cast<uint8_t>(0xa0 | N));
6773                 }
6774                 else if (N <= 255)
6775                 {
6776                     // str 8
6777                     v.push_back(0xd9);
6778                     add_to_vector(v, 1, N);
6779                 }
6780                 else if (N <= 65535)
6781                 {
6782                     // str 16
6783                     v.push_back(0xda);
6784                     add_to_vector(v, 2, N);
6785                 }
6786                 else if (N <= 4294967295)
6787                 {
6788                     // str 32
6789                     v.push_back(0xdb);
6790                     add_to_vector(v, 4, N);
6791                 }
6792
6793                 // append string
6794                 std::copy(j.m_value.string->begin(), j.m_value.string->end(),
6795                           std::back_inserter(v));
6796                 break;
6797             }
6798
6799             case value_t::array:
6800             {
6801                 const auto N = j.m_value.array->size();
6802                 if (N <= 15)
6803                 {
6804                     // fixarray
6805                     v.push_back(static_cast<uint8_t>(0x90 | N));
6806                 }
6807                 else if (N <= 0xffff)
6808                 {
6809                     // array 16
6810                     v.push_back(0xdc);
6811                     add_to_vector(v, 2, N);
6812                 }
6813                 else if (N <= 0xffffffff)
6814                 {
6815                     // array 32
6816                     v.push_back(0xdd);
6817                     add_to_vector(v, 4, N);
6818                 }
6819
6820                 // append each element
6821                 for (const auto& el : *j.m_value.array)
6822                 {
6823                     to_msgpack_internal(el, v);
6824                 }
6825                 break;
6826             }
6827
6828             case value_t::object:
6829             {
6830                 const auto N = j.m_value.object->size();
6831                 if (N <= 15)
6832                 {
6833                     // fixmap
6834                     v.push_back(static_cast<uint8_t>(0x80 | (N & 0xf)));
6835                 }
6836                 else if (N <= 65535)
6837                 {
6838                     // map 16
6839                     v.push_back(0xde);
6840                     add_to_vector(v, 2, N);
6841                 }
6842                 else if (N <= 4294967295)
6843                 {
6844                     // map 32
6845                     v.push_back(0xdf);
6846                     add_to_vector(v, 4, N);
6847                 }
6848
6849                 // append each element
6850                 for (const auto& el : *j.m_value.object)
6851                 {
6852                     to_msgpack_internal(el.first, v);
6853                     to_msgpack_internal(el.second, v);
6854                 }
6855                 break;
6856             }
6857
6858             default:
6859             {
6860                 break;
6861             }
6862         }
6863     }
6864
6865     /*!
6866     @brief create a CBOR serialization of a given JSON value
6867
6868     This is a straightforward implementation of the CBOR specification.
6869
6870     @param[in] j  JSON value to serialize
6871     @param[in,out] v  byte vector to write the serialization to
6872
6873     @sa https://tools.ietf.org/html/rfc7049
6874     */
6875     static void to_cbor_internal(const basic_json& j, std::vector<uint8_t>& v)
6876     {
6877         switch (j.type())
6878         {
6879             case value_t::null:
6880             {
6881                 v.push_back(0xf6);
6882                 break;
6883             }
6884
6885             case value_t::boolean:
6886             {
6887                 v.push_back(j.m_value.boolean ? 0xf5 : 0xf4);
6888                 break;
6889             }
6890
6891             case value_t::number_integer:
6892             {
6893                 if (j.m_value.number_integer >= 0)
6894                 {
6895                     // CBOR does not differentiate between positive signed
6896                     // integers and unsigned integers. Therefore, we used the
6897                     // code from the value_t::number_unsigned case here.
6898                     if (j.m_value.number_integer <= 0x17)
6899                     {
6900                         add_to_vector(v, 1, j.m_value.number_integer);
6901                     }
6902                     else if (j.m_value.number_integer <= std::numeric_limits<uint8_t>::max())
6903                     {
6904                         v.push_back(0x18);
6905                         // one-byte uint8_t
6906                         add_to_vector(v, 1, j.m_value.number_integer);
6907                     }
6908                     else if (j.m_value.number_integer <= std::numeric_limits<uint16_t>::max())
6909                     {
6910                         v.push_back(0x19);
6911                         // two-byte uint16_t
6912                         add_to_vector(v, 2, j.m_value.number_integer);
6913                     }
6914                     else if (j.m_value.number_integer <= std::numeric_limits<uint32_t>::max())
6915                     {
6916                         v.push_back(0x1a);
6917                         // four-byte uint32_t
6918                         add_to_vector(v, 4, j.m_value.number_integer);
6919                     }
6920                     else
6921                     {
6922                         v.push_back(0x1b);
6923                         // eight-byte uint64_t
6924                         add_to_vector(v, 8, j.m_value.number_integer);
6925                     }
6926                 }
6927                 else
6928                 {
6929                     // The conversions below encode the sign in the first
6930                     // byte, and the value is converted to a positive number.
6931                     const auto positive_number = -1 - j.m_value.number_integer;
6932                     if (j.m_value.number_integer >= -24)
6933                     {
6934                         v.push_back(static_cast<uint8_t>(0x20 + positive_number));
6935                     }
6936                     else if (positive_number <= std::numeric_limits<uint8_t>::max())
6937                     {
6938                         // int 8
6939                         v.push_back(0x38);
6940                         add_to_vector(v, 1, positive_number);
6941                     }
6942                     else if (positive_number <= std::numeric_limits<uint16_t>::max())
6943                     {
6944                         // int 16
6945                         v.push_back(0x39);
6946                         add_to_vector(v, 2, positive_number);
6947                     }
6948                     else if (positive_number <= std::numeric_limits<uint32_t>::max())
6949                     {
6950                         // int 32
6951                         v.push_back(0x3a);
6952                         add_to_vector(v, 4, positive_number);
6953                     }
6954                     else
6955                     {
6956                         // int 64
6957                         v.push_back(0x3b);
6958                         add_to_vector(v, 8, positive_number);
6959                     }
6960                 }
6961                 break;
6962             }
6963
6964             case value_t::number_unsigned:
6965             {
6966                 if (j.m_value.number_unsigned <= 0x17)
6967                 {
6968                     v.push_back(static_cast<uint8_t>(j.m_value.number_unsigned));
6969                 }
6970                 else if (j.m_value.number_unsigned <= 0xff)
6971                 {
6972                     v.push_back(0x18);
6973                     // one-byte uint8_t
6974                     add_to_vector(v, 1, j.m_value.number_unsigned);
6975                 }
6976                 else if (j.m_value.number_unsigned <= 0xffff)
6977                 {
6978                     v.push_back(0x19);
6979                     // two-byte uint16_t
6980                     add_to_vector(v, 2, j.m_value.number_unsigned);
6981                 }
6982                 else if (j.m_value.number_unsigned <= 0xffffffff)
6983                 {
6984                     v.push_back(0x1a);
6985                     // four-byte uint32_t
6986                     add_to_vector(v, 4, j.m_value.number_unsigned);
6987                 }
6988                 else if (j.m_value.number_unsigned <= 0xffffffffffffffff)
6989                 {
6990                     v.push_back(0x1b);
6991                     // eight-byte uint64_t
6992                     add_to_vector(v, 8, j.m_value.number_unsigned);
6993                 }
6994                 break;
6995             }
6996
6997             case value_t::number_float:
6998             {
6999                 // Double-Precision Float
7000                 v.push_back(0xfb);
7001                 const auto* helper = reinterpret_cast<const uint8_t*>(&(j.m_value.number_float));
7002                 for (size_t i = 0; i < 8; ++i)
7003                 {
7004                     v.push_back(helper[7 - i]);
7005                 }
7006                 break;
7007             }
7008
7009             case value_t::string:
7010             {
7011                 const auto N = j.m_value.string->size();
7012                 if (N <= 0x17)
7013                 {
7014                     v.push_back(0x60 + static_cast<uint8_t>(N));  // 1 byte for string + size
7015                 }
7016                 else if (N <= 0xff)
7017                 {
7018                     v.push_back(0x78);  // one-byte uint8_t for N
7019                     add_to_vector(v, 1, N);
7020                 }
7021                 else if (N <= 0xffff)
7022                 {
7023                     v.push_back(0x79);  // two-byte uint16_t for N
7024                     add_to_vector(v, 2, N);
7025                 }
7026                 else if (N <= 0xffffffff)
7027                 {
7028                     v.push_back(0x7a); // four-byte uint32_t for N
7029                     add_to_vector(v, 4, N);
7030                 }
7031                 // LCOV_EXCL_START
7032                 else if (N <= 0xffffffffffffffff)
7033                 {
7034                     v.push_back(0x7b);  // eight-byte uint64_t for N
7035                     add_to_vector(v, 8, N);
7036                 }
7037                 // LCOV_EXCL_STOP
7038
7039                 // append string
7040                 std::copy(j.m_value.string->begin(), j.m_value.string->end(),
7041                           std::back_inserter(v));
7042                 break;
7043             }
7044
7045             case value_t::array:
7046             {
7047                 const auto N = j.m_value.array->size();
7048                 if (N <= 0x17)
7049                 {
7050                     v.push_back(0x80 + static_cast<uint8_t>(N));  // 1 byte for array + size
7051                 }
7052                 else if (N <= 0xff)
7053                 {
7054                     v.push_back(0x98);  // one-byte uint8_t for N
7055                     add_to_vector(v, 1, N);
7056                 }
7057                 else if (N <= 0xffff)
7058                 {
7059                     v.push_back(0x99);  // two-byte uint16_t for N
7060                     add_to_vector(v, 2, N);
7061                 }
7062                 else if (N <= 0xffffffff)
7063                 {
7064                     v.push_back(0x9a);  // four-byte uint32_t for N
7065                     add_to_vector(v, 4, N);
7066                 }
7067                 // LCOV_EXCL_START
7068                 else if (N <= 0xffffffffffffffff)
7069                 {
7070                     v.push_back(0x9b);  // eight-byte uint64_t for N
7071                     add_to_vector(v, 8, N);
7072                 }
7073                 // LCOV_EXCL_STOP
7074
7075                 // append each element
7076                 for (const auto& el : *j.m_value.array)
7077                 {
7078                     to_cbor_internal(el, v);
7079                 }
7080                 break;
7081             }
7082
7083             case value_t::object:
7084             {
7085                 const auto N = j.m_value.object->size();
7086                 if (N <= 0x17)
7087                 {
7088                     v.push_back(0xa0 + static_cast<uint8_t>(N));  // 1 byte for object + size
7089                 }
7090                 else if (N <= 0xff)
7091                 {
7092                     v.push_back(0xb8);
7093                     add_to_vector(v, 1, N);  // one-byte uint8_t for N
7094                 }
7095                 else if (N <= 0xffff)
7096                 {
7097                     v.push_back(0xb9);
7098                     add_to_vector(v, 2, N);  // two-byte uint16_t for N
7099                 }
7100                 else if (N <= 0xffffffff)
7101                 {
7102                     v.push_back(0xba);
7103                     add_to_vector(v, 4, N);  // four-byte uint32_t for N
7104                 }
7105                 // LCOV_EXCL_START
7106                 else if (N <= 0xffffffffffffffff)
7107                 {
7108                     v.push_back(0xbb);
7109                     add_to_vector(v, 8, N);  // eight-byte uint64_t for N
7110                 }
7111                 // LCOV_EXCL_STOP
7112
7113                 // append each element
7114                 for (const auto& el : *j.m_value.object)
7115                 {
7116                     to_cbor_internal(el.first, v);
7117                     to_cbor_internal(el.second, v);
7118                 }
7119                 break;
7120             }
7121
7122             default:
7123             {
7124                 break;
7125             }
7126         }
7127     }
7128
7129
7130     /*
7131     @brief checks if given lengths do not exceed the size of a given vector
7132
7133     To secure the access to the byte vector during CBOR/MessagePack
7134     deserialization, bytes are copied from the vector into buffers. This
7135     function checks if the number of bytes to copy (@a len) does not exceed
7136     the size @s size of the vector. Additionally, an @a offset is given from
7137     where to start reading the bytes.
7138
7139     This function checks whether reading the bytes is safe; that is, offset is
7140     a valid index in the vector, offset+len
7141
7142     @param[in] size    size of the byte vector
7143     @param[in] len     number of bytes to read
7144     @param[in] offset  offset where to start reading
7145
7146     vec:  x x x x x X X X X X
7147           ^         ^         ^
7148           0         offset    len
7149
7150     @throws out_of_range if `len > v.size()`
7151     */
7152     static void check_length(const size_t size, const size_t len, const size_t offset)
7153     {
7154         // simple case: requested length is greater than the vector's length
7155         if (len > size or offset > size)
7156         {
7157             JSON_THROW(std::out_of_range("len out of range"));
7158         }
7159
7160         // second case: adding offset would result in overflow
7161         if ((size > (std::numeric_limits<size_t>::max() - offset)))
7162         {
7163             JSON_THROW(std::out_of_range("len+offset out of range"));
7164         }
7165
7166         // last case: reading past the end of the vector
7167         if (len + offset > size)
7168         {
7169             JSON_THROW(std::out_of_range("len+offset out of range"));
7170         }
7171     }
7172
7173     /*!
7174     @brief create a JSON value from a given MessagePack vector
7175
7176     @param[in] v  MessagePack serialization
7177     @param[in] idx  byte index to start reading from @a v
7178
7179     @return deserialized JSON value
7180
7181     @throw std::invalid_argument if unsupported features from MessagePack were
7182     used in the given vector @a v or if the input is not valid MessagePack
7183     @throw std::out_of_range if the given vector ends prematurely
7184
7185     @sa https://github.com/msgpack/msgpack/blob/master/spec.md
7186     */
7187     static basic_json from_msgpack_internal(const std::vector<uint8_t>& v, size_t& idx)
7188     {
7189         // make sure reading 1 byte is safe
7190         check_length(v.size(), 1, idx);
7191
7192         // store and increment index
7193         const size_t current_idx = idx++;
7194
7195         if (v[current_idx] <= 0xbf)
7196         {
7197             if (v[current_idx] <= 0x7f) // positive fixint
7198             {
7199                 return v[current_idx];
7200             }
7201             if (v[current_idx] <= 0x8f) // fixmap
7202             {
7203                 basic_json result = value_t::object;
7204                 const size_t len = v[current_idx] & 0x0f;
7205                 for (size_t i = 0; i < len; ++i)
7206                 {
7207                     std::string key = from_msgpack_internal(v, idx);
7208                     result[key] = from_msgpack_internal(v, idx);
7209                 }
7210                 return result;
7211             }
7212             else if (v[current_idx] <= 0x9f) // fixarray
7213             {
7214                 basic_json result = value_t::array;
7215                 const size_t len = v[current_idx] & 0x0f;
7216                 for (size_t i = 0; i < len; ++i)
7217                 {
7218                     result.push_back(from_msgpack_internal(v, idx));
7219                 }
7220                 return result;
7221             }
7222             else // fixstr
7223             {
7224                 const size_t len = v[current_idx] & 0x1f;
7225                 const size_t offset = current_idx + 1;
7226                 idx += len; // skip content bytes
7227                 check_length(v.size(), len, offset);
7228                 return std::string(reinterpret_cast<const char*>(v.data()) + offset, len);
7229             }
7230         }
7231         else if (v[current_idx] >= 0xe0) // negative fixint
7232         {
7233             return static_cast<int8_t>(v[current_idx]);
7234         }
7235         else
7236         {
7237             switch (v[current_idx])
7238             {
7239                 case 0xc0: // nil
7240                 {
7241                     return value_t::null;
7242                 }
7243
7244                 case 0xc2: // false
7245                 {
7246                     return false;
7247                 }
7248
7249                 case 0xc3: // true
7250                 {
7251                     return true;
7252                 }
7253
7254                 case 0xca: // float 32
7255                 {
7256                     // copy bytes in reverse order into the double variable
7257                     float res;
7258                     for (size_t byte = 0; byte < sizeof(float); ++byte)
7259                     {
7260                         reinterpret_cast<uint8_t*>(&res)[sizeof(float) - byte - 1] = v.at(current_idx + 1 + byte);
7261                     }
7262                     idx += sizeof(float); // skip content bytes
7263                     return res;
7264                 }
7265
7266                 case 0xcb: // float 64
7267                 {
7268                     // copy bytes in reverse order into the double variable
7269                     double res;
7270                     for (size_t byte = 0; byte < sizeof(double); ++byte)
7271                     {
7272                         reinterpret_cast<uint8_t*>(&res)[sizeof(double) - byte - 1] = v.at(current_idx + 1 + byte);
7273                     }
7274                     idx += sizeof(double); // skip content bytes
7275                     return res;
7276                 }
7277
7278                 case 0xcc: // uint 8
7279                 {
7280                     idx += 1; // skip content byte
7281                     return get_from_vector<uint8_t>(v, current_idx);
7282                 }
7283
7284                 case 0xcd: // uint 16
7285                 {
7286                     idx += 2; // skip 2 content bytes
7287                     return get_from_vector<uint16_t>(v, current_idx);
7288                 }
7289
7290                 case 0xce: // uint 32
7291                 {
7292                     idx += 4; // skip 4 content bytes
7293                     return get_from_vector<uint32_t>(v, current_idx);
7294                 }
7295
7296                 case 0xcf: // uint 64
7297                 {
7298                     idx += 8; // skip 8 content bytes
7299                     return get_from_vector<uint64_t>(v, current_idx);
7300                 }
7301
7302                 case 0xd0: // int 8
7303                 {
7304                     idx += 1; // skip content byte
7305                     return get_from_vector<int8_t>(v, current_idx);
7306                 }
7307
7308                 case 0xd1: // int 16
7309                 {
7310                     idx += 2; // skip 2 content bytes
7311                     return get_from_vector<int16_t>(v, current_idx);
7312                 }
7313
7314                 case 0xd2: // int 32
7315                 {
7316                     idx += 4; // skip 4 content bytes
7317                     return get_from_vector<int32_t>(v, current_idx);
7318                 }
7319
7320                 case 0xd3: // int 64
7321                 {
7322                     idx += 8; // skip 8 content bytes
7323                     return get_from_vector<int64_t>(v, current_idx);
7324                 }
7325
7326                 case 0xd9: // str 8
7327                 {
7328                     const auto len = static_cast<size_t>(get_from_vector<uint8_t>(v, current_idx));
7329                     const size_t offset = current_idx + 2;
7330                     idx += len + 1; // skip size byte + content bytes
7331                     check_length(v.size(), len, offset);
7332                     return std::string(reinterpret_cast<const char*>(v.data()) + offset, len);
7333                 }
7334
7335                 case 0xda: // str 16
7336                 {
7337                     const auto len = static_cast<size_t>(get_from_vector<uint16_t>(v, current_idx));
7338                     const size_t offset = current_idx + 3;
7339                     idx += len + 2; // skip 2 size bytes + content bytes
7340                     check_length(v.size(), len, offset);
7341                     return std::string(reinterpret_cast<const char*>(v.data()) + offset, len);
7342                 }
7343
7344                 case 0xdb: // str 32
7345                 {
7346                     const auto len = static_cast<size_t>(get_from_vector<uint32_t>(v, current_idx));
7347                     const size_t offset = current_idx + 5;
7348                     idx += len + 4; // skip 4 size bytes + content bytes
7349                     check_length(v.size(), len, offset);
7350                     return std::string(reinterpret_cast<const char*>(v.data()) + offset, len);
7351                 }
7352
7353                 case 0xdc: // array 16
7354                 {
7355                     basic_json result = value_t::array;
7356                     const auto len = static_cast<size_t>(get_from_vector<uint16_t>(v, current_idx));
7357                     idx += 2; // skip 2 size bytes
7358                     for (size_t i = 0; i < len; ++i)
7359                     {
7360                         result.push_back(from_msgpack_internal(v, idx));
7361                     }
7362                     return result;
7363                 }
7364
7365                 case 0xdd: // array 32
7366                 {
7367                     basic_json result = value_t::array;
7368                     const auto len = static_cast<size_t>(get_from_vector<uint32_t>(v, current_idx));
7369                     idx += 4; // skip 4 size bytes
7370                     for (size_t i = 0; i < len; ++i)
7371                     {
7372                         result.push_back(from_msgpack_internal(v, idx));
7373                     }
7374                     return result;
7375                 }
7376
7377                 case 0xde: // map 16
7378                 {
7379                     basic_json result = value_t::object;
7380                     const auto len = static_cast<size_t>(get_from_vector<uint16_t>(v, current_idx));
7381                     idx += 2; // skip 2 size bytes
7382                     for (size_t i = 0; i < len; ++i)
7383                     {
7384                         std::string key = from_msgpack_internal(v, idx);
7385                         result[key] = from_msgpack_internal(v, idx);
7386                     }
7387                     return result;
7388                 }
7389
7390                 case 0xdf: // map 32
7391                 {
7392                     basic_json result = value_t::object;
7393                     const auto len = static_cast<size_t>(get_from_vector<uint32_t>(v, current_idx));
7394                     idx += 4; // skip 4 size bytes
7395                     for (size_t i = 0; i < len; ++i)
7396                     {
7397                         std::string key = from_msgpack_internal(v, idx);
7398                         result[key] = from_msgpack_internal(v, idx);
7399                     }
7400                     return result;
7401                 }
7402
7403                 default:
7404                 {
7405                     JSON_THROW(std::invalid_argument("error parsing a msgpack @ " + std::to_string(current_idx) + ": " + std::to_string(static_cast<int>(v[current_idx]))));
7406                 }
7407             }
7408         }
7409     }
7410
7411     /*!
7412     @brief create a JSON value from a given CBOR vector
7413
7414     @param[in] v  CBOR serialization
7415     @param[in] idx  byte index to start reading from @a v
7416
7417     @return deserialized JSON value
7418
7419     @throw std::invalid_argument if unsupported features from CBOR were used in
7420     the given vector @a v or if the input is not valid CBOR
7421     @throw std::out_of_range if the given vector ends prematurely
7422
7423     @sa https://tools.ietf.org/html/rfc7049
7424     */
7425     static basic_json from_cbor_internal(const std::vector<uint8_t>& v, size_t& idx)
7426     {
7427         // store and increment index
7428         const size_t current_idx = idx++;
7429
7430         switch (v.at(current_idx))
7431         {
7432             // Integer 0x00..0x17 (0..23)
7433             case 0x00:
7434             case 0x01:
7435             case 0x02:
7436             case 0x03:
7437             case 0x04:
7438             case 0x05:
7439             case 0x06:
7440             case 0x07:
7441             case 0x08:
7442             case 0x09:
7443             case 0x0a:
7444             case 0x0b:
7445             case 0x0c:
7446             case 0x0d:
7447             case 0x0e:
7448             case 0x0f:
7449             case 0x10:
7450             case 0x11:
7451             case 0x12:
7452             case 0x13:
7453             case 0x14:
7454             case 0x15:
7455             case 0x16:
7456             case 0x17:
7457             {
7458                 return v[current_idx];
7459             }
7460
7461             case 0x18: // Unsigned integer (one-byte uint8_t follows)
7462             {
7463                 idx += 1; // skip content byte
7464                 return get_from_vector<uint8_t>(v, current_idx);
7465             }
7466
7467             case 0x19: // Unsigned integer (two-byte uint16_t follows)
7468             {
7469                 idx += 2; // skip 2 content bytes
7470                 return get_from_vector<uint16_t>(v, current_idx);
7471             }
7472
7473             case 0x1a: // Unsigned integer (four-byte uint32_t follows)
7474             {
7475                 idx += 4; // skip 4 content bytes
7476                 return get_from_vector<uint32_t>(v, current_idx);
7477             }
7478
7479             case 0x1b: // Unsigned integer (eight-byte uint64_t follows)
7480             {
7481                 idx += 8; // skip 8 content bytes
7482                 return get_from_vector<uint64_t>(v, current_idx);
7483             }
7484
7485             // Negative integer -1-0x00..-1-0x17 (-1..-24)
7486             case 0x20:
7487             case 0x21:
7488             case 0x22:
7489             case 0x23:
7490             case 0x24:
7491             case 0x25:
7492             case 0x26:
7493             case 0x27:
7494             case 0x28:
7495             case 0x29:
7496             case 0x2a:
7497             case 0x2b:
7498             case 0x2c:
7499             case 0x2d:
7500             case 0x2e:
7501             case 0x2f:
7502             case 0x30:
7503             case 0x31:
7504             case 0x32:
7505             case 0x33:
7506             case 0x34:
7507             case 0x35:
7508             case 0x36:
7509             case 0x37:
7510             {
7511                 return static_cast<int8_t>(0x20 - 1 - v[current_idx]);
7512             }
7513
7514             case 0x38: // Negative integer (one-byte uint8_t follows)
7515             {
7516                 idx += 1; // skip content byte
7517                 // must be uint8_t !
7518                 return static_cast<number_integer_t>(-1) - get_from_vector<uint8_t>(v, current_idx);
7519             }
7520
7521             case 0x39: // Negative integer -1-n (two-byte uint16_t follows)
7522             {
7523                 idx += 2; // skip 2 content bytes
7524                 return static_cast<number_integer_t>(-1) - get_from_vector<uint16_t>(v, current_idx);
7525             }
7526
7527             case 0x3a: // Negative integer -1-n (four-byte uint32_t follows)
7528             {
7529                 idx += 4; // skip 4 content bytes
7530                 return static_cast<number_integer_t>(-1) - get_from_vector<uint32_t>(v, current_idx);
7531             }
7532
7533             case 0x3b: // Negative integer -1-n (eight-byte uint64_t follows)
7534             {
7535                 idx += 8; // skip 8 content bytes
7536                 return static_cast<number_integer_t>(-1) - static_cast<number_integer_t>(get_from_vector<uint64_t>(v, current_idx));
7537             }
7538
7539             // UTF-8 string (0x00..0x17 bytes follow)
7540             case 0x60:
7541             case 0x61:
7542             case 0x62:
7543             case 0x63:
7544             case 0x64:
7545             case 0x65:
7546             case 0x66:
7547             case 0x67:
7548             case 0x68:
7549             case 0x69:
7550             case 0x6a:
7551             case 0x6b:
7552             case 0x6c:
7553             case 0x6d:
7554             case 0x6e:
7555             case 0x6f:
7556             case 0x70:
7557             case 0x71:
7558             case 0x72:
7559             case 0x73:
7560             case 0x74:
7561             case 0x75:
7562             case 0x76:
7563             case 0x77:
7564             {
7565                 const auto len = static_cast<size_t>(v[current_idx] - 0x60);
7566                 const size_t offset = current_idx + 1;
7567                 idx += len; // skip content bytes
7568                 check_length(v.size(), len, offset);
7569                 return std::string(reinterpret_cast<const char*>(v.data()) + offset, len);
7570             }
7571
7572             case 0x78: // UTF-8 string (one-byte uint8_t for n follows)
7573             {
7574                 const auto len = static_cast<size_t>(get_from_vector<uint8_t>(v, current_idx));
7575                 const size_t offset = current_idx + 2;
7576                 idx += len + 1; // skip size byte + content bytes
7577                 check_length(v.size(), len, offset);
7578                 return std::string(reinterpret_cast<const char*>(v.data()) + offset, len);
7579             }
7580
7581             case 0x79: // UTF-8 string (two-byte uint16_t for n follow)
7582             {
7583                 const auto len = static_cast<size_t>(get_from_vector<uint16_t>(v, current_idx));
7584                 const size_t offset = current_idx + 3;
7585                 idx += len + 2; // skip 2 size bytes + content bytes
7586                 check_length(v.size(), len, offset);
7587                 return std::string(reinterpret_cast<const char*>(v.data()) + offset, len);
7588             }
7589
7590             case 0x7a: // UTF-8 string (four-byte uint32_t for n follow)
7591             {
7592                 const auto len = static_cast<size_t>(get_from_vector<uint32_t>(v, current_idx));
7593                 const size_t offset = current_idx + 5;
7594                 idx += len + 4; // skip 4 size bytes + content bytes
7595                 check_length(v.size(), len, offset);
7596                 return std::string(reinterpret_cast<const char*>(v.data()) + offset, len);
7597             }
7598
7599             case 0x7b: // UTF-8 string (eight-byte uint64_t for n follow)
7600             {
7601                 const auto len = static_cast<size_t>(get_from_vector<uint64_t>(v, current_idx));
7602                 const size_t offset = current_idx + 9;
7603                 idx += len + 8; // skip 8 size bytes + content bytes
7604                 check_length(v.size(), len, offset);
7605                 return std::string(reinterpret_cast<const char*>(v.data()) + offset, len);
7606             }
7607
7608             case 0x7f: // UTF-8 string (indefinite length)
7609             {
7610                 std::string result;
7611                 while (v.at(idx) != 0xff)
7612                 {
7613                     string_t s = from_cbor_internal(v, idx);
7614                     result += s;
7615                 }
7616                 // skip break byte (0xFF)
7617                 idx += 1;
7618                 return result;
7619             }
7620
7621             // array (0x00..0x17 data items follow)
7622             case 0x80:
7623             case 0x81:
7624             case 0x82:
7625             case 0x83:
7626             case 0x84:
7627             case 0x85:
7628             case 0x86:
7629             case 0x87:
7630             case 0x88:
7631             case 0x89:
7632             case 0x8a:
7633             case 0x8b:
7634             case 0x8c:
7635             case 0x8d:
7636             case 0x8e:
7637             case 0x8f:
7638             case 0x90:
7639             case 0x91:
7640             case 0x92:
7641             case 0x93:
7642             case 0x94:
7643             case 0x95:
7644             case 0x96:
7645             case 0x97:
7646             {
7647                 basic_json result = value_t::array;
7648                 const auto len = static_cast<size_t>(v[current_idx] - 0x80);
7649                 for (size_t i = 0; i < len; ++i)
7650                 {
7651                     result.push_back(from_cbor_internal(v, idx));
7652                 }
7653                 return result;
7654             }
7655
7656             case 0x98: // array (one-byte uint8_t for n follows)
7657             {
7658                 basic_json result = value_t::array;
7659                 const auto len = static_cast<size_t>(get_from_vector<uint8_t>(v, current_idx));
7660                 idx += 1; // skip 1 size byte
7661                 for (size_t i = 0; i < len; ++i)
7662                 {
7663                     result.push_back(from_cbor_internal(v, idx));
7664                 }
7665                 return result;
7666             }
7667
7668             case 0x99: // array (two-byte uint16_t for n follow)
7669             {
7670                 basic_json result = value_t::array;
7671                 const auto len = static_cast<size_t>(get_from_vector<uint16_t>(v, current_idx));
7672                 idx += 2; // skip 4 size bytes
7673                 for (size_t i = 0; i < len; ++i)
7674                 {
7675                     result.push_back(from_cbor_internal(v, idx));
7676                 }
7677                 return result;
7678             }
7679
7680             case 0x9a: // array (four-byte uint32_t for n follow)
7681             {
7682                 basic_json result = value_t::array;
7683                 const auto len = static_cast<size_t>(get_from_vector<uint32_t>(v, current_idx));
7684                 idx += 4; // skip 4 size bytes
7685                 for (size_t i = 0; i < len; ++i)
7686                 {
7687                     result.push_back(from_cbor_internal(v, idx));
7688                 }
7689                 return result;
7690             }
7691
7692             case 0x9b: // array (eight-byte uint64_t for n follow)
7693             {
7694                 basic_json result = value_t::array;
7695                 const auto len = static_cast<size_t>(get_from_vector<uint64_t>(v, current_idx));
7696                 idx += 8; // skip 8 size bytes
7697                 for (size_t i = 0; i < len; ++i)
7698                 {
7699                     result.push_back(from_cbor_internal(v, idx));
7700                 }
7701                 return result;
7702             }
7703
7704             case 0x9f: // array (indefinite length)
7705             {
7706                 basic_json result = value_t::array;
7707                 while (v.at(idx) != 0xff)
7708                 {
7709                     result.push_back(from_cbor_internal(v, idx));
7710                 }
7711                 // skip break byte (0xFF)
7712                 idx += 1;
7713                 return result;
7714             }
7715
7716             // map (0x00..0x17 pairs of data items follow)
7717             case 0xa0:
7718             case 0xa1:
7719             case 0xa2:
7720             case 0xa3:
7721             case 0xa4:
7722             case 0xa5:
7723             case 0xa6:
7724             case 0xa7:
7725             case 0xa8:
7726             case 0xa9:
7727             case 0xaa:
7728             case 0xab:
7729             case 0xac:
7730             case 0xad:
7731             case 0xae:
7732             case 0xaf:
7733             case 0xb0:
7734             case 0xb1:
7735             case 0xb2:
7736             case 0xb3:
7737             case 0xb4:
7738             case 0xb5:
7739             case 0xb6:
7740             case 0xb7:
7741             {
7742                 basic_json result = value_t::object;
7743                 const auto len = static_cast<size_t>(v[current_idx] - 0xa0);
7744                 for (size_t i = 0; i < len; ++i)
7745                 {
7746                     std::string key = from_cbor_internal(v, idx);
7747                     result[key] = from_cbor_internal(v, idx);
7748                 }
7749                 return result;
7750             }
7751
7752             case 0xb8: // map (one-byte uint8_t for n follows)
7753             {
7754                 basic_json result = value_t::object;
7755                 const auto len = static_cast<size_t>(get_from_vector<uint8_t>(v, current_idx));
7756                 idx += 1; // skip 1 size byte
7757                 for (size_t i = 0; i < len; ++i)
7758                 {
7759                     std::string key = from_cbor_internal(v, idx);
7760                     result[key] = from_cbor_internal(v, idx);
7761                 }
7762                 return result;
7763             }
7764
7765             case 0xb9: // map (two-byte uint16_t for n follow)
7766             {
7767                 basic_json result = value_t::object;
7768                 const auto len = static_cast<size_t>(get_from_vector<uint16_t>(v, current_idx));
7769                 idx += 2; // skip 2 size bytes
7770                 for (size_t i = 0; i < len; ++i)
7771                 {
7772                     std::string key = from_cbor_internal(v, idx);
7773                     result[key] = from_cbor_internal(v, idx);
7774                 }
7775                 return result;
7776             }
7777
7778             case 0xba: // map (four-byte uint32_t for n follow)
7779             {
7780                 basic_json result = value_t::object;
7781                 const auto len = static_cast<size_t>(get_from_vector<uint32_t>(v, current_idx));
7782                 idx += 4; // skip 4 size bytes
7783                 for (size_t i = 0; i < len; ++i)
7784                 {
7785                     std::string key = from_cbor_internal(v, idx);
7786                     result[key] = from_cbor_internal(v, idx);
7787                 }
7788                 return result;
7789             }
7790
7791             case 0xbb: // map (eight-byte uint64_t for n follow)
7792             {
7793                 basic_json result = value_t::object;
7794                 const auto len = static_cast<size_t>(get_from_vector<uint64_t>(v, current_idx));
7795                 idx += 8; // skip 8 size bytes
7796                 for (size_t i = 0; i < len; ++i)
7797                 {
7798                     std::string key = from_cbor_internal(v, idx);
7799                     result[key] = from_cbor_internal(v, idx);
7800                 }
7801                 return result;
7802             }
7803
7804             case 0xbf: // map (indefinite length)
7805             {
7806                 basic_json result = value_t::object;
7807                 while (v.at(idx) != 0xff)
7808                 {
7809                     std::string key = from_cbor_internal(v, idx);
7810                     result[key] = from_cbor_internal(v, idx);
7811                 }
7812                 // skip break byte (0xFF)
7813                 idx += 1;
7814                 return result;
7815             }
7816
7817             case 0xf4: // false
7818             {
7819                 return false;
7820             }
7821
7822             case 0xf5: // true
7823             {
7824                 return true;
7825             }
7826
7827             case 0xf6: // null
7828             {
7829                 return value_t::null;
7830             }
7831
7832             case 0xf9: // Half-Precision Float (two-byte IEEE 754)
7833             {
7834                 idx += 2; // skip two content bytes
7835
7836                 // code from RFC 7049, Appendix D, Figure 3:
7837                 // As half-precision floating-point numbers were only added to
7838                 // IEEE 754 in 2008, today's programming platforms often still
7839                 // only have limited support for them. It is very easy to
7840                 // include at least decoding support for them even without such
7841                 // support. An example of a small decoder for half-precision
7842                 // floating-point numbers in the C language is shown in Fig. 3.
7843                 const int half = (v.at(current_idx + 1) << 8) + v.at(current_idx + 2);
7844                 const int exp = (half >> 10) & 0x1f;
7845                 const int mant = half & 0x3ff;
7846                 double val;
7847                 if (exp == 0)
7848                 {
7849                     val = std::ldexp(mant, -24);
7850                 }
7851                 else if (exp != 31)
7852                 {
7853                     val = std::ldexp(mant + 1024, exp - 25);
7854                 }
7855                 else
7856                 {
7857                     val = mant == 0
7858                           ? std::numeric_limits<double>::infinity()
7859                           : std::numeric_limits<double>::quiet_NaN();
7860                 }
7861                 return (half & 0x8000) != 0 ? -val : val;
7862             }
7863
7864             case 0xfa: // Single-Precision Float (four-byte IEEE 754)
7865             {
7866                 // copy bytes in reverse order into the float variable
7867                 float res;
7868                 for (size_t byte = 0; byte < sizeof(float); ++byte)
7869                 {
7870                     reinterpret_cast<uint8_t*>(&res)[sizeof(float) - byte - 1] = v.at(current_idx + 1 + byte);
7871                 }
7872                 idx += sizeof(float); // skip content bytes
7873                 return res;
7874             }
7875
7876             case 0xfb: // Double-Precision Float (eight-byte IEEE 754)
7877             {
7878                 // copy bytes in reverse order into the double variable
7879                 double res;
7880                 for (size_t byte = 0; byte < sizeof(double); ++byte)
7881                 {
7882                     reinterpret_cast<uint8_t*>(&res)[sizeof(double) - byte - 1] = v.at(current_idx + 1 + byte);
7883                 }
7884                 idx += sizeof(double); // skip content bytes
7885                 return res;
7886             }
7887
7888             default: // anything else (0xFF is handled inside the other types)
7889             {
7890                 JSON_THROW(std::invalid_argument("error parsing a CBOR @ " + std::to_string(current_idx) + ": " + std::to_string(static_cast<int>(v[current_idx]))));
7891             }
7892         }
7893     }
7894
7895   public:
7896     /*!
7897     @brief create a MessagePack serialization of a given JSON value
7898
7899     Serializes a given JSON value @a j to a byte vector using the MessagePack
7900     serialization format. MessagePack is a binary serialization format which
7901     aims to be more compact than JSON itself, yet more efficient to parse.
7902
7903     @param[in] j  JSON value to serialize
7904     @return MessagePack serialization as byte vector
7905
7906     @complexity Linear in the size of the JSON value @a j.
7907
7908     @liveexample{The example shows the serialization of a JSON value to a byte
7909     vector in MessagePack format.,to_msgpack}
7910
7911     @sa http://msgpack.org
7912     @sa @ref from_msgpack(const std::vector<uint8_t>&, const size_t) for the
7913         analogous deserialization
7914     @sa @ref to_cbor(const basic_json& for the related CBOR format
7915
7916     @since version 2.0.9
7917     */
7918     static std::vector<uint8_t> to_msgpack(const basic_json& j)
7919     {
7920         std::vector<uint8_t> result;
7921         to_msgpack_internal(j, result);
7922         return result;
7923     }
7924
7925     /*!
7926     @brief create a JSON value from a byte vector in MessagePack format
7927
7928     Deserializes a given byte vector @a v to a JSON value using the MessagePack
7929     serialization format.
7930
7931     @param[in] v  a byte vector in MessagePack format
7932     @param[in] start_index the index to start reading from @a v (0 by default)
7933     @return deserialized JSON value
7934
7935     @throw std::invalid_argument if unsupported features from MessagePack were
7936     used in the given vector @a v or if the input is not valid MessagePack
7937     @throw std::out_of_range if the given vector ends prematurely
7938
7939     @complexity Linear in the size of the byte vector @a v.
7940
7941     @liveexample{The example shows the deserialization of a byte vector in
7942     MessagePack format to a JSON value.,from_msgpack}
7943
7944     @sa http://msgpack.org
7945     @sa @ref to_msgpack(const basic_json&) for the analogous serialization
7946     @sa @ref from_cbor(const std::vector<uint8_t>&, const size_t) for the
7947         related CBOR format
7948
7949     @since version 2.0.9, parameter @a start_index since 2.1.1
7950     */
7951     static basic_json from_msgpack(const std::vector<uint8_t>& v,
7952                                    const size_t start_index = 0)
7953     {
7954         size_t i = start_index;
7955         return from_msgpack_internal(v, i);
7956     }
7957
7958     /*!
7959     @brief create a MessagePack serialization of a given JSON value
7960
7961     Serializes a given JSON value @a j to a byte vector using the CBOR (Concise
7962     Binary Object Representation) serialization format. CBOR is a binary
7963     serialization format which aims to be more compact than JSON itself, yet
7964     more efficient to parse.
7965
7966     @param[in] j  JSON value to serialize
7967     @return MessagePack serialization as byte vector
7968
7969     @complexity Linear in the size of the JSON value @a j.
7970
7971     @liveexample{The example shows the serialization of a JSON value to a byte
7972     vector in CBOR format.,to_cbor}
7973
7974     @sa http://cbor.io
7975     @sa @ref from_cbor(const std::vector<uint8_t>&, const size_t) for the
7976         analogous deserialization
7977     @sa @ref to_msgpack(const basic_json& for the related MessagePack format
7978
7979     @since version 2.0.9
7980     */
7981     static std::vector<uint8_t> to_cbor(const basic_json& j)
7982     {
7983         std::vector<uint8_t> result;
7984         to_cbor_internal(j, result);
7985         return result;
7986     }
7987
7988     /*!
7989     @brief create a JSON value from a byte vector in CBOR format
7990
7991     Deserializes a given byte vector @a v to a JSON value using the CBOR
7992     (Concise Binary Object Representation) serialization format.
7993
7994     @param[in] v  a byte vector in CBOR format
7995     @param[in] start_index the index to start reading from @a v (0 by default)
7996     @return deserialized JSON value
7997
7998     @throw std::invalid_argument if unsupported features from CBOR were used in
7999     the given vector @a v or if the input is not valid MessagePack
8000     @throw std::out_of_range if the given vector ends prematurely
8001
8002     @complexity Linear in the size of the byte vector @a v.
8003
8004     @liveexample{The example shows the deserialization of a byte vector in CBOR
8005     format to a JSON value.,from_cbor}
8006
8007     @sa http://cbor.io
8008     @sa @ref to_cbor(const basic_json&) for the analogous serialization
8009     @sa @ref from_msgpack(const std::vector<uint8_t>&, const size_t) for the
8010         related MessagePack format
8011
8012     @since version 2.0.9, parameter @a start_index since 2.1.1
8013     */
8014     static basic_json from_cbor(const std::vector<uint8_t>& v,
8015                                 const size_t start_index = 0)
8016     {
8017         size_t i = start_index;
8018         return from_cbor_internal(v, i);
8019     }
8020
8021     /// @}
8022
8023     ///////////////////////////
8024     // convenience functions //
8025     ///////////////////////////
8026
8027     /*!
8028     @brief return the type as string
8029
8030     Returns the type name as string to be used in error messages - usually to
8031     indicate that a function was called on a wrong JSON type.
8032
8033     @return basically a string representation of a the @a m_type member
8034
8035     @complexity Constant.
8036
8037     @liveexample{The following code exemplifies `type_name()` for all JSON
8038     types.,type_name}
8039
8040     @since version 1.0.0, public since 2.1.0
8041     */
8042     std::string type_name() const
8043     {
8044         {
8045             switch (m_type)
8046             {
8047                 case value_t::null:
8048                     return "null";
8049                 case value_t::object:
8050                     return "object";
8051                 case value_t::array:
8052                     return "array";
8053                 case value_t::string:
8054                     return "string";
8055                 case value_t::boolean:
8056                     return "boolean";
8057                 case value_t::discarded:
8058                     return "discarded";
8059                 default:
8060                     return "number";
8061             }
8062         }
8063     }
8064
8065   private:
8066     /*!
8067     @brief calculates the extra space to escape a JSON string
8068
8069     @param[in] s  the string to escape
8070     @return the number of characters required to escape string @a s
8071
8072     @complexity Linear in the length of string @a s.
8073     */
8074     static std::size_t extra_space(const string_t& s) noexcept
8075     {
8076         return std::accumulate(s.begin(), s.end(), size_t{},
8077                                [](size_t res, typename string_t::value_type c)
8078         {
8079             switch (c)
8080             {
8081                 case '"':
8082                 case '\\':
8083                 case '\b':
8084                 case '\f':
8085                 case '\n':
8086                 case '\r':
8087                 case '\t':
8088                 {
8089                     // from c (1 byte) to \x (2 bytes)
8090                     return res + 1;
8091                 }
8092
8093                 default:
8094                 {
8095                     if (c >= 0x00 and c <= 0x1f)
8096                     {
8097                         // from c (1 byte) to \uxxxx (6 bytes)
8098                         return res + 5;
8099                     }
8100
8101                     return res;
8102                 }
8103             }
8104         });
8105     }
8106
8107     /*!
8108     @brief escape a string
8109
8110     Escape a string by replacing certain special characters by a sequence of
8111     an escape character (backslash) and another character and other control
8112     characters by a sequence of "\u" followed by a four-digit hex
8113     representation.
8114
8115     @param[in] s  the string to escape
8116     @return  the escaped string
8117
8118     @complexity Linear in the length of string @a s.
8119     */
8120     static string_t escape_string(const string_t& s)
8121     {
8122         const auto space = extra_space(s);
8123         if (space == 0)
8124         {
8125             return s;
8126         }
8127
8128         // create a result string of necessary size
8129         string_t result(s.size() + space, '\\');
8130         std::size_t pos = 0;
8131
8132         for (const auto& c : s)
8133         {
8134             switch (c)
8135             {
8136                 // quotation mark (0x22)
8137                 case '"':
8138                 {
8139                     result[pos + 1] = '"';
8140                     pos += 2;
8141                     break;
8142                 }
8143
8144                 // reverse solidus (0x5c)
8145                 case '\\':
8146                 {
8147                     // nothing to change
8148                     pos += 2;
8149                     break;
8150                 }
8151
8152                 // backspace (0x08)
8153                 case '\b':
8154                 {
8155                     result[pos + 1] = 'b';
8156                     pos += 2;
8157                     break;
8158                 }
8159
8160                 // formfeed (0x0c)
8161                 case '\f':
8162                 {
8163                     result[pos + 1] = 'f';
8164                     pos += 2;
8165                     break;
8166                 }
8167
8168                 // newline (0x0a)
8169                 case '\n':
8170                 {
8171                     result[pos + 1] = 'n';
8172                     pos += 2;
8173                     break;
8174                 }
8175
8176                 // carriage return (0x0d)
8177                 case '\r':
8178                 {
8179                     result[pos + 1] = 'r';
8180                     pos += 2;
8181                     break;
8182                 }
8183
8184                 // horizontal tab (0x09)
8185                 case '\t':
8186                 {
8187                     result[pos + 1] = 't';
8188                     pos += 2;
8189                     break;
8190                 }
8191
8192                 default:
8193                 {
8194                     if (c >= 0x00 and c <= 0x1f)
8195                     {
8196                         // convert a number 0..15 to its hex representation
8197                         // (0..f)
8198                         static const char hexify[16] =
8199                         {
8200                             '0', '1', '2', '3', '4', '5', '6', '7',
8201                             '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'
8202                         };
8203
8204                         // print character c as \uxxxx
8205                         for (const char m :
8206                     { 'u', '0', '0', hexify[c >> 4], hexify[c & 0x0f]
8207                         })
8208                         {
8209                             result[++pos] = m;
8210                         }
8211
8212                         ++pos;
8213                     }
8214                     else
8215                     {
8216                         // all other characters are added as-is
8217                         result[pos++] = c;
8218                     }
8219                     break;
8220                 }
8221             }
8222         }
8223
8224         return result;
8225     }
8226
8227
8228     /*!
8229     @brief locale-independent serialization for built-in arithmetic types
8230     */
8231     struct numtostr
8232     {
8233       public:
8234         template<typename NumberType>
8235         numtostr(NumberType value)
8236         {
8237             x_write(value, std::is_integral<NumberType>());
8238         }
8239
8240         const char* c_str() const
8241         {
8242             return m_buf.data();
8243         }
8244
8245       private:
8246         /// a (hopefully) large enough character buffer
8247         std::array < char, 64 > m_buf{{}};
8248
8249         template<typename NumberType>
8250         void x_write(NumberType x, /*is_integral=*/std::true_type)
8251         {
8252             // special case for "0"
8253             if (x == 0)
8254             {
8255                 m_buf[0] = '0';
8256                 return;
8257             }
8258
8259             const bool is_negative = x < 0;
8260             size_t i = 0;
8261
8262             // spare 1 byte for '\0'
8263             while (x != 0 and i < m_buf.size() - 1)
8264             {
8265                 const auto digit = std::labs(static_cast<long>(x % 10));
8266                 m_buf[i++] = static_cast<char>('0' + digit);
8267                 x /= 10;
8268             }
8269
8270             // make sure the number has been processed completely
8271             assert(x == 0);
8272
8273             if (is_negative)
8274             {
8275                 // make sure there is capacity for the '-'
8276                 assert(i < m_buf.size() - 2);
8277                 m_buf[i++] = '-';
8278             }
8279
8280             std::reverse(m_buf.begin(), m_buf.begin() + i);
8281         }
8282
8283         template<typename NumberType>
8284         void x_write(NumberType x, /*is_integral=*/std::false_type)
8285         {
8286             // special case for 0.0 and -0.0
8287             if (x == 0)
8288             {
8289                 size_t i = 0;
8290                 if (std::signbit(x))
8291                 {
8292                     m_buf[i++] = '-';
8293                 }
8294                 m_buf[i++] = '0';
8295                 m_buf[i++] = '.';
8296                 m_buf[i] = '0';
8297                 return;
8298             }
8299
8300             // get number of digits for a text -> float -> text round-trip
8301             static constexpr auto d = std::numeric_limits<NumberType>::digits10;
8302
8303             // the actual conversion
8304             const auto written_bytes = snprintf(m_buf.data(), m_buf.size(), "%.*g", d, (double)x);
8305
8306             // negative value indicates an error
8307             assert(written_bytes > 0);
8308             // check if buffer was large enough
8309             assert(static_cast<size_t>(written_bytes) < m_buf.size());
8310
8311             // read information from locale
8312             const auto loc = localeconv();
8313             assert(loc != nullptr);
8314             const char thousands_sep = !loc->thousands_sep ? '\0'
8315                                        : loc->thousands_sep[0];
8316
8317             const char decimal_point = !loc->decimal_point ? '\0'
8318                                        : loc->decimal_point[0];
8319
8320             // erase thousands separator
8321             if (thousands_sep != '\0')
8322             {
8323                 const auto end = std::remove(m_buf.begin(), m_buf.begin() + written_bytes, thousands_sep);
8324                 std::fill(end, m_buf.end(), '\0');
8325             }
8326
8327             // convert decimal point to '.'
8328             if (decimal_point != '\0' and decimal_point != '.')
8329             {
8330                 for (auto& c : m_buf)
8331                 {
8332                     if (c == decimal_point)
8333                     {
8334                         c = '.';
8335                         break;
8336                     }
8337                 }
8338             }
8339
8340             // determine if need to append ".0"
8341             size_t i = 0;
8342             bool value_is_int_like = true;
8343             for (i = 0; i < m_buf.size(); ++i)
8344             {
8345                 // break when end of number is reached
8346                 if (m_buf[i] == '\0')
8347                 {
8348                     break;
8349                 }
8350
8351                 // check if we find non-int character
8352                 value_is_int_like = value_is_int_like and m_buf[i] != '.' and
8353                                     m_buf[i] != 'e' and m_buf[i] != 'E';
8354             }
8355
8356             if (value_is_int_like)
8357             {
8358                 // there must be 2 bytes left for ".0"
8359                 assert((i + 2) < m_buf.size());
8360                 // we write to the end of the number
8361                 assert(m_buf[i] == '\0');
8362                 assert(m_buf[i - 1] != '\0');
8363
8364                 // add ".0"
8365                 m_buf[i] = '.';
8366                 m_buf[i + 1] = '0';
8367
8368                 // the resulting string is properly terminated
8369                 assert(m_buf[i + 2] == '\0');
8370             }
8371         }
8372     };
8373
8374
8375     /*!
8376     @brief internal implementation of the serialization function
8377
8378     This function is called by the public member function dump and organizes
8379     the serialization internally. The indentation level is propagated as
8380     additional parameter. In case of arrays and objects, the function is
8381     called recursively. Note that
8382
8383     - strings and object keys are escaped using `escape_string()`
8384     - integer numbers are converted implicitly via `operator<<`
8385     - floating-point numbers are converted to a string using `"%g"` format
8386
8387     @param[out] o              stream to write to
8388     @param[in] pretty_print    whether the output shall be pretty-printed
8389     @param[in] indent_step     the indent level
8390     @param[in] current_indent  the current indent level (only used internally)
8391     */
8392     void dump(std::ostream& o,
8393               const bool pretty_print,
8394               const unsigned int indent_step,
8395               const unsigned int current_indent = 0) const
8396     {
8397         // variable to hold indentation for recursive calls
8398         unsigned int new_indent = current_indent;
8399
8400         switch (m_type)
8401         {
8402             case value_t::object:
8403             {
8404                 if (m_value.object->empty())
8405                 {
8406                     o << "{}";
8407                     return;
8408                 }
8409
8410                 o << "{";
8411
8412                 // increase indentation
8413                 if (pretty_print)
8414                 {
8415                     new_indent += indent_step;
8416                     o << "\n";
8417                 }
8418
8419                 for (auto i = m_value.object->cbegin(); i != m_value.object->cend(); ++i)
8420                 {
8421                     if (i != m_value.object->cbegin())
8422                     {
8423                         o << (pretty_print ? ",\n" : ",");
8424                     }
8425                     o << string_t(new_indent, ' ') << "\""
8426                       << escape_string(i->first) << "\":"
8427                       << (pretty_print ? " " : "");
8428                     i->second.dump(o, pretty_print, indent_step, new_indent);
8429                 }
8430
8431                 // decrease indentation
8432                 if (pretty_print)
8433                 {
8434                     new_indent -= indent_step;
8435                     o << "\n";
8436                 }
8437
8438                 o << string_t(new_indent, ' ') + "}";
8439                 return;
8440             }
8441
8442             case value_t::array:
8443             {
8444                 if (m_value.array->empty())
8445                 {
8446                     o << "[]";
8447                     return;
8448                 }
8449
8450                 o << "[";
8451
8452                 // increase indentation
8453                 if (pretty_print)
8454                 {
8455                     new_indent += indent_step;
8456                     o << "\n";
8457                 }
8458
8459                 for (auto i = m_value.array->cbegin(); i != m_value.array->cend(); ++i)
8460                 {
8461                     if (i != m_value.array->cbegin())
8462                     {
8463                         o << (pretty_print ? ",\n" : ",");
8464                     }
8465                     o << string_t(new_indent, ' ');
8466                     i->dump(o, pretty_print, indent_step, new_indent);
8467                 }
8468
8469                 // decrease indentation
8470                 if (pretty_print)
8471                 {
8472                     new_indent -= indent_step;
8473                     o << "\n";
8474                 }
8475
8476                 o << string_t(new_indent, ' ') << "]";
8477                 return;
8478             }
8479
8480             case value_t::string:
8481             {
8482                 o << string_t("\"") << escape_string(*m_value.string) << "\"";
8483                 return;
8484             }
8485
8486             case value_t::boolean:
8487             {
8488                 o << (m_value.boolean ? "true" : "false");
8489                 return;
8490             }
8491
8492             case value_t::number_integer:
8493             {
8494                 o << numtostr(m_value.number_integer).c_str();
8495                 return;
8496             }
8497
8498             case value_t::number_unsigned:
8499             {
8500                 o << numtostr(m_value.number_unsigned).c_str();
8501                 return;
8502             }
8503
8504             case value_t::number_float:
8505             {
8506                 o << numtostr(m_value.number_float).c_str();
8507                 return;
8508             }
8509
8510             case value_t::discarded:
8511             {
8512                 o << "<discarded>";
8513                 return;
8514             }
8515
8516             case value_t::null:
8517             {
8518                 o << "null";
8519                 return;
8520             }
8521         }
8522     }
8523
8524   private:
8525     //////////////////////
8526     // member variables //
8527     //////////////////////
8528
8529     /// the type of the current element
8530     value_t m_type = value_t::null;
8531
8532     /// the value of the current element
8533     json_value m_value = {};
8534
8535
8536   private:
8537     ///////////////
8538     // iterators //
8539     ///////////////
8540
8541     /*!
8542     @brief an iterator for primitive JSON types
8543
8544     This class models an iterator for primitive JSON types (boolean, number,
8545     string). It's only purpose is to allow the iterator/const_iterator classes
8546     to "iterate" over primitive values. Internally, the iterator is modeled by
8547     a `difference_type` variable. Value begin_value (`0`) models the begin,
8548     end_value (`1`) models past the end.
8549     */
8550     class primitive_iterator_t
8551     {
8552       public:
8553
8554         difference_type get_value() const noexcept
8555         {
8556             return m_it;
8557         }
8558         /// set iterator to a defined beginning
8559         void set_begin() noexcept
8560         {
8561             m_it = begin_value;
8562         }
8563
8564         /// set iterator to a defined past the end
8565         void set_end() noexcept
8566         {
8567             m_it = end_value;
8568         }
8569
8570         /// return whether the iterator can be dereferenced
8571         constexpr bool is_begin() const noexcept
8572         {
8573             return (m_it == begin_value);
8574         }
8575
8576         /// return whether the iterator is at end
8577         constexpr bool is_end() const noexcept
8578         {
8579             return (m_it == end_value);
8580         }
8581
8582         friend constexpr bool operator==(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
8583         {
8584             return lhs.m_it == rhs.m_it;
8585         }
8586
8587         friend constexpr bool operator!=(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
8588         {
8589             return !(lhs == rhs);
8590         }
8591
8592         friend constexpr bool operator<(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
8593         {
8594             return lhs.m_it < rhs.m_it;
8595         }
8596
8597         friend constexpr bool operator<=(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
8598         {
8599             return lhs.m_it <= rhs.m_it;
8600         }
8601
8602         friend constexpr bool operator>(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
8603         {
8604             return lhs.m_it > rhs.m_it;
8605         }
8606
8607         friend constexpr bool operator>=(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
8608         {
8609             return lhs.m_it >= rhs.m_it;
8610         }
8611
8612         primitive_iterator_t operator+(difference_type i)
8613         {
8614             auto result = *this;
8615             result += i;
8616             return result;
8617         }
8618
8619         friend constexpr difference_type operator-(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
8620         {
8621             return lhs.m_it - rhs.m_it;
8622         }
8623
8624         friend std::ostream& operator<<(std::ostream& os, primitive_iterator_t it)
8625         {
8626             return os << it.m_it;
8627         }
8628
8629         primitive_iterator_t& operator++()
8630         {
8631             ++m_it;
8632             return *this;
8633         }
8634
8635         primitive_iterator_t operator++(int)
8636         {
8637             auto result = *this;
8638             m_it++;
8639             return result;
8640         }
8641
8642         primitive_iterator_t& operator--()
8643         {
8644             --m_it;
8645             return *this;
8646         }
8647
8648         primitive_iterator_t operator--(int)
8649         {
8650             auto result = *this;
8651             m_it--;
8652             return result;
8653         }
8654
8655         primitive_iterator_t& operator+=(difference_type n)
8656         {
8657             m_it += n;
8658             return *this;
8659         }
8660
8661         primitive_iterator_t& operator-=(difference_type n)
8662         {
8663             m_it -= n;
8664             return *this;
8665         }
8666
8667       private:
8668         static constexpr difference_type begin_value = 0;
8669         static constexpr difference_type end_value = begin_value + 1;
8670
8671         /// iterator as signed integer type
8672         difference_type m_it = std::numeric_limits<std::ptrdiff_t>::denorm_min();
8673     };
8674
8675     /*!
8676     @brief an iterator value
8677
8678     @note This structure could easily be a union, but MSVC currently does not
8679     allow unions members with complex constructors, see
8680     https://github.com/nlohmann/json/pull/105.
8681     */
8682     struct internal_iterator
8683     {
8684         /// iterator for JSON objects
8685         typename object_t::iterator object_iterator;
8686         /// iterator for JSON arrays
8687         typename array_t::iterator array_iterator;
8688         /// generic iterator for all other types
8689         primitive_iterator_t primitive_iterator;
8690
8691         /// create an uninitialized internal_iterator
8692         internal_iterator() noexcept
8693             : object_iterator(), array_iterator(), primitive_iterator()
8694         {}
8695     };
8696
8697     /// proxy class for the iterator_wrapper functions
8698     template<typename IteratorType>
8699     class iteration_proxy
8700     {
8701       private:
8702         /// helper class for iteration
8703         class iteration_proxy_internal
8704         {
8705           private:
8706             /// the iterator
8707             IteratorType anchor;
8708             /// an index for arrays (used to create key names)
8709             size_t array_index = 0;
8710
8711           public:
8712             explicit iteration_proxy_internal(IteratorType it) noexcept
8713                 : anchor(it)
8714             {}
8715
8716             /// dereference operator (needed for range-based for)
8717             iteration_proxy_internal& operator*()
8718             {
8719                 return *this;
8720             }
8721
8722             /// increment operator (needed for range-based for)
8723             iteration_proxy_internal& operator++()
8724             {
8725                 ++anchor;
8726                 ++array_index;
8727
8728                 return *this;
8729             }
8730
8731             /// inequality operator (needed for range-based for)
8732             bool operator!= (const iteration_proxy_internal& o) const
8733             {
8734                 return anchor != o.anchor;
8735             }
8736
8737             /// return key of the iterator
8738             typename basic_json::string_t key() const
8739             {
8740                 assert(anchor.m_object != nullptr);
8741
8742                 switch (anchor.m_object->type())
8743                 {
8744                     // use integer array index as key
8745                     case value_t::array:
8746                     {
8747                         return std::to_string(array_index);
8748                     }
8749
8750                     // use key from the object
8751                     case value_t::object:
8752                     {
8753                         return anchor.key();
8754                     }
8755
8756                     // use an empty key for all primitive types
8757                     default:
8758                     {
8759                         return "";
8760                     }
8761                 }
8762             }
8763
8764             /// return value of the iterator
8765             typename IteratorType::reference value() const
8766             {
8767                 return anchor.value();
8768             }
8769         };
8770
8771         /// the container to iterate
8772         typename IteratorType::reference container;
8773
8774       public:
8775         /// construct iteration proxy from a container
8776         explicit iteration_proxy(typename IteratorType::reference cont)
8777             : container(cont)
8778         {}
8779
8780         /// return iterator begin (needed for range-based for)
8781         iteration_proxy_internal begin() noexcept
8782         {
8783             return iteration_proxy_internal(container.begin());
8784         }
8785
8786         /// return iterator end (needed for range-based for)
8787         iteration_proxy_internal end() noexcept
8788         {
8789             return iteration_proxy_internal(container.end());
8790         }
8791     };
8792
8793   public:
8794     /*!
8795     @brief a template for a random access iterator for the @ref basic_json class
8796
8797     This class implements a both iterators (iterator and const_iterator) for the
8798     @ref basic_json class.
8799
8800     @note An iterator is called *initialized* when a pointer to a JSON value
8801           has been set (e.g., by a constructor or a copy assignment). If the
8802           iterator is default-constructed, it is *uninitialized* and most
8803           methods are undefined. **The library uses assertions to detect calls
8804           on uninitialized iterators.**
8805
8806     @requirement The class satisfies the following concept requirements:
8807     - [RandomAccessIterator](http://en.cppreference.com/w/cpp/concept/RandomAccessIterator):
8808       The iterator that can be moved to point (forward and backward) to any
8809       element in constant time.
8810
8811     @since version 1.0.0, simplified in version 2.0.9
8812     */
8813     template<typename U>
8814     class iter_impl : public std::iterator<std::random_access_iterator_tag, U>
8815     {
8816         /// allow basic_json to access private members
8817         friend class basic_json;
8818
8819         // make sure U is basic_json or const basic_json
8820         static_assert(std::is_same<U, basic_json>::value
8821                       or std::is_same<U, const basic_json>::value,
8822                       "iter_impl only accepts (const) basic_json");
8823
8824       public:
8825         /// the type of the values when the iterator is dereferenced
8826         using value_type = typename basic_json::value_type;
8827         /// a type to represent differences between iterators
8828         using difference_type = typename basic_json::difference_type;
8829         /// defines a pointer to the type iterated over (value_type)
8830         using pointer = typename std::conditional<std::is_const<U>::value,
8831               typename basic_json::const_pointer,
8832               typename basic_json::pointer>::type;
8833         /// defines a reference to the type iterated over (value_type)
8834         using reference = typename std::conditional<std::is_const<U>::value,
8835               typename basic_json::const_reference,
8836               typename basic_json::reference>::type;
8837         /// the category of the iterator
8838         using iterator_category = std::bidirectional_iterator_tag;
8839
8840         /// default constructor
8841         iter_impl() = default;
8842
8843         /*!
8844         @brief constructor for a given JSON instance
8845         @param[in] object  pointer to a JSON object for this iterator
8846         @pre object != nullptr
8847         @post The iterator is initialized; i.e. `m_object != nullptr`.
8848         */
8849         explicit iter_impl(pointer object) noexcept
8850             : m_object(object)
8851         {
8852             assert(m_object != nullptr);
8853
8854             switch (m_object->m_type)
8855             {
8856                 case basic_json::value_t::object:
8857                 {
8858                     m_it.object_iterator = typename object_t::iterator();
8859                     break;
8860                 }
8861
8862                 case basic_json::value_t::array:
8863                 {
8864                     m_it.array_iterator = typename array_t::iterator();
8865                     break;
8866                 }
8867
8868                 default:
8869                 {
8870                     m_it.primitive_iterator = primitive_iterator_t();
8871                     break;
8872                 }
8873             }
8874         }
8875
8876         /*
8877         Use operator `const_iterator` instead of `const_iterator(const iterator&
8878         other) noexcept` to avoid two class definitions for @ref iterator and
8879         @ref const_iterator.
8880
8881         This function is only called if this class is an @ref iterator. If this
8882         class is a @ref const_iterator this function is not called.
8883         */
8884         operator const_iterator() const
8885         {
8886             const_iterator ret;
8887
8888             if (m_object)
8889             {
8890                 ret.m_object = m_object;
8891                 ret.m_it = m_it;
8892             }
8893
8894             return ret;
8895         }
8896
8897         /*!
8898         @brief copy constructor
8899         @param[in] other  iterator to copy from
8900         @note It is not checked whether @a other is initialized.
8901         */
8902         iter_impl(const iter_impl& other) noexcept
8903             : m_object(other.m_object), m_it(other.m_it)
8904         {}
8905
8906         /*!
8907         @brief copy assignment
8908         @param[in,out] other  iterator to copy from
8909         @note It is not checked whether @a other is initialized.
8910         */
8911         iter_impl& operator=(iter_impl other) noexcept(
8912             std::is_nothrow_move_constructible<pointer>::value and
8913             std::is_nothrow_move_assignable<pointer>::value and
8914             std::is_nothrow_move_constructible<internal_iterator>::value and
8915             std::is_nothrow_move_assignable<internal_iterator>::value
8916         )
8917         {
8918             std::swap(m_object, other.m_object);
8919             std::swap(m_it, other.m_it);
8920             return *this;
8921         }
8922
8923       private:
8924         /*!
8925         @brief set the iterator to the first value
8926         @pre The iterator is initialized; i.e. `m_object != nullptr`.
8927         */
8928         void set_begin() noexcept
8929         {
8930             assert(m_object != nullptr);
8931
8932             switch (m_object->m_type)
8933             {
8934                 case basic_json::value_t::object:
8935                 {
8936                     m_it.object_iterator = m_object->m_value.object->begin();
8937                     break;
8938                 }
8939
8940                 case basic_json::value_t::array:
8941                 {
8942                     m_it.array_iterator = m_object->m_value.array->begin();
8943                     break;
8944                 }
8945
8946                 case basic_json::value_t::null:
8947                 {
8948                     // set to end so begin()==end() is true: null is empty
8949                     m_it.primitive_iterator.set_end();
8950                     break;
8951                 }
8952
8953                 default:
8954                 {
8955                     m_it.primitive_iterator.set_begin();
8956                     break;
8957                 }
8958             }
8959         }
8960
8961         /*!
8962         @brief set the iterator past the last value
8963         @pre The iterator is initialized; i.e. `m_object != nullptr`.
8964         */
8965         void set_end() noexcept
8966         {
8967             assert(m_object != nullptr);
8968
8969             switch (m_object->m_type)
8970             {
8971                 case basic_json::value_t::object:
8972                 {
8973                     m_it.object_iterator = m_object->m_value.object->end();
8974                     break;
8975                 }
8976
8977                 case basic_json::value_t::array:
8978                 {
8979                     m_it.array_iterator = m_object->m_value.array->end();
8980                     break;
8981                 }
8982
8983                 default:
8984                 {
8985                     m_it.primitive_iterator.set_end();
8986                     break;
8987                 }
8988             }
8989         }
8990
8991       public:
8992         /*!
8993         @brief return a reference to the value pointed to by the iterator
8994         @pre The iterator is initialized; i.e. `m_object != nullptr`.
8995         */
8996         reference operator*() const
8997         {
8998             assert(m_object != nullptr);
8999
9000             switch (m_object->m_type)
9001             {
9002                 case basic_json::value_t::object:
9003                 {
9004                     assert(m_it.object_iterator != m_object->m_value.object->end());
9005                     return m_it.object_iterator->second;
9006                 }
9007
9008                 case basic_json::value_t::array:
9009                 {
9010                     assert(m_it.array_iterator != m_object->m_value.array->end());
9011                     return *m_it.array_iterator;
9012                 }
9013
9014                 case basic_json::value_t::null:
9015                 {
9016                     JSON_THROW(std::out_of_range("cannot get value"));
9017                 }
9018
9019                 default:
9020                 {
9021                     if (m_it.primitive_iterator.is_begin())
9022                     {
9023                         return *m_object;
9024                     }
9025
9026                     JSON_THROW(std::out_of_range("cannot get value"));
9027                 }
9028             }
9029         }
9030
9031         /*!
9032         @brief dereference the iterator
9033         @pre The iterator is initialized; i.e. `m_object != nullptr`.
9034         */
9035         pointer operator->() const
9036         {
9037             assert(m_object != nullptr);
9038
9039             switch (m_object->m_type)
9040             {
9041                 case basic_json::value_t::object:
9042                 {
9043                     assert(m_it.object_iterator != m_object->m_value.object->end());
9044                     return &(m_it.object_iterator->second);
9045                 }
9046
9047                 case basic_json::value_t::array:
9048                 {
9049                     assert(m_it.array_iterator != m_object->m_value.array->end());
9050                     return &*m_it.array_iterator;
9051                 }
9052
9053                 default:
9054                 {
9055                     if (m_it.primitive_iterator.is_begin())
9056                     {
9057                         return m_object;
9058                     }
9059
9060                     JSON_THROW(std::out_of_range("cannot get value"));
9061                 }
9062             }
9063         }
9064
9065         /*!
9066         @brief post-increment (it++)
9067         @pre The iterator is initialized; i.e. `m_object != nullptr`.
9068         */
9069         iter_impl operator++(int)
9070         {
9071             auto result = *this;
9072             ++(*this);
9073             return result;
9074         }
9075
9076         /*!
9077         @brief pre-increment (++it)
9078         @pre The iterator is initialized; i.e. `m_object != nullptr`.
9079         */
9080         iter_impl& operator++()
9081         {
9082             assert(m_object != nullptr);
9083
9084             switch (m_object->m_type)
9085             {
9086                 case basic_json::value_t::object:
9087                 {
9088                     std::advance(m_it.object_iterator, 1);
9089                     break;
9090                 }
9091
9092                 case basic_json::value_t::array:
9093                 {
9094                     std::advance(m_it.array_iterator, 1);
9095                     break;
9096                 }
9097
9098                 default:
9099                 {
9100                     ++m_it.primitive_iterator;
9101                     break;
9102                 }
9103             }
9104
9105             return *this;
9106         }
9107
9108         /*!
9109         @brief post-decrement (it--)
9110         @pre The iterator is initialized; i.e. `m_object != nullptr`.
9111         */
9112         iter_impl operator--(int)
9113         {
9114             auto result = *this;
9115             --(*this);
9116             return result;
9117         }
9118
9119         /*!
9120         @brief pre-decrement (--it)
9121         @pre The iterator is initialized; i.e. `m_object != nullptr`.
9122         */
9123         iter_impl& operator--()
9124         {
9125             assert(m_object != nullptr);
9126
9127             switch (m_object->m_type)
9128             {
9129                 case basic_json::value_t::object:
9130                 {
9131                     std::advance(m_it.object_iterator, -1);
9132                     break;
9133                 }
9134
9135                 case basic_json::value_t::array:
9136                 {
9137                     std::advance(m_it.array_iterator, -1);
9138                     break;
9139                 }
9140
9141                 default:
9142                 {
9143                     --m_it.primitive_iterator;
9144                     break;
9145                 }
9146             }
9147
9148             return *this;
9149         }
9150
9151         /*!
9152         @brief  comparison: equal
9153         @pre The iterator is initialized; i.e. `m_object != nullptr`.
9154         */
9155         bool operator==(const iter_impl& other) const
9156         {
9157             // if objects are not the same, the comparison is undefined
9158             if (m_object != other.m_object)
9159             {
9160                 JSON_THROW(std::domain_error("cannot compare iterators of different containers"));
9161             }
9162
9163             assert(m_object != nullptr);
9164
9165             switch (m_object->m_type)
9166             {
9167                 case basic_json::value_t::object:
9168                 {
9169                     return (m_it.object_iterator == other.m_it.object_iterator);
9170                 }
9171
9172                 case basic_json::value_t::array:
9173                 {
9174                     return (m_it.array_iterator == other.m_it.array_iterator);
9175                 }
9176
9177                 default:
9178                 {
9179                     return (m_it.primitive_iterator == other.m_it.primitive_iterator);
9180                 }
9181             }
9182         }
9183
9184         /*!
9185         @brief  comparison: not equal
9186         @pre The iterator is initialized; i.e. `m_object != nullptr`.
9187         */
9188         bool operator!=(const iter_impl& other) const
9189         {
9190             return not operator==(other);
9191         }
9192
9193         /*!
9194         @brief  comparison: smaller
9195         @pre The iterator is initialized; i.e. `m_object != nullptr`.
9196         */
9197         bool operator<(const iter_impl& other) const
9198         {
9199             // if objects are not the same, the comparison is undefined
9200             if (m_object != other.m_object)
9201             {
9202                 JSON_THROW(std::domain_error("cannot compare iterators of different containers"));
9203             }
9204
9205             assert(m_object != nullptr);
9206
9207             switch (m_object->m_type)
9208             {
9209                 case basic_json::value_t::object:
9210                 {
9211                     JSON_THROW(std::domain_error("cannot compare order of object iterators"));
9212                 }
9213
9214                 case basic_json::value_t::array:
9215                 {
9216                     return (m_it.array_iterator < other.m_it.array_iterator);
9217                 }
9218
9219                 default:
9220                 {
9221                     return (m_it.primitive_iterator < other.m_it.primitive_iterator);
9222                 }
9223             }
9224         }
9225
9226         /*!
9227         @brief  comparison: less than or equal
9228         @pre The iterator is initialized; i.e. `m_object != nullptr`.
9229         */
9230         bool operator<=(const iter_impl& other) const
9231         {
9232             return not other.operator < (*this);
9233         }
9234
9235         /*!
9236         @brief  comparison: greater than
9237         @pre The iterator is initialized; i.e. `m_object != nullptr`.
9238         */
9239         bool operator>(const iter_impl& other) const
9240         {
9241             return not operator<=(other);
9242         }
9243
9244         /*!
9245         @brief  comparison: greater than or equal
9246         @pre The iterator is initialized; i.e. `m_object != nullptr`.
9247         */
9248         bool operator>=(const iter_impl& other) const
9249         {
9250             return not operator<(other);
9251         }
9252
9253         /*!
9254         @brief  add to iterator
9255         @pre The iterator is initialized; i.e. `m_object != nullptr`.
9256         */
9257         iter_impl& operator+=(difference_type i)
9258         {
9259             assert(m_object != nullptr);
9260
9261             switch (m_object->m_type)
9262             {
9263                 case basic_json::value_t::object:
9264                 {
9265                     JSON_THROW(std::domain_error("cannot use offsets with object iterators"));
9266                 }
9267
9268                 case basic_json::value_t::array:
9269                 {
9270                     std::advance(m_it.array_iterator, i);
9271                     break;
9272                 }
9273
9274                 default:
9275                 {
9276                     m_it.primitive_iterator += i;
9277                     break;
9278                 }
9279             }
9280
9281             return *this;
9282         }
9283
9284         /*!
9285         @brief  subtract from iterator
9286         @pre The iterator is initialized; i.e. `m_object != nullptr`.
9287         */
9288         iter_impl& operator-=(difference_type i)
9289         {
9290             return operator+=(-i);
9291         }
9292
9293         /*!
9294         @brief  add to iterator
9295         @pre The iterator is initialized; i.e. `m_object != nullptr`.
9296         */
9297         iter_impl operator+(difference_type i)
9298         {
9299             auto result = *this;
9300             result += i;
9301             return result;
9302         }
9303
9304         /*!
9305         @brief  subtract from iterator
9306         @pre The iterator is initialized; i.e. `m_object != nullptr`.
9307         */
9308         iter_impl operator-(difference_type i)
9309         {
9310             auto result = *this;
9311             result -= i;
9312             return result;
9313         }
9314
9315         /*!
9316         @brief  return difference
9317         @pre The iterator is initialized; i.e. `m_object != nullptr`.
9318         */
9319         difference_type operator-(const iter_impl& other) const
9320         {
9321             assert(m_object != nullptr);
9322
9323             switch (m_object->m_type)
9324             {
9325                 case basic_json::value_t::object:
9326                 {
9327                     JSON_THROW(std::domain_error("cannot use offsets with object iterators"));
9328                 }
9329
9330                 case basic_json::value_t::array:
9331                 {
9332                     return m_it.array_iterator - other.m_it.array_iterator;
9333                 }
9334
9335                 default:
9336                 {
9337                     return m_it.primitive_iterator - other.m_it.primitive_iterator;
9338                 }
9339             }
9340         }
9341
9342         /*!
9343         @brief  access to successor
9344         @pre The iterator is initialized; i.e. `m_object != nullptr`.
9345         */
9346         reference operator[](difference_type n) const
9347         {
9348             assert(m_object != nullptr);
9349
9350             switch (m_object->m_type)
9351             {
9352                 case basic_json::value_t::object:
9353                 {
9354                     JSON_THROW(std::domain_error("cannot use operator[] for object iterators"));
9355                 }
9356
9357                 case basic_json::value_t::array:
9358                 {
9359                     return *std::next(m_it.array_iterator, n);
9360                 }
9361
9362                 case basic_json::value_t::null:
9363                 {
9364                     JSON_THROW(std::out_of_range("cannot get value"));
9365                 }
9366
9367                 default:
9368                 {
9369                     if (m_it.primitive_iterator.get_value() == -n)
9370                     {
9371                         return *m_object;
9372                     }
9373
9374                     JSON_THROW(std::out_of_range("cannot get value"));
9375                 }
9376             }
9377         }
9378
9379         /*!
9380         @brief  return the key of an object iterator
9381         @pre The iterator is initialized; i.e. `m_object != nullptr`.
9382         */
9383         typename object_t::key_type key() const
9384         {
9385             assert(m_object != nullptr);
9386
9387             if (m_object->is_object())
9388             {
9389                 return m_it.object_iterator->first;
9390             }
9391
9392             JSON_THROW(std::domain_error("cannot use key() for non-object iterators"));
9393         }
9394
9395         /*!
9396         @brief  return the value of an iterator
9397         @pre The iterator is initialized; i.e. `m_object != nullptr`.
9398         */
9399         reference value() const
9400         {
9401             return operator*();
9402         }
9403
9404       private:
9405         /// associated JSON instance
9406         pointer m_object = nullptr;
9407         /// the actual iterator of the associated instance
9408         internal_iterator m_it = internal_iterator();
9409     };
9410
9411     /*!
9412     @brief a template for a reverse iterator class
9413
9414     @tparam Base the base iterator type to reverse. Valid types are @ref
9415     iterator (to create @ref reverse_iterator) and @ref const_iterator (to
9416     create @ref const_reverse_iterator).
9417
9418     @requirement The class satisfies the following concept requirements:
9419     - [RandomAccessIterator](http://en.cppreference.com/w/cpp/concept/RandomAccessIterator):
9420       The iterator that can be moved to point (forward and backward) to any
9421       element in constant time.
9422     - [OutputIterator](http://en.cppreference.com/w/cpp/concept/OutputIterator):
9423       It is possible to write to the pointed-to element (only if @a Base is
9424       @ref iterator).
9425
9426     @since version 1.0.0
9427     */
9428     template<typename Base>
9429     class json_reverse_iterator : public std::reverse_iterator<Base>
9430     {
9431       public:
9432         /// shortcut to the reverse iterator adaptor
9433         using base_iterator = std::reverse_iterator<Base>;
9434         /// the reference type for the pointed-to element
9435         using reference = typename Base::reference;
9436
9437         /// create reverse iterator from iterator
9438         json_reverse_iterator(const typename base_iterator::iterator_type& it) noexcept
9439             : base_iterator(it)
9440         {}
9441
9442         /// create reverse iterator from base class
9443         json_reverse_iterator(const base_iterator& it) noexcept
9444             : base_iterator(it)
9445         {}
9446
9447         /// post-increment (it++)
9448         json_reverse_iterator operator++(int)
9449         {
9450             return base_iterator::operator++(1);
9451         }
9452
9453         /// pre-increment (++it)
9454         json_reverse_iterator& operator++()
9455         {
9456             base_iterator::operator++();
9457             return *this;
9458         }
9459
9460         /// post-decrement (it--)
9461         json_reverse_iterator operator--(int)
9462         {
9463             return base_iterator::operator--(1);
9464         }
9465
9466         /// pre-decrement (--it)
9467         json_reverse_iterator& operator--()
9468         {
9469             base_iterator::operator--();
9470             return *this;
9471         }
9472
9473         /// add to iterator
9474         json_reverse_iterator& operator+=(difference_type i)
9475         {
9476             base_iterator::operator+=(i);
9477             return *this;
9478         }
9479
9480         /// add to iterator
9481         json_reverse_iterator operator+(difference_type i) const
9482         {
9483             auto result = *this;
9484             result += i;
9485             return result;
9486         }
9487
9488         /// subtract from iterator
9489         json_reverse_iterator operator-(difference_type i) const
9490         {
9491             auto result = *this;
9492             result -= i;
9493             return result;
9494         }
9495
9496         /// return difference
9497         difference_type operator-(const json_reverse_iterator& other) const
9498         {
9499             return this->base() - other.base();
9500         }
9501
9502         /// access to successor
9503         reference operator[](difference_type n) const
9504         {
9505             return *(this->operator+(n));
9506         }
9507
9508         /// return the key of an object iterator
9509         typename object_t::key_type key() const
9510         {
9511             auto it = --this->base();
9512             return it.key();
9513         }
9514
9515         /// return the value of an iterator
9516         reference value() const
9517         {
9518             auto it = --this->base();
9519             return it.operator * ();
9520         }
9521     };
9522
9523
9524   private:
9525     //////////////////////
9526     // lexer and parser //
9527     //////////////////////
9528
9529     /*!
9530     @brief lexical analysis
9531
9532     This class organizes the lexical analysis during JSON deserialization. The
9533     core of it is a scanner generated by [re2c](http://re2c.org) that
9534     processes a buffer and recognizes tokens according to RFC 7159.
9535     */
9536     class lexer
9537     {
9538       public:
9539         /// token types for the parser
9540         enum class token_type
9541         {
9542             uninitialized,   ///< indicating the scanner is uninitialized
9543             literal_true,    ///< the `true` literal
9544             literal_false,   ///< the `false` literal
9545             literal_null,    ///< the `null` literal
9546             value_string,    ///< a string -- use get_string() for actual value
9547             value_unsigned,  ///< an unsigned integer -- use get_number() for actual value
9548             value_integer,   ///< a signed integer -- use get_number() for actual value
9549             value_float,     ///< an floating point number -- use get_number() for actual value
9550             begin_array,     ///< the character for array begin `[`
9551             begin_object,    ///< the character for object begin `{`
9552             end_array,       ///< the character for array end `]`
9553             end_object,      ///< the character for object end `}`
9554             name_separator,  ///< the name separator `:`
9555             value_separator, ///< the value separator `,`
9556             parse_error,     ///< indicating a parse error
9557             end_of_input     ///< indicating the end of the input buffer
9558         };
9559
9560         /// the char type to use in the lexer
9561         using lexer_char_t = unsigned char;
9562
9563         /// a lexer from a buffer with given length
9564         lexer(const lexer_char_t* buff, const size_t len) noexcept
9565             : m_content(buff)
9566         {
9567             assert(m_content != nullptr);
9568             m_start = m_cursor = m_content;
9569             m_limit = m_content + len;
9570         }
9571
9572         /// a lexer from an input stream
9573         explicit lexer(std::istream& s)
9574             : m_stream(&s), m_line_buffer()
9575         {
9576             // immediately abort if stream is erroneous
9577             if (s.fail())
9578             {
9579                 JSON_THROW(std::invalid_argument("stream error"));
9580             }
9581
9582             // fill buffer
9583             fill_line_buffer();
9584
9585             // skip UTF-8 byte-order mark
9586             if (m_line_buffer.size() >= 3 and m_line_buffer.substr(0, 3) == "\xEF\xBB\xBF")
9587             {
9588                 m_line_buffer[0] = ' ';
9589                 m_line_buffer[1] = ' ';
9590                 m_line_buffer[2] = ' ';
9591             }
9592         }
9593
9594         // switch off unwanted functions (due to pointer members)
9595         lexer() = delete;
9596         lexer(const lexer&) = delete;
9597         lexer operator=(const lexer&) = delete;
9598
9599         /*!
9600         @brief create a string from one or two Unicode code points
9601
9602         There are two cases: (1) @a codepoint1 is in the Basic Multilingual
9603         Plane (U+0000 through U+FFFF) and @a codepoint2 is 0, or (2)
9604         @a codepoint1 and @a codepoint2 are a UTF-16 surrogate pair to
9605         represent a code point above U+FFFF.
9606
9607         @param[in] codepoint1  the code point (can be high surrogate)
9608         @param[in] codepoint2  the code point (can be low surrogate or 0)
9609
9610         @return string representation of the code point; the length of the
9611         result string is between 1 and 4 characters.
9612
9613         @throw std::out_of_range if code point is > 0x10ffff; example: `"code
9614         points above 0x10FFFF are invalid"`
9615         @throw std::invalid_argument if the low surrogate is invalid; example:
9616         `""missing or wrong low surrogate""`
9617
9618         @complexity Constant.
9619
9620         @see <http://en.wikipedia.org/wiki/UTF-8#Sample_code>
9621         */
9622         static string_t to_unicode(const std::size_t codepoint1,
9623                                    const std::size_t codepoint2 = 0)
9624         {
9625             // calculate the code point from the given code points
9626             std::size_t codepoint = codepoint1;
9627
9628             // check if codepoint1 is a high surrogate
9629             if (codepoint1 >= 0xD800 and codepoint1 <= 0xDBFF)
9630             {
9631                 // check if codepoint2 is a low surrogate
9632                 if (codepoint2 >= 0xDC00 and codepoint2 <= 0xDFFF)
9633                 {
9634                     codepoint =
9635                         // high surrogate occupies the most significant 22 bits
9636                         (codepoint1 << 10)
9637                         // low surrogate occupies the least significant 15 bits
9638                         + codepoint2
9639                         // there is still the 0xD800, 0xDC00 and 0x10000 noise
9640                         // in the result so we have to subtract with:
9641                         // (0xD800 << 10) + DC00 - 0x10000 = 0x35FDC00
9642                         - 0x35FDC00;
9643                 }
9644                 else
9645                 {
9646                     JSON_THROW(std::invalid_argument("missing or wrong low surrogate"));
9647                 }
9648             }
9649
9650             string_t result;
9651
9652             if (codepoint < 0x80)
9653             {
9654                 // 1-byte characters: 0xxxxxxx (ASCII)
9655                 result.append(1, static_cast<typename string_t::value_type>(codepoint));
9656             }
9657             else if (codepoint <= 0x7ff)
9658             {
9659                 // 2-byte characters: 110xxxxx 10xxxxxx
9660                 result.append(1, static_cast<typename string_t::value_type>(0xC0 | ((codepoint >> 6) & 0x1F)));
9661                 result.append(1, static_cast<typename string_t::value_type>(0x80 | (codepoint & 0x3F)));
9662             }
9663             else if (codepoint <= 0xffff)
9664             {
9665                 // 3-byte characters: 1110xxxx 10xxxxxx 10xxxxxx
9666                 result.append(1, static_cast<typename string_t::value_type>(0xE0 | ((codepoint >> 12) & 0x0F)));
9667                 result.append(1, static_cast<typename string_t::value_type>(0x80 | ((codepoint >> 6) & 0x3F)));
9668                 result.append(1, static_cast<typename string_t::value_type>(0x80 | (codepoint & 0x3F)));
9669             }
9670             else if (codepoint <= 0x10ffff)
9671             {
9672                 // 4-byte characters: 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx
9673                 result.append(1, static_cast<typename string_t::value_type>(0xF0 | ((codepoint >> 18) & 0x07)));
9674                 result.append(1, static_cast<typename string_t::value_type>(0x80 | ((codepoint >> 12) & 0x3F)));
9675                 result.append(1, static_cast<typename string_t::value_type>(0x80 | ((codepoint >> 6) & 0x3F)));
9676                 result.append(1, static_cast<typename string_t::value_type>(0x80 | (codepoint & 0x3F)));
9677             }
9678             else
9679             {
9680                 JSON_THROW(std::out_of_range("code points above 0x10FFFF are invalid"));
9681             }
9682
9683             return result;
9684         }
9685
9686         /// return name of values of type token_type (only used for errors)
9687         static std::string token_type_name(const token_type t)
9688         {
9689             switch (t)
9690             {
9691                 case token_type::uninitialized:
9692                     return "<uninitialized>";
9693                 case token_type::literal_true:
9694                     return "true literal";
9695                 case token_type::literal_false:
9696                     return "false literal";
9697                 case token_type::literal_null:
9698                     return "null literal";
9699                 case token_type::value_string:
9700                     return "string literal";
9701                 case lexer::token_type::value_unsigned:
9702                 case lexer::token_type::value_integer:
9703                 case lexer::token_type::value_float:
9704                     return "number literal";
9705                 case token_type::begin_array:
9706                     return "'['";
9707                 case token_type::begin_object:
9708                     return "'{'";
9709                 case token_type::end_array:
9710                     return "']'";
9711                 case token_type::end_object:
9712                     return "'}'";
9713                 case token_type::name_separator:
9714                     return "':'";
9715                 case token_type::value_separator:
9716                     return "','";
9717                 case token_type::parse_error:
9718                     return "<parse error>";
9719                 case token_type::end_of_input:
9720                     return "end of input";
9721                 default:
9722                 {
9723                     // catch non-enum values
9724                     return "unknown token"; // LCOV_EXCL_LINE
9725                 }
9726             }
9727         }
9728
9729         /*!
9730         This function implements a scanner for JSON. It is specified using
9731         regular expressions that try to follow RFC 7159 as close as possible.
9732         These regular expressions are then translated into a minimized
9733         deterministic finite automaton (DFA) by the tool
9734         [re2c](http://re2c.org). As a result, the translated code for this
9735         function consists of a large block of code with `goto` jumps.
9736
9737         @return the class of the next token read from the buffer
9738
9739         @complexity Linear in the length of the input.\n
9740
9741         Proposition: The loop below will always terminate for finite input.\n
9742
9743         Proof (by contradiction): Assume a finite input. To loop forever, the
9744         loop must never hit code with a `break` statement. The only code
9745         snippets without a `break` statement are the continue statements for
9746         whitespace and byte-order-marks. To loop forever, the input must be an
9747         infinite sequence of whitespace or byte-order-marks. This contradicts
9748         the assumption of finite input, q.e.d.
9749         */
9750         token_type scan()
9751         {
9752             while (true)
9753             {
9754                 // pointer for backtracking information
9755                 m_marker = nullptr;
9756
9757                 // remember the begin of the token
9758                 m_start = m_cursor;
9759                 assert(m_start != nullptr);
9760
9761
9762                 {
9763                     lexer_char_t yych;
9764                     unsigned int yyaccept = 0;
9765                     static const unsigned char yybm[] =
9766                     {
9767                         0,   0,   0,   0,   0,   0,   0,   0,
9768                         0,  32,  32,   0,   0,  32,   0,   0,
9769                         0,   0,   0,   0,   0,   0,   0,   0,
9770                         0,   0,   0,   0,   0,   0,   0,   0,
9771                         160, 128,   0, 128, 128, 128, 128, 128,
9772                         128, 128, 128, 128, 128, 128, 128, 128,
9773                         192, 192, 192, 192, 192, 192, 192, 192,
9774                         192, 192, 128, 128, 128, 128, 128, 128,
9775                         128, 128, 128, 128, 128, 128, 128, 128,
9776                         128, 128, 128, 128, 128, 128, 128, 128,
9777                         128, 128, 128, 128, 128, 128, 128, 128,
9778                         128, 128, 128, 128,   0, 128, 128, 128,
9779                         128, 128, 128, 128, 128, 128, 128, 128,
9780                         128, 128, 128, 128, 128, 128, 128, 128,
9781                         128, 128, 128, 128, 128, 128, 128, 128,
9782                         128, 128, 128, 128, 128, 128, 128, 128,
9783                         0,   0,   0,   0,   0,   0,   0,   0,
9784                         0,   0,   0,   0,   0,   0,   0,   0,
9785                         0,   0,   0,   0,   0,   0,   0,   0,
9786                         0,   0,   0,   0,   0,   0,   0,   0,
9787                         0,   0,   0,   0,   0,   0,   0,   0,
9788                         0,   0,   0,   0,   0,   0,   0,   0,
9789                         0,   0,   0,   0,   0,   0,   0,   0,
9790                         0,   0,   0,   0,   0,   0,   0,   0,
9791                         0,   0,   0,   0,   0,   0,   0,   0,
9792                         0,   0,   0,   0,   0,   0,   0,   0,
9793                         0,   0,   0,   0,   0,   0,   0,   0,
9794                         0,   0,   0,   0,   0,   0,   0,   0,
9795                         0,   0,   0,   0,   0,   0,   0,   0,
9796                         0,   0,   0,   0,   0,   0,   0,   0,
9797                         0,   0,   0,   0,   0,   0,   0,   0,
9798                         0,   0,   0,   0,   0,   0,   0,   0,
9799                     };
9800                     if ((m_limit - m_cursor) < 5)
9801                     {
9802                         fill_line_buffer(5);    // LCOV_EXCL_LINE
9803                     }
9804                     yych = *m_cursor;
9805                     if (yybm[0 + yych] & 32)
9806                     {
9807                         goto basic_json_parser_6;
9808                     }
9809                     if (yych <= '[')
9810                     {
9811                         if (yych <= '-')
9812                         {
9813                             if (yych <= '"')
9814                             {
9815                                 if (yych <= 0x00)
9816                                 {
9817                                     goto basic_json_parser_2;
9818                                 }
9819                                 if (yych <= '!')
9820                                 {
9821                                     goto basic_json_parser_4;
9822                                 }
9823                                 goto basic_json_parser_9;
9824                             }
9825                             else
9826                             {
9827                                 if (yych <= '+')
9828                                 {
9829                                     goto basic_json_parser_4;
9830                                 }
9831                                 if (yych <= ',')
9832                                 {
9833                                     goto basic_json_parser_10;
9834                                 }
9835                                 goto basic_json_parser_12;
9836                             }
9837                         }
9838                         else
9839                         {
9840                             if (yych <= '9')
9841                             {
9842                                 if (yych <= '/')
9843                                 {
9844                                     goto basic_json_parser_4;
9845                                 }
9846                                 if (yych <= '0')
9847                                 {
9848                                     goto basic_json_parser_13;
9849                                 }
9850                                 goto basic_json_parser_15;
9851                             }
9852                             else
9853                             {
9854                                 if (yych <= ':')
9855                                 {
9856                                     goto basic_json_parser_17;
9857                                 }
9858                                 if (yych <= 'Z')
9859                                 {
9860                                     goto basic_json_parser_4;
9861                                 }
9862                                 goto basic_json_parser_19;
9863                             }
9864                         }
9865                     }
9866                     else
9867                     {
9868                         if (yych <= 'n')
9869                         {
9870                             if (yych <= 'e')
9871                             {
9872                                 if (yych == ']')
9873                                 {
9874                                     goto basic_json_parser_21;
9875                                 }
9876                                 goto basic_json_parser_4;
9877                             }
9878                             else
9879                             {
9880                                 if (yych <= 'f')
9881                                 {
9882                                     goto basic_json_parser_23;
9883                                 }
9884                                 if (yych <= 'm')
9885                                 {
9886                                     goto basic_json_parser_4;
9887                                 }
9888                                 goto basic_json_parser_24;
9889                             }
9890                         }
9891                         else
9892                         {
9893                             if (yych <= 'z')
9894                             {
9895                                 if (yych == 't')
9896                                 {
9897                                     goto basic_json_parser_25;
9898                                 }
9899                                 goto basic_json_parser_4;
9900                             }
9901                             else
9902                             {
9903                                 if (yych <= '{')
9904                                 {
9905                                     goto basic_json_parser_26;
9906                                 }
9907                                 if (yych == '}')
9908                                 {
9909                                     goto basic_json_parser_28;
9910                                 }
9911                                 goto basic_json_parser_4;
9912                             }
9913                         }
9914                     }
9915 basic_json_parser_2:
9916                     ++m_cursor;
9917                     {
9918                         last_token_type = token_type::end_of_input;
9919                         break;
9920                     }
9921 basic_json_parser_4:
9922                     ++m_cursor;
9923 basic_json_parser_5:
9924                     {
9925                         last_token_type = token_type::parse_error;
9926                         break;
9927                     }
9928 basic_json_parser_6:
9929                     ++m_cursor;
9930                     if (m_limit <= m_cursor)
9931                     {
9932                         fill_line_buffer(1);    // LCOV_EXCL_LINE
9933                     }
9934                     yych = *m_cursor;
9935                     if (yybm[0 + yych] & 32)
9936                     {
9937                         goto basic_json_parser_6;
9938                     }
9939                     {
9940                         continue;
9941                     }
9942 basic_json_parser_9:
9943                     yyaccept = 0;
9944                     yych = *(m_marker = ++m_cursor);
9945                     if (yych <= 0x1F)
9946                     {
9947                         goto basic_json_parser_5;
9948                     }
9949                     if (yych <= 0x7F)
9950                     {
9951                         goto basic_json_parser_31;
9952                     }
9953                     if (yych <= 0xC1)
9954                     {
9955                         goto basic_json_parser_5;
9956                     }
9957                     if (yych <= 0xF4)
9958                     {
9959                         goto basic_json_parser_31;
9960                     }
9961                     goto basic_json_parser_5;
9962 basic_json_parser_10:
9963                     ++m_cursor;
9964                     {
9965                         last_token_type = token_type::value_separator;
9966                         break;
9967                     }
9968 basic_json_parser_12:
9969                     yych = *++m_cursor;
9970                     if (yych <= '/')
9971                     {
9972                         goto basic_json_parser_5;
9973                     }
9974                     if (yych <= '0')
9975                     {
9976                         goto basic_json_parser_43;
9977                     }
9978                     if (yych <= '9')
9979                     {
9980                         goto basic_json_parser_45;
9981                     }
9982                     goto basic_json_parser_5;
9983 basic_json_parser_13:
9984                     yyaccept = 1;
9985                     yych = *(m_marker = ++m_cursor);
9986                     if (yych <= '9')
9987                     {
9988                         if (yych == '.')
9989                         {
9990                             goto basic_json_parser_47;
9991                         }
9992                         if (yych >= '0')
9993                         {
9994                             goto basic_json_parser_48;
9995                         }
9996                     }
9997                     else
9998                     {
9999                         if (yych <= 'E')
10000                         {
10001                             if (yych >= 'E')
10002                             {
10003                                 goto basic_json_parser_51;
10004                             }
10005                         }
10006                         else
10007                         {
10008                             if (yych == 'e')
10009                             {
10010                                 goto basic_json_parser_51;
10011                             }
10012                         }
10013                     }
10014 basic_json_parser_14:
10015                     {
10016                         last_token_type = token_type::value_unsigned;
10017                         break;
10018                     }
10019 basic_json_parser_15:
10020                     yyaccept = 1;
10021                     m_marker = ++m_cursor;
10022                     if ((m_limit - m_cursor) < 3)
10023                     {
10024                         fill_line_buffer(3);    // LCOV_EXCL_LINE
10025                     }
10026                     yych = *m_cursor;
10027                     if (yybm[0 + yych] & 64)
10028                     {
10029                         goto basic_json_parser_15;
10030                     }
10031                     if (yych <= 'D')
10032                     {
10033                         if (yych == '.')
10034                         {
10035                             goto basic_json_parser_47;
10036                         }
10037                         goto basic_json_parser_14;
10038                     }
10039                     else
10040                     {
10041                         if (yych <= 'E')
10042                         {
10043                             goto basic_json_parser_51;
10044                         }
10045                         if (yych == 'e')
10046                         {
10047                             goto basic_json_parser_51;
10048                         }
10049                         goto basic_json_parser_14;
10050                     }
10051 basic_json_parser_17:
10052                     ++m_cursor;
10053                     {
10054                         last_token_type = token_type::name_separator;
10055                         break;
10056                     }
10057 basic_json_parser_19:
10058                     ++m_cursor;
10059                     {
10060                         last_token_type = token_type::begin_array;
10061                         break;
10062                     }
10063 basic_json_parser_21:
10064                     ++m_cursor;
10065                     {
10066                         last_token_type = token_type::end_array;
10067                         break;
10068                     }
10069 basic_json_parser_23:
10070                     yyaccept = 0;
10071                     yych = *(m_marker = ++m_cursor);
10072                     if (yych == 'a')
10073                     {
10074                         goto basic_json_parser_52;
10075                     }
10076                     goto basic_json_parser_5;
10077 basic_json_parser_24:
10078                     yyaccept = 0;
10079                     yych = *(m_marker = ++m_cursor);
10080                     if (yych == 'u')
10081                     {
10082                         goto basic_json_parser_53;
10083                     }
10084                     goto basic_json_parser_5;
10085 basic_json_parser_25:
10086                     yyaccept = 0;
10087                     yych = *(m_marker = ++m_cursor);
10088                     if (yych == 'r')
10089                     {
10090                         goto basic_json_parser_54;
10091                     }
10092                     goto basic_json_parser_5;
10093 basic_json_parser_26:
10094                     ++m_cursor;
10095                     {
10096                         last_token_type = token_type::begin_object;
10097                         break;
10098                     }
10099 basic_json_parser_28:
10100                     ++m_cursor;
10101                     {
10102                         last_token_type = token_type::end_object;
10103                         break;
10104                     }
10105 basic_json_parser_30:
10106                     ++m_cursor;
10107                     if (m_limit <= m_cursor)
10108                     {
10109                         fill_line_buffer(1);    // LCOV_EXCL_LINE
10110                     }
10111                     yych = *m_cursor;
10112 basic_json_parser_31:
10113                     if (yybm[0 + yych] & 128)
10114                     {
10115                         goto basic_json_parser_30;
10116                     }
10117                     if (yych <= 0xE0)
10118                     {
10119                         if (yych <= '\\')
10120                         {
10121                             if (yych <= 0x1F)
10122                             {
10123                                 goto basic_json_parser_32;
10124                             }
10125                             if (yych <= '"')
10126                             {
10127                                 goto basic_json_parser_33;
10128                             }
10129                             goto basic_json_parser_35;
10130                         }
10131                         else
10132                         {
10133                             if (yych <= 0xC1)
10134                             {
10135                                 goto basic_json_parser_32;
10136                             }
10137                             if (yych <= 0xDF)
10138                             {
10139                                 goto basic_json_parser_36;
10140                             }
10141                             goto basic_json_parser_37;
10142                         }
10143                     }
10144                     else
10145                     {
10146                         if (yych <= 0xEF)
10147                         {
10148                             if (yych == 0xED)
10149                             {
10150                                 goto basic_json_parser_39;
10151                             }
10152                             goto basic_json_parser_38;
10153                         }
10154                         else
10155                         {
10156                             if (yych <= 0xF0)
10157                             {
10158                                 goto basic_json_parser_40;
10159                             }
10160                             if (yych <= 0xF3)
10161                             {
10162                                 goto basic_json_parser_41;
10163                             }
10164                             if (yych <= 0xF4)
10165                             {
10166                                 goto basic_json_parser_42;
10167                             }
10168                         }
10169                     }
10170 basic_json_parser_32:
10171                     m_cursor = m_marker;
10172                     if (yyaccept <= 1)
10173                     {
10174                         if (yyaccept == 0)
10175                         {
10176                             goto basic_json_parser_5;
10177                         }
10178                         else
10179                         {
10180                             goto basic_json_parser_14;
10181                         }
10182                     }
10183                     else
10184                     {
10185                         if (yyaccept == 2)
10186                         {
10187                             goto basic_json_parser_44;
10188                         }
10189                         else
10190                         {
10191                             goto basic_json_parser_58;
10192                         }
10193                     }
10194 basic_json_parser_33:
10195                     ++m_cursor;
10196                     {
10197                         last_token_type = token_type::value_string;
10198                         break;
10199                     }
10200 basic_json_parser_35:
10201                     ++m_cursor;
10202                     if (m_limit <= m_cursor)
10203                     {
10204                         fill_line_buffer(1);    // LCOV_EXCL_LINE
10205                     }
10206                     yych = *m_cursor;
10207                     if (yych <= 'e')
10208                     {
10209                         if (yych <= '/')
10210                         {
10211                             if (yych == '"')
10212                             {
10213                                 goto basic_json_parser_30;
10214                             }
10215                             if (yych <= '.')
10216                             {
10217                                 goto basic_json_parser_32;
10218                             }
10219                             goto basic_json_parser_30;
10220                         }
10221                         else
10222                         {
10223                             if (yych <= '\\')
10224                             {
10225                                 if (yych <= '[')
10226                                 {
10227                                     goto basic_json_parser_32;
10228                                 }
10229                                 goto basic_json_parser_30;
10230                             }
10231                             else
10232                             {
10233                                 if (yych == 'b')
10234                                 {
10235                                     goto basic_json_parser_30;
10236                                 }
10237                                 goto basic_json_parser_32;
10238                             }
10239                         }
10240                     }
10241                     else
10242                     {
10243                         if (yych <= 'q')
10244                         {
10245                             if (yych <= 'f')
10246                             {
10247                                 goto basic_json_parser_30;
10248                             }
10249                             if (yych == 'n')
10250                             {
10251                                 goto basic_json_parser_30;
10252                             }
10253                             goto basic_json_parser_32;
10254                         }
10255                         else
10256                         {
10257                             if (yych <= 's')
10258                             {
10259                                 if (yych <= 'r')
10260                                 {
10261                                     goto basic_json_parser_30;
10262                                 }
10263                                 goto basic_json_parser_32;
10264                             }
10265                             else
10266                             {
10267                                 if (yych <= 't')
10268                                 {
10269                                     goto basic_json_parser_30;
10270                                 }
10271                                 if (yych <= 'u')
10272                                 {
10273                                     goto basic_json_parser_55;
10274                                 }
10275                                 goto basic_json_parser_32;
10276                             }
10277                         }
10278                     }
10279 basic_json_parser_36:
10280                     ++m_cursor;
10281                     if (m_limit <= m_cursor)
10282                     {
10283                         fill_line_buffer(1);    // LCOV_EXCL_LINE
10284                     }
10285                     yych = *m_cursor;
10286                     if (yych <= 0x7F)
10287                     {
10288                         goto basic_json_parser_32;
10289                     }
10290                     if (yych <= 0xBF)
10291                     {
10292                         goto basic_json_parser_30;
10293                     }
10294                     goto basic_json_parser_32;
10295 basic_json_parser_37:
10296                     ++m_cursor;
10297                     if (m_limit <= m_cursor)
10298                     {
10299                         fill_line_buffer(1);    // LCOV_EXCL_LINE
10300                     }
10301                     yych = *m_cursor;
10302                     if (yych <= 0x9F)
10303                     {
10304                         goto basic_json_parser_32;
10305                     }
10306                     if (yych <= 0xBF)
10307                     {
10308                         goto basic_json_parser_36;
10309                     }
10310                     goto basic_json_parser_32;
10311 basic_json_parser_38:
10312                     ++m_cursor;
10313                     if (m_limit <= m_cursor)
10314                     {
10315                         fill_line_buffer(1);    // LCOV_EXCL_LINE
10316                     }
10317                     yych = *m_cursor;
10318                     if (yych <= 0x7F)
10319                     {
10320                         goto basic_json_parser_32;
10321                     }
10322                     if (yych <= 0xBF)
10323                     {
10324                         goto basic_json_parser_36;
10325                     }
10326                     goto basic_json_parser_32;
10327 basic_json_parser_39:
10328                     ++m_cursor;
10329                     if (m_limit <= m_cursor)
10330                     {
10331                         fill_line_buffer(1);    // LCOV_EXCL_LINE
10332                     }
10333                     yych = *m_cursor;
10334                     if (yych <= 0x7F)
10335                     {
10336                         goto basic_json_parser_32;
10337                     }
10338                     if (yych <= 0x9F)
10339                     {
10340                         goto basic_json_parser_36;
10341                     }
10342                     goto basic_json_parser_32;
10343 basic_json_parser_40:
10344                     ++m_cursor;
10345                     if (m_limit <= m_cursor)
10346                     {
10347                         fill_line_buffer(1);    // LCOV_EXCL_LINE
10348                     }
10349                     yych = *m_cursor;
10350                     if (yych <= 0x8F)
10351                     {
10352                         goto basic_json_parser_32;
10353                     }
10354                     if (yych <= 0xBF)
10355                     {
10356                         goto basic_json_parser_38;
10357                     }
10358                     goto basic_json_parser_32;
10359 basic_json_parser_41:
10360                     ++m_cursor;
10361                     if (m_limit <= m_cursor)
10362                     {
10363                         fill_line_buffer(1);    // LCOV_EXCL_LINE
10364                     }
10365                     yych = *m_cursor;
10366                     if (yych <= 0x7F)
10367                     {
10368                         goto basic_json_parser_32;
10369                     }
10370                     if (yych <= 0xBF)
10371                     {
10372                         goto basic_json_parser_38;
10373                     }
10374                     goto basic_json_parser_32;
10375 basic_json_parser_42:
10376                     ++m_cursor;
10377                     if (m_limit <= m_cursor)
10378                     {
10379                         fill_line_buffer(1);    // LCOV_EXCL_LINE
10380                     }
10381                     yych = *m_cursor;
10382                     if (yych <= 0x7F)
10383                     {
10384                         goto basic_json_parser_32;
10385                     }
10386                     if (yych <= 0x8F)
10387                     {
10388                         goto basic_json_parser_38;
10389                     }
10390                     goto basic_json_parser_32;
10391 basic_json_parser_43:
10392                     yyaccept = 2;
10393                     yych = *(m_marker = ++m_cursor);
10394                     if (yych <= '9')
10395                     {
10396                         if (yych == '.')
10397                         {
10398                             goto basic_json_parser_47;
10399                         }
10400                         if (yych >= '0')
10401                         {
10402                             goto basic_json_parser_48;
10403                         }
10404                     }
10405                     else
10406                     {
10407                         if (yych <= 'E')
10408                         {
10409                             if (yych >= 'E')
10410                             {
10411                                 goto basic_json_parser_51;
10412                             }
10413                         }
10414                         else
10415                         {
10416                             if (yych == 'e')
10417                             {
10418                                 goto basic_json_parser_51;
10419                             }
10420                         }
10421                     }
10422 basic_json_parser_44:
10423                     {
10424                         last_token_type = token_type::value_integer;
10425                         break;
10426                     }
10427 basic_json_parser_45:
10428                     yyaccept = 2;
10429                     m_marker = ++m_cursor;
10430                     if ((m_limit - m_cursor) < 3)
10431                     {
10432                         fill_line_buffer(3);    // LCOV_EXCL_LINE
10433                     }
10434                     yych = *m_cursor;
10435                     if (yych <= '9')
10436                     {
10437                         if (yych == '.')
10438                         {
10439                             goto basic_json_parser_47;
10440                         }
10441                         if (yych <= '/')
10442                         {
10443                             goto basic_json_parser_44;
10444                         }
10445                         goto basic_json_parser_45;
10446                     }
10447                     else
10448                     {
10449                         if (yych <= 'E')
10450                         {
10451                             if (yych <= 'D')
10452                             {
10453                                 goto basic_json_parser_44;
10454                             }
10455                             goto basic_json_parser_51;
10456                         }
10457                         else
10458                         {
10459                             if (yych == 'e')
10460                             {
10461                                 goto basic_json_parser_51;
10462                             }
10463                             goto basic_json_parser_44;
10464                         }
10465                     }
10466 basic_json_parser_47:
10467                     yych = *++m_cursor;
10468                     if (yych <= '/')
10469                     {
10470                         goto basic_json_parser_32;
10471                     }
10472                     if (yych <= '9')
10473                     {
10474                         goto basic_json_parser_56;
10475                     }
10476                     goto basic_json_parser_32;
10477 basic_json_parser_48:
10478                     ++m_cursor;
10479                     if (m_limit <= m_cursor)
10480                     {
10481                         fill_line_buffer(1);    // LCOV_EXCL_LINE
10482                     }
10483                     yych = *m_cursor;
10484                     if (yych <= '/')
10485                     {
10486                         goto basic_json_parser_50;
10487                     }
10488                     if (yych <= '9')
10489                     {
10490                         goto basic_json_parser_48;
10491                     }
10492 basic_json_parser_50:
10493                     {
10494                         last_token_type = token_type::parse_error;
10495                         break;
10496                     }
10497 basic_json_parser_51:
10498                     yych = *++m_cursor;
10499                     if (yych <= ',')
10500                     {
10501                         if (yych == '+')
10502                         {
10503                             goto basic_json_parser_59;
10504                         }
10505                         goto basic_json_parser_32;
10506                     }
10507                     else
10508                     {
10509                         if (yych <= '-')
10510                         {
10511                             goto basic_json_parser_59;
10512                         }
10513                         if (yych <= '/')
10514                         {
10515                             goto basic_json_parser_32;
10516                         }
10517                         if (yych <= '9')
10518                         {
10519                             goto basic_json_parser_60;
10520                         }
10521                         goto basic_json_parser_32;
10522                     }
10523 basic_json_parser_52:
10524                     yych = *++m_cursor;
10525                     if (yych == 'l')
10526                     {
10527                         goto basic_json_parser_62;
10528                     }
10529                     goto basic_json_parser_32;
10530 basic_json_parser_53:
10531                     yych = *++m_cursor;
10532                     if (yych == 'l')
10533                     {
10534                         goto basic_json_parser_63;
10535                     }
10536                     goto basic_json_parser_32;
10537 basic_json_parser_54:
10538                     yych = *++m_cursor;
10539                     if (yych == 'u')
10540                     {
10541                         goto basic_json_parser_64;
10542                     }
10543                     goto basic_json_parser_32;
10544 basic_json_parser_55:
10545                     ++m_cursor;
10546                     if (m_limit <= m_cursor)
10547                     {
10548                         fill_line_buffer(1);    // LCOV_EXCL_LINE
10549                     }
10550                     yych = *m_cursor;
10551                     if (yych <= '@')
10552                     {
10553                         if (yych <= '/')
10554                         {
10555                             goto basic_json_parser_32;
10556                         }
10557                         if (yych <= '9')
10558                         {
10559                             goto basic_json_parser_65;
10560                         }
10561                         goto basic_json_parser_32;
10562                     }
10563                     else
10564                     {
10565                         if (yych <= 'F')
10566                         {
10567                             goto basic_json_parser_65;
10568                         }
10569                         if (yych <= '`')
10570                         {
10571                             goto basic_json_parser_32;
10572                         }
10573                         if (yych <= 'f')
10574                         {
10575                             goto basic_json_parser_65;
10576                         }
10577                         goto basic_json_parser_32;
10578                     }
10579 basic_json_parser_56:
10580                     yyaccept = 3;
10581                     m_marker = ++m_cursor;
10582                     if ((m_limit - m_cursor) < 3)
10583                     {
10584                         fill_line_buffer(3);    // LCOV_EXCL_LINE
10585                     }
10586                     yych = *m_cursor;
10587                     if (yych <= 'D')
10588                     {
10589                         if (yych <= '/')
10590                         {
10591                             goto basic_json_parser_58;
10592                         }
10593                         if (yych <= '9')
10594                         {
10595                             goto basic_json_parser_56;
10596                         }
10597                     }
10598                     else
10599                     {
10600                         if (yych <= 'E')
10601                         {
10602                             goto basic_json_parser_51;
10603                         }
10604                         if (yych == 'e')
10605                         {
10606                             goto basic_json_parser_51;
10607                         }
10608                     }
10609 basic_json_parser_58:
10610                     {
10611                         last_token_type = token_type::value_float;
10612                         break;
10613                     }
10614 basic_json_parser_59:
10615                     yych = *++m_cursor;
10616                     if (yych <= '/')
10617                     {
10618                         goto basic_json_parser_32;
10619                     }
10620                     if (yych >= ':')
10621                     {
10622                         goto basic_json_parser_32;
10623                     }
10624 basic_json_parser_60:
10625                     ++m_cursor;
10626                     if (m_limit <= m_cursor)
10627                     {
10628                         fill_line_buffer(1);    // LCOV_EXCL_LINE
10629                     }
10630                     yych = *m_cursor;
10631                     if (yych <= '/')
10632                     {
10633                         goto basic_json_parser_58;
10634                     }
10635                     if (yych <= '9')
10636                     {
10637                         goto basic_json_parser_60;
10638                     }
10639                     goto basic_json_parser_58;
10640 basic_json_parser_62:
10641                     yych = *++m_cursor;
10642                     if (yych == 's')
10643                     {
10644                         goto basic_json_parser_66;
10645                     }
10646                     goto basic_json_parser_32;
10647 basic_json_parser_63:
10648                     yych = *++m_cursor;
10649                     if (yych == 'l')
10650                     {
10651                         goto basic_json_parser_67;
10652                     }
10653                     goto basic_json_parser_32;
10654 basic_json_parser_64:
10655                     yych = *++m_cursor;
10656                     if (yych == 'e')
10657                     {
10658                         goto basic_json_parser_69;
10659                     }
10660                     goto basic_json_parser_32;
10661 basic_json_parser_65:
10662                     ++m_cursor;
10663                     if (m_limit <= m_cursor)
10664                     {
10665                         fill_line_buffer(1);    // LCOV_EXCL_LINE
10666                     }
10667                     yych = *m_cursor;
10668                     if (yych <= '@')
10669                     {
10670                         if (yych <= '/')
10671                         {
10672                             goto basic_json_parser_32;
10673                         }
10674                         if (yych <= '9')
10675                         {
10676                             goto basic_json_parser_71;
10677                         }
10678                         goto basic_json_parser_32;
10679                     }
10680                     else
10681                     {
10682                         if (yych <= 'F')
10683                         {
10684                             goto basic_json_parser_71;
10685                         }
10686                         if (yych <= '`')
10687                         {
10688                             goto basic_json_parser_32;
10689                         }
10690                         if (yych <= 'f')
10691                         {
10692                             goto basic_json_parser_71;
10693                         }
10694                         goto basic_json_parser_32;
10695                     }
10696 basic_json_parser_66:
10697                     yych = *++m_cursor;
10698                     if (yych == 'e')
10699                     {
10700                         goto basic_json_parser_72;
10701                     }
10702                     goto basic_json_parser_32;
10703 basic_json_parser_67:
10704                     ++m_cursor;
10705                     {
10706                         last_token_type = token_type::literal_null;
10707                         break;
10708                     }
10709 basic_json_parser_69:
10710                     ++m_cursor;
10711                     {
10712                         last_token_type = token_type::literal_true;
10713                         break;
10714                     }
10715 basic_json_parser_71:
10716                     ++m_cursor;
10717                     if (m_limit <= m_cursor)
10718                     {
10719                         fill_line_buffer(1);    // LCOV_EXCL_LINE
10720                     }
10721                     yych = *m_cursor;
10722                     if (yych <= '@')
10723                     {
10724                         if (yych <= '/')
10725                         {
10726                             goto basic_json_parser_32;
10727                         }
10728                         if (yych <= '9')
10729                         {
10730                             goto basic_json_parser_74;
10731                         }
10732                         goto basic_json_parser_32;
10733                     }
10734                     else
10735                     {
10736                         if (yych <= 'F')
10737                         {
10738                             goto basic_json_parser_74;
10739                         }
10740                         if (yych <= '`')
10741                         {
10742                             goto basic_json_parser_32;
10743                         }
10744                         if (yych <= 'f')
10745                         {
10746                             goto basic_json_parser_74;
10747                         }
10748                         goto basic_json_parser_32;
10749                     }
10750 basic_json_parser_72:
10751                     ++m_cursor;
10752                     {
10753                         last_token_type = token_type::literal_false;
10754                         break;
10755                     }
10756 basic_json_parser_74:
10757                     ++m_cursor;
10758                     if (m_limit <= m_cursor)
10759                     {
10760                         fill_line_buffer(1);    // LCOV_EXCL_LINE
10761                     }
10762                     yych = *m_cursor;
10763                     if (yych <= '@')
10764                     {
10765                         if (yych <= '/')
10766                         {
10767                             goto basic_json_parser_32;
10768                         }
10769                         if (yych <= '9')
10770                         {
10771                             goto basic_json_parser_30;
10772                         }
10773                         goto basic_json_parser_32;
10774                     }
10775                     else
10776                     {
10777                         if (yych <= 'F')
10778                         {
10779                             goto basic_json_parser_30;
10780                         }
10781                         if (yych <= '`')
10782                         {
10783                             goto basic_json_parser_32;
10784                         }
10785                         if (yych <= 'f')
10786                         {
10787                             goto basic_json_parser_30;
10788                         }
10789                         goto basic_json_parser_32;
10790                     }
10791                 }
10792
10793             }
10794
10795             return last_token_type;
10796         }
10797
10798         /*!
10799         @brief append data from the stream to the line buffer
10800
10801         This function is called by the scan() function when the end of the
10802         buffer (`m_limit`) is reached and the `m_cursor` pointer cannot be
10803         incremented without leaving the limits of the line buffer. Note re2c
10804         decides when to call this function.
10805
10806         If the lexer reads from contiguous storage, there is no trailing null
10807         byte. Therefore, this function must make sure to add these padding
10808         null bytes.
10809
10810         If the lexer reads from an input stream, this function reads the next
10811         line of the input.
10812
10813         @pre
10814             p p p p p p u u u u u x . . . . . .
10815             ^           ^       ^   ^
10816             m_content   m_start |   m_limit
10817                                 m_cursor
10818
10819         @post
10820             u u u u u x x x x x x x . . . . . .
10821             ^       ^               ^
10822             |       m_cursor        m_limit
10823             m_start
10824             m_content
10825         */
10826         void fill_line_buffer(size_t n = 0)
10827         {
10828             // if line buffer is used, m_content points to its data
10829             assert(m_line_buffer.empty()
10830                    or m_content == reinterpret_cast<const lexer_char_t*>(m_line_buffer.data()));
10831
10832             // if line buffer is used, m_limit is set past the end of its data
10833             assert(m_line_buffer.empty()
10834                    or m_limit == m_content + m_line_buffer.size());
10835
10836             // pointer relationships
10837             assert(m_content <= m_start);
10838             assert(m_start <= m_cursor);
10839             assert(m_cursor <= m_limit);
10840             assert(m_marker == nullptr or m_marker  <= m_limit);
10841
10842             // number of processed characters (p)
10843             const auto num_processed_chars = static_cast<size_t>(m_start - m_content);
10844             // offset for m_marker wrt. to m_start
10845             const auto offset_marker = (m_marker == nullptr) ? 0 : m_marker - m_start;
10846             // number of unprocessed characters (u)
10847             const auto offset_cursor = m_cursor - m_start;
10848
10849             // no stream is used or end of file is reached
10850             if (m_stream == nullptr or m_stream->eof())
10851             {
10852                 // m_start may or may not be pointing into m_line_buffer at
10853                 // this point. We trust the standard library to do the right
10854                 // thing. See http://stackoverflow.com/q/28142011/266378
10855                 m_line_buffer.assign(m_start, m_limit);
10856
10857                 // append n characters to make sure that there is sufficient
10858                 // space between m_cursor and m_limit
10859                 m_line_buffer.append(1, '\x00');
10860                 if (n > 0)
10861                 {
10862                     m_line_buffer.append(n - 1, '\x01');
10863                 }
10864             }
10865             else
10866             {
10867                 // delete processed characters from line buffer
10868                 m_line_buffer.erase(0, num_processed_chars);
10869                 // read next line from input stream
10870                 m_line_buffer_tmp.clear();
10871                 std::getline(*m_stream, m_line_buffer_tmp, '\n');
10872
10873                 // add line with newline symbol to the line buffer
10874                 m_line_buffer += m_line_buffer_tmp;
10875                 m_line_buffer.push_back('\n');
10876             }
10877
10878             // set pointers
10879             m_content = reinterpret_cast<const lexer_char_t*>(m_line_buffer.data());
10880             assert(m_content != nullptr);
10881             m_start  = m_content;
10882             m_marker = m_start + offset_marker;
10883             m_cursor = m_start + offset_cursor;
10884             m_limit  = m_start + m_line_buffer.size();
10885         }
10886
10887         /// return string representation of last read token
10888         string_t get_token_string() const
10889         {
10890             assert(m_start != nullptr);
10891             return string_t(reinterpret_cast<typename string_t::const_pointer>(m_start),
10892                             static_cast<size_t>(m_cursor - m_start));
10893         }
10894
10895         /*!
10896         @brief return string value for string tokens
10897
10898         The function iterates the characters between the opening and closing
10899         quotes of the string value. The complete string is the range
10900         [m_start,m_cursor). Consequently, we iterate from m_start+1 to
10901         m_cursor-1.
10902
10903         We differentiate two cases:
10904
10905         1. Escaped characters. In this case, a new character is constructed
10906            according to the nature of the escape. Some escapes create new
10907            characters (e.g., `"\\n"` is replaced by `"\n"`), some are copied
10908            as is (e.g., `"\\\\"`). Furthermore, Unicode escapes of the shape
10909            `"\\uxxxx"` need special care. In this case, to_unicode takes care
10910            of the construction of the values.
10911         2. Unescaped characters are copied as is.
10912
10913         @pre `m_cursor - m_start >= 2`, meaning the length of the last token
10914         is at least 2 bytes which is trivially true for any string (which
10915         consists of at least two quotes).
10916
10917             " c1 c2 c3 ... "
10918             ^                ^
10919             m_start          m_cursor
10920
10921         @complexity Linear in the length of the string.\n
10922
10923         Lemma: The loop body will always terminate.\n
10924
10925         Proof (by contradiction): Assume the loop body does not terminate. As
10926         the loop body does not contain another loop, one of the called
10927         functions must never return. The called functions are `std::strtoul`
10928         and to_unicode. Neither function can loop forever, so the loop body
10929         will never loop forever which contradicts the assumption that the loop
10930         body does not terminate, q.e.d.\n
10931
10932         Lemma: The loop condition for the for loop is eventually false.\n
10933
10934         Proof (by contradiction): Assume the loop does not terminate. Due to
10935         the above lemma, this can only be due to a tautological loop
10936         condition; that is, the loop condition i < m_cursor - 1 must always be
10937         true. Let x be the change of i for any loop iteration. Then
10938         m_start + 1 + x < m_cursor - 1 must hold to loop indefinitely. This
10939         can be rephrased to m_cursor - m_start - 2 > x. With the
10940         precondition, we x <= 0, meaning that the loop condition holds
10941         indefinitely if i is always decreased. However, observe that the value
10942         of i is strictly increasing with each iteration, as it is incremented
10943         by 1 in the iteration expression and never decremented inside the loop
10944         body. Hence, the loop condition will eventually be false which
10945         contradicts the assumption that the loop condition is a tautology,
10946         q.e.d.
10947
10948         @return string value of current token without opening and closing
10949         quotes
10950         @throw std::out_of_range if to_unicode fails
10951         */
10952         string_t get_string() const
10953         {
10954             assert(m_cursor - m_start >= 2);
10955
10956             string_t result;
10957             result.reserve(static_cast<size_t>(m_cursor - m_start - 2));
10958
10959             // iterate the result between the quotes
10960             for (const lexer_char_t* i = m_start + 1; i < m_cursor - 1; ++i)
10961             {
10962                 // find next escape character
10963                 auto e = std::find(i, m_cursor - 1, '\\');
10964                 if (e != i)
10965                 {
10966                     // see https://github.com/nlohmann/json/issues/365#issuecomment-262874705
10967                     for (auto k = i; k < e; k++)
10968                     {
10969                         result.push_back(static_cast<typename string_t::value_type>(*k));
10970                     }
10971                     i = e - 1; // -1 because of ++i
10972                 }
10973                 else
10974                 {
10975                     // processing escaped character
10976                     // read next character
10977                     ++i;
10978
10979                     switch (*i)
10980                     {
10981                         // the default escapes
10982                         case 't':
10983                         {
10984                             result += "\t";
10985                             break;
10986                         }
10987                         case 'b':
10988                         {
10989                             result += "\b";
10990                             break;
10991                         }
10992                         case 'f':
10993                         {
10994                             result += "\f";
10995                             break;
10996                         }
10997                         case 'n':
10998                         {
10999                             result += "\n";
11000                             break;
11001                         }
11002                         case 'r':
11003                         {
11004                             result += "\r";
11005                             break;
11006                         }
11007                         case '\\':
11008                         {
11009                             result += "\\";
11010                             break;
11011                         }
11012                         case '/':
11013                         {
11014                             result += "/";
11015                             break;
11016                         }
11017                         case '"':
11018                         {
11019                             result += "\"";
11020                             break;
11021                         }
11022
11023                         // unicode
11024                         case 'u':
11025                         {
11026                             // get code xxxx from uxxxx
11027                             auto codepoint = std::strtoul(std::string(reinterpret_cast<typename string_t::const_pointer>(i + 1),
11028                                                           4).c_str(), nullptr, 16);
11029
11030                             // check if codepoint is a high surrogate
11031                             if (codepoint >= 0xD800 and codepoint <= 0xDBFF)
11032                             {
11033                                 // make sure there is a subsequent unicode
11034                                 if ((i + 6 >= m_limit) or * (i + 5) != '\\' or * (i + 6) != 'u')
11035                                 {
11036                                     JSON_THROW(std::invalid_argument("missing low surrogate"));
11037                                 }
11038
11039                                 // get code yyyy from uxxxx\uyyyy
11040                                 auto codepoint2 = std::strtoul(std::string(reinterpret_cast<typename string_t::const_pointer>
11041                                                                (i + 7), 4).c_str(), nullptr, 16);
11042                                 result += to_unicode(codepoint, codepoint2);
11043                                 // skip the next 10 characters (xxxx\uyyyy)
11044                                 i += 10;
11045                             }
11046                             else if (codepoint >= 0xDC00 and codepoint <= 0xDFFF)
11047                             {
11048                                 // we found a lone low surrogate
11049                                 JSON_THROW(std::invalid_argument("missing high surrogate"));
11050                             }
11051                             else
11052                             {
11053                                 // add unicode character(s)
11054                                 result += to_unicode(codepoint);
11055                                 // skip the next four characters (xxxx)
11056                                 i += 4;
11057                             }
11058                             break;
11059                         }
11060                     }
11061                 }
11062             }
11063
11064             return result;
11065         }
11066
11067
11068         /*!
11069         @brief parse string into a built-in arithmetic type as if the current
11070                locale is POSIX.
11071
11072         @note in floating-point case strtod may parse past the token's end -
11073               this is not an error
11074
11075         @note any leading blanks are not handled
11076         */
11077         struct strtonum
11078         {
11079           public:
11080             strtonum(const char* start, const char* end)
11081                 : m_start(start), m_end(end)
11082             {}
11083
11084             /*!
11085             @return true iff parsed successfully as number of type T
11086
11087             @param[in,out] val shall contain parsed value, or undefined value
11088             if could not parse
11089             */
11090             template<typename T, typename = typename std::enable_if<std::is_arithmetic<T>::value>::type>
11091             bool to(T& val) const
11092             {
11093                 return parse(val, std::is_integral<T>());
11094             }
11095
11096           private:
11097             const char* const m_start = nullptr;
11098             const char* const m_end = nullptr;
11099
11100             // floating-point conversion
11101
11102             // overloaded wrappers for strtod/strtof/strtold
11103             // that will be called from parse<floating_point_t>
11104             static void strtof(float& f, const char* str, char** endptr)
11105             {
11106                 f = std::strtof(str, endptr);
11107             }
11108
11109             static void strtof(double& f, const char* str, char** endptr)
11110             {
11111                 f = std::strtod(str, endptr);
11112             }
11113
11114             static void strtof(long double& f, const char* str, char** endptr)
11115             {
11116                 f = std::strtold(str, endptr);
11117             }
11118
11119             template<typename T>
11120             bool parse(T& value, /*is_integral=*/std::false_type) const
11121             {
11122                 // replace decimal separator with locale-specific version,
11123                 // when necessary; data will point to either the original
11124                 // string, or buf, or tempstr containing the fixed string.
11125                 std::string tempstr;
11126                 std::array<char, 64> buf;
11127                 const size_t len = static_cast<size_t>(m_end - m_start);
11128
11129                 // lexer will reject empty numbers
11130                 assert(len > 0);
11131
11132                 // since dealing with strtod family of functions, we're
11133                 // getting the decimal point char from the C locale facilities
11134                 // instead of C++'s numpunct facet of the current std::locale
11135                 const auto loc = localeconv();
11136                 assert(loc != nullptr);
11137                 const char decimal_point_char = (loc->decimal_point == nullptr) ? '.' : loc->decimal_point[0];
11138
11139                 const char* data = m_start;
11140
11141                 if (decimal_point_char != '.')
11142                 {
11143                     const size_t ds_pos = static_cast<size_t>(std::find(m_start, m_end, '.') - m_start);
11144
11145                     if (ds_pos != len)
11146                     {
11147                         // copy the data into the local buffer or tempstr, if
11148                         // buffer is too small; replace decimal separator, and
11149                         // update data to point to the modified bytes
11150                         if ((len + 1) < buf.size())
11151                         {
11152                             std::copy(m_start, m_end, buf.begin());
11153                             buf[len] = 0;
11154                             buf[ds_pos] = decimal_point_char;
11155                             data = buf.data();
11156                         }
11157                         else
11158                         {
11159                             tempstr.assign(m_start, m_end);
11160                             tempstr[ds_pos] = decimal_point_char;
11161                             data = tempstr.c_str();
11162                         }
11163                     }
11164                 }
11165
11166                 char* endptr = nullptr;
11167                 value = 0;
11168                 // this calls appropriate overload depending on T
11169                 strtof(value, data, &endptr);
11170
11171                 // parsing was successful iff strtof parsed exactly the number
11172                 // of characters determined by the lexer (len)
11173                 const bool ok = (endptr == (data + len));
11174
11175                 if (ok and (value == static_cast<T>(0.0)) and (*data == '-'))
11176                 {
11177                     // some implementations forget to negate the zero
11178                     value = -0.0;
11179                 }
11180
11181                 return ok;
11182             }
11183
11184             // integral conversion
11185
11186             signed long long parse_integral(char** endptr, /*is_signed*/std::true_type) const
11187             {
11188                 return std::strtoll(m_start, endptr, 10);
11189             }
11190
11191             unsigned long long parse_integral(char** endptr, /*is_signed*/std::false_type) const
11192             {
11193                 return std::strtoull(m_start, endptr, 10);
11194             }
11195
11196             template<typename T>
11197             bool parse(T& value, /*is_integral=*/std::true_type) const
11198             {
11199                 char* endptr = nullptr;
11200                 errno = 0; // these are thread-local
11201                 const auto x = parse_integral(&endptr, std::is_signed<T>());
11202
11203                 // called right overload?
11204                 static_assert(std::is_signed<T>() == std::is_signed<decltype(x)>(), "");
11205
11206                 value = static_cast<T>(x);
11207
11208                 return (x == static_cast<decltype(x)>(value)) // x fits into destination T
11209                        and (x < 0) == (value < 0)             // preserved sign
11210                        //and ((x != 0) or is_integral())        // strto[u]ll did nto fail
11211                        and (errno == 0)                       // strto[u]ll did not overflow
11212                        and (m_start < m_end)                  // token was not empty
11213                        and (endptr == m_end);                 // parsed entire token exactly
11214             }
11215         };
11216
11217         /*!
11218         @brief return number value for number tokens
11219
11220         This function translates the last token into the most appropriate
11221         number type (either integer, unsigned integer or floating point),
11222         which is passed back to the caller via the result parameter.
11223
11224         integral numbers that don't fit into the the range of the respective
11225         type are parsed as number_float_t
11226
11227         floating-point values do not satisfy std::isfinite predicate
11228         are converted to value_t::null
11229
11230         throws if the entire string [m_start .. m_cursor) cannot be
11231         interpreted as a number
11232
11233         @param[out] result  @ref basic_json object to receive the number.
11234         @param[in]  token   the type of the number token
11235         */
11236         bool get_number(basic_json& result, const token_type token) const
11237         {
11238             assert(m_start != nullptr);
11239             assert(m_start < m_cursor);
11240             assert((token == token_type::value_unsigned) or
11241                    (token == token_type::value_integer) or
11242                    (token == token_type::value_float));
11243
11244             strtonum num_converter(reinterpret_cast<const char*>(m_start),
11245                                    reinterpret_cast<const char*>(m_cursor));
11246
11247             switch (token)
11248             {
11249                 case lexer::token_type::value_unsigned:
11250                 {
11251                     number_unsigned_t val;
11252                     if (num_converter.to(val))
11253                     {
11254                         // parsing successful
11255                         result.m_type = value_t::number_unsigned;
11256                         result.m_value = val;
11257                         return true;
11258                     }
11259                     break;
11260                 }
11261
11262                 case lexer::token_type::value_integer:
11263                 {
11264                     number_integer_t val;
11265                     if (num_converter.to(val))
11266                     {
11267                         // parsing successful
11268                         result.m_type = value_t::number_integer;
11269                         result.m_value = val;
11270                         return true;
11271                     }
11272                     break;
11273                 }
11274
11275                 default:
11276                 {
11277                     break;
11278                 }
11279             }
11280
11281             // parse float (either explicitly or because a previous conversion
11282             // failed)
11283             number_float_t val;
11284             if (num_converter.to(val))
11285             {
11286                 // parsing successful
11287                 result.m_type = value_t::number_float;
11288                 result.m_value = val;
11289
11290                 // replace infinity and NAN by null
11291                 if (not std::isfinite(result.m_value.number_float))
11292                 {
11293                     result.m_type  = value_t::null;
11294                     result.m_value = basic_json::json_value();
11295                 }
11296
11297                 return true;
11298             }
11299
11300             // couldn't parse number in any format
11301             return false;
11302         }
11303
11304       private:
11305         /// optional input stream
11306         std::istream* m_stream = nullptr;
11307         /// line buffer buffer for m_stream
11308         string_t m_line_buffer {};
11309         /// used for filling m_line_buffer
11310         string_t m_line_buffer_tmp {};
11311         /// the buffer pointer
11312         const lexer_char_t* m_content = nullptr;
11313         /// pointer to the beginning of the current symbol
11314         const lexer_char_t* m_start = nullptr;
11315         /// pointer for backtracking information
11316         const lexer_char_t* m_marker = nullptr;
11317         /// pointer to the current symbol
11318         const lexer_char_t* m_cursor = nullptr;
11319         /// pointer to the end of the buffer
11320         const lexer_char_t* m_limit = nullptr;
11321         /// the last token type
11322         token_type last_token_type = token_type::end_of_input;
11323     };
11324
11325     /*!
11326     @brief syntax analysis
11327
11328     This class implements a recursive decent parser.
11329     */
11330     class parser
11331     {
11332       public:
11333         /// a parser reading from a string literal
11334         parser(const char* buff, const parser_callback_t cb = nullptr)
11335             : callback(cb),
11336               m_lexer(reinterpret_cast<const typename lexer::lexer_char_t*>(buff), std::strlen(buff))
11337         {}
11338
11339         /// a parser reading from an input stream
11340         parser(std::istream& is, const parser_callback_t cb = nullptr)
11341             : callback(cb), m_lexer(is)
11342         {}
11343
11344         /// a parser reading from an iterator range with contiguous storage
11345         template<class IteratorType, typename std::enable_if<
11346                      std::is_same<typename std::iterator_traits<IteratorType>::iterator_category, std::random_access_iterator_tag>::value
11347                      , int>::type
11348                  = 0>
11349         parser(IteratorType first, IteratorType last, const parser_callback_t cb = nullptr)
11350             : callback(cb),
11351               m_lexer(reinterpret_cast<const typename lexer::lexer_char_t*>(&(*first)),
11352                       static_cast<size_t>(std::distance(first, last)))
11353         {}
11354
11355         /// public parser interface
11356         basic_json parse()
11357         {
11358             // read first token
11359             get_token();
11360
11361             basic_json result = parse_internal(true);
11362             result.assert_invariant();
11363
11364             expect(lexer::token_type::end_of_input);
11365
11366             // return parser result and replace it with null in case the
11367             // top-level value was discarded by the callback function
11368             return result.is_discarded() ? basic_json() : std::move(result);
11369         }
11370
11371       private:
11372         /// the actual parser
11373         basic_json parse_internal(bool keep)
11374         {
11375             auto result = basic_json(value_t::discarded);
11376
11377             switch (last_token)
11378             {
11379                 case lexer::token_type::begin_object:
11380                 {
11381                     if (keep and (not callback
11382                                   or ((keep = callback(depth++, parse_event_t::object_start, result)) != 0)))
11383                     {
11384                         // explicitly set result to object to cope with {}
11385                         result.m_type = value_t::object;
11386                         result.m_value = value_t::object;
11387                     }
11388
11389                     // read next token
11390                     get_token();
11391
11392                     // closing } -> we are done
11393                     if (last_token == lexer::token_type::end_object)
11394                     {
11395                         get_token();
11396                         if (keep and callback and not callback(--depth, parse_event_t::object_end, result))
11397                         {
11398                             result = basic_json(value_t::discarded);
11399                         }
11400                         return result;
11401                     }
11402
11403                     // no comma is expected here
11404                     unexpect(lexer::token_type::value_separator);
11405
11406                     // otherwise: parse key-value pairs
11407                     do
11408                     {
11409                         // ugly, but could be fixed with loop reorganization
11410                         if (last_token == lexer::token_type::value_separator)
11411                         {
11412                             get_token();
11413                         }
11414
11415                         // store key
11416                         expect(lexer::token_type::value_string);
11417                         const auto key = m_lexer.get_string();
11418
11419                         bool keep_tag = false;
11420                         if (keep)
11421                         {
11422                             if (callback)
11423                             {
11424                                 basic_json k(key);
11425                                 keep_tag = callback(depth, parse_event_t::key, k);
11426                             }
11427                             else
11428                             {
11429                                 keep_tag = true;
11430                             }
11431                         }
11432
11433                         // parse separator (:)
11434                         get_token();
11435                         expect(lexer::token_type::name_separator);
11436
11437                         // parse and add value
11438                         get_token();
11439                         auto value = parse_internal(keep);
11440                         if (keep and keep_tag and not value.is_discarded())
11441                         {
11442                             result[key] = std::move(value);
11443                         }
11444                     }
11445                     while (last_token == lexer::token_type::value_separator);
11446
11447                     // closing }
11448                     expect(lexer::token_type::end_object);
11449                     get_token();
11450                     if (keep and callback and not callback(--depth, parse_event_t::object_end, result))
11451                     {
11452                         result = basic_json(value_t::discarded);
11453                     }
11454
11455                     return result;
11456                 }
11457
11458                 case lexer::token_type::begin_array:
11459                 {
11460                     if (keep and (not callback
11461                                   or ((keep = callback(depth++, parse_event_t::array_start, result)) != 0)))
11462                     {
11463                         // explicitly set result to object to cope with []
11464                         result.m_type = value_t::array;
11465                         result.m_value = value_t::array;
11466                     }
11467
11468                     // read next token
11469                     get_token();
11470
11471                     // closing ] -> we are done
11472                     if (last_token == lexer::token_type::end_array)
11473                     {
11474                         get_token();
11475                         if (callback and not callback(--depth, parse_event_t::array_end, result))
11476                         {
11477                             result = basic_json(value_t::discarded);
11478                         }
11479                         return result;
11480                     }
11481
11482                     // no comma is expected here
11483                     unexpect(lexer::token_type::value_separator);
11484
11485                     // otherwise: parse values
11486                     do
11487                     {
11488                         // ugly, but could be fixed with loop reorganization
11489                         if (last_token == lexer::token_type::value_separator)
11490                         {
11491                             get_token();
11492                         }
11493
11494                         // parse value
11495                         auto value = parse_internal(keep);
11496                         if (keep and not value.is_discarded())
11497                         {
11498                             result.push_back(std::move(value));
11499                         }
11500                     }
11501                     while (last_token == lexer::token_type::value_separator);
11502
11503                     // closing ]
11504                     expect(lexer::token_type::end_array);
11505                     get_token();
11506                     if (keep and callback and not callback(--depth, parse_event_t::array_end, result))
11507                     {
11508                         result = basic_json(value_t::discarded);
11509                     }
11510
11511                     return result;
11512                 }
11513
11514                 case lexer::token_type::literal_null:
11515                 {
11516                     get_token();
11517                     result.m_type = value_t::null;
11518                     break;
11519                 }
11520
11521                 case lexer::token_type::value_string:
11522                 {
11523                     const auto s = m_lexer.get_string();
11524                     get_token();
11525                     result = basic_json(s);
11526                     break;
11527                 }
11528
11529                 case lexer::token_type::literal_true:
11530                 {
11531                     get_token();
11532                     result.m_type = value_t::boolean;
11533                     result.m_value = true;
11534                     break;
11535                 }
11536
11537                 case lexer::token_type::literal_false:
11538                 {
11539                     get_token();
11540                     result.m_type = value_t::boolean;
11541                     result.m_value = false;
11542                     break;
11543                 }
11544
11545                 case lexer::token_type::value_unsigned:
11546                 case lexer::token_type::value_integer:
11547                 case lexer::token_type::value_float:
11548                 {
11549                     m_lexer.get_number(result, last_token);
11550                     get_token();
11551                     break;
11552                 }
11553
11554                 default:
11555                 {
11556                     // the last token was unexpected
11557                     unexpect(last_token);
11558                 }
11559             }
11560
11561             if (keep and callback and not callback(depth, parse_event_t::value, result))
11562             {
11563                 result = basic_json(value_t::discarded);
11564             }
11565             return result;
11566         }
11567
11568         /// get next token from lexer
11569         typename lexer::token_type get_token()
11570         {
11571             last_token = m_lexer.scan();
11572             return last_token;
11573         }
11574
11575         void expect(typename lexer::token_type t) const
11576         {
11577             if (t != last_token)
11578             {
11579                 std::string error_msg = "parse error - unexpected ";
11580                 error_msg += (last_token == lexer::token_type::parse_error ? ("'" +  m_lexer.get_token_string() +
11581                               "'") :
11582                               lexer::token_type_name(last_token));
11583                 error_msg += "; expected " + lexer::token_type_name(t);
11584                 JSON_THROW(std::invalid_argument(error_msg));
11585             }
11586         }
11587
11588         void unexpect(typename lexer::token_type t) const
11589         {
11590             if (t == last_token)
11591             {
11592                 std::string error_msg = "parse error - unexpected ";
11593                 error_msg += (last_token == lexer::token_type::parse_error ? ("'" +  m_lexer.get_token_string() +
11594                               "'") :
11595                               lexer::token_type_name(last_token));
11596                 JSON_THROW(std::invalid_argument(error_msg));
11597             }
11598         }
11599
11600       private:
11601         /// current level of recursion
11602         int depth = 0;
11603         /// callback function
11604         const parser_callback_t callback = nullptr;
11605         /// the type of the last read token
11606         typename lexer::token_type last_token = lexer::token_type::uninitialized;
11607         /// the lexer
11608         lexer m_lexer;
11609     };
11610
11611   public:
11612     /*!
11613     @brief JSON Pointer
11614
11615     A JSON pointer defines a string syntax for identifying a specific value
11616     within a JSON document. It can be used with functions `at` and
11617     `operator[]`. Furthermore, JSON pointers are the base for JSON patches.
11618
11619     @sa [RFC 6901](https://tools.ietf.org/html/rfc6901)
11620
11621     @since version 2.0.0
11622     */
11623     class json_pointer
11624     {
11625         /// allow basic_json to access private members
11626         friend class basic_json;
11627
11628       public:
11629         /*!
11630         @brief create JSON pointer
11631
11632         Create a JSON pointer according to the syntax described in
11633         [Section 3 of RFC6901](https://tools.ietf.org/html/rfc6901#section-3).
11634
11635         @param[in] s  string representing the JSON pointer; if omitted, the
11636                       empty string is assumed which references the whole JSON
11637                       value
11638
11639         @throw std::domain_error if reference token is nonempty and does not
11640         begin with a slash (`/`); example: `"JSON pointer must be empty or
11641         begin with /"`
11642         @throw std::domain_error if a tilde (`~`) is not followed by `0`
11643         (representing `~`) or `1` (representing `/`); example: `"escape error:
11644         ~ must be followed with 0 or 1"`
11645
11646         @liveexample{The example shows the construction several valid JSON
11647         pointers as well as the exceptional behavior.,json_pointer}
11648
11649         @since version 2.0.0
11650         */
11651         explicit json_pointer(const std::string& s = "")
11652             : reference_tokens(split(s))
11653         {}
11654
11655         /*!
11656         @brief return a string representation of the JSON pointer
11657
11658         @invariant For each JSON pointer `ptr`, it holds:
11659         @code {.cpp}
11660         ptr == json_pointer(ptr.to_string());
11661         @endcode
11662
11663         @return a string representation of the JSON pointer
11664
11665         @liveexample{The example shows the result of `to_string`.,
11666         json_pointer__to_string}
11667
11668         @since version 2.0.0
11669         */
11670         std::string to_string() const noexcept
11671         {
11672             return std::accumulate(reference_tokens.begin(),
11673                                    reference_tokens.end(), std::string{},
11674                                    [](const std::string & a, const std::string & b)
11675             {
11676                 return a + "/" + escape(b);
11677             });
11678         }
11679
11680         /// @copydoc to_string()
11681         operator std::string() const
11682         {
11683             return to_string();
11684         }
11685
11686       private:
11687         /// remove and return last reference pointer
11688         std::string pop_back()
11689         {
11690             if (is_root())
11691             {
11692                 JSON_THROW(std::domain_error("JSON pointer has no parent"));
11693             }
11694
11695             auto last = reference_tokens.back();
11696             reference_tokens.pop_back();
11697             return last;
11698         }
11699
11700         /// return whether pointer points to the root document
11701         bool is_root() const
11702         {
11703             return reference_tokens.empty();
11704         }
11705
11706         json_pointer top() const
11707         {
11708             if (is_root())
11709             {
11710                 JSON_THROW(std::domain_error("JSON pointer has no parent"));
11711             }
11712
11713             json_pointer result = *this;
11714             result.reference_tokens = {reference_tokens[0]};
11715             return result;
11716         }
11717
11718         /*!
11719         @brief create and return a reference to the pointed to value
11720
11721         @complexity Linear in the number of reference tokens.
11722         */
11723         reference get_and_create(reference j) const
11724         {
11725             pointer result = &j;
11726
11727             // in case no reference tokens exist, return a reference to the
11728             // JSON value j which will be overwritten by a primitive value
11729             for (const auto& reference_token : reference_tokens)
11730             {
11731                 switch (result->m_type)
11732                 {
11733                     case value_t::null:
11734                     {
11735                         if (reference_token == "0")
11736                         {
11737                             // start a new array if reference token is 0
11738                             result = &result->operator[](0);
11739                         }
11740                         else
11741                         {
11742                             // start a new object otherwise
11743                             result = &result->operator[](reference_token);
11744                         }
11745                         break;
11746                     }
11747
11748                     case value_t::object:
11749                     {
11750                         // create an entry in the object
11751                         result = &result->operator[](reference_token);
11752                         break;
11753                     }
11754
11755                     case value_t::array:
11756                     {
11757                         // create an entry in the array
11758                         result = &result->operator[](static_cast<size_type>(std::stoi(reference_token)));
11759                         break;
11760                     }
11761
11762                     /*
11763                     The following code is only reached if there exists a
11764                     reference token _and_ the current value is primitive. In
11765                     this case, we have an error situation, because primitive
11766                     values may only occur as single value; that is, with an
11767                     empty list of reference tokens.
11768                     */
11769                     default:
11770                     {
11771                         JSON_THROW(std::domain_error("invalid value to unflatten"));
11772                     }
11773                 }
11774             }
11775
11776             return *result;
11777         }
11778
11779         /*!
11780         @brief return a reference to the pointed to value
11781
11782         @note This version does not throw if a value is not present, but tries
11783         to create nested values instead. For instance, calling this function
11784         with pointer `"/this/that"` on a null value is equivalent to calling
11785         `operator[]("this").operator[]("that")` on that value, effectively
11786         changing the null value to an object.
11787
11788         @param[in] ptr  a JSON value
11789
11790         @return reference to the JSON value pointed to by the JSON pointer
11791
11792         @complexity Linear in the length of the JSON pointer.
11793
11794         @throw std::out_of_range      if the JSON pointer can not be resolved
11795         @throw std::domain_error      if an array index begins with '0'
11796         @throw std::invalid_argument  if an array index was not a number
11797         */
11798         reference get_unchecked(pointer ptr) const
11799         {
11800             for (const auto& reference_token : reference_tokens)
11801             {
11802                 // convert null values to arrays or objects before continuing
11803                 if (ptr->m_type == value_t::null)
11804                 {
11805                     // check if reference token is a number
11806                     const bool nums = std::all_of(reference_token.begin(),
11807                                                   reference_token.end(),
11808                                                   [](const char x)
11809                     {
11810                         return std::isdigit(x);
11811                     });
11812
11813                     // change value to array for numbers or "-" or to object
11814                     // otherwise
11815                     if (nums or reference_token == "-")
11816                     {
11817                         *ptr = value_t::array;
11818                     }
11819                     else
11820                     {
11821                         *ptr = value_t::object;
11822                     }
11823                 }
11824
11825                 switch (ptr->m_type)
11826                 {
11827                     case value_t::object:
11828                     {
11829                         // use unchecked object access
11830                         ptr = &ptr->operator[](reference_token);
11831                         break;
11832                     }
11833
11834                     case value_t::array:
11835                     {
11836                         // error condition (cf. RFC 6901, Sect. 4)
11837                         if (reference_token.size() > 1 and reference_token[0] == '0')
11838                         {
11839                             JSON_THROW(std::domain_error("array index must not begin with '0'"));
11840                         }
11841
11842                         if (reference_token == "-")
11843                         {
11844                             // explicitly treat "-" as index beyond the end
11845                             ptr = &ptr->operator[](ptr->m_value.array->size());
11846                         }
11847                         else
11848                         {
11849                             // convert array index to number; unchecked access
11850                             ptr = &ptr->operator[](static_cast<size_type>(std::stoi(reference_token)));
11851                         }
11852                         break;
11853                     }
11854
11855                     default:
11856                     {
11857                         JSON_THROW(std::out_of_range("unresolved reference token '" + reference_token + "'"));
11858                     }
11859                 }
11860             }
11861
11862             return *ptr;
11863         }
11864
11865         reference get_checked(pointer ptr) const
11866         {
11867             for (const auto& reference_token : reference_tokens)
11868             {
11869                 switch (ptr->m_type)
11870                 {
11871                     case value_t::object:
11872                     {
11873                         // note: at performs range check
11874                         ptr = &ptr->at(reference_token);
11875                         break;
11876                     }
11877
11878                     case value_t::array:
11879                     {
11880                         if (reference_token == "-")
11881                         {
11882                             // "-" always fails the range check
11883                             JSON_THROW(std::out_of_range("array index '-' (" +
11884                                                          std::to_string(ptr->m_value.array->size()) +
11885                                                          ") is out of range"));
11886                         }
11887
11888                         // error condition (cf. RFC 6901, Sect. 4)
11889                         if (reference_token.size() > 1 and reference_token[0] == '0')
11890                         {
11891                             JSON_THROW(std::domain_error("array index must not begin with '0'"));
11892                         }
11893
11894                         // note: at performs range check
11895                         ptr = &ptr->at(static_cast<size_type>(std::stoi(reference_token)));
11896                         break;
11897                     }
11898
11899                     default:
11900                     {
11901                         JSON_THROW(std::out_of_range("unresolved reference token '" + reference_token + "'"));
11902                     }
11903                 }
11904             }
11905
11906             return *ptr;
11907         }
11908
11909         /*!
11910         @brief return a const reference to the pointed to value
11911
11912         @param[in] ptr  a JSON value
11913
11914         @return const reference to the JSON value pointed to by the JSON
11915                 pointer
11916         */
11917         const_reference get_unchecked(const_pointer ptr) const
11918         {
11919             for (const auto& reference_token : reference_tokens)
11920             {
11921                 switch (ptr->m_type)
11922                 {
11923                     case value_t::object:
11924                     {
11925                         // use unchecked object access
11926                         ptr = &ptr->operator[](reference_token);
11927                         break;
11928                     }
11929
11930                     case value_t::array:
11931                     {
11932                         if (reference_token == "-")
11933                         {
11934                             // "-" cannot be used for const access
11935                             JSON_THROW(std::out_of_range("array index '-' (" +
11936                                                          std::to_string(ptr->m_value.array->size()) +
11937                                                          ") is out of range"));
11938                         }
11939
11940                         // error condition (cf. RFC 6901, Sect. 4)
11941                         if (reference_token.size() > 1 and reference_token[0] == '0')
11942                         {
11943                             JSON_THROW(std::domain_error("array index must not begin with '0'"));
11944                         }
11945
11946                         // use unchecked array access
11947                         ptr = &ptr->operator[](static_cast<size_type>(std::stoi(reference_token)));
11948                         break;
11949                     }
11950
11951                     default:
11952                     {
11953                         JSON_THROW(std::out_of_range("unresolved reference token '" + reference_token + "'"));
11954                     }
11955                 }
11956             }
11957
11958             return *ptr;
11959         }
11960
11961         const_reference get_checked(const_pointer ptr) const
11962         {
11963             for (const auto& reference_token : reference_tokens)
11964             {
11965                 switch (ptr->m_type)
11966                 {
11967                     case value_t::object:
11968                     {
11969                         // note: at performs range check
11970                         ptr = &ptr->at(reference_token);
11971                         break;
11972                     }
11973
11974                     case value_t::array:
11975                     {
11976                         if (reference_token == "-")
11977                         {
11978                             // "-" always fails the range check
11979                             JSON_THROW(std::out_of_range("array index '-' (" +
11980                                                          std::to_string(ptr->m_value.array->size()) +
11981                                                          ") is out of range"));
11982                         }
11983
11984                         // error condition (cf. RFC 6901, Sect. 4)
11985                         if (reference_token.size() > 1 and reference_token[0] == '0')
11986                         {
11987                             JSON_THROW(std::domain_error("array index must not begin with '0'"));
11988                         }
11989
11990                         // note: at performs range check
11991                         ptr = &ptr->at(static_cast<size_type>(std::stoi(reference_token)));
11992                         break;
11993                     }
11994
11995                     default:
11996                     {
11997                         JSON_THROW(std::out_of_range("unresolved reference token '" + reference_token + "'"));
11998                     }
11999                 }
12000             }
12001
12002             return *ptr;
12003         }
12004
12005         /// split the string input to reference tokens
12006         static std::vector<std::string> split(const std::string& reference_string)
12007         {
12008             std::vector<std::string> result;
12009
12010             // special case: empty reference string -> no reference tokens
12011             if (reference_string.empty())
12012             {
12013                 return result;
12014             }
12015
12016             // check if nonempty reference string begins with slash
12017             if (reference_string[0] != '/')
12018             {
12019                 JSON_THROW(std::domain_error("JSON pointer must be empty or begin with '/'"));
12020             }
12021
12022             // extract the reference tokens:
12023             // - slash: position of the last read slash (or end of string)
12024             // - start: position after the previous slash
12025             for (
12026                 // search for the first slash after the first character
12027                 size_t slash = reference_string.find_first_of('/', 1),
12028                 // set the beginning of the first reference token
12029                 start = 1;
12030                 // we can stop if start == string::npos+1 = 0
12031                 start != 0;
12032                 // set the beginning of the next reference token
12033                 // (will eventually be 0 if slash == std::string::npos)
12034                 start = slash + 1,
12035                 // find next slash
12036                 slash = reference_string.find_first_of('/', start))
12037             {
12038                 // use the text between the beginning of the reference token
12039                 // (start) and the last slash (slash).
12040                 auto reference_token = reference_string.substr(start, slash - start);
12041
12042                 // check reference tokens are properly escaped
12043                 for (size_t pos = reference_token.find_first_of('~');
12044                         pos != std::string::npos;
12045                         pos = reference_token.find_first_of('~', pos + 1))
12046                 {
12047                     assert(reference_token[pos] == '~');
12048
12049                     // ~ must be followed by 0 or 1
12050                     if (pos == reference_token.size() - 1 or
12051                             (reference_token[pos + 1] != '0' and
12052                              reference_token[pos + 1] != '1'))
12053                     {
12054                         JSON_THROW(std::domain_error("escape error: '~' must be followed with '0' or '1'"));
12055                     }
12056                 }
12057
12058                 // finally, store the reference token
12059                 unescape(reference_token);
12060                 result.push_back(reference_token);
12061             }
12062
12063             return result;
12064         }
12065
12066       private:
12067         /*!
12068         @brief replace all occurrences of a substring by another string
12069
12070         @param[in,out] s  the string to manipulate; changed so that all
12071                           occurrences of @a f are replaced with @a t
12072         @param[in]     f  the substring to replace with @a t
12073         @param[in]     t  the string to replace @a f
12074
12075         @pre The search string @a f must not be empty.
12076
12077         @since version 2.0.0
12078         */
12079         static void replace_substring(std::string& s,
12080                                       const std::string& f,
12081                                       const std::string& t)
12082         {
12083             assert(not f.empty());
12084
12085             for (
12086                 size_t pos = s.find(f);         // find first occurrence of f
12087                 pos != std::string::npos;       // make sure f was found
12088                 s.replace(pos, f.size(), t),    // replace with t
12089                 pos = s.find(f, pos + t.size()) // find next occurrence of f
12090             );
12091         }
12092
12093         /// escape tilde and slash
12094         static std::string escape(std::string s)
12095         {
12096             // escape "~"" to "~0" and "/" to "~1"
12097             replace_substring(s, "~", "~0");
12098             replace_substring(s, "/", "~1");
12099             return s;
12100         }
12101
12102         /// unescape tilde and slash
12103         static void unescape(std::string& s)
12104         {
12105             // first transform any occurrence of the sequence '~1' to '/'
12106             replace_substring(s, "~1", "/");
12107             // then transform any occurrence of the sequence '~0' to '~'
12108             replace_substring(s, "~0", "~");
12109         }
12110
12111         /*!
12112         @param[in] reference_string  the reference string to the current value
12113         @param[in] value             the value to consider
12114         @param[in,out] result        the result object to insert values to
12115
12116         @note Empty objects or arrays are flattened to `null`.
12117         */
12118         static void flatten(const std::string& reference_string,
12119                             const basic_json& value,
12120                             basic_json& result)
12121         {
12122             switch (value.m_type)
12123             {
12124                 case value_t::array:
12125                 {
12126                     if (value.m_value.array->empty())
12127                     {
12128                         // flatten empty array as null
12129                         result[reference_string] = nullptr;
12130                     }
12131                     else
12132                     {
12133                         // iterate array and use index as reference string
12134                         for (size_t i = 0; i < value.m_value.array->size(); ++i)
12135                         {
12136                             flatten(reference_string + "/" + std::to_string(i),
12137                                     value.m_value.array->operator[](i), result);
12138                         }
12139                     }
12140                     break;
12141                 }
12142
12143                 case value_t::object:
12144                 {
12145                     if (value.m_value.object->empty())
12146                     {
12147                         // flatten empty object as null
12148                         result[reference_string] = nullptr;
12149                     }
12150                     else
12151                     {
12152                         // iterate object and use keys as reference string
12153                         for (const auto& element : *value.m_value.object)
12154                         {
12155                             flatten(reference_string + "/" + escape(element.first),
12156                                     element.second, result);
12157                         }
12158                     }
12159                     break;
12160                 }
12161
12162                 default:
12163                 {
12164                     // add primitive value with its reference string
12165                     result[reference_string] = value;
12166                     break;
12167                 }
12168             }
12169         }
12170
12171         /*!
12172         @param[in] value  flattened JSON
12173
12174         @return unflattened JSON
12175         */
12176         static basic_json unflatten(const basic_json& value)
12177         {
12178             if (not value.is_object())
12179             {
12180                 JSON_THROW(std::domain_error("only objects can be unflattened"));
12181             }
12182
12183             basic_json result;
12184
12185             // iterate the JSON object values
12186             for (const auto& element : *value.m_value.object)
12187             {
12188                 if (not element.second.is_primitive())
12189                 {
12190                     JSON_THROW(std::domain_error("values in object must be primitive"));
12191                 }
12192
12193                 // assign value to reference pointed to by JSON pointer; Note
12194                 // that if the JSON pointer is "" (i.e., points to the whole
12195                 // value), function get_and_create returns a reference to
12196                 // result itself. An assignment will then create a primitive
12197                 // value.
12198                 json_pointer(element.first).get_and_create(result) = element.second;
12199             }
12200
12201             return result;
12202         }
12203
12204       private:
12205         friend bool operator==(json_pointer const& lhs,
12206                                json_pointer const& rhs) noexcept
12207         {
12208             return lhs.reference_tokens == rhs.reference_tokens;
12209         }
12210
12211         friend bool operator!=(json_pointer const& lhs,
12212                                json_pointer const& rhs) noexcept
12213         {
12214             return !(lhs == rhs);
12215         }
12216
12217         /// the reference tokens
12218         std::vector<std::string> reference_tokens {};
12219     };
12220
12221     //////////////////////////
12222     // JSON Pointer support //
12223     //////////////////////////
12224
12225     /// @name JSON Pointer functions
12226     /// @{
12227
12228     /*!
12229     @brief access specified element via JSON Pointer
12230
12231     Uses a JSON pointer to retrieve a reference to the respective JSON value.
12232     No bound checking is performed. Similar to @ref operator[](const typename
12233     object_t::key_type&), `null` values are created in arrays and objects if
12234     necessary.
12235
12236     In particular:
12237     - If the JSON pointer points to an object key that does not exist, it
12238       is created an filled with a `null` value before a reference to it
12239       is returned.
12240     - If the JSON pointer points to an array index that does not exist, it
12241       is created an filled with a `null` value before a reference to it
12242       is returned. All indices between the current maximum and the given
12243       index are also filled with `null`.
12244     - The special value `-` is treated as a synonym for the index past the
12245       end.
12246
12247     @param[in] ptr  a JSON pointer
12248
12249     @return reference to the element pointed to by @a ptr
12250
12251     @complexity Constant.
12252
12253     @throw std::out_of_range      if the JSON pointer can not be resolved
12254     @throw std::domain_error      if an array index begins with '0'
12255     @throw std::invalid_argument  if an array index was not a number
12256
12257     @liveexample{The behavior is shown in the example.,operatorjson_pointer}
12258
12259     @since version 2.0.0
12260     */
12261     reference operator[](const json_pointer& ptr)
12262     {
12263         return ptr.get_unchecked(this);
12264     }
12265
12266     /*!
12267     @brief access specified element via JSON Pointer
12268
12269     Uses a JSON pointer to retrieve a reference to the respective JSON value.
12270     No bound checking is performed. The function does not change the JSON
12271     value; no `null` values are created. In particular, the the special value
12272     `-` yields an exception.
12273
12274     @param[in] ptr  JSON pointer to the desired element
12275
12276     @return const reference to the element pointed to by @a ptr
12277
12278     @complexity Constant.
12279
12280     @throw std::out_of_range      if the JSON pointer can not be resolved
12281     @throw std::domain_error      if an array index begins with '0'
12282     @throw std::invalid_argument  if an array index was not a number
12283
12284     @liveexample{The behavior is shown in the example.,operatorjson_pointer_const}
12285
12286     @since version 2.0.0
12287     */
12288     const_reference operator[](const json_pointer& ptr) const
12289     {
12290         return ptr.get_unchecked(this);
12291     }
12292
12293     /*!
12294     @brief access specified element via JSON Pointer
12295
12296     Returns a reference to the element at with specified JSON pointer @a ptr,
12297     with bounds checking.
12298
12299     @param[in] ptr  JSON pointer to the desired element
12300
12301     @return reference to the element pointed to by @a ptr
12302
12303     @complexity Constant.
12304
12305     @throw std::out_of_range      if the JSON pointer can not be resolved
12306     @throw std::domain_error      if an array index begins with '0'
12307     @throw std::invalid_argument  if an array index was not a number
12308
12309     @liveexample{The behavior is shown in the example.,at_json_pointer}
12310
12311     @since version 2.0.0
12312     */
12313     reference at(const json_pointer& ptr)
12314     {
12315         return ptr.get_checked(this);
12316     }
12317
12318     /*!
12319     @brief access specified element via JSON Pointer
12320
12321     Returns a const reference to the element at with specified JSON pointer @a
12322     ptr, with bounds checking.
12323
12324     @param[in] ptr  JSON pointer to the desired element
12325
12326     @return reference to the element pointed to by @a ptr
12327
12328     @complexity Constant.
12329
12330     @throw std::out_of_range      if the JSON pointer can not be resolved
12331     @throw std::domain_error      if an array index begins with '0'
12332     @throw std::invalid_argument  if an array index was not a number
12333
12334     @liveexample{The behavior is shown in the example.,at_json_pointer_const}
12335
12336     @since version 2.0.0
12337     */
12338     const_reference at(const json_pointer& ptr) const
12339     {
12340         return ptr.get_checked(this);
12341     }
12342
12343     /*!
12344     @brief return flattened JSON value
12345
12346     The function creates a JSON object whose keys are JSON pointers (see [RFC
12347     6901](https://tools.ietf.org/html/rfc6901)) and whose values are all
12348     primitive. The original JSON value can be restored using the @ref
12349     unflatten() function.
12350
12351     @return an object that maps JSON pointers to primitive values
12352
12353     @note Empty objects and arrays are flattened to `null` and will not be
12354           reconstructed correctly by the @ref unflatten() function.
12355
12356     @complexity Linear in the size the JSON value.
12357
12358     @liveexample{The following code shows how a JSON object is flattened to an
12359     object whose keys consist of JSON pointers.,flatten}
12360
12361     @sa @ref unflatten() for the reverse function
12362
12363     @since version 2.0.0
12364     */
12365     basic_json flatten() const
12366     {
12367         basic_json result(value_t::object);
12368         json_pointer::flatten("", *this, result);
12369         return result;
12370     }
12371
12372     /*!
12373     @brief unflatten a previously flattened JSON value
12374
12375     The function restores the arbitrary nesting of a JSON value that has been
12376     flattened before using the @ref flatten() function. The JSON value must
12377     meet certain constraints:
12378     1. The value must be an object.
12379     2. The keys must be JSON pointers (see
12380        [RFC 6901](https://tools.ietf.org/html/rfc6901))
12381     3. The mapped values must be primitive JSON types.
12382
12383     @return the original JSON from a flattened version
12384
12385     @note Empty objects and arrays are flattened by @ref flatten() to `null`
12386           values and can not unflattened to their original type. Apart from
12387           this example, for a JSON value `j`, the following is always true:
12388           `j == j.flatten().unflatten()`.
12389
12390     @complexity Linear in the size the JSON value.
12391
12392     @liveexample{The following code shows how a flattened JSON object is
12393     unflattened into the original nested JSON object.,unflatten}
12394
12395     @sa @ref flatten() for the reverse function
12396
12397     @since version 2.0.0
12398     */
12399     basic_json unflatten() const
12400     {
12401         return json_pointer::unflatten(*this);
12402     }
12403
12404     /// @}
12405
12406     //////////////////////////
12407     // JSON Patch functions //
12408     //////////////////////////
12409
12410     /// @name JSON Patch functions
12411     /// @{
12412
12413     /*!
12414     @brief applies a JSON patch
12415
12416     [JSON Patch](http://jsonpatch.com) defines a JSON document structure for
12417     expressing a sequence of operations to apply to a JSON) document. With
12418     this function, a JSON Patch is applied to the current JSON value by
12419     executing all operations from the patch.
12420
12421     @param[in] json_patch  JSON patch document
12422     @return patched document
12423
12424     @note The application of a patch is atomic: Either all operations succeed
12425           and the patched document is returned or an exception is thrown. In
12426           any case, the original value is not changed: the patch is applied
12427           to a copy of the value.
12428
12429     @throw std::out_of_range if a JSON pointer inside the patch could not
12430     be resolved successfully in the current JSON value; example: `"key baz
12431     not found"`
12432     @throw invalid_argument if the JSON patch is malformed (e.g., mandatory
12433     attributes are missing); example: `"operation add must have member path"`
12434
12435     @complexity Linear in the size of the JSON value and the length of the
12436     JSON patch. As usually only a fraction of the JSON value is affected by
12437     the patch, the complexity can usually be neglected.
12438
12439     @liveexample{The following code shows how a JSON patch is applied to a
12440     value.,patch}
12441
12442     @sa @ref diff -- create a JSON patch by comparing two JSON values
12443
12444     @sa [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902)
12445     @sa [RFC 6901 (JSON Pointer)](https://tools.ietf.org/html/rfc6901)
12446
12447     @since version 2.0.0
12448     */
12449     basic_json patch(const basic_json& json_patch) const
12450     {
12451         // make a working copy to apply the patch to
12452         basic_json result = *this;
12453
12454         // the valid JSON Patch operations
12455         enum class patch_operations {add, remove, replace, move, copy, test, invalid};
12456
12457         const auto get_op = [](const std::string op)
12458         {
12459             if (op == "add")
12460             {
12461                 return patch_operations::add;
12462             }
12463             if (op == "remove")
12464             {
12465                 return patch_operations::remove;
12466             }
12467             if (op == "replace")
12468             {
12469                 return patch_operations::replace;
12470             }
12471             if (op == "move")
12472             {
12473                 return patch_operations::move;
12474             }
12475             if (op == "copy")
12476             {
12477                 return patch_operations::copy;
12478             }
12479             if (op == "test")
12480             {
12481                 return patch_operations::test;
12482             }
12483
12484             return patch_operations::invalid;
12485         };
12486
12487         // wrapper for "add" operation; add value at ptr
12488         const auto operation_add = [&result](json_pointer & ptr, basic_json val)
12489         {
12490             // adding to the root of the target document means replacing it
12491             if (ptr.is_root())
12492             {
12493                 result = val;
12494             }
12495             else
12496             {
12497                 // make sure the top element of the pointer exists
12498                 json_pointer top_pointer = ptr.top();
12499                 if (top_pointer != ptr)
12500                 {
12501                     result.at(top_pointer);
12502                 }
12503
12504                 // get reference to parent of JSON pointer ptr
12505                 const auto last_path = ptr.pop_back();
12506                 basic_json& parent = result[ptr];
12507
12508                 switch (parent.m_type)
12509                 {
12510                     case value_t::null:
12511                     case value_t::object:
12512                     {
12513                         // use operator[] to add value
12514                         parent[last_path] = val;
12515                         break;
12516                     }
12517
12518                     case value_t::array:
12519                     {
12520                         if (last_path == "-")
12521                         {
12522                             // special case: append to back
12523                             parent.push_back(val);
12524                         }
12525                         else
12526                         {
12527                             const auto idx = std::stoi(last_path);
12528                             if (static_cast<size_type>(idx) > parent.size())
12529                             {
12530                                 // avoid undefined behavior
12531                                 JSON_THROW(std::out_of_range("array index " + std::to_string(idx) + " is out of range"));
12532                             }
12533                             else
12534                             {
12535                                 // default case: insert add offset
12536                                 parent.insert(parent.begin() + static_cast<difference_type>(idx), val);
12537                             }
12538                         }
12539                         break;
12540                     }
12541
12542                     default:
12543                     {
12544                         // if there exists a parent it cannot be primitive
12545                         assert(false);  // LCOV_EXCL_LINE
12546                     }
12547                 }
12548             }
12549         };
12550
12551         // wrapper for "remove" operation; remove value at ptr
12552         const auto operation_remove = [&result](json_pointer & ptr)
12553         {
12554             // get reference to parent of JSON pointer ptr
12555             const auto last_path = ptr.pop_back();
12556             basic_json& parent = result.at(ptr);
12557
12558             // remove child
12559             if (parent.is_object())
12560             {
12561                 // perform range check
12562                 auto it = parent.find(last_path);
12563                 if (it != parent.end())
12564                 {
12565                     parent.erase(it);
12566                 }
12567                 else
12568                 {
12569                     JSON_THROW(std::out_of_range("key '" + last_path + "' not found"));
12570                 }
12571             }
12572             else if (parent.is_array())
12573             {
12574                 // note erase performs range check
12575                 parent.erase(static_cast<size_type>(std::stoi(last_path)));
12576             }
12577         };
12578
12579         // type check
12580         if (not json_patch.is_array())
12581         {
12582             // a JSON patch must be an array of objects
12583             JSON_THROW(std::invalid_argument("JSON patch must be an array of objects"));
12584         }
12585
12586         // iterate and apply the operations
12587         for (const auto& val : json_patch)
12588         {
12589             // wrapper to get a value for an operation
12590             const auto get_value = [&val](const std::string & op,
12591                                           const std::string & member,
12592                                           bool string_type) -> basic_json&
12593             {
12594                 // find value
12595                 auto it = val.m_value.object->find(member);
12596
12597                 // context-sensitive error message
12598                 const auto error_msg = (op == "op") ? "operation" : "operation '" + op + "'";
12599
12600                 // check if desired value is present
12601                 if (it == val.m_value.object->end())
12602                 {
12603                     JSON_THROW(std::invalid_argument(error_msg + " must have member '" + member + "'"));
12604                 }
12605
12606                 // check if result is of type string
12607                 if (string_type and not it->second.is_string())
12608                 {
12609                     JSON_THROW(std::invalid_argument(error_msg + " must have string member '" + member + "'"));
12610                 }
12611
12612                 // no error: return value
12613                 return it->second;
12614             };
12615
12616             // type check
12617             if (not val.is_object())
12618             {
12619                 JSON_THROW(std::invalid_argument("JSON patch must be an array of objects"));
12620             }
12621
12622             // collect mandatory members
12623             const std::string op = get_value("op", "op", true);
12624             const std::string path = get_value(op, "path", true);
12625             json_pointer ptr(path);
12626
12627             switch (get_op(op))
12628             {
12629                 case patch_operations::add:
12630                 {
12631                     operation_add(ptr, get_value("add", "value", false));
12632                     break;
12633                 }
12634
12635                 case patch_operations::remove:
12636                 {
12637                     operation_remove(ptr);
12638                     break;
12639                 }
12640
12641                 case patch_operations::replace:
12642                 {
12643                     // the "path" location must exist - use at()
12644                     result.at(ptr) = get_value("replace", "value", false);
12645                     break;
12646                 }
12647
12648                 case patch_operations::move:
12649                 {
12650                     const std::string from_path = get_value("move", "from", true);
12651                     json_pointer from_ptr(from_path);
12652
12653                     // the "from" location must exist - use at()
12654                     basic_json v = result.at(from_ptr);
12655
12656                     // The move operation is functionally identical to a
12657                     // "remove" operation on the "from" location, followed
12658                     // immediately by an "add" operation at the target
12659                     // location with the value that was just removed.
12660                     operation_remove(from_ptr);
12661                     operation_add(ptr, v);
12662                     break;
12663                 }
12664
12665                 case patch_operations::copy:
12666                 {
12667                     const std::string from_path = get_value("copy", "from", true);;
12668                     const json_pointer from_ptr(from_path);
12669
12670                     // the "from" location must exist - use at()
12671                     result[ptr] = result.at(from_ptr);
12672                     break;
12673                 }
12674
12675                 case patch_operations::test:
12676                 {
12677                     bool success = false;
12678                     JSON_TRY
12679                     {
12680                         // check if "value" matches the one at "path"
12681                         // the "path" location must exist - use at()
12682                         success = (result.at(ptr) == get_value("test", "value", false));
12683                     }
12684                     JSON_CATCH (std::out_of_range&)
12685                     {
12686                         // ignore out of range errors: success remains false
12687                     }
12688
12689                     // throw an exception if test fails
12690                     if (not success)
12691                     {
12692                         JSON_THROW(std::domain_error("unsuccessful: " + val.dump()));
12693                     }
12694
12695                     break;
12696                 }
12697
12698                 case patch_operations::invalid:
12699                 {
12700                     // op must be "add", "remove", "replace", "move", "copy", or
12701                     // "test"
12702                     JSON_THROW(std::invalid_argument("operation value '" + op + "' is invalid"));
12703                 }
12704             }
12705         }
12706
12707         return result;
12708     }
12709
12710     /*!
12711     @brief creates a diff as a JSON patch
12712
12713     Creates a [JSON Patch](http://jsonpatch.com) so that value @a source can
12714     be changed into the value @a target by calling @ref patch function.
12715
12716     @invariant For two JSON values @a source and @a target, the following code
12717     yields always `true`:
12718     @code {.cpp}
12719     source.patch(diff(source, target)) == target;
12720     @endcode
12721
12722     @note Currently, only `remove`, `add`, and `replace` operations are
12723           generated.
12724
12725     @param[in] source  JSON value to compare from
12726     @param[in] target  JSON value to compare against
12727     @param[in] path    helper value to create JSON pointers
12728
12729     @return a JSON patch to convert the @a source to @a target
12730
12731     @complexity Linear in the lengths of @a source and @a target.
12732
12733     @liveexample{The following code shows how a JSON patch is created as a
12734     diff for two JSON values.,diff}
12735
12736     @sa @ref patch -- apply a JSON patch
12737
12738     @sa [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902)
12739
12740     @since version 2.0.0
12741     */
12742     static basic_json diff(const basic_json& source,
12743                            const basic_json& target,
12744                            const std::string& path = "")
12745     {
12746         // the patch
12747         basic_json result(value_t::array);
12748
12749         // if the values are the same, return empty patch
12750         if (source == target)
12751         {
12752             return result;
12753         }
12754
12755         if (source.type() != target.type())
12756         {
12757             // different types: replace value
12758             result.push_back(
12759             {
12760                 {"op", "replace"},
12761                 {"path", path},
12762                 {"value", target}
12763             });
12764         }
12765         else
12766         {
12767             switch (source.type())
12768             {
12769                 case value_t::array:
12770                 {
12771                     // first pass: traverse common elements
12772                     size_t i = 0;
12773                     while (i < source.size() and i < target.size())
12774                     {
12775                         // recursive call to compare array values at index i
12776                         auto temp_diff = diff(source[i], target[i], path + "/" + std::to_string(i));
12777                         result.insert(result.end(), temp_diff.begin(), temp_diff.end());
12778                         ++i;
12779                     }
12780
12781                     // i now reached the end of at least one array
12782                     // in a second pass, traverse the remaining elements
12783
12784                     // remove my remaining elements
12785                     const auto end_index = static_cast<difference_type>(result.size());
12786                     while (i < source.size())
12787                     {
12788                         // add operations in reverse order to avoid invalid
12789                         // indices
12790                         result.insert(result.begin() + end_index, object(
12791                         {
12792                             {"op", "remove"},
12793                             {"path", path + "/" + std::to_string(i)}
12794                         }));
12795                         ++i;
12796                     }
12797
12798                     // add other remaining elements
12799                     while (i < target.size())
12800                     {
12801                         result.push_back(
12802                         {
12803                             {"op", "add"},
12804                             {"path", path + "/" + std::to_string(i)},
12805                             {"value", target[i]}
12806                         });
12807                         ++i;
12808                     }
12809
12810                     break;
12811                 }
12812
12813                 case value_t::object:
12814                 {
12815                     // first pass: traverse this object's elements
12816                     for (auto it = source.begin(); it != source.end(); ++it)
12817                     {
12818                         // escape the key name to be used in a JSON patch
12819                         const auto key = json_pointer::escape(it.key());
12820
12821                         if (target.find(it.key()) != target.end())
12822                         {
12823                             // recursive call to compare object values at key it
12824                             auto temp_diff = diff(it.value(), target[it.key()], path + "/" + key);
12825                             result.insert(result.end(), temp_diff.begin(), temp_diff.end());
12826                         }
12827                         else
12828                         {
12829                             // found a key that is not in o -> remove it
12830                             result.push_back(object(
12831                             {
12832                                 {"op", "remove"},
12833                                 {"path", path + "/" + key}
12834                             }));
12835                         }
12836                     }
12837
12838                     // second pass: traverse other object's elements
12839                     for (auto it = target.begin(); it != target.end(); ++it)
12840                     {
12841                         if (source.find(it.key()) == source.end())
12842                         {
12843                             // found a key that is not in this -> add it
12844                             const auto key = json_pointer::escape(it.key());
12845                             result.push_back(
12846                             {
12847                                 {"op", "add"},
12848                                 {"path", path + "/" + key},
12849                                 {"value", it.value()}
12850                             });
12851                         }
12852                     }
12853
12854                     break;
12855                 }
12856
12857                 default:
12858                 {
12859                     // both primitive type: replace value
12860                     result.push_back(
12861                     {
12862                         {"op", "replace"},
12863                         {"path", path},
12864                         {"value", target}
12865                     });
12866                     break;
12867                 }
12868             }
12869         }
12870
12871         return result;
12872     }
12873
12874     /// @}
12875 };
12876
12877 /////////////
12878 // presets //
12879 /////////////
12880
12881 /*!
12882 @brief default JSON class
12883
12884 This type is the default specialization of the @ref basic_json class which
12885 uses the standard template types.
12886
12887 @since version 1.0.0
12888 */
12889 using json = basic_json<>;
12890 } // namespace nlohmann
12891
12892
12893 ///////////////////////
12894 // nonmember support //
12895 ///////////////////////
12896
12897 // specialization of std::swap, and std::hash
12898 namespace std
12899 {
12900 /*!
12901 @brief exchanges the values of two JSON objects
12902
12903 @since version 1.0.0
12904 */
12905 template<>
12906 inline void swap(nlohmann::json& j1,
12907                  nlohmann::json& j2) noexcept(
12908                      is_nothrow_move_constructible<nlohmann::json>::value and
12909                      is_nothrow_move_assignable<nlohmann::json>::value
12910                  )
12911 {
12912     j1.swap(j2);
12913 }
12914
12915 /// hash value for JSON objects
12916 template<>
12917 struct hash<nlohmann::json>
12918 {
12919     /*!
12920     @brief return a hash value for a JSON object
12921
12922     @since version 1.0.0
12923     */
12924     std::size_t operator()(const nlohmann::json& j) const
12925     {
12926         // a naive hashing via the string representation
12927         const auto& h = hash<nlohmann::json::string_t>();
12928         return h(j.dump());
12929     }
12930 };
12931 } // namespace std
12932
12933 /*!
12934 @brief user-defined string literal for JSON values
12935
12936 This operator implements a user-defined string literal for JSON objects. It
12937 can be used by adding `"_json"` to a string literal and returns a JSON object
12938 if no parse error occurred.
12939
12940 @param[in] s  a string representation of a JSON object
12941 @param[in] n  the length of string @a s
12942 @return a JSON object
12943
12944 @since version 1.0.0
12945 */
12946 inline nlohmann::json operator "" _json(const char* s, std::size_t n)
12947 {
12948     return nlohmann::json::parse(s, s + n);
12949 }
12950
12951 /*!
12952 @brief user-defined string literal for JSON pointer
12953
12954 This operator implements a user-defined string literal for JSON Pointers. It
12955 can be used by adding `"_json_pointer"` to a string literal and returns a JSON pointer
12956 object if no parse error occurred.
12957
12958 @param[in] s  a string representation of a JSON Pointer
12959 @param[in] n  the length of string @a s
12960 @return a JSON pointer object
12961
12962 @since version 2.0.0
12963 */
12964 inline nlohmann::json::json_pointer operator "" _json_pointer(const char* s, std::size_t n)
12965 {
12966     return nlohmann::json::json_pointer(std::string(s, n));
12967 }
12968
12969 // clean up
12970 #undef JSON_CATCH
12971 #undef JSON_DEPRECATED
12972 #undef JSON_THROW
12973 #undef JSON_TRY
12974
12975 #endif