json.hpp

                           typename basic_json_t::const_iterator>::value,
          int>::type = 0>
  IteratorType erase(IteratorType pos)
  {
    // make sure iterator fits the current value
    if (this != pos.m_object)
    {
      JSON_THROW(std::domain_error("iterator does not fit current value"));
    }

    IteratorType result = end();

    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 pos.m_it.primitive_iterator.is_begin())
        {
          JSON_THROW(std::out_of_range("iterator out of range"));
        }

        if (is_string())
        {
          AllocatorType<string_t> alloc;
          alloc.destroy(m_value.string);
          alloc.deallocate(m_value.string, 1);
          m_value.string = nullptr;
        }

        m_type = value_t::null;
        assert_invariant();
        break;
      }

      case value_t::object:
      {
        result.m_it.object_iterator =
            m_value.object->erase(pos.m_it.object_iterator);
        break;
      }

      case value_t::array:
      {
        result.m_it.array_iterator =
            m_value.array->erase(pos.m_it.array_iterator);
        break;
      }

      default:
      {
        JSON_THROW(std::domain_error("cannot use erase() with " + type_name()));
      }
    }

    return result;
  }

  /*!
  @brief remove elements given an iterator range

  Removes the element specified by the range `[first; last)`. The iterator
  @a first does not need to be dereferenceable if `first == last`: erasing
  an empty range is a no-op.

  If called on a primitive type other than `null`, the resulting JSON value
  will be `null`.

  @param[in] first iterator to the beginning of the range to remove
  @param[in] last iterator past the end of the range to remove
  @return Iterator following the last removed element. If the iterator @a
  second refers to the last element, the `end()` iterator is returned.

  @tparam IteratorType an @ref iterator or @ref const_iterator

  @post Invalidates iterators and references at or after the point of the
  erase, including the `end()` iterator.

  @throw std::domain_error if called on a `null` value; example: `"cannot
  use erase() with null"`
  @throw std::domain_error if called on iterators which does not belong to
  the current JSON value; example: `"iterators do not fit current value"`
  @throw std::out_of_range if called on a primitive type with invalid
  iterators (i.e., if `first != begin()` and `last != end()`); example:
  `"iterators out of range"`

  @complexity The complexity depends on the type:
  - objects: `log(size()) + std::distance(first, last)`
  - arrays: linear in the distance between @a first and @a last, plus linear
    in the distance between @a last and end of the container
  - strings: linear in the length of the string
  - other types: constant

  @liveexample{The example shows the result of `erase()` for different JSON
  types.,erase__IteratorType_IteratorType}

  @sa @ref erase(IteratorType) -- removes the element at a given position
  @sa @ref erase(const typename object_t::key_type&) -- removes the element
  from an object at the given key
  @sa @ref erase(const size_type) -- removes the element from an array at
  the given index

  @since version 1.0.0
  */
  template <
      class IteratorType,
      typename std::enable_if<
          std::is_same<IteratorType, typename basic_json_t::iterator>::value or
              std::is_same<IteratorType,
                           typename basic_json_t::const_iterator>::value,
          int>::type = 0>
  IteratorType erase(IteratorType first, IteratorType last)
  {
    // make sure iterator fits the current value
    if (this != first.m_object or this != last.m_object)
    {
      JSON_THROW(std::domain_error("iterators do not fit current value"));
    }

    IteratorType result = end();

    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"));
        }

        if (is_string())
        {
          AllocatorType<string_t> alloc;
          alloc.destroy(m_value.string);
          alloc.deallocate(m_value.string, 1);
          m_value.string = nullptr;
        }

        m_type = value_t::null;
        assert_invariant();
        break;
      }

      case value_t::object:
      {
        result.m_it.object_iterator = m_value.object->erase(
            first.m_it.object_iterator, last.m_it.object_iterator);
        break;
      }

      case value_t::array:
      {
        result.m_it.array_iterator = m_value.array->erase(
            first.m_it.array_iterator, last.m_it.array_iterator);
        break;
      }

      default:
      {
        JSON_THROW(std::domain_error("cannot use erase() with " + type_name()));
      }
    }

    return result;
  }

  /*!
  @brief remove element from a JSON object given a key

  Removes elements from a JSON object with the key value @a key.

  @param[in] key value of the elements to remove

  @return Number of elements removed. If @a ObjectType is the default
  `std::map` type, the return value will always be `0` (@a key was not
  found) or `1` (@a key was found).

  @post References and iterators to the erased elements are invalidated.
  Other references and iterators are not affected.

  @throw std::domain_error when called on a type other than JSON object;
  example: `"cannot use erase() with null"`

  @complexity `log(size()) + count(key)`

  @liveexample{The example shows the effect of `erase()`.,erase__key_type}

  @sa @ref erase(IteratorType) -- removes the element at a given position
  @sa @ref erase(IteratorType, IteratorType) -- removes the elements in
  the given range
  @sa @ref erase(const size_type) -- removes the element from an array at
  the given index

  @since version 1.0.0
  */
  size_type erase(const typename object_t::key_type &key)
  {
    // this erase only works for objects
    if (is_object())
    {
      return m_value.object->erase(key);
    }

    JSON_THROW(std::domain_error("cannot use erase() with " + type_name()));
  }

  /*!
  @brief remove element from a JSON array given an index

  Removes element from a JSON array at the index @a idx.

  @param[in] idx index of the element to remove

  @throw std::domain_error when called on a type other than JSON array;
  example: `"cannot use erase() with null"`
  @throw std::out_of_range when `idx >= size()`; example: `"array index 17
  is out of range"`

  @complexity Linear in distance between @a idx and the end of the container.

  @liveexample{The example shows the effect of `erase()`.,erase__size_type}

  @sa @ref erase(IteratorType) -- removes the element at a given position
  @sa @ref erase(IteratorType, IteratorType) -- removes the elements in
  the given range
  @sa @ref erase(const typename object_t::key_type&) -- removes the element
  from an object at the given key

  @since version 1.0.0
  */
  void erase(const size_type idx)
  {
    // this erase only works for arrays
    if (is_array())
    {
      if (idx >= size())
      {
        JSON_THROW(std::out_of_range("array index " + std::to_string(idx) +
                                     " is out of range"));
      }

      m_value.array->erase(m_value.array->begin() +
                           static_cast<difference_type>(idx));
    }
    else
    {
      JSON_THROW(std::domain_error("cannot use erase() with " + type_name()));
    }
  }

  /// @}

  ////////////
  // lookup //
  ////////////

  /// @name lookup
  /// @{

  /*!
  @brief find an element in a JSON object

  Finds an element in a JSON object with key equivalent to @a key. If the
  element is not found or the JSON value is not an object, end() is
  returned.

  @note This method always returns @ref end() when executed on a JSON type
        that is not an object.

  @param[in] key key value of the element to search for

  @return Iterator to an element with key equivalent to @a key. If no such
  element is found or the JSON value is not an object, past-the-end (see
  @ref end()) iterator is returned.

  @complexity Logarithmic in the size of the JSON object.

  @liveexample{The example shows how `find()` is used.,find__key_type}

  @since version 1.0.0
  */
  iterator find(typename object_t::key_type key)
  {
    auto result = end();

    if (is_object())
    {
      result.m_it.object_iterator = m_value.object->find(key);
    }

    return result;
  }

  /*!
  @brief find an element in a JSON object
  @copydoc find(typename object_t::key_type)
  */
  const_iterator find(typename object_t::key_type key) const
  {
    auto result = cend();

    if (is_object())
    {
      result.m_it.object_iterator = m_value.object->find(key);
    }

    return result;
  }

  /*!
  @brief returns the number of occurrences of a key in a JSON object

  Returns the number of elements with key @a key. If ObjectType is the
  default `std::map` type, the return value will always be `0` (@a key was
  not found) or `1` (@a key was found).

  @note This method always returns `0` when executed on a JSON type that is
        not an object.

  @param[in] key key value of the element to count

  @return Number of elements with key @a key. If the JSON value is not an
  object, the return value will be `0`.

  @complexity Logarithmic in the size of the JSON object.

  @liveexample{The example shows how `count()` is used.,count}

  @since version 1.0.0
  */
  size_type count(typename object_t::key_type key) const
  {
    // return 0 for all nonobject types
    return is_object() ? m_value.object->count(key) : 0;
  }

  /// @}

  ///////////////
  // iterators //
  ///////////////

  /// @name iterators
  /// @{

  /*!
  @brief returns an iterator to the first element

  Returns an iterator to the first element.

  @image html range-begin-end.svg "Illustration from cppreference.com"

  @return iterator to the first element

  @complexity Constant.

  @requirement This function helps `basic_json` satisfying the
  [Container](http://en.cppreference.com/w/cpp/concept/Container)
  requirements:
  - The complexity is constant.

  @liveexample{The following code shows an example for `begin()`.,begin}

  @sa @ref cbegin() -- returns a const iterator to the beginning
  @sa @ref end() -- returns an iterator to the end
  @sa @ref cend() -- returns a const iterator to the end

  @since version 1.0.0
  */
  iterator begin() noexcept
  {
    iterator result(this);
    result.set_begin();
    return result;
  }

  /*!
  @copydoc basic_json::cbegin()
  */
  const_iterator begin() const noexcept { return cbegin(); }

  /*!
  @brief returns a const iterator to the first element

  Returns a const iterator to the first element.

  @image html range-begin-end.svg "Illustration from cppreference.com"

  @return const iterator to the first element

  @complexity Constant.

  @requirement This function helps `basic_json` satisfying the
  [Container](http://en.cppreference.com/w/cpp/concept/Container)
  requirements:
  - The complexity is constant.
  - Has the semantics of `const_cast<const basic_json&>(*this).begin()`.

  @liveexample{The following code shows an example for `cbegin()`.,cbegin}

  @sa @ref begin() -- returns an iterator to the beginning
  @sa @ref end() -- returns an iterator to the end
  @sa @ref cend() -- returns a const iterator to the end

  @since version 1.0.0
  */
  const_iterator cbegin() const noexcept
  {
    const_iterator result(this);
    result.set_begin();
    return result;
  }

  /*!
  @brief returns an iterator to one past the last element

  Returns an iterator to one past the last element.

  @image html range-begin-end.svg "Illustration from cppreference.com"

  @return iterator one past the last element

  @complexity Constant.

  @requirement This function helps `basic_json` satisfying the
  [Container](http://en.cppreference.com/w/cpp/concept/Container)
  requirements:
  - The complexity is constant.

  @liveexample{The following code shows an example for `end()`.,end}

  @sa @ref cend() -- returns a const iterator to the end
  @sa @ref begin() -- returns an iterator to the beginning
  @sa @ref cbegin() -- returns a const iterator to the beginning

  @since version 1.0.0
  */
  iterator end() noexcept
  {
    iterator result(this);
    result.set_end();
    return result;
  }

  /*!
  @copydoc basic_json::cend()
  */
  const_iterator end() const noexcept { return cend(); }

  /*!
  @brief returns a const iterator to one past the last element

  Returns a const iterator to one past the last element.

  @image html range-begin-end.svg "Illustration from cppreference.com"

  @return const iterator one past the last element

  @complexity Constant.

  @requirement This function helps `basic_json` satisfying the
  [Container](http://en.cppreference.com/w/cpp/concept/Container)
  requirements:
  - The complexity is constant.
  - Has the semantics of `const_cast<const basic_json&>(*this).end()`.

  @liveexample{The following code shows an example for `cend()`.,cend}

  @sa @ref end() -- returns an iterator to the end
  @sa @ref begin() -- returns an iterator to the beginning
  @sa @ref cbegin() -- returns a const iterator to the beginning

  @since version 1.0.0
  */
  const_iterator cend() const noexcept
  {
    const_iterator result(this);
    result.set_end();
    return result;
  }

  /*!
  @brief returns an iterator to the reverse-beginning

  Returns an iterator to the reverse-beginning; that is, the last element.

  @image html range-rbegin-rend.svg "Illustration from cppreference.com"

  @complexity Constant.

  @requirement This function helps `basic_json` satisfying the
  [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
  requirements:
  - The complexity is constant.
  - Has the semantics of `reverse_iterator(end())`.

  @liveexample{The following code shows an example for `rbegin()`.,rbegin}

  @sa @ref crbegin() -- returns a const reverse iterator to the beginning
  @sa @ref rend() -- returns a reverse iterator to the end
  @sa @ref crend() -- returns a const reverse iterator to the end

  @since version 1.0.0
  */
  reverse_iterator rbegin() noexcept { return reverse_iterator(end()); }

  /*!
  @copydoc basic_json::crbegin()
  */
  const_reverse_iterator rbegin() const noexcept { return crbegin(); }

  /*!
  @brief returns an iterator to the reverse-end

  Returns an iterator to the reverse-end; that is, one before the first
  element.

  @image html range-rbegin-rend.svg "Illustration from cppreference.com"

  @complexity Constant.

  @requirement This function helps `basic_json` satisfying the
  [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
  requirements:
  - The complexity is constant.
  - Has the semantics of `reverse_iterator(begin())`.

  @liveexample{The following code shows an example for `rend()`.,rend}

  @sa @ref crend() -- returns a const reverse iterator to the end
  @sa @ref rbegin() -- returns a reverse iterator to the beginning
  @sa @ref crbegin() -- returns a const reverse iterator to the beginning

  @since version 1.0.0
  */
  reverse_iterator rend() noexcept { return reverse_iterator(begin()); }

  /*!
  @copydoc basic_json::crend()
  */
  const_reverse_iterator rend() const noexcept { return crend(); }

  /*!
  @brief returns a const reverse iterator to the last element

  Returns a const iterator to the reverse-beginning; that is, the last
  element.

  @image html range-rbegin-rend.svg "Illustration from cppreference.com"

  @complexity Constant.

  @requirement This function helps `basic_json` satisfying the
  [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
  requirements:
  - The complexity is constant.
  - Has the semantics of `const_cast<const basic_json&>(*this).rbegin()`.

  @liveexample{The following code shows an example for `crbegin()`.,crbegin}

  @sa @ref rbegin() -- returns a reverse iterator to the beginning
  @sa @ref rend() -- returns a reverse iterator to the end
  @sa @ref crend() -- returns a const reverse iterator to the end

  @since version 1.0.0
  */
  const_reverse_iterator crbegin() const noexcept
  {
    return const_reverse_iterator(cend());
  }

  /*!
  @brief returns a const reverse iterator to one before the first

  Returns a const reverse iterator to the reverse-end; that is, one before
  the first element.

  @image html range-rbegin-rend.svg "Illustration from cppreference.com"

  @complexity Constant.

  @requirement This function helps `basic_json` satisfying the
  [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
  requirements:
  - The complexity is constant.
  - Has the semantics of `const_cast<const basic_json&>(*this).rend()`.

  @liveexample{The following code shows an example for `crend()`.,crend}

  @sa @ref rend() -- returns a reverse iterator to the end
  @sa @ref rbegin() -- returns a reverse iterator to the beginning
  @sa @ref crbegin() -- returns a const reverse iterator to the beginning

  @since version 1.0.0
  */
  const_reverse_iterator crend() const noexcept
  {
    return const_reverse_iterator(cbegin());
  }

