json.hpp

  @since version 1.0.0
  */
  enum class parse_event_t : uint8_t
  {
    /// the parser read `{` and started to process a JSON object
    object_start,
    /// the parser read `}` and finished processing a JSON object
    object_end,
    /// the parser read `[` and started to process a JSON array
    array_start,
    /// the parser read `]` and finished processing a JSON array
    array_end,
    /// the parser read a key of a value in an object
    key,
    /// the parser finished reading a JSON value
    value
  };

  /*!
  @brief per-element parser callback type

  With a parser callback function, the result of parsing a JSON text can be
  influenced. When passed to @ref parse(std::istream&, const
  parser_callback_t) or @ref parse(const CharT, const parser_callback_t),
  it is called on certain events (passed as @ref parse_event_t via parameter
  @a event) with a set recursion depth @a depth and context JSON value
  @a parsed. The return value of the callback function is a boolean
  indicating whether the element that emitted the callback shall be kept or
  not.

  We distinguish six scenarios (determined by the event type) in which the
  callback function can be called. The following table describes the values
  of the parameters @a depth, @a event, and @a parsed.

  parameter @a event | description | parameter @a depth | parameter @a parsed
  ------------------ | ----------- | ------------------ | -------------------
  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
  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
  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
  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
  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
  parse_event_t::value | the parser finished reading a JSON value | depth of the
  value | the parsed JSON value

  @image html callback_events.png "Example when certain parse events are
  triggered"

  Discarding a value (i.e., returning `false`) has different effects
  depending on the context in which function was called:

  - Discarded values in structured types are skipped. That is, the parser
    will behave as if the discarded value was never read.
  - In case a value outside a structured type is skipped, it is replaced
    with `null`. This case happens if the top-level element is skipped.

  @param[in] depth  the depth of the recursion during parsing

  @param[in] event  an event of type parse_event_t indicating the context in
  the callback function has been called

  @param[in,out] parsed  the current intermediate parse result; note that
  writing to this value has no effect for parse_event_t::key events

  @return Whether the JSON value which called the function during parsing
  should be kept (`true`) or not (`false`). In the latter case, it is either
  skipped completely or replaced by an empty discarded object.

  @sa @ref parse(std::istream&, parser_callback_t) or
  @ref parse(const CharT, const parser_callback_t) for examples

  @since version 1.0.0
  */
  using parser_callback_t =
      std::function<bool(int depth, parse_event_t event, basic_json &parsed)>;

  //////////////////
  // constructors //
  //////////////////

  /// @name constructors and destructors
  /// Constructors of class @ref basic_json, copy/move constructor, copy
  /// assignment, static functions creating objects, and the destructor.
  /// @{

  /*!
  @brief create an empty value with a given type

  Create an empty JSON value with a given type. The value will be default
  initialized with an empty value which depends on the type:

  Value type  | initial value
  ----------- | -------------
  null        | `null`
  boolean     | `false`
  string      | `""`
  number      | `0`
  object      | `{}`
  array       | `[]`

  @param[in] value_type  the type of the value to create

  @complexity Constant.

  @throw std::bad_alloc if allocation for object, array, or string value
  fails

  @liveexample{The following code shows the constructor for different @ref
  value_t values,basic_json__value_t}

  @sa @ref basic_json(std::nullptr_t) -- create a `null` value
  @sa @ref basic_json(boolean_t value) -- create a boolean value
  @sa @ref basic_json(const string_t&) -- create a string value
  @sa @ref basic_json(const object_t&) -- create a object value
  @sa @ref basic_json(const array_t&) -- create a array value
  @sa @ref basic_json(const number_float_t) -- create a number
  (floating-point) value
  @sa @ref basic_json(const number_integer_t) -- create a number (integer)
  value
  @sa @ref basic_json(const number_unsigned_t) -- create a number (unsigned)
  value

  @since version 1.0.0
  */
  basic_json(const value_t value_type) : m_type(value_type), m_value(value_type)
  {
    assert_invariant();
  }

  /*!
  @brief create a null object

  Create a `null` JSON value. It either takes a null pointer as parameter
  (explicitly creating `null`) or no parameter (implicitly creating `null`).
  The passed null pointer itself is not read -- it is only used to choose
  the right constructor.

  @complexity Constant.

  @exceptionsafety No-throw guarantee: this constructor never throws
  exceptions.

  @liveexample{The following code shows the constructor with and without a
  null pointer parameter.,basic_json__nullptr_t}

  @since version 1.0.0
  */
  basic_json(std::nullptr_t = nullptr) noexcept : basic_json(value_t::null)
  {
    assert_invariant();
  }

  /*!
  @brief create an object (explicit)

  Create an object JSON value with a given content.

  @param[in] val  a value for the object

  @complexity Linear in the size of the passed @a val.

  @throw std::bad_alloc if allocation for object value fails

  @liveexample{The following code shows the constructor with an @ref
  object_t parameter.,basic_json__object_t}

  @sa @ref basic_json(const CompatibleObjectType&) -- create an object value
  from a compatible STL container

  @since version 1.0.0
  */
  basic_json(const object_t &val) : m_type(value_t::object), m_value(val)
  {
    assert_invariant();
  }

  /*!
  @brief create an object (implicit)

  Create an object JSON value with a given content. This constructor allows
  any type @a CompatibleObjectType that can be used to construct values of
  type @ref object_t.

  @tparam CompatibleObjectType An object type whose `key_type` and
  `value_type` is compatible to @ref object_t. Examples include `std::map`,
  `std::unordered_map`, `std::multimap`, and `std::unordered_multimap` with
  a `key_type` of `std::string`, and a `value_type` from which a @ref
  basic_json value can be constructed.

  @param[in] val  a value for the object

  @complexity Linear in the size of the passed @a val.

  @throw std::bad_alloc if allocation for object value fails

  @liveexample{The following code shows the constructor with several
  compatible object type parameters.,basic_json__CompatibleObjectType}

  @sa @ref basic_json(const object_t&) -- create an object value

  @since version 1.0.0
  */
  template <class CompatibleObjectType,
            typename std::enable_if<
                std::is_constructible<
                    typename object_t::key_type,
                    typename CompatibleObjectType::key_type>::value and
                    std::is_constructible<
                        basic_json,
                        typename CompatibleObjectType::mapped_type>::value,
                int>::type = 0>
  basic_json(const CompatibleObjectType &val) : m_type(value_t::object)
  {
    using std::begin;
    using std::end;
    m_value.object = create<object_t>(begin(val), end(val));
    assert_invariant();
  }

  /*!
  @brief create an array (explicit)

  Create an array JSON value with a given content.

  @param[in] val  a value for the array

  @complexity Linear in the size of the passed @a val.

  @throw std::bad_alloc if allocation for array value fails

  @liveexample{The following code shows the constructor with an @ref array_t
  parameter.,basic_json__array_t}

  @sa @ref basic_json(const CompatibleArrayType&) -- create an array value
  from a compatible STL containers

  @since version 1.0.0
  */
  basic_json(const array_t &val) : m_type(value_t::array), m_value(val)
  {
    assert_invariant();
  }

  /*!
  @brief create an array (implicit)

  Create an array JSON value with a given content. This constructor allows
  any type @a CompatibleArrayType that can be used to construct values of
  type @ref array_t.

  @tparam CompatibleArrayType An object type whose `value_type` is
  compatible to @ref array_t. Examples include `std::vector`, `std::deque`,
  `std::list`, `std::forward_list`, `std::array`, `std::set`,
  `std::unordered_set`, `std::multiset`, and `unordered_multiset` with a
  `value_type` from which a @ref basic_json value can be constructed.

  @param[in] val  a value for the array

  @complexity Linear in the size of the passed @a val.

  @throw std::bad_alloc if allocation for array value fails

  @liveexample{The following code shows the constructor with several
  compatible array type parameters.,basic_json__CompatibleArrayType}

  @sa @ref basic_json(const array_t&) -- create an array value

  @since version 1.0.0
  */
  template <
      class CompatibleArrayType,
      typename std::enable_if<
          not std::is_same<CompatibleArrayType,
                           typename basic_json_t::iterator>::value and
              not std::is_same<CompatibleArrayType,
                               typename basic_json_t::const_iterator>::value and
              not std::is_same<
                  CompatibleArrayType,
                  typename basic_json_t::reverse_iterator>::value and
              not std::is_same<
                  CompatibleArrayType,
                  typename basic_json_t::const_reverse_iterator>::value and
              not std::is_same<CompatibleArrayType,
                               typename array_t::iterator>::value and
              not std::is_same<CompatibleArrayType,
                               typename array_t::const_iterator>::value and
              std::is_constructible<
                  basic_json, typename CompatibleArrayType::value_type>::value,
          int>::type = 0>
  basic_json(const CompatibleArrayType &val) : m_type(value_t::array)
  {
    using std::begin;
    using std::end;
    m_value.array = create<array_t>(begin(val), end(val));
    assert_invariant();
  }

  /*!
  @brief create a string (explicit)

  Create an string JSON value with a given content.

  @param[in] val  a value for the string

  @complexity Linear in the size of the passed @a val.

  @throw std::bad_alloc if allocation for string value fails

  @liveexample{The following code shows the constructor with an @ref
  string_t parameter.,basic_json__string_t}

  @sa @ref basic_json(const typename string_t::value_type*) -- create a
  string value from a character pointer
  @sa @ref basic_json(const CompatibleStringType&) -- create a string value
  from a compatible string container

  @since version 1.0.0
  */
  basic_json(const string_t &val) : m_type(value_t::string), m_value(val)
  {
    assert_invariant();
  }

  /*!
  @brief create a string (explicit)

  Create a string JSON value with a given content.

  @param[in] val  a literal value for the string

  @complexity Linear in the size of the passed @a val.

  @throw std::bad_alloc if allocation for string value fails

  @liveexample{The following code shows the constructor with string literal
  parameter.,basic_json__string_t_value_type}

  @sa @ref basic_json(const string_t&) -- create a string value
  @sa @ref basic_json(const CompatibleStringType&) -- create a string value
  from a compatible string container

  @since version 1.0.0
  */
  basic_json(const typename string_t::value_type *val)
      : basic_json(string_t(val))
  {
    assert_invariant();
  }

  /*!
  @brief create a string (implicit)

  Create a string JSON value with a given content.

  @param[in] val  a value for the string

  @tparam CompatibleStringType an string type which is compatible to @ref
  string_t, for instance `std::string`.

  @complexity Linear in the size of the passed @a val.

  @throw std::bad_alloc if allocation for string value fails

  @liveexample{The following code shows the construction of a string value
  from a compatible type.,basic_json__CompatibleStringType}

  @sa @ref basic_json(const string_t&) -- create a string value
  @sa @ref basic_json(const typename string_t::value_type*) -- create a
  string value from a character pointer

  @since version 1.0.0
  */
  template <class CompatibleStringType,
            typename std::enable_if<
                std::is_constructible<string_t, CompatibleStringType>::value,
                int>::type = 0>
  basic_json(const CompatibleStringType &val) : basic_json(string_t(val))
  {
    assert_invariant();
  }

  /*!
  @brief create a boolean (explicit)

  Creates a JSON boolean type from a given value.

  @param[in] val  a boolean value to store

  @complexity Constant.

  @liveexample{The example below demonstrates boolean
  values.,basic_json__boolean_t}

  @since version 1.0.0
  */
  basic_json(boolean_t val) noexcept : m_type(value_t::boolean), m_value(val)
  {
    assert_invariant();
  }

  /*!
  @brief create an integer number (explicit)

  Create an integer number JSON value with a given content.

  @tparam T A helper type to remove this function via SFINAE in case @ref
  number_integer_t is the same as `int`. In this case, this constructor
  would have the same signature as @ref basic_json(const int value). Note
  the helper type @a T is not visible in this constructor's interface.

  @param[in] val  an integer to create a JSON number from

  @complexity Constant.

  @liveexample{The example below shows the construction of an integer
  number value.,basic_json__number_integer_t}

  @sa @ref basic_json(const int) -- create a number value (integer)
  @sa @ref basic_json(const CompatibleNumberIntegerType) -- create a number
  value (integer) from a compatible number type

  @since version 1.0.0
  */
  template <typename T, typename std::enable_if<
                            not(std::is_same<T, int>::value) and
                                std::is_same<T, number_integer_t>::value,
                            int>::type = 0>
  basic_json(const number_integer_t val) noexcept
      : m_type(value_t::number_integer),
        m_value(val)
  {
    assert_invariant();
  }

  /*!
  @brief create an integer number from an enum type (explicit)

  Create an integer number JSON value with a given content.

  @param[in] val  an integer to create a JSON number from

  @note This constructor allows to pass enums directly to a constructor. As
  C++ has no way of specifying the type of an anonymous enum explicitly, we
  can only rely on the fact that such values implicitly convert to int. As
  int may already be the same type of number_integer_t, we may need to
  switch off the constructor @ref basic_json(const number_integer_t).

  @complexity Constant.

  @liveexample{The example below shows the construction of an integer
  number value from an anonymous enum.,basic_json__const_int}

  @sa @ref basic_json(const number_integer_t) -- create a number value
  (integer)
  @sa @ref basic_json(const CompatibleNumberIntegerType) -- create a number
  value (integer) from a compatible number type

  @since version 1.0.0
  */
  basic_json(const int val) noexcept
      : m_type(value_t::number_integer),
        m_value(static_cast<number_integer_t>(val))
  {
    assert_invariant();
  }

  /*!
  @brief create an integer number (implicit)

  Create an integer number JSON value with a given content. This constructor
  allows any type @a CompatibleNumberIntegerType that can be used to
  construct values of type @ref number_integer_t.

  @tparam CompatibleNumberIntegerType An integer type which is compatible to
  @ref number_integer_t. Examples include the types `int`, `int32_t`,
  `long`, and `short`.

  @param[in] val  an integer to create a JSON number from

  @complexity Constant.

  @liveexample{The example below shows the construction of several integer
  number values from compatible
  types.,basic_json__CompatibleIntegerNumberType}

  @sa @ref basic_json(const number_integer_t) -- create a number value
  (integer)
  @sa @ref basic_json(const int) -- create a number value (integer)

  @since version 1.0.0
  */
  template <
      typename CompatibleNumberIntegerType,
      typename std::enable_if<
          std::is_constructible<number_integer_t,
                                CompatibleNumberIntegerType>::value and
              std::numeric_limits<CompatibleNumberIntegerType>::is_integer and
              std::numeric_limits<CompatibleNumberIntegerType>::is_signed,
          CompatibleNumberIntegerType>::type = 0>
  basic_json(const CompatibleNumberIntegerType val) noexcept
      : m_type(value_t::number_integer),
        m_value(static_cast<number_integer_t>(val))
  {
    assert_invariant();
  }

  /*!
  @brief create an unsigned integer number (explicit)

  Create an unsigned integer number JSON value with a given content.

  @tparam T  helper type to compare number_unsigned_t and unsigned int (not
  visible in) the interface.

  @param[in] val  an integer to create a JSON number from

  @complexity Constant.

  @sa @ref basic_json(const CompatibleNumberUnsignedType) -- create a number
  value (unsigned integer) from a compatible number type

  @since version 2.0.0
  */
  template <typename T, typename std::enable_if<
                            not(std::is_same<T, int>::value) and
                                std::is_same<T, number_unsigned_t>::value,
                            int>::type = 0>
  basic_json(const number_unsigned_t val) noexcept
      : m_type(value_t::number_unsigned),
        m_value(val)
  {
    assert_invariant();
  }

  /*!
  @brief create an unsigned number (implicit)

  Create an unsigned number JSON value with a given content. This
  constructor allows any type @a CompatibleNumberUnsignedType that can be
  used to construct values of type @ref number_unsigned_t.

  @tparam CompatibleNumberUnsignedType An integer type which is compatible
  to @ref number_unsigned_t. Examples may include the types `unsigned int`,
  `uint32_t`, or `unsigned short`.

  @param[in] val  an unsigned integer to create a JSON number from

  @complexity Constant.

  @sa @ref basic_json(const number_unsigned_t) -- create a number value
  (unsigned)

  @since version 2.0.0
  */
  template <
      typename CompatibleNumberUnsignedType,
      typename std::enable_if<
          std::is_constructible<number_unsigned_t,
                                CompatibleNumberUnsignedType>::value and
              std::numeric_limits<CompatibleNumberUnsignedType>::is_integer and
              not std::numeric_limits<CompatibleNumberUnsignedType>::is_signed,
          CompatibleNumberUnsignedType>::type = 0>
  basic_json(const CompatibleNumberUnsignedType val) noexcept
      : m_type(value_t::number_unsigned),
        m_value(static_cast<number_unsigned_t>(val))
  {
    assert_invariant();
  }

  /*!
  @brief create a floating-point number (explicit)

  Create a floating-point number JSON value with a given content.

  @param[in] val  a floating-point value to create a JSON number from

  @note [RFC 7159](http://www.rfc-editor.org/rfc/rfc7159.txt), section 6
  disallows NaN values:
  > Numeric values that cannot be represented in the grammar below (such as
  > Infinity and NaN) are not permitted.
  In case the parameter @a val is not a number, a JSON null value is created
  instead.

  @complexity Constant.

  @liveexample{The following example creates several floating-point
  values.,basic_json__number_float_t}

  @sa @ref basic_json(const CompatibleNumberFloatType) -- create a number
  value (floating-point) from a compatible number type

  @since version 1.0.0
  */
  basic_json(const number_float_t val) noexcept : m_type(value_t::number_float),
                                                  m_value(val)
  {
    // replace infinity and NAN by null
    if (not std::isfinite(val))
    {
      m_type = value_t::null;
      m_value = json_value();
    }

    assert_invariant();
  }

  /*!
  @brief create an floating-point number (implicit)

  Create an floating-point number JSON value with a given content. This
  constructor allows any type @a CompatibleNumberFloatType that can be used
  to construct values of type @ref number_float_t.

  @tparam CompatibleNumberFloatType A floating-point type which is
  compatible to @ref number_float_t. Examples may include the types `float`
  or `double`.

  @param[in] val  a floating-point to create a JSON number from

  @note [RFC 7159](http://www.rfc-editor.org/rfc/rfc7159.txt), section 6
  disallows NaN values:
  > Numeric values that cannot be represented in the grammar below (such as
  > Infinity and NaN) are not permitted.
  In case the parameter @a val is not a number, a JSON null value is
  created instead.

  @complexity Constant.

  @liveexample{The example below shows the construction of several
  floating-point number values from compatible
  types.,basic_json__CompatibleNumberFloatType}

  @sa @ref basic_json(const number_float_t) -- create a number value
  (floating-point)

  @since version 1.0.0
  */
  template <typename CompatibleNumberFloatType,
            typename = typename std::enable_if<
                std::is_constructible<number_float_t,
                                      CompatibleNumberFloatType>::value and
                std::is_floating_point<CompatibleNumberFloatType>::value>::type>
  basic_json(const CompatibleNumberFloatType val) noexcept
      : basic_json(number_float_t(val))
  {
    assert_invariant();
  }

  /*!
  @brief create a container (array or object) from an initializer list

  Creates a JSON value of type array or object from the passed initializer
  list @a init. In case @a type_deduction is `true` (default), the type of
  the JSON value to be created is deducted from the initializer list @a init
  according to the following rules:

  1. If the list is empty, an empty JSON object value `{}` is created.
  2. If the list consists of pairs whose first element is a string, a JSON
     object value is created where the first elements of the pairs are
     treated as keys and the second elements are as values.
  3. In all other cases, an array is created.

  The rules aim to create the best fit between a C++ initializer list and
  JSON values. The rationale is as follows:

  1. The empty initializer list is written as `{}` which is exactly an empty
     JSON object.
  2. C++ has now way of describing mapped types other than to list a list of
     pairs. As JSON requires that keys must be of type string, rule 2 is the
     weakest constraint one can pose on initializer lists to interpret them
     as an object.
  3. In all other cases, the initializer list could not be interpreted as
     JSON object type, so interpreting it as JSON array type is safe.

  With the rules described above, the following JSON values cannot be
  expressed by an initializer list:

  - the empty array (`[]`): use @ref array(std::initializer_list<basic_json>)
    with an empty initializer list in this case
  - arrays whose elements satisfy rule 2: use @ref
    array(std::initializer_list<basic_json>) with the same initializer list
    in this case

  @note When used without parentheses around an empty initializer list, @ref
  basic_json() is called instead of this function, yielding the JSON null
  value.

  @param[in] init  initializer list with JSON values

  @param[in] type_deduction internal parameter; when set to `true`, the type
  of the JSON value is deducted from the initializer list @a init; when set
  to `false`, the type provided via @a manual_type is forced. This mode is
  used by the functions @ref array(std::initializer_list<basic_json>) and
  @ref object(std::initializer_list<basic_json>).

  @param[in] manual_type internal parameter; when @a type_deduction is set
  to `false`, the created JSON value will use the provided type (only @ref
  value_t::array and @ref value_t::object are valid); when @a type_deduction
  is set to `true`, this parameter has no effect

  @throw std::domain_error if @a type_deduction is `false`, @a manual_type
  is `value_t::object`, but @a init contains an element which is not a pair
  whose first element is a string; example: `"cannot create object from
  initializer list"`

  @complexity Linear in the size of the initializer list @a init.

  @liveexample{The example below shows how JSON values are created from
  initializer lists.,basic_json__list_init_t}

  @sa @ref array(std::initializer_list<basic_json>) -- create a JSON array
  value from an initializer list
  @sa @ref object(std::initializer_list<basic_json>) -- create a JSON object
  value from an initializer list

  @since version 1.0.0
  */
  basic_json(std::initializer_list<basic_json> init, bool type_deduction = true,
             value_t manual_type = value_t::array)
  {
    // check if each element is an array with two elements whose first
    // element is a string
    bool is_an_object =
        std::all_of(init.begin(), init.end(), [](const basic_json &element) {
          return element.is_array() and element.size() == 2 and
                 element[0].is_string();
        });

    // adjust type if type deduction is not wanted
    if (not type_deduction)
    {
      // if array is wanted, do not create an object though possible
      if (manual_type == value_t::array)
      {
        is_an_object = false;
      }

      // if object is wanted but impossible, throw an exception
      if (manual_type == value_t::object and not is_an_object)
      {
        JSON_THROW(
            std::domain_error("cannot create object from initializer list"));
      }
    }

    if (is_an_object)
    {
      // the initializer list is a list of pairs -> create object
      m_type = value_t::object;
      m_value = value_t::object;

      std::for_each(
          init.begin(), init.end(), [this](const basic_json &element) {
            m_value.object->emplace(*(element[0].m_value.string), element[1]);
          });
    }
    else
    {
      // the initializer list describes an array -> create array
      m_type = value_t::array;
      m_value.array = create<array_t>(init);
    }

    assert_invariant();
  }

  /*!
  @brief explicitly create an array from an initializer list

  Creates a JSON array value from a given initializer list. That is, given a
  list of values `a, b, c`, creates the JSON value `[a, b, c]`. If the
  initializer list is empty, the empty array `[]` is created.

  @note This function is only needed to express two edge cases that cannot
  be realized with the initializer list constructor (@ref
  basic_json(std::initializer_list<basic_json>, bool, value_t)). These cases
  are:
  1. creating an array whose elements are all pairs whose first element is a
  string -- in this case, the initializer list constructor would create an
  object, taking the first elements as keys
  2. creating an empty array -- passing the empty initializer list to the
  initializer list constructor yields an empty object

  @param[in] init  initializer list with JSON values to create an array from
  (optional)

  @return JSON array value

  @complexity Linear in the size of @a init.

  @liveexample{The following code shows an example for the `array`
  function.,array}

  @sa @ref basic_json(std::initializer_list<basic_json>, bool, value_t) --
  create a JSON value from an initializer list
  @sa @ref object(std::initializer_list<basic_json>) -- create a JSON object
  value from an initializer list

  @since version 1.0.0
  */
  static basic_json array(std::initializer_list<basic_json> init =
                              std::initializer_list<basic_json>())
  {
    return basic_json(init, false, value_t::array);
  }

  /*!
  @brief explicitly create an object from an initializer list

  Creates a JSON object value from a given initializer list. The initializer
  lists elements must be pairs, and their first elements must be strings. If
  the initializer list is empty, the empty object `{}` is created.

  @note This function is only added for symmetry reasons. In contrast to the
  related function @ref array(std::initializer_list<basic_json>), there are
  no cases which can only be expressed by this function. That is, any
  initializer list @a init can also be passed to the initializer list
  constructor @ref basic_json(std::initializer_list<basic_json>, bool,
  value_t).

  @param[in] init  initializer list to create an object from (optional)

  @return JSON object value

  @throw std::domain_error if @a init is not a pair whose first elements are
  strings; thrown by
  @ref basic_json(std::initializer_list<basic_json>, bool, value_t)

  @complexity Linear in the size of @a init.

  @liveexample{The following code shows an example for the `object`
  function.,object}

  @sa @ref basic_json(std::initializer_list<basic_json>, bool, value_t) --
  create a JSON value from an initializer list
  @sa @ref array(std::initializer_list<basic_json>) -- create a JSON array
  value from an initializer list

  @since version 1.0.0
  */
  static basic_json object(std::initializer_list<basic_json> init =
                               std::initializer_list<basic_json>())
  {
    return basic_json(init, false, value_t::object);
  }

  /*!
  @brief construct an array with count copies of given value

  Constructs a JSON array value by creating @a cnt copies of a passed value.
  In case @a cnt is `0`, an empty array is created. As postcondition,
  `std::distance(begin(),end()) == cnt` holds.

  @param[in] cnt  the number of JSON copies of @a val to create
  @param[in] val  the JSON value to copy

  @complexity Linear in @a cnt.

  @liveexample{The following code shows examples for the @ref
  basic_json(size_type\, const basic_json&)
  constructor.,basic_json__size_type_basic_json}

  @since version 1.0.0
  */
  basic_json(size_type cnt, const basic_json &val) : m_type(value_t::array)
  {
    m_value.array = create<array_t>(cnt, val);
    assert_invariant();
  }

  /*!
  @brief construct a JSON container given an iterator range

  Constructs the JSON value with the contents of the range `[first, last)`.
  The semantics depends on the different types a JSON value can have:
  - In case of primitive types (number, boolean, or string), @a first must
    be `begin()` and @a last must be `end()`. In this case, the value is
    copied. Otherwise, std::out_of_range is thrown.
  - In case of structured types (array, object), the constructor behaves as
    similar versions for `std::vector`.
  - In case of a null type, std::domain_error is thrown.

  @tparam InputIT an input iterator type (@ref iterator or @ref
  const_iterator)

  @param[in] first begin of the range to copy from (included)
  @param[in] last end of the range to copy from (excluded)

  @pre Iterators @a first and @a last must be initialized. **This
       precondition is enforced with an assertion.**

  @throw std::domain_error if iterators are not compatible; that is, do not
  belong to the same JSON value; example: `"iterators are not compatible"`
  @throw std::out_of_range if iterators are for a primitive type (number,
  boolean, or string) where an out of range error can be detected easily;
  example: `"iterators out of range"`
  @throw std::bad_alloc if allocation for object, array, or string fails
  @throw std::domain_error if called with a null value; example: `"cannot
  use construct with iterators from null"`

  @complexity Linear in distance between @a first and @a last.

  @liveexample{The example below shows several ways to create JSON values by
  specifying a subrange with iterators.,basic_json__InputIt_InputIt}

  @since version 1.0.0
  */
  template <class InputIT,
            typename std::enable_if<
                std::is_same<InputIT, typename basic_json_t::iterator>::value or
                    std::is_same<InputIT,
                                 typename basic_json_t::const_iterator>::value,
                int>::type = 0>
  basic_json(InputIT first, InputIT last)
  {
    assert(first.m_object != nullptr);
    assert(last.m_object != nullptr);

    // make sure iterator fits the current value
    if (first.m_object != last.m_object)
    {
      JSON_THROW(std::domain_error("iterators are not compatible"));
    }

    // copy type from first iterator
    m_type = first.m_object->m_type;

    // check if iterator range is complete for primitive values
    switch (m_type)
    {
      case value_t::boolean:
      case value_t::number_float:
      case value_t::number_integer:
      case value_t::number_unsigned:
      case value_t::string:
      {
        if (not first.m_it.primitive_iterator.is_begin() or
            not last.m_it.primitive_iterator.is_end())
        {
          JSON_THROW(std::out_of_range("iterators out of range"));
        }
        break;
      }

      default:
      {
        break;
      }
    }

    switch (m_type)
    {
      case value_t::number_integer:
      {
        m_value.number_integer = first.m_object->m_value.number_integer;
        break;
      }

      case value_t::number_unsigned:
      {
        m_value.number_unsigned = first.m_object->m_value.number_unsigned;
        break;
      }

      case value_t::number_float:
      {
        m_value.number_float = first.m_object->m_value.number_float;
        break;
      }

      case value_t::boolean:
      {
        m_value.boolean = first.m_object->m_value.boolean;
        break;
      }

      case value_t::string:
      {
        m_value = *first.m_object->m_value.string;
        break;
      }

      case value_t::object:
      {
        m_value.object = create<object_t>(first.m_it.object_iterator,
                                          last.m_it.object_iterator);
        break;
      }

      case value_t::array:
      {
        m_value.array = create<array_t>(first.m_it.array_iterator,
                                        last.m_it.array_iterator);