Logo ROOT   6.14/05
Reference Guide
json.hpp
Go to the documentation of this file.
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 // exclude unsupported compilers
61 #if defined(__clang__)
62  #if (__clang_major__ * 10000 + __clang_minor__ * 100 + __clang_patchlevel__) < 30400
63  #error "unsupported Clang version - see https://github.com/nlohmann/json#supported-compilers"
64  #endif
65 #elif defined(__GNUC__)
66  #if (__GNUC__ * 10000 + __GNUC_MINOR__ * 100 + __GNUC_PATCHLEVEL__) < 40900
67 // #error "unsupported GCC version - see https://github.com/nlohmann/json#supported-compilers"
68  #endif
69 #endif
70 
71 // disable float-equal warnings on GCC/clang
72 #if defined(__clang__) || defined(__GNUC__) || defined(__GNUG__)
73  #pragma GCC diagnostic push
74  #pragma GCC diagnostic ignored "-Wfloat-equal"
75 #endif
76 
77 // disable documentation warnings on clang
78 #if defined(__clang__)
79  #pragma GCC diagnostic push
80  #pragma GCC diagnostic ignored "-Wdocumentation"
81 #endif
82 
83 // allow for portable deprecation warnings
84 #if defined(__clang__) || defined(__GNUC__) || defined(__GNUG__)
85  #define JSON_DEPRECATED __attribute__((deprecated))
86 #elif defined(_MSC_VER)
87  #define JSON_DEPRECATED __declspec(deprecated)
88 #else
89  #define JSON_DEPRECATED
90 #endif
91 
92 // allow to disable exceptions
93 #if not defined(JSON_NOEXCEPTION) || defined(__EXCEPTIONS)
94  #define JSON_THROW(exception) throw exception
95  #define JSON_TRY try
96  #define JSON_CATCH(exception) catch(exception)
97 #else
98  #define JSON_THROW(exception) std::abort()
99  #define JSON_TRY if(true)
100  #define JSON_CATCH(exception) if(false)
101 #endif
102 
103 /*!
104 @brief namespace for Niels Lohmann
105 @see https://github.com/nlohmann
106 @since version 1.0.0
107 */
108 namespace nlohmann
109 {
110 
111 /*!
112 @brief unnamed namespace with internal helper functions
113 
114 This namespace collects some functions that could not be defined inside the
115 @ref basic_json class.
116 
117 @since version 2.1.0
118 */
119 namespace detail
120 {
121 ///////////////////////////
122 // JSON type enumeration //
123 ///////////////////////////
124 
125 /*!
126 @brief the JSON type enumeration
127 
128 This enumeration collects the different JSON types. It is internally used to
129 distinguish the stored values, and the functions @ref basic_json::is_null(),
130 @ref basic_json::is_object(), @ref basic_json::is_array(),
131 @ref basic_json::is_string(), @ref basic_json::is_boolean(),
132 @ref basic_json::is_number() (with @ref basic_json::is_number_integer(),
133 @ref basic_json::is_number_unsigned(), and @ref basic_json::is_number_float()),
134 @ref basic_json::is_discarded(), @ref basic_json::is_primitive(), and
135 @ref basic_json::is_structured() rely on it.
136 
137 @note There are three enumeration entries (number_integer, number_unsigned, and
138 number_float), because the library distinguishes these three types for numbers:
139 @ref basic_json::number_unsigned_t is used for unsigned integers,
140 @ref basic_json::number_integer_t is used for signed integers, and
141 @ref basic_json::number_float_t is used for floating-point numbers or to
142 approximate integers which do not fit in the limits of their respective type.
143 
144 @sa @ref basic_json::basic_json(const value_t value_type) -- create a JSON
145 value with the default value for a given type
146 
147 @since version 1.0.0
148 */
149 enum class value_t : uint8_t
150 {
151  null, ///< null value
152  object, ///< object (unordered set of name/value pairs)
153  array, ///< array (ordered collection of values)
154  string, ///< string value
155  boolean, ///< boolean value
156  number_integer, ///< number value (signed integer)
157  number_unsigned, ///< number value (unsigned integer)
158  number_float, ///< number value (floating-point)
159  discarded ///< discarded by the the parser callback function
160 };
161 
162 /*!
163 @brief comparison operator for JSON types
164 
165 Returns an ordering that is similar to Python:
166 - order: null < boolean < number < object < array < string
167 - furthermore, each type is not smaller than itself
168 
169 @since version 1.0.0
170 */
171 inline bool operator<(const value_t lhs, const value_t rhs) noexcept
172 {
173  static constexpr std::array<uint8_t, 8> order = {{
174  0, // null
175  3, // object
176  4, // array
177  5, // string
178  1, // boolean
179  2, // integer
180  2, // unsigned
181  2, // float
182  }
183  };
184 
185  // discarded values are not comparable
186  if (lhs == value_t::discarded or rhs == value_t::discarded)
187  {
188  return false;
189  }
190 
191  return order[static_cast<std::size_t>(lhs)] <
192  order[static_cast<std::size_t>(rhs)];
193 }
194 
195 
196 /////////////
197 // helpers //
198 /////////////
199 
200 // alias templates to reduce boilerplate
201 template<bool B, typename T = void>
203 
204 template<typename T>
206 
207 // taken from http://stackoverflow.com/a/26936864/266378
208 template<typename T>
209 using is_unscoped_enum =
210  std::integral_constant<bool, std::is_convertible<T, int>::value and
211  std::is_enum<T>::value>;
212 
213 /*
214 Implementation of two C++17 constructs: conjunction, negation. This is needed
215 to avoid evaluating all the traits in a condition
216 
217 For example: not std::is_same<void, T>::value and has_value_type<T>::value
218 will not compile when T = void (on MSVC at least). Whereas
219 conjunction<negation<std::is_same<void, T>>, has_value_type<T>>::value will
220 stop evaluating if negation<...>::value == false
221 
222 Please note that those constructs must be used with caution, since symbols can
223 become very long quickly (which can slow down compilation and cause MSVC
224 internal compiler errors). Only use it when you have to (see example ahead).
225 */
226 template<class...> struct conjunction : std::true_type {};
227 template<class B1> struct conjunction<B1> : B1 {};
228 template<class B1, class... Bn>
229 struct conjunction<B1, Bn...> : std::conditional<bool(B1::value), conjunction<Bn...>, B1>::type {};
230 
231 template<class B> struct negation : std::integral_constant < bool, !B::value > {};
232 
233 // dispatch utility (taken from ranges-v3)
234 template<unsigned N> struct priority_tag : priority_tag < N - 1 > {};
235 template<> struct priority_tag<0> {};
236 
237 
238 //////////////////
239 // constructors //
240 //////////////////
241 
242 template<value_t> struct external_constructor;
243 
244 template<>
246 {
247  template<typename BasicJsonType>
248  static void construct(BasicJsonType& j, typename BasicJsonType::boolean_t b) noexcept
249  {
250  j.m_type = value_t::boolean;
251  j.m_value = b;
252  j.assert_invariant();
253  }
254 };
255 
256 template<>
258 {
259  template<typename BasicJsonType>
260  static void construct(BasicJsonType& j, const typename BasicJsonType::string_t& s)
261  {
262  j.m_type = value_t::string;
263  j.m_value = s;
264  j.assert_invariant();
265  }
266 };
267 
268 template<>
270 {
271  template<typename BasicJsonType>
272  static void construct(BasicJsonType& j, typename BasicJsonType::number_float_t val) noexcept
273  {
274  // replace infinity and NAN by null
275  if (not std::isfinite(val))
276  {
277  j = BasicJsonType{};
278  }
279  else
280  {
281  j.m_type = value_t::number_float;
282  j.m_value = val;
283  }
284  j.assert_invariant();
285  }
286 };
287 
288 template<>
290 {
291  template<typename BasicJsonType>
292  static void construct(BasicJsonType& j, typename BasicJsonType::number_unsigned_t val) noexcept
293  {
294  j.m_type = value_t::number_unsigned;
295  j.m_value = val;
296  j.assert_invariant();
297  }
298 };
299 
300 template<>
302 {
303  template<typename BasicJsonType>
304  static void construct(BasicJsonType& j, typename BasicJsonType::number_integer_t val) noexcept
305  {
306  j.m_type = value_t::number_integer;
307  j.m_value = val;
308  j.assert_invariant();
309  }
310 };
311 
312 template<>
314 {
315  template<typename BasicJsonType>
316  static void construct(BasicJsonType& j, const typename BasicJsonType::array_t& arr)
317  {
318  j.m_type = value_t::array;
319  j.m_value = arr;
320  j.assert_invariant();
321  }
322 
323  template<typename BasicJsonType, typename CompatibleArrayType,
324  enable_if_t<not std::is_same<CompatibleArrayType,
325  typename BasicJsonType::array_t>::value,
326  int> = 0>
327  static void construct(BasicJsonType& j, const CompatibleArrayType& arr)
328  {
329  using std::begin;
330  using std::end;
331  j.m_type = value_t::array;
332  j.m_value.array = j.template create<typename BasicJsonType::array_t>(begin(arr), end(arr));
333  j.assert_invariant();
334  }
335 };
336 
337 template<>
339 {
340  template<typename BasicJsonType>
341  static void construct(BasicJsonType& j, const typename BasicJsonType::object_t& obj)
342  {
343  j.m_type = value_t::object;
344  j.m_value = obj;
345  j.assert_invariant();
346  }
347 
348  template<typename BasicJsonType, typename CompatibleObjectType,
349  enable_if_t<not std::is_same<CompatibleObjectType,
350  typename BasicJsonType::object_t>::value,
351  int> = 0>
352  static void construct(BasicJsonType& j, const CompatibleObjectType& obj)
353  {
354  using std::begin;
355  using std::end;
356 
357  j.m_type = value_t::object;
358  j.m_value.object = j.template create<typename BasicJsonType::object_t>(begin(obj), end(obj));
359  j.assert_invariant();
360  }
361 };
362 
363 
364 ////////////////////////
365 // has_/is_ functions //
366 ////////////////////////
367 
368 /*!
369 @brief Helper to determine whether there's a key_type for T.
370 
371 This helper is used to tell associative containers apart from other containers
372 such as sequence containers. For instance, `std::map` passes the test as it
373 contains a `mapped_type`, whereas `std::vector` fails the test.
374 
375 @sa http://stackoverflow.com/a/7728728/266378
376 @since version 1.0.0, overworked in version 2.0.6
377 */
378 #define NLOHMANN_JSON_HAS_HELPER(type) \
379  template<typename T> struct has_##type { \
380  private: \
381  template<typename U, typename = typename U::type> \
382  static int detect(U &&); \
383  static void detect(...); \
384  public: \
385  static constexpr bool value = \
386  std::is_integral<decltype(detect(std::declval<T>()))>::value; \
387  }
388 
389 NLOHMANN_JSON_HAS_HELPER(mapped_type);
390 NLOHMANN_JSON_HAS_HELPER(key_type);
391 NLOHMANN_JSON_HAS_HELPER(value_type);
392 NLOHMANN_JSON_HAS_HELPER(iterator);
393 
394 #undef NLOHMANN_JSON_HAS_HELPER
395 
396 
397 template<bool B, class RealType, class CompatibleObjectType>
398 struct is_compatible_object_type_impl : std::false_type {};
399 
400 template<class RealType, class CompatibleObjectType>
401 struct is_compatible_object_type_impl<true, RealType, CompatibleObjectType>
402 {
403  static constexpr auto value =
404  std::is_constructible<typename RealType::key_type,
405  typename CompatibleObjectType::key_type>::value and
406  std::is_constructible<typename RealType::mapped_type,
407  typename CompatibleObjectType::mapped_type>::value;
408 };
409 
410 template<class BasicJsonType, class CompatibleObjectType>
412 {
413  static auto constexpr value = is_compatible_object_type_impl <
415  has_mapped_type<CompatibleObjectType>,
416  has_key_type<CompatibleObjectType>>::value,
417  typename BasicJsonType::object_t, CompatibleObjectType >::value;
418 };
419 
420 template<typename BasicJsonType, typename T>
422 {
423  static auto constexpr value = std::is_same<T, typename BasicJsonType::iterator>::value or
424  std::is_same<T, typename BasicJsonType::const_iterator>::value or
425  std::is_same<T, typename BasicJsonType::reverse_iterator>::value or
426  std::is_same<T, typename BasicJsonType::const_reverse_iterator>::value or
427  std::is_same<T, typename BasicJsonType::json_pointer>::value;
428 };
429 
430 template<class BasicJsonType, class CompatibleArrayType>
432 {
433  static auto constexpr value =
436  BasicJsonType, CompatibleArrayType>>,
437  negation<std::is_constructible<typename BasicJsonType::string_t,
438  CompatibleArrayType>>,
440  has_value_type<CompatibleArrayType>,
441  has_iterator<CompatibleArrayType>>::value;
442 };
443 
444 template<bool, typename, typename>
445 struct is_compatible_integer_type_impl : std::false_type {};
446 
447 template<typename RealIntegerType, typename CompatibleNumberIntegerType>
448 struct is_compatible_integer_type_impl<true, RealIntegerType, CompatibleNumberIntegerType>
449 {
450  // is there an assert somewhere on overflows?
451  using RealLimits = std::numeric_limits<RealIntegerType>;
452  using CompatibleLimits = std::numeric_limits<CompatibleNumberIntegerType>;
453 
454  static constexpr auto value =
455  std::is_constructible<RealIntegerType,
456  CompatibleNumberIntegerType>::value and
457  CompatibleLimits::is_integer and
458  RealLimits::is_signed == CompatibleLimits::is_signed;
459 };
460 
461 template<typename RealIntegerType, typename CompatibleNumberIntegerType>
463 {
464  static constexpr auto value =
466  std::is_integral<CompatibleNumberIntegerType>::value and
467  not std::is_same<bool, CompatibleNumberIntegerType>::value,
468  RealIntegerType, CompatibleNumberIntegerType > ::value;
469 };
470 
471 
472 // trait checking if JSONSerializer<T>::from_json(json const&, udt&) exists
473 template<typename BasicJsonType, typename T>
475 {
476  private:
477  // also check the return type of from_json
479  std::declval<BasicJsonType>(), std::declval<T&>()))>::value>>
480  static int detect(U&&);
481  static void detect(...);
482 
483  public:
484  static constexpr bool value = std::is_integral<decltype(
485  detect(std::declval<typename BasicJsonType::template json_serializer<T, void>>()))>::value;
486 };
487 
488 // This trait checks if JSONSerializer<T>::from_json(json const&) exists
489 // this overload is used for non-default-constructible user-defined-types
490 template<typename BasicJsonType, typename T>
492 {
493  private:
494  template <
495  typename U,
496  typename = enable_if_t<std::is_same<
497  T, decltype(uncvref_t<U>::from_json(std::declval<BasicJsonType>()))>::value >>
498  static int detect(U&&);
499  static void detect(...);
500 
501  public:
502  static constexpr bool value = std::is_integral<decltype(detect(
503  std::declval<typename BasicJsonType::template json_serializer<T, void>>()))>::value;
504 };
505 
506 // This trait checks if BasicJsonType::json_serializer<T>::to_json exists
507 template<typename BasicJsonType, typename T>
509 {
510  private:
512  std::declval<BasicJsonType&>(), std::declval<T>()))>
513  static int detect(U&&);
514  static void detect(...);
515 
516  public:
517  static constexpr bool value = std::is_integral<decltype(detect(
518  std::declval<typename BasicJsonType::template json_serializer<T, void>>()))>::value;
519 };
520 
521 
522 /////////////
523 // to_json //
524 /////////////
525 
526 template<typename BasicJsonType, typename T, enable_if_t<
527  std::is_same<T, typename BasicJsonType::boolean_t>::value, int> = 0>
528 void to_json(BasicJsonType& j, T b) noexcept
529 {
531 }
532 
533 template<typename BasicJsonType, typename CompatibleString,
534  enable_if_t<std::is_constructible<typename BasicJsonType::string_t,
535  CompatibleString>::value, int> = 0>
536 void to_json(BasicJsonType& j, const CompatibleString& s)
537 {
539 }
540 
541 template<typename BasicJsonType, typename FloatType,
543 void to_json(BasicJsonType& j, FloatType val) noexcept
544 {
545  external_constructor<value_t::number_float>::construct(j, static_cast<typename BasicJsonType::number_float_t>(val));
546 }
547 
548 template <
549  typename BasicJsonType, typename CompatibleNumberUnsignedType,
550  enable_if_t<is_compatible_integer_type<typename BasicJsonType::number_unsigned_t,
551  CompatibleNumberUnsignedType>::value, int> = 0 >
552 void to_json(BasicJsonType& j, CompatibleNumberUnsignedType val) noexcept
553 {
554  external_constructor<value_t::number_unsigned>::construct(j, static_cast<typename BasicJsonType::number_unsigned_t>(val));
555 }
556 
557 template <
558  typename BasicJsonType, typename CompatibleNumberIntegerType,
559  enable_if_t<is_compatible_integer_type<typename BasicJsonType::number_integer_t,
560  CompatibleNumberIntegerType>::value, int> = 0 >
561 void to_json(BasicJsonType& j, CompatibleNumberIntegerType val) noexcept
562 {
563  external_constructor<value_t::number_integer>::construct(j, static_cast<typename BasicJsonType::number_integer_t>(val));
564 }
565 
566 template<typename BasicJsonType, typename UnscopedEnumType,
568 void to_json(BasicJsonType& j, UnscopedEnumType e) noexcept
569 {
571 }
572 
573 template <
574  typename BasicJsonType, typename CompatibleArrayType,
575  enable_if_t <
577  std::is_same<typename BasicJsonType::array_t, CompatibleArrayType>::value,
578  int > = 0 >
579 void to_json(BasicJsonType& j, const CompatibleArrayType& arr)
580 {
582 }
583 
584 template <
585  typename BasicJsonType, typename CompatibleObjectType,
587  int> = 0 >
588 void to_json(BasicJsonType& j, const CompatibleObjectType& arr)
589 {
591 }
592 
593 
594 ///////////////
595 // from_json //
596 ///////////////
597 
598 // overloads for basic_json template parameters
599 template<typename BasicJsonType, typename ArithmeticType,
601  not std::is_same<ArithmeticType,
602  typename BasicJsonType::boolean_t>::value,
603  int> = 0>
604 void get_arithmetic_value(const BasicJsonType& j, ArithmeticType& val)
605 {
606  switch (static_cast<value_t>(j))
607  {
609  {
610  val = static_cast<ArithmeticType>(
611  *j.template get_ptr<const typename BasicJsonType::number_unsigned_t*>());
612  break;
613  }
615  {
616  val = static_cast<ArithmeticType>(
617  *j.template get_ptr<const typename BasicJsonType::number_integer_t*>());
618  break;
619  }
621  {
622  val = static_cast<ArithmeticType>(
623  *j.template get_ptr<const typename BasicJsonType::number_float_t*>());
624  break;
625  }
626  default:
627  {
628  JSON_THROW(
629  std::domain_error("type must be number, but is " + j.type_name()));
630  }
631  }
632 }
633 
634 template<typename BasicJsonType>
635 void from_json(const BasicJsonType& j, typename BasicJsonType::boolean_t& b)
636 {
637  if (not j.is_boolean())
638  {
639  JSON_THROW(std::domain_error("type must be boolean, but is " + j.type_name()));
640  }
641  b = *j.template get_ptr<const typename BasicJsonType::boolean_t*>();
642 }
643 
644 template<typename BasicJsonType>
645 void from_json(const BasicJsonType& j, typename BasicJsonType::string_t& s)
646 {
647  if (not j.is_string())
648  {
649  JSON_THROW(std::domain_error("type must be string, but is " + j.type_name()));
650  }
651  s = *j.template get_ptr<const typename BasicJsonType::string_t*>();
652 }
653 
654 template<typename BasicJsonType>
655 void from_json(const BasicJsonType& j, typename BasicJsonType::number_float_t& val)
656 {
657  get_arithmetic_value(j, val);
658 }
659 
660 template<typename BasicJsonType>
661 void from_json(const BasicJsonType& j, typename BasicJsonType::number_unsigned_t& val)
662 {
663  get_arithmetic_value(j, val);
664 }
665 
666 template<typename BasicJsonType>
667 void from_json(const BasicJsonType& j, typename BasicJsonType::number_integer_t& val)
668 {
669  get_arithmetic_value(j, val);
670 }
671 
672 template<typename BasicJsonType, typename UnscopedEnumType,
673  enable_if_t<is_unscoped_enum<UnscopedEnumType>::value, int> = 0>
674 void from_json(const BasicJsonType& j, UnscopedEnumType& e)
675 {
677  get_arithmetic_value(j, val);
678  e = static_cast<UnscopedEnumType>(val);
679 }
680 
681 template<typename BasicJsonType>
682 void from_json(const BasicJsonType& j, typename BasicJsonType::array_t& arr)
683 {
684  if (not j.is_array())
685  {
686  JSON_THROW(std::domain_error("type must be array, but is " + j.type_name()));
687  }
688  arr = *j.template get_ptr<const typename BasicJsonType::array_t*>();
689 }
690 
691 // forward_list doesn't have an insert method
692 template<typename BasicJsonType, typename T, typename Allocator>
693 void from_json(const BasicJsonType& j, std::forward_list<T, Allocator>& l)
694 {
695  // do not perform the check when user wants to retrieve jsons
696  // (except when it's null.. ?)
697  if (j.is_null())
698  {
699  JSON_THROW(std::domain_error("type must be array, but is " + j.type_name()));
700  }
701  if (not std::is_same<T, BasicJsonType>::value)
702  {
703  if (not j.is_array())
704  {
705  JSON_THROW(std::domain_error("type must be array, but is " + j.type_name()));
706  }
707  }
708  for (auto it = j.rbegin(), end = j.rend(); it != end; ++it)
709  {
710  l.push_front(it->template get<T>());
711  }
712 }
713 
714 template<typename BasicJsonType, typename CompatibleArrayType>
715 void from_json_array_impl(const BasicJsonType& j, CompatibleArrayType& arr, priority_tag<0>)
716 {
717  using std::begin;
718  using std::end;
719 
720  std::transform(j.begin(), j.end(),
721  std::inserter(arr, end(arr)), [](const BasicJsonType & i)
722  {
723  // get<BasicJsonType>() returns *this, this won't call a from_json
724  // method when value_type is BasicJsonType
725  return i.template get<typename CompatibleArrayType::value_type>();
726  });
727 }
728 
729 template<typename BasicJsonType, typename CompatibleArrayType>
730 auto from_json_array_impl(const BasicJsonType& j, CompatibleArrayType& arr, priority_tag<1>)
731 -> decltype(
732  arr.reserve(std::declval<typename CompatibleArrayType::size_type>()),
733  void())
734 {
735  using std::begin;
736  using std::end;
737 
738  arr.reserve(j.size());
739  std::transform(
740  j.begin(), j.end(), std::inserter(arr, end(arr)), [](const BasicJsonType & i)
741  {
742  // get<BasicJsonType>() returns *this, this won't call a from_json
743  // method when value_type is BasicJsonType
744  return i.template get<typename CompatibleArrayType::value_type>();
745  });
746 }
747 
748 template<typename BasicJsonType, typename CompatibleArrayType,
750  not std::is_same<typename BasicJsonType::array_t, CompatibleArrayType>::value, int> = 0>
751 void from_json(const BasicJsonType& j, CompatibleArrayType& arr)
752 {
753  if (j.is_null())
754  {
755  JSON_THROW(std::domain_error("type must be array, but is " + j.type_name()));
756  }
757 
758  // when T == BasicJsonType, do not check if value_t is correct
759  if (not std::is_same<typename CompatibleArrayType::value_type, BasicJsonType>::value)
760  {
761  if (not j.is_array())
762  {
763  JSON_THROW(std::domain_error("type must be array, but is " + j.type_name()));
764  }
765  }
767 }
768 
769 template<typename BasicJsonType, typename CompatibleObjectType,
770  enable_if_t<is_compatible_object_type<BasicJsonType, CompatibleObjectType>::value, int> = 0>
771 void from_json(const BasicJsonType& j, CompatibleObjectType& obj)
772 {
773  if (not j.is_object())
774  {
775  JSON_THROW(std::domain_error("type must be object, but is " + j.type_name()));
776  }
777 
778  auto inner_object = j.template get_ptr<const typename BasicJsonType::object_t*>();
779  using std::begin;
780  using std::end;
781  // we could avoid the assignment, but this might require a for loop, which
782  // might be less efficient than the container constructor for some
783  // containers (would it?)
784  obj = CompatibleObjectType(begin(*inner_object), end(*inner_object));
785 }
786 
787 // overload for arithmetic types, not chosen for basic_json template arguments
788 // (BooleanType, etc..); note: Is it really necessary to provide explicit
789 // overloads for boolean_t etc. in case of a custom BooleanType which is not
790 // an arithmetic type?
791 template<typename BasicJsonType, typename ArithmeticType,
792  enable_if_t <
793  std::is_arithmetic<ArithmeticType>::value and
794  not std::is_same<ArithmeticType, typename BasicJsonType::number_unsigned_t>::value and
795  not std::is_same<ArithmeticType, typename BasicJsonType::number_integer_t>::value and
796  not std::is_same<ArithmeticType, typename BasicJsonType::number_float_t>::value and
797  not std::is_same<ArithmeticType, typename BasicJsonType::boolean_t>::value,
798  int> = 0>
799 void from_json(const BasicJsonType& j, ArithmeticType& val)
800 {
801  switch (static_cast<value_t>(j))
802  {
804  {
805  val = static_cast<ArithmeticType>(*j.template get_ptr<const typename BasicJsonType::number_unsigned_t*>());
806  break;
807  }
809  {
810  val = static_cast<ArithmeticType>(*j.template get_ptr<const typename BasicJsonType::number_integer_t*>());
811  break;
812  }
814  {
815  val = static_cast<ArithmeticType>(*j.template get_ptr<const typename BasicJsonType::number_float_t*>());
816  break;
817  }
818  case value_t::boolean:
819  {
820  val = static_cast<ArithmeticType>(*j.template get_ptr<const typename BasicJsonType::boolean_t*>());
821  break;
822  }
823  default:
824  {
825  JSON_THROW(std::domain_error("type must be number, but is " + j.type_name()));
826  }
827  }
828 }
829 
831 {
832  private:
833  template<typename BasicJsonType, typename T>
834  auto call(BasicJsonType& j, T&& val, priority_tag<1>) const noexcept(noexcept(to_json(j, std::forward<T>(val))))
835  -> decltype(to_json(j, std::forward<T>(val)), void())
836  {
837  return to_json(j, std::forward<T>(val));
838  }
839 
840  template<typename BasicJsonType, typename T>
841  void call(BasicJsonType&, T&&, priority_tag<0>) const noexcept
842  {
843  static_assert(sizeof(BasicJsonType) == 0,
844  "could not find to_json() method in T's namespace");
845  }
846 
847  public:
848  template<typename BasicJsonType, typename T>
849  void operator()(BasicJsonType& j, T&& val) const
850  noexcept(noexcept(std::declval<to_json_fn>().call(j, std::forward<T>(val), priority_tag<1> {})))
851  {
852  return call(j, std::forward<T>(val), priority_tag<1> {});
853  }
854 };
855 
857 {
858  private:
859  template<typename BasicJsonType, typename T>
860  auto call(const BasicJsonType& j, T& val, priority_tag<1>) const
861  noexcept(noexcept(from_json(j, val)))
862  -> decltype(from_json(j, val), void())
863  {
864  return from_json(j, val);
865  }
866 
867  template<typename BasicJsonType, typename T>
868  void call(const BasicJsonType&, T&, priority_tag<0>) const noexcept
869  {
870  static_assert(sizeof(BasicJsonType) == 0,
871  "could not find from_json() method in T's namespace");
872  }
873 
874  public:
875  template<typename BasicJsonType, typename T>
876  void operator()(const BasicJsonType& j, T& val) const
877  noexcept(noexcept(std::declval<from_json_fn>().call(j, val, priority_tag<1> {})))
878  {
879  return call(j, val, priority_tag<1> {});
880  }
881 };
882 
883 // taken from ranges-v3
884 template<typename T>
886 {
887  static constexpr T value{};
888 };
889 
890 template<typename T>
891 constexpr T static_const<T>::value;
892 } // namespace detail
893 
894 
895 /// namespace to hold default `to_json` / `from_json` functions
896 namespace
897 {
900 }
901 
902 
903 /*!
904 @brief default JSONSerializer template argument
905 
906 This serializer ignores the template arguments and uses ADL
907 ([argument-dependent lookup](http://en.cppreference.com/w/cpp/language/adl))
908 for serialization.
909 */
910 template<typename = void, typename = void>
912 {
913  /*!
914  @brief convert a JSON value to any value type
915 
916  This function is usually called by the `get()` function of the
917  @ref basic_json class (either explicit or via conversion operators).
918 
919  @param[in] j JSON value to read from
920  @param[in,out] val value to write to
921  */
922  template<typename BasicJsonType, typename ValueType>
923  static void from_json(BasicJsonType&& j, ValueType& val) noexcept(
924  noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), val)))
925  {
926  ::nlohmann::from_json(std::forward<BasicJsonType>(j), val);
927  }
928 
929  /*!
930  @brief convert any value type to a JSON value
931 
932  This function is usually called by the constructors of the @ref basic_json
933  class.
934 
935  @param[in,out] j JSON value to write to
936  @param[in] val value to read from
937  */
938  template<typename BasicJsonType, typename ValueType>
939  static void to_json(BasicJsonType& j, ValueType&& val) noexcept(
940  noexcept(::nlohmann::to_json(j, std::forward<ValueType>(val))))
941  {
942  ::nlohmann::to_json(j, std::forward<ValueType>(val));
943  }
944 };
945 
946 
947 /*!
948 @brief a class to store JSON values
949 
950 @tparam ObjectType type for JSON objects (`std::map` by default; will be used
951 in @ref object_t)
952 @tparam ArrayType type for JSON arrays (`std::vector` by default; will be used
953 in @ref array_t)
954 @tparam StringType type for JSON strings and object keys (`std::string` by
955 default; will be used in @ref string_t)
956 @tparam BooleanType type for JSON booleans (`bool` by default; will be used
957 in @ref boolean_t)
958 @tparam NumberIntegerType type for JSON integer numbers (`int64_t` by
959 default; will be used in @ref number_integer_t)
960 @tparam NumberUnsignedType type for JSON unsigned integer numbers (@c
961 `uint64_t` by default; will be used in @ref number_unsigned_t)
962 @tparam NumberFloatType type for JSON floating-point numbers (`double` by
963 default; will be used in @ref number_float_t)
964 @tparam AllocatorType type of the allocator to use (`std::allocator` by
965 default)
966 @tparam JSONSerializer the serializer to resolve internal calls to `to_json()`
967 and `from_json()` (@ref adl_serializer by default)
968 
969 @requirement The class satisfies the following concept requirements:
970 - Basic
971  - [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible):
972  JSON values can be default constructed. The result will be a JSON null
973  value.
974  - [MoveConstructible](http://en.cppreference.com/w/cpp/concept/MoveConstructible):
975  A JSON value can be constructed from an rvalue argument.
976  - [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible):
977  A JSON value can be copy-constructed from an lvalue expression.
978  - [MoveAssignable](http://en.cppreference.com/w/cpp/concept/MoveAssignable):
979  A JSON value van be assigned from an rvalue argument.
980  - [CopyAssignable](http://en.cppreference.com/w/cpp/concept/CopyAssignable):
981  A JSON value can be copy-assigned from an lvalue expression.
982  - [Destructible](http://en.cppreference.com/w/cpp/concept/Destructible):
983  JSON values can be destructed.
984 - Layout
985  - [StandardLayoutType](http://en.cppreference.com/w/cpp/concept/StandardLayoutType):
986  JSON values have
987  [standard layout](http://en.cppreference.com/w/cpp/language/data_members#Standard_layout):
988  All non-static data members are private and standard layout types, the
989  class has no virtual functions or (virtual) base classes.
990 - Library-wide
991  - [EqualityComparable](http://en.cppreference.com/w/cpp/concept/EqualityComparable):
992  JSON values can be compared with `==`, see @ref
993  operator==(const_reference,const_reference).
994  - [LessThanComparable](http://en.cppreference.com/w/cpp/concept/LessThanComparable):
995  JSON values can be compared with `<`, see @ref
996  operator<(const_reference,const_reference).
997  - [Swappable](http://en.cppreference.com/w/cpp/concept/Swappable):
998  Any JSON lvalue or rvalue of can be swapped with any lvalue or rvalue of
999  other compatible types, using unqualified function call @ref swap().
1000  - [NullablePointer](http://en.cppreference.com/w/cpp/concept/NullablePointer):
1001  JSON values can be compared against `std::nullptr_t` objects which are used
1002  to model the `null` value.
1003 - Container
1004  - [Container](http://en.cppreference.com/w/cpp/concept/Container):
1005  JSON values can be used like STL containers and provide iterator access.
1006  - [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer);
1007  JSON values can be used like STL containers and provide reverse iterator
1008  access.
1009 
1010 @invariant The member variables @a m_value and @a m_type have the following
1011 relationship:
1012 - If `m_type == value_t::object`, then `m_value.object != nullptr`.
1013 - If `m_type == value_t::array`, then `m_value.array != nullptr`.
1014 - If `m_type == value_t::string`, then `m_value.string != nullptr`.
1015 The invariants are checked by member function assert_invariant().
1016 
1017 @internal
1018 @note ObjectType trick from http://stackoverflow.com/a/9860911
1019 @endinternal
1020 
1021 @see [RFC 7159: The JavaScript Object Notation (JSON) Data Interchange
1022 Format](http://rfc7159.net/rfc7159)
1023 
1024 @since version 1.0.0
1025 
1026 @nosubgrouping
1027 */
1028 template <
1029  template<typename U, typename V, typename... Args> class ObjectType = std::map,
1030  template<typename U, typename... Args> class ArrayType = std::vector,
1031  class StringType = std::string,
1032  class BooleanType = bool,
1033  class NumberIntegerType = std::int64_t,
1034  class NumberUnsignedType = std::uint64_t,
1035  class NumberFloatType = double,
1036  template<typename U> class AllocatorType = std::allocator,
1037  template<typename T, typename SFINAE = void> class JSONSerializer = adl_serializer
1038  >
1040 {
1041  private:
1042  template<detail::value_t> friend struct detail::external_constructor;
1043  /// workaround type for MSVC
1044  using basic_json_t = basic_json<ObjectType, ArrayType, StringType,
1045  BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType,
1046  AllocatorType, JSONSerializer>;
1047 
1048  public:
1050  // forward declarations
1051  template<typename U> class iter_impl;
1052  template<typename Base> class json_reverse_iterator;
1053  class json_pointer;
1054  template<typename T, typename SFINAE>
1055  using json_serializer = JSONSerializer<T, SFINAE>;
1056 
1057  /////////////////////
1058  // container types //
1059  /////////////////////
1060 
1061  /// @name container types
1062  /// The canonic container types to use @ref basic_json like any other STL
1063  /// container.
1064  /// @{
1065 
1066  /// the type of elements in a basic_json container
1068 
1069  /// the type of an element reference
1071  /// the type of an element const reference
1072  using const_reference = const value_type&;
1073 
1074  /// a type to represent differences between iterators
1075  using difference_type = std::ptrdiff_t;
1076  /// a type to represent container sizes
1077  using size_type = std::size_t;
1078 
1079  /// the allocator type
1080  using allocator_type = AllocatorType<basic_json>;
1081 
1082  /// the type of an element pointer
1083  using pointer = typename std::allocator_traits<allocator_type>::pointer;
1084  /// the type of an element const pointer
1085  using const_pointer = typename std::allocator_traits<allocator_type>::const_pointer;
1086 
1087  /// an iterator for a basic_json container
1089  /// a const iterator for a basic_json container
1091  /// a reverse iterator for a basic_json container
1093  /// a const reverse iterator for a basic_json container
1095 
1096  /// @}
1097 
1098 
1099  /*!
1100  @brief returns the allocator associated with the container
1101  */
1103  {
1104  return allocator_type();
1105  }
1106 
1107  /*!
1108  @brief returns version information on the library
1109 
1110  This function returns a JSON object with information about the library,
1111  including the version number and information on the platform and compiler.
1112 
1113  @return JSON object holding version information
1114  key | description
1115  ----------- | ---------------
1116  `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).
1117  `copyright` | The copyright line for the library as string.
1118  `name` | The name of the library as string.
1119  `platform` | The used platform as string. Possible values are `win32`, `linux`, `apple`, `unix`, and `unknown`.
1120  `url` | The URL of the project as string.
1121  `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).
1122 
1123  @liveexample{The following code shows an example output of the `meta()`
1124  function.,meta}
1125 
1126  @complexity Constant.
1127 
1128  @since 2.1.0
1129  */
1130  static basic_json meta()
1131  {
1132  basic_json result;
1133 
1134  result["copyright"] = "(C) 2013-2017 Niels Lohmann";
1135  result["name"] = "JSON for Modern C++";
1136  result["url"] = "https://github.com/nlohmann/json";
1137  result["version"] =
1138  {
1139  {"string", "2.1.1"},
1140  {"major", 2},
1141  {"minor", 1},
1142  {"patch", 1}
1143  };
1144 
1145 #ifdef _WIN32
1146  result["platform"] = "win32";
1147 #elif defined __linux__
1148  result["platform"] = "linux";
1149 #elif defined __APPLE__
1150  result["platform"] = "apple";
1151 #elif defined __unix__
1152  result["platform"] = "unix";
1153 #else
1154  result["platform"] = "unknown";
1155 #endif
1156 
1157 #if defined(__clang__)
1158  result["compiler"] = {{"family", "clang"}, {"version", __clang_version__}};
1159 #elif defined(__ICC) || defined(__INTEL_COMPILER)
1160  result["compiler"] = {{"family", "icc"}, {"version", __INTEL_COMPILER}};
1161 #elif defined(__GNUC__) || defined(__GNUG__)
1162  result["compiler"] = {{"family", "gcc"}, {"version", std::to_string(__GNUC__) + "." + std::to_string(__GNUC_MINOR__) + "." + std::to_string(__GNUC_PATCHLEVEL__)}};
1163 #elif defined(__HP_cc) || defined(__HP_aCC)
1164  result["compiler"] = "hp"
1165 #elif defined(__IBMCPP__)
1166  result["compiler"] = {{"family", "ilecpp"}, {"version", __IBMCPP__}};
1167 #elif defined(_MSC_VER)
1168  result["compiler"] = {{"family", "msvc"}, {"version", _MSC_VER}};
1169 #elif defined(__PGI)
1170  result["compiler"] = {{"family", "pgcpp"}, {"version", __PGI}};
1171 #elif defined(__SUNPRO_CC)
1172  result["compiler"] = {{"family", "sunpro"}, {"version", __SUNPRO_CC}};
1173 #else
1174  result["compiler"] = {{"family", "unknown"}, {"version", "unknown"}};
1175 #endif
1176 
1177 #ifdef __cplusplus
1178  result["compiler"]["c++"] = std::to_string(__cplusplus);
1179 #else
1180  result["compiler"]["c++"] = "unknown";
1181 #endif
1182  return result;
1183  }
1184 
1185 
1186  ///////////////////////////
1187  // JSON value data types //
1188  ///////////////////////////
1189 
1190  /// @name JSON value data types
1191  /// The data types to store a JSON value. These types are derived from
1192  /// the template arguments passed to class @ref basic_json.
1193  /// @{
1194 
1195  /*!
1196  @brief a type for an object
1197 
1198  [RFC 7159](http://rfc7159.net/rfc7159) describes JSON objects as follows:
1199  > An object is an unordered collection of zero or more name/value pairs,
1200  > where a name is a string and a value is a string, number, boolean, null,
1201  > object, or array.
1202 
1203  To store objects in C++, a type is defined by the template parameters
1204  described below.
1205 
1206  @tparam ObjectType the container to store objects (e.g., `std::map` or
1207  `std::unordered_map`)
1208  @tparam StringType the type of the keys or names (e.g., `std::string`).
1209  The comparison function `std::less<StringType>` is used to order elements
1210  inside the container.
1211  @tparam AllocatorType the allocator to use for objects (e.g.,
1212  `std::allocator`)
1213 
1214  #### Default type
1215 
1216  With the default values for @a ObjectType (`std::map`), @a StringType
1217  (`std::string`), and @a AllocatorType (`std::allocator`), the default
1218  value for @a object_t is:
1219 
1220  @code {.cpp}
1221  std::map<
1222  std::string, // key_type
1223  basic_json, // value_type
1224  std::less<std::string>, // key_compare
1225  std::allocator<std::pair<const std::string, basic_json>> // allocator_type
1226  >
1227  @endcode
1228 
1229  #### Behavior
1230 
1231  The choice of @a object_t influences the behavior of the JSON class. With
1232  the default type, objects have the following behavior:
1233 
1234  - When all names are unique, objects will be interoperable in the sense
1235  that all software implementations receiving that object will agree on
1236  the name-value mappings.
1237  - When the names within an object are not unique, later stored name/value
1238  pairs overwrite previously stored name/value pairs, leaving the used
1239  names unique. For instance, `{"key": 1}` and `{"key": 2, "key": 1}` will
1240  be treated as equal and both stored as `{"key": 1}`.
1241  - Internally, name/value pairs are stored in lexicographical order of the
1242  names. Objects will also be serialized (see @ref dump) in this order.
1243  For instance, `{"b": 1, "a": 2}` and `{"a": 2, "b": 1}` will be stored
1244  and serialized as `{"a": 2, "b": 1}`.
1245  - When comparing objects, the order of the name/value pairs is irrelevant.
1246  This makes objects interoperable in the sense that they will not be
1247  affected by these differences. For instance, `{"b": 1, "a": 2}` and
1248  `{"a": 2, "b": 1}` will be treated as equal.
1249 
1250  #### Limits
1251 
1252  [RFC 7159](http://rfc7159.net/rfc7159) specifies:
1253  > An implementation may set limits on the maximum depth of nesting.
1254 
1255  In this class, the object's limit of nesting is not constraint explicitly.
1256  However, a maximum depth of nesting may be introduced by the compiler or
1257  runtime environment. A theoretical limit can be queried by calling the
1258  @ref max_size function of a JSON object.
1259 
1260  #### Storage
1261 
1262  Objects are stored as pointers in a @ref basic_json type. That is, for any
1263  access to object values, a pointer of type `object_t*` must be
1264  dereferenced.
1265 
1266  @sa @ref array_t -- type for an array value
1267 
1268  @since version 1.0.0
1269 
1270  @note The order name/value pairs are added to the object is *not*
1271  preserved by the library. Therefore, iterating an object may return
1272  name/value pairs in a different order than they were originally stored. In
1273  fact, keys will be traversed in alphabetical order as `std::map` with
1274  `std::less` is used by default. Please note this behavior conforms to [RFC
1275  7159](http://rfc7159.net/rfc7159), because any order implements the
1276  specified "unordered" nature of JSON objects.
1277  */
1278  using object_t = ObjectType<StringType,
1279  basic_json,
1280  std::less<StringType>,
1281  AllocatorType<std::pair<const StringType,
1282  basic_json>>>;
1283 
1284  /*!
1285  @brief a type for an array
1286 
1287  [RFC 7159](http://rfc7159.net/rfc7159) describes JSON arrays as follows:
1288  > An array is an ordered sequence of zero or more values.
1289 
1290  To store objects in C++, a type is defined by the template parameters
1291  explained below.
1292 
1293  @tparam ArrayType container type to store arrays (e.g., `std::vector` or
1294  `std::list`)
1295  @tparam AllocatorType allocator to use for arrays (e.g., `std::allocator`)
1296 
1297  #### Default type
1298 
1299  With the default values for @a ArrayType (`std::vector`) and @a
1300  AllocatorType (`std::allocator`), the default value for @a array_t is:
1301 
1302  @code {.cpp}
1303  std::vector<
1304  basic_json, // value_type
1305  std::allocator<basic_json> // allocator_type
1306  >
1307  @endcode
1308 
1309  #### Limits
1310 
1311  [RFC 7159](http://rfc7159.net/rfc7159) specifies:
1312  > An implementation may set limits on the maximum depth of nesting.
1313 
1314  In this class, the array's limit of nesting is not constraint explicitly.
1315  However, a maximum depth of nesting may be introduced by the compiler or
1316  runtime environment. A theoretical limit can be queried by calling the
1317  @ref max_size function of a JSON array.
1318 
1319  #### Storage
1320 
1321  Arrays are stored as pointers in a @ref basic_json type. That is, for any
1322  access to array values, a pointer of type `array_t*` must be dereferenced.
1323 
1324  @sa @ref object_t -- type for an object value
1325 
1326  @since version 1.0.0
1327  */
1328  using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;
1329 
1330  /*!
1331  @brief a type for a string
1332 
1333  [RFC 7159](http://rfc7159.net/rfc7159) describes JSON strings as follows:
1334  > A string is a sequence of zero or more Unicode characters.
1335 
1336  To store objects in C++, a type is defined by the template parameter
1337  described below. Unicode values are split by the JSON class into
1338  byte-sized characters during deserialization.
1339 
1340  @tparam StringType the container to store strings (e.g., `std::string`).
1341  Note this container is used for keys/names in objects, see @ref object_t.
1342 
1343  #### Default type
1344 
1345  With the default values for @a StringType (`std::string`), the default
1346  value for @a string_t is:
1347 
1348  @code {.cpp}
1349  std::string
1350  @endcode
1351 
1352  #### Encoding
1353 
1354  Strings are stored in UTF-8 encoding. Therefore, functions like
1355  `std::string::size()` or `std::string::length()` return the number of
1356  bytes in the string rather than the number of characters or glyphs.
1357 
1358  #### String comparison
1359 
1360  [RFC 7159](http://rfc7159.net/rfc7159) states:
1361  > Software implementations are typically required to test names of object
1362  > members for equality. Implementations that transform the textual
1363  > representation into sequences of Unicode code units and then perform the
1364  > comparison numerically, code unit by code unit, are interoperable in the
1365  > sense that implementations will agree in all cases on equality or
1366  > inequality of two strings. For example, implementations that compare
1367  > strings with escaped characters unconverted may incorrectly find that
1368  > `"a\\b"` and `"a\u005Cb"` are not equal.
1369 
1370  This implementation is interoperable as it does compare strings code unit
1371  by code unit.
1372 
1373  #### Storage
1374 
1375  String values are stored as pointers in a @ref basic_json type. That is,
1376  for any access to string values, a pointer of type `string_t*` must be
1377  dereferenced.
1378 
1379  @since version 1.0.0
1380  */
1381  using string_t = StringType;
1382 
1383  /*!
1384  @brief a type for a boolean
1385 
1386  [RFC 7159](http://rfc7159.net/rfc7159) implicitly describes a boolean as a
1387  type which differentiates the two literals `true` and `false`.
1388 
1389  To store objects in C++, a type is defined by the template parameter @a
1390  BooleanType which chooses the type to use.
1391 
1392  #### Default type
1393 
1394  With the default values for @a BooleanType (`bool`), the default value for
1395  @a boolean_t is:
1396 
1397  @code {.cpp}
1398  bool
1399  @endcode
1400 
1401  #### Storage
1402 
1403  Boolean values are stored directly inside a @ref basic_json type.
1404 
1405  @since version 1.0.0
1406  */
1407  using boolean_t = BooleanType;
1408 
1409  /*!
1410  @brief a type for a number (integer)
1411 
1412  [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
1413  > The representation of numbers is similar to that used in most
1414  > programming languages. A number is represented in base 10 using decimal
1415  > digits. It contains an integer component that may be prefixed with an
1416  > optional minus sign, which may be followed by a fraction part and/or an
1417  > exponent part. Leading zeros are not allowed. (...) Numeric values that
1418  > cannot be represented in the grammar below (such as Infinity and NaN)
1419  > are not permitted.
1420 
1421  This description includes both integer and floating-point numbers.
1422  However, C++ allows more precise storage if it is known whether the number
1423  is a signed integer, an unsigned integer or a floating-point number.
1424  Therefore, three different types, @ref number_integer_t, @ref
1425  number_unsigned_t and @ref number_float_t are used.
1426 
1427  To store integer numbers in C++, a type is defined by the template
1428  parameter @a NumberIntegerType which chooses the type to use.
1429 
1430  #### Default type
1431 
1432  With the default values for @a NumberIntegerType (`int64_t`), the default
1433  value for @a number_integer_t is:
1434 
1435  @code {.cpp}
1436  int64_t
1437  @endcode
1438 
1439  #### Default behavior
1440 
1441  - The restrictions about leading zeros is not enforced in C++. Instead,
1442  leading zeros in integer literals lead to an interpretation as octal
1443  number. Internally, the value will be stored as decimal number. For
1444  instance, the C++ integer literal `010` will be serialized to `8`.
1445  During deserialization, leading zeros yield an error.
1446  - Not-a-number (NaN) values will be serialized to `null`.
1447 
1448  #### Limits
1449 
1450  [RFC 7159](http://rfc7159.net/rfc7159) specifies:
1451  > An implementation may set limits on the range and precision of numbers.
1452 
1453  When the default type is used, the maximal integer number that can be
1454  stored is `9223372036854775807` (INT64_MAX) and the minimal integer number
1455  that can be stored is `-9223372036854775808` (INT64_MIN). Integer numbers
1456  that are out of range will yield over/underflow when used in a
1457  constructor. During deserialization, too large or small integer numbers
1458  will be automatically be stored as @ref number_unsigned_t or @ref
1459  number_float_t.
1460 
1461  [RFC 7159](http://rfc7159.net/rfc7159) further states:
1462  > Note that when such software is used, numbers that are integers and are
1463  > in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
1464  > that implementations will agree exactly on their numeric values.
1465 
1466  As this range is a subrange of the exactly supported range [INT64_MIN,
1467  INT64_MAX], this class's integer type is interoperable.
1468 
1469  #### Storage
1470 
1471  Integer number values are stored directly inside a @ref basic_json type.
1472 
1473  @sa @ref number_float_t -- type for number values (floating-point)
1474 
1475  @sa @ref number_unsigned_t -- type for number values (unsigned integer)
1476 
1477  @since version 1.0.0
1478  */
1479  using number_integer_t = NumberIntegerType;
1480 
1481  /*!
1482  @brief a type for a number (unsigned)
1483 
1484  [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
1485  > The representation of numbers is similar to that used in most
1486  > programming languages. A number is represented in base 10 using decimal
1487  > digits. It contains an integer component that may be prefixed with an
1488  > optional minus sign, which may be followed by a fraction part and/or an
1489  > exponent part. Leading zeros are not allowed. (...) Numeric values that
1490  > cannot be represented in the grammar below (such as Infinity and NaN)
1491  > are not permitted.
1492 
1493  This description includes both integer and floating-point numbers.
1494  However, C++ allows more precise storage if it is known whether the number
1495  is a signed integer, an unsigned integer or a floating-point number.
1496  Therefore, three different types, @ref number_integer_t, @ref
1497  number_unsigned_t and @ref number_float_t are used.
1498 
1499  To store unsigned integer numbers in C++, a type is defined by the
1500  template parameter @a NumberUnsignedType which chooses the type to use.
1501 
1502  #### Default type
1503 
1504  With the default values for @a NumberUnsignedType (`uint64_t`), the
1505  default value for @a number_unsigned_t is:
1506 
1507  @code {.cpp}
1508  uint64_t
1509  @endcode
1510 
1511  #### Default behavior
1512 
1513  - The restrictions about leading zeros is not enforced in C++. Instead,
1514  leading zeros in integer literals lead to an interpretation as octal
1515  number. Internally, the value will be stored as decimal number. For
1516  instance, the C++ integer literal `010` will be serialized to `8`.
1517  During deserialization, leading zeros yield an error.
1518  - Not-a-number (NaN) values will be serialized to `null`.
1519 
1520  #### Limits
1521 
1522  [RFC 7159](http://rfc7159.net/rfc7159) specifies:
1523  > An implementation may set limits on the range and precision of numbers.
1524 
1525  When the default type is used, the maximal integer number that can be
1526  stored is `18446744073709551615` (UINT64_MAX) and the minimal integer
1527  number that can be stored is `0`. Integer numbers that are out of range
1528  will yield over/underflow when used in a constructor. During
1529  deserialization, too large or small integer numbers will be automatically
1530  be stored as @ref number_integer_t or @ref number_float_t.
1531 
1532  [RFC 7159](http://rfc7159.net/rfc7159) further states:
1533  > Note that when such software is used, numbers that are integers and are
1534  > in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
1535  > that implementations will agree exactly on their numeric values.
1536 
1537  As this range is a subrange (when considered in conjunction with the
1538  number_integer_t type) of the exactly supported range [0, UINT64_MAX],
1539  this class's integer type is interoperable.
1540 
1541  #### Storage
1542 
1543  Integer number values are stored directly inside a @ref basic_json type.
1544 
1545  @sa @ref number_float_t -- type for number values (floating-point)
1546  @sa @ref number_integer_t -- type for number values (integer)
1547 
1548  @since version 2.0.0
1549  */
1550  using number_unsigned_t = NumberUnsignedType;
1551 
1552  /*!
1553  @brief a type for a number (floating-point)
1554 
1555  [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
1556  > The representation of numbers is similar to that used in most
1557  > programming languages. A number is represented in base 10 using decimal
1558  > digits. It contains an integer component that may be prefixed with an
1559  > optional minus sign, which may be followed by a fraction part and/or an
1560  > exponent part. Leading zeros are not allowed. (...) Numeric values that
1561  > cannot be represented in the grammar below (such as Infinity and NaN)
1562  > are not permitted.
1563 
1564  This description includes both integer and floating-point numbers.
1565  However, C++ allows more precise storage if it is known whether the number
1566  is a signed integer, an unsigned integer or a floating-point number.
1567  Therefore, three different types, @ref number_integer_t, @ref
1568  number_unsigned_t and @ref number_float_t are used.
1569 
1570  To store floating-point numbers in C++, a type is defined by the template
1571  parameter @a NumberFloatType which chooses the type to use.
1572 
1573  #### Default type
1574 
1575  With the default values for @a NumberFloatType (`double`), the default
1576  value for @a number_float_t is:
1577 
1578  @code {.cpp}
1579  double
1580  @endcode
1581 
1582  #### Default behavior
1583 
1584  - The restrictions about leading zeros is not enforced in C++. Instead,
1585  leading zeros in floating-point literals will be ignored. Internally,
1586  the value will be stored as decimal number. For instance, the C++
1587  floating-point literal `01.2` will be serialized to `1.2`. During
1588  deserialization, leading zeros yield an error.
1589  - Not-a-number (NaN) values will be serialized to `null`.
1590 
1591  #### Limits
1592 
1593  [RFC 7159](http://rfc7159.net/rfc7159) states:
1594  > This specification allows implementations to set limits on the range and
1595  > precision of numbers accepted. Since software that implements IEEE
1596  > 754-2008 binary64 (double precision) numbers is generally available and
1597  > widely used, good interoperability can be achieved by implementations
1598  > that expect no more precision or range than these provide, in the sense
1599  > that implementations will approximate JSON numbers within the expected
1600  > precision.
1601 
1602  This implementation does exactly follow this approach, as it uses double
1603  precision floating-point numbers. Note values smaller than
1604  `-1.79769313486232e+308` and values greater than `1.79769313486232e+308`
1605  will be stored as NaN internally and be serialized to `null`.
1606 
1607  #### Storage
1608 
1609  Floating-point number values are stored directly inside a @ref basic_json
1610  type.
1611 
1612  @sa @ref number_integer_t -- type for number values (integer)
1613 
1614  @sa @ref number_unsigned_t -- type for number values (unsigned integer)
1615 
1616  @since version 1.0.0
1617  */
1618  using number_float_t = NumberFloatType;
1619 
1620  /// @}
1621 
1622  private:
1623 
1624  /// helper for exception-safe object creation
1625  template<typename T, typename... Args>
1626  static T* create(Args&& ... args)
1627  {
1628  AllocatorType<T> alloc;
1629  auto deleter = [&](T * object)
1630  {
1631  alloc.deallocate(object, 1);
1632  };
1633  std::unique_ptr<T, decltype(deleter)> object(alloc.allocate(1), deleter);
1634  alloc.construct(object.get(), std::forward<Args>(args)...);
1635  assert(object != nullptr);
1636  return object.release();
1637  }
1638 
1639  ////////////////////////
1640  // JSON value storage //
1641  ////////////////////////
1642 
1643  /*!
1644  @brief a JSON value
1645 
1646  The actual storage for a JSON value of the @ref basic_json class. This
1647  union combines the different storage types for the JSON value types
1648  defined in @ref value_t.
1649 
1650  JSON type | value_t type | used type
1651  --------- | --------------- | ------------------------
1652  object | object | pointer to @ref object_t
1653  array | array | pointer to @ref array_t
1654  string | string | pointer to @ref string_t
1655  boolean | boolean | @ref boolean_t
1656  number | number_integer | @ref number_integer_t
1657  number | number_unsigned | @ref number_unsigned_t
1658  number | number_float | @ref number_float_t
1659  null | null | *no value is stored*
1660 
1661  @note Variable-length types (objects, arrays, and strings) are stored as
1662  pointers. The size of the union should not exceed 64 bits if the default
1663  value types are used.
1664 
1665  @since version 1.0.0
1666  */
1668  {
1669  /// object (stored with pointer to save storage)
1671  /// array (stored with pointer to save storage)
1673  /// string (stored with pointer to save storage)
1675  /// boolean
1677  /// number (integer)
1679  /// number (unsigned integer)
1681  /// number (floating-point)
1683 
1684  /// default constructor (for null values)
1685  json_value() = default;
1686  /// constructor for booleans
1687  json_value(boolean_t v) noexcept : boolean(v) {}
1688  /// constructor for numbers (integer)
1690  /// constructor for numbers (unsigned)
1692  /// constructor for numbers (floating-point)
1694  /// constructor for empty values of a given type
1696  {
1697  switch (t)
1698  {
1699  case value_t::object:
1700  {
1701  object = create<object_t>();
1702  break;
1703  }
1704 
1705  case value_t::array:
1706  {
1707  array = create<array_t>();
1708  break;
1709  }
1710 
1711  case value_t::string:
1712  {
1713  string = create<string_t>("");
1714  break;
1715  }
1716 
1717  case value_t::boolean:
1718  {
1719  boolean = boolean_t(false);
1720  break;
1721  }
1722 
1724  {
1725  number_integer = number_integer_t(0);
1726  break;
1727  }
1728 
1730  {
1731  number_unsigned = number_unsigned_t(0);
1732  break;
1733  }
1734 
1735  case value_t::number_float:
1736  {
1737  number_float = number_float_t(0.0);
1738  break;
1739  }
1740 
1741  case value_t::null:
1742  {
1743  break;
1744  }
1745 
1746  default:
1747  {
1748  if (t == value_t::null)
1749  {
1750  JSON_THROW(std::domain_error("961c151d2e87f2686a955a9be24d316f1362bf21 2.1.1")); // LCOV_EXCL_LINE
1751  }
1752  break;
1753  }
1754  }
1755  }
1756 
1757  /// constructor for strings
1758  json_value(const string_t& value)
1759  {
1760  string = create<string_t>(value);
1761  }
1762 
1763  /// constructor for objects
1764  json_value(const object_t& value)
1765  {
1766  object = create<object_t>(value);
1767  }
1768 
1769  /// constructor for arrays
1770  json_value(const array_t& value)
1771  {
1772  array = create<array_t>(value);
1773  }
1774  };
1775 
1776  /*!
1777  @brief checks the class invariants
1778 
1779  This function asserts the class invariants. It needs to be called at the
1780  end of every constructor to make sure that created objects respect the
1781  invariant. Furthermore, it has to be called each time the type of a JSON
1782  value is changed, because the invariant expresses a relationship between
1783  @a m_type and @a m_value.
1784  */
1785  void assert_invariant() const
1786  {
1787  assert(m_type != value_t::object or m_value.object != nullptr);
1788  assert(m_type != value_t::array or m_value.array != nullptr);
1789  assert(m_type != value_t::string or m_value.string != nullptr);
1790  }
1791 
1792  public:
1793  //////////////////////////
1794  // JSON parser callback //
1795  //////////////////////////
1796 
1797  /*!
1798  @brief JSON callback events
1799 
1800  This enumeration lists the parser events that can trigger calling a
1801  callback function of type @ref parser_callback_t during parsing.
1802 
1803  @image html callback_events.png "Example when certain parse events are triggered"
1804 
1805  @since version 1.0.0
1806  */
1807  enum class parse_event_t : uint8_t
1808  {
1809  /// the parser read `{` and started to process a JSON object
1810  object_start,
1811  /// the parser read `}` and finished processing a JSON object
1812  object_end,
1813  /// the parser read `[` and started to process a JSON array
1814  array_start,
1815  /// the parser read `]` and finished processing a JSON array
1816  array_end,
1817  /// the parser read a key of a value in an object
1818  key,
1819  /// the parser finished reading a JSON value
1820  value
1821  };
1822 
1823  /*!
1824  @brief per-element parser callback type
1825 
1826  With a parser callback function, the result of parsing a JSON text can be
1827  influenced. When passed to @ref parse(std::istream&, const
1828  parser_callback_t) or @ref parse(const CharT, const parser_callback_t),
1829  it is called on certain events (passed as @ref parse_event_t via parameter
1830  @a event) with a set recursion depth @a depth and context JSON value
1831  @a parsed. The return value of the callback function is a boolean
1832  indicating whether the element that emitted the callback shall be kept or
1833  not.
1834 
1835  We distinguish six scenarios (determined by the event type) in which the
1836  callback function can be called. The following table describes the values
1837  of the parameters @a depth, @a event, and @a parsed.
1838 
1839  parameter @a event | description | parameter @a depth | parameter @a parsed
1840  ------------------ | ----------- | ------------------ | -------------------
1841  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
1842  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
1843  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
1844  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
1845  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
1846  parse_event_t::value | the parser finished reading a JSON value | depth of the value | the parsed JSON value
1847 
1848  @image html callback_events.png "Example when certain parse events are triggered"
1849 
1850  Discarding a value (i.e., returning `false`) has different effects
1851  depending on the context in which function was called:
1852 
1853  - Discarded values in structured types are skipped. That is, the parser
1854  will behave as if the discarded value was never read.
1855  - In case a value outside a structured type is skipped, it is replaced
1856  with `null`. This case happens if the top-level element is skipped.
1857 
1858  @param[in] depth the depth of the recursion during parsing
1859 
1860  @param[in] event an event of type parse_event_t indicating the context in
1861  the callback function has been called
1862 
1863  @param[in,out] parsed the current intermediate parse result; note that
1864  writing to this value has no effect for parse_event_t::key events
1865 
1866  @return Whether the JSON value which called the function during parsing
1867  should be kept (`true`) or not (`false`). In the latter case, it is either
1868  skipped completely or replaced by an empty discarded object.
1869 
1870  @sa @ref parse(std::istream&, parser_callback_t) or
1871  @ref parse(const CharT, const parser_callback_t) for examples
1872 
1873  @since version 1.0.0
1874  */
1875  using parser_callback_t = std::function<bool(int depth,
1876  parse_event_t event,
1877  basic_json& parsed)>;
1878 
1879 
1880  //////////////////
1881  // constructors //
1882  //////////////////
1883 
1884  /// @name constructors and destructors
1885  /// Constructors of class @ref basic_json, copy/move constructor, copy
1886  /// assignment, static functions creating objects, and the destructor.
1887  /// @{
1888 
1889  /*!
1890  @brief create an empty value with a given type
1891 
1892  Create an empty JSON value with a given type. The value will be default
1893  initialized with an empty value which depends on the type:
1894 
1895  Value type | initial value
1896  ----------- | -------------
1897  null | `null`
1898  boolean | `false`
1899  string | `""`
1900  number | `0`
1901  object | `{}`
1902  array | `[]`
1903 
1904  @param[in] value_type the type of the value to create
1905 
1906  @complexity Constant.
1907 
1908  @throw std::bad_alloc if allocation for object, array, or string value
1909  fails
1910 
1911  @liveexample{The following code shows the constructor for different @ref
1912  value_t values,basic_json__value_t}
1913 
1914  @since version 1.0.0
1915  */
1917  : m_type(value_type), m_value(value_type)
1918  {
1919  assert_invariant();
1920  }
1921 
1922  /*!
1923  @brief create a null object
1924 
1925  Create a `null` JSON value. It either takes a null pointer as parameter
1926  (explicitly creating `null`) or no parameter (implicitly creating `null`).
1927  The passed null pointer itself is not read -- it is only used to choose
1928  the right constructor.
1929 
1930  @complexity Constant.
1931 
1932  @exceptionsafety No-throw guarantee: this constructor never throws
1933  exceptions.
1934 
1935  @liveexample{The following code shows the constructor with and without a
1936  null pointer parameter.,basic_json__nullptr_t}
1937 
1938  @since version 1.0.0
1939  */
1940  basic_json(std::nullptr_t = nullptr) noexcept
1941  : basic_json(value_t::null)
1942  {
1943  assert_invariant();
1944  }
1945 
1946  /*!
1947  @brief create a JSON value
1948 
1949  This is a "catch all" constructor for all compatible JSON types; that is,
1950  types for which a `to_json()` method exsits. The constructor forwards the
1951  parameter @a val to that method (to `json_serializer<U>::to_json` method
1952  with `U = uncvref_t<CompatibleType>`, to be exact).
1953 
1954  Template type @a CompatibleType includes, but is not limited to, the
1955  following types:
1956  - **arrays**: @ref array_t and all kinds of compatible containers such as
1957  `std::vector`, `std::deque`, `std::list`, `std::forward_list`,
1958  `std::array`, `std::set`, `std::unordered_set`, `std::multiset`, and
1959  `unordered_multiset` with a `value_type` from which a @ref basic_json
1960  value can be constructed.
1961  - **objects**: @ref object_t and all kinds of compatible associative
1962  containers such as `std::map`, `std::unordered_map`, `std::multimap`,
1963  and `std::unordered_multimap` with a `key_type` compatible to
1964  @ref string_t and a `value_type` from which a @ref basic_json value can
1965  be constructed.
1966  - **strings**: @ref string_t, string literals, and all compatible string
1967  containers can be used.
1968  - **numbers**: @ref number_integer_t, @ref number_unsigned_t,
1969  @ref number_float_t, and all convertible number types such as `int`,
1970  `size_t`, `int64_t`, `float` or `double` can be used.
1971  - **boolean**: @ref boolean_t / `bool` can be used.
1972 
1973  See the examples below.
1974 
1975  @tparam CompatibleType a type such that:
1976  - @a CompatibleType is not derived from `std::istream`,
1977  - @a CompatibleType is not @ref basic_json (to avoid hijacking copy/move
1978  constructors),
1979  - @a CompatibleType is not a @ref basic_json nested type (e.g.,
1980  @ref json_pointer, @ref iterator, etc ...)
1981  - @ref @ref json_serializer<U> has a
1982  `to_json(basic_json_t&, CompatibleType&&)` method
1983 
1984  @tparam U = `uncvref_t<CompatibleType>`
1985 
1986  @param[in] val the value to be forwarded
1987 
1988  @complexity Usually linear in the size of the passed @a val, also
1989  depending on the implementation of the called `to_json()`
1990  method.
1991 
1992  @throw what `json_serializer<U>::to_json()` throws
1993 
1994  @liveexample{The following code shows the constructor with several
1995  compatible types.,basic_json__CompatibleType}
1996 
1997  @since version 2.1.0
1998  */
1999  template<typename CompatibleType, typename U = detail::uncvref_t<CompatibleType>,
2000  detail::enable_if_t<not std::is_base_of<std::istream, U>::value and
2001  not std::is_same<U, basic_json_t>::value and
2002  not detail::is_basic_json_nested_type<
2003  basic_json_t, U>::value and
2004  detail::has_to_json<basic_json, U>::value,
2005  int> = 0>
2006  basic_json(CompatibleType && val) noexcept(noexcept(JSONSerializer<U>::to_json(
2007  std::declval<basic_json_t&>(), std::forward<CompatibleType>(val))))
2008  {
2009  JSONSerializer<U>::to_json(*this, std::forward<CompatibleType>(val));
2010  assert_invariant();
2011  }
2012 
2013  /*!
2014  @brief create a container (array or object) from an initializer list
2015 
2016  Creates a JSON value of type array or object from the passed initializer
2017  list @a init. In case @a type_deduction is `true` (default), the type of
2018  the JSON value to be created is deducted from the initializer list @a init
2019  according to the following rules:
2020 
2021  1. If the list is empty, an empty JSON object value `{}` is created.
2022  2. If the list consists of pairs whose first element is a string, a JSON
2023  object value is created where the first elements of the pairs are
2024  treated as keys and the second elements are as values.
2025  3. In all other cases, an array is created.
2026 
2027  The rules aim to create the best fit between a C++ initializer list and
2028  JSON values. The rationale is as follows:
2029 
2030  1. The empty initializer list is written as `{}` which is exactly an empty
2031  JSON object.
2032  2. C++ has now way of describing mapped types other than to list a list of
2033  pairs. As JSON requires that keys must be of type string, rule 2 is the
2034  weakest constraint one can pose on initializer lists to interpret them
2035  as an object.
2036  3. In all other cases, the initializer list could not be interpreted as
2037  JSON object type, so interpreting it as JSON array type is safe.
2038 
2039  With the rules described above, the following JSON values cannot be
2040  expressed by an initializer list:
2041 
2042  - the empty array (`[]`): use @ref array(std::initializer_list<basic_json>)
2043  with an empty initializer list in this case
2044  - arrays whose elements satisfy rule 2: use @ref
2045  array(std::initializer_list<basic_json>) with the same initializer list
2046  in this case
2047 
2048  @note When used without parentheses around an empty initializer list, @ref
2049  basic_json() is called instead of this function, yielding the JSON null
2050  value.
2051 
2052  @param[in] init initializer list with JSON values
2053 
2054  @param[in] type_deduction internal parameter; when set to `true`, the type
2055  of the JSON value is deducted from the initializer list @a init; when set
2056  to `false`, the type provided via @a manual_type is forced. This mode is
2057  used by the functions @ref array(std::initializer_list<basic_json>) and
2058  @ref object(std::initializer_list<basic_json>).
2059 
2060  @param[in] manual_type internal parameter; when @a type_deduction is set
2061  to `false`, the created JSON value will use the provided type (only @ref
2062  value_t::array and @ref value_t::object are valid); when @a type_deduction
2063  is set to `true`, this parameter has no effect
2064 
2065  @throw std::domain_error if @a type_deduction is `false`, @a manual_type
2066  is `value_t::object`, but @a init contains an element which is not a pair
2067  whose first element is a string; example: `"cannot create object from
2068  initializer list"`
2069 
2070  @complexity Linear in the size of the initializer list @a init.
2071 
2072  @liveexample{The example below shows how JSON values are created from
2073  initializer lists.,basic_json__list_init_t}
2074 
2075  @sa @ref array(std::initializer_list<basic_json>) -- create a JSON array
2076  value from an initializer list
2077  @sa @ref object(std::initializer_list<basic_json>) -- create a JSON object
2078  value from an initializer list
2079 
2080  @since version 1.0.0
2081  */
2082  basic_json(std::initializer_list<basic_json> init,
2083  bool type_deduction = true,
2084  value_t manual_type = value_t::array)
2085  {
2086  // check if each element is an array with two elements whose first
2087  // element is a string
2088  bool is_an_object = std::all_of(init.begin(), init.end(),
2089  [](const basic_json & element)
2090  {
2091  return element.is_array() and element.size() == 2 and element[0].is_string();
2092  });
2093 
2094  // adjust type if type deduction is not wanted
2095  if (not type_deduction)
2096  {
2097  // if array is wanted, do not create an object though possible
2098  if (manual_type == value_t::array)
2099  {
2100  is_an_object = false;
2101  }
2102 
2103  // if object is wanted but impossible, throw an exception
2104  if (manual_type == value_t::object and not is_an_object)
2105  {
2106  JSON_THROW(std::domain_error("cannot create object from initializer list"));
2107  }
2108  }
2109 
2110  if (is_an_object)
2111  {
2112  // the initializer list is a list of pairs -> create object
2113  m_type = value_t::object;
2114  m_value = value_t::object;
2115 
2116  std::for_each(init.begin(), init.end(), [this](const basic_json & element)
2117  {
2118  m_value.object->emplace(*(element[0].m_value.string), element[1]);
2119  });
2120  }
2121  else
2122  {
2123  // the initializer list describes an array -> create array
2124  m_type = value_t::array;
2125  m_value.array = create<array_t>(init);
2126  }
2127 
2128  assert_invariant();
2129  }
2130 
2131  /*!
2132  @brief explicitly create an array from an initializer list
2133 
2134  Creates a JSON array value from a given initializer list. That is, given a
2135  list of values `a, b, c`, creates the JSON value `[a, b, c]`. If the
2136  initializer list is empty, the empty array `[]` is created.
2137 
2138  @note This function is only needed to express two edge cases that cannot
2139  be realized with the initializer list constructor (@ref
2140  basic_json(std::initializer_list<basic_json>, bool, value_t)). These cases
2141  are:
2142  1. creating an array whose elements are all pairs whose first element is a
2143  string -- in this case, the initializer list constructor would create an
2144  object, taking the first elements as keys
2145  2. creating an empty array -- passing the empty initializer list to the
2146  initializer list constructor yields an empty object
2147 
2148  @param[in] init initializer list with JSON values to create an array from
2149  (optional)
2150 
2151  @return JSON array value
2152 
2153  @complexity Linear in the size of @a init.
2154 
2155  @liveexample{The following code shows an example for the `array`
2156  function.,array}
2157 
2158  @sa @ref basic_json(std::initializer_list<basic_json>, bool, value_t) --
2159  create a JSON value from an initializer list
2160  @sa @ref object(std::initializer_list<basic_json>) -- create a JSON object
2161  value from an initializer list
2162 
2163  @since version 1.0.0
2164  */
2165  static basic_json array(std::initializer_list<basic_json> init =
2166  std::initializer_list<basic_json>())
2167  {
2168  return basic_json(init, false, value_t::array);
2169  }
2170 
2171  /*!
2172  @brief explicitly create an object from an initializer list
2173 
2174  Creates a JSON object value from a given initializer list. The initializer
2175  lists elements must be pairs, and their first elements must be strings. If
2176  the initializer list is empty, the empty object `{}` is created.
2177 
2178  @note This function is only added for symmetry reasons. In contrast to the
2179  related function @ref array(std::initializer_list<basic_json>), there are
2180  no cases which can only be expressed by this function. That is, any
2181  initializer list @a init can also be passed to the initializer list
2182  constructor @ref basic_json(std::initializer_list<basic_json>, bool,
2183  value_t).
2184 
2185  @param[in] init initializer list to create an object from (optional)
2186 
2187  @return JSON object value
2188 
2189  @throw std::domain_error if @a init is not a pair whose first elements are
2190  strings; thrown by
2191  @ref basic_json(std::initializer_list<basic_json>, bool, value_t)
2192 
2193  @complexity Linear in the size of @a init.
2194 
2195  @liveexample{The following code shows an example for the `object`
2196  function.,object}
2197 
2198  @sa @ref basic_json(std::initializer_list<basic_json>, bool, value_t) --
2199  create a JSON value from an initializer list
2200  @sa @ref array(std::initializer_list<basic_json>) -- create a JSON array
2201  value from an initializer list
2202 
2203  @since version 1.0.0
2204  */
2205  static basic_json object(std::initializer_list<basic_json> init =
2206  std::initializer_list<basic_json>())
2207  {
2208  return basic_json(init, false, value_t::object);
2209  }
2210 
2211  /*!
2212  @brief construct an array with count copies of given value
2213 
2214  Constructs a JSON array value by creating @a cnt copies of a passed value.
2215  In case @a cnt is `0`, an empty array is created. As postcondition,
2216  `std::distance(begin(),end()) == cnt` holds.
2217 
2218  @param[in] cnt the number of JSON copies of @a val to create
2219  @param[in] val the JSON value to copy
2220 
2221  @complexity Linear in @a cnt.
2222 
2223  @liveexample{The following code shows examples for the @ref
2224  basic_json(size_type\, const basic_json&)
2225  constructor.,basic_json__size_type_basic_json}
2226 
2227  @since version 1.0.0
2228  */
2230  : m_type(value_t::array)
2231  {
2232  m_value.array = create<array_t>(cnt, val);
2233  assert_invariant();
2234  }
2235 
2236  /*!
2237  @brief construct a JSON container given an iterator range
2238 
2239  Constructs the JSON value with the contents of the range `[first, last)`.
2240  The semantics depends on the different types a JSON value can have:
2241  - In case of primitive types (number, boolean, or string), @a first must
2242  be `begin()` and @a last must be `end()`. In this case, the value is
2243  copied. Otherwise, std::out_of_range is thrown.
2244  - In case of structured types (array, object), the constructor behaves as
2245  similar versions for `std::vector`.
2246  - In case of a null type, std::domain_error is thrown.
2247 
2248  @tparam InputIT an input iterator type (@ref iterator or @ref
2249  const_iterator)
2250 
2251  @param[in] first begin of the range to copy from (included)
2252  @param[in] last end of the range to copy from (excluded)
2253 
2254  @pre Iterators @a first and @a last must be initialized. **This
2255  precondition is enforced with an assertion.**
2256 
2257  @throw std::domain_error if iterators are not compatible; that is, do not
2258  belong to the same JSON value; example: `"iterators are not compatible"`
2259  @throw std::out_of_range if iterators are for a primitive type (number,
2260  boolean, or string) where an out of range error can be detected easily;
2261  example: `"iterators out of range"`
2262  @throw std::bad_alloc if allocation for object, array, or string fails
2263  @throw std::domain_error if called with a null value; example: `"cannot
2264  use construct with iterators from null"`
2265 
2266  @complexity Linear in distance between @a first and @a last.
2267 
2268  @liveexample{The example below shows several ways to create JSON values by
2269  specifying a subrange with iterators.,basic_json__InputIt_InputIt}
2270 
2271  @since version 1.0.0
2272  */
2273  template<class InputIT, typename std::enable_if<
2274  std::is_same<InputIT, typename basic_json_t::iterator>::value or
2275  std::is_same<InputIT, typename basic_json_t::const_iterator>::value, int>::type = 0>
2276  basic_json(InputIT first, InputIT last)
2277  {
2278  assert(first.m_object != nullptr);
2279  assert(last.m_object != nullptr);
2280 
2281  // make sure iterator fits the current value
2282  if (first.m_object != last.m_object)
2283  {
2284  JSON_THROW(std::domain_error("iterators are not compatible"));
2285  }
2286 
2287  // copy type from first iterator
2288  m_type = first.m_object->m_type;
2289 
2290  // check if iterator range is complete for primitive values
2291  switch (m_type)
2292  {
2293  case value_t::boolean:
2294  case value_t::number_float:
2297  case value_t::string:
2298  {
2299  if (not first.m_it.primitive_iterator.is_begin() or not last.m_it.primitive_iterator.is_end())
2300  {
2301  JSON_THROW(std::out_of_range("iterators out of range"));
2302  }
2303  break;
2304  }
2305 
2306  default:
2307  {
2308  break;
2309  }
2310  }
2311 
2312  switch (m_type)
2313  {
2315  {
2316  m_value.number_integer = first.m_object->m_value.number_integer;
2317  break;
2318  }
2319 
2321  {
2322  m_value.number_unsigned = first.m_object->m_value.number_unsigned;
2323  break;
2324  }
2325 
2326  case value_t::number_float:
2327  {
2328  m_value.number_float = first.m_object->m_value.number_float;
2329  break;
2330  }
2331 
2332  case value_t::boolean:
2333  {
2334  m_value.boolean = first.m_object->m_value.boolean;
2335  break;
2336  }
2337 
2338  case value_t::string:
2339  {
2340  m_value = *first.m_object->m_value.string;
2341  break;
2342  }
2343 
2344  case value_t::object:
2345  {
2346  m_value.object = create<object_t>(first.m_it.object_iterator,
2347  last.m_it.object_iterator);
2348  break;
2349  }
2350 
2351  case value_t::array:
2352  {
2353  m_value.array = create<array_t>(first.m_it.array_iterator,
2354  last.m_it.array_iterator);
2355  break;
2356  }
2357 
2358  default:
2359  {
2360  JSON_THROW(std::domain_error("cannot use construct with iterators from " + first.m_object->type_name()));
2361  }
2362  }
2363 
2364  assert_invariant();
2365  }
2366 
2367  /*!
2368  @brief construct a JSON value given an input stream
2369 
2370  @param[in,out] i stream to read a serialized JSON value from
2371  @param[in] cb a parser callback function of type @ref parser_callback_t
2372  which is used to control the deserialization by filtering unwanted values
2373  (optional)
2374 
2375  @complexity Linear in the length of the input. The parser is a predictive
2376  LL(1) parser. The complexity can be higher if the parser callback function
2377  @a cb has a super-linear complexity.
2378 
2379  @note A UTF-8 byte order mark is silently ignored.
2380 
2381  @deprecated This constructor is deprecated and will be removed in version
2382  3.0.0 to unify the interface of the library. Deserialization will be
2383  done by stream operators or by calling one of the `parse` functions,
2384  e.g. @ref parse(std::istream&, const parser_callback_t). That is, calls
2385  like `json j(i);` for an input stream @a i need to be replaced by
2386  `json j = json::parse(i);`. See the example below.
2387 
2388  @liveexample{The example below demonstrates constructing a JSON value from
2389  a `std::stringstream` with and without callback
2390  function.,basic_json__istream}
2391 
2392  @since version 2.0.0, deprecated in version 2.0.3, to be removed in
2393  version 3.0.0
2394  */
2396  explicit basic_json(std::istream& i, const parser_callback_t cb = nullptr)
2397  {
2398  *this = parser(i, cb).parse();
2399  assert_invariant();
2400  }
2401 
2402  ///////////////////////////////////////
2403  // other constructors and destructor //
2404  ///////////////////////////////////////
2405 
2406  /*!
2407  @brief copy constructor
2408 
2409  Creates a copy of a given JSON value.
2410 
2411  @param[in] other the JSON value to copy
2412 
2413  @complexity Linear in the size of @a other.
2414 
2415  @requirement This function helps `basic_json` satisfying the
2416  [Container](http://en.cppreference.com/w/cpp/concept/Container)
2417  requirements:
2418  - The complexity is linear.
2419  - As postcondition, it holds: `other == basic_json(other)`.
2420 
2421  @throw std::bad_alloc if allocation for object, array, or string fails.
2422 
2423  @liveexample{The following code shows an example for the copy
2424  constructor.,basic_json__basic_json}
2425 
2426  @since version 1.0.0
2427  */
2428  basic_json(const basic_json& other)
2429  : m_type(other.m_type)
2430  {
2431  // check of passed value is valid
2432  other.assert_invariant();
2433 
2434  switch (m_type)
2435  {
2436  case value_t::object:
2437  {
2438  m_value = *other.m_value.object;
2439  break;
2440  }
2441 
2442  case value_t::array:
2443  {
2444  m_value = *other.m_value.array;
2445  break;
2446  }
2447 
2448  case value_t::string:
2449  {
2450  m_value = *other.m_value.string;
2451  break;
2452  }
2453 
2454  case value_t::boolean:
2455  {
2456  m_value = other.m_value.boolean;
2457  break;
2458  }
2459 
2461  {
2462  m_value = other.m_value.number_integer;
2463  break;
2464  }
2465 
2467  {
2468  m_value = other.m_value.number_unsigned;
2469  break;
2470  }
2471 
2472  case value_t::number_float:
2473  {
2474  m_value = other.m_value.number_float;
2475  break;
2476  }
2477 
2478  default:
2479  {
2480  break;
2481  }
2482  }
2483 
2484  assert_invariant();
2485  }
2486 
2487  /*!
2488  @brief move constructor
2489 
2490  Move constructor. Constructs a JSON value with the contents of the given
2491  value @a other using move semantics. It "steals" the resources from @a
2492  other and leaves it as JSON null value.
2493 
2494  @param[in,out] other value to move to this object
2495 
2496  @post @a other is a JSON null value
2497 
2498  @complexity Constant.
2499 
2500  @liveexample{The code below shows the move constructor explicitly called
2501  via std::move.,basic_json__moveconstructor}
2502 
2503  @since version 1.0.0
2504  */
2505  basic_json(basic_json&& other) noexcept
2506  : m_type(std::move(other.m_type)),
2507  m_value(std::move(other.m_value))
2508  {
2509  // check that passed value is valid
2510  other.assert_invariant();
2511 
2512  // invalidate payload
2513  other.m_type = value_t::null;
2514  other.m_value = {};
2515 
2516  assert_invariant();
2517  }
2518 
2519  /*!
2520  @brief copy assignment
2521 
2522  Copy assignment operator. Copies a JSON value via the "copy and swap"
2523  strategy: It is expressed in terms of the copy constructor, destructor,
2524  and the swap() member function.
2525 
2526  @param[in] other value to copy from
2527 
2528  @complexity Linear.
2529 
2530  @requirement This function helps `basic_json` satisfying the
2531  [Container](http://en.cppreference.com/w/cpp/concept/Container)
2532  requirements:
2533  - The complexity is linear.
2534 
2535  @liveexample{The code below shows and example for the copy assignment. It
2536  creates a copy of value `a` which is then swapped with `b`. Finally\, the
2537  copy of `a` (which is the null value after the swap) is
2538  destroyed.,basic_json__copyassignment}
2539 
2540  @since version 1.0.0
2541  */
2542  reference& operator=(basic_json other) noexcept (
2543  std::is_nothrow_move_constructible<value_t>::value and
2544  std::is_nothrow_move_assignable<value_t>::value and
2545  std::is_nothrow_move_constructible<json_value>::value and
2546  std::is_nothrow_move_assignable<json_value>::value
2547  )
2548  {
2549  // check that passed value is valid
2550  other.assert_invariant();
2551 
2552  using std::swap;
2553  swap(m_type, other.m_type);
2554  swap(m_value, other.m_value);
2555 
2556  assert_invariant();
2557  return *this;
2558  }
2559 
2560  /*!
2561  @brief destructor
2562 
2563  Destroys the JSON value and frees all allocated memory.
2564 
2565  @complexity Linear.
2566 
2567  @requirement This function helps `basic_json` satisfying the
2568  [Container](http://en.cppreference.com/w/cpp/concept/Container)
2569  requirements:
2570  - The complexity is linear.
2571  - All stored elements are destroyed and all memory is freed.
2572 
2573  @since version 1.0.0
2574  */
2576  {
2577  assert_invariant();
2578 
2579  switch (m_type)
2580  {
2581  case value_t::object:
2582  {
2583  AllocatorType<object_t> alloc;
2584  alloc.destroy(m_value.object);
2585  alloc.deallocate(m_value.object, 1);
2586  break;
2587  }
2588 
2589  case value_t::array:
2590  {
2591  AllocatorType<array_t> alloc;
2592  alloc.destroy(m_value.array);
2593  alloc.deallocate(m_value.array, 1);
2594  break;
2595  }
2596 
2597  case value_t::string:
2598  {
2599  AllocatorType<string_t> alloc;
2600  alloc.destroy(m_value.string);
2601  alloc.deallocate(m_value.string, 1);
2602  break;
2603  }
2604 
2605  default:
2606  {
2607  // all other types need no specific destructor
2608  break;
2609  }
2610  }
2611  }
2612 
2613  /// @}
2614 
2615  public:
2616  ///////////////////////
2617  // object inspection //
2618  ///////////////////////
2619 
2620  /// @name object inspection
2621  /// Functions to inspect the type of a JSON value.
2622  /// @{
2623 
2624  /*!
2625  @brief serialization
2626 
2627  Serialization function for JSON values. The function tries to mimic
2628  Python's `json.dumps()` function, and currently supports its @a indent
2629  parameter.
2630 
2631  @param[in] indent If indent is nonnegative, then array elements and object
2632  members will be pretty-printed with that indent level. An indent level of
2633  `0` will only insert newlines. `-1` (the default) selects the most compact
2634  representation.
2635 
2636  @return string containing the serialization of the JSON value
2637 
2638  @complexity Linear.
2639 
2640  @liveexample{The following example shows the effect of different @a indent
2641  parameters to the result of the serialization.,dump}
2642 
2643  @see https://docs.python.org/2/library/json.html#json.dump
2644 
2645  @since version 1.0.0
2646  */
2647  string_t dump(const int indent = -1) const
2648  {
2649  std::stringstream ss;
2650 
2651  if (indent >= 0)
2652  {
2653  dump(ss, true, static_cast<unsigned int>(indent));
2654  }
2655  else
2656  {
2657  dump(ss, false, 0);
2658  }
2659 
2660  return ss.str();
2661  }
2662 
2663  /*!
2664  @brief return the type of the JSON value (explicit)
2665 
2666  Return the type of the JSON value as a value from the @ref value_t
2667  enumeration.
2668 
2669  @return the type of the JSON value
2670 
2671  @complexity Constant.
2672 
2673  @exceptionsafety No-throw guarantee: this member function never throws
2674  exceptions.
2675 
2676  @liveexample{The following code exemplifies `type()` for all JSON
2677  types.,type}
2678 
2679  @since version 1.0.0
2680  */
2681  constexpr value_t type() const noexcept
2682  {
2683  return m_type;
2684  }
2685 
2686  /*!
2687  @brief return whether type is primitive
2688 
2689  This function returns true iff the JSON type is primitive (string, number,
2690  boolean, or null).
2691 
2692  @return `true` if type is primitive (string, number, boolean, or null),
2693  `false` otherwise.
2694 
2695  @complexity Constant.
2696 
2697  @exceptionsafety No-throw guarantee: this member function never throws
2698  exceptions.
2699 
2700  @liveexample{The following code exemplifies `is_primitive()` for all JSON
2701  types.,is_primitive}
2702 
2703  @sa @ref is_structured() -- returns whether JSON value is structured
2704  @sa @ref is_null() -- returns whether JSON value is `null`
2705  @sa @ref is_string() -- returns whether JSON value is a string
2706  @sa @ref is_boolean() -- returns whether JSON value is a boolean
2707  @sa @ref is_number() -- returns whether JSON value is a number
2708 
2709  @since version 1.0.0
2710  */
2711  constexpr bool is_primitive() const noexcept
2712  {
2713  return is_null() or is_string() or is_boolean() or is_number();
2714  }
2715 
2716  /*!
2717  @brief return whether type is structured
2718 
2719  This function returns true iff the JSON type is structured (array or
2720  object).
2721 
2722  @return `true` if type is structured (array or object), `false` otherwise.
2723 
2724  @complexity Constant.
2725 
2726  @exceptionsafety No-throw guarantee: this member function never throws
2727  exceptions.
2728 
2729  @liveexample{The following code exemplifies `is_structured()` for all JSON
2730  types.,is_structured}
2731 
2732  @sa @ref is_primitive() -- returns whether value is primitive
2733  @sa @ref is_array() -- returns whether value is an array
2734  @sa @ref is_object() -- returns whether value is an object
2735 
2736  @since version 1.0.0
2737  */
2738  constexpr bool is_structured() const noexcept
2739  {
2740  return is_array() or is_object();
2741  }
2742 
2743  /*!
2744  @brief return whether value is null
2745 
2746  This function returns true iff the JSON value is null.
2747 
2748  @return `true` if type is null, `false` otherwise.
2749 
2750  @complexity Constant.
2751 
2752  @exceptionsafety No-throw guarantee: this member function never throws
2753  exceptions.
2754 
2755  @liveexample{The following code exemplifies `is_null()` for all JSON
2756  types.,is_null}
2757 
2758  @since version 1.0.0
2759  */
2760  constexpr bool is_null() const noexcept
2761  {
2762  return m_type == value_t::null;
2763  }
2764 
2765  /*!
2766  @brief return whether value is a boolean
2767 
2768  This function returns true iff the JSON value is a boolean.
2769 
2770  @return `true` if type is boolean, `false` otherwise.
2771 
2772  @complexity Constant.
2773 
2774  @exceptionsafety No-throw guarantee: this member function never throws
2775  exceptions.
2776 
2777  @liveexample{The following code exemplifies `is_boolean()` for all JSON
2778  types.,is_boolean}
2779 
2780  @since version 1.0.0
2781  */
2782  constexpr bool is_boolean() const noexcept
2783  {
2784  return m_type == value_t::boolean;
2785  }
2786 
2787  /*!
2788  @brief return whether value is a number
2789 
2790  This function returns true iff the JSON value is a number. This includes
2791  both integer and floating-point values.
2792 
2793  @return `true` if type is number (regardless whether integer, unsigned
2794  integer or floating-type), `false` otherwise.
2795 
2796  @complexity Constant.
2797 
2798  @exceptionsafety No-throw guarantee: this member function never throws
2799  exceptions.
2800 
2801  @liveexample{The following code exemplifies `is_number()` for all JSON
2802  types.,is_number}
2803 
2804  @sa @ref is_number_integer() -- check if value is an integer or unsigned
2805  integer number
2806  @sa @ref is_number_unsigned() -- check if value is an unsigned integer
2807  number
2808  @sa @ref is_number_float() -- check if value is a floating-point number
2809 
2810  @since version 1.0.0
2811  */
2812  constexpr bool is_number() const noexcept
2813  {
2814  return is_number_integer() or is_number_float();
2815  }
2816 
2817  /*!
2818  @brief return whether value is an integer number
2819 
2820  This function returns true iff the JSON value is an integer or unsigned
2821  integer number. This excludes floating-point values.
2822 
2823  @return `true` if type is an integer or unsigned integer number, `false`
2824  otherwise.
2825 
2826  @complexity Constant.
2827 
2828  @exceptionsafety No-throw guarantee: this member function never throws
2829  exceptions.
2830 
2831  @liveexample{The following code exemplifies `is_number_integer()` for all
2832  JSON types.,is_number_integer}
2833 
2834  @sa @ref is_number() -- check if value is a number
2835  @sa @ref is_number_unsigned() -- check if value is an unsigned integer
2836  number
2837  @sa @ref is_number_float() -- check if value is a floating-point number
2838 
2839  @since version 1.0.0
2840  */
2841  constexpr bool is_number_integer() const noexcept
2842  {
2843  return m_type == value_t::number_integer or m_type == value_t::number_unsigned;
2844  }
2845 
2846  /*!
2847  @brief return whether value is an unsigned integer number
2848 
2849  This function returns true iff the JSON value is an unsigned integer
2850  number. This excludes floating-point and (signed) integer values.
2851 
2852  @return `true` if type is an unsigned integer number, `false` otherwise.
2853 
2854  @complexity Constant.
2855 
2856  @exceptionsafety No-throw guarantee: this member function never throws
2857  exceptions.
2858 
2859  @liveexample{The following code exemplifies `is_number_unsigned()` for all
2860  JSON types.,is_number_unsigned}
2861 
2862  @sa @ref is_number() -- check if value is a number
2863  @sa @ref is_number_integer() -- check if value is an integer or unsigned
2864  integer number
2865  @sa @ref is_number_float() -- check if value is a floating-point number
2866 
2867  @since version 2.0.0
2868  */
2869  constexpr bool is_number_unsigned() const noexcept
2870  {
2871  return m_type == value_t::number_unsigned;
2872  }
2873 
2874  /*!
2875  @brief return whether value is a floating-point number
2876 
2877  This function returns true iff the JSON value is a floating-point number.
2878  This excludes integer and unsigned integer values.
2879 
2880  @return `true` if type is a floating-point number, `false` otherwise.
2881 
2882  @complexity Constant.
2883 
2884  @exceptionsafety No-throw guarantee: this member function never throws
2885  exceptions.
2886 
2887  @liveexample{The following code exemplifies `is_number_float()` for all
2888  JSON types.,is_number_float}
2889 
2890  @sa @ref is_number() -- check if value is number
2891  @sa @ref is_number_integer() -- check if value is an integer number
2892  @sa @ref is_number_unsigned() -- check if value is an unsigned integer
2893  number
2894 
2895  @since version 1.0.0
2896  */
2897  constexpr bool is_number_float() const noexcept
2898  {
2899  return m_type == value_t::number_float;
2900  }
2901 
2902  /*!
2903  @brief return whether value is an object
2904 
2905  This function returns true iff the JSON value is an object.
2906 
2907  @return `true` if type is object, `false` otherwise.
2908 
2909  @complexity Constant.
2910 
2911  @exceptionsafety No-throw guarantee: this member function never throws
2912  exceptions.
2913 
2914  @liveexample{The following code exemplifies `is_object()` for all JSON
2915  types.,is_object}
2916 
2917  @since version 1.0.0
2918  */
2919  constexpr bool is_object() const noexcept
2920  {
2921  return m_type == value_t::object;
2922  }
2923 
2924  /*!
2925  @brief return whether value is an array
2926 
2927  This function returns true iff the JSON value is an array.
2928 
2929  @return `true` if type is array, `false` otherwise.
2930 
2931  @complexity Constant.
2932 
2933  @exceptionsafety No-throw guarantee: this member function never throws
2934  exceptions.
2935 
2936  @liveexample{The following code exemplifies `is_array()` for all JSON
2937  types.,is_array}
2938 
2939  @since version 1.0.0
2940  */
2941  constexpr bool is_array() const noexcept
2942  {
2943  return m_type == value_t::array;
2944  }
2945 
2946  /*!
2947  @brief return whether value is a string
2948 
2949  This function returns true iff the JSON value is a string.
2950 
2951  @return `true` if type is string, `false` otherwise.
2952 
2953  @complexity Constant.
2954 
2955  @exceptionsafety No-throw guarantee: this member function never throws
2956  exceptions.
2957 
2958  @liveexample{The following code exemplifies `is_string()` for all JSON
2959  types.,is_string}
2960 
2961  @since version 1.0.0
2962  */
2963  constexpr bool is_string() const noexcept
2964  {
2965  return m_type == value_t::string;
2966  }
2967 
2968  /*!
2969  @brief return whether value is discarded
2970 
2971  This function returns true iff the JSON value was discarded during parsing
2972  with a callback function (see @ref parser_callback_t).
2973 
2974  @note This function will always be `false` for JSON values after parsing.
2975  That is, discarded values can only occur during parsing, but will be
2976  removed when inside a structured value or replaced by null in other cases.
2977 
2978  @return `true` if type is discarded, `false` otherwise.
2979 
2980  @complexity Constant.
2981 
2982  @exceptionsafety No-throw guarantee: this member function never throws
2983  exceptions.
2984 
2985  @liveexample{The following code exemplifies `is_discarded()` for all JSON
2986  types.,is_discarded}
2987 
2988  @since version 1.0.0
2989  */
2990  constexpr bool is_discarded() const noexcept
2991  {
2992  return m_type == value_t::discarded;
2993  }
2994 
2995  /*!
2996  @brief return the type of the JSON value (implicit)
2997 
2998  Implicitly return the type of the JSON value as a value from the @ref
2999  value_t enumeration.
3000 
3001  @return the type of the JSON value
3002 
3003  @complexity Constant.
3004 
3005  @exceptionsafety No-throw guarantee: this member function never throws
3006  exceptions.
3007 
3008  @liveexample{The following code exemplifies the @ref value_t operator for
3009  all JSON types.,operator__value_t}
3010 
3011  @since version 1.0.0
3012  */
3013  constexpr operator value_t() const noexcept
3014  {
3015  return m_type;
3016  }
3017 
3018  /// @}
3019 
3020  private:
3021  //////////////////
3022  // value access //
3023  //////////////////
3024 
3025  /// get a boolean (explicit)
3026  boolean_t get_impl(boolean_t* /*unused*/) const
3027  {
3028  if (is_boolean())
3029  {
3030  return m_value.boolean;
3031  }
3032 
3033  JSON_THROW(std::domain_error("type must be boolean, but is " + type_name()));
3034  }
3035 
3036  /// get a pointer to the value (object)
3037  object_t* get_impl_ptr(object_t* /*unused*/) noexcept
3038  {
3039  return is_object() ? m_value.object : nullptr;
3040  }
3041 
3042  /// get a pointer to the value (object)
3043  constexpr const object_t* get_impl_ptr(const object_t* /*unused*/) const noexcept
3044  {
3045  return is_object() ? m_value.object : nullptr;
3046  }
3047 
3048  /// get a pointer to the value (array)
3049  array_t* get_impl_ptr(array_t* /*unused*/) noexcept
3050  {
3051  return is_array() ? m_value.array : nullptr;
3052  }
3053 
3054  /// get a pointer to the value (array)
3055  constexpr const array_t* get_impl_ptr(const array_t* /*unused*/) const noexcept
3056  {
3057  return is_array() ? m_value.array : nullptr;
3058  }
3059 
3060  /// get a pointer to the value (string)
3061  string_t* get_impl_ptr(string_t* /*unused*/) noexcept
3062  {
3063  return is_string() ? m_value.string : nullptr;
3064  }
3065 
3066  /// get a pointer to the value (string)
3067  constexpr const string_t* get_impl_ptr(const string_t* /*unused*/) const noexcept
3068  {
3069  return is_string() ? m_value.string : nullptr;
3070  }
3071 
3072  /// get a pointer to the value (boolean)
3073  boolean_t* get_impl_ptr(boolean_t* /*unused*/) noexcept
3074  {
3075  return is_boolean() ? &m_value.boolean : nullptr;
3076  }
3077 
3078  /// get a pointer to the value (boolean)
3079  constexpr const boolean_t* get_impl_ptr(const boolean_t* /*unused*/) const noexcept
3080  {
3081  return is_boolean() ? &m_value.boolean : nullptr;
3082  }
3083 
3084  /// get a pointer to the value (integer number)
3086  {
3087  return is_number_integer() ? &m_value.number_integer : nullptr;
3088  }
3089 
3090  /// get a pointer to the value (integer number)
3091  constexpr const number_integer_t* get_impl_ptr(const number_integer_t* /*unused*/) const noexcept
3092  {
3093  return is_number_integer() ? &m_value.number_integer : nullptr;
3094  }
3095 
3096  /// get a pointer to the value (unsigned number)
3098  {
3099  return is_number_unsigned() ? &m_value.number_unsigned : nullptr;
3100  }
3101 
3102  /// get a pointer to the value (unsigned number)
3103  constexpr const number_unsigned_t* get_impl_ptr(const number_unsigned_t* /*unused*/) const noexcept
3104  {
3105  return is_number_unsigned() ? &m_value.number_unsigned : nullptr;
3106  }
3107 
3108  /// get a pointer to the value (floating-point number)
3110  {
3111  return is_number_float() ? &m_value.number_float : nullptr;
3112  }
3113 
3114  /// get a pointer to the value (floating-point number)
3115  constexpr const number_float_t* get_impl_ptr(const number_float_t* /*unused*/) const noexcept
3116  {
3117  return is_number_float() ? &m_value.number_float : nullptr;
3118  }
3119 
3120  /*!
3121  @brief helper function to implement get_ref()
3122 
3123  This funcion helps to implement get_ref() without code duplication for
3124  const and non-const overloads
3125 
3126  @tparam ThisType will be deduced as `basic_json` or `const basic_json`
3127 
3128  @throw std::domain_error if ReferenceType does not match underlying value
3129  type of the current JSON
3130  */
3131  template<typename ReferenceType, typename ThisType>
3132  static ReferenceType get_ref_impl(ThisType& obj)
3133  {
3134  // helper type
3135  using PointerType = typename std::add_pointer<ReferenceType>::type;
3136 
3137  // delegate the call to get_ptr<>()
3138  auto ptr = obj.template get_ptr<PointerType>();
3139 
3140  if (ptr != nullptr)
3141  {
3142  return *ptr;
3143  }
3144 
3145  JSON_THROW(std::domain_error("incompatible ReferenceType for get_ref, actual type is " +
3146  obj.type_name()));
3147  }
3148 
3149  public:
3150  /// @name value access
3151  /// Direct access to the stored value of a JSON value.
3152  /// @{
3153 
3154  /*!
3155  @brief get special-case overload
3156 
3157  This overloads avoids a lot of template boilerplate, it can be seen as the
3158  identity method
3159 
3160  @tparam BasicJsonType == @ref basic_json
3161 
3162  @return a copy of *this
3163 
3164  @complexity Constant.
3165 
3166  @since version 2.1.0
3167  */
3168  template <
3169  typename BasicJsonType,
3171  basic_json_t>::value,
3172  int> = 0 >
3173  basic_json get() const
3174  {
3175  return *this;
3176  }
3177 
3178  /*!
3179  @brief get a value (explicit)
3180 
3181  Explicit type conversion between the JSON value and a compatible value
3182  which is [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible)
3183  and [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible).
3184  The value is converted by calling the @ref json_serializer<ValueType>
3185  `from_json()` method.
3186 
3187  The function is equivalent to executing
3188  @code {.cpp}
3189  ValueType ret;
3190  JSONSerializer<ValueType>::from_json(*this, ret);
3191  return ret;
3192  @endcode
3193 
3194  This overloads is chosen if:
3195  - @a ValueType is not @ref basic_json,
3196  - @ref json_serializer<ValueType> has a `from_json()` method of the form
3197  `void from_json(const @ref basic_json&, ValueType&)`, and
3198  - @ref json_serializer<ValueType> does not have a `from_json()` method of
3199  the form `ValueType from_json(const @ref basic_json&)`
3200 
3201  @tparam ValueTypeCV the provided value type
3202  @tparam ValueType the returned value type
3203 
3204  @return copy of the JSON value, converted to @a ValueType
3205 
3206  @throw what @ref json_serializer<ValueType> `from_json()` method throws
3207 
3208  @liveexample{The example below shows several conversions from JSON values
3209  to other types. There a few things to note: (1) Floating-point numbers can
3210  be converted to integers\, (2) A JSON array can be converted to a standard
3211  `std::vector<short>`\, (3) A JSON object can be converted to C++
3212  associative containers such as `std::unordered_map<std::string\,
3213  json>`.,get__ValueType_const}
3214 
3215  @since version 2.1.0
3216  */
3217  template <
3218  typename ValueTypeCV,
3219  typename ValueType = detail::uncvref_t<ValueTypeCV>,
3221  not std::is_same<basic_json_t, ValueType>::value and
3224  int > = 0 >
3225  ValueType get() const noexcept(noexcept(
3226  JSONSerializer<ValueType>::from_json(std::declval<const basic_json_t&>(), std::declval<ValueType&>())))
3227  {
3228  // we cannot static_assert on ValueTypeCV being non-const, because
3229  // there is support for get<const basic_json_t>(), which is why we
3230  // still need the uncvref
3231  static_assert(not std::is_reference<ValueTypeCV>::value,
3232  "get() cannot be used with reference types, you might want to use get_ref()");
3233  static_assert(std::is_default_constructible<ValueType>::value,
3234  "types must be DefaultConstructible when used with get()");
3235 
3236  ValueType ret;
3238  return ret;
3239  }
3240 
3241  /*!
3242  @brief get a value (explicit); special case
3243 
3244  Explicit type conversion between the JSON value and a compatible value
3245  which is **not** [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible)
3246  and **not** [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible).
3247  The value is converted by calling the @ref json_serializer<ValueType>
3248  `from_json()` method.
3249 
3250  The function is equivalent to executing
3251  @code {.cpp}
3252  return JSONSerializer<ValueTypeCV>::from_json(*this);
3253  @endcode
3254 
3255  This overloads is chosen if:
3256  - @a ValueType is not @ref basic_json and
3257  - @ref json_serializer<ValueType> has a `from_json()` method of the form
3258  `ValueType from_json(const @ref basic_json&)`
3259 
3260  @note If @ref json_serializer<ValueType> has both overloads of
3261  `from_json()`, this one is chosen.
3262 
3263  @tparam ValueTypeCV the provided value type
3264  @tparam ValueType the returned value type
3265 
3266  @return copy of the JSON value, converted to @a ValueType
3267 
3268  @throw what @ref json_serializer<ValueType> `from_json()` method throws
3269 
3270  @since version 2.1.0
3271  */
3272  template <
3273  typename ValueTypeCV,
3274  typename ValueType = detail::uncvref_t<ValueTypeCV>,
3277  ValueType>::value, int> = 0 >
3278  ValueType get() const noexcept(noexcept(
3279  JSONSerializer<ValueTypeCV>::from_json(std::declval<const basic_json_t&>())))
3280  {
3281  static_assert(not std::is_reference<ValueTypeCV>::value,
3282  "get() cannot be used with reference types, you might want to use get_ref()");
3284  }
3285 
3286  /*!
3287  @brief get a pointer value (explicit)
3288 
3289  Explicit pointer access to the internally stored JSON value. No copies are
3290  made.
3291 
3292  @warning The pointer becomes invalid if the underlying JSON object
3293  changes.
3294 
3295  @tparam PointerType pointer type; must be a pointer to @ref array_t, @ref
3296  object_t, @ref string_t, @ref boolean_t, @ref number_integer_t,
3297  @ref number_unsigned_t, or @ref number_float_t.
3298 
3299  @return pointer to the internally stored JSON value if the requested
3300  pointer type @a PointerType fits to the JSON value; `nullptr` otherwise
3301 
3302  @complexity Constant.
3303 
3304  @liveexample{The example below shows how pointers to internal values of a
3305  JSON value can be requested. Note that no type conversions are made and a
3306  `nullptr` is returned if the value and the requested pointer type does not
3307  match.,get__PointerType}
3308 
3309  @sa @ref get_ptr() for explicit pointer-member access
3310 
3311  @since version 1.0.0
3312  */
3313  template<typename PointerType, typename std::enable_if<
3314  std::is_pointer<PointerType>::value, int>::type = 0>
3315  PointerType get() noexcept
3316  {
3317  // delegate the call to get_ptr
3318  return get_ptr<PointerType>();
3319  }
3320 
3321  /*!
3322  @brief get a pointer value (explicit)
3323  @copydoc get()
3324  */
3325  template<typename PointerType, typename std::enable_if<
3326  std::is_pointer<PointerType>::value, int>::type = 0>
3327  constexpr const PointerType get() const noexcept
3328  {
3329  // delegate the call to get_ptr
3330  return get_ptr<PointerType>();
3331  }
3332 
3333  /*!
3334  @brief get a pointer value (implicit)
3335 
3336  Implicit pointer access to the internally stored JSON value. No copies are
3337  made.
3338 
3339  @warning Writing data to the pointee of the result yields an undefined
3340  state.
3341 
3342  @tparam PointerType pointer type; must be a pointer to @ref array_t, @ref
3343  object_t, @ref string_t, @ref boolean_t, @ref number_integer_t,
3344  @ref number_unsigned_t, or @ref number_float_t. Enforced by a static
3345  assertion.
3346 
3347  @return pointer to the internally stored JSON value if the requested
3348  pointer type @a PointerType fits to the JSON value; `nullptr` otherwise
3349 
3350  @complexity Constant.
3351 
3352  @liveexample{The example below shows how pointers to internal values of a
3353  JSON value can be requested. Note that no type conversions are made and a
3354  `nullptr` is returned if the value and the requested pointer type does not
3355  match.,get_ptr}
3356 
3357  @since version 1.0.0
3358  */
3359  template<typename PointerType, typename std::enable_if<
3360  std::is_pointer<PointerType>::value, int>::type = 0>
3361  PointerType get_ptr() noexcept
3362  {
3363  // get the type of the PointerType (remove pointer and const)
3364  using pointee_t = typename std::remove_const<typename
3365  std::remove_pointer<typename
3367  // make sure the type matches the allowed types
3368  static_assert(
3369  std::is_same<object_t, pointee_t>::value
3370  or std::is_same<array_t, pointee_t>::value
3371  or std::is_same<string_t, pointee_t>::value
3372  or std::is_same<boolean_t, pointee_t>::value
3373  or std::is_same<number_integer_t, pointee_t>::value
3374  or std::is_same<number_unsigned_t, pointee_t>::value
3375  or std::is_same<number_float_t, pointee_t>::value
3376  , "incompatible pointer type");
3377 
3378  // delegate the call to get_impl_ptr<>()
3379  return get_impl_ptr(static_cast<PointerType>(nullptr));
3380  }
3381 
3382  /*!
3383  @brief get a pointer value (implicit)
3384  @copydoc get_ptr()
3385  */
3386  template<typename PointerType, typename std::enable_if<
3387  std::is_pointer<PointerType>::value and
3389  constexpr const PointerType get_ptr() const noexcept
3390  {
3391  // get the type of the PointerType (remove pointer and const)
3392  using pointee_t = typename std::remove_const<typename
3393  std::remove_pointer<typename
3395  // make sure the type matches the allowed types
3396  static_assert(
3397  std::is_same<object_t, pointee_t>::value
3398  or std::is_same<array_t, pointee_t>::value
3399  or std::is_same<string_t, pointee_t>::value
3400  or std::is_same<boolean_t, pointee_t>::value
3401  or std::is_same<number_integer_t, pointee_t>::value
3402  or std::is_same<number_unsigned_t, pointee_t>::value
3403  or std::is_same<number_float_t, pointee_t>::value
3404  , "incompatible pointer type");
3405 
3406  // delegate the call to get_impl_ptr<>() const
3407  return get_impl_ptr(static_cast<const PointerType>(nullptr));
3408  }
3409 
3410  /*!
3411  @brief get a reference value (implicit)
3412 
3413  Implicit reference access to the internally stored JSON value. No copies
3414  are made.
3415 
3416  @warning Writing data to the referee of the result yields an undefined
3417  state.
3418 
3419  @tparam ReferenceType reference type; must be a reference to @ref array_t,
3420  @ref object_t, @ref string_t, @ref boolean_t, @ref number_integer_t, or
3421  @ref number_float_t. Enforced by static assertion.
3422 
3423  @return reference to the internally stored JSON value if the requested
3424  reference type @a ReferenceType fits to the JSON value; throws
3425  std::domain_error otherwise
3426 
3427  @throw std::domain_error in case passed type @a ReferenceType is
3428  incompatible with the stored JSON value
3429 
3430  @complexity Constant.
3431 
3432  @liveexample{The example shows several calls to `get_ref()`.,get_ref}
3433 
3434  @since version 1.1.0
3435  */
3436  template<typename ReferenceType, typename std::enable_if<
3437  std::is_reference<ReferenceType>::value, int>::type = 0>
3438  ReferenceType get_ref()
3439  {
3440  // delegate call to get_ref_impl
3441  return get_ref_impl<ReferenceType>(*this);
3442  }
3443 
3444  /*!
3445  @brief get a reference value (implicit)
3446  @copydoc get_ref()
3447  */
3448  template<typename ReferenceType, typename std::enable_if<
3449  std::is_reference<ReferenceType>::value and
3451  ReferenceType get_ref() const
3452  {
3453  // delegate call to get_ref_impl
3454  return get_ref_impl<ReferenceType>(*this);
3455  }
3456 
3457  /*!
3458  @brief get a value (implicit)
3459 
3460  Implicit type conversion between the JSON value and a compatible value.
3461  The call is realized by calling @ref get() const.
3462 
3463  @tparam ValueType non-pointer type compatible to the JSON value, for
3464  instance `int` for JSON integer numbers, `bool` for JSON booleans, or
3465  `std::vector` types for JSON arrays. The character type of @ref string_t
3466  as well as an initializer list of this type is excluded to avoid
3467  ambiguities as these types implicitly convert to `std::string`.
3468 
3469  @return copy of the JSON value, converted to type @a ValueType
3470 
3471  @throw std::domain_error in case passed type @a ValueType is incompatible
3472  to JSON, thrown by @ref get() const
3473 
3474  @complexity Linear in the size of the JSON value.
3475 
3476  @liveexample{The example below shows several conversions from JSON values
3477  to other types. There a few things to note: (1) Floating-point numbers can
3478  be converted to integers\, (2) A JSON array can be converted to a standard
3479  `std::vector<short>`\, (3) A JSON object can be converted to C++
3480  associative containers such as `std::unordered_map<std::string\,
3481  json>`.,operator__ValueType}
3482 
3483  @since version 1.0.0
3484  */
3485  template < typename ValueType, typename std::enable_if <
3486  not std::is_pointer<ValueType>::value and
3487  not std::is_same<ValueType, typename string_t::value_type>::value
3488 #ifndef _MSC_VER // fix for issue #167 operator<< ambiguity under VS2015
3489  and not std::is_same<ValueType, std::initializer_list<typename string_t::value_type>>::value
3490 #endif
3491  , int >::type = 0 >
3492  operator ValueType() const
3493  {
3494  // delegate the call to get<>() const
3495  return get<ValueType>();
3496  }
3497 
3498  /// @}
3499 
3500 
3501  ////////////////////
3502  // element access //
3503  ////////////////////
3504 
3505  /// @name element access
3506  /// Access to the JSON value.
3507  /// @{
3508 
3509  /*!
3510  @brief access specified array element with bounds checking
3511 
3512  Returns a reference to the element at specified location @a idx, with
3513  bounds checking.
3514 
3515  @param[in] idx index of the element to access
3516 
3517  @return reference to the element at index @a idx
3518 
3519  @throw std::domain_error if the JSON value is not an array; example:
3520  `"cannot use at() with string"`
3521  @throw std::out_of_range if the index @a idx is out of range of the array;
3522  that is, `idx >= size()`; example: `"array index 7 is out of range"`
3523 
3524  @complexity Constant.
3525 
3526  @liveexample{The example below shows how array elements can be read and
3527  written using `at()`.,at__size_type}
3528 
3529  @since version 1.0.0
3530  */
3532  {
3533  // at only works for arrays
3534  if (is_array())
3535  {
3536  JSON_TRY
3537  {
3538  return m_value.array->at(idx);
3539  }
3540  JSON_CATCH (std::out_of_range&)
3541  {
3542  // create better exception explanation
3543  JSON_THROW(std::out_of_range("array index " + std::to_string(idx) + " is out of range"));
3544  }
3545  }
3546  else
3547  {
3548  JSON_THROW(std::domain_error("cannot use at() with " + type_name()));
3549  }
3550  }
3551 
3552  /*!
3553  @brief access specified array element with bounds checking
3554 
3555  Returns a const reference to the element at specified location @a idx,
3556  with bounds checking.
3557 
3558  @param[in] idx index of the element to access
3559 
3560  @return const reference to the element at index @a idx
3561 
3562  @throw std::domain_error if the JSON value is not an array; example:
3563  `"cannot use at() with string"`
3564  @throw std::out_of_range if the index @a idx is out of range of the array;
3565  that is, `idx >= size()`; example: `"array index 7 is out of range"`
3566 
3567  @complexity Constant.
3568 
3569  @liveexample{The example below shows how array elements can be read using
3570  `at()`.,at__size_type_const}
3571 
3572  @since version 1.0.0
3573  */
3575  {
3576  // at only works for arrays
3577  if (is_array())
3578  {
3579  JSON_TRY
3580  {
3581  return m_value.array->at(idx);
3582  }
3583  JSON_CATCH (std::out_of_range&)
3584  {
3585  // create better exception explanation
3586  JSON_THROW(std::out_of_range("array index " + std::to_string(idx) + " is out of range"));
3587  }
3588  }
3589  else
3590  {
3591  JSON_THROW(std::domain_error("cannot use at() with " + type_name()));
3592  }
3593  }
3594 
3595  /*!
3596  @brief access specified object element with bounds checking
3597 
3598  Returns a reference to the element at with specified key @a key, with
3599  bounds checking.
3600 
3601  @param[in] key key of the element to access
3602 
3603  @return reference to the element at key @a key
3604 
3605  @throw std::domain_error if the JSON value is not an object; example:
3606  `"cannot use at() with boolean"`
3607  @throw std::out_of_range if the key @a key is is not stored in the object;
3608  that is, `find(key) == end()`; example: `"key "the fast" not found"`
3609 
3610  @complexity Logarithmic in the size of the container.
3611 
3612  @liveexample{The example below shows how object elements can be read and
3613  written using `at()`.,at__object_t_key_type}
3614 
3615  @sa @ref operator[](const typename object_t::key_type&) for unchecked
3616  access by reference
3617  @sa @ref value() for access by value with a default value
3618 
3619  @since version 1.0.0
3620  */
3621  reference at(const typename object_t::key_type& key)
3622  {
3623  // at only works for objects
3624  if (is_object())
3625  {
3626  JSON_TRY
3627  {
3628  return m_value.object->at(key);
3629  }
3630  JSON_CATCH (std::out_of_range&)
3631  {
3632  // create better exception explanation
3633  JSON_THROW(std::out_of_range("key '" + key + "' not found"));
3634  }
3635  }
3636  else
3637  {
3638  JSON_THROW(std::domain_error("cannot use at() with " + type_name()));
3639  }
3640  }
3641 
3642  /*!
3643  @brief access specified object element with bounds checking
3644 
3645  Returns a const reference to the element at with specified key @a key,
3646  with bounds checking.
3647 
3648  @param[in] key key of the element to access
3649 
3650  @return const reference to the element at key @a key
3651 
3652  @throw std::domain_error if the JSON value is not an object; example:
3653  `"cannot use at() with boolean"`
3654  @throw std::out_of_range if the key @a key is is not stored in the object;
3655  that is, `find(key) == end()`; example: `"key "the fast" not found"`
3656 
3657  @complexity Logarithmic in the size of the container.
3658 
3659  @liveexample{The example below shows how object elements can be read using
3660  `at()`.,at__object_t_key_type_const}
3661 
3662  @sa @ref operator[](const typename object_t::key_type&) for unchecked
3663  access by reference
3664  @sa @ref value() for access by value with a default value
3665 
3666  @since version 1.0.0
3667  */
3668  const_reference at(const typename object_t::key_type& key) const
3669  {
3670  // at only works for objects
3671  if (is_object())
3672  {
3673  JSON_TRY
3674  {
3675  return m_value.object->at(key);
3676  }
3677  JSON_CATCH (std::out_of_range&)
3678  {
3679  // create better exception explanation
3680  JSON_THROW(std::out_of_range("key '" + key + "' not found"));
3681  }
3682  }
3683  else
3684  {
3685  JSON_THROW(std::domain_error("cannot use at() with " + type_name()));
3686  }
3687  }
3688 
3689  /*!
3690  @brief access specified array element
3691 
3692  Returns a reference to the element at specified location @a idx.
3693 
3694  @note If @a idx is beyond the range of the array (i.e., `idx >= size()`),
3695  then the array is silently filled up with `null` values to make `idx` a
3696  valid reference to the last stored element.
3697 
3698  @param[in] idx index of the element to access
3699 
3700  @return reference to the element at index @a idx
3701 
3702  @throw std::domain_error if JSON is not an array or null; example:
3703  `"cannot use operator[] with string"`
3704 
3705  @complexity Constant if @a idx is in the range of the array. Otherwise
3706  linear in `idx - size()`.
3707 
3708  @liveexample{The example below shows how array elements can be read and
3709  written using `[]` operator. Note the addition of `null`
3710  values.,operatorarray__size_type}
3711 
3712  @since version 1.0.0
3713  */
3715  {
3716  // implicitly convert null value to an empty array
3717  if (is_null())
3718  {
3719  m_type = value_t::array;
3720  m_value.array = create<array_t>();
3721  assert_invariant();
3722  }
3723 
3724  // operator[] only works for arrays
3725  if (is_array())
3726  {
3727  // fill up array with null values if given idx is outside range
3728  if (idx >= m_value.array->size())
3729  {
3730  m_value.array->insert(m_value.array->end(),
3731  idx - m_value.array->size() + 1,
3732  basic_json());
3733  }
3734 
3735  return m_value.array->operator[](idx);
3736  }
3737 
3738  JSON_THROW(std::domain_error("cannot use operator[] with " + type_name()));
3739  }
3740 
3741  /*!
3742  @brief access specified array element
3743 
3744  Returns a const reference to the element at specified location @a idx.
3745 
3746  @param[in] idx index of the element to access
3747 
3748  @return const reference to the element at index @a idx
3749 
3750  @throw std::domain_error if JSON is not an array; example: `"cannot use
3751  operator[] with null"`
3752 
3753  @complexity Constant.
3754 
3755  @liveexample{The example below shows how array elements can be read using
3756  the `[]` operator.,operatorarray__size_type_const}
3757 
3758  @since version 1.0.0
3759  */
3761  {
3762  // const operator[] only works for arrays
3763  if (is_array())
3764  {
3765  return m_value.array->operator[](idx);
3766  }
3767 
3768  JSON_THROW(std::domain_error("cannot use operator[] with " + type_name()));
3769  }
3770 
3771  /*!
3772  @brief access specified object element
3773 
3774  Returns a reference to the element at with specified key @a key.
3775 
3776  @note If @a key is not found in the object, then it is silently added to
3777  the object and filled with a `null` value to make `key` a valid reference.
3778  In case the value was `null` before, it is converted to an object.
3779 
3780  @param[in] key key of the element to access
3781 
3782  @return reference to the element at key @a key
3783 
3784  @throw std::domain_error if JSON is not an object or null; example:
3785  `"cannot use operator[] with string"`
3786 
3787  @complexity Logarithmic in the size of the container.
3788 
3789  @liveexample{The example below shows how object elements can be read and
3790  written using the `[]` operator.,operatorarray__key_type}
3791 
3792  @sa @ref at(const typename object_t::key_type&) for access by reference
3793  with range checking
3794  @sa @ref value() for access by value with a default value
3795 
3796  @since version 1.0.0
3797  */
3798  reference operator[](const typename object_t::key_type& key)
3799  {
3800  // implicitly convert null value to an empty object
3801  if (is_null())
3802  {
3803  m_type = value_t::object;
3804  m_value.object = create<object_t>();
3805  assert_invariant();
3806  }
3807 
3808  // operator[] only works for objects
3809  if (is_object())
3810  {
3811  return m_value.object->operator[](key);
3812  }
3813 
3814  JSON_THROW(std::domain_error("cannot use operator[] with " + type_name()));
3815  }
3816 
3817  /*!
3818  @brief read-only access specified object element
3819 
3820  Returns a const reference to the element at with specified key @a key. No
3821  bounds checking is performed.
3822 
3823  @warning If the element with key @a key does not exist, the behavior is
3824  undefined.
3825 
3826  @param[in] key key of the element to access
3827 
3828  @return const reference to the element at key @a key
3829 
3830  @pre The element with key @a key must exist. **This precondition is
3831  enforced with an assertion.**
3832 
3833  @throw std::domain_error if JSON is not an object; example: `"cannot use
3834  operator[] with null"`
3835 
3836  @complexity Logarithmic in the size of the container.
3837 
3838  @liveexample{The example below shows how object elements can be read using
3839  the `[]` operator.,operatorarray__key_type_const}
3840 
3841  @sa @ref at(const typename object_t::key_type&) for access by reference
3842  with range checking
3843  @sa @ref value() for access by value with a default value
3844 
3845  @since version 1.0.0
3846  */
3847  const_reference operator[](const typename object_t::key_type& key) const
3848  {
3849  // const operator[] only works for objects
3850  if (is_object())
3851  {
3852  assert(m_value.object->find(key) != m_value.object->end());
3853  return m_value.object->find(key)->second;
3854  }
3855 
3856  JSON_THROW(std::domain_error("cannot use operator[] with " + type_name()));
3857  }
3858 
3859  /*!
3860  @brief access specified object element
3861 
3862  Returns a reference to the element at with specified key @a key.
3863 
3864  @note If @a key is not found in the object, then it is silently added to
3865  the object and filled with a `null` value to make `key` a valid reference.
3866  In case the value was `null` before, it is converted to an object.
3867 
3868  @param[in] key key of the element to access
3869 
3870  @return reference to the element at key @a key
3871 
3872  @throw std::domain_error if JSON is not an object or null; example:
3873  `"cannot use operator[] with string"`
3874 
3875  @complexity Logarithmic in the size of the container.
3876 
3877  @liveexample{The example below shows how object elements can be read and
3878  written using the `[]` operator.,operatorarray__key_type}
3879 
3880  @sa @ref at(const typename object_t::key_type&) for access by reference
3881  with range checking
3882  @sa @ref value() for access by value with a default value
3883 
3884  @since version 1.0.0
3885  */
3886  template<typename T, std::size_t n>
3887  reference operator[](T * (&key)[n])
3888  {
3889  return operator[](static_cast<const T>(key));
3890  }
3891 
3892  /*!
3893  @brief read-only access specified object element
3894 
3895  Returns a const reference to the element at with specified key @a key. No
3896  bounds checking is performed.
3897 
3898  @warning If the element with key @a key does not exist, the behavior is
3899  undefined.
3900 
3901  @note This function is required for compatibility reasons with Clang.
3902 
3903  @param[in] key key of the element to access
3904 
3905  @return const reference to the element at key @a key
3906 
3907  @throw std::domain_error if JSON is not an object; example: `"cannot use
3908  operator[] with null"`
3909 
3910  @complexity Logarithmic in the size of the container.
3911 
3912  @liveexample{The example below shows how object elements can be read using
3913  the `[]` operator.,operatorarray__key_type_const}
3914 
3915  @sa @ref at(const typename object_t::key_type&) for access by reference
3916  with range checking
3917  @sa @ref value() for access by value with a default value
3918 
3919  @since version 1.0.0
3920  */
3921  template<typename T, std::size_t n>
3922  const_reference operator[](T * (&key)[n]) const
3923  {
3924  return operator[](static_cast<const T>(key));
3925  }
3926 
3927  /*!
3928  @brief access specified object element
3929 
3930  Returns a reference to the element at with specified key @a key.
3931 
3932  @note If @a key is not found in the object, then it is silently added to
3933  the object and filled with a `null` value to make `key` a valid reference.
3934  In case the value was `null` before, it is converted to an object.
3935 
3936  @param[in] key key of the element to access
3937 
3938  @return reference to the element at key @a key
3939 
3940  @throw std::domain_error if JSON is not an object or null; example:
3941  `"cannot use operator[] with string"`
3942 
3943  @complexity Logarithmic in the size of the container.
3944 
3945  @liveexample{The example below shows how object elements can be read and
3946  written using the `[]` operator.,operatorarray__key_type}
3947 
3948  @sa @ref at(const typename object_t::key_type&) for access by reference
3949  with range checking
3950  @sa @ref value() for access by value with a default value
3951 
3952  @since version 1.1.0
3953  */
3954  template<typename T>
3956  {
3957  // implicitly convert null to object
3958  if (is_null())
3959  {
3960  m_type = value_t::object;
3961  m_value = value_t::object;
3962  assert_invariant();
3963  }
3964 
3965  // at only works for objects
3966  if (is_object())
3967  {
3968  return m_value.object->operator[](key);
3969  }
3970 
3971  JSON_THROW(std::domain_error("cannot use operator[] with " + type_name()));
3972  }
3973 
3974  /*!
3975  @brief read-only access specified object element
3976 
3977  Returns a const reference to the element at with specified key @a key. No
3978  bounds checking is performed.
3979 
3980  @warning If the element with key @a key does not exist, the behavior is
3981  undefined.
3982 
3983  @param[in] key key of the element to access
3984 
3985  @return const reference to the element at key @a key
3986 
3987  @pre The element with key @a key must exist. **This precondition is
3988  enforced with an assertion.**
3989 
3990  @throw std::domain_error if JSON is not an object; example: `"cannot use
3991  operator[] with null"`
3992 
3993  @complexity Logarithmic in the size of the container.
3994 
3995  @liveexample{The example below shows how object elements can be read using
3996  the `[]` operator.,operatorarray__key_type_const}
3997 
3998  @sa @ref at(const typename object_t::key_type&) for access by reference
3999  with range checking
4000  @sa @ref value() for access by value with a default value
4001 
4002  @since version 1.1.0
4003  */
4004  template<typename T>
4006  {
4007  // at only works for objects
4008  if (is_object())
4009  {
4010  assert(m_value.object->find(key) != m_value.object->end());
4011  return m_value.object->find(key)->second;
4012  }
4013 
4014  JSON_THROW(std::domain_error("cannot use operator[] with " + type_name()));
4015  }
4016 
4017  /*!
4018  @brief access specified object element with default value
4019 
4020  Returns either a copy of an object's element at the specified key @a key
4021  or a given default value if no element with key @a key exists.
4022 
4023  The function is basically equivalent to executing
4024  @code {.cpp}
4025  try {
4026  return at(key);
4027  } catch(std::out_of_range) {
4028  return default_value;
4029  }
4030  @endcode
4031 
4032  @note Unlike @ref at(const typename object_t::key_type&), this function
4033  does not throw if the given key @a key was not found.
4034 
4035  @note Unlike @ref operator[](const typename object_t::key_type& key), this
4036  function does not implicitly add an element to the position defined by @a
4037  key. This function is furthermore also applicable to const objects.
4038 
4039  @param[in] key key of the element to access
4040  @param[in] default_value the value to return if @a key is not found
4041 
4042  @tparam ValueType type compatible to JSON values, for instance `int` for
4043  JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
4044  JSON arrays. Note the type of the expected value at @a key and the default
4045  value @a default_value must be compatible.
4046 
4047  @return copy of the element at key @a key or @a default_value if @a key
4048  is not found
4049 
4050  @throw std::domain_error if JSON is not an object; example: `"cannot use
4051  value() with null"`
4052 
4053  @complexity Logarithmic in the size of the container.
4054 
4055  @liveexample{The example below shows how object elements can be queried
4056  with a default value.,basic_json__value}
4057 
4058  @sa @ref at(const typename object_t::key_type&) for access by reference
4059  with range checking
4060  @sa @ref operator[](const typename object_t::key_type&) for unchecked
4061  access by reference
4062 
4063  @since version 1.0.0
4064  */
4065  template<class ValueType, typename std::enable_if<
4066  std::is_convertible<basic_json_t, ValueType>::value, int>::type = 0>
4067  ValueType value(const typename object_t::key_type& key, ValueType default_value) const
4068  {
4069  // at only works for objects
4070  if (is_object())
4071  {
4072  // if key is found, return value and given default value otherwise
4073  const auto it = find(key);
4074  if (it != end())
4075  {
4076  return *it;
4077  }
4078 
4079  return default_value;
4080  }
4081  else
4082  {
4083  JSON_THROW(std::domain_error("cannot use value() with " + type_name()));
4084  }
4085  }
4086 
4087  /*!
4088  @brief overload for a default value of type const char*
4089  @copydoc basic_json::value(const typename object_t::key_type&, ValueType) const
4090  */
4091  string_t value(const typename object_t::key_type& key, const char* default_value) const
4092  {
4093  return value(key, string_t(default_value));
4094  }
4095 
4096  /*!
4097  @brief access specified object element via JSON Pointer with default value
4098 
4099  Returns either a copy of an object's element at the specified key @a key
4100  or a given default value if no element with key @a key exists.
4101 
4102  The function is basically equivalent to executing
4103  @code {.cpp}
4104  try {
4105  return at(ptr);
4106  } catch(std::out_of_range) {
4107  return default_value;
4108  }
4109  @endcode
4110 
4111  @note Unlike @ref at(const json_pointer&), this function does not throw
4112  if the given key @a key was not found.
4113 
4114  @param[in] ptr a JSON pointer to the element to access
4115  @param[in] default_value the value to return if @a ptr found no value
4116 
4117  @tparam ValueType type compatible to JSON values, for instance `int` for
4118  JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
4119  JSON arrays. Note the type of the expected value at @a key and the default
4120  value @a default_value must be compatible.
4121 
4122  @return copy of the element at key @a key or @a default_value if @a key
4123  is not found
4124 
4125  @throw std::domain_error if JSON is not an object; example: `"cannot use
4126  value() with null"`
4127 
4128  @complexity Logarithmic in the size of the container.
4129 
4130  @liveexample{The example below shows how object elements can be queried
4131  with a default value.,basic_json__value_ptr}
4132 
4133  @sa @ref operator[](const json_pointer&) for unchecked access by reference
4134 
4135  @since version 2.0.2
4136  */
4137  template<class ValueType, typename std::enable_if<
4138  std::is_convertible<basic_json_t, ValueType>::value, int>::type = 0>
4139  ValueType value(const json_pointer& ptr, ValueType default_value) const
4140  {
4141  // at only works for objects
4142  if (is_object())
4143  {
4144  // if pointer resolves a value, return it or use default value
4145  JSON_TRY
4146  {
4147  return ptr.get_checked(this);
4148  }
4149  JSON_CATCH (std::out_of_range&)
4150  {
4151  return default_value;
4152  }
4153  }
4154 
4155  JSON_THROW(std::domain_error("cannot use value() with " + type_name()));
4156  }
4157 
4158  /*!
4159  @brief overload for a default value of type const char*
4160  @copydoc basic_json::value(const json_pointer&, ValueType) const
4161  */
4162  string_t value(const json_pointer& ptr, const char* default_value) const
4163  {
4164  return value(ptr, string_t(default_value));
4165  }
4166 
4167  /*!
4168  @brief access the first element
4169 
4170  Returns a reference to the first element in the container. For a JSON
4171  container `c`, the expression `c.front()` is equivalent to `*c.begin()`.
4172 
4173  @return In case of a structured type (array or object), a reference to the
4174  first element is returned. In case of number, string, or boolean values, a
4175  reference to the value is returned.
4176 
4177  @complexity Constant.
4178 
4179  @pre The JSON value must not be `null` (would throw `std::out_of_range`)
4180  or an empty array or object (undefined behavior, **guarded by
4181  assertions**).
4182  @post The JSON value remains unchanged.
4183 
4184  @throw std::out_of_range when called on `null` value
4185 
4186  @liveexample{The following code shows an example for `front()`.,front}
4187 
4188  @sa @ref back() -- access the last element
4189 
4190  @since version 1.0.0
4191  */
4193  {
4194  return *begin();
4195  }
4196 
4197  /*!
4198  @copydoc basic_json::front()
4199  */
4201  {
4202  return *cbegin();
4203  }
4204 
4205  /*!
4206  @brief access the last element
4207 
4208  Returns a reference to the last element in the container. For a JSON
4209  container `c`, the expression `c.back()` is equivalent to
4210  @code {.cpp}
4211  auto tmp = c.end();
4212  --tmp;
4213  return *tmp;
4214  @endcode
4215 
4216  @return In case of a structured type (array or object), a reference to the
4217  last element is returned. In case of number, string, or boolean values, a
4218  reference to the value is returned.
4219 
4220  @complexity Constant.
4221 
4222  @pre The JSON value must not be `null` (would throw `std::out_of_range`)
4223  or an empty array or object (undefined behavior, **guarded by
4224  assertions**).
4225  @post The JSON value remains unchanged.
4226 
4227  @throw std::out_of_range when called on `null` value.
4228 
4229  @liveexample{The following code shows an example for `back()`.,back}
4230 
4231  @sa @ref front() -- access the first element
4232 
4233  @since version 1.0.0
4234  */
4236  {
4237  auto tmp = end();
4238  --tmp;
4239  return *tmp;
4240  }
4241 
4242  /*!
4243  @copydoc basic_json::back()
4244  */
4246  {
4247  auto tmp = cend();
4248  --tmp;
4249  return *tmp;
4250  }
4251 
4252  /*!
4253  @brief remove element given an iterator
4254 
4255  Removes the element specified by iterator @a pos. The iterator @a pos must
4256  be valid and dereferenceable. Thus the `end()` iterator (which is valid,
4257  but is not dereferenceable) cannot be used as a value for @a pos.
4258 
4259  If called on a primitive type other than `null`, the resulting JSON value
4260  will be `null`.
4261 
4262  @param[in] pos iterator to the element to remove
4263  @return Iterator following the last removed element. If the iterator @a
4264  pos refers to the last element, the `end()` iterator is returned.
4265 
4266  @tparam IteratorType an @ref iterator or @ref const_iterator
4267 
4268  @post Invalidates iterators and references at or after the point of the
4269  erase, including the `end()` iterator.
4270 
4271  @throw std::domain_error if called on a `null` value; example: `"cannot
4272  use erase() with null"`
4273  @throw std::domain_error if called on an iterator which does not belong to
4274  the current JSON value; example: `"iterator does not fit current value"`
4275  @throw std::out_of_range if called on a primitive type with invalid
4276  iterator (i.e., any iterator which is not `begin()`); example: `"iterator
4277  out of range"`
4278 
4279  @complexity The complexity depends on the type:
4280  - objects: amortized constant
4281  - arrays: linear in distance between @a pos and the end of the container
4282  - strings: linear in the length of the string
4283  - other types: constant
4284 
4285  @liveexample{The example shows the result of `erase()` for different JSON
4286  types.,erase__IteratorType}
4287 
4288  @sa @ref erase(IteratorType, IteratorType) -- removes the elements in
4289  the given range
4290  @sa @ref erase(const typename object_t::key_type&) -- removes the element
4291  from an object at the given key
4292  @sa @ref erase(const size_type) -- removes the element from an array at
4293  the given index
4294 
4295  @since version 1.0.0
4296  */
4297  template<class IteratorType, typename std::enable_if<
4298  std::is_same<IteratorType, typename basic_json_t::iterator>::value or
4299  std::is_same<IteratorType, typename basic_json_t::const_iterator>::value, int>::type
4300  = 0>
4301  IteratorType erase(IteratorType pos)
4302  {
4303  // make sure iterator fits the current value
4304  if (this != pos.m_object)
4305  {
4306  JSON_THROW(std::domain_error("iterator does not fit current value"));
4307  }
4308 
4309  IteratorType result = end();
4310 
4311  switch (m_type)
4312  {
4313  case value_t::boolean:
4314  case value_t::number_float:
4317  case value_t::string:
4318  {
4319  if (not pos.m_it.primitive_iterator.is_begin())
4320  {
4321  JSON_THROW(std::out_of_range("iterator out of range"));
4322  }
4323 
4324  if (is_string())
4325  {
4326  AllocatorType<string_t> alloc;
4327  alloc.destroy(m_value.string);
4328  alloc.deallocate(m_value.string, 1);
4329  m_value.string = nullptr;
4330  }
4331 
4332  m_type = value_t::null;
4333  assert_invariant();
4334  break;
4335  }
4336 
4337  case value_t::object:
4338  {
4339  result.m_it.object_iterator = m_value.object->erase(pos.m_it.object_iterator);
4340  break;
4341  }
4342 
4343  case value_t::array:
4344  {
4345  result.m_it.array_iterator = m_value.array->erase(pos.m_it.array_iterator);
4346  break;
4347  }
4348 
4349  default:
4350  {
4351  JSON_THROW(std::domain_error("cannot use erase() with " + type_name()));
4352  }
4353  }
4354 
4355  return result;
4356  }
4357 
4358  /*!
4359  @brief remove elements given an iterator range
4360 
4361  Removes the element specified by the range `[first; last)`. The iterator
4362  @a first does not need to be dereferenceable if `first == last`: erasing
4363  an empty range is a no-op.
4364 
4365  If called on a primitive type other than `null`, the resulting JSON value
4366  will be `null`.
4367 
4368  @param[in] first iterator to the beginning of the range to remove
4369  @param[in] last iterator past the end of the range to remove
4370  @return Iterator following the last removed element. If the iterator @a
4371  second refers to the last element, the `end()` iterator is returned.
4372 
4373  @tparam IteratorType an @ref iterator or @ref const_iterator
4374 
4375  @post Invalidates iterators and references at or after the point of the
4376  erase, including the `end()` iterator.
4377 
4378  @throw std::domain_error if called on a `null` value; example: `"cannot
4379  use erase() with null"`
4380  @throw std::domain_error if called on iterators which does not belong to
4381  the current JSON value; example: `"iterators do not fit current value"`
4382  @throw std::out_of_range if called on a primitive type with invalid
4383  iterators (i.e., if `first != begin()` and `last != end()`); example:
4384  `"iterators out of range"`
4385 
4386  @complexity The complexity depends on the type:
4387  - objects: `log(size()) + std::distance(first, last)`
4388  - arrays: linear in the distance between @a first and @a last, plus linear
4389  in the distance between @a last and end of the container
4390  - strings: linear in the length of the string
4391  - other types: constant
4392 
4393  @liveexample{The example shows the result of `erase()` for different JSON
4394  types.,erase__IteratorType_IteratorType}
4395 
4396  @sa @ref erase(IteratorType) -- removes the element at a given position
4397  @sa @ref erase(const typename object_t::key_type&) -- removes the element
4398  from an object at the given key
4399  @sa @ref erase(const size_type) -- removes the element from an array at
4400  the given index
4401 
4402  @since version 1.0.0
4403  */
4404  template<class IteratorType, typename std::enable_if<
4405  std::is_same<IteratorType, typename basic_json_t::iterator>::value or
4406  std::is_same<IteratorType, typename basic_json_t::const_iterator>::value, int>::type
4407  = 0>
4408  IteratorType erase(IteratorType first, IteratorType last)
4409  {
4410  // make sure iterator fits the current value
4411  if (this != first.m_object or this != last.m_object)
4412  {
4413  JSON_THROW(std::domain_error("iterators do not fit current value"));
4414  }
4415 
4416  IteratorType result = end();
4417 
4418  switch (m_type)
4419  {
4420  case value_t::boolean:
4421  case value_t::number_float:
4424  case value_t::string:
4425  {
4426  if (not first.m_it.primitive_iterator.is_begin() or not last.m_it.primitive_iterator.is_end())
4427  {
4428  JSON_THROW(std::out_of_range("iterators out of range"));
4429  }
4430 
4431  if (is_string())
4432  {
4433  AllocatorType<string_t> alloc;
4434  alloc.destroy(m_value.string);
4435  alloc.deallocate(m_value.string, 1);
4436  m_value.string = nullptr;
4437  }
4438 
4439  m_type = value_t::null;
4440  assert_invariant();
4441  break;
4442  }
4443 
4444  case value_t::object:
4445  {
4446  result.m_it.object_iterator = m_value.object->erase(first.m_it.object_iterator,
4447  last.m_it.object_iterator);
4448  break;
4449  }
4450 
4451  case value_t::array:
4452  {
4453  result.m_it.array_iterator = m_value.array->erase(first.m_it.array_iterator,
4454  last.m_it.array_iterator);
4455  break;
4456  }
4457 
4458  default:
4459  {
4460  JSON_THROW(std::domain_error("cannot use erase() with " + type_name()));
4461  }
4462  }
4463 
4464  return result;
4465  }
4466 
4467  /*!
4468  @brief remove element from a JSON object given a key
4469 
4470  Removes elements from a JSON object with the key value @a key.
4471 
4472  @param[in] key value of the elements to remove
4473 
4474  @return Number of elements removed. If @a ObjectType is the default
4475  `std::map` type, the return value will always be `0` (@a key was not
4476  found) or `1` (@a key was found).
4477 
4478  @post References and iterators to the erased elements are invalidated.
4479  Other references and iterators are not affected.
4480 
4481  @throw std::domain_error when called on a type other than JSON object;
4482  example: `"cannot use erase() with null"`
4483 
4484  @complexity `log(size()) + count(key)`
4485 
4486  @liveexample{The example shows the effect of `erase()`.,erase__key_type}
4487 
4488  @sa @ref erase(IteratorType) -- removes the element at a given position
4489  @sa @ref erase(IteratorType, IteratorType) -- removes the elements in
4490  the given range
4491  @sa @ref erase(const size_type) -- removes the element from an array at
4492  the given index
4493 
4494  @since version 1.0.0
4495  */
4496  size_type erase(const typename object_t::key_type& key)
4497  {
4498  // this erase only works for objects
4499  if (is_object())
4500  {
4501  return m_value.object->erase(key);
4502  }
4503 
4504  JSON_THROW(std::domain_error("cannot use erase() with " + type_name()));
4505  }
4506 
4507  /*!
4508  @brief remove element from a JSON array given an index
4509 
4510  Removes element from a JSON array at the index @a idx.
4511 
4512  @param[in] idx index of the element to remove
4513 
4514  @throw std::domain_error when called on a type other than JSON array;
4515  example: `"cannot use erase() with null"`
4516  @throw std::out_of_range when `idx >= size()`; example: `"array index 17
4517  is out of range"`
4518 
4519  @complexity Linear in distance between @a idx and the end of the container.
4520 
4521  @liveexample{The example shows the effect of `erase()`.,erase__size_type}
4522 
4523  @sa @ref erase(IteratorType) -- removes the element at a given position
4524  @sa @ref erase(IteratorType, IteratorType) -- removes the elements in
4525  the given range
4526  @sa @ref erase(const typename object_t::key_type&) -- removes the element
4527  from an object at the given key
4528 
4529  @since version 1.0.0
4530  */
4531  void erase(const size_type idx)
4532  {
4533  // this erase only works for arrays
4534  if (is_array())
4535  {
4536  if (idx >= size())
4537  {
4538  JSON_THROW(std::out_of_range("array index " + std::to_string(idx) + " is out of range"));
4539  }
4540 
4541  m_value.array->erase(m_value.array->begin() + static_cast<difference_type>(idx));
4542  }
4543  else
4544  {
4545  JSON_THROW(std::domain_error("cannot use erase() with " + type_name()));
4546  }
4547  }
4548 
4549  /// @}
4550 
4551 
4552  ////////////
4553  // lookup //
4554  ////////////
4555 
4556  /// @name lookup
4557  /// @{
4558 
4559  /*!
4560  @brief find an element in a JSON object
4561 
4562  Finds an element in a JSON object with key equivalent to @a key. If the
4563  element is not found or the JSON value is not an object, end() is
4564  returned.
4565 
4566  @note This method always returns @ref end() when executed on a JSON type
4567  that is not an object.
4568 
4569  @param[in] key key value of the element to search for
4570 
4571  @return Iterator to an element with key equivalent to @a key. If no such
4572  element is found or the JSON value is not an object, past-the-end (see
4573  @ref end()) iterator is returned.
4574 
4575  @complexity Logarithmic in the size of the JSON object.
4576 
4577  @liveexample{The example shows how `find()` is used.,find__key_type}
4578 
4579  @since version 1.0.0
4580  */
4581  iterator find(typename object_t::key_type key)
4582  {
4583  auto result = end();
4584 
4585  if (is_object())
4586  {
4587  result.m_it.object_iterator = m_value.object->find(key);
4588  }
4589 
4590  return result;
4591  }
4592 
4593  /*!
4594  @brief find an element in a JSON object
4595  @copydoc find(typename object_t::key_type)
4596  */
4597  const_iterator find(typename object_t::key_type key) const
4598  {
4599  auto result = cend();
4600 
4601  if (is_object())
4602  {
4603  result.m_it.object_iterator = m_value.object->find(key);
4604  }
4605 
4606  return result;
4607  }
4608 
4609  /*!
4610  @brief returns the number of occurrences of a key in a JSON object
4611 
4612  Returns the number of elements with key @a key. If ObjectType is the
4613  default `std::map` type, the return value will always be `0` (@a key was
4614  not found) or `1` (@a key was found).
4615 
4616  @note This method always returns `0` when executed on a JSON type that is
4617  not an object.
4618 
4619  @param[in] key key value of the element to count
4620 
4621  @return Number of elements with key @a key. If the JSON value is not an
4622  object, the return value will be `0`.
4623 
4624  @complexity Logarithmic in the size of the JSON object.
4625 
4626  @liveexample{The example shows how `count()` is used.,count}
4627 
4628  @since version 1.0.0
4629  */
4630  size_type count(typename object_t::key_type key) const
4631  {
4632  // return 0 for all nonobject types
4633  return is_object() ? m_value.object->count(key) : 0;
4634  }
4635 
4636  /// @}
4637 
4638 
4639  ///////////////
4640  // iterators //
4641  ///////////////
4642 
4643  /// @name iterators
4644  /// @{
4645 
4646  /*!
4647  @brief returns an iterator to the first element
4648 
4649  Returns an iterator to the first element.
4650 
4651  @image html range-begin-end.svg "Illustration from cppreference.com"
4652 
4653  @return iterator to the first element
4654 
4655  @complexity Constant.
4656 
4657  @requirement This function helps `basic_json` satisfying the
4658  [Container](http://en.cppreference.com/w/cpp/concept/Container)
4659  requirements:
4660  - The complexity is constant.
4661 
4662  @liveexample{The following code shows an example for `begin()`.,begin}
4663 
4664  @sa @ref cbegin() -- returns a const iterator to the beginning
4665  @sa @ref end() -- returns an iterator to the end
4666  @sa @ref cend() -- returns a const iterator to the end
4667 
4668  @since version 1.0.0
4669  */
4670  iterator begin() noexcept
4671  {
4672  iterator result(this);
4673  result.set_begin();
4674  return result;
4675  }
4676 
4677  /*!
4678  @copydoc basic_json::cbegin()
4679  */
4680  const_iterator begin() const noexcept
4681  {
4682  return cbegin();
4683  }
4684 
4685  /*!
4686  @brief returns a const iterator to the first element
4687 
4688  Returns a const iterator to the first element.
4689 
4690  @image html range-begin-end.svg "Illustration from cppreference.com"
4691 
4692  @return const iterator to the first element
4693 
4694  @complexity Constant.
4695 
4696  @requirement This function helps `basic_json` satisfying the
4697  [Container](http://en.cppreference.com/w/cpp/concept/Container)
4698  requirements:
4699  - The complexity is constant.
4700  - Has the semantics of `const_cast<const basic_json&>(*this).begin()`.
4701 
4702  @liveexample{The following code shows an example for `cbegin()`.,cbegin}
4703 
4704  @sa @ref begin() -- returns an iterator to the beginning
4705  @sa @ref end() -- returns an iterator to the end
4706  @sa @ref cend() -- returns a const iterator to the end
4707 
4708  @since version 1.0.0
4709  */
4710  const_iterator cbegin() const noexcept
4711  {
4712  const_iterator result(this);
4713  result.set_begin();
4714  return result;
4715  }
4716 
4717  /*!
4718  @brief returns an iterator to one past the last element
4719 
4720  Returns an iterator to one past the last element.
4721 
4722  @image html range-begin-end.svg "Illustration from cppreference.com"
4723 
4724  @return iterator one past the last element
4725 
4726  @complexity Constant.
4727 
4728  @requirement This function helps `basic_json` satisfying the
4729  [Container](http://en.cppreference.com/w/cpp/concept/Container)
4730  requirements:
4731  - The complexity is constant.
4732 
4733  @liveexample{The following code shows an example for `end()`.,end}
4734 
4735  @sa @ref cend() -- returns a const iterator to the end
4736  @sa @ref begin() -- returns an iterator to the beginning
4737  @sa @ref cbegin() -- returns a const iterator to the beginning
4738 
4739  @since version 1.0.0
4740  */
4741  iterator end() noexcept
4742  {
4743  iterator result(this);
4744  result.set_end();
4745  return result;
4746  }
4747 
4748  /*!
4749  @copydoc basic_json::cend()
4750  */
4751  const_iterator end() const noexcept
4752  {
4753  return cend();
4754  }
4755 
4756  /*!
4757  @brief returns a const iterator to one past the last element
4758 
4759  Returns a const iterator to one past the last element.
4760 
4761  @image html range-begin-end.svg "Illustration from cppreference.com"
4762 
4763  @return const iterator one past the last element
4764 
4765  @complexity Constant.
4766 
4767  @requirement This function helps `basic_json` satisfying the
4768  [Container](http://en.cppreference.com/w/cpp/concept/Container)
4769  requirements:
4770  - The complexity is constant.
4771  - Has the semantics of `const_cast<const basic_json&>(*this).end()`.
4772 
4773  @liveexample{The following code shows an example for `cend()`.,cend}
4774 
4775  @sa @ref end() -- returns an iterator to the end
4776  @sa @ref begin() -- returns an iterator to the beginning
4777  @sa @ref cbegin() -- returns a const iterator to the beginning
4778 
4779  @since version 1.0.0
4780  */
4781  const_iterator cend() const noexcept
4782  {
4783  const_iterator result(this);
4784  result.set_end();
4785  return result;
4786  }
4787 
4788  /*!
4789  @brief returns an iterator to the reverse-beginning
4790 
4791  Returns an iterator to the reverse-beginning; that is, the last element.
4792 
4793  @image html range-rbegin-rend.svg "Illustration from cppreference.com"
4794 
4795  @complexity Constant.
4796 
4797  @requirement This function helps `basic_json` satisfying the
4798  [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
4799  requirements:
4800  - The complexity is constant.
4801  - Has the semantics of `reverse_iterator(end())`.
4802 
4803  @liveexample{The following code shows an example for `rbegin()`.,rbegin}
4804 
4805  @sa @ref crbegin() -- returns a const reverse iterator to the beginning
4806  @sa @ref rend() -- returns a reverse iterator to the end
4807  @sa @ref crend() -- returns a const reverse iterator to the end
4808 
4809  @since version 1.0.0
4810  */
4812  {
4813  return reverse_iterator(end());
4814  }
4815 
4816  /*!
4817  @copydoc basic_json::crbegin()
4818  */
4820  {
4821  return crbegin();
4822  }
4823 
4824  /*!
4825  @brief returns an iterator to the reverse-end
4826 
4827  Returns an iterator to the reverse-end; that is, one before the first
4828  element.
4829 
4830  @image html range-rbegin-rend.svg "Illustration from cppreference.com"
4831 
4832  @complexity Constant.
4833 
4834  @requirement This function helps `basic_json` satisfying the
4835  [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
4836  requirements:
4837  - The complexity is constant.
4838  - Has the semantics of `reverse_iterator(begin())`.
4839 
4840  @liveexample{The following code shows an example for `rend()`.,rend}
4841 
4842  @sa @ref crend() -- returns a const reverse iterator to the end
4843  @sa @ref rbegin() -- returns a reverse iterator to the beginning
4844  @sa @ref crbegin() -- returns a const reverse iterator to the beginning
4845 
4846  @since version 1.0.0
4847  */
4849  {
4850  return reverse_iterator(begin());
4851  }
4852 
4853  /*!
4854  @copydoc basic_json::crend()
4855  */
4856  const_reverse_iterator rend() const noexcept
4857  {
4858  return crend();
4859  }
4860 
4861  /*!
4862  @brief returns a const reverse iterator to the last element
4863 
4864  Returns a const iterator to the reverse-beginning; that is, the last
4865  element.
4866 
4867  @image html range-rbegin-rend.svg "Illustration from cppreference.com"
4868 
4869  @complexity Constant.
4870 
4871  @requirement This function helps `basic_json` satisfying the
4872  [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
4873  requirements:
4874  - The complexity is constant.
4875  - Has the semantics of `const_cast<const basic_json&>(*this).rbegin()`.
4876 
4877  @liveexample{The following code shows an example for `crbegin()`.,crbegin}
4878 
4879  @sa @ref rbegin() -- returns a reverse iterator to the beginning
4880  @sa @ref rend() -- returns a reverse iterator to the end
4881  @sa @ref crend() -- returns a const reverse iterator to the end
4882 
4883  @since version 1.0.0
4884  */
4886  {
4887  return const_reverse_iterator(cend());
4888  }
4889 
4890  /*!
4891  @brief returns a const reverse iterator to one before the first
4892 
4893  Returns a const reverse iterator to the reverse-end; that is, one before
4894  the first element.
4895 
4896  @image html range-rbegin-rend.svg "Illustration from cppreference.com"
4897 
4898  @complexity Constant.
4899 
4900  @requirement This function helps `basic_json` satisfying the
4901  [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
4902  requirements:
4903  - The complexity is constant.
4904  - Has the semantics of `const_cast<const basic_json&>(*this).rend()`.
4905 
4906  @liveexample{The following code shows an example for `crend()`.,crend}
4907 
4908  @sa @ref rend() -- returns a reverse iterator to the end
4909  @sa @ref rbegin() -- returns a reverse iterator to the beginning
4910  @sa @ref crbegin() -- returns a const reverse iterator to the beginning
4911 
4912  @since version 1.0.0
4913  */
4915  {
4916  return const_reverse_iterator(cbegin());
4917  }
4918 
4919  private:
4920  // forward declaration
4921  template<typename IteratorType> class iteration_proxy;
4922 
4923  public:
4924  /*!
4925  @brief wrapper to access iterator member functions in range-based for
4926 
4927  This function allows to access @ref iterator::key() and @ref
4928  iterator::value() during range-based for loops. In these loops, a
4929  reference to the JSON values is returned, so there is no access to the
4930  underlying iterator.
4931 
4932  @note The name of this function is not yet final and may change in the
4933  future.
4934  */
4936  {
4937  return iteration_proxy<iterator>(cont);
4938  }
4939 
4940  /*!
4941  @copydoc iterator_wrapper(reference)
4942  */
4944  {
4945  return iteration_proxy<const_iterator>(cont);
4946  }
4947 
4948  /// @}
4949 
4950 
4951  //////////////
4952  // capacity //
4953  //////////////
4954 
4955  /// @name capacity
4956  /// @{
4957 
4958  /*!
4959  @brief checks whether the container is empty
4960 
4961  Checks if a JSON value has no elements.
4962 
4963  @return The return value depends on the different types and is
4964  defined as follows:
4965  Value type | return value
4966  ----------- | -------------
4967  null | `true`
4968  boolean | `false`
4969  string | `false`
4970  number | `false`
4971  object | result of function `object_t::empty()`
4972  array | result of function `array_t::empty()`
4973 
4974  @note This function does not return whether a string stored as JSON value
4975  is empty - it returns whether the JSON container itself is empty which is
4976  false in the case of a string.
4977 
4978  @complexity Constant, as long as @ref array_t and @ref object_t satisfy
4979  the Container concept; that is, their `empty()` functions have constant
4980  complexity.
4981 
4982  @requirement This function helps `basic_json` satisfying the
4983  [Container](http://en.cppreference.com/w/cpp/concept/Container)
4984  requirements:
4985  - The complexity is constant.
4986  - Has the semantics of `begin() == end()`.
4987 
4988  @liveexample{The following code uses `empty()` to check if a JSON
4989  object contains any elements.,empty}
4990 
4991  @sa @ref size() -- returns the number of elements
4992 
4993  @since version 1.0.0
4994  */
4995  bool empty() const noexcept
4996  {
4997  switch (m_type)
4998  {
4999  case value_t::null:
5000  {
5001  // null values are empty
5002  return true;
5003  }
5004 
5005  case value_t::array:
5006  {
5007  // delegate call to array_t::empty()
5008  return m_value.array->empty();
5009  }
5010 
5011  case value_t::object:
5012  {
5013  // delegate call to object_t::empty()
5014  return m_value.object->empty();
5015  }
5016 
5017  default:
5018  {
5019  // all other types are nonempty
5020  return false;
5021  }
5022  }
5023  }
5024 
5025  /*!
5026  @brief returns the number of elements
5027 
5028  Returns the number of elements in a JSON value.
5029 
5030  @return The return value depends on the different types and is
5031  defined as follows:
5032  Value type | return value
5033  ----------- | -------------
5034  null | `0`
5035  boolean | `1`
5036  string | `1`
5037  number | `1`
5038  object | result of function object_t::size()
5039  array | result of function array_t::size()
5040 
5041  @note This function does not return the length of a string stored as JSON
5042  value - it returns the number of elements in the JSON value which is 1 in
5043  the case of a string.
5044 
5045  @complexity Constant, as long as @ref array_t and @ref object_t satisfy
5046  the Container concept; that is, their size() functions have constant
5047  complexity.
5048 
5049  @requirement This function helps `basic_json` satisfying the
5050  [Container](http://en.cppreference.com/w/cpp/concept/Container)
5051  requirements:
5052  - The complexity is constant.
5053  - Has the semantics of `std::distance(begin(), end())`.
5054 
5055  @liveexample{The following code calls `size()` on the different value
5056  types.,size}
5057 
5058  @sa @ref empty() -- checks whether the container is empty
5059  @sa @ref max_size() -- returns the maximal number of elements
5060 
5061  @since version 1.0.0
5062  */
5063  size_type size() const noexcept
5064  {
5065  switch (m_type)
5066  {
5067  case value_t::null:
5068  {
5069  // null values are empty
5070  return 0;
5071  }
5072 
5073  case value_t::array:
5074  {
5075  // delegate call to array_t::size()
5076  return m_value.array->size();
5077  }
5078 
5079  case value_t::object:
5080  {
5081  // delegate call to object_t::size()
5082  return m_value.object->size();
5083  }
5084 
5085  default:
5086  {
5087  // all other types have size 1
5088  return 1;
5089  }
5090  }
5091  }
5092 
5093  /*!
5094  @brief returns the maximum possible number of elements
5095 
5096  Returns the maximum number of elements a JSON value is able to hold due to
5097  system or library implementation limitations, i.e. `std::distance(begin(),
5098  end())` for the JSON value.
5099 
5100  @return The return value depends on the different types and is
5101  defined as follows:
5102  Value type | return value
5103  ----------- | -------------
5104  null | `0` (same as `size()`)
5105  boolean | `1` (same as `size()`)
5106  string | `1` (same as `size()`)
5107  number | `1` (same as `size()`)
5108  object | result of function `object_t::max_size()`
5109  array | result of function `array_t::max_size()`
5110 
5111  @complexity Constant, as long as @ref array_t and @ref object_t satisfy
5112  the Container concept; that is, their `max_size()` functions have constant
5113  complexity.
5114 
5115  @requirement This function helps `basic_json` satisfying the
5116  [Container](http://en.cppreference.com/w/cpp/concept/Container)
5117  requirements:
5118  - The complexity is constant.
5119  - Has the semantics of returning `b.size()` where `b` is the largest
5120  possible JSON value.
5121 
5122  @liveexample{The following code calls `max_size()` on the different value
5123  types. Note the output is implementation specific.,max_size}
5124 
5125  @sa @ref size() -- returns the number of elements
5126 
5127  @since version 1.0.0
5128  */
5129  size_type max_size() const noexcept
5130  {
5131  switch (m_type)
5132  {
5133  case value_t::array:
5134  {
5135  // delegate call to array_t::max_size()
5136  return m_value.array->max_size();
5137  }
5138 
5139  case value_t::object:
5140  {
5141  // delegate call to object_t::max_size()
5142  return m_value.object->max_size();
5143  }
5144 
5145  default:
5146  {
5147  // all other types have max_size() == size()
5148  return size();
5149  }
5150  }
5151  }
5152 
5153  /// @}
5154 
5155 
5156  ///////////////
5157  // modifiers //
5158  ///////////////
5159 
5160  /// @name modifiers
5161  /// @{
5162 
5163  /*!
5164  @brief clears the contents
5165 
5166  Clears the content of a JSON value and resets it to the default value as
5167  if @ref basic_json(value_t) would have been called:
5168 
5169  Value type | initial value
5170  ----------- | -------------
5171  null | `null`
5172  boolean | `false`
5173  string | `""`
5174  number | `0`
5175  object | `{}`
5176  array | `[]`
5177 
5178  @complexity Linear in the size of the JSON value.
5179 
5180  @liveexample{The example below shows the effect of `clear()` to different
5181  JSON types.,clear}
5182 
5183  @since version 1.0.0
5184  */
5185  void clear() noexcept
5186  {
5187  switch (m_type)
5188  {
5190  {
5191  m_value.number_integer = 0;
5192  break;
5193  }
5194 
5196  {
5197  m_value.number_unsigned = 0;
5198  break;
5199  }
5200 
5201  case value_t::number_float:
5202  {
5203  m_value.number_float = 0.0;
5204  break;
5205  }
5206 
5207  case value_t::boolean:
5208  {
5209  m_value.boolean = false;
5210  break;
5211  }
5212 
5213  case value_t::string:
5214  {
5215  m_value.string->clear();
5216  break;
5217  }
5218 
5219  case value_t::array:
5220  {
5221  m_value.array->clear();
5222  break;
5223  }
5224 
5225  case value_t::object:
5226  {
5227  m_value.object->clear();
5228  break;
5229  }
5230 
5231  default:
5232  {
5233  break;
5234  }
5235  }
5236  }
5237 
5238  /*!
5239  @brief add an object to an array
5240 
5241  Appends the given element @a val to the end of the JSON value. If the
5242  function is called on a JSON null value, an empty array is created before
5243  appending @a val.
5244 
5245  @param[in] val the value to add to the JSON array
5246 
5247  @throw std::domain_error when called on a type other than JSON array or
5248  null; example: `"cannot use push_back() with number"`
5249 
5250  @complexity Amortized constant.
5251 
5252  @liveexample{The example shows how `push_back()` and `+=` can be used to
5253  add elements to a JSON array. Note how the `null` value was silently
5254  converted to a JSON array.,push_back}
5255 
5256  @since version 1.0.0
5257  */
5258  void push_back(basic_json&& val)
5259  {
5260  // push_back only works for null objects or arrays
5261  if (not(is_null() or is_array()))
5262  {
5263  JSON_THROW(std::domain_error("cannot use push_back() with " + type_name()));
5264  }
5265 
5266  // transform null object into an array
5267  if (is_null())
5268  {
5269  m_type = value_t::array;
5270  m_value = value_t::array;
5271  assert_invariant();
5272  }
5273 
5274  // add element to array (move semantics)
5275  m_value.array->push_back(std::move(val));
5276  // invalidate object
5277  val.m_type = value_t::null;
5278  }
5279 
5280  /*!
5281  @brief add an object to an array
5282  @copydoc push_back(basic_json&&)
5283  */
5285  {
5286  push_back(std::move(val));
5287  return *this;
5288  }
5289 
5290  /*!
5291  @brief add an object to an array
5292  @copydoc push_back(basic_json&&)
5293  */
5294  void push_back(const basic_json& val)
5295  {
5296  // push_back only works for null objects or arrays
5297  if (not(is_null() or is_array()))
5298  {
5299  JSON_THROW(std::domain_error("cannot use push_back() with " + type_name()));
5300  }
5301 
5302  // transform null object into an array
5303  if (is_null())
5304  {
5305  m_type = value_t::array;
5306  m_value = value_t::array;
5307  assert_invariant();
5308  }
5309 
5310  // add element to array
5311  m_value.array->push_back(val);
5312  }
5313 
5314  /*!
5315  @brief add an object to an array
5316  @copydoc push_back(basic_json&&)
5317  */
5319  {
5320  push_back(val);
5321  return *this;
5322  }
5323 
5324  /*!
5325  @brief add an object to an object
5326 
5327  Inserts the given element @a val to the JSON object. If the function is
5328  called on a JSON null value, an empty object is created before inserting
5329  @a val.
5330 
5331  @param[in] val the value to add to the JSON object
5332 
5333  @throw std::domain_error when called on a type other than JSON object or
5334  null; example: `"cannot use push_back() with number"`
5335 
5336  @complexity Logarithmic in the size of the container, O(log(`size()`)).
5337 
5338  @liveexample{The example shows how `push_back()` and `+=` can be used to
5339  add elements to a JSON object. Note how the `null` value was silently
5340  converted to a JSON object.,push_back__object_t__value}
5341 
5342  @since version 1.0.0
5343  */
5344  void push_back(const typename object_t::value_type& val)
5345  {
5346  // push_back only works for null objects or objects
5347  if (not(is_null() or is_object()))
5348  {
5349  JSON_THROW(std::domain_error("cannot use push_back() with " + type_name()));
5350  }
5351 
5352  // transform null object into an object
5353  if (is_null())
5354  {
5355  m_type = value_t::object;
5356  m_value = value_t::object;
5357  assert_invariant();
5358  }
5359 
5360  // add element to array
5361  m_value.object->insert(val);
5362  }
5363 
5364  /*!
5365  @brief add an object to an object
5366  @copydoc push_back(const typename object_t::value_type&)
5367  */
5368  reference operator+=(const typename object_t::value_type& val)
5369  {
5370  push_back(val);
5371  return *this;
5372  }
5373 
5374  /*!
5375  @brief add an object to an object
5376 
5377  This function allows to use `push_back` with an initializer list. In case
5378 
5379  1. the current value is an object,
5380  2. the initializer list @a init contains only two elements, and
5381  3. the first element of @a init is a string,
5382 
5383  @a init is converted into an object element and added using
5384  @ref push_back(const typename object_t::value_type&). Otherwise, @a init
5385  is converted to a JSON value and added using @ref push_back(basic_json&&).
5386 
5387  @param init an initializer list
5388 
5389  @complexity Linear in the size of the initializer list @a init.
5390 
5391  @note This function is required to resolve an ambiguous overload error,
5392  because pairs like `{"key", "value"}` can be both interpreted as
5393  `object_t::value_type` or `std::initializer_list<basic_json>`, see
5394  https://github.com/nlohmann/json/issues/235 for more information.
5395 
5396  @liveexample{The example shows how initializer lists are treated as
5397  objects when possible.,push_back__initializer_list}
5398  */
5399  void push_back(std::initializer_list<basic_json> init)
5400  {
5401  if (is_object() and init.size() == 2 and init.begin()->is_string())
5402  {
5403  const string_t key = *init.begin();
5404  push_back(typename object_t::value_type(key, *(init.begin() + 1)));
5405  }
5406  else
5407  {
5408  push_back(basic_json(init));
5409  }
5410  }
5411 
5412  /*!
5413  @brief add an object to an object
5414  @copydoc push_back(std::initializer_list<basic_json>)
5415  */
5416  reference operator+=(std::initializer_list<basic_json> init)
5417  {
5418  push_back(init);
5419  return *this;
5420  }
5421 
5422  /*!
5423  @brief add an object to an array
5424 
5425  Creates a JSON value from the passed parameters @a args to the end of the
5426  JSON value. If the function is called on a JSON null value, an empty array
5427  is created before appending the value created from @a args.
5428 
5429  @param[in] args arguments to forward to a constructor of @ref basic_json
5430  @tparam Args compatible types to create a @ref basic_json object
5431 
5432  @throw std::domain_error when called on a type other than JSON array or
5433  null; example: `"cannot use emplace_back() with number"`
5434 
5435  @complexity Amortized constant.
5436 
5437  @liveexample{The example shows how `push_back()` can be used to add
5438  elements to a JSON array. Note how the `null` value was silently converted
5439  to a JSON array.,emplace_back}
5440 
5441  @since version 2.0.8
5442  */
5443  template<class... Args>
5444  void emplace_back(Args&& ... args)
5445  {
5446  // emplace_back only works for null objects or arrays
5447  if (not(is_null() or is_array()))
5448  {
5449  JSON_THROW(std::domain_error("cannot use emplace_back() with " + type_name()));
5450  }
5451 
5452  // transform null object into an array
5453  if (is_null())
5454  {
5455  m_type = value_t::array;
5456  m_value = value_t::array;
5457  assert_invariant();
5458  }
5459 
5460  // add element to array (perfect forwarding)
5461  m_value.array->emplace_back(std::forward<Args>(args)...);
5462  }
5463 
5464  /*!
5465  @brief add an object to an object if key does not exist
5466 
5467  Inserts a new element into a JSON object constructed in-place with the
5468  given @a args if there is no element with the key in the container. If the
5469  function is called on a JSON null value, an empty object is created before
5470  appending the value created from @a args.
5471 
5472  @param[in] args arguments to forward to a constructor of @ref basic_json
5473  @tparam Args compatible types to create a @ref basic_json object
5474 
5475  @return a pair consisting of an iterator to the inserted element, or the
5476  already-existing element if no insertion happened, and a bool
5477  denoting whether the insertion took place.
5478 
5479  @throw std::domain_error when called on a type other than JSON object or
5480  null; example: `"cannot use emplace() with number"`
5481 
5482  @complexity Logarithmic in the size of the container, O(log(`size()`)).
5483 
5484  @liveexample{The example shows how `emplace()` can be used to add elements
5485  to a JSON object. Note how the `null` value was silently converted to a
5486  JSON object. Further note how no value is added if there was already one
5487  value stored with the same key.,emplace}
5488 
5489  @since version 2.0.8
5490  */
5491  template<class... Args>
5492  std::pair<iterator, bool> emplace(Args&& ... args)
5493  {
5494  // emplace only works for null objects or arrays
5495  if (not(is_null() or is_object()))
5496  {
5497  JSON_THROW(std::domain_error("cannot use emplace() with " + type_name()));
5498  }
5499 
5500  // transform null object into an object
5501  if (is_null())
5502  {
5503  m_type = value_t::object;
5504  m_value = value_t::object;
5505  assert_invariant();
5506  }
5507 
5508  // add element to array (perfect forwarding)
5509  auto res = m_value.object->emplace(std::forward<Args>(args)...);
5510  // create result iterator and set iterator to the result of emplace
5511  auto it = begin();
5512  it.m_it.object_iterator = res.first;
5513 
5514  // return pair of iterator and boolean
5515  return {it, res.second};
5516  }
5517 
5518  /*!
5519  @brief inserts element
5520 
5521  Inserts element @a val before iterator @a pos.
5522 
5523  @param[in] pos iterator before which the content will be inserted; may be
5524  the end() iterator
5525  @param[in] val element to insert
5526  @return iterator pointing to the inserted @a val.
5527 
5528  @throw std::domain_error if called on JSON values other than arrays;
5529  example: `"cannot use insert() with string"`
5530  @throw std::domain_error if @a pos is not an iterator of *this; example:
5531  `"iterator does not fit current value"`
5532 
5533  @complexity Constant plus linear in the distance between @a pos and end of
5534  the container.
5535 
5536  @liveexample{The example shows how `insert()` is used.,insert}
5537 
5538  @since version 1.0.0
5539  */
5541  {
5542  // insert only works for arrays
5543  if (is_array())
5544  {
5545  // check if iterator pos fits to this JSON value
5546  if (pos.m_object != this)
5547  {
5548  JSON_THROW(std::domain_error("iterator does not fit current value"));
5549  }
5550 
5551  // insert to array and return iterator
5552  iterator result(this);
5553  result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, val);
5554  return result;
5555  }
5556 
5557  JSON_THROW(std::domain_error("cannot use insert() with " + type_name()));
5558  }
5559 
5560  /*!
5561  @brief inserts element
5562  @copydoc insert(const_iterator, const basic_json&)
5563  */
5565  {
5566  return insert(pos, val);
5567  }
5568 
5569  /*!
5570  @brief inserts elements
5571 
5572  Inserts @a cnt copies of @a val before iterator @a pos.
5573 
5574  @param[in] pos iterator before which the content will be inserted; may be
5575  the end() iterator
5576  @param[in] cnt number of copies of @a val to insert
5577  @param[in] val element to insert
5578  @return iterator pointing to the first element inserted, or @a pos if
5579  `cnt==0`
5580 
5581  @throw std::domain_error if called on JSON values other than arrays;
5582  example: `"cannot use insert() with string"`
5583  @throw std::domain_error if @a pos is not an iterator of *this; example:
5584  `"iterator does not fit current value"`
5585 
5586  @complexity Linear in @a cnt plus linear in the distance between @a pos
5587  and end of the container.
5588 
5589  @liveexample{The example shows how `insert()` is used.,insert__count}
5590 
5591  @since version 1.0.0
5592  */
5594  {
5595  // insert only works for arrays
5596  if (is_array())
5597  {
5598  // check if iterator pos fits to this JSON value
5599  if (pos.m_object != this)
5600  {
5601  JSON_THROW(std::domain_error("iterator does not fit current value"));
5602  }
5603 
5604  // insert to array and return iterator
5605  iterator result(this);
5606  result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, cnt, val);
5607  return result;
5608  }
5609 
5610  JSON_THROW(std::domain_error("cannot use insert() with " + type_name()));
5611  }
5612 
5613  /*!
5614  @brief inserts elements
5615 
5616  Inserts elements from range `[first, last)` before iterator @a pos.
5617 
5618  @param[in] pos iterator before which the content will be inserted; may be
5619  the end() iterator
5620  @param[in] first begin of the range of elements to insert
5621  @param[in] last end of the range of elements to insert
5622 
5623  @throw std::domain_error if called on JSON values other than arrays;
5624  example: `"cannot use insert() with string"`
5625  @throw std::domain_error if @a pos is not an iterator of *this; example:
5626  `"iterator does not fit current value"`
5627  @throw std::domain_error if @a first and @a last do not belong to the same
5628  JSON value; example: `"iterators do not fit"`
5629  @throw std::domain_error if @a first or @a last are iterators into
5630  container for which insert is called; example: `"passed iterators may not
5631  belong to container"`
5632 
5633  @return iterator pointing to the first element inserted, or @a pos if
5634  `first==last`
5635 
5636  @complexity Linear in `std::distance(first, last)` plus linear in the
5637  distance between @a pos and end of the container.
5638 
5639  @liveexample{The example shows how `insert()` is used.,insert__range}
5640 
5641  @since version 1.0.0
5642  */
5644  {
5645  // insert only works for arrays
5646  if (not is_array())
5647  {
5648  JSON_THROW(std::domain_error("cannot use insert() with " + type_name()));
5649  }
5650 
5651  // check if iterator pos fits to this JSON value
5652  if (pos.m_object != this)
5653  {
5654  JSON_THROW(std::domain_error("iterator does not fit current value"));
5655  }
5656 
5657  // check if range iterators belong to the same JSON object
5658  if (first.m_object != last.m_object)
5659  {
5660  JSON_THROW(std::domain_error("iterators do not fit"));
5661  }
5662 
5663  if (first.m_object == this or last.m_object == this)
5664  {
5665  JSON_THROW(std::domain_error("passed iterators may not belong to container"));
5666  }
5667 
5668  // insert to array and return iterator
5669  iterator result(this);
5670  result.m_it.array_iterator = m_value.array->insert(
5671  pos.m_it.array_iterator,
5672  first.m_it.array_iterator,
5673  last.m_it.array_iterator);
5674  return result;
5675  }
5676 
5677  /*!
5678  @brief inserts elements
5679 
5680  Inserts elements from initializer list @a ilist before iterator @a pos.
5681 
5682  @param[in] pos iterator before which the content will be inserted; may be
5683  the end() iterator
5684  @param[in] ilist initializer list to insert the values from
5685 
5686  @throw std::domain_error if called on JSON values other than arrays;
5687  example: `"cannot use insert() with string"`
5688  @throw std::domain_error if @a pos is not an iterator of *this; example:
5689  `"iterator does not fit current value"`
5690 
5691  @return iterator pointing to the first element inserted, or @a pos if
5692  `ilist` is empty
5693 
5694  @complexity Linear in `ilist.size()` plus linear in the distance between
5695  @a pos and end of the container.
5696 
5697  @liveexample{The example shows how `insert()` is used.,insert__ilist}
5698 
5699  @since version 1.0.0
5700  */
5701  iterator insert(const_iterator pos, std::initializer_list<basic_json> ilist)
5702  {
5703  // insert only works for arrays
5704  if (not is_array())
5705  {
5706  JSON_THROW(std::domain_error("cannot use insert() with " + type_name()));
5707  }
5708 
5709  // check if iterator pos fits to this JSON value
5710  if (pos.m_object != this)
5711  {
5712  JSON_THROW(std::domain_error("iterator does not fit current value"));
5713  }
5714 
5715  // insert to array and return iterator
5716  iterator result(this);
5717  result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, ilist);
5718  return result;
5719  }
5720 
5721  /*!
5722  @brief exchanges the values
5723 
5724  Exchanges the contents of the JSON value with those of @a other. Does not
5725  invoke any move, copy, or swap operations on individual elements. All
5726  iterators and references remain valid. The past-the-end iterator is
5727  invalidated.
5728 
5729  @param[in,out] other JSON value to exchange the contents with
5730 
5731  @complexity Constant.
5732 
5733  @liveexample{The example below shows how JSON values can be swapped with
5734  `swap()`.,swap__reference}
5735 
5736  @since version 1.0.0
5737  */
5738  void swap(reference other) noexcept (
5739  std::is_nothrow_move_constructible<value_t>::value and
5740  std::is_nothrow_move_assignable<value_t>::value and
5741  std::is_nothrow_move_constructible<json_value>::value and
5742  std::is_nothrow_move_assignable<json_value>::value
5743  )
5744  {
5745  std::swap(m_type, other.m_type);
5746  std::swap(m_value, other.m_value);
5747  assert_invariant();
5748  }
5749 
5750  /*!
5751  @brief exchanges the values
5752 
5753  Exchanges the contents of a JSON array with those of @a other. Does not
5754  invoke any move, copy, or swap operations on individual elements. All
5755  iterators and references remain valid. The past-the-end iterator is
5756  invalidated.
5757 
5758  @param[in,out] other array to exchange the contents with
5759 
5760  @throw std::domain_error when JSON value is not an array; example:
5761  `"cannot use swap() with string"`
5762 
5763  @complexity Constant.
5764 
5765  @liveexample{The example below shows how arrays can be swapped with
5766  `swap()`.,swap__array_t}
5767 
5768  @since version 1.0.0
5769  */
5770  void swap(array_t& other)
5771  {
5772  // swap only works for arrays
5773  if (is_array())
5774  {
5775  std::swap(*(m_value.array), other);
5776  }
5777  else
5778  {
5779  JSON_THROW(std::domain_error("cannot use swap() with " + type_name()));
5780  }
5781  }
5782 
5783  /*!
5784  @brief exchanges the values
5785 
5786  Exchanges the contents of a JSON object with those of @a other. Does not
5787  invoke any move, copy, or swap operations on individual elements. All
5788  iterators and references remain valid. The past-the-end iterator is
5789  invalidated.
5790 
5791  @param[in,out] other object to exchange the contents with
5792 
5793  @throw std::domain_error when JSON value is not an object; example:
5794  `"cannot use swap() with string"`
5795 
5796  @complexity Constant.
5797 
5798  @liveexample{The example below shows how objects can be swapped with
5799  `swap()`.,swap__object_t}
5800 
5801  @since version 1.0.0
5802  */
5803  void swap(object_t& other)
5804  {
5805  // swap only works for objects
5806  if (is_object())
5807  {
5808  std::swap(*(m_value.object), other);
5809  }
5810  else
5811  {
5812  JSON_THROW(std::domain_error("cannot use swap() with " + type_name()));
5813  }
5814  }
5815 
5816  /*!
5817  @brief exchanges the values
5818 
5819  Exchanges the contents of a JSON string with those of @a other. Does not
5820  invoke any move, copy, or swap operations on individual elements. All
5821  iterators and references remain valid. The past-the-end iterator is
5822  invalidated.
5823 
5824  @param[in,out] other string to exchange the contents with
5825 
5826  @throw std::domain_error when JSON value is not a string; example: `"cannot
5827  use swap() with boolean"`
5828 
5829  @complexity Constant.
5830 
5831  @liveexample{The example below shows how strings can be swapped with
5832  `swap()`.,swap__string_t}
5833 
5834  @since version 1.0.0
5835  */
5836  void swap(string_t& other)
5837  {
5838  // swap only works for strings
5839  if (is_string())
5840  {
5841  std::swap(*(m_value.string), other);
5842  }
5843  else
5844  {
5845  JSON_THROW(std::domain_error("cannot use swap() with " + type_name()));
5846  }
5847  }
5848 
5849  /// @}
5850 
5851  public:
5852  //////////////////////////////////////////
5853  // lexicographical comparison operators //
5854  //////////////////////////////////////////
5855 
5856  /// @name lexicographical comparison operators
5857  /// @{
5858 
5859  /*!
5860  @brief comparison: equal
5861 
5862  Compares two JSON values for equality according to the following rules:
5863  - Two JSON values are equal if (1) they are from the same type and (2)
5864  their stored values are the same.
5865  - Integer and floating-point numbers are automatically converted before
5866  comparison. Floating-point numbers are compared indirectly: two
5867  floating-point numbers `f1` and `f2` are considered equal if neither
5868  `f1 > f2` nor `f2 > f1` holds.
5869  - Two JSON null values are equal.
5870 
5871  @param[in] lhs first JSON value to consider
5872  @param[in] rhs second JSON value to consider
5873  @return whether the values @a lhs and @a rhs are equal
5874 
5875  @complexity Linear.
5876 
5877  @liveexample{The example demonstrates comparing several JSON
5878  types.,operator__equal}
5879 
5880  @since version 1.0.0
5881  */
5882  friend bool operator==(const_reference lhs, const_reference rhs) noexcept
5883  {
5884  const auto lhs_type = lhs.type();
5885  const auto rhs_type = rhs.type();
5886 
5887  if (lhs_type == rhs_type)
5888  {
5889  switch (lhs_type)
5890  {
5891  case value_t::array:
5892  {
5893  return *lhs.m_value.array == *rhs.m_value.array;
5894  }
5895  case value_t::object:
5896  {
5897  return *lhs.m_value.object == *rhs.m_value.object;
5898  }
5899  case value_t::null:
5900  {
5901  return true;
5902  }
5903  case value_t::string:
5904  {
5905  return *lhs.m_value.string == *rhs.m_value.string;
5906  }
5907  case value_t::boolean:
5908  {
5909  return lhs.m_value.boolean == rhs.m_value.boolean;
5910  }
5912  {
5913  return lhs.m_value.number_integer == rhs.m_value.number_integer;
5914  }
5916  {
5917  return lhs.m_value.number_unsigned == rhs.m_value.number_unsigned;
5918  }
5919  case value_t::number_float:
5920  {
5921  return lhs.m_value.number_float == rhs.m_value.number_float;
5922  }
5923  default:
5924  {
5925  return false;
5926  }
5927  }
5928  }
5929  else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_float)
5930  {
5931  return static_cast<number_float_t>(lhs.m_value.number_integer) == rhs.m_value.number_float;
5932  }
5933  else if (lhs_type == value_t::number_float and rhs_type == value_t::number_integer)
5934  {
5935  return lhs.m_value.number_float == static_cast<number_float_t>(rhs.m_value.number_integer);
5936  }
5937  else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_float)
5938  {
5939  return static_cast<number_float_t>(lhs.m_value.number_unsigned) == rhs.m_value.number_float;
5940  }
5941  else if (lhs_type == value_t::number_float and rhs_type == value_t::number_unsigned)
5942  {
5943  return lhs.m_value.number_float == static_cast<number_float_t>(rhs.m_value.number_unsigned);
5944  }
5945  else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_integer)
5946  {
5947  return static_cast<number_integer_t>(lhs.m_value.number_unsigned) == rhs.m_value.number_integer;
5948  }
5949  else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_unsigned)
5950  {
5951  return lhs.m_value.number_integer == static_cast<number_integer_t>(rhs.m_value.number_unsigned);
5952  }
5953 
5954  return false;
5955  }
5956 
5957  /*!
5958  @brief comparison: equal
5959  @copydoc operator==(const_reference, const_reference)
5960  */
5961  template<typename ScalarType, typename std::enable_if<
5962  std::is_scalar<ScalarType>::value, int>::type = 0>
5963  friend bool operator==(const_reference lhs, const ScalarType rhs) noexcept
5964  {
5965  return (lhs == basic_json(rhs));
5966  }
5967 
5968  /*!
5969  @brief comparison: equal
5970  @copydoc operator==(const_reference, const_reference)
5971  */
5972  template<typename ScalarType, typename std::enable_if<
5973  std::is_scalar<ScalarType>::value, int>::type = 0>
5974  friend bool operator==(const ScalarType lhs, const_reference rhs) noexcept
5975  {
5976  return (basic_json(lhs) == rhs);
5977  }
5978 
5979  /*!
5980  @brief comparison: not equal
5981 
5982  Compares two JSON values for inequality by calculating `not (lhs == rhs)`.
5983 
5984  @param[in] lhs first JSON value to consider
5985  @param[in] rhs second JSON value to consider
5986  @return whether the values @a lhs and @a rhs are not equal
5987 
5988  @complexity Linear.
5989 
5990  @liveexample{The example demonstrates comparing several JSON
5991  types.,operator__notequal}
5992 
5993  @since version 1.0.0
5994  */
5995  friend bool operator!=(const_reference lhs, const_reference rhs) noexcept
5996  {
5997  return not (lhs == rhs);
5998  }
5999 
6000  /*!
6001  @brief comparison: not equal
6002  @copydoc operator!=(const_reference, const_reference)
6003  */
6004  template<typename ScalarType, typename std::enable_if<
6005  std::is_scalar<ScalarType>::value, int>::type = 0>
6006  friend bool operator!=(const_reference lhs, const ScalarType rhs) noexcept
6007  {
6008  return (lhs != basic_json(rhs));
6009  }
6010 
6011  /*!
6012  @brief comparison: not equal
6013  @copydoc operator!=(const_reference, const_reference)
6014  */
6015  template<typename ScalarType, typename std::enable_if<
6016  std::is_scalar<ScalarType>::value, int>::type = 0>
6017  friend bool operator!=(const ScalarType lhs, const_reference rhs) noexcept
6018  {
6019  return (basic_json(lhs) != rhs);
6020  }
6021 
6022  /*!
6023  @brief comparison: less than
6024 
6025  Compares whether one JSON value @a lhs is less than another JSON value @a
6026  rhs according to the following rules:
6027  - If @a lhs and @a rhs have the same type, the values are compared using
6028  the default `<` operator.
6029  - Integer and floating-point numbers are automatically converted before
6030  comparison
6031  - In case @a lhs and @a rhs have different types, the values are ignored
6032  and the order of the types is considered, see
6033  @ref operator<(const value_t, const value_t).
6034 
6035  @param[in] lhs first JSON value to consider
6036  @param[in] rhs second JSON value to consider
6037  @return whether @a lhs is less than @a rhs
6038 
6039  @complexity Linear.
6040 
6041  @liveexample{The example demonstrates comparing several JSON
6042  types.,operator__less}
6043 
6044  @since version 1.0.0
6045  */
6046  friend bool operator<(const_reference lhs, const_reference rhs) noexcept
6047  {
6048  const auto lhs_type = lhs.type();
6049  const auto rhs_type = rhs.type();
6050 
6051  if (lhs_type == rhs_type)
6052  {
6053  switch (lhs_type)
6054  {
6055  case value_t::array:
6056  {
6057  return *lhs.m_value.array < *rhs.m_value.array;
6058  }
6059  case value_t::object:
6060  {
6061  return *lhs.m_value.object < *rhs.m_value.object;
6062  }
6063  case value_t::null:
6064  {
6065  return false;
6066  }
6067  case value_t::string:
6068  {
6069  return *lhs.m_value.string < *rhs.m_value.string;
6070  }
6071  case value_t::boolean:
6072  {
6073  return lhs.m_value.boolean < rhs.m_value.boolean;
6074  }
6076  {
6077  return lhs.m_value.number_integer < rhs.m_value.number_integer;
6078  }
6080  {
6081  return lhs.m_value.number_unsigned < rhs.m_value.number_unsigned;
6082  }
6083  case value_t::number_float:
6084  {
6085  return lhs.m_value.number_float < rhs.m_value.number_float;
6086  }
6087  default:
6088  {
6089  return false;
6090  }
6091  }
6092  }
6093  else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_float)
6094  {
6095  return static_cast<number_float_t>(lhs.m_value.number_integer) < rhs.m_value.number_float;
6096  }
6097  else if (lhs_type == value_t::number_float and rhs_type == value_t::number_integer)
6098  {
6099  return lhs.m_value.number_float < static_cast<number_float_t>(rhs.m_value.number_integer);
6100  }
6101  else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_float)
6102  {
6103  return static_cast<number_float_t>(lhs.m_value.number_unsigned) < rhs.m_value.number_float;
6104  }
6105  else if (lhs_type == value_t::number_float and rhs_type == value_t::number_unsigned)
6106  {
6107  return lhs.m_value.number_float < static_cast<number_float_t>(rhs.m_value.number_unsigned);
6108  }
6109  else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_unsigned)
6110  {
6111  return lhs.m_value.number_integer < static_cast<number_integer_t>(rhs.m_value.number_unsigned);
6112  }
6113  else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_integer)
6114  {
6115  return static_cast<number_integer_t>(lhs.m_value.number_unsigned) < rhs.m_value.number_integer;
6116  }
6117 
6118  // We only reach this line if we cannot compare values. In that case,
6119  // we compare types. Note we have to call the operator explicitly,
6120  // because MSVC has problems otherwise.
6121  return operator<(lhs_type, rhs_type);
6122  }
6123 
6124  /*!
6125  @brief comparison: less than or equal
6126 
6127  Compares whether one JSON value @a lhs is less than or equal to another
6128  JSON value by calculating `not (rhs < lhs)`.
6129 
6130  @param[in] lhs first JSON value to consider
6131  @param[in] rhs second JSON value to consider
6132  @return whether @a lhs is less than or equal to @a rhs
6133 
6134  @complexity Linear.
6135 
6136  @liveexample{The example demonstrates comparing several JSON
6137  types.,operator__greater}
6138 
6139  @since version 1.0.0
6140  */
6141  friend bool operator<=(const_reference lhs, const_reference rhs) noexcept
6142  {
6143  return not (rhs < lhs);
6144  }
6145 
6146  /*!
6147  @brief comparison: greater than
6148 
6149  Compares whether one JSON value @a lhs is greater than another
6150  JSON value by calculating `not (lhs <= rhs)`.
6151 
6152  @param[in] lhs first JSON value to consider
6153  @param[in] rhs second JSON value to consider
6154  @return whether @a lhs is greater than to @a rhs
6155 
6156  @complexity Linear.
6157 
6158  @liveexample{The example demonstrates comparing several JSON
6159  types.,operator__lessequal}
6160 
6161  @since version 1.0.0
6162  */
6163  friend bool operator>(const_reference lhs, const_reference rhs) noexcept
6164  {
6165  return not (lhs <= rhs);
6166  }
6167 
6168  /*!
6169  @brief comparison: greater than or equal
6170 
6171  Compares whether one JSON value @a lhs is greater than or equal to another
6172  JSON value by calculating `not (lhs < rhs)`.
6173 
6174  @param[in] lhs first JSON value to consider
6175  @param[in] rhs second JSON value to consider
6176  @return whether @a lhs is greater than or equal to @a rhs
6177 
6178  @complexity Linear.
6179 
6180  @liveexample{The example demonstrates comparing several JSON
6181  types.,operator__greaterequal}
6182 
6183  @since version 1.0.0
6184  */
6185  friend bool operator>=(const_reference lhs, const_reference rhs) noexcept
6186  {
6187  return not (lhs < rhs);
6188  }
6189 
6190  /// @}
6191 
6192 
6193  ///////////////////
6194  // serialization //
6195  ///////////////////
6196 
6197  /// @name serialization
6198  /// @{
6199 
6200  /*!
6201  @brief serialize to stream
6202 
6203  Serialize the given JSON value @a j to the output stream @a o. The JSON
6204  value will be serialized using the @ref dump member function. The
6205  indentation of the output can be controlled with the member variable
6206  `width` of the output stream @a o. For instance, using the manipulator
6207  `std::setw(4)` on @a o sets the indentation level to `4` and the
6208  serialization result is the same as calling `dump(4)`.
6209 
6210  @param[in,out] o stream to serialize to
6211  @param[in] j JSON value to serialize
6212 
6213  @return the stream @a o
6214 
6215  @complexity Linear.
6216 
6217  @liveexample{The example below shows the serialization with different
6218  parameters to `width` to adjust the indentation level.,operator_serialize}
6219 
6220  @since version 1.0.0
6221  */
6222  friend std::ostream& operator<<(std::ostream& o, const basic_json& j)
6223  {
6224  // read width member and use it as indentation parameter if nonzero
6225  const bool pretty_print = (o.width() > 0);
6226  const auto indentation = (pretty_print ? o.width() : 0);
6227 
6228  // reset width to 0 for subsequent calls to this stream
6229  o.width(0);
6230 
6231  // do the actual serialization
6232  j.dump(o, pretty_print, static_cast<unsigned int>(indentation));
6233 
6234  return o;
6235  }
6236 
6237  /*!
6238  @brief serialize to stream
6239  @copydoc operator<<(std::ostream&, const basic_json&)
6240  */
6241  friend std::ostream& operator>>(const basic_json& j, std::ostream& o)
6242  {
6243  return o << j;
6244  }
6245 
6246  /// @}
6247 
6248 
6249  /////////////////////
6250  // deserialization //
6251  /////////////////////
6252 
6253  /// @name deserialization
6254  /// @{
6255 
6256  /*!
6257  @brief deserialize from an array
6258 
6259  This function reads from an array of 1-byte values.
6260 
6261  @pre Each element of the container has a size of 1 byte. Violating this
6262  precondition yields undefined behavior. **This precondition is enforced
6263  with a static assertion.**
6264 
6265  @param[in] array array to read from
6266  @param[in] cb a parser callback function of type @ref parser_callback_t
6267  which is used to control the deserialization by filtering unwanted values
6268  (optional)
6269 
6270  @return result of the deserialization
6271 
6272  @complexity Linear in the length of the input. The parser is a predictive
6273  LL(1) parser. The complexity can be higher if the parser callback function
6274  @a cb has a super-linear complexity.
6275 
6276  @note A UTF-8 byte order mark is silently ignored.
6277 
6278  @liveexample{The example below demonstrates the `parse()` function reading
6279  from an array.,parse__array__parser_callback_t}
6280 
6281  @since version 2.0.3
6282  */
6283  template<class T, std::size_t N>
6284  static basic_json parse(T (&array)[N],
6285  const parser_callback_t cb = nullptr)
6286  {
6287  // delegate the call to the iterator-range parse overload
6288  return parse(std::begin(array), std::end(array), cb);
6289  }
6290 
6291  /*!
6292  @brief deserialize from string literal
6293 
6294  @tparam CharT character/literal type with size of 1 byte
6295  @param[in] s string literal to read a serialized JSON value from
6296  @param[in] cb a parser callback function of type @ref parser_callback_t
6297  which is used to control the deserialization by filtering unwanted values
6298  (optional)
6299 
6300  @return result of the deserialization
6301 
6302  @complexity Linear in the length of the input. The parser is a predictive
6303  LL(1) parser. The complexity can be higher if the parser callback function
6304  @a cb has a super-linear complexity.
6305 
6306  @note A UTF-8 byte order mark is silently ignored.
6307  @note String containers like `std::string` or @ref string_t can be parsed
6308  with @ref parse(const ContiguousContainer&, const parser_callback_t)
6309 
6310  @liveexample{The example below demonstrates the `parse()` function with
6311  and without callback function.,parse__string__parser_callback_t}
6312 
6313  @sa @ref parse(std::istream&, const parser_callback_t) for a version that
6314  reads from an input stream
6315 
6316  @since version 1.0.0 (originally for @ref string_t)
6317  */
6318  template<typename CharT, typename std::enable_if<
6319  std::is_pointer<CharT>::value and
6321  sizeof(typename std::remove_pointer<CharT>::type) == 1, int>::type = 0>
6322  static basic_json parse(const CharT s,
6323  const parser_callback_t cb = nullptr)
6324  {
6325  return parser(reinterpret_cast<const char*>(s), cb).parse();
6326  }
6327 
6328  /*!
6329  @brief deserialize from stream
6330 
6331  @param[in,out] i stream to read a serialized JSON value from
6332  @param[in] cb a parser callback function of type @ref parser_callback_t
6333  which is used to control the deserialization by filtering unwanted values
6334  (optional)
6335 
6336  @return result of the deserialization
6337 
6338  @complexity Linear in the length of the input. The parser is a predictive
6339  LL(1) parser. The complexity can be higher if the parser callback function
6340  @a cb has a super-linear complexity.
6341 
6342  @note A UTF-8 byte order mark is silently ignored.
6343 
6344  @liveexample{The example below demonstrates the `parse()` function with
6345  and without callback function.,parse__istream__parser_callback_t}
6346 
6347  @sa @ref parse(const CharT, const parser_callback_t) for a version
6348  that reads from a string
6349 
6350  @since version 1.0.0
6351  */
6352  static basic_json parse(std::istream& i,
6353  const parser_callback_t cb = nullptr)
6354  {
6355  return parser(i, cb).parse();
6356  }
6357 
6358  /*!
6359  @copydoc parse(std::istream&, const parser_callback_t)
6360  */
6361  static basic_json parse(std::istream&& i,
6362  const parser_callback_t cb = nullptr)
6363  {
6364  return parser(i, cb).parse();
6365  }
6366 
6367  /*!
6368  @brief deserialize from an iterator range with contiguous storage
6369 
6370  This function reads from an iterator range of a container with contiguous
6371  storage of 1-byte values. Compatible container types include
6372  `std::vector`, `std::string`, `std::array`, `std::valarray`, and
6373  `std::initializer_list`. Furthermore, C-style arrays can be used with
6374  `std::begin()`/`std::end()`. User-defined containers can be used as long
6375  as they implement random-access iterators and a contiguous storage.
6376 
6377  @pre The iterator range is contiguous. Violating this precondition yields
6378  undefined behavior. **This precondition is enforced with an assertion.**
6379  @pre Each element in the range has a size of 1 byte. Violating this
6380  precondition yields undefined behavior. **This precondition is enforced
6381  with a static assertion.**
6382 
6383  @warning There is no way to enforce all preconditions at compile-time. If
6384  the function is called with noncompliant iterators and with
6385  assertions switched off, the behavior is undefined and will most
6386  likely yield segmentation violation.
6387 
6388  @tparam IteratorType iterator of container with contiguous storage
6389  @param[in] first begin of the range to parse (included)
6390  @param[in] last end of the range to parse (excluded)
6391  @param[in] cb a parser callback function of type @ref parser_callback_t
6392  which is used to control the deserialization by filtering unwanted values
6393  (optional)
6394 
6395  @return result of the deserialization
6396 
6397  @complexity Linear in the length of the input. The parser is a predictive
6398  LL(1) parser. The complexity can be higher if the parser callback function
6399  @a cb has a super-linear complexity.
6400 
6401  @note A UTF-8 byte order mark is silently ignored.
6402 
6403  @liveexample{The example below demonstrates the `parse()` function reading
6404  from an iterator range.,parse__iteratortype__parser_callback_t}
6405 
6406  @since version 2.0.3
6407  */
6408  template<class IteratorType, typename std::enable_if<
6409  std::is_base_of<
6410  std::random_access_iterator_tag,
6411  typename std::iterator_traits<IteratorType>::iterator_category>::value, int>::type = 0>
6412  static basic_json parse(IteratorType first, IteratorType last,
6413  const parser_callback_t cb = nullptr)
6414  {
6415  // assertion to check that the iterator range is indeed contiguous,
6416  // see http://stackoverflow.com/a/35008842/266378 for more discussion
6417  assert(std::accumulate(first, last, std::pair<bool, int>(true, 0),
6418  [&first](std::pair<bool, int> res, decltype(*first) val)
6419  {
6420  res.first &= (val == *(std::next(std::addressof(*first), res.second++)));
6421  return res;
6422  }).first);
6423 
6424  // assertion to check that each element is 1 byte long
6425  static_assert(sizeof(typename std::iterator_traits<IteratorType>::value_type) == 1,