private:
  // forward declaration
  template <typename IteratorType> class iteration_proxy;

public:
  /*!
  @brief wrapper to access iterator member functions in range-based for

  This function allows to access @ref iterator::key() and @ref
  iterator::value() during range-based for loops. In these loops, a
  reference to the JSON values is returned, so there is no access to the
  underlying iterator.

  @note The name of this function is not yet final and may change in the
  future.
  */
  static iteration_proxy<iterator> iterator_wrapper(reference cont)
  {
    return iteration_proxy<iterator>(cont);
  }

  /*!
  @copydoc iterator_wrapper(reference)
  */
  static iteration_proxy<const_iterator> iterator_wrapper(const_reference cont)
  {
    return iteration_proxy<const_iterator>(cont);
  }

  /// @}

  //////////////
  // capacity //
  //////////////

  /// @name capacity
  /// @{

  /*!
  @brief checks whether the container is empty

  Checks if a JSON value has no elements.

  @return The return value depends on the different types and is
          defined as follows:
          Value type  | return value
          ----------- | -------------
          null        | `true`
          boolean     | `false`
          string      | `false`
          number      | `false`
          object      | result of function `object_t::empty()`
          array       | result of function `array_t::empty()`

  @note This function does not return whether a string stored as JSON value
  is empty - it returns whether the JSON container itself is empty which is
  false in the case of a string.

  @complexity Constant, as long as @ref array_t and @ref object_t satisfy
  the Container concept; that is, their `empty()` functions have constant
  complexity.

  @requirement This function helps `basic_json` satisfying the
  [Container](http://en.cppreference.com/w/cpp/concept/Container)
  requirements:
  - The complexity is constant.
  - Has the semantics of `begin() == end()`.

  @liveexample{The following code uses `empty()` to check if a JSON
  object contains any elements.,empty}

  @sa @ref size() -- returns the number of elements

  @since version 1.0.0
  */
  bool empty() const noexcept
  {
    switch (m_type)
    {
      case value_t::null:
      {
        // null values are empty
        return true;
      }

      case value_t::array:
      {
        // delegate call to array_t::empty()
        return m_value.array->empty();
      }

      case value_t::object:
      {
        // delegate call to object_t::empty()
        return m_value.object->empty();
      }

      default:
      {
        // all other types are nonempty
        return false;
      }
    }
  }

  /*!
  @brief returns the number of elements

  Returns the number of elements in a JSON value.

  @return The return value depends on the different types and is
          defined as follows:
          Value type  | return value
          ----------- | -------------
          null        | `0`
          boolean     | `1`
          string      | `1`
          number      | `1`
          object      | result of function object_t::size()
          array       | result of function array_t::size()

  @note This function does not return the length of a string stored as JSON
  value - it returns the number of elements in the JSON value which is 1 in
  the case of a string.

  @complexity Constant, as long as @ref array_t and @ref object_t satisfy
  the Container concept; that is, their size() functions have constant
  complexity.

  @requirement This function helps `basic_json` satisfying the
  [Container](http://en.cppreference.com/w/cpp/concept/Container)
  requirements:
  - The complexity is constant.
  - Has the semantics of `std::distance(begin(), end())`.

  @liveexample{The following code calls `size()` on the different value
  types.,size}

  @sa @ref empty() -- checks whether the container is empty
  @sa @ref max_size() -- returns the maximal number of elements

  @since version 1.0.0
  */
  size_type size() const noexcept
  {
    switch (m_type)
    {
      case value_t::null:
      {
        // null values are empty
        return 0;
      }

      case value_t::array:
      {
        // delegate call to array_t::size()
        return m_value.array->size();
      }

      case value_t::object:
      {
        // delegate call to object_t::size()
        return m_value.object->size();
      }

      default:
      {
        // all other types have size 1
        return 1;
      }
    }
  }

  /*!
  @brief returns the maximum possible number of elements

  Returns the maximum number of elements a JSON value is able to hold due to
  system or library implementation limitations, i.e. `std::distance(begin(),
  end())` for the JSON value.

  @return The return value depends on the different types and is
          defined as follows:
          Value type  | return value
          ----------- | -------------
          null        | `0` (same as `size()`)
          boolean     | `1` (same as `size()`)
          string      | `1` (same as `size()`)
          number      | `1` (same as `size()`)
          object      | result of function `object_t::max_size()`
          array       | result of function `array_t::max_size()`

  @complexity Constant, as long as @ref array_t and @ref object_t satisfy
  the Container concept; that is, their `max_size()` functions have constant
  complexity.

  @requirement This function helps `basic_json` satisfying the
  [Container](http://en.cppreference.com/w/cpp/concept/Container)
  requirements:
  - The complexity is constant.
  - Has the semantics of returning `b.size()` where `b` is the largest
    possible JSON value.

  @liveexample{The following code calls `max_size()` on the different value
  types. Note the output is implementation specific.,max_size}

  @sa @ref size() -- returns the number of elements

  @since version 1.0.0
  */
  size_type max_size() const noexcept
  {
    switch (m_type)
    {
      case value_t::array:
      {
        // delegate call to array_t::max_size()
        return m_value.array->max_size();
      }

      case value_t::object:
      {
        // delegate call to object_t::max_size()
        return m_value.object->max_size();
      }

      default:
      {
        // all other types have max_size() == size()
        return size();
      }
    }
  }

  /// @}

  ///////////////
  // modifiers //
  ///////////////

  /// @name modifiers
  /// @{

  /*!
  @brief clears the contents

  Clears the content of a JSON value and resets it to the default value as
  if @ref basic_json(value_t) would have been called:

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

  @complexity Linear in the size of the JSON value.

  @liveexample{The example below shows the effect of `clear()` to different
  JSON types.,clear}

  @since version 1.0.0
  */
  void clear() noexcept
  {
    switch (m_type)
    {
      case value_t::number_integer:
      {
        m_value.number_integer = 0;
        break;
      }

      case value_t::number_unsigned:
      {
        m_value.number_unsigned = 0;
        break;
      }

      case value_t::number_float:
      {
        m_value.number_float = 0.0;
        break;
      }

      case value_t::boolean:
      {
        m_value.boolean = false;
        break;
      }

      case value_t::string:
      {
        m_value.string->clear();
        break;
      }

      case value_t::array:
      {
        m_value.array->clear();
        break;
      }

      case value_t::object:
      {
        m_value.object->clear();
        break;
      }

      default:
      {
        break;
      }
    }
  }

  /*!
  @brief add an object to an array

  Appends the given element @a val to the end of the JSON value. If the
  function is called on a JSON null value, an empty array is created before
  appending @a val.

  @param[in] val the value to add to the JSON array

  @throw std::domain_error when called on a type other than JSON array or
  null; example: `"cannot use push_back() with number"`

  @complexity Amortized constant.

  @liveexample{The example shows how `push_back()` and `+=` can be used to
  add elements to a JSON array. Note how the `null` value was silently
  converted to a JSON array.,push_back}

  @since version 1.0.0
  */
  void push_back(basic_json &&val)
  {
    // push_back only works for null objects or arrays
    if (not(is_null() or is_array()))
    {
      JSON_THROW(
          std::domain_error("cannot use push_back() with " + type_name()));
    }

    // transform null object into an array
    if (is_null())
    {
      m_type = value_t::array;
      m_value = value_t::array;
      assert_invariant();
    }

    // add element to array (move semantics)
    m_value.array->push_back(std::move(val));
    // invalidate object
    val.m_type = value_t::null;
  }

  /*!
  @brief add an object to an array
  @copydoc push_back(basic_json&&)
  */
  reference operator+=(basic_json &&val)
  {
    push_back(std::move(val));
    return *this;
  }

  /*!
  @brief add an object to an array
  @copydoc push_back(basic_json&&)
  */
  void push_back(const basic_json &val)
  {
    // push_back only works for null objects or arrays
    if (not(is_null() or is_array()))
    {
      JSON_THROW(
          std::domain_error("cannot use push_back() with " + type_name()));
    }

    // transform null object into an array
    if (is_null())
    {
      m_type = value_t::array;
      m_value = value_t::array;
      assert_invariant();
    }

    // add element to array