From fe086d7432191fbc9f9d3d8adb4766e291f19d50 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9o=20DELRIEU?= <delrieutheo@gmail.com>
Date: Sat, 1 Jul 2017 19:44:05 +0200
Subject: [PATCH 1/9] forward declare basic_json, add two macros

Those macros are used to reduce template argument boilerplate
---
 src/json.hpp | 53 +++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 38 insertions(+), 15 deletions(-)

diff --git a/src/json.hpp b/src/json.hpp
index 1bde08ced0..3c61545192 100644
--- a/src/json.hpp
+++ b/src/json.hpp
@@ -115,6 +115,39 @@ SOFTWARE.
 */
 namespace nlohmann
 {
+template<typename = void, typename = void>
+struct adl_serializer;
+
+// forward declaration of basic_json (required to split the class)
+template <template <typename U, typename V, typename... Args> class ObjectType =
+          std::map,
+          template <typename U, typename... Args> class ArrayType = std::vector,
+          class StringType = std::string, class BooleanType = bool,
+          class NumberIntegerType = std::int64_t,
+          class NumberUnsignedType = std::uint64_t,
+          class NumberFloatType = double,
+          template <typename U> class AllocatorType = std::allocator,
+          template <typename T, typename SFINAE = void> class JSONSerializer =
+          adl_serializer>
+class basic_json;
+
+// Ugly macros to avoid uglier copy-paste when specializing basic_json
+// This is only temporary and will be removed in 3.0
+
+#define NLOHMANN_BASIC_JSON_TPL_DECLARATION                                    \
+    template <template <typename, typename, typename...> class ObjectType,       \
+              template <typename, typename...> class ArrayType,                  \
+              class StringType, class BooleanType, class NumberIntegerType,      \
+              class NumberUnsignedType, class NumberFloatType,                   \
+              template <typename> class AllocatorType,                           \
+              template <typename, typename = void> class JSONSerializer>
+
+#define NLOHMANN_BASIC_JSON_TPL                                                \
+    basic_json<ObjectType, ArrayType, StringType, BooleanType,                   \
+    NumberIntegerType, NumberUnsignedType, NumberFloatType,           \
+    AllocatorType, JSONSerializer>
+
+
 
 /*!
 @brief unnamed namespace with internal helper functions
@@ -1251,7 +1284,7 @@ This serializer ignores the template arguments and uses ADL
 ([argument-dependent lookup](http://en.cppreference.com/w/cpp/language/adl))
 for serialization.
 */
-template<typename = void, typename = void>
+template<typename, typename>
 struct adl_serializer
 {
     /*!
@@ -1369,25 +1402,13 @@ Format](http://rfc7159.net/rfc7159)
 
 @nosubgrouping
 */
-template <
-    template<typename U, typename V, typename... Args> class ObjectType = std::map,
-    template<typename U, typename... Args> class ArrayType = std::vector,
-    class StringType = std::string,
-    class BooleanType = bool,
-    class NumberIntegerType = std::int64_t,
-    class NumberUnsignedType = std::uint64_t,
-    class NumberFloatType = double,
-    template<typename U> class AllocatorType = std::allocator,
-    template<typename T, typename SFINAE = void> class JSONSerializer = adl_serializer
-    >
+NLOHMANN_BASIC_JSON_TPL_DECLARATION
 class basic_json
 {
   private:
     template<detail::value_t> friend struct detail::external_constructor;
     /// workaround type for MSVC
-    using basic_json_t = basic_json<ObjectType, ArrayType, StringType,
-          BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType,
-          AllocatorType, JSONSerializer>;
+    using basic_json_t = NLOHMANN_BASIC_JSON_TPL;
 
   public:
     using value_t = detail::value_t;
@@ -14512,5 +14533,7 @@ inline nlohmann::json::json_pointer operator "" _json_pointer(const char* s, std
 #undef JSON_LIKELY
 #undef JSON_UNLIKELY
 #undef JSON_DEPRECATED
+#undef NLOHMANN_BASIC_JSON_TPL_DECLARATION
+#undef NLOHMANN_BASIC_JSON_TPL
 
 #endif

From a3321421943360697655c9593f27bf553f2c44b9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9o=20DELRIEU?= <delrieutheo@gmail.com>
Date: Sat, 1 Jul 2017 19:52:18 +0200
Subject: [PATCH 2/9] move json_pointer outside of basic_json

---
 src/json.hpp | 1616 ++++++++++++++++++++++++++------------------------
 1 file changed, 846 insertions(+), 770 deletions(-)

diff --git a/src/json.hpp b/src/json.hpp
index 3c61545192..2df26ae0a0 100644
--- a/src/json.hpp
+++ b/src/json.hpp
@@ -748,8 +748,7 @@ struct is_basic_json_nested_type
     static auto constexpr value = std::is_same<T, typename BasicJsonType::iterator>::value or
                                   std::is_same<T, typename BasicJsonType::const_iterator>::value or
                                   std::is_same<T, typename BasicJsonType::reverse_iterator>::value or
-                                  std::is_same<T, typename BasicJsonType::const_reverse_iterator>::value or
-                                  std::is_same<T, typename BasicJsonType::json_pointer>::value;
+                                  std::is_same<T, typename BasicJsonType::const_reverse_iterator>::value;
 };
 
 template<class BasicJsonType, class CompatibleArrayType>
@@ -1320,6 +1319,335 @@ struct adl_serializer
     }
 };
 
+/*!
+@brief JSON Pointer
+
+A JSON pointer defines a string syntax for identifying a specific value
+within a JSON document. It can be used with functions `at` and
+`operator[]`. Furthermore, JSON pointers are the base for JSON patches.
+
+@sa [RFC 6901](https://tools.ietf.org/html/rfc6901)
+
+@since version 2.0.0
+*/
+class json_pointer
+{
+    /// allow basic_json to access private members
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    friend class basic_json;
+
+  public:
+    /*!
+      @brief create JSON pointer
+
+      Create a JSON pointer according to the syntax described in
+      [Section 3 of RFC6901](https://tools.ietf.org/html/rfc6901#section-3).
+
+      @param[in] s  string representing the JSON pointer; if omitted, the
+      empty string is assumed which references the whole JSON
+      value
+
+      @throw parse_error.107 if the given JSON pointer @a s is nonempty and
+      does not begin with a slash (`/`); see example below
+
+      @throw parse_error.108 if a tilde (`~`) in the given JSON pointer @a s
+      is not followed by `0` (representing `~`) or `1` (representing `/`);
+      see example below
+
+      @liveexample{The example shows the construction several valid JSON
+      pointers as well as the exceptional behavior.,json_pointer}
+
+      @since version 2.0.0
+      */
+    explicit json_pointer(const std::string& s = "") : reference_tokens(split(s)) {}
+
+    /*!
+      @brief return a string representation of the JSON pointer
+
+      @invariant For each JSON pointer `ptr`, it holds:
+      @code {.cpp}
+      ptr == json_pointer(ptr.to_string());
+      @endcode
+
+      @return a string representation of the JSON pointer
+
+      @liveexample{The example shows the result of `to_string`.,
+      json_pointer__to_string}
+
+      @since version 2.0.0
+      */
+    std::string to_string() const noexcept
+    {
+        return std::accumulate(reference_tokens.begin(), reference_tokens.end(),
+                               std::string{},
+                               [](const std::string & a, const std::string & b)
+        {
+            return a + "/" + escape(b);
+        });
+    }
+
+    /// @copydoc to_string()
+    operator std::string() const
+    {
+        return to_string();
+    }
+
+  private:
+    /*!
+      @brief remove and return last reference pointer
+      @throw out_of_range.405 if JSON pointer has no parent
+      */
+    std::string pop_back()
+    {
+        if (is_root())
+        {
+            JSON_THROW(
+                detail::out_of_range::create(405, "JSON pointer has no parent"));
+        }
+
+        auto last = reference_tokens.back();
+        reference_tokens.pop_back();
+        return last;
+    }
+
+    /// return whether pointer points to the root document
+    bool is_root() const
+    {
+        return reference_tokens.empty();
+    }
+
+    json_pointer top() const
+    {
+        if (is_root())
+        {
+            JSON_THROW(detail::out_of_range::create(405, "JSON pointer has no parent"));
+        }
+
+        json_pointer result = *this;
+        result.reference_tokens = {reference_tokens[0]};
+        return result;
+    }
+
+
+    /*!
+      @brief create and return a reference to the pointed to value
+
+      @complexity Linear in the number of reference tokens.
+
+      @throw parse_error.109 if array index is not a number
+      @throw type_error.313 if value cannot be unflattened
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    NLOHMANN_BASIC_JSON_TPL& get_and_create(NLOHMANN_BASIC_JSON_TPL& j) const;
+
+    /*!
+      @brief return a reference to the pointed to value
+
+      @note This version does not throw if a value is not present, but tries
+      to create nested values instead. For instance, calling this function
+      with pointer `"/this/that"` on a null value is equivalent to calling
+      `operator[]("this").operator[]("that")` on that value, effectively
+      changing the null value to an object.
+
+      @param[in] ptr  a JSON value
+
+      @return reference to the JSON value pointed to by the JSON pointer
+
+      @complexity Linear in the length of the JSON pointer.
+
+      @throw parse_error.106   if an array index begins with '0'
+      @throw parse_error.109   if an array index was not a number
+      @throw out_of_range.404  if the JSON pointer can not be resolved
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    NLOHMANN_BASIC_JSON_TPL& get_unchecked(NLOHMANN_BASIC_JSON_TPL* ptr) const;
+
+    /*!
+      @throw parse_error.106   if an array index begins with '0'
+      @throw parse_error.109   if an array index was not a number
+      @throw out_of_range.402  if the array index '-' is used
+      @throw out_of_range.404  if the JSON pointer can not be resolved
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    NLOHMANN_BASIC_JSON_TPL& get_checked(NLOHMANN_BASIC_JSON_TPL* ptr) const;
+
+    /*!
+      @brief return a const reference to the pointed to value
+
+      @param[in] ptr  a JSON value
+
+      @return const reference to the JSON value pointed to by the JSON
+      pointer
+
+      @throw parse_error.106   if an array index begins with '0'
+      @throw parse_error.109   if an array index was not a number
+      @throw out_of_range.402  if the array index '-' is used
+      @throw out_of_range.404  if the JSON pointer can not be resolved
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    const NLOHMANN_BASIC_JSON_TPL& get_unchecked(const NLOHMANN_BASIC_JSON_TPL* ptr) const;
+
+    /*!
+      @throw parse_error.106   if an array index begins with '0'
+      @throw parse_error.109   if an array index was not a number
+      @throw out_of_range.402  if the array index '-' is used
+      @throw out_of_range.404  if the JSON pointer can not be resolved
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    const NLOHMANN_BASIC_JSON_TPL& get_checked(const NLOHMANN_BASIC_JSON_TPL* ptr) const;
+
+    /*!
+      @brief split the string input to reference tokens
+
+      @note This function is only called by the json_pointer constructor.
+      All exceptions below are documented there.
+
+      @throw parse_error.107  if the pointer is not empty or begins with '/'
+      @throw parse_error.108  if character '~' is not followed by '0' or '1'
+      */
+    static std::vector<std::string> split(const std::string& reference_string)
+    {
+        std::vector<std::string> result;
+
+        // special case: empty reference string -> no reference tokens
+        if (reference_string.empty())
+        {
+            return result;
+        }
+
+        // check if nonempty reference string begins with slash
+        if (reference_string[0] != '/')
+        {
+            JSON_THROW(detail::parse_error::create(
+                           107, 1,
+                           "JSON pointer must be empty or begin with '/' - was: '" +
+                           reference_string + "'"));
+        }
+
+        // extract the reference tokens:
+        // - slash: position of the last read slash (or end of string)
+        // - start: position after the previous slash
+        for (
+            // search for the first slash after the first character
+            size_t slash = reference_string.find_first_of('/', 1),
+            // set the beginning of the first reference token
+            start = 1;
+            // we can stop if start == string::npos+1 = 0
+            start != 0;
+            // set the beginning of the next reference token
+            // (will eventually be 0 if slash == std::string::npos)
+            start = slash + 1,
+            // find next slash
+            slash = reference_string.find_first_of('/', start))
+        {
+            // use the text between the beginning of the reference token
+            // (start) and the last slash (slash).
+            auto reference_token = reference_string.substr(start, slash - start);
+
+            // check reference tokens are properly escaped
+            for (size_t pos = reference_token.find_first_of('~');
+                    pos != std::string::npos;
+                    pos = reference_token.find_first_of('~', pos + 1))
+            {
+                assert(reference_token[pos] == '~');
+
+                // ~ must be followed by 0 or 1
+                if (pos == reference_token.size() - 1 or
+                        (reference_token[pos + 1] != '0' and
+                         reference_token[pos + 1] != '1'))
+                {
+                    JSON_THROW(detail::parse_error::create(
+                                   108, 0, "escape character '~' must be followed with '0' or '1'"));
+                }
+            }
+
+            // finally, store the reference token
+            unescape(reference_token);
+            result.push_back(reference_token);
+        }
+
+        return result;
+    }
+
+    /*!
+      @brief replace all occurrences of a substring by another string
+
+      @param[in,out] s  the string to manipulate; changed so that all
+      occurrences of @a f are replaced with @a t
+      @param[in]     f  the substring to replace with @a t
+      @param[in]     t  the string to replace @a f
+
+      @pre The search string @a f must not be empty. **This precondition is
+      enforced with an assertion.**
+
+      @since version 2.0.0
+      */
+    static void replace_substring(std::string& s, const std::string& f,
+                                  const std::string& t)
+    {
+        assert(not f.empty());
+
+        for (size_t pos = s.find(f);         // find first occurrence of f
+                pos != std::string::npos;       // make sure f was found
+                s.replace(pos, f.size(), t),    // replace with t
+                pos = s.find(f, pos + t.size()) // find next occurrence of f
+            )
+            ;
+    }
+
+    /// escape tilde and slash
+    static std::string escape(std::string s)
+    {
+        // escape "~"" to "~0" and "/" to "~1"
+        replace_substring(s, "~", "~0");
+        replace_substring(s, "/", "~1");
+        return s;
+    }
+
+    /// unescape tilde and slash
+    static void unescape(std::string& s)
+    {
+        // first transform any occurrence of the sequence '~1' to '/'
+        replace_substring(s, "~1", "/");
+        // then transform any occurrence of the sequence '~0' to '~'
+        replace_substring(s, "~0", "~");
+    }
+
+    /*!
+      @param[in] reference_string  the reference string to the current value
+      @param[in] value             the value to consider
+      @param[in,out] result        the result object to insert values to
+
+      @note Empty objects or arrays are flattened to `null`.
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    static void flatten(const std::string& reference_string,
+                        const NLOHMANN_BASIC_JSON_TPL& value,
+                        NLOHMANN_BASIC_JSON_TPL& result);
+
+    /*!
+      @param[in] value  flattened JSON
+
+      @return unflattened JSON
+
+      @throw parse_error.109 if array index is not a number
+      @throw type_error.314  if value is not an object
+      @throw type_error.315  if object values are not primitive
+      @throw type_error.313  if value cannot be unflattened
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    static NLOHMANN_BASIC_JSON_TPL
+    unflatten(const NLOHMANN_BASIC_JSON_TPL& value);
+
+    friend bool operator==(json_pointer const& lhs,
+                           json_pointer const& rhs) noexcept;
+
+    friend bool operator!=(json_pointer const& lhs,
+                           json_pointer const& rhs) noexcept;
+
+    /// the reference tokens
+    std::vector<std::string> reference_tokens;
+};
 
 /*!
 @brief a class to store JSON values
@@ -1409,13 +1737,14 @@ class basic_json
     template<detail::value_t> friend struct detail::external_constructor;
     /// workaround type for MSVC
     using basic_json_t = NLOHMANN_BASIC_JSON_TPL;
+    friend ::nlohmann::json_pointer;
 
   public:
     using value_t = detail::value_t;
     // forward declarations
     template<typename U> class iter_impl;
     template<typename Base> class json_reverse_iterator;
-    class json_pointer;
+    using json_pointer = ::nlohmann::json_pointer;
     template<typename T, typename SFINAE>
     using json_serializer = JSONSerializer<T, SFINAE>;
 
@@ -13031,803 +13360,124 @@ class basic_json
     };
 
   public:
+    //////////////////////////
+    // JSON Pointer support //
+    //////////////////////////
+
+    /// @name JSON Pointer functions
+    /// @{
+
     /*!
-    @brief JSON Pointer
+    @brief access specified element via JSON Pointer
+
+    Uses a JSON pointer to retrieve a reference to the respective JSON value.
+    No bound checking is performed. Similar to @ref operator[](const typename
+    object_t::key_type&), `null` values are created in arrays and objects if
+    necessary.
+
+    In particular:
+    - If the JSON pointer points to an object key that does not exist, it
+      is created an filled with a `null` value before a reference to it
+      is returned.
+    - If the JSON pointer points to an array index that does not exist, it
+      is created an filled with a `null` value before a reference to it
+      is returned. All indices between the current maximum and the given
+      index are also filled with `null`.
+    - The special value `-` is treated as a synonym for the index past the
+      end.
+
+    @param[in] ptr  a JSON pointer
+
+    @return reference to the element pointed to by @a ptr
+
+    @complexity Constant.
 
-    A JSON pointer defines a string syntax for identifying a specific value
-    within a JSON document. It can be used with functions `at` and
-    `operator[]`. Furthermore, JSON pointers are the base for JSON patches.
+    @throw parse_error.106   if an array index begins with '0'
+    @throw parse_error.109   if an array index was not a number
+    @throw out_of_range.404  if the JSON pointer can not be resolved
 
-    @sa [RFC 6901](https://tools.ietf.org/html/rfc6901)
+    @liveexample{The behavior is shown in the example.,operatorjson_pointer}
 
     @since version 2.0.0
     */
-    class json_pointer
+    reference operator[](const json_pointer& ptr)
     {
-        /// allow basic_json to access private members
-        friend class basic_json;
+        return ptr.get_unchecked(this);
+    }
 
-      public:
-        /*!
-        @brief create JSON pointer
+    /*!
+    @brief access specified element via JSON Pointer
 
-        Create a JSON pointer according to the syntax described in
-        [Section 3 of RFC6901](https://tools.ietf.org/html/rfc6901#section-3).
+    Uses a JSON pointer to retrieve a reference to the respective JSON value.
+    No bound checking is performed. The function does not change the JSON
+    value; no `null` values are created. In particular, the the special value
+    `-` yields an exception.
 
-        @param[in] s  string representing the JSON pointer; if omitted, the
-                      empty string is assumed which references the whole JSON
-                      value
+    @param[in] ptr  JSON pointer to the desired element
 
-        @throw parse_error.107 if the given JSON pointer @a s is nonempty and
-        does not begin with a slash (`/`); see example below
+    @return const reference to the element pointed to by @a ptr
 
-        @throw parse_error.108 if a tilde (`~`) in the given JSON pointer @a s
-        is not followed by `0` (representing `~`) or `1` (representing `/`);
-        see example below
+    @complexity Constant.
 
-        @liveexample{The example shows the construction several valid JSON
-        pointers as well as the exceptional behavior.,json_pointer}
+    @throw parse_error.106   if an array index begins with '0'
+    @throw parse_error.109   if an array index was not a number
+    @throw out_of_range.402  if the array index '-' is used
+    @throw out_of_range.404  if the JSON pointer can not be resolved
 
-        @since version 2.0.0
-        */
-        explicit json_pointer(const std::string& s = "")
-            : reference_tokens(split(s))
-        {}
+    @liveexample{The behavior is shown in the example.,operatorjson_pointer_const}
 
-        /*!
-        @brief return a string representation of the JSON pointer
+    @since version 2.0.0
+    */
+    const_reference operator[](const json_pointer& ptr) const
+    {
+        return ptr.get_unchecked(this);
+    }
 
-        @invariant For each JSON pointer `ptr`, it holds:
-        @code {.cpp}
-        ptr == json_pointer(ptr.to_string());
-        @endcode
+    /*!
+    @brief access specified element via JSON Pointer
 
-        @return a string representation of the JSON pointer
+    Returns a reference to the element at with specified JSON pointer @a ptr,
+    with bounds checking.
 
-        @liveexample{The example shows the result of `to_string`.,
-        json_pointer__to_string}
+    @param[in] ptr  JSON pointer to the desired element
 
-        @since version 2.0.0
-        */
-        std::string to_string() const noexcept
-        {
-            return std::accumulate(reference_tokens.begin(),
-                                   reference_tokens.end(), std::string{},
-                                   [](const std::string & a, const std::string & b)
-            {
-                return a + "/" + escape(b);
-            });
-        }
+    @return reference to the element pointed to by @a ptr
 
-        /// @copydoc to_string()
-        operator std::string() const
-        {
-            return to_string();
-        }
+    @throw parse_error.106 if an array index in the passed JSON pointer @a ptr
+    begins with '0'. See example below.
 
-      private:
-        /*!
-        @brief remove and return last reference pointer
-        @throw out_of_range.405 if JSON pointer has no parent
-        */
-        std::string pop_back()
-        {
-            if (is_root())
-            {
-                JSON_THROW(out_of_range::create(405, "JSON pointer has no parent"));
-            }
+    @throw parse_error.109 if an array index in the passed JSON pointer @a ptr
+    is not a number. See example below.
 
-            auto last = reference_tokens.back();
-            reference_tokens.pop_back();
-            return last;
-        }
+    @throw out_of_range.401 if an array index in the passed JSON pointer @a ptr
+    is out of range. See example below.
 
-        /// return whether pointer points to the root document
-        bool is_root() const
-        {
-            return reference_tokens.empty();
-        }
+    @throw out_of_range.402 if the array index '-' is used in the passed JSON
+    pointer @a ptr. As `at` provides checked access (and no elements are
+    implicitly inserted), the index '-' is always invalid. See example below.
 
-        json_pointer top() const
-        {
-            if (is_root())
-            {
-                JSON_THROW(out_of_range::create(405, "JSON pointer has no parent"));
-            }
+    @throw out_of_range.404 if the JSON pointer @a ptr can not be resolved.
+    See example below.
 
-            json_pointer result = *this;
-            result.reference_tokens = {reference_tokens[0]};
-            return result;
-        }
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
 
-        /*!
-        @brief create and return a reference to the pointed to value
+    @complexity Constant.
 
-        @complexity Linear in the number of reference tokens.
+    @since version 2.0.0
 
-        @throw parse_error.109 if array index is not a number
-        @throw type_error.313 if value cannot be unflattened
-        */
-        reference get_and_create(reference j) const
-        {
-            pointer result = &j;
+    @liveexample{The behavior is shown in the example.,at_json_pointer}
+    */
+    reference at(const json_pointer& ptr)
+    {
+        return ptr.get_checked(this);
+    }
 
-            // in case no reference tokens exist, return a reference to the
-            // JSON value j which will be overwritten by a primitive value
-            for (const auto& reference_token : reference_tokens)
-            {
-                switch (result->m_type)
-                {
-                    case value_t::null:
-                    {
-                        if (reference_token == "0")
-                        {
-                            // start a new array if reference token is 0
-                            result = &result->operator[](0);
-                        }
-                        else
-                        {
-                            // start a new object otherwise
-                            result = &result->operator[](reference_token);
-                        }
-                        break;
-                    }
+    /*!
+    @brief access specified element via JSON Pointer
 
-                    case value_t::object:
-                    {
-                        // create an entry in the object
-                        result = &result->operator[](reference_token);
-                        break;
-                    }
-
-                    case value_t::array:
-                    {
-                        // create an entry in the array
-                        JSON_TRY
-                        {
-                            result = &result->operator[](static_cast<size_type>(std::stoi(reference_token)));
-                        }
-                        JSON_CATCH (std::invalid_argument&)
-                        {
-                            JSON_THROW(parse_error::create(109, 0, "array index '" + reference_token + "' is not a number"));
-                        }
-                        break;
-                    }
-
-                    /*
-                    The following code is only reached if there exists a
-                    reference token _and_ the current value is primitive. In
-                    this case, we have an error situation, because primitive
-                    values may only occur as single value; that is, with an
-                    empty list of reference tokens.
-                    */
-                    default:
-                    {
-                        JSON_THROW(type_error::create(313, "invalid value to unflatten"));
-                    }
-                }
-            }
-
-            return *result;
-        }
-
-        /*!
-        @brief return a reference to the pointed to value
-
-        @note This version does not throw if a value is not present, but tries
-        to create nested values instead. For instance, calling this function
-        with pointer `"/this/that"` on a null value is equivalent to calling
-        `operator[]("this").operator[]("that")` on that value, effectively
-        changing the null value to an object.
-
-        @param[in] ptr  a JSON value
-
-        @return reference to the JSON value pointed to by the JSON pointer
-
-        @complexity Linear in the length of the JSON pointer.
-
-        @throw parse_error.106   if an array index begins with '0'
-        @throw parse_error.109   if an array index was not a number
-        @throw out_of_range.404  if the JSON pointer can not be resolved
-        */
-        reference get_unchecked(pointer ptr) const
-        {
-            for (const auto& reference_token : reference_tokens)
-            {
-                // convert null values to arrays or objects before continuing
-                if (ptr->m_type == value_t::null)
-                {
-                    // check if reference token is a number
-                    const bool nums = std::all_of(reference_token.begin(),
-                                                  reference_token.end(),
-                                                  [](const char x)
-                    {
-                        return (x >= '0' and x <= '9');
-                    });
-
-                    // change value to array for numbers or "-" or to object
-                    // otherwise
-                    if (nums or reference_token == "-")
-                    {
-                        *ptr = value_t::array;
-                    }
-                    else
-                    {
-                        *ptr = value_t::object;
-                    }
-                }
-
-                switch (ptr->m_type)
-                {
-                    case value_t::object:
-                    {
-                        // use unchecked object access
-                        ptr = &ptr->operator[](reference_token);
-                        break;
-                    }
-
-                    case value_t::array:
-                    {
-                        // error condition (cf. RFC 6901, Sect. 4)
-                        if (reference_token.size() > 1 and reference_token[0] == '0')
-                        {
-                            JSON_THROW(parse_error::create(106, 0, "array index '" + reference_token + "' must not begin with '0'"));
-                        }
-
-                        if (reference_token == "-")
-                        {
-                            // explicitly treat "-" as index beyond the end
-                            ptr = &ptr->operator[](ptr->m_value.array->size());
-                        }
-                        else
-                        {
-                            // convert array index to number; unchecked access
-                            JSON_TRY
-                            {
-                                ptr = &ptr->operator[](static_cast<size_type>(std::stoi(reference_token)));
-                            }
-                            JSON_CATCH (std::invalid_argument&)
-                            {
-                                JSON_THROW(parse_error::create(109, 0, "array index '" + reference_token + "' is not a number"));
-                            }
-                        }
-                        break;
-                    }
-
-                    default:
-                    {
-                        JSON_THROW(out_of_range::create(404, "unresolved reference token '" + reference_token + "'"));
-                    }
-                }
-            }
-
-            return *ptr;
-        }
-
-        /*!
-        @throw parse_error.106   if an array index begins with '0'
-        @throw parse_error.109   if an array index was not a number
-        @throw out_of_range.402  if the array index '-' is used
-        @throw out_of_range.404  if the JSON pointer can not be resolved
-        */
-        reference get_checked(pointer ptr) const
-        {
-            for (const auto& reference_token : reference_tokens)
-            {
-                switch (ptr->m_type)
-                {
-                    case value_t::object:
-                    {
-                        // note: at performs range check
-                        ptr = &ptr->at(reference_token);
-                        break;
-                    }
-
-                    case value_t::array:
-                    {
-                        if (reference_token == "-")
-                        {
-                            // "-" always fails the range check
-                            JSON_THROW(out_of_range::create(402, "array index '-' (" +
-                                                            std::to_string(ptr->m_value.array->size()) +
-                                                            ") is out of range"));
-                        }
-
-                        // error condition (cf. RFC 6901, Sect. 4)
-                        if (reference_token.size() > 1 and reference_token[0] == '0')
-                        {
-                            JSON_THROW(parse_error::create(106, 0, "array index '" + reference_token + "' must not begin with '0'"));
-                        }
-
-                        // note: at performs range check
-                        JSON_TRY
-                        {
-                            ptr = &ptr->at(static_cast<size_type>(std::stoi(reference_token)));
-                        }
-                        JSON_CATCH (std::invalid_argument&)
-                        {
-                            JSON_THROW(parse_error::create(109, 0, "array index '" + reference_token + "' is not a number"));
-                        }
-                        break;
-                    }
-
-                    default:
-                    {
-                        JSON_THROW(out_of_range::create(404, "unresolved reference token '" + reference_token + "'"));
-                    }
-                }
-            }
-
-            return *ptr;
-        }
-
-        /*!
-        @brief return a const reference to the pointed to value
-
-        @param[in] ptr  a JSON value
-
-        @return const reference to the JSON value pointed to by the JSON
-                pointer
-
-        @throw parse_error.106   if an array index begins with '0'
-        @throw parse_error.109   if an array index was not a number
-        @throw out_of_range.402  if the array index '-' is used
-        @throw out_of_range.404  if the JSON pointer can not be resolved
-        */
-        const_reference get_unchecked(const_pointer ptr) const
-        {
-            for (const auto& reference_token : reference_tokens)
-            {
-                switch (ptr->m_type)
-                {
-                    case value_t::object:
-                    {
-                        // use unchecked object access
-                        ptr = &ptr->operator[](reference_token);
-                        break;
-                    }
-
-                    case value_t::array:
-                    {
-                        if (reference_token == "-")
-                        {
-                            // "-" cannot be used for const access
-                            JSON_THROW(out_of_range::create(402, "array index '-' (" +
-                                                            std::to_string(ptr->m_value.array->size()) +
-                                                            ") is out of range"));
-                        }
-
-                        // error condition (cf. RFC 6901, Sect. 4)
-                        if (reference_token.size() > 1 and reference_token[0] == '0')
-                        {
-                            JSON_THROW(parse_error::create(106, 0, "array index '" + reference_token + "' must not begin with '0'"));
-                        }
-
-                        // use unchecked array access
-                        JSON_TRY
-                        {
-                            ptr = &ptr->operator[](static_cast<size_type>(std::stoi(reference_token)));
-                        }
-                        JSON_CATCH (std::invalid_argument&)
-                        {
-                            JSON_THROW(parse_error::create(109, 0, "array index '" + reference_token + "' is not a number"));
-                        }
-                        break;
-                    }
-
-                    default:
-                    {
-                        JSON_THROW(out_of_range::create(404, "unresolved reference token '" + reference_token + "'"));
-                    }
-                }
-            }
-
-            return *ptr;
-        }
-
-        /*!
-        @throw parse_error.106   if an array index begins with '0'
-        @throw parse_error.109   if an array index was not a number
-        @throw out_of_range.402  if the array index '-' is used
-        @throw out_of_range.404  if the JSON pointer can not be resolved
-        */
-        const_reference get_checked(const_pointer ptr) const
-        {
-            for (const auto& reference_token : reference_tokens)
-            {
-                switch (ptr->m_type)
-                {
-                    case value_t::object:
-                    {
-                        // note: at performs range check
-                        ptr = &ptr->at(reference_token);
-                        break;
-                    }
-
-                    case value_t::array:
-                    {
-                        if (reference_token == "-")
-                        {
-                            // "-" always fails the range check
-                            JSON_THROW(out_of_range::create(402, "array index '-' (" +
-                                                            std::to_string(ptr->m_value.array->size()) +
-                                                            ") is out of range"));
-                        }
-
-                        // error condition (cf. RFC 6901, Sect. 4)
-                        if (reference_token.size() > 1 and reference_token[0] == '0')
-                        {
-                            JSON_THROW(parse_error::create(106, 0, "array index '" + reference_token + "' must not begin with '0'"));
-                        }
-
-                        // note: at performs range check
-                        JSON_TRY
-                        {
-                            ptr = &ptr->at(static_cast<size_type>(std::stoi(reference_token)));
-                        }
-                        JSON_CATCH (std::invalid_argument&)
-                        {
-                            JSON_THROW(parse_error::create(109, 0, "array index '" + reference_token + "' is not a number"));
-                        }
-                        break;
-                    }
-
-                    default:
-                    {
-                        JSON_THROW(out_of_range::create(404, "unresolved reference token '" + reference_token + "'"));
-                    }
-                }
-            }
-
-            return *ptr;
-        }
-
-        /*!
-        @brief split the string input to reference tokens
-
-        @note This function is only called by the json_pointer constructor.
-              All exceptions below are documented there.
-
-        @throw parse_error.107  if the pointer is not empty or begins with '/'
-        @throw parse_error.108  if character '~' is not followed by '0' or '1'
-        */
-        static std::vector<std::string> split(const std::string& reference_string)
-        {
-            std::vector<std::string> result;
-
-            // special case: empty reference string -> no reference tokens
-            if (reference_string.empty())
-            {
-                return result;
-            }
-
-            // check if nonempty reference string begins with slash
-            if (reference_string[0] != '/')
-            {
-                JSON_THROW(parse_error::create(107, 1, "JSON pointer must be empty or begin with '/' - was: '" + reference_string + "'"));
-            }
-
-            // extract the reference tokens:
-            // - slash: position of the last read slash (or end of string)
-            // - start: position after the previous slash
-            for (
-                // search for the first slash after the first character
-                size_t slash = reference_string.find_first_of('/', 1),
-                // set the beginning of the first reference token
-                start = 1;
-                // we can stop if start == string::npos+1 = 0
-                start != 0;
-                // set the beginning of the next reference token
-                // (will eventually be 0 if slash == std::string::npos)
-                start = slash + 1,
-                // find next slash
-                slash = reference_string.find_first_of('/', start))
-            {
-                // use the text between the beginning of the reference token
-                // (start) and the last slash (slash).
-                auto reference_token = reference_string.substr(start, slash - start);
-
-                // check reference tokens are properly escaped
-                for (size_t pos = reference_token.find_first_of('~');
-                        pos != std::string::npos;
-                        pos = reference_token.find_first_of('~', pos + 1))
-                {
-                    assert(reference_token[pos] == '~');
-
-                    // ~ must be followed by 0 or 1
-                    if (pos == reference_token.size() - 1 or
-                            (reference_token[pos + 1] != '0' and
-                             reference_token[pos + 1] != '1'))
-                    {
-                        JSON_THROW(parse_error::create(108, 0, "escape character '~' must be followed with '0' or '1'"));
-                    }
-                }
-
-                // finally, store the reference token
-                unescape(reference_token);
-                result.push_back(reference_token);
-            }
-
-            return result;
-        }
-
-        /*!
-        @brief replace all occurrences of a substring by another string
-
-        @param[in,out] s  the string to manipulate; changed so that all
-                          occurrences of @a f are replaced with @a t
-        @param[in]     f  the substring to replace with @a t
-        @param[in]     t  the string to replace @a f
-
-        @pre The search string @a f must not be empty. **This precondition is
-             enforced with an assertion.**
-
-        @since version 2.0.0
-        */
-        static void replace_substring(std::string& s,
-                                      const std::string& f,
-                                      const std::string& t)
-        {
-            assert(not f.empty());
-
-            for (
-                size_t pos = s.find(f);         // find first occurrence of f
-                pos != std::string::npos;       // make sure f was found
-                s.replace(pos, f.size(), t),    // replace with t
-                pos = s.find(f, pos + t.size()) // find next occurrence of f
-            );
-        }
-
-        /// escape tilde and slash
-        static std::string escape(std::string s)
-        {
-            // escape "~"" to "~0" and "/" to "~1"
-            replace_substring(s, "~", "~0");
-            replace_substring(s, "/", "~1");
-            return s;
-        }
-
-        /// unescape tilde and slash
-        static void unescape(std::string& s)
-        {
-            // first transform any occurrence of the sequence '~1' to '/'
-            replace_substring(s, "~1", "/");
-            // then transform any occurrence of the sequence '~0' to '~'
-            replace_substring(s, "~0", "~");
-        }
-
-        /*!
-        @param[in] reference_string  the reference string to the current value
-        @param[in] value             the value to consider
-        @param[in,out] result        the result object to insert values to
-
-        @note Empty objects or arrays are flattened to `null`.
-        */
-        static void flatten(const std::string& reference_string,
-                            const basic_json& value,
-                            basic_json& result)
-        {
-            switch (value.m_type)
-            {
-                case value_t::array:
-                {
-                    if (value.m_value.array->empty())
-                    {
-                        // flatten empty array as null
-                        result[reference_string] = nullptr;
-                    }
-                    else
-                    {
-                        // iterate array and use index as reference string
-                        for (size_t i = 0; i < value.m_value.array->size(); ++i)
-                        {
-                            flatten(reference_string + "/" + std::to_string(i),
-                                    value.m_value.array->operator[](i), result);
-                        }
-                    }
-                    break;
-                }
-
-                case value_t::object:
-                {
-                    if (value.m_value.object->empty())
-                    {
-                        // flatten empty object as null
-                        result[reference_string] = nullptr;
-                    }
-                    else
-                    {
-                        // iterate object and use keys as reference string
-                        for (const auto& element : *value.m_value.object)
-                        {
-                            flatten(reference_string + "/" + escape(element.first),
-                                    element.second, result);
-                        }
-                    }
-                    break;
-                }
-
-                default:
-                {
-                    // add primitive value with its reference string
-                    result[reference_string] = value;
-                    break;
-                }
-            }
-        }
-
-        /*!
-        @param[in] value  flattened JSON
-
-        @return unflattened JSON
-
-        @throw parse_error.109 if array index is not a number
-        @throw type_error.314  if value is not an object
-        @throw type_error.315  if object values are not primitive
-        @throw type_error.313  if value cannot be unflattened
-        */
-        static basic_json unflatten(const basic_json& value)
-        {
-            if (not value.is_object())
-            {
-                JSON_THROW(type_error::create(314, "only objects can be unflattened"));
-            }
-
-            basic_json result;
-
-            // iterate the JSON object values
-            for (const auto& element : *value.m_value.object)
-            {
-                if (not element.second.is_primitive())
-                {
-                    JSON_THROW(type_error::create(315, "values in object must be primitive"));
-                }
-
-                // assign value to reference pointed to by JSON pointer; Note
-                // that if the JSON pointer is "" (i.e., points to the whole
-                // value), function get_and_create returns a reference to
-                // result itself. An assignment will then create a primitive
-                // value.
-                json_pointer(element.first).get_and_create(result) = element.second;
-            }
-
-            return result;
-        }
-
-        friend bool operator==(json_pointer const& lhs,
-                               json_pointer const& rhs) noexcept
-        {
-            return lhs.reference_tokens == rhs.reference_tokens;
-        }
-
-        friend bool operator!=(json_pointer const& lhs,
-                               json_pointer const& rhs) noexcept
-        {
-            return !(lhs == rhs);
-        }
-
-        /// the reference tokens
-        std::vector<std::string> reference_tokens {};
-    };
-
-    //////////////////////////
-    // JSON Pointer support //
-    //////////////////////////
-
-    /// @name JSON Pointer functions
-    /// @{
-
-    /*!
-    @brief access specified element via JSON Pointer
-
-    Uses a JSON pointer to retrieve a reference to the respective JSON value.
-    No bound checking is performed. Similar to @ref operator[](const typename
-    object_t::key_type&), `null` values are created in arrays and objects if
-    necessary.
-
-    In particular:
-    - If the JSON pointer points to an object key that does not exist, it
-      is created an filled with a `null` value before a reference to it
-      is returned.
-    - If the JSON pointer points to an array index that does not exist, it
-      is created an filled with a `null` value before a reference to it
-      is returned. All indices between the current maximum and the given
-      index are also filled with `null`.
-    - The special value `-` is treated as a synonym for the index past the
-      end.
-
-    @param[in] ptr  a JSON pointer
-
-    @return reference to the element pointed to by @a ptr
-
-    @complexity Constant.
-
-    @throw parse_error.106   if an array index begins with '0'
-    @throw parse_error.109   if an array index was not a number
-    @throw out_of_range.404  if the JSON pointer can not be resolved
-
-    @liveexample{The behavior is shown in the example.,operatorjson_pointer}
-
-    @since version 2.0.0
-    */
-    reference operator[](const json_pointer& ptr)
-    {
-        return ptr.get_unchecked(this);
-    }
-
-    /*!
-    @brief access specified element via JSON Pointer
-
-    Uses a JSON pointer to retrieve a reference to the respective JSON value.
-    No bound checking is performed. The function does not change the JSON
-    value; no `null` values are created. In particular, the the special value
-    `-` yields an exception.
-
-    @param[in] ptr  JSON pointer to the desired element
-
-    @return const reference to the element pointed to by @a ptr
-
-    @complexity Constant.
-
-    @throw parse_error.106   if an array index begins with '0'
-    @throw parse_error.109   if an array index was not a number
-    @throw out_of_range.402  if the array index '-' is used
-    @throw out_of_range.404  if the JSON pointer can not be resolved
-
-    @liveexample{The behavior is shown in the example.,operatorjson_pointer_const}
-
-    @since version 2.0.0
-    */
-    const_reference operator[](const json_pointer& ptr) const
-    {
-        return ptr.get_unchecked(this);
-    }
-
-    /*!
-    @brief access specified element via JSON Pointer
-
-    Returns a reference to the element at with specified JSON pointer @a ptr,
-    with bounds checking.
-
-    @param[in] ptr  JSON pointer to the desired element
-
-    @return reference to the element pointed to by @a ptr
-
-    @throw parse_error.106 if an array index in the passed JSON pointer @a ptr
-    begins with '0'. See example below.
-
-    @throw parse_error.109 if an array index in the passed JSON pointer @a ptr
-    is not a number. See example below.
-
-    @throw out_of_range.401 if an array index in the passed JSON pointer @a ptr
-    is out of range. See example below.
-
-    @throw out_of_range.402 if the array index '-' is used in the passed JSON
-    pointer @a ptr. As `at` provides checked access (and no elements are
-    implicitly inserted), the index '-' is always invalid. See example below.
-
-    @throw out_of_range.404 if the JSON pointer @a ptr can not be resolved.
-    See example below.
-
-    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
-    changes in the JSON value.
-
-    @complexity Constant.
-
-    @since version 2.0.0
-
-    @liveexample{The behavior is shown in the example.,at_json_pointer}
-    */
-    reference at(const json_pointer& ptr)
-    {
-        return ptr.get_checked(this);
-    }
-
-    /*!
-    @brief access specified element via JSON Pointer
-
-    Returns a const reference to the element at with specified JSON pointer @a
-    ptr, with bounds checking.
+    Returns a const reference to the element at with specified JSON pointer @a
+    ptr, with bounds checking.
 
     @param[in] ptr  JSON pointer to the desired element
 
@@ -14423,6 +14073,432 @@ uses the standard template types.
 @since version 1.0.0
 */
 using json = basic_json<>;
+
+//////////////////
+// json_pointer //
+//////////////////
+
+NLOHMANN_BASIC_JSON_TPL_DECLARATION
+NLOHMANN_BASIC_JSON_TPL&
+json_pointer::get_and_create(NLOHMANN_BASIC_JSON_TPL& j) const
+{
+    using size_type = typename NLOHMANN_BASIC_JSON_TPL::size_type;
+    auto result = &j;
+
+    // in case no reference tokens exist, return a reference to the
+    // JSON value j which will be overwritten by a primitive value
+    for (const auto& reference_token : reference_tokens)
+    {
+        switch (result->m_type)
+        {
+            case detail::value_t::null:
+            {
+                if (reference_token == "0")
+                {
+                    // start a new array if reference token is 0
+                    result = &result->operator[](0);
+                }
+                else
+                {
+                    // start a new object otherwise
+                    result = &result->operator[](reference_token);
+                }
+                break;
+            }
+
+            case detail::value_t::object:
+            {
+                // create an entry in the object
+                result = &result->operator[](reference_token);
+                break;
+            }
+
+            case detail::value_t::array:
+            {
+                // create an entry in the array
+                JSON_TRY
+                {
+                    result = &result->operator[](
+                        static_cast<size_type>(std::stoi(reference_token)));
+                }
+                JSON_CATCH(std::invalid_argument&)
+                {
+                    JSON_THROW(detail::parse_error::create(
+                                   109, 0, "array index '" + reference_token + "' is not a number"));
+                }
+                break;
+            }
+
+            /*
+            The following code is only reached if there exists a
+            reference token _and_ the current value is primitive. In
+            this case, we have an error situation, because primitive
+            values may only occur as single value; that is, with an
+            empty list of reference tokens.
+            */
+            default:
+            {
+                JSON_THROW(detail::type_error::create(313, "invalid value to unflatten"));
+            }
+        }
+    }
+
+    return *result;
+}
+
+NLOHMANN_BASIC_JSON_TPL_DECLARATION
+NLOHMANN_BASIC_JSON_TPL&
+json_pointer::get_unchecked(NLOHMANN_BASIC_JSON_TPL* ptr) const
+{
+    using size_type = typename NLOHMANN_BASIC_JSON_TPL::size_type;
+    for (const auto& reference_token : reference_tokens)
+    {
+        // convert null values to arrays or objects before continuing
+        if (ptr->m_type == detail::value_t::null)
+        {
+            // check if reference token is a number
+            const bool nums =
+                std::all_of(reference_token.begin(), reference_token.end(),
+                            [](const char x)
+            {
+                return (x >= '0' and x <= '9');
+            });
+
+            // change value to array for numbers or "-" or to object
+            // otherwise
+            if (nums or reference_token == "-")
+            {
+                *ptr = detail::value_t::array;
+            }
+            else
+            {
+                *ptr = detail::value_t::object;
+            }
+        }
+
+        switch (ptr->m_type)
+        {
+            case detail::value_t::object:
+            {
+                // use unchecked object access
+                ptr = &ptr->operator[](reference_token);
+                break;
+            }
+
+            case detail::value_t::array:
+            {
+                // error condition (cf. RFC 6901, Sect. 4)
+                if (reference_token.size() > 1 and reference_token[0] == '0')
+                {
+                    JSON_THROW(detail::parse_error::create(106, 0,
+                                                           "array index '" + reference_token +
+                                                           "' must not begin with '0'"));
+                }
+
+                if (reference_token == "-")
+                {
+                    // explicitly treat "-" as index beyond the end
+                    ptr = &ptr->operator[](ptr->m_value.array->size());
+                }
+                else
+                {
+                    // convert array index to number; unchecked access
+                    JSON_TRY
+                    {
+                        ptr = &ptr->operator[](
+                            static_cast<size_type>(std::stoi(reference_token)));
+                    }
+                    JSON_CATCH(std::invalid_argument&)
+                    {
+                        JSON_THROW(detail::parse_error::create(
+                                       109, 0, "array index '" + reference_token + "' is not a number"));
+                    }
+                }
+                break;
+            }
+
+            default:
+            {
+                JSON_THROW(detail::out_of_range::create(
+                               404, "unresolved reference token '" + reference_token + "'"));
+            }
+        }
+    }
+
+    return *ptr;
+}
+
+NLOHMANN_BASIC_JSON_TPL_DECLARATION
+NLOHMANN_BASIC_JSON_TPL&
+json_pointer::get_checked(NLOHMANN_BASIC_JSON_TPL* ptr) const
+{
+    using size_type = typename NLOHMANN_BASIC_JSON_TPL::size_type;
+    for (const auto& reference_token : reference_tokens)
+    {
+        switch (ptr->m_type)
+        {
+            case detail::value_t::object:
+            {
+                // note: at performs range check
+                ptr = &ptr->at(reference_token);
+                break;
+            }
+
+            case detail::value_t::array:
+            {
+                if (reference_token == "-")
+                {
+                    // "-" always fails the range check
+                    JSON_THROW(detail::out_of_range::create(
+                                   402,
+                                   "array index '-' (" + std::to_string(ptr->m_value.array->size()) +
+                                   ") is out of range"));
+                }
+
+                // error condition (cf. RFC 6901, Sect. 4)
+                if (reference_token.size() > 1 and reference_token[0] == '0')
+                {
+                    JSON_THROW(detail::parse_error::create(106, 0,
+                                                           "array index '" + reference_token +
+                                                           "' must not begin with '0'"));
+                }
+
+                // note: at performs range check
+                JSON_TRY
+                {
+                    ptr = &ptr->at(static_cast<size_type>(std::stoi(reference_token)));
+                }
+                JSON_CATCH(std::invalid_argument&)
+                {
+                    JSON_THROW(detail::parse_error::create(
+                                   109, 0, "array index '" + reference_token + "' is not a number"));
+                }
+                break;
+            }
+
+            default:
+            {
+                JSON_THROW(detail::out_of_range::create(
+                               404, "unresolved reference token '" + reference_token + "'"));
+            }
+        }
+    }
+
+    return *ptr;
+}
+
+NLOHMANN_BASIC_JSON_TPL_DECLARATION
+const NLOHMANN_BASIC_JSON_TPL&
+json_pointer::get_unchecked(const NLOHMANN_BASIC_JSON_TPL* ptr) const
+{
+    using size_type = typename NLOHMANN_BASIC_JSON_TPL::size_type;
+    for (const auto& reference_token : reference_tokens)
+    {
+        switch (ptr->m_type)
+        {
+            case detail::value_t::object:
+            {
+                // use unchecked object access
+                ptr = &ptr->operator[](reference_token);
+                break;
+            }
+
+            case detail::value_t::array:
+            {
+                if (reference_token == "-")
+                {
+                    // "-" cannot be used for const access
+                    JSON_THROW(detail::out_of_range::create(
+                                   402,
+                                   "array index '-' (" + std::to_string(ptr->m_value.array->size()) +
+                                   ") is out of range"));
+                }
+
+                // error condition (cf. RFC 6901, Sect. 4)
+                if (reference_token.size() > 1 and reference_token[0] == '0')
+                {
+                    JSON_THROW(detail::parse_error::create(106, 0,
+                                                           "array index '" + reference_token +
+                                                           "' must not begin with '0'"));
+                }
+
+                // use unchecked array access
+                JSON_TRY
+                {
+                    ptr = &ptr->operator[](
+                        static_cast<size_type>(std::stoi(reference_token)));
+                }
+                JSON_CATCH(std::invalid_argument&)
+                {
+                    JSON_THROW(detail::parse_error::create(
+                                   109, 0, "array index '" + reference_token + "' is not a number"));
+                }
+                break;
+            }
+
+            default:
+            {
+                JSON_THROW(detail::out_of_range::create(
+                               404, "unresolved reference token '" + reference_token + "'"));
+            }
+        }
+    }
+
+    return *ptr;
+}
+
+NLOHMANN_BASIC_JSON_TPL_DECLARATION
+const NLOHMANN_BASIC_JSON_TPL&
+json_pointer::get_checked(const NLOHMANN_BASIC_JSON_TPL* ptr) const
+{
+    using size_type = typename NLOHMANN_BASIC_JSON_TPL::size_type;
+    for (const auto& reference_token : reference_tokens)
+    {
+        switch (ptr->m_type)
+        {
+            case detail::value_t::object:
+            {
+                // note: at performs range check
+                ptr = &ptr->at(reference_token);
+                break;
+            }
+
+            case detail::value_t::array:
+            {
+                if (reference_token == "-")
+                {
+                    // "-" always fails the range check
+                    JSON_THROW(detail::out_of_range::create(
+                                   402,
+                                   "array index '-' (" + std::to_string(ptr->m_value.array->size()) +
+                                   ") is out of range"));
+                }
+
+                // error condition (cf. RFC 6901, Sect. 4)
+                if (reference_token.size() > 1 and reference_token[0] == '0')
+                {
+                    JSON_THROW(detail::parse_error::create(106, 0,
+                                                           "array index '" + reference_token +
+                                                           "' must not begin with '0'"));
+                }
+
+                // note: at performs range check
+                JSON_TRY
+                {
+                    ptr = &ptr->at(static_cast<size_type>(std::stoi(reference_token)));
+                }
+                JSON_CATCH(std::invalid_argument&)
+                {
+                    JSON_THROW(detail::parse_error::create(
+                                   109, 0, "array index '" + reference_token + "' is not a number"));
+                }
+                break;
+            }
+
+            default:
+            {
+                JSON_THROW(detail::out_of_range::create(
+                               404, "unresolved reference token '" + reference_token + "'"));
+            }
+        }
+    }
+
+    return *ptr;
+}
+
+NLOHMANN_BASIC_JSON_TPL_DECLARATION
+void json_pointer::flatten(const std::string& reference_string,
+                           const NLOHMANN_BASIC_JSON_TPL& value,
+                           NLOHMANN_BASIC_JSON_TPL& result)
+{
+    switch (value.m_type)
+    {
+        case detail::value_t::array:
+        {
+            if (value.m_value.array->empty())
+            {
+                // flatten empty array as null
+                result[reference_string] = nullptr;
+            }
+            else
+            {
+                // iterate array and use index as reference string
+                for (size_t i = 0; i < value.m_value.array->size(); ++i)
+                {
+                    flatten(reference_string + "/" + std::to_string(i),
+                            value.m_value.array->operator[](i), result);
+                }
+            }
+            break;
+        }
+
+        case detail::value_t::object:
+        {
+            if (value.m_value.object->empty())
+            {
+                // flatten empty object as null
+                result[reference_string] = nullptr;
+            }
+            else
+            {
+                // iterate object and use keys as reference string
+                for (const auto& element : *value.m_value.object)
+                {
+                    flatten(reference_string + "/" + escape(element.first), element.second,
+                            result);
+                }
+            }
+            break;
+        }
+
+        default:
+        {
+            // add primitive value with its reference string
+            result[reference_string] = value;
+            break;
+        }
+    }
+}
+
+NLOHMANN_BASIC_JSON_TPL_DECLARATION
+NLOHMANN_BASIC_JSON_TPL
+json_pointer::unflatten(const NLOHMANN_BASIC_JSON_TPL& value)
+{
+    if (not value.is_object())
+    {
+        JSON_THROW(detail::type_error::create(314, "only objects can be unflattened"));
+    }
+
+    NLOHMANN_BASIC_JSON_TPL result;
+
+    // iterate the JSON object values
+    for (const auto& element : *value.m_value.object)
+    {
+        if (not element.second.is_primitive())
+        {
+            JSON_THROW(detail::type_error::create(315, "values in object must be primitive"));
+        }
+
+        // assign value to reference pointed to by JSON pointer; Note
+        // that if the JSON pointer is "" (i.e., points to the whole
+        // value), function get_and_create returns a reference to
+        // result itself. An assignment will then create a primitive
+        // value.
+        json_pointer(element.first).get_and_create(result) = element.second;
+    }
+
+    return result;
+}
+
+inline bool operator==(json_pointer const& lhs, json_pointer const& rhs) noexcept
+{
+    return lhs.reference_tokens == rhs.reference_tokens;
+}
+
+inline bool operator!=(json_pointer const& lhs, json_pointer const& rhs) noexcept
+{
+    return !(lhs == rhs);
+}
 } // namespace nlohmann
 
 

From 15625ca4a753144e01f2a0345687bc4859eff97f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9o=20DELRIEU?= <delrieutheo@gmail.com>
Date: Sat, 1 Jul 2017 20:01:28 +0200
Subject: [PATCH 3/9] move input adapters outside of basic_json

---
 src/json.hpp                   | 556 ++++++++++----------
 test/src/unit-class_lexer.cpp  |   2 +-
 test/src/unit-class_parser.cpp | 934 ++++++++++++++++-----------------
 3 files changed, 749 insertions(+), 743 deletions(-)

diff --git a/src/json.hpp b/src/json.hpp
index 2df26ae0a0..fd63fe132b 100644
--- a/src/json.hpp
+++ b/src/json.hpp
@@ -1265,6 +1265,270 @@ struct static_const
 
 template<typename T>
 constexpr T static_const<T>::value;
+
+////////////////////
+// input adapters //
+////////////////////
+
+/// abstract input adapter interface
+struct input_adapter
+{
+    virtual int get_character() = 0;
+    virtual std::string read(size_t offset, size_t length) = 0;
+    virtual ~input_adapter() {}
+};
+
+/// a type to simplify interfaces
+using input_adapter_t = std::shared_ptr<input_adapter>;
+
+/// input adapter for cached stream input
+template<std::size_t N>
+class cached_input_stream_adapter : public input_adapter
+{
+  public:
+    cached_input_stream_adapter(std::istream& i)
+        : is(i), start_position(is.tellg())
+    {
+        fill_buffer();
+
+        // skip byte order mark
+        if (fill_size >= 3 and buffer[0] == '\xEF' and buffer[1] == '\xBB' and buffer[2] == '\xBF')
+        {
+            buffer_pos += 3;
+            processed_chars += 3;
+        }
+    }
+
+    ~cached_input_stream_adapter() override
+    {
+        // clear stream flags
+        is.clear();
+        // We initially read a lot of characters into the buffer, and we
+        // may not have processed all of them. Therefore, we need to
+        // "rewind" the stream after the last processed char.
+        is.seekg(start_position);
+        is.ignore(static_cast<std::streamsize>(processed_chars));
+        // clear stream flags
+        is.clear();
+    }
+
+    int get_character() override
+    {
+        // check if refilling is necessary and possible
+        if (buffer_pos == fill_size and not eof)
+        {
+            fill_buffer();
+
+            // check and remember that filling did not yield new input
+            if (fill_size == 0)
+            {
+                eof = true;
+                return std::char_traits<char>::eof();
+            }
+
+            // the buffer is ready
+            buffer_pos = 0;
+        }
+
+        ++processed_chars;
+        assert(buffer_pos < buffer.size());
+        return buffer[buffer_pos++] & 0xFF;
+    }
+
+    std::string read(size_t offset, size_t length) override
+    {
+        // create buffer
+        std::string result(length, '\0');
+
+        // save stream position
+        const auto current_pos = is.tellg();
+        // save stream flags
+        const auto flags = is.rdstate();
+
+        // clear stream flags
+        is.clear();
+        // set stream position
+        is.seekg(static_cast<std::streamoff>(offset));
+        // read bytes
+        is.read(&result[0], static_cast<std::streamsize>(length));
+
+        // reset stream position
+        is.seekg(current_pos);
+        // reset stream flags
+        is.setstate(flags);
+
+        return result;
+    }
+
+  private:
+    void fill_buffer()
+    {
+        // fill
+        is.read(buffer.data(), static_cast<std::streamsize>(buffer.size()));
+        // store number of bytes in the buffer
+        fill_size = static_cast<size_t>(is.gcount());
+    }
+
+    /// the associated input stream
+    std::istream& is;
+
+    /// chars returned via get_character()
+    size_t processed_chars = 0;
+    /// chars processed in the current buffer
+    size_t buffer_pos = 0;
+
+    /// whether stream reached eof
+    bool eof = false;
+    /// how many chars have been copied to the buffer by last (re)fill
+    size_t fill_size = 0;
+
+    /// position of the stream when we started
+    const std::streampos start_position;
+
+    /// internal buffer
+    std::array<char, N> buffer{{}};
+};
+
+/// input adapter for buffer input
+class input_buffer_adapter : public input_adapter
+{
+  public:
+    input_buffer_adapter(const char* b, size_t l)
+        : input_adapter(), cursor(b), limit(b + l), start(b)
+    {
+        // skip byte order mark
+        if (l >= 3 and b[0] == '\xEF' and b[1] == '\xBB' and b[2] == '\xBF')
+        {
+            cursor += 3;
+        }
+    }
+
+    // delete because of pointer members
+    input_buffer_adapter(const input_buffer_adapter&) = delete;
+    input_buffer_adapter& operator=(input_buffer_adapter&) = delete;
+
+    int get_character() noexcept override
+    {
+        if (JSON_LIKELY(cursor < limit))
+        {
+            return *(cursor++) & 0xFF;
+        }
+        else
+        {
+            return std::char_traits<char>::eof();
+        }
+    }
+
+    std::string read(size_t offset, size_t length) override
+    {
+        // avoid reading too many characters
+        const size_t max_length = static_cast<size_t>(limit - start);
+        return std::string(start + offset, (std::min)(length, max_length - offset));
+    }
+
+  private:
+    /// pointer to the current character
+    const char* cursor;
+    /// pointer past the last character
+    const char* limit;
+    /// pointer to the first character
+    const char* start;
+};
+
+struct input_adapter_factory
+{
+    // native support
+
+    /// input adapter for input stream
+    static std::shared_ptr<input_adapter> create(std::istream& i)
+    {
+        return std::make_shared<cached_input_stream_adapter<16384>> (i);
+    }
+
+    /// input adapter for input stream
+    static std::shared_ptr<input_adapter> create(std::istream&& i)
+    {
+        return std::make_shared<cached_input_stream_adapter<16384>>(i);
+    }
+
+    /// input adapter for buffer
+    static std::shared_ptr<input_adapter> create(const char* b, size_t l)
+    {
+        return std::make_shared<input_buffer_adapter>(b, l);
+    }
+
+    // derived support
+
+    /// input adapter for string literal
+    template <typename CharT,
+              typename std::enable_if<
+                  std::is_pointer<CharT>::value and
+                  std::is_integral<
+                      typename std::remove_pointer<CharT>::type>::value and
+                  sizeof(typename std::remove_pointer<CharT>::type) == 1,
+                  int>::type = 0>
+    static std::shared_ptr<input_adapter> create(CharT b)
+    {
+        return create(reinterpret_cast<const char*>(b),
+                      std::strlen(reinterpret_cast<const char*>(b)));
+    }
+
+    /// input adapter for iterator range with contiguous storage
+    template <class IteratorType,
+              typename std::enable_if<
+                  std::is_same<typename std::iterator_traits<
+                                   IteratorType>::iterator_category,
+                               std::random_access_iterator_tag>::value,
+                  int>::type = 0>
+    static std::shared_ptr<input_adapter> create(IteratorType first,
+            IteratorType last)
+    {
+        // assertion to check that the iterator range is indeed contiguous,
+        // see http://stackoverflow.com/a/35008842/266378 for more discussion
+        assert(std::accumulate(
+                   first, last, std::pair<bool, int>(true, 0),
+                   [&first](std::pair<bool, int> res, decltype(*first) val)
+        {
+            res.first &=
+                (val ==
+                 *(std::next(std::addressof(*first), res.second++)));
+            return res;
+        })
+        .first);
+
+        // assertion to check that each element is 1 byte long
+        static_assert(
+            sizeof(typename std::iterator_traits<IteratorType>::value_type) == 1, "each element in the iterator range must have the size of 1 byte");
+
+        return create(reinterpret_cast<const char*>(&(*first)),
+                      static_cast<size_t>(std::distance(first, last)));
+    }
+
+    /// input adapter for array
+    template <class T, std::size_t N>
+    static std::shared_ptr<input_adapter> create(T (&array)[N])
+    {
+        // delegate the call to the iterator-range overload
+        return create(std::begin(array), std::end(array));
+    }
+
+    /// input adapter for contiguous container
+    template <
+        class ContiguousContainer,
+        typename std::enable_if <
+            not std::is_pointer<ContiguousContainer>::value and
+            std::is_base_of<std::random_access_iterator_tag,
+                            typename std::iterator_traits<decltype(std::begin(
+                                        std::declval<ContiguousContainer const>()))>::
+                            iterator_category>::value,
+            int >::type = 0 >
+    static std::shared_ptr<input_adapter> create(const ContiguousContainer& c)
+    {
+        // delegate the call to the iterator-range overload
+        return create(std::begin(c), std::end(c));
+    }
+};
+
 } // namespace detail
 
 
@@ -7822,7 +8086,7 @@ class basic_json
     static basic_json parse(const CharT s,
                             const parser_callback_t cb = nullptr)
     {
-        return parser(input_adapter::create(s), cb).parse(true);
+        return parser(detail::input_adapter_factory::create(s), cb).parse(true);
     }
 
     template<typename CharT, typename std::enable_if<
@@ -7831,7 +8095,7 @@ class basic_json
                  sizeof(typename std::remove_pointer<CharT>::type) == 1, int>::type = 0>
     static bool accept(const CharT s)
     {
-        return parser(input_adapter::create(s)).accept(true);
+        return parser(detail::input_adapter_factory::create(s)).accept(true);
     }
 
     /*!
@@ -7865,12 +8129,12 @@ class basic_json
     static basic_json parse(std::istream& i,
                             const parser_callback_t cb = nullptr)
     {
-        return parser(input_adapter::create(i), cb).parse(true);
+        return parser(detail::input_adapter_factory::create(i), cb).parse(true);
     }
 
     static bool accept(std::istream& i)
     {
-        return parser(input_adapter::create(i)).accept(true);
+        return parser(detail::input_adapter_factory::create(i)).accept(true);
     }
 
     /*!
@@ -7879,12 +8143,12 @@ class basic_json
     static basic_json parse(std::istream&& i,
                             const parser_callback_t cb = nullptr)
     {
-        return parser(input_adapter::create(i), cb).parse(true);
+        return parser(detail::input_adapter_factory::create(i), cb).parse(true);
     }
 
     static bool accept(std::istream&& i)
     {
-        return parser(input_adapter::create(i)).accept(true);
+        return parser(detail::input_adapter_factory::create(i)).accept(true);
     }
 
     /*!
@@ -7939,7 +8203,7 @@ class basic_json
     static basic_json parse(IteratorType first, IteratorType last,
                             const parser_callback_t cb = nullptr)
     {
-        return parser(input_adapter::create(first, last), cb).parse(true);
+        return parser(detail::input_adapter_factory::create(first, last), cb).parse(true);
     }
 
     template<class IteratorType, typename std::enable_if<
@@ -7948,7 +8212,7 @@ class basic_json
                      typename std::iterator_traits<IteratorType>::iterator_category>::value, int>::type = 0>
     static bool accept(IteratorType first, IteratorType last)
     {
-        return parser(input_adapter::create(first, last)).accept(true);
+        return parser(detail::input_adapter_factory::create(first, last)).accept(true);
     }
 
     /*!
@@ -8030,7 +8294,7 @@ class basic_json
     JSON_DEPRECATED
     friend std::istream& operator<<(basic_json& j, std::istream& i)
     {
-        j = parser(input_adapter::create(i)).parse(false);
+        j = parser(detail::input_adapter_factory::create(i)).parse(false);
         return i;
     }
 
@@ -8061,7 +8325,7 @@ class basic_json
     */
     friend std::istream& operator>>(std::istream& i, basic_json& j)
     {
-        j = parser(input_adapter::create(i)).parse(false);
+        j = parser(detail::input_adapter_factory::create(i)).parse(false);
         return i;
     }
 
@@ -9100,263 +9364,6 @@ class basic_json
 
 
   private:
-    ////////////////////
-    // input adapters //
-    ////////////////////
-
-    /// abstract input adapter interface
-    class input_adapter
-    {
-      public:
-        virtual int get_character() = 0;
-        virtual std::string read(size_t offset, size_t length) = 0;
-        virtual ~input_adapter() {}
-
-        // native support
-
-        /// input adapter for input stream
-        static std::shared_ptr<input_adapter> create(std::istream& i)
-        {
-            return std::make_shared<cached_input_stream_adapter<16384>> (i);
-        }
-
-        /// input adapter for input stream
-        static std::shared_ptr<input_adapter> create(std::istream&& i)
-        {
-            return std::make_shared<cached_input_stream_adapter<16384>>(i);
-        }
-
-        /// input adapter for buffer
-        static std::shared_ptr<input_adapter> create(const char* b, size_t l)
-        {
-            return std::make_shared<input_buffer_adapter>(b, l);
-        }
-
-        // derived support
-
-        /// input adapter for string literal
-        template<typename CharT, typename std::enable_if<
-                     std::is_pointer<CharT>::value and
-                     std::is_integral<typename std::remove_pointer<CharT>::type>::value and
-                     sizeof(typename std::remove_pointer<CharT>::type) == 1, int>::type = 0>
-        static std::shared_ptr<input_adapter> create(CharT b)
-        {
-            return create(reinterpret_cast<const char*>(b),
-                          std::strlen(reinterpret_cast<const char*>(b)));
-        }
-
-        /// input adapter for iterator range with contiguous storage
-        template<class IteratorType, typename std::enable_if<
-                     std::is_same<typename std::iterator_traits<IteratorType>::iterator_category, std::random_access_iterator_tag>::value
-                     , int>::type
-                 = 0>
-        static std::shared_ptr<input_adapter> create(IteratorType first, IteratorType last)
-        {
-            // assertion to check that the iterator range is indeed contiguous,
-            // see http://stackoverflow.com/a/35008842/266378 for more discussion
-            assert(std::accumulate(first, last, std::pair<bool, int>(true, 0),
-                                   [&first](std::pair<bool, int> res, decltype(*first) val)
-            {
-                res.first &= (val == *(std::next(std::addressof(*first), res.second++)));
-                return res;
-            }).first);
-
-            // assertion to check that each element is 1 byte long
-            static_assert(sizeof(typename std::iterator_traits<IteratorType>::value_type) == 1,
-                          "each element in the iterator range must have the size of 1 byte");
-
-            const auto len = static_cast<size_t>(std::distance(first, last));
-            if (JSON_LIKELY(len > 0))
-            {
-                // there is at least one element: use the address of first
-                return create(reinterpret_cast<const char*>(&(*first)), len);
-            }
-            else
-            {
-                // the address of first cannot be used - use nullptr
-                return create(nullptr, len);
-            }
-        }
-
-        /// input adapter for array
-        template<class T, std::size_t N>
-        static std::shared_ptr<input_adapter> create(T (&array)[N])
-        {
-            // delegate the call to the iterator-range overload
-            return create(std::begin(array), std::end(array));
-        }
-
-        /// input adapter for contiguous container
-        template<class ContiguousContainer, typename std::enable_if<
-                     not std::is_pointer<ContiguousContainer>::value and
-                     std::is_base_of<
-                         std::random_access_iterator_tag,
-                         typename std::iterator_traits<decltype(std::begin(std::declval<ContiguousContainer const>()))>::iterator_category>::value
-                     , int>::type = 0>
-        static std::shared_ptr<input_adapter> create(const ContiguousContainer& c)
-        {
-            // delegate the call to the iterator-range overload
-            return create(std::begin(c), std::end(c));
-        }
-    };
-
-    /// a type to simplify interfaces
-    using input_adapter_t = std::shared_ptr<input_adapter>;
-
-    /// input adapter for cached stream input
-    template<std::size_t N>
-    class cached_input_stream_adapter : public input_adapter
-    {
-      public:
-        cached_input_stream_adapter(std::istream& i)
-            : is(i), start_position(is.tellg())
-        {
-            fill_buffer();
-
-            // skip byte order mark
-            if (fill_size >= 3 and buffer[0] == '\xEF' and buffer[1] == '\xBB' and buffer[2] == '\xBF')
-            {
-                buffer_pos += 3;
-                processed_chars += 3;
-            }
-        }
-
-        ~cached_input_stream_adapter() override
-        {
-            // clear stream flags
-            is.clear();
-            // We initially read a lot of characters into the buffer, and we
-            // may not have processed all of them. Therefore, we need to
-            // "rewind" the stream after the last processed char.
-            is.seekg(start_position);
-            is.ignore(static_cast<std::streamsize>(processed_chars));
-            // clear stream flags
-            is.clear();
-        }
-
-        int get_character() override
-        {
-            // check if refilling is necessary and possible
-            if (buffer_pos == fill_size and not eof)
-            {
-                fill_buffer();
-
-                // check and remember that filling did not yield new input
-                if (fill_size == 0)
-                {
-                    eof = true;
-                    return std::char_traits<char>::eof();
-                }
-
-                // the buffer is ready
-                buffer_pos = 0;
-            }
-
-            ++processed_chars;
-            assert(buffer_pos < buffer.size());
-            return buffer[buffer_pos++] & 0xFF;
-        }
-
-        std::string read(size_t offset, size_t length) override
-        {
-            // create buffer
-            std::string result(length, '\0');
-
-            // save stream position
-            const auto current_pos = is.tellg();
-            // save stream flags
-            const auto flags = is.rdstate();
-
-            // clear stream flags
-            is.clear();
-            // set stream position
-            is.seekg(static_cast<std::streamoff>(offset));
-            // read bytes
-            is.read(&result[0], static_cast<std::streamsize>(length));
-
-            // reset stream position
-            is.seekg(current_pos);
-            // reset stream flags
-            is.setstate(flags);
-
-            return result;
-        }
-
-      private:
-        void fill_buffer()
-        {
-            // fill
-            is.read(buffer.data(), static_cast<std::streamsize>(buffer.size()));
-            // store number of bytes in the buffer
-            fill_size = static_cast<size_t>(is.gcount());
-        }
-
-        /// the associated input stream
-        std::istream& is;
-
-        /// chars returned via get_character()
-        size_t processed_chars = 0;
-        /// chars processed in the current buffer
-        size_t buffer_pos = 0;
-
-        /// whether stream reached eof
-        bool eof = false;
-        /// how many chars have been copied to the buffer by last (re)fill
-        size_t fill_size = 0;
-
-        /// position of the stream when we started
-        const std::streampos start_position;
-
-        /// internal buffer
-        std::array<char, N> buffer{{}};
-    };
-
-    /// input adapter for buffer input
-    class input_buffer_adapter : public input_adapter
-    {
-      public:
-        input_buffer_adapter(const char* b, size_t l)
-            : input_adapter(), cursor(b), limit(b + l), start(b)
-        {
-            // skip byte order mark
-            if (l >= 3 and b[0] == '\xEF' and b[1] == '\xBB' and b[2] == '\xBF')
-            {
-                cursor += 3;
-            }
-        }
-
-        // delete because of pointer members
-        input_buffer_adapter(const input_buffer_adapter&) = delete;
-        input_buffer_adapter& operator=(input_buffer_adapter&) = delete;
-
-        int get_character() noexcept override
-        {
-            if (JSON_LIKELY(cursor < limit))
-            {
-                return *(cursor++) & 0xFF;
-            }
-            else
-            {
-                return std::char_traits<char>::eof();
-            }
-        }
-
-        std::string read(size_t offset, size_t length) override
-        {
-            // avoid reading too many characters
-            const size_t max_length = static_cast<size_t>(limit - start);
-            return std::string(start + offset, (std::min)(length, max_length - offset));
-        }
-
-      private:
-        /// pointer to the current character
-        const char* cursor;
-        /// pointer past the last character
-        const char* limit;
-        /// pointer to the first character
-        const char* start;
-    };
-
     //////////////////////////////////////////
     // binary serialization/deserialization //
     //////////////////////////////////////////
@@ -9364,7 +9371,6 @@ class basic_json
     /// @name binary serialization/deserialization support
     /// @{
 
-  private:
     /*!
     @brief deserialization of CBOR and MessagePack values
     */
@@ -9376,7 +9382,7 @@ class basic_json
 
         @param[in] adapter  input adapter to read from
         */
-        explicit binary_reader(input_adapter_t adapter)
+        explicit binary_reader(detail::input_adapter_t adapter)
             : ia(adapter), is_little_endian(little_endianess())
         {
             assert(ia);
@@ -10489,7 +10495,7 @@ class basic_json
 
       private:
         /// input adapter
-        input_adapter_t ia = nullptr;
+        detail::input_adapter_t ia = nullptr;
 
         /// the current character
         int current = std::char_traits<char>::eof();
@@ -11299,7 +11305,7 @@ class basic_json
     static basic_json from_cbor(const std::vector<uint8_t>& v,
                                 const size_t start_index = 0)
     {
-        binary_reader br(input_adapter::create(v.begin() + static_cast<difference_type>(start_index), v.end()));
+        binary_reader br(detail::input_adapter_factory::create(v.begin() + static_cast<difference_type>(start_index), v.end()));
         return br.parse_cbor();
     }
 
@@ -11374,7 +11380,7 @@ class basic_json
     static basic_json from_msgpack(const std::vector<uint8_t>& v,
                                    const size_t start_index = 0)
     {
-        binary_reader br(input_adapter::create(v.begin() + static_cast<difference_type>(start_index), v.end()));
+        binary_reader br(detail::input_adapter_factory::create(v.begin() + static_cast<difference_type>(start_index), v.end()));
         return br.parse_msgpack();
     }
 
@@ -11460,7 +11466,7 @@ class basic_json
             }
         }
 
-        explicit lexer(input_adapter_t adapter)
+        explicit lexer(detail::input_adapter_t adapter)
             : ia(adapter), decimal_point_char(get_decimal_point())
         {}
 
@@ -12864,7 +12870,7 @@ class basic_json
 
       private:
         /// input adapter
-        input_adapter_t ia = nullptr;
+        detail::input_adapter_t ia = nullptr;
 
         /// the current character
         int current = std::char_traits<char>::eof();
@@ -12903,7 +12909,7 @@ class basic_json
     {
       public:
         /// a parser reading from an input adapter
-        explicit parser(input_adapter_t adapter,
+        explicit parser(detail::input_adapter_t adapter,
                         const parser_callback_t cb = nullptr)
             : callback(cb), m_lexer(adapter)
         {}
diff --git a/test/src/unit-class_lexer.cpp b/test/src/unit-class_lexer.cpp
index 071337b5d7..794feb4ec4 100644
--- a/test/src/unit-class_lexer.cpp
+++ b/test/src/unit-class_lexer.cpp
@@ -36,7 +36,7 @@ using nlohmann::json;
 json::lexer::token_type scan_string(const char* s);
 json::lexer::token_type scan_string(const char* s)
 {
-    return json::lexer(json::input_adapter::create(s)).scan();
+    return json::lexer(nlohmann::detail::input_adapter_factory::create(s)).scan();
 }
 
 TEST_CASE("lexer class")
diff --git a/test/src/unit-class_parser.cpp b/test/src/unit-class_parser.cpp
index 7a8378a71a..59765eda0b 100644
--- a/test/src/unit-class_parser.cpp
+++ b/test/src/unit-class_parser.cpp
@@ -40,30 +40,30 @@ TEST_CASE("parser class")
     {
         SECTION("null")
         {
-            CHECK(json::parser(json::input_adapter::create(std::string("null"))).parse() == json(nullptr));
+            CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("null"))).parse() == json(nullptr));
         }
 
         SECTION("true")
         {
-            CHECK(json::parser(json::input_adapter::create(std::string("true"))).parse() == json(true));
+            CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("true"))).parse() == json(true));
         }
 
         SECTION("false")
         {
-            CHECK(json::parser(json::input_adapter::create(std::string("false"))).parse() == json(false));
+            CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("false"))).parse() == json(false));
         }
 
         SECTION("array")
         {
             SECTION("empty array")
             {
-                CHECK(json::parser(json::input_adapter::create(std::string("[]"))).parse() == json(json::value_t::array));
-                CHECK(json::parser(json::input_adapter::create(std::string("[ ]"))).parse() == json(json::value_t::array));
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("[]"))).parse() == json(json::value_t::array));
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("[ ]"))).parse() == json(json::value_t::array));
             }
 
             SECTION("nonempty array")
             {
-                CHECK(json::parser(json::input_adapter::create(std::string("[true, false, null]"))).parse() == json({true, false, nullptr}));
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("[true, false, null]"))).parse() == json({true, false, nullptr}));
             }
         }
 
@@ -71,113 +71,113 @@ TEST_CASE("parser class")
         {
             SECTION("empty object")
             {
-                CHECK(json::parser(json::input_adapter::create(std::string("{}"))).parse() == json(json::value_t::object));
-                CHECK(json::parser(json::input_adapter::create(std::string("{ }"))).parse() == json(json::value_t::object));
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{}"))).parse() == json(json::value_t::object));
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{ }"))).parse() == json(json::value_t::object));
             }
 
             SECTION("nonempty object")
             {
-                CHECK(json::parser(json::input_adapter::create(std::string("{\"\": true, \"one\": 1, \"two\": null}"))).parse() == json({{"", true}, {"one", 1}, {"two", nullptr}}));
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{\"\": true, \"one\": 1, \"two\": null}"))).parse() == json({{"", true}, {"one", 1}, {"two", nullptr}}));
             }
         }
 
         SECTION("string")
         {
             // empty string
-            CHECK(json::parser(json::input_adapter::create(std::string("\"\""))).parse() == json(json::value_t::string));
+            CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\""))).parse() == json(json::value_t::string));
 
             SECTION("errors")
             {
                 // error: tab in string
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\t\""))).parse(), json::parse_error&);
-                CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("\"\t\""))).parse(),
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\t\""))).parse(), json::parse_error&);
+                CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\t\""))).parse(),
                                   "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+0009>'");
                 // error: newline in string
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\n\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\r\""))).parse(), json::parse_error&);
-                CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("\"\n\""))).parse(),
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\n\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\r\""))).parse(), json::parse_error&);
+                CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\n\""))).parse(),
                                   "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+000A>'");
-                CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("\"\r\""))).parse(),
+                CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\r\""))).parse(),
                                   "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+000D>'");
                 // error: backspace in string
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\b\""))).parse(), json::parse_error&);
-                CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("\"\b\""))).parse(),
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\b\""))).parse(), json::parse_error&);
+                CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\b\""))).parse(),
                                   "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+0008>'");
                 // improve code coverage
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\uFF01"))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("[-4:1,]"))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\uFF01"))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("[-4:1,]"))).parse(), json::parse_error&);
                 // unescaped control characters
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x00\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x01\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x02\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x03\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x04\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x05\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x06\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x07\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x08\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x09\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x0a\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x0b\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x0c\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x0d\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x0e\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x0f\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x10\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x11\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x12\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x13\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x14\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x15\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x16\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x17\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x18\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x19\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x1a\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x1b\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x1c\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x1d\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x1e\""))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\x1f\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x00\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x01\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x02\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x03\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x04\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x05\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x06\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x07\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x08\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x09\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x0a\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x0b\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x0c\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x0d\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x0e\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x0f\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x10\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x11\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x12\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x13\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x14\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x15\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x16\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x17\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x18\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x19\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x1a\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x1b\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x1c\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x1d\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x1e\""))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x1f\""))).parse(), json::parse_error&);
             }
 
             SECTION("escaped")
             {
                 // quotation mark "\""
                 auto r1 = R"("\"")"_json;
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\\"\""))).parse() == r1);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\\"\""))).parse() == r1);
                 // reverse solidus "\\"
                 auto r2 = R"("\\")"_json;
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\\\\""))).parse() == r2);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\\\\""))).parse() == r2);
                 // solidus
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\/\""))).parse() == R"("/")"_json);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\/\""))).parse() == R"("/")"_json);
                 // backspace
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\b\""))).parse() == json("\b"));
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\b\""))).parse() == json("\b"));
                 // formfeed
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\f\""))).parse() == json("\f"));
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\f\""))).parse() == json("\f"));
                 // newline
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\n\""))).parse() == json("\n"));
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\n\""))).parse() == json("\n"));
                 // carriage return
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\r\""))).parse() == json("\r"));
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\r\""))).parse() == json("\r"));
                 // horizontal tab
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\t\""))).parse() == json("\t"));
-
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\u0001\""))).parse().get<json::string_t>() == "\x01");
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\u000a\""))).parse().get<json::string_t>() == "\n");
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\u00b0\""))).parse().get<json::string_t>() == "°");
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\u0c00\""))).parse().get<json::string_t>() == "ఀ");
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\ud000\""))).parse().get<json::string_t>() == "퀀");
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\u000E\""))).parse().get<json::string_t>() == "\x0E");
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\u00F0\""))).parse().get<json::string_t>() == "ð");
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\u0100\""))).parse().get<json::string_t>() == "Ā");
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\u2000\""))).parse().get<json::string_t>() == " ");
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\uFFFF\""))).parse().get<json::string_t>() == "￿");
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\u20AC\""))).parse().get<json::string_t>() == "€");
-                CHECK(json::parser(json::input_adapter::create(std::string("\"€\""))).parse().get<json::string_t>() == "€");
-                CHECK(json::parser(json::input_adapter::create(std::string("\"🎈\""))).parse().get<json::string_t>() == "🎈");
-
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\ud80c\\udc60\""))).parse().get<json::string_t>() == u8"\U00013060");
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\ud83c\\udf1e\""))).parse().get<json::string_t>() == "🌞");
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\t\""))).parse() == json("\t"));
+
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u0001\""))).parse().get<json::string_t>() == "\x01");
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u000a\""))).parse().get<json::string_t>() == "\n");
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u00b0\""))).parse().get<json::string_t>() == "°");
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u0c00\""))).parse().get<json::string_t>() == "ఀ");
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\ud000\""))).parse().get<json::string_t>() == "퀀");
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u000E\""))).parse().get<json::string_t>() == "\x0E");
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u00F0\""))).parse().get<json::string_t>() == "ð");
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u0100\""))).parse().get<json::string_t>() == "Ā");
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u2000\""))).parse().get<json::string_t>() == " ");
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\uFFFF\""))).parse().get<json::string_t>() == "￿");
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u20AC\""))).parse().get<json::string_t>() == "€");
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"€\""))).parse().get<json::string_t>() == "€");
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"🎈\""))).parse().get<json::string_t>() == "🎈");
+
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\ud80c\\udc60\""))).parse().get<json::string_t>() == u8"\U00013060");
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\ud83c\\udf1e\""))).parse().get<json::string_t>() == "🌞");
             }
         }
 
@@ -187,40 +187,40 @@ TEST_CASE("parser class")
             {
                 SECTION("without exponent")
                 {
-                    CHECK(json::parser(json::input_adapter::create(std::string("-128"))).parse() == json(-128));
-                    CHECK(json::parser(json::input_adapter::create(std::string("-0"))).parse() == json(-0));
-                    CHECK(json::parser(json::input_adapter::create(std::string("0"))).parse() == json(0));
-                    CHECK(json::parser(json::input_adapter::create(std::string("128"))).parse() == json(128));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-128"))).parse() == json(-128));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0"))).parse() == json(-0));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("0"))).parse() == json(0));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("128"))).parse() == json(128));
                 }
 
                 SECTION("with exponent")
                 {
-                    CHECK(json::parser(json::input_adapter::create(std::string("0e1"))).parse() == json(0e1));
-                    CHECK(json::parser(json::input_adapter::create(std::string("0E1"))).parse() == json(0e1));
-
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000E-4"))).parse() == json(10000e-4));
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000E-3"))).parse() == json(10000e-3));
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000E-2"))).parse() == json(10000e-2));
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000E-1"))).parse() == json(10000e-1));
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000E0"))).parse() == json(10000e0));
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000E1"))).parse() == json(10000e1));
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000E2"))).parse() == json(10000e2));
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000E3"))).parse() == json(10000e3));
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000E4"))).parse() == json(10000e4));
-
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000e-4"))).parse() == json(10000e-4));
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000e-3"))).parse() == json(10000e-3));
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000e-2"))).parse() == json(10000e-2));
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000e-1"))).parse() == json(10000e-1));
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000e0"))).parse() == json(10000e0));
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000e1"))).parse() == json(10000e1));
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000e2"))).parse() == json(10000e2));
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000e3"))).parse() == json(10000e3));
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000e4"))).parse() == json(10000e4));
-
-                    CHECK(json::parser(json::input_adapter::create(std::string("-0e1"))).parse() == json(-0e1));
-                    CHECK(json::parser(json::input_adapter::create(std::string("-0E1"))).parse() == json(-0e1));
-                    CHECK(json::parser(json::input_adapter::create(std::string("-0E123"))).parse() == json(-0e123));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("0e1"))).parse() == json(0e1));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("0E1"))).parse() == json(0e1));
+
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000E-4"))).parse() == json(10000e-4));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000E-3"))).parse() == json(10000e-3));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000E-2"))).parse() == json(10000e-2));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000E-1"))).parse() == json(10000e-1));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000E0"))).parse() == json(10000e0));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000E1"))).parse() == json(10000e1));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000E2"))).parse() == json(10000e2));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000E3"))).parse() == json(10000e3));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000E4"))).parse() == json(10000e4));
+
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000e-4"))).parse() == json(10000e-4));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000e-3"))).parse() == json(10000e-3));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000e-2"))).parse() == json(10000e-2));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000e-1"))).parse() == json(10000e-1));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000e0"))).parse() == json(10000e0));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000e1"))).parse() == json(10000e1));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000e2"))).parse() == json(10000e2));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000e3"))).parse() == json(10000e3));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000e4"))).parse() == json(10000e4));
+
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0e1"))).parse() == json(-0e1));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0E1"))).parse() == json(-0e1));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0E123"))).parse() == json(-0e123));
                 }
 
                 SECTION("edge cases")
@@ -232,9 +232,9 @@ TEST_CASE("parser class")
                     // agree exactly on their numeric values.
 
                     // -(2**53)+1
-                    CHECK(json::parser(json::input_adapter::create(std::string("-9007199254740991"))).parse().get<int64_t>() == -9007199254740991);
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-9007199254740991"))).parse().get<int64_t>() == -9007199254740991);
                     // (2**53)-1
-                    CHECK(json::parser(json::input_adapter::create(std::string("9007199254740991"))).parse().get<int64_t>() == 9007199254740991);
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("9007199254740991"))).parse().get<int64_t>() == 9007199254740991);
                 }
 
                 SECTION("over the edge cases")  // issue #178 - Integer conversion to unsigned (incorrect handling of 64 bit integers)
@@ -247,11 +247,11 @@ TEST_CASE("parser class")
                     // i.e. -(2**63) -> (2**64)-1.
 
                     // -(2**63)    ** Note: compilers see negative literals as negated positive numbers (hence the -1))
-                    CHECK(json::parser(json::input_adapter::create(std::string("-9223372036854775808"))).parse().get<int64_t>() == -9223372036854775807 - 1);
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-9223372036854775808"))).parse().get<int64_t>() == -9223372036854775807 - 1);
                     // (2**63)-1
-                    CHECK(json::parser(json::input_adapter::create(std::string("9223372036854775807"))).parse().get<int64_t>() == 9223372036854775807);
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("9223372036854775807"))).parse().get<int64_t>() == 9223372036854775807);
                     // (2**64)-1
-                    CHECK(json::parser(json::input_adapter::create(std::string("18446744073709551615"))).parse().get<uint64_t>() == 18446744073709551615u);
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("18446744073709551615"))).parse().get<uint64_t>() == 18446744073709551615u);
                 }
             }
 
@@ -259,85 +259,85 @@ TEST_CASE("parser class")
             {
                 SECTION("without exponent")
                 {
-                    CHECK(json::parser(json::input_adapter::create(std::string("-128.5"))).parse() == json(-128.5));
-                    CHECK(json::parser(json::input_adapter::create(std::string("0.999"))).parse() == json(0.999));
-                    CHECK(json::parser(json::input_adapter::create(std::string("128.5"))).parse() == json(128.5));
-                    CHECK(json::parser(json::input_adapter::create(std::string("-0.0"))).parse() == json(-0.0));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-128.5"))).parse() == json(-128.5));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("0.999"))).parse() == json(0.999));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("128.5"))).parse() == json(128.5));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0.0"))).parse() == json(-0.0));
                 }
 
                 SECTION("with exponent")
                 {
-                    CHECK(json::parser(json::input_adapter::create(std::string("-128.5E3"))).parse() == json(-128.5E3));
-                    CHECK(json::parser(json::input_adapter::create(std::string("-128.5E-3"))).parse() == json(-128.5E-3));
-                    CHECK(json::parser(json::input_adapter::create(std::string("-0.0e1"))).parse() == json(-0.0e1));
-                    CHECK(json::parser(json::input_adapter::create(std::string("-0.0E1"))).parse() == json(-0.0e1));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-128.5E3"))).parse() == json(-128.5E3));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-128.5E-3"))).parse() == json(-128.5E-3));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0.0e1"))).parse() == json(-0.0e1));
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0.0E1"))).parse() == json(-0.0e1));
                 }
             }
 
             SECTION("overflow")
             {
                 // overflows during parsing yield an exception
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("1.18973e+4932"))).parse() == json(), json::out_of_range&);
-                CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("1.18973e+4932"))).parse() == json(),
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1.18973e+4932"))).parse() == json(), json::out_of_range&);
+                CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1.18973e+4932"))).parse() == json(),
                                   "[json.exception.out_of_range.406] number overflow parsing '1.18973e+4932'");
             }
 
             SECTION("invalid numbers")
             {
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("01"))).parse(),      json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("--1"))).parse(),     json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("1."))).parse(),      json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("1E"))).parse(),      json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("1E-"))).parse(),     json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("1.E1"))).parse(),    json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("-1E"))).parse(),     json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("-0E#"))).parse(),    json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("-0E-#"))).parse(),   json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("-0#"))).parse(),     json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("-0.0:"))).parse(),   json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("-0.0Z"))).parse(),   json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("-0E123:"))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("-0e0-:"))).parse(),  json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("-0e-:"))).parse(),   json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("-0f"))).parse(),     json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("01"))).parse(),      json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("--1"))).parse(),     json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1."))).parse(),      json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1E"))).parse(),      json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1E-"))).parse(),     json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1.E1"))).parse(),    json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-1E"))).parse(),     json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0E#"))).parse(),    json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0E-#"))).parse(),   json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0#"))).parse(),     json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0.0:"))).parse(),   json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0.0Z"))).parse(),   json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0E123:"))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0e0-:"))).parse(),  json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0e-:"))).parse(),   json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0f"))).parse(),     json::parse_error&);
 
                 // numbers must not begin with "+"
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("+1"))).parse(), json::parse_error&);
-                CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("+0"))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("+1"))).parse(), json::parse_error&);
+                CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("+0"))).parse(), json::parse_error&);
 
-                CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("01"))).parse(),
+                CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("01"))).parse(),
                                   "[json.exception.parse_error.101] parse error at 2: syntax error - unexpected number literal; expected end of input");
-                CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("-01"))).parse(),
+                CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-01"))).parse(),
                                   "[json.exception.parse_error.101] parse error at 3: syntax error - unexpected number literal; expected end of input");
-                CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("--1"))).parse(),
+                CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("--1"))).parse(),
                                   "[json.exception.parse_error.101] parse error at 2: syntax error - invalid number; expected digit after '-'; last read: '--'");
-                CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("1."))).parse(),
+                CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1."))).parse(),
                                   "[json.exception.parse_error.101] parse error at 3: syntax error - invalid number; expected digit after '.'; last read: '1.'");
-                CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("1E"))).parse(),
+                CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1E"))).parse(),
                                   "[json.exception.parse_error.101] parse error at 3: syntax error - invalid number; expected '+', '-', or digit after exponent; last read: '1E'");
-                CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("1E-"))).parse(),
+                CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1E-"))).parse(),
                                   "[json.exception.parse_error.101] parse error at 4: syntax error - invalid number; expected digit after exponent sign; last read: '1E-'");
-                CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("1.E1"))).parse(),
+                CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1.E1"))).parse(),
                                   "[json.exception.parse_error.101] parse error at 3: syntax error - invalid number; expected digit after '.'; last read: '1.E'");
-                CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("-1E"))).parse(),
+                CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-1E"))).parse(),
                                   "[json.exception.parse_error.101] parse error at 4: syntax error - invalid number; expected '+', '-', or digit after exponent; last read: '-1E'");
-                CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("-0E#"))).parse(),
+                CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0E#"))).parse(),
                                   "[json.exception.parse_error.101] parse error at 4: syntax error - invalid number; expected '+', '-', or digit after exponent; last read: '-0E#'");
-                CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("-0E-#"))).parse(),
+                CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0E-#"))).parse(),
                                   "[json.exception.parse_error.101] parse error at 5: syntax error - invalid number; expected digit after exponent sign; last read: '-0E-#'");
-                CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("-0#"))).parse(),
+                CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0#"))).parse(),
                                   "[json.exception.parse_error.101] parse error at 3: syntax error - invalid literal; last read: '-0#'; expected end of input");
-                CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("-0.0:"))).parse(),
+                CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0.0:"))).parse(),
                                   "[json.exception.parse_error.101] parse error at 5: syntax error - unexpected ':'; expected end of input");
-                CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("-0.0Z"))).parse(),
+                CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0.0Z"))).parse(),
                                   "[json.exception.parse_error.101] parse error at 5: syntax error - invalid literal; last read: '-0.0Z'; expected end of input");
-                CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("-0E123:"))).parse(),
+                CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0E123:"))).parse(),
                                   "[json.exception.parse_error.101] parse error at 7: syntax error - unexpected ':'; expected end of input");
-                CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("-0e0-:"))).parse(),
+                CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0e0-:"))).parse(),
                                   "[json.exception.parse_error.101] parse error at 6: syntax error - invalid number; expected digit after '-'; last read: '-:'; expected end of input");
-                CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("-0e-:"))).parse(),
+                CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0e-:"))).parse(),
                                   "[json.exception.parse_error.101] parse error at 5: syntax error - invalid number; expected digit after exponent sign; last read: '-0e-:'");
-                CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("-0f"))).parse(),
+                CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0f"))).parse(),
                                   "[json.exception.parse_error.101] parse error at 4: syntax error - invalid literal; last read: '-0f'; expected end of input");
             }
         }
@@ -347,30 +347,30 @@ TEST_CASE("parser class")
     {
         SECTION("null")
         {
-            CHECK(json::parser(json::input_adapter::create(std::string("null"))).accept());
+            CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("null"))).accept());
         }
 
         SECTION("true")
         {
-            CHECK(json::parser(json::input_adapter::create(std::string("true"))).accept());
+            CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("true"))).accept());
         }
 
         SECTION("false")
         {
-            CHECK(json::parser(json::input_adapter::create(std::string("false"))).accept());
+            CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("false"))).accept());
         }
 
         SECTION("array")
         {
             SECTION("empty array")
             {
-                CHECK(json::parser(json::input_adapter::create(std::string("[]"))).accept());
-                CHECK(json::parser(json::input_adapter::create(std::string("[ ]"))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("[]"))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("[ ]"))).accept());
             }
 
             SECTION("nonempty array")
             {
-                CHECK(json::parser(json::input_adapter::create(std::string("[true, false, null]"))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("[true, false, null]"))).accept());
             }
         }
 
@@ -378,105 +378,105 @@ TEST_CASE("parser class")
         {
             SECTION("empty object")
             {
-                CHECK(json::parser(json::input_adapter::create(std::string("{}"))).accept());
-                CHECK(json::parser(json::input_adapter::create(std::string("{ }"))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{}"))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{ }"))).accept());
             }
 
             SECTION("nonempty object")
             {
-                CHECK(json::parser(json::input_adapter::create(std::string("{\"\": true, \"one\": 1, \"two\": null}"))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{\"\": true, \"one\": 1, \"two\": null}"))).accept());
             }
         }
 
         SECTION("string")
         {
             // empty string
-            CHECK(json::parser(json::input_adapter::create(std::string("\"\""))).accept());
+            CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\""))).accept());
 
             SECTION("errors")
             {
                 // error: tab in string
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\t\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\t\""))).accept() == false);
                 // error: newline in string
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\n\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\r\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\n\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\r\""))).accept() == false);
                 // error: backspace in string
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\b\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\b\""))).accept() == false);
                 // improve code coverage
-                CHECK(json::parser(json::input_adapter::create(std::string("\uFF01"))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("[-4:1,]"))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\uFF01"))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("[-4:1,]"))).accept() == false);
                 // unescaped control characters
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x00\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x01\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x02\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x03\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x04\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x05\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x06\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x07\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x08\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x09\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x0a\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x0b\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x0c\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x0d\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x0e\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x0f\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x10\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x11\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x12\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x13\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x14\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x15\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x16\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x17\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x18\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x19\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x1a\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x1b\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x1c\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x1d\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x1e\""))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\x1f\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x00\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x01\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x02\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x03\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x04\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x05\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x06\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x07\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x08\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x09\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x0a\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x0b\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x0c\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x0d\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x0e\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x0f\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x10\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x11\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x12\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x13\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x14\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x15\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x16\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x17\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x18\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x19\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x1a\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x1b\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x1c\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x1d\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x1e\""))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\x1f\""))).accept() == false);
             }
 
             SECTION("escaped")
             {
                 // quotation mark "\""
                 auto r1 = R"("\"")"_json;
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\\"\""))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\\"\""))).accept());
                 // reverse solidus "\\"
                 auto r2 = R"("\\")"_json;
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\\\\""))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\\\\""))).accept());
                 // solidus
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\/\""))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\/\""))).accept());
                 // backspace
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\b\""))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\b\""))).accept());
                 // formfeed
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\f\""))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\f\""))).accept());
                 // newline
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\n\""))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\n\""))).accept());
                 // carriage return
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\r\""))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\r\""))).accept());
                 // horizontal tab
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\t\""))).accept());
-
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\u0001\""))).accept());
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\u000a\""))).accept());
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\u00b0\""))).accept());
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\u0c00\""))).accept());
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\ud000\""))).accept());
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\u000E\""))).accept());
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\u00F0\""))).accept());
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\u0100\""))).accept());
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\u2000\""))).accept());
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\uFFFF\""))).accept());
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\u20AC\""))).accept());
-                CHECK(json::parser(json::input_adapter::create(std::string("\"€\""))).accept());
-                CHECK(json::parser(json::input_adapter::create(std::string("\"🎈\""))).accept());
-
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\ud80c\\udc60\""))).accept());
-                CHECK(json::parser(json::input_adapter::create(std::string("\"\\ud83c\\udf1e\""))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\t\""))).accept());
+
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u0001\""))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u000a\""))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u00b0\""))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u0c00\""))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\ud000\""))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u000E\""))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u00F0\""))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u0100\""))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u2000\""))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\uFFFF\""))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u20AC\""))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"€\""))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"🎈\""))).accept());
+
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\ud80c\\udc60\""))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\ud83c\\udf1e\""))).accept());
             }
         }
 
@@ -486,40 +486,40 @@ TEST_CASE("parser class")
             {
                 SECTION("without exponent")
                 {
-                    CHECK(json::parser(json::input_adapter::create(std::string("-128"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("-0"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("0"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("128"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-128"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("0"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("128"))).accept());
                 }
 
                 SECTION("with exponent")
                 {
-                    CHECK(json::parser(json::input_adapter::create(std::string("0e1"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("0E1"))).accept());
-
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000E-4"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000E-3"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000E-2"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000E-1"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000E0"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000E1"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000E2"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000E3"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000E4"))).accept());
-
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000e-4"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000e-3"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000e-2"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000e-1"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000e0"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000e1"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000e2"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000e3"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("10000e4"))).accept());
-
-                    CHECK(json::parser(json::input_adapter::create(std::string("-0e1"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("-0E1"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("-0E123"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("0e1"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("0E1"))).accept());
+
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000E-4"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000E-3"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000E-2"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000E-1"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000E0"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000E1"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000E2"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000E3"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000E4"))).accept());
+
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000e-4"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000e-3"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000e-2"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000e-1"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000e0"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000e1"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000e2"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000e3"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("10000e4"))).accept());
+
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0e1"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0E1"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0E123"))).accept());
                 }
 
                 SECTION("edge cases")
@@ -531,9 +531,9 @@ TEST_CASE("parser class")
                     // agree exactly on their numeric values.
 
                     // -(2**53)+1
-                    CHECK(json::parser(json::input_adapter::create(std::string("-9007199254740991"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-9007199254740991"))).accept());
                     // (2**53)-1
-                    CHECK(json::parser(json::input_adapter::create(std::string("9007199254740991"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("9007199254740991"))).accept());
                 }
 
                 SECTION("over the edge cases")  // issue #178 - Integer conversion to unsigned (incorrect handling of 64 bit integers)
@@ -546,11 +546,11 @@ TEST_CASE("parser class")
                     // i.e. -(2**63) -> (2**64)-1.
 
                     // -(2**63)    ** Note: compilers see negative literals as negated positive numbers (hence the -1))
-                    CHECK(json::parser(json::input_adapter::create(std::string("-9223372036854775808"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-9223372036854775808"))).accept());
                     // (2**63)-1
-                    CHECK(json::parser(json::input_adapter::create(std::string("9223372036854775807"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("9223372036854775807"))).accept());
                     // (2**64)-1
-                    CHECK(json::parser(json::input_adapter::create(std::string("18446744073709551615"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("18446744073709551615"))).accept());
                 }
             }
 
@@ -558,49 +558,49 @@ TEST_CASE("parser class")
             {
                 SECTION("without exponent")
                 {
-                    CHECK(json::parser(json::input_adapter::create(std::string("-128.5"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("0.999"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("128.5"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("-0.0"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-128.5"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("0.999"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("128.5"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0.0"))).accept());
                 }
 
                 SECTION("with exponent")
                 {
-                    CHECK(json::parser(json::input_adapter::create(std::string("-128.5E3"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("-128.5E-3"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("-0.0e1"))).accept());
-                    CHECK(json::parser(json::input_adapter::create(std::string("-0.0E1"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-128.5E3"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-128.5E-3"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0.0e1"))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0.0E1"))).accept());
                 }
             }
 
             SECTION("overflow")
             {
                 // overflows during parsing yield an exception, but is accepted anyway
-                CHECK(json::parser(json::input_adapter::create(std::string("1.18973e+4932"))).accept());
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1.18973e+4932"))).accept());
             }
 
             SECTION("invalid numbers")
             {
-                CHECK(json::parser(json::input_adapter::create(std::string("01"))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("--1"))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("1."))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("1E"))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("1E-"))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("1.E1"))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("-1E"))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("-0E#"))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("-0E-#"))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("-0#"))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("-0.0:"))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("-0.0Z"))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("-0E123:"))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("-0e0-:"))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("-0e-:"))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("-0f"))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("01"))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("--1"))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1."))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1E"))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1E-"))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1.E1"))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-1E"))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0E#"))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0E-#"))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0#"))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0.0:"))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0.0Z"))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0E123:"))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0e0-:"))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0e-:"))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0f"))).accept() == false);
 
                 // numbers must not begin with "+"
-                CHECK(json::parser(json::input_adapter::create(std::string("+1"))).accept() == false);
-                CHECK(json::parser(json::input_adapter::create(std::string("+0"))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("+1"))).accept() == false);
+                CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("+0"))).accept() == false);
             }
         }
     }
@@ -608,152 +608,152 @@ TEST_CASE("parser class")
     SECTION("parse errors")
     {
         // unexpected end of number
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("0."))).parse(),  json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("-"))).parse(),   json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("--"))).parse(),  json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("-0."))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("-."))).parse(),  json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("-:"))).parse(),  json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("0.:"))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("e."))).parse(),  json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("1e."))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("1e/"))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("1e:"))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("1E."))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("1E/"))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("1E:"))).parse(), json::parse_error&);
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("0."))).parse(),
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("0."))).parse(),  json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-"))).parse(),   json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("--"))).parse(),  json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0."))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-."))).parse(),  json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-:"))).parse(),  json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("0.:"))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("e."))).parse(),  json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1e."))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1e/"))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1e:"))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1E."))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1E/"))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1E:"))).parse(), json::parse_error&);
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("0."))).parse(),
                           "[json.exception.parse_error.101] parse error at 3: syntax error - invalid number; expected digit after '.'; last read: '0.'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("-"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-"))).parse(),
                           "[json.exception.parse_error.101] parse error at 2: syntax error - invalid number; expected digit after '-'; last read: '-'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("--"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("--"))).parse(),
                           "[json.exception.parse_error.101] parse error at 2: syntax error - invalid number; expected digit after '-'; last read: '--'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("-0."))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0."))).parse(),
                           "[json.exception.parse_error.101] parse error at 4: syntax error - invalid number; expected digit after '.'; last read: '-0.'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("-."))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-."))).parse(),
                           "[json.exception.parse_error.101] parse error at 2: syntax error - invalid number; expected digit after '-'; last read: '-.'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("-:"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-:"))).parse(),
                           "[json.exception.parse_error.101] parse error at 2: syntax error - invalid number; expected digit after '-'; last read: '-:'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("0.:"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("0.:"))).parse(),
                           "[json.exception.parse_error.101] parse error at 3: syntax error - invalid number; expected digit after '.'; last read: '0.:'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("e."))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("e."))).parse(),
                           "[json.exception.parse_error.101] parse error at 1: syntax error - invalid literal; last read: 'e'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("1e."))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1e."))).parse(),
                           "[json.exception.parse_error.101] parse error at 3: syntax error - invalid number; expected '+', '-', or digit after exponent; last read: '1e.'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("1e/"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1e/"))).parse(),
                           "[json.exception.parse_error.101] parse error at 3: syntax error - invalid number; expected '+', '-', or digit after exponent; last read: '1e/'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("1e:"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1e:"))).parse(),
                           "[json.exception.parse_error.101] parse error at 3: syntax error - invalid number; expected '+', '-', or digit after exponent; last read: '1e:'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("1E."))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1E."))).parse(),
                           "[json.exception.parse_error.101] parse error at 3: syntax error - invalid number; expected '+', '-', or digit after exponent; last read: '1E.'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("1E/"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1E/"))).parse(),
                           "[json.exception.parse_error.101] parse error at 3: syntax error - invalid number; expected '+', '-', or digit after exponent; last read: '1E/'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("1E:"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1E:"))).parse(),
                           "[json.exception.parse_error.101] parse error at 3: syntax error - invalid number; expected '+', '-', or digit after exponent; last read: '1E:'");
 
         // unexpected end of null
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("n"))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("nu"))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("nul"))).parse(), json::parse_error&);
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("n"))).parse(),
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("n"))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("nu"))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("nul"))).parse(), json::parse_error&);
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("n"))).parse(),
                           "[json.exception.parse_error.101] parse error at 2: syntax error - invalid literal; last read: 'n'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("nu"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("nu"))).parse(),
                           "[json.exception.parse_error.101] parse error at 3: syntax error - invalid literal; last read: 'nu'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("nul"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("nul"))).parse(),
                           "[json.exception.parse_error.101] parse error at 4: syntax error - invalid literal; last read: 'nul'");
 
         // unexpected end of true
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("t"))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("tr"))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("tru"))).parse(), json::parse_error&);
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("t"))).parse(),
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("t"))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("tr"))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("tru"))).parse(), json::parse_error&);
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("t"))).parse(),
                           "[json.exception.parse_error.101] parse error at 2: syntax error - invalid literal; last read: 't'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("tr"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("tr"))).parse(),
                           "[json.exception.parse_error.101] parse error at 3: syntax error - invalid literal; last read: 'tr'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("tru"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("tru"))).parse(),
                           "[json.exception.parse_error.101] parse error at 4: syntax error - invalid literal; last read: 'tru'");
 
         // unexpected end of false
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("f"))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("fa"))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("fal"))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("fals"))).parse(), json::parse_error&);
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("f"))).parse(),
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("f"))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("fa"))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("fal"))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("fals"))).parse(), json::parse_error&);
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("f"))).parse(),
                           "[json.exception.parse_error.101] parse error at 2: syntax error - invalid literal; last read: 'f'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("fa"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("fa"))).parse(),
                           "[json.exception.parse_error.101] parse error at 3: syntax error - invalid literal; last read: 'fa'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("fal"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("fal"))).parse(),
                           "[json.exception.parse_error.101] parse error at 4: syntax error - invalid literal; last read: 'fal'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("fals"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("fals"))).parse(),
                           "[json.exception.parse_error.101] parse error at 5: syntax error - invalid literal; last read: 'fals'");
 
         // missing/unexpected end of array
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("["))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("[1"))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("[1,"))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("[1,]"))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("]"))).parse(), json::parse_error&);
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("["))).parse(),
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("["))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("[1"))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("[1,"))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("[1,]"))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("]"))).parse(), json::parse_error&);
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("["))).parse(),
                           "[json.exception.parse_error.101] parse error at 2: syntax error - unexpected end of input; expected '[', '{', or a literal");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("[1"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("[1"))).parse(),
                           "[json.exception.parse_error.101] parse error at 3: syntax error - unexpected end of input; expected ']'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("[1,"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("[1,"))).parse(),
                           "[json.exception.parse_error.101] parse error at 4: syntax error - unexpected end of input; expected '[', '{', or a literal");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("[1,]"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("[1,]"))).parse(),
                           "[json.exception.parse_error.101] parse error at 4: syntax error - unexpected ']'; expected '[', '{', or a literal");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("]"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("]"))).parse(),
                           "[json.exception.parse_error.101] parse error at 1: syntax error - unexpected ']'; expected '[', '{', or a literal");
 
         // missing/unexpected end of object
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("{"))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("{\"foo\""))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("{\"foo\":"))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("{\"foo\":}"))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("{\"foo\":1,}"))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("}"))).parse(), json::parse_error&);
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("{"))).parse(),
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{"))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{\"foo\""))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{\"foo\":"))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{\"foo\":}"))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{\"foo\":1,}"))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("}"))).parse(), json::parse_error&);
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{"))).parse(),
                           "[json.exception.parse_error.101] parse error at 2: syntax error - unexpected end of input; expected string literal");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("{\"foo\""))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{\"foo\""))).parse(),
                           "[json.exception.parse_error.101] parse error at 7: syntax error - unexpected end of input; expected ':'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("{\"foo\":"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{\"foo\":"))).parse(),
                           "[json.exception.parse_error.101] parse error at 8: syntax error - unexpected end of input; expected '[', '{', or a literal");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("{\"foo\":}"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{\"foo\":}"))).parse(),
                           "[json.exception.parse_error.101] parse error at 8: syntax error - unexpected '}'; expected '[', '{', or a literal");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("{\"foo\":1,}"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{\"foo\":1,}"))).parse(),
                           "[json.exception.parse_error.101] parse error at 10: syntax error - unexpected '}'; expected string literal");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("}"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("}"))).parse(),
                           "[json.exception.parse_error.101] parse error at 1: syntax error - unexpected '}'; expected '[', '{', or a literal");
 
         // missing/unexpected end of string
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\""))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\\\""))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\\u\""))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\\u0\""))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\\u01\""))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\\u012\""))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\\u"))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\\u0"))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\\u01"))).parse(), json::parse_error&);
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("\"\\u012"))).parse(), json::parse_error&);
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("\""))).parse(),
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\""))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\\""))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u\""))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u0\""))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u01\""))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u012\""))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u"))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u0"))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u01"))).parse(), json::parse_error&);
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u012"))).parse(), json::parse_error&);
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\""))).parse(),
                           "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: missing closing quote; last read: '\"'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("\"\\\""))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\\""))).parse(),
                           "[json.exception.parse_error.101] parse error at 4: syntax error - invalid string: missing closing quote; last read: '\"\\\"'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("\"\\u\""))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u\""))).parse(),
                           "[json.exception.parse_error.101] parse error at 4: syntax error - invalid string: '\\u' must be followed by 4 hex digits; last read: '\"\\u\"'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("\"\\u0\""))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u0\""))).parse(),
                           "[json.exception.parse_error.101] parse error at 5: syntax error - invalid string: '\\u' must be followed by 4 hex digits; last read: '\"\\u0\"'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("\"\\u01\""))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u01\""))).parse(),
                           "[json.exception.parse_error.101] parse error at 6: syntax error - invalid string: '\\u' must be followed by 4 hex digits; last read: '\"\\u01\"'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("\"\\u012\""))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u012\""))).parse(),
                           "[json.exception.parse_error.101] parse error at 7: syntax error - invalid string: '\\u' must be followed by 4 hex digits; last read: '\"\\u012\"'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("\"\\u"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u"))).parse(),
                           "[json.exception.parse_error.101] parse error at 4: syntax error - invalid string: '\\u' must be followed by 4 hex digits; last read: '\"\\u'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("\"\\u0"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u0"))).parse(),
                           "[json.exception.parse_error.101] parse error at 5: syntax error - invalid string: '\\u' must be followed by 4 hex digits; last read: '\"\\u0'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("\"\\u01"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u01"))).parse(),
                           "[json.exception.parse_error.101] parse error at 6: syntax error - invalid string: '\\u' must be followed by 4 hex digits; last read: '\"\\u01'");
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("\"\\u012"))).parse(),
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u012"))).parse(),
                           "[json.exception.parse_error.101] parse error at 7: syntax error - invalid string: '\\u' must be followed by 4 hex digits; last read: '\"\\u012'");
 
         // invalid escapes
@@ -773,7 +773,7 @@ TEST_CASE("parser class")
                 case ('r'):
                 case ('t'):
                 {
-                    CHECK_NOTHROW(json::parser(json::input_adapter::create(std::string(s.c_str()))).parse());
+                    CHECK_NOTHROW(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s.c_str()))).parse());
                     break;
                 }
 
@@ -786,11 +786,11 @@ TEST_CASE("parser class")
                 // any other combination of backslash and character is invalid
                 default:
                 {
-                    CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string(s.c_str()))).parse(), json::parse_error&);
+                    CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s.c_str()))).parse(), json::parse_error&);
                     // only check error message if c is not a control character
                     if (c > 0x1f)
                     {
-                        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string(s.c_str()))).parse(),
+                        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s.c_str()))).parse(),
                                           "[json.exception.parse_error.101] parse error at 3: syntax error - invalid string: forbidden character after backslash; last read: '\"\\" + std::string(1, static_cast<char>(c)) + "'");
                     }
                     break;
@@ -851,49 +851,49 @@ TEST_CASE("parser class")
                 if (valid(c))
                 {
                     CAPTURE(s1);
-                    CHECK_NOTHROW(json::parser(json::input_adapter::create(std::string(s1.c_str()))).parse());
+                    CHECK_NOTHROW(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s1.c_str()))).parse());
                     CAPTURE(s2);
-                    CHECK_NOTHROW(json::parser(json::input_adapter::create(std::string(s2.c_str()))).parse());
+                    CHECK_NOTHROW(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s2.c_str()))).parse());
                     CAPTURE(s3);
-                    CHECK_NOTHROW(json::parser(json::input_adapter::create(std::string(s3.c_str()))).parse());
+                    CHECK_NOTHROW(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s3.c_str()))).parse());
                     CAPTURE(s4);
-                    CHECK_NOTHROW(json::parser(json::input_adapter::create(std::string(s4.c_str()))).parse());
+                    CHECK_NOTHROW(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s4.c_str()))).parse());
                 }
                 else
                 {
                     CAPTURE(s1);
-                    CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string(s1.c_str()))).parse(), json::parse_error&);
+                    CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s1.c_str()))).parse(), json::parse_error&);
                     // only check error message if c is not a control character
                     if (c > 0x1f)
                     {
-                        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string(s1.c_str()))).parse(),
+                        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s1.c_str()))).parse(),
                                           "[json.exception.parse_error.101] parse error at 7: syntax error - invalid string: '\\u' must be followed by 4 hex digits; last read: '" + s1.substr(0, 7) + "'");
                     }
 
                     CAPTURE(s2);
-                    CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string(s2.c_str()))).parse(), json::parse_error&);
+                    CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s2.c_str()))).parse(), json::parse_error&);
                     // only check error message if c is not a control character
                     if (c > 0x1f)
                     {
-                        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string(s2.c_str()))).parse(),
+                        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s2.c_str()))).parse(),
                                           "[json.exception.parse_error.101] parse error at 6: syntax error - invalid string: '\\u' must be followed by 4 hex digits; last read: '" + s2.substr(0, 6) + "'");
                     }
 
                     CAPTURE(s3);
-                    CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string(s3.c_str()))).parse(), json::parse_error&);
+                    CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s3.c_str()))).parse(), json::parse_error&);
                     // only check error message if c is not a control character
                     if (c > 0x1f)
                     {
-                        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string(s3.c_str()))).parse(),
+                        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s3.c_str()))).parse(),
                                           "[json.exception.parse_error.101] parse error at 5: syntax error - invalid string: '\\u' must be followed by 4 hex digits; last read: '" + s3.substr(0, 5) + "'");
                     }
 
                     CAPTURE(s4);
-                    CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string(s4.c_str()))).parse(), json::parse_error&);
+                    CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s4.c_str()))).parse(), json::parse_error&);
                     // only check error message if c is not a control character
                     if (c > 0x1f)
                     {
-                        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string(s4.c_str()))).parse(),
+                        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s4.c_str()))).parse(),
                                           "[json.exception.parse_error.101] parse error at 4: syntax error - invalid string: '\\u' must be followed by 4 hex digits; last read: '" + s4.substr(0, 4) + "'");
                     }
                 }
@@ -919,63 +919,63 @@ TEST_CASE("parser class")
     SECTION("parse errors (accept)")
     {
         // unexpected end of number
-        CHECK(json::parser(json::input_adapter::create(std::string("0."))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("-"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("--"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("-0."))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("-."))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("-:"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("0.:"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("e."))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("1e."))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("1e/"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("1e:"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("1E."))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("1E/"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("1E:"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("0."))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("--"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-0."))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-."))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("-:"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("0.:"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("e."))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1e."))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1e/"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1e:"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1E."))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1E/"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("1E:"))).accept() == false);
 
         // unexpected end of null
-        CHECK(json::parser(json::input_adapter::create(std::string("n"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("nu"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("nul"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("n"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("nu"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("nul"))).accept() == false);
 
         // unexpected end of true
-        CHECK(json::parser(json::input_adapter::create(std::string("t"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("tr"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("tru"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("t"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("tr"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("tru"))).accept() == false);
 
         // unexpected end of false
-        CHECK(json::parser(json::input_adapter::create(std::string("f"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("fa"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("fal"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("fals"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("f"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("fa"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("fal"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("fals"))).accept() == false);
 
         // missing/unexpected end of array
-        CHECK(json::parser(json::input_adapter::create(std::string("["))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("[1"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("[1,"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("[1,]"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("]"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("["))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("[1"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("[1,"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("[1,]"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("]"))).accept() == false);
 
         // missing/unexpected end of object
-        CHECK(json::parser(json::input_adapter::create(std::string("{"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("{\"foo\""))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("{\"foo\":"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("{\"foo\":}"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("{\"foo\":1,}"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("}"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{\"foo\""))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{\"foo\":"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{\"foo\":}"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{\"foo\":1,}"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("}"))).accept() == false);
 
         // missing/unexpected end of string
-        CHECK(json::parser(json::input_adapter::create(std::string("\""))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("\"\\\""))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("\"\\u\""))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("\"\\u0\""))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("\"\\u01\""))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("\"\\u012\""))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("\"\\u"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("\"\\u0"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("\"\\u01"))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("\"\\u012"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\""))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\\""))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u\""))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u0\""))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u01\""))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u012\""))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u0"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u01"))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\u012"))).accept() == false);
 
         // invalid escapes
         for (int c = 1; c < 128; ++c)
@@ -994,7 +994,7 @@ TEST_CASE("parser class")
                 case ('r'):
                 case ('t'):
                 {
-                    CHECK(json::parser(json::input_adapter::create(std::string(s.c_str()))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s.c_str()))).accept());
                     break;
                 }
 
@@ -1007,7 +1007,7 @@ TEST_CASE("parser class")
                 // any other combination of backslash and character is invalid
                 default:
                 {
-                    CHECK(json::parser(json::input_adapter::create(std::string(s.c_str()))).accept() == false);
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s.c_str()))).accept() == false);
                     break;
                 }
             }
@@ -1066,48 +1066,48 @@ TEST_CASE("parser class")
                 if (valid(c))
                 {
                     CAPTURE(s1);
-                    CHECK(json::parser(json::input_adapter::create(std::string(s1.c_str()))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s1.c_str()))).accept());
                     CAPTURE(s2);
-                    CHECK(json::parser(json::input_adapter::create(std::string(s2.c_str()))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s2.c_str()))).accept());
                     CAPTURE(s3);
-                    CHECK(json::parser(json::input_adapter::create(std::string(s3.c_str()))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s3.c_str()))).accept());
                     CAPTURE(s4);
-                    CHECK(json::parser(json::input_adapter::create(std::string(s4.c_str()))).accept());
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s4.c_str()))).accept());
                 }
                 else
                 {
                     CAPTURE(s1);
-                    CHECK(json::parser(json::input_adapter::create(std::string(s1.c_str()))).accept() == false);
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s1.c_str()))).accept() == false);
 
                     CAPTURE(s2);
-                    CHECK(json::parser(json::input_adapter::create(std::string(s2.c_str()))).accept() == false);
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s2.c_str()))).accept() == false);
 
                     CAPTURE(s3);
-                    CHECK(json::parser(json::input_adapter::create(std::string(s3.c_str()))).accept() == false);
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s3.c_str()))).accept() == false);
 
                     CAPTURE(s4);
-                    CHECK(json::parser(json::input_adapter::create(std::string(s4.c_str()))).accept() == false);
+                    CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string(s4.c_str()))).accept() == false);
                 }
             }
         }
 
         // missing part of a surrogate pair
-        CHECK(json::parser(json::input_adapter::create(std::string("\"\\uD80C\""))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\uD80C\""))).accept() == false);
         // invalid surrogate pair
-        CHECK(json::parser(json::input_adapter::create(std::string("\"\\uD80C\\uD80C\""))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("\"\\uD80C\\u0000\""))).accept() == false);
-        CHECK(json::parser(json::input_adapter::create(std::string("\"\\uD80C\\uFFFF\""))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\uD80C\\uD80C\""))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\uD80C\\u0000\""))).accept() == false);
+        CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("\"\\uD80C\\uFFFF\""))).accept() == false);
     }
 
     SECTION("tests found by mutate++")
     {
         // test case to make sure no comma preceeds the first key
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("{,\"key\": false}"))).parse(), json::parse_error&);
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("{,\"key\": false}"))).parse(),
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{,\"key\": false}"))).parse(), json::parse_error&);
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("{,\"key\": false}"))).parse(),
                           "[json.exception.parse_error.101] parse error at 2: syntax error - unexpected ','; expected string literal");
         // test case to make sure an object is properly closed
-        CHECK_THROWS_AS(json::parser(json::input_adapter::create(std::string("[{\"key\": false true]"))).parse(), json::parse_error&);
-        CHECK_THROWS_WITH(json::parser(json::input_adapter::create(std::string("[{\"key\": false true]"))).parse(),
+        CHECK_THROWS_AS(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("[{\"key\": false true]"))).parse(), json::parse_error&);
+        CHECK_THROWS_WITH(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("[{\"key\": false true]"))).parse(),
                           "[json.exception.parse_error.101] parse error at 19: syntax error - unexpected true literal; expected '}'");
 
         // test case to make sure the callback is properly evaluated after reading a key
@@ -1295,42 +1295,42 @@ TEST_CASE("parser class")
         SECTION("from std::vector")
         {
             std::vector<uint8_t> v = {'t', 'r', 'u', 'e'};
-            CHECK(json::parser(json::input_adapter::create(std::begin(v), std::end(v))).parse() == json(true));
+            CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::begin(v), std::end(v))).parse() == json(true));
         }
 
         SECTION("from std::array")
         {
             std::array<uint8_t, 5> v { {'t', 'r', 'u', 'e'} };
-            CHECK(json::parser(json::input_adapter::create(std::begin(v), std::end(v))).parse() == json(true));
+            CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::begin(v), std::end(v))).parse() == json(true));
         }
 
         SECTION("from array")
         {
             uint8_t v[] = {'t', 'r', 'u', 'e'};
-            CHECK(json::parser(json::input_adapter::create(std::begin(v), std::end(v))).parse() == json(true));
+            CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::begin(v), std::end(v))).parse() == json(true));
         }
 
         SECTION("from char literal")
         {
-            CHECK(json::parser(json::input_adapter::create(std::string("true"))).parse() == json(true));
+            CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::string("true"))).parse() == json(true));
         }
 
         SECTION("from std::string")
         {
             std::string v = {'t', 'r', 'u', 'e'};
-            CHECK(json::parser(json::input_adapter::create(std::begin(v), std::end(v))).parse() == json(true));
+            CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::begin(v), std::end(v))).parse() == json(true));
         }
 
         SECTION("from std::initializer_list")
         {
             std::initializer_list<uint8_t> v = {'t', 'r', 'u', 'e'};
-            CHECK(json::parser(json::input_adapter::create(std::begin(v), std::end(v))).parse() == json(true));
+            CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::begin(v), std::end(v))).parse() == json(true));
         }
 
         SECTION("from std::valarray")
         {
             std::valarray<uint8_t> v = {'t', 'r', 'u', 'e'};
-            CHECK(json::parser(json::input_adapter::create(std::begin(v), std::end(v))).parse() == json(true));
+            CHECK(json::parser(nlohmann::detail::input_adapter_factory::create(std::begin(v), std::end(v))).parse() == json(true));
         }
     }
 }

From 8e681d1e570b2274a799521aad83292ed719e172 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9o=20DELRIEU?= <delrieutheo@gmail.com>
Date: Sun, 9 Jul 2017 16:38:24 +0200
Subject: [PATCH 4/9] move lexer/parser outside of basic_json

---
 src/json.hpp | 19012 +++++++++++++++++++++++++------------------------
 1 file changed, 9525 insertions(+), 9487 deletions(-)

diff --git a/src/json.hpp b/src/json.hpp
index fd63fe132b..8459c1a621 100644
--- a/src/json.hpp
+++ b/src/json.hpp
@@ -1529,11843 +1529,11881 @@ struct input_adapter_factory
     }
 };
 
-} // namespace detail
-
-
-/// namespace to hold default `to_json` / `from_json` functions
-namespace
-{
-constexpr const auto& to_json = detail::static_const<detail::to_json_fn>::value;
-constexpr const auto& from_json = detail::static_const<detail::from_json_fn>::value;
-}
-
+//////////////////////
+// lexer and parser //
+//////////////////////
 
 /*!
-@brief default JSONSerializer template argument
+@brief lexical analysis
 
-This serializer ignores the template arguments and uses ADL
-([argument-dependent lookup](http://en.cppreference.com/w/cpp/language/adl))
-for serialization.
+This class organizes the lexical analysis during JSON deserialization.
 */
-template<typename, typename>
-struct adl_serializer
+template <typename BasicJsonType>
+class lexer
 {
-    /*!
-    @brief convert a JSON value to any value type
+    using number_integer_t = typename BasicJsonType::number_integer_t;
+    using number_unsigned_t = typename BasicJsonType::number_unsigned_t;
+    using number_float_t = typename BasicJsonType::number_float_t;
 
-    This function is usually called by the `get()` function of the
-    @ref basic_json class (either explicit or via conversion operators).
+  public:
+    /// token types for the parser
+    enum class token_type
+    {
+        uninitialized,  ///< indicating the scanner is uninitialized
+        literal_true,   ///< the `true` literal
+        literal_false,  ///< the `false` literal
+        literal_null,   ///< the `null` literal
+        value_string,   ///< a string -- use get_string() for actual value
+        value_unsigned, ///< an unsigned integer -- use get_number_unsigned() for
+        ///actual value
+        value_integer,  ///< a signed integer -- use get_number_integer() for actual
+        ///value
+        value_float,    ///< an floating point number -- use get_number_float() for
+        ///actual value
+        begin_array,    ///< the character for array begin `[`
+        begin_object,   ///< the character for object begin `{`
+        end_array,      ///< the character for array end `]`
+        end_object,     ///< the character for object end `}`
+        name_separator, ///< the name separator `:`
+        value_separator, ///< the value separator `,`
+        parse_error,     ///< indicating a parse error
+        end_of_input,    ///< indicating the end of the input buffer
+        literal_or_value ///< a literal or the begin of a value (only for
+        ///diagnostics)
+    };
 
-    @param[in] j         JSON value to read from
-    @param[in,out] val  value to write to
-    */
-    template<typename BasicJsonType, typename ValueType>
-    static void from_json(BasicJsonType&& j, ValueType& val) noexcept(
-        noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), val)))
-    {
-        ::nlohmann::from_json(std::forward<BasicJsonType>(j), val);
+    /// return name of values of type token_type (only used for errors)
+    static const char* token_type_name(const token_type t) noexcept
+    {
+        switch (t)
+        {
+            case token_type::uninitialized:
+                return "<uninitialized>";
+            case token_type::literal_true:
+                return "true literal";
+            case token_type::literal_false:
+                return "false literal";
+            case token_type::literal_null:
+                return "null literal";
+            case token_type::value_string:
+                return "string literal";
+            case lexer::token_type::value_unsigned:
+            case lexer::token_type::value_integer:
+            case lexer::token_type::value_float:
+                return "number literal";
+            case token_type::begin_array:
+                return "'['";
+            case token_type::begin_object:
+                return "'{'";
+            case token_type::end_array:
+                return "']'";
+            case token_type::end_object:
+                return "'}'";
+            case token_type::name_separator:
+                return "':'";
+            case token_type::value_separator:
+                return "','";
+            case token_type::parse_error:
+                return "<parse error>";
+            case token_type::end_of_input:
+                return "end of input";
+            case token_type::literal_or_value:
+                return "'[', '{', or a literal";
+            default:
+            {
+                // catch non-enum values
+                return "unknown token"; // LCOV_EXCL_LINE
+            }
+        }
     }
 
-    /*!
-    @brief convert any value type to a JSON value
+    explicit lexer(detail::input_adapter_t adapter)
+        : ia(adapter), decimal_point_char(get_decimal_point()) {}
 
-    This function is usually called by the constructors of the @ref basic_json
-    class.
+    // delete because of pointer members
+    lexer(const lexer&) = delete;
+    lexer& operator=(lexer&) = delete;
 
-    @param[in,out] j  JSON value to write to
-    @param[in] val     value to read from
-    */
-    template<typename BasicJsonType, typename ValueType>
-    static void to_json(BasicJsonType& j, ValueType&& val) noexcept(
-        noexcept(::nlohmann::to_json(j, std::forward<ValueType>(val))))
+  private:
+    /////////////////////
+    // locales
+    /////////////////////
+
+    /// return the locale-dependent decimal point
+    static char get_decimal_point() noexcept
     {
-        ::nlohmann::to_json(j, std::forward<ValueType>(val));
+        const auto loc = localeconv();
+        assert(loc != nullptr);
+        return (loc->decimal_point == nullptr) ? '.' : loc->decimal_point[0];
     }
-};
-
-/*!
-@brief JSON Pointer
-
-A JSON pointer defines a string syntax for identifying a specific value
-within a JSON document. It can be used with functions `at` and
-`operator[]`. Furthermore, JSON pointers are the base for JSON patches.
-
-@sa [RFC 6901](https://tools.ietf.org/html/rfc6901)
-
-@since version 2.0.0
-*/
-class json_pointer
-{
-    /// allow basic_json to access private members
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    friend class basic_json;
-
-  public:
-    /*!
-      @brief create JSON pointer
-
-      Create a JSON pointer according to the syntax described in
-      [Section 3 of RFC6901](https://tools.ietf.org/html/rfc6901#section-3).
-
-      @param[in] s  string representing the JSON pointer; if omitted, the
-      empty string is assumed which references the whole JSON
-      value
-
-      @throw parse_error.107 if the given JSON pointer @a s is nonempty and
-      does not begin with a slash (`/`); see example below
-
-      @throw parse_error.108 if a tilde (`~`) in the given JSON pointer @a s
-      is not followed by `0` (representing `~`) or `1` (representing `/`);
-      see example below
-
-      @liveexample{The example shows the construction several valid JSON
-      pointers as well as the exceptional behavior.,json_pointer}
 
-      @since version 2.0.0
-      */
-    explicit json_pointer(const std::string& s = "") : reference_tokens(split(s)) {}
+    /////////////////////
+    // scan functions
+    /////////////////////
 
     /*!
-      @brief return a string representation of the JSON pointer
-
-      @invariant For each JSON pointer `ptr`, it holds:
-      @code {.cpp}
-      ptr == json_pointer(ptr.to_string());
-      @endcode
-
-      @return a string representation of the JSON pointer
-
-      @liveexample{The example shows the result of `to_string`.,
-      json_pointer__to_string}
-
-      @since version 2.0.0
-      */
-    std::string to_string() const noexcept
-    {
-        return std::accumulate(reference_tokens.begin(), reference_tokens.end(),
-                               std::string{},
-                               [](const std::string & a, const std::string & b)
-        {
-            return a + "/" + escape(b);
-        });
-    }
+    @brief get codepoint from 4 hex characters following `\u`
 
-    /// @copydoc to_string()
-    operator std::string() const
+    @return codepoint or -1 in case of an error (e.g. EOF or non-hex
+            character)
+    */
+    int get_codepoint()
     {
-        return to_string();
-    }
+        // this function only makes sense after reading `\u`
+        assert(current == 'u');
+        int codepoint = 0;
 
-  private:
-    /*!
-      @brief remove and return last reference pointer
-      @throw out_of_range.405 if JSON pointer has no parent
-      */
-    std::string pop_back()
-    {
-        if (is_root())
+        // byte 1: \uXxxx
+        switch (get())
         {
-            JSON_THROW(
-                detail::out_of_range::create(405, "JSON pointer has no parent"));
+            case '0':
+                break;
+            case '1':
+                codepoint += 0x1000;
+                break;
+            case '2':
+                codepoint += 0x2000;
+                break;
+            case '3':
+                codepoint += 0x3000;
+                break;
+            case '4':
+                codepoint += 0x4000;
+                break;
+            case '5':
+                codepoint += 0x5000;
+                break;
+            case '6':
+                codepoint += 0x6000;
+                break;
+            case '7':
+                codepoint += 0x7000;
+                break;
+            case '8':
+                codepoint += 0x8000;
+                break;
+            case '9':
+                codepoint += 0x9000;
+                break;
+            case 'A':
+            case 'a':
+                codepoint += 0xa000;
+                break;
+            case 'B':
+            case 'b':
+                codepoint += 0xb000;
+                break;
+            case 'C':
+            case 'c':
+                codepoint += 0xc000;
+                break;
+            case 'D':
+            case 'd':
+                codepoint += 0xd000;
+                break;
+            case 'E':
+            case 'e':
+                codepoint += 0xe000;
+                break;
+            case 'F':
+            case 'f':
+                codepoint += 0xf000;
+                break;
+            default:
+                return -1;
         }
 
-        auto last = reference_tokens.back();
-        reference_tokens.pop_back();
-        return last;
-    }
+        // byte 2: \uxXxx
+        switch (get())
+        {
+            case '0':
+                break;
+            case '1':
+                codepoint += 0x0100;
+                break;
+            case '2':
+                codepoint += 0x0200;
+                break;
+            case '3':
+                codepoint += 0x0300;
+                break;
+            case '4':
+                codepoint += 0x0400;
+                break;
+            case '5':
+                codepoint += 0x0500;
+                break;
+            case '6':
+                codepoint += 0x0600;
+                break;
+            case '7':
+                codepoint += 0x0700;
+                break;
+            case '8':
+                codepoint += 0x0800;
+                break;
+            case '9':
+                codepoint += 0x0900;
+                break;
+            case 'A':
+            case 'a':
+                codepoint += 0x0a00;
+                break;
+            case 'B':
+            case 'b':
+                codepoint += 0x0b00;
+                break;
+            case 'C':
+            case 'c':
+                codepoint += 0x0c00;
+                break;
+            case 'D':
+            case 'd':
+                codepoint += 0x0d00;
+                break;
+            case 'E':
+            case 'e':
+                codepoint += 0x0e00;
+                break;
+            case 'F':
+            case 'f':
+                codepoint += 0x0f00;
+                break;
+            default:
+                return -1;
+        }
 
-    /// return whether pointer points to the root document
-    bool is_root() const
-    {
-        return reference_tokens.empty();
-    }
+        // byte 3: \uxxXx
+        switch (get())
+        {
+            case '0':
+                break;
+            case '1':
+                codepoint += 0x0010;
+                break;
+            case '2':
+                codepoint += 0x0020;
+                break;
+            case '3':
+                codepoint += 0x0030;
+                break;
+            case '4':
+                codepoint += 0x0040;
+                break;
+            case '5':
+                codepoint += 0x0050;
+                break;
+            case '6':
+                codepoint += 0x0060;
+                break;
+            case '7':
+                codepoint += 0x0070;
+                break;
+            case '8':
+                codepoint += 0x0080;
+                break;
+            case '9':
+                codepoint += 0x0090;
+                break;
+            case 'A':
+            case 'a':
+                codepoint += 0x00a0;
+                break;
+            case 'B':
+            case 'b':
+                codepoint += 0x00b0;
+                break;
+            case 'C':
+            case 'c':
+                codepoint += 0x00c0;
+                break;
+            case 'D':
+            case 'd':
+                codepoint += 0x00d0;
+                break;
+            case 'E':
+            case 'e':
+                codepoint += 0x00e0;
+                break;
+            case 'F':
+            case 'f':
+                codepoint += 0x00f0;
+                break;
+            default:
+                return -1;
+        }
 
-    json_pointer top() const
-    {
-        if (is_root())
+        // byte 4: \uxxxX
+        switch (get())
         {
-            JSON_THROW(detail::out_of_range::create(405, "JSON pointer has no parent"));
+            case '0':
+                break;
+            case '1':
+                codepoint += 0x0001;
+                break;
+            case '2':
+                codepoint += 0x0002;
+                break;
+            case '3':
+                codepoint += 0x0003;
+                break;
+            case '4':
+                codepoint += 0x0004;
+                break;
+            case '5':
+                codepoint += 0x0005;
+                break;
+            case '6':
+                codepoint += 0x0006;
+                break;
+            case '7':
+                codepoint += 0x0007;
+                break;
+            case '8':
+                codepoint += 0x0008;
+                break;
+            case '9':
+                codepoint += 0x0009;
+                break;
+            case 'A':
+            case 'a':
+                codepoint += 0x000a;
+                break;
+            case 'B':
+            case 'b':
+                codepoint += 0x000b;
+                break;
+            case 'C':
+            case 'c':
+                codepoint += 0x000c;
+                break;
+            case 'D':
+            case 'd':
+                codepoint += 0x000d;
+                break;
+            case 'E':
+            case 'e':
+                codepoint += 0x000e;
+                break;
+            case 'F':
+            case 'f':
+                codepoint += 0x000f;
+                break;
+            default:
+                return -1;
         }
 
-        json_pointer result = *this;
-        result.reference_tokens = {reference_tokens[0]};
-        return result;
+        return codepoint;
     }
 
-
     /*!
-      @brief create and return a reference to the pointed to value
+    @brief scan a string literal
 
-      @complexity Linear in the number of reference tokens.
+    This function scans a string according to Sect. 7 of RFC 7159. While
+    scanning, bytes are escaped and copied into buffer yytext. Then the
+    function returns successfully, yytext is null-terminated and yylen
+    contains the number of bytes in the string.
 
-      @throw parse_error.109 if array index is not a number
-      @throw type_error.313 if value cannot be unflattened
-      */
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    NLOHMANN_BASIC_JSON_TPL& get_and_create(NLOHMANN_BASIC_JSON_TPL& j) const;
+    @return token_type::value_string if string could be successfully
+            scanned, token_type::parse_error otherwise
 
-    /*!
-      @brief return a reference to the pointed to value
+    @note In case of errors, variable error_message contains a textual
+          description.
+    */
+    token_type scan_string()
+    {
+        // reset yytext (ignore opening quote)
+        reset();
 
-      @note This version does not throw if a value is not present, but tries
-      to create nested values instead. For instance, calling this function
-      with pointer `"/this/that"` on a null value is equivalent to calling
-      `operator[]("this").operator[]("that")` on that value, effectively
-      changing the null value to an object.
+        // we entered the function by reading an open quote
+        assert(current == '\"');
 
-      @param[in] ptr  a JSON value
+        while (true)
+        {
+            // get next character
+            switch (get())
+            {
+                // end of file while parsing string
+                case std::char_traits<char>::eof():
+                {
+                    error_message = "invalid string: missing closing quote";
+                    return token_type::parse_error;
+                }
 
-      @return reference to the JSON value pointed to by the JSON pointer
+                // closing quote
+                case '\"':
+                {
+                    // terminate yytext
+                    add('\0');
+                    --yylen;
+                    return token_type::value_string;
+                }
+
+                // escapes
+                case '\\':
+                {
+                    switch (get())
+                    {
+                        // quotation mark
+                        case '\"':
+                            add('\"');
+                            break;
+                        // reverse solidus
+                        case '\\':
+                            add('\\');
+                            break;
+                        // solidus
+                        case '/':
+                            add('/');
+                            break;
+                        // backspace
+                        case 'b':
+                            add('\b');
+                            break;
+                        // form feed
+                        case 'f':
+                            add('\f');
+                            break;
+                        // line feed
+                        case 'n':
+                            add('\n');
+                            break;
+                        // carriage return
+                        case 'r':
+                            add('\r');
+                            break;
+                        // tab
+                        case 't':
+                            add('\t');
+                            break;
+
+                        // unicode escapes
+                        case 'u':
+                        {
+                            int codepoint;
+                            int codepoint1 = get_codepoint();
 
-      @complexity Linear in the length of the JSON pointer.
+                            if (JSON_UNLIKELY(codepoint1 == -1))
+                            {
+                                error_message =
+                                    "invalid string: '\\u' must be followed by 4 hex digits";
+                                return token_type::parse_error;
+                            }
 
-      @throw parse_error.106   if an array index begins with '0'
-      @throw parse_error.109   if an array index was not a number
-      @throw out_of_range.404  if the JSON pointer can not be resolved
-      */
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    NLOHMANN_BASIC_JSON_TPL& get_unchecked(NLOHMANN_BASIC_JSON_TPL* ptr) const;
-
-    /*!
-      @throw parse_error.106   if an array index begins with '0'
-      @throw parse_error.109   if an array index was not a number
-      @throw out_of_range.402  if the array index '-' is used
-      @throw out_of_range.404  if the JSON pointer can not be resolved
-      */
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    NLOHMANN_BASIC_JSON_TPL& get_checked(NLOHMANN_BASIC_JSON_TPL* ptr) const;
+                            // check if code point is a high surrogate
+                            if (0xD800 <= codepoint1 and codepoint1 <= 0xDBFF)
+                            {
+                                // expect next \uxxxx entry
+                                if (JSON_LIKELY(get() == '\\' and get() == 'u'))
+                                {
+                                    const int codepoint2 = get_codepoint();
 
-    /*!
-      @brief return a const reference to the pointed to value
+                                    if (JSON_UNLIKELY(codepoint2 == -1))
+                                    {
+                                        error_message =
+                                            "invalid string: '\\u' must be followed by 4 hex digits";
+                                        return token_type::parse_error;
+                                    }
 
-      @param[in] ptr  a JSON value
+                                    // check if codepoint2 is a low surrogate
+                                    if (JSON_LIKELY(0xDC00 <= codepoint2 and codepoint2 <= 0xDFFF))
+                                    {
+                                        codepoint =
+                                            // high surrogate occupies the most significant 22 bits
+                                            (codepoint1 << 10)
+                                            // low surrogate occupies the least significant 15 bits
+                                            + codepoint2
+                                            // there is still the 0xD800, 0xDC00 and 0x10000 noise
+                                            // in the result so we have to subtract with:
+                                            // (0xD800 << 10) + DC00 - 0x10000 = 0x35FDC00
+                                            - 0x35FDC00;
+                                    }
+                                    else
+                                    {
+                                        error_message = "invalid string: surrogate U+DC00..U+DFFF must "
+                                                        "be followed by U+DC00..U+DFFF";
+                                        return token_type::parse_error;
+                                    }
+                                }
+                                else
+                                {
+                                    error_message = "invalid string: surrogate U+DC00..U+DFFF must "
+                                                    "be followed by U+DC00..U+DFFF";
+                                    return token_type::parse_error;
+                                }
+                            }
+                            else
+                            {
+                                if (JSON_UNLIKELY(0xDC00 <= codepoint1 and codepoint1 <= 0xDFFF))
+                                {
+                                    error_message = "invalid string: surrogate U+DC00..U+DFFF must "
+                                                    "follow U+D800..U+DBFF";
+                                    return token_type::parse_error;
+                                }
 
-      @return const reference to the JSON value pointed to by the JSON
-      pointer
+                                // only work with first code point
+                                codepoint = codepoint1;
+                            }
 
-      @throw parse_error.106   if an array index begins with '0'
-      @throw parse_error.109   if an array index was not a number
-      @throw out_of_range.402  if the array index '-' is used
-      @throw out_of_range.404  if the JSON pointer can not be resolved
-      */
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    const NLOHMANN_BASIC_JSON_TPL& get_unchecked(const NLOHMANN_BASIC_JSON_TPL* ptr) const;
+                            // result of the above calculation yields a proper codepoint
+                            assert(0x00 <= codepoint and codepoint <= 0x10FFFF);
 
-    /*!
-      @throw parse_error.106   if an array index begins with '0'
-      @throw parse_error.109   if an array index was not a number
-      @throw out_of_range.402  if the array index '-' is used
-      @throw out_of_range.404  if the JSON pointer can not be resolved
-      */
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    const NLOHMANN_BASIC_JSON_TPL& get_checked(const NLOHMANN_BASIC_JSON_TPL* ptr) const;
+                            // translate code point to bytes
+                            if (codepoint < 0x80)
+                            {
+                                // 1-byte characters: 0xxxxxxx (ASCII)
+                                add(codepoint);
+                            }
+                            else if (codepoint <= 0x7ff)
+                            {
+                                // 2-byte characters: 110xxxxx 10xxxxxx
+                                add(0xC0 | (codepoint >> 6));
+                                add(0x80 | (codepoint & 0x3F));
+                            }
+                            else if (codepoint <= 0xffff)
+                            {
+                                // 3-byte characters: 1110xxxx 10xxxxxx 10xxxxxx
+                                add(0xE0 | (codepoint >> 12));
+                                add(0x80 | ((codepoint >> 6) & 0x3F));
+                                add(0x80 | (codepoint & 0x3F));
+                            }
+                            else
+                            {
+                                // 4-byte characters: 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx
+                                add(0xF0 | (codepoint >> 18));
+                                add(0x80 | ((codepoint >> 12) & 0x3F));
+                                add(0x80 | ((codepoint >> 6) & 0x3F));
+                                add(0x80 | (codepoint & 0x3F));
+                            }
 
-    /*!
-      @brief split the string input to reference tokens
+                            break;
+                        }
 
-      @note This function is only called by the json_pointer constructor.
-      All exceptions below are documented there.
+                        // other characters after escape
+                        default:
+                            error_message = "invalid string: forbidden character after backslash";
+                            return token_type::parse_error;
+                    }
 
-      @throw parse_error.107  if the pointer is not empty or begins with '/'
-      @throw parse_error.108  if character '~' is not followed by '0' or '1'
-      */
-    static std::vector<std::string> split(const std::string& reference_string)
-    {
-        std::vector<std::string> result;
+                    break;
+                }
 
-        // special case: empty reference string -> no reference tokens
-        if (reference_string.empty())
-        {
-            return result;
-        }
+                // invalid control characters
+                case 0x00:
+                case 0x01:
+                case 0x02:
+                case 0x03:
+                case 0x04:
+                case 0x05:
+                case 0x06:
+                case 0x07:
+                case 0x08:
+                case 0x09:
+                case 0x0a:
+                case 0x0b:
+                case 0x0c:
+                case 0x0d:
+                case 0x0e:
+                case 0x0f:
+                case 0x10:
+                case 0x11:
+                case 0x12:
+                case 0x13:
+                case 0x14:
+                case 0x15:
+                case 0x16:
+                case 0x17:
+                case 0x18:
+                case 0x19:
+                case 0x1a:
+                case 0x1b:
+                case 0x1c:
+                case 0x1d:
+                case 0x1e:
+                case 0x1f:
+                {
+                    error_message = "invalid string: control character must be escaped";
+                    return token_type::parse_error;
+                }
 
-        // check if nonempty reference string begins with slash
-        if (reference_string[0] != '/')
-        {
-            JSON_THROW(detail::parse_error::create(
-                           107, 1,
-                           "JSON pointer must be empty or begin with '/' - was: '" +
-                           reference_string + "'"));
-        }
+                // U+0020..U+007F (except U+0022 (quote) and U+005C (backspace))
+                case 0x20:
+                case 0x21:
+                case 0x23:
+                case 0x24:
+                case 0x25:
+                case 0x26:
+                case 0x27:
+                case 0x28:
+                case 0x29:
+                case 0x2a:
+                case 0x2b:
+                case 0x2c:
+                case 0x2d:
+                case 0x2e:
+                case 0x2f:
+                case 0x30:
+                case 0x31:
+                case 0x32:
+                case 0x33:
+                case 0x34:
+                case 0x35:
+                case 0x36:
+                case 0x37:
+                case 0x38:
+                case 0x39:
+                case 0x3a:
+                case 0x3b:
+                case 0x3c:
+                case 0x3d:
+                case 0x3e:
+                case 0x3f:
+                case 0x40:
+                case 0x41:
+                case 0x42:
+                case 0x43:
+                case 0x44:
+                case 0x45:
+                case 0x46:
+                case 0x47:
+                case 0x48:
+                case 0x49:
+                case 0x4a:
+                case 0x4b:
+                case 0x4c:
+                case 0x4d:
+                case 0x4e:
+                case 0x4f:
+                case 0x50:
+                case 0x51:
+                case 0x52:
+                case 0x53:
+                case 0x54:
+                case 0x55:
+                case 0x56:
+                case 0x57:
+                case 0x58:
+                case 0x59:
+                case 0x5a:
+                case 0x5b:
+                case 0x5d:
+                case 0x5e:
+                case 0x5f:
+                case 0x60:
+                case 0x61:
+                case 0x62:
+                case 0x63:
+                case 0x64:
+                case 0x65:
+                case 0x66:
+                case 0x67:
+                case 0x68:
+                case 0x69:
+                case 0x6a:
+                case 0x6b:
+                case 0x6c:
+                case 0x6d:
+                case 0x6e:
+                case 0x6f:
+                case 0x70:
+                case 0x71:
+                case 0x72:
+                case 0x73:
+                case 0x74:
+                case 0x75:
+                case 0x76:
+                case 0x77:
+                case 0x78:
+                case 0x79:
+                case 0x7a:
+                case 0x7b:
+                case 0x7c:
+                case 0x7d:
+                case 0x7e:
+                case 0x7f:
+                {
+                    add(current);
+                    break;
+                }
 
-        // extract the reference tokens:
-        // - slash: position of the last read slash (or end of string)
-        // - start: position after the previous slash
-        for (
-            // search for the first slash after the first character
-            size_t slash = reference_string.find_first_of('/', 1),
-            // set the beginning of the first reference token
-            start = 1;
-            // we can stop if start == string::npos+1 = 0
-            start != 0;
-            // set the beginning of the next reference token
-            // (will eventually be 0 if slash == std::string::npos)
-            start = slash + 1,
-            // find next slash
-            slash = reference_string.find_first_of('/', start))
-        {
-            // use the text between the beginning of the reference token
-            // (start) and the last slash (slash).
-            auto reference_token = reference_string.substr(start, slash - start);
+                // U+0080..U+07FF: bytes C2..DF 80..BF
+                case 0xc2:
+                case 0xc3:
+                case 0xc4:
+                case 0xc5:
+                case 0xc6:
+                case 0xc7:
+                case 0xc8:
+                case 0xc9:
+                case 0xca:
+                case 0xcb:
+                case 0xcc:
+                case 0xcd:
+                case 0xce:
+                case 0xcf:
+                case 0xd0:
+                case 0xd1:
+                case 0xd2:
+                case 0xd3:
+                case 0xd4:
+                case 0xd5:
+                case 0xd6:
+                case 0xd7:
+                case 0xd8:
+                case 0xd9:
+                case 0xda:
+                case 0xdb:
+                case 0xdc:
+                case 0xdd:
+                case 0xde:
+                case 0xdf:
+                {
+                    add(current);
+                    get();
+                    if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
+                    {
+                        add(current);
+                        continue;
+                    }
 
-            // check reference tokens are properly escaped
-            for (size_t pos = reference_token.find_first_of('~');
-                    pos != std::string::npos;
-                    pos = reference_token.find_first_of('~', pos + 1))
-            {
-                assert(reference_token[pos] == '~');
+                    error_message = "invalid string: ill-formed UTF-8 byte";
+                    return token_type::parse_error;
+                }
 
-                // ~ must be followed by 0 or 1
-                if (pos == reference_token.size() - 1 or
-                        (reference_token[pos + 1] != '0' and
-                         reference_token[pos + 1] != '1'))
+                // U+0800..U+0FFF: bytes E0 A0..BF 80..BF
+                case 0xe0:
                 {
-                    JSON_THROW(detail::parse_error::create(
-                                   108, 0, "escape character '~' must be followed with '0' or '1'"));
+                    add(current);
+                    get();
+                    if (JSON_LIKELY(0xa0 <= current and current <= 0xbf))
+                    {
+                        add(current);
+                        get();
+                        if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
+                        {
+                            add(current);
+                            continue;
+                        }
+                    }
+
+                    error_message = "invalid string: ill-formed UTF-8 byte";
+                    return token_type::parse_error;
                 }
-            }
 
-            // finally, store the reference token
-            unescape(reference_token);
-            result.push_back(reference_token);
-        }
+                // U+1000..U+CFFF: bytes E1..EC 80..BF 80..BF
+                // U+E000..U+FFFF: bytes EE..EF 80..BF 80..BF
+                case 0xe1:
+                case 0xe2:
+                case 0xe3:
+                case 0xe4:
+                case 0xe5:
+                case 0xe6:
+                case 0xe7:
+                case 0xe8:
+                case 0xe9:
+                case 0xea:
+                case 0xeb:
+                case 0xec:
+                case 0xee:
+                case 0xef:
+                {
+                    add(current);
+                    get();
+                    if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
+                    {
+                        add(current);
+                        get();
+                        if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
+                        {
+                            add(current);
+                            continue;
+                        }
+                    }
 
-        return result;
-    }
+                    error_message = "invalid string: ill-formed UTF-8 byte";
+                    return token_type::parse_error;
+                }
 
-    /*!
-      @brief replace all occurrences of a substring by another string
+                // U+D000..U+D7FF: bytes ED 80..9F 80..BF
+                case 0xed:
+                {
+                    add(current);
+                    get();
+                    if (JSON_LIKELY(0x80 <= current and current <= 0x9f))
+                    {
+                        add(current);
+                        get();
+                        if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
+                        {
+                            add(current);
+                            continue;
+                        }
+                    }
 
-      @param[in,out] s  the string to manipulate; changed so that all
-      occurrences of @a f are replaced with @a t
-      @param[in]     f  the substring to replace with @a t
-      @param[in]     t  the string to replace @a f
+                    error_message = "invalid string: ill-formed UTF-8 byte";
+                    return token_type::parse_error;
+                }
 
-      @pre The search string @a f must not be empty. **This precondition is
-      enforced with an assertion.**
+                // U+10000..U+3FFFF F0 90..BF 80..BF 80..BF
+                case 0xf0:
+                {
+                    add(current);
+                    get();
+                    if (JSON_LIKELY(0x90 <= current and current <= 0xbf))
+                    {
+                        add(current);
+                        get();
+                        if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
+                        {
+                            add(current);
+                            get();
+                            if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
+                            {
+                                add(current);
+                                continue;
+                            }
+                        }
+                    }
 
-      @since version 2.0.0
-      */
-    static void replace_substring(std::string& s, const std::string& f,
-                                  const std::string& t)
-    {
-        assert(not f.empty());
+                    error_message = "invalid string: ill-formed UTF-8 byte";
+                    return token_type::parse_error;
+                }
 
-        for (size_t pos = s.find(f);         // find first occurrence of f
-                pos != std::string::npos;       // make sure f was found
-                s.replace(pos, f.size(), t),    // replace with t
-                pos = s.find(f, pos + t.size()) // find next occurrence of f
-            )
-            ;
+                // U+40000..U+FFFFF F1..F3 80..BF 80..BF 80..BF
+                case 0xf1:
+                case 0xf2:
+                case 0xf3:
+                {
+                    add(current);
+                    get();
+                    if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
+                    {
+                        add(current);
+                        get();
+                        if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
+                        {
+                            add(current);
+                            get();
+                            if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
+                            {
+                                add(current);
+                                continue;
+                            }
+                        }
+                    }
+
+                    error_message = "invalid string: ill-formed UTF-8 byte";
+                    return token_type::parse_error;
+                }
+
+                // U+100000..U+10FFFF F4 80..8F 80..BF 80..BF
+                case 0xf4:
+                {
+                    add(current);
+                    get();
+                    if (JSON_LIKELY(0x80 <= current and current <= 0x8f))
+                    {
+                        add(current);
+                        get();
+                        if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
+                        {
+                            add(current);
+                            get();
+                            if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
+                            {
+                                add(current);
+                                continue;
+                            }
+                        }
+                    }
+
+                    error_message = "invalid string: ill-formed UTF-8 byte";
+                    return token_type::parse_error;
+                }
+
+                // remaining bytes (80..C1 and F5..FF) are ill-formed
+                default:
+                {
+                    error_message = "invalid string: ill-formed UTF-8 byte";
+                    return token_type::parse_error;
+                }
+            }
+        }
     }
 
-    /// escape tilde and slash
-    static std::string escape(std::string s)
+    static void strtof(float& f, const char* str, char** endptr) noexcept
     {
-        // escape "~"" to "~0" and "/" to "~1"
-        replace_substring(s, "~", "~0");
-        replace_substring(s, "/", "~1");
-        return s;
+        f = std::strtof(str, endptr);
     }
 
-    /// unescape tilde and slash
-    static void unescape(std::string& s)
+    static void strtof(double& f, const char* str, char** endptr) noexcept
     {
-        // first transform any occurrence of the sequence '~1' to '/'
-        replace_substring(s, "~1", "/");
-        // then transform any occurrence of the sequence '~0' to '~'
-        replace_substring(s, "~0", "~");
+        f = std::strtod(str, endptr);
+    }
+
+    static void strtof(long double& f, const char* str, char** endptr) noexcept
+    {
+        f = std::strtold(str, endptr);
     }
 
     /*!
-      @param[in] reference_string  the reference string to the current value
-      @param[in] value             the value to consider
-      @param[in,out] result        the result object to insert values to
+    @brief scan a number literal
 
-      @note Empty objects or arrays are flattened to `null`.
-      */
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    static void flatten(const std::string& reference_string,
-                        const NLOHMANN_BASIC_JSON_TPL& value,
-                        NLOHMANN_BASIC_JSON_TPL& result);
+    This function scans a string according to Sect. 6 of RFC 7159.
 
-    /*!
-      @param[in] value  flattened JSON
+    The function is realized with a deterministic finite state machine
+    derived from the grammar described in RFC 7159. Starting in state
+    "init", the input is read and used to determined the next state. Only
+    state "done" accepts the number. State "error" is a trap state to model
+    errors. In the table below, "anything" means any character but the ones
+    listed before.
 
-      @return unflattened JSON
+    state    | 0        | 1-9      | e E      | +       | -       | .        |
+    anything
+    ---------|----------|----------|----------|---------|---------|----------|-----------
+    init     | zero     | any1     | [error]  | [error] | minus   | [error]  |
+    [error]
+    minus    | zero     | any1     | [error]  | [error] | [error] | [error]  |
+    [error]
+    zero     | done     | done     | exponent | done    | done    | decimal1 |
+    done
+    any1     | any1     | any1     | exponent | done    | done    | decimal1 |
+    done
+    decimal1 | decimal2 | [error]  | [error]  | [error] | [error] | [error]  |
+    [error]
+    decimal2 | decimal2 | decimal2 | exponent | done    | done    | done     |
+    done
+    exponent | any2     | any2     | [error]  | sign    | sign    | [error]  |
+    [error]
+    sign     | any2     | any2     | [error]  | [error] | [error] | [error]  |
+    [error]
+    any2     | any2     | any2     | done     | done    | done    | done     |
+    done
 
-      @throw parse_error.109 if array index is not a number
-      @throw type_error.314  if value is not an object
-      @throw type_error.315  if object values are not primitive
-      @throw type_error.313  if value cannot be unflattened
-      */
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    static NLOHMANN_BASIC_JSON_TPL
-    unflatten(const NLOHMANN_BASIC_JSON_TPL& value);
+    The state machine is realized with one label per state (prefixed with
+    "scan_number_") and `goto` statements between them. The state machine
+    contains cycles, but any cycle can be left when EOF is read. Therefore,
+    the function is guaranteed to terminate.
 
-    friend bool operator==(json_pointer const& lhs,
-                           json_pointer const& rhs) noexcept;
+    During scanning, the read bytes are stored in yytext. This string is
+    then converted to a signed integer, an unsigned integer, or a
+    floating-point number.
 
-    friend bool operator!=(json_pointer const& lhs,
-                           json_pointer const& rhs) noexcept;
+    @return token_type::value_unsigned, token_type::value_integer, or
+            token_type::value_float if number could be successfully scanned,
+            token_type::parse_error otherwise
 
-    /// the reference tokens
-    std::vector<std::string> reference_tokens;
-};
+    @note The scanner is independent of the current locale. Internally, the
+          locale's decimal point is used instead of `.` to work with the
+          locale-dependent converters.
+    */
+    token_type scan_number()
+    {
+        // reset yytext to store the number's bytes
+        reset();
 
-/*!
-@brief a class to store JSON values
+        // the type of the parsed number; initially set to unsigned; will be
+        // changed if minus sign, decimal point or exponent is read
+        token_type number_type = token_type::value_unsigned;
 
-@tparam ObjectType type for JSON objects (`std::map` by default; will be used
-in @ref object_t)
-@tparam ArrayType type for JSON arrays (`std::vector` by default; will be used
-in @ref array_t)
-@tparam StringType type for JSON strings and object keys (`std::string` by
-default; will be used in @ref string_t)
-@tparam BooleanType type for JSON booleans (`bool` by default; will be used
-in @ref boolean_t)
-@tparam NumberIntegerType type for JSON integer numbers (`int64_t` by
-default; will be used in @ref number_integer_t)
-@tparam NumberUnsignedType type for JSON unsigned integer numbers (@c
-`uint64_t` by default; will be used in @ref number_unsigned_t)
-@tparam NumberFloatType type for JSON floating-point numbers (`double` by
-default; will be used in @ref number_float_t)
-@tparam AllocatorType type of the allocator to use (`std::allocator` by
-default)
-@tparam JSONSerializer the serializer to resolve internal calls to `to_json()`
-and `from_json()` (@ref adl_serializer by default)
+        // state (init): we just found out we need to scan a number
+        switch (current)
+        {
+            case '-':
+            {
+                add(current);
+                goto scan_number_minus;
+            }
 
-@requirement The class satisfies the following concept requirements:
-- Basic
- - [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible):
-   JSON values can be default constructed. The result will be a JSON null
-   value.
- - [MoveConstructible](http://en.cppreference.com/w/cpp/concept/MoveConstructible):
-   A JSON value can be constructed from an rvalue argument.
- - [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible):
-   A JSON value can be copy-constructed from an lvalue expression.
- - [MoveAssignable](http://en.cppreference.com/w/cpp/concept/MoveAssignable):
-   A JSON value van be assigned from an rvalue argument.
- - [CopyAssignable](http://en.cppreference.com/w/cpp/concept/CopyAssignable):
-   A JSON value can be copy-assigned from an lvalue expression.
- - [Destructible](http://en.cppreference.com/w/cpp/concept/Destructible):
-   JSON values can be destructed.
-- Layout
- - [StandardLayoutType](http://en.cppreference.com/w/cpp/concept/StandardLayoutType):
-   JSON values have
-   [standard layout](http://en.cppreference.com/w/cpp/language/data_members#Standard_layout):
-   All non-static data members are private and standard layout types, the
-   class has no virtual functions or (virtual) base classes.
-- Library-wide
- - [EqualityComparable](http://en.cppreference.com/w/cpp/concept/EqualityComparable):
-   JSON values can be compared with `==`, see @ref
-   operator==(const_reference,const_reference).
- - [LessThanComparable](http://en.cppreference.com/w/cpp/concept/LessThanComparable):
-   JSON values can be compared with `<`, see @ref
-   operator<(const_reference,const_reference).
- - [Swappable](http://en.cppreference.com/w/cpp/concept/Swappable):
-   Any JSON lvalue or rvalue of can be swapped with any lvalue or rvalue of
-   other compatible types, using unqualified function call @ref swap().
- - [NullablePointer](http://en.cppreference.com/w/cpp/concept/NullablePointer):
-   JSON values can be compared against `std::nullptr_t` objects which are used
-   to model the `null` value.
-- Container
- - [Container](http://en.cppreference.com/w/cpp/concept/Container):
-   JSON values can be used like STL containers and provide iterator access.
- - [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer);
-   JSON values can be used like STL containers and provide reverse iterator
-   access.
+            case '0':
+            {
+                add(current);
+                goto scan_number_zero;
+            }
 
-@invariant The member variables @a m_value and @a m_type have the following
-relationship:
-- If `m_type == value_t::object`, then `m_value.object != nullptr`.
-- If `m_type == value_t::array`, then `m_value.array != nullptr`.
-- If `m_type == value_t::string`, then `m_value.string != nullptr`.
-The invariants are checked by member function assert_invariant().
+            case '1':
+            case '2':
+            case '3':
+            case '4':
+            case '5':
+            case '6':
+            case '7':
+            case '8':
+            case '9':
+            {
+                add(current);
+                goto scan_number_any1;
+            }
 
-@internal
-@note ObjectType trick from http://stackoverflow.com/a/9860911
-@endinternal
+            default:
+            {
+                // all other characters are rejected outside scan_number()
+                assert(false); // LCOV_EXCL_LINE
+            }
+        }
 
-@see [RFC 7159: The JavaScript Object Notation (JSON) Data Interchange
-Format](http://rfc7159.net/rfc7159)
+scan_number_minus:
+        // state: we just parsed a leading minus sign
+        number_type = token_type::value_integer;
+        switch (get())
+        {
+            case '0':
+            {
+                add(current);
+                goto scan_number_zero;
+            }
 
-@since version 1.0.0
+            case '1':
+            case '2':
+            case '3':
+            case '4':
+            case '5':
+            case '6':
+            case '7':
+            case '8':
+            case '9':
+            {
+                add(current);
+                goto scan_number_any1;
+            }
 
-@nosubgrouping
-*/
-NLOHMANN_BASIC_JSON_TPL_DECLARATION
-class basic_json
-{
-  private:
-    template<detail::value_t> friend struct detail::external_constructor;
-    /// workaround type for MSVC
-    using basic_json_t = NLOHMANN_BASIC_JSON_TPL;
-    friend ::nlohmann::json_pointer;
+            default:
+            {
+                error_message = "invalid number; expected digit after '-'";
+                return token_type::parse_error;
+            }
+        }
 
-  public:
-    using value_t = detail::value_t;
-    // forward declarations
-    template<typename U> class iter_impl;
-    template<typename Base> class json_reverse_iterator;
-    using json_pointer = ::nlohmann::json_pointer;
-    template<typename T, typename SFINAE>
-    using json_serializer = JSONSerializer<T, SFINAE>;
+scan_number_zero:
+        // state: we just parse a zero (maybe with a leading minus sign)
+        switch (get())
+        {
+            case '.':
+            {
+                add(decimal_point_char);
+                goto scan_number_decimal1;
+            }
 
+            case 'e':
+            case 'E':
+            {
+                add(current);
+                goto scan_number_exponent;
+            }
 
-    ////////////////
-    // exceptions //
-    ////////////////
+            default:
+            {
+                goto scan_number_done;
+            }
+        }
 
-    /// @name exceptions
-    /// Classes to implement user-defined exceptions.
-    /// @{
+scan_number_any1:
+        // state: we just parsed a number 0-9 (maybe with a leading minus sign)
+        switch (get())
+        {
+            case '0':
+            case '1':
+            case '2':
+            case '3':
+            case '4':
+            case '5':
+            case '6':
+            case '7':
+            case '8':
+            case '9':
+            {
+                add(current);
+                goto scan_number_any1;
+            }
 
-    /// @copydoc detail::exception
-    using exception = detail::exception;
-    /// @copydoc detail::parse_error
-    using parse_error = detail::parse_error;
-    /// @copydoc detail::invalid_iterator
-    using invalid_iterator = detail::invalid_iterator;
-    /// @copydoc detail::type_error
-    using type_error = detail::type_error;
-    /// @copydoc detail::out_of_range
-    using out_of_range = detail::out_of_range;
-    /// @copydoc detail::other_error
-    using other_error = detail::other_error;
+            case '.':
+            {
+                add(decimal_point_char);
+                goto scan_number_decimal1;
+            }
 
-    /// @}
+            case 'e':
+            case 'E':
+            {
+                add(current);
+                goto scan_number_exponent;
+            }
 
+            default:
+            {
+                goto scan_number_done;
+            }
+        }
 
-    /////////////////////
-    // container types //
-    /////////////////////
+scan_number_decimal1:
+        // state: we just parsed a decimal point
+        number_type = token_type::value_float;
+        switch (get())
+        {
+            case '0':
+            case '1':
+            case '2':
+            case '3':
+            case '4':
+            case '5':
+            case '6':
+            case '7':
+            case '8':
+            case '9':
+            {
+                add(current);
+                goto scan_number_decimal2;
+            }
 
-    /// @name container types
-    /// The canonic container types to use @ref basic_json like any other STL
-    /// container.
-    /// @{
+            default:
+            {
+                error_message = "invalid number; expected digit after '.'";
+                return token_type::parse_error;
+            }
+        }
 
-    /// the type of elements in a basic_json container
-    using value_type = basic_json;
+scan_number_decimal2:
+        // we just parsed at least one number after a decimal point
+        switch (get())
+        {
+            case '0':
+            case '1':
+            case '2':
+            case '3':
+            case '4':
+            case '5':
+            case '6':
+            case '7':
+            case '8':
+            case '9':
+            {
+                add(current);
+                goto scan_number_decimal2;
+            }
 
-    /// the type of an element reference
-    using reference = value_type&;
-    /// the type of an element const reference
-    using const_reference = const value_type&;
+            case 'e':
+            case 'E':
+            {
+                add(current);
+                goto scan_number_exponent;
+            }
 
-    /// a type to represent differences between iterators
-    using difference_type = std::ptrdiff_t;
-    /// a type to represent container sizes
-    using size_type = std::size_t;
+            default:
+            {
+                goto scan_number_done;
+            }
+        }
 
-    /// the allocator type
-    using allocator_type = AllocatorType<basic_json>;
+scan_number_exponent:
+        // we just parsed an exponent
+        number_type = token_type::value_float;
+        switch (get())
+        {
+            case '+':
+            case '-':
+            {
+                add(current);
+                goto scan_number_sign;
+            }
 
-    /// the type of an element pointer
-    using pointer = typename std::allocator_traits<allocator_type>::pointer;
-    /// the type of an element const pointer
-    using const_pointer = typename std::allocator_traits<allocator_type>::const_pointer;
+            case '0':
+            case '1':
+            case '2':
+            case '3':
+            case '4':
+            case '5':
+            case '6':
+            case '7':
+            case '8':
+            case '9':
+            {
+                add(current);
+                goto scan_number_any2;
+            }
 
-    /// an iterator for a basic_json container
-    using iterator = iter_impl<basic_json>;
-    /// a const iterator for a basic_json container
-    using const_iterator = iter_impl<const basic_json>;
-    /// a reverse iterator for a basic_json container
-    using reverse_iterator = json_reverse_iterator<typename basic_json::iterator>;
-    /// a const reverse iterator for a basic_json container
-    using const_reverse_iterator = json_reverse_iterator<typename basic_json::const_iterator>;
+            default:
+            {
+                error_message =
+                    "invalid number; expected '+', '-', or digit after exponent";
+                return token_type::parse_error;
+            }
+        }
 
-    /// @}
+scan_number_sign:
+        // we just parsed an exponent sign
+        switch (get())
+        {
+            case '0':
+            case '1':
+            case '2':
+            case '3':
+            case '4':
+            case '5':
+            case '6':
+            case '7':
+            case '8':
+            case '9':
+            {
+                add(current);
+                goto scan_number_any2;
+            }
+
+            default:
+            {
+                error_message = "invalid number; expected digit after exponent sign";
+                return token_type::parse_error;
+            }
+        }
+
+scan_number_any2:
+        // we just parsed a number after the exponent or exponent sign
+        switch (get())
+        {
+            case '0':
+            case '1':
+            case '2':
+            case '3':
+            case '4':
+            case '5':
+            case '6':
+            case '7':
+            case '8':
+            case '9':
+            {
+                add(current);
+                goto scan_number_any2;
+            }
+
+            default:
+            {
+                goto scan_number_done;
+            }
+        }
+
+scan_number_done:
+        // unget the character after the number (we only read it to know
+        // that we are done scanning a number)
+        --chars_read;
+        next_unget = true;
+
+        // terminate token
+        add('\0');
+        --yylen;
+
+        // try to parse integers first and fall back to floats
+        if (number_type == token_type::value_unsigned)
+        {
+            char* endptr = nullptr;
+            errno = 0;
+            const auto x = std::strtoull(yytext.data(), &endptr, 10);
+
+            // we checked the number format before
+            assert(endptr == yytext.data() + yylen);
+
+            if (errno == 0)
+            {
+                value_unsigned = static_cast<number_unsigned_t>(x);
+                if (value_unsigned == x)
+                {
+                    return token_type::value_unsigned;
+                }
+            }
+        }
+        else if (number_type == token_type::value_integer)
+        {
+            char* endptr = nullptr;
+            errno = 0;
+            const auto x = std::strtoll(yytext.data(), &endptr, 10);
+
+            // we checked the number format before
+            assert(endptr == yytext.data() + yylen);
+
+            if (errno == 0)
+            {
+                value_integer = static_cast<number_integer_t>(x);
+                if (value_integer == x)
+                {
+                    return token_type::value_integer;
+                }
+            }
+        }
 
+        // this code is reached if we parse a floating-point number or if
+        // an integer conversion above failed
+        strtof(value_float, yytext.data(), nullptr);
+        return token_type::value_float;
+    }
 
     /*!
-    @brief returns the allocator associated with the container
+    @param[in] literal_text  the literal text to expect
+    @param[in] length        the length of the passed literal text
+    @param[in] return_type   the token type to return on success
     */
-    static allocator_type get_allocator()
+    token_type scan_literal(const char* literal_text, const size_t length,
+                            token_type return_type)
     {
-        return allocator_type();
+        assert(current == literal_text[0]);
+        for (size_t i = 1; i < length; ++i)
+        {
+            if (JSON_UNLIKELY(get() != literal_text[i]))
+            {
+                error_message = "invalid literal";
+                return token_type::parse_error;
+            }
+        }
+        return return_type;
     }
 
-    /*!
-    @brief returns version information on the library
+    /////////////////////
+    // input management
+    /////////////////////
 
-    This function returns a JSON object with information about the library,
-    including the version number and information on the platform and compiler.
+    /// reset yytext
+    void reset() noexcept
+    {
+        yylen = 0;
+        start_pos = chars_read - 1;
+    }
 
-    @return JSON object holding version information
-    key         | description
-    ----------- | ---------------
-    `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).
-    `copyright` | The copyright line for the library as string.
-    `name`      | The name of the library as string.
-    `platform`  | The used platform as string. Possible values are `win32`, `linux`, `apple`, `unix`, and `unknown`.
-    `url`       | The URL of the project as string.
-    `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).
+    /// get a character from the input
+    int get()
+    {
+        ++chars_read;
+        return next_unget ? (next_unget = false, current)
+               : (current = ia->get_character());
+    }
 
-    @liveexample{The following code shows an example output of the `meta()`
-    function.,meta}
+    /// add a character to yytext
+    void add(int c)
+    {
+        // resize yytext if necessary; this condition is deemed unlikely,
+        // because we start with a 1024-byte buffer
+        if (JSON_UNLIKELY((yylen + 1 > yytext.capacity())))
+        {
+            yytext.resize(2 * yytext.capacity(), '\0');
+        }
+        assert(yylen < yytext.size());
+        yytext[yylen++] = static_cast<char>(c);
+    }
 
-    @complexity Constant.
+  public:
+    /////////////////////
+    // value getters
+    /////////////////////
 
-    @since 2.1.0
-    */
-    static basic_json meta()
+    /// return integer value
+    constexpr number_integer_t get_number_integer() const noexcept
     {
-        basic_json result;
+        return value_integer;
+    }
 
-        result["copyright"] = "(C) 2013-2017 Niels Lohmann";
-        result["name"] = "JSON for Modern C++";
-        result["url"] = "https://github.com/nlohmann/json";
-        result["version"] =
-        {
-            {"string", "2.1.1"}, {"major", 2}, {"minor", 1}, {"patch", 1}
-        };
+    /// return unsigned integer value
+    constexpr number_unsigned_t get_number_unsigned() const noexcept
+    {
+        return value_unsigned;
+    }
 
-#ifdef _WIN32
-        result["platform"] = "win32";
-#elif defined __linux__
-        result["platform"] = "linux";
-#elif defined __APPLE__
-        result["platform"] = "apple";
-#elif defined __unix__
-        result["platform"] = "unix";
-#else
-        result["platform"] = "unknown";
-#endif
-
-#if defined(__clang__)
-        result["compiler"] = {{"family", "clang"}, {"version", __clang_version__}};
-#elif defined(__ICC) || defined(__INTEL_COMPILER)
-        result["compiler"] = {{"family", "icc"}, {"version", __INTEL_COMPILER}};
-#elif defined(__GNUC__) || defined(__GNUG__)
-        result["compiler"] = {{"family", "gcc"}, {"version", std::to_string(__GNUC__) + "." + std::to_string(__GNUC_MINOR__) + "." + std::to_string(__GNUC_PATCHLEVEL__)}};
-#elif defined(__HP_cc) || defined(__HP_aCC)
-        result["compiler"] = "hp"
-#elif defined(__IBMCPP__)
-        result["compiler"] = {{"family", "ilecpp"}, {"version", __IBMCPP__}};
-#elif defined(_MSC_VER)
-        result["compiler"] = {{"family", "msvc"}, {"version", _MSC_VER}};
-#elif defined(__PGI)
-        result["compiler"] = {{"family", "pgcpp"}, {"version", __PGI}};
-#elif defined(__SUNPRO_CC)
-        result["compiler"] = {{"family", "sunpro"}, {"version", __SUNPRO_CC}};
-#else
-        result["compiler"] = {{"family", "unknown"}, {"version", "unknown"}};
-#endif
-
-#ifdef __cplusplus
-        result["compiler"]["c++"] = std::to_string(__cplusplus);
-#else
-        result["compiler"]["c++"] = "unknown";
-#endif
-        return result;
+    /// return floating-point value
+    constexpr number_float_t get_number_float() const noexcept
+    {
+        return value_float;
     }
 
+    /// return string value
+    const std::string get_string()
+    {
+        // yytext cannot be returned as char*, because it may contain a
+        // null byte (parsed as "\u0000")
+        return std::string(yytext.data(), yylen);
+    }
 
-    ///////////////////////////
-    // JSON value data types //
-    ///////////////////////////
+    /////////////////////
+    // diagnostics
+    /////////////////////
 
-    /// @name JSON value data types
-    /// The data types to store a JSON value. These types are derived from
-    /// the template arguments passed to class @ref basic_json.
-    /// @{
+    /// return position of last read token
+    constexpr size_t get_position() const noexcept
+    {
+        return chars_read;
+    }
 
-    /*!
-    @brief a type for an object
+    /// return the last read token (for errors only)
+    std::string get_token_string() const
+    {
+        // get the raw byte sequence of the last token
+        std::string s = ia->read(start_pos, chars_read - start_pos);
 
-    [RFC 7159](http://rfc7159.net/rfc7159) describes JSON objects as follows:
-    > An object is an unordered collection of zero or more name/value pairs,
-    > where a name is a string and a value is a string, number, boolean, null,
-    > object, or array.
+        // escape control characters
+        std::string result;
+        for (auto c : s)
+        {
+            if (c == '\0' or c == std::char_traits<char>::eof())
+            {
+                // ignore EOF
+                continue;
+            }
+            else if ('\x00' <= c and c <= '\x1f')
+            {
+                // escape control characters
+                std::stringstream ss;
+                ss << "<U+" << std::setw(4) << std::uppercase << std::setfill('0')
+                   << std::hex << static_cast<int>(c) << ">";
+                result += ss.str();
+            }
+            else
+            {
+                // add character as is
+                result.append(1, c);
+            }
+        }
 
-    To store objects in C++, a type is defined by the template parameters
-    described below.
+        return result;
+    }
 
-    @tparam ObjectType  the container to store objects (e.g., `std::map` or
-    `std::unordered_map`)
-    @tparam StringType the type of the keys or names (e.g., `std::string`).
-    The comparison function `std::less<StringType>` is used to order elements
-    inside the container.
-    @tparam AllocatorType the allocator to use for objects (e.g.,
-    `std::allocator`)
+    /// return syntax error message
+    constexpr const char* get_error_message() const noexcept
+    {
+        return error_message;
+    }
 
-    #### Default type
+    /////////////////////
+    // actual scanner
+    /////////////////////
 
-    With the default values for @a ObjectType (`std::map`), @a StringType
-    (`std::string`), and @a AllocatorType (`std::allocator`), the default
-    value for @a object_t is:
+    token_type scan()
+    {
+        // read next character and ignore whitespace
+        do
+        {
+            get();
+        }
+        while (current == ' ' or current == '\t' or current == '\n' or
+                current == '\r');
+
+        switch (current)
+        {
+            // structural characters
+            case '[':
+                return token_type::begin_array;
+            case ']':
+                return token_type::end_array;
+            case '{':
+                return token_type::begin_object;
+            case '}':
+                return token_type::end_object;
+            case ':':
+                return token_type::name_separator;
+            case ',':
+                return token_type::value_separator;
+
+            // literals
+            case 't':
+                return scan_literal("true", 4, token_type::literal_true);
+            case 'f':
+                return scan_literal("false", 5, token_type::literal_false);
+            case 'n':
+                return scan_literal("null", 4, token_type::literal_null);
+
+            // string
+            case '\"':
+                return scan_string();
+
+            // number
+            case '-':
+            case '0':
+            case '1':
+            case '2':
+            case '3':
+            case '4':
+            case '5':
+            case '6':
+            case '7':
+            case '8':
+            case '9':
+                return scan_number();
+
+            // end of input (the null byte is needed when parsing from
+            // string literals)
+            case '\0':
+            case std::char_traits<char>::eof():
+                return token_type::end_of_input;
+
+            // error
+            default:
+                error_message = "invalid literal";
+                return token_type::parse_error;
+        }
+    }
 
-    @code {.cpp}
-    std::map<
-      std::string, // key_type
-      basic_json, // value_type
-      std::less<std::string>, // key_compare
-      std::allocator<std::pair<const std::string, basic_json>> // allocator_type
-    >
-    @endcode
+  private:
+    /// input adapter
+    detail::input_adapter_t ia = nullptr;
 
-    #### Behavior
+    /// the current character
+    int current = std::char_traits<char>::eof();
 
-    The choice of @a object_t influences the behavior of the JSON class. With
-    the default type, objects have the following behavior:
+    /// whether get() should return the last character again
+    bool next_unget = false;
 
-    - When all names are unique, objects will be interoperable in the sense
-      that all software implementations receiving that object will agree on
-      the name-value mappings.
-    - When the names within an object are not unique, later stored name/value
-      pairs overwrite previously stored name/value pairs, leaving the used
-      names unique. For instance, `{"key": 1}` and `{"key": 2, "key": 1}` will
-      be treated as equal and both stored as `{"key": 1}`.
-    - Internally, name/value pairs are stored in lexicographical order of the
-      names. Objects will also be serialized (see @ref dump) in this order.
-      For instance, `{"b": 1, "a": 2}` and `{"a": 2, "b": 1}` will be stored
-      and serialized as `{"a": 2, "b": 1}`.
-    - When comparing objects, the order of the name/value pairs is irrelevant.
-      This makes objects interoperable in the sense that they will not be
-      affected by these differences. For instance, `{"b": 1, "a": 2}` and
-      `{"a": 2, "b": 1}` will be treated as equal.
+    /// the number of characters read
+    size_t chars_read = 0;
+    /// the start position of the current token
+    size_t start_pos = 0;
 
-    #### Limits
+    /// buffer for variable-length tokens (numbers, strings)
+    std::vector<char> yytext = std::vector<char>(1024, '\0');
+    /// current index in yytext
+    size_t yylen = 0;
 
-    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
-    > An implementation may set limits on the maximum depth of nesting.
+    /// a description of occurred lexer errors
+    const char* error_message = "";
 
-    In this class, the object's limit of nesting is not constraint explicitly.
-    However, a maximum depth of nesting may be introduced by the compiler or
-    runtime environment. A theoretical limit can be queried by calling the
-    @ref max_size function of a JSON object.
+    // number values
+    number_integer_t value_integer = 0;
+    number_unsigned_t value_unsigned = 0;
+    number_float_t value_float = 0;
 
-    #### Storage
+    /// the decimal point
+    const char decimal_point_char = '.';
+};
 
-    Objects are stored as pointers in a @ref basic_json type. That is, for any
-    access to object values, a pointer of type `object_t*` must be
-    dereferenced.
+/*!
+@brief syntax analysis
 
-    @sa @ref array_t -- type for an array value
+This class implements a recursive decent parser.
+*/
+template <typename BasicJsonType>
+class parser
+{
+    using number_integer_t = typename BasicJsonType::number_integer_t;
+    using number_unsigned_t = typename BasicJsonType::number_unsigned_t;
+    using number_float_t = typename BasicJsonType::number_float_t;
 
-    @since version 1.0.0
+    using lexer_t = lexer<BasicJsonType>;
+    using token_type = typename lexer_t::token_type;
 
-    @note The order name/value pairs are added to the object is *not*
-    preserved by the library. Therefore, iterating an object may return
-    name/value pairs in a different order than they were originally stored. In
-    fact, keys will be traversed in alphabetical order as `std::map` with
-    `std::less` is used by default. Please note this behavior conforms to [RFC
-    7159](http://rfc7159.net/rfc7159), because any order implements the
-    specified "unordered" nature of JSON objects.
-    */
-    using object_t = ObjectType<StringType,
-          basic_json,
-          std::less<StringType>,
-          AllocatorType<std::pair<const StringType,
-          basic_json>>>;
+  public:
+    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 a type for an array
+    using parser_callback_t =
+        std::function<bool(int depth, parse_event_t event, BasicJsonType& parsed)>;
 
-    [RFC 7159](http://rfc7159.net/rfc7159) describes JSON arrays as follows:
-    > An array is an ordered sequence of zero or more values.
+    /// a parser reading from an input adapter
+    explicit parser(detail::input_adapter_t adapter,
+                    const parser_callback_t cb = nullptr)
+        : callback(cb), m_lexer(adapter) {}
 
-    To store objects in C++, a type is defined by the template parameters
-    explained below.
+    /*!
+    @brief public parser interface
 
-    @tparam ArrayType  container type to store arrays (e.g., `std::vector` or
-    `std::list`)
-    @tparam AllocatorType allocator to use for arrays (e.g., `std::allocator`)
+    @param[in] strict  whether to expect the last token to be EOF
+    @return parsed JSON value
 
-    #### Default type
+    @throw parse_error.101 in case of an unexpected token
+    @throw parse_error.102 if to_unicode fails or surrogate error
+    @throw parse_error.103 if to_unicode fails
+    */
+    BasicJsonType parse(const bool strict = true)
+    {
+        // read first token
+        get_token();
 
-    With the default values for @a ArrayType (`std::vector`) and @a
-    AllocatorType (`std::allocator`), the default value for @a array_t is:
+        BasicJsonType result = parse_internal(true);
+        result.assert_invariant();
 
-    @code {.cpp}
-    std::vector<
-      basic_json, // value_type
-      std::allocator<basic_json> // allocator_type
-    >
-    @endcode
+        if (strict)
+        {
+            get_token();
+            expect(token_type::end_of_input);
+        }
 
-    #### Limits
+        // return parser result and replace it with null in case the
+        // top-level value was discarded by the callback function
+        return result.is_discarded() ? BasicJsonType() : std::move(result);
+    }
 
-    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
-    > An implementation may set limits on the maximum depth of nesting.
+    /*!
+    @brief public accept interface
 
-    In this class, the array's limit of nesting is not constraint explicitly.
-    However, a maximum depth of nesting may be introduced by the compiler or
-    runtime environment. A theoretical limit can be queried by calling the
-    @ref max_size function of a JSON array.
+    @param[in] strict  whether to expect the last token to be EOF
+    @return whether the input is a proper JSON text
+    */
+    bool accept(const bool strict = true)
+    {
+        // read first token
+        get_token();
 
-    #### Storage
+        if (not accept_internal())
+        {
+            return false;
+        }
 
-    Arrays are stored as pointers in a @ref basic_json type. That is, for any
-    access to array values, a pointer of type `array_t*` must be dereferenced.
+        if (strict and get_token() != token_type::end_of_input)
+        {
+            return false;
+        }
 
-    @sa @ref object_t -- type for an object value
+        return true;
+    }
 
-    @since version 1.0.0
+  private:
+    /*!
+    @brief the actual parser
+    @throw parse_error.101 in case of an unexpected token
+    @throw parse_error.102 if to_unicode fails or surrogate error
+    @throw parse_error.103 if to_unicode fails
     */
-    using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;
+    BasicJsonType parse_internal(bool keep)
+    {
+        auto result = BasicJsonType(value_t::discarded);
 
-    /*!
-    @brief a type for a string
+        switch (last_token)
+        {
+            case token_type::begin_object:
+            {
+                if (keep and (not callback or
+                              ((keep = callback(depth++, parse_event_t::object_start,
+                                                result)) != 0)))
+                {
+                    // explicitly set result to object to cope with {}
+                    result.m_type = value_t::object;
+                    result.m_value = value_t::object;
+                }
 
-    [RFC 7159](http://rfc7159.net/rfc7159) describes JSON strings as follows:
-    > A string is a sequence of zero or more Unicode characters.
+                // read next token
+                get_token();
 
-    To store objects in C++, a type is defined by the template parameter
-    described below. Unicode values are split by the JSON class into
-    byte-sized characters during deserialization.
+                // closing } -> we are done
+                if (last_token == token_type::end_object)
+                {
+                    if (keep and callback and
+                            not callback(--depth, parse_event_t::object_end, result))
+                    {
+                        result = BasicJsonType(value_t::discarded);
+                    }
+                    return result;
+                }
 
-    @tparam StringType  the container to store strings (e.g., `std::string`).
-    Note this container is used for keys/names in objects, see @ref object_t.
+                // parse values
+                while (true)
+                {
+                    // store key
+                    expect(token_type::value_string);
+                    const auto key = m_lexer.get_string();
 
-    #### Default type
+                    bool keep_tag = false;
+                    if (keep)
+                    {
+                        if (callback)
+                        {
+                            BasicJsonType k(key);
+                            keep_tag = callback(depth, parse_event_t::key, k);
+                        }
+                        else
+                        {
+                            keep_tag = true;
+                        }
+                    }
 
-    With the default values for @a StringType (`std::string`), the default
-    value for @a string_t is:
+                    // parse separator (:)
+                    get_token();
+                    expect(token_type::name_separator);
 
-    @code {.cpp}
-    std::string
-    @endcode
+                    // parse and add value
+                    get_token();
+                    auto value = parse_internal(keep);
+                    if (keep and keep_tag and not value.is_discarded())
+                    {
+                        result[key] = std::move(value);
+                    }
 
-    #### Encoding
+                    // comma -> next value
+                    get_token();
+                    if (last_token == token_type::value_separator)
+                    {
+                        get_token();
+                        continue;
+                    }
 
-    Strings are stored in UTF-8 encoding. Therefore, functions like
-    `std::string::size()` or `std::string::length()` return the number of
-    bytes in the string rather than the number of characters or glyphs.
+                    // closing }
+                    expect(token_type::end_object);
+                    break;
+                }
 
-    #### String comparison
-
-    [RFC 7159](http://rfc7159.net/rfc7159) states:
-    > Software implementations are typically required to test names of object
-    > members for equality. Implementations that transform the textual
-    > representation into sequences of Unicode code units and then perform the
-    > comparison numerically, code unit by code unit, are interoperable in the
-    > sense that implementations will agree in all cases on equality or
-    > inequality of two strings. For example, implementations that compare
-    > strings with escaped characters unconverted may incorrectly find that
-    > `"a\\b"` and `"a\u005Cb"` are not equal.
+                if (keep and callback and
+                        not callback(--depth, parse_event_t::object_end, result))
+                {
+                    result = BasicJsonType(value_t::discarded);
+                }
 
-    This implementation is interoperable as it does compare strings code unit
-    by code unit.
+                return result;
+            }
 
-    #### Storage
+            case token_type::begin_array:
+            {
+                if (keep and (not callback or
+                              ((keep = callback(depth++, parse_event_t::array_start,
+                                                result)) != 0)))
+                {
+                    // explicitly set result to object to cope with []
+                    result.m_type = value_t::array;
+                    result.m_value = value_t::array;
+                }
 
-    String values are stored as pointers in a @ref basic_json type. That is,
-    for any access to string values, a pointer of type `string_t*` must be
-    dereferenced.
+                // read next token
+                get_token();
 
-    @since version 1.0.0
-    */
-    using string_t = StringType;
+                // closing ] -> we are done
+                if (last_token == token_type::end_array)
+                {
+                    if (callback and
+                            not callback(--depth, parse_event_t::array_end, result))
+                    {
+                        result = BasicJsonType(value_t::discarded);
+                    }
+                    return result;
+                }
 
-    /*!
-    @brief a type for a boolean
+                // parse values
+                while (true)
+                {
+                    // parse value
+                    auto value = parse_internal(keep);
+                    if (keep and not value.is_discarded())
+                    {
+                        result.push_back(std::move(value));
+                    }
 
-    [RFC 7159](http://rfc7159.net/rfc7159) implicitly describes a boolean as a
-    type which differentiates the two literals `true` and `false`.
+                    // comma -> next value
+                    get_token();
+                    if (last_token == token_type::value_separator)
+                    {
+                        get_token();
+                        continue;
+                    }
 
-    To store objects in C++, a type is defined by the template parameter @a
-    BooleanType which chooses the type to use.
+                    // closing ]
+                    expect(token_type::end_array);
+                    break;
+                }
 
-    #### Default type
+                if (keep and callback and
+                        not callback(--depth, parse_event_t::array_end, result))
+                {
+                    result = BasicJsonType(value_t::discarded);
+                }
 
-    With the default values for @a BooleanType (`bool`), the default value for
-    @a boolean_t is:
+                return result;
+            }
 
-    @code {.cpp}
-    bool
-    @endcode
+            case token_type::literal_null:
+            {
+                result.m_type = value_t::null;
+                break;
+            }
 
-    #### Storage
+            case token_type::value_string:
+            {
+                result = BasicJsonType(m_lexer.get_string());
+                break;
+            }
 
-    Boolean values are stored directly inside a @ref basic_json type.
+            case token_type::literal_true:
+            {
+                result.m_type = value_t::boolean;
+                result.m_value = true;
+                break;
+            }
 
-    @since version 1.0.0
-    */
-    using boolean_t = BooleanType;
+            case token_type::literal_false:
+            {
+                result.m_type = value_t::boolean;
+                result.m_value = false;
+                break;
+            }
 
-    /*!
-    @brief a type for a number (integer)
+            case token_type::value_unsigned:
+            {
+                result.m_type = value_t::number_unsigned;
+                result.m_value = m_lexer.get_number_unsigned();
+                break;
+            }
 
-    [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
-    > The representation of numbers is similar to that used in most
-    > programming languages. A number is represented in base 10 using decimal
-    > digits. It contains an integer component that may be prefixed with an
-    > optional minus sign, which may be followed by a fraction part and/or an
-    > exponent part. Leading zeros are not allowed. (...) Numeric values that
-    > cannot be represented in the grammar below (such as Infinity and NaN)
-    > are not permitted.
+            case token_type::value_integer:
+            {
+                result.m_type = value_t::number_integer;
+                result.m_value = m_lexer.get_number_integer();
+                break;
+            }
 
-    This description includes both integer and floating-point numbers.
-    However, C++ allows more precise storage if it is known whether the number
-    is a signed integer, an unsigned integer or a floating-point number.
-    Therefore, three different types, @ref number_integer_t, @ref
-    number_unsigned_t and @ref number_float_t are used.
+            case token_type::value_float:
+            {
+                result.m_type = value_t::number_float;
+                result.m_value = m_lexer.get_number_float();
 
-    To store integer numbers in C++, a type is defined by the template
-    parameter @a NumberIntegerType which chooses the type to use.
+                // throw in case of infinity or NAN
+                if (JSON_UNLIKELY(not std::isfinite(result.m_value.number_float)))
+                {
+                    JSON_THROW(out_of_range::create(406, "number overflow parsing '" +
+                                                    m_lexer.get_token_string() +
+                                                    "'"));
+                }
 
-    #### Default type
+                break;
+            }
 
-    With the default values for @a NumberIntegerType (`int64_t`), the default
-    value for @a number_integer_t is:
+            case token_type::parse_error:
+            {
+                // using "uninitialized" to avoid "expected" message
+                expect(token_type::uninitialized);
+                break; // LCOV_EXCL_LINE
+            }
 
-    @code {.cpp}
-    int64_t
-    @endcode
+            default:
+            {
+                // the last token was unexpected; we expected a value
+                expect(token_type::literal_or_value);
+                break; // LCOV_EXCL_LINE
+            }
+        }
 
-    #### Default behavior
+        if (keep and callback and
+                not callback(depth, parse_event_t::value, result))
+        {
+            result = BasicJsonType(value_t::discarded);
+        }
+        return result;
+    }
 
-    - The restrictions about leading zeros is not enforced in C++. Instead,
-      leading zeros in integer literals lead to an interpretation as octal
-      number. Internally, the value will be stored as decimal number. For
-      instance, the C++ integer literal `010` will be serialized to `8`.
-      During deserialization, leading zeros yield an error.
-    - Not-a-number (NaN) values will be serialized to `null`.
+    /*!
+    @brief the acutal acceptor
 
-    #### Limits
+    @invariant 1. The last token is not yet processed. Therefore, the
+                  caller of this function must make sure a token has
+                  been read.
+               2. When this function returns, the last token is processed.
+                  That is, the last read character was already considered.
 
-    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
-    > An implementation may set limits on the range and precision of numbers.
+    This invariant makes sure that no token needs to be "unput".
+    */
+    bool accept_internal()
+    {
+        switch (last_token)
+        {
+            case token_type::begin_object:
+            {
+                // read next token
+                get_token();
 
-    When the default type is used, the maximal integer number that can be
-    stored is `9223372036854775807` (INT64_MAX) and the minimal integer number
-    that can be stored is `-9223372036854775808` (INT64_MIN). Integer numbers
-    that are out of range will yield over/underflow when used in a
-    constructor. During deserialization, too large or small integer numbers
-    will be automatically be stored as @ref number_unsigned_t or @ref
-    number_float_t.
+                // closing } -> we are done
+                if (last_token == token_type::end_object)
+                {
+                    return true;
+                }
 
-    [RFC 7159](http://rfc7159.net/rfc7159) further states:
-    > Note that when such software is used, numbers that are integers and are
-    > in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
-    > that implementations will agree exactly on their numeric values.
+                // parse values
+                while (true)
+                {
+                    // parse key
+                    if (last_token != token_type::value_string)
+                    {
+                        return false;
+                    }
 
-    As this range is a subrange of the exactly supported range [INT64_MIN,
-    INT64_MAX], this class's integer type is interoperable.
+                    // parse separator (:)
+                    get_token();
+                    if (last_token != token_type::name_separator)
+                    {
+                        return false;
+                    }
 
-    #### Storage
+                    // parse value
+                    get_token();
+                    if (not accept_internal())
+                    {
+                        return false;
+                    }
 
-    Integer number values are stored directly inside a @ref basic_json type.
+                    // comma -> next value
+                    get_token();
+                    if (last_token == token_type::value_separator)
+                    {
+                        get_token();
+                        continue;
+                    }
 
-    @sa @ref number_float_t -- type for number values (floating-point)
+                    // closing }
+                    if (last_token != token_type::end_object)
+                    {
+                        return false;
+                    }
 
-    @sa @ref number_unsigned_t -- type for number values (unsigned integer)
+                    return true;
+                }
+            }
 
-    @since version 1.0.0
-    */
-    using number_integer_t = NumberIntegerType;
+            case token_type::begin_array:
+            {
+                // read next token
+                get_token();
 
-    /*!
-    @brief a type for a number (unsigned)
+                // closing ] -> we are done
+                if (last_token == token_type::end_array)
+                {
+                    return true;
+                }
 
-    [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
-    > The representation of numbers is similar to that used in most
-    > programming languages. A number is represented in base 10 using decimal
-    > digits. It contains an integer component that may be prefixed with an
-    > optional minus sign, which may be followed by a fraction part and/or an
-    > exponent part. Leading zeros are not allowed. (...) Numeric values that
-    > cannot be represented in the grammar below (such as Infinity and NaN)
-    > are not permitted.
+                // parse values
+                while (true)
+                {
+                    // parse value
+                    if (not accept_internal())
+                    {
+                        return false;
+                    }
 
-    This description includes both integer and floating-point numbers.
-    However, C++ allows more precise storage if it is known whether the number
-    is a signed integer, an unsigned integer or a floating-point number.
-    Therefore, three different types, @ref number_integer_t, @ref
-    number_unsigned_t and @ref number_float_t are used.
+                    // comma -> next value
+                    get_token();
+                    if (last_token == token_type::value_separator)
+                    {
+                        get_token();
+                        continue;
+                    }
 
-    To store unsigned integer numbers in C++, a type is defined by the
-    template parameter @a NumberUnsignedType which chooses the type to use.
+                    // closing ]
+                    if (last_token != token_type::end_array)
+                    {
+                        return false;
+                    }
 
-    #### Default type
+                    return true;
+                }
+            }
 
-    With the default values for @a NumberUnsignedType (`uint64_t`), the
-    default value for @a number_unsigned_t is:
+            case token_type::literal_false:
+            case token_type::literal_null:
+            case token_type::literal_true:
+            case token_type::value_float:
+            case token_type::value_integer:
+            case token_type::value_string:
+            case token_type::value_unsigned:
+            {
+                return true;
+            }
 
-    @code {.cpp}
-    uint64_t
-    @endcode
+            default:
+            {
+                // the last token was unexpected
+                return false;
+            }
+        }
+    }
 
-    #### Default behavior
+    /// get next token from lexer
+    token_type get_token()
+    {
+        return (last_token = m_lexer.scan());
+    }
 
-    - The restrictions about leading zeros is not enforced in C++. Instead,
-      leading zeros in integer literals lead to an interpretation as octal
-      number. Internally, the value will be stored as decimal number. For
-      instance, the C++ integer literal `010` will be serialized to `8`.
-      During deserialization, leading zeros yield an error.
-    - Not-a-number (NaN) values will be serialized to `null`.
+    /*!
+    @throw parse_error.101 if expected token did not occur
+    */
+    void expect(token_type t)
+    {
+        if (JSON_UNLIKELY(t != last_token))
+        {
+            errored = true;
+            expected = t;
+            throw_exception();
+        }
+    }
 
-    #### Limits
+    [[noreturn]] void throw_exception() const
+    {
+        std::string error_msg = "syntax error - ";
+        if (last_token == token_type::parse_error)
+        {
+            error_msg += std::string(m_lexer.get_error_message()) + "; last read: '" +
+                         m_lexer.get_token_string() + "'";
+        }
+        else
+        {
+            error_msg +=
+                "unexpected " + std::string(lexer_t::token_type_name(last_token));
+        }
 
-    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
-    > An implementation may set limits on the range and precision of numbers.
+        if (expected != token_type::uninitialized)
+        {
+            error_msg +=
+                "; expected " + std::string(lexer_t::token_type_name(expected));
+        }
 
-    When the default type is used, the maximal integer number that can be
-    stored is `18446744073709551615` (UINT64_MAX) and the minimal integer
-    number that can be stored is `0`. Integer numbers that are out of range
-    will yield over/underflow when used in a constructor. During
-    deserialization, too large or small integer numbers will be automatically
-    be stored as @ref number_integer_t or @ref number_float_t.
+        JSON_THROW(parse_error::create(101, m_lexer.get_position(), error_msg));
+    }
 
-    [RFC 7159](http://rfc7159.net/rfc7159) further states:
-    > Note that when such software is used, numbers that are integers and are
-    > in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
-    > that implementations will agree exactly on their numeric values.
+  private:
+    /// current level of recursion
+    int depth = 0;
+    /// callback function
+    const parser_callback_t callback = nullptr;
+    /// the type of the last read token
+    token_type last_token = token_type::uninitialized;
+    /// the lexer
+    lexer_t m_lexer;
+    /// whether a syntax error occurred
+    bool errored = false;
+    /// possible reason for the syntax error
+    token_type expected = token_type::uninitialized;
+};
+} // namespace detail
 
-    As this range is a subrange (when considered in conjunction with the
-    number_integer_t type) of the exactly supported range [0, UINT64_MAX],
-    this class's integer type is interoperable.
+/// namespace to hold default `to_json` / `from_json` functions
+namespace
+{
+constexpr const auto& to_json = detail::static_const<detail::to_json_fn>::value;
+constexpr const auto& from_json = detail::static_const<detail::from_json_fn>::value;
+}
 
-    #### Storage
 
-    Integer number values are stored directly inside a @ref basic_json type.
+/*!
+@brief default JSONSerializer template argument
 
-    @sa @ref number_float_t -- type for number values (floating-point)
-    @sa @ref number_integer_t -- type for number values (integer)
+This serializer ignores the template arguments and uses ADL
+([argument-dependent lookup](http://en.cppreference.com/w/cpp/language/adl))
+for serialization.
+*/
+template<typename, typename>
+struct adl_serializer
+{
+    /*!
+    @brief convert a JSON value to any value type
 
-    @since version 2.0.0
+    This function is usually called by the `get()` function of the
+    @ref basic_json class (either explicit or via conversion operators).
+
+    @param[in] j         JSON value to read from
+    @param[in,out] val  value to write to
     */
-    using number_unsigned_t = NumberUnsignedType;
+    template<typename BasicJsonType, typename ValueType>
+    static void from_json(BasicJsonType&& j, ValueType& val) noexcept(
+        noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), val)))
+    {
+        ::nlohmann::from_json(std::forward<BasicJsonType>(j), val);
+    }
 
     /*!
-    @brief a type for a number (floating-point)
-
-    [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
-    > The representation of numbers is similar to that used in most
-    > programming languages. A number is represented in base 10 using decimal
-    > digits. It contains an integer component that may be prefixed with an
-    > optional minus sign, which may be followed by a fraction part and/or an
-    > exponent part. Leading zeros are not allowed. (...) Numeric values that
-    > cannot be represented in the grammar below (such as Infinity and NaN)
-    > are not permitted.
+    @brief convert any value type to a JSON value
 
-    This description includes both integer and floating-point numbers.
-    However, C++ allows more precise storage if it is known whether the number
-    is a signed integer, an unsigned integer or a floating-point number.
-    Therefore, three different types, @ref number_integer_t, @ref
-    number_unsigned_t and @ref number_float_t are used.
+    This function is usually called by the constructors of the @ref basic_json
+    class.
 
-    To store floating-point numbers in C++, a type is defined by the template
-    parameter @a NumberFloatType which chooses the type to use.
+    @param[in,out] j  JSON value to write to
+    @param[in] val     value to read from
+    */
+    template<typename BasicJsonType, typename ValueType>
+    static void to_json(BasicJsonType& j, ValueType&& val) noexcept(
+        noexcept(::nlohmann::to_json(j, std::forward<ValueType>(val))))
+    {
+        ::nlohmann::to_json(j, std::forward<ValueType>(val));
+    }
+};
 
-    #### Default type
+/*!
+@brief JSON Pointer
 
-    With the default values for @a NumberFloatType (`double`), the default
-    value for @a number_float_t is:
+A JSON pointer defines a string syntax for identifying a specific value
+within a JSON document. It can be used with functions `at` and
+`operator[]`. Furthermore, JSON pointers are the base for JSON patches.
 
-    @code {.cpp}
-    double
-    @endcode
+@sa [RFC 6901](https://tools.ietf.org/html/rfc6901)
 
-    #### Default behavior
+@since version 2.0.0
+*/
+class json_pointer
+{
+    /// allow basic_json to access private members
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    friend class basic_json;
 
-    - The restrictions about leading zeros is not enforced in C++. Instead,
-      leading zeros in floating-point literals will be ignored. Internally,
-      the value will be stored as decimal number. For instance, the C++
-      floating-point literal `01.2` will be serialized to `1.2`. During
-      deserialization, leading zeros yield an error.
-    - Not-a-number (NaN) values will be serialized to `null`.
+  public:
+    /*!
+      @brief create JSON pointer
 
-    #### Limits
+      Create a JSON pointer according to the syntax described in
+      [Section 3 of RFC6901](https://tools.ietf.org/html/rfc6901#section-3).
 
-    [RFC 7159](http://rfc7159.net/rfc7159) states:
-    > This specification allows implementations to set limits on the range and
-    > precision of numbers accepted. Since software that implements IEEE
-    > 754-2008 binary64 (double precision) numbers is generally available and
-    > widely used, good interoperability can be achieved by implementations
-    > that expect no more precision or range than these provide, in the sense
-    > that implementations will approximate JSON numbers within the expected
-    > precision.
+      @param[in] s  string representing the JSON pointer; if omitted, the
+      empty string is assumed which references the whole JSON
+      value
 
-    This implementation does exactly follow this approach, as it uses double
-    precision floating-point numbers. Note values smaller than
-    `-1.79769313486232e+308` and values greater than `1.79769313486232e+308`
-    will be stored as NaN internally and be serialized to `null`.
+      @throw parse_error.107 if the given JSON pointer @a s is nonempty and
+      does not begin with a slash (`/`); see example below
 
-    #### Storage
+      @throw parse_error.108 if a tilde (`~`) in the given JSON pointer @a s
+      is not followed by `0` (representing `~`) or `1` (representing `/`);
+      see example below
 
-    Floating-point number values are stored directly inside a @ref basic_json
-    type.
+      @liveexample{The example shows the construction several valid JSON
+      pointers as well as the exceptional behavior.,json_pointer}
 
-    @sa @ref number_integer_t -- type for number values (integer)
+      @since version 2.0.0
+      */
+    explicit json_pointer(const std::string& s = "") : reference_tokens(split(s)) {}
 
-    @sa @ref number_unsigned_t -- type for number values (unsigned integer)
+    /*!
+      @brief return a string representation of the JSON pointer
 
-    @since version 1.0.0
-    */
-    using number_float_t = NumberFloatType;
+      @invariant For each JSON pointer `ptr`, it holds:
+      @code {.cpp}
+      ptr == json_pointer(ptr.to_string());
+      @endcode
 
-    /// @}
+      @return a string representation of the JSON pointer
 
-  private:
+      @liveexample{The example shows the result of `to_string`.,
+      json_pointer__to_string}
 
-    /// helper for exception-safe object creation
-    template<typename T, typename... Args>
-    static T* create(Args&& ... args)
+      @since version 2.0.0
+      */
+    std::string to_string() const noexcept
     {
-        AllocatorType<T> alloc;
-        auto deleter = [&](T * object)
+        return std::accumulate(reference_tokens.begin(), reference_tokens.end(),
+                               std::string{},
+                               [](const std::string & a, const std::string & b)
         {
-            alloc.deallocate(object, 1);
-        };
-        std::unique_ptr<T, decltype(deleter)> object(alloc.allocate(1), deleter);
-        alloc.construct(object.get(), std::forward<Args>(args)...);
-        assert(object != nullptr);
-        return object.release();
+            return a + "/" + escape(b);
+        });
     }
 
-    ////////////////////////
-    // JSON value storage //
-    ////////////////////////
+    /// @copydoc to_string()
+    operator std::string() const
+    {
+        return to_string();
+    }
 
+  private:
     /*!
-    @brief a JSON value
-
-    The actual storage for a JSON value of the @ref basic_json class. This
-    union combines the different storage types for the JSON value types
-    defined in @ref value_t.
-
-    JSON type | value_t type    | used type
-    --------- | --------------- | ------------------------
-    object    | object          | pointer to @ref object_t
-    array     | array           | pointer to @ref array_t
-    string    | string          | pointer to @ref string_t
-    boolean   | boolean         | @ref boolean_t
-    number    | number_integer  | @ref number_integer_t
-    number    | number_unsigned | @ref number_unsigned_t
-    number    | number_float    | @ref number_float_t
-    null      | null            | *no value is stored*
+      @brief remove and return last reference pointer
+      @throw out_of_range.405 if JSON pointer has no parent
+      */
+    std::string pop_back()
+    {
+        if (is_root())
+        {
+            JSON_THROW(
+                detail::out_of_range::create(405, "JSON pointer has no parent"));
+        }
 
-    @note Variable-length types (objects, arrays, and strings) are stored as
-    pointers. The size of the union should not exceed 64 bits if the default
-    value types are used.
+        auto last = reference_tokens.back();
+        reference_tokens.pop_back();
+        return last;
+    }
 
-    @since version 1.0.0
-    */
-    union json_value
+    /// return whether pointer points to the root document
+    bool is_root() const
     {
-        /// object (stored with pointer to save storage)
-        object_t* object;
-        /// array (stored with pointer to save storage)
-        array_t* array;
-        /// string (stored with pointer to save storage)
-        string_t* string;
-        /// boolean
-        boolean_t boolean;
-        /// number (integer)
-        number_integer_t number_integer;
-        /// number (unsigned integer)
-        number_unsigned_t number_unsigned;
-        /// number (floating-point)
-        number_float_t number_float;
+        return reference_tokens.empty();
+    }
 
-        /// default constructor (for null values)
-        json_value() = default;
-        /// constructor for booleans
-        json_value(boolean_t v) noexcept : boolean(v) {}
-        /// constructor for numbers (integer)
-        json_value(number_integer_t v) noexcept : number_integer(v) {}
-        /// constructor for numbers (unsigned)
-        json_value(number_unsigned_t v) noexcept : number_unsigned(v) {}
-        /// constructor for numbers (floating-point)
-        json_value(number_float_t v) noexcept : number_float(v) {}
-        /// constructor for empty values of a given type
-        json_value(value_t t)
+    json_pointer top() const
+    {
+        if (is_root())
         {
-            switch (t)
-            {
-                case value_t::object:
-                {
-                    object = create<object_t>();
-                    break;
-                }
+            JSON_THROW(detail::out_of_range::create(405, "JSON pointer has no parent"));
+        }
 
-                case value_t::array:
-                {
-                    array = create<array_t>();
-                    break;
-                }
+        json_pointer result = *this;
+        result.reference_tokens = {reference_tokens[0]};
+        return result;
+    }
 
-                case value_t::string:
-                {
-                    string = create<string_t>("");
-                    break;
-                }
 
-                case value_t::boolean:
-                {
-                    boolean = boolean_t(false);
-                    break;
-                }
+    /*!
+      @brief create and return a reference to the pointed to value
 
-                case value_t::number_integer:
-                {
-                    number_integer = number_integer_t(0);
-                    break;
-                }
+      @complexity Linear in the number of reference tokens.
 
-                case value_t::number_unsigned:
-                {
-                    number_unsigned = number_unsigned_t(0);
-                    break;
-                }
+      @throw parse_error.109 if array index is not a number
+      @throw type_error.313 if value cannot be unflattened
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    NLOHMANN_BASIC_JSON_TPL& get_and_create(NLOHMANN_BASIC_JSON_TPL& j) const;
 
-                case value_t::number_float:
-                {
-                    number_float = number_float_t(0.0);
-                    break;
-                }
+    /*!
+      @brief return a reference to the pointed to value
 
-                case value_t::null:
-                {
-                    break;
-                }
+      @note This version does not throw if a value is not present, but tries
+      to create nested values instead. For instance, calling this function
+      with pointer `"/this/that"` on a null value is equivalent to calling
+      `operator[]("this").operator[]("that")` on that value, effectively
+      changing the null value to an object.
 
-                default:
-                {
-                    if (JSON_UNLIKELY(t == value_t::null))
-                    {
-                        JSON_THROW(other_error::create(500, "961c151d2e87f2686a955a9be24d316f1362bf21 2.1.1")); // LCOV_EXCL_LINE
-                    }
-                    break;
-                }
-            }
-        }
+      @param[in] ptr  a JSON value
 
-        /// constructor for strings
-        json_value(const string_t& value)
-        {
-            string = create<string_t>(value);
-        }
+      @return reference to the JSON value pointed to by the JSON pointer
 
-        /// constructor for objects
-        json_value(const object_t& value)
-        {
-            object = create<object_t>(value);
-        }
+      @complexity Linear in the length of the JSON pointer.
 
-        /// constructor for arrays
-        json_value(const array_t& value)
-        {
-            array = create<array_t>(value);
-        }
-    };
+      @throw parse_error.106   if an array index begins with '0'
+      @throw parse_error.109   if an array index was not a number
+      @throw out_of_range.404  if the JSON pointer can not be resolved
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    NLOHMANN_BASIC_JSON_TPL& get_unchecked(NLOHMANN_BASIC_JSON_TPL* ptr) const;
 
     /*!
-    @brief checks the class invariants
-
-    This function asserts the class invariants. It needs to be called at the
-    end of every constructor to make sure that created objects respect the
-    invariant. Furthermore, it has to be called each time the type of a JSON
-    value is changed, because the invariant expresses a relationship between
-    @a m_type and @a m_value.
-    */
-    void assert_invariant() const
-    {
-        assert(m_type != value_t::object or m_value.object != nullptr);
-        assert(m_type != value_t::array or m_value.array != nullptr);
-        assert(m_type != value_t::string or m_value.string != nullptr);
-    }
-
-  public:
-    //////////////////////////
-    // JSON parser callback //
-    //////////////////////////
+      @throw parse_error.106   if an array index begins with '0'
+      @throw parse_error.109   if an array index was not a number
+      @throw out_of_range.402  if the array index '-' is used
+      @throw out_of_range.404  if the JSON pointer can not be resolved
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    NLOHMANN_BASIC_JSON_TPL& get_checked(NLOHMANN_BASIC_JSON_TPL* ptr) const;
 
     /*!
-    @brief JSON callback events
+      @brief return a const reference to the pointed to value
 
-    This enumeration lists the parser events that can trigger calling a
-    callback function of type @ref parser_callback_t during parsing.
+      @param[in] ptr  a JSON value
 
-    @image html callback_events.png "Example when certain parse events are triggered"
+      @return const reference to the JSON value pointed to by the JSON
+      pointer
 
-    @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
-    };
+      @throw parse_error.106   if an array index begins with '0'
+      @throw parse_error.109   if an array index was not a number
+      @throw out_of_range.402  if the array index '-' is used
+      @throw out_of_range.404  if the JSON pointer can not be resolved
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    const NLOHMANN_BASIC_JSON_TPL& get_unchecked(const NLOHMANN_BASIC_JSON_TPL* ptr) const;
 
     /*!
-    @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.
+      @throw parse_error.106   if an array index begins with '0'
+      @throw parse_error.109   if an array index was not a number
+      @throw out_of_range.402  if the array index '-' is used
+      @throw out_of_range.404  if the JSON pointer can not be resolved
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    const NLOHMANN_BASIC_JSON_TPL& get_checked(const NLOHMANN_BASIC_JSON_TPL* ptr) const;
 
-    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
+    /*!
+      @brief split the string input to reference tokens
 
-    @image html callback_events.png "Example when certain parse events are triggered"
+      @note This function is only called by the json_pointer constructor.
+      All exceptions below are documented there.
 
-    Discarding a value (i.e., returning `false`) has different effects
-    depending on the context in which function was called:
+      @throw parse_error.107  if the pointer is not empty or begins with '/'
+      @throw parse_error.108  if character '~' is not followed by '0' or '1'
+      */
+    static std::vector<std::string> split(const std::string& reference_string)
+    {
+        std::vector<std::string> result;
 
-    - 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.
+        // special case: empty reference string -> no reference tokens
+        if (reference_string.empty())
+        {
+            return result;
+        }
 
-    @param[in] depth  the depth of the recursion during parsing
+        // check if nonempty reference string begins with slash
+        if (reference_string[0] != '/')
+        {
+            JSON_THROW(detail::parse_error::create(
+                           107, 1,
+                           "JSON pointer must be empty or begin with '/' - was: '" +
+                           reference_string + "'"));
+        }
 
-    @param[in] event  an event of type parse_event_t indicating the context in
-    the callback function has been called
+        // extract the reference tokens:
+        // - slash: position of the last read slash (or end of string)
+        // - start: position after the previous slash
+        for (
+            // search for the first slash after the first character
+            size_t slash = reference_string.find_first_of('/', 1),
+            // set the beginning of the first reference token
+            start = 1;
+            // we can stop if start == string::npos+1 = 0
+            start != 0;
+            // set the beginning of the next reference token
+            // (will eventually be 0 if slash == std::string::npos)
+            start = slash + 1,
+            // find next slash
+            slash = reference_string.find_first_of('/', start))
+        {
+            // use the text between the beginning of the reference token
+            // (start) and the last slash (slash).
+            auto reference_token = reference_string.substr(start, slash - start);
 
-    @param[in,out] parsed  the current intermediate parse result; note that
-    writing to this value has no effect for parse_event_t::key events
+            // check reference tokens are properly escaped
+            for (size_t pos = reference_token.find_first_of('~');
+                    pos != std::string::npos;
+                    pos = reference_token.find_first_of('~', pos + 1))
+            {
+                assert(reference_token[pos] == '~');
 
-    @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.
+                // ~ must be followed by 0 or 1
+                if (pos == reference_token.size() - 1 or
+                        (reference_token[pos + 1] != '0' and
+                         reference_token[pos + 1] != '1'))
+                {
+                    JSON_THROW(detail::parse_error::create(
+                                   108, 0, "escape character '~' must be followed with '0' or '1'"));
+                }
+            }
 
-    @sa @ref parse(std::istream&, parser_callback_t) or
-    @ref parse(const CharT, const parser_callback_t) for examples
+            // finally, store the reference token
+            unescape(reference_token);
+            result.push_back(reference_token);
+        }
 
-    @since version 1.0.0
-    */
-    using parser_callback_t = std::function<bool(int depth,
-                              parse_event_t event,
-                              basic_json& parsed)>;
+        return result;
+    }
 
+    /*!
+      @brief replace all occurrences of a substring by another string
 
-    //////////////////
-    // 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:
+      @param[in,out] s  the string to manipulate; changed so that all
+      occurrences of @a f are replaced with @a t
+      @param[in]     f  the substring to replace with @a t
+      @param[in]     t  the string to replace @a f
 
-    Value type  | initial value
-    ----------- | -------------
-    null        | `null`
-    boolean     | `false`
-    string      | `""`
-    number      | `0`
-    object      | `{}`
-    array       | `[]`
+      @pre The search string @a f must not be empty. **This precondition is
+      enforced with an assertion.**
 
-    @param[in] v  the type of the value to create
+      @since version 2.0.0
+      */
+    static void replace_substring(std::string& s, const std::string& f,
+                                  const std::string& t)
+    {
+        assert(not f.empty());
 
-    @complexity Constant.
+        for (size_t pos = s.find(f);         // find first occurrence of f
+                pos != std::string::npos;       // make sure f was found
+                s.replace(pos, f.size(), t),    // replace with t
+                pos = s.find(f, pos + t.size()) // find next occurrence of f
+            )
+            ;
+    }
 
-    @liveexample{The following code shows the constructor for different @ref
-    value_t values,basic_json__value_t}
+    /// escape tilde and slash
+    static std::string escape(std::string s)
+    {
+        // escape "~"" to "~0" and "/" to "~1"
+        replace_substring(s, "~", "~0");
+        replace_substring(s, "/", "~1");
+        return s;
+    }
 
-    @since version 1.0.0
-    */
-    basic_json(const value_t v)
-        : m_type(v), m_value(v)
+    /// unescape tilde and slash
+    static void unescape(std::string& s)
     {
-        assert_invariant();
+        // first transform any occurrence of the sequence '~1' to '/'
+        replace_substring(s, "~1", "/");
+        // then transform any occurrence of the sequence '~0' to '~'
+        replace_substring(s, "~0", "~");
     }
 
     /*!
-    @brief create a null object
+      @param[in] reference_string  the reference string to the current value
+      @param[in] value             the value to consider
+      @param[in,out] result        the result object to insert values to
 
-    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.
+      @note Empty objects or arrays are flattened to `null`.
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    static void flatten(const std::string& reference_string,
+                        const NLOHMANN_BASIC_JSON_TPL& value,
+                        NLOHMANN_BASIC_JSON_TPL& result);
 
-    @complexity Constant.
+    /*!
+      @param[in] value  flattened JSON
 
-    @exceptionsafety No-throw guarantee: this constructor never throws
-    exceptions.
+      @return unflattened JSON
 
-    @liveexample{The following code shows the constructor with and without a
-    null pointer parameter.,basic_json__nullptr_t}
+      @throw parse_error.109 if array index is not a number
+      @throw type_error.314  if value is not an object
+      @throw type_error.315  if object values are not primitive
+      @throw type_error.313  if value cannot be unflattened
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    static NLOHMANN_BASIC_JSON_TPL
+    unflatten(const NLOHMANN_BASIC_JSON_TPL& value);
 
-    @since version 1.0.0
-    */
-    basic_json(std::nullptr_t = nullptr) noexcept
-        : basic_json(value_t::null)
-    {
-        assert_invariant();
-    }
+    friend bool operator==(json_pointer const& lhs,
+                           json_pointer const& rhs) noexcept;
 
-    /*!
-    @brief create a JSON value
+    friend bool operator!=(json_pointer const& lhs,
+                           json_pointer const& rhs) noexcept;
 
-    This is a "catch all" constructor for all compatible JSON types; that is,
-    types for which a `to_json()` method exsits. The constructor forwards the
-    parameter @a val to that method (to `json_serializer<U>::to_json` method
-    with `U = uncvref_t<CompatibleType>`, to be exact).
+    /// the reference tokens
+    std::vector<std::string> reference_tokens;
+};
 
-    Template type @a CompatibleType includes, but is not limited to, the
-    following types:
-    - **arrays**: @ref array_t and all kinds of compatible containers such as
-      `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.
-    - **objects**: @ref object_t and all kinds of compatible associative
-      containers such as `std::map`, `std::unordered_map`, `std::multimap`,
-      and `std::unordered_multimap` with a `key_type` compatible to
-      @ref string_t and a `value_type` from which a @ref basic_json value can
-      be constructed.
-    - **strings**: @ref string_t, string literals, and all compatible string
-      containers can be used.
-    - **numbers**: @ref number_integer_t, @ref number_unsigned_t,
-      @ref number_float_t, and all convertible number types such as `int`,
-      `size_t`, `int64_t`, `float` or `double` can be used.
-    - **boolean**: @ref boolean_t / `bool` can be used.
+/*!
+@brief a class to store JSON values
 
-    See the examples below.
+@tparam ObjectType type for JSON objects (`std::map` by default; will be used
+in @ref object_t)
+@tparam ArrayType type for JSON arrays (`std::vector` by default; will be used
+in @ref array_t)
+@tparam StringType type for JSON strings and object keys (`std::string` by
+default; will be used in @ref string_t)
+@tparam BooleanType type for JSON booleans (`bool` by default; will be used
+in @ref boolean_t)
+@tparam NumberIntegerType type for JSON integer numbers (`int64_t` by
+default; will be used in @ref number_integer_t)
+@tparam NumberUnsignedType type for JSON unsigned integer numbers (@c
+`uint64_t` by default; will be used in @ref number_unsigned_t)
+@tparam NumberFloatType type for JSON floating-point numbers (`double` by
+default; will be used in @ref number_float_t)
+@tparam AllocatorType type of the allocator to use (`std::allocator` by
+default)
+@tparam JSONSerializer the serializer to resolve internal calls to `to_json()`
+and `from_json()` (@ref adl_serializer by default)
 
-    @tparam CompatibleType a type such that:
-    - @a CompatibleType is not derived from `std::istream`,
-    - @a CompatibleType is not @ref basic_json (to avoid hijacking copy/move
-         constructors),
-    - @a CompatibleType is not a @ref basic_json nested type (e.g.,
-         @ref json_pointer, @ref iterator, etc ...)
-    - @ref @ref json_serializer<U> has a
-         `to_json(basic_json_t&, CompatibleType&&)` method
+@requirement The class satisfies the following concept requirements:
+- Basic
+ - [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible):
+   JSON values can be default constructed. The result will be a JSON null
+   value.
+ - [MoveConstructible](http://en.cppreference.com/w/cpp/concept/MoveConstructible):
+   A JSON value can be constructed from an rvalue argument.
+ - [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible):
+   A JSON value can be copy-constructed from an lvalue expression.
+ - [MoveAssignable](http://en.cppreference.com/w/cpp/concept/MoveAssignable):
+   A JSON value van be assigned from an rvalue argument.
+ - [CopyAssignable](http://en.cppreference.com/w/cpp/concept/CopyAssignable):
+   A JSON value can be copy-assigned from an lvalue expression.
+ - [Destructible](http://en.cppreference.com/w/cpp/concept/Destructible):
+   JSON values can be destructed.
+- Layout
+ - [StandardLayoutType](http://en.cppreference.com/w/cpp/concept/StandardLayoutType):
+   JSON values have
+   [standard layout](http://en.cppreference.com/w/cpp/language/data_members#Standard_layout):
+   All non-static data members are private and standard layout types, the
+   class has no virtual functions or (virtual) base classes.
+- Library-wide
+ - [EqualityComparable](http://en.cppreference.com/w/cpp/concept/EqualityComparable):
+   JSON values can be compared with `==`, see @ref
+   operator==(const_reference,const_reference).
+ - [LessThanComparable](http://en.cppreference.com/w/cpp/concept/LessThanComparable):
+   JSON values can be compared with `<`, see @ref
+   operator<(const_reference,const_reference).
+ - [Swappable](http://en.cppreference.com/w/cpp/concept/Swappable):
+   Any JSON lvalue or rvalue of can be swapped with any lvalue or rvalue of
+   other compatible types, using unqualified function call @ref swap().
+ - [NullablePointer](http://en.cppreference.com/w/cpp/concept/NullablePointer):
+   JSON values can be compared against `std::nullptr_t` objects which are used
+   to model the `null` value.
+- Container
+ - [Container](http://en.cppreference.com/w/cpp/concept/Container):
+   JSON values can be used like STL containers and provide iterator access.
+ - [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer);
+   JSON values can be used like STL containers and provide reverse iterator
+   access.
 
-    @tparam U = `uncvref_t<CompatibleType>`
+@invariant The member variables @a m_value and @a m_type have the following
+relationship:
+- If `m_type == value_t::object`, then `m_value.object != nullptr`.
+- If `m_type == value_t::array`, then `m_value.array != nullptr`.
+- If `m_type == value_t::string`, then `m_value.string != nullptr`.
+The invariants are checked by member function assert_invariant().
 
-    @param[in] val the value to be forwarded
+@internal
+@note ObjectType trick from http://stackoverflow.com/a/9860911
+@endinternal
 
-    @complexity Usually linear in the size of the passed @a val, also
-                depending on the implementation of the called `to_json()`
-                method.
+@see [RFC 7159: The JavaScript Object Notation (JSON) Data Interchange
+Format](http://rfc7159.net/rfc7159)
 
-    @throw what `json_serializer<U>::to_json()` throws
+@since version 1.0.0
 
-    @liveexample{The following code shows the constructor with several
-    compatible types.,basic_json__CompatibleType}
+@nosubgrouping
+*/
+NLOHMANN_BASIC_JSON_TPL_DECLARATION
+class basic_json
+{
+  private:
+    template<detail::value_t> friend struct detail::external_constructor;
+    friend ::nlohmann::json_pointer;
+    friend ::nlohmann::detail::parser<basic_json>;
+    /// workaround type for MSVC
+    using basic_json_t = NLOHMANN_BASIC_JSON_TPL;
 
-    @since version 2.1.0
-    */
-    template<typename CompatibleType, typename U = detail::uncvref_t<CompatibleType>,
-             detail::enable_if_t<not std::is_base_of<std::istream, U>::value and
-                                 not std::is_same<U, basic_json_t>::value and
-                                 not detail::is_basic_json_nested_type<
-                                     basic_json_t, U>::value and
-                                 detail::has_to_json<basic_json, U>::value,
-                                 int> = 0>
-    basic_json(CompatibleType && val) noexcept(noexcept(JSONSerializer<U>::to_json(
-                std::declval<basic_json_t&>(), std::forward<CompatibleType>(val))))
-    {
-        JSONSerializer<U>::to_json(*this, std::forward<CompatibleType>(val));
-        assert_invariant();
-    }
+    // convenience aliases for types residing in namespace detail;
+    using lexer = ::nlohmann::detail::lexer<basic_json>;
+    using parser = ::nlohmann::detail::parser<basic_json>;
 
-    /*!
-    @brief create a container (array or object) from an initializer list
+  public:
+    using value_t = detail::value_t;
+    // forward declarations
+    template<typename U> class iter_impl;
+    template<typename Base> class json_reverse_iterator;
+    using json_pointer = ::nlohmann::json_pointer;
+    template<typename T, typename SFINAE>
+    using json_serializer = JSONSerializer<T, SFINAE>;
 
-    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
+    ////////////////
+    // exceptions //
+    ////////////////
 
-    @note When used without parentheses around an empty initializer list, @ref
-    basic_json() is called instead of this function, yielding the JSON null
-    value.
+    /// @name exceptions
+    /// Classes to implement user-defined exceptions.
+    /// @{
 
-    @param[in] init  initializer list with JSON values
+    /// @copydoc detail::exception
+    using exception = detail::exception;
+    /// @copydoc detail::parse_error
+    using parse_error = detail::parse_error;
+    /// @copydoc detail::invalid_iterator
+    using invalid_iterator = detail::invalid_iterator;
+    /// @copydoc detail::type_error
+    using type_error = detail::type_error;
+    /// @copydoc detail::out_of_range
+    using out_of_range = detail::out_of_range;
+    /// @copydoc detail::other_error
+    using other_error = detail::other_error;
 
-    @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 type_error.301 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. In this case, the constructor could not
-    create an object. If @a type_deduction would have be `true`, an array
-    would have been created. See @ref object(std::initializer_list<basic_json>)
-    for an example.
+    /////////////////////
+    // container types //
+    /////////////////////
 
-    @complexity Linear in the size of the initializer list @a init.
+    /// @name container types
+    /// The canonic container types to use @ref basic_json like any other STL
+    /// container.
+    /// @{
 
-    @liveexample{The example below shows how JSON values are created from
-    initializer lists.,basic_json__list_init_t}
+    /// the type of elements in a basic_json container
+    using value_type = basic_json;
 
-    @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
+    /// the type of an element reference
+    using reference = value_type&;
+    /// the type of an element const reference
+    using const_reference = const value_type&;
 
-    @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();
-        });
+    /// a type to represent differences between iterators
+    using difference_type = std::ptrdiff_t;
+    /// a type to represent container sizes
+    using size_type = std::size_t;
 
-        // 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;
-            }
+    /// the allocator type
+    using allocator_type = AllocatorType<basic_json>;
 
-            // if object is wanted but impossible, throw an exception
-            if (manual_type == value_t::object and not is_an_object)
-            {
-                JSON_THROW(type_error::create(301, "cannot create object from initializer list"));
-            }
-        }
+    /// the type of an element pointer
+    using pointer = typename std::allocator_traits<allocator_type>::pointer;
+    /// the type of an element const pointer
+    using const_pointer = typename std::allocator_traits<allocator_type>::const_pointer;
 
-        if (is_an_object)
-        {
-            // the initializer list is a list of pairs -> create object
-            m_type = value_t::object;
-            m_value = value_t::object;
+    /// an iterator for a basic_json container
+    using iterator = iter_impl<basic_json>;
+    /// a const iterator for a basic_json container
+    using const_iterator = iter_impl<const basic_json>;
+    /// a reverse iterator for a basic_json container
+    using reverse_iterator = json_reverse_iterator<typename basic_json::iterator>;
+    /// a const reverse iterator for a basic_json container
+    using const_reverse_iterator = json_reverse_iterator<typename basic_json::const_iterator>;
 
-            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
+    @brief returns the allocator associated with the container
     */
-    static basic_json array(std::initializer_list<basic_json> init =
-                                std::initializer_list<basic_json>())
+    static allocator_type get_allocator()
     {
-        return basic_json(init, false, value_t::array);
+        return allocator_type();
     }
 
     /*!
-    @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
+    @brief returns version information on the library
 
-    @throw type_error.301 if @a init is not a list of pairs whose first
-    elements are strings. In this case, no object can be created. When such a
-    value is passed to @ref basic_json(std::initializer_list<basic_json>, bool, value_t),
-    an array would have been created from the passed initializer list @a init.
-    See example below.
+    This function returns a JSON object with information about the library,
+    including the version number and information on the platform and compiler.
 
-    @complexity Linear in the size of @a init.
+    @return JSON object holding version information
+    key         | description
+    ----------- | ---------------
+    `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).
+    `copyright` | The copyright line for the library as string.
+    `name`      | The name of the library as string.
+    `platform`  | The used platform as string. Possible values are `win32`, `linux`, `apple`, `unix`, and `unknown`.
+    `url`       | The URL of the project as string.
+    `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).
 
-    @liveexample{The following code shows an example for the `object`
-    function.,object}
+    @liveexample{The following code shows an example output of the `meta()`
+    function.,meta}
 
-    @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
+    @complexity Constant.
 
-    @since version 1.0.0
+    @since 2.1.0
     */
-    static basic_json object(std::initializer_list<basic_json> init =
-                                 std::initializer_list<basic_json>())
+    static basic_json meta()
     {
-        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.
+        basic_json result;
 
-    @param[in] cnt  the number of JSON copies of @a val to create
-    @param[in] val  the JSON value to copy
+        result["copyright"] = "(C) 2013-2017 Niels Lohmann";
+        result["name"] = "JSON for Modern C++";
+        result["url"] = "https://github.com/nlohmann/json";
+        result["version"] =
+        {
+            {"string", "2.1.1"}, {"major", 2}, {"minor", 1}, {"patch", 1}
+        };
 
-    @complexity Linear in @a cnt.
+#ifdef _WIN32
+        result["platform"] = "win32";
+#elif defined __linux__
+        result["platform"] = "linux";
+#elif defined __APPLE__
+        result["platform"] = "apple";
+#elif defined __unix__
+        result["platform"] = "unix";
+#else
+        result["platform"] = "unknown";
+#endif
 
-    @liveexample{The following code shows examples for the @ref
-    basic_json(size_type\, const basic_json&)
-    constructor.,basic_json__size_type_basic_json}
+#if defined(__clang__)
+        result["compiler"] = {{"family", "clang"}, {"version", __clang_version__}};
+#elif defined(__ICC) || defined(__INTEL_COMPILER)
+        result["compiler"] = {{"family", "icc"}, {"version", __INTEL_COMPILER}};
+#elif defined(__GNUC__) || defined(__GNUG__)
+        result["compiler"] = {{"family", "gcc"}, {"version", std::to_string(__GNUC__) + "." + std::to_string(__GNUC_MINOR__) + "." + std::to_string(__GNUC_PATCHLEVEL__)}};
+#elif defined(__HP_cc) || defined(__HP_aCC)
+        result["compiler"] = "hp"
+#elif defined(__IBMCPP__)
+        result["compiler"] = {{"family", "ilecpp"}, {"version", __IBMCPP__}};
+#elif defined(_MSC_VER)
+        result["compiler"] = {{"family", "msvc"}, {"version", _MSC_VER}};
+#elif defined(__PGI)
+        result["compiler"] = {{"family", "pgcpp"}, {"version", __PGI}};
+#elif defined(__SUNPRO_CC)
+        result["compiler"] = {{"family", "sunpro"}, {"version", __SUNPRO_CC}};
+#else
+        result["compiler"] = {{"family", "unknown"}, {"version", "unknown"}};
+#endif
 
-    @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();
+#ifdef __cplusplus
+        result["compiler"]["c++"] = std::to_string(__cplusplus);
+#else
+        result["compiler"]["c++"] = "unknown";
+#endif
+        return result;
     }
 
-    /*!
-    @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, invalid_iterator.204 is thrown.
-    - In case of structured types (array, object), the constructor behaves as
-      similar versions for `std::vector`.
-    - In case of a null type, invalid_iterator.206 is thrown.
+    ///////////////////////////
+    // JSON value data types //
+    ///////////////////////////
 
-    @tparam InputIT an input iterator type (@ref iterator or @ref
-    const_iterator)
+    /// @name JSON value data types
+    /// The data types to store a JSON value. These types are derived from
+    /// the template arguments passed to class @ref basic_json.
+    /// @{
 
-    @param[in] first begin of the range to copy from (included)
-    @param[in] last end of the range to copy from (excluded)
+    /*!
+    @brief a type for an object
 
-    @pre Iterators @a first and @a last must be initialized. **This
-         precondition is enforced with an assertion.**
+    [RFC 7159](http://rfc7159.net/rfc7159) describes JSON objects as follows:
+    > An object is an unordered collection of zero or more name/value pairs,
+    > where a name is a string and a value is a string, number, boolean, null,
+    > object, or array.
 
-    @pre Range `[first, last)` is valid. Usually, this precondition cannot be
-         checked efficiently. Only certain edge cases are detected; see the
-         description of the exceptions below.
+    To store objects in C++, a type is defined by the template parameters
+    described below.
 
-    @throw invalid_iterator.201 if iterators @a first and @a last are not
-    compatible (i.e., do not belong to the same JSON value). In this case,
-    the range `[first, last)` is undefined.
-    @throw invalid_iterator.204 if iterators @a first and @a last belong to a
-    primitive type (number, boolean, or string), but @a first does not point
-    to the first element any more. In this case, the range `[first, last)` is
-    undefined. See example code below.
-    @throw invalid_iterator.206 if iterators @a first and @a last belong to a
-    null value. In this case, the range `[first, last)` is undefined.
+    @tparam ObjectType  the container to store objects (e.g., `std::map` or
+    `std::unordered_map`)
+    @tparam StringType the type of the keys or names (e.g., `std::string`).
+    The comparison function `std::less<StringType>` is used to order elements
+    inside the container.
+    @tparam AllocatorType the allocator to use for objects (e.g.,
+    `std::allocator`)
 
-    @complexity Linear in distance between @a first and @a last.
+    #### Default type
 
-    @liveexample{The example below shows several ways to create JSON values by
-    specifying a subrange with iterators.,basic_json__InputIt_InputIt}
+    With the default values for @a ObjectType (`std::map`), @a StringType
+    (`std::string`), and @a AllocatorType (`std::allocator`), the default
+    value for @a object_t is:
 
-    @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);
+    @code {.cpp}
+    std::map<
+      std::string, // key_type
+      basic_json, // value_type
+      std::less<std::string>, // key_compare
+      std::allocator<std::pair<const std::string, basic_json>> // allocator_type
+    >
+    @endcode
 
-        // make sure iterator fits the current value
-        if (first.m_object != last.m_object)
-        {
-            JSON_THROW(invalid_iterator::create(201, "iterators are not compatible"));
-        }
+    #### Behavior
 
-        // copy type from first iterator
-        m_type = first.m_object->m_type;
+    The choice of @a object_t influences the behavior of the JSON class. With
+    the default type, objects have the following behavior:
 
-        // 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(invalid_iterator::create(204, "iterators out of range"));
-                }
-                break;
-            }
+    - When all names are unique, objects will be interoperable in the sense
+      that all software implementations receiving that object will agree on
+      the name-value mappings.
+    - When the names within an object are not unique, later stored name/value
+      pairs overwrite previously stored name/value pairs, leaving the used
+      names unique. For instance, `{"key": 1}` and `{"key": 2, "key": 1}` will
+      be treated as equal and both stored as `{"key": 1}`.
+    - Internally, name/value pairs are stored in lexicographical order of the
+      names. Objects will also be serialized (see @ref dump) in this order.
+      For instance, `{"b": 1, "a": 2}` and `{"a": 2, "b": 1}` will be stored
+      and serialized as `{"a": 2, "b": 1}`.
+    - When comparing objects, the order of the name/value pairs is irrelevant.
+      This makes objects interoperable in the sense that they will not be
+      affected by these differences. For instance, `{"b": 1, "a": 2}` and
+      `{"a": 2, "b": 1}` will be treated as equal.
 
-            default:
-            {
-                break;
-            }
-        }
+    #### Limits
 
-        switch (m_type)
-        {
-            case value_t::number_integer:
-            {
-                m_value.number_integer = first.m_object->m_value.number_integer;
-                break;
-            }
+    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
+    > An implementation may set limits on the maximum depth of nesting.
 
-            case value_t::number_unsigned:
-            {
-                m_value.number_unsigned = first.m_object->m_value.number_unsigned;
-                break;
-            }
+    In this class, the object's limit of nesting is not constraint explicitly.
+    However, a maximum depth of nesting may be introduced by the compiler or
+    runtime environment. A theoretical limit can be queried by calling the
+    @ref max_size function of a JSON object.
 
-            case value_t::number_float:
-            {
-                m_value.number_float = first.m_object->m_value.number_float;
-                break;
-            }
+    #### Storage
 
-            case value_t::boolean:
-            {
-                m_value.boolean = first.m_object->m_value.boolean;
-                break;
-            }
+    Objects are stored as pointers in a @ref basic_json type. That is, for any
+    access to object values, a pointer of type `object_t*` must be
+    dereferenced.
 
-            case value_t::string:
-            {
-                m_value = *first.m_object->m_value.string;
-                break;
-            }
+    @sa @ref array_t -- type for an array value
 
-            case value_t::object:
-            {
-                m_value.object = create<object_t>(first.m_it.object_iterator,
-                                                  last.m_it.object_iterator);
-                break;
-            }
+    @since version 1.0.0
 
-            case value_t::array:
-            {
-                m_value.array = create<array_t>(first.m_it.array_iterator,
-                                                last.m_it.array_iterator);
-                break;
-            }
+    @note The order name/value pairs are added to the object is *not*
+    preserved by the library. Therefore, iterating an object may return
+    name/value pairs in a different order than they were originally stored. In
+    fact, keys will be traversed in alphabetical order as `std::map` with
+    `std::less` is used by default. Please note this behavior conforms to [RFC
+    7159](http://rfc7159.net/rfc7159), because any order implements the
+    specified "unordered" nature of JSON objects.
+    */
+    using object_t = ObjectType<StringType,
+          basic_json,
+          std::less<StringType>,
+          AllocatorType<std::pair<const StringType,
+          basic_json>>>;
 
-            default:
-            {
-                JSON_THROW(invalid_iterator::create(206, "cannot construct with iterators from " +
-                                                    first.m_object->type_name()));
-            }
-        }
+    /*!
+    @brief a type for an array
 
-        assert_invariant();
-    }
+    [RFC 7159](http://rfc7159.net/rfc7159) describes JSON arrays as follows:
+    > An array is an ordered sequence of zero or more values.
 
+    To store objects in C++, a type is defined by the template parameters
+    explained below.
 
-    ///////////////////////////////////////
-    // other constructors and destructor //
-    ///////////////////////////////////////
+    @tparam ArrayType  container type to store arrays (e.g., `std::vector` or
+    `std::list`)
+    @tparam AllocatorType allocator to use for arrays (e.g., `std::allocator`)
 
-    /*!
-    @brief copy constructor
+    #### Default type
 
-    Creates a copy of a given JSON value.
+    With the default values for @a ArrayType (`std::vector`) and @a
+    AllocatorType (`std::allocator`), the default value for @a array_t is:
 
-    @param[in] other  the JSON value to copy
+    @code {.cpp}
+    std::vector<
+      basic_json, // value_type
+      std::allocator<basic_json> // allocator_type
+    >
+    @endcode
 
-    @complexity Linear in the size of @a other.
+    #### Limits
 
-    @requirement This function helps `basic_json` satisfying the
-    [Container](http://en.cppreference.com/w/cpp/concept/Container)
-    requirements:
-    - The complexity is linear.
-    - As postcondition, it holds: `other == basic_json(other)`.
+    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
+    > An implementation may set limits on the maximum depth of nesting.
 
-    @liveexample{The following code shows an example for the copy
-    constructor.,basic_json__basic_json}
+    In this class, the array's limit of nesting is not constraint explicitly.
+    However, a maximum depth of nesting may be introduced by the compiler or
+    runtime environment. A theoretical limit can be queried by calling the
+    @ref max_size function of a JSON array.
+
+    #### Storage
+
+    Arrays are stored as pointers in a @ref basic_json type. That is, for any
+    access to array values, a pointer of type `array_t*` must be dereferenced.
+
+    @sa @ref object_t -- type for an object value
 
     @since version 1.0.0
     */
-    basic_json(const basic_json& other)
-        : m_type(other.m_type)
-    {
-        // check of passed value is valid
-        other.assert_invariant();
-
-        switch (m_type)
-        {
-            case value_t::object:
-            {
-                m_value = *other.m_value.object;
-                break;
-            }
+    using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;
 
-            case value_t::array:
-            {
-                m_value = *other.m_value.array;
-                break;
-            }
+    /*!
+    @brief a type for a string
 
-            case value_t::string:
-            {
-                m_value = *other.m_value.string;
-                break;
-            }
+    [RFC 7159](http://rfc7159.net/rfc7159) describes JSON strings as follows:
+    > A string is a sequence of zero or more Unicode characters.
 
-            case value_t::boolean:
-            {
-                m_value = other.m_value.boolean;
-                break;
-            }
+    To store objects in C++, a type is defined by the template parameter
+    described below. Unicode values are split by the JSON class into
+    byte-sized characters during deserialization.
 
-            case value_t::number_integer:
-            {
-                m_value = other.m_value.number_integer;
-                break;
-            }
+    @tparam StringType  the container to store strings (e.g., `std::string`).
+    Note this container is used for keys/names in objects, see @ref object_t.
 
-            case value_t::number_unsigned:
-            {
-                m_value = other.m_value.number_unsigned;
-                break;
-            }
+    #### Default type
 
-            case value_t::number_float:
-            {
-                m_value = other.m_value.number_float;
-                break;
-            }
+    With the default values for @a StringType (`std::string`), the default
+    value for @a string_t is:
 
-            default:
-            {
-                break;
-            }
-        }
+    @code {.cpp}
+    std::string
+    @endcode
 
-        assert_invariant();
-    }
+    #### Encoding
 
-    /*!
-    @brief move constructor
+    Strings are stored in UTF-8 encoding. Therefore, functions like
+    `std::string::size()` or `std::string::length()` return the number of
+    bytes in the string rather than the number of characters or glyphs.
 
-    Move constructor. Constructs a JSON value with the contents of the given
-    value @a other using move semantics. It "steals" the resources from @a
-    other and leaves it as JSON null value.
+    #### String comparison
 
-    @param[in,out] other  value to move to this object
+    [RFC 7159](http://rfc7159.net/rfc7159) states:
+    > Software implementations are typically required to test names of object
+    > members for equality. Implementations that transform the textual
+    > representation into sequences of Unicode code units and then perform the
+    > comparison numerically, code unit by code unit, are interoperable in the
+    > sense that implementations will agree in all cases on equality or
+    > inequality of two strings. For example, implementations that compare
+    > strings with escaped characters unconverted may incorrectly find that
+    > `"a\\b"` and `"a\u005Cb"` are not equal.
 
-    @post @a other is a JSON null value
+    This implementation is interoperable as it does compare strings code unit
+    by code unit.
 
-    @complexity Constant.
+    #### Storage
 
-    @liveexample{The code below shows the move constructor explicitly called
-    via std::move.,basic_json__moveconstructor}
+    String values are stored as pointers in a @ref basic_json type. That is,
+    for any access to string values, a pointer of type `string_t*` must be
+    dereferenced.
 
     @since version 1.0.0
     */
-    basic_json(basic_json&& other) noexcept
-        : m_type(std::move(other.m_type)),
-          m_value(std::move(other.m_value))
-    {
-        // check that passed value is valid
-        other.assert_invariant();
+    using string_t = StringType;
 
-        // invalidate payload
-        other.m_type = value_t::null;
-        other.m_value = {};
+    /*!
+    @brief a type for a boolean
 
-        assert_invariant();
-    }
+    [RFC 7159](http://rfc7159.net/rfc7159) implicitly describes a boolean as a
+    type which differentiates the two literals `true` and `false`.
 
-    /*!
-    @brief copy assignment
+    To store objects in C++, a type is defined by the template parameter @a
+    BooleanType which chooses the type to use.
 
-    Copy assignment operator. Copies a JSON value via the "copy and swap"
-    strategy: It is expressed in terms of the copy constructor, destructor,
-    and the swap() member function.
+    #### Default type
 
-    @param[in] other  value to copy from
+    With the default values for @a BooleanType (`bool`), the default value for
+    @a boolean_t is:
 
-    @complexity Linear.
+    @code {.cpp}
+    bool
+    @endcode
 
-    @requirement This function helps `basic_json` satisfying the
-    [Container](http://en.cppreference.com/w/cpp/concept/Container)
-    requirements:
-    - The complexity is linear.
+    #### Storage
 
-    @liveexample{The code below shows and example for the copy assignment. It
-    creates a copy of value `a` which is then swapped with `b`. Finally\, the
-    copy of `a` (which is the null value after the swap) is
-    destroyed.,basic_json__copyassignment}
+    Boolean values are stored directly inside a @ref basic_json type.
 
     @since version 1.0.0
     */
-    reference& operator=(basic_json other) noexcept (
-        std::is_nothrow_move_constructible<value_t>::value and
-        std::is_nothrow_move_assignable<value_t>::value and
-        std::is_nothrow_move_constructible<json_value>::value and
-        std::is_nothrow_move_assignable<json_value>::value
-    )
-    {
-        // check that passed value is valid
-        other.assert_invariant();
-
-        using std::swap;
-        swap(m_type, other.m_type);
-        swap(m_value, other.m_value);
-
-        assert_invariant();
-        return *this;
-    }
+    using boolean_t = BooleanType;
 
     /*!
-    @brief destructor
+    @brief a type for a number (integer)
 
-    Destroys the JSON value and frees all allocated memory.
+    [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
+    > The representation of numbers is similar to that used in most
+    > programming languages. A number is represented in base 10 using decimal
+    > digits. It contains an integer component that may be prefixed with an
+    > optional minus sign, which may be followed by a fraction part and/or an
+    > exponent part. Leading zeros are not allowed. (...) Numeric values that
+    > cannot be represented in the grammar below (such as Infinity and NaN)
+    > are not permitted.
 
-    @complexity Linear.
+    This description includes both integer and floating-point numbers.
+    However, C++ allows more precise storage if it is known whether the number
+    is a signed integer, an unsigned integer or a floating-point number.
+    Therefore, three different types, @ref number_integer_t, @ref
+    number_unsigned_t and @ref number_float_t are used.
 
-    @requirement This function helps `basic_json` satisfying the
-    [Container](http://en.cppreference.com/w/cpp/concept/Container)
-    requirements:
-    - The complexity is linear.
-    - All stored elements are destroyed and all memory is freed.
+    To store integer numbers in C++, a type is defined by the template
+    parameter @a NumberIntegerType which chooses the type to use.
 
-    @since version 1.0.0
-    */
-    ~basic_json()
-    {
-        assert_invariant();
+    #### Default type
 
-        switch (m_type)
-        {
-            case value_t::object:
-            {
-                AllocatorType<object_t> alloc;
-                alloc.destroy(m_value.object);
-                alloc.deallocate(m_value.object, 1);
-                break;
-            }
+    With the default values for @a NumberIntegerType (`int64_t`), the default
+    value for @a number_integer_t is:
 
-            case value_t::array:
-            {
-                AllocatorType<array_t> alloc;
-                alloc.destroy(m_value.array);
-                alloc.deallocate(m_value.array, 1);
-                break;
-            }
+    @code {.cpp}
+    int64_t
+    @endcode
 
-            case value_t::string:
-            {
-                AllocatorType<string_t> alloc;
-                alloc.destroy(m_value.string);
-                alloc.deallocate(m_value.string, 1);
-                break;
-            }
+    #### Default behavior
 
-            default:
-            {
-                // all other types need no specific destructor
-                break;
-            }
-        }
-    }
+    - The restrictions about leading zeros is not enforced in C++. Instead,
+      leading zeros in integer literals lead to an interpretation as octal
+      number. Internally, the value will be stored as decimal number. For
+      instance, the C++ integer literal `010` will be serialized to `8`.
+      During deserialization, leading zeros yield an error.
+    - Not-a-number (NaN) values will be serialized to `null`.
 
-    /// @}
-
-  public:
-    ///////////////////////
-    // object inspection //
-    ///////////////////////
+    #### Limits
 
-    /// @name object inspection
-    /// Functions to inspect the type of a JSON value.
-    /// @{
+    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
+    > An implementation may set limits on the range and precision of numbers.
 
-    /*!
-    @brief serialization
+    When the default type is used, the maximal integer number that can be
+    stored is `9223372036854775807` (INT64_MAX) and the minimal integer number
+    that can be stored is `-9223372036854775808` (INT64_MIN). Integer numbers
+    that are out of range will yield over/underflow when used in a
+    constructor. During deserialization, too large or small integer numbers
+    will be automatically be stored as @ref number_unsigned_t or @ref
+    number_float_t.
 
-    Serialization function for JSON values. The function tries to mimic
-    Python's `json.dumps()` function, and currently supports its @a indent
-    parameter.
+    [RFC 7159](http://rfc7159.net/rfc7159) further states:
+    > Note that when such software is used, numbers that are integers and are
+    > in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
+    > that implementations will agree exactly on their numeric values.
 
-    @param[in] indent If indent is nonnegative, then array elements and object
-    members will be pretty-printed with that indent level. An indent level of
-    `0` will only insert newlines. `-1` (the default) selects the most compact
-    representation.
-    @param[in] indent_char The character to use for indentation if @a indent is
-    greater than `0`. The default is ` ` (space).
+    As this range is a subrange of the exactly supported range [INT64_MIN,
+    INT64_MAX], this class's integer type is interoperable.
 
-    @return string containing the serialization of the JSON value
+    #### Storage
 
-    @complexity Linear.
+    Integer number values are stored directly inside a @ref basic_json type.
 
-    @liveexample{The following example shows the effect of different @a indent
-    parameters to the result of the serialization.,dump}
+    @sa @ref number_float_t -- type for number values (floating-point)
 
-    @see https://docs.python.org/2/library/json.html#json.dump
+    @sa @ref number_unsigned_t -- type for number values (unsigned integer)
 
-    @since version 1.0.0; indentation character added in version 3.0.0
+    @since version 1.0.0
     */
-    string_t dump(const int indent = -1, const char indent_char = ' ') const
-    {
-        string_t result;
-        serializer s(output_adapter<char>::create(result), indent_char);
+    using number_integer_t = NumberIntegerType;
 
-        if (indent >= 0)
-        {
-            s.dump(*this, true, static_cast<unsigned int>(indent));
-        }
-        else
-        {
-            s.dump(*this, false, 0);
-        }
+    /*!
+    @brief a type for a number (unsigned)
 
-        return result;
-    }
+    [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
+    > The representation of numbers is similar to that used in most
+    > programming languages. A number is represented in base 10 using decimal
+    > digits. It contains an integer component that may be prefixed with an
+    > optional minus sign, which may be followed by a fraction part and/or an
+    > exponent part. Leading zeros are not allowed. (...) Numeric values that
+    > cannot be represented in the grammar below (such as Infinity and NaN)
+    > are not permitted.
 
-    /*!
-    @brief return the type of the JSON value (explicit)
+    This description includes both integer and floating-point numbers.
+    However, C++ allows more precise storage if it is known whether the number
+    is a signed integer, an unsigned integer or a floating-point number.
+    Therefore, three different types, @ref number_integer_t, @ref
+    number_unsigned_t and @ref number_float_t are used.
 
-    Return the type of the JSON value as a value from the @ref value_t
-    enumeration.
+    To store unsigned integer numbers in C++, a type is defined by the
+    template parameter @a NumberUnsignedType which chooses the type to use.
 
-    @return the type of the JSON value
+    #### Default type
 
-    @complexity Constant.
+    With the default values for @a NumberUnsignedType (`uint64_t`), the
+    default value for @a number_unsigned_t is:
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    @code {.cpp}
+    uint64_t
+    @endcode
 
-    @liveexample{The following code exemplifies `type()` for all JSON
-    types.,type}
+    #### Default behavior
 
-    @since version 1.0.0
-    */
-    constexpr value_t type() const noexcept
-    {
-        return m_type;
-    }
+    - The restrictions about leading zeros is not enforced in C++. Instead,
+      leading zeros in integer literals lead to an interpretation as octal
+      number. Internally, the value will be stored as decimal number. For
+      instance, the C++ integer literal `010` will be serialized to `8`.
+      During deserialization, leading zeros yield an error.
+    - Not-a-number (NaN) values will be serialized to `null`.
 
-    /*!
-    @brief return whether type is primitive
+    #### Limits
 
-    This function returns true iff the JSON type is primitive (string, number,
-    boolean, or null).
+    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
+    > An implementation may set limits on the range and precision of numbers.
 
-    @return `true` if type is primitive (string, number, boolean, or null),
-    `false` otherwise.
+    When the default type is used, the maximal integer number that can be
+    stored is `18446744073709551615` (UINT64_MAX) and the minimal integer
+    number that can be stored is `0`. Integer numbers that are out of range
+    will yield over/underflow when used in a constructor. During
+    deserialization, too large or small integer numbers will be automatically
+    be stored as @ref number_integer_t or @ref number_float_t.
 
-    @complexity Constant.
+    [RFC 7159](http://rfc7159.net/rfc7159) further states:
+    > Note that when such software is used, numbers that are integers and are
+    > in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
+    > that implementations will agree exactly on their numeric values.
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    As this range is a subrange (when considered in conjunction with the
+    number_integer_t type) of the exactly supported range [0, UINT64_MAX],
+    this class's integer type is interoperable.
 
-    @liveexample{The following code exemplifies `is_primitive()` for all JSON
-    types.,is_primitive}
+    #### Storage
 
-    @sa @ref is_structured() -- returns whether JSON value is structured
-    @sa @ref is_null() -- returns whether JSON value is `null`
-    @sa @ref is_string() -- returns whether JSON value is a string
-    @sa @ref is_boolean() -- returns whether JSON value is a boolean
-    @sa @ref is_number() -- returns whether JSON value is a number
+    Integer number values are stored directly inside a @ref basic_json type.
 
-    @since version 1.0.0
+    @sa @ref number_float_t -- type for number values (floating-point)
+    @sa @ref number_integer_t -- type for number values (integer)
+
+    @since version 2.0.0
     */
-    constexpr bool is_primitive() const noexcept
-    {
-        return is_null() or is_string() or is_boolean() or is_number();
-    }
+    using number_unsigned_t = NumberUnsignedType;
 
     /*!
-    @brief return whether type is structured
+    @brief a type for a number (floating-point)
 
-    This function returns true iff the JSON type is structured (array or
-    object).
+    [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
+    > The representation of numbers is similar to that used in most
+    > programming languages. A number is represented in base 10 using decimal
+    > digits. It contains an integer component that may be prefixed with an
+    > optional minus sign, which may be followed by a fraction part and/or an
+    > exponent part. Leading zeros are not allowed. (...) Numeric values that
+    > cannot be represented in the grammar below (such as Infinity and NaN)
+    > are not permitted.
 
-    @return `true` if type is structured (array or object), `false` otherwise.
+    This description includes both integer and floating-point numbers.
+    However, C++ allows more precise storage if it is known whether the number
+    is a signed integer, an unsigned integer or a floating-point number.
+    Therefore, three different types, @ref number_integer_t, @ref
+    number_unsigned_t and @ref number_float_t are used.
 
-    @complexity Constant.
+    To store floating-point numbers in C++, a type is defined by the template
+    parameter @a NumberFloatType which chooses the type to use.
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    #### Default type
 
-    @liveexample{The following code exemplifies `is_structured()` for all JSON
-    types.,is_structured}
+    With the default values for @a NumberFloatType (`double`), the default
+    value for @a number_float_t is:
 
-    @sa @ref is_primitive() -- returns whether value is primitive
-    @sa @ref is_array() -- returns whether value is an array
-    @sa @ref is_object() -- returns whether value is an object
+    @code {.cpp}
+    double
+    @endcode
 
-    @since version 1.0.0
-    */
-    constexpr bool is_structured() const noexcept
-    {
-        return is_array() or is_object();
-    }
+    #### Default behavior
 
-    /*!
-    @brief return whether value is null
+    - The restrictions about leading zeros is not enforced in C++. Instead,
+      leading zeros in floating-point literals will be ignored. Internally,
+      the value will be stored as decimal number. For instance, the C++
+      floating-point literal `01.2` will be serialized to `1.2`. During
+      deserialization, leading zeros yield an error.
+    - Not-a-number (NaN) values will be serialized to `null`.
 
-    This function returns true iff the JSON value is null.
+    #### Limits
 
-    @return `true` if type is null, `false` otherwise.
+    [RFC 7159](http://rfc7159.net/rfc7159) states:
+    > This specification allows implementations to set limits on the range and
+    > precision of numbers accepted. Since software that implements IEEE
+    > 754-2008 binary64 (double precision) numbers is generally available and
+    > widely used, good interoperability can be achieved by implementations
+    > that expect no more precision or range than these provide, in the sense
+    > that implementations will approximate JSON numbers within the expected
+    > precision.
 
-    @complexity Constant.
+    This implementation does exactly follow this approach, as it uses double
+    precision floating-point numbers. Note values smaller than
+    `-1.79769313486232e+308` and values greater than `1.79769313486232e+308`
+    will be stored as NaN internally and be serialized to `null`.
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    #### Storage
 
-    @liveexample{The following code exemplifies `is_null()` for all JSON
-    types.,is_null}
+    Floating-point number values are stored directly inside a @ref basic_json
+    type.
+
+    @sa @ref number_integer_t -- type for number values (integer)
+
+    @sa @ref number_unsigned_t -- type for number values (unsigned integer)
 
     @since version 1.0.0
     */
-    constexpr bool is_null() const noexcept
+    using number_float_t = NumberFloatType;
+
+    /// @}
+
+  private:
+
+    /// helper for exception-safe object creation
+    template<typename T, typename... Args>
+    static T* create(Args&& ... args)
     {
-        return m_type == value_t::null;
+        AllocatorType<T> alloc;
+        auto deleter = [&](T * object)
+        {
+            alloc.deallocate(object, 1);
+        };
+        std::unique_ptr<T, decltype(deleter)> object(alloc.allocate(1), deleter);
+        alloc.construct(object.get(), std::forward<Args>(args)...);
+        assert(object != nullptr);
+        return object.release();
     }
 
-    /*!
-    @brief return whether value is a boolean
+    ////////////////////////
+    // JSON value storage //
+    ////////////////////////
 
-    This function returns true iff the JSON value is a boolean.
+    /*!
+    @brief a JSON value
 
-    @return `true` if type is boolean, `false` otherwise.
-
-    @complexity Constant.
+    The actual storage for a JSON value of the @ref basic_json class. This
+    union combines the different storage types for the JSON value types
+    defined in @ref value_t.
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    JSON type | value_t type    | used type
+    --------- | --------------- | ------------------------
+    object    | object          | pointer to @ref object_t
+    array     | array           | pointer to @ref array_t
+    string    | string          | pointer to @ref string_t
+    boolean   | boolean         | @ref boolean_t
+    number    | number_integer  | @ref number_integer_t
+    number    | number_unsigned | @ref number_unsigned_t
+    number    | number_float    | @ref number_float_t
+    null      | null            | *no value is stored*
 
-    @liveexample{The following code exemplifies `is_boolean()` for all JSON
-    types.,is_boolean}
+    @note Variable-length types (objects, arrays, and strings) are stored as
+    pointers. The size of the union should not exceed 64 bits if the default
+    value types are used.
 
     @since version 1.0.0
     */
-    constexpr bool is_boolean() const noexcept
+    union json_value
     {
-        return m_type == value_t::boolean;
-    }
-
-    /*!
-    @brief return whether value is a number
-
-    This function returns true iff the JSON value is a number. This includes
-    both integer and floating-point values.
+        /// object (stored with pointer to save storage)
+        object_t* object;
+        /// array (stored with pointer to save storage)
+        array_t* array;
+        /// string (stored with pointer to save storage)
+        string_t* string;
+        /// boolean
+        boolean_t boolean;
+        /// number (integer)
+        number_integer_t number_integer;
+        /// number (unsigned integer)
+        number_unsigned_t number_unsigned;
+        /// number (floating-point)
+        number_float_t number_float;
 
-    @return `true` if type is number (regardless whether integer, unsigned
-    integer or floating-type), `false` otherwise.
+        /// default constructor (for null values)
+        json_value() = default;
+        /// constructor for booleans
+        json_value(boolean_t v) noexcept : boolean(v) {}
+        /// constructor for numbers (integer)
+        json_value(number_integer_t v) noexcept : number_integer(v) {}
+        /// constructor for numbers (unsigned)
+        json_value(number_unsigned_t v) noexcept : number_unsigned(v) {}
+        /// constructor for numbers (floating-point)
+        json_value(number_float_t v) noexcept : number_float(v) {}
+        /// constructor for empty values of a given type
+        json_value(value_t t)
+        {
+            switch (t)
+            {
+                case value_t::object:
+                {
+                    object = create<object_t>();
+                    break;
+                }
 
-    @complexity Constant.
+                case value_t::array:
+                {
+                    array = create<array_t>();
+                    break;
+                }
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+                case value_t::string:
+                {
+                    string = create<string_t>("");
+                    break;
+                }
 
-    @liveexample{The following code exemplifies `is_number()` for all JSON
-    types.,is_number}
+                case value_t::boolean:
+                {
+                    boolean = boolean_t(false);
+                    break;
+                }
 
-    @sa @ref is_number_integer() -- check if value is an integer or unsigned
-    integer number
-    @sa @ref is_number_unsigned() -- check if value is an unsigned integer
-    number
-    @sa @ref is_number_float() -- check if value is a floating-point number
+                case value_t::number_integer:
+                {
+                    number_integer = number_integer_t(0);
+                    break;
+                }
 
-    @since version 1.0.0
-    */
-    constexpr bool is_number() const noexcept
-    {
-        return is_number_integer() or is_number_float();
-    }
+                case value_t::number_unsigned:
+                {
+                    number_unsigned = number_unsigned_t(0);
+                    break;
+                }
 
-    /*!
-    @brief return whether value is an integer number
+                case value_t::number_float:
+                {
+                    number_float = number_float_t(0.0);
+                    break;
+                }
 
-    This function returns true iff the JSON value is an integer or unsigned
-    integer number. This excludes floating-point values.
+                case value_t::null:
+                {
+                    break;
+                }
 
-    @return `true` if type is an integer or unsigned integer number, `false`
-    otherwise.
+                default:
+                {
+                    if (JSON_UNLIKELY(t == value_t::null))
+                    {
+                        JSON_THROW(other_error::create(500, "961c151d2e87f2686a955a9be24d316f1362bf21 2.1.1")); // LCOV_EXCL_LINE
+                    }
+                    break;
+                }
+            }
+        }
 
-    @complexity Constant.
+        /// constructor for strings
+        json_value(const string_t& value)
+        {
+            string = create<string_t>(value);
+        }
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+        /// constructor for objects
+        json_value(const object_t& value)
+        {
+            object = create<object_t>(value);
+        }
 
-    @liveexample{The following code exemplifies `is_number_integer()` for all
-    JSON types.,is_number_integer}
+        /// constructor for arrays
+        json_value(const array_t& value)
+        {
+            array = create<array_t>(value);
+        }
+    };
 
-    @sa @ref is_number() -- check if value is a number
-    @sa @ref is_number_unsigned() -- check if value is an unsigned integer
-    number
-    @sa @ref is_number_float() -- check if value is a floating-point number
+    /*!
+    @brief checks the class invariants
 
-    @since version 1.0.0
+    This function asserts the class invariants. It needs to be called at the
+    end of every constructor to make sure that created objects respect the
+    invariant. Furthermore, it has to be called each time the type of a JSON
+    value is changed, because the invariant expresses a relationship between
+    @a m_type and @a m_value.
     */
-    constexpr bool is_number_integer() const noexcept
+    void assert_invariant() const
     {
-        return m_type == value_t::number_integer or m_type == value_t::number_unsigned;
+        assert(m_type != value_t::object or m_value.object != nullptr);
+        assert(m_type != value_t::array or m_value.array != nullptr);
+        assert(m_type != value_t::string or m_value.string != nullptr);
     }
 
-    /*!
-    @brief return whether value is an unsigned integer number
-
-    This function returns true iff the JSON value is an unsigned integer
-    number. This excludes floating-point and (signed) integer values.
+  public:
+    //////////////////////////
+    // JSON parser callback //
+    //////////////////////////
 
-    @return `true` if type is an unsigned integer number, `false` otherwise.
+    using parse_event_t = typename parser::parse_event_t;
 
-    @complexity Constant.
+    /*!
+    @brief per-element parser callback type
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    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.
 
-    @liveexample{The following code exemplifies `is_number_unsigned()` for all
-    JSON types.,is_number_unsigned}
+    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.
 
-    @sa @ref is_number() -- check if value is a number
-    @sa @ref is_number_integer() -- check if value is an integer or unsigned
-    integer number
-    @sa @ref is_number_float() -- check if value is a floating-point number
+    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
 
-    @since version 2.0.0
-    */
-    constexpr bool is_number_unsigned() const noexcept
-    {
-        return m_type == value_t::number_unsigned;
-    }
+    @image html callback_events.png "Example when certain parse events are triggered"
 
-    /*!
-    @brief return whether value is a floating-point number
+    Discarding a value (i.e., returning `false`) has different effects
+    depending on the context in which function was called:
 
-    This function returns true iff the JSON value is a floating-point number.
-    This excludes integer and unsigned integer values.
+    - 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.
 
-    @return `true` if type is a floating-point number, `false` otherwise.
+    @param[in] depth  the depth of the recursion during parsing
 
-    @complexity Constant.
+    @param[in] event  an event of type parse_event_t indicating the context in
+    the callback function has been called
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    @param[in,out] parsed  the current intermediate parse result; note that
+    writing to this value has no effect for parse_event_t::key events
 
-    @liveexample{The following code exemplifies `is_number_float()` for all
-    JSON types.,is_number_float}
+    @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 is_number() -- check if value is number
-    @sa @ref is_number_integer() -- check if value is an integer number
-    @sa @ref is_number_unsigned() -- check if value is an unsigned integer
-    number
+    @sa @ref parse(std::istream&, parser_callback_t) or
+    @ref parse(const CharT, const parser_callback_t) for examples
 
     @since version 1.0.0
     */
-    constexpr bool is_number_float() const noexcept
-    {
-        return m_type == value_t::number_float;
-    }
+    using parser_callback_t = typename parser::parser_callback_t;
 
-    /*!
-    @brief return whether value is an object
 
-    This function returns true iff the JSON value is an object.
+    //////////////////
+    // constructors //
+    //////////////////
 
-    @return `true` if type is object, `false` otherwise.
+    /// @name constructors and destructors
+    /// Constructors of class @ref basic_json, copy/move constructor, copy
+    /// assignment, static functions creating objects, and the destructor.
+    /// @{
 
-    @complexity Constant.
+    /*!
+    @brief create an empty value with a given type
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    Create an empty JSON value with a given type. The value will be default
+    initialized with an empty value which depends on the type:
 
-    @liveexample{The following code exemplifies `is_object()` for all JSON
-    types.,is_object}
+    Value type  | initial value
+    ----------- | -------------
+    null        | `null`
+    boolean     | `false`
+    string      | `""`
+    number      | `0`
+    object      | `{}`
+    array       | `[]`
+
+    @param[in] v  the type of the value to create
+
+    @complexity Constant.
+
+    @liveexample{The following code shows the constructor for different @ref
+    value_t values,basic_json__value_t}
 
     @since version 1.0.0
     */
-    constexpr bool is_object() const noexcept
+    basic_json(const value_t v)
+        : m_type(v), m_value(v)
     {
-        return m_type == value_t::object;
+        assert_invariant();
     }
 
     /*!
-    @brief return whether value is an array
-
-    This function returns true iff the JSON value is an array.
+    @brief create a null object
 
-    @return `true` if type is array, `false` otherwise.
+    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 member function never throws
+    @exceptionsafety No-throw guarantee: this constructor never throws
     exceptions.
 
-    @liveexample{The following code exemplifies `is_array()` for all JSON
-    types.,is_array}
+    @liveexample{The following code shows the constructor with and without a
+    null pointer parameter.,basic_json__nullptr_t}
 
     @since version 1.0.0
     */
-    constexpr bool is_array() const noexcept
+    basic_json(std::nullptr_t = nullptr) noexcept
+        : basic_json(value_t::null)
     {
-        return m_type == value_t::array;
+        assert_invariant();
     }
 
     /*!
-    @brief return whether value is a string
+    @brief create a JSON value
 
-    This function returns true iff the JSON value is a string.
+    This is a "catch all" constructor for all compatible JSON types; that is,
+    types for which a `to_json()` method exsits. The constructor forwards the
+    parameter @a val to that method (to `json_serializer<U>::to_json` method
+    with `U = uncvref_t<CompatibleType>`, to be exact).
 
-    @return `true` if type is string, `false` otherwise.
+    Template type @a CompatibleType includes, but is not limited to, the
+    following types:
+    - **arrays**: @ref array_t and all kinds of compatible containers such as
+      `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.
+    - **objects**: @ref object_t and all kinds of compatible associative
+      containers such as `std::map`, `std::unordered_map`, `std::multimap`,
+      and `std::unordered_multimap` with a `key_type` compatible to
+      @ref string_t and a `value_type` from which a @ref basic_json value can
+      be constructed.
+    - **strings**: @ref string_t, string literals, and all compatible string
+      containers can be used.
+    - **numbers**: @ref number_integer_t, @ref number_unsigned_t,
+      @ref number_float_t, and all convertible number types such as `int`,
+      `size_t`, `int64_t`, `float` or `double` can be used.
+    - **boolean**: @ref boolean_t / `bool` can be used.
 
-    @complexity Constant.
+    See the examples below.
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    @tparam CompatibleType a type such that:
+    - @a CompatibleType is not derived from `std::istream`,
+    - @a CompatibleType is not @ref basic_json (to avoid hijacking copy/move
+         constructors),
+    - @a CompatibleType is not a @ref basic_json nested type (e.g.,
+         @ref json_pointer, @ref iterator, etc ...)
+    - @ref @ref json_serializer<U> has a
+         `to_json(basic_json_t&, CompatibleType&&)` method
 
-    @liveexample{The following code exemplifies `is_string()` for all JSON
-    types.,is_string}
+    @tparam U = `uncvref_t<CompatibleType>`
 
-    @since version 1.0.0
+    @param[in] val the value to be forwarded
+
+    @complexity Usually linear in the size of the passed @a val, also
+                depending on the implementation of the called `to_json()`
+                method.
+
+    @throw what `json_serializer<U>::to_json()` throws
+
+    @liveexample{The following code shows the constructor with several
+    compatible types.,basic_json__CompatibleType}
+
+    @since version 2.1.0
     */
-    constexpr bool is_string() const noexcept
+    template<typename CompatibleType, typename U = detail::uncvref_t<CompatibleType>,
+             detail::enable_if_t<not std::is_base_of<std::istream, U>::value and
+                                 not std::is_same<U, basic_json_t>::value and
+                                 not detail::is_basic_json_nested_type<
+                                     basic_json_t, U>::value and
+                                 detail::has_to_json<basic_json, U>::value,
+                                 int> = 0>
+    basic_json(CompatibleType && val) noexcept(noexcept(JSONSerializer<U>::to_json(
+                std::declval<basic_json_t&>(), std::forward<CompatibleType>(val))))
     {
-        return m_type == value_t::string;
+        JSONSerializer<U>::to_json(*this, std::forward<CompatibleType>(val));
+        assert_invariant();
     }
 
     /*!
-    @brief return whether value is discarded
+    @brief create a container (array or object) from an initializer list
 
-    This function returns true iff the JSON value was discarded during parsing
-    with a callback function (see @ref parser_callback_t).
+    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:
 
-    @note This function will always be `false` for JSON values after parsing.
-    That is, discarded values can only occur during parsing, but will be
-    removed when inside a structured value or replaced by null in other cases.
+    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.
 
-    @return `true` if type is discarded, `false` otherwise.
+    The rules aim to create the best fit between a C++ initializer list and
+    JSON values. The rationale is as follows:
 
-    @complexity Constant.
+    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.
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    With the rules described above, the following JSON values cannot be
+    expressed by an initializer list:
 
-    @liveexample{The following code exemplifies `is_discarded()` for all JSON
-    types.,is_discarded}
+    - 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
 
-    @since version 1.0.0
-    */
-    constexpr bool is_discarded() const noexcept
-    {
-        return m_type == value_t::discarded;
-    }
+    @note When used without parentheses around an empty initializer list, @ref
+    basic_json() is called instead of this function, yielding the JSON null
+    value.
 
-    /*!
-    @brief return the type of the JSON value (implicit)
+    @param[in] init  initializer list with JSON values
 
-    Implicitly return the type of the JSON value as a value from the @ref
-    value_t enumeration.
+    @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>).
 
-    @return the type of the JSON value
+    @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
 
-    @complexity Constant.
+    @throw type_error.301 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. In this case, the constructor could not
+    create an object. If @a type_deduction would have be `true`, an array
+    would have been created. See @ref object(std::initializer_list<basic_json>)
+    for an example.
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    @complexity Linear in the size of the initializer list @a init.
 
-    @liveexample{The following code exemplifies the @ref value_t operator for
-    all JSON types.,operator__value_t}
+    @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
     */
-    constexpr operator value_t() const noexcept
+    basic_json(std::initializer_list<basic_json> init,
+               bool type_deduction = true,
+               value_t manual_type = value_t::array)
     {
-        return m_type;
-    }
-
-    /// @}
-
-  private:
-    //////////////////
-    // value access //
-    //////////////////
+        // 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();
+        });
 
-    /// get a boolean (explicit)
-    boolean_t get_impl(boolean_t* /*unused*/) const
-    {
-        if (is_boolean())
+        // adjust type if type deduction is not wanted
+        if (not type_deduction)
         {
-            return m_value.boolean;
+            // 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(type_error::create(301, "cannot create object from initializer list"));
+            }
         }
 
-        JSON_THROW(type_error::create(302, "type must be boolean, but is " + type_name()));
-    }
+        if (is_an_object)
+        {
+            // the initializer list is a list of pairs -> create object
+            m_type = value_t::object;
+            m_value = value_t::object;
 
-    /// get a pointer to the value (object)
-    object_t* get_impl_ptr(object_t* /*unused*/) noexcept
-    {
-        return is_object() ? m_value.object : nullptr;
-    }
+            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);
+        }
 
-    /// get a pointer to the value (object)
-    constexpr const object_t* get_impl_ptr(const object_t* /*unused*/) const noexcept
-    {
-        return is_object() ? m_value.object : nullptr;
+        assert_invariant();
     }
 
-    /// get a pointer to the value (array)
-    array_t* get_impl_ptr(array_t* /*unused*/) noexcept
-    {
-        return is_array() ? m_value.array : nullptr;
-    }
+    /*!
+    @brief explicitly create an array from an initializer list
 
-    /// get a pointer to the value (array)
-    constexpr const array_t* get_impl_ptr(const array_t* /*unused*/) const noexcept
-    {
-        return is_array() ? m_value.array : nullptr;
-    }
+    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.
 
-    /// get a pointer to the value (string)
-    string_t* get_impl_ptr(string_t* /*unused*/) noexcept
-    {
-        return is_string() ? m_value.string : nullptr;
-    }
+    @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
 
-    /// get a pointer to the value (string)
-    constexpr const string_t* get_impl_ptr(const string_t* /*unused*/) const noexcept
-    {
-        return is_string() ? m_value.string : nullptr;
-    }
+    @param[in] init  initializer list with JSON values to create an array from
+    (optional)
 
-    /// get a pointer to the value (boolean)
-    boolean_t* get_impl_ptr(boolean_t* /*unused*/) noexcept
-    {
-        return is_boolean() ? &m_value.boolean : nullptr;
-    }
+    @return JSON array value
 
-    /// get a pointer to the value (boolean)
-    constexpr const boolean_t* get_impl_ptr(const boolean_t* /*unused*/) const noexcept
-    {
-        return is_boolean() ? &m_value.boolean : nullptr;
-    }
+    @complexity Linear in the size of @a init.
 
-    /// get a pointer to the value (integer number)
-    number_integer_t* get_impl_ptr(number_integer_t* /*unused*/) noexcept
-    {
-        return is_number_integer() ? &m_value.number_integer : nullptr;
-    }
+    @liveexample{The following code shows an example for the `array`
+    function.,array}
 
-    /// get a pointer to the value (integer number)
-    constexpr const number_integer_t* get_impl_ptr(const number_integer_t* /*unused*/) const noexcept
-    {
-        return is_number_integer() ? &m_value.number_integer : nullptr;
-    }
+    @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
 
-    /// get a pointer to the value (unsigned number)
-    number_unsigned_t* get_impl_ptr(number_unsigned_t* /*unused*/) noexcept
+    @since version 1.0.0
+    */
+    static basic_json array(std::initializer_list<basic_json> init =
+                                std::initializer_list<basic_json>())
     {
-        return is_number_unsigned() ? &m_value.number_unsigned : nullptr;
+        return basic_json(init, false, value_t::array);
     }
 
-    /// get a pointer to the value (unsigned number)
-    constexpr const number_unsigned_t* get_impl_ptr(const number_unsigned_t* /*unused*/) const noexcept
-    {
-        return is_number_unsigned() ? &m_value.number_unsigned : nullptr;
-    }
+    /*!
+    @brief explicitly create an object from an initializer list
 
-    /// get a pointer to the value (floating-point number)
-    number_float_t* get_impl_ptr(number_float_t* /*unused*/) noexcept
-    {
-        return is_number_float() ? &m_value.number_float : nullptr;
-    }
+    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.
 
-    /// get a pointer to the value (floating-point number)
-    constexpr const number_float_t* get_impl_ptr(const number_float_t* /*unused*/) const noexcept
-    {
-        return is_number_float() ? &m_value.number_float : nullptr;
-    }
+    @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).
 
-    /*!
-    @brief helper function to implement get_ref()
+    @param[in] init  initializer list to create an object from (optional)
 
-    This function helps to implement get_ref() without code duplication for
-    const and non-const overloads
+    @return JSON object value
 
-    @tparam ThisType will be deduced as `basic_json` or `const basic_json`
+    @throw type_error.301 if @a init is not a list of pairs whose first
+    elements are strings. In this case, no object can be created. When such a
+    value is passed to @ref basic_json(std::initializer_list<basic_json>, bool, value_t),
+    an array would have been created from the passed initializer list @a init.
+    See example below.
 
-    @throw type_error.303 if ReferenceType does not match underlying value
-    type of the current JSON
-    */
-    template<typename ReferenceType, typename ThisType>
-    static ReferenceType get_ref_impl(ThisType& obj)
-    {
-        // helper type
-        using PointerType = typename std::add_pointer<ReferenceType>::type;
+    @complexity Linear in the size of @a init.
 
-        // delegate the call to get_ptr<>()
-        auto ptr = obj.template get_ptr<PointerType>();
+    @liveexample{The following code shows an example for the `object`
+    function.,object}
 
-        if (ptr != nullptr)
-        {
-            return *ptr;
-        }
+    @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
 
-        JSON_THROW(type_error::create(303, "incompatible ReferenceType for get_ref, actual type is " + obj.type_name()));
+    @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);
     }
 
-  public:
-    /// @name value access
-    /// Direct access to the stored value of a JSON value.
-    /// @{
-
     /*!
-    @brief get special-case overload
+    @brief construct an array with count copies of given value
 
-    This overloads avoids a lot of template boilerplate, it can be seen as the
-    identity method
+    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.
 
-    @tparam BasicJsonType == @ref basic_json
+    @param[in] cnt  the number of JSON copies of @a val to create
+    @param[in] val  the JSON value to copy
 
-    @return a copy of *this
+    @complexity Linear in @a cnt.
 
-    @complexity Constant.
+    @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 2.1.0
+    @since version 1.0.0
     */
-    template <
-        typename BasicJsonType,
-        detail::enable_if_t<std::is_same<typename std::remove_const<BasicJsonType>::type,
-                                         basic_json_t>::value,
-                            int> = 0 >
-    basic_json get() const
+    basic_json(size_type cnt, const basic_json& val)
+        : m_type(value_t::array)
     {
-        return *this;
+        m_value.array = create<array_t>(cnt, val);
+        assert_invariant();
     }
 
     /*!
-    @brief get a value (explicit)
+    @brief construct a JSON container given an iterator range
 
-    Explicit type conversion between the JSON value and a compatible value
-    which is [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible)
-    and [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible).
-    The value is converted by calling the @ref json_serializer<ValueType>
-    `from_json()` method.
+    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, invalid_iterator.204 is thrown.
+    - In case of structured types (array, object), the constructor behaves as
+      similar versions for `std::vector`.
+    - In case of a null type, invalid_iterator.206 is thrown.
 
-    The function is equivalent to executing
-    @code {.cpp}
-    ValueType ret;
-    JSONSerializer<ValueType>::from_json(*this, ret);
-    return ret;
-    @endcode
+    @tparam InputIT an input iterator type (@ref iterator or @ref
+    const_iterator)
 
-    This overloads is chosen if:
-    - @a ValueType is not @ref basic_json,
-    - @ref json_serializer<ValueType> has a `from_json()` method of the form
-      `void from_json(const basic_json&, ValueType&)`, and
-    - @ref json_serializer<ValueType> does not have a `from_json()` method of
-      the form `ValueType from_json(const basic_json&)`
+    @param[in] first begin of the range to copy from (included)
+    @param[in] last end of the range to copy from (excluded)
 
-    @tparam ValueTypeCV the provided value type
-    @tparam ValueType the returned value type
+    @pre Iterators @a first and @a last must be initialized. **This
+         precondition is enforced with an assertion.**
 
-    @return copy of the JSON value, converted to @a ValueType
+    @pre Range `[first, last)` is valid. Usually, this precondition cannot be
+         checked efficiently. Only certain edge cases are detected; see the
+         description of the exceptions below.
 
-    @throw what @ref json_serializer<ValueType> `from_json()` method throws
+    @throw invalid_iterator.201 if iterators @a first and @a last are not
+    compatible (i.e., do not belong to the same JSON value). In this case,
+    the range `[first, last)` is undefined.
+    @throw invalid_iterator.204 if iterators @a first and @a last belong to a
+    primitive type (number, boolean, or string), but @a first does not point
+    to the first element any more. In this case, the range `[first, last)` is
+    undefined. See example code below.
+    @throw invalid_iterator.206 if iterators @a first and @a last belong to a
+    null value. In this case, the range `[first, last)` is undefined.
 
-    @liveexample{The example below shows several conversions from JSON values
-    to other types. There a few things to note: (1) Floating-point numbers can
-    be converted to integers\, (2) A JSON array can be converted to a standard
-    `std::vector<short>`\, (3) A JSON object can be converted to C++
-    associative containers such as `std::unordered_map<std::string\,
-    json>`.,get__ValueType_const}
+    @complexity Linear in distance between @a first and @a last.
 
-    @since version 2.1.0
+    @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 <
-        typename ValueTypeCV,
-        typename ValueType = detail::uncvref_t<ValueTypeCV>,
-        detail::enable_if_t <
-            not std::is_same<basic_json_t, ValueType>::value and
-            detail::has_from_json<basic_json_t, ValueType>::value and
-            not detail::has_non_default_from_json<basic_json_t, ValueType>::value,
-            int > = 0 >
-    ValueType get() const noexcept(noexcept(
-                                       JSONSerializer<ValueType>::from_json(std::declval<const basic_json_t&>(), std::declval<ValueType&>())))
+    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)
     {
-        // we cannot static_assert on ValueTypeCV being non-const, because
-        // there is support for get<const basic_json_t>(), which is why we
-        // still need the uncvref
-        static_assert(not std::is_reference<ValueTypeCV>::value,
-                      "get() cannot be used with reference types, you might want to use get_ref()");
-        static_assert(std::is_default_constructible<ValueType>::value,
-                      "types must be DefaultConstructible when used with get()");
+        assert(first.m_object != nullptr);
+        assert(last.m_object != nullptr);
 
-        ValueType ret;
-        JSONSerializer<ValueType>::from_json(*this, ret);
-        return ret;
-    }
+        // make sure iterator fits the current value
+        if (first.m_object != last.m_object)
+        {
+            JSON_THROW(invalid_iterator::create(201, "iterators are not compatible"));
+        }
 
-    /*!
-    @brief get a value (explicit); special case
+        // copy type from first iterator
+        m_type = first.m_object->m_type;
 
-    Explicit type conversion between the JSON value and a compatible value
-    which is **not** [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible)
-    and **not** [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible).
-    The value is converted by calling the @ref json_serializer<ValueType>
-    `from_json()` method.
+        // 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(invalid_iterator::create(204, "iterators out of range"));
+                }
+                break;
+            }
 
-    The function is equivalent to executing
-    @code {.cpp}
-    return JSONSerializer<ValueTypeCV>::from_json(*this);
-    @endcode
+            default:
+            {
+                break;
+            }
+        }
 
-    This overloads is chosen if:
-    - @a ValueType is not @ref basic_json and
-    - @ref json_serializer<ValueType> has a `from_json()` method of the form
-      `ValueType from_json(const basic_json&)`
+        switch (m_type)
+        {
+            case value_t::number_integer:
+            {
+                m_value.number_integer = first.m_object->m_value.number_integer;
+                break;
+            }
 
-    @note If @ref json_serializer<ValueType> has both overloads of
-    `from_json()`, this one is chosen.
+            case value_t::number_unsigned:
+            {
+                m_value.number_unsigned = first.m_object->m_value.number_unsigned;
+                break;
+            }
 
-    @tparam ValueTypeCV the provided value type
-    @tparam ValueType the returned value type
+            case value_t::number_float:
+            {
+                m_value.number_float = first.m_object->m_value.number_float;
+                break;
+            }
 
-    @return copy of the JSON value, converted to @a ValueType
+            case value_t::boolean:
+            {
+                m_value.boolean = first.m_object->m_value.boolean;
+                break;
+            }
 
-    @throw what @ref json_serializer<ValueType> `from_json()` method throws
+            case value_t::string:
+            {
+                m_value = *first.m_object->m_value.string;
+                break;
+            }
 
-    @since version 2.1.0
-    */
-    template <
-        typename ValueTypeCV,
-        typename ValueType = detail::uncvref_t<ValueTypeCV>,
-        detail::enable_if_t<not std::is_same<basic_json_t, ValueType>::value and
-                            detail::has_non_default_from_json<basic_json_t,
-                                    ValueType>::value, int> = 0 >
-    ValueType get() const noexcept(noexcept(
-                                       JSONSerializer<ValueTypeCV>::from_json(std::declval<const basic_json_t&>())))
-    {
-        static_assert(not std::is_reference<ValueTypeCV>::value,
-                      "get() cannot be used with reference types, you might want to use get_ref()");
-        return JSONSerializer<ValueTypeCV>::from_json(*this);
+            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);
+                break;
+            }
+
+            default:
+            {
+                JSON_THROW(invalid_iterator::create(206, "cannot construct with iterators from " +
+                                                    first.m_object->type_name()));
+            }
+        }
+
+        assert_invariant();
     }
 
-    /*!
-    @brief get a pointer value (explicit)
 
-    Explicit pointer access to the internally stored JSON value. No copies are
-    made.
+    ///////////////////////////////////////
+    // other constructors and destructor //
+    ///////////////////////////////////////
 
-    @warning The pointer becomes invalid if the underlying JSON object
-    changes.
+    /*!
+    @brief copy constructor
 
-    @tparam PointerType pointer type; must be a pointer to @ref array_t, @ref
-    object_t, @ref string_t, @ref boolean_t, @ref number_integer_t,
-    @ref number_unsigned_t, or @ref number_float_t.
+    Creates a copy of a given JSON value.
 
-    @return pointer to the internally stored JSON value if the requested
-    pointer type @a PointerType fits to the JSON value; `nullptr` otherwise
+    @param[in] other  the JSON value to copy
 
-    @complexity Constant.
+    @complexity Linear in the size of @a other.
 
-    @liveexample{The example below shows how pointers to internal values of a
-    JSON value can be requested. Note that no type conversions are made and a
-    `nullptr` is returned if the value and the requested pointer type does not
-    match.,get__PointerType}
+    @requirement This function helps `basic_json` satisfying the
+    [Container](http://en.cppreference.com/w/cpp/concept/Container)
+    requirements:
+    - The complexity is linear.
+    - As postcondition, it holds: `other == basic_json(other)`.
 
-    @sa @ref get_ptr() for explicit pointer-member access
+    @liveexample{The following code shows an example for the copy
+    constructor.,basic_json__basic_json}
 
     @since version 1.0.0
     */
-    template<typename PointerType, typename std::enable_if<
-                 std::is_pointer<PointerType>::value, int>::type = 0>
-    PointerType get() noexcept
+    basic_json(const basic_json& other)
+        : m_type(other.m_type)
     {
-        // delegate the call to get_ptr
-        return get_ptr<PointerType>();
-    }
+        // check of passed value is valid
+        other.assert_invariant();
 
-    /*!
-    @brief get a pointer value (explicit)
-    @copydoc get()
-    */
-    template<typename PointerType, typename std::enable_if<
-                 std::is_pointer<PointerType>::value, int>::type = 0>
-    constexpr const PointerType get() const noexcept
-    {
-        // delegate the call to get_ptr
-        return get_ptr<PointerType>();
+        switch (m_type)
+        {
+            case value_t::object:
+            {
+                m_value = *other.m_value.object;
+                break;
+            }
+
+            case value_t::array:
+            {
+                m_value = *other.m_value.array;
+                break;
+            }
+
+            case value_t::string:
+            {
+                m_value = *other.m_value.string;
+                break;
+            }
+
+            case value_t::boolean:
+            {
+                m_value = other.m_value.boolean;
+                break;
+            }
+
+            case value_t::number_integer:
+            {
+                m_value = other.m_value.number_integer;
+                break;
+            }
+
+            case value_t::number_unsigned:
+            {
+                m_value = other.m_value.number_unsigned;
+                break;
+            }
+
+            case value_t::number_float:
+            {
+                m_value = other.m_value.number_float;
+                break;
+            }
+
+            default:
+            {
+                break;
+            }
+        }
+
+        assert_invariant();
     }
 
     /*!
-    @brief get a pointer value (implicit)
-
-    Implicit pointer access to the internally stored JSON value. No copies are
-    made.
+    @brief move constructor
 
-    @warning Writing data to the pointee of the result yields an undefined
-    state.
+    Move constructor. Constructs a JSON value with the contents of the given
+    value @a other using move semantics. It "steals" the resources from @a
+    other and leaves it as JSON null value.
 
-    @tparam PointerType pointer type; must be a pointer to @ref array_t, @ref
-    object_t, @ref string_t, @ref boolean_t, @ref number_integer_t,
-    @ref number_unsigned_t, or @ref number_float_t. Enforced by a static
-    assertion.
+    @param[in,out] other  value to move to this object
 
-    @return pointer to the internally stored JSON value if the requested
-    pointer type @a PointerType fits to the JSON value; `nullptr` otherwise
+    @post @a other is a JSON null value
 
     @complexity Constant.
 
-    @liveexample{The example below shows how pointers to internal values of a
-    JSON value can be requested. Note that no type conversions are made and a
-    `nullptr` is returned if the value and the requested pointer type does not
-    match.,get_ptr}
+    @liveexample{The code below shows the move constructor explicitly called
+    via std::move.,basic_json__moveconstructor}
 
     @since version 1.0.0
     */
-    template<typename PointerType, typename std::enable_if<
-                 std::is_pointer<PointerType>::value, int>::type = 0>
-    PointerType get_ptr() noexcept
+    basic_json(basic_json&& other) noexcept
+        : m_type(std::move(other.m_type)),
+          m_value(std::move(other.m_value))
     {
-        // get the type of the PointerType (remove pointer and const)
-        using pointee_t = typename std::remove_const<typename
-                          std::remove_pointer<typename
-                          std::remove_const<PointerType>::type>::type>::type;
-        // make sure the type matches the allowed types
-        static_assert(
-            std::is_same<object_t, pointee_t>::value
-            or std::is_same<array_t, pointee_t>::value
-            or std::is_same<string_t, pointee_t>::value
-            or std::is_same<boolean_t, pointee_t>::value
-            or std::is_same<number_integer_t, pointee_t>::value
-            or std::is_same<number_unsigned_t, pointee_t>::value
-            or std::is_same<number_float_t, pointee_t>::value
-            , "incompatible pointer type");
-
-        // delegate the call to get_impl_ptr<>()
-        return get_impl_ptr(static_cast<PointerType>(nullptr));
-    }
+        // check that passed value is valid
+        other.assert_invariant();
 
-    /*!
-    @brief get a pointer value (implicit)
-    @copydoc get_ptr()
-    */
-    template<typename PointerType, typename std::enable_if<
-                 std::is_pointer<PointerType>::value and
-                 std::is_const<typename std::remove_pointer<PointerType>::type>::value, int>::type = 0>
-    constexpr const PointerType get_ptr() const noexcept
-    {
-        // get the type of the PointerType (remove pointer and const)
-        using pointee_t = typename std::remove_const<typename
-                          std::remove_pointer<typename
-                          std::remove_const<PointerType>::type>::type>::type;
-        // make sure the type matches the allowed types
-        static_assert(
-            std::is_same<object_t, pointee_t>::value
-            or std::is_same<array_t, pointee_t>::value
-            or std::is_same<string_t, pointee_t>::value
-            or std::is_same<boolean_t, pointee_t>::value
-            or std::is_same<number_integer_t, pointee_t>::value
-            or std::is_same<number_unsigned_t, pointee_t>::value
-            or std::is_same<number_float_t, pointee_t>::value
-            , "incompatible pointer type");
+        // invalidate payload
+        other.m_type = value_t::null;
+        other.m_value = {};
 
-        // delegate the call to get_impl_ptr<>() const
-        return get_impl_ptr(static_cast<const PointerType>(nullptr));
+        assert_invariant();
     }
 
     /*!
-    @brief get a reference value (implicit)
-
-    Implicit reference access to the internally stored JSON value. No copies
-    are made.
-
-    @warning Writing data to the referee of the result yields an undefined
-    state.
+    @brief copy assignment
 
-    @tparam ReferenceType reference type; must be a reference to @ref array_t,
-    @ref object_t, @ref string_t, @ref boolean_t, @ref number_integer_t, or
-    @ref number_float_t. Enforced by static assertion.
+    Copy assignment operator. Copies a JSON value via the "copy and swap"
+    strategy: It is expressed in terms of the copy constructor, destructor,
+    and the swap() member function.
 
-    @return reference to the internally stored JSON value if the requested
-    reference type @a ReferenceType fits to the JSON value; throws
-    type_error.303 otherwise
+    @param[in] other  value to copy from
 
-    @throw type_error.303 in case passed type @a ReferenceType is incompatible
-    with the stored JSON value; see example below
+    @complexity Linear.
 
-    @complexity Constant.
+    @requirement This function helps `basic_json` satisfying the
+    [Container](http://en.cppreference.com/w/cpp/concept/Container)
+    requirements:
+    - The complexity is linear.
 
-    @liveexample{The example shows several calls to `get_ref()`.,get_ref}
+    @liveexample{The code below shows and example for the copy assignment. It
+    creates a copy of value `a` which is then swapped with `b`. Finally\, the
+    copy of `a` (which is the null value after the swap) is
+    destroyed.,basic_json__copyassignment}
 
-    @since version 1.1.0
+    @since version 1.0.0
     */
-    template<typename ReferenceType, typename std::enable_if<
-                 std::is_reference<ReferenceType>::value, int>::type = 0>
-    ReferenceType get_ref()
+    reference& operator=(basic_json other) noexcept (
+        std::is_nothrow_move_constructible<value_t>::value and
+        std::is_nothrow_move_assignable<value_t>::value and
+        std::is_nothrow_move_constructible<json_value>::value and
+        std::is_nothrow_move_assignable<json_value>::value
+    )
     {
-        // delegate call to get_ref_impl
-        return get_ref_impl<ReferenceType>(*this);
-    }
+        // check that passed value is valid
+        other.assert_invariant();
 
-    /*!
-    @brief get a reference value (implicit)
-    @copydoc get_ref()
-    */
-    template<typename ReferenceType, typename std::enable_if<
-                 std::is_reference<ReferenceType>::value and
-                 std::is_const<typename std::remove_reference<ReferenceType>::type>::value, int>::type = 0>
-    ReferenceType get_ref() const
-    {
-        // delegate call to get_ref_impl
-        return get_ref_impl<ReferenceType>(*this);
+        using std::swap;
+        swap(m_type, other.m_type);
+        swap(m_value, other.m_value);
+
+        assert_invariant();
+        return *this;
     }
 
     /*!
-    @brief get a value (implicit)
-
-    Implicit type conversion between the JSON value and a compatible value.
-    The call is realized by calling @ref get() const.
-
-    @tparam ValueType non-pointer type compatible to the JSON value, for
-    instance `int` for JSON integer numbers, `bool` for JSON booleans, or
-    `std::vector` types for JSON arrays. The character type of @ref string_t
-    as well as an initializer list of this type is excluded to avoid
-    ambiguities as these types implicitly convert to `std::string`.
-
-    @return copy of the JSON value, converted to type @a ValueType
+    @brief destructor
 
-    @throw type_error.302 in case passed type @a ValueType is incompatible
-    to the JSON value type (e.g., the JSON value is of type boolean, but a
-    string is requested); see example below
+    Destroys the JSON value and frees all allocated memory.
 
-    @complexity Linear in the size of the JSON value.
+    @complexity Linear.
 
-    @liveexample{The example below shows several conversions from JSON values
-    to other types. There a few things to note: (1) Floating-point numbers can
-    be converted to integers\, (2) A JSON array can be converted to a standard
-    `std::vector<short>`\, (3) A JSON object can be converted to C++
-    associative containers such as `std::unordered_map<std::string\,
-    json>`.,operator__ValueType}
+    @requirement This function helps `basic_json` satisfying the
+    [Container](http://en.cppreference.com/w/cpp/concept/Container)
+    requirements:
+    - The complexity is linear.
+    - All stored elements are destroyed and all memory is freed.
 
     @since version 1.0.0
     */
-    template < typename ValueType, typename std::enable_if <
-                   not std::is_pointer<ValueType>::value and
-                   not std::is_same<ValueType, typename string_t::value_type>::value
-#ifndef _MSC_VER  // fix for issue #167 operator<< ambiguity under VS2015
-                   and not std::is_same<ValueType, std::initializer_list<typename string_t::value_type>>::value
-#endif
-#if (defined(__cplusplus) && __cplusplus >= 201703L) || (defined(_MSC_VER) && _MSC_VER >1900 && defined(_HAS_CXX17) && _HAS_CXX17 == 1) // fix for issue #464
-                   and not std::is_same<ValueType, typename std::string_view>::value
-#endif
-                   , int >::type = 0 >
-    operator ValueType() const
+    ~basic_json()
     {
-        // delegate the call to get<>() const
-        return get<ValueType>();
+        assert_invariant();
+
+        switch (m_type)
+        {
+            case value_t::object:
+            {
+                AllocatorType<object_t> alloc;
+                alloc.destroy(m_value.object);
+                alloc.deallocate(m_value.object, 1);
+                break;
+            }
+
+            case value_t::array:
+            {
+                AllocatorType<array_t> alloc;
+                alloc.destroy(m_value.array);
+                alloc.deallocate(m_value.array, 1);
+                break;
+            }
+
+            case value_t::string:
+            {
+                AllocatorType<string_t> alloc;
+                alloc.destroy(m_value.string);
+                alloc.deallocate(m_value.string, 1);
+                break;
+            }
+
+            default:
+            {
+                // all other types need no specific destructor
+                break;
+            }
+        }
     }
 
     /// @}
 
+  public:
+    ///////////////////////
+    // object inspection //
+    ///////////////////////
 
-    ////////////////////
-    // element access //
-    ////////////////////
-
-    /// @name element access
-    /// Access to the JSON value.
+    /// @name object inspection
+    /// Functions to inspect the type of a JSON value.
     /// @{
 
     /*!
-    @brief access specified array element with bounds checking
-
-    Returns a reference to the element at specified location @a idx, with
-    bounds checking.
+    @brief serialization
 
-    @param[in] idx  index of the element to access
+    Serialization function for JSON values. The function tries to mimic
+    Python's `json.dumps()` function, and currently supports its @a indent
+    parameter.
 
-    @return reference to the element at index @a idx
+    @param[in] indent If indent is nonnegative, then array elements and object
+    members will be pretty-printed with that indent level. An indent level of
+    `0` will only insert newlines. `-1` (the default) selects the most compact
+    representation.
+    @param[in] indent_char The character to use for indentation if @a indent is
+    greater than `0`. The default is ` ` (space).
 
-    @throw type_error.304 if the JSON value is not an array; in this case,
-    calling `at` with an index makes no sense. See example below.
-    @throw out_of_range.401 if the index @a idx is out of range of the array;
-    that is, `idx >= size()`. See example below.
+    @return string containing the serialization of the JSON value
 
-    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
-    changes in the JSON value.
+    @complexity Linear.
 
-    @complexity Constant.
+    @liveexample{The following example shows the effect of different @a indent
+    parameters to the result of the serialization.,dump}
 
-    @since version 1.0.0
+    @see https://docs.python.org/2/library/json.html#json.dump
 
-    @liveexample{The example below shows how array elements can be read and
-    written using `at()`. It also demonstrates the different exceptions that
-    can be thrown.,at__size_type}
+    @since version 1.0.0; indentation character added in version 3.0.0
     */
-    reference at(size_type idx)
+    string_t dump(const int indent = -1, const char indent_char = ' ') const
     {
-        // at only works for arrays
-        if (is_array())
+        string_t result;
+        serializer s(output_adapter<char>::create(result), indent_char);
+
+        if (indent >= 0)
         {
-            JSON_TRY
-            {
-                return m_value.array->at(idx);
-            }
-            JSON_CATCH (std::out_of_range&)
-            {
-                // create better exception explanation
-                JSON_THROW(out_of_range::create(401, "array index " + std::to_string(idx) + " is out of range"));
-            }
+            s.dump(*this, true, static_cast<unsigned int>(indent));
         }
         else
         {
-            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
+            s.dump(*this, false, 0);
         }
+
+        return result;
     }
 
     /*!
-    @brief access specified array element with bounds checking
-
-    Returns a const reference to the element at specified location @a idx,
-    with bounds checking.
+    @brief return the type of the JSON value (explicit)
 
-    @param[in] idx  index of the element to access
+    Return the type of the JSON value as a value from the @ref value_t
+    enumeration.
 
-    @return const reference to the element at index @a idx
+    @return the type of the JSON value
 
-    @throw type_error.304 if the JSON value is not an array; in this case,
-    calling `at` with an index makes no sense. See example below.
-    @throw out_of_range.401 if the index @a idx is out of range of the array;
-    that is, `idx >= size()`. See example below.
+    @complexity Constant.
 
-    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
-    changes in the JSON value.
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @complexity Constant.
+    @liveexample{The following code exemplifies `type()` for all JSON
+    types.,type}
 
     @since version 1.0.0
-
-    @liveexample{The example below shows how array elements can be read using
-    `at()`. It also demonstrates the different exceptions that can be thrown.,
-    at__size_type_const}
     */
-    const_reference at(size_type idx) const
+    constexpr value_t type() const noexcept
     {
-        // at only works for arrays
-        if (is_array())
-        {
-            JSON_TRY
-            {
-                return m_value.array->at(idx);
-            }
-            JSON_CATCH (std::out_of_range&)
-            {
-                // create better exception explanation
-                JSON_THROW(out_of_range::create(401, "array index " + std::to_string(idx) + " is out of range"));
-            }
-        }
-        else
-        {
-            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
-        }
+        return m_type;
     }
 
     /*!
-    @brief access specified object element with bounds checking
-
-    Returns a reference to the element at with specified key @a key, with
-    bounds checking.
+    @brief return whether type is primitive
 
-    @param[in] key  key of the element to access
+    This function returns true iff the JSON type is primitive (string, number,
+    boolean, or null).
 
-    @return reference to the element at key @a key
+    @return `true` if type is primitive (string, number, boolean, or null),
+    `false` otherwise.
 
-    @throw type_error.304 if the JSON value is not an object; in this case,
-    calling `at` with a key makes no sense. See example below.
-    @throw out_of_range.403 if the key @a key is is not stored in the object;
-    that is, `find(key) == end()`. See example below.
+    @complexity Constant.
 
-    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
-    changes in the JSON value.
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @complexity Logarithmic in the size of the container.
+    @liveexample{The following code exemplifies `is_primitive()` for all JSON
+    types.,is_primitive}
 
-    @sa @ref operator[](const typename object_t::key_type&) for unchecked
-    access by reference
-    @sa @ref value() for access by value with a default value
+    @sa @ref is_structured() -- returns whether JSON value is structured
+    @sa @ref is_null() -- returns whether JSON value is `null`
+    @sa @ref is_string() -- returns whether JSON value is a string
+    @sa @ref is_boolean() -- returns whether JSON value is a boolean
+    @sa @ref is_number() -- returns whether JSON value is a number
 
     @since version 1.0.0
-
-    @liveexample{The example below shows how object elements can be read and
-    written using `at()`. It also demonstrates the different exceptions that
-    can be thrown.,at__object_t_key_type}
     */
-    reference at(const typename object_t::key_type& key)
+    constexpr bool is_primitive() const noexcept
     {
-        // at only works for objects
-        if (is_object())
-        {
-            JSON_TRY
-            {
-                return m_value.object->at(key);
-            }
-            JSON_CATCH (std::out_of_range&)
-            {
-                // create better exception explanation
-                JSON_THROW(out_of_range::create(403, "key '" + key + "' not found"));
-            }
-        }
-        else
-        {
-            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
-        }
+        return is_null() or is_string() or is_boolean() or is_number();
     }
 
     /*!
-    @brief access specified object element with bounds checking
-
-    Returns a const reference to the element at with specified key @a key,
-    with bounds checking.
+    @brief return whether type is structured
 
-    @param[in] key  key of the element to access
+    This function returns true iff the JSON type is structured (array or
+    object).
 
-    @return const reference to the element at key @a key
+    @return `true` if type is structured (array or object), `false` otherwise.
 
-    @throw type_error.304 if the JSON value is not an object; in this case,
-    calling `at` with a key makes no sense. See example below.
-    @throw out_of_range.403 if the key @a key is is not stored in the object;
-    that is, `find(key) == end()`. See example below.
+    @complexity Constant.
 
-    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
-    changes in the JSON value.
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @complexity Logarithmic in the size of the container.
+    @liveexample{The following code exemplifies `is_structured()` for all JSON
+    types.,is_structured}
 
-    @sa @ref operator[](const typename object_t::key_type&) for unchecked
-    access by reference
-    @sa @ref value() for access by value with a default value
+    @sa @ref is_primitive() -- returns whether value is primitive
+    @sa @ref is_array() -- returns whether value is an array
+    @sa @ref is_object() -- returns whether value is an object
 
     @since version 1.0.0
-
-    @liveexample{The example below shows how object elements can be read using
-    `at()`. It also demonstrates the different exceptions that can be thrown.,
-    at__object_t_key_type_const}
     */
-    const_reference at(const typename object_t::key_type& key) const
+    constexpr bool is_structured() const noexcept
     {
-        // at only works for objects
-        if (is_object())
-        {
-            JSON_TRY
-            {
-                return m_value.object->at(key);
-            }
-            JSON_CATCH (std::out_of_range&)
-            {
-                // create better exception explanation
-                JSON_THROW(out_of_range::create(403, "key '" + key + "' not found"));
-            }
-        }
-        else
-        {
-            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
-        }
+        return is_array() or is_object();
     }
 
     /*!
-    @brief access specified array element
-
-    Returns a reference to the element at specified location @a idx.
-
-    @note If @a idx is beyond the range of the array (i.e., `idx >= size()`),
-    then the array is silently filled up with `null` values to make `idx` a
-    valid reference to the last stored element.
+    @brief return whether value is null
 
-    @param[in] idx  index of the element to access
+    This function returns true iff the JSON value is null.
 
-    @return reference to the element at index @a idx
+    @return `true` if type is null, `false` otherwise.
 
-    @throw type_error.305 if the JSON value is not an array or null; in that
-    cases, using the [] operator with an index makes no sense.
+    @complexity Constant.
 
-    @complexity Constant if @a idx is in the range of the array. Otherwise
-    linear in `idx - size()`.
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @liveexample{The example below shows how array elements can be read and
-    written using `[]` operator. Note the addition of `null`
-    values.,operatorarray__size_type}
+    @liveexample{The following code exemplifies `is_null()` for all JSON
+    types.,is_null}
 
     @since version 1.0.0
     */
-    reference operator[](size_type idx)
+    constexpr bool is_null() const noexcept
     {
-        // implicitly convert null value to an empty array
-        if (is_null())
-        {
-            m_type = value_t::array;
-            m_value.array = create<array_t>();
-            assert_invariant();
-        }
-
-        // operator[] only works for arrays
-        if (is_array())
-        {
-            // fill up array with null values if given idx is outside range
-            if (idx >= m_value.array->size())
-            {
-                m_value.array->insert(m_value.array->end(),
-                                      idx - m_value.array->size() + 1,
-                                      basic_json());
-            }
-
-            return m_value.array->operator[](idx);
-        }
-
-        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+        return m_type == value_t::null;
     }
 
     /*!
-    @brief access specified array element
-
-    Returns a const reference to the element at specified location @a idx.
-
-    @param[in] idx  index of the element to access
+    @brief return whether value is a boolean
 
-    @return const reference to the element at index @a idx
+    This function returns true iff the JSON value is a boolean.
 
-    @throw type_error.305 if the JSON value is not an array; in that cases,
-    using the [] operator with an index makes no sense.
+    @return `true` if type is boolean, `false` otherwise.
 
     @complexity Constant.
 
-    @liveexample{The example below shows how array elements can be read using
-    the `[]` operator.,operatorarray__size_type_const}
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
+
+    @liveexample{The following code exemplifies `is_boolean()` for all JSON
+    types.,is_boolean}
 
     @since version 1.0.0
     */
-    const_reference operator[](size_type idx) const
+    constexpr bool is_boolean() const noexcept
     {
-        // const operator[] only works for arrays
-        if (is_array())
-        {
-            return m_value.array->operator[](idx);
-        }
-
-        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+        return m_type == value_t::boolean;
     }
 
     /*!
-    @brief access specified object element
-
-    Returns a reference to the element at with specified key @a key.
+    @brief return whether value is a number
 
-    @note If @a key is not found in the object, then it is silently added to
-    the object and filled with a `null` value to make `key` a valid reference.
-    In case the value was `null` before, it is converted to an object.
+    This function returns true iff the JSON value is a number. This includes
+    both integer and floating-point values.
 
-    @param[in] key  key of the element to access
+    @return `true` if type is number (regardless whether integer, unsigned
+    integer or floating-type), `false` otherwise.
 
-    @return reference to the element at key @a key
+    @complexity Constant.
 
-    @throw type_error.305 if the JSON value is not an object or null; in that
-    cases, using the [] operator with a key makes no sense.
-
-    @complexity Logarithmic in the size of the container.
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @liveexample{The example below shows how object elements can be read and
-    written using the `[]` operator.,operatorarray__key_type}
+    @liveexample{The following code exemplifies `is_number()` for all JSON
+    types.,is_number}
 
-    @sa @ref at(const typename object_t::key_type&) for access by reference
-    with range checking
-    @sa @ref value() for access by value with a default value
+    @sa @ref is_number_integer() -- check if value is an integer or unsigned
+    integer number
+    @sa @ref is_number_unsigned() -- check if value is an unsigned integer
+    number
+    @sa @ref is_number_float() -- check if value is a floating-point number
 
     @since version 1.0.0
     */
-    reference operator[](const typename object_t::key_type& key)
+    constexpr bool is_number() const noexcept
     {
-        // implicitly convert null value to an empty object
-        if (is_null())
-        {
-            m_type = value_t::object;
-            m_value.object = create<object_t>();
-            assert_invariant();
-        }
-
-        // operator[] only works for objects
-        if (is_object())
-        {
-            return m_value.object->operator[](key);
-        }
-
-        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+        return is_number_integer() or is_number_float();
     }
 
     /*!
-    @brief read-only access specified object element
-
-    Returns a const reference to the element at with specified key @a key. No
-    bounds checking is performed.
-
-    @warning If the element with key @a key does not exist, the behavior is
-    undefined.
-
-    @param[in] key  key of the element to access
+    @brief return whether value is an integer number
 
-    @return const reference to the element at key @a key
+    This function returns true iff the JSON value is an integer or unsigned
+    integer number. This excludes floating-point values.
 
-    @pre The element with key @a key must exist. **This precondition is
-         enforced with an assertion.**
+    @return `true` if type is an integer or unsigned integer number, `false`
+    otherwise.
 
-    @throw type_error.305 if the JSON value is not an object; in that cases,
-    using the [] operator with a key makes no sense.
+    @complexity Constant.
 
-    @complexity Logarithmic in the size of the container.
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @liveexample{The example below shows how object elements can be read using
-    the `[]` operator.,operatorarray__key_type_const}
+    @liveexample{The following code exemplifies `is_number_integer()` for all
+    JSON types.,is_number_integer}
 
-    @sa @ref at(const typename object_t::key_type&) for access by reference
-    with range checking
-    @sa @ref value() for access by value with a default value
+    @sa @ref is_number() -- check if value is a number
+    @sa @ref is_number_unsigned() -- check if value is an unsigned integer
+    number
+    @sa @ref is_number_float() -- check if value is a floating-point number
 
     @since version 1.0.0
     */
-    const_reference operator[](const typename object_t::key_type& key) const
+    constexpr bool is_number_integer() const noexcept
     {
-        // const operator[] only works for objects
-        if (is_object())
-        {
-            assert(m_value.object->find(key) != m_value.object->end());
-            return m_value.object->find(key)->second;
-        }
-
-        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+        return m_type == value_t::number_integer or m_type == value_t::number_unsigned;
     }
 
     /*!
-    @brief access specified object element
-
-    Returns a reference to the element at with specified key @a key.
-
-    @note If @a key is not found in the object, then it is silently added to
-    the object and filled with a `null` value to make `key` a valid reference.
-    In case the value was `null` before, it is converted to an object.
+    @brief return whether value is an unsigned integer number
 
-    @param[in] key  key of the element to access
+    This function returns true iff the JSON value is an unsigned integer
+    number. This excludes floating-point and (signed) integer values.
 
-    @return reference to the element at key @a key
+    @return `true` if type is an unsigned integer number, `false` otherwise.
 
-    @throw type_error.305 if the JSON value is not an object or null; in that
-    cases, using the [] operator with a key makes no sense.
+    @complexity Constant.
 
-    @complexity Logarithmic in the size of the container.
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @liveexample{The example below shows how object elements can be read and
-    written using the `[]` operator.,operatorarray__key_type}
+    @liveexample{The following code exemplifies `is_number_unsigned()` for all
+    JSON types.,is_number_unsigned}
 
-    @sa @ref at(const typename object_t::key_type&) for access by reference
-    with range checking
-    @sa @ref value() for access by value with a default value
+    @sa @ref is_number() -- check if value is a number
+    @sa @ref is_number_integer() -- check if value is an integer or unsigned
+    integer number
+    @sa @ref is_number_float() -- check if value is a floating-point number
 
-    @since version 1.1.0
+    @since version 2.0.0
     */
-    template<typename T>
-    reference operator[](T* key)
+    constexpr bool is_number_unsigned() const noexcept
     {
-        // implicitly convert null to object
-        if (is_null())
-        {
-            m_type = value_t::object;
-            m_value = value_t::object;
-            assert_invariant();
-        }
-
-        // at only works for objects
-        if (is_object())
-        {
-            return m_value.object->operator[](key);
-        }
-
-        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+        return m_type == value_t::number_unsigned;
     }
 
     /*!
-    @brief read-only access specified object element
+    @brief return whether value is a floating-point number
 
-    Returns a const reference to the element at with specified key @a key. No
-    bounds checking is performed.
+    This function returns true iff the JSON value is a floating-point number.
+    This excludes integer and unsigned integer values.
 
-    @warning If the element with key @a key does not exist, the behavior is
-    undefined.
+    @return `true` if type is a floating-point number, `false` otherwise.
 
-    @param[in] key  key of the element to access
+    @complexity Constant.
 
-    @return const reference to the element at key @a key
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @pre The element with key @a key must exist. **This precondition is
-         enforced with an assertion.**
+    @liveexample{The following code exemplifies `is_number_float()` for all
+    JSON types.,is_number_float}
 
-    @throw type_error.305 if the JSON value is not an object; in that cases,
-    using the [] operator with a key makes no sense.
+    @sa @ref is_number() -- check if value is number
+    @sa @ref is_number_integer() -- check if value is an integer number
+    @sa @ref is_number_unsigned() -- check if value is an unsigned integer
+    number
 
-    @complexity Logarithmic in the size of the container.
+    @since version 1.0.0
+    */
+    constexpr bool is_number_float() const noexcept
+    {
+        return m_type == value_t::number_float;
+    }
 
-    @liveexample{The example below shows how object elements can be read using
-    the `[]` operator.,operatorarray__key_type_const}
+    /*!
+    @brief return whether value is an object
 
-    @sa @ref at(const typename object_t::key_type&) for access by reference
-    with range checking
-    @sa @ref value() for access by value with a default value
+    This function returns true iff the JSON value is an object.
 
-    @since version 1.1.0
+    @return `true` if type is object, `false` otherwise.
+
+    @complexity Constant.
+
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
+
+    @liveexample{The following code exemplifies `is_object()` for all JSON
+    types.,is_object}
+
+    @since version 1.0.0
     */
-    template<typename T>
-    const_reference operator[](T* key) const
+    constexpr bool is_object() const noexcept
     {
-        // at only works for objects
-        if (is_object())
-        {
-            assert(m_value.object->find(key) != m_value.object->end());
-            return m_value.object->find(key)->second;
-        }
-
-        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+        return m_type == value_t::object;
     }
 
     /*!
-    @brief access specified object element with default value
+    @brief return whether value is an array
 
-    Returns either a copy of an object's element at the specified key @a key
-    or a given default value if no element with key @a key exists.
+    This function returns true iff the JSON value is an array.
 
-    The function is basically equivalent to executing
-    @code {.cpp}
-    try {
-        return at(key);
-    } catch(out_of_range) {
-        return default_value;
-    }
-    @endcode
+    @return `true` if type is array, `false` otherwise.
 
-    @note Unlike @ref at(const typename object_t::key_type&), this function
-    does not throw if the given key @a key was not found.
+    @complexity Constant.
 
-    @note Unlike @ref operator[](const typename object_t::key_type& key), this
-    function does not implicitly add an element to the position defined by @a
-    key. This function is furthermore also applicable to const objects.
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @param[in] key  key of the element to access
-    @param[in] default_value  the value to return if @a key is not found
+    @liveexample{The following code exemplifies `is_array()` for all JSON
+    types.,is_array}
 
-    @tparam ValueType type compatible to JSON values, for instance `int` for
-    JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
-    JSON arrays. Note the type of the expected value at @a key and the default
-    value @a default_value must be compatible.
+    @since version 1.0.0
+    */
+    constexpr bool is_array() const noexcept
+    {
+        return m_type == value_t::array;
+    }
 
-    @return copy of the element at key @a key or @a default_value if @a key
-    is not found
+    /*!
+    @brief return whether value is a string
 
-    @throw type_error.306 if the JSON value is not an objec; in that cases,
-    using `value()` with a key makes no sense.
+    This function returns true iff the JSON value is a string.
 
-    @complexity Logarithmic in the size of the container.
+    @return `true` if type is string, `false` otherwise.
 
-    @liveexample{The example below shows how object elements can be queried
-    with a default value.,basic_json__value}
+    @complexity Constant.
 
-    @sa @ref at(const typename object_t::key_type&) for access by reference
-    with range checking
-    @sa @ref operator[](const typename object_t::key_type&) for unchecked
-    access by reference
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
+
+    @liveexample{The following code exemplifies `is_string()` for all JSON
+    types.,is_string}
 
     @since version 1.0.0
     */
-    template<class ValueType, typename std::enable_if<
-                 std::is_convertible<basic_json_t, ValueType>::value, int>::type = 0>
-    ValueType value(const typename object_t::key_type& key, ValueType default_value) const
+    constexpr bool is_string() const noexcept
     {
-        // at only works for objects
-        if (is_object())
-        {
-            // if key is found, return value and given default value otherwise
-            const auto it = find(key);
-            if (it != end())
-            {
-                return *it;
-            }
-
-            return default_value;
-        }
-        else
-        {
-            JSON_THROW(type_error::create(306, "cannot use value() with " + type_name()));
-        }
+        return m_type == value_t::string;
     }
 
     /*!
-    @brief overload for a default value of type const char*
-    @copydoc basic_json::value(const typename object_t::key_type&, ValueType) const
-    */
-    string_t value(const typename object_t::key_type& key, const char* default_value) const
-    {
-        return value(key, string_t(default_value));
-    }
+    @brief return whether value is discarded
 
-    /*!
-    @brief access specified object element via JSON Pointer with default value
+    This function returns true iff the JSON value was discarded during parsing
+    with a callback function (see @ref parser_callback_t).
 
-    Returns either a copy of an object's element at the specified key @a key
-    or a given default value if no element with key @a key exists.
+    @note This function will always be `false` for JSON values after parsing.
+    That is, discarded values can only occur during parsing, but will be
+    removed when inside a structured value or replaced by null in other cases.
 
-    The function is basically equivalent to executing
-    @code {.cpp}
-    try {
-        return at(ptr);
-    } catch(out_of_range) {
-        return default_value;
-    }
-    @endcode
+    @return `true` if type is discarded, `false` otherwise.
 
-    @note Unlike @ref at(const json_pointer&), this function does not throw
-    if the given key @a key was not found.
+    @complexity Constant.
 
-    @param[in] ptr  a JSON pointer to the element to access
-    @param[in] default_value  the value to return if @a ptr found no value
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @tparam ValueType type compatible to JSON values, for instance `int` for
-    JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
-    JSON arrays. Note the type of the expected value at @a key and the default
-    value @a default_value must be compatible.
+    @liveexample{The following code exemplifies `is_discarded()` for all JSON
+    types.,is_discarded}
 
-    @return copy of the element at key @a key or @a default_value if @a key
-    is not found
+    @since version 1.0.0
+    */
+    constexpr bool is_discarded() const noexcept
+    {
+        return m_type == value_t::discarded;
+    }
 
-    @throw type_error.306 if the JSON value is not an objec; in that cases,
-    using `value()` with a key makes no sense.
+    /*!
+    @brief return the type of the JSON value (implicit)
 
-    @complexity Logarithmic in the size of the container.
+    Implicitly return the type of the JSON value as a value from the @ref
+    value_t enumeration.
 
-    @liveexample{The example below shows how object elements can be queried
-    with a default value.,basic_json__value_ptr}
+    @return the type of the JSON value
 
-    @sa @ref operator[](const json_pointer&) for unchecked access by reference
+    @complexity Constant.
 
-    @since version 2.0.2
-    */
-    template<class ValueType, typename std::enable_if<
-                 std::is_convertible<basic_json_t, ValueType>::value, int>::type = 0>
-    ValueType value(const json_pointer& ptr, ValueType default_value) const
-    {
-        // at only works for objects
-        if (is_object())
-        {
-            // if pointer resolves a value, return it or use default value
-            JSON_TRY
-            {
-                return ptr.get_checked(this);
-            }
-            JSON_CATCH (out_of_range&)
-            {
-                return default_value;
-            }
-        }
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-        JSON_THROW(type_error::create(306, "cannot use value() with " + type_name()));
-    }
+    @liveexample{The following code exemplifies the @ref value_t operator for
+    all JSON types.,operator__value_t}
 
-    /*!
-    @brief overload for a default value of type const char*
-    @copydoc basic_json::value(const json_pointer&, ValueType) const
+    @since version 1.0.0
     */
-    string_t value(const json_pointer& ptr, const char* default_value) const
+    constexpr operator value_t() const noexcept
     {
-        return value(ptr, string_t(default_value));
+        return m_type;
     }
 
-    /*!
-    @brief access the first element
-
-    Returns a reference to the first element in the container. For a JSON
-    container `c`, the expression `c.front()` is equivalent to `*c.begin()`.
-
-    @return In case of a structured type (array or object), a reference to the
-    first element is returned. In case of number, string, or boolean values, a
-    reference to the value is returned.
+    /// @}
 
-    @complexity Constant.
+  private:
+    //////////////////
+    // value access //
+    //////////////////
 
-    @pre The JSON value must not be `null` (would throw `std::out_of_range`)
-    or an empty array or object (undefined behavior, **guarded by
-    assertions**).
-    @post The JSON value remains unchanged.
+    /// get a boolean (explicit)
+    boolean_t get_impl(boolean_t* /*unused*/) const
+    {
+        if (is_boolean())
+        {
+            return m_value.boolean;
+        }
 
-    @throw invalid_iterator.214 when called on `null` value
+        JSON_THROW(type_error::create(302, "type must be boolean, but is " + type_name()));
+    }
 
-    @liveexample{The following code shows an example for `front()`.,front}
+    /// get a pointer to the value (object)
+    object_t* get_impl_ptr(object_t* /*unused*/) noexcept
+    {
+        return is_object() ? m_value.object : nullptr;
+    }
 
-    @sa @ref back() -- access the last element
+    /// get a pointer to the value (object)
+    constexpr const object_t* get_impl_ptr(const object_t* /*unused*/) const noexcept
+    {
+        return is_object() ? m_value.object : nullptr;
+    }
 
-    @since version 1.0.0
-    */
-    reference front()
+    /// get a pointer to the value (array)
+    array_t* get_impl_ptr(array_t* /*unused*/) noexcept
     {
-        return *begin();
+        return is_array() ? m_value.array : nullptr;
     }
 
-    /*!
-    @copydoc basic_json::front()
-    */
-    const_reference front() const
+    /// get a pointer to the value (array)
+    constexpr const array_t* get_impl_ptr(const array_t* /*unused*/) const noexcept
     {
-        return *cbegin();
+        return is_array() ? m_value.array : nullptr;
     }
 
-    /*!
-    @brief access the last element
+    /// get a pointer to the value (string)
+    string_t* get_impl_ptr(string_t* /*unused*/) noexcept
+    {
+        return is_string() ? m_value.string : nullptr;
+    }
 
-    Returns a reference to the last element in the container. For a JSON
-    container `c`, the expression `c.back()` is equivalent to
-    @code {.cpp}
-    auto tmp = c.end();
-    --tmp;
-    return *tmp;
-    @endcode
+    /// get a pointer to the value (string)
+    constexpr const string_t* get_impl_ptr(const string_t* /*unused*/) const noexcept
+    {
+        return is_string() ? m_value.string : nullptr;
+    }
 
-    @return In case of a structured type (array or object), a reference to the
-    last element is returned. In case of number, string, or boolean values, a
-    reference to the value is returned.
+    /// get a pointer to the value (boolean)
+    boolean_t* get_impl_ptr(boolean_t* /*unused*/) noexcept
+    {
+        return is_boolean() ? &m_value.boolean : nullptr;
+    }
 
-    @complexity Constant.
+    /// get a pointer to the value (boolean)
+    constexpr const boolean_t* get_impl_ptr(const boolean_t* /*unused*/) const noexcept
+    {
+        return is_boolean() ? &m_value.boolean : nullptr;
+    }
 
-    @pre The JSON value must not be `null` (would throw `std::out_of_range`)
-    or an empty array or object (undefined behavior, **guarded by
-    assertions**).
-    @post The JSON value remains unchanged.
+    /// get a pointer to the value (integer number)
+    number_integer_t* get_impl_ptr(number_integer_t* /*unused*/) noexcept
+    {
+        return is_number_integer() ? &m_value.number_integer : nullptr;
+    }
 
-    @throw invalid_iterator.214 when called on a `null` value. See example
-    below.
+    /// get a pointer to the value (integer number)
+    constexpr const number_integer_t* get_impl_ptr(const number_integer_t* /*unused*/) const noexcept
+    {
+        return is_number_integer() ? &m_value.number_integer : nullptr;
+    }
 
-    @liveexample{The following code shows an example for `back()`.,back}
+    /// get a pointer to the value (unsigned number)
+    number_unsigned_t* get_impl_ptr(number_unsigned_t* /*unused*/) noexcept
+    {
+        return is_number_unsigned() ? &m_value.number_unsigned : nullptr;
+    }
 
-    @sa @ref front() -- access the first element
+    /// get a pointer to the value (unsigned number)
+    constexpr const number_unsigned_t* get_impl_ptr(const number_unsigned_t* /*unused*/) const noexcept
+    {
+        return is_number_unsigned() ? &m_value.number_unsigned : nullptr;
+    }
 
-    @since version 1.0.0
-    */
-    reference back()
+    /// get a pointer to the value (floating-point number)
+    number_float_t* get_impl_ptr(number_float_t* /*unused*/) noexcept
     {
-        auto tmp = end();
-        --tmp;
-        return *tmp;
+        return is_number_float() ? &m_value.number_float : nullptr;
     }
 
-    /*!
-    @copydoc basic_json::back()
-    */
-    const_reference back() const
+    /// get a pointer to the value (floating-point number)
+    constexpr const number_float_t* get_impl_ptr(const number_float_t* /*unused*/) const noexcept
     {
-        auto tmp = cend();
-        --tmp;
-        return *tmp;
+        return is_number_float() ? &m_value.number_float : nullptr;
     }
 
     /*!
-    @brief remove element given an iterator
+    @brief helper function to implement get_ref()
 
-    Removes the element specified by iterator @a pos. The iterator @a pos must
-    be valid and dereferenceable. Thus the `end()` iterator (which is valid,
-    but is not dereferenceable) cannot be used as a value for @a pos.
+    This function helps to implement get_ref() without code duplication for
+    const and non-const overloads
 
-    If called on a primitive type other than `null`, the resulting JSON value
-    will be `null`.
+    @tparam ThisType will be deduced as `basic_json` or `const basic_json`
 
-    @param[in] pos iterator to the element to remove
-    @return Iterator following the last removed element. If the iterator @a
-    pos refers to the last element, the `end()` iterator is returned.
+    @throw type_error.303 if ReferenceType does not match underlying value
+    type of the current JSON
+    */
+    template<typename ReferenceType, typename ThisType>
+    static ReferenceType get_ref_impl(ThisType& obj)
+    {
+        // helper type
+        using PointerType = typename std::add_pointer<ReferenceType>::type;
 
-    @tparam IteratorType an @ref iterator or @ref const_iterator
+        // delegate the call to get_ptr<>()
+        auto ptr = obj.template get_ptr<PointerType>();
 
-    @post Invalidates iterators and references at or after the point of the
-    erase, including the `end()` iterator.
+        if (ptr != nullptr)
+        {
+            return *ptr;
+        }
 
-    @throw type_error.307 if called on a `null` value; example: `"cannot use
-    erase() with null"`
-    @throw invalid_iterator.202 if called on an iterator which does not belong
-    to the current JSON value; example: `"iterator does not fit current
-    value"`
-    @throw invalid_iterator.205 if called on a primitive type with invalid
-    iterator (i.e., any iterator which is not `begin()`); example: `"iterator
-    out of range"`
+        JSON_THROW(type_error::create(303, "incompatible ReferenceType for get_ref, actual type is " + obj.type_name()));
+    }
 
-    @complexity The complexity depends on the type:
-    - objects: amortized constant
-    - arrays: linear in distance between @a pos and the end of the container
-    - strings: linear in the length of the string
-    - other types: constant
+  public:
+    /// @name value access
+    /// Direct access to the stored value of a JSON value.
+    /// @{
 
-    @liveexample{The example shows the result of `erase()` for different JSON
-    types.,erase__IteratorType}
+    /*!
+    @brief get special-case overload
 
-    @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
-    @sa @ref erase(const size_type) -- removes the element from an array at
-    the given index
+    This overloads avoids a lot of template boilerplate, it can be seen as the
+    identity method
 
-    @since version 1.0.0
+    @tparam BasicJsonType == @ref basic_json
+
+    @return a copy of *this
+
+    @complexity Constant.
+
+    @since version 2.1.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 pos)
+    template <
+        typename BasicJsonType,
+        detail::enable_if_t<std::is_same<typename std::remove_const<BasicJsonType>::type,
+                                         basic_json_t>::value,
+                            int> = 0 >
+    basic_json get() const
     {
-        // make sure iterator fits the current value
-        if (this != pos.m_object)
-        {
-            JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
-        }
+        return *this;
+    }
 
-        IteratorType result = end();
+    /*!
+    @brief get a value (explicit)
 
-        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(invalid_iterator::create(205, "iterator out of range"));
-                }
+    Explicit type conversion between the JSON value and a compatible value
+    which is [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible)
+    and [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible).
+    The value is converted by calling the @ref json_serializer<ValueType>
+    `from_json()` method.
 
-                if (is_string())
-                {
-                    AllocatorType<string_t> alloc;
-                    alloc.destroy(m_value.string);
-                    alloc.deallocate(m_value.string, 1);
-                    m_value.string = nullptr;
-                }
+    The function is equivalent to executing
+    @code {.cpp}
+    ValueType ret;
+    JSONSerializer<ValueType>::from_json(*this, ret);
+    return ret;
+    @endcode
 
-                m_type = value_t::null;
-                assert_invariant();
-                break;
-            }
+    This overloads is chosen if:
+    - @a ValueType is not @ref basic_json,
+    - @ref json_serializer<ValueType> has a `from_json()` method of the form
+      `void from_json(const basic_json&, ValueType&)`, and
+    - @ref json_serializer<ValueType> does not have a `from_json()` method of
+      the form `ValueType from_json(const basic_json&)`
 
-            case value_t::object:
-            {
-                result.m_it.object_iterator = m_value.object->erase(pos.m_it.object_iterator);
-                break;
-            }
+    @tparam ValueTypeCV the provided value type
+    @tparam ValueType the returned value type
 
-            case value_t::array:
-            {
-                result.m_it.array_iterator = m_value.array->erase(pos.m_it.array_iterator);
-                break;
-            }
+    @return copy of the JSON value, converted to @a ValueType
 
-            default:
-            {
-                JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
-            }
-        }
+    @throw what @ref json_serializer<ValueType> `from_json()` method throws
 
-        return result;
-    }
+    @liveexample{The example below shows several conversions from JSON values
+    to other types. There a few things to note: (1) Floating-point numbers can
+    be converted to integers\, (2) A JSON array can be converted to a standard
+    `std::vector<short>`\, (3) A JSON object can be converted to C++
+    associative containers such as `std::unordered_map<std::string\,
+    json>`.,get__ValueType_const}
 
-    /*!
-    @brief remove elements given an iterator range
+    @since version 2.1.0
+    */
+    template <
+        typename ValueTypeCV,
+        typename ValueType = detail::uncvref_t<ValueTypeCV>,
+        detail::enable_if_t <
+            not std::is_same<basic_json_t, ValueType>::value and
+            detail::has_from_json<basic_json_t, ValueType>::value and
+            not detail::has_non_default_from_json<basic_json_t, ValueType>::value,
+            int > = 0 >
+    ValueType get() const noexcept(noexcept(
+                                       JSONSerializer<ValueType>::from_json(std::declval<const basic_json_t&>(), std::declval<ValueType&>())))
+    {
+        // we cannot static_assert on ValueTypeCV being non-const, because
+        // there is support for get<const basic_json_t>(), which is why we
+        // still need the uncvref
+        static_assert(not std::is_reference<ValueTypeCV>::value,
+                      "get() cannot be used with reference types, you might want to use get_ref()");
+        static_assert(std::is_default_constructible<ValueType>::value,
+                      "types must be DefaultConstructible when used with get()");
 
-    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.
+        ValueType ret;
+        JSONSerializer<ValueType>::from_json(*this, ret);
+        return ret;
+    }
 
-    If called on a primitive type other than `null`, the resulting JSON value
-    will be `null`.
+    /*!
+    @brief get a value (explicit); special case
 
-    @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.
+    Explicit type conversion between the JSON value and a compatible value
+    which is **not** [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible)
+    and **not** [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible).
+    The value is converted by calling the @ref json_serializer<ValueType>
+    `from_json()` method.
 
-    @tparam IteratorType an @ref iterator or @ref const_iterator
+    The function is equivalent to executing
+    @code {.cpp}
+    return JSONSerializer<ValueTypeCV>::from_json(*this);
+    @endcode
 
-    @post Invalidates iterators and references at or after the point of the
-    erase, including the `end()` iterator.
+    This overloads is chosen if:
+    - @a ValueType is not @ref basic_json and
+    - @ref json_serializer<ValueType> has a `from_json()` method of the form
+      `ValueType from_json(const basic_json&)`
 
-    @throw type_error.307 if called on a `null` value; example: `"cannot use
-    erase() with null"`
-    @throw invalid_iterator.203 if called on iterators which does not belong
-    to the current JSON value; example: `"iterators do not fit current value"`
-    @throw invalid_iterator.204 if called on a primitive type with invalid
-    iterators (i.e., if `first != begin()` and `last != end()`); example:
-    `"iterators out of range"`
+    @note If @ref json_serializer<ValueType> has both overloads of
+    `from_json()`, this one is chosen.
 
-    @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
+    @tparam ValueTypeCV the provided value type
+    @tparam ValueType the returned value type
 
-    @liveexample{The example shows the result of `erase()` for different JSON
-    types.,erase__IteratorType_IteratorType}
+    @return copy of the JSON value, converted to @a ValueType
 
-    @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
+    @throw what @ref json_serializer<ValueType> `from_json()` method throws
 
-    @since version 1.0.0
+    @since version 2.1.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)
+    template <
+        typename ValueTypeCV,
+        typename ValueType = detail::uncvref_t<ValueTypeCV>,
+        detail::enable_if_t<not std::is_same<basic_json_t, ValueType>::value and
+                            detail::has_non_default_from_json<basic_json_t,
+                                    ValueType>::value, int> = 0 >
+    ValueType get() const noexcept(noexcept(
+                                       JSONSerializer<ValueTypeCV>::from_json(std::declval<const basic_json_t&>())))
     {
-        // make sure iterator fits the current value
-        if (this != first.m_object or this != last.m_object)
-        {
-            JSON_THROW(invalid_iterator::create(203, "iterators do not fit current value"));
-        }
+        static_assert(not std::is_reference<ValueTypeCV>::value,
+                      "get() cannot be used with reference types, you might want to use get_ref()");
+        return JSONSerializer<ValueTypeCV>::from_json(*this);
+    }
 
-        IteratorType result = end();
+    /*!
+    @brief get a pointer value (explicit)
 
-        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(invalid_iterator::create(204, "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(type_error::create(307, "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
+    Explicit pointer access to the internally stored JSON value. No copies are
+    made.
 
-    @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).
+    @warning The pointer becomes invalid if the underlying JSON object
+    changes.
 
-    @post References and iterators to the erased elements are invalidated.
-    Other references and iterators are not affected.
+    @tparam PointerType pointer type; must be a pointer to @ref array_t, @ref
+    object_t, @ref string_t, @ref boolean_t, @ref number_integer_t,
+    @ref number_unsigned_t, or @ref number_float_t.
 
-    @throw type_error.307 when called on a type other than JSON object;
-    example: `"cannot use erase() with null"`
+    @return pointer to the internally stored JSON value if the requested
+    pointer type @a PointerType fits to the JSON value; `nullptr` otherwise
 
-    @complexity `log(size()) + count(key)`
+    @complexity Constant.
 
-    @liveexample{The example shows the effect of `erase()`.,erase__key_type}
+    @liveexample{The example below shows how pointers to internal values of a
+    JSON value can be requested. Note that no type conversions are made and a
+    `nullptr` is returned if the value and the requested pointer type does not
+    match.,get__PointerType}
 
-    @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
+    @sa @ref get_ptr() for explicit pointer-member access
 
     @since version 1.0.0
     */
-    size_type erase(const typename object_t::key_type& key)
+    template<typename PointerType, typename std::enable_if<
+                 std::is_pointer<PointerType>::value, int>::type = 0>
+    PointerType get() noexcept
     {
-        // this erase only works for objects
-        if (is_object())
-        {
-            return m_value.object->erase(key);
-        }
+        // delegate the call to get_ptr
+        return get_ptr<PointerType>();
+    }
 
-        JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
+    /*!
+    @brief get a pointer value (explicit)
+    @copydoc get()
+    */
+    template<typename PointerType, typename std::enable_if<
+                 std::is_pointer<PointerType>::value, int>::type = 0>
+    constexpr const PointerType get() const noexcept
+    {
+        // delegate the call to get_ptr
+        return get_ptr<PointerType>();
     }
 
     /*!
-    @brief remove element from a JSON array given an index
+    @brief get a pointer value (implicit)
 
-    Removes element from a JSON array at the index @a idx.
+    Implicit pointer access to the internally stored JSON value. No copies are
+    made.
 
-    @param[in] idx index of the element to remove
+    @warning Writing data to the pointee of the result yields an undefined
+    state.
 
-    @throw type_error.307 when called on a type other than JSON object;
-    example: `"cannot use erase() with null"`
-    @throw out_of_range.401 when `idx >= size()`; example: `"array index 17
-    is out of range"`
+    @tparam PointerType pointer type; must be a pointer to @ref array_t, @ref
+    object_t, @ref string_t, @ref boolean_t, @ref number_integer_t,
+    @ref number_unsigned_t, or @ref number_float_t. Enforced by a static
+    assertion.
 
-    @complexity Linear in distance between @a idx and the end of the container.
+    @return pointer to the internally stored JSON value if the requested
+    pointer type @a PointerType fits to the JSON value; `nullptr` otherwise
 
-    @liveexample{The example shows the effect of `erase()`.,erase__size_type}
+    @complexity Constant.
 
-    @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
+    @liveexample{The example below shows how pointers to internal values of a
+    JSON value can be requested. Note that no type conversions are made and a
+    `nullptr` is returned if the value and the requested pointer type does not
+    match.,get_ptr}
 
     @since version 1.0.0
     */
-    void erase(const size_type idx)
+    template<typename PointerType, typename std::enable_if<
+                 std::is_pointer<PointerType>::value, int>::type = 0>
+    PointerType get_ptr() noexcept
     {
-        // this erase only works for arrays
-        if (is_array())
-        {
-            if (idx >= size())
-            {
-                JSON_THROW(out_of_range::create(401, "array index " + std::to_string(idx) + " is out of range"));
-            }
+        // get the type of the PointerType (remove pointer and const)
+        using pointee_t = typename std::remove_const<typename
+                          std::remove_pointer<typename
+                          std::remove_const<PointerType>::type>::type>::type;
+        // make sure the type matches the allowed types
+        static_assert(
+            std::is_same<object_t, pointee_t>::value
+            or std::is_same<array_t, pointee_t>::value
+            or std::is_same<string_t, pointee_t>::value
+            or std::is_same<boolean_t, pointee_t>::value
+            or std::is_same<number_integer_t, pointee_t>::value
+            or std::is_same<number_unsigned_t, pointee_t>::value
+            or std::is_same<number_float_t, pointee_t>::value
+            , "incompatible pointer type");
 
-            m_value.array->erase(m_value.array->begin() + static_cast<difference_type>(idx));
-        }
-        else
-        {
-            JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
-        }
+        // delegate the call to get_impl_ptr<>()
+        return get_impl_ptr(static_cast<PointerType>(nullptr));
     }
 
-    /// @}
-
-
-    ////////////
-    // lookup //
-    ////////////
+    /*!
+    @brief get a pointer value (implicit)
+    @copydoc get_ptr()
+    */
+    template<typename PointerType, typename std::enable_if<
+                 std::is_pointer<PointerType>::value and
+                 std::is_const<typename std::remove_pointer<PointerType>::type>::value, int>::type = 0>
+    constexpr const PointerType get_ptr() const noexcept
+    {
+        // get the type of the PointerType (remove pointer and const)
+        using pointee_t = typename std::remove_const<typename
+                          std::remove_pointer<typename
+                          std::remove_const<PointerType>::type>::type>::type;
+        // make sure the type matches the allowed types
+        static_assert(
+            std::is_same<object_t, pointee_t>::value
+            or std::is_same<array_t, pointee_t>::value
+            or std::is_same<string_t, pointee_t>::value
+            or std::is_same<boolean_t, pointee_t>::value
+            or std::is_same<number_integer_t, pointee_t>::value
+            or std::is_same<number_unsigned_t, pointee_t>::value
+            or std::is_same<number_float_t, pointee_t>::value
+            , "incompatible pointer type");
 
-    /// @name lookup
-    /// @{
+        // delegate the call to get_impl_ptr<>() const
+        return get_impl_ptr(static_cast<const PointerType>(nullptr));
+    }
 
     /*!
-    @brief find an element in a JSON object
+    @brief get a reference value (implicit)
 
-    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.
+    Implicit reference access to the internally stored JSON value. No copies
+    are made.
 
-    @note This method always returns @ref end() when executed on a JSON type
-          that is not an object.
+    @warning Writing data to the referee of the result yields an undefined
+    state.
 
-    @param[in] key key value of the element to search for
+    @tparam ReferenceType reference type; must be a reference to @ref array_t,
+    @ref object_t, @ref string_t, @ref boolean_t, @ref number_integer_t, or
+    @ref number_float_t. Enforced by static assertion.
 
-    @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.
+    @return reference to the internally stored JSON value if the requested
+    reference type @a ReferenceType fits to the JSON value; throws
+    type_error.303 otherwise
 
-    @complexity Logarithmic in the size of the JSON object.
+    @throw type_error.303 in case passed type @a ReferenceType is incompatible
+    with the stored JSON value; see example below
 
-    @liveexample{The example shows how `find()` is used.,find__key_type}
+    @complexity Constant.
 
-    @since version 1.0.0
+    @liveexample{The example shows several calls to `get_ref()`.,get_ref}
+
+    @since version 1.1.0
     */
-    iterator find(typename object_t::key_type key)
+    template<typename ReferenceType, typename std::enable_if<
+                 std::is_reference<ReferenceType>::value, int>::type = 0>
+    ReferenceType get_ref()
     {
-        auto result = end();
-
-        if (is_object())
-        {
-            result.m_it.object_iterator = m_value.object->find(key);
-        }
-
-        return result;
+        // delegate call to get_ref_impl
+        return get_ref_impl<ReferenceType>(*this);
     }
 
     /*!
-    @brief find an element in a JSON object
-    @copydoc find(typename object_t::key_type)
+    @brief get a reference value (implicit)
+    @copydoc get_ref()
     */
-    const_iterator find(typename object_t::key_type key) const
+    template<typename ReferenceType, typename std::enable_if<
+                 std::is_reference<ReferenceType>::value and
+                 std::is_const<typename std::remove_reference<ReferenceType>::type>::value, int>::type = 0>
+    ReferenceType get_ref() const
     {
-        auto result = cend();
-
-        if (is_object())
-        {
-            result.m_it.object_iterator = m_value.object->find(key);
-        }
-
-        return result;
+        // delegate call to get_ref_impl
+        return get_ref_impl<ReferenceType>(*this);
     }
 
     /*!
-    @brief returns the number of occurrences of a key in a JSON object
+    @brief get a value (implicit)
 
-    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).
+    Implicit type conversion between the JSON value and a compatible value.
+    The call is realized by calling @ref get() const.
 
-    @note This method always returns `0` when executed on a JSON type that is
-          not an object.
+    @tparam ValueType non-pointer type compatible to the JSON value, for
+    instance `int` for JSON integer numbers, `bool` for JSON booleans, or
+    `std::vector` types for JSON arrays. The character type of @ref string_t
+    as well as an initializer list of this type is excluded to avoid
+    ambiguities as these types implicitly convert to `std::string`.
 
-    @param[in] key key value of the element to count
+    @return copy of the JSON value, converted to type @a ValueType
 
-    @return Number of elements with key @a key. If the JSON value is not an
-    object, the return value will be `0`.
+    @throw type_error.302 in case passed type @a ValueType is incompatible
+    to the JSON value type (e.g., the JSON value is of type boolean, but a
+    string is requested); see example below
 
-    @complexity Logarithmic in the size of the JSON object.
+    @complexity Linear in the size of the JSON value.
 
-    @liveexample{The example shows how `count()` is used.,count}
+    @liveexample{The example below shows several conversions from JSON values
+    to other types. There a few things to note: (1) Floating-point numbers can
+    be converted to integers\, (2) A JSON array can be converted to a standard
+    `std::vector<short>`\, (3) A JSON object can be converted to C++
+    associative containers such as `std::unordered_map<std::string\,
+    json>`.,operator__ValueType}
 
     @since version 1.0.0
     */
-    size_type count(typename object_t::key_type key) const
+    template < typename ValueType, typename std::enable_if <
+                   not std::is_pointer<ValueType>::value and
+                   not std::is_same<ValueType, typename string_t::value_type>::value
+#ifndef _MSC_VER  // fix for issue #167 operator<< ambiguity under VS2015
+                   and not std::is_same<ValueType, std::initializer_list<typename string_t::value_type>>::value
+#endif
+#if (defined(__cplusplus) && __cplusplus >= 201703L) || (defined(_MSC_VER) && _MSC_VER >1900 && defined(_HAS_CXX17) && _HAS_CXX17 == 1) // fix for issue #464
+                   and not std::is_same<ValueType, typename std::string_view>::value
+#endif
+                   , int >::type = 0 >
+    operator ValueType() const
     {
-        // return 0 for all nonobject types
-        return is_object() ? m_value.object->count(key) : 0;
+        // delegate the call to get<>() const
+        return get<ValueType>();
     }
 
     /// @}
 
 
-    ///////////////
-    // iterators //
-    ///////////////
+    ////////////////////
+    // element access //
+    ////////////////////
 
-    /// @name iterators
+    /// @name element access
+    /// Access to the JSON value.
     /// @{
 
     /*!
-    @brief returns an iterator to the first element
-
-    Returns an iterator to the first element.
+    @brief access specified array element with bounds checking
 
-    @image html range-begin-end.svg "Illustration from cppreference.com"
+    Returns a reference to the element at specified location @a idx, with
+    bounds checking.
 
-    @return iterator to the first element
+    @param[in] idx  index of the element to access
 
-    @complexity Constant.
+    @return reference to the element at index @a idx
 
-    @requirement This function helps `basic_json` satisfying the
-    [Container](http://en.cppreference.com/w/cpp/concept/Container)
-    requirements:
-    - The complexity is constant.
+    @throw type_error.304 if the JSON value is not an array; in this case,
+    calling `at` with an index makes no sense. See example below.
+    @throw out_of_range.401 if the index @a idx is out of range of the array;
+    that is, `idx >= size()`. See example below.
 
-    @liveexample{The following code shows an example for `begin()`.,begin}
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
 
-    @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
+    @complexity Constant.
 
     @since version 1.0.0
-    */
-    iterator begin() noexcept
-    {
-        iterator result(this);
-        result.set_begin();
-        return result;
-    }
 
-    /*!
-    @copydoc basic_json::cbegin()
+    @liveexample{The example below shows how array elements can be read and
+    written using `at()`. It also demonstrates the different exceptions that
+    can be thrown.,at__size_type}
     */
-    const_iterator begin() const noexcept
+    reference at(size_type idx)
     {
-        return cbegin();
+        // at only works for arrays
+        if (is_array())
+        {
+            JSON_TRY
+            {
+                return m_value.array->at(idx);
+            }
+            JSON_CATCH (std::out_of_range&)
+            {
+                // create better exception explanation
+                JSON_THROW(out_of_range::create(401, "array index " + std::to_string(idx) + " is out of range"));
+            }
+        }
+        else
+        {
+            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
+        }
     }
 
     /*!
-    @brief returns a const iterator to the first element
-
-    Returns a const iterator to the first element.
+    @brief access specified array element with bounds checking
 
-    @image html range-begin-end.svg "Illustration from cppreference.com"
+    Returns a const reference to the element at specified location @a idx,
+    with bounds checking.
 
-    @return const iterator to the first element
+    @param[in] idx  index of the element to access
 
-    @complexity Constant.
+    @return const reference to the element at index @a idx
 
-    @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()`.
+    @throw type_error.304 if the JSON value is not an array; in this case,
+    calling `at` with an index makes no sense. See example below.
+    @throw out_of_range.401 if the index @a idx is out of range of the array;
+    that is, `idx >= size()`. See example below.
 
-    @liveexample{The following code shows an example for `cbegin()`.,cbegin}
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
 
-    @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
+    @complexity Constant.
 
     @since version 1.0.0
+
+    @liveexample{The example below shows how array elements can be read using
+    `at()`. It also demonstrates the different exceptions that can be thrown.,
+    at__size_type_const}
     */
-    const_iterator cbegin() const noexcept
+    const_reference at(size_type idx) const
     {
-        const_iterator result(this);
-        result.set_begin();
-        return result;
+        // at only works for arrays
+        if (is_array())
+        {
+            JSON_TRY
+            {
+                return m_value.array->at(idx);
+            }
+            JSON_CATCH (std::out_of_range&)
+            {
+                // create better exception explanation
+                JSON_THROW(out_of_range::create(401, "array index " + std::to_string(idx) + " is out of range"));
+            }
+        }
+        else
+        {
+            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
+        }
     }
 
     /*!
-    @brief returns an iterator to one past the last element
+    @brief access specified object element with bounds checking
 
-    Returns an iterator to one past the last element.
+    Returns a reference to the element at with specified key @a key, with
+    bounds checking.
 
-    @image html range-begin-end.svg "Illustration from cppreference.com"
+    @param[in] key  key of the element to access
 
-    @return iterator one past the last element
+    @return reference to the element at key @a key
 
-    @complexity Constant.
+    @throw type_error.304 if the JSON value is not an object; in this case,
+    calling `at` with a key makes no sense. See example below.
+    @throw out_of_range.403 if the key @a key is is not stored in the object;
+    that is, `find(key) == end()`. See example below.
 
-    @requirement This function helps `basic_json` satisfying the
-    [Container](http://en.cppreference.com/w/cpp/concept/Container)
-    requirements:
-    - The complexity is constant.
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
 
-    @liveexample{The following code shows an example for `end()`.,end}
+    @complexity Logarithmic in the size of the container.
 
-    @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
+    @sa @ref operator[](const typename object_t::key_type&) for unchecked
+    access by reference
+    @sa @ref value() for access by value with a default value
 
     @since version 1.0.0
-    */
-    iterator end() noexcept
-    {
-        iterator result(this);
-        result.set_end();
-        return result;
-    }
 
-    /*!
-    @copydoc basic_json::cend()
+    @liveexample{The example below shows how object elements can be read and
+    written using `at()`. It also demonstrates the different exceptions that
+    can be thrown.,at__object_t_key_type}
     */
-    const_iterator end() const noexcept
+    reference at(const typename object_t::key_type& key)
     {
-        return cend();
+        // at only works for objects
+        if (is_object())
+        {
+            JSON_TRY
+            {
+                return m_value.object->at(key);
+            }
+            JSON_CATCH (std::out_of_range&)
+            {
+                // create better exception explanation
+                JSON_THROW(out_of_range::create(403, "key '" + key + "' not found"));
+            }
+        }
+        else
+        {
+            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
+        }
     }
 
     /*!
-    @brief returns a const iterator to one past the last element
+    @brief access specified object element with bounds checking
 
-    Returns a const iterator to one past the last element.
+    Returns a const reference to the element at with specified key @a key,
+    with bounds checking.
 
-    @image html range-begin-end.svg "Illustration from cppreference.com"
+    @param[in] key  key of the element to access
 
-    @return const iterator one past the last element
+    @return const reference to the element at key @a key
 
-    @complexity Constant.
+    @throw type_error.304 if the JSON value is not an object; in this case,
+    calling `at` with a key makes no sense. See example below.
+    @throw out_of_range.403 if the key @a key is is not stored in the object;
+    that is, `find(key) == end()`. See example below.
 
-    @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()`.
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
 
-    @liveexample{The following code shows an example for `cend()`.,cend}
+    @complexity Logarithmic in the size of the container.
 
-    @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
+    @sa @ref operator[](const typename object_t::key_type&) for unchecked
+    access by reference
+    @sa @ref value() for access by value with a default value
 
     @since version 1.0.0
+
+    @liveexample{The example below shows how object elements can be read using
+    `at()`. It also demonstrates the different exceptions that can be thrown.,
+    at__object_t_key_type_const}
     */
-    const_iterator cend() const noexcept
+    const_reference at(const typename object_t::key_type& key) const
     {
-        const_iterator result(this);
-        result.set_end();
-        return result;
+        // at only works for objects
+        if (is_object())
+        {
+            JSON_TRY
+            {
+                return m_value.object->at(key);
+            }
+            JSON_CATCH (std::out_of_range&)
+            {
+                // create better exception explanation
+                JSON_THROW(out_of_range::create(403, "key '" + key + "' not found"));
+            }
+        }
+        else
+        {
+            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
+        }
     }
 
     /*!
-    @brief returns an iterator to the reverse-beginning
+    @brief access specified array element
 
-    Returns an iterator to the reverse-beginning; that is, the last element.
+    Returns a reference to the element at specified location @a idx.
 
-    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
+    @note If @a idx is beyond the range of the array (i.e., `idx >= size()`),
+    then the array is silently filled up with `null` values to make `idx` a
+    valid reference to the last stored element.
 
-    @complexity Constant.
+    @param[in] idx  index of the element to access
 
-    @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())`.
+    @return reference to the element at index @a idx
 
-    @liveexample{The following code shows an example for `rbegin()`.,rbegin}
+    @throw type_error.305 if the JSON value is not an array or null; in that
+    cases, using the [] operator with an index makes no sense.
 
-    @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
+    @complexity Constant if @a idx is in the range of the array. Otherwise
+    linear in `idx - size()`.
+
+    @liveexample{The example below shows how array elements can be read and
+    written using `[]` operator. Note the addition of `null`
+    values.,operatorarray__size_type}
 
     @since version 1.0.0
     */
-    reverse_iterator rbegin() noexcept
+    reference operator[](size_type idx)
     {
-        return reverse_iterator(end());
-    }
+        // implicitly convert null value to an empty array
+        if (is_null())
+        {
+            m_type = value_t::array;
+            m_value.array = create<array_t>();
+            assert_invariant();
+        }
 
-    /*!
-    @copydoc basic_json::crbegin()
-    */
-    const_reverse_iterator rbegin() const noexcept
-    {
-        return crbegin();
+        // operator[] only works for arrays
+        if (is_array())
+        {
+            // fill up array with null values if given idx is outside range
+            if (idx >= m_value.array->size())
+            {
+                m_value.array->insert(m_value.array->end(),
+                                      idx - m_value.array->size() + 1,
+                                      basic_json());
+            }
+
+            return m_value.array->operator[](idx);
+        }
+
+        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
     }
 
     /*!
-    @brief returns an iterator to the reverse-end
+    @brief access specified array element
 
-    Returns an iterator to the reverse-end; that is, one before the first
-    element.
+    Returns a const reference to the element at specified location @a idx.
 
-    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
+    @param[in] idx  index of the element to access
 
-    @complexity Constant.
+    @return const reference to the element at index @a idx
 
-    @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())`.
+    @throw type_error.305 if the JSON value is not an array; in that cases,
+    using the [] operator with an index makes no sense.
 
-    @liveexample{The following code shows an example for `rend()`.,rend}
+    @complexity Constant.
 
-    @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
+    @liveexample{The example below shows how array elements can be read using
+    the `[]` operator.,operatorarray__size_type_const}
 
     @since version 1.0.0
     */
-    reverse_iterator rend() noexcept
+    const_reference operator[](size_type idx) const
     {
-        return reverse_iterator(begin());
-    }
+        // const operator[] only works for arrays
+        if (is_array())
+        {
+            return m_value.array->operator[](idx);
+        }
 
-    /*!
-    @copydoc basic_json::crend()
-    */
-    const_reverse_iterator rend() const noexcept
-    {
-        return crend();
+        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
     }
 
     /*!
-    @brief returns a const reverse iterator to the last element
+    @brief access specified object element
 
-    Returns a const iterator to the reverse-beginning; that is, the last
-    element.
+    Returns a reference to the element at with specified key @a key.
 
-    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
+    @note If @a key is not found in the object, then it is silently added to
+    the object and filled with a `null` value to make `key` a valid reference.
+    In case the value was `null` before, it is converted to an object.
 
-    @complexity Constant.
+    @param[in] key  key of the element to access
 
-    @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()`.
+    @return reference to the element at key @a key
 
-    @liveexample{The following code shows an example for `crbegin()`.,crbegin}
+    @throw type_error.305 if the JSON value is not an object or null; in that
+    cases, using the [] operator with a key makes no sense.
 
-    @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
+    @complexity Logarithmic in the size of the container.
+
+    @liveexample{The example below shows how object elements can be read and
+    written using the `[]` operator.,operatorarray__key_type}
+
+    @sa @ref at(const typename object_t::key_type&) for access by reference
+    with range checking
+    @sa @ref value() for access by value with a default value
 
     @since version 1.0.0
     */
-    const_reverse_iterator crbegin() const noexcept
+    reference operator[](const typename object_t::key_type& key)
     {
-        return const_reverse_iterator(cend());
-    }
+        // implicitly convert null value to an empty object
+        if (is_null())
+        {
+            m_type = value_t::object;
+            m_value.object = create<object_t>();
+            assert_invariant();
+        }
 
-    /*!
-    @brief returns a const reverse iterator to one before the first
+        // operator[] only works for objects
+        if (is_object())
+        {
+            return m_value.object->operator[](key);
+        }
 
-    Returns a const reverse iterator to the reverse-end; that is, one before
-    the first element.
+        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+    }
 
-    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
+    /*!
+    @brief read-only access specified object element
 
-    @complexity Constant.
+    Returns a const reference to the element at with specified key @a key. No
+    bounds checking is performed.
 
-    @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()`.
+    @warning If the element with key @a key does not exist, the behavior is
+    undefined.
 
-    @liveexample{The following code shows an example for `crend()`.,crend}
+    @param[in] key  key of the element to access
 
-    @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
+    @return const reference to the element at key @a key
 
-    @since version 1.0.0
-    */
-    const_reverse_iterator crend() const noexcept
-    {
-        return const_reverse_iterator(cbegin());
-    }
+    @pre The element with key @a key must exist. **This precondition is
+         enforced with an assertion.**
 
-  private:
-    // forward declaration
-    template<typename IteratorType> class iteration_proxy;
+    @throw type_error.305 if the JSON value is not an object; in that cases,
+    using the [] operator with a key makes no sense.
 
-  public:
-    /*!
-    @brief wrapper to access iterator member functions in range-based for
+    @complexity Logarithmic in the size of the container.
 
-    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.
+    @liveexample{The example below shows how object elements can be read using
+    the `[]` operator.,operatorarray__key_type_const}
 
-    @liveexample{The following code shows how the wrapper is used,iterator_wrapper}
+    @sa @ref at(const typename object_t::key_type&) for access by reference
+    with range checking
+    @sa @ref value() for access by value with a default value
 
-    @note The name of this function is not yet final and may change in the
-    future.
+    @since version 1.0.0
     */
-    static iteration_proxy<iterator> iterator_wrapper(reference cont)
+    const_reference operator[](const typename object_t::key_type& key) const
     {
-        return iteration_proxy<iterator>(cont);
+        // const operator[] only works for objects
+        if (is_object())
+        {
+            assert(m_value.object->find(key) != m_value.object->end());
+            return m_value.object->find(key)->second;
+        }
+
+        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
     }
 
     /*!
-    @copydoc iterator_wrapper(reference)
-    */
-    static iteration_proxy<const_iterator> iterator_wrapper(const_reference cont)
-    {
-        return iteration_proxy<const_iterator>(cont);
-    }
+    @brief access specified object element
 
-    /// @}
+    Returns a reference to the element at with specified key @a key.
 
+    @note If @a key is not found in the object, then it is silently added to
+    the object and filled with a `null` value to make `key` a valid reference.
+    In case the value was `null` before, it is converted to an object.
 
-    //////////////
-    // 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()`
+    @param[in] key  key of the element to access
 
-    @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.
+    @return reference to the element at key @a key
 
-    @complexity Constant, as long as @ref array_t and @ref object_t satisfy
-    the Container concept; that is, their `empty()` functions have constant
-    complexity.
+    @throw type_error.305 if the JSON value is not an object or null; in that
+    cases, using the [] operator with a key makes no sense.
 
-    @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()`.
+    @complexity Logarithmic in the size of the container.
 
-    @liveexample{The following code uses `empty()` to check if a JSON
-    object contains any elements.,empty}
+    @liveexample{The example below shows how object elements can be read and
+    written using the `[]` operator.,operatorarray__key_type}
 
-    @sa @ref size() -- returns the number of elements
+    @sa @ref at(const typename object_t::key_type&) for access by reference
+    with range checking
+    @sa @ref value() for access by value with a default value
 
-    @since version 1.0.0
+    @since version 1.1.0
     */
-    bool empty() const noexcept
+    template<typename T>
+    reference operator[](T* key)
     {
-        switch (m_type)
+        // implicitly convert null to object
+        if (is_null())
         {
-            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();
-            }
+            m_type = value_t::object;
+            m_value = value_t::object;
+            assert_invariant();
+        }
 
-            default:
-            {
-                // all other types are nonempty
-                return false;
-            }
+        // at only works for objects
+        if (is_object())
+        {
+            return m_value.object->operator[](key);
         }
+
+        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
     }
 
     /*!
-    @brief returns the number of elements
+    @brief read-only access specified object element
 
-    Returns the number of elements in a JSON value.
+    Returns a const reference to the element at with specified key @a key. No
+    bounds checking is performed.
 
-    @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()
+    @warning If the element with key @a key does not exist, the behavior is
+    undefined.
 
-    @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.
+    @param[in] key  key of the element to access
 
-    @complexity Constant, as long as @ref array_t and @ref object_t satisfy
-    the Container concept; that is, their size() functions have constant
-    complexity.
+    @return const reference to the element at key @a key
 
-    @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())`.
+    @pre The element with key @a key must exist. **This precondition is
+         enforced with an assertion.**
 
-    @liveexample{The following code calls `size()` on the different value
-    types.,size}
+    @throw type_error.305 if the JSON value is not an object; in that cases,
+    using the [] operator with a key makes no sense.
 
-    @sa @ref empty() -- checks whether the container is empty
-    @sa @ref max_size() -- returns the maximal number of elements
+    @complexity Logarithmic in the size of the container.
 
-    @since version 1.0.0
+    @liveexample{The example below shows how object elements can be read using
+    the `[]` operator.,operatorarray__key_type_const}
+
+    @sa @ref at(const typename object_t::key_type&) for access by reference
+    with range checking
+    @sa @ref value() for access by value with a default value
+
+    @since version 1.1.0
     */
-    size_type size() const noexcept
+    template<typename T>
+    const_reference operator[](T* key) const
     {
-        switch (m_type)
+        // at only works for objects
+        if (is_object())
         {
-            case value_t::null:
-            {
-                // null values are empty
-                return 0;
-            }
+            assert(m_value.object->find(key) != m_value.object->end());
+            return m_value.object->find(key)->second;
+        }
 
-            case value_t::array:
-            {
-                // delegate call to array_t::size()
-                return m_value.array->size();
-            }
+        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+    }
 
-            case value_t::object:
-            {
-                // delegate call to object_t::size()
-                return m_value.object->size();
-            }
+    /*!
+    @brief access specified object element with default value
 
-            default:
-            {
-                // all other types have size 1
-                return 1;
-            }
-        }
+    Returns either a copy of an object's element at the specified key @a key
+    or a given default value if no element with key @a key exists.
+
+    The function is basically equivalent to executing
+    @code {.cpp}
+    try {
+        return at(key);
+    } catch(out_of_range) {
+        return default_value;
     }
+    @endcode
 
-    /*!
-    @brief returns the maximum possible number of elements
+    @note Unlike @ref at(const typename object_t::key_type&), this function
+    does not throw if the given key @a key was not found.
 
-    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.
+    @note Unlike @ref operator[](const typename object_t::key_type& key), this
+    function does not implicitly add an element to the position defined by @a
+    key. This function is furthermore also applicable to const objects.
 
-    @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()`
+    @param[in] key  key of the element to access
+    @param[in] default_value  the value to return if @a key is not found
 
-    @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.
+    @tparam ValueType type compatible to JSON values, for instance `int` for
+    JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
+    JSON arrays. Note the type of the expected value at @a key and the default
+    value @a default_value must be compatible.
 
-    @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.
+    @return copy of the element at key @a key or @a default_value if @a key
+    is not found
 
-    @liveexample{The following code calls `max_size()` on the different value
-    types. Note the output is implementation specific.,max_size}
+    @throw type_error.306 if the JSON value is not an objec; in that cases,
+    using `value()` with a key makes no sense.
 
-    @sa @ref size() -- returns the number of elements
+    @complexity Logarithmic in the size of the container.
+
+    @liveexample{The example below shows how object elements can be queried
+    with a default value.,basic_json__value}
+
+    @sa @ref at(const typename object_t::key_type&) for access by reference
+    with range checking
+    @sa @ref operator[](const typename object_t::key_type&) for unchecked
+    access by reference
 
     @since version 1.0.0
     */
-    size_type max_size() const noexcept
+    template<class ValueType, typename std::enable_if<
+                 std::is_convertible<basic_json_t, ValueType>::value, int>::type = 0>
+    ValueType value(const typename object_t::key_type& key, ValueType default_value) const
     {
-        switch (m_type)
+        // at only works for objects
+        if (is_object())
         {
-            case value_t::array:
-            {
-                // delegate call to array_t::max_size()
-                return m_value.array->max_size();
-            }
-
-            case value_t::object:
+            // if key is found, return value and given default value otherwise
+            const auto it = find(key);
+            if (it != end())
             {
-                // delegate call to object_t::max_size()
-                return m_value.object->max_size();
+                return *it;
             }
 
-            default:
-            {
-                // all other types have max_size() == size()
-                return size();
-            }
+            return default_value;
         }
-    }
-
-    /// @}
-
-
-    ///////////////
-    // modifiers //
-    ///////////////
+        else
+        {
+            JSON_THROW(type_error::create(306, "cannot use value() with " + type_name()));
+        }
+    }
 
-    /// @name modifiers
-    /// @{
+    /*!
+    @brief overload for a default value of type const char*
+    @copydoc basic_json::value(const typename object_t::key_type&, ValueType) const
+    */
+    string_t value(const typename object_t::key_type& key, const char* default_value) const
+    {
+        return value(key, string_t(default_value));
+    }
 
     /*!
-    @brief clears the contents
+    @brief access specified object element via JSON Pointer with default value
 
-    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:
+    Returns either a copy of an object's element at the specified key @a key
+    or a given default value if no element with key @a key exists.
 
-    Value type  | initial value
-    ----------- | -------------
-    null        | `null`
-    boolean     | `false`
-    string      | `""`
-    number      | `0`
-    object      | `{}`
-    array       | `[]`
+    The function is basically equivalent to executing
+    @code {.cpp}
+    try {
+        return at(ptr);
+    } catch(out_of_range) {
+        return default_value;
+    }
+    @endcode
 
-    @complexity Linear in the size of the JSON value.
+    @note Unlike @ref at(const json_pointer&), this function does not throw
+    if the given key @a key was not found.
 
-    @liveexample{The example below shows the effect of `clear()` to different
-    JSON types.,clear}
+    @param[in] ptr  a JSON pointer to the element to access
+    @param[in] default_value  the value to return if @a ptr found no value
 
-    @since version 1.0.0
-    */
-    void clear() noexcept
-    {
-        switch (m_type)
-        {
-            case value_t::number_integer:
-            {
-                m_value.number_integer = 0;
-                break;
-            }
+    @tparam ValueType type compatible to JSON values, for instance `int` for
+    JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
+    JSON arrays. Note the type of the expected value at @a key and the default
+    value @a default_value must be compatible.
 
-            case value_t::number_unsigned:
-            {
-                m_value.number_unsigned = 0;
-                break;
-            }
+    @return copy of the element at key @a key or @a default_value if @a key
+    is not found
 
-            case value_t::number_float:
-            {
-                m_value.number_float = 0.0;
-                break;
-            }
+    @throw type_error.306 if the JSON value is not an objec; in that cases,
+    using `value()` with a key makes no sense.
 
-            case value_t::boolean:
-            {
-                m_value.boolean = false;
-                break;
-            }
+    @complexity Logarithmic in the size of the container.
 
-            case value_t::string:
-            {
-                m_value.string->clear();
-                break;
-            }
+    @liveexample{The example below shows how object elements can be queried
+    with a default value.,basic_json__value_ptr}
 
-            case value_t::array:
-            {
-                m_value.array->clear();
-                break;
-            }
+    @sa @ref operator[](const json_pointer&) for unchecked access by reference
 
-            case value_t::object:
+    @since version 2.0.2
+    */
+    template<class ValueType, typename std::enable_if<
+                 std::is_convertible<basic_json_t, ValueType>::value, int>::type = 0>
+    ValueType value(const json_pointer& ptr, ValueType default_value) const
+    {
+        // at only works for objects
+        if (is_object())
+        {
+            // if pointer resolves a value, return it or use default value
+            JSON_TRY
             {
-                m_value.object->clear();
-                break;
+                return ptr.get_checked(this);
             }
-
-            default:
+            JSON_CATCH (out_of_range&)
             {
-                break;
+                return default_value;
             }
         }
+
+        JSON_THROW(type_error::create(306, "cannot use value() with " + type_name()));
     }
 
     /*!
-    @brief add an object to an array
+    @brief overload for a default value of type const char*
+    @copydoc basic_json::value(const json_pointer&, ValueType) const
+    */
+    string_t value(const json_pointer& ptr, const char* default_value) const
+    {
+        return value(ptr, string_t(default_value));
+    }
 
-    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.
+    /*!
+    @brief access the first element
 
-    @param[in] val the value to add to the JSON array
+    Returns a reference to the first element in the container. For a JSON
+    container `c`, the expression `c.front()` is equivalent to `*c.begin()`.
 
-    @throw type_error.308 when called on a type other than JSON array or
-    null; example: `"cannot use push_back() with number"`
+    @return In case of a structured type (array or object), a reference to the
+    first element is returned. In case of number, string, or boolean values, a
+    reference to the value is returned.
 
-    @complexity Amortized constant.
+    @complexity 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}
+    @pre The JSON value must not be `null` (would throw `std::out_of_range`)
+    or an empty array or object (undefined behavior, **guarded by
+    assertions**).
+    @post The JSON value remains unchanged.
 
-    @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(type_error::create(308, "cannot use push_back() with " + type_name()));
-        }
+    @throw invalid_iterator.214 when called on `null` value
 
-        // transform null object into an array
-        if (is_null())
-        {
-            m_type = value_t::array;
-            m_value = value_t::array;
-            assert_invariant();
-        }
+    @liveexample{The following code shows an example for `front()`.,front}
 
-        // add element to array (move semantics)
-        m_value.array->push_back(std::move(val));
-        // invalidate object
-        val.m_type = value_t::null;
-    }
+    @sa @ref back() -- access the last element
 
-    /*!
-    @brief add an object to an array
-    @copydoc push_back(basic_json&&)
+    @since version 1.0.0
     */
-    reference operator+=(basic_json&& val)
+    reference front()
     {
-        push_back(std::move(val));
-        return *this;
+        return *begin();
     }
 
     /*!
-    @brief add an object to an array
-    @copydoc push_back(basic_json&&)
+    @copydoc basic_json::front()
     */
-    void push_back(const basic_json& val)
+    const_reference front() const
     {
-        // push_back only works for null objects or arrays
-        if (not(is_null() or is_array()))
-        {
-            JSON_THROW(type_error::create(308, "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
-        m_value.array->push_back(val);
+        return *cbegin();
     }
 
     /*!
-    @brief add an object to an array
-    @copydoc push_back(basic_json&&)
-    */
-    reference operator+=(const basic_json& val)
-    {
-        push_back(val);
-        return *this;
-    }
+    @brief access the last element
 
-    /*!
-    @brief add an object to an object
+    Returns a reference to the last element in the container. For a JSON
+    container `c`, the expression `c.back()` is equivalent to
+    @code {.cpp}
+    auto tmp = c.end();
+    --tmp;
+    return *tmp;
+    @endcode
 
-    Inserts the given element @a val to the JSON object. If the function is
-    called on a JSON null value, an empty object is created before inserting
-    @a val.
+    @return In case of a structured type (array or object), a reference to the
+    last element is returned. In case of number, string, or boolean values, a
+    reference to the value is returned.
 
-    @param[in] val the value to add to the JSON object
+    @complexity Constant.
 
-    @throw type_error.308 when called on a type other than JSON object or
-    null; example: `"cannot use push_back() with number"`
+    @pre The JSON value must not be `null` (would throw `std::out_of_range`)
+    or an empty array or object (undefined behavior, **guarded by
+    assertions**).
+    @post The JSON value remains unchanged.
 
-    @complexity Logarithmic in the size of the container, O(log(`size()`)).
+    @throw invalid_iterator.214 when called on a `null` value. See example
+    below.
 
-    @liveexample{The example shows how `push_back()` and `+=` can be used to
-    add elements to a JSON object. Note how the `null` value was silently
-    converted to a JSON object.,push_back__object_t__value}
+    @liveexample{The following code shows an example for `back()`.,back}
+
+    @sa @ref front() -- access the first element
 
     @since version 1.0.0
     */
-    void push_back(const typename object_t::value_type& val)
+    reference back()
     {
-        // push_back only works for null objects or objects
-        if (not(is_null() or is_object()))
-        {
-            JSON_THROW(type_error::create(308, "cannot use push_back() with " + type_name()));
-        }
-
-        // transform null object into an object
-        if (is_null())
-        {
-            m_type = value_t::object;
-            m_value = value_t::object;
-            assert_invariant();
-        }
-
-        // add element to array
-        m_value.object->insert(val);
+        auto tmp = end();
+        --tmp;
+        return *tmp;
     }
 
     /*!
-    @brief add an object to an object
-    @copydoc push_back(const typename object_t::value_type&)
+    @copydoc basic_json::back()
     */
-    reference operator+=(const typename object_t::value_type& val)
+    const_reference back() const
     {
-        push_back(val);
-        return *this;
+        auto tmp = cend();
+        --tmp;
+        return *tmp;
     }
 
     /*!
-    @brief add an object to an object
+    @brief remove element given an iterator
 
-    This function allows to use `push_back` with an initializer list. In case
+    Removes the element specified by iterator @a pos. The iterator @a pos must
+    be valid and dereferenceable. Thus the `end()` iterator (which is valid,
+    but is not dereferenceable) cannot be used as a value for @a pos.
 
-    1. the current value is an object,
-    2. the initializer list @a init contains only two elements, and
-    3. the first element of @a init is a string,
+    If called on a primitive type other than `null`, the resulting JSON value
+    will be `null`.
 
-    @a init is converted into an object element and added using
-    @ref push_back(const typename object_t::value_type&). Otherwise, @a init
-    is converted to a JSON value and added using @ref push_back(basic_json&&).
+    @param[in] pos iterator to the element to remove
+    @return Iterator following the last removed element. If the iterator @a
+    pos refers to the last element, the `end()` iterator is returned.
 
-    @param[in] init  an initializer list
+    @tparam IteratorType an @ref iterator or @ref const_iterator
 
-    @complexity Linear in the size of the initializer list @a init.
+    @post Invalidates iterators and references at or after the point of the
+    erase, including the `end()` iterator.
 
-    @note This function is required to resolve an ambiguous overload error,
-          because pairs like `{"key", "value"}` can be both interpreted as
-          `object_t::value_type` or `std::initializer_list<basic_json>`, see
-          https://github.com/nlohmann/json/issues/235 for more information.
+    @throw type_error.307 if called on a `null` value; example: `"cannot use
+    erase() with null"`
+    @throw invalid_iterator.202 if called on an iterator which does not belong
+    to the current JSON value; example: `"iterator does not fit current
+    value"`
+    @throw invalid_iterator.205 if called on a primitive type with invalid
+    iterator (i.e., any iterator which is not `begin()`); example: `"iterator
+    out of range"`
 
-    @liveexample{The example shows how initializer lists are treated as
-    objects when possible.,push_back__initializer_list}
+    @complexity The complexity depends on the type:
+    - objects: amortized constant
+    - arrays: linear in distance between @a pos and the 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}
+
+    @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
+    @sa @ref erase(const size_type) -- removes the element from an array at
+    the given index
+
+    @since version 1.0.0
     */
-    void push_back(std::initializer_list<basic_json> init)
+    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 pos)
     {
-        if (is_object() and init.size() == 2 and init.begin()->is_string())
-        {
-            const string_t key = *init.begin();
-            push_back(typename object_t::value_type(key, *(init.begin() + 1)));
-        }
-        else
+        // make sure iterator fits the current value
+        if (this != pos.m_object)
         {
-            push_back(basic_json(init));
+            JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
         }
-    }
-
-    /*!
-    @brief add an object to an object
-    @copydoc push_back(std::initializer_list<basic_json>)
-    */
-    reference operator+=(std::initializer_list<basic_json> init)
-    {
-        push_back(init);
-        return *this;
-    }
-
-    /*!
-    @brief add an object to an array
 
-    Creates a JSON value from the passed parameters @a args to the end of the
-    JSON value. If the function is called on a JSON null value, an empty array
-    is created before appending the value created from @a args.
+        IteratorType result = end();
 
-    @param[in] args arguments to forward to a constructor of @ref basic_json
-    @tparam Args compatible types to create a @ref basic_json object
+        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(invalid_iterator::create(205, "iterator out of range"));
+                }
 
-    @throw type_error.311 when called on a type other than JSON array or
-    null; example: `"cannot use emplace_back() with number"`
+                if (is_string())
+                {
+                    AllocatorType<string_t> alloc;
+                    alloc.destroy(m_value.string);
+                    alloc.deallocate(m_value.string, 1);
+                    m_value.string = nullptr;
+                }
 
-    @complexity Amortized constant.
+                m_type = value_t::null;
+                assert_invariant();
+                break;
+            }
 
-    @liveexample{The example shows how `push_back()` can be used to add
-    elements to a JSON array. Note how the `null` value was silently converted
-    to a JSON array.,emplace_back}
+            case value_t::object:
+            {
+                result.m_it.object_iterator = m_value.object->erase(pos.m_it.object_iterator);
+                break;
+            }
 
-    @since version 2.0.8
-    */
-    template<class... Args>
-    void emplace_back(Args&& ... args)
-    {
-        // emplace_back only works for null objects or arrays
-        if (not(is_null() or is_array()))
-        {
-            JSON_THROW(type_error::create(311, "cannot use emplace_back() with " + type_name()));
-        }
+            case value_t::array:
+            {
+                result.m_it.array_iterator = m_value.array->erase(pos.m_it.array_iterator);
+                break;
+            }
 
-        // transform null object into an array
-        if (is_null())
-        {
-            m_type = value_t::array;
-            m_value = value_t::array;
-            assert_invariant();
+            default:
+            {
+                JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
+            }
         }
 
-        // add element to array (perfect forwarding)
-        m_value.array->emplace_back(std::forward<Args>(args)...);
+        return result;
     }
 
     /*!
-    @brief add an object to an object if key does not exist
+    @brief remove elements given an iterator range
 
-    Inserts a new element into a JSON object constructed in-place with the
-    given @a args if there is no element with the key in the container. If the
-    function is called on a JSON null value, an empty object is created before
-    appending the value created from @a args.
+    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.
 
-    @param[in] args arguments to forward to a constructor of @ref basic_json
-    @tparam Args compatible types to create a @ref basic_json object
+    If called on a primitive type other than `null`, the resulting JSON value
+    will be `null`.
 
-    @return a pair consisting of an iterator to the inserted element, or the
-            already-existing element if no insertion happened, and a bool
-            denoting whether the insertion took place.
+    @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.
 
-    @throw type_error.311 when called on a type other than JSON object or
-    null; example: `"cannot use emplace() with number"`
+    @tparam IteratorType an @ref iterator or @ref const_iterator
 
-    @complexity Logarithmic in the size of the container, O(log(`size()`)).
+    @post Invalidates iterators and references at or after the point of the
+    erase, including the `end()` iterator.
 
-    @liveexample{The example shows how `emplace()` can be used to add elements
-    to a JSON object. Note how the `null` value was silently converted to a
-    JSON object. Further note how no value is added if there was already one
-    value stored with the same key.,emplace}
+    @throw type_error.307 if called on a `null` value; example: `"cannot use
+    erase() with null"`
+    @throw invalid_iterator.203 if called on iterators which does not belong
+    to the current JSON value; example: `"iterators do not fit current value"`
+    @throw invalid_iterator.204 if called on a primitive type with invalid
+    iterators (i.e., if `first != begin()` and `last != end()`); example:
+    `"iterators out of range"`
 
-    @since version 2.0.8
+    @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... Args>
-    std::pair<iterator, bool> emplace(Args&& ... args)
+    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)
     {
-        // emplace only works for null objects or arrays
-        if (not(is_null() or is_object()))
-        {
-            JSON_THROW(type_error::create(311, "cannot use emplace() with " + type_name()));
-        }
-
-        // transform null object into an object
-        if (is_null())
+        // make sure iterator fits the current value
+        if (this != first.m_object or this != last.m_object)
         {
-            m_type = value_t::object;
-            m_value = value_t::object;
-            assert_invariant();
+            JSON_THROW(invalid_iterator::create(203, "iterators do not fit current value"));
         }
 
-        // add element to array (perfect forwarding)
-        auto res = m_value.object->emplace(std::forward<Args>(args)...);
-        // create result iterator and set iterator to the result of emplace
-        auto it = begin();
-        it.m_it.object_iterator = res.first;
+        IteratorType result = end();
 
-        // return pair of iterator and boolean
-        return {it, res.second};
-    }
-
-    /*!
-    @brief inserts element
-
-    Inserts element @a val before iterator @a pos.
-
-    @param[in] pos iterator before which the content will be inserted; may be
-    the end() iterator
-    @param[in] val element to insert
-    @return iterator pointing to the inserted @a val.
+        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(invalid_iterator::create(204, "iterators out of range"));
+                }
 
-    @throw type_error.309 if called on JSON values other than arrays;
-    example: `"cannot use insert() with string"`
-    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
-    example: `"iterator does not fit current value"`
+                if (is_string())
+                {
+                    AllocatorType<string_t> alloc;
+                    alloc.destroy(m_value.string);
+                    alloc.deallocate(m_value.string, 1);
+                    m_value.string = nullptr;
+                }
 
-    @complexity Constant plus linear in the distance between @a pos and end of
-    the container.
+                m_type = value_t::null;
+                assert_invariant();
+                break;
+            }
 
-    @liveexample{The example shows how `insert()` is used.,insert}
+            case value_t::object:
+            {
+                result.m_it.object_iterator = m_value.object->erase(first.m_it.object_iterator,
+                                              last.m_it.object_iterator);
+                break;
+            }
 
-    @since version 1.0.0
-    */
-    iterator insert(const_iterator pos, const basic_json& val)
-    {
-        // insert only works for arrays
-        if (is_array())
-        {
-            // check if iterator pos fits to this JSON value
-            if (pos.m_object != this)
+            case value_t::array:
             {
-                JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
+                result.m_it.array_iterator = m_value.array->erase(first.m_it.array_iterator,
+                                             last.m_it.array_iterator);
+                break;
             }
 
-            // insert to array and return iterator
-            iterator result(this);
-            result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, val);
-            return result;
+            default:
+            {
+                JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
+            }
         }
 
-        JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
+        return result;
     }
 
     /*!
-    @brief inserts element
-    @copydoc insert(const_iterator, const basic_json&)
-    */
-    iterator insert(const_iterator pos, basic_json&& val)
-    {
-        return insert(pos, val);
-    }
+    @brief remove element from a JSON object given a key
 
-    /*!
-    @brief inserts elements
+    Removes elements from a JSON object with the key value @a key.
 
-    Inserts @a cnt copies of @a val before iterator @a pos.
+    @param[in] key value of the elements to remove
 
-    @param[in] pos iterator before which the content will be inserted; may be
-    the end() iterator
-    @param[in] cnt number of copies of @a val to insert
-    @param[in] val element to insert
-    @return iterator pointing to the first element inserted, or @a pos if
-    `cnt==0`
+    @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).
 
-    @throw type_error.309 if called on JSON values other than arrays; example:
-    `"cannot use insert() with string"`
-    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
-    example: `"iterator does not fit current value"`
+    @post References and iterators to the erased elements are invalidated.
+    Other references and iterators are not affected.
 
-    @complexity Linear in @a cnt plus linear in the distance between @a pos
-    and end of the container.
+    @throw type_error.307 when called on a type other than JSON object;
+    example: `"cannot use erase() with null"`
 
-    @liveexample{The example shows how `insert()` is used.,insert__count}
+    @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
     */
-    iterator insert(const_iterator pos, size_type cnt, const basic_json& val)
+    size_type erase(const typename object_t::key_type& key)
     {
-        // insert only works for arrays
-        if (is_array())
+        // this erase only works for objects
+        if (is_object())
         {
-            // check if iterator pos fits to this JSON value
-            if (pos.m_object != this)
-            {
-                JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
-            }
-
-            // insert to array and return iterator
-            iterator result(this);
-            result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, cnt, val);
-            return result;
+            return m_value.object->erase(key);
         }
 
-        JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
+        JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
     }
 
     /*!
-    @brief inserts elements
+    @brief remove element from a JSON array given an index
 
-    Inserts elements from range `[first, last)` before iterator @a pos.
+    Removes element from a JSON array at the index @a idx.
 
-    @param[in] pos iterator before which the content will be inserted; may be
-    the end() iterator
-    @param[in] first begin of the range of elements to insert
-    @param[in] last end of the range of elements to insert
+    @param[in] idx index of the element to remove
 
-    @throw type_error.309 if called on JSON values other than arrays; example:
-    `"cannot use insert() with string"`
-    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
-    example: `"iterator does not fit current value"`
-    @throw invalid_iterator.210 if @a first and @a last do not belong to the
-    same JSON value; example: `"iterators do not fit"`
-    @throw invalid_iterator.211 if @a first or @a last are iterators into
-    container for which insert is called; example: `"passed iterators may not
-    belong to container"`
+    @throw type_error.307 when called on a type other than JSON object;
+    example: `"cannot use erase() with null"`
+    @throw out_of_range.401 when `idx >= size()`; example: `"array index 17
+    is out of range"`
 
-    @return iterator pointing to the first element inserted, or @a pos if
-    `first==last`
+    @complexity Linear in distance between @a idx and the end of the container.
 
-    @complexity Linear in `std::distance(first, last)` plus linear in the
-    distance between @a pos and end of the container.
+    @liveexample{The example shows the effect of `erase()`.,erase__size_type}
 
-    @liveexample{The example shows how `insert()` is used.,insert__range}
+    @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
     */
-    iterator insert(const_iterator pos, const_iterator first, const_iterator last)
+    void erase(const size_type idx)
     {
-        // insert only works for arrays
-        if (not is_array())
+        // this erase only works for arrays
+        if (is_array())
         {
-            JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
-        }
+            if (idx >= size())
+            {
+                JSON_THROW(out_of_range::create(401, "array index " + std::to_string(idx) + " is out of range"));
+            }
 
-        // check if iterator pos fits to this JSON value
-        if (pos.m_object != this)
-        {
-            JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
+            m_value.array->erase(m_value.array->begin() + static_cast<difference_type>(idx));
         }
-
-        // check if range iterators belong to the same JSON object
-        if (first.m_object != last.m_object)
+        else
         {
-            JSON_THROW(invalid_iterator::create(210, "iterators do not fit"));
+            JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
         }
+    }
 
-        if (first.m_object == this or last.m_object == this)
-        {
-            JSON_THROW(invalid_iterator::create(211, "passed iterators may not belong to container"));
-        }
+    /// @}
 
-        // insert to array and return iterator
-        iterator result(this);
-        result.m_it.array_iterator = m_value.array->insert(
-                                         pos.m_it.array_iterator,
-                                         first.m_it.array_iterator,
-                                         last.m_it.array_iterator);
-        return result;
-    }
+
+    ////////////
+    // lookup //
+    ////////////
+
+    /// @name lookup
+    /// @{
 
     /*!
-    @brief inserts elements
+    @brief find an element in a JSON object
 
-    Inserts elements from initializer list @a ilist before iterator @a pos.
+    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.
 
-    @param[in] pos iterator before which the content will be inserted; may be
-    the end() iterator
-    @param[in] ilist initializer list to insert the values from
+    @note This method always returns @ref end() when executed on a JSON type
+          that is not an object.
 
-    @throw type_error.309 if called on JSON values other than arrays; example:
-    `"cannot use insert() with string"`
-    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
-    example: `"iterator does not fit current value"`
+    @param[in] key key value of the element to search for
 
-    @return iterator pointing to the first element inserted, or @a pos if
-    `ilist` is empty
+    @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 Linear in `ilist.size()` plus linear in the distance between
-    @a pos and end of the container.
+    @complexity Logarithmic in the size of the JSON object.
 
-    @liveexample{The example shows how `insert()` is used.,insert__ilist}
+    @liveexample{The example shows how `find()` is used.,find__key_type}
 
     @since version 1.0.0
     */
-    iterator insert(const_iterator pos, std::initializer_list<basic_json> ilist)
+    iterator find(typename object_t::key_type key)
     {
-        // insert only works for arrays
-        if (not is_array())
-        {
-            JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
-        }
+        auto result = end();
 
-        // check if iterator pos fits to this JSON value
-        if (pos.m_object != this)
+        if (is_object())
         {
-            JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
+            result.m_it.object_iterator = m_value.object->find(key);
         }
 
-        // insert to array and return iterator
-        iterator result(this);
-        result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, ilist);
         return result;
     }
 
     /*!
-    @brief inserts elements
-
-    Inserts elements from range `[first, last)`.
-
-    @param[in] first begin of the range of elements to insert
-    @param[in] last end of the range of elements to insert
-
-    @throw type_error.309 if called on JSON values other than objects; example:
-    `"cannot use insert() with string"`
-    @throw invalid_iterator.202 if iterator @a first or @a last does does not
-    point to an object; example: `"iterators first and last must point to
-    objects"`
-    @throw invalid_iterator.210 if @a first and @a last do not belong to the
-    same JSON value; example: `"iterators do not fit"`
-
-    @complexity Logarithmic: `O(N*log(size() + N))`, where `N` is the number
-    of elements to insert.
-
-    @liveexample{The example shows how `insert()` is used.,insert__range_object}
-
-    @since version 3.0.0
+    @brief find an element in a JSON object
+    @copydoc find(typename object_t::key_type)
     */
-    void insert(const_iterator first, const_iterator last)
+    const_iterator find(typename object_t::key_type key) const
     {
-        // insert only works for objects
-        if (not is_object())
-        {
-            JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
-        }
-
-        // check if range iterators belong to the same JSON object
-        if (first.m_object != last.m_object)
-        {
-            JSON_THROW(invalid_iterator::create(210, "iterators do not fit"));
-        }
+        auto result = cend();
 
-        // passed iterators must belong to objects
-        if (not first.m_object->is_object() or not first.m_object->is_object())
+        if (is_object())
         {
-            JSON_THROW(invalid_iterator::create(202, "iterators first and last must point to objects"));
+            result.m_it.object_iterator = m_value.object->find(key);
         }
 
-        m_value.object->insert(first.m_it.object_iterator, last.m_it.object_iterator);
+        return result;
     }
 
     /*!
-    @brief exchanges the values
+    @brief returns the number of occurrences of a key in a JSON object
 
-    Exchanges the contents of the JSON value with those of @a other. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated.
+    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).
 
-    @param[in,out] other JSON value to exchange the contents with
+    @note This method always returns `0` when executed on a JSON type that is
+          not an object.
 
-    @complexity Constant.
+    @param[in] key key value of the element to count
 
-    @liveexample{The example below shows how JSON values can be swapped with
-    `swap()`.,swap__reference}
+    @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
     */
-    void swap(reference other) noexcept (
-        std::is_nothrow_move_constructible<value_t>::value and
-        std::is_nothrow_move_assignable<value_t>::value and
-        std::is_nothrow_move_constructible<json_value>::value and
-        std::is_nothrow_move_assignable<json_value>::value
-    )
+    size_type count(typename object_t::key_type key) const
     {
-        std::swap(m_type, other.m_type);
-        std::swap(m_value, other.m_value);
-        assert_invariant();
+        // return 0 for all nonobject types
+        return is_object() ? m_value.object->count(key) : 0;
     }
 
+    /// @}
+
+
+    ///////////////
+    // iterators //
+    ///////////////
+
+    /// @name iterators
+    /// @{
+
     /*!
-    @brief exchanges the values
+    @brief returns an iterator to the first element
 
-    Exchanges the contents of a JSON array with those of @a other. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated.
+    Returns an iterator to the first element.
 
-    @param[in,out] other array to exchange the contents with
+    @image html range-begin-end.svg "Illustration from cppreference.com"
 
-    @throw type_error.310 when JSON value is not an array; example: `"cannot
-    use swap() with string"`
+    @return iterator to the first element
 
     @complexity Constant.
 
-    @liveexample{The example below shows how arrays can be swapped with
-    `swap()`.,swap__array_t}
+    @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
     */
-    void swap(array_t& other)
+    iterator begin() noexcept
     {
-        // swap only works for arrays
-        if (is_array())
-        {
-            std::swap(*(m_value.array), other);
-        }
-        else
-        {
-            JSON_THROW(type_error::create(310, "cannot use swap() with " + type_name()));
-        }
+        iterator result(this);
+        result.set_begin();
+        return result;
     }
 
     /*!
-    @brief exchanges the values
+    @copydoc basic_json::cbegin()
+    */
+    const_iterator begin() const noexcept
+    {
+        return cbegin();
+    }
 
-    Exchanges the contents of a JSON object with those of @a other. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated.
+    /*!
+    @brief returns a const iterator to the first element
 
-    @param[in,out] other object to exchange the contents with
+    Returns a const iterator to the first element.
 
-    @throw type_error.310 when JSON value is not an object; example:
-    `"cannot use swap() with string"`
+    @image html range-begin-end.svg "Illustration from cppreference.com"
+
+    @return const iterator to the first element
 
     @complexity Constant.
 
-    @liveexample{The example below shows how objects can be swapped with
-    `swap()`.,swap__object_t}
+    @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
     */
-    void swap(object_t& other)
+    const_iterator cbegin() const noexcept
     {
-        // swap only works for objects
-        if (is_object())
-        {
-            std::swap(*(m_value.object), other);
-        }
-        else
-        {
-            JSON_THROW(type_error::create(310, "cannot use swap() with " + type_name()));
-        }
+        const_iterator result(this);
+        result.set_begin();
+        return result;
     }
 
     /*!
-    @brief exchanges the values
+    @brief returns an iterator to one past the last element
 
-    Exchanges the contents of a JSON string with those of @a other. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated.
+    Returns an iterator to one past the last element.
 
-    @param[in,out] other string to exchange the contents with
+    @image html range-begin-end.svg "Illustration from cppreference.com"
 
-    @throw type_error.310 when JSON value is not a string; example: `"cannot
-    use swap() with boolean"`
+    @return iterator one past the last element
 
     @complexity Constant.
 
-    @liveexample{The example below shows how strings can be swapped with
-    `swap()`.,swap__string_t}
+    @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
     */
-    void swap(string_t& other)
+    iterator end() noexcept
     {
-        // swap only works for strings
-        if (is_string())
-        {
-            std::swap(*(m_value.string), other);
-        }
-        else
-        {
-            JSON_THROW(type_error::create(310, "cannot use swap() with " + type_name()));
-        }
+        iterator result(this);
+        result.set_end();
+        return result;
     }
 
-    /// @}
+    /*!
+    @copydoc basic_json::cend()
+    */
+    const_iterator end() const noexcept
+    {
+        return cend();
+    }
 
-  public:
-    //////////////////////////////////////////
-    // lexicographical comparison operators //
-    //////////////////////////////////////////
+    /*!
+    @brief returns a const iterator to one past the last element
 
-    /// @name lexicographical comparison operators
-    /// @{
+    Returns a const iterator to one past the last element.
 
-    /*!
-    @brief comparison: equal
+    @image html range-begin-end.svg "Illustration from cppreference.com"
 
-    Compares two JSON values for equality according to the following rules:
-    - Two JSON values are equal if (1) they are from the same type and (2)
-      their stored values are the same according to their respective
-      `operator==`.
-    - Integer and floating-point numbers are automatically converted before
-      comparison. Note than two NaN values are always treated as unequal.
-    - Two JSON null values are equal.
+    @return const iterator one past the last element
 
-    @note NaN values never compare equal to themselves or to other NaN values.
+    @complexity Constant.
 
-    @param[in] lhs  first JSON value to consider
-    @param[in] rhs  second JSON value to consider
-    @return whether the values @a lhs and @a rhs are equal
+    @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()`.
 
-    @complexity Linear.
+    @liveexample{The following code shows an example for `cend()`.,cend}
 
-    @liveexample{The example demonstrates comparing several JSON
-    types.,operator__equal}
+    @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
     */
-    friend bool operator==(const_reference lhs, const_reference rhs) noexcept
+    const_iterator cend() const noexcept
     {
-        const auto lhs_type = lhs.type();
-        const auto rhs_type = rhs.type();
-
-        if (lhs_type == rhs_type)
-        {
-            switch (lhs_type)
-            {
-                case value_t::array:
-                {
-                    return *lhs.m_value.array == *rhs.m_value.array;
-                }
-                case value_t::object:
-                {
-                    return *lhs.m_value.object == *rhs.m_value.object;
-                }
-                case value_t::null:
-                {
-                    return true;
-                }
-                case value_t::string:
-                {
-                    return *lhs.m_value.string == *rhs.m_value.string;
-                }
-                case value_t::boolean:
-                {
-                    return lhs.m_value.boolean == rhs.m_value.boolean;
-                }
-                case value_t::number_integer:
-                {
-                    return lhs.m_value.number_integer == rhs.m_value.number_integer;
-                }
-                case value_t::number_unsigned:
-                {
-                    return lhs.m_value.number_unsigned == rhs.m_value.number_unsigned;
-                }
-                case value_t::number_float:
-                {
-                    return lhs.m_value.number_float == rhs.m_value.number_float;
-                }
-                default:
-                {
-                    return false;
-                }
-            }
-        }
-        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_float)
-        {
-            return static_cast<number_float_t>(lhs.m_value.number_integer) == rhs.m_value.number_float;
-        }
-        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_integer)
-        {
-            return lhs.m_value.number_float == static_cast<number_float_t>(rhs.m_value.number_integer);
-        }
-        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_float)
-        {
-            return static_cast<number_float_t>(lhs.m_value.number_unsigned) == rhs.m_value.number_float;
-        }
-        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_unsigned)
-        {
-            return lhs.m_value.number_float == static_cast<number_float_t>(rhs.m_value.number_unsigned);
-        }
-        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_integer)
-        {
-            return static_cast<number_integer_t>(lhs.m_value.number_unsigned) == rhs.m_value.number_integer;
-        }
-        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_unsigned)
-        {
-            return lhs.m_value.number_integer == static_cast<number_integer_t>(rhs.m_value.number_unsigned);
-        }
-
-        return false;
+        const_iterator result(this);
+        result.set_end();
+        return result;
     }
 
     /*!
-    @brief comparison: equal
-    @copydoc operator==(const_reference, const_reference)
+    @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
     */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator==(const_reference lhs, const ScalarType rhs) noexcept
+    reverse_iterator rbegin() noexcept
     {
-        return (lhs == basic_json(rhs));
+        return reverse_iterator(end());
     }
 
     /*!
-    @brief comparison: equal
-    @copydoc operator==(const_reference, const_reference)
+    @copydoc basic_json::crbegin()
     */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator==(const ScalarType lhs, const_reference rhs) noexcept
+    const_reverse_iterator rbegin() const noexcept
     {
-        return (basic_json(lhs) == rhs);
+        return crbegin();
     }
 
     /*!
-    @brief comparison: not equal
+    @brief returns an iterator to the reverse-end
 
-    Compares two JSON values for inequality by calculating `not (lhs == rhs)`.
+    Returns an iterator to the reverse-end; that is, one before the first
+    element.
 
-    @param[in] lhs  first JSON value to consider
-    @param[in] rhs  second JSON value to consider
-    @return whether the values @a lhs and @a rhs are not equal
+    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
 
-    @complexity Linear.
+    @complexity Constant.
 
-    @liveexample{The example demonstrates comparing several JSON
-    types.,operator__notequal}
+    @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
     */
-    friend bool operator!=(const_reference lhs, const_reference rhs) noexcept
+    reverse_iterator rend() noexcept
     {
-        return not (lhs == rhs);
+        return reverse_iterator(begin());
     }
 
     /*!
-    @brief comparison: not equal
-    @copydoc operator!=(const_reference, const_reference)
+    @copydoc basic_json::crend()
     */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator!=(const_reference lhs, const ScalarType rhs) noexcept
+    const_reverse_iterator rend() const noexcept
     {
-        return (lhs != basic_json(rhs));
+        return crend();
     }
 
     /*!
-    @brief comparison: not equal
-    @copydoc operator!=(const_reference, const_reference)
+    @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
     */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator!=(const ScalarType lhs, const_reference rhs) noexcept
+    const_reverse_iterator crbegin() const noexcept
     {
-        return (basic_json(lhs) != rhs);
+        return const_reverse_iterator(cend());
     }
 
     /*!
-    @brief comparison: less than
+    @brief returns a const reverse iterator to one before the first
 
-    Compares whether one JSON value @a lhs is less than another JSON value @a
-    rhs according to the following rules:
-    - If @a lhs and @a rhs have the same type, the values are compared using
-      the default `<` operator.
-    - Integer and floating-point numbers are automatically converted before
-      comparison
-    - In case @a lhs and @a rhs have different types, the values are ignored
-      and the order of the types is considered, see
-      @ref operator<(const value_t, const value_t).
+    Returns a const reverse iterator to the reverse-end; that is, one before
+    the first element.
 
-    @param[in] lhs  first JSON value to consider
-    @param[in] rhs  second JSON value to consider
-    @return whether @a lhs is less than @a rhs
+    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
 
-    @complexity Linear.
+    @complexity Constant.
 
-    @liveexample{The example demonstrates comparing several JSON
-    types.,operator__less}
+    @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
     */
-    friend bool operator<(const_reference lhs, const_reference rhs) noexcept
+    const_reverse_iterator crend() const noexcept
     {
-        const auto lhs_type = lhs.type();
-        const auto rhs_type = rhs.type();
+        return const_reverse_iterator(cbegin());
+    }
 
-        if (lhs_type == rhs_type)
-        {
-            switch (lhs_type)
-            {
-                case value_t::array:
-                {
-                    return (*lhs.m_value.array) < (*rhs.m_value.array);
-                }
-                case value_t::object:
-                {
-                    return *lhs.m_value.object < *rhs.m_value.object;
-                }
-                case value_t::null:
-                {
-                    return false;
-                }
-                case value_t::string:
-                {
-                    return *lhs.m_value.string < *rhs.m_value.string;
-                }
-                case value_t::boolean:
-                {
-                    return lhs.m_value.boolean < rhs.m_value.boolean;
-                }
-                case value_t::number_integer:
-                {
-                    return lhs.m_value.number_integer < rhs.m_value.number_integer;
-                }
-                case value_t::number_unsigned:
-                {
-                    return lhs.m_value.number_unsigned < rhs.m_value.number_unsigned;
-                }
-                case value_t::number_float:
-                {
-                    return lhs.m_value.number_float < rhs.m_value.number_float;
-                }
-                default:
-                {
-                    return false;
-                }
-            }
-        }
-        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_float)
-        {
-            return static_cast<number_float_t>(lhs.m_value.number_integer) < rhs.m_value.number_float;
-        }
-        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_integer)
-        {
-            return lhs.m_value.number_float < static_cast<number_float_t>(rhs.m_value.number_integer);
-        }
-        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_float)
-        {
-            return static_cast<number_float_t>(lhs.m_value.number_unsigned) < rhs.m_value.number_float;
-        }
-        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_unsigned)
-        {
-            return lhs.m_value.number_float < static_cast<number_float_t>(rhs.m_value.number_unsigned);
-        }
-        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_unsigned)
-        {
-            return lhs.m_value.number_integer < static_cast<number_integer_t>(rhs.m_value.number_unsigned);
-        }
-        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_integer)
-        {
-            return static_cast<number_integer_t>(lhs.m_value.number_unsigned) < rhs.m_value.number_integer;
-        }
-
-        // We only reach this line if we cannot compare values. In that case,
-        // we compare types. Note we have to call the operator explicitly,
-        // because MSVC has problems otherwise.
-        return operator<(lhs_type, rhs_type);
-    }
+  private:
+    // forward declaration
+    template<typename IteratorType> class iteration_proxy;
 
+  public:
     /*!
-    @brief comparison: less than
-    @copydoc operator<(const_reference, const_reference)
+    @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.
+
+    @liveexample{The following code shows how the wrapper is used,iterator_wrapper}
+
+    @note The name of this function is not yet final and may change in the
+    future.
     */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator<(const_reference lhs, const ScalarType rhs) noexcept
+    static iteration_proxy<iterator> iterator_wrapper(reference cont)
     {
-        return (lhs < basic_json(rhs));
+        return iteration_proxy<iterator>(cont);
     }
 
     /*!
-    @brief comparison: less than
-    @copydoc operator<(const_reference, const_reference)
+    @copydoc iterator_wrapper(reference)
     */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator<(const ScalarType lhs, const_reference rhs) noexcept
+    static iteration_proxy<const_iterator> iterator_wrapper(const_reference cont)
     {
-        return (basic_json(lhs) < rhs);
+        return iteration_proxy<const_iterator>(cont);
     }
 
-    /*!
-    @brief comparison: less than or equal
-
-    Compares whether one JSON value @a lhs is less than or equal to another
-    JSON value by calculating `not (rhs < lhs)`.
-
-    @param[in] lhs  first JSON value to consider
-    @param[in] rhs  second JSON value to consider
-    @return whether @a lhs is less than or equal to @a rhs
+    /// @}
 
-    @complexity Linear.
 
-    @liveexample{The example demonstrates comparing several JSON
-    types.,operator__greater}
+    //////////////
+    // capacity //
+    //////////////
 
-    @since version 1.0.0
-    */
-    friend bool operator<=(const_reference lhs, const_reference rhs) noexcept
-    {
-        return not (rhs < lhs);
-    }
+    /// @name capacity
+    /// @{
 
     /*!
-    @brief comparison: less than or equal
-    @copydoc operator<=(const_reference, const_reference)
-    */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator<=(const_reference lhs, const ScalarType rhs) noexcept
-    {
-        return (lhs <= basic_json(rhs));
-    }
+    @brief checks whether the container is empty
 
-    /*!
-    @brief comparison: less than or equal
-    @copydoc operator<=(const_reference, const_reference)
-    */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator<=(const ScalarType lhs, const_reference rhs) noexcept
-    {
-        return (basic_json(lhs) <= rhs);
-    }
+    Checks if a JSON value has no elements.
 
-    /*!
-    @brief comparison: greater than
+    @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()`
 
-    Compares whether one JSON value @a lhs is greater than another
-    JSON value by calculating `not (lhs <= rhs)`.
+    @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.
 
-    @param[in] lhs  first JSON value to consider
-    @param[in] rhs  second JSON value to consider
-    @return whether @a lhs is greater than to @a rhs
+    @complexity Constant, as long as @ref array_t and @ref object_t satisfy
+    the Container concept; that is, their `empty()` functions have constant
+    complexity.
 
-    @complexity Linear.
+    @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 example demonstrates comparing several JSON
-    types.,operator__lessequal}
+    @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
     */
-    friend bool operator>(const_reference lhs, const_reference rhs) noexcept
+    bool empty() const noexcept
     {
-        return not (lhs <= rhs);
-    }
+        switch (m_type)
+        {
+            case value_t::null:
+            {
+                // null values are empty
+                return true;
+            }
 
-    /*!
-    @brief comparison: greater than
-    @copydoc operator>(const_reference, const_reference)
-    */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator>(const_reference lhs, const ScalarType rhs) noexcept
-    {
-        return (lhs > basic_json(rhs));
-    }
+            case value_t::array:
+            {
+                // delegate call to array_t::empty()
+                return m_value.array->empty();
+            }
 
-    /*!
-    @brief comparison: greater than
-    @copydoc operator>(const_reference, const_reference)
-    */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator>(const ScalarType lhs, const_reference rhs) noexcept
-    {
-        return (basic_json(lhs) > rhs);
+            case value_t::object:
+            {
+                // delegate call to object_t::empty()
+                return m_value.object->empty();
+            }
+
+            default:
+            {
+                // all other types are nonempty
+                return false;
+            }
+        }
     }
 
     /*!
-    @brief comparison: greater than or equal
+    @brief returns the number of elements
 
-    Compares whether one JSON value @a lhs is greater than or equal to another
-    JSON value by calculating `not (lhs < rhs)`.
+    Returns the number of elements in a JSON value.
 
-    @param[in] lhs  first JSON value to consider
-    @param[in] rhs  second JSON value to consider
-    @return whether @a lhs is greater than or equal to @a rhs
+    @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()
 
-    @complexity Linear.
+    @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.
 
-    @liveexample{The example demonstrates comparing several JSON
-    types.,operator__greaterequal}
+    @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
     */
-    friend bool operator>=(const_reference lhs, const_reference rhs) noexcept
+    size_type size() const noexcept
     {
-        return not (lhs < rhs);
-    }
+        switch (m_type)
+        {
+            case value_t::null:
+            {
+                // null values are empty
+                return 0;
+            }
 
-    /*!
-    @brief comparison: greater than or equal
-    @copydoc operator>=(const_reference, const_reference)
-    */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator>=(const_reference lhs, const ScalarType rhs) noexcept
-    {
-        return (lhs >= basic_json(rhs));
-    }
+            case value_t::array:
+            {
+                // delegate call to array_t::size()
+                return m_value.array->size();
+            }
 
-    /*!
-    @brief comparison: greater than or equal
-    @copydoc operator>=(const_reference, const_reference)
-    */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator>=(const ScalarType lhs, const_reference rhs) noexcept
-    {
-        return (basic_json(lhs) >= rhs);
-    }
-
-    /// @}
-
-  private:
-    /////////////////////
-    // output adapters //
-    /////////////////////
-
-    /// abstract output adapter interface
-    template<typename CharType>
-    class output_adapter
-    {
-      public:
-        virtual void write_character(CharType c) = 0;
-        virtual void write_characters(const CharType* s, size_t length) = 0;
-        virtual ~output_adapter() {}
+            case value_t::object:
+            {
+                // delegate call to object_t::size()
+                return m_value.object->size();
+            }
 
-        static std::shared_ptr<output_adapter<CharType>> create(std::vector<CharType>& vec)
-        {
-            return std::make_shared<output_vector_adapter<CharType>>(vec);
+            default:
+            {
+                // all other types have size 1
+                return 1;
+            }
         }
+    }
 
-        static std::shared_ptr<output_adapter<CharType>> create(std::ostream& s)
-        {
-            return std::make_shared<output_stream_adapter<CharType>>(s);
-        }
+    /*!
+    @brief returns the maximum possible number of elements
 
-        static std::shared_ptr<output_adapter<CharType>> create(std::string& s)
-        {
-            return std::make_shared<output_string_adapter<CharType>>(s);
-        }
-    };
+    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.
 
-    /// a type to simplify interfaces
-    template<typename CharType>
-    using output_adapter_t = std::shared_ptr<output_adapter<CharType>>;
+    @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()`
 
-    /// output adapter for byte vectors
-    template<typename CharType>
-    class output_vector_adapter : public output_adapter<CharType>
-    {
-      public:
-        output_vector_adapter(std::vector<CharType>& vec)
-            : v(vec)
-        {}
+    @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.
 
-        void write_character(CharType c) override
-        {
-            v.push_back(c);
-        }
+    @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.
 
-        void write_characters(const CharType* s, size_t length) override
-        {
-            std::copy(s, s + length, std::back_inserter(v));
-        }
+    @liveexample{The following code calls `max_size()` on the different value
+    types. Note the output is implementation specific.,max_size}
 
-      private:
-        std::vector<CharType>& v;
-    };
+    @sa @ref size() -- returns the number of elements
 
-    /// output adapter for output streams
-    template<typename CharType>
-    class output_stream_adapter : public output_adapter<CharType>
+    @since version 1.0.0
+    */
+    size_type max_size() const noexcept
     {
-      public:
-        output_stream_adapter(std::basic_ostream<CharType>& s)
-            : stream(s)
-        {}
-
-        void write_character(CharType c) override
-        {
-            stream.put(c);
-        }
-
-        void write_characters(const CharType* s, size_t length) override
+        switch (m_type)
         {
-            stream.write(s, static_cast<std::streamsize>(length));
-        }
-
-      private:
-        std::basic_ostream<CharType>& stream;
-    };
-
-    /// output adapter for basic_string
-    template<typename CharType>
-    class output_string_adapter : public output_adapter<CharType>
-    {
-      public:
-        output_string_adapter(std::string& s)
-            : str(s)
-        {}
+            case value_t::array:
+            {
+                // delegate call to array_t::max_size()
+                return m_value.array->max_size();
+            }
 
-        void write_character(CharType c) override
-        {
-            str.push_back(c);
-        }
+            case value_t::object:
+            {
+                // delegate call to object_t::max_size()
+                return m_value.object->max_size();
+            }
 
-        void write_characters(const CharType* s, size_t length) override
-        {
-            str.append(s, length);
+            default:
+            {
+                // all other types have max_size() == size()
+                return size();
+            }
         }
+    }
 
-      private:
-        std::basic_string<CharType>& str;
-    };
+    /// @}
 
 
-    ///////////////////
-    // serialization //
-    ///////////////////
+    ///////////////
+    // modifiers //
+    ///////////////
 
-    /// @name serialization
+    /// @name modifiers
     /// @{
 
-  private:
     /*!
-    @brief wrapper around the serialization functions
-    */
-    class serializer
-    {
-      public:
-        /*!
-        @param[in] s  output stream to serialize to
-        @param[in] ichar  indentation character to use
-        */
-        serializer(output_adapter_t<char> s, const char ichar)
-            : o(s), loc(std::localeconv()),
-              thousands_sep(!loc->thousands_sep ? '\0' : loc->thousands_sep[0]),
-              decimal_point(!loc->decimal_point ? '\0' : loc->decimal_point[0]),
-              indent_char(ichar), indent_string(512, indent_char)
-        {}
+    @brief clears the contents
 
-        // delete because of pointer members
-        serializer(const serializer&) = delete;
-        serializer& operator=(const serializer&) = delete;
+    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:
 
-        /*!
-        @brief internal implementation of the serialization function
+    Value type  | initial value
+    ----------- | -------------
+    null        | `null`
+    boolean     | `false`
+    string      | `""`
+    number      | `0`
+    object      | `{}`
+    array       | `[]`
 
-        This function is called by the public member function dump and
-        organizes the serialization internally. The indentation level is
-        propagated as additional parameter. In case of arrays and objects, the
-        function is called recursively.
+    @complexity Linear in the size of the JSON value.
 
-        - strings and object keys are escaped using `escape_string()`
-        - integer numbers are converted implicitly via `operator<<`
-        - floating-point numbers are converted to a string using `"%g"` format
+    @liveexample{The example below shows the effect of `clear()` to different
+    JSON types.,clear}
 
-        @param[in] val             value to serialize
-        @param[in] pretty_print    whether the output shall be pretty-printed
-        @param[in] indent_step     the indent level
-        @param[in] current_indent  the current indent level (only used internally)
-        */
-        void dump(const basic_json& val,
-                  const bool pretty_print,
-                  const unsigned int indent_step,
-                  const unsigned int current_indent = 0)
+    @since version 1.0.0
+    */
+    void clear() noexcept
+    {
+        switch (m_type)
         {
-            switch (val.m_type)
+            case value_t::number_integer:
             {
-                case value_t::object:
-                {
-                    if (val.m_value.object->empty())
-                    {
-                        o->write_characters("{}", 2);
-                        return;
-                    }
+                m_value.number_integer = 0;
+                break;
+            }
 
-                    if (pretty_print)
-                    {
-                        o->write_characters("{\n", 2);
+            case value_t::number_unsigned:
+            {
+                m_value.number_unsigned = 0;
+                break;
+            }
 
-                        // variable to hold indentation for recursive calls
-                        const auto new_indent = current_indent + indent_step;
-                        if (JSON_UNLIKELY(indent_string.size() < new_indent))
-                        {
-                            indent_string.resize(indent_string.size() * 2, ' ');
-                        }
+            case value_t::number_float:
+            {
+                m_value.number_float = 0.0;
+                break;
+            }
 
-                        // first n-1 elements
-                        auto i = val.m_value.object->cbegin();
-                        for (size_t cnt = 0; cnt < val.m_value.object->size() - 1; ++cnt, ++i)
-                        {
-                            o->write_characters(indent_string.c_str(), new_indent);
-                            o->write_character('\"');
-                            dump_escaped(i->first);
-                            o->write_characters("\": ", 3);
-                            dump(i->second, true, indent_step, new_indent);
-                            o->write_characters(",\n", 2);
-                        }
-
-                        // last element
-                        assert(i != val.m_value.object->cend());
-                        o->write_characters(indent_string.c_str(), new_indent);
-                        o->write_character('\"');
-                        dump_escaped(i->first);
-                        o->write_characters("\": ", 3);
-                        dump(i->second, true, indent_step, new_indent);
+            case value_t::boolean:
+            {
+                m_value.boolean = false;
+                break;
+            }
 
-                        o->write_character('\n');
-                        o->write_characters(indent_string.c_str(), current_indent);
-                        o->write_character('}');
-                    }
-                    else
-                    {
-                        o->write_character('{');
+            case value_t::string:
+            {
+                m_value.string->clear();
+                break;
+            }
 
-                        // first n-1 elements
-                        auto i = val.m_value.object->cbegin();
-                        for (size_t cnt = 0; cnt < val.m_value.object->size() - 1; ++cnt, ++i)
-                        {
-                            o->write_character('\"');
-                            dump_escaped(i->first);
-                            o->write_characters("\":", 2);
-                            dump(i->second, false, indent_step, current_indent);
-                            o->write_character(',');
-                        }
+            case value_t::array:
+            {
+                m_value.array->clear();
+                break;
+            }
 
-                        // last element
-                        assert(i != val.m_value.object->cend());
-                        o->write_character('\"');
-                        dump_escaped(i->first);
-                        o->write_characters("\":", 2);
-                        dump(i->second, false, indent_step, current_indent);
+            case value_t::object:
+            {
+                m_value.object->clear();
+                break;
+            }
 
-                        o->write_character('}');
-                    }
+            default:
+            {
+                break;
+            }
+        }
+    }
 
-                    return;
-                }
+    /*!
+    @brief add an object to an array
 
-                case value_t::array:
-                {
-                    if (val.m_value.array->empty())
-                    {
-                        o->write_characters("[]", 2);
-                        return;
-                    }
+    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.
 
-                    if (pretty_print)
-                    {
-                        o->write_characters("[\n", 2);
+    @param[in] val the value to add to the JSON array
 
-                        // variable to hold indentation for recursive calls
-                        const auto new_indent = current_indent + indent_step;
-                        if (indent_string.size() < new_indent)
-                        {
-                            indent_string.resize(new_indent, ' ');
-                        }
+    @throw type_error.308 when called on a type other than JSON array or
+    null; example: `"cannot use push_back() with number"`
 
-                        // first n-1 elements
-                        for (auto i = val.m_value.array->cbegin(); i != val.m_value.array->cend() - 1; ++i)
-                        {
-                            o->write_characters(indent_string.c_str(), new_indent);
-                            dump(*i, true, indent_step, new_indent);
-                            o->write_characters(",\n", 2);
-                        }
+    @complexity Amortized constant.
 
-                        // last element
-                        assert(not val.m_value.array->empty());
-                        o->write_characters(indent_string.c_str(), new_indent);
-                        dump(val.m_value.array->back(), true, indent_step, new_indent);
+    @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}
 
-                        o->write_character('\n');
-                        o->write_characters(indent_string.c_str(), current_indent);
-                        o->write_character(']');
-                    }
-                    else
-                    {
-                        o->write_character('[');
+    @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(type_error::create(308, "cannot use push_back() with " + type_name()));
+        }
 
-                        // first n-1 elements
-                        for (auto i = val.m_value.array->cbegin(); i != val.m_value.array->cend() - 1; ++i)
-                        {
-                            dump(*i, false, indent_step, current_indent);
-                            o->write_character(',');
-                        }
+        // transform null object into an array
+        if (is_null())
+        {
+            m_type = value_t::array;
+            m_value = value_t::array;
+            assert_invariant();
+        }
 
-                        // last element
-                        assert(not val.m_value.array->empty());
-                        dump(val.m_value.array->back(), false, indent_step, current_indent);
+        // add element to array (move semantics)
+        m_value.array->push_back(std::move(val));
+        // invalidate object
+        val.m_type = value_t::null;
+    }
 
-                        o->write_character(']');
-                    }
+    /*!
+    @brief add an object to an array
+    @copydoc push_back(basic_json&&)
+    */
+    reference operator+=(basic_json&& val)
+    {
+        push_back(std::move(val));
+        return *this;
+    }
 
-                    return;
-                }
+    /*!
+    @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(type_error::create(308, "cannot use push_back() with " + type_name()));
+        }
 
-                case value_t::string:
-                {
-                    o->write_character('\"');
-                    dump_escaped(*val.m_value.string);
-                    o->write_character('\"');
-                    return;
-                }
+        // transform null object into an array
+        if (is_null())
+        {
+            m_type = value_t::array;
+            m_value = value_t::array;
+            assert_invariant();
+        }
 
-                case value_t::boolean:
-                {
-                    if (val.m_value.boolean)
-                    {
-                        o->write_characters("true", 4);
-                    }
-                    else
-                    {
-                        o->write_characters("false", 5);
-                    }
-                    return;
-                }
+        // add element to array
+        m_value.array->push_back(val);
+    }
 
-                case value_t::number_integer:
-                {
-                    dump_integer(val.m_value.number_integer);
-                    return;
-                }
+    /*!
+    @brief add an object to an array
+    @copydoc push_back(basic_json&&)
+    */
+    reference operator+=(const basic_json& val)
+    {
+        push_back(val);
+        return *this;
+    }
 
-                case value_t::number_unsigned:
-                {
-                    dump_integer(val.m_value.number_unsigned);
-                    return;
-                }
+    /*!
+    @brief add an object to an object
 
-                case value_t::number_float:
-                {
-                    dump_float(val.m_value.number_float);
-                    return;
-                }
+    Inserts the given element @a val to the JSON object. If the function is
+    called on a JSON null value, an empty object is created before inserting
+    @a val.
 
-                case value_t::discarded:
-                {
-                    o->write_characters("<discarded>", 11);
-                    return;
-                }
+    @param[in] val the value to add to the JSON object
 
-                case value_t::null:
-                {
-                    o->write_characters("null", 4);
-                    return;
-                }
-            }
-        }
+    @throw type_error.308 when called on a type other than JSON object or
+    null; example: `"cannot use push_back() with number"`
 
-      private:
-        /*!
-        @brief calculates the extra space to escape a JSON string
+    @complexity Logarithmic in the size of the container, O(log(`size()`)).
 
-        @param[in] s  the string to escape
-        @return the number of characters required to escape string @a s
+    @liveexample{The example shows how `push_back()` and `+=` can be used to
+    add elements to a JSON object. Note how the `null` value was silently
+    converted to a JSON object.,push_back__object_t__value}
 
-        @complexity Linear in the length of string @a s.
-        */
-        static std::size_t extra_space(const string_t& s) noexcept
-        {
-            return std::accumulate(s.begin(), s.end(), size_t{},
-                                   [](size_t res, typename string_t::value_type c)
-            {
-                switch (c)
-                {
-                    case '"':
-                    case '\\':
-                    case '\b':
-                    case '\f':
-                    case '\n':
-                    case '\r':
-                    case '\t':
-                    {
-                        // from c (1 byte) to \x (2 bytes)
-                        return res + 1;
-                    }
-
-                    case 0x00:
-                    case 0x01:
-                    case 0x02:
-                    case 0x03:
-                    case 0x04:
-                    case 0x05:
-                    case 0x06:
-                    case 0x07:
-                    case 0x0b:
-                    case 0x0e:
-                    case 0x0f:
-                    case 0x10:
-                    case 0x11:
-                    case 0x12:
-                    case 0x13:
-                    case 0x14:
-                    case 0x15:
-                    case 0x16:
-                    case 0x17:
-                    case 0x18:
-                    case 0x19:
-                    case 0x1a:
-                    case 0x1b:
-                    case 0x1c:
-                    case 0x1d:
-                    case 0x1e:
-                    case 0x1f:
-                    {
-                        // from c (1 byte) to \uxxxx (6 bytes)
-                        return res + 5;
-                    }
+    @since version 1.0.0
+    */
+    void push_back(const typename object_t::value_type& val)
+    {
+        // push_back only works for null objects or objects
+        if (not(is_null() or is_object()))
+        {
+            JSON_THROW(type_error::create(308, "cannot use push_back() with " + type_name()));
+        }
 
-                    default:
-                    {
-                        return res;
-                    }
-                }
-            });
+        // transform null object into an object
+        if (is_null())
+        {
+            m_type = value_t::object;
+            m_value = value_t::object;
+            assert_invariant();
         }
 
-        /*!
-        @brief dump escaped string
+        // add element to array
+        m_value.object->insert(val);
+    }
 
-        Escape a string by replacing certain special characters by a sequence
-        of an escape character (backslash) and another character and other
-        control characters by a sequence of "\u" followed by a four-digit hex
-        representation. The escaped string is written to output stream @a o.
+    /*!
+    @brief add an object to an object
+    @copydoc push_back(const typename object_t::value_type&)
+    */
+    reference operator+=(const typename object_t::value_type& val)
+    {
+        push_back(val);
+        return *this;
+    }
 
-        @param[in] s  the string to escape
+    /*!
+    @brief add an object to an object
 
-        @complexity Linear in the length of string @a s.
-        */
-        void dump_escaped(const string_t& s) const
-        {
-            const auto space = extra_space(s);
-            if (space == 0)
-            {
-                o->write_characters(s.c_str(), s.size());
-                return;
-            }
+    This function allows to use `push_back` with an initializer list. In case
 
-            // create a result string of necessary size
-            string_t result(s.size() + space, '\\');
-            std::size_t pos = 0;
+    1. the current value is an object,
+    2. the initializer list @a init contains only two elements, and
+    3. the first element of @a init is a string,
 
-            for (const auto& c : s)
-            {
-                switch (c)
-                {
-                    // quotation mark (0x22)
-                    case '"':
-                    {
-                        result[pos + 1] = '"';
-                        pos += 2;
-                        break;
-                    }
+    @a init is converted into an object element and added using
+    @ref push_back(const typename object_t::value_type&). Otherwise, @a init
+    is converted to a JSON value and added using @ref push_back(basic_json&&).
 
-                    // reverse solidus (0x5c)
-                    case '\\':
-                    {
-                        // nothing to change
-                        pos += 2;
-                        break;
-                    }
+    @param[in] init  an initializer list
 
-                    // backspace (0x08)
-                    case '\b':
-                    {
-                        result[pos + 1] = 'b';
-                        pos += 2;
-                        break;
-                    }
+    @complexity Linear in the size of the initializer list @a init.
 
-                    // formfeed (0x0c)
-                    case '\f':
-                    {
-                        result[pos + 1] = 'f';
-                        pos += 2;
-                        break;
-                    }
+    @note This function is required to resolve an ambiguous overload error,
+          because pairs like `{"key", "value"}` can be both interpreted as
+          `object_t::value_type` or `std::initializer_list<basic_json>`, see
+          https://github.com/nlohmann/json/issues/235 for more information.
 
-                    // newline (0x0a)
-                    case '\n':
-                    {
-                        result[pos + 1] = 'n';
-                        pos += 2;
-                        break;
-                    }
+    @liveexample{The example shows how initializer lists are treated as
+    objects when possible.,push_back__initializer_list}
+    */
+    void push_back(std::initializer_list<basic_json> init)
+    {
+        if (is_object() and init.size() == 2 and init.begin()->is_string())
+        {
+            const string_t key = *init.begin();
+            push_back(typename object_t::value_type(key, *(init.begin() + 1)));
+        }
+        else
+        {
+            push_back(basic_json(init));
+        }
+    }
 
-                    // carriage return (0x0d)
-                    case '\r':
-                    {
-                        result[pos + 1] = 'r';
-                        pos += 2;
-                        break;
-                    }
+    /*!
+    @brief add an object to an object
+    @copydoc push_back(std::initializer_list<basic_json>)
+    */
+    reference operator+=(std::initializer_list<basic_json> init)
+    {
+        push_back(init);
+        return *this;
+    }
 
-                    // horizontal tab (0x09)
-                    case '\t':
-                    {
-                        result[pos + 1] = 't';
-                        pos += 2;
-                        break;
-                    }
+    /*!
+    @brief add an object to an array
 
-                    case 0x00:
-                    case 0x01:
-                    case 0x02:
-                    case 0x03:
-                    case 0x04:
-                    case 0x05:
-                    case 0x06:
-                    case 0x07:
-                    case 0x0b:
-                    case 0x0e:
-                    case 0x0f:
-                    case 0x10:
-                    case 0x11:
-                    case 0x12:
-                    case 0x13:
-                    case 0x14:
-                    case 0x15:
-                    case 0x16:
-                    case 0x17:
-                    case 0x18:
-                    case 0x19:
-                    case 0x1a:
-                    case 0x1b:
-                    case 0x1c:
-                    case 0x1d:
-                    case 0x1e:
-                    case 0x1f:
-                    {
-                        // convert a number 0..15 to its hex representation
-                        // (0..f)
-                        static const char hexify[16] =
-                        {
-                            '0', '1', '2', '3', '4', '5', '6', '7',
-                            '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'
-                        };
+    Creates a JSON value from the passed parameters @a args to the end of the
+    JSON value. If the function is called on a JSON null value, an empty array
+    is created before appending the value created from @a args.
 
-                        // print character c as \uxxxx
-                        for (const char m :
-                    { 'u', '0', '0', hexify[c >> 4], hexify[c & 0x0f]
-                        })
-                        {
-                            result[++pos] = m;
-                        }
+    @param[in] args arguments to forward to a constructor of @ref basic_json
+    @tparam Args compatible types to create a @ref basic_json object
 
-                        ++pos;
-                        break;
-                    }
+    @throw type_error.311 when called on a type other than JSON array or
+    null; example: `"cannot use emplace_back() with number"`
 
-                    default:
-                    {
-                        // all other characters are added as-is
-                        result[pos++] = c;
-                        break;
-                    }
-                }
-            }
+    @complexity Amortized constant.
 
-            assert(pos == s.size() + space);
-            o->write_characters(result.c_str(), result.size());
+    @liveexample{The example shows how `push_back()` can be used to add
+    elements to a JSON array. Note how the `null` value was silently converted
+    to a JSON array.,emplace_back}
+
+    @since version 2.0.8
+    */
+    template<class... Args>
+    void emplace_back(Args&& ... args)
+    {
+        // emplace_back only works for null objects or arrays
+        if (not(is_null() or is_array()))
+        {
+            JSON_THROW(type_error::create(311, "cannot use emplace_back() with " + type_name()));
         }
 
-        /*!
-        @brief dump an integer
+        // transform null object into an array
+        if (is_null())
+        {
+            m_type = value_t::array;
+            m_value = value_t::array;
+            assert_invariant();
+        }
 
-        Dump a given integer to output stream @a o. Works internally with
-        @a number_buffer.
+        // add element to array (perfect forwarding)
+        m_value.array->emplace_back(std::forward<Args>(args)...);
+    }
 
-        @param[in] x  integer number (signed or unsigned) to dump
-        @tparam NumberType either @a number_integer_t or @a number_unsigned_t
-        */
-        template<typename NumberType, detail::enable_if_t <
-                     std::is_same<NumberType, number_unsigned_t>::value or
-                     std::is_same<NumberType, number_integer_t>::value, int> = 0>
-        void dump_integer(NumberType x)
-        {
-            // special case for "0"
-            if (x == 0)
-            {
-                o->write_character('0');
-                return;
-            }
+    /*!
+    @brief add an object to an object if key does not exist
 
-            const bool is_negative = x < 0;
-            size_t i = 0;
+    Inserts a new element into a JSON object constructed in-place with the
+    given @a args if there is no element with the key in the container. If the
+    function is called on a JSON null value, an empty object is created before
+    appending the value created from @a args.
 
-            // spare 1 byte for '\0'
-            while (x != 0 and i < number_buffer.size() - 1)
-            {
-                const auto digit = std::labs(static_cast<long>(x % 10));
-                number_buffer[i++] = static_cast<char>('0' + digit);
-                x /= 10;
-            }
+    @param[in] args arguments to forward to a constructor of @ref basic_json
+    @tparam Args compatible types to create a @ref basic_json object
 
-            // make sure the number has been processed completely
-            assert(x == 0);
+    @return a pair consisting of an iterator to the inserted element, or the
+            already-existing element if no insertion happened, and a bool
+            denoting whether the insertion took place.
 
-            if (is_negative)
-            {
-                // make sure there is capacity for the '-'
-                assert(i < number_buffer.size() - 2);
-                number_buffer[i++] = '-';
-            }
+    @throw type_error.311 when called on a type other than JSON object or
+    null; example: `"cannot use emplace() with number"`
 
-            std::reverse(number_buffer.begin(), number_buffer.begin() + i);
-            o->write_characters(number_buffer.data(), i);
-        }
+    @complexity Logarithmic in the size of the container, O(log(`size()`)).
 
-        /*!
-        @brief dump a floating-point number
+    @liveexample{The example shows how `emplace()` can be used to add elements
+    to a JSON object. Note how the `null` value was silently converted to a
+    JSON object. Further note how no value is added if there was already one
+    value stored with the same key.,emplace}
 
-        Dump a given floating-point number to output stream @a o. Works
-        internally with @a number_buffer.
+    @since version 2.0.8
+    */
+    template<class... Args>
+    std::pair<iterator, bool> emplace(Args&& ... args)
+    {
+        // emplace only works for null objects or arrays
+        if (not(is_null() or is_object()))
+        {
+            JSON_THROW(type_error::create(311, "cannot use emplace() with " + type_name()));
+        }
 
-        @param[in] x  floating-point number to dump
-        */
-        void dump_float(number_float_t x)
+        // transform null object into an object
+        if (is_null())
         {
-            // NaN / inf
-            if (not std::isfinite(x) or std::isnan(x))
-            {
-                o->write_characters("null", 4);
-                return;
-            }
+            m_type = value_t::object;
+            m_value = value_t::object;
+            assert_invariant();
+        }
 
-            // special case for 0.0 and -0.0
-            if (x == 0)
-            {
-                if (std::signbit(x))
-                {
-                    o->write_characters("-0.0", 4);
-                }
-                else
-                {
-                    o->write_characters("0.0", 3);
-                }
-                return;
-            }
+        // add element to array (perfect forwarding)
+        auto res = m_value.object->emplace(std::forward<Args>(args)...);
+        // create result iterator and set iterator to the result of emplace
+        auto it = begin();
+        it.m_it.object_iterator = res.first;
 
-            // get number of digits for a text -> float -> text round-trip
-            static constexpr auto d = std::numeric_limits<number_float_t>::digits10;
+        // return pair of iterator and boolean
+        return {it, res.second};
+    }
 
-            // the actual conversion
-            std::ptrdiff_t len = snprintf(number_buffer.data(), number_buffer.size(),
-                                          "%.*g", d, x);
+    /*!
+    @brief inserts element
 
-            // negative value indicates an error
-            assert(len > 0);
-            // check if buffer was large enough
-            assert(static_cast<size_t>(len) < number_buffer.size());
+    Inserts element @a val before iterator @a pos.
 
-            // erase thousands separator
-            if (thousands_sep != '\0')
-            {
-                const auto end = std::remove(number_buffer.begin(),
-                                             number_buffer.begin() + len,
-                                             thousands_sep);
-                std::fill(end, number_buffer.end(), '\0');
-                assert((end - number_buffer.begin()) <= len);
-                len = (end - number_buffer.begin());
-            }
+    @param[in] pos iterator before which the content will be inserted; may be
+    the end() iterator
+    @param[in] val element to insert
+    @return iterator pointing to the inserted @a val.
 
-            // convert decimal point to '.'
-            if (decimal_point != '\0' and decimal_point != '.')
-            {
-                for (auto& c : number_buffer)
-                {
-                    if (c == decimal_point)
-                    {
-                        c = '.';
-                        break;
-                    }
-                }
-            }
+    @throw type_error.309 if called on JSON values other than arrays;
+    example: `"cannot use insert() with string"`
+    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
+    example: `"iterator does not fit current value"`
 
-            o->write_characters(number_buffer.data(), static_cast<size_t>(len));
+    @complexity Constant plus linear in the distance between @a pos and end of
+    the container.
 
-            // determine if need to append ".0"
-            const bool value_is_int_like = std::none_of(number_buffer.begin(),
-                                           number_buffer.begin() + len + 1,
-                                           [](char c)
-            {
-                return c == '.' or c == 'e';
-            });
+    @liveexample{The example shows how `insert()` is used.,insert}
 
-            if (value_is_int_like)
+    @since version 1.0.0
+    */
+    iterator insert(const_iterator pos, const basic_json& val)
+    {
+        // insert only works for arrays
+        if (is_array())
+        {
+            // check if iterator pos fits to this JSON value
+            if (pos.m_object != this)
             {
-                o->write_characters(".0", 2);
+                JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
             }
-        }
 
-      private:
-        /// the output of the serializer
-        output_adapter_t<char> o = nullptr;
+            // insert to array and return iterator
+            iterator result(this);
+            result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, val);
+            return result;
+        }
 
-        /// a (hopefully) large enough character buffer
-        std::array<char, 64> number_buffer{{}};
+        JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
+    }
 
-        /// the locale
-        const std::lconv* loc = nullptr;
-        /// the locale's thousand separator character
-        const char thousands_sep = '\0';
-        /// the locale's decimal point character
-        const char decimal_point = '\0';
+    /*!
+    @brief inserts element
+    @copydoc insert(const_iterator, const basic_json&)
+    */
+    iterator insert(const_iterator pos, basic_json&& val)
+    {
+        return insert(pos, val);
+    }
 
-        /// the indentation character
-        const char indent_char;
+    /*!
+    @brief inserts elements
 
-        /// the indentation string
-        string_t indent_string;
-    };
+    Inserts @a cnt copies of @a val before iterator @a pos.
 
-  public:
-    /*!
-    @brief serialize to stream
+    @param[in] pos iterator before which the content will be inserted; may be
+    the end() iterator
+    @param[in] cnt number of copies of @a val to insert
+    @param[in] val element to insert
+    @return iterator pointing to the first element inserted, or @a pos if
+    `cnt==0`
 
-    Serialize the given JSON value @a j to the output stream @a o. The JSON
-    value will be serialized using the @ref dump member function.
+    @throw type_error.309 if called on JSON values other than arrays; example:
+    `"cannot use insert() with string"`
+    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
+    example: `"iterator does not fit current value"`
 
-    - The indentation of the output can be controlled with the member variable
-      `width` of the output stream @a o. For instance, using the manipulator
-      `std::setw(4)` on @a o sets the indentation level to `4` and the
-      serialization result is the same as calling `dump(4)`.
+    @complexity Linear in @a cnt plus linear in the distance between @a pos
+    and end of the container.
 
-    - The indentation characrer can be controlled with the member variable
-      `fill` of the output stream @a o. For instance, the manipulator
-      `std::setfill('\\t')` sets indentation to use a tab character rather than
-      the default space character.
+    @liveexample{The example shows how `insert()` is used.,insert__count}
 
-    @param[in,out] o  stream to serialize to
-    @param[in] j  JSON value to serialize
-
-    @return the stream @a o
-
-    @complexity Linear.
-
-    @liveexample{The example below shows the serialization with different
-    parameters to `width` to adjust the indentation level.,operator_serialize}
-
-    @since version 1.0.0; indentaction character added in version 3.0.0
+    @since version 1.0.0
     */
-    friend std::ostream& operator<<(std::ostream& o, const basic_json& j)
+    iterator insert(const_iterator pos, size_type cnt, const basic_json& val)
     {
-        // read width member and use it as indentation parameter if nonzero
-        const bool pretty_print = (o.width() > 0);
-        const auto indentation = (pretty_print ? o.width() : 0);
+        // insert only works for arrays
+        if (is_array())
+        {
+            // check if iterator pos fits to this JSON value
+            if (pos.m_object != this)
+            {
+                JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
+            }
 
-        // reset width to 0 for subsequent calls to this stream
-        o.width(0);
+            // insert to array and return iterator
+            iterator result(this);
+            result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, cnt, val);
+            return result;
+        }
 
-        // do the actual serialization
-        serializer s(output_adapter<char>::create(o), o.fill());
-        s.dump(j, pretty_print, static_cast<unsigned int>(indentation));
-        return o;
+        JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
     }
 
     /*!
-    @brief serialize to stream
-    @deprecated This stream operator is deprecated and will be removed in a
-                future version of the library. Please use
-                @ref std::ostream& operator<<(std::ostream&, const basic_json&)
-                instead; that is, replace calls like `j >> o;` with `o << j;`.
-    */
-    JSON_DEPRECATED
-    friend std::ostream& operator>>(const basic_json& j, std::ostream& o)
-    {
-        return o << j;
-    }
-
-    /// @}
-
-
-    /////////////////////
-    // deserialization //
-    /////////////////////
-
-    /// @name deserialization
-    /// @{
+    @brief inserts elements
 
-    /*!
-    @brief deserialize from an array
+    Inserts elements from range `[first, last)` before iterator @a pos.
 
-    This function reads from an array of 1-byte values.
+    @param[in] pos iterator before which the content will be inserted; may be
+    the end() iterator
+    @param[in] first begin of the range of elements to insert
+    @param[in] last end of the range of elements to insert
 
-    @pre Each element of the container has a size of 1 byte. Violating this
-    precondition yields undefined behavior. **This precondition is enforced
-    with a static assertion.**
+    @throw type_error.309 if called on JSON values other than arrays; example:
+    `"cannot use insert() with string"`
+    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
+    example: `"iterator does not fit current value"`
+    @throw invalid_iterator.210 if @a first and @a last do not belong to the
+    same JSON value; example: `"iterators do not fit"`
+    @throw invalid_iterator.211 if @a first or @a last are iterators into
+    container for which insert is called; example: `"passed iterators may not
+    belong to container"`
 
-    @param[in] array  array to read from
-    @param[in] cb  a parser callback function of type @ref parser_callback_t
-    which is used to control the deserialization by filtering unwanted values
-    (optional)
+    @return iterator pointing to the first element inserted, or @a pos if
+    `first==last`
 
-    @return result of the deserialization
+    @complexity Linear in `std::distance(first, last)` plus linear in the
+    distance between @a pos and end of the container.
 
-    @throw parse_error.101 if a parse error occurs; example: `""unexpected end
-    of input; expected string literal""`
-    @throw parse_error.102 if to_unicode fails or surrogate error
-    @throw parse_error.103 if to_unicode fails
+    @liveexample{The example shows how `insert()` is used.,insert__range}
 
-    @complexity Linear in the length of the input. The parser is a predictive
-    LL(1) parser. The complexity can be higher if the parser callback function
-    @a cb has a super-linear complexity.
+    @since version 1.0.0
+    */
+    iterator insert(const_iterator pos, const_iterator first, const_iterator last)
+    {
+        // insert only works for arrays
+        if (not is_array())
+        {
+            JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
+        }
 
-    @note A UTF-8 byte order mark is silently ignored.
+        // check if iterator pos fits to this JSON value
+        if (pos.m_object != this)
+        {
+            JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
+        }
 
-    @liveexample{The example below demonstrates the `parse()` function reading
-    from an array.,parse__array__parser_callback_t}
+        // check if range iterators belong to the same JSON object
+        if (first.m_object != last.m_object)
+        {
+            JSON_THROW(invalid_iterator::create(210, "iterators do not fit"));
+        }
 
-    @since version 2.0.3
-    */
-    template<class T, std::size_t N>
-    static basic_json parse(T (&array)[N],
-                            const parser_callback_t cb = nullptr)
-    {
-        // delegate the call to the iterator-range parse overload
-        return parse(std::begin(array), std::end(array), cb);
-    }
+        if (first.m_object == this or last.m_object == this)
+        {
+            JSON_THROW(invalid_iterator::create(211, "passed iterators may not belong to container"));
+        }
 
-    template<class T, std::size_t N>
-    static bool accept(T (&array)[N])
-    {
-        // delegate the call to the iterator-range accept overload
-        return accept(std::begin(array), std::end(array));
+        // insert to array and return iterator
+        iterator result(this);
+        result.m_it.array_iterator = m_value.array->insert(
+                                         pos.m_it.array_iterator,
+                                         first.m_it.array_iterator,
+                                         last.m_it.array_iterator);
+        return result;
     }
 
     /*!
-    @brief deserialize from string literal
-
-    @tparam CharT character/literal type with size of 1 byte
-    @param[in] s  string literal to read a serialized JSON value from
-    @param[in] cb a parser callback function of type @ref parser_callback_t
-    which is used to control the deserialization by filtering unwanted values
-    (optional)
+    @brief inserts elements
 
-    @return result of the deserialization
+    Inserts elements from initializer list @a ilist before iterator @a pos.
 
-    @throw parse_error.101 in case of an unexpected token
-    @throw parse_error.102 if to_unicode fails or surrogate error
-    @throw parse_error.103 if to_unicode fails
+    @param[in] pos iterator before which the content will be inserted; may be
+    the end() iterator
+    @param[in] ilist initializer list to insert the values from
 
-    @complexity Linear in the length of the input. The parser is a predictive
-    LL(1) parser. The complexity can be higher if the parser callback function
-    @a cb has a super-linear complexity.
+    @throw type_error.309 if called on JSON values other than arrays; example:
+    `"cannot use insert() with string"`
+    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
+    example: `"iterator does not fit current value"`
 
-    @note A UTF-8 byte order mark is silently ignored.
-    @note String containers like `std::string` or @ref string_t can be parsed
-          with @ref parse(const ContiguousContainer&, const parser_callback_t)
+    @return iterator pointing to the first element inserted, or @a pos if
+    `ilist` is empty
 
-    @liveexample{The example below demonstrates the `parse()` function with
-    and without callback function.,parse__string__parser_callback_t}
+    @complexity Linear in `ilist.size()` plus linear in the distance between
+    @a pos and end of the container.
 
-    @sa @ref parse(std::istream&, const parser_callback_t) for a version that
-    reads from an input stream
+    @liveexample{The example shows how `insert()` is used.,insert__ilist}
 
-    @since version 1.0.0 (originally for @ref string_t)
+    @since version 1.0.0
     */
-    template<typename CharT, typename std::enable_if<
-                 std::is_pointer<CharT>::value and
-                 std::is_integral<typename std::remove_pointer<CharT>::type>::value and
-                 sizeof(typename std::remove_pointer<CharT>::type) == 1, int>::type = 0>
-    static basic_json parse(const CharT s,
-                            const parser_callback_t cb = nullptr)
+    iterator insert(const_iterator pos, std::initializer_list<basic_json> ilist)
     {
-        return parser(detail::input_adapter_factory::create(s), cb).parse(true);
-    }
+        // insert only works for arrays
+        if (not is_array())
+        {
+            JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
+        }
 
-    template<typename CharT, typename std::enable_if<
-                 std::is_pointer<CharT>::value and
-                 std::is_integral<typename std::remove_pointer<CharT>::type>::value and
-                 sizeof(typename std::remove_pointer<CharT>::type) == 1, int>::type = 0>
-    static bool accept(const CharT s)
-    {
-        return parser(detail::input_adapter_factory::create(s)).accept(true);
+        // check if iterator pos fits to this JSON value
+        if (pos.m_object != this)
+        {
+            JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
+        }
+
+        // insert to array and return iterator
+        iterator result(this);
+        result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, ilist);
+        return result;
     }
 
     /*!
-    @brief deserialize from stream
-
-    @param[in,out] i  stream to read a serialized JSON value from
-    @param[in] cb a parser callback function of type @ref parser_callback_t
-    which is used to control the deserialization by filtering unwanted values
-    (optional)
-
-    @return result of the deserialization
+    @brief inserts elements
 
-    @throw parse_error.101 in case of an unexpected token
-    @throw parse_error.102 if to_unicode fails or surrogate error
-    @throw parse_error.103 if to_unicode fails
+    Inserts elements from range `[first, last)`.
 
-    @complexity Linear in the length of the input. The parser is a predictive
-    LL(1) parser. The complexity can be higher if the parser callback function
-    @a cb has a super-linear complexity.
+    @param[in] first begin of the range of elements to insert
+    @param[in] last end of the range of elements to insert
 
-    @note A UTF-8 byte order mark is silently ignored.
+    @throw type_error.309 if called on JSON values other than objects; example:
+    `"cannot use insert() with string"`
+    @throw invalid_iterator.202 if iterator @a first or @a last does does not
+    point to an object; example: `"iterators first and last must point to
+    objects"`
+    @throw invalid_iterator.210 if @a first and @a last do not belong to the
+    same JSON value; example: `"iterators do not fit"`
 
-    @liveexample{The example below demonstrates the `parse()` function with
-    and without callback function.,parse__istream__parser_callback_t}
+    @complexity Logarithmic: `O(N*log(size() + N))`, where `N` is the number
+    of elements to insert.
 
-    @sa @ref parse(const CharT, const parser_callback_t) for a version
-    that reads from a string
+    @liveexample{The example shows how `insert()` is used.,insert__range_object}
 
-    @since version 1.0.0
+    @since version 3.0.0
     */
-    static basic_json parse(std::istream& i,
-                            const parser_callback_t cb = nullptr)
+    void insert(const_iterator first, const_iterator last)
     {
-        return parser(detail::input_adapter_factory::create(i), cb).parse(true);
-    }
+        // insert only works for objects
+        if (not is_object())
+        {
+            JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
+        }
 
-    static bool accept(std::istream& i)
-    {
-        return parser(detail::input_adapter_factory::create(i)).accept(true);
-    }
+        // check if range iterators belong to the same JSON object
+        if (first.m_object != last.m_object)
+        {
+            JSON_THROW(invalid_iterator::create(210, "iterators do not fit"));
+        }
 
-    /*!
-    @copydoc parse(std::istream&, const parser_callback_t)
-    */
-    static basic_json parse(std::istream&& i,
-                            const parser_callback_t cb = nullptr)
-    {
-        return parser(detail::input_adapter_factory::create(i), cb).parse(true);
-    }
+        // passed iterators must belong to objects
+        if (not first.m_object->is_object() or not first.m_object->is_object())
+        {
+            JSON_THROW(invalid_iterator::create(202, "iterators first and last must point to objects"));
+        }
 
-    static bool accept(std::istream&& i)
-    {
-        return parser(detail::input_adapter_factory::create(i)).accept(true);
+        m_value.object->insert(first.m_it.object_iterator, last.m_it.object_iterator);
     }
 
     /*!
-    @brief deserialize from an iterator range with contiguous storage
-
-    This function reads from an iterator range of a container with contiguous
-    storage of 1-byte values. Compatible container types include
-    `std::vector`, `std::string`, `std::array`, `std::valarray`, and
-    `std::initializer_list`. Furthermore, C-style arrays can be used with
-    `std::begin()`/`std::end()`. User-defined containers can be used as long
-    as they implement random-access iterators and a contiguous storage.
-
-    @pre The iterator range is contiguous. Violating this precondition yields
-    undefined behavior. **This precondition is enforced with an assertion.**
-    @pre Each element in the range has a size of 1 byte. Violating this
-    precondition yields undefined behavior. **This precondition is enforced
-    with a static assertion.**
-
-    @warning There is no way to enforce all preconditions at compile-time. If
-             the function is called with noncompliant iterators and with
-             assertions switched off, the behavior is undefined and will most
-             likely yield segmentation violation.
-
-    @tparam IteratorType iterator of container with contiguous storage
-    @param[in] first  begin of the range to parse (included)
-    @param[in] last  end of the range to parse (excluded)
-    @param[in] cb  a parser callback function of type @ref parser_callback_t
-    which is used to control the deserialization by filtering unwanted values
-    (optional)
-
-    @return result of the deserialization
+    @brief exchanges the values
 
-    @throw parse_error.101 in case of an unexpected token
-    @throw parse_error.102 if to_unicode fails or surrogate error
-    @throw parse_error.103 if to_unicode fails
+    Exchanges the contents of the JSON value with those of @a other. Does not
+    invoke any move, copy, or swap operations on individual elements. All
+    iterators and references remain valid. The past-the-end iterator is
+    invalidated.
 
-    @complexity Linear in the length of the input. The parser is a predictive
-    LL(1) parser. The complexity can be higher if the parser callback function
-    @a cb has a super-linear complexity.
+    @param[in,out] other JSON value to exchange the contents with
 
-    @note A UTF-8 byte order mark is silently ignored.
+    @complexity Constant.
 
-    @liveexample{The example below demonstrates the `parse()` function reading
-    from an iterator range.,parse__iteratortype__parser_callback_t}
+    @liveexample{The example below shows how JSON values can be swapped with
+    `swap()`.,swap__reference}
 
-    @since version 2.0.3
+    @since version 1.0.0
     */
-    template<class IteratorType, typename std::enable_if<
-                 std::is_base_of<
-                     std::random_access_iterator_tag,
-                     typename std::iterator_traits<IteratorType>::iterator_category>::value, int>::type = 0>
-    static basic_json parse(IteratorType first, IteratorType last,
-                            const parser_callback_t cb = nullptr)
-    {
-        return parser(detail::input_adapter_factory::create(first, last), cb).parse(true);
-    }
-
-    template<class IteratorType, typename std::enable_if<
-                 std::is_base_of<
-                     std::random_access_iterator_tag,
-                     typename std::iterator_traits<IteratorType>::iterator_category>::value, int>::type = 0>
-    static bool accept(IteratorType first, IteratorType last)
+    void swap(reference other) noexcept (
+        std::is_nothrow_move_constructible<value_t>::value and
+        std::is_nothrow_move_assignable<value_t>::value and
+        std::is_nothrow_move_constructible<json_value>::value and
+        std::is_nothrow_move_assignable<json_value>::value
+    )
     {
-        return parser(detail::input_adapter_factory::create(first, last)).accept(true);
+        std::swap(m_type, other.m_type);
+        std::swap(m_value, other.m_value);
+        assert_invariant();
     }
 
     /*!
-    @brief deserialize from a container with contiguous storage
+    @brief exchanges the values
 
-    This function reads from a container with contiguous storage of 1-byte
-    values. Compatible container types include `std::vector`, `std::string`,
-    `std::array`, and `std::initializer_list`. User-defined containers can be
-    used as long as they implement random-access iterators and a contiguous
-    storage.
+    Exchanges the contents of a JSON array with those of @a other. Does not
+    invoke any move, copy, or swap operations on individual elements. All
+    iterators and references remain valid. The past-the-end iterator is
+    invalidated.
 
-    @pre The container storage is contiguous. Violating this precondition
-    yields undefined behavior. **This precondition is enforced with an
-    assertion.**
-    @pre Each element of the container has a size of 1 byte. Violating this
-    precondition yields undefined behavior. **This precondition is enforced
-    with a static assertion.**
+    @param[in,out] other array to exchange the contents with
 
-    @warning There is no way to enforce all preconditions at compile-time. If
-             the function is called with a noncompliant container and with
-             assertions switched off, the behavior is undefined and will most
-             likely yield segmentation violation.
+    @throw type_error.310 when JSON value is not an array; example: `"cannot
+    use swap() with string"`
 
-    @tparam ContiguousContainer container type with contiguous storage
-    @param[in] c  container to read from
-    @param[in] cb  a parser callback function of type @ref parser_callback_t
-    which is used to control the deserialization by filtering unwanted values
-    (optional)
+    @complexity Constant.
 
-    @return result of the deserialization
+    @liveexample{The example below shows how arrays can be swapped with
+    `swap()`.,swap__array_t}
 
-    @throw parse_error.101 in case of an unexpected token
-    @throw parse_error.102 if to_unicode fails or surrogate error
-    @throw parse_error.103 if to_unicode fails
+    @since version 1.0.0
+    */
+    void swap(array_t& other)
+    {
+        // swap only works for arrays
+        if (is_array())
+        {
+            std::swap(*(m_value.array), other);
+        }
+        else
+        {
+            JSON_THROW(type_error::create(310, "cannot use swap() with " + type_name()));
+        }
+    }
 
-    @complexity Linear in the length of the input. The parser is a predictive
-    LL(1) parser. The complexity can be higher if the parser callback function
-    @a cb has a super-linear complexity.
+    /*!
+    @brief exchanges the values
 
-    @note A UTF-8 byte order mark is silently ignored.
+    Exchanges the contents of a JSON object with those of @a other. Does not
+    invoke any move, copy, or swap operations on individual elements. All
+    iterators and references remain valid. The past-the-end iterator is
+    invalidated.
 
-    @liveexample{The example below demonstrates the `parse()` function reading
-    from a contiguous container.,parse__contiguouscontainer__parser_callback_t}
+    @param[in,out] other object to exchange the contents with
 
-    @since version 2.0.3
-    */
-    template<class ContiguousContainer, typename std::enable_if<
-                 not std::is_pointer<ContiguousContainer>::value and
-                 std::is_base_of<
-                     std::random_access_iterator_tag,
-                     typename std::iterator_traits<decltype(std::begin(std::declval<ContiguousContainer const>()))>::iterator_category>::value
-                 , int>::type = 0>
-    static basic_json parse(const ContiguousContainer& c,
-                            const parser_callback_t cb = nullptr)
-    {
-        // delegate the call to the iterator-range parse overload
-        return parse(std::begin(c), std::end(c), cb);
-    }
+    @throw type_error.310 when JSON value is not an object; example:
+    `"cannot use swap() with string"`
 
-    template<class ContiguousContainer, typename std::enable_if<
-                 not std::is_pointer<ContiguousContainer>::value and
-                 std::is_base_of<
-                     std::random_access_iterator_tag,
-                     typename std::iterator_traits<decltype(std::begin(std::declval<ContiguousContainer const>()))>::iterator_category>::value
-                 , int>::type = 0>
-    static bool accept(const ContiguousContainer& c)
-    {
-        // delegate the call to the iterator-range accept overload
-        return accept(std::begin(c), std::end(c));
-    }
+    @complexity Constant.
 
-    /*!
-    @brief deserialize from stream
-    @deprecated This stream operator is deprecated and will be removed in a
-                future version of the library. Please use
-                @ref std::istream& operator>>(std::istream&, basic_json&)
-                instead; that is, replace calls like `j << i;` with `i >> j;`.
+    @liveexample{The example below shows how objects can be swapped with
+    `swap()`.,swap__object_t}
+
+    @since version 1.0.0
     */
-    JSON_DEPRECATED
-    friend std::istream& operator<<(basic_json& j, std::istream& i)
+    void swap(object_t& other)
     {
-        j = parser(detail::input_adapter_factory::create(i)).parse(false);
-        return i;
+        // swap only works for objects
+        if (is_object())
+        {
+            std::swap(*(m_value.object), other);
+        }
+        else
+        {
+            JSON_THROW(type_error::create(310, "cannot use swap() with " + type_name()));
+        }
     }
 
     /*!
-    @brief deserialize from stream
-
-    Deserializes an input stream to a JSON value.
-
-    @param[in,out] i  input stream to read a serialized JSON value from
-    @param[in,out] j  JSON value to write the deserialized input to
+    @brief exchanges the values
 
-    @throw parse_error.101 in case of an unexpected token
-    @throw parse_error.102 if to_unicode fails or surrogate error
-    @throw parse_error.103 if to_unicode fails
+    Exchanges the contents of a JSON string with those of @a other. Does not
+    invoke any move, copy, or swap operations on individual elements. All
+    iterators and references remain valid. The past-the-end iterator is
+    invalidated.
 
-    @complexity Linear in the length of the input. The parser is a predictive
-    LL(1) parser.
+    @param[in,out] other string to exchange the contents with
 
-    @note A UTF-8 byte order mark is silently ignored.
+    @throw type_error.310 when JSON value is not a string; example: `"cannot
+    use swap() with boolean"`
 
-    @liveexample{The example below shows how a JSON value is constructed by
-    reading a serialization from a stream.,operator_deserialize}
+    @complexity Constant.
 
-    @sa parse(std::istream&, const parser_callback_t) for a variant with a
-    parser callback function to filter values while parsing
+    @liveexample{The example below shows how strings can be swapped with
+    `swap()`.,swap__string_t}
 
     @since version 1.0.0
     */
-    friend std::istream& operator>>(std::istream& i, basic_json& j)
+    void swap(string_t& other)
     {
-        j = parser(detail::input_adapter_factory::create(i)).parse(false);
-        return i;
+        // swap only works for strings
+        if (is_string())
+        {
+            std::swap(*(m_value.string), other);
+        }
+        else
+        {
+            JSON_THROW(type_error::create(310, "cannot use swap() with " + type_name()));
+        }
     }
 
     /// @}
 
-    ///////////////////////////
-    // convenience functions //
-    ///////////////////////////
+  public:
+    //////////////////////////////////////////
+    // lexicographical comparison operators //
+    //////////////////////////////////////////
+
+    /// @name lexicographical comparison operators
+    /// @{
 
     /*!
-    @brief return the type as string
+    @brief comparison: equal
 
-    Returns the type name as string to be used in error messages - usually to
-    indicate that a function was called on a wrong JSON type.
+    Compares two JSON values for equality according to the following rules:
+    - Two JSON values are equal if (1) they are from the same type and (2)
+      their stored values are the same according to their respective
+      `operator==`.
+    - Integer and floating-point numbers are automatically converted before
+      comparison. Note than two NaN values are always treated as unequal.
+    - Two JSON null values are equal.
 
-    @return basically a string representation of a the @a m_type member
+    @note NaN values never compare equal to themselves or to other NaN values.
 
-    @complexity Constant.
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether the values @a lhs and @a rhs are equal
 
-    @liveexample{The following code exemplifies `type_name()` for all JSON
-    types.,type_name}
+    @complexity Linear.
 
-    @since version 1.0.0, public since 2.1.0
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__equal}
+
+    @since version 1.0.0
     */
-    std::string type_name() const
+    friend bool operator==(const_reference lhs, const_reference rhs) noexcept
     {
+        const auto lhs_type = lhs.type();
+        const auto rhs_type = rhs.type();
+
+        if (lhs_type == rhs_type)
         {
-            switch (m_type)
+            switch (lhs_type)
             {
-                case value_t::null:
-                    return "null";
-                case value_t::object:
-                    return "object";
                 case value_t::array:
-                    return "array";
+                {
+                    return *lhs.m_value.array == *rhs.m_value.array;
+                }
+                case value_t::object:
+                {
+                    return *lhs.m_value.object == *rhs.m_value.object;
+                }
+                case value_t::null:
+                {
+                    return true;
+                }
                 case value_t::string:
-                    return "string";
+                {
+                    return *lhs.m_value.string == *rhs.m_value.string;
+                }
                 case value_t::boolean:
-                    return "boolean";
-                case value_t::discarded:
-                    return "discarded";
+                {
+                    return lhs.m_value.boolean == rhs.m_value.boolean;
+                }
+                case value_t::number_integer:
+                {
+                    return lhs.m_value.number_integer == rhs.m_value.number_integer;
+                }
+                case value_t::number_unsigned:
+                {
+                    return lhs.m_value.number_unsigned == rhs.m_value.number_unsigned;
+                }
+                case value_t::number_float:
+                {
+                    return lhs.m_value.number_float == rhs.m_value.number_float;
+                }
                 default:
-                    return "number";
+                {
+                    return false;
+                }
             }
         }
-    }
-
-
-  private:
-    //////////////////////
-    // member variables //
-    //////////////////////
-
-    /// the type of the current element
-    value_t m_type = value_t::null;
-
-    /// the value of the current element
-    json_value m_value = {};
-
-
-  private:
-    ///////////////
-    // iterators //
-    ///////////////
-
-    /*!
-    @brief an iterator for primitive JSON types
-
-    This class models an iterator for primitive JSON types (boolean, number,
-    string). It's only purpose is to allow the iterator/const_iterator classes
-    to "iterate" over primitive values. Internally, the iterator is modeled by
-    a `difference_type` variable. Value begin_value (`0`) models the begin,
-    end_value (`1`) models past the end.
-    */
-    class primitive_iterator_t
-    {
-      public:
-
-        difference_type get_value() const noexcept
+        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_float)
         {
-            return m_it;
+            return static_cast<number_float_t>(lhs.m_value.number_integer) == rhs.m_value.number_float;
         }
-        /// set iterator to a defined beginning
-        void set_begin() noexcept
+        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_integer)
         {
-            m_it = begin_value;
+            return lhs.m_value.number_float == static_cast<number_float_t>(rhs.m_value.number_integer);
         }
-
-        /// set iterator to a defined past the end
-        void set_end() noexcept
+        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_float)
         {
-            m_it = end_value;
+            return static_cast<number_float_t>(lhs.m_value.number_unsigned) == rhs.m_value.number_float;
         }
-
-        /// return whether the iterator can be dereferenced
-        constexpr bool is_begin() const noexcept
+        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_unsigned)
         {
-            return (m_it == begin_value);
+            return lhs.m_value.number_float == static_cast<number_float_t>(rhs.m_value.number_unsigned);
         }
-
-        /// return whether the iterator is at end
-        constexpr bool is_end() const noexcept
+        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_integer)
         {
-            return (m_it == end_value);
+            return static_cast<number_integer_t>(lhs.m_value.number_unsigned) == rhs.m_value.number_integer;
         }
-
-        friend constexpr bool operator==(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
+        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_unsigned)
         {
-            return lhs.m_it == rhs.m_it;
+            return lhs.m_value.number_integer == static_cast<number_integer_t>(rhs.m_value.number_unsigned);
         }
 
-        friend constexpr bool operator!=(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
-        {
-            return !(lhs == rhs);
-        }
+        return false;
+    }
 
-        friend constexpr bool operator<(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
-        {
-            return lhs.m_it < rhs.m_it;
-        }
+    /*!
+    @brief comparison: equal
+    @copydoc operator==(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator==(const_reference lhs, const ScalarType rhs) noexcept
+    {
+        return (lhs == basic_json(rhs));
+    }
 
-        friend constexpr bool operator<=(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
-        {
-            return lhs.m_it <= rhs.m_it;
-        }
+    /*!
+    @brief comparison: equal
+    @copydoc operator==(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator==(const ScalarType lhs, const_reference rhs) noexcept
+    {
+        return (basic_json(lhs) == rhs);
+    }
 
-        friend constexpr bool operator>(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
-        {
-            return lhs.m_it > rhs.m_it;
-        }
+    /*!
+    @brief comparison: not equal
 
-        friend constexpr bool operator>=(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
-        {
-            return lhs.m_it >= rhs.m_it;
-        }
+    Compares two JSON values for inequality by calculating `not (lhs == rhs)`.
 
-        primitive_iterator_t operator+(difference_type i)
-        {
-            auto result = *this;
-            result += i;
-            return result;
-        }
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether the values @a lhs and @a rhs are not equal
 
-        friend constexpr difference_type operator-(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
-        {
-            return lhs.m_it - rhs.m_it;
-        }
+    @complexity Linear.
 
-        friend std::ostream& operator<<(std::ostream& os, primitive_iterator_t it)
-        {
-            return os << it.m_it;
-        }
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__notequal}
 
-        primitive_iterator_t& operator++()
-        {
-            ++m_it;
-            return *this;
-        }
+    @since version 1.0.0
+    */
+    friend bool operator!=(const_reference lhs, const_reference rhs) noexcept
+    {
+        return not (lhs == rhs);
+    }
 
-        primitive_iterator_t operator++(int)
-        {
-            auto result = *this;
-            m_it++;
-            return result;
-        }
+    /*!
+    @brief comparison: not equal
+    @copydoc operator!=(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator!=(const_reference lhs, const ScalarType rhs) noexcept
+    {
+        return (lhs != basic_json(rhs));
+    }
 
-        primitive_iterator_t& operator--()
-        {
-            --m_it;
-            return *this;
-        }
+    /*!
+    @brief comparison: not equal
+    @copydoc operator!=(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator!=(const ScalarType lhs, const_reference rhs) noexcept
+    {
+        return (basic_json(lhs) != rhs);
+    }
 
-        primitive_iterator_t operator--(int)
+    /*!
+    @brief comparison: less than
+
+    Compares whether one JSON value @a lhs is less than another JSON value @a
+    rhs according to the following rules:
+    - If @a lhs and @a rhs have the same type, the values are compared using
+      the default `<` operator.
+    - Integer and floating-point numbers are automatically converted before
+      comparison
+    - In case @a lhs and @a rhs have different types, the values are ignored
+      and the order of the types is considered, see
+      @ref operator<(const value_t, const value_t).
+
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether @a lhs is less than @a rhs
+
+    @complexity Linear.
+
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__less}
+
+    @since version 1.0.0
+    */
+    friend bool operator<(const_reference lhs, const_reference rhs) noexcept
+    {
+        const auto lhs_type = lhs.type();
+        const auto rhs_type = rhs.type();
+
+        if (lhs_type == rhs_type)
         {
-            auto result = *this;
-            m_it--;
-            return result;
+            switch (lhs_type)
+            {
+                case value_t::array:
+                {
+                    return (*lhs.m_value.array) < (*rhs.m_value.array);
+                }
+                case value_t::object:
+                {
+                    return *lhs.m_value.object < *rhs.m_value.object;
+                }
+                case value_t::null:
+                {
+                    return false;
+                }
+                case value_t::string:
+                {
+                    return *lhs.m_value.string < *rhs.m_value.string;
+                }
+                case value_t::boolean:
+                {
+                    return lhs.m_value.boolean < rhs.m_value.boolean;
+                }
+                case value_t::number_integer:
+                {
+                    return lhs.m_value.number_integer < rhs.m_value.number_integer;
+                }
+                case value_t::number_unsigned:
+                {
+                    return lhs.m_value.number_unsigned < rhs.m_value.number_unsigned;
+                }
+                case value_t::number_float:
+                {
+                    return lhs.m_value.number_float < rhs.m_value.number_float;
+                }
+                default:
+                {
+                    return false;
+                }
+            }
         }
-
-        primitive_iterator_t& operator+=(difference_type n)
+        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_float)
         {
-            m_it += n;
-            return *this;
+            return static_cast<number_float_t>(lhs.m_value.number_integer) < rhs.m_value.number_float;
         }
-
-        primitive_iterator_t& operator-=(difference_type n)
+        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_integer)
         {
-            m_it -= n;
-            return *this;
+            return lhs.m_value.number_float < static_cast<number_float_t>(rhs.m_value.number_integer);
+        }
+        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_float)
+        {
+            return static_cast<number_float_t>(lhs.m_value.number_unsigned) < rhs.m_value.number_float;
+        }
+        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_unsigned)
+        {
+            return lhs.m_value.number_float < static_cast<number_float_t>(rhs.m_value.number_unsigned);
+        }
+        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_unsigned)
+        {
+            return lhs.m_value.number_integer < static_cast<number_integer_t>(rhs.m_value.number_unsigned);
+        }
+        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_integer)
+        {
+            return static_cast<number_integer_t>(lhs.m_value.number_unsigned) < rhs.m_value.number_integer;
         }
 
-      private:
-        static constexpr difference_type begin_value = 0;
-        static constexpr difference_type end_value = begin_value + 1;
-
-        /// iterator as signed integer type
-        difference_type m_it = std::numeric_limits<std::ptrdiff_t>::denorm_min();
-    };
+        // We only reach this line if we cannot compare values. In that case,
+        // we compare types. Note we have to call the operator explicitly,
+        // because MSVC has problems otherwise.
+        return operator<(lhs_type, rhs_type);
+    }
 
     /*!
-    @brief an iterator value
+    @brief comparison: less than
+    @copydoc operator<(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator<(const_reference lhs, const ScalarType rhs) noexcept
+    {
+        return (lhs < basic_json(rhs));
+    }
 
-    @note This structure could easily be a union, but MSVC currently does not
-    allow unions members with complex constructors, see
-    https://github.com/nlohmann/json/pull/105.
+    /*!
+    @brief comparison: less than
+    @copydoc operator<(const_reference, const_reference)
     */
-    struct internal_iterator
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator<(const ScalarType lhs, const_reference rhs) noexcept
     {
-        /// iterator for JSON objects
-        typename object_t::iterator object_iterator;
-        /// iterator for JSON arrays
-        typename array_t::iterator array_iterator;
-        /// generic iterator for all other types
-        primitive_iterator_t primitive_iterator;
+        return (basic_json(lhs) < rhs);
+    }
 
-        /// create an uninitialized internal_iterator
-        internal_iterator() noexcept
-            : object_iterator(), array_iterator(), primitive_iterator()
-        {}
-    };
+    /*!
+    @brief comparison: less than or equal
 
-    /// proxy class for the iterator_wrapper functions
-    template<typename IteratorType>
-    class iteration_proxy
-    {
-      private:
-        /// helper class for iteration
-        class iteration_proxy_internal
-        {
-          private:
-            /// the iterator
-            IteratorType anchor;
-            /// an index for arrays (used to create key names)
-            size_t array_index = 0;
+    Compares whether one JSON value @a lhs is less than or equal to another
+    JSON value by calculating `not (rhs < lhs)`.
 
-          public:
-            explicit iteration_proxy_internal(IteratorType it) noexcept
-                : anchor(it)
-            {}
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether @a lhs is less than or equal to @a rhs
 
-            /// dereference operator (needed for range-based for)
-            iteration_proxy_internal& operator*()
-            {
-                return *this;
-            }
+    @complexity Linear.
 
-            /// increment operator (needed for range-based for)
-            iteration_proxy_internal& operator++()
-            {
-                ++anchor;
-                ++array_index;
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__greater}
 
-                return *this;
-            }
+    @since version 1.0.0
+    */
+    friend bool operator<=(const_reference lhs, const_reference rhs) noexcept
+    {
+        return not (rhs < lhs);
+    }
 
-            /// inequality operator (needed for range-based for)
-            bool operator!= (const iteration_proxy_internal& o) const
-            {
-                return anchor != o.anchor;
-            }
+    /*!
+    @brief comparison: less than or equal
+    @copydoc operator<=(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator<=(const_reference lhs, const ScalarType rhs) noexcept
+    {
+        return (lhs <= basic_json(rhs));
+    }
 
-            /// return key of the iterator
-            typename basic_json::string_t key() const
-            {
-                assert(anchor.m_object != nullptr);
+    /*!
+    @brief comparison: less than or equal
+    @copydoc operator<=(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator<=(const ScalarType lhs, const_reference rhs) noexcept
+    {
+        return (basic_json(lhs) <= rhs);
+    }
 
-                switch (anchor.m_object->type())
-                {
-                    // use integer array index as key
-                    case value_t::array:
-                    {
-                        return std::to_string(array_index);
-                    }
+    /*!
+    @brief comparison: greater than
 
-                    // use key from the object
-                    case value_t::object:
-                    {
-                        return anchor.key();
-                    }
+    Compares whether one JSON value @a lhs is greater than another
+    JSON value by calculating `not (lhs <= rhs)`.
 
-                    // use an empty key for all primitive types
-                    default:
-                    {
-                        return "";
-                    }
-                }
-            }
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether @a lhs is greater than to @a rhs
 
-            /// return value of the iterator
-            typename IteratorType::reference value() const
-            {
-                return anchor.value();
-            }
-        };
+    @complexity Linear.
 
-        /// the container to iterate
-        typename IteratorType::reference container;
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__lessequal}
 
-      public:
-        /// construct iteration proxy from a container
-        explicit iteration_proxy(typename IteratorType::reference cont)
-            : container(cont)
-        {}
+    @since version 1.0.0
+    */
+    friend bool operator>(const_reference lhs, const_reference rhs) noexcept
+    {
+        return not (lhs <= rhs);
+    }
 
-        /// return iterator begin (needed for range-based for)
-        iteration_proxy_internal begin() noexcept
-        {
-            return iteration_proxy_internal(container.begin());
-        }
+    /*!
+    @brief comparison: greater than
+    @copydoc operator>(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator>(const_reference lhs, const ScalarType rhs) noexcept
+    {
+        return (lhs > basic_json(rhs));
+    }
 
-        /// return iterator end (needed for range-based for)
-        iteration_proxy_internal end() noexcept
-        {
-            return iteration_proxy_internal(container.end());
-        }
-    };
+    /*!
+    @brief comparison: greater than
+    @copydoc operator>(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator>(const ScalarType lhs, const_reference rhs) noexcept
+    {
+        return (basic_json(lhs) > rhs);
+    }
 
-  public:
     /*!
-    @brief a template for a random access iterator for the @ref basic_json class
+    @brief comparison: greater than or equal
 
-    This class implements a both iterators (iterator and const_iterator) for the
-    @ref basic_json class.
+    Compares whether one JSON value @a lhs is greater than or equal to another
+    JSON value by calculating `not (lhs < rhs)`.
 
-    @note An iterator is called *initialized* when a pointer to a JSON value
-          has been set (e.g., by a constructor or a copy assignment). If the
-          iterator is default-constructed, it is *uninitialized* and most
-          methods are undefined. **The library uses assertions to detect calls
-          on uninitialized iterators.**
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether @a lhs is greater than or equal to @a rhs
 
-    @requirement The class satisfies the following concept requirements:
-    - [RandomAccessIterator](http://en.cppreference.com/w/cpp/concept/RandomAccessIterator):
-      The iterator that can be moved to point (forward and backward) to any
-      element in constant time.
+    @complexity Linear.
 
-    @since version 1.0.0, simplified in version 2.0.9
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__greaterequal}
+
+    @since version 1.0.0
     */
-    template<typename U>
-    class iter_impl : public std::iterator<std::random_access_iterator_tag, U>
+    friend bool operator>=(const_reference lhs, const_reference rhs) noexcept
     {
-        /// allow basic_json to access private members
-        friend class basic_json;
+        return not (lhs < rhs);
+    }
 
-        // make sure U is basic_json or const basic_json
-        static_assert(std::is_same<U, basic_json>::value
-                      or std::is_same<U, const basic_json>::value,
-                      "iter_impl only accepts (const) basic_json");
+    /*!
+    @brief comparison: greater than or equal
+    @copydoc operator>=(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator>=(const_reference lhs, const ScalarType rhs) noexcept
+    {
+        return (lhs >= basic_json(rhs));
+    }
 
-      public:
-        /// the type of the values when the iterator is dereferenced
-        using value_type = typename basic_json::value_type;
-        /// a type to represent differences between iterators
-        using difference_type = typename basic_json::difference_type;
-        /// defines a pointer to the type iterated over (value_type)
-        using pointer = typename std::conditional<std::is_const<U>::value,
-              typename basic_json::const_pointer,
-              typename basic_json::pointer>::type;
-        /// defines a reference to the type iterated over (value_type)
-        using reference = typename std::conditional<std::is_const<U>::value,
-              typename basic_json::const_reference,
-              typename basic_json::reference>::type;
-        /// the category of the iterator
-        using iterator_category = std::bidirectional_iterator_tag;
+    /*!
+    @brief comparison: greater than or equal
+    @copydoc operator>=(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator>=(const ScalarType lhs, const_reference rhs) noexcept
+    {
+        return (basic_json(lhs) >= rhs);
+    }
 
-        /// default constructor
-        iter_impl() = default;
+    /// @}
 
-        /*!
-        @brief constructor for a given JSON instance
-        @param[in] object  pointer to a JSON object for this iterator
-        @pre object != nullptr
-        @post The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        explicit iter_impl(pointer object) noexcept
-            : m_object(object)
-        {
-            assert(m_object != nullptr);
+  private:
+    /////////////////////
+    // output adapters //
+    /////////////////////
 
-            switch (m_object->m_type)
-            {
-                case basic_json::value_t::object:
-                {
-                    m_it.object_iterator = typename object_t::iterator();
-                    break;
-                }
+    /// abstract output adapter interface
+    template<typename CharType>
+    class output_adapter
+    {
+      public:
+        virtual void write_character(CharType c) = 0;
+        virtual void write_characters(const CharType* s, size_t length) = 0;
+        virtual ~output_adapter() {}
 
-                case basic_json::value_t::array:
-                {
-                    m_it.array_iterator = typename array_t::iterator();
-                    break;
-                }
+        static std::shared_ptr<output_adapter<CharType>> create(std::vector<CharType>& vec)
+        {
+            return std::make_shared<output_vector_adapter<CharType>>(vec);
+        }
 
-                default:
-                {
-                    m_it.primitive_iterator = primitive_iterator_t();
-                    break;
-                }
-            }
+        static std::shared_ptr<output_adapter<CharType>> create(std::ostream& s)
+        {
+            return std::make_shared<output_stream_adapter<CharType>>(s);
         }
 
-        /*!
-        @note The conventional copy constructor and copy assignment are
-              implicitly defined.
-              Combined with the following converting constructor and assignment,
-              they support: copy from iterator to iterator,
-                            copy from const iterator to const iterator,
-                            and conversion from iterator to const iterator.
-              However conversion from const iterator to iterator is not defined.
-        */
+        static std::shared_ptr<output_adapter<CharType>> create(std::string& s)
+        {
+            return std::make_shared<output_string_adapter<CharType>>(s);
+        }
+    };
 
-        /*!
-        @brief converting constructor
-        @param[in] other  non-const iterator to copy from
-        @note It is not checked whether @a other is initialized.
-        */
-        iter_impl(const iter_impl<basic_json>& other) noexcept
-            : m_object(other.m_object), m_it(other.m_it)
+    /// a type to simplify interfaces
+    template<typename CharType>
+    using output_adapter_t = std::shared_ptr<output_adapter<CharType>>;
+
+    /// output adapter for byte vectors
+    template<typename CharType>
+    class output_vector_adapter : public output_adapter<CharType>
+    {
+      public:
+        output_vector_adapter(std::vector<CharType>& vec)
+            : v(vec)
         {}
 
-        /*!
-        @brief converting assignment
-        @param[in,out] other  non-const iterator to copy from
-        @return const/non-const iterator
-        @note It is not checked whether @a other is initialized.
-        */
-        iter_impl& operator=(const iter_impl<basic_json>& other) noexcept
+        void write_character(CharType c) override
         {
-            m_object = other.m_object;
-            m_it = other.m_it;
-            return *this;
+            v.push_back(c);
         }
 
-      private:
-        /*!
-        @brief set the iterator to the first value
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        void set_begin() noexcept
+        void write_characters(const CharType* s, size_t length) override
         {
-            assert(m_object != nullptr);
-
-            switch (m_object->m_type)
-            {
-                case basic_json::value_t::object:
-                {
-                    m_it.object_iterator = m_object->m_value.object->begin();
-                    break;
-                }
+            std::copy(s, s + length, std::back_inserter(v));
+        }
 
-                case basic_json::value_t::array:
-                {
-                    m_it.array_iterator = m_object->m_value.array->begin();
-                    break;
-                }
+      private:
+        std::vector<CharType>& v;
+    };
 
-                case basic_json::value_t::null:
-                {
-                    // set to end so begin()==end() is true: null is empty
-                    m_it.primitive_iterator.set_end();
-                    break;
-                }
+    /// output adapter for output streams
+    template<typename CharType>
+    class output_stream_adapter : public output_adapter<CharType>
+    {
+      public:
+        output_stream_adapter(std::basic_ostream<CharType>& s)
+            : stream(s)
+        {}
 
-                default:
-                {
-                    m_it.primitive_iterator.set_begin();
-                    break;
-                }
-            }
+        void write_character(CharType c) override
+        {
+            stream.put(c);
         }
 
-        /*!
-        @brief set the iterator past the last value
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        void set_end() noexcept
+        void write_characters(const CharType* s, size_t length) override
         {
-            assert(m_object != nullptr);
+            stream.write(s, static_cast<std::streamsize>(length));
+        }
 
-            switch (m_object->m_type)
-            {
-                case basic_json::value_t::object:
-                {
-                    m_it.object_iterator = m_object->m_value.object->end();
-                    break;
-                }
+      private:
+        std::basic_ostream<CharType>& stream;
+    };
 
-                case basic_json::value_t::array:
-                {
-                    m_it.array_iterator = m_object->m_value.array->end();
-                    break;
-                }
+    /// output adapter for basic_string
+    template<typename CharType>
+    class output_string_adapter : public output_adapter<CharType>
+    {
+      public:
+        output_string_adapter(std::string& s)
+            : str(s)
+        {}
 
-                default:
-                {
-                    m_it.primitive_iterator.set_end();
-                    break;
-                }
-            }
+        void write_character(CharType c) override
+        {
+            str.push_back(c);
+        }
+
+        void write_characters(const CharType* s, size_t length) override
+        {
+            str.append(s, length);
         }
 
+      private:
+        std::basic_string<CharType>& str;
+    };
+
+
+    ///////////////////
+    // serialization //
+    ///////////////////
+
+    /// @name serialization
+    /// @{
+
+  private:
+    /*!
+    @brief wrapper around the serialization functions
+    */
+    class serializer
+    {
       public:
         /*!
-        @brief return a reference to the value pointed to by the iterator
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        @param[in] s  output stream to serialize to
+        @param[in] ichar  indentation character to use
         */
-        reference operator*() const
-        {
-            assert(m_object != nullptr);
+        serializer(output_adapter_t<char> s, const char ichar)
+            : o(s), loc(std::localeconv()),
+              thousands_sep(!loc->thousands_sep ? '\0' : loc->thousands_sep[0]),
+              decimal_point(!loc->decimal_point ? '\0' : loc->decimal_point[0]),
+              indent_char(ichar), indent_string(512, indent_char)
+        {}
 
-            switch (m_object->m_type)
-            {
-                case basic_json::value_t::object:
-                {
-                    assert(m_it.object_iterator != m_object->m_value.object->end());
-                    return m_it.object_iterator->second;
-                }
+        // delete because of pointer members
+        serializer(const serializer&) = delete;
+        serializer& operator=(const serializer&) = delete;
 
-                case basic_json::value_t::array:
-                {
-                    assert(m_it.array_iterator != m_object->m_value.array->end());
-                    return *m_it.array_iterator;
-                }
+        /*!
+        @brief internal implementation of the serialization function
 
-                case basic_json::value_t::null:
-                {
-                    JSON_THROW(invalid_iterator::create(214, "cannot get value"));
-                }
+        This function is called by the public member function dump and
+        organizes the serialization internally. The indentation level is
+        propagated as additional parameter. In case of arrays and objects, the
+        function is called recursively.
 
-                default:
+        - strings and object keys are escaped using `escape_string()`
+        - integer numbers are converted implicitly via `operator<<`
+        - floating-point numbers are converted to a string using `"%g"` format
+
+        @param[in] val             value to serialize
+        @param[in] pretty_print    whether the output shall be pretty-printed
+        @param[in] indent_step     the indent level
+        @param[in] current_indent  the current indent level (only used internally)
+        */
+        void dump(const basic_json& val,
+                  const bool pretty_print,
+                  const unsigned int indent_step,
+                  const unsigned int current_indent = 0)
+        {
+            switch (val.m_type)
+            {
+                case value_t::object:
                 {
-                    if (m_it.primitive_iterator.is_begin())
+                    if (val.m_value.object->empty())
                     {
-                        return *m_object;
+                        o->write_characters("{}", 2);
+                        return;
                     }
 
-                    JSON_THROW(invalid_iterator::create(214, "cannot get value"));
-                }
-            }
-        }
+                    if (pretty_print)
+                    {
+                        o->write_characters("{\n", 2);
 
-        /*!
-        @brief dereference the iterator
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        pointer operator->() const
-        {
-            assert(m_object != nullptr);
+                        // variable to hold indentation for recursive calls
+                        const auto new_indent = current_indent + indent_step;
+                        if (JSON_UNLIKELY(indent_string.size() < new_indent))
+                        {
+                            indent_string.resize(indent_string.size() * 2, ' ');
+                        }
 
-            switch (m_object->m_type)
-            {
-                case basic_json::value_t::object:
-                {
-                    assert(m_it.object_iterator != m_object->m_value.object->end());
-                    return &(m_it.object_iterator->second);
-                }
+                        // first n-1 elements
+                        auto i = val.m_value.object->cbegin();
+                        for (size_t cnt = 0; cnt < val.m_value.object->size() - 1; ++cnt, ++i)
+                        {
+                            o->write_characters(indent_string.c_str(), new_indent);
+                            o->write_character('\"');
+                            dump_escaped(i->first);
+                            o->write_characters("\": ", 3);
+                            dump(i->second, true, indent_step, new_indent);
+                            o->write_characters(",\n", 2);
+                        }
 
-                case basic_json::value_t::array:
-                {
-                    assert(m_it.array_iterator != m_object->m_value.array->end());
-                    return &*m_it.array_iterator;
-                }
+                        // last element
+                        assert(i != val.m_value.object->cend());
+                        o->write_characters(indent_string.c_str(), new_indent);
+                        o->write_character('\"');
+                        dump_escaped(i->first);
+                        o->write_characters("\": ", 3);
+                        dump(i->second, true, indent_step, new_indent);
 
-                default:
-                {
-                    if (m_it.primitive_iterator.is_begin())
-                    {
-                        return m_object;
+                        o->write_character('\n');
+                        o->write_characters(indent_string.c_str(), current_indent);
+                        o->write_character('}');
                     }
+                    else
+                    {
+                        o->write_character('{');
 
-                    JSON_THROW(invalid_iterator::create(214, "cannot get value"));
-                }
-            }
-        }
-
-        /*!
-        @brief post-increment (it++)
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        iter_impl operator++(int)
-        {
-            auto result = *this;
-            ++(*this);
-            return result;
-        }
+                        // first n-1 elements
+                        auto i = val.m_value.object->cbegin();
+                        for (size_t cnt = 0; cnt < val.m_value.object->size() - 1; ++cnt, ++i)
+                        {
+                            o->write_character('\"');
+                            dump_escaped(i->first);
+                            o->write_characters("\":", 2);
+                            dump(i->second, false, indent_step, current_indent);
+                            o->write_character(',');
+                        }
 
-        /*!
-        @brief pre-increment (++it)
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        iter_impl& operator++()
-        {
-            assert(m_object != nullptr);
+                        // last element
+                        assert(i != val.m_value.object->cend());
+                        o->write_character('\"');
+                        dump_escaped(i->first);
+                        o->write_characters("\":", 2);
+                        dump(i->second, false, indent_step, current_indent);
 
-            switch (m_object->m_type)
-            {
-                case basic_json::value_t::object:
-                {
-                    std::advance(m_it.object_iterator, 1);
-                    break;
-                }
+                        o->write_character('}');
+                    }
 
-                case basic_json::value_t::array:
-                {
-                    std::advance(m_it.array_iterator, 1);
-                    break;
+                    return;
                 }
 
-                default:
+                case value_t::array:
                 {
-                    ++m_it.primitive_iterator;
-                    break;
-                }
-            }
+                    if (val.m_value.array->empty())
+                    {
+                        o->write_characters("[]", 2);
+                        return;
+                    }
 
-            return *this;
-        }
+                    if (pretty_print)
+                    {
+                        o->write_characters("[\n", 2);
 
-        /*!
-        @brief post-decrement (it--)
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        iter_impl operator--(int)
-        {
-            auto result = *this;
-            --(*this);
-            return result;
-        }
+                        // variable to hold indentation for recursive calls
+                        const auto new_indent = current_indent + indent_step;
+                        if (indent_string.size() < new_indent)
+                        {
+                            indent_string.resize(new_indent, ' ');
+                        }
 
-        /*!
-        @brief pre-decrement (--it)
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        iter_impl& operator--()
-        {
-            assert(m_object != nullptr);
+                        // first n-1 elements
+                        for (auto i = val.m_value.array->cbegin(); i != val.m_value.array->cend() - 1; ++i)
+                        {
+                            o->write_characters(indent_string.c_str(), new_indent);
+                            dump(*i, true, indent_step, new_indent);
+                            o->write_characters(",\n", 2);
+                        }
 
-            switch (m_object->m_type)
-            {
-                case basic_json::value_t::object:
-                {
-                    std::advance(m_it.object_iterator, -1);
-                    break;
+                        // last element
+                        assert(not val.m_value.array->empty());
+                        o->write_characters(indent_string.c_str(), new_indent);
+                        dump(val.m_value.array->back(), true, indent_step, new_indent);
+
+                        o->write_character('\n');
+                        o->write_characters(indent_string.c_str(), current_indent);
+                        o->write_character(']');
+                    }
+                    else
+                    {
+                        o->write_character('[');
+
+                        // first n-1 elements
+                        for (auto i = val.m_value.array->cbegin(); i != val.m_value.array->cend() - 1; ++i)
+                        {
+                            dump(*i, false, indent_step, current_indent);
+                            o->write_character(',');
+                        }
+
+                        // last element
+                        assert(not val.m_value.array->empty());
+                        dump(val.m_value.array->back(), false, indent_step, current_indent);
+
+                        o->write_character(']');
+                    }
+
+                    return;
                 }
 
-                case basic_json::value_t::array:
+                case value_t::string:
                 {
-                    std::advance(m_it.array_iterator, -1);
-                    break;
+                    o->write_character('\"');
+                    dump_escaped(*val.m_value.string);
+                    o->write_character('\"');
+                    return;
                 }
 
-                default:
+                case value_t::boolean:
                 {
-                    --m_it.primitive_iterator;
-                    break;
+                    if (val.m_value.boolean)
+                    {
+                        o->write_characters("true", 4);
+                    }
+                    else
+                    {
+                        o->write_characters("false", 5);
+                    }
+                    return;
                 }
-            }
 
-            return *this;
-        }
-
-        /*!
-        @brief  comparison: equal
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        bool operator==(const iter_impl& other) const
-        {
-            // if objects are not the same, the comparison is undefined
-            if (m_object != other.m_object)
-            {
-                JSON_THROW(invalid_iterator::create(212, "cannot compare iterators of different containers"));
-            }
+                case value_t::number_integer:
+                {
+                    dump_integer(val.m_value.number_integer);
+                    return;
+                }
 
-            assert(m_object != nullptr);
+                case value_t::number_unsigned:
+                {
+                    dump_integer(val.m_value.number_unsigned);
+                    return;
+                }
 
-            switch (m_object->m_type)
-            {
-                case basic_json::value_t::object:
+                case value_t::number_float:
                 {
-                    return (m_it.object_iterator == other.m_it.object_iterator);
+                    dump_float(val.m_value.number_float);
+                    return;
                 }
 
-                case basic_json::value_t::array:
+                case value_t::discarded:
                 {
-                    return (m_it.array_iterator == other.m_it.array_iterator);
+                    o->write_characters("<discarded>", 11);
+                    return;
                 }
 
-                default:
+                case value_t::null:
                 {
-                    return (m_it.primitive_iterator == other.m_it.primitive_iterator);
+                    o->write_characters("null", 4);
+                    return;
                 }
             }
         }
 
+      private:
         /*!
-        @brief  comparison: not equal
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        bool operator!=(const iter_impl& other) const
-        {
-            return not operator==(other);
-        }
+        @brief calculates the extra space to escape a JSON string
 
-        /*!
-        @brief  comparison: smaller
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        @param[in] s  the string to escape
+        @return the number of characters required to escape string @a s
+
+        @complexity Linear in the length of string @a s.
         */
-        bool operator<(const iter_impl& other) const
+        static std::size_t extra_space(const string_t& s) noexcept
         {
-            // if objects are not the same, the comparison is undefined
-            if (m_object != other.m_object)
-            {
-                JSON_THROW(invalid_iterator::create(212, "cannot compare iterators of different containers"));
-            }
-
-            assert(m_object != nullptr);
-
-            switch (m_object->m_type)
+            return std::accumulate(s.begin(), s.end(), size_t{},
+                                   [](size_t res, typename string_t::value_type c)
             {
-                case basic_json::value_t::object:
+                switch (c)
                 {
-                    JSON_THROW(invalid_iterator::create(213, "cannot compare order of object iterators"));
-                }
+                    case '"':
+                    case '\\':
+                    case '\b':
+                    case '\f':
+                    case '\n':
+                    case '\r':
+                    case '\t':
+                    {
+                        // from c (1 byte) to \x (2 bytes)
+                        return res + 1;
+                    }
 
-                case basic_json::value_t::array:
-                {
-                    return (m_it.array_iterator < other.m_it.array_iterator);
-                }
+                    case 0x00:
+                    case 0x01:
+                    case 0x02:
+                    case 0x03:
+                    case 0x04:
+                    case 0x05:
+                    case 0x06:
+                    case 0x07:
+                    case 0x0b:
+                    case 0x0e:
+                    case 0x0f:
+                    case 0x10:
+                    case 0x11:
+                    case 0x12:
+                    case 0x13:
+                    case 0x14:
+                    case 0x15:
+                    case 0x16:
+                    case 0x17:
+                    case 0x18:
+                    case 0x19:
+                    case 0x1a:
+                    case 0x1b:
+                    case 0x1c:
+                    case 0x1d:
+                    case 0x1e:
+                    case 0x1f:
+                    {
+                        // from c (1 byte) to \uxxxx (6 bytes)
+                        return res + 5;
+                    }
 
-                default:
-                {
-                    return (m_it.primitive_iterator < other.m_it.primitive_iterator);
+                    default:
+                    {
+                        return res;
+                    }
                 }
-            }
+            });
         }
 
         /*!
-        @brief  comparison: less than or equal
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        bool operator<=(const iter_impl& other) const
-        {
-            return not other.operator < (*this);
-        }
+        @brief dump escaped string
 
-        /*!
-        @brief  comparison: greater than
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        bool operator>(const iter_impl& other) const
-        {
-            return not operator<=(other);
-        }
+        Escape a string by replacing certain special characters by a sequence
+        of an escape character (backslash) and another character and other
+        control characters by a sequence of "\u" followed by a four-digit hex
+        representation. The escaped string is written to output stream @a o.
 
-        /*!
-        @brief  comparison: greater than or equal
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        bool operator>=(const iter_impl& other) const
-        {
-            return not operator<(other);
-        }
+        @param[in] s  the string to escape
 
-        /*!
-        @brief  add to iterator
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        @complexity Linear in the length of string @a s.
         */
-        iter_impl& operator+=(difference_type i)
+        void dump_escaped(const string_t& s) const
         {
-            assert(m_object != nullptr);
-
-            switch (m_object->m_type)
+            const auto space = extra_space(s);
+            if (space == 0)
             {
-                case basic_json::value_t::object:
-                {
-                    JSON_THROW(invalid_iterator::create(209, "cannot use offsets with object iterators"));
-                }
+                o->write_characters(s.c_str(), s.size());
+                return;
+            }
 
-                case basic_json::value_t::array:
-                {
-                    std::advance(m_it.array_iterator, i);
-                    break;
-                }
+            // create a result string of necessary size
+            string_t result(s.size() + space, '\\');
+            std::size_t pos = 0;
 
-                default:
+            for (const auto& c : s)
+            {
+                switch (c)
                 {
-                    m_it.primitive_iterator += i;
-                    break;
-                }
-            }
+                    // quotation mark (0x22)
+                    case '"':
+                    {
+                        result[pos + 1] = '"';
+                        pos += 2;
+                        break;
+                    }
 
-            return *this;
-        }
+                    // reverse solidus (0x5c)
+                    case '\\':
+                    {
+                        // nothing to change
+                        pos += 2;
+                        break;
+                    }
 
-        /*!
-        @brief  subtract from iterator
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        iter_impl& operator-=(difference_type i)
-        {
-            return operator+=(-i);
-        }
+                    // backspace (0x08)
+                    case '\b':
+                    {
+                        result[pos + 1] = 'b';
+                        pos += 2;
+                        break;
+                    }
 
-        /*!
-        @brief  add to iterator
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        iter_impl operator+(difference_type i) const
-        {
-            auto result = *this;
-            result += i;
-            return result;
-        }
+                    // formfeed (0x0c)
+                    case '\f':
+                    {
+                        result[pos + 1] = 'f';
+                        pos += 2;
+                        break;
+                    }
 
-        /*!
-        @brief  addition of distance and iterator
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        friend iter_impl operator+(difference_type i, const iter_impl& it)
-        {
-            auto result = it;
-            result += i;
-            return result;
-        }
+                    // newline (0x0a)
+                    case '\n':
+                    {
+                        result[pos + 1] = 'n';
+                        pos += 2;
+                        break;
+                    }
 
-        /*!
-        @brief  subtract from iterator
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        iter_impl operator-(difference_type i) const
-        {
-            auto result = *this;
-            result -= i;
-            return result;
-        }
+                    // carriage return (0x0d)
+                    case '\r':
+                    {
+                        result[pos + 1] = 'r';
+                        pos += 2;
+                        break;
+                    }
 
-        /*!
-        @brief  return difference
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        difference_type operator-(const iter_impl& other) const
-        {
-            assert(m_object != nullptr);
+                    // horizontal tab (0x09)
+                    case '\t':
+                    {
+                        result[pos + 1] = 't';
+                        pos += 2;
+                        break;
+                    }
 
-            switch (m_object->m_type)
-            {
-                case basic_json::value_t::object:
-                {
-                    JSON_THROW(invalid_iterator::create(209, "cannot use offsets with object iterators"));
-                }
+                    case 0x00:
+                    case 0x01:
+                    case 0x02:
+                    case 0x03:
+                    case 0x04:
+                    case 0x05:
+                    case 0x06:
+                    case 0x07:
+                    case 0x0b:
+                    case 0x0e:
+                    case 0x0f:
+                    case 0x10:
+                    case 0x11:
+                    case 0x12:
+                    case 0x13:
+                    case 0x14:
+                    case 0x15:
+                    case 0x16:
+                    case 0x17:
+                    case 0x18:
+                    case 0x19:
+                    case 0x1a:
+                    case 0x1b:
+                    case 0x1c:
+                    case 0x1d:
+                    case 0x1e:
+                    case 0x1f:
+                    {
+                        // convert a number 0..15 to its hex representation
+                        // (0..f)
+                        static const char hexify[16] =
+                        {
+                            '0', '1', '2', '3', '4', '5', '6', '7',
+                            '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'
+                        };
 
-                case basic_json::value_t::array:
-                {
-                    return m_it.array_iterator - other.m_it.array_iterator;
-                }
+                        // print character c as \uxxxx
+                        for (const char m :
+                    { 'u', '0', '0', hexify[c >> 4], hexify[c & 0x0f]
+                        })
+                        {
+                            result[++pos] = m;
+                        }
 
-                default:
-                {
-                    return m_it.primitive_iterator - other.m_it.primitive_iterator;
+                        ++pos;
+                        break;
+                    }
+
+                    default:
+                    {
+                        // all other characters are added as-is
+                        result[pos++] = c;
+                        break;
+                    }
                 }
             }
+
+            assert(pos == s.size() + space);
+            o->write_characters(result.c_str(), result.size());
         }
 
         /*!
-        @brief  access to successor
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        @brief dump an integer
+
+        Dump a given integer to output stream @a o. Works internally with
+        @a number_buffer.
+
+        @param[in] x  integer number (signed or unsigned) to dump
+        @tparam NumberType either @a number_integer_t or @a number_unsigned_t
         */
-        reference operator[](difference_type n) const
+        template<typename NumberType, detail::enable_if_t <
+                     std::is_same<NumberType, number_unsigned_t>::value or
+                     std::is_same<NumberType, number_integer_t>::value, int> = 0>
+        void dump_integer(NumberType x)
         {
-            assert(m_object != nullptr);
-
-            switch (m_object->m_type)
+            // special case for "0"
+            if (x == 0)
             {
-                case basic_json::value_t::object:
-                {
-                    JSON_THROW(invalid_iterator::create(208, "cannot use operator[] for object iterators"));
-                }
-
-                case basic_json::value_t::array:
-                {
-                    return *std::next(m_it.array_iterator, n);
-                }
-
-                case basic_json::value_t::null:
-                {
-                    JSON_THROW(invalid_iterator::create(214, "cannot get value"));
-                }
+                o->write_character('0');
+                return;
+            }
 
-                default:
-                {
-                    if (m_it.primitive_iterator.get_value() == -n)
-                    {
-                        return *m_object;
-                    }
+            const bool is_negative = x < 0;
+            size_t i = 0;
 
-                    JSON_THROW(invalid_iterator::create(214, "cannot get value"));
-                }
+            // spare 1 byte for '\0'
+            while (x != 0 and i < number_buffer.size() - 1)
+            {
+                const auto digit = std::labs(static_cast<long>(x % 10));
+                number_buffer[i++] = static_cast<char>('0' + digit);
+                x /= 10;
             }
-        }
 
-        /*!
-        @brief  return the key of an object iterator
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        typename object_t::key_type key() const
-        {
-            assert(m_object != nullptr);
+            // make sure the number has been processed completely
+            assert(x == 0);
 
-            if (m_object->is_object())
+            if (is_negative)
             {
-                return m_it.object_iterator->first;
+                // make sure there is capacity for the '-'
+                assert(i < number_buffer.size() - 2);
+                number_buffer[i++] = '-';
             }
 
-            JSON_THROW(invalid_iterator::create(207, "cannot use key() for non-object iterators"));
+            std::reverse(number_buffer.begin(), number_buffer.begin() + i);
+            o->write_characters(number_buffer.data(), i);
         }
 
         /*!
-        @brief  return the value of an iterator
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        @brief dump a floating-point number
+
+        Dump a given floating-point number to output stream @a o. Works
+        internally with @a number_buffer.
+
+        @param[in] x  floating-point number to dump
         */
-        reference value() const
+        void dump_float(number_float_t x)
         {
-            return operator*();
-        }
+            // NaN / inf
+            if (not std::isfinite(x) or std::isnan(x))
+            {
+                o->write_characters("null", 4);
+                return;
+            }
 
-      private:
-        /// associated JSON instance
-        pointer m_object = nullptr;
-        /// the actual iterator of the associated instance
-        struct internal_iterator m_it = internal_iterator();
-    };
+            // special case for 0.0 and -0.0
+            if (x == 0)
+            {
+                if (std::signbit(x))
+                {
+                    o->write_characters("-0.0", 4);
+                }
+                else
+                {
+                    o->write_characters("0.0", 3);
+                }
+                return;
+            }
 
-    /*!
-    @brief a template for a reverse iterator class
+            // get number of digits for a text -> float -> text round-trip
+            static constexpr auto d = std::numeric_limits<number_float_t>::digits10;
 
-    @tparam Base the base iterator type to reverse. Valid types are @ref
-    iterator (to create @ref reverse_iterator) and @ref const_iterator (to
-    create @ref const_reverse_iterator).
+            // the actual conversion
+            std::ptrdiff_t len = snprintf(number_buffer.data(), number_buffer.size(),
+                                          "%.*g", d, x);
 
-    @requirement The class satisfies the following concept requirements:
-    - [RandomAccessIterator](http://en.cppreference.com/w/cpp/concept/RandomAccessIterator):
-      The iterator that can be moved to point (forward and backward) to any
-      element in constant time.
-    - [OutputIterator](http://en.cppreference.com/w/cpp/concept/OutputIterator):
-      It is possible to write to the pointed-to element (only if @a Base is
-      @ref iterator).
+            // negative value indicates an error
+            assert(len > 0);
+            // check if buffer was large enough
+            assert(static_cast<size_t>(len) < number_buffer.size());
 
-    @since version 1.0.0
-    */
-    template<typename Base>
-    class json_reverse_iterator : public std::reverse_iterator<Base>
-    {
-      public:
-        /// shortcut to the reverse iterator adaptor
-        using base_iterator = std::reverse_iterator<Base>;
-        /// the reference type for the pointed-to element
-        using reference = typename Base::reference;
+            // erase thousands separator
+            if (thousands_sep != '\0')
+            {
+                const auto end = std::remove(number_buffer.begin(),
+                                             number_buffer.begin() + len,
+                                             thousands_sep);
+                std::fill(end, number_buffer.end(), '\0');
+                assert((end - number_buffer.begin()) <= len);
+                len = (end - number_buffer.begin());
+            }
 
-        /// create reverse iterator from iterator
-        json_reverse_iterator(const typename base_iterator::iterator_type& it) noexcept
-            : base_iterator(it)
-        {}
+            // convert decimal point to '.'
+            if (decimal_point != '\0' and decimal_point != '.')
+            {
+                for (auto& c : number_buffer)
+                {
+                    if (c == decimal_point)
+                    {
+                        c = '.';
+                        break;
+                    }
+                }
+            }
 
-        /// create reverse iterator from base class
-        json_reverse_iterator(const base_iterator& it) noexcept
-            : base_iterator(it)
-        {}
+            o->write_characters(number_buffer.data(), static_cast<size_t>(len));
 
-        /// post-increment (it++)
-        json_reverse_iterator operator++(int)
-        {
-            return static_cast<json_reverse_iterator>(base_iterator::operator++(1));
-        }
+            // determine if need to append ".0"
+            const bool value_is_int_like = std::none_of(number_buffer.begin(),
+                                           number_buffer.begin() + len + 1,
+                                           [](char c)
+            {
+                return c == '.' or c == 'e';
+            });
 
-        /// pre-increment (++it)
-        json_reverse_iterator& operator++()
-        {
-            return static_cast<json_reverse_iterator&>(base_iterator::operator++());
+            if (value_is_int_like)
+            {
+                o->write_characters(".0", 2);
+            }
         }
 
-        /// post-decrement (it--)
-        json_reverse_iterator operator--(int)
-        {
-            return static_cast<json_reverse_iterator>(base_iterator::operator--(1));
-        }
+      private:
+        /// the output of the serializer
+        output_adapter_t<char> o = nullptr;
 
-        /// pre-decrement (--it)
-        json_reverse_iterator& operator--()
-        {
-            return static_cast<json_reverse_iterator&>(base_iterator::operator--());
-        }
+        /// a (hopefully) large enough character buffer
+        std::array<char, 64> number_buffer{{}};
 
-        /// add to iterator
-        json_reverse_iterator& operator+=(difference_type i)
-        {
-            return static_cast<json_reverse_iterator&>(base_iterator::operator+=(i));
-        }
+        /// the locale
+        const std::lconv* loc = nullptr;
+        /// the locale's thousand separator character
+        const char thousands_sep = '\0';
+        /// the locale's decimal point character
+        const char decimal_point = '\0';
 
-        /// add to iterator
-        json_reverse_iterator operator+(difference_type i) const
-        {
-            return static_cast<json_reverse_iterator>(base_iterator::operator+(i));
-        }
+        /// the indentation character
+        const char indent_char;
 
-        /// subtract from iterator
-        json_reverse_iterator operator-(difference_type i) const
-        {
-            return static_cast<json_reverse_iterator>(base_iterator::operator-(i));
-        }
+        /// the indentation string
+        string_t indent_string;
+    };
 
-        /// return difference
-        difference_type operator-(const json_reverse_iterator& other) const
-        {
-            return base_iterator(*this) - base_iterator(other);
-        }
+  public:
+    /*!
+    @brief serialize to stream
 
-        /// access to successor
-        reference operator[](difference_type n) const
-        {
-            return *(this->operator+(n));
-        }
+    Serialize the given JSON value @a j to the output stream @a o. The JSON
+    value will be serialized using the @ref dump member function.
 
-        /// return the key of an object iterator
-        typename object_t::key_type key() const
-        {
-            auto it = --this->base();
-            return it.key();
-        }
+    - The indentation of the output can be controlled with the member variable
+      `width` of the output stream @a o. For instance, using the manipulator
+      `std::setw(4)` on @a o sets the indentation level to `4` and the
+      serialization result is the same as calling `dump(4)`.
 
-        /// return the value of an iterator
-        reference value() const
-        {
-            auto it = --this->base();
-            return it.operator * ();
-        }
-    };
+    - The indentation characrer can be controlled with the member variable
+      `fill` of the output stream @a o. For instance, the manipulator
+      `std::setfill('\\t')` sets indentation to use a tab character rather than
+      the default space character.
 
+    @param[in,out] o  stream to serialize to
+    @param[in] j  JSON value to serialize
 
-  private:
-    //////////////////////////////////////////
-    // binary serialization/deserialization //
-    //////////////////////////////////////////
+    @return the stream @a o
 
-    /// @name binary serialization/deserialization support
-    /// @{
+    @complexity Linear.
 
-    /*!
-    @brief deserialization of CBOR and MessagePack values
+    @liveexample{The example below shows the serialization with different
+    parameters to `width` to adjust the indentation level.,operator_serialize}
+
+    @since version 1.0.0; indentaction character added in version 3.0.0
     */
-    class binary_reader
+    friend std::ostream& operator<<(std::ostream& o, const basic_json& j)
     {
-      public:
-        /*!
-        @brief create a binary reader
+        // read width member and use it as indentation parameter if nonzero
+        const bool pretty_print = (o.width() > 0);
+        const auto indentation = (pretty_print ? o.width() : 0);
 
-        @param[in] adapter  input adapter to read from
-        */
-        explicit binary_reader(detail::input_adapter_t adapter)
-            : ia(adapter), is_little_endian(little_endianess())
-        {
-            assert(ia);
-        }
+        // reset width to 0 for subsequent calls to this stream
+        o.width(0);
 
-        /*!
-        @brief create a JSON value from CBOR input
+        // do the actual serialization
+        serializer s(output_adapter<char>::create(o), o.fill());
+        s.dump(j, pretty_print, static_cast<unsigned int>(indentation));
+        return o;
+    }
 
-        @param[in] get_char  whether a new character should be retrieved from
-                             the input (true, default) or whether the last
-                             read character should be considered instead
+    /*!
+    @brief serialize to stream
+    @deprecated This stream operator is deprecated and will be removed in a
+                future version of the library. Please use
+                @ref std::ostream& operator<<(std::ostream&, const basic_json&)
+                instead; that is, replace calls like `j >> o;` with `o << j;`.
+    */
+    JSON_DEPRECATED
+    friend std::ostream& operator>>(const basic_json& j, std::ostream& o)
+    {
+        return o << j;
+    }
 
-        @return JSON value created from CBOR input
+    /// @}
 
-        @throw parse_error.110 if input ended unexpectedly
-        @throw parse_error.112 if unsupported byte was read
-        */
-        basic_json parse_cbor(const bool get_char = true)
-        {
-            switch (get_char ? get() : current)
-            {
-                // EOF
-                case std::char_traits<char>::eof():
-                {
-                    JSON_THROW(parse_error::create(110, chars_read, "unexpected end of input"));
-                }
 
-                // Integer 0x00..0x17 (0..23)
-                case 0x00:
-                case 0x01:
-                case 0x02:
-                case 0x03:
-                case 0x04:
-                case 0x05:
-                case 0x06:
-                case 0x07:
-                case 0x08:
-                case 0x09:
-                case 0x0a:
-                case 0x0b:
-                case 0x0c:
-                case 0x0d:
-                case 0x0e:
-                case 0x0f:
-                case 0x10:
-                case 0x11:
-                case 0x12:
-                case 0x13:
-                case 0x14:
-                case 0x15:
-                case 0x16:
-                case 0x17:
-                {
-                    return static_cast<number_unsigned_t>(current);
-                }
+    /////////////////////
+    // deserialization //
+    /////////////////////
 
-                case 0x18: // Unsigned integer (one-byte uint8_t follows)
-                {
-                    return get_number<uint8_t>();
-                }
+    /// @name deserialization
+    /// @{
 
-                case 0x19: // Unsigned integer (two-byte uint16_t follows)
-                {
-                    return get_number<uint16_t>();
-                }
+    /*!
+    @brief deserialize from an array
 
-                case 0x1a: // Unsigned integer (four-byte uint32_t follows)
-                {
-                    return get_number<uint32_t>();
-                }
+    This function reads from an array of 1-byte values.
 
-                case 0x1b: // Unsigned integer (eight-byte uint64_t follows)
-                {
-                    return get_number<uint64_t>();
-                }
+    @pre Each element of the container has a size of 1 byte. Violating this
+    precondition yields undefined behavior. **This precondition is enforced
+    with a static assertion.**
 
-                // Negative integer -1-0x00..-1-0x17 (-1..-24)
-                case 0x20:
-                case 0x21:
-                case 0x22:
-                case 0x23:
-                case 0x24:
-                case 0x25:
-                case 0x26:
-                case 0x27:
-                case 0x28:
-                case 0x29:
-                case 0x2a:
-                case 0x2b:
-                case 0x2c:
-                case 0x2d:
-                case 0x2e:
-                case 0x2f:
-                case 0x30:
-                case 0x31:
-                case 0x32:
-                case 0x33:
-                case 0x34:
-                case 0x35:
-                case 0x36:
-                case 0x37:
-                {
-                    return static_cast<int8_t>(0x20 - 1 - current);
-                }
+    @param[in] array  array to read from
+    @param[in] cb  a parser callback function of type @ref parser_callback_t
+    which is used to control the deserialization by filtering unwanted values
+    (optional)
 
-                case 0x38: // Negative integer (one-byte uint8_t follows)
-                {
-                    // must be uint8_t !
-                    return static_cast<number_integer_t>(-1) - get_number<uint8_t>();
-                }
+    @return result of the deserialization
 
-                case 0x39: // Negative integer -1-n (two-byte uint16_t follows)
-                {
-                    return static_cast<number_integer_t>(-1) - get_number<uint16_t>();
-                }
+    @throw parse_error.101 if a parse error occurs; example: `""unexpected end
+    of input; expected string literal""`
+    @throw parse_error.102 if to_unicode fails or surrogate error
+    @throw parse_error.103 if to_unicode fails
 
-                case 0x3a: // Negative integer -1-n (four-byte uint32_t follows)
-                {
-                    return static_cast<number_integer_t>(-1) - get_number<uint32_t>();
-                }
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser. The complexity can be higher if the parser callback function
+    @a cb has a super-linear complexity.
 
-                case 0x3b: // Negative integer -1-n (eight-byte uint64_t follows)
-                {
-                    return static_cast<number_integer_t>(-1) - static_cast<number_integer_t>(get_number<uint64_t>());
-                }
+    @note A UTF-8 byte order mark is silently ignored.
 
-                // UTF-8 string (0x00..0x17 bytes follow)
-                case 0x60:
-                case 0x61:
-                case 0x62:
-                case 0x63:
-                case 0x64:
-                case 0x65:
-                case 0x66:
-                case 0x67:
-                case 0x68:
-                case 0x69:
-                case 0x6a:
-                case 0x6b:
-                case 0x6c:
-                case 0x6d:
-                case 0x6e:
-                case 0x6f:
-                case 0x70:
-                case 0x71:
-                case 0x72:
-                case 0x73:
-                case 0x74:
-                case 0x75:
-                case 0x76:
-                case 0x77:
-                case 0x78: // UTF-8 string (one-byte uint8_t for n follows)
-                case 0x79: // UTF-8 string (two-byte uint16_t for n follow)
-                case 0x7a: // UTF-8 string (four-byte uint32_t for n follow)
-                case 0x7b: // UTF-8 string (eight-byte uint64_t for n follow)
-                case 0x7f: // UTF-8 string (indefinite length)
-                {
-                    return get_cbor_string();
-                }
+    @liveexample{The example below demonstrates the `parse()` function reading
+    from an array.,parse__array__parser_callback_t}
 
-                // array (0x00..0x17 data items follow)
-                case 0x80:
-                case 0x81:
-                case 0x82:
-                case 0x83:
-                case 0x84:
-                case 0x85:
-                case 0x86:
-                case 0x87:
-                case 0x88:
-                case 0x89:
-                case 0x8a:
-                case 0x8b:
-                case 0x8c:
-                case 0x8d:
-                case 0x8e:
-                case 0x8f:
-                case 0x90:
-                case 0x91:
-                case 0x92:
-                case 0x93:
-                case 0x94:
-                case 0x95:
-                case 0x96:
-                case 0x97:
-                {
-                    basic_json result = value_t::array;
-                    const auto len = static_cast<size_t>(current & 0x1f);
-                    for (size_t i = 0; i < len; ++i)
-                    {
-                        result.push_back(parse_cbor());
-                    }
-                    return result;
-                }
+    @since version 2.0.3
+    */
+    template<class T, std::size_t N>
+    static basic_json parse(T (&array)[N],
+                            const parser_callback_t cb = nullptr)
+    {
+        // delegate the call to the iterator-range parse overload
+        return parse(std::begin(array), std::end(array), cb);
+    }
 
-                case 0x98: // array (one-byte uint8_t for n follows)
-                {
-                    basic_json result = value_t::array;
-                    const auto len = static_cast<size_t>(get_number<uint8_t>());
-                    for (size_t i = 0; i < len; ++i)
-                    {
-                        result.push_back(parse_cbor());
-                    }
-                    return result;
-                }
+    template<class T, std::size_t N>
+    static bool accept(T (&array)[N])
+    {
+        // delegate the call to the iterator-range accept overload
+        return accept(std::begin(array), std::end(array));
+    }
 
-                case 0x99: // array (two-byte uint16_t for n follow)
-                {
-                    basic_json result = value_t::array;
-                    const auto len = static_cast<size_t>(get_number<uint16_t>());
-                    for (size_t i = 0; i < len; ++i)
-                    {
-                        result.push_back(parse_cbor());
-                    }
-                    return result;
-                }
+    /*!
+    @brief deserialize from string literal
 
-                case 0x9a: // array (four-byte uint32_t for n follow)
-                {
-                    basic_json result = value_t::array;
-                    const auto len = static_cast<size_t>(get_number<uint32_t>());
-                    for (size_t i = 0; i < len; ++i)
-                    {
-                        result.push_back(parse_cbor());
-                    }
-                    return result;
-                }
+    @tparam CharT character/literal type with size of 1 byte
+    @param[in] s  string literal to read a serialized JSON value from
+    @param[in] cb a parser callback function of type @ref parser_callback_t
+    which is used to control the deserialization by filtering unwanted values
+    (optional)
 
-                case 0x9b: // array (eight-byte uint64_t for n follow)
-                {
-                    basic_json result = value_t::array;
-                    const auto len = static_cast<size_t>(get_number<uint64_t>());
-                    for (size_t i = 0; i < len; ++i)
-                    {
-                        result.push_back(parse_cbor());
-                    }
-                    return result;
-                }
+    @return result of the deserialization
 
-                case 0x9f: // array (indefinite length)
-                {
-                    basic_json result = value_t::array;
-                    while (get() != 0xff)
-                    {
-                        result.push_back(parse_cbor(false));
-                    }
-                    return result;
-                }
+    @throw parse_error.101 in case of an unexpected token
+    @throw parse_error.102 if to_unicode fails or surrogate error
+    @throw parse_error.103 if to_unicode fails
 
-                // map (0x00..0x17 pairs of data items follow)
-                case 0xa0:
-                case 0xa1:
-                case 0xa2:
-                case 0xa3:
-                case 0xa4:
-                case 0xa5:
-                case 0xa6:
-                case 0xa7:
-                case 0xa8:
-                case 0xa9:
-                case 0xaa:
-                case 0xab:
-                case 0xac:
-                case 0xad:
-                case 0xae:
-                case 0xaf:
-                case 0xb0:
-                case 0xb1:
-                case 0xb2:
-                case 0xb3:
-                case 0xb4:
-                case 0xb5:
-                case 0xb6:
-                case 0xb7:
-                {
-                    basic_json result = value_t::object;
-                    const auto len = static_cast<size_t>(current & 0x1f);
-                    for (size_t i = 0; i < len; ++i)
-                    {
-                        get();
-                        auto key = get_cbor_string();
-                        result[key] = parse_cbor();
-                    }
-                    return result;
-                }
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser. The complexity can be higher if the parser callback function
+    @a cb has a super-linear complexity.
 
-                case 0xb8: // map (one-byte uint8_t for n follows)
-                {
-                    basic_json result = value_t::object;
-                    const auto len = static_cast<size_t>(get_number<uint8_t>());
-                    for (size_t i = 0; i < len; ++i)
-                    {
-                        get();
-                        auto key = get_cbor_string();
-                        result[key] = parse_cbor();
-                    }
-                    return result;
-                }
+    @note A UTF-8 byte order mark is silently ignored.
+    @note String containers like `std::string` or @ref string_t can be parsed
+          with @ref parse(const ContiguousContainer&, const parser_callback_t)
 
-                case 0xb9: // map (two-byte uint16_t for n follow)
-                {
-                    basic_json result = value_t::object;
-                    const auto len = static_cast<size_t>(get_number<uint16_t>());
-                    for (size_t i = 0; i < len; ++i)
-                    {
-                        get();
-                        auto key = get_cbor_string();
-                        result[key] = parse_cbor();
-                    }
-                    return result;
-                }
+    @liveexample{The example below demonstrates the `parse()` function with
+    and without callback function.,parse__string__parser_callback_t}
 
-                case 0xba: // map (four-byte uint32_t for n follow)
-                {
-                    basic_json result = value_t::object;
-                    const auto len = static_cast<size_t>(get_number<uint32_t>());
-                    for (size_t i = 0; i < len; ++i)
-                    {
-                        get();
-                        auto key = get_cbor_string();
-                        result[key] = parse_cbor();
-                    }
-                    return result;
-                }
+    @sa @ref parse(std::istream&, const parser_callback_t) for a version that
+    reads from an input stream
 
-                case 0xbb: // map (eight-byte uint64_t for n follow)
-                {
-                    basic_json result = value_t::object;
-                    const auto len = static_cast<size_t>(get_number<uint64_t>());
-                    for (size_t i = 0; i < len; ++i)
-                    {
-                        get();
-                        auto key = get_cbor_string();
-                        result[key] = parse_cbor();
-                    }
-                    return result;
-                }
+    @since version 1.0.0 (originally for @ref string_t)
+    */
+    template<typename CharT, typename std::enable_if<
+                 std::is_pointer<CharT>::value and
+                 std::is_integral<typename std::remove_pointer<CharT>::type>::value and
+                 sizeof(typename std::remove_pointer<CharT>::type) == 1, int>::type = 0>
+    static basic_json parse(const CharT s,
+                            const parser_callback_t cb = nullptr)
+    {
+        return parser(detail::input_adapter_factory::create(s), cb).parse(true);
+    }
 
-                case 0xbf: // map (indefinite length)
-                {
-                    basic_json result = value_t::object;
-                    while (get() != 0xff)
-                    {
-                        auto key = get_cbor_string();
-                        result[key] = parse_cbor();
-                    }
-                    return result;
-                }
+    template<typename CharT, typename std::enable_if<
+                 std::is_pointer<CharT>::value and
+                 std::is_integral<typename std::remove_pointer<CharT>::type>::value and
+                 sizeof(typename std::remove_pointer<CharT>::type) == 1, int>::type = 0>
+    static bool accept(const CharT s)
+    {
+        return parser(detail::input_adapter_factory::create(s)).accept(true);
+    }
 
-                case 0xf4: // false
-                {
-                    return false;
-                }
+    /*!
+    @brief deserialize from stream
 
-                case 0xf5: // true
-                {
-                    return true;
-                }
+    @param[in,out] i  stream to read a serialized JSON value from
+    @param[in] cb a parser callback function of type @ref parser_callback_t
+    which is used to control the deserialization by filtering unwanted values
+    (optional)
 
-                case 0xf6: // null
-                {
-                    return value_t::null;
-                }
+    @return result of the deserialization
 
-                case 0xf9: // Half-Precision Float (two-byte IEEE 754)
-                {
-                    const int byte1 = get();
-                    check_eof();
-                    const int byte2 = get();
-                    check_eof();
+    @throw parse_error.101 in case of an unexpected token
+    @throw parse_error.102 if to_unicode fails or surrogate error
+    @throw parse_error.103 if to_unicode fails
 
-                    // code from RFC 7049, Appendix D, Figure 3:
-                    // As half-precision floating-point numbers were only added
-                    // to IEEE 754 in 2008, today's programming platforms often
-                    // still only have limited support for them. It is very
-                    // easy to include at least decoding support for them even
-                    // without such support. An example of a small decoder for
-                    // half-precision floating-point numbers in the C language
-                    // is shown in Fig. 3.
-                    const int half = (byte1 << 8) + byte2;
-                    const int exp = (half >> 10) & 0x1f;
-                    const int mant = half & 0x3ff;
-                    double val;
-                    if (exp == 0)
-                    {
-                        val = std::ldexp(mant, -24);
-                    }
-                    else if (exp != 31)
-                    {
-                        val = std::ldexp(mant + 1024, exp - 25);
-                    }
-                    else
-                    {
-                        val = (mant == 0)
-                              ? std::numeric_limits<double>::infinity()
-                              : std::numeric_limits<double>::quiet_NaN();
-                    }
-                    return (half & 0x8000) != 0 ? -val : val;
-                }
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser. The complexity can be higher if the parser callback function
+    @a cb has a super-linear complexity.
 
-                case 0xfa: // Single-Precision Float (four-byte IEEE 754)
-                {
-                    return get_number<float>();
-                }
+    @note A UTF-8 byte order mark is silently ignored.
 
-                case 0xfb: // Double-Precision Float (eight-byte IEEE 754)
-                {
-                    return get_number<double>();
-                }
+    @liveexample{The example below demonstrates the `parse()` function with
+    and without callback function.,parse__istream__parser_callback_t}
 
-                default: // anything else (0xFF is handled inside the other types)
-                {
-                    std::stringstream ss;
-                    ss << std::setw(2) << std::setfill('0') << std::hex << current;
-                    JSON_THROW(parse_error::create(112, chars_read, "error reading CBOR; last byte: 0x" + ss.str()));
-                }
-            }
-        }
+    @sa @ref parse(const CharT, const parser_callback_t) for a version
+    that reads from a string
 
-        /*!
-        @brief create a JSON value from MessagePack input
+    @since version 1.0.0
+    */
+    static basic_json parse(std::istream& i,
+                            const parser_callback_t cb = nullptr)
+    {
+        return parser(detail::input_adapter_factory::create(i), cb).parse(true);
+    }
 
-        @return JSON value created from MessagePack input
+    static bool accept(std::istream& i)
+    {
+        return parser(detail::input_adapter_factory::create(i)).accept(true);
+    }
 
-        @throw parse_error.110 if input ended unexpectedly
-        @throw parse_error.112 if unsupported byte was read
-        */
-        basic_json parse_msgpack()
-        {
-            switch (get())
-            {
-                // EOF
-                case std::char_traits<char>::eof():
-                {
-                    JSON_THROW(parse_error::create(110, chars_read, "unexpected end of input"));
-                }
+    /*!
+    @copydoc parse(std::istream&, const parser_callback_t)
+    */
+    static basic_json parse(std::istream&& i,
+                            const parser_callback_t cb = nullptr)
+    {
+        return parser(detail::input_adapter_factory::create(i), cb).parse(true);
+    }
 
-                // positive fixint
-                case 0x00:
-                case 0x01:
-                case 0x02:
-                case 0x03:
-                case 0x04:
-                case 0x05:
-                case 0x06:
-                case 0x07:
-                case 0x08:
-                case 0x09:
-                case 0x0a:
-                case 0x0b:
-                case 0x0c:
-                case 0x0d:
-                case 0x0e:
-                case 0x0f:
-                case 0x10:
-                case 0x11:
-                case 0x12:
-                case 0x13:
-                case 0x14:
-                case 0x15:
-                case 0x16:
-                case 0x17:
-                case 0x18:
-                case 0x19:
-                case 0x1a:
-                case 0x1b:
-                case 0x1c:
-                case 0x1d:
-                case 0x1e:
-                case 0x1f:
-                case 0x20:
-                case 0x21:
-                case 0x22:
-                case 0x23:
-                case 0x24:
-                case 0x25:
-                case 0x26:
-                case 0x27:
-                case 0x28:
-                case 0x29:
-                case 0x2a:
-                case 0x2b:
-                case 0x2c:
-                case 0x2d:
-                case 0x2e:
-                case 0x2f:
-                case 0x30:
-                case 0x31:
-                case 0x32:
-                case 0x33:
-                case 0x34:
-                case 0x35:
-                case 0x36:
-                case 0x37:
-                case 0x38:
-                case 0x39:
-                case 0x3a:
-                case 0x3b:
-                case 0x3c:
-                case 0x3d:
-                case 0x3e:
-                case 0x3f:
-                case 0x40:
-                case 0x41:
-                case 0x42:
-                case 0x43:
-                case 0x44:
-                case 0x45:
-                case 0x46:
-                case 0x47:
-                case 0x48:
-                case 0x49:
-                case 0x4a:
-                case 0x4b:
-                case 0x4c:
-                case 0x4d:
-                case 0x4e:
-                case 0x4f:
-                case 0x50:
-                case 0x51:
-                case 0x52:
-                case 0x53:
-                case 0x54:
-                case 0x55:
-                case 0x56:
-                case 0x57:
-                case 0x58:
-                case 0x59:
-                case 0x5a:
-                case 0x5b:
-                case 0x5c:
-                case 0x5d:
-                case 0x5e:
-                case 0x5f:
-                case 0x60:
-                case 0x61:
-                case 0x62:
-                case 0x63:
-                case 0x64:
-                case 0x65:
-                case 0x66:
-                case 0x67:
-                case 0x68:
-                case 0x69:
-                case 0x6a:
-                case 0x6b:
-                case 0x6c:
-                case 0x6d:
-                case 0x6e:
-                case 0x6f:
-                case 0x70:
-                case 0x71:
-                case 0x72:
-                case 0x73:
-                case 0x74:
-                case 0x75:
-                case 0x76:
-                case 0x77:
-                case 0x78:
-                case 0x79:
-                case 0x7a:
-                case 0x7b:
-                case 0x7c:
-                case 0x7d:
-                case 0x7e:
-                case 0x7f:
-                {
-                    return static_cast<number_unsigned_t>(current);
-                }
+    static bool accept(std::istream&& i)
+    {
+        return parser(detail::input_adapter_factory::create(i)).accept(true);
+    }
 
-                // fixmap
-                case 0x80:
-                case 0x81:
-                case 0x82:
-                case 0x83:
-                case 0x84:
-                case 0x85:
-                case 0x86:
-                case 0x87:
-                case 0x88:
-                case 0x89:
-                case 0x8a:
-                case 0x8b:
-                case 0x8c:
-                case 0x8d:
-                case 0x8e:
-                case 0x8f:
-                {
-                    basic_json result = value_t::object;
-                    const auto len = static_cast<size_t>(current & 0x0f);
-                    for (size_t i = 0; i < len; ++i)
-                    {
-                        get();
-                        auto key = get_msgpack_string();
-                        result[key] = parse_msgpack();
-                    }
-                    return result;
-                }
+    /*!
+    @brief deserialize from an iterator range with contiguous storage
 
-                // fixarray
-                case 0x90:
-                case 0x91:
-                case 0x92:
-                case 0x93:
-                case 0x94:
-                case 0x95:
-                case 0x96:
-                case 0x97:
-                case 0x98:
-                case 0x99:
-                case 0x9a:
-                case 0x9b:
-                case 0x9c:
-                case 0x9d:
-                case 0x9e:
-                case 0x9f:
-                {
-                    basic_json result = value_t::array;
-                    const auto len = static_cast<size_t>(current & 0x0f);
-                    for (size_t i = 0; i < len; ++i)
-                    {
-                        result.push_back(parse_msgpack());
-                    }
-                    return result;
-                }
+    This function reads from an iterator range of a container with contiguous
+    storage of 1-byte values. Compatible container types include
+    `std::vector`, `std::string`, `std::array`, `std::valarray`, and
+    `std::initializer_list`. Furthermore, C-style arrays can be used with
+    `std::begin()`/`std::end()`. User-defined containers can be used as long
+    as they implement random-access iterators and a contiguous storage.
 
-                // fixstr
-                case 0xa0:
-                case 0xa1:
-                case 0xa2:
-                case 0xa3:
-                case 0xa4:
-                case 0xa5:
-                case 0xa6:
-                case 0xa7:
-                case 0xa8:
-                case 0xa9:
-                case 0xaa:
-                case 0xab:
-                case 0xac:
-                case 0xad:
-                case 0xae:
-                case 0xaf:
-                case 0xb0:
-                case 0xb1:
-                case 0xb2:
-                case 0xb3:
-                case 0xb4:
-                case 0xb5:
-                case 0xb6:
-                case 0xb7:
-                case 0xb8:
-                case 0xb9:
-                case 0xba:
-                case 0xbb:
-                case 0xbc:
-                case 0xbd:
-                case 0xbe:
-                case 0xbf:
-                {
-                    return get_msgpack_string();
-                }
+    @pre The iterator range is contiguous. Violating this precondition yields
+    undefined behavior. **This precondition is enforced with an assertion.**
+    @pre Each element in the range has a size of 1 byte. Violating this
+    precondition yields undefined behavior. **This precondition is enforced
+    with a static assertion.**
 
-                case 0xc0: // nil
-                {
-                    return value_t::null;
-                }
+    @warning There is no way to enforce all preconditions at compile-time. If
+             the function is called with noncompliant iterators and with
+             assertions switched off, the behavior is undefined and will most
+             likely yield segmentation violation.
 
-                case 0xc2: // false
-                {
-                    return false;
-                }
+    @tparam IteratorType iterator of container with contiguous storage
+    @param[in] first  begin of the range to parse (included)
+    @param[in] last  end of the range to parse (excluded)
+    @param[in] cb  a parser callback function of type @ref parser_callback_t
+    which is used to control the deserialization by filtering unwanted values
+    (optional)
 
-                case 0xc3: // true
-                {
-                    return true;
-                }
+    @return result of the deserialization
 
-                case 0xca: // float 32
-                {
-                    return get_number<float>();
-                }
+    @throw parse_error.101 in case of an unexpected token
+    @throw parse_error.102 if to_unicode fails or surrogate error
+    @throw parse_error.103 if to_unicode fails
 
-                case 0xcb: // float 64
-                {
-                    return get_number<double>();
-                }
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser. The complexity can be higher if the parser callback function
+    @a cb has a super-linear complexity.
 
-                case 0xcc: // uint 8
-                {
-                    return get_number<uint8_t>();
-                }
+    @note A UTF-8 byte order mark is silently ignored.
 
-                case 0xcd: // uint 16
-                {
-                    return get_number<uint16_t>();
-                }
+    @liveexample{The example below demonstrates the `parse()` function reading
+    from an iterator range.,parse__iteratortype__parser_callback_t}
 
-                case 0xce: // uint 32
-                {
-                    return get_number<uint32_t>();
-                }
+    @since version 2.0.3
+    */
+    template<class IteratorType, typename std::enable_if<
+                 std::is_base_of<
+                     std::random_access_iterator_tag,
+                     typename std::iterator_traits<IteratorType>::iterator_category>::value, int>::type = 0>
+    static basic_json parse(IteratorType first, IteratorType last,
+                            const parser_callback_t cb = nullptr)
+    {
+        return parser(detail::input_adapter_factory::create(first, last), cb).parse(true);
+    }
 
-                case 0xcf: // uint 64
-                {
-                    return get_number<uint64_t>();
-                }
+    template<class IteratorType, typename std::enable_if<
+                 std::is_base_of<
+                     std::random_access_iterator_tag,
+                     typename std::iterator_traits<IteratorType>::iterator_category>::value, int>::type = 0>
+    static bool accept(IteratorType first, IteratorType last)
+    {
+        return parser(detail::input_adapter_factory::create(first, last)).accept(true);
+    }
 
-                case 0xd0: // int 8
-                {
-                    return get_number<int8_t>();
-                }
+    /*!
+    @brief deserialize from a container with contiguous storage
 
-                case 0xd1: // int 16
-                {
-                    return get_number<int16_t>();
-                }
+    This function reads from a container with contiguous storage of 1-byte
+    values. Compatible container types include `std::vector`, `std::string`,
+    `std::array`, and `std::initializer_list`. User-defined containers can be
+    used as long as they implement random-access iterators and a contiguous
+    storage.
 
-                case 0xd2: // int 32
-                {
-                    return get_number<int32_t>();
-                }
+    @pre The container storage is contiguous. Violating this precondition
+    yields undefined behavior. **This precondition is enforced with an
+    assertion.**
+    @pre Each element of the container has a size of 1 byte. Violating this
+    precondition yields undefined behavior. **This precondition is enforced
+    with a static assertion.**
 
-                case 0xd3: // int 64
-                {
-                    return get_number<int64_t>();
-                }
+    @warning There is no way to enforce all preconditions at compile-time. If
+             the function is called with a noncompliant container and with
+             assertions switched off, the behavior is undefined and will most
+             likely yield segmentation violation.
 
-                case 0xd9: // str 8
-                case 0xda: // str 16
-                case 0xdb: // str 32
-                {
-                    return get_msgpack_string();
-                }
+    @tparam ContiguousContainer container type with contiguous storage
+    @param[in] c  container to read from
+    @param[in] cb  a parser callback function of type @ref parser_callback_t
+    which is used to control the deserialization by filtering unwanted values
+    (optional)
 
-                case 0xdc: // array 16
-                {
-                    basic_json result = value_t::array;
-                    const auto len = static_cast<size_t>(get_number<uint16_t>());
-                    for (size_t i = 0; i < len; ++i)
-                    {
-                        result.push_back(parse_msgpack());
-                    }
-                    return result;
-                }
+    @return result of the deserialization
 
-                case 0xdd: // array 32
-                {
-                    basic_json result = value_t::array;
-                    const auto len = static_cast<size_t>(get_number<uint32_t>());
-                    for (size_t i = 0; i < len; ++i)
-                    {
-                        result.push_back(parse_msgpack());
-                    }
-                    return result;
-                }
+    @throw parse_error.101 in case of an unexpected token
+    @throw parse_error.102 if to_unicode fails or surrogate error
+    @throw parse_error.103 if to_unicode fails
 
-                case 0xde: // map 16
-                {
-                    basic_json result = value_t::object;
-                    const auto len = static_cast<size_t>(get_number<uint16_t>());
-                    for (size_t i = 0; i < len; ++i)
-                    {
-                        get();
-                        auto key = get_msgpack_string();
-                        result[key] = parse_msgpack();
-                    }
-                    return result;
-                }
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser. The complexity can be higher if the parser callback function
+    @a cb has a super-linear complexity.
 
-                case 0xdf: // map 32
-                {
-                    basic_json result = value_t::object;
-                    const auto len = static_cast<size_t>(get_number<uint32_t>());
-                    for (size_t i = 0; i < len; ++i)
-                    {
-                        get();
-                        auto key = get_msgpack_string();
-                        result[key] = parse_msgpack();
-                    }
-                    return result;
-                }
+    @note A UTF-8 byte order mark is silently ignored.
 
-                // positive fixint
-                case 0xe0:
-                case 0xe1:
-                case 0xe2:
-                case 0xe3:
-                case 0xe4:
-                case 0xe5:
-                case 0xe6:
-                case 0xe7:
-                case 0xe8:
-                case 0xe9:
-                case 0xea:
-                case 0xeb:
-                case 0xec:
-                case 0xed:
-                case 0xee:
-                case 0xef:
-                case 0xf0:
-                case 0xf1:
-                case 0xf2:
-                case 0xf3:
-                case 0xf4:
-                case 0xf5:
-                case 0xf6:
-                case 0xf7:
-                case 0xf8:
-                case 0xf9:
-                case 0xfa:
-                case 0xfb:
-                case 0xfc:
-                case 0xfd:
-                case 0xfe:
-                case 0xff:
-                {
-                    return static_cast<int8_t>(current);
-                }
+    @liveexample{The example below demonstrates the `parse()` function reading
+    from a contiguous container.,parse__contiguouscontainer__parser_callback_t}
 
-                default: // anything else
-                {
-                    std::stringstream ss;
-                    ss << std::setw(2) << std::setfill('0') << std::hex << current;
-                    JSON_THROW(parse_error::create(112, chars_read, "error reading MessagePack; last byte: 0x" + ss.str()));
-                }
-            }
-        }
+    @since version 2.0.3
+    */
+    template<class ContiguousContainer, typename std::enable_if<
+                 not std::is_pointer<ContiguousContainer>::value and
+                 std::is_base_of<
+                     std::random_access_iterator_tag,
+                     typename std::iterator_traits<decltype(std::begin(std::declval<ContiguousContainer const>()))>::iterator_category>::value
+                 , int>::type = 0>
+    static basic_json parse(const ContiguousContainer& c,
+                            const parser_callback_t cb = nullptr)
+    {
+        // delegate the call to the iterator-range parse overload
+        return parse(std::begin(c), std::end(c), cb);
+    }
 
-        /*!
-        @brief determine system byte order
+    template<class ContiguousContainer, typename std::enable_if<
+                 not std::is_pointer<ContiguousContainer>::value and
+                 std::is_base_of<
+                     std::random_access_iterator_tag,
+                     typename std::iterator_traits<decltype(std::begin(std::declval<ContiguousContainer const>()))>::iterator_category>::value
+                 , int>::type = 0>
+    static bool accept(const ContiguousContainer& c)
+    {
+        // delegate the call to the iterator-range accept overload
+        return accept(std::begin(c), std::end(c));
+    }
 
-        @return true iff system's byte order is little endian
+    /*!
+    @brief deserialize from stream
+    @deprecated This stream operator is deprecated and will be removed in a
+                future version of the library. Please use
+                @ref std::istream& operator>>(std::istream&, basic_json&)
+                instead; that is, replace calls like `j << i;` with `i >> j;`.
+    */
+    JSON_DEPRECATED
+    friend std::istream& operator<<(basic_json& j, std::istream& i)
+    {
+        j = parser(detail::input_adapter_factory::create(i)).parse(false);
+        return i;
+    }
 
-        @note from http://stackoverflow.com/a/1001328/266378
-        */
-        static bool little_endianess() noexcept
-        {
-            int num = 1;
-            return (*reinterpret_cast<char*>(&num) == 1);
-        }
+    /*!
+    @brief deserialize from stream
 
-      private:
-        /*!
-        @brief get next character from the input
+    Deserializes an input stream to a JSON value.
 
-        This function provides the interface to the used input adapter. It does
-        not throw in case the input reached EOF, but returns
-        `std::char_traits<char>::eof()` in that case.
+    @param[in,out] i  input stream to read a serialized JSON value from
+    @param[in,out] j  JSON value to write the deserialized input to
 
-        @return character read from the input
-        */
-        int get()
-        {
-            ++chars_read;
-            return (current = ia->get_character());
-        }
+    @throw parse_error.101 in case of an unexpected token
+    @throw parse_error.102 if to_unicode fails or surrogate error
+    @throw parse_error.103 if to_unicode fails
 
-        /*
-        @brief read a number from the input
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser.
 
-        @tparam NumberType the type of the number
+    @note A UTF-8 byte order mark is silently ignored.
 
-        @return number of type @a NumberType
+    @liveexample{The example below shows how a JSON value is constructed by
+    reading a serialization from a stream.,operator_deserialize}
 
-        @note This function needs to respect the system's endianess, because
-              bytes in CBOR and MessagePack are stored in network order (big
-              endian) and therefore need reordering on little endian systems.
+    @sa parse(std::istream&, const parser_callback_t) for a variant with a
+    parser callback function to filter values while parsing
 
-        @throw parse_error.110 if input has less than `sizeof(NumberType)`
-                               bytes
-        */
-        template<typename NumberType>
-        NumberType get_number()
-        {
-            // step 1: read input into array with system's byte order
-            std::array<uint8_t, sizeof(NumberType)> vec;
-            for (size_t i = 0; i < sizeof(NumberType); ++i)
-            {
-                get();
-                check_eof();
+    @since version 1.0.0
+    */
+    friend std::istream& operator>>(std::istream& i, basic_json& j)
+    {
+        j = parser(detail::input_adapter_factory::create(i)).parse(false);
+        return i;
+    }
 
-                // reverse byte order prior to conversion if necessary
-                if (is_little_endian)
-                {
-                    vec[sizeof(NumberType) - i - 1] = static_cast<uint8_t>(current);
-                }
-                else
-                {
-                    vec[i] = static_cast<uint8_t>(current);  // LCOV_EXCL_LINE
-                }
-            }
+    /// @}
 
-            // step 2: convert array into number of type T and return
-            NumberType result;
-            std::memcpy(&result, vec.data(), sizeof(NumberType));
-            return result;
-        }
+    ///////////////////////////
+    // convenience functions //
+    ///////////////////////////
 
-        /*!
-        @brief create a string by reading characters from the input
+    /*!
+    @brief return the type as string
 
-        @param[in] len number of bytes to read
+    Returns the type name as string to be used in error messages - usually to
+    indicate that a function was called on a wrong JSON type.
 
-        @note We can not reserve @a len bytes for the result, because @a len
-              may be too large. Usually, @ref check_eof() detects the end of
-              the input before we run out of string memory.
+    @return basically a string representation of a the @a m_type member
 
-        @return string created by reading @a len bytes
+    @complexity Constant.
 
-        @throw parse_error.110 if input has less than @a len bytes
-        */
-        std::string get_string(const size_t len)
+    @liveexample{The following code exemplifies `type_name()` for all JSON
+    types.,type_name}
+
+    @since version 1.0.0, public since 2.1.0
+    */
+    std::string type_name() const
+    {
         {
-            std::string result;
-            for (size_t i = 0; i < len; ++i)
+            switch (m_type)
             {
-                get();
-                check_eof();
-                result.append(1, static_cast<char>(current));
+                case value_t::null:
+                    return "null";
+                case value_t::object:
+                    return "object";
+                case value_t::array:
+                    return "array";
+                case value_t::string:
+                    return "string";
+                case value_t::boolean:
+                    return "boolean";
+                case value_t::discarded:
+                    return "discarded";
+                default:
+                    return "number";
             }
-            return result;
         }
+    }
 
-        /*!
-        @brief reads a CBOR string
 
-        This function first reads starting bytes to determine the expected
-        string length and then copies this number of bytes into a string.
-        Additionally, CBOR's strings with indefinite lengths are supported.
+  private:
+    //////////////////////
+    // member variables //
+    //////////////////////
 
-        @return string
+    /// the type of the current element
+    value_t m_type = value_t::null;
 
-        @throw parse_error.110 if input ended
-        @throw parse_error.113 if an unexpected byte is read
-        */
-        std::string get_cbor_string()
-        {
-            check_eof();
+    /// the value of the current element
+    json_value m_value = {};
 
-            switch (current)
-            {
-                // UTF-8 string (0x00..0x17 bytes follow)
-                case 0x60:
-                case 0x61:
-                case 0x62:
-                case 0x63:
-                case 0x64:
-                case 0x65:
-                case 0x66:
-                case 0x67:
-                case 0x68:
-                case 0x69:
-                case 0x6a:
-                case 0x6b:
-                case 0x6c:
-                case 0x6d:
-                case 0x6e:
-                case 0x6f:
-                case 0x70:
-                case 0x71:
-                case 0x72:
-                case 0x73:
-                case 0x74:
-                case 0x75:
-                case 0x76:
-                case 0x77:
-                {
-                    const auto len = static_cast<size_t>(current & 0x1f);
-                    return get_string(len);
-                }
 
-                case 0x78: // UTF-8 string (one-byte uint8_t for n follows)
-                {
-                    const auto len = static_cast<size_t>(get_number<uint8_t>());
-                    return get_string(len);
-                }
+  private:
+    ///////////////
+    // iterators //
+    ///////////////
 
-                case 0x79: // UTF-8 string (two-byte uint16_t for n follow)
-                {
-                    const auto len = static_cast<size_t>(get_number<uint16_t>());
-                    return get_string(len);
-                }
+    /*!
+    @brief an iterator for primitive JSON types
 
-                case 0x7a: // UTF-8 string (four-byte uint32_t for n follow)
-                {
-                    const auto len = static_cast<size_t>(get_number<uint32_t>());
-                    return get_string(len);
-                }
+    This class models an iterator for primitive JSON types (boolean, number,
+    string). It's only purpose is to allow the iterator/const_iterator classes
+    to "iterate" over primitive values. Internally, the iterator is modeled by
+    a `difference_type` variable. Value begin_value (`0`) models the begin,
+    end_value (`1`) models past the end.
+    */
+    class primitive_iterator_t
+    {
+      public:
 
-                case 0x7b: // UTF-8 string (eight-byte uint64_t for n follow)
-                {
-                    const auto len = static_cast<size_t>(get_number<uint64_t>());
-                    return get_string(len);
-                }
+        difference_type get_value() const noexcept
+        {
+            return m_it;
+        }
+        /// set iterator to a defined beginning
+        void set_begin() noexcept
+        {
+            m_it = begin_value;
+        }
 
-                case 0x7f: // UTF-8 string (indefinite length)
-                {
-                    std::string result;
-                    while (get() != 0xff)
-                    {
-                        check_eof();
-                        result.append(1, static_cast<char>(current));
-                    }
-                    return result;
-                }
+        /// set iterator to a defined past the end
+        void set_end() noexcept
+        {
+            m_it = end_value;
+        }
 
-                default:
-                {
-                    std::stringstream ss;
-                    ss << std::setw(2) << std::setfill('0') << std::hex << current;
-                    JSON_THROW(parse_error::create(113, chars_read, "expected a CBOR string; last byte: 0x" + ss.str()));
-                }
-            }
+        /// return whether the iterator can be dereferenced
+        constexpr bool is_begin() const noexcept
+        {
+            return (m_it == begin_value);
         }
 
-        /*!
-        @brief reads a MessagePack string
+        /// return whether the iterator is at end
+        constexpr bool is_end() const noexcept
+        {
+            return (m_it == end_value);
+        }
 
-        This function first reads starting bytes to determine the expected
-        string length and then copies this number of bytes into a string.
+        friend constexpr bool operator==(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
+        {
+            return lhs.m_it == rhs.m_it;
+        }
 
-        @return string
+        friend constexpr bool operator!=(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
+        {
+            return !(lhs == rhs);
+        }
 
-        @throw parse_error.110 if input ended
-        @throw parse_error.113 if an unexpected byte is read
-        */
-        std::string get_msgpack_string()
+        friend constexpr bool operator<(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
         {
-            check_eof();
+            return lhs.m_it < rhs.m_it;
+        }
 
-            switch (current)
-            {
-                // fixstr
-                case 0xa0:
-                case 0xa1:
-                case 0xa2:
-                case 0xa3:
-                case 0xa4:
-                case 0xa5:
-                case 0xa6:
-                case 0xa7:
-                case 0xa8:
-                case 0xa9:
-                case 0xaa:
-                case 0xab:
-                case 0xac:
-                case 0xad:
-                case 0xae:
-                case 0xaf:
-                case 0xb0:
-                case 0xb1:
-                case 0xb2:
-                case 0xb3:
-                case 0xb4:
-                case 0xb5:
-                case 0xb6:
-                case 0xb7:
-                case 0xb8:
-                case 0xb9:
-                case 0xba:
-                case 0xbb:
-                case 0xbc:
-                case 0xbd:
-                case 0xbe:
-                case 0xbf:
-                {
-                    const auto len = static_cast<size_t>(current & 0x1f);
-                    return get_string(len);
-                }
+        friend constexpr bool operator<=(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
+        {
+            return lhs.m_it <= rhs.m_it;
+        }
 
-                case 0xd9: // str 8
-                {
-                    const auto len = static_cast<size_t>(get_number<uint8_t>());
-                    return get_string(len);
-                }
+        friend constexpr bool operator>(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
+        {
+            return lhs.m_it > rhs.m_it;
+        }
 
-                case 0xda: // str 16
-                {
-                    const auto len = static_cast<size_t>(get_number<uint16_t>());
-                    return get_string(len);
-                }
+        friend constexpr bool operator>=(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
+        {
+            return lhs.m_it >= rhs.m_it;
+        }
 
-                case 0xdb: // str 32
-                {
-                    const auto len = static_cast<size_t>(get_number<uint32_t>());
-                    return get_string(len);
-                }
+        primitive_iterator_t operator+(difference_type i)
+        {
+            auto result = *this;
+            result += i;
+            return result;
+        }
 
-                default:
-                {
-                    std::stringstream ss;
-                    ss << std::setw(2) << std::setfill('0') << std::hex << current;
-                    JSON_THROW(parse_error::create(113, chars_read, "expected a MessagePack string; last byte: 0x" + ss.str()));
-                }
-            }
+        friend constexpr difference_type operator-(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
+        {
+            return lhs.m_it - rhs.m_it;
         }
 
-        /*!
-        @brief check if input ended
-        @throw parse_error.110 if input ended
-        */
-        void check_eof() const
+        friend std::ostream& operator<<(std::ostream& os, primitive_iterator_t it)
         {
-            if (JSON_UNLIKELY(current == std::char_traits<char>::eof()))
-            {
-                JSON_THROW(parse_error::create(110, chars_read, "unexpected end of input"));
-            }
+            return os << it.m_it;
         }
 
-      private:
-        /// input adapter
-        detail::input_adapter_t ia = nullptr;
+        primitive_iterator_t& operator++()
+        {
+            ++m_it;
+            return *this;
+        }
 
-        /// the current character
-        int current = std::char_traits<char>::eof();
+        primitive_iterator_t operator++(int)
+        {
+            auto result = *this;
+            m_it++;
+            return result;
+        }
 
-        /// the number of characters read
-        size_t chars_read = 0;
+        primitive_iterator_t& operator--()
+        {
+            --m_it;
+            return *this;
+        }
 
-        /// whether we can assume little endianess
-        const bool is_little_endian = true;
+        primitive_iterator_t operator--(int)
+        {
+            auto result = *this;
+            m_it--;
+            return result;
+        }
+
+        primitive_iterator_t& operator+=(difference_type n)
+        {
+            m_it += n;
+            return *this;
+        }
+
+        primitive_iterator_t& operator-=(difference_type n)
+        {
+            m_it -= n;
+            return *this;
+        }
+
+      private:
+        static constexpr difference_type begin_value = 0;
+        static constexpr difference_type end_value = begin_value + 1;
+
+        /// iterator as signed integer type
+        difference_type m_it = std::numeric_limits<std::ptrdiff_t>::denorm_min();
     };
 
     /*!
-    @brief serialization to CBOR and MessagePack values
+    @brief an iterator value
+
+    @note This structure could easily be a union, but MSVC currently does not
+    allow unions members with complex constructors, see
+    https://github.com/nlohmann/json/pull/105.
     */
-    class binary_writer
+    struct internal_iterator
     {
-      public:
-        /*!
-        @brief create a binary writer
+        /// iterator for JSON objects
+        typename object_t::iterator object_iterator;
+        /// iterator for JSON arrays
+        typename array_t::iterator array_iterator;
+        /// generic iterator for all other types
+        primitive_iterator_t primitive_iterator;
 
-        @param[in] adapter  output adapter to write to
-        */
-        explicit binary_writer(output_adapter_t<uint8_t> adapter)
-            : is_little_endian(binary_reader::little_endianess()), oa(adapter)
-        {
-            assert(oa);
-        }
+        /// create an uninitialized internal_iterator
+        internal_iterator() noexcept
+            : object_iterator(), array_iterator(), primitive_iterator()
+        {}
+    };
 
-        /*!
-        @brief[in] j  JSON value to serialize
-        */
-        void write_cbor(const basic_json& j)
+    /// proxy class for the iterator_wrapper functions
+    template<typename IteratorType>
+    class iteration_proxy
+    {
+      private:
+        /// helper class for iteration
+        class iteration_proxy_internal
         {
-            switch (j.type())
+          private:
+            /// the iterator
+            IteratorType anchor;
+            /// an index for arrays (used to create key names)
+            size_t array_index = 0;
+
+          public:
+            explicit iteration_proxy_internal(IteratorType it) noexcept
+                : anchor(it)
+            {}
+
+            /// dereference operator (needed for range-based for)
+            iteration_proxy_internal& operator*()
             {
-                case value_t::null:
-                {
-                    oa->write_character(0xf6);
-                    break;
-                }
+                return *this;
+            }
 
-                case value_t::boolean:
-                {
-                    oa->write_character(j.m_value.boolean ? 0xf5 : 0xf4);
-                    break;
-                }
+            /// increment operator (needed for range-based for)
+            iteration_proxy_internal& operator++()
+            {
+                ++anchor;
+                ++array_index;
 
-                case value_t::number_integer:
+                return *this;
+            }
+
+            /// inequality operator (needed for range-based for)
+            bool operator!= (const iteration_proxy_internal& o) const
+            {
+                return anchor != o.anchor;
+            }
+
+            /// return key of the iterator
+            typename basic_json::string_t key() const
+            {
+                assert(anchor.m_object != nullptr);
+
+                switch (anchor.m_object->type())
                 {
-                    if (j.m_value.number_integer >= 0)
+                    // use integer array index as key
+                    case value_t::array:
                     {
-                        // CBOR does not differentiate between positive signed
-                        // integers and unsigned integers. Therefore, we used the
-                        // code from the value_t::number_unsigned case here.
-                        if (j.m_value.number_integer <= 0x17)
-                        {
-                            write_number(static_cast<uint8_t>(j.m_value.number_integer));
-                        }
-                        else if (j.m_value.number_integer <= (std::numeric_limits<uint8_t>::max)())
-                        {
-                            oa->write_character(0x18);
-                            write_number(static_cast<uint8_t>(j.m_value.number_integer));
-                        }
-                        else if (j.m_value.number_integer <= (std::numeric_limits<uint16_t>::max)())
-                        {
-                            oa->write_character(0x19);
-                            write_number(static_cast<uint16_t>(j.m_value.number_integer));
-                        }
-                        else if (j.m_value.number_integer <= (std::numeric_limits<uint32_t>::max)())
-                        {
-                            oa->write_character(0x1a);
-                            write_number(static_cast<uint32_t>(j.m_value.number_integer));
-                        }
-                        else
-                        {
-                            oa->write_character(0x1b);
-                            write_number(static_cast<uint64_t>(j.m_value.number_integer));
-                        }
+                        return std::to_string(array_index);
                     }
-                    else
-                    {
-                        // The conversions below encode the sign in the first
-                        // byte, and the value is converted to a positive number.
-                        const auto positive_number = -1 - j.m_value.number_integer;
-                        if (j.m_value.number_integer >= -24)
-                        {
-                            write_number(static_cast<uint8_t>(0x20 + positive_number));
-                        }
-                        else if (positive_number <= (std::numeric_limits<uint8_t>::max)())
-                        {
-                            oa->write_character(0x38);
-                            write_number(static_cast<uint8_t>(positive_number));
-                        }
-                        else if (positive_number <= (std::numeric_limits<uint16_t>::max)())
-                        {
-                            oa->write_character(0x39);
-                            write_number(static_cast<uint16_t>(positive_number));
-                        }
-                        else if (positive_number <= (std::numeric_limits<uint32_t>::max)())
-                        {
-                            oa->write_character(0x3a);
-                            write_number(static_cast<uint32_t>(positive_number));
-                        }
-                        else
-                        {
-                            oa->write_character(0x3b);
-                            write_number(static_cast<uint64_t>(positive_number));
-                        }
-                    }
-                    break;
-                }
 
-                case value_t::number_unsigned:
-                {
-                    if (j.m_value.number_unsigned <= 0x17)
-                    {
-                        write_number(static_cast<uint8_t>(j.m_value.number_unsigned));
-                    }
-                    else if (j.m_value.number_unsigned <= (std::numeric_limits<uint8_t>::max)())
-                    {
-                        oa->write_character(0x18);
-                        write_number(static_cast<uint8_t>(j.m_value.number_unsigned));
-                    }
-                    else if (j.m_value.number_unsigned <= (std::numeric_limits<uint16_t>::max)())
-                    {
-                        oa->write_character(0x19);
-                        write_number(static_cast<uint16_t>(j.m_value.number_unsigned));
-                    }
-                    else if (j.m_value.number_unsigned <= (std::numeric_limits<uint32_t>::max)())
+                    // use key from the object
+                    case value_t::object:
                     {
-                        oa->write_character(0x1a);
-                        write_number(static_cast<uint32_t>(j.m_value.number_unsigned));
+                        return anchor.key();
                     }
-                    else
+
+                    // use an empty key for all primitive types
+                    default:
                     {
-                        oa->write_character(0x1b);
-                        write_number(static_cast<uint64_t>(j.m_value.number_unsigned));
+                        return "";
                     }
-                    break;
                 }
+            }
 
-                case value_t::number_float:
+            /// return value of the iterator
+            typename IteratorType::reference value() const
+            {
+                return anchor.value();
+            }
+        };
+
+        /// the container to iterate
+        typename IteratorType::reference container;
+
+      public:
+        /// construct iteration proxy from a container
+        explicit iteration_proxy(typename IteratorType::reference cont)
+            : container(cont)
+        {}
+
+        /// return iterator begin (needed for range-based for)
+        iteration_proxy_internal begin() noexcept
+        {
+            return iteration_proxy_internal(container.begin());
+        }
+
+        /// return iterator end (needed for range-based for)
+        iteration_proxy_internal end() noexcept
+        {
+            return iteration_proxy_internal(container.end());
+        }
+    };
+
+  public:
+    /*!
+    @brief a template for a random access iterator for the @ref basic_json class
+
+    This class implements a both iterators (iterator and const_iterator) for the
+    @ref basic_json class.
+
+    @note An iterator is called *initialized* when a pointer to a JSON value
+          has been set (e.g., by a constructor or a copy assignment). If the
+          iterator is default-constructed, it is *uninitialized* and most
+          methods are undefined. **The library uses assertions to detect calls
+          on uninitialized iterators.**
+
+    @requirement The class satisfies the following concept requirements:
+    - [RandomAccessIterator](http://en.cppreference.com/w/cpp/concept/RandomAccessIterator):
+      The iterator that can be moved to point (forward and backward) to any
+      element in constant time.
+
+    @since version 1.0.0, simplified in version 2.0.9
+    */
+    template<typename U>
+    class iter_impl : public std::iterator<std::random_access_iterator_tag, U>
+    {
+        /// allow basic_json to access private members
+        friend class basic_json;
+
+        // make sure U is basic_json or const basic_json
+        static_assert(std::is_same<U, basic_json>::value
+                      or std::is_same<U, const basic_json>::value,
+                      "iter_impl only accepts (const) basic_json");
+
+      public:
+        /// the type of the values when the iterator is dereferenced
+        using value_type = typename basic_json::value_type;
+        /// a type to represent differences between iterators
+        using difference_type = typename basic_json::difference_type;
+        /// defines a pointer to the type iterated over (value_type)
+        using pointer = typename std::conditional<std::is_const<U>::value,
+              typename basic_json::const_pointer,
+              typename basic_json::pointer>::type;
+        /// defines a reference to the type iterated over (value_type)
+        using reference = typename std::conditional<std::is_const<U>::value,
+              typename basic_json::const_reference,
+              typename basic_json::reference>::type;
+        /// the category of the iterator
+        using iterator_category = std::bidirectional_iterator_tag;
+
+        /// default constructor
+        iter_impl() = default;
+
+        /*!
+        @brief constructor for a given JSON instance
+        @param[in] object  pointer to a JSON object for this iterator
+        @pre object != nullptr
+        @post The iterator is initialized; i.e. `m_object != nullptr`.
+        */
+        explicit iter_impl(pointer object) noexcept
+            : m_object(object)
+        {
+            assert(m_object != nullptr);
+
+            switch (m_object->m_type)
+            {
+                case basic_json::value_t::object:
                 {
-                    // Double-Precision Float
-                    oa->write_character(0xfb);
-                    write_number(j.m_value.number_float);
+                    m_it.object_iterator = typename object_t::iterator();
                     break;
                 }
 
-                case value_t::string:
+                case basic_json::value_t::array:
                 {
-                    // step 1: write control byte and the string length
-                    const auto N = j.m_value.string->size();
-                    if (N <= 0x17)
-                    {
-                        write_number(static_cast<uint8_t>(0x60 + N));
-                    }
-                    else if (N <= 0xff)
-                    {
-                        oa->write_character(0x78);
-                        write_number(static_cast<uint8_t>(N));
-                    }
-                    else if (N <= 0xffff)
-                    {
-                        oa->write_character(0x79);
-                        write_number(static_cast<uint16_t>(N));
-                    }
-                    else if (N <= 0xffffffff)
-                    {
-                        oa->write_character(0x7a);
-                        write_number(static_cast<uint32_t>(N));
-                    }
-                    // LCOV_EXCL_START
-                    else if (N <= 0xffffffffffffffff)
-                    {
-                        oa->write_character(0x7b);
-                        write_number(static_cast<uint64_t>(N));
-                    }
-                    // LCOV_EXCL_STOP
-
-                    // step 2: write the string
-                    oa->write_characters(reinterpret_cast<const uint8_t*>(j.m_value.string->c_str()),
-                                         j.m_value.string->size());
+                    m_it.array_iterator = typename array_t::iterator();
                     break;
                 }
 
-                case value_t::array:
+                default:
                 {
-                    // step 1: write control byte and the array size
-                    const auto N = j.m_value.array->size();
-                    if (N <= 0x17)
-                    {
-                        write_number(static_cast<uint8_t>(0x80 + N));
-                    }
-                    else if (N <= 0xff)
-                    {
-                        oa->write_character(0x98);
-                        write_number(static_cast<uint8_t>(N));
-                    }
-                    else if (N <= 0xffff)
-                    {
-                        oa->write_character(0x99);
-                        write_number(static_cast<uint16_t>(N));
-                    }
-                    else if (N <= 0xffffffff)
-                    {
-                        oa->write_character(0x9a);
-                        write_number(static_cast<uint32_t>(N));
-                    }
-                    // LCOV_EXCL_START
-                    else if (N <= 0xffffffffffffffff)
-                    {
-                        oa->write_character(0x9b);
-                        write_number(static_cast<uint64_t>(N));
-                    }
-                    // LCOV_EXCL_STOP
-
-                    // step 2: write each element
-                    for (const auto& el : *j.m_value.array)
-                    {
-                        write_cbor(el);
-                    }
+                    m_it.primitive_iterator = primitive_iterator_t();
                     break;
                 }
+            }
+        }
 
-                case value_t::object:
-                {
-                    // step 1: write control byte and the object size
-                    const auto N = j.m_value.object->size();
-                    if (N <= 0x17)
-                    {
-                        write_number(static_cast<uint8_t>(0xa0 + N));
-                    }
-                    else if (N <= 0xff)
-                    {
-                        oa->write_character(0xb8);
-                        write_number(static_cast<uint8_t>(N));
-                    }
-                    else if (N <= 0xffff)
-                    {
-                        oa->write_character(0xb9);
-                        write_number(static_cast<uint16_t>(N));
-                    }
-                    else if (N <= 0xffffffff)
-                    {
-                        oa->write_character(0xba);
-                        write_number(static_cast<uint32_t>(N));
-                    }
-                    // LCOV_EXCL_START
-                    else if (N <= 0xffffffffffffffff)
-                    {
-                        oa->write_character(0xbb);
-                        write_number(static_cast<uint64_t>(N));
-                    }
-                    // LCOV_EXCL_STOP
+        /*!
+        @note The conventional copy constructor and copy assignment are
+              implicitly defined.
+              Combined with the following converting constructor and assignment,
+              they support: copy from iterator to iterator,
+                            copy from const iterator to const iterator,
+                            and conversion from iterator to const iterator.
+              However conversion from const iterator to iterator is not defined.
+        */
 
-                    // step 2: write each element
-                    for (const auto& el : *j.m_value.object)
-                    {
-                        write_cbor(el.first);
-                        write_cbor(el.second);
-                    }
+        /*!
+        @brief converting constructor
+        @param[in] other  non-const iterator to copy from
+        @note It is not checked whether @a other is initialized.
+        */
+        iter_impl(const iter_impl<basic_json>& other) noexcept
+            : m_object(other.m_object), m_it(other.m_it)
+        {}
+
+        /*!
+        @brief converting assignment
+        @param[in,out] other  non-const iterator to copy from
+        @return const/non-const iterator
+        @note It is not checked whether @a other is initialized.
+        */
+        iter_impl& operator=(const iter_impl<basic_json>& other) noexcept
+        {
+            m_object = other.m_object;
+            m_it = other.m_it;
+            return *this;
+        }
+
+      private:
+        /*!
+        @brief set the iterator to the first value
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        */
+        void set_begin() noexcept
+        {
+            assert(m_object != nullptr);
+
+            switch (m_object->m_type)
+            {
+                case basic_json::value_t::object:
+                {
+                    m_it.object_iterator = m_object->m_value.object->begin();
+                    break;
+                }
+
+                case basic_json::value_t::array:
+                {
+                    m_it.array_iterator = m_object->m_value.array->begin();
+                    break;
+                }
+
+                case basic_json::value_t::null:
+                {
+                    // set to end so begin()==end() is true: null is empty
+                    m_it.primitive_iterator.set_end();
                     break;
                 }
 
                 default:
                 {
+                    m_it.primitive_iterator.set_begin();
                     break;
                 }
             }
         }
 
         /*!
-        @brief[in] j  JSON value to serialize
+        @brief set the iterator past the last value
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
         */
-        void write_msgpack(const basic_json& j)
+        void set_end() noexcept
         {
-            switch (j.type())
+            assert(m_object != nullptr);
+
+            switch (m_object->m_type)
             {
-                case value_t::null:
+                case basic_json::value_t::object:
                 {
-                    // nil
-                    oa->write_character(0xc0);
+                    m_it.object_iterator = m_object->m_value.object->end();
                     break;
                 }
 
-                case value_t::boolean:
+                case basic_json::value_t::array:
                 {
-                    // true and false
-                    oa->write_character(j.m_value.boolean ? 0xc3 : 0xc2);
+                    m_it.array_iterator = m_object->m_value.array->end();
                     break;
                 }
 
-                case value_t::number_integer:
+                default:
                 {
-                    if (j.m_value.number_integer >= 0)
-                    {
-                        // MessagePack does not differentiate between positive
-                        // signed integers and unsigned integers. Therefore, we
-                        // used the code from the value_t::number_unsigned case
-                        // here.
-                        if (j.m_value.number_unsigned < 128)
-                        {
-                            // positive fixnum
-                            write_number(static_cast<uint8_t>(j.m_value.number_integer));
-                        }
-                        else if (j.m_value.number_unsigned <= (std::numeric_limits<uint8_t>::max)())
-                        {
-                            // uint 8
-                            oa->write_character(0xcc);
-                            write_number(static_cast<uint8_t>(j.m_value.number_integer));
-                        }
-                        else if (j.m_value.number_unsigned <= (std::numeric_limits<uint16_t>::max)())
-                        {
-                            // uint 16
-                            oa->write_character(0xcd);
-                            write_number(static_cast<uint16_t>(j.m_value.number_integer));
-                        }
-                        else if (j.m_value.number_unsigned <= (std::numeric_limits<uint32_t>::max)())
-                        {
-                            // uint 32
-                            oa->write_character(0xce);
-                            write_number(static_cast<uint32_t>(j.m_value.number_integer));
-                        }
-                        else if (j.m_value.number_unsigned <= (std::numeric_limits<uint64_t>::max)())
-                        {
-                            // uint 64
-                            oa->write_character(0xcf);
-                            write_number(static_cast<uint64_t>(j.m_value.number_integer));
-                        }
-                    }
-                    else
-                    {
-                        if (j.m_value.number_integer >= -32)
-                        {
-                            // negative fixnum
-                            write_number(static_cast<int8_t>(j.m_value.number_integer));
-                        }
-                        else if (j.m_value.number_integer >= (std::numeric_limits<int8_t>::min)() and j.m_value.number_integer <= (std::numeric_limits<int8_t>::max)())
-                        {
-                            // int 8
-                            oa->write_character(0xd0);
-                            write_number(static_cast<int8_t>(j.m_value.number_integer));
-                        }
-                        else if (j.m_value.number_integer >= (std::numeric_limits<int16_t>::min)() and j.m_value.number_integer <= (std::numeric_limits<int16_t>::max)())
-                        {
-                            // int 16
-                            oa->write_character(0xd1);
-                            write_number(static_cast<int16_t>(j.m_value.number_integer));
-                        }
-                        else if (j.m_value.number_integer >= (std::numeric_limits<int32_t>::min)() and j.m_value.number_integer <= (std::numeric_limits<int32_t>::max)())
-                        {
-                            // int 32
-                            oa->write_character(0xd2);
-                            write_number(static_cast<int32_t>(j.m_value.number_integer));
-                        }
-                        else if (j.m_value.number_integer >= (std::numeric_limits<int64_t>::min)() and j.m_value.number_integer <= (std::numeric_limits<int64_t>::max)())
-                        {
-                            // int 64
-                            oa->write_character(0xd3);
-                            write_number(static_cast<int64_t>(j.m_value.number_integer));
-                        }
-                    }
+                    m_it.primitive_iterator.set_end();
                     break;
                 }
+            }
+        }
 
-                case value_t::number_unsigned:
+      public:
+        /*!
+        @brief return a reference to the value pointed to by the iterator
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        */
+        reference operator*() const
+        {
+            assert(m_object != nullptr);
+
+            switch (m_object->m_type)
+            {
+                case basic_json::value_t::object:
                 {
-                    if (j.m_value.number_unsigned < 128)
-                    {
-                        // positive fixnum
-                        write_number(static_cast<uint8_t>(j.m_value.number_integer));
-                    }
-                    else if (j.m_value.number_unsigned <= (std::numeric_limits<uint8_t>::max)())
-                    {
-                        // uint 8
-                        oa->write_character(0xcc);
-                        write_number(static_cast<uint8_t>(j.m_value.number_integer));
-                    }
-                    else if (j.m_value.number_unsigned <= (std::numeric_limits<uint16_t>::max)())
-                    {
-                        // uint 16
-                        oa->write_character(0xcd);
-                        write_number(static_cast<uint16_t>(j.m_value.number_integer));
-                    }
-                    else if (j.m_value.number_unsigned <= (std::numeric_limits<uint32_t>::max)())
-                    {
-                        // uint 32
-                        oa->write_character(0xce);
-                        write_number(static_cast<uint32_t>(j.m_value.number_integer));
-                    }
-                    else if (j.m_value.number_unsigned <= (std::numeric_limits<uint64_t>::max)())
-                    {
-                        // uint 64
-                        oa->write_character(0xcf);
-                        write_number(static_cast<uint64_t>(j.m_value.number_integer));
-                    }
-                    break;
+                    assert(m_it.object_iterator != m_object->m_value.object->end());
+                    return m_it.object_iterator->second;
                 }
 
-                case value_t::number_float:
+                case basic_json::value_t::array:
                 {
-                    // float 64
-                    oa->write_character(0xcb);
-                    write_number(j.m_value.number_float);
-                    break;
+                    assert(m_it.array_iterator != m_object->m_value.array->end());
+                    return *m_it.array_iterator;
                 }
 
-                case value_t::string:
+                case basic_json::value_t::null:
                 {
-                    // step 1: write control byte and the string length
-                    const auto N = j.m_value.string->size();
-                    if (N <= 31)
-                    {
-                        // fixstr
-                        write_number(static_cast<uint8_t>(0xa0 | N));
-                    }
-                    else if (N <= 255)
-                    {
-                        // str 8
-                        oa->write_character(0xd9);
-                        write_number(static_cast<uint8_t>(N));
-                    }
-                    else if (N <= 65535)
-                    {
-                        // str 16
-                        oa->write_character(0xda);
-                        write_number(static_cast<uint16_t>(N));
-                    }
-                    else if (N <= 4294967295)
+                    JSON_THROW(invalid_iterator::create(214, "cannot get value"));
+                }
+
+                default:
+                {
+                    if (m_it.primitive_iterator.is_begin())
                     {
-                        // str 32
-                        oa->write_character(0xdb);
-                        write_number(static_cast<uint32_t>(N));
+                        return *m_object;
                     }
 
-                    // step 2: write the string
-                    oa->write_characters(reinterpret_cast<const uint8_t*>(j.m_value.string->c_str()),
-                                         j.m_value.string->size());
-                    break;
+                    JSON_THROW(invalid_iterator::create(214, "cannot get value"));
                 }
+            }
+        }
 
-                case value_t::array:
+        /*!
+        @brief dereference the iterator
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        */
+        pointer operator->() const
+        {
+            assert(m_object != nullptr);
+
+            switch (m_object->m_type)
+            {
+                case basic_json::value_t::object:
                 {
-                    // step 1: write control byte and the array size
-                    const auto N = j.m_value.array->size();
-                    if (N <= 15)
-                    {
-                        // fixarray
-                        write_number(static_cast<uint8_t>(0x90 | N));
-                    }
-                    else if (N <= 0xffff)
-                    {
-                        // array 16
-                        oa->write_character(0xdc);
-                        write_number(static_cast<uint16_t>(N));
-                    }
-                    else if (N <= 0xffffffff)
-                    {
-                        // array 32
-                        oa->write_character(0xdd);
-                        write_number(static_cast<uint32_t>(N));
-                    }
+                    assert(m_it.object_iterator != m_object->m_value.object->end());
+                    return &(m_it.object_iterator->second);
+                }
 
-                    // step 2: write each element
-                    for (const auto& el : *j.m_value.array)
-                    {
-                        write_msgpack(el);
-                    }
-                    break;
+                case basic_json::value_t::array:
+                {
+                    assert(m_it.array_iterator != m_object->m_value.array->end());
+                    return &*m_it.array_iterator;
                 }
 
-                case value_t::object:
+                default:
                 {
-                    // step 1: write control byte and the object size
-                    const auto N = j.m_value.object->size();
-                    if (N <= 15)
-                    {
-                        // fixmap
-                        write_number(static_cast<uint8_t>(0x80 | (N & 0xf)));
-                    }
-                    else if (N <= 65535)
-                    {
-                        // map 16
-                        oa->write_character(0xde);
-                        write_number(static_cast<uint16_t>(N));
-                    }
-                    else if (N <= 4294967295)
+                    if (m_it.primitive_iterator.is_begin())
                     {
-                        // map 32
-                        oa->write_character(0xdf);
-                        write_number(static_cast<uint32_t>(N));
+                        return m_object;
                     }
 
-                    // step 2: write each element
-                    for (const auto& el : *j.m_value.object)
-                    {
-                        write_msgpack(el.first);
-                        write_msgpack(el.second);
-                    }
+                    JSON_THROW(invalid_iterator::create(214, "cannot get value"));
+                }
+            }
+        }
+
+        /*!
+        @brief post-increment (it++)
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        */
+        iter_impl operator++(int)
+        {
+            auto result = *this;
+            ++(*this);
+            return result;
+        }
+
+        /*!
+        @brief pre-increment (++it)
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        */
+        iter_impl& operator++()
+        {
+            assert(m_object != nullptr);
+
+            switch (m_object->m_type)
+            {
+                case basic_json::value_t::object:
+                {
+                    std::advance(m_it.object_iterator, 1);
+                    break;
+                }
+
+                case basic_json::value_t::array:
+                {
+                    std::advance(m_it.array_iterator, 1);
                     break;
                 }
 
                 default:
                 {
+                    ++m_it.primitive_iterator;
                     break;
                 }
             }
-        }
 
-      private:
-        /*
-        @brief write a number to output input
+            return *this;
+        }
 
-        @param[in] n number of type @a NumberType
-        @tparam NumberType the type of the number
+        /*!
+        @brief post-decrement (it--)
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        */
+        iter_impl operator--(int)
+        {
+            auto result = *this;
+            --(*this);
+            return result;
+        }
 
-        @note This function needs to respect the system's endianess, because
-              bytes in CBOR and MessagePack are stored in network order (big
-              endian) and therefore need reordering on little endian systems.
+        /*!
+        @brief pre-decrement (--it)
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
         */
-        template<typename NumberType>
-        void write_number(NumberType n)
+        iter_impl& operator--()
         {
-            // step 1: write number to array of length NumberType
-            std::array<uint8_t, sizeof(NumberType)> vec;
-            std::memcpy(vec.data(), &n, sizeof(NumberType));
+            assert(m_object != nullptr);
 
-            // step 2: write array to output (with possible reordering)
-            if (is_little_endian)
+            switch (m_object->m_type)
             {
-                // reverse byte order prior to conversion if necessary
-                std::reverse(vec.begin(), vec.end());
+                case basic_json::value_t::object:
+                {
+                    std::advance(m_it.object_iterator, -1);
+                    break;
+                }
+
+                case basic_json::value_t::array:
+                {
+                    std::advance(m_it.array_iterator, -1);
+                    break;
+                }
+
+                default:
+                {
+                    --m_it.primitive_iterator;
+                    break;
+                }
             }
 
-            oa->write_characters(vec.data(), sizeof(NumberType));
+            return *this;
         }
 
-      private:
-        /// whether we can assume little endianess
-        const bool is_little_endian = true;
-
-        /// the output
-        output_adapter_t<uint8_t> oa = nullptr;
-    };
+        /*!
+        @brief  comparison: equal
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        */
+        bool operator==(const iter_impl& other) const
+        {
+            // if objects are not the same, the comparison is undefined
+            if (m_object != other.m_object)
+            {
+                JSON_THROW(invalid_iterator::create(212, "cannot compare iterators of different containers"));
+            }
 
-  public:
-    /*!
-    @brief create a CBOR serialization of a given JSON value
+            assert(m_object != nullptr);
 
-    Serializes a given JSON value @a j to a byte vector using the CBOR (Concise
-    Binary Object Representation) serialization format. CBOR is a binary
-    serialization format which aims to be more compact than JSON itself, yet
-    more efficient to parse.
+            switch (m_object->m_type)
+            {
+                case basic_json::value_t::object:
+                {
+                    return (m_it.object_iterator == other.m_it.object_iterator);
+                }
 
-    The library uses the following mapping from JSON values types to
-    CBOR types according to the CBOR specification (RFC 7049):
+                case basic_json::value_t::array:
+                {
+                    return (m_it.array_iterator == other.m_it.array_iterator);
+                }
 
-    JSON value type | value/range                                | CBOR type                          | first byte
-    --------------- | ------------------------------------------ | ---------------------------------- | ---------------
-    null            | `null`                                     | Null                               | 0xf6
-    boolean         | `true`                                     | True                               | 0xf5
-    boolean         | `false`                                    | False                              | 0xf4
-    number_integer  | -9223372036854775808..-2147483649          | Negative integer (8 bytes follow)  | 0x3b
-    number_integer  | -2147483648..-32769                        | Negative integer (4 bytes follow)  | 0x3a
-    number_integer  | -32768..-129                               | Negative integer (2 bytes follow)  | 0x39
-    number_integer  | -128..-25                                  | Negative integer (1 byte follow)   | 0x38
-    number_integer  | -24..-1                                    | Negative integer                   | 0x20..0x37
-    number_integer  | 0..23                                      | Integer                            | 0x00..0x17
-    number_integer  | 24..255                                    | Unsigned integer (1 byte follow)   | 0x18
-    number_integer  | 256..65535                                 | Unsigned integer (2 bytes follow)  | 0x19
-    number_integer  | 65536..4294967295                          | Unsigned integer (4 bytes follow)  | 0x1a
-    number_integer  | 4294967296..18446744073709551615           | Unsigned integer (8 bytes follow)  | 0x1b
-    number_unsigned | 0..23                                      | Integer                            | 0x00..0x17
-    number_unsigned | 24..255                                    | Unsigned integer (1 byte follow)   | 0x18
-    number_unsigned | 256..65535                                 | Unsigned integer (2 bytes follow)  | 0x19
-    number_unsigned | 65536..4294967295                          | Unsigned integer (4 bytes follow)  | 0x1a
-    number_unsigned | 4294967296..18446744073709551615           | Unsigned integer (8 bytes follow)  | 0x1b
-    number_float    | *any value*                                | Double-Precision Float             | 0xfb
-    string          | *length*: 0..23                            | UTF-8 string                       | 0x60..0x77
-    string          | *length*: 23..255                          | UTF-8 string (1 byte follow)       | 0x78
-    string          | *length*: 256..65535                       | UTF-8 string (2 bytes follow)      | 0x79
-    string          | *length*: 65536..4294967295                | UTF-8 string (4 bytes follow)      | 0x7a
-    string          | *length*: 4294967296..18446744073709551615 | UTF-8 string (8 bytes follow)      | 0x7b
-    array           | *size*: 0..23                              | array                              | 0x80..0x97
-    array           | *size*: 23..255                            | array (1 byte follow)              | 0x98
-    array           | *size*: 256..65535                         | array (2 bytes follow)             | 0x99
-    array           | *size*: 65536..4294967295                  | array (4 bytes follow)             | 0x9a
-    array           | *size*: 4294967296..18446744073709551615   | array (8 bytes follow)             | 0x9b
-    object          | *size*: 0..23                              | map                                | 0xa0..0xb7
-    object          | *size*: 23..255                            | map (1 byte follow)                | 0xb8
-    object          | *size*: 256..65535                         | map (2 bytes follow)               | 0xb9
-    object          | *size*: 65536..4294967295                  | map (4 bytes follow)               | 0xba
-    object          | *size*: 4294967296..18446744073709551615   | map (8 bytes follow)               | 0xbb
+                default:
+                {
+                    return (m_it.primitive_iterator == other.m_it.primitive_iterator);
+                }
+            }
+        }
 
-    @note The mapping is **complete** in the sense that any JSON value type
-          can be converted to a CBOR value.
+        /*!
+        @brief  comparison: not equal
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        */
+        bool operator!=(const iter_impl& other) const
+        {
+            return not operator==(other);
+        }
 
-    @note The following CBOR types are not used in the conversion:
-          - byte strings (0x40..0x5f)
-          - UTF-8 strings terminated by "break" (0x7f)
-          - arrays terminated by "break" (0x9f)
-          - maps terminated by "break" (0xbf)
-          - date/time (0xc0..0xc1)
-          - bignum (0xc2..0xc3)
-          - decimal fraction (0xc4)
-          - bigfloat (0xc5)
-          - tagged items (0xc6..0xd4, 0xd8..0xdb)
-          - expected conversions (0xd5..0xd7)
-          - simple values (0xe0..0xf3, 0xf8)
-          - undefined (0xf7)
-          - half and single-precision floats (0xf9-0xfa)
-          - break (0xff)
+        /*!
+        @brief  comparison: smaller
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        */
+        bool operator<(const iter_impl& other) const
+        {
+            // if objects are not the same, the comparison is undefined
+            if (m_object != other.m_object)
+            {
+                JSON_THROW(invalid_iterator::create(212, "cannot compare iterators of different containers"));
+            }
 
-    @param[in] j  JSON value to serialize
-    @return MessagePack serialization as byte vector
+            assert(m_object != nullptr);
 
-    @complexity Linear in the size of the JSON value @a j.
+            switch (m_object->m_type)
+            {
+                case basic_json::value_t::object:
+                {
+                    JSON_THROW(invalid_iterator::create(213, "cannot compare order of object iterators"));
+                }
 
-    @liveexample{The example shows the serialization of a JSON value to a byte
-    vector in CBOR format.,to_cbor}
+                case basic_json::value_t::array:
+                {
+                    return (m_it.array_iterator < other.m_it.array_iterator);
+                }
 
-    @sa http://cbor.io
-    @sa @ref from_cbor(const std::vector<uint8_t>&, const size_t) for the
-        analogous deserialization
-    @sa @ref to_msgpack(const basic_json& for the related MessagePack format
+                default:
+                {
+                    return (m_it.primitive_iterator < other.m_it.primitive_iterator);
+                }
+            }
+        }
 
-    @since version 2.0.9
-    */
-    static std::vector<uint8_t> to_cbor(const basic_json& j)
-    {
-        std::vector<uint8_t> result;
-        binary_writer bw(output_adapter<uint8_t>::create(result));
-        bw.write_cbor(j);
-        return result;
-    }
+        /*!
+        @brief  comparison: less than or equal
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        */
+        bool operator<=(const iter_impl& other) const
+        {
+            return not other.operator < (*this);
+        }
 
-    /*!
-    @brief create a MessagePack serialization of a given JSON value
+        /*!
+        @brief  comparison: greater than
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        */
+        bool operator>(const iter_impl& other) const
+        {
+            return not operator<=(other);
+        }
 
-    Serializes a given JSON value @a j to a byte vector using the MessagePack
-    serialization format. MessagePack is a binary serialization format which
-    aims to be more compact than JSON itself, yet more efficient to parse.
+        /*!
+        @brief  comparison: greater than or equal
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        */
+        bool operator>=(const iter_impl& other) const
+        {
+            return not operator<(other);
+        }
 
-    The library uses the following mapping from JSON values types to
-    MessagePack types according to the MessagePack specification:
+        /*!
+        @brief  add to iterator
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        */
+        iter_impl& operator+=(difference_type i)
+        {
+            assert(m_object != nullptr);
 
-    JSON value type | value/range                       | MessagePack type | first byte
-    --------------- | --------------------------------- | ---------------- | ----------
-    null            | `null`                            | nil              | 0xc0
-    boolean         | `true`                            | true             | 0xc3
-    boolean         | `false`                           | false            | 0xc2
-    number_integer  | -9223372036854775808..-2147483649 | int64            | 0xd3
-    number_integer  | -2147483648..-32769               | int32            | 0xd2
-    number_integer  | -32768..-129                      | int16            | 0xd1
-    number_integer  | -128..-33                         | int8             | 0xd0
-    number_integer  | -32..-1                           | negative fixint  | 0xe0..0xff
-    number_integer  | 0..127                            | positive fixint  | 0x00..0x7f
-    number_integer  | 128..255                          | uint 8           | 0xcc
-    number_integer  | 256..65535                        | uint 16          | 0xcd
-    number_integer  | 65536..4294967295                 | uint 32          | 0xce
-    number_integer  | 4294967296..18446744073709551615  | uint 64          | 0xcf
-    number_unsigned | 0..127                            | positive fixint  | 0x00..0x7f
-    number_unsigned | 128..255                          | uint 8           | 0xcc
-    number_unsigned | 256..65535                        | uint 16          | 0xcd
-    number_unsigned | 65536..4294967295                 | uint 32          | 0xce
-    number_unsigned | 4294967296..18446744073709551615  | uint 64          | 0xcf
-    number_float    | *any value*                       | float 64         | 0xcb
-    string          | *length*: 0..31                   | fixstr           | 0xa0..0xbf
-    string          | *length*: 32..255                 | str 8            | 0xd9
-    string          | *length*: 256..65535              | str 16           | 0xda
-    string          | *length*: 65536..4294967295       | str 32           | 0xdb
-    array           | *size*: 0..15                     | fixarray         | 0x90..0x9f
-    array           | *size*: 16..65535                 | array 16         | 0xdc
-    array           | *size*: 65536..4294967295         | array 32         | 0xdd
-    object          | *size*: 0..15                     | fix map          | 0x80..0x8f
-    object          | *size*: 16..65535                 | map 16           | 0xde
-    object          | *size*: 65536..4294967295         | map 32           | 0xdf
+            switch (m_object->m_type)
+            {
+                case basic_json::value_t::object:
+                {
+                    JSON_THROW(invalid_iterator::create(209, "cannot use offsets with object iterators"));
+                }
 
-    @note The mapping is **complete** in the sense that any JSON value type
-          can be converted to a MessagePack value.
+                case basic_json::value_t::array:
+                {
+                    std::advance(m_it.array_iterator, i);
+                    break;
+                }
 
-    @note The following values can **not** be converted to a MessagePack value:
-          - strings with more than 4294967295 bytes
-          - arrays with more than 4294967295 elements
-          - objects with more than 4294967295 elements
+                default:
+                {
+                    m_it.primitive_iterator += i;
+                    break;
+                }
+            }
 
-    @note The following MessagePack types are not used in the conversion:
-          - bin 8 - bin 32 (0xc4..0xc6)
-          - ext 8 - ext 32 (0xc7..0xc9)
-          - float 32 (0xca)
-          - fixext 1 - fixext 16 (0xd4..0xd8)
+            return *this;
+        }
 
-    @note Any MessagePack output created @ref to_msgpack can be successfully
-          parsed by @ref from_msgpack.
+        /*!
+        @brief  subtract from iterator
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        */
+        iter_impl& operator-=(difference_type i)
+        {
+            return operator+=(-i);
+        }
 
-    @param[in] j  JSON value to serialize
-    @return MessagePack serialization as byte vector
+        /*!
+        @brief  add to iterator
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        */
+        iter_impl operator+(difference_type i) const
+        {
+            auto result = *this;
+            result += i;
+            return result;
+        }
 
-    @complexity Linear in the size of the JSON value @a j.
+        /*!
+        @brief  addition of distance and iterator
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        */
+        friend iter_impl operator+(difference_type i, const iter_impl& it)
+        {
+            auto result = it;
+            result += i;
+            return result;
+        }
 
-    @liveexample{The example shows the serialization of a JSON value to a byte
-    vector in MessagePack format.,to_msgpack}
+        /*!
+        @brief  subtract from iterator
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        */
+        iter_impl operator-(difference_type i) const
+        {
+            auto result = *this;
+            result -= i;
+            return result;
+        }
 
-    @sa http://msgpack.org
-    @sa @ref from_msgpack(const std::vector<uint8_t>&, const size_t) for the
-        analogous deserialization
-    @sa @ref to_cbor(const basic_json& for the related CBOR format
+        /*!
+        @brief  return difference
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        */
+        difference_type operator-(const iter_impl& other) const
+        {
+            assert(m_object != nullptr);
 
-    @since version 2.0.9
-    */
-    static std::vector<uint8_t> to_msgpack(const basic_json& j)
-    {
-        std::vector<uint8_t> result;
-        binary_writer bw(output_adapter<uint8_t>::create(result));
-        bw.write_msgpack(j);
-        return result;
-    }
+            switch (m_object->m_type)
+            {
+                case basic_json::value_t::object:
+                {
+                    JSON_THROW(invalid_iterator::create(209, "cannot use offsets with object iterators"));
+                }
 
-    /*!
-    @brief create a JSON value from a byte vector in CBOR format
+                case basic_json::value_t::array:
+                {
+                    return m_it.array_iterator - other.m_it.array_iterator;
+                }
 
-    Deserializes a given byte vector @a v to a JSON value using the CBOR
-    (Concise Binary Object Representation) serialization format.
+                default:
+                {
+                    return m_it.primitive_iterator - other.m_it.primitive_iterator;
+                }
+            }
+        }
 
-    The library maps CBOR types to JSON value types as follows:
+        /*!
+        @brief  access to successor
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        */
+        reference operator[](difference_type n) const
+        {
+            assert(m_object != nullptr);
 
-    CBOR type              | JSON value type | first byte
-    ---------------------- | --------------- | ----------
-    Integer                | number_unsigned | 0x00..0x17
-    Unsigned integer       | number_unsigned | 0x18
-    Unsigned integer       | number_unsigned | 0x19
-    Unsigned integer       | number_unsigned | 0x1a
-    Unsigned integer       | number_unsigned | 0x1b
-    Negative integer       | number_integer  | 0x20..0x37
-    Negative integer       | number_integer  | 0x38
-    Negative integer       | number_integer  | 0x39
-    Negative integer       | number_integer  | 0x3a
-    Negative integer       | number_integer  | 0x3b
-    Negative integer       | number_integer  | 0x40..0x57
-    UTF-8 string           | string          | 0x60..0x77
-    UTF-8 string           | string          | 0x78
-    UTF-8 string           | string          | 0x79
-    UTF-8 string           | string          | 0x7a
-    UTF-8 string           | string          | 0x7b
-    UTF-8 string           | string          | 0x7f
-    array                  | array           | 0x80..0x97
-    array                  | array           | 0x98
-    array                  | array           | 0x99
-    array                  | array           | 0x9a
-    array                  | array           | 0x9b
-    array                  | array           | 0x9f
-    map                    | object          | 0xa0..0xb7
-    map                    | object          | 0xb8
-    map                    | object          | 0xb9
-    map                    | object          | 0xba
-    map                    | object          | 0xbb
-    map                    | object          | 0xbf
-    False                  | `false`         | 0xf4
-    True                   | `true`          | 0xf5
-    Nill                   | `null`          | 0xf6
-    Half-Precision Float   | number_float    | 0xf9
-    Single-Precision Float | number_float    | 0xfa
-    Double-Precision Float | number_float    | 0xfb
+            switch (m_object->m_type)
+            {
+                case basic_json::value_t::object:
+                {
+                    JSON_THROW(invalid_iterator::create(208, "cannot use operator[] for object iterators"));
+                }
 
-    @warning The mapping is **incomplete** in the sense that not all CBOR
-             types can be converted to a JSON value. The following CBOR types
-             are not supported and will yield parse errors (parse_error.112):
-             - byte strings (0x40..0x5f)
-             - date/time (0xc0..0xc1)
-             - bignum (0xc2..0xc3)
-             - decimal fraction (0xc4)
-             - bigfloat (0xc5)
-             - tagged items (0xc6..0xd4, 0xd8..0xdb)
-             - expected conversions (0xd5..0xd7)
-             - simple values (0xe0..0xf3, 0xf8)
-             - undefined (0xf7)
+                case basic_json::value_t::array:
+                {
+                    return *std::next(m_it.array_iterator, n);
+                }
 
-    @warning CBOR allows map keys of any type, whereas JSON only allows
-             strings as keys in object values. Therefore, CBOR maps with keys
-             other than UTF-8 strings are rejected (parse_error.113).
+                case basic_json::value_t::null:
+                {
+                    JSON_THROW(invalid_iterator::create(214, "cannot get value"));
+                }
 
-    @note Any CBOR output created @ref to_cbor can be successfully parsed by
-          @ref from_cbor.
+                default:
+                {
+                    if (m_it.primitive_iterator.get_value() == -n)
+                    {
+                        return *m_object;
+                    }
 
-    @param[in] v  a byte vector in CBOR format
-    @param[in] start_index the index to start reading from @a v (0 by default)
-    @return deserialized JSON value
+                    JSON_THROW(invalid_iterator::create(214, "cannot get value"));
+                }
+            }
+        }
 
-    @throw parse_error.110 if the given vector ends prematurely
-    @throw parse_error.112 if unsupported features from CBOR were
-    used in the given vector @a v or if the input is not valid CBOR
-    @throw parse_error.113 if a string was expected as map key, but not found
+        /*!
+        @brief  return the key of an object iterator
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        */
+        typename object_t::key_type key() const
+        {
+            assert(m_object != nullptr);
 
-    @complexity Linear in the size of the byte vector @a v.
+            if (m_object->is_object())
+            {
+                return m_it.object_iterator->first;
+            }
 
-    @liveexample{The example shows the deserialization of a byte vector in CBOR
-    format to a JSON value.,from_cbor}
+            JSON_THROW(invalid_iterator::create(207, "cannot use key() for non-object iterators"));
+        }
 
-    @sa http://cbor.io
-    @sa @ref to_cbor(const basic_json&) for the analogous serialization
-    @sa @ref from_msgpack(const std::vector<uint8_t>&, const size_t) for the
-        related MessagePack format
+        /*!
+        @brief  return the value of an iterator
+        @pre The iterator is initialized; i.e. `m_object != nullptr`.
+        */
+        reference value() const
+        {
+            return operator*();
+        }
 
-    @since version 2.0.9, parameter @a start_index since 2.1.1
+      private:
+        /// associated JSON instance
+        pointer m_object = nullptr;
+        /// the actual iterator of the associated instance
+        struct internal_iterator m_it = internal_iterator();
+    };
+
+    /*!
+    @brief a template for a reverse iterator class
+
+    @tparam Base the base iterator type to reverse. Valid types are @ref
+    iterator (to create @ref reverse_iterator) and @ref const_iterator (to
+    create @ref const_reverse_iterator).
+
+    @requirement The class satisfies the following concept requirements:
+    - [RandomAccessIterator](http://en.cppreference.com/w/cpp/concept/RandomAccessIterator):
+      The iterator that can be moved to point (forward and backward) to any
+      element in constant time.
+    - [OutputIterator](http://en.cppreference.com/w/cpp/concept/OutputIterator):
+      It is possible to write to the pointed-to element (only if @a Base is
+      @ref iterator).
+
+    @since version 1.0.0
     */
-    static basic_json from_cbor(const std::vector<uint8_t>& v,
-                                const size_t start_index = 0)
+    template<typename Base>
+    class json_reverse_iterator : public std::reverse_iterator<Base>
     {
-        binary_reader br(detail::input_adapter_factory::create(v.begin() + static_cast<difference_type>(start_index), v.end()));
-        return br.parse_cbor();
-    }
+      public:
+        /// shortcut to the reverse iterator adaptor
+        using base_iterator = std::reverse_iterator<Base>;
+        /// the reference type for the pointed-to element
+        using reference = typename Base::reference;
 
+        /// create reverse iterator from iterator
+        json_reverse_iterator(const typename base_iterator::iterator_type& it) noexcept
+            : base_iterator(it)
+        {}
 
-    /*!
-    @brief create a JSON value from a byte vector in MessagePack format
+        /// create reverse iterator from base class
+        json_reverse_iterator(const base_iterator& it) noexcept
+            : base_iterator(it)
+        {}
 
-    Deserializes a given byte vector @a v to a JSON value using the MessagePack
-    serialization format.
+        /// post-increment (it++)
+        json_reverse_iterator operator++(int)
+        {
+            return static_cast<json_reverse_iterator>(base_iterator::operator++(1));
+        }
 
-    The library maps MessagePack types to JSON value types as follows:
+        /// pre-increment (++it)
+        json_reverse_iterator& operator++()
+        {
+            return static_cast<json_reverse_iterator&>(base_iterator::operator++());
+        }
 
-    MessagePack type | JSON value type | first byte
-    ---------------- | --------------- | ----------
-    positive fixint  | number_unsigned | 0x00..0x7f
-    fixmap           | object          | 0x80..0x8f
-    fixarray         | array           | 0x90..0x9f
-    fixstr           | string          | 0xa0..0xbf
-    nil              | `null`          | 0xc0
-    false            | `false`         | 0xc2
-    true             | `true`          | 0xc3
-    float 32         | number_float    | 0xca
-    float 64         | number_float    | 0xcb
-    uint 8           | number_unsigned | 0xcc
-    uint 16          | number_unsigned | 0xcd
-    uint 32          | number_unsigned | 0xce
-    uint 64          | number_unsigned | 0xcf
-    int 8            | number_integer  | 0xd0
-    int 16           | number_integer  | 0xd1
-    int 32           | number_integer  | 0xd2
-    int 64           | number_integer  | 0xd3
-    str 8            | string          | 0xd9
-    str 16           | string          | 0xda
-    str 32           | string          | 0xdb
-    array 16         | array           | 0xdc
-    array 32         | array           | 0xdd
-    map 16           | object          | 0xde
-    map 32           | object          | 0xdf
-    negative fixint  | number_integer  | 0xe0-0xff
+        /// post-decrement (it--)
+        json_reverse_iterator operator--(int)
+        {
+            return static_cast<json_reverse_iterator>(base_iterator::operator--(1));
+        }
 
-    @warning The mapping is **incomplete** in the sense that not all
-             MessagePack types can be converted to a JSON value. The following
-             MessagePack types are not supported and will yield parse errors:
-              - bin 8 - bin 32 (0xc4..0xc6)
-              - ext 8 - ext 32 (0xc7..0xc9)
-              - fixext 1 - fixext 16 (0xd4..0xd8)
+        /// pre-decrement (--it)
+        json_reverse_iterator& operator--()
+        {
+            return static_cast<json_reverse_iterator&>(base_iterator::operator--());
+        }
 
-    @note Any MessagePack output created @ref to_msgpack can be successfully
-          parsed by @ref from_msgpack.
+        /// add to iterator
+        json_reverse_iterator& operator+=(difference_type i)
+        {
+            return static_cast<json_reverse_iterator&>(base_iterator::operator+=(i));
+        }
 
-    @param[in] v  a byte vector in MessagePack format
-    @param[in] start_index the index to start reading from @a v (0 by default)
-    @return deserialized JSON value
+        /// add to iterator
+        json_reverse_iterator operator+(difference_type i) const
+        {
+            return static_cast<json_reverse_iterator>(base_iterator::operator+(i));
+        }
 
-    @throw parse_error.110 if the given vector ends prematurely
-    @throw parse_error.112 if unsupported features from MessagePack were
-    used in the given vector @a v or if the input is not valid MessagePack
-    @throw parse_error.113 if a string was expected as map key, but not found
+        /// subtract from iterator
+        json_reverse_iterator operator-(difference_type i) const
+        {
+            return static_cast<json_reverse_iterator>(base_iterator::operator-(i));
+        }
 
-    @complexity Linear in the size of the byte vector @a v.
+        /// return difference
+        difference_type operator-(const json_reverse_iterator& other) const
+        {
+            return base_iterator(*this) - base_iterator(other);
+        }
+
+        /// access to successor
+        reference operator[](difference_type n) const
+        {
+            return *(this->operator+(n));
+        }
+
+        /// return the key of an object iterator
+        typename object_t::key_type key() const
+        {
+            auto it = --this->base();
+            return it.key();
+        }
+
+        /// return the value of an iterator
+        reference value() const
+        {
+            auto it = --this->base();
+            return it.operator * ();
+        }
+    };
+
+
+  private:
+    //////////////////////////////////////////
+    // binary serialization/deserialization //
+    //////////////////////////////////////////
+
+    /// @name binary serialization/deserialization support
+    /// @{
+
+    /*!
+    @brief deserialization of CBOR and MessagePack values
+    */
+    class binary_reader
+    {
+      public:
+        /*!
+        @brief create a binary reader
+
+        @param[in] adapter  input adapter to read from
+        */
+        explicit binary_reader(detail::input_adapter_t adapter)
+            : ia(adapter), is_little_endian(little_endianess())
+        {
+            assert(ia);
+        }
+
+        /*!
+        @brief create a JSON value from CBOR input
+
+        @param[in] get_char  whether a new character should be retrieved from
+                             the input (true, default) or whether the last
+                             read character should be considered instead
+
+        @return JSON value created from CBOR input
+
+        @throw parse_error.110 if input ended unexpectedly
+        @throw parse_error.112 if unsupported byte was read
+        */
+        basic_json parse_cbor(const bool get_char = true)
+        {
+            switch (get_char ? get() : current)
+            {
+                // EOF
+                case std::char_traits<char>::eof():
+                {
+                    JSON_THROW(parse_error::create(110, chars_read, "unexpected end of input"));
+                }
+
+                // Integer 0x00..0x17 (0..23)
+                case 0x00:
+                case 0x01:
+                case 0x02:
+                case 0x03:
+                case 0x04:
+                case 0x05:
+                case 0x06:
+                case 0x07:
+                case 0x08:
+                case 0x09:
+                case 0x0a:
+                case 0x0b:
+                case 0x0c:
+                case 0x0d:
+                case 0x0e:
+                case 0x0f:
+                case 0x10:
+                case 0x11:
+                case 0x12:
+                case 0x13:
+                case 0x14:
+                case 0x15:
+                case 0x16:
+                case 0x17:
+                {
+                    return static_cast<number_unsigned_t>(current);
+                }
+
+                case 0x18: // Unsigned integer (one-byte uint8_t follows)
+                {
+                    return get_number<uint8_t>();
+                }
+
+                case 0x19: // Unsigned integer (two-byte uint16_t follows)
+                {
+                    return get_number<uint16_t>();
+                }
+
+                case 0x1a: // Unsigned integer (four-byte uint32_t follows)
+                {
+                    return get_number<uint32_t>();
+                }
+
+                case 0x1b: // Unsigned integer (eight-byte uint64_t follows)
+                {
+                    return get_number<uint64_t>();
+                }
+
+                // Negative integer -1-0x00..-1-0x17 (-1..-24)
+                case 0x20:
+                case 0x21:
+                case 0x22:
+                case 0x23:
+                case 0x24:
+                case 0x25:
+                case 0x26:
+                case 0x27:
+                case 0x28:
+                case 0x29:
+                case 0x2a:
+                case 0x2b:
+                case 0x2c:
+                case 0x2d:
+                case 0x2e:
+                case 0x2f:
+                case 0x30:
+                case 0x31:
+                case 0x32:
+                case 0x33:
+                case 0x34:
+                case 0x35:
+                case 0x36:
+                case 0x37:
+                {
+                    return static_cast<int8_t>(0x20 - 1 - current);
+                }
+
+                case 0x38: // Negative integer (one-byte uint8_t follows)
+                {
+                    // must be uint8_t !
+                    return static_cast<number_integer_t>(-1) - get_number<uint8_t>();
+                }
+
+                case 0x39: // Negative integer -1-n (two-byte uint16_t follows)
+                {
+                    return static_cast<number_integer_t>(-1) - get_number<uint16_t>();
+                }
+
+                case 0x3a: // Negative integer -1-n (four-byte uint32_t follows)
+                {
+                    return static_cast<number_integer_t>(-1) - get_number<uint32_t>();
+                }
+
+                case 0x3b: // Negative integer -1-n (eight-byte uint64_t follows)
+                {
+                    return static_cast<number_integer_t>(-1) - static_cast<number_integer_t>(get_number<uint64_t>());
+                }
+
+                // UTF-8 string (0x00..0x17 bytes follow)
+                case 0x60:
+                case 0x61:
+                case 0x62:
+                case 0x63:
+                case 0x64:
+                case 0x65:
+                case 0x66:
+                case 0x67:
+                case 0x68:
+                case 0x69:
+                case 0x6a:
+                case 0x6b:
+                case 0x6c:
+                case 0x6d:
+                case 0x6e:
+                case 0x6f:
+                case 0x70:
+                case 0x71:
+                case 0x72:
+                case 0x73:
+                case 0x74:
+                case 0x75:
+                case 0x76:
+                case 0x77:
+                case 0x78: // UTF-8 string (one-byte uint8_t for n follows)
+                case 0x79: // UTF-8 string (two-byte uint16_t for n follow)
+                case 0x7a: // UTF-8 string (four-byte uint32_t for n follow)
+                case 0x7b: // UTF-8 string (eight-byte uint64_t for n follow)
+                case 0x7f: // UTF-8 string (indefinite length)
+                {
+                    return get_cbor_string();
+                }
+
+                // array (0x00..0x17 data items follow)
+                case 0x80:
+                case 0x81:
+                case 0x82:
+                case 0x83:
+                case 0x84:
+                case 0x85:
+                case 0x86:
+                case 0x87:
+                case 0x88:
+                case 0x89:
+                case 0x8a:
+                case 0x8b:
+                case 0x8c:
+                case 0x8d:
+                case 0x8e:
+                case 0x8f:
+                case 0x90:
+                case 0x91:
+                case 0x92:
+                case 0x93:
+                case 0x94:
+                case 0x95:
+                case 0x96:
+                case 0x97:
+                {
+                    basic_json result = value_t::array;
+                    const auto len = static_cast<size_t>(current & 0x1f);
+                    for (size_t i = 0; i < len; ++i)
+                    {
+                        result.push_back(parse_cbor());
+                    }
+                    return result;
+                }
+
+                case 0x98: // array (one-byte uint8_t for n follows)
+                {
+                    basic_json result = value_t::array;
+                    const auto len = static_cast<size_t>(get_number<uint8_t>());
+                    for (size_t i = 0; i < len; ++i)
+                    {
+                        result.push_back(parse_cbor());
+                    }
+                    return result;
+                }
+
+                case 0x99: // array (two-byte uint16_t for n follow)
+                {
+                    basic_json result = value_t::array;
+                    const auto len = static_cast<size_t>(get_number<uint16_t>());
+                    for (size_t i = 0; i < len; ++i)
+                    {
+                        result.push_back(parse_cbor());
+                    }
+                    return result;
+                }
+
+                case 0x9a: // array (four-byte uint32_t for n follow)
+                {
+                    basic_json result = value_t::array;
+                    const auto len = static_cast<size_t>(get_number<uint32_t>());
+                    for (size_t i = 0; i < len; ++i)
+                    {
+                        result.push_back(parse_cbor());
+                    }
+                    return result;
+                }
+
+                case 0x9b: // array (eight-byte uint64_t for n follow)
+                {
+                    basic_json result = value_t::array;
+                    const auto len = static_cast<size_t>(get_number<uint64_t>());
+                    for (size_t i = 0; i < len; ++i)
+                    {
+                        result.push_back(parse_cbor());
+                    }
+                    return result;
+                }
+
+                case 0x9f: // array (indefinite length)
+                {
+                    basic_json result = value_t::array;
+                    while (get() != 0xff)
+                    {
+                        result.push_back(parse_cbor(false));
+                    }
+                    return result;
+                }
+
+                // map (0x00..0x17 pairs of data items follow)
+                case 0xa0:
+                case 0xa1:
+                case 0xa2:
+                case 0xa3:
+                case 0xa4:
+                case 0xa5:
+                case 0xa6:
+                case 0xa7:
+                case 0xa8:
+                case 0xa9:
+                case 0xaa:
+                case 0xab:
+                case 0xac:
+                case 0xad:
+                case 0xae:
+                case 0xaf:
+                case 0xb0:
+                case 0xb1:
+                case 0xb2:
+                case 0xb3:
+                case 0xb4:
+                case 0xb5:
+                case 0xb6:
+                case 0xb7:
+                {
+                    basic_json result = value_t::object;
+                    const auto len = static_cast<size_t>(current & 0x1f);
+                    for (size_t i = 0; i < len; ++i)
+                    {
+                        get();
+                        auto key = get_cbor_string();
+                        result[key] = parse_cbor();
+                    }
+                    return result;
+                }
+
+                case 0xb8: // map (one-byte uint8_t for n follows)
+                {
+                    basic_json result = value_t::object;
+                    const auto len = static_cast<size_t>(get_number<uint8_t>());
+                    for (size_t i = 0; i < len; ++i)
+                    {
+                        get();
+                        auto key = get_cbor_string();
+                        result[key] = parse_cbor();
+                    }
+                    return result;
+                }
+
+                case 0xb9: // map (two-byte uint16_t for n follow)
+                {
+                    basic_json result = value_t::object;
+                    const auto len = static_cast<size_t>(get_number<uint16_t>());
+                    for (size_t i = 0; i < len; ++i)
+                    {
+                        get();
+                        auto key = get_cbor_string();
+                        result[key] = parse_cbor();
+                    }
+                    return result;
+                }
+
+                case 0xba: // map (four-byte uint32_t for n follow)
+                {
+                    basic_json result = value_t::object;
+                    const auto len = static_cast<size_t>(get_number<uint32_t>());
+                    for (size_t i = 0; i < len; ++i)
+                    {
+                        get();
+                        auto key = get_cbor_string();
+                        result[key] = parse_cbor();
+                    }
+                    return result;
+                }
+
+                case 0xbb: // map (eight-byte uint64_t for n follow)
+                {
+                    basic_json result = value_t::object;
+                    const auto len = static_cast<size_t>(get_number<uint64_t>());
+                    for (size_t i = 0; i < len; ++i)
+                    {
+                        get();
+                        auto key = get_cbor_string();
+                        result[key] = parse_cbor();
+                    }
+                    return result;
+                }
+
+                case 0xbf: // map (indefinite length)
+                {
+                    basic_json result = value_t::object;
+                    while (get() != 0xff)
+                    {
+                        auto key = get_cbor_string();
+                        result[key] = parse_cbor();
+                    }
+                    return result;
+                }
+
+                case 0xf4: // false
+                {
+                    return false;
+                }
+
+                case 0xf5: // true
+                {
+                    return true;
+                }
+
+                case 0xf6: // null
+                {
+                    return value_t::null;
+                }
+
+                case 0xf9: // Half-Precision Float (two-byte IEEE 754)
+                {
+                    const int byte1 = get();
+                    check_eof();
+                    const int byte2 = get();
+                    check_eof();
+
+                    // code from RFC 7049, Appendix D, Figure 3:
+                    // As half-precision floating-point numbers were only added
+                    // to IEEE 754 in 2008, today's programming platforms often
+                    // still only have limited support for them. It is very
+                    // easy to include at least decoding support for them even
+                    // without such support. An example of a small decoder for
+                    // half-precision floating-point numbers in the C language
+                    // is shown in Fig. 3.
+                    const int half = (byte1 << 8) + byte2;
+                    const int exp = (half >> 10) & 0x1f;
+                    const int mant = half & 0x3ff;
+                    double val;
+                    if (exp == 0)
+                    {
+                        val = std::ldexp(mant, -24);
+                    }
+                    else if (exp != 31)
+                    {
+                        val = std::ldexp(mant + 1024, exp - 25);
+                    }
+                    else
+                    {
+                        val = (mant == 0)
+                              ? std::numeric_limits<double>::infinity()
+                              : std::numeric_limits<double>::quiet_NaN();
+                    }
+                    return (half & 0x8000) != 0 ? -val : val;
+                }
+
+                case 0xfa: // Single-Precision Float (four-byte IEEE 754)
+                {
+                    return get_number<float>();
+                }
+
+                case 0xfb: // Double-Precision Float (eight-byte IEEE 754)
+                {
+                    return get_number<double>();
+                }
+
+                default: // anything else (0xFF is handled inside the other types)
+                {
+                    std::stringstream ss;
+                    ss << std::setw(2) << std::setfill('0') << std::hex << current;
+                    JSON_THROW(parse_error::create(112, chars_read, "error reading CBOR; last byte: 0x" + ss.str()));
+                }
+            }
+        }
+
+        /*!
+        @brief create a JSON value from MessagePack input
+
+        @return JSON value created from MessagePack input
+
+        @throw parse_error.110 if input ended unexpectedly
+        @throw parse_error.112 if unsupported byte was read
+        */
+        basic_json parse_msgpack()
+        {
+            switch (get())
+            {
+                // EOF
+                case std::char_traits<char>::eof():
+                {
+                    JSON_THROW(parse_error::create(110, chars_read, "unexpected end of input"));
+                }
+
+                // positive fixint
+                case 0x00:
+                case 0x01:
+                case 0x02:
+                case 0x03:
+                case 0x04:
+                case 0x05:
+                case 0x06:
+                case 0x07:
+                case 0x08:
+                case 0x09:
+                case 0x0a:
+                case 0x0b:
+                case 0x0c:
+                case 0x0d:
+                case 0x0e:
+                case 0x0f:
+                case 0x10:
+                case 0x11:
+                case 0x12:
+                case 0x13:
+                case 0x14:
+                case 0x15:
+                case 0x16:
+                case 0x17:
+                case 0x18:
+                case 0x19:
+                case 0x1a:
+                case 0x1b:
+                case 0x1c:
+                case 0x1d:
+                case 0x1e:
+                case 0x1f:
+                case 0x20:
+                case 0x21:
+                case 0x22:
+                case 0x23:
+                case 0x24:
+                case 0x25:
+                case 0x26:
+                case 0x27:
+                case 0x28:
+                case 0x29:
+                case 0x2a:
+                case 0x2b:
+                case 0x2c:
+                case 0x2d:
+                case 0x2e:
+                case 0x2f:
+                case 0x30:
+                case 0x31:
+                case 0x32:
+                case 0x33:
+                case 0x34:
+                case 0x35:
+                case 0x36:
+                case 0x37:
+                case 0x38:
+                case 0x39:
+                case 0x3a:
+                case 0x3b:
+                case 0x3c:
+                case 0x3d:
+                case 0x3e:
+                case 0x3f:
+                case 0x40:
+                case 0x41:
+                case 0x42:
+                case 0x43:
+                case 0x44:
+                case 0x45:
+                case 0x46:
+                case 0x47:
+                case 0x48:
+                case 0x49:
+                case 0x4a:
+                case 0x4b:
+                case 0x4c:
+                case 0x4d:
+                case 0x4e:
+                case 0x4f:
+                case 0x50:
+                case 0x51:
+                case 0x52:
+                case 0x53:
+                case 0x54:
+                case 0x55:
+                case 0x56:
+                case 0x57:
+                case 0x58:
+                case 0x59:
+                case 0x5a:
+                case 0x5b:
+                case 0x5c:
+                case 0x5d:
+                case 0x5e:
+                case 0x5f:
+                case 0x60:
+                case 0x61:
+                case 0x62:
+                case 0x63:
+                case 0x64:
+                case 0x65:
+                case 0x66:
+                case 0x67:
+                case 0x68:
+                case 0x69:
+                case 0x6a:
+                case 0x6b:
+                case 0x6c:
+                case 0x6d:
+                case 0x6e:
+                case 0x6f:
+                case 0x70:
+                case 0x71:
+                case 0x72:
+                case 0x73:
+                case 0x74:
+                case 0x75:
+                case 0x76:
+                case 0x77:
+                case 0x78:
+                case 0x79:
+                case 0x7a:
+                case 0x7b:
+                case 0x7c:
+                case 0x7d:
+                case 0x7e:
+                case 0x7f:
+                {
+                    return static_cast<number_unsigned_t>(current);
+                }
+
+                // fixmap
+                case 0x80:
+                case 0x81:
+                case 0x82:
+                case 0x83:
+                case 0x84:
+                case 0x85:
+                case 0x86:
+                case 0x87:
+                case 0x88:
+                case 0x89:
+                case 0x8a:
+                case 0x8b:
+                case 0x8c:
+                case 0x8d:
+                case 0x8e:
+                case 0x8f:
+                {
+                    basic_json result = value_t::object;
+                    const auto len = static_cast<size_t>(current & 0x0f);
+                    for (size_t i = 0; i < len; ++i)
+                    {
+                        get();
+                        auto key = get_msgpack_string();
+                        result[key] = parse_msgpack();
+                    }
+                    return result;
+                }
+
+                // fixarray
+                case 0x90:
+                case 0x91:
+                case 0x92:
+                case 0x93:
+                case 0x94:
+                case 0x95:
+                case 0x96:
+                case 0x97:
+                case 0x98:
+                case 0x99:
+                case 0x9a:
+                case 0x9b:
+                case 0x9c:
+                case 0x9d:
+                case 0x9e:
+                case 0x9f:
+                {
+                    basic_json result = value_t::array;
+                    const auto len = static_cast<size_t>(current & 0x0f);
+                    for (size_t i = 0; i < len; ++i)
+                    {
+                        result.push_back(parse_msgpack());
+                    }
+                    return result;
+                }
+
+                // fixstr
+                case 0xa0:
+                case 0xa1:
+                case 0xa2:
+                case 0xa3:
+                case 0xa4:
+                case 0xa5:
+                case 0xa6:
+                case 0xa7:
+                case 0xa8:
+                case 0xa9:
+                case 0xaa:
+                case 0xab:
+                case 0xac:
+                case 0xad:
+                case 0xae:
+                case 0xaf:
+                case 0xb0:
+                case 0xb1:
+                case 0xb2:
+                case 0xb3:
+                case 0xb4:
+                case 0xb5:
+                case 0xb6:
+                case 0xb7:
+                case 0xb8:
+                case 0xb9:
+                case 0xba:
+                case 0xbb:
+                case 0xbc:
+                case 0xbd:
+                case 0xbe:
+                case 0xbf:
+                {
+                    return get_msgpack_string();
+                }
 
-    @liveexample{The example shows the deserialization of a byte vector in
-    MessagePack format to a JSON value.,from_msgpack}
+                case 0xc0: // nil
+                {
+                    return value_t::null;
+                }
 
-    @sa http://msgpack.org
-    @sa @ref to_msgpack(const basic_json&) for the analogous serialization
-    @sa @ref from_cbor(const std::vector<uint8_t>&, const size_t) for the
-        related CBOR format
+                case 0xc2: // false
+                {
+                    return false;
+                }
 
-    @since version 2.0.9, parameter @a start_index since 2.1.1
-    */
-    static basic_json from_msgpack(const std::vector<uint8_t>& v,
-                                   const size_t start_index = 0)
-    {
-        binary_reader br(detail::input_adapter_factory::create(v.begin() + static_cast<difference_type>(start_index), v.end()));
-        return br.parse_msgpack();
-    }
+                case 0xc3: // true
+                {
+                    return true;
+                }
 
-    /// @}
+                case 0xca: // float 32
+                {
+                    return get_number<float>();
+                }
 
-    //////////////////////
-    // lexer and parser //
-    //////////////////////
+                case 0xcb: // float 64
+                {
+                    return get_number<double>();
+                }
 
-  private:
-    /*!
-    @brief lexical analysis
+                case 0xcc: // uint 8
+                {
+                    return get_number<uint8_t>();
+                }
 
-    This class organizes the lexical analysis during JSON deserialization.
-    */
-    class lexer
-    {
-      public:
-        /// token types for the parser
-        enum class token_type
-        {
-            uninitialized,   ///< indicating the scanner is uninitialized
-            literal_true,    ///< the `true` literal
-            literal_false,   ///< the `false` literal
-            literal_null,    ///< the `null` literal
-            value_string,    ///< a string -- use get_string() for actual value
-            value_unsigned,  ///< an unsigned integer -- use get_number_unsigned() for actual value
-            value_integer,   ///< a signed integer -- use get_number_integer() for actual value
-            value_float,     ///< an floating point number -- use get_number_float() for actual value
-            begin_array,     ///< the character for array begin `[`
-            begin_object,    ///< the character for object begin `{`
-            end_array,       ///< the character for array end `]`
-            end_object,      ///< the character for object end `}`
-            name_separator,  ///< the name separator `:`
-            value_separator, ///< the value separator `,`
-            parse_error,     ///< indicating a parse error
-            end_of_input,    ///< indicating the end of the input buffer
-            literal_or_value ///< a literal or the begin of a value (only for diagnostics)
-        };
+                case 0xcd: // uint 16
+                {
+                    return get_number<uint16_t>();
+                }
 
-        /// return name of values of type token_type (only used for errors)
-        static const char* token_type_name(const token_type t) noexcept
-        {
-            switch (t)
-            {
-                case token_type::uninitialized:
-                    return "<uninitialized>";
-                case token_type::literal_true:
-                    return "true literal";
-                case token_type::literal_false:
-                    return "false literal";
-                case token_type::literal_null:
-                    return "null literal";
-                case token_type::value_string:
-                    return "string literal";
-                case lexer::token_type::value_unsigned:
-                case lexer::token_type::value_integer:
-                case lexer::token_type::value_float:
-                    return "number literal";
-                case token_type::begin_array:
-                    return "'['";
-                case token_type::begin_object:
-                    return "'{'";
-                case token_type::end_array:
-                    return "']'";
-                case token_type::end_object:
-                    return "'}'";
-                case token_type::name_separator:
-                    return "':'";
-                case token_type::value_separator:
-                    return "','";
-                case token_type::parse_error:
-                    return "<parse error>";
-                case token_type::end_of_input:
-                    return "end of input";
-                case token_type::literal_or_value:
-                    return "'[', '{', or a literal";
-                default:
+                case 0xce: // uint 32
                 {
-                    // catch non-enum values
-                    return "unknown token"; // LCOV_EXCL_LINE
+                    return get_number<uint32_t>();
                 }
-            }
-        }
 
-        explicit lexer(detail::input_adapter_t adapter)
-            : ia(adapter), decimal_point_char(get_decimal_point())
-        {}
+                case 0xcf: // uint 64
+                {
+                    return get_number<uint64_t>();
+                }
 
-        // delete because of pointer members
-        lexer(const lexer&) = delete;
-        lexer& operator=(lexer&) = delete;
+                case 0xd0: // int 8
+                {
+                    return get_number<int8_t>();
+                }
 
-      private:
-        /////////////////////
-        // locales
-        /////////////////////
+                case 0xd1: // int 16
+                {
+                    return get_number<int16_t>();
+                }
 
-        /// return the locale-dependent decimal point
-        static char get_decimal_point() noexcept
-        {
-            const auto loc = localeconv();
-            assert(loc != nullptr);
-            return (loc->decimal_point == nullptr) ? '.' : loc->decimal_point[0];
-        }
+                case 0xd2: // int 32
+                {
+                    return get_number<int32_t>();
+                }
 
-        /////////////////////
-        // scan functions
-        /////////////////////
+                case 0xd3: // int 64
+                {
+                    return get_number<int64_t>();
+                }
 
-        /*!
-        @brief get codepoint from 4 hex characters following `\u`
+                case 0xd9: // str 8
+                case 0xda: // str 16
+                case 0xdb: // str 32
+                {
+                    return get_msgpack_string();
+                }
 
-        @return codepoint or -1 in case of an error (e.g. EOF or non-hex
-                character)
-        */
-        int get_codepoint()
-        {
-            // this function only makes sense after reading `\u`
-            assert(current == 'u');
-            int codepoint = 0;
+                case 0xdc: // array 16
+                {
+                    basic_json result = value_t::array;
+                    const auto len = static_cast<size_t>(get_number<uint16_t>());
+                    for (size_t i = 0; i < len; ++i)
+                    {
+                        result.push_back(parse_msgpack());
+                    }
+                    return result;
+                }
 
-            // byte 1: \uXxxx
-            switch (get())
-            {
-                case '0':
-                    break;
-                case '1':
-                    codepoint += 0x1000;
-                    break;
-                case '2':
-                    codepoint += 0x2000;
-                    break;
-                case '3':
-                    codepoint += 0x3000;
-                    break;
-                case '4':
-                    codepoint += 0x4000;
-                    break;
-                case '5':
-                    codepoint += 0x5000;
-                    break;
-                case '6':
-                    codepoint += 0x6000;
-                    break;
-                case '7':
-                    codepoint += 0x7000;
-                    break;
-                case '8':
-                    codepoint += 0x8000;
-                    break;
-                case '9':
-                    codepoint += 0x9000;
-                    break;
-                case 'A':
-                case 'a':
-                    codepoint += 0xa000;
-                    break;
-                case 'B':
-                case 'b':
-                    codepoint += 0xb000;
-                    break;
-                case 'C':
-                case 'c':
-                    codepoint += 0xc000;
-                    break;
-                case 'D':
-                case 'd':
-                    codepoint += 0xd000;
-                    break;
-                case 'E':
-                case 'e':
-                    codepoint += 0xe000;
-                    break;
-                case 'F':
-                case 'f':
-                    codepoint += 0xf000;
-                    break;
-                default:
-                    return -1;
-            }
+                case 0xdd: // array 32
+                {
+                    basic_json result = value_t::array;
+                    const auto len = static_cast<size_t>(get_number<uint32_t>());
+                    for (size_t i = 0; i < len; ++i)
+                    {
+                        result.push_back(parse_msgpack());
+                    }
+                    return result;
+                }
 
-            // byte 2: \uxXxx
-            switch (get())
-            {
-                case '0':
-                    break;
-                case '1':
-                    codepoint += 0x0100;
-                    break;
-                case '2':
-                    codepoint += 0x0200;
-                    break;
-                case '3':
-                    codepoint += 0x0300;
-                    break;
-                case '4':
-                    codepoint += 0x0400;
-                    break;
-                case '5':
-                    codepoint += 0x0500;
-                    break;
-                case '6':
-                    codepoint += 0x0600;
-                    break;
-                case '7':
-                    codepoint += 0x0700;
-                    break;
-                case '8':
-                    codepoint += 0x0800;
-                    break;
-                case '9':
-                    codepoint += 0x0900;
-                    break;
-                case 'A':
-                case 'a':
-                    codepoint += 0x0a00;
-                    break;
-                case 'B':
-                case 'b':
-                    codepoint += 0x0b00;
-                    break;
-                case 'C':
-                case 'c':
-                    codepoint += 0x0c00;
-                    break;
-                case 'D':
-                case 'd':
-                    codepoint += 0x0d00;
-                    break;
-                case 'E':
-                case 'e':
-                    codepoint += 0x0e00;
-                    break;
-                case 'F':
-                case 'f':
-                    codepoint += 0x0f00;
-                    break;
-                default:
-                    return -1;
-            }
+                case 0xde: // map 16
+                {
+                    basic_json result = value_t::object;
+                    const auto len = static_cast<size_t>(get_number<uint16_t>());
+                    for (size_t i = 0; i < len; ++i)
+                    {
+                        get();
+                        auto key = get_msgpack_string();
+                        result[key] = parse_msgpack();
+                    }
+                    return result;
+                }
 
-            // byte 3: \uxxXx
-            switch (get())
-            {
-                case '0':
-                    break;
-                case '1':
-                    codepoint += 0x0010;
-                    break;
-                case '2':
-                    codepoint += 0x0020;
-                    break;
-                case '3':
-                    codepoint += 0x0030;
-                    break;
-                case '4':
-                    codepoint += 0x0040;
-                    break;
-                case '5':
-                    codepoint += 0x0050;
-                    break;
-                case '6':
-                    codepoint += 0x0060;
-                    break;
-                case '7':
-                    codepoint += 0x0070;
-                    break;
-                case '8':
-                    codepoint += 0x0080;
-                    break;
-                case '9':
-                    codepoint += 0x0090;
-                    break;
-                case 'A':
-                case 'a':
-                    codepoint += 0x00a0;
-                    break;
-                case 'B':
-                case 'b':
-                    codepoint += 0x00b0;
-                    break;
-                case 'C':
-                case 'c':
-                    codepoint += 0x00c0;
-                    break;
-                case 'D':
-                case 'd':
-                    codepoint += 0x00d0;
-                    break;
-                case 'E':
-                case 'e':
-                    codepoint += 0x00e0;
-                    break;
-                case 'F':
-                case 'f':
-                    codepoint += 0x00f0;
-                    break;
-                default:
-                    return -1;
-            }
+                case 0xdf: // map 32
+                {
+                    basic_json result = value_t::object;
+                    const auto len = static_cast<size_t>(get_number<uint32_t>());
+                    for (size_t i = 0; i < len; ++i)
+                    {
+                        get();
+                        auto key = get_msgpack_string();
+                        result[key] = parse_msgpack();
+                    }
+                    return result;
+                }
 
-            // byte 4: \uxxxX
-            switch (get())
-            {
-                case '0':
-                    break;
-                case '1':
-                    codepoint += 0x0001;
-                    break;
-                case '2':
-                    codepoint += 0x0002;
-                    break;
-                case '3':
-                    codepoint += 0x0003;
-                    break;
-                case '4':
-                    codepoint += 0x0004;
-                    break;
-                case '5':
-                    codepoint += 0x0005;
-                    break;
-                case '6':
-                    codepoint += 0x0006;
-                    break;
-                case '7':
-                    codepoint += 0x0007;
-                    break;
-                case '8':
-                    codepoint += 0x0008;
-                    break;
-                case '9':
-                    codepoint += 0x0009;
-                    break;
-                case 'A':
-                case 'a':
-                    codepoint += 0x000a;
-                    break;
-                case 'B':
-                case 'b':
-                    codepoint += 0x000b;
-                    break;
-                case 'C':
-                case 'c':
-                    codepoint += 0x000c;
-                    break;
-                case 'D':
-                case 'd':
-                    codepoint += 0x000d;
-                    break;
-                case 'E':
-                case 'e':
-                    codepoint += 0x000e;
-                    break;
-                case 'F':
-                case 'f':
-                    codepoint += 0x000f;
-                    break;
-                default:
-                    return -1;
-            }
+                // positive fixint
+                case 0xe0:
+                case 0xe1:
+                case 0xe2:
+                case 0xe3:
+                case 0xe4:
+                case 0xe5:
+                case 0xe6:
+                case 0xe7:
+                case 0xe8:
+                case 0xe9:
+                case 0xea:
+                case 0xeb:
+                case 0xec:
+                case 0xed:
+                case 0xee:
+                case 0xef:
+                case 0xf0:
+                case 0xf1:
+                case 0xf2:
+                case 0xf3:
+                case 0xf4:
+                case 0xf5:
+                case 0xf6:
+                case 0xf7:
+                case 0xf8:
+                case 0xf9:
+                case 0xfa:
+                case 0xfb:
+                case 0xfc:
+                case 0xfd:
+                case 0xfe:
+                case 0xff:
+                {
+                    return static_cast<int8_t>(current);
+                }
 
-            return codepoint;
+                default: // anything else
+                {
+                    std::stringstream ss;
+                    ss << std::setw(2) << std::setfill('0') << std::hex << current;
+                    JSON_THROW(parse_error::create(112, chars_read, "error reading MessagePack; last byte: 0x" + ss.str()));
+                }
+            }
         }
 
         /*!
-        @brief scan a string literal
-
-        This function scans a string according to Sect. 7 of RFC 7159. While
-        scanning, bytes are escaped and copied into buffer yytext. Then the
-        function returns successfully, yytext is null-terminated and yylen
-        contains the number of bytes in the string.
+        @brief determine system byte order
 
-        @return token_type::value_string if string could be successfully
-                scanned, token_type::parse_error otherwise
+        @return true iff system's byte order is little endian
 
-        @note In case of errors, variable error_message contains a textual
-              description.
+        @note from http://stackoverflow.com/a/1001328/266378
         */
-        token_type scan_string()
+        static bool little_endianess() noexcept
         {
-            // reset yytext (ignore opening quote)
-            reset();
+            int num = 1;
+            return (*reinterpret_cast<char*>(&num) == 1);
+        }
 
-            // we entered the function by reading an open quote
-            assert(current == '\"');
+      private:
+        /*!
+        @brief get next character from the input
 
-            while (true)
-            {
-                // get next character
-                switch (get())
-                {
-                    // end of file while parsing string
-                    case std::char_traits<char>::eof():
-                    {
-                        error_message = "invalid string: missing closing quote";
-                        return token_type::parse_error;
-                    }
+        This function provides the interface to the used input adapter. It does
+        not throw in case the input reached EOF, but returns
+        `std::char_traits<char>::eof()` in that case.
 
-                    // closing quote
-                    case '\"':
-                    {
-                        // terminate yytext
-                        add('\0');
-                        --yylen;
-                        return token_type::value_string;
-                    }
+        @return character read from the input
+        */
+        int get()
+        {
+            ++chars_read;
+            return (current = ia->get_character());
+        }
 
-                    // escapes
-                    case '\\':
-                    {
-                        switch (get())
-                        {
-                            // quotation mark
-                            case '\"':
-                                add('\"');
-                                break;
-                            // reverse solidus
-                            case '\\':
-                                add('\\');
-                                break;
-                            // solidus
-                            case '/':
-                                add('/');
-                                break;
-                            // backspace
-                            case 'b':
-                                add('\b');
-                                break;
-                            // form feed
-                            case 'f':
-                                add('\f');
-                                break;
-                            // line feed
-                            case 'n':
-                                add('\n');
-                                break;
-                            // carriage return
-                            case 'r':
-                                add('\r');
-                                break;
-                            // tab
-                            case 't':
-                                add('\t');
-                                break;
-
-                            // unicode escapes
-                            case 'u':
-                            {
-                                int codepoint;
-                                int codepoint1 = get_codepoint();
+        /*
+        @brief read a number from the input
 
-                                if (JSON_UNLIKELY(codepoint1 == -1))
-                                {
-                                    error_message = "invalid string: '\\u' must be followed by 4 hex digits";
-                                    return token_type::parse_error;
-                                }
+        @tparam NumberType the type of the number
 
-                                // check if code point is a high surrogate
-                                if (0xD800 <= codepoint1 and codepoint1 <= 0xDBFF)
-                                {
-                                    // expect next \uxxxx entry
-                                    if (JSON_LIKELY(get() == '\\' and get() == 'u'))
-                                    {
-                                        const int codepoint2 = get_codepoint();
-
-                                        if (JSON_UNLIKELY(codepoint2 == -1))
-                                        {
-                                            error_message = "invalid string: '\\u' must be followed by 4 hex digits";
-                                            return token_type::parse_error;
-                                        }
-
-                                        // check if codepoint2 is a low surrogate
-                                        if (JSON_LIKELY(0xDC00 <= codepoint2 and codepoint2 <= 0xDFFF))
-                                        {
-                                            codepoint =
-                                                // high surrogate occupies the most significant 22 bits
-                                                (codepoint1 << 10)
-                                                // low surrogate occupies the least significant 15 bits
-                                                + codepoint2
-                                                // there is still the 0xD800, 0xDC00 and 0x10000 noise
-                                                // in the result so we have to subtract with:
-                                                // (0xD800 << 10) + DC00 - 0x10000 = 0x35FDC00
-                                                - 0x35FDC00;
-                                        }
-                                        else
-                                        {
-                                            error_message = "invalid string: surrogate U+DC00..U+DFFF must be followed by U+DC00..U+DFFF";
-                                            return token_type::parse_error;
-                                        }
-                                    }
-                                    else
-                                    {
-                                        error_message = "invalid string: surrogate U+DC00..U+DFFF must be followed by U+DC00..U+DFFF";
-                                        return token_type::parse_error;
-                                    }
-                                }
-                                else
-                                {
-                                    if (JSON_UNLIKELY(0xDC00 <= codepoint1 and codepoint1 <= 0xDFFF))
-                                    {
-                                        error_message = "invalid string: surrogate U+DC00..U+DFFF must follow U+D800..U+DBFF";
-                                        return token_type::parse_error;
-                                    }
+        @return number of type @a NumberType
 
-                                    // only work with first code point
-                                    codepoint = codepoint1;
-                                }
+        @note This function needs to respect the system's endianess, because
+              bytes in CBOR and MessagePack are stored in network order (big
+              endian) and therefore need reordering on little endian systems.
 
-                                // result of the above calculation yields a proper codepoint
-                                assert(0x00 <= codepoint and codepoint <= 0x10FFFF);
+        @throw parse_error.110 if input has less than `sizeof(NumberType)`
+                               bytes
+        */
+        template<typename NumberType>
+        NumberType get_number()
+        {
+            // step 1: read input into array with system's byte order
+            std::array<uint8_t, sizeof(NumberType)> vec;
+            for (size_t i = 0; i < sizeof(NumberType); ++i)
+            {
+                get();
+                check_eof();
 
-                                // translate code point to bytes
-                                if (codepoint < 0x80)
-                                {
-                                    // 1-byte characters: 0xxxxxxx (ASCII)
-                                    add(codepoint);
-                                }
-                                else if (codepoint <= 0x7ff)
-                                {
-                                    // 2-byte characters: 110xxxxx 10xxxxxx
-                                    add(0xC0 | (codepoint >> 6));
-                                    add(0x80 | (codepoint & 0x3F));
-                                }
-                                else if (codepoint <= 0xffff)
-                                {
-                                    // 3-byte characters: 1110xxxx 10xxxxxx 10xxxxxx
-                                    add(0xE0 | (codepoint >> 12));
-                                    add(0x80 | ((codepoint >> 6) & 0x3F));
-                                    add(0x80 | (codepoint & 0x3F));
-                                }
-                                else
-                                {
-                                    // 4-byte characters: 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx
-                                    add(0xF0 | (codepoint >> 18));
-                                    add(0x80 | ((codepoint >> 12) & 0x3F));
-                                    add(0x80 | ((codepoint >> 6) & 0x3F));
-                                    add(0x80 | (codepoint & 0x3F));
-                                }
+                // reverse byte order prior to conversion if necessary
+                if (is_little_endian)
+                {
+                    vec[sizeof(NumberType) - i - 1] = static_cast<uint8_t>(current);
+                }
+                else
+                {
+                    vec[i] = static_cast<uint8_t>(current);  // LCOV_EXCL_LINE
+                }
+            }
 
-                                break;
-                            }
+            // step 2: convert array into number of type T and return
+            NumberType result;
+            std::memcpy(&result, vec.data(), sizeof(NumberType));
+            return result;
+        }
 
-                            // other characters after escape
-                            default:
-                                error_message = "invalid string: forbidden character after backslash";
-                                return token_type::parse_error;
-                        }
+        /*!
+        @brief create a string by reading characters from the input
 
-                        break;
-                    }
+        @param[in] len number of bytes to read
 
-                    // invalid control characters
-                    case 0x00:
-                    case 0x01:
-                    case 0x02:
-                    case 0x03:
-                    case 0x04:
-                    case 0x05:
-                    case 0x06:
-                    case 0x07:
-                    case 0x08:
-                    case 0x09:
-                    case 0x0a:
-                    case 0x0b:
-                    case 0x0c:
-                    case 0x0d:
-                    case 0x0e:
-                    case 0x0f:
-                    case 0x10:
-                    case 0x11:
-                    case 0x12:
-                    case 0x13:
-                    case 0x14:
-                    case 0x15:
-                    case 0x16:
-                    case 0x17:
-                    case 0x18:
-                    case 0x19:
-                    case 0x1a:
-                    case 0x1b:
-                    case 0x1c:
-                    case 0x1d:
-                    case 0x1e:
-                    case 0x1f:
-                    {
-                        error_message = "invalid string: control character must be escaped";
-                        return token_type::parse_error;
-                    }
-
-                    // U+0020..U+007F (except U+0022 (quote) and U+005C (backspace))
-                    case 0x20:
-                    case 0x21:
-                    case 0x23:
-                    case 0x24:
-                    case 0x25:
-                    case 0x26:
-                    case 0x27:
-                    case 0x28:
-                    case 0x29:
-                    case 0x2a:
-                    case 0x2b:
-                    case 0x2c:
-                    case 0x2d:
-                    case 0x2e:
-                    case 0x2f:
-                    case 0x30:
-                    case 0x31:
-                    case 0x32:
-                    case 0x33:
-                    case 0x34:
-                    case 0x35:
-                    case 0x36:
-                    case 0x37:
-                    case 0x38:
-                    case 0x39:
-                    case 0x3a:
-                    case 0x3b:
-                    case 0x3c:
-                    case 0x3d:
-                    case 0x3e:
-                    case 0x3f:
-                    case 0x40:
-                    case 0x41:
-                    case 0x42:
-                    case 0x43:
-                    case 0x44:
-                    case 0x45:
-                    case 0x46:
-                    case 0x47:
-                    case 0x48:
-                    case 0x49:
-                    case 0x4a:
-                    case 0x4b:
-                    case 0x4c:
-                    case 0x4d:
-                    case 0x4e:
-                    case 0x4f:
-                    case 0x50:
-                    case 0x51:
-                    case 0x52:
-                    case 0x53:
-                    case 0x54:
-                    case 0x55:
-                    case 0x56:
-                    case 0x57:
-                    case 0x58:
-                    case 0x59:
-                    case 0x5a:
-                    case 0x5b:
-                    case 0x5d:
-                    case 0x5e:
-                    case 0x5f:
-                    case 0x60:
-                    case 0x61:
-                    case 0x62:
-                    case 0x63:
-                    case 0x64:
-                    case 0x65:
-                    case 0x66:
-                    case 0x67:
-                    case 0x68:
-                    case 0x69:
-                    case 0x6a:
-                    case 0x6b:
-                    case 0x6c:
-                    case 0x6d:
-                    case 0x6e:
-                    case 0x6f:
-                    case 0x70:
-                    case 0x71:
-                    case 0x72:
-                    case 0x73:
-                    case 0x74:
-                    case 0x75:
-                    case 0x76:
-                    case 0x77:
-                    case 0x78:
-                    case 0x79:
-                    case 0x7a:
-                    case 0x7b:
-                    case 0x7c:
-                    case 0x7d:
-                    case 0x7e:
-                    case 0x7f:
-                    {
-                        add(current);
-                        break;
-                    }
+        @note We can not reserve @a len bytes for the result, because @a len
+              may be too large. Usually, @ref check_eof() detects the end of
+              the input before we run out of string memory.
 
-                    // U+0080..U+07FF: bytes C2..DF 80..BF
-                    case 0xc2:
-                    case 0xc3:
-                    case 0xc4:
-                    case 0xc5:
-                    case 0xc6:
-                    case 0xc7:
-                    case 0xc8:
-                    case 0xc9:
-                    case 0xca:
-                    case 0xcb:
-                    case 0xcc:
-                    case 0xcd:
-                    case 0xce:
-                    case 0xcf:
-                    case 0xd0:
-                    case 0xd1:
-                    case 0xd2:
-                    case 0xd3:
-                    case 0xd4:
-                    case 0xd5:
-                    case 0xd6:
-                    case 0xd7:
-                    case 0xd8:
-                    case 0xd9:
-                    case 0xda:
-                    case 0xdb:
-                    case 0xdc:
-                    case 0xdd:
-                    case 0xde:
-                    case 0xdf:
-                    {
-                        add(current);
-                        get();
-                        if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
-                        {
-                            add(current);
-                            continue;
-                        }
+        @return string created by reading @a len bytes
 
-                        error_message = "invalid string: ill-formed UTF-8 byte";
-                        return token_type::parse_error;
-                    }
+        @throw parse_error.110 if input has less than @a len bytes
+        */
+        std::string get_string(const size_t len)
+        {
+            std::string result;
+            for (size_t i = 0; i < len; ++i)
+            {
+                get();
+                check_eof();
+                result.append(1, static_cast<char>(current));
+            }
+            return result;
+        }
 
-                    // U+0800..U+0FFF: bytes E0 A0..BF 80..BF
-                    case 0xe0:
-                    {
-                        add(current);
-                        get();
-                        if (JSON_LIKELY(0xa0 <= current and current <= 0xbf))
-                        {
-                            add(current);
-                            get();
-                            if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
-                            {
-                                add(current);
-                                continue;
-                            }
-                        }
+        /*!
+        @brief reads a CBOR string
 
-                        error_message = "invalid string: ill-formed UTF-8 byte";
-                        return token_type::parse_error;
-                    }
-
-                    // U+1000..U+CFFF: bytes E1..EC 80..BF 80..BF
-                    // U+E000..U+FFFF: bytes EE..EF 80..BF 80..BF
-                    case 0xe1:
-                    case 0xe2:
-                    case 0xe3:
-                    case 0xe4:
-                    case 0xe5:
-                    case 0xe6:
-                    case 0xe7:
-                    case 0xe8:
-                    case 0xe9:
-                    case 0xea:
-                    case 0xeb:
-                    case 0xec:
-                    case 0xee:
-                    case 0xef:
-                    {
-                        add(current);
-                        get();
-                        if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
-                        {
-                            add(current);
-                            get();
-                            if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
-                            {
-                                add(current);
-                                continue;
-                            }
-                        }
+        This function first reads starting bytes to determine the expected
+        string length and then copies this number of bytes into a string.
+        Additionally, CBOR's strings with indefinite lengths are supported.
 
-                        error_message = "invalid string: ill-formed UTF-8 byte";
-                        return token_type::parse_error;
-                    }
+        @return string
 
-                    // U+D000..U+D7FF: bytes ED 80..9F 80..BF
-                    case 0xed:
-                    {
-                        add(current);
-                        get();
-                        if (JSON_LIKELY(0x80 <= current and current <= 0x9f))
-                        {
-                            add(current);
-                            get();
-                            if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
-                            {
-                                add(current);
-                                continue;
-                            }
-                        }
+        @throw parse_error.110 if input ended
+        @throw parse_error.113 if an unexpected byte is read
+        */
+        std::string get_cbor_string()
+        {
+            check_eof();
 
-                        error_message = "invalid string: ill-formed UTF-8 byte";
-                        return token_type::parse_error;
-                    }
+            switch (current)
+            {
+                // UTF-8 string (0x00..0x17 bytes follow)
+                case 0x60:
+                case 0x61:
+                case 0x62:
+                case 0x63:
+                case 0x64:
+                case 0x65:
+                case 0x66:
+                case 0x67:
+                case 0x68:
+                case 0x69:
+                case 0x6a:
+                case 0x6b:
+                case 0x6c:
+                case 0x6d:
+                case 0x6e:
+                case 0x6f:
+                case 0x70:
+                case 0x71:
+                case 0x72:
+                case 0x73:
+                case 0x74:
+                case 0x75:
+                case 0x76:
+                case 0x77:
+                {
+                    const auto len = static_cast<size_t>(current & 0x1f);
+                    return get_string(len);
+                }
 
-                    // U+10000..U+3FFFF F0 90..BF 80..BF 80..BF
-                    case 0xf0:
-                    {
-                        add(current);
-                        get();
-                        if (JSON_LIKELY(0x90 <= current and current <= 0xbf))
-                        {
-                            add(current);
-                            get();
-                            if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
-                            {
-                                add(current);
-                                get();
-                                if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
-                                {
-                                    add(current);
-                                    continue;
-                                }
-                            }
-                        }
+                case 0x78: // UTF-8 string (one-byte uint8_t for n follows)
+                {
+                    const auto len = static_cast<size_t>(get_number<uint8_t>());
+                    return get_string(len);
+                }
 
-                        error_message = "invalid string: ill-formed UTF-8 byte";
-                        return token_type::parse_error;
-                    }
+                case 0x79: // UTF-8 string (two-byte uint16_t for n follow)
+                {
+                    const auto len = static_cast<size_t>(get_number<uint16_t>());
+                    return get_string(len);
+                }
 
-                    // U+40000..U+FFFFF F1..F3 80..BF 80..BF 80..BF
-                    case 0xf1:
-                    case 0xf2:
-                    case 0xf3:
-                    {
-                        add(current);
-                        get();
-                        if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
-                        {
-                            add(current);
-                            get();
-                            if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
-                            {
-                                add(current);
-                                get();
-                                if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
-                                {
-                                    add(current);
-                                    continue;
-                                }
-                            }
-                        }
+                case 0x7a: // UTF-8 string (four-byte uint32_t for n follow)
+                {
+                    const auto len = static_cast<size_t>(get_number<uint32_t>());
+                    return get_string(len);
+                }
 
-                        error_message = "invalid string: ill-formed UTF-8 byte";
-                        return token_type::parse_error;
-                    }
+                case 0x7b: // UTF-8 string (eight-byte uint64_t for n follow)
+                {
+                    const auto len = static_cast<size_t>(get_number<uint64_t>());
+                    return get_string(len);
+                }
 
-                    // U+100000..U+10FFFF F4 80..8F 80..BF 80..BF
-                    case 0xf4:
+                case 0x7f: // UTF-8 string (indefinite length)
+                {
+                    std::string result;
+                    while (get() != 0xff)
                     {
-                        add(current);
-                        get();
-                        if (JSON_LIKELY(0x80 <= current and current <= 0x8f))
-                        {
-                            add(current);
-                            get();
-                            if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
-                            {
-                                add(current);
-                                get();
-                                if (JSON_LIKELY(0x80 <= current and current <= 0xbf))
-                                {
-                                    add(current);
-                                    continue;
-                                }
-                            }
-                        }
-
-                        error_message = "invalid string: ill-formed UTF-8 byte";
-                        return token_type::parse_error;
+                        check_eof();
+                        result.append(1, static_cast<char>(current));
                     }
+                    return result;
+                }
 
-                    // remaining bytes (80..C1 and F5..FF) are ill-formed
-                    default:
-                    {
-                        error_message = "invalid string: ill-formed UTF-8 byte";
-                        return token_type::parse_error;
-                    }
+                default:
+                {
+                    std::stringstream ss;
+                    ss << std::setw(2) << std::setfill('0') << std::hex << current;
+                    JSON_THROW(parse_error::create(113, chars_read, "expected a CBOR string; last byte: 0x" + ss.str()));
                 }
             }
         }
 
-        static void strtof(float& f, const char* str, char** endptr) noexcept
-        {
-            f = std::strtof(str, endptr);
-        }
+        /*!
+        @brief reads a MessagePack string
 
-        static void strtof(double& f, const char* str, char** endptr) noexcept
-        {
-            f = std::strtod(str, endptr);
-        }
+        This function first reads starting bytes to determine the expected
+        string length and then copies this number of bytes into a string.
 
-        static void strtof(long double& f, const char* str, char** endptr) noexcept
-        {
-            f = std::strtold(str, endptr);
-        }
+        @return string
 
-        /*!
-        @brief scan a number literal
-
-        This function scans a string according to Sect. 6 of RFC 7159.
-
-        The function is realized with a deterministic finite state machine
-        derived from the grammar described in RFC 7159. Starting in state
-        "init", the input is read and used to determined the next state. Only
-        state "done" accepts the number. State "error" is a trap state to model
-        errors. In the table below, "anything" means any character but the ones
-        listed before.
-
-        state    | 0        | 1-9      | e E      | +       | -       | .        | anything
-        ---------|----------|----------|----------|---------|---------|----------|-----------
-        init     | zero     | any1     | [error]  | [error] | minus   | [error]  | [error]
-        minus    | zero     | any1     | [error]  | [error] | [error] | [error]  | [error]
-        zero     | done     | done     | exponent | done    | done    | decimal1 | done
-        any1     | any1     | any1     | exponent | done    | done    | decimal1 | done
-        decimal1 | decimal2 | [error]  | [error]  | [error] | [error] | [error]  | [error]
-        decimal2 | decimal2 | decimal2 | exponent | done    | done    | done     | done
-        exponent | any2     | any2     | [error]  | sign    | sign    | [error]  | [error]
-        sign     | any2     | any2     | [error]  | [error] | [error] | [error]  | [error]
-        any2     | any2     | any2     | done     | done    | done    | done     | done
-
-        The state machine is realized with one label per state (prefixed with
-        "scan_number_") and `goto` statements between them. The state machine
-        contains cycles, but any cycle can be left when EOF is read. Therefore,
-        the function is guaranteed to terminate.
-
-        During scanning, the read bytes are stored in yytext. This string is
-        then converted to a signed integer, an unsigned integer, or a
-        floating-point number.
-
-        @return token_type::value_unsigned, token_type::value_integer, or
-                token_type::value_float if number could be successfully scanned,
-                token_type::parse_error otherwise
-
-        @note The scanner is independent of the current locale. Internally, the
-              locale's decimal point is used instead of `.` to work with the
-              locale-dependent converters.
+        @throw parse_error.110 if input ended
+        @throw parse_error.113 if an unexpected byte is read
         */
-        token_type scan_number()
+        std::string get_msgpack_string()
         {
-            // reset yytext to store the number's bytes
-            reset();
-
-            // the type of the parsed number; initially set to unsigned; will be
-            // changed if minus sign, decimal point or exponent is read
-            token_type number_type = token_type::value_unsigned;
+            check_eof();
 
-            // state (init): we just found out we need to scan a number
             switch (current)
             {
-                case '-':
+                // fixstr
+                case 0xa0:
+                case 0xa1:
+                case 0xa2:
+                case 0xa3:
+                case 0xa4:
+                case 0xa5:
+                case 0xa6:
+                case 0xa7:
+                case 0xa8:
+                case 0xa9:
+                case 0xaa:
+                case 0xab:
+                case 0xac:
+                case 0xad:
+                case 0xae:
+                case 0xaf:
+                case 0xb0:
+                case 0xb1:
+                case 0xb2:
+                case 0xb3:
+                case 0xb4:
+                case 0xb5:
+                case 0xb6:
+                case 0xb7:
+                case 0xb8:
+                case 0xb9:
+                case 0xba:
+                case 0xbb:
+                case 0xbc:
+                case 0xbd:
+                case 0xbe:
+                case 0xbf:
                 {
-                    add(current);
-                    goto scan_number_minus;
+                    const auto len = static_cast<size_t>(current & 0x1f);
+                    return get_string(len);
                 }
 
-                case '0':
+                case 0xd9: // str 8
                 {
-                    add(current);
-                    goto scan_number_zero;
+                    const auto len = static_cast<size_t>(get_number<uint8_t>());
+                    return get_string(len);
                 }
 
-                case '1':
-                case '2':
-                case '3':
-                case '4':
-                case '5':
-                case '6':
-                case '7':
-                case '8':
-                case '9':
+                case 0xda: // str 16
                 {
-                    add(current);
-                    goto scan_number_any1;
+                    const auto len = static_cast<size_t>(get_number<uint16_t>());
+                    return get_string(len);
+                }
+
+                case 0xdb: // str 32
+                {
+                    const auto len = static_cast<size_t>(get_number<uint32_t>());
+                    return get_string(len);
                 }
 
                 default:
                 {
-                    // all other characters are rejected outside scan_number()
-                    assert(false);  // LCOV_EXCL_LINE
+                    std::stringstream ss;
+                    ss << std::setw(2) << std::setfill('0') << std::hex << current;
+                    JSON_THROW(parse_error::create(113, chars_read, "expected a MessagePack string; last byte: 0x" + ss.str()));
                 }
             }
+        }
 
-scan_number_minus:
-            // state: we just parsed a leading minus sign
-            number_type = token_type::value_integer;
-            switch (get())
+        /*!
+        @brief check if input ended
+        @throw parse_error.110 if input ended
+        */
+        void check_eof() const
+        {
+            if (JSON_UNLIKELY(current == std::char_traits<char>::eof()))
             {
-                case '0':
-                {
-                    add(current);
-                    goto scan_number_zero;
-                }
+                JSON_THROW(parse_error::create(110, chars_read, "unexpected end of input"));
+            }
+        }
 
-                case '1':
-                case '2':
-                case '3':
-                case '4':
-                case '5':
-                case '6':
-                case '7':
-                case '8':
-                case '9':
-                {
-                    add(current);
-                    goto scan_number_any1;
-                }
+      private:
+        /// input adapter
+        detail::input_adapter_t ia = nullptr;
 
-                default:
-                {
-                    error_message = "invalid number; expected digit after '-'";
-                    return token_type::parse_error;
-                }
-            }
+        /// the current character
+        int current = std::char_traits<char>::eof();
 
-scan_number_zero:
-            // state: we just parse a zero (maybe with a leading minus sign)
-            switch (get())
+        /// the number of characters read
+        size_t chars_read = 0;
+
+        /// whether we can assume little endianess
+        const bool is_little_endian = true;
+    };
+
+    /*!
+    @brief serialization to CBOR and MessagePack values
+    */
+    class binary_writer
+    {
+      public:
+        /*!
+        @brief create a binary writer
+
+        @param[in] adapter  output adapter to write to
+        */
+        explicit binary_writer(output_adapter_t<uint8_t> adapter)
+            : is_little_endian(binary_reader::little_endianess()), oa(adapter)
+        {
+            assert(oa);
+        }
+
+        /*!
+        @brief[in] j  JSON value to serialize
+        */
+        void write_cbor(const basic_json& j)
+        {
+            switch (j.type())
             {
-                case '.':
+                case value_t::null:
                 {
-                    add(decimal_point_char);
-                    goto scan_number_decimal1;
+                    oa->write_character(0xf6);
+                    break;
                 }
 
-                case 'e':
-                case 'E':
+                case value_t::boolean:
                 {
-                    add(current);
-                    goto scan_number_exponent;
+                    oa->write_character(j.m_value.boolean ? 0xf5 : 0xf4);
+                    break;
                 }
 
-                default:
+                case value_t::number_integer:
                 {
-                    goto scan_number_done;
+                    if (j.m_value.number_integer >= 0)
+                    {
+                        // CBOR does not differentiate between positive signed
+                        // integers and unsigned integers. Therefore, we used the
+                        // code from the value_t::number_unsigned case here.
+                        if (j.m_value.number_integer <= 0x17)
+                        {
+                            write_number(static_cast<uint8_t>(j.m_value.number_integer));
+                        }
+                        else if (j.m_value.number_integer <= (std::numeric_limits<uint8_t>::max)())
+                        {
+                            oa->write_character(0x18);
+                            write_number(static_cast<uint8_t>(j.m_value.number_integer));
+                        }
+                        else if (j.m_value.number_integer <= (std::numeric_limits<uint16_t>::max)())
+                        {
+                            oa->write_character(0x19);
+                            write_number(static_cast<uint16_t>(j.m_value.number_integer));
+                        }
+                        else if (j.m_value.number_integer <= (std::numeric_limits<uint32_t>::max)())
+                        {
+                            oa->write_character(0x1a);
+                            write_number(static_cast<uint32_t>(j.m_value.number_integer));
+                        }
+                        else
+                        {
+                            oa->write_character(0x1b);
+                            write_number(static_cast<uint64_t>(j.m_value.number_integer));
+                        }
+                    }
+                    else
+                    {
+                        // The conversions below encode the sign in the first
+                        // byte, and the value is converted to a positive number.
+                        const auto positive_number = -1 - j.m_value.number_integer;
+                        if (j.m_value.number_integer >= -24)
+                        {
+                            write_number(static_cast<uint8_t>(0x20 + positive_number));
+                        }
+                        else if (positive_number <= (std::numeric_limits<uint8_t>::max)())
+                        {
+                            oa->write_character(0x38);
+                            write_number(static_cast<uint8_t>(positive_number));
+                        }
+                        else if (positive_number <= (std::numeric_limits<uint16_t>::max)())
+                        {
+                            oa->write_character(0x39);
+                            write_number(static_cast<uint16_t>(positive_number));
+                        }
+                        else if (positive_number <= (std::numeric_limits<uint32_t>::max)())
+                        {
+                            oa->write_character(0x3a);
+                            write_number(static_cast<uint32_t>(positive_number));
+                        }
+                        else
+                        {
+                            oa->write_character(0x3b);
+                            write_number(static_cast<uint64_t>(positive_number));
+                        }
+                    }
+                    break;
                 }
-            }
 
-scan_number_any1:
-            // state: we just parsed a number 0-9 (maybe with a leading minus sign)
-            switch (get())
-            {
-                case '0':
-                case '1':
-                case '2':
-                case '3':
-                case '4':
-                case '5':
-                case '6':
-                case '7':
-                case '8':
-                case '9':
+                case value_t::number_unsigned:
                 {
-                    add(current);
-                    goto scan_number_any1;
+                    if (j.m_value.number_unsigned <= 0x17)
+                    {
+                        write_number(static_cast<uint8_t>(j.m_value.number_unsigned));
+                    }
+                    else if (j.m_value.number_unsigned <= (std::numeric_limits<uint8_t>::max)())
+                    {
+                        oa->write_character(0x18);
+                        write_number(static_cast<uint8_t>(j.m_value.number_unsigned));
+                    }
+                    else if (j.m_value.number_unsigned <= (std::numeric_limits<uint16_t>::max)())
+                    {
+                        oa->write_character(0x19);
+                        write_number(static_cast<uint16_t>(j.m_value.number_unsigned));
+                    }
+                    else if (j.m_value.number_unsigned <= (std::numeric_limits<uint32_t>::max)())
+                    {
+                        oa->write_character(0x1a);
+                        write_number(static_cast<uint32_t>(j.m_value.number_unsigned));
+                    }
+                    else
+                    {
+                        oa->write_character(0x1b);
+                        write_number(static_cast<uint64_t>(j.m_value.number_unsigned));
+                    }
+                    break;
                 }
 
-                case '.':
+                case value_t::number_float:
                 {
-                    add(decimal_point_char);
-                    goto scan_number_decimal1;
+                    // Double-Precision Float
+                    oa->write_character(0xfb);
+                    write_number(j.m_value.number_float);
+                    break;
                 }
 
-                case 'e':
-                case 'E':
+                case value_t::string:
                 {
-                    add(current);
-                    goto scan_number_exponent;
-                }
+                    // step 1: write control byte and the string length
+                    const auto N = j.m_value.string->size();
+                    if (N <= 0x17)
+                    {
+                        write_number(static_cast<uint8_t>(0x60 + N));
+                    }
+                    else if (N <= 0xff)
+                    {
+                        oa->write_character(0x78);
+                        write_number(static_cast<uint8_t>(N));
+                    }
+                    else if (N <= 0xffff)
+                    {
+                        oa->write_character(0x79);
+                        write_number(static_cast<uint16_t>(N));
+                    }
+                    else if (N <= 0xffffffff)
+                    {
+                        oa->write_character(0x7a);
+                        write_number(static_cast<uint32_t>(N));
+                    }
+                    // LCOV_EXCL_START
+                    else if (N <= 0xffffffffffffffff)
+                    {
+                        oa->write_character(0x7b);
+                        write_number(static_cast<uint64_t>(N));
+                    }
+                    // LCOV_EXCL_STOP
 
-                default:
-                {
-                    goto scan_number_done;
+                    // step 2: write the string
+                    oa->write_characters(reinterpret_cast<const uint8_t*>(j.m_value.string->c_str()),
+                                         j.m_value.string->size());
+                    break;
                 }
-            }
 
-scan_number_decimal1:
-            // state: we just parsed a decimal point
-            number_type = token_type::value_float;
-            switch (get())
-            {
-                case '0':
-                case '1':
-                case '2':
-                case '3':
-                case '4':
-                case '5':
-                case '6':
-                case '7':
-                case '8':
-                case '9':
+                case value_t::array:
                 {
-                    add(current);
-                    goto scan_number_decimal2;
-                }
+                    // step 1: write control byte and the array size
+                    const auto N = j.m_value.array->size();
+                    if (N <= 0x17)
+                    {
+                        write_number(static_cast<uint8_t>(0x80 + N));
+                    }
+                    else if (N <= 0xff)
+                    {
+                        oa->write_character(0x98);
+                        write_number(static_cast<uint8_t>(N));
+                    }
+                    else if (N <= 0xffff)
+                    {
+                        oa->write_character(0x99);
+                        write_number(static_cast<uint16_t>(N));
+                    }
+                    else if (N <= 0xffffffff)
+                    {
+                        oa->write_character(0x9a);
+                        write_number(static_cast<uint32_t>(N));
+                    }
+                    // LCOV_EXCL_START
+                    else if (N <= 0xffffffffffffffff)
+                    {
+                        oa->write_character(0x9b);
+                        write_number(static_cast<uint64_t>(N));
+                    }
+                    // LCOV_EXCL_STOP
 
-                default:
-                {
-                    error_message = "invalid number; expected digit after '.'";
-                    return token_type::parse_error;
+                    // step 2: write each element
+                    for (const auto& el : *j.m_value.array)
+                    {
+                        write_cbor(el);
+                    }
+                    break;
                 }
-            }
 
-scan_number_decimal2:
-            // we just parsed at least one number after a decimal point
-            switch (get())
-            {
-                case '0':
-                case '1':
-                case '2':
-                case '3':
-                case '4':
-                case '5':
-                case '6':
-                case '7':
-                case '8':
-                case '9':
+                case value_t::object:
                 {
-                    add(current);
-                    goto scan_number_decimal2;
-                }
+                    // step 1: write control byte and the object size
+                    const auto N = j.m_value.object->size();
+                    if (N <= 0x17)
+                    {
+                        write_number(static_cast<uint8_t>(0xa0 + N));
+                    }
+                    else if (N <= 0xff)
+                    {
+                        oa->write_character(0xb8);
+                        write_number(static_cast<uint8_t>(N));
+                    }
+                    else if (N <= 0xffff)
+                    {
+                        oa->write_character(0xb9);
+                        write_number(static_cast<uint16_t>(N));
+                    }
+                    else if (N <= 0xffffffff)
+                    {
+                        oa->write_character(0xba);
+                        write_number(static_cast<uint32_t>(N));
+                    }
+                    // LCOV_EXCL_START
+                    else if (N <= 0xffffffffffffffff)
+                    {
+                        oa->write_character(0xbb);
+                        write_number(static_cast<uint64_t>(N));
+                    }
+                    // LCOV_EXCL_STOP
 
-                case 'e':
-                case 'E':
-                {
-                    add(current);
-                    goto scan_number_exponent;
+                    // step 2: write each element
+                    for (const auto& el : *j.m_value.object)
+                    {
+                        write_cbor(el.first);
+                        write_cbor(el.second);
+                    }
+                    break;
                 }
 
                 default:
                 {
-                    goto scan_number_done;
+                    break;
                 }
             }
+        }
 
-scan_number_exponent:
-            // we just parsed an exponent
-            number_type = token_type::value_float;
-            switch (get())
+        /*!
+        @brief[in] j  JSON value to serialize
+        */
+        void write_msgpack(const basic_json& j)
+        {
+            switch (j.type())
             {
-                case '+':
-                case '-':
+                case value_t::null:
                 {
-                    add(current);
-                    goto scan_number_sign;
+                    // nil
+                    oa->write_character(0xc0);
+                    break;
                 }
 
-                case '0':
-                case '1':
-                case '2':
-                case '3':
-                case '4':
-                case '5':
-                case '6':
-                case '7':
-                case '8':
-                case '9':
+                case value_t::boolean:
                 {
-                    add(current);
-                    goto scan_number_any2;
+                    // true and false
+                    oa->write_character(j.m_value.boolean ? 0xc3 : 0xc2);
+                    break;
                 }
 
-                default:
+                case value_t::number_integer:
                 {
-                    error_message = "invalid number; expected '+', '-', or digit after exponent";
-                    return token_type::parse_error;
+                    if (j.m_value.number_integer >= 0)
+                    {
+                        // MessagePack does not differentiate between positive
+                        // signed integers and unsigned integers. Therefore, we
+                        // used the code from the value_t::number_unsigned case
+                        // here.
+                        if (j.m_value.number_unsigned < 128)
+                        {
+                            // positive fixnum
+                            write_number(static_cast<uint8_t>(j.m_value.number_integer));
+                        }
+                        else if (j.m_value.number_unsigned <= (std::numeric_limits<uint8_t>::max)())
+                        {
+                            // uint 8
+                            oa->write_character(0xcc);
+                            write_number(static_cast<uint8_t>(j.m_value.number_integer));
+                        }
+                        else if (j.m_value.number_unsigned <= (std::numeric_limits<uint16_t>::max)())
+                        {
+                            // uint 16
+                            oa->write_character(0xcd);
+                            write_number(static_cast<uint16_t>(j.m_value.number_integer));
+                        }
+                        else if (j.m_value.number_unsigned <= (std::numeric_limits<uint32_t>::max)())
+                        {
+                            // uint 32
+                            oa->write_character(0xce);
+                            write_number(static_cast<uint32_t>(j.m_value.number_integer));
+                        }
+                        else if (j.m_value.number_unsigned <= (std::numeric_limits<uint64_t>::max)())
+                        {
+                            // uint 64
+                            oa->write_character(0xcf);
+                            write_number(static_cast<uint64_t>(j.m_value.number_integer));
+                        }
+                    }
+                    else
+                    {
+                        if (j.m_value.number_integer >= -32)
+                        {
+                            // negative fixnum
+                            write_number(static_cast<int8_t>(j.m_value.number_integer));
+                        }
+                        else if (j.m_value.number_integer >= (std::numeric_limits<int8_t>::min)() and j.m_value.number_integer <= (std::numeric_limits<int8_t>::max)())
+                        {
+                            // int 8
+                            oa->write_character(0xd0);
+                            write_number(static_cast<int8_t>(j.m_value.number_integer));
+                        }
+                        else if (j.m_value.number_integer >= (std::numeric_limits<int16_t>::min)() and j.m_value.number_integer <= (std::numeric_limits<int16_t>::max)())
+                        {
+                            // int 16
+                            oa->write_character(0xd1);
+                            write_number(static_cast<int16_t>(j.m_value.number_integer));
+                        }
+                        else if (j.m_value.number_integer >= (std::numeric_limits<int32_t>::min)() and j.m_value.number_integer <= (std::numeric_limits<int32_t>::max)())
+                        {
+                            // int 32
+                            oa->write_character(0xd2);
+                            write_number(static_cast<int32_t>(j.m_value.number_integer));
+                        }
+                        else if (j.m_value.number_integer >= (std::numeric_limits<int64_t>::min)() and j.m_value.number_integer <= (std::numeric_limits<int64_t>::max)())
+                        {
+                            // int 64
+                            oa->write_character(0xd3);
+                            write_number(static_cast<int64_t>(j.m_value.number_integer));
+                        }
+                    }
+                    break;
                 }
-            }
 
-scan_number_sign:
-            // we just parsed an exponent sign
-            switch (get())
-            {
-                case '0':
-                case '1':
-                case '2':
-                case '3':
-                case '4':
-                case '5':
-                case '6':
-                case '7':
-                case '8':
-                case '9':
+                case value_t::number_unsigned:
                 {
-                    add(current);
-                    goto scan_number_any2;
+                    if (j.m_value.number_unsigned < 128)
+                    {
+                        // positive fixnum
+                        write_number(static_cast<uint8_t>(j.m_value.number_integer));
+                    }
+                    else if (j.m_value.number_unsigned <= (std::numeric_limits<uint8_t>::max)())
+                    {
+                        // uint 8
+                        oa->write_character(0xcc);
+                        write_number(static_cast<uint8_t>(j.m_value.number_integer));
+                    }
+                    else if (j.m_value.number_unsigned <= (std::numeric_limits<uint16_t>::max)())
+                    {
+                        // uint 16
+                        oa->write_character(0xcd);
+                        write_number(static_cast<uint16_t>(j.m_value.number_integer));
+                    }
+                    else if (j.m_value.number_unsigned <= (std::numeric_limits<uint32_t>::max)())
+                    {
+                        // uint 32
+                        oa->write_character(0xce);
+                        write_number(static_cast<uint32_t>(j.m_value.number_integer));
+                    }
+                    else if (j.m_value.number_unsigned <= (std::numeric_limits<uint64_t>::max)())
+                    {
+                        // uint 64
+                        oa->write_character(0xcf);
+                        write_number(static_cast<uint64_t>(j.m_value.number_integer));
+                    }
+                    break;
                 }
 
-                default:
+                case value_t::number_float:
                 {
-                    error_message = "invalid number; expected digit after exponent sign";
-                    return token_type::parse_error;
+                    // float 64
+                    oa->write_character(0xcb);
+                    write_number(j.m_value.number_float);
+                    break;
                 }
-            }
 
-scan_number_any2:
-            // we just parsed a number after the exponent or exponent sign
-            switch (get())
-            {
-                case '0':
-                case '1':
-                case '2':
-                case '3':
-                case '4':
-                case '5':
-                case '6':
-                case '7':
-                case '8':
-                case '9':
+                case value_t::string:
                 {
-                    add(current);
-                    goto scan_number_any2;
-                }
+                    // step 1: write control byte and the string length
+                    const auto N = j.m_value.string->size();
+                    if (N <= 31)
+                    {
+                        // fixstr
+                        write_number(static_cast<uint8_t>(0xa0 | N));
+                    }
+                    else if (N <= 255)
+                    {
+                        // str 8
+                        oa->write_character(0xd9);
+                        write_number(static_cast<uint8_t>(N));
+                    }
+                    else if (N <= 65535)
+                    {
+                        // str 16
+                        oa->write_character(0xda);
+                        write_number(static_cast<uint16_t>(N));
+                    }
+                    else if (N <= 4294967295)
+                    {
+                        // str 32
+                        oa->write_character(0xdb);
+                        write_number(static_cast<uint32_t>(N));
+                    }
 
-                default:
-                {
-                    goto scan_number_done;
+                    // step 2: write the string
+                    oa->write_characters(reinterpret_cast<const uint8_t*>(j.m_value.string->c_str()),
+                                         j.m_value.string->size());
+                    break;
                 }
-            }
-
-scan_number_done:
-            // unget the character after the number (we only read it to know
-            // that we are done scanning a number)
-            --chars_read;
-            next_unget = true;
-
-            // terminate token
-            add('\0');
-            --yylen;
 
-            // try to parse integers first and fall back to floats
-            if (number_type == token_type::value_unsigned)
-            {
-                char* endptr = nullptr;
-                errno = 0;
-                const auto x = std::strtoull(yytext.data(), &endptr, 10);
-
-                // we checked the number format before
-                assert(endptr == yytext.data() + yylen);
-
-                if (errno == 0)
+                case value_t::array:
                 {
-                    value_unsigned = static_cast<number_unsigned_t>(x);
-                    if (value_unsigned == x)
+                    // step 1: write control byte and the array size
+                    const auto N = j.m_value.array->size();
+                    if (N <= 15)
                     {
-                        return token_type::value_unsigned;
+                        // fixarray
+                        write_number(static_cast<uint8_t>(0x90 | N));
                     }
-                }
-            }
-            else if (number_type == token_type::value_integer)
-            {
-                char* endptr = nullptr;
-                errno = 0;
-                const auto x = std::strtoll(yytext.data(), &endptr, 10);
-
-                // we checked the number format before
-                assert(endptr == yytext.data() + yylen);
-
-                if (errno == 0)
-                {
-                    value_integer = static_cast<number_integer_t>(x);
-                    if (value_integer == x)
+                    else if (N <= 0xffff)
                     {
-                        return token_type::value_integer;
+                        // array 16
+                        oa->write_character(0xdc);
+                        write_number(static_cast<uint16_t>(N));
+                    }
+                    else if (N <= 0xffffffff)
+                    {
+                        // array 32
+                        oa->write_character(0xdd);
+                        write_number(static_cast<uint32_t>(N));
                     }
-                }
-            }
-
-            // this code is reached if we parse a floating-point number or if
-            // an integer conversion above failed
-            strtof(value_float, yytext.data(), nullptr);
-            return token_type::value_float;
-        }
 
-        /*!
-        @param[in] literal_text  the literal text to expect
-        @param[in] length        the length of the passed literal text
-        @param[in] return_type   the token type to return on success
-        */
-        token_type scan_literal(const char* literal_text, const size_t length,
-                                token_type return_type)
-        {
-            assert(current == literal_text[0]);
-            for (size_t i = 1; i < length; ++i)
-            {
-                if (JSON_UNLIKELY(get() != literal_text[i]))
-                {
-                    error_message = "invalid literal";
-                    return token_type::parse_error;
+                    // step 2: write each element
+                    for (const auto& el : *j.m_value.array)
+                    {
+                        write_msgpack(el);
+                    }
+                    break;
                 }
-            }
-            return return_type;
-        }
-
-        /////////////////////
-        // input management
-        /////////////////////
-
-        /// reset yytext
-        void reset() noexcept
-        {
-            yylen = 0;
-            start_pos = chars_read - 1;
-        }
-
-        /// get a character from the input
-        int get()
-        {
-            ++chars_read;
-            return next_unget
-                   ? (next_unget = false, current)
-                   : (current = ia->get_character());
-        }
 
-        /// add a character to yytext
-        void add(int c)
-        {
-            // resize yytext if necessary; this condition is deemed unlikely,
-            // because we start with a 1024-byte buffer
-            if (JSON_UNLIKELY((yylen + 1 > yytext.capacity())))
-            {
-                yytext.resize(2 * yytext.capacity(), '\0');
-            }
-            assert(yylen < yytext.size());
-            yytext[yylen++] = static_cast<char>(c);
-        }
-
-      public:
-        /////////////////////
-        // value getters
-        /////////////////////
-
-        /// return integer value
-        constexpr number_integer_t get_number_integer() const noexcept
-        {
-            return value_integer;
-        }
-
-        /// return unsigned integer value
-        constexpr number_unsigned_t get_number_unsigned() const noexcept
-        {
-            return value_unsigned;
-        }
-
-        /// return floating-point value
-        constexpr number_float_t get_number_float() const noexcept
-        {
-            return value_float;
-        }
-
-        /// return string value
-        const std::string get_string()
-        {
-            // yytext cannot be returned as char*, because it may contain a
-            // null byte (parsed as "\u0000")
-            return std::string(yytext.data(), yylen);
-        }
-
-        /////////////////////
-        // diagnostics
-        /////////////////////
-
-        /// return position of last read token
-        constexpr size_t get_position() const noexcept
-        {
-            return chars_read;
-        }
-
-        /// return the last read token (for errors only)
-        std::string get_token_string() const
-        {
-            // get the raw byte sequence of the last token
-            std::string s = ia->read(start_pos, chars_read - start_pos);
-
-            // escape control characters
-            std::string result;
-            for (auto c : s)
-            {
-                if (c == '\0' or c == std::char_traits<char>::eof())
-                {
-                    // ignore EOF
-                    continue;
-                }
-                else if ('\x00' <= c and c <= '\x1f')
-                {
-                    // escape control characters
-                    std::stringstream ss;
-                    ss << "<U+" << std::setw(4) << std::uppercase << std::setfill('0') << std::hex << static_cast<int>(c) << ">";
-                    result += ss.str();
-                }
-                else
+                case value_t::object:
                 {
-                    // add character as is
-                    result.append(1, c);
-                }
-            }
-
-            return result;
-        }
-
-        /// return syntax error message
-        constexpr const char* get_error_message() const noexcept
-        {
-            return error_message;
-        }
-
-        /////////////////////
-        // actual scanner
-        /////////////////////
-
-        token_type scan()
-        {
-            // read next character and ignore whitespace
-            do
-            {
-                get();
-            }
-            while (current == ' ' or current == '\t' or current == '\n' or current == '\r');
-
-            switch (current)
-            {
-                // structural characters
-                case '[':
-                    return token_type::begin_array;
-                case ']':
-                    return token_type::end_array;
-                case '{':
-                    return token_type::begin_object;
-                case '}':
-                    return token_type::end_object;
-                case ':':
-                    return token_type::name_separator;
-                case ',':
-                    return token_type::value_separator;
-
-                // literals
-                case 't':
-                    return scan_literal("true", 4, token_type::literal_true);
-                case 'f':
-                    return scan_literal("false", 5, token_type::literal_false);
-                case 'n':
-                    return scan_literal("null", 4, token_type::literal_null);
-
-                // string
-                case '\"':
-                    return scan_string();
-
-                // number
-                case '-':
-                case '0':
-                case '1':
-                case '2':
-                case '3':
-                case '4':
-                case '5':
-                case '6':
-                case '7':
-                case '8':
-                case '9':
-                    return scan_number();
-
-                // end of input (the null byte is needed when parsing from
-                // string literals)
-                case '\0':
-                case std::char_traits<char>::eof():
-                    return token_type::end_of_input;
-
-                // error
-                default:
-                    error_message = "invalid literal";
-                    return token_type::parse_error;
-            }
-        }
-
-      private:
-        /// input adapter
-        detail::input_adapter_t ia = nullptr;
-
-        /// the current character
-        int current = std::char_traits<char>::eof();
-
-        /// whether get() should return the last character again
-        bool next_unget = false;
-
-        /// the number of characters read
-        size_t chars_read = 0;
-        /// the start position of the current token
-        size_t start_pos = 0;
-
-        /// buffer for variable-length tokens (numbers, strings)
-        std::vector<char> yytext = std::vector<char>(1024, '\0');
-        /// current index in yytext
-        size_t yylen = 0;
-
-        /// a description of occurred lexer errors
-        const char* error_message = "";
-
-        // number values
-        number_integer_t value_integer = 0;
-        number_unsigned_t value_unsigned = 0;
-        number_float_t value_float = 0;
-
-        /// the decimal point
-        const char decimal_point_char = '.';
-    };
-
-    /*!
-    @brief syntax analysis
-
-    This class implements a recursive decent parser.
-    */
-    class parser
-    {
-      public:
-        /// a parser reading from an input adapter
-        explicit parser(detail::input_adapter_t adapter,
-                        const parser_callback_t cb = nullptr)
-            : callback(cb), m_lexer(adapter)
-        {}
-
-        /*!
-        @brief public parser interface
-
-        @param[in] strict  whether to expect the last token to be EOF
-        @return parsed JSON value
-
-        @throw parse_error.101 in case of an unexpected token
-        @throw parse_error.102 if to_unicode fails or surrogate error
-        @throw parse_error.103 if to_unicode fails
-        */
-        basic_json parse(const bool strict = true)
-        {
-            // read first token
-            get_token();
+                    // step 1: write control byte and the object size
+                    const auto N = j.m_value.object->size();
+                    if (N <= 15)
+                    {
+                        // fixmap
+                        write_number(static_cast<uint8_t>(0x80 | (N & 0xf)));
+                    }
+                    else if (N <= 65535)
+                    {
+                        // map 16
+                        oa->write_character(0xde);
+                        write_number(static_cast<uint16_t>(N));
+                    }
+                    else if (N <= 4294967295)
+                    {
+                        // map 32
+                        oa->write_character(0xdf);
+                        write_number(static_cast<uint32_t>(N));
+                    }
 
-            basic_json result = parse_internal(true);
-            result.assert_invariant();
+                    // step 2: write each element
+                    for (const auto& el : *j.m_value.object)
+                    {
+                        write_msgpack(el.first);
+                        write_msgpack(el.second);
+                    }
+                    break;
+                }
 
-            if (strict)
-            {
-                get_token();
-                expect(lexer::token_type::end_of_input);
+                default:
+                {
+                    break;
+                }
             }
-
-            // return parser result and replace it with null in case the
-            // top-level value was discarded by the callback function
-            return result.is_discarded() ? basic_json() : std::move(result);
         }
 
-        /*!
-        @brief public accept interface
+      private:
+        /*
+        @brief write a number to output input
+
+        @param[in] n number of type @a NumberType
+        @tparam NumberType the type of the number
 
-        @param[in] strict  whether to expect the last token to be EOF
-        @return whether the input is a proper JSON text
+        @note This function needs to respect the system's endianess, because
+              bytes in CBOR and MessagePack are stored in network order (big
+              endian) and therefore need reordering on little endian systems.
         */
-        bool accept(const bool strict = true)
+        template<typename NumberType>
+        void write_number(NumberType n)
         {
-            // read first token
-            get_token();
-
-            if (not accept_internal())
-            {
-                return false;
-            }
+            // step 1: write number to array of length NumberType
+            std::array<uint8_t, sizeof(NumberType)> vec;
+            std::memcpy(vec.data(), &n, sizeof(NumberType));
 
-            if (strict and get_token() != lexer::token_type::end_of_input)
+            // step 2: write array to output (with possible reordering)
+            if (is_little_endian)
             {
-                return false;
+                // reverse byte order prior to conversion if necessary
+                std::reverse(vec.begin(), vec.end());
             }
 
-            return true;
+            oa->write_characters(vec.data(), sizeof(NumberType));
         }
 
       private:
-        /*!
-        @brief the actual parser
-        @throw parse_error.101 in case of an unexpected token
-        @throw parse_error.102 if to_unicode fails or surrogate error
-        @throw parse_error.103 if to_unicode fails
-        */
-        basic_json parse_internal(bool keep)
-        {
-            auto result = basic_json(value_t::discarded);
-
-            switch (last_token)
-            {
-                case lexer::token_type::begin_object:
-                {
-                    if (keep and (not callback
-                                  or ((keep = callback(depth++, parse_event_t::object_start, result)) != 0)))
-                    {
-                        // explicitly set result to object to cope with {}
-                        result.m_type = value_t::object;
-                        result.m_value = value_t::object;
-                    }
-
-                    // read next token
-                    get_token();
-
-                    // closing } -> we are done
-                    if (last_token == lexer::token_type::end_object)
-                    {
-                        if (keep and callback and not callback(--depth, parse_event_t::object_end, result))
-                        {
-                            result = basic_json(value_t::discarded);
-                        }
-                        return result;
-                    }
-
-                    // parse values
-                    while (true)
-                    {
-                        // store key
-                        expect(lexer::token_type::value_string);
-                        const auto key = m_lexer.get_string();
+        /// whether we can assume little endianess
+        const bool is_little_endian = true;
 
-                        bool keep_tag = false;
-                        if (keep)
-                        {
-                            if (callback)
-                            {
-                                basic_json k(key);
-                                keep_tag = callback(depth, parse_event_t::key, k);
-                            }
-                            else
-                            {
-                                keep_tag = true;
-                            }
-                        }
+        /// the output
+        output_adapter_t<uint8_t> oa = nullptr;
+    };
 
-                        // parse separator (:)
-                        get_token();
-                        expect(lexer::token_type::name_separator);
+  public:
+    /*!
+    @brief create a CBOR serialization of a given JSON value
 
-                        // parse and add value
-                        get_token();
-                        auto value = parse_internal(keep);
-                        if (keep and keep_tag and not value.is_discarded())
-                        {
-                            result[key] = std::move(value);
-                        }
+    Serializes a given JSON value @a j to a byte vector using the CBOR (Concise
+    Binary Object Representation) serialization format. CBOR is a binary
+    serialization format which aims to be more compact than JSON itself, yet
+    more efficient to parse.
 
-                        // comma -> next value
-                        get_token();
-                        if (last_token == lexer::token_type::value_separator)
-                        {
-                            get_token();
-                            continue;
-                        }
+    The library uses the following mapping from JSON values types to
+    CBOR types according to the CBOR specification (RFC 7049):
 
-                        // closing }
-                        expect(lexer::token_type::end_object);
-                        break;
-                    }
+    JSON value type | value/range                                | CBOR type                          | first byte
+    --------------- | ------------------------------------------ | ---------------------------------- | ---------------
+    null            | `null`                                     | Null                               | 0xf6
+    boolean         | `true`                                     | True                               | 0xf5
+    boolean         | `false`                                    | False                              | 0xf4
+    number_integer  | -9223372036854775808..-2147483649          | Negative integer (8 bytes follow)  | 0x3b
+    number_integer  | -2147483648..-32769                        | Negative integer (4 bytes follow)  | 0x3a
+    number_integer  | -32768..-129                               | Negative integer (2 bytes follow)  | 0x39
+    number_integer  | -128..-25                                  | Negative integer (1 byte follow)   | 0x38
+    number_integer  | -24..-1                                    | Negative integer                   | 0x20..0x37
+    number_integer  | 0..23                                      | Integer                            | 0x00..0x17
+    number_integer  | 24..255                                    | Unsigned integer (1 byte follow)   | 0x18
+    number_integer  | 256..65535                                 | Unsigned integer (2 bytes follow)  | 0x19
+    number_integer  | 65536..4294967295                          | Unsigned integer (4 bytes follow)  | 0x1a
+    number_integer  | 4294967296..18446744073709551615           | Unsigned integer (8 bytes follow)  | 0x1b
+    number_unsigned | 0..23                                      | Integer                            | 0x00..0x17
+    number_unsigned | 24..255                                    | Unsigned integer (1 byte follow)   | 0x18
+    number_unsigned | 256..65535                                 | Unsigned integer (2 bytes follow)  | 0x19
+    number_unsigned | 65536..4294967295                          | Unsigned integer (4 bytes follow)  | 0x1a
+    number_unsigned | 4294967296..18446744073709551615           | Unsigned integer (8 bytes follow)  | 0x1b
+    number_float    | *any value*                                | Double-Precision Float             | 0xfb
+    string          | *length*: 0..23                            | UTF-8 string                       | 0x60..0x77
+    string          | *length*: 23..255                          | UTF-8 string (1 byte follow)       | 0x78
+    string          | *length*: 256..65535                       | UTF-8 string (2 bytes follow)      | 0x79
+    string          | *length*: 65536..4294967295                | UTF-8 string (4 bytes follow)      | 0x7a
+    string          | *length*: 4294967296..18446744073709551615 | UTF-8 string (8 bytes follow)      | 0x7b
+    array           | *size*: 0..23                              | array                              | 0x80..0x97
+    array           | *size*: 23..255                            | array (1 byte follow)              | 0x98
+    array           | *size*: 256..65535                         | array (2 bytes follow)             | 0x99
+    array           | *size*: 65536..4294967295                  | array (4 bytes follow)             | 0x9a
+    array           | *size*: 4294967296..18446744073709551615   | array (8 bytes follow)             | 0x9b
+    object          | *size*: 0..23                              | map                                | 0xa0..0xb7
+    object          | *size*: 23..255                            | map (1 byte follow)                | 0xb8
+    object          | *size*: 256..65535                         | map (2 bytes follow)               | 0xb9
+    object          | *size*: 65536..4294967295                  | map (4 bytes follow)               | 0xba
+    object          | *size*: 4294967296..18446744073709551615   | map (8 bytes follow)               | 0xbb
 
-                    if (keep and callback and not callback(--depth, parse_event_t::object_end, result))
-                    {
-                        result = basic_json(value_t::discarded);
-                    }
+    @note The mapping is **complete** in the sense that any JSON value type
+          can be converted to a CBOR value.
 
-                    return result;
-                }
+    @note The following CBOR types are not used in the conversion:
+          - byte strings (0x40..0x5f)
+          - UTF-8 strings terminated by "break" (0x7f)
+          - arrays terminated by "break" (0x9f)
+          - maps terminated by "break" (0xbf)
+          - date/time (0xc0..0xc1)
+          - bignum (0xc2..0xc3)
+          - decimal fraction (0xc4)
+          - bigfloat (0xc5)
+          - tagged items (0xc6..0xd4, 0xd8..0xdb)
+          - expected conversions (0xd5..0xd7)
+          - simple values (0xe0..0xf3, 0xf8)
+          - undefined (0xf7)
+          - half and single-precision floats (0xf9-0xfa)
+          - break (0xff)
 
-                case lexer::token_type::begin_array:
-                {
-                    if (keep and (not callback
-                                  or ((keep = callback(depth++, parse_event_t::array_start, result)) != 0)))
-                    {
-                        // explicitly set result to object to cope with []
-                        result.m_type = value_t::array;
-                        result.m_value = value_t::array;
-                    }
+    @param[in] j  JSON value to serialize
+    @return MessagePack serialization as byte vector
 
-                    // read next token
-                    get_token();
+    @complexity Linear in the size of the JSON value @a j.
 
-                    // closing ] -> we are done
-                    if (last_token == lexer::token_type::end_array)
-                    {
-                        if (callback and not callback(--depth, parse_event_t::array_end, result))
-                        {
-                            result = basic_json(value_t::discarded);
-                        }
-                        return result;
-                    }
+    @liveexample{The example shows the serialization of a JSON value to a byte
+    vector in CBOR format.,to_cbor}
 
-                    // parse values
-                    while (true)
-                    {
-                        // parse value
-                        auto value = parse_internal(keep);
-                        if (keep and not value.is_discarded())
-                        {
-                            result.push_back(std::move(value));
-                        }
+    @sa http://cbor.io
+    @sa @ref from_cbor(const std::vector<uint8_t>&, const size_t) for the
+        analogous deserialization
+    @sa @ref to_msgpack(const basic_json& for the related MessagePack format
 
-                        // comma -> next value
-                        get_token();
-                        if (last_token == lexer::token_type::value_separator)
-                        {
-                            get_token();
-                            continue;
-                        }
+    @since version 2.0.9
+    */
+    static std::vector<uint8_t> to_cbor(const basic_json& j)
+    {
+        std::vector<uint8_t> result;
+        binary_writer bw(output_adapter<uint8_t>::create(result));
+        bw.write_cbor(j);
+        return result;
+    }
 
-                        // closing ]
-                        expect(lexer::token_type::end_array);
-                        break;
-                    }
+    /*!
+    @brief create a MessagePack serialization of a given JSON value
 
-                    if (keep and callback and not callback(--depth, parse_event_t::array_end, result))
-                    {
-                        result = basic_json(value_t::discarded);
-                    }
+    Serializes a given JSON value @a j to a byte vector using the MessagePack
+    serialization format. MessagePack is a binary serialization format which
+    aims to be more compact than JSON itself, yet more efficient to parse.
 
-                    return result;
-                }
+    The library uses the following mapping from JSON values types to
+    MessagePack types according to the MessagePack specification:
 
-                case lexer::token_type::literal_null:
-                {
-                    result.m_type = value_t::null;
-                    break;
-                }
+    JSON value type | value/range                       | MessagePack type | first byte
+    --------------- | --------------------------------- | ---------------- | ----------
+    null            | `null`                            | nil              | 0xc0
+    boolean         | `true`                            | true             | 0xc3
+    boolean         | `false`                           | false            | 0xc2
+    number_integer  | -9223372036854775808..-2147483649 | int64            | 0xd3
+    number_integer  | -2147483648..-32769               | int32            | 0xd2
+    number_integer  | -32768..-129                      | int16            | 0xd1
+    number_integer  | -128..-33                         | int8             | 0xd0
+    number_integer  | -32..-1                           | negative fixint  | 0xe0..0xff
+    number_integer  | 0..127                            | positive fixint  | 0x00..0x7f
+    number_integer  | 128..255                          | uint 8           | 0xcc
+    number_integer  | 256..65535                        | uint 16          | 0xcd
+    number_integer  | 65536..4294967295                 | uint 32          | 0xce
+    number_integer  | 4294967296..18446744073709551615  | uint 64          | 0xcf
+    number_unsigned | 0..127                            | positive fixint  | 0x00..0x7f
+    number_unsigned | 128..255                          | uint 8           | 0xcc
+    number_unsigned | 256..65535                        | uint 16          | 0xcd
+    number_unsigned | 65536..4294967295                 | uint 32          | 0xce
+    number_unsigned | 4294967296..18446744073709551615  | uint 64          | 0xcf
+    number_float    | *any value*                       | float 64         | 0xcb
+    string          | *length*: 0..31                   | fixstr           | 0xa0..0xbf
+    string          | *length*: 32..255                 | str 8            | 0xd9
+    string          | *length*: 256..65535              | str 16           | 0xda
+    string          | *length*: 65536..4294967295       | str 32           | 0xdb
+    array           | *size*: 0..15                     | fixarray         | 0x90..0x9f
+    array           | *size*: 16..65535                 | array 16         | 0xdc
+    array           | *size*: 65536..4294967295         | array 32         | 0xdd
+    object          | *size*: 0..15                     | fix map          | 0x80..0x8f
+    object          | *size*: 16..65535                 | map 16           | 0xde
+    object          | *size*: 65536..4294967295         | map 32           | 0xdf
 
-                case lexer::token_type::value_string:
-                {
-                    result = basic_json(m_lexer.get_string());
-                    break;
-                }
+    @note The mapping is **complete** in the sense that any JSON value type
+          can be converted to a MessagePack value.
 
-                case lexer::token_type::literal_true:
-                {
-                    result.m_type = value_t::boolean;
-                    result.m_value = true;
-                    break;
-                }
+    @note The following values can **not** be converted to a MessagePack value:
+          - strings with more than 4294967295 bytes
+          - arrays with more than 4294967295 elements
+          - objects with more than 4294967295 elements
 
-                case lexer::token_type::literal_false:
-                {
-                    result.m_type = value_t::boolean;
-                    result.m_value = false;
-                    break;
-                }
+    @note The following MessagePack types are not used in the conversion:
+          - bin 8 - bin 32 (0xc4..0xc6)
+          - ext 8 - ext 32 (0xc7..0xc9)
+          - float 32 (0xca)
+          - fixext 1 - fixext 16 (0xd4..0xd8)
 
-                case lexer::token_type::value_unsigned:
-                {
-                    result.m_type = value_t::number_unsigned;
-                    result.m_value = m_lexer.get_number_unsigned();
-                    break;
-                }
+    @note Any MessagePack output created @ref to_msgpack can be successfully
+          parsed by @ref from_msgpack.
 
-                case lexer::token_type::value_integer:
-                {
-                    result.m_type = value_t::number_integer;
-                    result.m_value = m_lexer.get_number_integer();
-                    break;
-                }
+    @param[in] j  JSON value to serialize
+    @return MessagePack serialization as byte vector
 
-                case lexer::token_type::value_float:
-                {
-                    result.m_type = value_t::number_float;
-                    result.m_value = m_lexer.get_number_float();
+    @complexity Linear in the size of the JSON value @a j.
 
-                    // throw in case of infinity or NAN
-                    if (JSON_UNLIKELY(not std::isfinite(result.m_value.number_float)))
-                    {
-                        JSON_THROW(out_of_range::create(406, "number overflow parsing '" + m_lexer.get_token_string() + "'"));
-                    }
+    @liveexample{The example shows the serialization of a JSON value to a byte
+    vector in MessagePack format.,to_msgpack}
 
-                    break;
-                }
+    @sa http://msgpack.org
+    @sa @ref from_msgpack(const std::vector<uint8_t>&, const size_t) for the
+        analogous deserialization
+    @sa @ref to_cbor(const basic_json& for the related CBOR format
 
-                case lexer::token_type::parse_error:
-                {
-                    // using "uninitialized" to avoid "expected" message
-                    expect(lexer::token_type::uninitialized);
-                    break;  // LCOV_EXCL_LINE
-                }
+    @since version 2.0.9
+    */
+    static std::vector<uint8_t> to_msgpack(const basic_json& j)
+    {
+        std::vector<uint8_t> result;
+        binary_writer bw(output_adapter<uint8_t>::create(result));
+        bw.write_msgpack(j);
+        return result;
+    }
 
-                default:
-                {
-                    // the last token was unexpected; we expected a value
-                    expect(lexer::token_type::literal_or_value);
-                    break;  // LCOV_EXCL_LINE
-                }
-            }
+    /*!
+    @brief create a JSON value from a byte vector in CBOR format
 
-            if (keep and callback and not callback(depth, parse_event_t::value, result))
-            {
-                result = basic_json(value_t::discarded);
-            }
-            return result;
-        }
+    Deserializes a given byte vector @a v to a JSON value using the CBOR
+    (Concise Binary Object Representation) serialization format.
 
-        /*!
-        @brief the acutal acceptor
+    The library maps CBOR types to JSON value types as follows:
 
-        @invariant 1. The last token is not yet processed. Therefore, the
-                      caller of this function must make sure a token has
-                      been read.
-                   2. When this function returns, the last token is processed.
-                      That is, the last read character was already considered.
+    CBOR type              | JSON value type | first byte
+    ---------------------- | --------------- | ----------
+    Integer                | number_unsigned | 0x00..0x17
+    Unsigned integer       | number_unsigned | 0x18
+    Unsigned integer       | number_unsigned | 0x19
+    Unsigned integer       | number_unsigned | 0x1a
+    Unsigned integer       | number_unsigned | 0x1b
+    Negative integer       | number_integer  | 0x20..0x37
+    Negative integer       | number_integer  | 0x38
+    Negative integer       | number_integer  | 0x39
+    Negative integer       | number_integer  | 0x3a
+    Negative integer       | number_integer  | 0x3b
+    Negative integer       | number_integer  | 0x40..0x57
+    UTF-8 string           | string          | 0x60..0x77
+    UTF-8 string           | string          | 0x78
+    UTF-8 string           | string          | 0x79
+    UTF-8 string           | string          | 0x7a
+    UTF-8 string           | string          | 0x7b
+    UTF-8 string           | string          | 0x7f
+    array                  | array           | 0x80..0x97
+    array                  | array           | 0x98
+    array                  | array           | 0x99
+    array                  | array           | 0x9a
+    array                  | array           | 0x9b
+    array                  | array           | 0x9f
+    map                    | object          | 0xa0..0xb7
+    map                    | object          | 0xb8
+    map                    | object          | 0xb9
+    map                    | object          | 0xba
+    map                    | object          | 0xbb
+    map                    | object          | 0xbf
+    False                  | `false`         | 0xf4
+    True                   | `true`          | 0xf5
+    Nill                   | `null`          | 0xf6
+    Half-Precision Float   | number_float    | 0xf9
+    Single-Precision Float | number_float    | 0xfa
+    Double-Precision Float | number_float    | 0xfb
 
-        This invariant makes sure that no token needs to be "unput".
-        */
-        bool accept_internal()
-        {
-            switch (last_token)
-            {
-                case lexer::token_type::begin_object:
-                {
-                    // read next token
-                    get_token();
+    @warning The mapping is **incomplete** in the sense that not all CBOR
+             types can be converted to a JSON value. The following CBOR types
+             are not supported and will yield parse errors (parse_error.112):
+             - byte strings (0x40..0x5f)
+             - date/time (0xc0..0xc1)
+             - bignum (0xc2..0xc3)
+             - decimal fraction (0xc4)
+             - bigfloat (0xc5)
+             - tagged items (0xc6..0xd4, 0xd8..0xdb)
+             - expected conversions (0xd5..0xd7)
+             - simple values (0xe0..0xf3, 0xf8)
+             - undefined (0xf7)
 
-                    // closing } -> we are done
-                    if (last_token == lexer::token_type::end_object)
-                    {
-                        return true;
-                    }
+    @warning CBOR allows map keys of any type, whereas JSON only allows
+             strings as keys in object values. Therefore, CBOR maps with keys
+             other than UTF-8 strings are rejected (parse_error.113).
 
-                    // parse values
-                    while (true)
-                    {
-                        // parse key
-                        if (last_token != lexer::token_type::value_string)
-                        {
-                            return false;
-                        }
+    @note Any CBOR output created @ref to_cbor can be successfully parsed by
+          @ref from_cbor.
 
-                        // parse separator (:)
-                        get_token();
-                        if (last_token != lexer::token_type::name_separator)
-                        {
-                            return false;
-                        }
+    @param[in] v  a byte vector in CBOR format
+    @param[in] start_index the index to start reading from @a v (0 by default)
+    @return deserialized JSON value
 
-                        // parse value
-                        get_token();
-                        if (not accept_internal())
-                        {
-                            return false;
-                        }
+    @throw parse_error.110 if the given vector ends prematurely
+    @throw parse_error.112 if unsupported features from CBOR were
+    used in the given vector @a v or if the input is not valid CBOR
+    @throw parse_error.113 if a string was expected as map key, but not found
 
-                        // comma -> next value
-                        get_token();
-                        if (last_token == lexer::token_type::value_separator)
-                        {
-                            get_token();
-                            continue;
-                        }
+    @complexity Linear in the size of the byte vector @a v.
 
-                        // closing }
-                        if (last_token != lexer::token_type::end_object)
-                        {
-                            return false;
-                        }
+    @liveexample{The example shows the deserialization of a byte vector in CBOR
+    format to a JSON value.,from_cbor}
 
-                        return true;
-                    }
-                }
+    @sa http://cbor.io
+    @sa @ref to_cbor(const basic_json&) for the analogous serialization
+    @sa @ref from_msgpack(const std::vector<uint8_t>&, const size_t) for the
+        related MessagePack format
 
-                case lexer::token_type::begin_array:
-                {
-                    // read next token
-                    get_token();
+    @since version 2.0.9, parameter @a start_index since 2.1.1
+    */
+    static basic_json from_cbor(const std::vector<uint8_t>& v,
+                                const size_t start_index = 0)
+    {
+        binary_reader br(detail::input_adapter_factory::create(v.begin() + static_cast<difference_type>(start_index), v.end()));
+        return br.parse_cbor();
+    }
 
-                    // closing ] -> we are done
-                    if (last_token == lexer::token_type::end_array)
-                    {
-                        return true;
-                    }
 
-                    // parse values
-                    while (true)
-                    {
-                        // parse value
-                        if (not accept_internal())
-                        {
-                            return false;
-                        }
+    /*!
+    @brief create a JSON value from a byte vector in MessagePack format
 
-                        // comma -> next value
-                        get_token();
-                        if (last_token == lexer::token_type::value_separator)
-                        {
-                            get_token();
-                            continue;
-                        }
+    Deserializes a given byte vector @a v to a JSON value using the MessagePack
+    serialization format.
 
-                        // closing ]
-                        if (last_token != lexer::token_type::end_array)
-                        {
-                            return false;
-                        }
+    The library maps MessagePack types to JSON value types as follows:
 
-                        return true;
-                    }
-                }
+    MessagePack type | JSON value type | first byte
+    ---------------- | --------------- | ----------
+    positive fixint  | number_unsigned | 0x00..0x7f
+    fixmap           | object          | 0x80..0x8f
+    fixarray         | array           | 0x90..0x9f
+    fixstr           | string          | 0xa0..0xbf
+    nil              | `null`          | 0xc0
+    false            | `false`         | 0xc2
+    true             | `true`          | 0xc3
+    float 32         | number_float    | 0xca
+    float 64         | number_float    | 0xcb
+    uint 8           | number_unsigned | 0xcc
+    uint 16          | number_unsigned | 0xcd
+    uint 32          | number_unsigned | 0xce
+    uint 64          | number_unsigned | 0xcf
+    int 8            | number_integer  | 0xd0
+    int 16           | number_integer  | 0xd1
+    int 32           | number_integer  | 0xd2
+    int 64           | number_integer  | 0xd3
+    str 8            | string          | 0xd9
+    str 16           | string          | 0xda
+    str 32           | string          | 0xdb
+    array 16         | array           | 0xdc
+    array 32         | array           | 0xdd
+    map 16           | object          | 0xde
+    map 32           | object          | 0xdf
+    negative fixint  | number_integer  | 0xe0-0xff
 
-                case lexer::token_type::literal_false:
-                case lexer::token_type::literal_null:
-                case lexer::token_type::literal_true:
-                case lexer::token_type::value_float:
-                case lexer::token_type::value_integer:
-                case lexer::token_type::value_string:
-                case lexer::token_type::value_unsigned:
-                {
-                    return true;
-                }
+    @warning The mapping is **incomplete** in the sense that not all
+             MessagePack types can be converted to a JSON value. The following
+             MessagePack types are not supported and will yield parse errors:
+              - bin 8 - bin 32 (0xc4..0xc6)
+              - ext 8 - ext 32 (0xc7..0xc9)
+              - fixext 1 - fixext 16 (0xd4..0xd8)
 
-                default:
-                {
-                    // the last token was unexpected
-                    return false;
-                }
-            }
-        }
+    @note Any MessagePack output created @ref to_msgpack can be successfully
+          parsed by @ref from_msgpack.
 
-        /// get next token from lexer
-        typename lexer::token_type get_token()
-        {
-            return (last_token = m_lexer.scan());
-        }
+    @param[in] v  a byte vector in MessagePack format
+    @param[in] start_index the index to start reading from @a v (0 by default)
+    @return deserialized JSON value
 
-        /*!
-        @throw parse_error.101 if expected token did not occur
-        */
-        void expect(typename lexer::token_type t)
-        {
-            if (JSON_UNLIKELY(t != last_token))
-            {
-                errored = true;
-                expected = t;
-                throw_exception();
-            }
-        }
+    @throw parse_error.110 if the given vector ends prematurely
+    @throw parse_error.112 if unsupported features from MessagePack were
+    used in the given vector @a v or if the input is not valid MessagePack
+    @throw parse_error.113 if a string was expected as map key, but not found
 
-        [[noreturn]] void throw_exception() const
-        {
-            std::string error_msg = "syntax error - ";
-            if (last_token == lexer::token_type::parse_error)
-            {
-                error_msg += std::string(m_lexer.get_error_message()) + "; last read: '" + m_lexer.get_token_string() + "'";
-            }
-            else
-            {
-                error_msg += "unexpected " + std::string(lexer::token_type_name(last_token));
-            }
+    @complexity Linear in the size of the byte vector @a v.
 
-            if (expected != lexer::token_type::uninitialized)
-            {
-                error_msg += "; expected " + std::string(lexer::token_type_name(expected));
-            }
+    @liveexample{The example shows the deserialization of a byte vector in
+    MessagePack format to a JSON value.,from_msgpack}
 
-            JSON_THROW(parse_error::create(101, m_lexer.get_position(), error_msg));
-        }
+    @sa http://msgpack.org
+    @sa @ref to_msgpack(const basic_json&) for the analogous serialization
+    @sa @ref from_cbor(const std::vector<uint8_t>&, const size_t) for the
+        related CBOR format
 
-      private:
-        /// current level of recursion
-        int depth = 0;
-        /// callback function
-        const parser_callback_t callback = nullptr;
-        /// the type of the last read token
-        typename lexer::token_type last_token = lexer::token_type::uninitialized;
-        /// the lexer
-        lexer m_lexer;
-        /// whether a syntax error occurred
-        bool errored = false;
-        /// possible reason for the syntax error
-        typename lexer::token_type expected = lexer::token_type::uninitialized;
-    };
+    @since version 2.0.9, parameter @a start_index since 2.1.1
+    */
+    static basic_json from_msgpack(const std::vector<uint8_t>& v,
+                                   const size_t start_index = 0)
+    {
+        binary_reader br(detail::input_adapter_factory::create(v.begin() + static_cast<difference_type>(start_index), v.end()));
+        return br.parse_msgpack();
+    }
+
+    /// @}
 
-  public:
     //////////////////////////
     // JSON Pointer support //
     //////////////////////////

From 00d6e2719404ee5407c8533f591e4b8363587395 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9o=20DELRIEU?= <delrieutheo@gmail.com>
Date: Sat, 1 Jul 2017 20:18:42 +0200
Subject: [PATCH 5/9] move primitive_iterator outside of basic_json

---
 src/json.hpp | 286 ++++++++++++++++++++++++++-------------------------
 1 file changed, 148 insertions(+), 138 deletions(-)

diff --git a/src/json.hpp b/src/json.hpp
index 8459c1a621..76359eaa52 100644
--- a/src/json.hpp
+++ b/src/json.hpp
@@ -3569,6 +3569,152 @@ class parser
     /// possible reason for the syntax error
     token_type expected = token_type::uninitialized;
 };
+
+///////////////
+// iterators //
+///////////////
+
+/*!
+@brief an iterator for primitive JSON types
+
+This class models an iterator for primitive JSON types (boolean, number,
+string). It's only purpose is to allow the iterator/const_iterator classes
+to "iterate" over primitive values. Internally, the iterator is modeled by
+a `difference_type` variable. Value begin_value (`0`) models the begin,
+end_value (`1`) models past the end.
+*/
+class primitive_iterator_t
+{
+  public:
+    using difference_type = std::ptrdiff_t;
+
+    difference_type get_value() const noexcept
+    {
+        return m_it;
+    }
+    /// set iterator to a defined beginning
+    void set_begin() noexcept
+    {
+        m_it = begin_value;
+    }
+
+    /// set iterator to a defined past the end
+    void set_end() noexcept
+    {
+        m_it = end_value;
+    }
+
+    /// return whether the iterator can be dereferenced
+    constexpr bool is_begin() const noexcept
+    {
+        return (m_it == begin_value);
+    }
+
+    /// return whether the iterator is at end
+    constexpr bool is_end() const noexcept
+    {
+        return (m_it == end_value);
+    }
+
+    friend constexpr bool operator==(primitive_iterator_t lhs,
+                                     primitive_iterator_t rhs) noexcept
+    {
+        return lhs.m_it == rhs.m_it;
+    }
+
+    friend constexpr bool operator!=(primitive_iterator_t lhs,
+                                     primitive_iterator_t rhs) noexcept
+    {
+        return !(lhs == rhs);
+    }
+
+    friend constexpr bool operator<(primitive_iterator_t lhs,
+                                    primitive_iterator_t rhs) noexcept
+    {
+        return lhs.m_it < rhs.m_it;
+    }
+
+    friend constexpr bool operator<=(primitive_iterator_t lhs,
+                                     primitive_iterator_t rhs) noexcept
+    {
+        return lhs.m_it <= rhs.m_it;
+    }
+
+    friend constexpr bool operator>(primitive_iterator_t lhs,
+                                    primitive_iterator_t rhs) noexcept
+    {
+        return lhs.m_it > rhs.m_it;
+    }
+
+    friend constexpr bool operator>=(primitive_iterator_t lhs,
+                                     primitive_iterator_t rhs) noexcept
+    {
+        return lhs.m_it >= rhs.m_it;
+    }
+
+    primitive_iterator_t operator+(difference_type i)
+    {
+        auto result = *this;
+        result += i;
+        return result;
+    }
+
+    friend constexpr difference_type
+    operator-(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
+    {
+        return lhs.m_it - rhs.m_it;
+    }
+
+    friend std::ostream& operator<<(std::ostream& os, primitive_iterator_t it)
+    {
+        return os << it.m_it;
+    }
+
+    primitive_iterator_t& operator++()
+    {
+        ++m_it;
+        return *this;
+    }
+
+    primitive_iterator_t operator++(int)
+    {
+        auto result = *this;
+        m_it++;
+        return result;
+    }
+
+    primitive_iterator_t& operator--()
+    {
+        --m_it;
+        return *this;
+    }
+
+    primitive_iterator_t operator--(int)
+    {
+        auto result = *this;
+        m_it--;
+        return result;
+    }
+
+    primitive_iterator_t& operator+=(difference_type n)
+    {
+        m_it += n;
+        return *this;
+    }
+
+    primitive_iterator_t& operator-=(difference_type n)
+    {
+        m_it -= n;
+        return *this;
+    }
+
+  private:
+    static constexpr difference_type begin_value = 0;
+    static constexpr difference_type end_value = begin_value + 1;
+
+    /// iterator as signed integer type
+    difference_type m_it = std::numeric_limits<std::ptrdiff_t>::denorm_min();
+};
 } // namespace detail
 
 /// namespace to hold default `to_json` / `from_json` functions
@@ -4047,6 +4193,8 @@ class basic_json
     using lexer = ::nlohmann::detail::lexer<basic_json>;
     using parser = ::nlohmann::detail::parser<basic_json>;
 
+    using primitive_iterator_t = ::nlohmann::detail::primitive_iterator_t;
+
   public:
     using value_t = detail::value_t;
     // forward declarations
@@ -10405,144 +10553,6 @@ class basic_json
 
 
   private:
-    ///////////////
-    // iterators //
-    ///////////////
-
-    /*!
-    @brief an iterator for primitive JSON types
-
-    This class models an iterator for primitive JSON types (boolean, number,
-    string). It's only purpose is to allow the iterator/const_iterator classes
-    to "iterate" over primitive values. Internally, the iterator is modeled by
-    a `difference_type` variable. Value begin_value (`0`) models the begin,
-    end_value (`1`) models past the end.
-    */
-    class primitive_iterator_t
-    {
-      public:
-
-        difference_type get_value() const noexcept
-        {
-            return m_it;
-        }
-        /// set iterator to a defined beginning
-        void set_begin() noexcept
-        {
-            m_it = begin_value;
-        }
-
-        /// set iterator to a defined past the end
-        void set_end() noexcept
-        {
-            m_it = end_value;
-        }
-
-        /// return whether the iterator can be dereferenced
-        constexpr bool is_begin() const noexcept
-        {
-            return (m_it == begin_value);
-        }
-
-        /// return whether the iterator is at end
-        constexpr bool is_end() const noexcept
-        {
-            return (m_it == end_value);
-        }
-
-        friend constexpr bool operator==(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
-        {
-            return lhs.m_it == rhs.m_it;
-        }
-
-        friend constexpr bool operator!=(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
-        {
-            return !(lhs == rhs);
-        }
-
-        friend constexpr bool operator<(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
-        {
-            return lhs.m_it < rhs.m_it;
-        }
-
-        friend constexpr bool operator<=(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
-        {
-            return lhs.m_it <= rhs.m_it;
-        }
-
-        friend constexpr bool operator>(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
-        {
-            return lhs.m_it > rhs.m_it;
-        }
-
-        friend constexpr bool operator>=(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
-        {
-            return lhs.m_it >= rhs.m_it;
-        }
-
-        primitive_iterator_t operator+(difference_type i)
-        {
-            auto result = *this;
-            result += i;
-            return result;
-        }
-
-        friend constexpr difference_type operator-(primitive_iterator_t lhs, primitive_iterator_t rhs) noexcept
-        {
-            return lhs.m_it - rhs.m_it;
-        }
-
-        friend std::ostream& operator<<(std::ostream& os, primitive_iterator_t it)
-        {
-            return os << it.m_it;
-        }
-
-        primitive_iterator_t& operator++()
-        {
-            ++m_it;
-            return *this;
-        }
-
-        primitive_iterator_t operator++(int)
-        {
-            auto result = *this;
-            m_it++;
-            return result;
-        }
-
-        primitive_iterator_t& operator--()
-        {
-            --m_it;
-            return *this;
-        }
-
-        primitive_iterator_t operator--(int)
-        {
-            auto result = *this;
-            m_it--;
-            return result;
-        }
-
-        primitive_iterator_t& operator+=(difference_type n)
-        {
-            m_it += n;
-            return *this;
-        }
-
-        primitive_iterator_t& operator-=(difference_type n)
-        {
-            m_it -= n;
-            return *this;
-        }
-
-      private:
-        static constexpr difference_type begin_value = 0;
-        static constexpr difference_type end_value = begin_value + 1;
-
-        /// iterator as signed integer type
-        difference_type m_it = std::numeric_limits<std::ptrdiff_t>::denorm_min();
-    };
-
     /*!
     @brief an iterator value
 

From 0ba98b6fe08f8f8e3060be1f8f3f3b7c4c23af3d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9o=20DELRIEU?= <delrieutheo@gmail.com>
Date: Sun, 9 Jul 2017 16:53:36 +0200
Subject: [PATCH 6/9] move internal_iterator/iter_impl/iteration_proxy outside
 of basic_json

---
 src/json.hpp | 11410 +++++++++++++++++++++++++------------------------
 1 file changed, 5712 insertions(+), 5698 deletions(-)

diff --git a/src/json.hpp b/src/json.hpp
index 76359eaa52..1e75b5e251 100644
--- a/src/json.hpp
+++ b/src/json.hpp
@@ -490,6 +490,10 @@ inline bool operator<(const value_t lhs, const value_t rhs) noexcept
 // helpers //
 /////////////
 
+template <typename> struct is_basic_json : std::false_type {};
+
+NLOHMANN_BASIC_JSON_TPL_DECLARATION struct is_basic_json<NLOHMANN_BASIC_JSON_TPL> : std::true_type {};
+
 // alias templates to reduce boilerplate
 template<bool B, typename T = void>
 using enable_if_t = typename std::enable_if<B, T>::type;
@@ -3715,2407 +3719,2822 @@ class primitive_iterator_t
     /// iterator as signed integer type
     difference_type m_it = std::numeric_limits<std::ptrdiff_t>::denorm_min();
 };
-} // namespace detail
 
-/// namespace to hold default `to_json` / `from_json` functions
-namespace
+/*!
+@brief an iterator value
+
+@note This structure could easily be a union, but MSVC currently does not
+allow unions members with complex constructors, see
+https://github.com/nlohmann/json/pull/105.
+*/
+template <typename BasicJsonType> struct internal_iterator
 {
-constexpr const auto& to_json = detail::static_const<detail::to_json_fn>::value;
-constexpr const auto& from_json = detail::static_const<detail::from_json_fn>::value;
-}
+    /// iterator for JSON objects
+    typename BasicJsonType::object_t::iterator object_iterator;
+    /// iterator for JSON arrays
+    typename BasicJsonType::array_t::iterator array_iterator;
+    /// generic iterator for all other types
+    primitive_iterator_t primitive_iterator;
+
+    /// create an uninitialized internal_iterator
+    internal_iterator() noexcept : object_iterator(),
+        array_iterator(),
+        primitive_iterator() {}
+};
 
+template <typename IteratorType> class iteration_proxy;
 
 /*!
-@brief default JSONSerializer template argument
+@brief a template for a random access iterator for the @ref basic_json class
 
-This serializer ignores the template arguments and uses ADL
-([argument-dependent lookup](http://en.cppreference.com/w/cpp/language/adl))
-for serialization.
+This class implements a both iterators (iterator and const_iterator) for the
+@ref basic_json class.
+
+@note An iterator is called *initialized* when a pointer to a JSON value
+      has been set (e.g., by a constructor or a copy assignment). If the
+      iterator is default-constructed, it is *uninitialized* and most
+      methods are undefined. **The library uses assertions to detect calls
+      on uninitialized iterators.**
+
+@requirement The class satisfies the following concept requirements:
+-
+[RandomAccessIterator](http://en.cppreference.com/w/cpp/concept/RandomAccessIterator):
+  The iterator that can be moved to point (forward and backward) to any
+  element in constant time.
+
+@since version 1.0.0, simplified in version 2.0.9
 */
-template<typename, typename>
-struct adl_serializer
+template <typename BasicJsonType>
+class iter_impl : public std::iterator<std::random_access_iterator_tag, BasicJsonType>
 {
-    /*!
-    @brief convert a JSON value to any value type
+    /// allow basic_json to access private members
+    friend iter_impl<typename std::conditional<std::is_const<BasicJsonType>::value, typename std::remove_const<BasicJsonType>::type, const BasicJsonType>::type>;
+    friend BasicJsonType;
+    friend iteration_proxy<iter_impl>;
 
-    This function is usually called by the `get()` function of the
-    @ref basic_json class (either explicit or via conversion operators).
+    using object_t = typename BasicJsonType::object_t;
+    using array_t = typename BasicJsonType::array_t;
+    // make sure BasicJsonType is basic_json or const basic_json
+    static_assert(is_basic_json<typename std::remove_const<BasicJsonType>::type>::value,
+                  "iter_impl only accepts (const) basic_json");
 
-    @param[in] j         JSON value to read from
-    @param[in,out] val  value to write to
+  public:
+    /// the type of the values when the iterator is dereferenced
+    using value_type = typename BasicJsonType::value_type;
+    /// a type to represent differences between iterators
+    using difference_type = typename BasicJsonType::difference_type;
+    /// defines a pointer to the type iterated over (value_type)
+    using pointer = typename std::conditional<std::is_const<BasicJsonType>::value,
+          typename BasicJsonType::const_pointer,
+          typename BasicJsonType::pointer>::type;
+    /// defines a reference to the type iterated over (value_type)
+    using reference =
+        typename std::conditional<std::is_const<BasicJsonType>::value,
+        typename BasicJsonType::const_reference,
+        typename BasicJsonType::reference>::type;
+    /// the category of the iterator
+    using iterator_category = std::bidirectional_iterator_tag;
+
+    /// default constructor
+    iter_impl() = default;
+
+    /*!
+    @brief constructor for a given JSON instance
+    @param[in] object  pointer to a JSON object for this iterator
+    @pre object != nullptr
+    @post The iterator is initialized; i.e. `m_object != nullptr`.
     */
-    template<typename BasicJsonType, typename ValueType>
-    static void from_json(BasicJsonType&& j, ValueType& val) noexcept(
-        noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), val)))
+    explicit iter_impl(pointer object) noexcept : m_object(object)
     {
-        ::nlohmann::from_json(std::forward<BasicJsonType>(j), val);
+        assert(m_object != nullptr);
+
+        switch (m_object->m_type)
+        {
+            case value_t::object:
+            {
+                m_it.object_iterator = typename object_t::iterator();
+                break;
+            }
+
+            case value_t::array:
+            {
+                m_it.array_iterator = typename array_t::iterator();
+                break;
+            }
+
+            default:
+            {
+                m_it.primitive_iterator = primitive_iterator_t();
+                break;
+            }
+        }
     }
 
     /*!
-    @brief convert any value type to a JSON value
+    @note The conventional copy constructor and copy assignment are
+          implicitly defined.
+          Combined with the following converting constructor and assignment,
+          they support: copy from iterator to iterator,
+                        copy from const iterator to const iterator,
+                        and conversion from iterator to const iterator.
+          However conversion from const iterator to iterator is not defined.
+    */
 
-    This function is usually called by the constructors of the @ref basic_json
-    class.
+    /*!
+    @brief converting constructor
+    @param[in] other  non-const iterator to copy from
+    @note It is not checked whether @a other is initialized.
+    */
+    iter_impl(const iter_impl<typename std::remove_const<BasicJsonType>::type>& other) noexcept
+        : m_object(other.m_object),
+          m_it(other.m_it) {}
 
-    @param[in,out] j  JSON value to write to
-    @param[in] val     value to read from
+    /*!
+    @brief converting assignment
+    @param[in,out] other  non-const iterator to copy from
+    @return const/non-const iterator
+    @note It is not checked whether @a other is initialized.
     */
-    template<typename BasicJsonType, typename ValueType>
-    static void to_json(BasicJsonType& j, ValueType&& val) noexcept(
-        noexcept(::nlohmann::to_json(j, std::forward<ValueType>(val))))
+    iter_impl& operator=(const iter_impl<typename std::remove_const<BasicJsonType>::type>& other) noexcept
     {
-        ::nlohmann::to_json(j, std::forward<ValueType>(val));
+        m_object = other.m_object;
+        m_it = other.m_it;
+        return *this;
     }
-};
 
-/*!
-@brief JSON Pointer
+  private:
+    /*!
+    @brief set the iterator to the first value
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    void set_begin() noexcept
+    {
+        assert(m_object != nullptr);
 
-A JSON pointer defines a string syntax for identifying a specific value
-within a JSON document. It can be used with functions `at` and
-`operator[]`. Furthermore, JSON pointers are the base for JSON patches.
+        switch (m_object->m_type)
+        {
+            case value_t::object:
+            {
+                m_it.object_iterator = m_object->m_value.object->begin();
+                break;
+            }
 
-@sa [RFC 6901](https://tools.ietf.org/html/rfc6901)
+            case value_t::array:
+            {
+                m_it.array_iterator = m_object->m_value.array->begin();
+                break;
+            }
 
-@since version 2.0.0
-*/
-class json_pointer
-{
-    /// allow basic_json to access private members
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    friend class basic_json;
+            case value_t::null:
+            {
+                // set to end so begin()==end() is true: null is empty
+                m_it.primitive_iterator.set_end();
+                break;
+            }
 
-  public:
-    /*!
-      @brief create JSON pointer
+            default:
+            {
+                m_it.primitive_iterator.set_begin();
+                break;
+            }
+        }
+    }
 
-      Create a JSON pointer according to the syntax described in
-      [Section 3 of RFC6901](https://tools.ietf.org/html/rfc6901#section-3).
+    /*!
+    @brief set the iterator past the last value
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    void set_end() noexcept
+    {
+        assert(m_object != nullptr);
 
-      @param[in] s  string representing the JSON pointer; if omitted, the
-      empty string is assumed which references the whole JSON
-      value
+        switch (m_object->m_type)
+        {
+            case value_t::object:
+            {
+                m_it.object_iterator = m_object->m_value.object->end();
+                break;
+            }
 
-      @throw parse_error.107 if the given JSON pointer @a s is nonempty and
-      does not begin with a slash (`/`); see example below
+            case value_t::array:
+            {
+                m_it.array_iterator = m_object->m_value.array->end();
+                break;
+            }
 
-      @throw parse_error.108 if a tilde (`~`) in the given JSON pointer @a s
-      is not followed by `0` (representing `~`) or `1` (representing `/`);
-      see example below
+            default:
+            {
+                m_it.primitive_iterator.set_end();
+                break;
+            }
+        }
+    }
 
-      @liveexample{The example shows the construction several valid JSON
-      pointers as well as the exceptional behavior.,json_pointer}
+  public:
+    /*!
+    @brief return a reference to the value pointed to by the iterator
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    reference operator*() const
+    {
+        assert(m_object != nullptr);
 
-      @since version 2.0.0
-      */
-    explicit json_pointer(const std::string& s = "") : reference_tokens(split(s)) {}
+        switch (m_object->m_type)
+        {
+            case value_t::object:
+            {
+                assert(m_it.object_iterator != m_object->m_value.object->end());
+                return m_it.object_iterator->second;
+            }
 
-    /*!
-      @brief return a string representation of the JSON pointer
+            case value_t::array:
+            {
+                assert(m_it.array_iterator != m_object->m_value.array->end());
+                return *m_it.array_iterator;
+            }
 
-      @invariant For each JSON pointer `ptr`, it holds:
-      @code {.cpp}
-      ptr == json_pointer(ptr.to_string());
-      @endcode
+            case value_t::null:
+            {
+                JSON_THROW(invalid_iterator::create(214, "cannot get value"));
+            }
 
-      @return a string representation of the JSON pointer
+            default:
+            {
+                if (m_it.primitive_iterator.is_begin())
+                {
+                    return *m_object;
+                }
 
-      @liveexample{The example shows the result of `to_string`.,
-      json_pointer__to_string}
+                JSON_THROW(invalid_iterator::create(214, "cannot get value"));
+            }
+        }
+    }
 
-      @since version 2.0.0
-      */
-    std::string to_string() const noexcept
+    /*!
+    @brief dereference the iterator
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    pointer operator->() const
     {
-        return std::accumulate(reference_tokens.begin(), reference_tokens.end(),
-                               std::string{},
-                               [](const std::string & a, const std::string & b)
+        assert(m_object != nullptr);
+
+        switch (m_object->m_type)
         {
-            return a + "/" + escape(b);
-        });
+            case value_t::object:
+            {
+                assert(m_it.object_iterator != m_object->m_value.object->end());
+                return &(m_it.object_iterator->second);
+            }
+
+            case value_t::array:
+            {
+                assert(m_it.array_iterator != m_object->m_value.array->end());
+                return &*m_it.array_iterator;
+            }
+
+            default:
+            {
+                if (m_it.primitive_iterator.is_begin())
+                {
+                    return m_object;
+                }
+
+                JSON_THROW(invalid_iterator::create(214, "cannot get value"));
+            }
+        }
     }
 
-    /// @copydoc to_string()
-    operator std::string() const
+    /*!
+    @brief post-increment (it++)
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    iter_impl operator++(int)
     {
-        return to_string();
+        auto result = *this;
+        ++(*this);
+        return result;
     }
 
-  private:
     /*!
-      @brief remove and return last reference pointer
-      @throw out_of_range.405 if JSON pointer has no parent
-      */
-    std::string pop_back()
+    @brief pre-increment (++it)
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    iter_impl& operator++()
     {
-        if (is_root())
+        assert(m_object != nullptr);
+
+        switch (m_object->m_type)
         {
-            JSON_THROW(
-                detail::out_of_range::create(405, "JSON pointer has no parent"));
+            case value_t::object:
+            {
+                std::advance(m_it.object_iterator, 1);
+                break;
+            }
+
+            case value_t::array:
+            {
+                std::advance(m_it.array_iterator, 1);
+                break;
+            }
+
+            default:
+            {
+                ++m_it.primitive_iterator;
+                break;
+            }
         }
 
-        auto last = reference_tokens.back();
-        reference_tokens.pop_back();
-        return last;
+        return *this;
     }
 
-    /// return whether pointer points to the root document
-    bool is_root() const
+    /*!
+    @brief post-decrement (it--)
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    iter_impl operator--(int)
     {
-        return reference_tokens.empty();
+        auto result = *this;
+        --(*this);
+        return result;
     }
 
-    json_pointer top() const
+    /*!
+    @brief pre-decrement (--it)
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    iter_impl& operator--()
     {
-        if (is_root())
+        assert(m_object != nullptr);
+
+        switch (m_object->m_type)
         {
-            JSON_THROW(detail::out_of_range::create(405, "JSON pointer has no parent"));
-        }
+            case value_t::object:
+            {
+                std::advance(m_it.object_iterator, -1);
+                break;
+            }
 
-        json_pointer result = *this;
-        result.reference_tokens = {reference_tokens[0]};
-        return result;
-    }
-
-
-    /*!
-      @brief create and return a reference to the pointed to value
+            case value_t::array:
+            {
+                std::advance(m_it.array_iterator, -1);
+                break;
+            }
 
-      @complexity Linear in the number of reference tokens.
+            default:
+            {
+                --m_it.primitive_iterator;
+                break;
+            }
+        }
 
-      @throw parse_error.109 if array index is not a number
-      @throw type_error.313 if value cannot be unflattened
-      */
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    NLOHMANN_BASIC_JSON_TPL& get_and_create(NLOHMANN_BASIC_JSON_TPL& j) const;
+        return *this;
+    }
 
     /*!
-      @brief return a reference to the pointed to value
-
-      @note This version does not throw if a value is not present, but tries
-      to create nested values instead. For instance, calling this function
-      with pointer `"/this/that"` on a null value is equivalent to calling
-      `operator[]("this").operator[]("that")` on that value, effectively
-      changing the null value to an object.
+    @brief  comparison: equal
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    bool operator==(const iter_impl& other) const
+    {
+        // if objects are not the same, the comparison is undefined
+        if (m_object != other.m_object)
+        {
+            JSON_THROW(invalid_iterator::create(
+                           212, "cannot compare iterators of different containers"));
+        }
 
-      @param[in] ptr  a JSON value
+        assert(m_object != nullptr);
 
-      @return reference to the JSON value pointed to by the JSON pointer
+        switch (m_object->m_type)
+        {
+            case value_t::object:
+            {
+                return (m_it.object_iterator == other.m_it.object_iterator);
+            }
 
-      @complexity Linear in the length of the JSON pointer.
+            case value_t::array:
+            {
+                return (m_it.array_iterator == other.m_it.array_iterator);
+            }
 
-      @throw parse_error.106   if an array index begins with '0'
-      @throw parse_error.109   if an array index was not a number
-      @throw out_of_range.404  if the JSON pointer can not be resolved
-      */
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    NLOHMANN_BASIC_JSON_TPL& get_unchecked(NLOHMANN_BASIC_JSON_TPL* ptr) const;
+            default:
+            {
+                return (m_it.primitive_iterator == other.m_it.primitive_iterator);
+            }
+        }
+    }
 
     /*!
-      @throw parse_error.106   if an array index begins with '0'
-      @throw parse_error.109   if an array index was not a number
-      @throw out_of_range.402  if the array index '-' is used
-      @throw out_of_range.404  if the JSON pointer can not be resolved
-      */
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    NLOHMANN_BASIC_JSON_TPL& get_checked(NLOHMANN_BASIC_JSON_TPL* ptr) const;
+    @brief  comparison: not equal
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    bool operator!=(const iter_impl& other) const
+    {
+        return not operator==(other);
+    }
 
     /*!
-      @brief return a const reference to the pointed to value
+    @brief  comparison: smaller
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    bool operator<(const iter_impl& other) const
+    {
+        // if objects are not the same, the comparison is undefined
+        if (m_object != other.m_object)
+        {
+            JSON_THROW(invalid_iterator::create(
+                           212, "cannot compare iterators of different containers"));
+        }
 
-      @param[in] ptr  a JSON value
+        assert(m_object != nullptr);
 
-      @return const reference to the JSON value pointed to by the JSON
-      pointer
+        switch (m_object->m_type)
+        {
+            case value_t::object:
+            {
+                JSON_THROW(invalid_iterator::create(
+                               213, "cannot compare order of object iterators"));
+            }
 
-      @throw parse_error.106   if an array index begins with '0'
-      @throw parse_error.109   if an array index was not a number
-      @throw out_of_range.402  if the array index '-' is used
-      @throw out_of_range.404  if the JSON pointer can not be resolved
-      */
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    const NLOHMANN_BASIC_JSON_TPL& get_unchecked(const NLOHMANN_BASIC_JSON_TPL* ptr) const;
+            case value_t::array:
+            {
+                return (m_it.array_iterator < other.m_it.array_iterator);
+            }
 
-    /*!
-      @throw parse_error.106   if an array index begins with '0'
-      @throw parse_error.109   if an array index was not a number
-      @throw out_of_range.402  if the array index '-' is used
-      @throw out_of_range.404  if the JSON pointer can not be resolved
-      */
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    const NLOHMANN_BASIC_JSON_TPL& get_checked(const NLOHMANN_BASIC_JSON_TPL* ptr) const;
+            default:
+            {
+                return (m_it.primitive_iterator < other.m_it.primitive_iterator);
+            }
+        }
+    }
 
     /*!
-      @brief split the string input to reference tokens
-
-      @note This function is only called by the json_pointer constructor.
-      All exceptions below are documented there.
+    @brief  comparison: less than or equal
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    bool operator<=(const iter_impl& other) const
+    {
+        return not other.operator < (*this);
+    }
 
-      @throw parse_error.107  if the pointer is not empty or begins with '/'
-      @throw parse_error.108  if character '~' is not followed by '0' or '1'
-      */
-    static std::vector<std::string> split(const std::string& reference_string)
+    /*!
+    @brief  comparison: greater than
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    bool operator>(const iter_impl& other) const
     {
-        std::vector<std::string> result;
+        return not operator<=(other);
+    }
 
-        // special case: empty reference string -> no reference tokens
-        if (reference_string.empty())
-        {
-            return result;
-        }
+    /*!
+    @brief  comparison: greater than or equal
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    bool operator>=(const iter_impl& other) const
+    {
+        return not operator<(other);
+    }
 
-        // check if nonempty reference string begins with slash
-        if (reference_string[0] != '/')
-        {
-            JSON_THROW(detail::parse_error::create(
-                           107, 1,
-                           "JSON pointer must be empty or begin with '/' - was: '" +
-                           reference_string + "'"));
-        }
+    /*!
+    @brief  add to iterator
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    iter_impl& operator+=(difference_type i)
+    {
+        assert(m_object != nullptr);
 
-        // extract the reference tokens:
-        // - slash: position of the last read slash (or end of string)
-        // - start: position after the previous slash
-        for (
-            // search for the first slash after the first character
-            size_t slash = reference_string.find_first_of('/', 1),
-            // set the beginning of the first reference token
-            start = 1;
-            // we can stop if start == string::npos+1 = 0
-            start != 0;
-            // set the beginning of the next reference token
-            // (will eventually be 0 if slash == std::string::npos)
-            start = slash + 1,
-            // find next slash
-            slash = reference_string.find_first_of('/', start))
+        switch (m_object->m_type)
         {
-            // use the text between the beginning of the reference token
-            // (start) and the last slash (slash).
-            auto reference_token = reference_string.substr(start, slash - start);
-
-            // check reference tokens are properly escaped
-            for (size_t pos = reference_token.find_first_of('~');
-                    pos != std::string::npos;
-                    pos = reference_token.find_first_of('~', pos + 1))
+            case value_t::object:
             {
-                assert(reference_token[pos] == '~');
+                JSON_THROW(invalid_iterator::create(
+                               209, "cannot use offsets with object iterators"));
+            }
 
-                // ~ must be followed by 0 or 1
-                if (pos == reference_token.size() - 1 or
-                        (reference_token[pos + 1] != '0' and
-                         reference_token[pos + 1] != '1'))
-                {
-                    JSON_THROW(detail::parse_error::create(
-                                   108, 0, "escape character '~' must be followed with '0' or '1'"));
-                }
+            case value_t::array:
+            {
+                std::advance(m_it.array_iterator, i);
+                break;
             }
 
-            // finally, store the reference token
-            unescape(reference_token);
-            result.push_back(reference_token);
+            default:
+            {
+                m_it.primitive_iterator += i;
+                break;
+            }
         }
 
-        return result;
+        return *this;
     }
 
     /*!
-      @brief replace all occurrences of a substring by another string
-
-      @param[in,out] s  the string to manipulate; changed so that all
-      occurrences of @a f are replaced with @a t
-      @param[in]     f  the substring to replace with @a t
-      @param[in]     t  the string to replace @a f
-
-      @pre The search string @a f must not be empty. **This precondition is
-      enforced with an assertion.**
-
-      @since version 2.0.0
-      */
-    static void replace_substring(std::string& s, const std::string& f,
-                                  const std::string& t)
+    @brief  subtract from iterator
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    iter_impl& operator-=(difference_type i)
     {
-        assert(not f.empty());
-
-        for (size_t pos = s.find(f);         // find first occurrence of f
-                pos != std::string::npos;       // make sure f was found
-                s.replace(pos, f.size(), t),    // replace with t
-                pos = s.find(f, pos + t.size()) // find next occurrence of f
-            )
-            ;
+        return operator+=(-i);
     }
 
-    /// escape tilde and slash
-    static std::string escape(std::string s)
+    /*!
+    @brief  add to iterator
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    iter_impl operator+(difference_type i) const
     {
-        // escape "~"" to "~0" and "/" to "~1"
-        replace_substring(s, "~", "~0");
-        replace_substring(s, "/", "~1");
-        return s;
+        auto result = *this;
+        result += i;
+        return result;
     }
 
-    /// unescape tilde and slash
-    static void unescape(std::string& s)
+    /*!
+    @brief  addition of distance and iterator
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    friend iter_impl operator+(difference_type i, const iter_impl& it)
     {
-        // first transform any occurrence of the sequence '~1' to '/'
-        replace_substring(s, "~1", "/");
-        // then transform any occurrence of the sequence '~0' to '~'
-        replace_substring(s, "~0", "~");
+        auto result = it;
+        result += i;
+        return result;
     }
 
     /*!
-      @param[in] reference_string  the reference string to the current value
-      @param[in] value             the value to consider
-      @param[in,out] result        the result object to insert values to
-
-      @note Empty objects or arrays are flattened to `null`.
-      */
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    static void flatten(const std::string& reference_string,
-                        const NLOHMANN_BASIC_JSON_TPL& value,
-                        NLOHMANN_BASIC_JSON_TPL& result);
+    @brief  subtract from iterator
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    iter_impl operator-(difference_type i) const
+    {
+        auto result = *this;
+        result -= i;
+        return result;
+    }
 
     /*!
-      @param[in] value  flattened JSON
+    @brief  return difference
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    difference_type operator-(const iter_impl& other) const
+    {
+        assert(m_object != nullptr);
 
-      @return unflattened JSON
+        switch (m_object->m_type)
+        {
+            case value_t::object:
+            {
+                JSON_THROW(invalid_iterator::create(
+                               209, "cannot use offsets with object iterators"));
+            }
 
-      @throw parse_error.109 if array index is not a number
-      @throw type_error.314  if value is not an object
-      @throw type_error.315  if object values are not primitive
-      @throw type_error.313  if value cannot be unflattened
-      */
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    static NLOHMANN_BASIC_JSON_TPL
-    unflatten(const NLOHMANN_BASIC_JSON_TPL& value);
+            case value_t::array:
+            {
+                return m_it.array_iterator - other.m_it.array_iterator;
+            }
 
-    friend bool operator==(json_pointer const& lhs,
-                           json_pointer const& rhs) noexcept;
+            default:
+            {
+                return m_it.primitive_iterator - other.m_it.primitive_iterator;
+            }
+        }
+    }
 
-    friend bool operator!=(json_pointer const& lhs,
-                           json_pointer const& rhs) noexcept;
+    /*!
+    @brief  access to successor
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    reference operator[](difference_type n) const
+    {
+        assert(m_object != nullptr);
 
-    /// the reference tokens
-    std::vector<std::string> reference_tokens;
-};
+        switch (m_object->m_type)
+        {
+            case value_t::object:
+            {
+                JSON_THROW(invalid_iterator::create(
+                               208, "cannot use operator[] for object iterators"));
+            }
 
-/*!
-@brief a class to store JSON values
+            case value_t::array:
+            {
+                return *std::next(m_it.array_iterator, n);
+            }
 
-@tparam ObjectType type for JSON objects (`std::map` by default; will be used
-in @ref object_t)
-@tparam ArrayType type for JSON arrays (`std::vector` by default; will be used
-in @ref array_t)
-@tparam StringType type for JSON strings and object keys (`std::string` by
-default; will be used in @ref string_t)
-@tparam BooleanType type for JSON booleans (`bool` by default; will be used
-in @ref boolean_t)
-@tparam NumberIntegerType type for JSON integer numbers (`int64_t` by
-default; will be used in @ref number_integer_t)
-@tparam NumberUnsignedType type for JSON unsigned integer numbers (@c
-`uint64_t` by default; will be used in @ref number_unsigned_t)
-@tparam NumberFloatType type for JSON floating-point numbers (`double` by
-default; will be used in @ref number_float_t)
-@tparam AllocatorType type of the allocator to use (`std::allocator` by
-default)
-@tparam JSONSerializer the serializer to resolve internal calls to `to_json()`
-and `from_json()` (@ref adl_serializer by default)
+            case value_t::null:
+            {
+                JSON_THROW(invalid_iterator::create(214, "cannot get value"));
+            }
 
-@requirement The class satisfies the following concept requirements:
-- Basic
- - [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible):
-   JSON values can be default constructed. The result will be a JSON null
-   value.
- - [MoveConstructible](http://en.cppreference.com/w/cpp/concept/MoveConstructible):
-   A JSON value can be constructed from an rvalue argument.
- - [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible):
-   A JSON value can be copy-constructed from an lvalue expression.
- - [MoveAssignable](http://en.cppreference.com/w/cpp/concept/MoveAssignable):
-   A JSON value van be assigned from an rvalue argument.
- - [CopyAssignable](http://en.cppreference.com/w/cpp/concept/CopyAssignable):
-   A JSON value can be copy-assigned from an lvalue expression.
- - [Destructible](http://en.cppreference.com/w/cpp/concept/Destructible):
-   JSON values can be destructed.
-- Layout
- - [StandardLayoutType](http://en.cppreference.com/w/cpp/concept/StandardLayoutType):
-   JSON values have
-   [standard layout](http://en.cppreference.com/w/cpp/language/data_members#Standard_layout):
-   All non-static data members are private and standard layout types, the
-   class has no virtual functions or (virtual) base classes.
-- Library-wide
- - [EqualityComparable](http://en.cppreference.com/w/cpp/concept/EqualityComparable):
-   JSON values can be compared with `==`, see @ref
-   operator==(const_reference,const_reference).
- - [LessThanComparable](http://en.cppreference.com/w/cpp/concept/LessThanComparable):
-   JSON values can be compared with `<`, see @ref
-   operator<(const_reference,const_reference).
- - [Swappable](http://en.cppreference.com/w/cpp/concept/Swappable):
-   Any JSON lvalue or rvalue of can be swapped with any lvalue or rvalue of
-   other compatible types, using unqualified function call @ref swap().
- - [NullablePointer](http://en.cppreference.com/w/cpp/concept/NullablePointer):
-   JSON values can be compared against `std::nullptr_t` objects which are used
-   to model the `null` value.
-- Container
- - [Container](http://en.cppreference.com/w/cpp/concept/Container):
-   JSON values can be used like STL containers and provide iterator access.
- - [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer);
-   JSON values can be used like STL containers and provide reverse iterator
-   access.
+            default:
+            {
+                if (m_it.primitive_iterator.get_value() == -n)
+                {
+                    return *m_object;
+                }
 
-@invariant The member variables @a m_value and @a m_type have the following
-relationship:
-- If `m_type == value_t::object`, then `m_value.object != nullptr`.
-- If `m_type == value_t::array`, then `m_value.array != nullptr`.
-- If `m_type == value_t::string`, then `m_value.string != nullptr`.
-The invariants are checked by member function assert_invariant().
+                JSON_THROW(invalid_iterator::create(214, "cannot get value"));
+            }
+        }
+    }
 
-@internal
-@note ObjectType trick from http://stackoverflow.com/a/9860911
-@endinternal
+    /*!
+    @brief  return the key of an object iterator
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    typename object_t::key_type key() const
+    {
+        assert(m_object != nullptr);
 
-@see [RFC 7159: The JavaScript Object Notation (JSON) Data Interchange
-Format](http://rfc7159.net/rfc7159)
+        if (m_object->is_object())
+        {
+            return m_it.object_iterator->first;
+        }
 
-@since version 1.0.0
+        JSON_THROW(invalid_iterator::create(
+                       207, "cannot use key() for non-object iterators"));
+    }
 
-@nosubgrouping
-*/
-NLOHMANN_BASIC_JSON_TPL_DECLARATION
-class basic_json
+    /*!
+    @brief  return the value of an iterator
+    @pre The iterator is initialized; i.e. `m_object != nullptr`.
+    */
+    reference value() const
+    {
+        return operator*();
+    }
+
+  private:
+    /// associated JSON instance
+    pointer m_object = nullptr;
+    /// the actual iterator of the associated instance
+    internal_iterator<typename std::remove_const<BasicJsonType>::type> m_it = {};
+};
+
+/// proxy class for the iterator_wrapper functions
+template <typename IteratorType> class iteration_proxy
 {
   private:
-    template<detail::value_t> friend struct detail::external_constructor;
-    friend ::nlohmann::json_pointer;
-    friend ::nlohmann::detail::parser<basic_json>;
-    /// workaround type for MSVC
-    using basic_json_t = NLOHMANN_BASIC_JSON_TPL;
+    /// helper class for iteration
+    class iteration_proxy_internal
+    {
+      private:
+        /// the iterator
+        IteratorType anchor;
+        /// an index for arrays (used to create key names)
+        size_t array_index = 0;
 
-    // convenience aliases for types residing in namespace detail;
-    using lexer = ::nlohmann::detail::lexer<basic_json>;
-    using parser = ::nlohmann::detail::parser<basic_json>;
+      public:
+        explicit iteration_proxy_internal(IteratorType it) noexcept : anchor(it) {}
 
-    using primitive_iterator_t = ::nlohmann::detail::primitive_iterator_t;
+        /// dereference operator (needed for range-based for)
+        iteration_proxy_internal& operator*()
+        {
+            return *this;
+        }
 
-  public:
-    using value_t = detail::value_t;
-    // forward declarations
-    template<typename U> class iter_impl;
-    template<typename Base> class json_reverse_iterator;
-    using json_pointer = ::nlohmann::json_pointer;
-    template<typename T, typename SFINAE>
-    using json_serializer = JSONSerializer<T, SFINAE>;
+        /// increment operator (needed for range-based for)
+        iteration_proxy_internal& operator++()
+        {
+            ++anchor;
+            ++array_index;
 
+            return *this;
+        }
 
-    ////////////////
-    // exceptions //
-    ////////////////
+        /// inequality operator (needed for range-based for)
+        bool operator!=(const iteration_proxy_internal& o) const
+        {
+            return anchor != o.anchor;
+        }
 
-    /// @name exceptions
-    /// Classes to implement user-defined exceptions.
-    /// @{
+        /// return key of the iterator
+        std::string key() const
+        {
+            assert(anchor.m_object != nullptr);
 
-    /// @copydoc detail::exception
-    using exception = detail::exception;
-    /// @copydoc detail::parse_error
-    using parse_error = detail::parse_error;
-    /// @copydoc detail::invalid_iterator
-    using invalid_iterator = detail::invalid_iterator;
-    /// @copydoc detail::type_error
-    using type_error = detail::type_error;
-    /// @copydoc detail::out_of_range
-    using out_of_range = detail::out_of_range;
-    /// @copydoc detail::other_error
-    using other_error = detail::other_error;
+            switch (anchor.m_object->type())
+            {
+                // use integer array index as key
+                case value_t::array:
+                {
+                    return std::to_string(array_index);
+                }
 
-    /// @}
+                // use key from the object
+                case value_t::object:
+                {
+                    return anchor.key();
+                }
 
+                // use an empty key for all primitive types
+                default:
+                {
+                    return "";
+                }
+            }
+        }
 
-    /////////////////////
-    // container types //
-    /////////////////////
+        /// return value of the iterator
+        typename IteratorType::reference value() const
+        {
+            return anchor.value();
+        }
+    };
 
-    /// @name container types
-    /// The canonic container types to use @ref basic_json like any other STL
-    /// container.
-    /// @{
+    /// the container to iterate
+    typename IteratorType::reference container;
 
-    /// the type of elements in a basic_json container
-    using value_type = basic_json;
+  public:
+    /// construct iteration proxy from a container
+    explicit iteration_proxy(typename IteratorType::reference cont)
+        : container(cont) {}
 
-    /// the type of an element reference
-    using reference = value_type&;
-    /// the type of an element const reference
-    using const_reference = const value_type&;
+    /// return iterator begin (needed for range-based for)
+    iteration_proxy_internal begin() noexcept
+    {
+        return iteration_proxy_internal(container.begin());
+    }
 
-    /// a type to represent differences between iterators
-    using difference_type = std::ptrdiff_t;
-    /// a type to represent container sizes
-    using size_type = std::size_t;
+    /// return iterator end (needed for range-based for)
+    iteration_proxy_internal end() noexcept
+    {
+        return iteration_proxy_internal(container.end());
+    }
+};
+} // namespace detail
 
-    /// the allocator type
-    using allocator_type = AllocatorType<basic_json>;
+/// namespace to hold default `to_json` / `from_json` functions
+namespace
+{
+constexpr const auto& to_json = detail::static_const<detail::to_json_fn>::value;
+constexpr const auto& from_json = detail::static_const<detail::from_json_fn>::value;
+}
 
-    /// the type of an element pointer
-    using pointer = typename std::allocator_traits<allocator_type>::pointer;
-    /// the type of an element const pointer
-    using const_pointer = typename std::allocator_traits<allocator_type>::const_pointer;
 
-    /// an iterator for a basic_json container
-    using iterator = iter_impl<basic_json>;
-    /// a const iterator for a basic_json container
-    using const_iterator = iter_impl<const basic_json>;
-    /// a reverse iterator for a basic_json container
-    using reverse_iterator = json_reverse_iterator<typename basic_json::iterator>;
-    /// a const reverse iterator for a basic_json container
-    using const_reverse_iterator = json_reverse_iterator<typename basic_json::const_iterator>;
+/*!
+@brief default JSONSerializer template argument
 
-    /// @}
+This serializer ignores the template arguments and uses ADL
+([argument-dependent lookup](http://en.cppreference.com/w/cpp/language/adl))
+for serialization.
+*/
+template<typename, typename>
+struct adl_serializer
+{
+    /*!
+    @brief convert a JSON value to any value type
 
+    This function is usually called by the `get()` function of the
+    @ref basic_json class (either explicit or via conversion operators).
 
-    /*!
-    @brief returns the allocator associated with the container
+    @param[in] j         JSON value to read from
+    @param[in,out] val  value to write to
     */
-    static allocator_type get_allocator()
+    template<typename BasicJsonType, typename ValueType>
+    static void from_json(BasicJsonType&& j, ValueType& val) noexcept(
+        noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), val)))
     {
-        return allocator_type();
+        ::nlohmann::from_json(std::forward<BasicJsonType>(j), val);
     }
 
     /*!
-    @brief returns version information on the library
-
-    This function returns a JSON object with information about the library,
-    including the version number and information on the platform and compiler.
-
-    @return JSON object holding version information
-    key         | description
-    ----------- | ---------------
-    `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).
-    `copyright` | The copyright line for the library as string.
-    `name`      | The name of the library as string.
-    `platform`  | The used platform as string. Possible values are `win32`, `linux`, `apple`, `unix`, and `unknown`.
-    `url`       | The URL of the project as string.
-    `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).
-
-    @liveexample{The following code shows an example output of the `meta()`
-    function.,meta}
+    @brief convert any value type to a JSON value
 
-    @complexity Constant.
+    This function is usually called by the constructors of the @ref basic_json
+    class.
 
-    @since 2.1.0
+    @param[in,out] j  JSON value to write to
+    @param[in] val     value to read from
     */
-    static basic_json meta()
+    template<typename BasicJsonType, typename ValueType>
+    static void to_json(BasicJsonType& j, ValueType&& val) noexcept(
+        noexcept(::nlohmann::to_json(j, std::forward<ValueType>(val))))
     {
-        basic_json result;
-
-        result["copyright"] = "(C) 2013-2017 Niels Lohmann";
-        result["name"] = "JSON for Modern C++";
-        result["url"] = "https://github.com/nlohmann/json";
-        result["version"] =
-        {
-            {"string", "2.1.1"}, {"major", 2}, {"minor", 1}, {"patch", 1}
-        };
-
-#ifdef _WIN32
-        result["platform"] = "win32";
-#elif defined __linux__
-        result["platform"] = "linux";
-#elif defined __APPLE__
-        result["platform"] = "apple";
-#elif defined __unix__
-        result["platform"] = "unix";
-#else
-        result["platform"] = "unknown";
-#endif
-
-#if defined(__clang__)
-        result["compiler"] = {{"family", "clang"}, {"version", __clang_version__}};
-#elif defined(__ICC) || defined(__INTEL_COMPILER)
-        result["compiler"] = {{"family", "icc"}, {"version", __INTEL_COMPILER}};
-#elif defined(__GNUC__) || defined(__GNUG__)
-        result["compiler"] = {{"family", "gcc"}, {"version", std::to_string(__GNUC__) + "." + std::to_string(__GNUC_MINOR__) + "." + std::to_string(__GNUC_PATCHLEVEL__)}};
-#elif defined(__HP_cc) || defined(__HP_aCC)
-        result["compiler"] = "hp"
-#elif defined(__IBMCPP__)
-        result["compiler"] = {{"family", "ilecpp"}, {"version", __IBMCPP__}};
-#elif defined(_MSC_VER)
-        result["compiler"] = {{"family", "msvc"}, {"version", _MSC_VER}};
-#elif defined(__PGI)
-        result["compiler"] = {{"family", "pgcpp"}, {"version", __PGI}};
-#elif defined(__SUNPRO_CC)
-        result["compiler"] = {{"family", "sunpro"}, {"version", __SUNPRO_CC}};
-#else
-        result["compiler"] = {{"family", "unknown"}, {"version", "unknown"}};
-#endif
-
-#ifdef __cplusplus
-        result["compiler"]["c++"] = std::to_string(__cplusplus);
-#else
-        result["compiler"]["c++"] = "unknown";
-#endif
-        return result;
+        ::nlohmann::to_json(j, std::forward<ValueType>(val));
     }
+};
+
+/*!
+@brief JSON Pointer
 
+A JSON pointer defines a string syntax for identifying a specific value
+within a JSON document. It can be used with functions `at` and
+`operator[]`. Furthermore, JSON pointers are the base for JSON patches.
 
-    ///////////////////////////
-    // JSON value data types //
-    ///////////////////////////
+@sa [RFC 6901](https://tools.ietf.org/html/rfc6901)
 
-    /// @name JSON value data types
-    /// The data types to store a JSON value. These types are derived from
-    /// the template arguments passed to class @ref basic_json.
-    /// @{
+@since version 2.0.0
+*/
+class json_pointer
+{
+    /// allow basic_json to access private members
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    friend class basic_json;
 
+  public:
     /*!
-    @brief a type for an object
+      @brief create JSON pointer
 
-    [RFC 7159](http://rfc7159.net/rfc7159) describes JSON objects as follows:
-    > An object is an unordered collection of zero or more name/value pairs,
-    > where a name is a string and a value is a string, number, boolean, null,
-    > object, or array.
+      Create a JSON pointer according to the syntax described in
+      [Section 3 of RFC6901](https://tools.ietf.org/html/rfc6901#section-3).
 
-    To store objects in C++, a type is defined by the template parameters
-    described below.
+      @param[in] s  string representing the JSON pointer; if omitted, the
+      empty string is assumed which references the whole JSON
+      value
 
-    @tparam ObjectType  the container to store objects (e.g., `std::map` or
-    `std::unordered_map`)
-    @tparam StringType the type of the keys or names (e.g., `std::string`).
-    The comparison function `std::less<StringType>` is used to order elements
-    inside the container.
-    @tparam AllocatorType the allocator to use for objects (e.g.,
-    `std::allocator`)
+      @throw parse_error.107 if the given JSON pointer @a s is nonempty and
+      does not begin with a slash (`/`); see example below
 
-    #### Default type
+      @throw parse_error.108 if a tilde (`~`) in the given JSON pointer @a s
+      is not followed by `0` (representing `~`) or `1` (representing `/`);
+      see example below
 
-    With the default values for @a ObjectType (`std::map`), @a StringType
-    (`std::string`), and @a AllocatorType (`std::allocator`), the default
-    value for @a object_t is:
+      @liveexample{The example shows the construction several valid JSON
+      pointers as well as the exceptional behavior.,json_pointer}
 
-    @code {.cpp}
-    std::map<
-      std::string, // key_type
-      basic_json, // value_type
-      std::less<std::string>, // key_compare
-      std::allocator<std::pair<const std::string, basic_json>> // allocator_type
-    >
-    @endcode
+      @since version 2.0.0
+      */
+    explicit json_pointer(const std::string& s = "") : reference_tokens(split(s)) {}
 
-    #### Behavior
+    /*!
+      @brief return a string representation of the JSON pointer
 
-    The choice of @a object_t influences the behavior of the JSON class. With
-    the default type, objects have the following behavior:
+      @invariant For each JSON pointer `ptr`, it holds:
+      @code {.cpp}
+      ptr == json_pointer(ptr.to_string());
+      @endcode
 
-    - When all names are unique, objects will be interoperable in the sense
-      that all software implementations receiving that object will agree on
-      the name-value mappings.
-    - When the names within an object are not unique, later stored name/value
-      pairs overwrite previously stored name/value pairs, leaving the used
-      names unique. For instance, `{"key": 1}` and `{"key": 2, "key": 1}` will
-      be treated as equal and both stored as `{"key": 1}`.
-    - Internally, name/value pairs are stored in lexicographical order of the
-      names. Objects will also be serialized (see @ref dump) in this order.
-      For instance, `{"b": 1, "a": 2}` and `{"a": 2, "b": 1}` will be stored
-      and serialized as `{"a": 2, "b": 1}`.
-    - When comparing objects, the order of the name/value pairs is irrelevant.
-      This makes objects interoperable in the sense that they will not be
-      affected by these differences. For instance, `{"b": 1, "a": 2}` and
-      `{"a": 2, "b": 1}` will be treated as equal.
+      @return a string representation of the JSON pointer
 
-    #### Limits
+      @liveexample{The example shows the result of `to_string`.,
+      json_pointer__to_string}
 
-    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
-    > An implementation may set limits on the maximum depth of nesting.
+      @since version 2.0.0
+      */
+    std::string to_string() const noexcept
+    {
+        return std::accumulate(reference_tokens.begin(), reference_tokens.end(),
+                               std::string{},
+                               [](const std::string & a, const std::string & b)
+        {
+            return a + "/" + escape(b);
+        });
+    }
 
-    In this class, the object's limit of nesting is not constraint explicitly.
-    However, a maximum depth of nesting may be introduced by the compiler or
-    runtime environment. A theoretical limit can be queried by calling the
-    @ref max_size function of a JSON object.
+    /// @copydoc to_string()
+    operator std::string() const
+    {
+        return to_string();
+    }
 
-    #### Storage
+  private:
+    /*!
+      @brief remove and return last reference pointer
+      @throw out_of_range.405 if JSON pointer has no parent
+      */
+    std::string pop_back()
+    {
+        if (is_root())
+        {
+            JSON_THROW(
+                detail::out_of_range::create(405, "JSON pointer has no parent"));
+        }
 
-    Objects are stored as pointers in a @ref basic_json type. That is, for any
-    access to object values, a pointer of type `object_t*` must be
-    dereferenced.
+        auto last = reference_tokens.back();
+        reference_tokens.pop_back();
+        return last;
+    }
 
-    @sa @ref array_t -- type for an array value
+    /// return whether pointer points to the root document
+    bool is_root() const
+    {
+        return reference_tokens.empty();
+    }
 
-    @since version 1.0.0
+    json_pointer top() const
+    {
+        if (is_root())
+        {
+            JSON_THROW(detail::out_of_range::create(405, "JSON pointer has no parent"));
+        }
+
+        json_pointer result = *this;
+        result.reference_tokens = {reference_tokens[0]};
+        return result;
+    }
 
-    @note The order name/value pairs are added to the object is *not*
-    preserved by the library. Therefore, iterating an object may return
-    name/value pairs in a different order than they were originally stored. In
-    fact, keys will be traversed in alphabetical order as `std::map` with
-    `std::less` is used by default. Please note this behavior conforms to [RFC
-    7159](http://rfc7159.net/rfc7159), because any order implements the
-    specified "unordered" nature of JSON objects.
-    */
-    using object_t = ObjectType<StringType,
-          basic_json,
-          std::less<StringType>,
-          AllocatorType<std::pair<const StringType,
-          basic_json>>>;
 
     /*!
-    @brief a type for an array
+      @brief create and return a reference to the pointed to value
 
-    [RFC 7159](http://rfc7159.net/rfc7159) describes JSON arrays as follows:
-    > An array is an ordered sequence of zero or more values.
+      @complexity Linear in the number of reference tokens.
 
-    To store objects in C++, a type is defined by the template parameters
-    explained below.
+      @throw parse_error.109 if array index is not a number
+      @throw type_error.313 if value cannot be unflattened
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    NLOHMANN_BASIC_JSON_TPL& get_and_create(NLOHMANN_BASIC_JSON_TPL& j) const;
 
-    @tparam ArrayType  container type to store arrays (e.g., `std::vector` or
-    `std::list`)
-    @tparam AllocatorType allocator to use for arrays (e.g., `std::allocator`)
+    /*!
+      @brief return a reference to the pointed to value
 
-    #### Default type
+      @note This version does not throw if a value is not present, but tries
+      to create nested values instead. For instance, calling this function
+      with pointer `"/this/that"` on a null value is equivalent to calling
+      `operator[]("this").operator[]("that")` on that value, effectively
+      changing the null value to an object.
 
-    With the default values for @a ArrayType (`std::vector`) and @a
-    AllocatorType (`std::allocator`), the default value for @a array_t is:
+      @param[in] ptr  a JSON value
 
-    @code {.cpp}
-    std::vector<
-      basic_json, // value_type
-      std::allocator<basic_json> // allocator_type
-    >
-    @endcode
+      @return reference to the JSON value pointed to by the JSON pointer
 
-    #### Limits
+      @complexity Linear in the length of the JSON pointer.
 
-    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
-    > An implementation may set limits on the maximum depth of nesting.
+      @throw parse_error.106   if an array index begins with '0'
+      @throw parse_error.109   if an array index was not a number
+      @throw out_of_range.404  if the JSON pointer can not be resolved
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    NLOHMANN_BASIC_JSON_TPL& get_unchecked(NLOHMANN_BASIC_JSON_TPL* ptr) const;
 
-    In this class, the array's limit of nesting is not constraint explicitly.
-    However, a maximum depth of nesting may be introduced by the compiler or
-    runtime environment. A theoretical limit can be queried by calling the
-    @ref max_size function of a JSON array.
+    /*!
+      @throw parse_error.106   if an array index begins with '0'
+      @throw parse_error.109   if an array index was not a number
+      @throw out_of_range.402  if the array index '-' is used
+      @throw out_of_range.404  if the JSON pointer can not be resolved
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    NLOHMANN_BASIC_JSON_TPL& get_checked(NLOHMANN_BASIC_JSON_TPL* ptr) const;
 
-    #### Storage
+    /*!
+      @brief return a const reference to the pointed to value
 
-    Arrays are stored as pointers in a @ref basic_json type. That is, for any
-    access to array values, a pointer of type `array_t*` must be dereferenced.
+      @param[in] ptr  a JSON value
 
-    @sa @ref object_t -- type for an object value
+      @return const reference to the JSON value pointed to by the JSON
+      pointer
 
-    @since version 1.0.0
-    */
-    using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;
+      @throw parse_error.106   if an array index begins with '0'
+      @throw parse_error.109   if an array index was not a number
+      @throw out_of_range.402  if the array index '-' is used
+      @throw out_of_range.404  if the JSON pointer can not be resolved
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    const NLOHMANN_BASIC_JSON_TPL& get_unchecked(const NLOHMANN_BASIC_JSON_TPL* ptr) const;
 
     /*!
-    @brief a type for a string
+      @throw parse_error.106   if an array index begins with '0'
+      @throw parse_error.109   if an array index was not a number
+      @throw out_of_range.402  if the array index '-' is used
+      @throw out_of_range.404  if the JSON pointer can not be resolved
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    const NLOHMANN_BASIC_JSON_TPL& get_checked(const NLOHMANN_BASIC_JSON_TPL* ptr) const;
 
-    [RFC 7159](http://rfc7159.net/rfc7159) describes JSON strings as follows:
-    > A string is a sequence of zero or more Unicode characters.
+    /*!
+      @brief split the string input to reference tokens
 
-    To store objects in C++, a type is defined by the template parameter
-    described below. Unicode values are split by the JSON class into
-    byte-sized characters during deserialization.
+      @note This function is only called by the json_pointer constructor.
+      All exceptions below are documented there.
 
-    @tparam StringType  the container to store strings (e.g., `std::string`).
-    Note this container is used for keys/names in objects, see @ref object_t.
+      @throw parse_error.107  if the pointer is not empty or begins with '/'
+      @throw parse_error.108  if character '~' is not followed by '0' or '1'
+      */
+    static std::vector<std::string> split(const std::string& reference_string)
+    {
+        std::vector<std::string> result;
 
-    #### Default type
+        // special case: empty reference string -> no reference tokens
+        if (reference_string.empty())
+        {
+            return result;
+        }
 
-    With the default values for @a StringType (`std::string`), the default
-    value for @a string_t is:
+        // check if nonempty reference string begins with slash
+        if (reference_string[0] != '/')
+        {
+            JSON_THROW(detail::parse_error::create(
+                           107, 1,
+                           "JSON pointer must be empty or begin with '/' - was: '" +
+                           reference_string + "'"));
+        }
 
-    @code {.cpp}
-    std::string
-    @endcode
+        // extract the reference tokens:
+        // - slash: position of the last read slash (or end of string)
+        // - start: position after the previous slash
+        for (
+            // search for the first slash after the first character
+            size_t slash = reference_string.find_first_of('/', 1),
+            // set the beginning of the first reference token
+            start = 1;
+            // we can stop if start == string::npos+1 = 0
+            start != 0;
+            // set the beginning of the next reference token
+            // (will eventually be 0 if slash == std::string::npos)
+            start = slash + 1,
+            // find next slash
+            slash = reference_string.find_first_of('/', start))
+        {
+            // use the text between the beginning of the reference token
+            // (start) and the last slash (slash).
+            auto reference_token = reference_string.substr(start, slash - start);
 
-    #### Encoding
+            // check reference tokens are properly escaped
+            for (size_t pos = reference_token.find_first_of('~');
+                    pos != std::string::npos;
+                    pos = reference_token.find_first_of('~', pos + 1))
+            {
+                assert(reference_token[pos] == '~');
 
-    Strings are stored in UTF-8 encoding. Therefore, functions like
-    `std::string::size()` or `std::string::length()` return the number of
-    bytes in the string rather than the number of characters or glyphs.
+                // ~ must be followed by 0 or 1
+                if (pos == reference_token.size() - 1 or
+                        (reference_token[pos + 1] != '0' and
+                         reference_token[pos + 1] != '1'))
+                {
+                    JSON_THROW(detail::parse_error::create(
+                                   108, 0, "escape character '~' must be followed with '0' or '1'"));
+                }
+            }
 
-    #### String comparison
+            // finally, store the reference token
+            unescape(reference_token);
+            result.push_back(reference_token);
+        }
 
-    [RFC 7159](http://rfc7159.net/rfc7159) states:
-    > Software implementations are typically required to test names of object
-    > members for equality. Implementations that transform the textual
-    > representation into sequences of Unicode code units and then perform the
-    > comparison numerically, code unit by code unit, are interoperable in the
-    > sense that implementations will agree in all cases on equality or
-    > inequality of two strings. For example, implementations that compare
-    > strings with escaped characters unconverted may incorrectly find that
-    > `"a\\b"` and `"a\u005Cb"` are not equal.
+        return result;
+    }
 
-    This implementation is interoperable as it does compare strings code unit
-    by code unit.
+    /*!
+      @brief replace all occurrences of a substring by another string
 
-    #### Storage
+      @param[in,out] s  the string to manipulate; changed so that all
+      occurrences of @a f are replaced with @a t
+      @param[in]     f  the substring to replace with @a t
+      @param[in]     t  the string to replace @a f
 
-    String values are stored as pointers in a @ref basic_json type. That is,
-    for any access to string values, a pointer of type `string_t*` must be
-    dereferenced.
+      @pre The search string @a f must not be empty. **This precondition is
+      enforced with an assertion.**
 
-    @since version 1.0.0
-    */
-    using string_t = StringType;
+      @since version 2.0.0
+      */
+    static void replace_substring(std::string& s, const std::string& f,
+                                  const std::string& t)
+    {
+        assert(not f.empty());
 
-    /*!
-    @brief a type for a boolean
+        for (size_t pos = s.find(f);         // find first occurrence of f
+                pos != std::string::npos;       // make sure f was found
+                s.replace(pos, f.size(), t),    // replace with t
+                pos = s.find(f, pos + t.size()) // find next occurrence of f
+            )
+            ;
+    }
 
-    [RFC 7159](http://rfc7159.net/rfc7159) implicitly describes a boolean as a
-    type which differentiates the two literals `true` and `false`.
+    /// escape tilde and slash
+    static std::string escape(std::string s)
+    {
+        // escape "~"" to "~0" and "/" to "~1"
+        replace_substring(s, "~", "~0");
+        replace_substring(s, "/", "~1");
+        return s;
+    }
 
-    To store objects in C++, a type is defined by the template parameter @a
-    BooleanType which chooses the type to use.
+    /// unescape tilde and slash
+    static void unescape(std::string& s)
+    {
+        // first transform any occurrence of the sequence '~1' to '/'
+        replace_substring(s, "~1", "/");
+        // then transform any occurrence of the sequence '~0' to '~'
+        replace_substring(s, "~0", "~");
+    }
 
-    #### Default type
+    /*!
+      @param[in] reference_string  the reference string to the current value
+      @param[in] value             the value to consider
+      @param[in,out] result        the result object to insert values to
 
-    With the default values for @a BooleanType (`bool`), the default value for
-    @a boolean_t is:
+      @note Empty objects or arrays are flattened to `null`.
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    static void flatten(const std::string& reference_string,
+                        const NLOHMANN_BASIC_JSON_TPL& value,
+                        NLOHMANN_BASIC_JSON_TPL& result);
 
-    @code {.cpp}
-    bool
-    @endcode
+    /*!
+      @param[in] value  flattened JSON
 
-    #### Storage
+      @return unflattened JSON
 
-    Boolean values are stored directly inside a @ref basic_json type.
+      @throw parse_error.109 if array index is not a number
+      @throw type_error.314  if value is not an object
+      @throw type_error.315  if object values are not primitive
+      @throw type_error.313  if value cannot be unflattened
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    static NLOHMANN_BASIC_JSON_TPL
+    unflatten(const NLOHMANN_BASIC_JSON_TPL& value);
 
-    @since version 1.0.0
-    */
-    using boolean_t = BooleanType;
+    friend bool operator==(json_pointer const& lhs,
+                           json_pointer const& rhs) noexcept;
 
-    /*!
-    @brief a type for a number (integer)
+    friend bool operator!=(json_pointer const& lhs,
+                           json_pointer const& rhs) noexcept;
 
-    [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
-    > The representation of numbers is similar to that used in most
-    > programming languages. A number is represented in base 10 using decimal
-    > digits. It contains an integer component that may be prefixed with an
-    > optional minus sign, which may be followed by a fraction part and/or an
-    > exponent part. Leading zeros are not allowed. (...) Numeric values that
-    > cannot be represented in the grammar below (such as Infinity and NaN)
-    > are not permitted.
-
-    This description includes both integer and floating-point numbers.
-    However, C++ allows more precise storage if it is known whether the number
-    is a signed integer, an unsigned integer or a floating-point number.
-    Therefore, three different types, @ref number_integer_t, @ref
-    number_unsigned_t and @ref number_float_t are used.
-
-    To store integer numbers in C++, a type is defined by the template
-    parameter @a NumberIntegerType which chooses the type to use.
-
-    #### Default type
+    /// the reference tokens
+    std::vector<std::string> reference_tokens;
+};
 
-    With the default values for @a NumberIntegerType (`int64_t`), the default
-    value for @a number_integer_t is:
+/*!
+@brief a class to store JSON values
 
-    @code {.cpp}
-    int64_t
-    @endcode
+@tparam ObjectType type for JSON objects (`std::map` by default; will be used
+in @ref object_t)
+@tparam ArrayType type for JSON arrays (`std::vector` by default; will be used
+in @ref array_t)
+@tparam StringType type for JSON strings and object keys (`std::string` by
+default; will be used in @ref string_t)
+@tparam BooleanType type for JSON booleans (`bool` by default; will be used
+in @ref boolean_t)
+@tparam NumberIntegerType type for JSON integer numbers (`int64_t` by
+default; will be used in @ref number_integer_t)
+@tparam NumberUnsignedType type for JSON unsigned integer numbers (@c
+`uint64_t` by default; will be used in @ref number_unsigned_t)
+@tparam NumberFloatType type for JSON floating-point numbers (`double` by
+default; will be used in @ref number_float_t)
+@tparam AllocatorType type of the allocator to use (`std::allocator` by
+default)
+@tparam JSONSerializer the serializer to resolve internal calls to `to_json()`
+and `from_json()` (@ref adl_serializer by default)
 
-    #### Default behavior
+@requirement The class satisfies the following concept requirements:
+- Basic
+ - [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible):
+   JSON values can be default constructed. The result will be a JSON null
+   value.
+ - [MoveConstructible](http://en.cppreference.com/w/cpp/concept/MoveConstructible):
+   A JSON value can be constructed from an rvalue argument.
+ - [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible):
+   A JSON value can be copy-constructed from an lvalue expression.
+ - [MoveAssignable](http://en.cppreference.com/w/cpp/concept/MoveAssignable):
+   A JSON value van be assigned from an rvalue argument.
+ - [CopyAssignable](http://en.cppreference.com/w/cpp/concept/CopyAssignable):
+   A JSON value can be copy-assigned from an lvalue expression.
+ - [Destructible](http://en.cppreference.com/w/cpp/concept/Destructible):
+   JSON values can be destructed.
+- Layout
+ - [StandardLayoutType](http://en.cppreference.com/w/cpp/concept/StandardLayoutType):
+   JSON values have
+   [standard layout](http://en.cppreference.com/w/cpp/language/data_members#Standard_layout):
+   All non-static data members are private and standard layout types, the
+   class has no virtual functions or (virtual) base classes.
+- Library-wide
+ - [EqualityComparable](http://en.cppreference.com/w/cpp/concept/EqualityComparable):
+   JSON values can be compared with `==`, see @ref
+   operator==(const_reference,const_reference).
+ - [LessThanComparable](http://en.cppreference.com/w/cpp/concept/LessThanComparable):
+   JSON values can be compared with `<`, see @ref
+   operator<(const_reference,const_reference).
+ - [Swappable](http://en.cppreference.com/w/cpp/concept/Swappable):
+   Any JSON lvalue or rvalue of can be swapped with any lvalue or rvalue of
+   other compatible types, using unqualified function call @ref swap().
+ - [NullablePointer](http://en.cppreference.com/w/cpp/concept/NullablePointer):
+   JSON values can be compared against `std::nullptr_t` objects which are used
+   to model the `null` value.
+- Container
+ - [Container](http://en.cppreference.com/w/cpp/concept/Container):
+   JSON values can be used like STL containers and provide iterator access.
+ - [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer);
+   JSON values can be used like STL containers and provide reverse iterator
+   access.
 
-    - The restrictions about leading zeros is not enforced in C++. Instead,
-      leading zeros in integer literals lead to an interpretation as octal
-      number. Internally, the value will be stored as decimal number. For
-      instance, the C++ integer literal `010` will be serialized to `8`.
-      During deserialization, leading zeros yield an error.
-    - Not-a-number (NaN) values will be serialized to `null`.
+@invariant The member variables @a m_value and @a m_type have the following
+relationship:
+- If `m_type == value_t::object`, then `m_value.object != nullptr`.
+- If `m_type == value_t::array`, then `m_value.array != nullptr`.
+- If `m_type == value_t::string`, then `m_value.string != nullptr`.
+The invariants are checked by member function assert_invariant().
 
-    #### Limits
+@internal
+@note ObjectType trick from http://stackoverflow.com/a/9860911
+@endinternal
 
-    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
-    > An implementation may set limits on the range and precision of numbers.
+@see [RFC 7159: The JavaScript Object Notation (JSON) Data Interchange
+Format](http://rfc7159.net/rfc7159)
 
-    When the default type is used, the maximal integer number that can be
-    stored is `9223372036854775807` (INT64_MAX) and the minimal integer number
-    that can be stored is `-9223372036854775808` (INT64_MIN). Integer numbers
-    that are out of range will yield over/underflow when used in a
-    constructor. During deserialization, too large or small integer numbers
-    will be automatically be stored as @ref number_unsigned_t or @ref
-    number_float_t.
+@since version 1.0.0
 
-    [RFC 7159](http://rfc7159.net/rfc7159) further states:
-    > Note that when such software is used, numbers that are integers and are
-    > in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
-    > that implementations will agree exactly on their numeric values.
+@nosubgrouping
+*/
+NLOHMANN_BASIC_JSON_TPL_DECLARATION
+class basic_json
+{
+  private:
+    template<detail::value_t> friend struct detail::external_constructor;
+    friend ::nlohmann::json_pointer;
+    friend ::nlohmann::detail::parser<basic_json>;
+    template <typename BasicJsonType>
+    friend class ::nlohmann::detail::iter_impl;
+    /// workaround type for MSVC
+    using basic_json_t = NLOHMANN_BASIC_JSON_TPL;
 
-    As this range is a subrange of the exactly supported range [INT64_MIN,
-    INT64_MAX], this class's integer type is interoperable.
+    // convenience aliases for types residing in namespace detail;
+    using lexer = ::nlohmann::detail::lexer<basic_json>;
+    using parser = ::nlohmann::detail::parser<basic_json>;
 
-    #### Storage
+    using primitive_iterator_t = ::nlohmann::detail::primitive_iterator_t;
+    template <typename BasicJsonType>
+    using internal_iterator = ::nlohmann::detail::internal_iterator<BasicJsonType>;
+    template <typename BasicJsonType>
+    using iter_impl = ::nlohmann::detail::iter_impl<BasicJsonType>;
+    template <typename Iterator>
+    using iteration_proxy = ::nlohmann::detail::iteration_proxy<Iterator>;
 
-    Integer number values are stored directly inside a @ref basic_json type.
+  public:
+    using value_t = detail::value_t;
+    // forward declarations
+    template<typename Base> class json_reverse_iterator;
+    using json_pointer = ::nlohmann::json_pointer;
+    template<typename T, typename SFINAE>
+    using json_serializer = JSONSerializer<T, SFINAE>;
 
-    @sa @ref number_float_t -- type for number values (floating-point)
 
-    @sa @ref number_unsigned_t -- type for number values (unsigned integer)
+    ////////////////
+    // exceptions //
+    ////////////////
 
-    @since version 1.0.0
-    */
-    using number_integer_t = NumberIntegerType;
+    /// @name exceptions
+    /// Classes to implement user-defined exceptions.
+    /// @{
 
-    /*!
-    @brief a type for a number (unsigned)
+    /// @copydoc detail::exception
+    using exception = detail::exception;
+    /// @copydoc detail::parse_error
+    using parse_error = detail::parse_error;
+    /// @copydoc detail::invalid_iterator
+    using invalid_iterator = detail::invalid_iterator;
+    /// @copydoc detail::type_error
+    using type_error = detail::type_error;
+    /// @copydoc detail::out_of_range
+    using out_of_range = detail::out_of_range;
+    /// @copydoc detail::other_error
+    using other_error = detail::other_error;
 
-    [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
-    > The representation of numbers is similar to that used in most
-    > programming languages. A number is represented in base 10 using decimal
-    > digits. It contains an integer component that may be prefixed with an
-    > optional minus sign, which may be followed by a fraction part and/or an
-    > exponent part. Leading zeros are not allowed. (...) Numeric values that
-    > cannot be represented in the grammar below (such as Infinity and NaN)
-    > are not permitted.
+    /// @}
 
-    This description includes both integer and floating-point numbers.
-    However, C++ allows more precise storage if it is known whether the number
-    is a signed integer, an unsigned integer or a floating-point number.
-    Therefore, three different types, @ref number_integer_t, @ref
-    number_unsigned_t and @ref number_float_t are used.
 
-    To store unsigned integer numbers in C++, a type is defined by the
-    template parameter @a NumberUnsignedType which chooses the type to use.
+    /////////////////////
+    // container types //
+    /////////////////////
 
-    #### Default type
+    /// @name container types
+    /// The canonic container types to use @ref basic_json like any other STL
+    /// container.
+    /// @{
 
-    With the default values for @a NumberUnsignedType (`uint64_t`), the
-    default value for @a number_unsigned_t is:
+    /// the type of elements in a basic_json container
+    using value_type = basic_json;
 
-    @code {.cpp}
-    uint64_t
-    @endcode
+    /// the type of an element reference
+    using reference = value_type&;
+    /// the type of an element const reference
+    using const_reference = const value_type&;
 
-    #### Default behavior
+    /// a type to represent differences between iterators
+    using difference_type = std::ptrdiff_t;
+    /// a type to represent container sizes
+    using size_type = std::size_t;
 
-    - The restrictions about leading zeros is not enforced in C++. Instead,
-      leading zeros in integer literals lead to an interpretation as octal
-      number. Internally, the value will be stored as decimal number. For
-      instance, the C++ integer literal `010` will be serialized to `8`.
-      During deserialization, leading zeros yield an error.
-    - Not-a-number (NaN) values will be serialized to `null`.
+    /// the allocator type
+    using allocator_type = AllocatorType<basic_json>;
 
-    #### Limits
+    /// the type of an element pointer
+    using pointer = typename std::allocator_traits<allocator_type>::pointer;
+    /// the type of an element const pointer
+    using const_pointer = typename std::allocator_traits<allocator_type>::const_pointer;
 
-    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
-    > An implementation may set limits on the range and precision of numbers.
+    /// an iterator for a basic_json container
+    using iterator = iter_impl<basic_json>;
+    /// a const iterator for a basic_json container
+    using const_iterator = iter_impl<const basic_json>;
+    /// a reverse iterator for a basic_json container
+    using reverse_iterator = json_reverse_iterator<typename basic_json::iterator>;
+    /// a const reverse iterator for a basic_json container
+    using const_reverse_iterator = json_reverse_iterator<typename basic_json::const_iterator>;
 
-    When the default type is used, the maximal integer number that can be
-    stored is `18446744073709551615` (UINT64_MAX) and the minimal integer
-    number that can be stored is `0`. Integer numbers that are out of range
-    will yield over/underflow when used in a constructor. During
-    deserialization, too large or small integer numbers will be automatically
-    be stored as @ref number_integer_t or @ref number_float_t.
+    /// @}
 
-    [RFC 7159](http://rfc7159.net/rfc7159) further states:
-    > Note that when such software is used, numbers that are integers and are
-    > in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
-    > that implementations will agree exactly on their numeric values.
 
-    As this range is a subrange (when considered in conjunction with the
-    number_integer_t type) of the exactly supported range [0, UINT64_MAX],
-    this class's integer type is interoperable.
+    /*!
+    @brief returns the allocator associated with the container
+    */
+    static allocator_type get_allocator()
+    {
+        return allocator_type();
+    }
 
-    #### Storage
+    /*!
+    @brief returns version information on the library
 
-    Integer number values are stored directly inside a @ref basic_json type.
+    This function returns a JSON object with information about the library,
+    including the version number and information on the platform and compiler.
 
-    @sa @ref number_float_t -- type for number values (floating-point)
-    @sa @ref number_integer_t -- type for number values (integer)
+    @return JSON object holding version information
+    key         | description
+    ----------- | ---------------
+    `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).
+    `copyright` | The copyright line for the library as string.
+    `name`      | The name of the library as string.
+    `platform`  | The used platform as string. Possible values are `win32`, `linux`, `apple`, `unix`, and `unknown`.
+    `url`       | The URL of the project as string.
+    `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).
 
-    @since version 2.0.0
+    @liveexample{The following code shows an example output of the `meta()`
+    function.,meta}
+
+    @complexity Constant.
+
+    @since 2.1.0
     */
-    using number_unsigned_t = NumberUnsignedType;
+    static basic_json meta()
+    {
+        basic_json result;
+
+        result["copyright"] = "(C) 2013-2017 Niels Lohmann";
+        result["name"] = "JSON for Modern C++";
+        result["url"] = "https://github.com/nlohmann/json";
+        result["version"] =
+        {
+            {"string", "2.1.1"}, {"major", 2}, {"minor", 1}, {"patch", 1}
+        };
+
+#ifdef _WIN32
+        result["platform"] = "win32";
+#elif defined __linux__
+        result["platform"] = "linux";
+#elif defined __APPLE__
+        result["platform"] = "apple";
+#elif defined __unix__
+        result["platform"] = "unix";
+#else
+        result["platform"] = "unknown";
+#endif
+
+#if defined(__clang__)
+        result["compiler"] = {{"family", "clang"}, {"version", __clang_version__}};
+#elif defined(__ICC) || defined(__INTEL_COMPILER)
+        result["compiler"] = {{"family", "icc"}, {"version", __INTEL_COMPILER}};
+#elif defined(__GNUC__) || defined(__GNUG__)
+        result["compiler"] = {{"family", "gcc"}, {"version", std::to_string(__GNUC__) + "." + std::to_string(__GNUC_MINOR__) + "." + std::to_string(__GNUC_PATCHLEVEL__)}};
+#elif defined(__HP_cc) || defined(__HP_aCC)
+        result["compiler"] = "hp"
+#elif defined(__IBMCPP__)
+        result["compiler"] = {{"family", "ilecpp"}, {"version", __IBMCPP__}};
+#elif defined(_MSC_VER)
+        result["compiler"] = {{"family", "msvc"}, {"version", _MSC_VER}};
+#elif defined(__PGI)
+        result["compiler"] = {{"family", "pgcpp"}, {"version", __PGI}};
+#elif defined(__SUNPRO_CC)
+        result["compiler"] = {{"family", "sunpro"}, {"version", __SUNPRO_CC}};
+#else
+        result["compiler"] = {{"family", "unknown"}, {"version", "unknown"}};
+#endif
+
+#ifdef __cplusplus
+        result["compiler"]["c++"] = std::to_string(__cplusplus);
+#else
+        result["compiler"]["c++"] = "unknown";
+#endif
+        return result;
+    }
+
+
+    ///////////////////////////
+    // JSON value data types //
+    ///////////////////////////
+
+    /// @name JSON value data types
+    /// The data types to store a JSON value. These types are derived from
+    /// the template arguments passed to class @ref basic_json.
+    /// @{
 
     /*!
-    @brief a type for a number (floating-point)
+    @brief a type for an object
 
-    [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
-    > The representation of numbers is similar to that used in most
-    > programming languages. A number is represented in base 10 using decimal
-    > digits. It contains an integer component that may be prefixed with an
-    > optional minus sign, which may be followed by a fraction part and/or an
-    > exponent part. Leading zeros are not allowed. (...) Numeric values that
-    > cannot be represented in the grammar below (such as Infinity and NaN)
-    > are not permitted.
+    [RFC 7159](http://rfc7159.net/rfc7159) describes JSON objects as follows:
+    > An object is an unordered collection of zero or more name/value pairs,
+    > where a name is a string and a value is a string, number, boolean, null,
+    > object, or array.
 
-    This description includes both integer and floating-point numbers.
-    However, C++ allows more precise storage if it is known whether the number
-    is a signed integer, an unsigned integer or a floating-point number.
-    Therefore, three different types, @ref number_integer_t, @ref
-    number_unsigned_t and @ref number_float_t are used.
+    To store objects in C++, a type is defined by the template parameters
+    described below.
 
-    To store floating-point numbers in C++, a type is defined by the template
-    parameter @a NumberFloatType which chooses the type to use.
+    @tparam ObjectType  the container to store objects (e.g., `std::map` or
+    `std::unordered_map`)
+    @tparam StringType the type of the keys or names (e.g., `std::string`).
+    The comparison function `std::less<StringType>` is used to order elements
+    inside the container.
+    @tparam AllocatorType the allocator to use for objects (e.g.,
+    `std::allocator`)
 
     #### Default type
 
-    With the default values for @a NumberFloatType (`double`), the default
-    value for @a number_float_t is:
+    With the default values for @a ObjectType (`std::map`), @a StringType
+    (`std::string`), and @a AllocatorType (`std::allocator`), the default
+    value for @a object_t is:
 
     @code {.cpp}
-    double
+    std::map<
+      std::string, // key_type
+      basic_json, // value_type
+      std::less<std::string>, // key_compare
+      std::allocator<std::pair<const std::string, basic_json>> // allocator_type
+    >
     @endcode
 
-    #### Default behavior
+    #### Behavior
 
-    - The restrictions about leading zeros is not enforced in C++. Instead,
-      leading zeros in floating-point literals will be ignored. Internally,
-      the value will be stored as decimal number. For instance, the C++
-      floating-point literal `01.2` will be serialized to `1.2`. During
-      deserialization, leading zeros yield an error.
-    - Not-a-number (NaN) values will be serialized to `null`.
+    The choice of @a object_t influences the behavior of the JSON class. With
+    the default type, objects have the following behavior:
+
+    - When all names are unique, objects will be interoperable in the sense
+      that all software implementations receiving that object will agree on
+      the name-value mappings.
+    - When the names within an object are not unique, later stored name/value
+      pairs overwrite previously stored name/value pairs, leaving the used
+      names unique. For instance, `{"key": 1}` and `{"key": 2, "key": 1}` will
+      be treated as equal and both stored as `{"key": 1}`.
+    - Internally, name/value pairs are stored in lexicographical order of the
+      names. Objects will also be serialized (see @ref dump) in this order.
+      For instance, `{"b": 1, "a": 2}` and `{"a": 2, "b": 1}` will be stored
+      and serialized as `{"a": 2, "b": 1}`.
+    - When comparing objects, the order of the name/value pairs is irrelevant.
+      This makes objects interoperable in the sense that they will not be
+      affected by these differences. For instance, `{"b": 1, "a": 2}` and
+      `{"a": 2, "b": 1}` will be treated as equal.
 
     #### Limits
 
-    [RFC 7159](http://rfc7159.net/rfc7159) states:
-    > This specification allows implementations to set limits on the range and
-    > precision of numbers accepted. Since software that implements IEEE
-    > 754-2008 binary64 (double precision) numbers is generally available and
-    > widely used, good interoperability can be achieved by implementations
-    > that expect no more precision or range than these provide, in the sense
-    > that implementations will approximate JSON numbers within the expected
-    > precision.
+    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
+    > An implementation may set limits on the maximum depth of nesting.
 
-    This implementation does exactly follow this approach, as it uses double
-    precision floating-point numbers. Note values smaller than
-    `-1.79769313486232e+308` and values greater than `1.79769313486232e+308`
-    will be stored as NaN internally and be serialized to `null`.
+    In this class, the object's limit of nesting is not constraint explicitly.
+    However, a maximum depth of nesting may be introduced by the compiler or
+    runtime environment. A theoretical limit can be queried by calling the
+    @ref max_size function of a JSON object.
 
     #### Storage
 
-    Floating-point number values are stored directly inside a @ref basic_json
-    type.
-
-    @sa @ref number_integer_t -- type for number values (integer)
+    Objects are stored as pointers in a @ref basic_json type. That is, for any
+    access to object values, a pointer of type `object_t*` must be
+    dereferenced.
 
-    @sa @ref number_unsigned_t -- type for number values (unsigned integer)
+    @sa @ref array_t -- type for an array value
 
     @since version 1.0.0
+
+    @note The order name/value pairs are added to the object is *not*
+    preserved by the library. Therefore, iterating an object may return
+    name/value pairs in a different order than they were originally stored. In
+    fact, keys will be traversed in alphabetical order as `std::map` with
+    `std::less` is used by default. Please note this behavior conforms to [RFC
+    7159](http://rfc7159.net/rfc7159), because any order implements the
+    specified "unordered" nature of JSON objects.
     */
-    using number_float_t = NumberFloatType;
+    using object_t = ObjectType<StringType,
+          basic_json,
+          std::less<StringType>,
+          AllocatorType<std::pair<const StringType,
+          basic_json>>>;
 
-    /// @}
+    /*!
+    @brief a type for an array
 
-  private:
+    [RFC 7159](http://rfc7159.net/rfc7159) describes JSON arrays as follows:
+    > An array is an ordered sequence of zero or more values.
 
-    /// helper for exception-safe object creation
-    template<typename T, typename... Args>
-    static T* create(Args&& ... args)
-    {
-        AllocatorType<T> alloc;
-        auto deleter = [&](T * object)
-        {
-            alloc.deallocate(object, 1);
-        };
-        std::unique_ptr<T, decltype(deleter)> object(alloc.allocate(1), deleter);
-        alloc.construct(object.get(), std::forward<Args>(args)...);
-        assert(object != nullptr);
-        return object.release();
-    }
+    To store objects in C++, a type is defined by the template parameters
+    explained below.
 
-    ////////////////////////
-    // JSON value storage //
-    ////////////////////////
+    @tparam ArrayType  container type to store arrays (e.g., `std::vector` or
+    `std::list`)
+    @tparam AllocatorType allocator to use for arrays (e.g., `std::allocator`)
 
-    /*!
-    @brief a JSON value
+    #### Default type
 
-    The actual storage for a JSON value of the @ref basic_json class. This
-    union combines the different storage types for the JSON value types
-    defined in @ref value_t.
+    With the default values for @a ArrayType (`std::vector`) and @a
+    AllocatorType (`std::allocator`), the default value for @a array_t is:
 
-    JSON type | value_t type    | used type
-    --------- | --------------- | ------------------------
-    object    | object          | pointer to @ref object_t
-    array     | array           | pointer to @ref array_t
-    string    | string          | pointer to @ref string_t
-    boolean   | boolean         | @ref boolean_t
-    number    | number_integer  | @ref number_integer_t
-    number    | number_unsigned | @ref number_unsigned_t
-    number    | number_float    | @ref number_float_t
-    null      | null            | *no value is stored*
+    @code {.cpp}
+    std::vector<
+      basic_json, // value_type
+      std::allocator<basic_json> // allocator_type
+    >
+    @endcode
 
-    @note Variable-length types (objects, arrays, and strings) are stored as
-    pointers. The size of the union should not exceed 64 bits if the default
-    value types are used.
+    #### Limits
 
-    @since version 1.0.0
-    */
-    union json_value
-    {
-        /// object (stored with pointer to save storage)
-        object_t* object;
-        /// array (stored with pointer to save storage)
-        array_t* array;
-        /// string (stored with pointer to save storage)
-        string_t* string;
-        /// boolean
-        boolean_t boolean;
-        /// number (integer)
-        number_integer_t number_integer;
-        /// number (unsigned integer)
-        number_unsigned_t number_unsigned;
-        /// number (floating-point)
-        number_float_t number_float;
+    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
+    > An implementation may set limits on the maximum depth of nesting.
 
-        /// default constructor (for null values)
-        json_value() = default;
-        /// constructor for booleans
-        json_value(boolean_t v) noexcept : boolean(v) {}
-        /// constructor for numbers (integer)
-        json_value(number_integer_t v) noexcept : number_integer(v) {}
-        /// constructor for numbers (unsigned)
-        json_value(number_unsigned_t v) noexcept : number_unsigned(v) {}
-        /// constructor for numbers (floating-point)
-        json_value(number_float_t v) noexcept : number_float(v) {}
-        /// constructor for empty values of a given type
-        json_value(value_t t)
-        {
-            switch (t)
-            {
-                case value_t::object:
-                {
-                    object = create<object_t>();
-                    break;
-                }
+    In this class, the array's limit of nesting is not constraint explicitly.
+    However, a maximum depth of nesting may be introduced by the compiler or
+    runtime environment. A theoretical limit can be queried by calling the
+    @ref max_size function of a JSON array.
 
-                case value_t::array:
-                {
-                    array = create<array_t>();
-                    break;
-                }
+    #### Storage
 
-                case value_t::string:
-                {
-                    string = create<string_t>("");
-                    break;
-                }
+    Arrays are stored as pointers in a @ref basic_json type. That is, for any
+    access to array values, a pointer of type `array_t*` must be dereferenced.
 
-                case value_t::boolean:
-                {
-                    boolean = boolean_t(false);
-                    break;
-                }
+    @sa @ref object_t -- type for an object value
 
-                case value_t::number_integer:
-                {
-                    number_integer = number_integer_t(0);
-                    break;
-                }
+    @since version 1.0.0
+    */
+    using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;
 
-                case value_t::number_unsigned:
-                {
-                    number_unsigned = number_unsigned_t(0);
-                    break;
-                }
+    /*!
+    @brief a type for a string
 
-                case value_t::number_float:
-                {
-                    number_float = number_float_t(0.0);
-                    break;
-                }
+    [RFC 7159](http://rfc7159.net/rfc7159) describes JSON strings as follows:
+    > A string is a sequence of zero or more Unicode characters.
 
-                case value_t::null:
-                {
-                    break;
-                }
+    To store objects in C++, a type is defined by the template parameter
+    described below. Unicode values are split by the JSON class into
+    byte-sized characters during deserialization.
 
-                default:
-                {
-                    if (JSON_UNLIKELY(t == value_t::null))
-                    {
-                        JSON_THROW(other_error::create(500, "961c151d2e87f2686a955a9be24d316f1362bf21 2.1.1")); // LCOV_EXCL_LINE
-                    }
-                    break;
-                }
-            }
-        }
+    @tparam StringType  the container to store strings (e.g., `std::string`).
+    Note this container is used for keys/names in objects, see @ref object_t.
 
-        /// constructor for strings
-        json_value(const string_t& value)
-        {
-            string = create<string_t>(value);
-        }
+    #### Default type
 
-        /// constructor for objects
-        json_value(const object_t& value)
-        {
-            object = create<object_t>(value);
-        }
+    With the default values for @a StringType (`std::string`), the default
+    value for @a string_t is:
 
-        /// constructor for arrays
-        json_value(const array_t& value)
-        {
-            array = create<array_t>(value);
-        }
-    };
+    @code {.cpp}
+    std::string
+    @endcode
 
-    /*!
-    @brief checks the class invariants
+    #### Encoding
 
-    This function asserts the class invariants. It needs to be called at the
-    end of every constructor to make sure that created objects respect the
-    invariant. Furthermore, it has to be called each time the type of a JSON
-    value is changed, because the invariant expresses a relationship between
-    @a m_type and @a m_value.
-    */
-    void assert_invariant() const
-    {
-        assert(m_type != value_t::object or m_value.object != nullptr);
-        assert(m_type != value_t::array or m_value.array != nullptr);
-        assert(m_type != value_t::string or m_value.string != nullptr);
-    }
+    Strings are stored in UTF-8 encoding. Therefore, functions like
+    `std::string::size()` or `std::string::length()` return the number of
+    bytes in the string rather than the number of characters or glyphs.
 
-  public:
-    //////////////////////////
-    // JSON parser callback //
-    //////////////////////////
+    #### String comparison
 
-    using parse_event_t = typename parser::parse_event_t;
+    [RFC 7159](http://rfc7159.net/rfc7159) states:
+    > Software implementations are typically required to test names of object
+    > members for equality. Implementations that transform the textual
+    > representation into sequences of Unicode code units and then perform the
+    > comparison numerically, code unit by code unit, are interoperable in the
+    > sense that implementations will agree in all cases on equality or
+    > inequality of two strings. For example, implementations that compare
+    > strings with escaped characters unconverted may incorrectly find that
+    > `"a\\b"` and `"a\u005Cb"` are not equal.
 
-    /*!
-    @brief per-element parser callback type
+    This implementation is interoperable as it does compare strings code unit
+    by code unit.
 
-    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.
+    #### Storage
 
-    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.
+    String values are stored as pointers in a @ref basic_json type. That is,
+    for any access to string values, a pointer of type `string_t*` must be
+    dereferenced.
 
-    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
+    @since version 1.0.0
+    */
+    using string_t = StringType;
 
-    @image html callback_events.png "Example when certain parse events are triggered"
+    /*!
+    @brief a type for a boolean
 
-    Discarding a value (i.e., returning `false`) has different effects
-    depending on the context in which function was called:
+    [RFC 7159](http://rfc7159.net/rfc7159) implicitly describes a boolean as a
+    type which differentiates the two literals `true` and `false`.
 
-    - 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.
+    To store objects in C++, a type is defined by the template parameter @a
+    BooleanType which chooses the type to use.
 
-    @param[in] depth  the depth of the recursion during parsing
+    #### Default type
 
-    @param[in] event  an event of type parse_event_t indicating the context in
-    the callback function has been called
+    With the default values for @a BooleanType (`bool`), the default value for
+    @a boolean_t is:
 
-    @param[in,out] parsed  the current intermediate parse result; note that
-    writing to this value has no effect for parse_event_t::key events
+    @code {.cpp}
+    bool
+    @endcode
 
-    @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.
+    #### Storage
 
-    @sa @ref parse(std::istream&, parser_callback_t) or
-    @ref parse(const CharT, const parser_callback_t) for examples
+    Boolean values are stored directly inside a @ref basic_json type.
 
     @since version 1.0.0
     */
-    using parser_callback_t = typename parser::parser_callback_t;
+    using boolean_t = BooleanType;
 
+    /*!
+    @brief a type for a number (integer)
 
-    //////////////////
-    // constructors //
-    //////////////////
+    [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
+    > The representation of numbers is similar to that used in most
+    > programming languages. A number is represented in base 10 using decimal
+    > digits. It contains an integer component that may be prefixed with an
+    > optional minus sign, which may be followed by a fraction part and/or an
+    > exponent part. Leading zeros are not allowed. (...) Numeric values that
+    > cannot be represented in the grammar below (such as Infinity and NaN)
+    > are not permitted.
 
-    /// @name constructors and destructors
-    /// Constructors of class @ref basic_json, copy/move constructor, copy
-    /// assignment, static functions creating objects, and the destructor.
-    /// @{
+    This description includes both integer and floating-point numbers.
+    However, C++ allows more precise storage if it is known whether the number
+    is a signed integer, an unsigned integer or a floating-point number.
+    Therefore, three different types, @ref number_integer_t, @ref
+    number_unsigned_t and @ref number_float_t are used.
 
-    /*!
-    @brief create an empty value with a given type
+    To store integer numbers in C++, a type is defined by the template
+    parameter @a NumberIntegerType which chooses the type to use.
 
-    Create an empty JSON value with a given type. The value will be default
-    initialized with an empty value which depends on the type:
+    #### Default type
 
-    Value type  | initial value
-    ----------- | -------------
-    null        | `null`
-    boolean     | `false`
-    string      | `""`
-    number      | `0`
-    object      | `{}`
-    array       | `[]`
+    With the default values for @a NumberIntegerType (`int64_t`), the default
+    value for @a number_integer_t is:
 
-    @param[in] v  the type of the value to create
+    @code {.cpp}
+    int64_t
+    @endcode
 
-    @complexity Constant.
+    #### Default behavior
 
-    @liveexample{The following code shows the constructor for different @ref
-    value_t values,basic_json__value_t}
+    - The restrictions about leading zeros is not enforced in C++. Instead,
+      leading zeros in integer literals lead to an interpretation as octal
+      number. Internally, the value will be stored as decimal number. For
+      instance, the C++ integer literal `010` will be serialized to `8`.
+      During deserialization, leading zeros yield an error.
+    - Not-a-number (NaN) values will be serialized to `null`.
 
-    @since version 1.0.0
-    */
-    basic_json(const value_t v)
-        : m_type(v), m_value(v)
-    {
-        assert_invariant();
-    }
+    #### Limits
 
-    /*!
-    @brief create a null object
+    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
+    > An implementation may set limits on the range and precision of numbers.
 
-    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.
+    When the default type is used, the maximal integer number that can be
+    stored is `9223372036854775807` (INT64_MAX) and the minimal integer number
+    that can be stored is `-9223372036854775808` (INT64_MIN). Integer numbers
+    that are out of range will yield over/underflow when used in a
+    constructor. During deserialization, too large or small integer numbers
+    will be automatically be stored as @ref number_unsigned_t or @ref
+    number_float_t.
 
-    @complexity Constant.
+    [RFC 7159](http://rfc7159.net/rfc7159) further states:
+    > Note that when such software is used, numbers that are integers and are
+    > in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
+    > that implementations will agree exactly on their numeric values.
 
-    @exceptionsafety No-throw guarantee: this constructor never throws
-    exceptions.
+    As this range is a subrange of the exactly supported range [INT64_MIN,
+    INT64_MAX], this class's integer type is interoperable.
 
-    @liveexample{The following code shows the constructor with and without a
-    null pointer parameter.,basic_json__nullptr_t}
+    #### Storage
+
+    Integer number values are stored directly inside a @ref basic_json type.
+
+    @sa @ref number_float_t -- type for number values (floating-point)
+
+    @sa @ref number_unsigned_t -- type for number values (unsigned integer)
 
     @since version 1.0.0
     */
-    basic_json(std::nullptr_t = nullptr) noexcept
-        : basic_json(value_t::null)
-    {
-        assert_invariant();
-    }
+    using number_integer_t = NumberIntegerType;
 
     /*!
-    @brief create a JSON value
-
-    This is a "catch all" constructor for all compatible JSON types; that is,
-    types for which a `to_json()` method exsits. The constructor forwards the
-    parameter @a val to that method (to `json_serializer<U>::to_json` method
-    with `U = uncvref_t<CompatibleType>`, to be exact).
+    @brief a type for a number (unsigned)
 
-    Template type @a CompatibleType includes, but is not limited to, the
-    following types:
-    - **arrays**: @ref array_t and all kinds of compatible containers such as
-      `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.
-    - **objects**: @ref object_t and all kinds of compatible associative
-      containers such as `std::map`, `std::unordered_map`, `std::multimap`,
-      and `std::unordered_multimap` with a `key_type` compatible to
-      @ref string_t and a `value_type` from which a @ref basic_json value can
-      be constructed.
-    - **strings**: @ref string_t, string literals, and all compatible string
-      containers can be used.
-    - **numbers**: @ref number_integer_t, @ref number_unsigned_t,
-      @ref number_float_t, and all convertible number types such as `int`,
-      `size_t`, `int64_t`, `float` or `double` can be used.
-    - **boolean**: @ref boolean_t / `bool` can be used.
+    [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
+    > The representation of numbers is similar to that used in most
+    > programming languages. A number is represented in base 10 using decimal
+    > digits. It contains an integer component that may be prefixed with an
+    > optional minus sign, which may be followed by a fraction part and/or an
+    > exponent part. Leading zeros are not allowed. (...) Numeric values that
+    > cannot be represented in the grammar below (such as Infinity and NaN)
+    > are not permitted.
 
-    See the examples below.
+    This description includes both integer and floating-point numbers.
+    However, C++ allows more precise storage if it is known whether the number
+    is a signed integer, an unsigned integer or a floating-point number.
+    Therefore, three different types, @ref number_integer_t, @ref
+    number_unsigned_t and @ref number_float_t are used.
 
-    @tparam CompatibleType a type such that:
-    - @a CompatibleType is not derived from `std::istream`,
-    - @a CompatibleType is not @ref basic_json (to avoid hijacking copy/move
-         constructors),
-    - @a CompatibleType is not a @ref basic_json nested type (e.g.,
-         @ref json_pointer, @ref iterator, etc ...)
-    - @ref @ref json_serializer<U> has a
-         `to_json(basic_json_t&, CompatibleType&&)` method
+    To store unsigned integer numbers in C++, a type is defined by the
+    template parameter @a NumberUnsignedType which chooses the type to use.
 
-    @tparam U = `uncvref_t<CompatibleType>`
+    #### Default type
 
-    @param[in] val the value to be forwarded
+    With the default values for @a NumberUnsignedType (`uint64_t`), the
+    default value for @a number_unsigned_t is:
 
-    @complexity Usually linear in the size of the passed @a val, also
-                depending on the implementation of the called `to_json()`
-                method.
+    @code {.cpp}
+    uint64_t
+    @endcode
 
-    @throw what `json_serializer<U>::to_json()` throws
+    #### Default behavior
 
-    @liveexample{The following code shows the constructor with several
-    compatible types.,basic_json__CompatibleType}
+    - The restrictions about leading zeros is not enforced in C++. Instead,
+      leading zeros in integer literals lead to an interpretation as octal
+      number. Internally, the value will be stored as decimal number. For
+      instance, the C++ integer literal `010` will be serialized to `8`.
+      During deserialization, leading zeros yield an error.
+    - Not-a-number (NaN) values will be serialized to `null`.
 
-    @since version 2.1.0
-    */
-    template<typename CompatibleType, typename U = detail::uncvref_t<CompatibleType>,
-             detail::enable_if_t<not std::is_base_of<std::istream, U>::value and
-                                 not std::is_same<U, basic_json_t>::value and
-                                 not detail::is_basic_json_nested_type<
-                                     basic_json_t, U>::value and
-                                 detail::has_to_json<basic_json, U>::value,
-                                 int> = 0>
-    basic_json(CompatibleType && val) noexcept(noexcept(JSONSerializer<U>::to_json(
-                std::declval<basic_json_t&>(), std::forward<CompatibleType>(val))))
-    {
-        JSONSerializer<U>::to_json(*this, std::forward<CompatibleType>(val));
-        assert_invariant();
-    }
+    #### Limits
 
-    /*!
-    @brief create a container (array or object) from an initializer list
+    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
+    > An implementation may set limits on the range and precision of numbers.
 
-    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:
+    When the default type is used, the maximal integer number that can be
+    stored is `18446744073709551615` (UINT64_MAX) and the minimal integer
+    number that can be stored is `0`. Integer numbers that are out of range
+    will yield over/underflow when used in a constructor. During
+    deserialization, too large or small integer numbers will be automatically
+    be stored as @ref number_integer_t or @ref number_float_t.
 
-    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.
+    [RFC 7159](http://rfc7159.net/rfc7159) further states:
+    > Note that when such software is used, numbers that are integers and are
+    > in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
+    > that implementations will agree exactly on their numeric values.
 
-    The rules aim to create the best fit between a C++ initializer list and
-    JSON values. The rationale is as follows:
+    As this range is a subrange (when considered in conjunction with the
+    number_integer_t type) of the exactly supported range [0, UINT64_MAX],
+    this class's integer type is interoperable.
 
-    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.
+    #### Storage
 
-    With the rules described above, the following JSON values cannot be
-    expressed by an initializer list:
+    Integer number values are stored directly inside a @ref basic_json type.
 
-    - 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
+    @sa @ref number_float_t -- type for number values (floating-point)
+    @sa @ref number_integer_t -- type for number values (integer)
 
-    @note When used without parentheses around an empty initializer list, @ref
-    basic_json() is called instead of this function, yielding the JSON null
-    value.
+    @since version 2.0.0
+    */
+    using number_unsigned_t = NumberUnsignedType;
 
-    @param[in] init  initializer list with JSON values
+    /*!
+    @brief a type for a number (floating-point)
 
-    @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>).
+    [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
+    > The representation of numbers is similar to that used in most
+    > programming languages. A number is represented in base 10 using decimal
+    > digits. It contains an integer component that may be prefixed with an
+    > optional minus sign, which may be followed by a fraction part and/or an
+    > exponent part. Leading zeros are not allowed. (...) Numeric values that
+    > cannot be represented in the grammar below (such as Infinity and NaN)
+    > are not permitted.
 
-    @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
+    This description includes both integer and floating-point numbers.
+    However, C++ allows more precise storage if it is known whether the number
+    is a signed integer, an unsigned integer or a floating-point number.
+    Therefore, three different types, @ref number_integer_t, @ref
+    number_unsigned_t and @ref number_float_t are used.
 
-    @throw type_error.301 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. In this case, the constructor could not
-    create an object. If @a type_deduction would have be `true`, an array
-    would have been created. See @ref object(std::initializer_list<basic_json>)
-    for an example.
+    To store floating-point numbers in C++, a type is defined by the template
+    parameter @a NumberFloatType which chooses the type to use.
 
-    @complexity Linear in the size of the initializer list @a init.
+    #### Default type
 
-    @liveexample{The example below shows how JSON values are created from
-    initializer lists.,basic_json__list_init_t}
+    With the default values for @a NumberFloatType (`double`), the default
+    value for @a number_float_t is:
 
-    @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
+    @code {.cpp}
+    double
+    @endcode
 
-    @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();
-        });
+    #### Default behavior
 
-        // 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(type_error::create(301, "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
+    - The restrictions about leading zeros is not enforced in C++. Instead,
+      leading zeros in floating-point literals will be ignored. Internally,
+      the value will be stored as decimal number. For instance, the C++
+      floating-point literal `01.2` will be serialized to `1.2`. During
+      deserialization, leading zeros yield an error.
+    - Not-a-number (NaN) values will be serialized to `null`.
 
-    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.
+    #### Limits
 
-    @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
+    [RFC 7159](http://rfc7159.net/rfc7159) states:
+    > This specification allows implementations to set limits on the range and
+    > precision of numbers accepted. Since software that implements IEEE
+    > 754-2008 binary64 (double precision) numbers is generally available and
+    > widely used, good interoperability can be achieved by implementations
+    > that expect no more precision or range than these provide, in the sense
+    > that implementations will approximate JSON numbers within the expected
+    > precision.
 
-    @param[in] init  initializer list with JSON values to create an array from
-    (optional)
+    This implementation does exactly follow this approach, as it uses double
+    precision floating-point numbers. Note values smaller than
+    `-1.79769313486232e+308` and values greater than `1.79769313486232e+308`
+    will be stored as NaN internally and be serialized to `null`.
 
-    @return JSON array value
+    #### Storage
 
-    @complexity Linear in the size of @a init.
+    Floating-point number values are stored directly inside a @ref basic_json
+    type.
 
-    @liveexample{The following code shows an example for the `array`
-    function.,array}
+    @sa @ref number_integer_t -- type for number values (integer)
 
-    @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
+    @sa @ref number_unsigned_t -- type for number values (unsigned integer)
 
     @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 type_error.301 if @a init is not a list of pairs whose first
-    elements are strings. In this case, no object can be created. When such a
-    value is passed to @ref basic_json(std::initializer_list<basic_json>, bool, value_t),
-    an array would have been created from the passed initializer list @a init.
-    See example below.
-
-    @complexity Linear in the size of @a init.
+    using number_float_t = NumberFloatType;
 
-    @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
+  private:
 
-    @since version 1.0.0
-    */
-    static basic_json object(std::initializer_list<basic_json> init =
-                                 std::initializer_list<basic_json>())
+    /// helper for exception-safe object creation
+    template<typename T, typename... Args>
+    static T* create(Args&& ... args)
     {
-        return basic_json(init, false, value_t::object);
+        AllocatorType<T> alloc;
+        auto deleter = [&](T * object)
+        {
+            alloc.deallocate(object, 1);
+        };
+        std::unique_ptr<T, decltype(deleter)> object(alloc.allocate(1), deleter);
+        alloc.construct(object.get(), std::forward<Args>(args)...);
+        assert(object != nullptr);
+        return object.release();
     }
 
-    /*!
-    @brief construct an array with count copies of given value
+    ////////////////////////
+    // JSON value storage //
+    ////////////////////////
 
-    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.
+    /*!
+    @brief a JSON value
 
-    @param[in] cnt  the number of JSON copies of @a val to create
-    @param[in] val  the JSON value to copy
+    The actual storage for a JSON value of the @ref basic_json class. This
+    union combines the different storage types for the JSON value types
+    defined in @ref value_t.
 
-    @complexity Linear in @a cnt.
+    JSON type | value_t type    | used type
+    --------- | --------------- | ------------------------
+    object    | object          | pointer to @ref object_t
+    array     | array           | pointer to @ref array_t
+    string    | string          | pointer to @ref string_t
+    boolean   | boolean         | @ref boolean_t
+    number    | number_integer  | @ref number_integer_t
+    number    | number_unsigned | @ref number_unsigned_t
+    number    | number_float    | @ref number_float_t
+    null      | null            | *no value is stored*
 
-    @liveexample{The following code shows examples for the @ref
-    basic_json(size_type\, const basic_json&)
-    constructor.,basic_json__size_type_basic_json}
+    @note Variable-length types (objects, arrays, and strings) are stored as
+    pointers. The size of the union should not exceed 64 bits if the default
+    value types are used.
 
     @since version 1.0.0
     */
-    basic_json(size_type cnt, const basic_json& val)
-        : m_type(value_t::array)
+    union json_value
     {
-        m_value.array = create<array_t>(cnt, val);
-        assert_invariant();
-    }
+        /// object (stored with pointer to save storage)
+        object_t* object;
+        /// array (stored with pointer to save storage)
+        array_t* array;
+        /// string (stored with pointer to save storage)
+        string_t* string;
+        /// boolean
+        boolean_t boolean;
+        /// number (integer)
+        number_integer_t number_integer;
+        /// number (unsigned integer)
+        number_unsigned_t number_unsigned;
+        /// number (floating-point)
+        number_float_t number_float;
 
-    /*!
-    @brief construct a JSON container given an iterator range
+        /// default constructor (for null values)
+        json_value() = default;
+        /// constructor for booleans
+        json_value(boolean_t v) noexcept : boolean(v) {}
+        /// constructor for numbers (integer)
+        json_value(number_integer_t v) noexcept : number_integer(v) {}
+        /// constructor for numbers (unsigned)
+        json_value(number_unsigned_t v) noexcept : number_unsigned(v) {}
+        /// constructor for numbers (floating-point)
+        json_value(number_float_t v) noexcept : number_float(v) {}
+        /// constructor for empty values of a given type
+        json_value(value_t t)
+        {
+            switch (t)
+            {
+                case value_t::object:
+                {
+                    object = create<object_t>();
+                    break;
+                }
 
-    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, invalid_iterator.204 is thrown.
-    - In case of structured types (array, object), the constructor behaves as
-      similar versions for `std::vector`.
-    - In case of a null type, invalid_iterator.206 is thrown.
+                case value_t::array:
+                {
+                    array = create<array_t>();
+                    break;
+                }
 
-    @tparam InputIT an input iterator type (@ref iterator or @ref
-    const_iterator)
+                case value_t::string:
+                {
+                    string = create<string_t>("");
+                    break;
+                }
 
-    @param[in] first begin of the range to copy from (included)
-    @param[in] last end of the range to copy from (excluded)
+                case value_t::boolean:
+                {
+                    boolean = boolean_t(false);
+                    break;
+                }
 
-    @pre Iterators @a first and @a last must be initialized. **This
-         precondition is enforced with an assertion.**
+                case value_t::number_integer:
+                {
+                    number_integer = number_integer_t(0);
+                    break;
+                }
 
-    @pre Range `[first, last)` is valid. Usually, this precondition cannot be
-         checked efficiently. Only certain edge cases are detected; see the
-         description of the exceptions below.
+                case value_t::number_unsigned:
+                {
+                    number_unsigned = number_unsigned_t(0);
+                    break;
+                }
 
-    @throw invalid_iterator.201 if iterators @a first and @a last are not
-    compatible (i.e., do not belong to the same JSON value). In this case,
-    the range `[first, last)` is undefined.
-    @throw invalid_iterator.204 if iterators @a first and @a last belong to a
-    primitive type (number, boolean, or string), but @a first does not point
-    to the first element any more. In this case, the range `[first, last)` is
-    undefined. See example code below.
-    @throw invalid_iterator.206 if iterators @a first and @a last belong to a
-    null value. In this case, the range `[first, last)` is undefined.
-
-    @complexity Linear in distance between @a first and @a last.
+                case value_t::number_float:
+                {
+                    number_float = number_float_t(0.0);
+                    break;
+                }
 
-    @liveexample{The example below shows several ways to create JSON values by
-    specifying a subrange with iterators.,basic_json__InputIt_InputIt}
+                case value_t::null:
+                {
+                    break;
+                }
 
-    @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);
+                default:
+                {
+                    if (JSON_UNLIKELY(t == value_t::null))
+                    {
+                        JSON_THROW(other_error::create(500, "961c151d2e87f2686a955a9be24d316f1362bf21 2.1.1")); // LCOV_EXCL_LINE
+                    }
+                    break;
+                }
+            }
+        }
 
-        // make sure iterator fits the current value
-        if (first.m_object != last.m_object)
+        /// constructor for strings
+        json_value(const string_t& value)
         {
-            JSON_THROW(invalid_iterator::create(201, "iterators are not compatible"));
+            string = create<string_t>(value);
         }
 
-        // copy type from first iterator
-        m_type = first.m_object->m_type;
-
-        // check if iterator range is complete for primitive values
-        switch (m_type)
+        /// constructor for objects
+        json_value(const object_t& value)
         {
-            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(invalid_iterator::create(204, "iterators out of range"));
-                }
-                break;
-            }
-
-            default:
-            {
-                break;
-            }
+            object = create<object_t>(value);
         }
 
-        switch (m_type)
+        /// constructor for arrays
+        json_value(const array_t& value)
         {
-            case value_t::number_integer:
-            {
-                m_value.number_integer = first.m_object->m_value.number_integer;
-                break;
-            }
+            array = create<array_t>(value);
+        }
+    };
 
-            case value_t::number_unsigned:
-            {
-                m_value.number_unsigned = first.m_object->m_value.number_unsigned;
-                break;
-            }
+    /*!
+    @brief checks the class invariants
 
-            case value_t::number_float:
-            {
-                m_value.number_float = first.m_object->m_value.number_float;
-                break;
-            }
+    This function asserts the class invariants. It needs to be called at the
+    end of every constructor to make sure that created objects respect the
+    invariant. Furthermore, it has to be called each time the type of a JSON
+    value is changed, because the invariant expresses a relationship between
+    @a m_type and @a m_value.
+    */
+    void assert_invariant() const
+    {
+        assert(m_type != value_t::object or m_value.object != nullptr);
+        assert(m_type != value_t::array or m_value.array != nullptr);
+        assert(m_type != value_t::string or m_value.string != nullptr);
+    }
 
-            case value_t::boolean:
-            {
-                m_value.boolean = first.m_object->m_value.boolean;
-                break;
-            }
+  public:
+    //////////////////////////
+    // JSON parser callback //
+    //////////////////////////
 
-            case value_t::string:
-            {
-                m_value = *first.m_object->m_value.string;
-                break;
-            }
+    using parse_event_t = typename parser::parse_event_t;
 
-            case value_t::object:
-            {
-                m_value.object = create<object_t>(first.m_it.object_iterator,
-                                                  last.m_it.object_iterator);
-                break;
-            }
+    /*!
+    @brief per-element parser callback type
 
-            case value_t::array:
-            {
-                m_value.array = create<array_t>(first.m_it.array_iterator,
-                                                last.m_it.array_iterator);
-                break;
-            }
+    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.
 
-            default:
-            {
-                JSON_THROW(invalid_iterator::create(206, "cannot construct with iterators from " +
-                                                    first.m_object->type_name()));
-            }
-        }
+    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.
 
-        assert_invariant();
-    }
+    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"
 
-    ///////////////////////////////////////
-    // other constructors and destructor //
-    ///////////////////////////////////////
+    Discarding a value (i.e., returning `false`) has different effects
+    depending on the context in which function was called:
 
-    /*!
-    @brief copy constructor
+    - 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.
 
-    Creates a copy of a given JSON value.
+    @param[in] depth  the depth of the recursion during parsing
 
-    @param[in] other  the JSON value to copy
+    @param[in] event  an event of type parse_event_t indicating the context in
+    the callback function has been called
 
-    @complexity Linear in the size of @a other.
+    @param[in,out] parsed  the current intermediate parse result; note that
+    writing to this value has no effect for parse_event_t::key events
 
-    @requirement This function helps `basic_json` satisfying the
-    [Container](http://en.cppreference.com/w/cpp/concept/Container)
-    requirements:
-    - The complexity is linear.
-    - As postcondition, it holds: `other == basic_json(other)`.
+    @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.
 
-    @liveexample{The following code shows an example for the copy
-    constructor.,basic_json__basic_json}
+    @sa @ref parse(std::istream&, parser_callback_t) or
+    @ref parse(const CharT, const parser_callback_t) for examples
 
     @since version 1.0.0
     */
-    basic_json(const basic_json& other)
-        : m_type(other.m_type)
-    {
-        // check of passed value is valid
-        other.assert_invariant();
+    using parser_callback_t = typename parser::parser_callback_t;
 
-        switch (m_type)
-        {
-            case value_t::object:
-            {
-                m_value = *other.m_value.object;
-                break;
-            }
 
-            case value_t::array:
-            {
-                m_value = *other.m_value.array;
-                break;
-            }
+    //////////////////
+    // constructors //
+    //////////////////
 
-            case value_t::string:
-            {
-                m_value = *other.m_value.string;
-                break;
-            }
+    /// @name constructors and destructors
+    /// Constructors of class @ref basic_json, copy/move constructor, copy
+    /// assignment, static functions creating objects, and the destructor.
+    /// @{
 
-            case value_t::boolean:
-            {
-                m_value = other.m_value.boolean;
-                break;
-            }
+    /*!
+    @brief create an empty value with a given type
 
-            case value_t::number_integer:
-            {
-                m_value = other.m_value.number_integer;
-                break;
-            }
+    Create an empty JSON value with a given type. The value will be default
+    initialized with an empty value which depends on the type:
 
-            case value_t::number_unsigned:
-            {
-                m_value = other.m_value.number_unsigned;
-                break;
-            }
+    Value type  | initial value
+    ----------- | -------------
+    null        | `null`
+    boolean     | `false`
+    string      | `""`
+    number      | `0`
+    object      | `{}`
+    array       | `[]`
 
-            case value_t::number_float:
-            {
-                m_value = other.m_value.number_float;
-                break;
-            }
+    @param[in] v  the type of the value to create
 
-            default:
-            {
-                break;
-            }
-        }
+    @complexity Constant.
+
+    @liveexample{The following code shows the constructor for different @ref
+    value_t values,basic_json__value_t}
 
+    @since version 1.0.0
+    */
+    basic_json(const value_t v)
+        : m_type(v), m_value(v)
+    {
         assert_invariant();
     }
 
     /*!
-    @brief move constructor
-
-    Move constructor. Constructs a JSON value with the contents of the given
-    value @a other using move semantics. It "steals" the resources from @a
-    other and leaves it as JSON null value.
-
-    @param[in,out] other  value to move to this object
+    @brief create a null object
 
-    @post @a other is a JSON null value
+    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.
 
-    @liveexample{The code below shows the move constructor explicitly called
-    via std::move.,basic_json__moveconstructor}
+    @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(basic_json&& other) noexcept
-        : m_type(std::move(other.m_type)),
-          m_value(std::move(other.m_value))
+    basic_json(std::nullptr_t = nullptr) noexcept
+        : basic_json(value_t::null)
     {
-        // check that passed value is valid
-        other.assert_invariant();
-
-        // invalidate payload
-        other.m_type = value_t::null;
-        other.m_value = {};
-
         assert_invariant();
     }
 
     /*!
-    @brief copy assignment
+    @brief create a JSON value
 
-    Copy assignment operator. Copies a JSON value via the "copy and swap"
-    strategy: It is expressed in terms of the copy constructor, destructor,
-    and the swap() member function.
+    This is a "catch all" constructor for all compatible JSON types; that is,
+    types for which a `to_json()` method exsits. The constructor forwards the
+    parameter @a val to that method (to `json_serializer<U>::to_json` method
+    with `U = uncvref_t<CompatibleType>`, to be exact).
 
-    @param[in] other  value to copy from
+    Template type @a CompatibleType includes, but is not limited to, the
+    following types:
+    - **arrays**: @ref array_t and all kinds of compatible containers such as
+      `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.
+    - **objects**: @ref object_t and all kinds of compatible associative
+      containers such as `std::map`, `std::unordered_map`, `std::multimap`,
+      and `std::unordered_multimap` with a `key_type` compatible to
+      @ref string_t and a `value_type` from which a @ref basic_json value can
+      be constructed.
+    - **strings**: @ref string_t, string literals, and all compatible string
+      containers can be used.
+    - **numbers**: @ref number_integer_t, @ref number_unsigned_t,
+      @ref number_float_t, and all convertible number types such as `int`,
+      `size_t`, `int64_t`, `float` or `double` can be used.
+    - **boolean**: @ref boolean_t / `bool` can be used.
 
-    @complexity Linear.
+    See the examples below.
 
-    @requirement This function helps `basic_json` satisfying the
-    [Container](http://en.cppreference.com/w/cpp/concept/Container)
-    requirements:
-    - The complexity is linear.
+    @tparam CompatibleType a type such that:
+    - @a CompatibleType is not derived from `std::istream`,
+    - @a CompatibleType is not @ref basic_json (to avoid hijacking copy/move
+         constructors),
+    - @a CompatibleType is not a @ref basic_json nested type (e.g.,
+         @ref json_pointer, @ref iterator, etc ...)
+    - @ref @ref json_serializer<U> has a
+         `to_json(basic_json_t&, CompatibleType&&)` method
 
-    @liveexample{The code below shows and example for the copy assignment. It
-    creates a copy of value `a` which is then swapped with `b`. Finally\, the
-    copy of `a` (which is the null value after the swap) is
-    destroyed.,basic_json__copyassignment}
+    @tparam U = `uncvref_t<CompatibleType>`
 
-    @since version 1.0.0
-    */
-    reference& operator=(basic_json other) noexcept (
-        std::is_nothrow_move_constructible<value_t>::value and
-        std::is_nothrow_move_assignable<value_t>::value and
-        std::is_nothrow_move_constructible<json_value>::value and
-        std::is_nothrow_move_assignable<json_value>::value
-    )
-    {
-        // check that passed value is valid
-        other.assert_invariant();
+    @param[in] val the value to be forwarded
 
-        using std::swap;
-        swap(m_type, other.m_type);
-        swap(m_value, other.m_value);
+    @complexity Usually linear in the size of the passed @a val, also
+                depending on the implementation of the called `to_json()`
+                method.
+
+    @throw what `json_serializer<U>::to_json()` throws
 
+    @liveexample{The following code shows the constructor with several
+    compatible types.,basic_json__CompatibleType}
+
+    @since version 2.1.0
+    */
+    template<typename CompatibleType, typename U = detail::uncvref_t<CompatibleType>,
+             detail::enable_if_t<not std::is_base_of<std::istream, U>::value and
+                                 not std::is_same<U, basic_json_t>::value and
+                                 not detail::is_basic_json_nested_type<
+                                     basic_json_t, U>::value and
+                                 detail::has_to_json<basic_json, U>::value,
+                                 int> = 0>
+    basic_json(CompatibleType && val) noexcept(noexcept(JSONSerializer<U>::to_json(
+                std::declval<basic_json_t&>(), std::forward<CompatibleType>(val))))
+    {
+        JSONSerializer<U>::to_json(*this, std::forward<CompatibleType>(val));
         assert_invariant();
-        return *this;
     }
 
     /*!
-    @brief destructor
+    @brief create a container (array or object) from an initializer list
 
-    Destroys the JSON value and frees all allocated memory.
+    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:
 
-    @complexity Linear.
+    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.
 
-    @requirement This function helps `basic_json` satisfying the
-    [Container](http://en.cppreference.com/w/cpp/concept/Container)
-    requirements:
-    - The complexity is linear.
-    - All stored elements are destroyed and all memory is freed.
+    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 type_error.301 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. In this case, the constructor could not
+    create an object. If @a type_deduction would have be `true`, an array
+    would have been created. See @ref object(std::initializer_list<basic_json>)
+    for an example.
+
+    @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()
+    basic_json(std::initializer_list<basic_json> init,
+               bool type_deduction = true,
+               value_t manual_type = value_t::array)
     {
-        assert_invariant();
+        // 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();
+        });
 
-        switch (m_type)
+        // adjust type if type deduction is not wanted
+        if (not type_deduction)
         {
-            case value_t::object:
+            // if array is wanted, do not create an object though possible
+            if (manual_type == value_t::array)
             {
-                AllocatorType<object_t> alloc;
-                alloc.destroy(m_value.object);
-                alloc.deallocate(m_value.object, 1);
-                break;
+                is_an_object = false;
             }
 
-            case value_t::array:
+            // if object is wanted but impossible, throw an exception
+            if (manual_type == value_t::object and not is_an_object)
             {
-                AllocatorType<array_t> alloc;
-                alloc.destroy(m_value.array);
-                alloc.deallocate(m_value.array, 1);
-                break;
+                JSON_THROW(type_error::create(301, "cannot create object from initializer list"));
             }
+        }
 
-            case value_t::string:
-            {
-                AllocatorType<string_t> alloc;
-                alloc.destroy(m_value.string);
-                alloc.deallocate(m_value.string, 1);
-                break;
-            }
+        if (is_an_object)
+        {
+            // the initializer list is a list of pairs -> create object
+            m_type = value_t::object;
+            m_value = value_t::object;
 
-            default:
+            std::for_each(init.begin(), init.end(), [this](const basic_json & element)
             {
-                // all other types need no specific destructor
-                break;
-            }
-        }
-    }
-
-    /// @}
-
-  public:
-    ///////////////////////
-    // object inspection //
-    ///////////////////////
-
-    /// @name object inspection
-    /// Functions to inspect the type of a JSON value.
-    /// @{
-
-    /*!
-    @brief serialization
-
-    Serialization function for JSON values. The function tries to mimic
-    Python's `json.dumps()` function, and currently supports its @a indent
-    parameter.
-
-    @param[in] indent If indent is nonnegative, then array elements and object
-    members will be pretty-printed with that indent level. An indent level of
-    `0` will only insert newlines. `-1` (the default) selects the most compact
-    representation.
-    @param[in] indent_char The character to use for indentation if @a indent is
-    greater than `0`. The default is ` ` (space).
-
-    @return string containing the serialization of the JSON value
-
-    @complexity Linear.
-
-    @liveexample{The following example shows the effect of different @a indent
-    parameters to the result of the serialization.,dump}
-
-    @see https://docs.python.org/2/library/json.html#json.dump
-
-    @since version 1.0.0; indentation character added in version 3.0.0
-    */
-    string_t dump(const int indent = -1, const char indent_char = ' ') const
-    {
-        string_t result;
-        serializer s(output_adapter<char>::create(result), indent_char);
-
-        if (indent >= 0)
-        {
-            s.dump(*this, true, static_cast<unsigned int>(indent));
+                m_value.object->emplace(*(element[0].m_value.string), element[1]);
+            });
         }
         else
         {
-            s.dump(*this, false, 0);
+            // the initializer list describes an array -> create array
+            m_type = value_t::array;
+            m_value.array = create<array_t>(init);
         }
 
-        return result;
+        assert_invariant();
     }
 
     /*!
-    @brief return the type of the JSON value (explicit)
-
-    Return the type of the JSON value as a value from the @ref value_t
-    enumeration.
-
-    @return the type of the JSON value
-
-    @complexity Constant.
-
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
-
-    @liveexample{The following code exemplifies `type()` for all JSON
-    types.,type}
-
-    @since version 1.0.0
-    */
-    constexpr value_t type() const noexcept
-    {
-        return m_type;
-    }
+    @brief explicitly create an array from an initializer list
 
-    /*!
-    @brief return whether type is primitive
+    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.
 
-    This function returns true iff the JSON type is primitive (string, number,
-    boolean, or null).
+    @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
 
-    @return `true` if type is primitive (string, number, boolean, or null),
-    `false` otherwise.
+    @param[in] init  initializer list with JSON values to create an array from
+    (optional)
 
-    @complexity Constant.
+    @return JSON array value
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    @complexity Linear in the size of @a init.
 
-    @liveexample{The following code exemplifies `is_primitive()` for all JSON
-    types.,is_primitive}
+    @liveexample{The following code shows an example for the `array`
+    function.,array}
 
-    @sa @ref is_structured() -- returns whether JSON value is structured
-    @sa @ref is_null() -- returns whether JSON value is `null`
-    @sa @ref is_string() -- returns whether JSON value is a string
-    @sa @ref is_boolean() -- returns whether JSON value is a boolean
-    @sa @ref is_number() -- returns whether JSON value is a number
+    @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
     */
-    constexpr bool is_primitive() const noexcept
+    static basic_json array(std::initializer_list<basic_json> init =
+                                std::initializer_list<basic_json>())
     {
-        return is_null() or is_string() or is_boolean() or is_number();
+        return basic_json(init, false, value_t::array);
     }
 
     /*!
-    @brief return whether type is structured
-
-    This function returns true iff the JSON type is structured (array or
-    object).
-
-    @return `true` if type is structured (array or object), `false` otherwise.
-
-    @complexity Constant.
-
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
-
-    @liveexample{The following code exemplifies `is_structured()` for all JSON
-    types.,is_structured}
+    @brief explicitly create an object from an initializer list
 
-    @sa @ref is_primitive() -- returns whether value is primitive
-    @sa @ref is_array() -- returns whether value is an array
-    @sa @ref is_object() -- returns whether value is an object
+    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.
 
-    @since version 1.0.0
-    */
-    constexpr bool is_structured() const noexcept
-    {
-        return is_array() or is_object();
-    }
+    @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).
 
-    /*!
-    @brief return whether value is null
+    @param[in] init  initializer list to create an object from (optional)
 
-    This function returns true iff the JSON value is null.
+    @return JSON object value
 
-    @return `true` if type is null, `false` otherwise.
+    @throw type_error.301 if @a init is not a list of pairs whose first
+    elements are strings. In this case, no object can be created. When such a
+    value is passed to @ref basic_json(std::initializer_list<basic_json>, bool, value_t),
+    an array would have been created from the passed initializer list @a init.
+    See example below.
 
-    @complexity Constant.
+    @complexity Linear in the size of @a init.
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    @liveexample{The following code shows an example for the `object`
+    function.,object}
 
-    @liveexample{The following code exemplifies `is_null()` for all JSON
-    types.,is_null}
+    @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
     */
-    constexpr bool is_null() const noexcept
+    static basic_json object(std::initializer_list<basic_json> init =
+                                 std::initializer_list<basic_json>())
     {
-        return m_type == value_t::null;
+        return basic_json(init, false, value_t::object);
     }
 
     /*!
-    @brief return whether value is a boolean
-
-    This function returns true iff the JSON value is a boolean.
+    @brief construct an array with count copies of given value
 
-    @return `true` if type is boolean, `false` otherwise.
+    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.
 
-    @complexity Constant.
+    @param[in] cnt  the number of JSON copies of @a val to create
+    @param[in] val  the JSON value to copy
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    @complexity Linear in @a cnt.
 
-    @liveexample{The following code exemplifies `is_boolean()` for all JSON
-    types.,is_boolean}
+    @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
     */
-    constexpr bool is_boolean() const noexcept
+    basic_json(size_type cnt, const basic_json& val)
+        : m_type(value_t::array)
     {
-        return m_type == value_t::boolean;
+        m_value.array = create<array_t>(cnt, val);
+        assert_invariant();
     }
 
     /*!
-    @brief return whether value is a number
+    @brief construct a JSON container given an iterator range
 
-    This function returns true iff the JSON value is a number. This includes
-    both integer and floating-point values.
+    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, invalid_iterator.204 is thrown.
+    - In case of structured types (array, object), the constructor behaves as
+      similar versions for `std::vector`.
+    - In case of a null type, invalid_iterator.206 is thrown.
 
-    @return `true` if type is number (regardless whether integer, unsigned
-    integer or floating-type), `false` otherwise.
+    @tparam InputIT an input iterator type (@ref iterator or @ref
+    const_iterator)
 
-    @complexity Constant.
+    @param[in] first begin of the range to copy from (included)
+    @param[in] last end of the range to copy from (excluded)
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    @pre Iterators @a first and @a last must be initialized. **This
+         precondition is enforced with an assertion.**
 
-    @liveexample{The following code exemplifies `is_number()` for all JSON
-    types.,is_number}
+    @pre Range `[first, last)` is valid. Usually, this precondition cannot be
+         checked efficiently. Only certain edge cases are detected; see the
+         description of the exceptions below.
 
-    @sa @ref is_number_integer() -- check if value is an integer or unsigned
-    integer number
-    @sa @ref is_number_unsigned() -- check if value is an unsigned integer
-    number
-    @sa @ref is_number_float() -- check if value is a floating-point number
+    @throw invalid_iterator.201 if iterators @a first and @a last are not
+    compatible (i.e., do not belong to the same JSON value). In this case,
+    the range `[first, last)` is undefined.
+    @throw invalid_iterator.204 if iterators @a first and @a last belong to a
+    primitive type (number, boolean, or string), but @a first does not point
+    to the first element any more. In this case, the range `[first, last)` is
+    undefined. See example code below.
+    @throw invalid_iterator.206 if iterators @a first and @a last belong to a
+    null value. In this case, the range `[first, last)` is undefined.
+
+    @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
     */
-    constexpr bool is_number() const noexcept
+    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)
     {
-        return is_number_integer() or is_number_float();
-    }
+        assert(first.m_object != nullptr);
+        assert(last.m_object != nullptr);
 
-    /*!
-    @brief return whether value is an integer number
-
-    This function returns true iff the JSON value is an integer or unsigned
-    integer number. This excludes floating-point values.
+        // make sure iterator fits the current value
+        if (first.m_object != last.m_object)
+        {
+            JSON_THROW(invalid_iterator::create(201, "iterators are not compatible"));
+        }
 
-    @return `true` if type is an integer or unsigned integer number, `false`
-    otherwise.
+        // copy type from first iterator
+        m_type = first.m_object->m_type;
 
-    @complexity Constant.
+        // 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(invalid_iterator::create(204, "iterators out of range"));
+                }
+                break;
+            }
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+            default:
+            {
+                break;
+            }
+        }
 
-    @liveexample{The following code exemplifies `is_number_integer()` for all
-    JSON types.,is_number_integer}
+        switch (m_type)
+        {
+            case value_t::number_integer:
+            {
+                m_value.number_integer = first.m_object->m_value.number_integer;
+                break;
+            }
 
-    @sa @ref is_number() -- check if value is a number
-    @sa @ref is_number_unsigned() -- check if value is an unsigned integer
-    number
-    @sa @ref is_number_float() -- check if value is a floating-point number
+            case value_t::number_unsigned:
+            {
+                m_value.number_unsigned = first.m_object->m_value.number_unsigned;
+                break;
+            }
 
-    @since version 1.0.0
-    */
-    constexpr bool is_number_integer() const noexcept
-    {
-        return m_type == value_t::number_integer or m_type == value_t::number_unsigned;
-    }
+            case value_t::number_float:
+            {
+                m_value.number_float = first.m_object->m_value.number_float;
+                break;
+            }
 
-    /*!
-    @brief return whether value is an unsigned integer number
+            case value_t::boolean:
+            {
+                m_value.boolean = first.m_object->m_value.boolean;
+                break;
+            }
 
-    This function returns true iff the JSON value is an unsigned integer
-    number. This excludes floating-point and (signed) integer values.
+            case value_t::string:
+            {
+                m_value = *first.m_object->m_value.string;
+                break;
+            }
 
-    @return `true` if type is an unsigned integer number, `false` otherwise.
+            case value_t::object:
+            {
+                m_value.object = create<object_t>(first.m_it.object_iterator,
+                                                  last.m_it.object_iterator);
+                break;
+            }
 
-    @complexity Constant.
+            case value_t::array:
+            {
+                m_value.array = create<array_t>(first.m_it.array_iterator,
+                                                last.m_it.array_iterator);
+                break;
+            }
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+            default:
+            {
+                JSON_THROW(invalid_iterator::create(206, "cannot construct with iterators from " +
+                                                    first.m_object->type_name()));
+            }
+        }
 
-    @liveexample{The following code exemplifies `is_number_unsigned()` for all
-    JSON types.,is_number_unsigned}
+        assert_invariant();
+    }
 
-    @sa @ref is_number() -- check if value is a number
-    @sa @ref is_number_integer() -- check if value is an integer or unsigned
-    integer number
-    @sa @ref is_number_float() -- check if value is a floating-point number
 
-    @since version 2.0.0
-    */
-    constexpr bool is_number_unsigned() const noexcept
-    {
-        return m_type == value_t::number_unsigned;
-    }
+    ///////////////////////////////////////
+    // other constructors and destructor //
+    ///////////////////////////////////////
 
     /*!
-    @brief return whether value is a floating-point number
-
-    This function returns true iff the JSON value is a floating-point number.
-    This excludes integer and unsigned integer values.
+    @brief copy constructor
 
-    @return `true` if type is a floating-point number, `false` otherwise.
+    Creates a copy of a given JSON value.
 
-    @complexity Constant.
+    @param[in] other  the JSON value to copy
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    @complexity Linear in the size of @a other.
 
-    @liveexample{The following code exemplifies `is_number_float()` for all
-    JSON types.,is_number_float}
+    @requirement This function helps `basic_json` satisfying the
+    [Container](http://en.cppreference.com/w/cpp/concept/Container)
+    requirements:
+    - The complexity is linear.
+    - As postcondition, it holds: `other == basic_json(other)`.
 
-    @sa @ref is_number() -- check if value is number
-    @sa @ref is_number_integer() -- check if value is an integer number
-    @sa @ref is_number_unsigned() -- check if value is an unsigned integer
-    number
+    @liveexample{The following code shows an example for the copy
+    constructor.,basic_json__basic_json}
 
     @since version 1.0.0
     */
-    constexpr bool is_number_float() const noexcept
+    basic_json(const basic_json& other)
+        : m_type(other.m_type)
     {
-        return m_type == value_t::number_float;
-    }
+        // check of passed value is valid
+        other.assert_invariant();
 
-    /*!
-    @brief return whether value is an object
+        switch (m_type)
+        {
+            case value_t::object:
+            {
+                m_value = *other.m_value.object;
+                break;
+            }
 
-    This function returns true iff the JSON value is an object.
+            case value_t::array:
+            {
+                m_value = *other.m_value.array;
+                break;
+            }
 
-    @return `true` if type is object, `false` otherwise.
+            case value_t::string:
+            {
+                m_value = *other.m_value.string;
+                break;
+            }
 
-    @complexity Constant.
+            case value_t::boolean:
+            {
+                m_value = other.m_value.boolean;
+                break;
+            }
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+            case value_t::number_integer:
+            {
+                m_value = other.m_value.number_integer;
+                break;
+            }
 
-    @liveexample{The following code exemplifies `is_object()` for all JSON
-    types.,is_object}
+            case value_t::number_unsigned:
+            {
+                m_value = other.m_value.number_unsigned;
+                break;
+            }
 
-    @since version 1.0.0
-    */
-    constexpr bool is_object() const noexcept
-    {
-        return m_type == value_t::object;
+            case value_t::number_float:
+            {
+                m_value = other.m_value.number_float;
+                break;
+            }
+
+            default:
+            {
+                break;
+            }
+        }
+
+        assert_invariant();
     }
 
     /*!
-    @brief return whether value is an array
+    @brief move constructor
 
-    This function returns true iff the JSON value is an array.
+    Move constructor. Constructs a JSON value with the contents of the given
+    value @a other using move semantics. It "steals" the resources from @a
+    other and leaves it as JSON null value.
 
-    @return `true` if type is array, `false` otherwise.
+    @param[in,out] other  value to move to this object
 
-    @complexity Constant.
+    @post @a other is a JSON null value
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    @complexity Constant.
 
-    @liveexample{The following code exemplifies `is_array()` for all JSON
-    types.,is_array}
+    @liveexample{The code below shows the move constructor explicitly called
+    via std::move.,basic_json__moveconstructor}
 
     @since version 1.0.0
     */
-    constexpr bool is_array() const noexcept
+    basic_json(basic_json&& other) noexcept
+        : m_type(std::move(other.m_type)),
+          m_value(std::move(other.m_value))
     {
-        return m_type == value_t::array;
+        // check that passed value is valid
+        other.assert_invariant();
+
+        // invalidate payload
+        other.m_type = value_t::null;
+        other.m_value = {};
+
+        assert_invariant();
     }
 
     /*!
-    @brief return whether value is a string
+    @brief copy assignment
 
-    This function returns true iff the JSON value is a string.
+    Copy assignment operator. Copies a JSON value via the "copy and swap"
+    strategy: It is expressed in terms of the copy constructor, destructor,
+    and the swap() member function.
 
-    @return `true` if type is string, `false` otherwise.
+    @param[in] other  value to copy from
 
-    @complexity Constant.
+    @complexity Linear.
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    @requirement This function helps `basic_json` satisfying the
+    [Container](http://en.cppreference.com/w/cpp/concept/Container)
+    requirements:
+    - The complexity is linear.
 
-    @liveexample{The following code exemplifies `is_string()` for all JSON
-    types.,is_string}
+    @liveexample{The code below shows and example for the copy assignment. It
+    creates a copy of value `a` which is then swapped with `b`. Finally\, the
+    copy of `a` (which is the null value after the swap) is
+    destroyed.,basic_json__copyassignment}
 
     @since version 1.0.0
     */
-    constexpr bool is_string() const noexcept
+    reference& operator=(basic_json other) noexcept (
+        std::is_nothrow_move_constructible<value_t>::value and
+        std::is_nothrow_move_assignable<value_t>::value and
+        std::is_nothrow_move_constructible<json_value>::value and
+        std::is_nothrow_move_assignable<json_value>::value
+    )
     {
-        return m_type == value_t::string;
+        // check that passed value is valid
+        other.assert_invariant();
+
+        using std::swap;
+        swap(m_type, other.m_type);
+        swap(m_value, other.m_value);
+
+        assert_invariant();
+        return *this;
     }
 
     /*!
-    @brief return whether value is discarded
+    @brief destructor
 
-    This function returns true iff the JSON value was discarded during parsing
-    with a callback function (see @ref parser_callback_t).
+    Destroys the JSON value and frees all allocated memory.
 
-    @note This function will always be `false` for JSON values after parsing.
-    That is, discarded values can only occur during parsing, but will be
-    removed when inside a structured value or replaced by null in other cases.
+    @complexity Linear.
 
-    @return `true` if type is discarded, `false` otherwise.
+    @requirement This function helps `basic_json` satisfying the
+    [Container](http://en.cppreference.com/w/cpp/concept/Container)
+    requirements:
+    - The complexity is linear.
+    - All stored elements are destroyed and all memory is freed.
 
-    @complexity Constant.
+    @since version 1.0.0
+    */
+    ~basic_json()
+    {
+        assert_invariant();
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+        switch (m_type)
+        {
+            case value_t::object:
+            {
+                AllocatorType<object_t> alloc;
+                alloc.destroy(m_value.object);
+                alloc.deallocate(m_value.object, 1);
+                break;
+            }
 
-    @liveexample{The following code exemplifies `is_discarded()` for all JSON
-    types.,is_discarded}
+            case value_t::array:
+            {
+                AllocatorType<array_t> alloc;
+                alloc.destroy(m_value.array);
+                alloc.deallocate(m_value.array, 1);
+                break;
+            }
 
-    @since version 1.0.0
+            case value_t::string:
+            {
+                AllocatorType<string_t> alloc;
+                alloc.destroy(m_value.string);
+                alloc.deallocate(m_value.string, 1);
+                break;
+            }
+
+            default:
+            {
+                // all other types need no specific destructor
+                break;
+            }
+        }
+    }
+
+    /// @}
+
+  public:
+    ///////////////////////
+    // object inspection //
+    ///////////////////////
+
+    /// @name object inspection
+    /// Functions to inspect the type of a JSON value.
+    /// @{
+
+    /*!
+    @brief serialization
+
+    Serialization function for JSON values. The function tries to mimic
+    Python's `json.dumps()` function, and currently supports its @a indent
+    parameter.
+
+    @param[in] indent If indent is nonnegative, then array elements and object
+    members will be pretty-printed with that indent level. An indent level of
+    `0` will only insert newlines. `-1` (the default) selects the most compact
+    representation.
+    @param[in] indent_char The character to use for indentation if @a indent is
+    greater than `0`. The default is ` ` (space).
+
+    @return string containing the serialization of the JSON value
+
+    @complexity Linear.
+
+    @liveexample{The following example shows the effect of different @a indent
+    parameters to the result of the serialization.,dump}
+
+    @see https://docs.python.org/2/library/json.html#json.dump
+
+    @since version 1.0.0; indentation character added in version 3.0.0
     */
-    constexpr bool is_discarded() const noexcept
+    string_t dump(const int indent = -1, const char indent_char = ' ') const
     {
-        return m_type == value_t::discarded;
+        string_t result;
+        serializer s(output_adapter<char>::create(result), indent_char);
+
+        if (indent >= 0)
+        {
+            s.dump(*this, true, static_cast<unsigned int>(indent));
+        }
+        else
+        {
+            s.dump(*this, false, 0);
+        }
+
+        return result;
     }
 
     /*!
-    @brief return the type of the JSON value (implicit)
+    @brief return the type of the JSON value (explicit)
 
-    Implicitly return the type of the JSON value as a value from the @ref
-    value_t enumeration.
+    Return the type of the JSON value as a value from the @ref value_t
+    enumeration.
 
     @return the type of the JSON value
 
@@ -6124,5167 +6543,4762 @@ class basic_json
     @exceptionsafety No-throw guarantee: this member function never throws
     exceptions.
 
-    @liveexample{The following code exemplifies the @ref value_t operator for
-    all JSON types.,operator__value_t}
+    @liveexample{The following code exemplifies `type()` for all JSON
+    types.,type}
 
     @since version 1.0.0
     */
-    constexpr operator value_t() const noexcept
+    constexpr value_t type() const noexcept
     {
         return m_type;
     }
 
-    /// @}
-
-  private:
-    //////////////////
-    // value access //
-    //////////////////
+    /*!
+    @brief return whether type is primitive
 
-    /// get a boolean (explicit)
-    boolean_t get_impl(boolean_t* /*unused*/) const
-    {
-        if (is_boolean())
-        {
-            return m_value.boolean;
-        }
+    This function returns true iff the JSON type is primitive (string, number,
+    boolean, or null).
 
-        JSON_THROW(type_error::create(302, "type must be boolean, but is " + type_name()));
-    }
+    @return `true` if type is primitive (string, number, boolean, or null),
+    `false` otherwise.
 
-    /// get a pointer to the value (object)
-    object_t* get_impl_ptr(object_t* /*unused*/) noexcept
-    {
-        return is_object() ? m_value.object : nullptr;
-    }
+    @complexity Constant.
 
-    /// get a pointer to the value (object)
-    constexpr const object_t* get_impl_ptr(const object_t* /*unused*/) const noexcept
-    {
-        return is_object() ? m_value.object : nullptr;
-    }
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    /// get a pointer to the value (array)
-    array_t* get_impl_ptr(array_t* /*unused*/) noexcept
-    {
-        return is_array() ? m_value.array : nullptr;
-    }
+    @liveexample{The following code exemplifies `is_primitive()` for all JSON
+    types.,is_primitive}
 
-    /// get a pointer to the value (array)
-    constexpr const array_t* get_impl_ptr(const array_t* /*unused*/) const noexcept
-    {
-        return is_array() ? m_value.array : nullptr;
-    }
+    @sa @ref is_structured() -- returns whether JSON value is structured
+    @sa @ref is_null() -- returns whether JSON value is `null`
+    @sa @ref is_string() -- returns whether JSON value is a string
+    @sa @ref is_boolean() -- returns whether JSON value is a boolean
+    @sa @ref is_number() -- returns whether JSON value is a number
 
-    /// get a pointer to the value (string)
-    string_t* get_impl_ptr(string_t* /*unused*/) noexcept
+    @since version 1.0.0
+    */
+    constexpr bool is_primitive() const noexcept
     {
-        return is_string() ? m_value.string : nullptr;
+        return is_null() or is_string() or is_boolean() or is_number();
     }
 
-    /// get a pointer to the value (string)
-    constexpr const string_t* get_impl_ptr(const string_t* /*unused*/) const noexcept
-    {
-        return is_string() ? m_value.string : nullptr;
-    }
+    /*!
+    @brief return whether type is structured
 
-    /// get a pointer to the value (boolean)
-    boolean_t* get_impl_ptr(boolean_t* /*unused*/) noexcept
-    {
-        return is_boolean() ? &m_value.boolean : nullptr;
-    }
+    This function returns true iff the JSON type is structured (array or
+    object).
 
-    /// get a pointer to the value (boolean)
-    constexpr const boolean_t* get_impl_ptr(const boolean_t* /*unused*/) const noexcept
-    {
-        return is_boolean() ? &m_value.boolean : nullptr;
-    }
+    @return `true` if type is structured (array or object), `false` otherwise.
 
-    /// get a pointer to the value (integer number)
-    number_integer_t* get_impl_ptr(number_integer_t* /*unused*/) noexcept
-    {
-        return is_number_integer() ? &m_value.number_integer : nullptr;
-    }
+    @complexity Constant.
 
-    /// get a pointer to the value (integer number)
-    constexpr const number_integer_t* get_impl_ptr(const number_integer_t* /*unused*/) const noexcept
-    {
-        return is_number_integer() ? &m_value.number_integer : nullptr;
-    }
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    /// get a pointer to the value (unsigned number)
-    number_unsigned_t* get_impl_ptr(number_unsigned_t* /*unused*/) noexcept
-    {
-        return is_number_unsigned() ? &m_value.number_unsigned : nullptr;
-    }
+    @liveexample{The following code exemplifies `is_structured()` for all JSON
+    types.,is_structured}
 
-    /// get a pointer to the value (unsigned number)
-    constexpr const number_unsigned_t* get_impl_ptr(const number_unsigned_t* /*unused*/) const noexcept
-    {
-        return is_number_unsigned() ? &m_value.number_unsigned : nullptr;
-    }
+    @sa @ref is_primitive() -- returns whether value is primitive
+    @sa @ref is_array() -- returns whether value is an array
+    @sa @ref is_object() -- returns whether value is an object
 
-    /// get a pointer to the value (floating-point number)
-    number_float_t* get_impl_ptr(number_float_t* /*unused*/) noexcept
+    @since version 1.0.0
+    */
+    constexpr bool is_structured() const noexcept
     {
-        return is_number_float() ? &m_value.number_float : nullptr;
-    }
-
-    /// get a pointer to the value (floating-point number)
-    constexpr const number_float_t* get_impl_ptr(const number_float_t* /*unused*/) const noexcept
-    {
-        return is_number_float() ? &m_value.number_float : nullptr;
+        return is_array() or is_object();
     }
 
     /*!
-    @brief helper function to implement get_ref()
+    @brief return whether value is null
 
-    This function helps to implement get_ref() without code duplication for
-    const and non-const overloads
+    This function returns true iff the JSON value is null.
 
-    @tparam ThisType will be deduced as `basic_json` or `const basic_json`
+    @return `true` if type is null, `false` otherwise.
 
-    @throw type_error.303 if ReferenceType does not match underlying value
-    type of the current JSON
-    */
-    template<typename ReferenceType, typename ThisType>
-    static ReferenceType get_ref_impl(ThisType& obj)
-    {
-        // helper type
-        using PointerType = typename std::add_pointer<ReferenceType>::type;
+    @complexity Constant.
 
-        // delegate the call to get_ptr<>()
-        auto ptr = obj.template get_ptr<PointerType>();
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-        if (ptr != nullptr)
-        {
-            return *ptr;
-        }
+    @liveexample{The following code exemplifies `is_null()` for all JSON
+    types.,is_null}
 
-        JSON_THROW(type_error::create(303, "incompatible ReferenceType for get_ref, actual type is " + obj.type_name()));
+    @since version 1.0.0
+    */
+    constexpr bool is_null() const noexcept
+    {
+        return m_type == value_t::null;
     }
 
-  public:
-    /// @name value access
-    /// Direct access to the stored value of a JSON value.
-    /// @{
-
     /*!
-    @brief get special-case overload
-
-    This overloads avoids a lot of template boilerplate, it can be seen as the
-    identity method
+    @brief return whether value is a boolean
 
-    @tparam BasicJsonType == @ref basic_json
+    This function returns true iff the JSON value is a boolean.
 
-    @return a copy of *this
+    @return `true` if type is boolean, `false` otherwise.
 
     @complexity Constant.
 
-    @since version 2.1.0
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
+
+    @liveexample{The following code exemplifies `is_boolean()` for all JSON
+    types.,is_boolean}
+
+    @since version 1.0.0
     */
-    template <
-        typename BasicJsonType,
-        detail::enable_if_t<std::is_same<typename std::remove_const<BasicJsonType>::type,
-                                         basic_json_t>::value,
-                            int> = 0 >
-    basic_json get() const
+    constexpr bool is_boolean() const noexcept
     {
-        return *this;
+        return m_type == value_t::boolean;
     }
 
     /*!
-    @brief get a value (explicit)
-
-    Explicit type conversion between the JSON value and a compatible value
-    which is [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible)
-    and [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible).
-    The value is converted by calling the @ref json_serializer<ValueType>
-    `from_json()` method.
+    @brief return whether value is a number
 
-    The function is equivalent to executing
-    @code {.cpp}
-    ValueType ret;
-    JSONSerializer<ValueType>::from_json(*this, ret);
-    return ret;
-    @endcode
+    This function returns true iff the JSON value is a number. This includes
+    both integer and floating-point values.
 
-    This overloads is chosen if:
-    - @a ValueType is not @ref basic_json,
-    - @ref json_serializer<ValueType> has a `from_json()` method of the form
-      `void from_json(const basic_json&, ValueType&)`, and
-    - @ref json_serializer<ValueType> does not have a `from_json()` method of
-      the form `ValueType from_json(const basic_json&)`
+    @return `true` if type is number (regardless whether integer, unsigned
+    integer or floating-type), `false` otherwise.
 
-    @tparam ValueTypeCV the provided value type
-    @tparam ValueType the returned value type
+    @complexity Constant.
 
-    @return copy of the JSON value, converted to @a ValueType
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @throw what @ref json_serializer<ValueType> `from_json()` method throws
+    @liveexample{The following code exemplifies `is_number()` for all JSON
+    types.,is_number}
 
-    @liveexample{The example below shows several conversions from JSON values
-    to other types. There a few things to note: (1) Floating-point numbers can
-    be converted to integers\, (2) A JSON array can be converted to a standard
-    `std::vector<short>`\, (3) A JSON object can be converted to C++
-    associative containers such as `std::unordered_map<std::string\,
-    json>`.,get__ValueType_const}
+    @sa @ref is_number_integer() -- check if value is an integer or unsigned
+    integer number
+    @sa @ref is_number_unsigned() -- check if value is an unsigned integer
+    number
+    @sa @ref is_number_float() -- check if value is a floating-point number
 
-    @since version 2.1.0
+    @since version 1.0.0
     */
-    template <
-        typename ValueTypeCV,
-        typename ValueType = detail::uncvref_t<ValueTypeCV>,
-        detail::enable_if_t <
-            not std::is_same<basic_json_t, ValueType>::value and
-            detail::has_from_json<basic_json_t, ValueType>::value and
-            not detail::has_non_default_from_json<basic_json_t, ValueType>::value,
-            int > = 0 >
-    ValueType get() const noexcept(noexcept(
-                                       JSONSerializer<ValueType>::from_json(std::declval<const basic_json_t&>(), std::declval<ValueType&>())))
+    constexpr bool is_number() const noexcept
     {
-        // we cannot static_assert on ValueTypeCV being non-const, because
-        // there is support for get<const basic_json_t>(), which is why we
-        // still need the uncvref
-        static_assert(not std::is_reference<ValueTypeCV>::value,
-                      "get() cannot be used with reference types, you might want to use get_ref()");
-        static_assert(std::is_default_constructible<ValueType>::value,
-                      "types must be DefaultConstructible when used with get()");
-
-        ValueType ret;
-        JSONSerializer<ValueType>::from_json(*this, ret);
-        return ret;
+        return is_number_integer() or is_number_float();
     }
 
     /*!
-    @brief get a value (explicit); special case
-
-    Explicit type conversion between the JSON value and a compatible value
-    which is **not** [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible)
-    and **not** [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible).
-    The value is converted by calling the @ref json_serializer<ValueType>
-    `from_json()` method.
+    @brief return whether value is an integer number
 
-    The function is equivalent to executing
-    @code {.cpp}
-    return JSONSerializer<ValueTypeCV>::from_json(*this);
-    @endcode
+    This function returns true iff the JSON value is an integer or unsigned
+    integer number. This excludes floating-point values.
 
-    This overloads is chosen if:
-    - @a ValueType is not @ref basic_json and
-    - @ref json_serializer<ValueType> has a `from_json()` method of the form
-      `ValueType from_json(const basic_json&)`
+    @return `true` if type is an integer or unsigned integer number, `false`
+    otherwise.
 
-    @note If @ref json_serializer<ValueType> has both overloads of
-    `from_json()`, this one is chosen.
+    @complexity Constant.
 
-    @tparam ValueTypeCV the provided value type
-    @tparam ValueType the returned value type
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @return copy of the JSON value, converted to @a ValueType
+    @liveexample{The following code exemplifies `is_number_integer()` for all
+    JSON types.,is_number_integer}
 
-    @throw what @ref json_serializer<ValueType> `from_json()` method throws
+    @sa @ref is_number() -- check if value is a number
+    @sa @ref is_number_unsigned() -- check if value is an unsigned integer
+    number
+    @sa @ref is_number_float() -- check if value is a floating-point number
 
-    @since version 2.1.0
+    @since version 1.0.0
     */
-    template <
-        typename ValueTypeCV,
-        typename ValueType = detail::uncvref_t<ValueTypeCV>,
-        detail::enable_if_t<not std::is_same<basic_json_t, ValueType>::value and
-                            detail::has_non_default_from_json<basic_json_t,
-                                    ValueType>::value, int> = 0 >
-    ValueType get() const noexcept(noexcept(
-                                       JSONSerializer<ValueTypeCV>::from_json(std::declval<const basic_json_t&>())))
+    constexpr bool is_number_integer() const noexcept
     {
-        static_assert(not std::is_reference<ValueTypeCV>::value,
-                      "get() cannot be used with reference types, you might want to use get_ref()");
-        return JSONSerializer<ValueTypeCV>::from_json(*this);
+        return m_type == value_t::number_integer or m_type == value_t::number_unsigned;
     }
 
     /*!
-    @brief get a pointer value (explicit)
-
-    Explicit pointer access to the internally stored JSON value. No copies are
-    made.
-
-    @warning The pointer becomes invalid if the underlying JSON object
-    changes.
+    @brief return whether value is an unsigned integer number
 
-    @tparam PointerType pointer type; must be a pointer to @ref array_t, @ref
-    object_t, @ref string_t, @ref boolean_t, @ref number_integer_t,
-    @ref number_unsigned_t, or @ref number_float_t.
+    This function returns true iff the JSON value is an unsigned integer
+    number. This excludes floating-point and (signed) integer values.
 
-    @return pointer to the internally stored JSON value if the requested
-    pointer type @a PointerType fits to the JSON value; `nullptr` otherwise
+    @return `true` if type is an unsigned integer number, `false` otherwise.
 
     @complexity Constant.
 
-    @liveexample{The example below shows how pointers to internal values of a
-    JSON value can be requested. Note that no type conversions are made and a
-    `nullptr` is returned if the value and the requested pointer type does not
-    match.,get__PointerType}
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @sa @ref get_ptr() for explicit pointer-member access
+    @liveexample{The following code exemplifies `is_number_unsigned()` for all
+    JSON types.,is_number_unsigned}
 
-    @since version 1.0.0
-    */
-    template<typename PointerType, typename std::enable_if<
-                 std::is_pointer<PointerType>::value, int>::type = 0>
-    PointerType get() noexcept
-    {
-        // delegate the call to get_ptr
-        return get_ptr<PointerType>();
-    }
+    @sa @ref is_number() -- check if value is a number
+    @sa @ref is_number_integer() -- check if value is an integer or unsigned
+    integer number
+    @sa @ref is_number_float() -- check if value is a floating-point number
 
-    /*!
-    @brief get a pointer value (explicit)
-    @copydoc get()
+    @since version 2.0.0
     */
-    template<typename PointerType, typename std::enable_if<
-                 std::is_pointer<PointerType>::value, int>::type = 0>
-    constexpr const PointerType get() const noexcept
+    constexpr bool is_number_unsigned() const noexcept
     {
-        // delegate the call to get_ptr
-        return get_ptr<PointerType>();
+        return m_type == value_t::number_unsigned;
     }
 
     /*!
-    @brief get a pointer value (implicit)
-
-    Implicit pointer access to the internally stored JSON value. No copies are
-    made.
-
-    @warning Writing data to the pointee of the result yields an undefined
-    state.
+    @brief return whether value is a floating-point number
 
-    @tparam PointerType pointer type; must be a pointer to @ref array_t, @ref
-    object_t, @ref string_t, @ref boolean_t, @ref number_integer_t,
-    @ref number_unsigned_t, or @ref number_float_t. Enforced by a static
-    assertion.
+    This function returns true iff the JSON value is a floating-point number.
+    This excludes integer and unsigned integer values.
 
-    @return pointer to the internally stored JSON value if the requested
-    pointer type @a PointerType fits to the JSON value; `nullptr` otherwise
+    @return `true` if type is a floating-point number, `false` otherwise.
 
     @complexity Constant.
 
-    @liveexample{The example below shows how pointers to internal values of a
-    JSON value can be requested. Note that no type conversions are made and a
-    `nullptr` is returned if the value and the requested pointer type does not
-    match.,get_ptr}
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @since version 1.0.0
-    */
-    template<typename PointerType, typename std::enable_if<
-                 std::is_pointer<PointerType>::value, int>::type = 0>
-    PointerType get_ptr() noexcept
-    {
-        // get the type of the PointerType (remove pointer and const)
-        using pointee_t = typename std::remove_const<typename
-                          std::remove_pointer<typename
-                          std::remove_const<PointerType>::type>::type>::type;
-        // make sure the type matches the allowed types
-        static_assert(
-            std::is_same<object_t, pointee_t>::value
-            or std::is_same<array_t, pointee_t>::value
-            or std::is_same<string_t, pointee_t>::value
-            or std::is_same<boolean_t, pointee_t>::value
-            or std::is_same<number_integer_t, pointee_t>::value
-            or std::is_same<number_unsigned_t, pointee_t>::value
-            or std::is_same<number_float_t, pointee_t>::value
-            , "incompatible pointer type");
+    @liveexample{The following code exemplifies `is_number_float()` for all
+    JSON types.,is_number_float}
 
-        // delegate the call to get_impl_ptr<>()
-        return get_impl_ptr(static_cast<PointerType>(nullptr));
-    }
+    @sa @ref is_number() -- check if value is number
+    @sa @ref is_number_integer() -- check if value is an integer number
+    @sa @ref is_number_unsigned() -- check if value is an unsigned integer
+    number
 
-    /*!
-    @brief get a pointer value (implicit)
-    @copydoc get_ptr()
+    @since version 1.0.0
     */
-    template<typename PointerType, typename std::enable_if<
-                 std::is_pointer<PointerType>::value and
-                 std::is_const<typename std::remove_pointer<PointerType>::type>::value, int>::type = 0>
-    constexpr const PointerType get_ptr() const noexcept
+    constexpr bool is_number_float() const noexcept
     {
-        // get the type of the PointerType (remove pointer and const)
-        using pointee_t = typename std::remove_const<typename
-                          std::remove_pointer<typename
-                          std::remove_const<PointerType>::type>::type>::type;
-        // make sure the type matches the allowed types
-        static_assert(
-            std::is_same<object_t, pointee_t>::value
-            or std::is_same<array_t, pointee_t>::value
-            or std::is_same<string_t, pointee_t>::value
-            or std::is_same<boolean_t, pointee_t>::value
-            or std::is_same<number_integer_t, pointee_t>::value
-            or std::is_same<number_unsigned_t, pointee_t>::value
-            or std::is_same<number_float_t, pointee_t>::value
-            , "incompatible pointer type");
-
-        // delegate the call to get_impl_ptr<>() const
-        return get_impl_ptr(static_cast<const PointerType>(nullptr));
+        return m_type == value_t::number_float;
     }
 
     /*!
-    @brief get a reference value (implicit)
-
-    Implicit reference access to the internally stored JSON value. No copies
-    are made.
-
-    @warning Writing data to the referee of the result yields an undefined
-    state.
-
-    @tparam ReferenceType reference type; must be a reference to @ref array_t,
-    @ref object_t, @ref string_t, @ref boolean_t, @ref number_integer_t, or
-    @ref number_float_t. Enforced by static assertion.
+    @brief return whether value is an object
 
-    @return reference to the internally stored JSON value if the requested
-    reference type @a ReferenceType fits to the JSON value; throws
-    type_error.303 otherwise
+    This function returns true iff the JSON value is an object.
 
-    @throw type_error.303 in case passed type @a ReferenceType is incompatible
-    with the stored JSON value; see example below
+    @return `true` if type is object, `false` otherwise.
 
     @complexity Constant.
 
-    @liveexample{The example shows several calls to `get_ref()`.,get_ref}
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @since version 1.1.0
-    */
-    template<typename ReferenceType, typename std::enable_if<
-                 std::is_reference<ReferenceType>::value, int>::type = 0>
-    ReferenceType get_ref()
-    {
-        // delegate call to get_ref_impl
-        return get_ref_impl<ReferenceType>(*this);
-    }
+    @liveexample{The following code exemplifies `is_object()` for all JSON
+    types.,is_object}
 
-    /*!
-    @brief get a reference value (implicit)
-    @copydoc get_ref()
+    @since version 1.0.0
     */
-    template<typename ReferenceType, typename std::enable_if<
-                 std::is_reference<ReferenceType>::value and
-                 std::is_const<typename std::remove_reference<ReferenceType>::type>::value, int>::type = 0>
-    ReferenceType get_ref() const
+    constexpr bool is_object() const noexcept
     {
-        // delegate call to get_ref_impl
-        return get_ref_impl<ReferenceType>(*this);
+        return m_type == value_t::object;
     }
 
     /*!
-    @brief get a value (implicit)
-
-    Implicit type conversion between the JSON value and a compatible value.
-    The call is realized by calling @ref get() const.
+    @brief return whether value is an array
 
-    @tparam ValueType non-pointer type compatible to the JSON value, for
-    instance `int` for JSON integer numbers, `bool` for JSON booleans, or
-    `std::vector` types for JSON arrays. The character type of @ref string_t
-    as well as an initializer list of this type is excluded to avoid
-    ambiguities as these types implicitly convert to `std::string`.
+    This function returns true iff the JSON value is an array.
 
-    @return copy of the JSON value, converted to type @a ValueType
+    @return `true` if type is array, `false` otherwise.
 
-    @throw type_error.302 in case passed type @a ValueType is incompatible
-    to the JSON value type (e.g., the JSON value is of type boolean, but a
-    string is requested); see example below
+    @complexity Constant.
 
-    @complexity Linear in the size of the JSON value.
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @liveexample{The example below shows several conversions from JSON values
-    to other types. There a few things to note: (1) Floating-point numbers can
-    be converted to integers\, (2) A JSON array can be converted to a standard
-    `std::vector<short>`\, (3) A JSON object can be converted to C++
-    associative containers such as `std::unordered_map<std::string\,
-    json>`.,operator__ValueType}
+    @liveexample{The following code exemplifies `is_array()` for all JSON
+    types.,is_array}
 
     @since version 1.0.0
     */
-    template < typename ValueType, typename std::enable_if <
-                   not std::is_pointer<ValueType>::value and
-                   not std::is_same<ValueType, typename string_t::value_type>::value
-#ifndef _MSC_VER  // fix for issue #167 operator<< ambiguity under VS2015
-                   and not std::is_same<ValueType, std::initializer_list<typename string_t::value_type>>::value
-#endif
-#if (defined(__cplusplus) && __cplusplus >= 201703L) || (defined(_MSC_VER) && _MSC_VER >1900 && defined(_HAS_CXX17) && _HAS_CXX17 == 1) // fix for issue #464
-                   and not std::is_same<ValueType, typename std::string_view>::value
-#endif
-                   , int >::type = 0 >
-    operator ValueType() const
+    constexpr bool is_array() const noexcept
     {
-        // delegate the call to get<>() const
-        return get<ValueType>();
+        return m_type == value_t::array;
     }
 
-    /// @}
-
-
-    ////////////////////
-    // element access //
-    ////////////////////
-
-    /// @name element access
-    /// Access to the JSON value.
-    /// @{
-
     /*!
-    @brief access specified array element with bounds checking
-
-    Returns a reference to the element at specified location @a idx, with
-    bounds checking.
+    @brief return whether value is a string
 
-    @param[in] idx  index of the element to access
+    This function returns true iff the JSON value is a string.
 
-    @return reference to the element at index @a idx
+    @return `true` if type is string, `false` otherwise.
 
-    @throw type_error.304 if the JSON value is not an array; in this case,
-    calling `at` with an index makes no sense. See example below.
-    @throw out_of_range.401 if the index @a idx is out of range of the array;
-    that is, `idx >= size()`. See example below.
+    @complexity Constant.
 
-    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
-    changes in the JSON value.
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @complexity Constant.
+    @liveexample{The following code exemplifies `is_string()` for all JSON
+    types.,is_string}
 
     @since version 1.0.0
-
-    @liveexample{The example below shows how array elements can be read and
-    written using `at()`. It also demonstrates the different exceptions that
-    can be thrown.,at__size_type}
     */
-    reference at(size_type idx)
+    constexpr bool is_string() const noexcept
     {
-        // at only works for arrays
-        if (is_array())
-        {
-            JSON_TRY
-            {
-                return m_value.array->at(idx);
-            }
-            JSON_CATCH (std::out_of_range&)
-            {
-                // create better exception explanation
-                JSON_THROW(out_of_range::create(401, "array index " + std::to_string(idx) + " is out of range"));
-            }
-        }
-        else
-        {
-            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
-        }
+        return m_type == value_t::string;
     }
 
     /*!
-    @brief access specified array element with bounds checking
+    @brief return whether value is discarded
 
-    Returns a const reference to the element at specified location @a idx,
-    with bounds checking.
+    This function returns true iff the JSON value was discarded during parsing
+    with a callback function (see @ref parser_callback_t).
 
-    @param[in] idx  index of the element to access
+    @note This function will always be `false` for JSON values after parsing.
+    That is, discarded values can only occur during parsing, but will be
+    removed when inside a structured value or replaced by null in other cases.
 
-    @return const reference to the element at index @a idx
+    @return `true` if type is discarded, `false` otherwise.
 
-    @throw type_error.304 if the JSON value is not an array; in this case,
-    calling `at` with an index makes no sense. See example below.
-    @throw out_of_range.401 if the index @a idx is out of range of the array;
-    that is, `idx >= size()`. See example below.
+    @complexity Constant.
 
-    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
-    changes in the JSON value.
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @complexity Constant.
+    @liveexample{The following code exemplifies `is_discarded()` for all JSON
+    types.,is_discarded}
 
     @since version 1.0.0
-
-    @liveexample{The example below shows how array elements can be read using
-    `at()`. It also demonstrates the different exceptions that can be thrown.,
-    at__size_type_const}
     */
-    const_reference at(size_type idx) const
+    constexpr bool is_discarded() const noexcept
     {
-        // at only works for arrays
-        if (is_array())
-        {
-            JSON_TRY
-            {
-                return m_value.array->at(idx);
-            }
-            JSON_CATCH (std::out_of_range&)
-            {
-                // create better exception explanation
-                JSON_THROW(out_of_range::create(401, "array index " + std::to_string(idx) + " is out of range"));
-            }
-        }
-        else
-        {
-            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
-        }
+        return m_type == value_t::discarded;
     }
 
     /*!
-    @brief access specified object element with bounds checking
+    @brief return the type of the JSON value (implicit)
 
-    Returns a reference to the element at with specified key @a key, with
-    bounds checking.
+    Implicitly return the type of the JSON value as a value from the @ref
+    value_t enumeration.
 
-    @param[in] key  key of the element to access
+    @return the type of the JSON value
 
-    @return reference to the element at key @a key
+    @complexity Constant.
 
-    @throw type_error.304 if the JSON value is not an object; in this case,
-    calling `at` with a key makes no sense. See example below.
-    @throw out_of_range.403 if the key @a key is is not stored in the object;
-    that is, `find(key) == end()`. See example below.
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
-    changes in the JSON value.
+    @liveexample{The following code exemplifies the @ref value_t operator for
+    all JSON types.,operator__value_t}
 
-    @complexity Logarithmic in the size of the container.
+    @since version 1.0.0
+    */
+    constexpr operator value_t() const noexcept
+    {
+        return m_type;
+    }
 
-    @sa @ref operator[](const typename object_t::key_type&) for unchecked
-    access by reference
-    @sa @ref value() for access by value with a default value
+    /// @}
 
-    @since version 1.0.0
+  private:
+    //////////////////
+    // value access //
+    //////////////////
 
-    @liveexample{The example below shows how object elements can be read and
-    written using `at()`. It also demonstrates the different exceptions that
-    can be thrown.,at__object_t_key_type}
-    */
-    reference at(const typename object_t::key_type& key)
+    /// get a boolean (explicit)
+    boolean_t get_impl(boolean_t* /*unused*/) const
     {
-        // at only works for objects
-        if (is_object())
-        {
-            JSON_TRY
-            {
-                return m_value.object->at(key);
-            }
-            JSON_CATCH (std::out_of_range&)
-            {
-                // create better exception explanation
-                JSON_THROW(out_of_range::create(403, "key '" + key + "' not found"));
-            }
-        }
-        else
+        if (is_boolean())
         {
-            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
+            return m_value.boolean;
         }
-    }
 
-    /*!
-    @brief access specified object element with bounds checking
+        JSON_THROW(type_error::create(302, "type must be boolean, but is " + type_name()));
+    }
 
-    Returns a const reference to the element at with specified key @a key,
-    with bounds checking.
+    /// get a pointer to the value (object)
+    object_t* get_impl_ptr(object_t* /*unused*/) noexcept
+    {
+        return is_object() ? m_value.object : nullptr;
+    }
 
-    @param[in] key  key of the element to access
+    /// get a pointer to the value (object)
+    constexpr const object_t* get_impl_ptr(const object_t* /*unused*/) const noexcept
+    {
+        return is_object() ? m_value.object : nullptr;
+    }
 
-    @return const reference to the element at key @a key
+    /// get a pointer to the value (array)
+    array_t* get_impl_ptr(array_t* /*unused*/) noexcept
+    {
+        return is_array() ? m_value.array : nullptr;
+    }
 
-    @throw type_error.304 if the JSON value is not an object; in this case,
-    calling `at` with a key makes no sense. See example below.
-    @throw out_of_range.403 if the key @a key is is not stored in the object;
-    that is, `find(key) == end()`. See example below.
+    /// get a pointer to the value (array)
+    constexpr const array_t* get_impl_ptr(const array_t* /*unused*/) const noexcept
+    {
+        return is_array() ? m_value.array : nullptr;
+    }
 
-    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
-    changes in the JSON value.
+    /// get a pointer to the value (string)
+    string_t* get_impl_ptr(string_t* /*unused*/) noexcept
+    {
+        return is_string() ? m_value.string : nullptr;
+    }
 
-    @complexity Logarithmic in the size of the container.
+    /// get a pointer to the value (string)
+    constexpr const string_t* get_impl_ptr(const string_t* /*unused*/) const noexcept
+    {
+        return is_string() ? m_value.string : nullptr;
+    }
 
-    @sa @ref operator[](const typename object_t::key_type&) for unchecked
-    access by reference
-    @sa @ref value() for access by value with a default value
+    /// get a pointer to the value (boolean)
+    boolean_t* get_impl_ptr(boolean_t* /*unused*/) noexcept
+    {
+        return is_boolean() ? &m_value.boolean : nullptr;
+    }
 
-    @since version 1.0.0
+    /// get a pointer to the value (boolean)
+    constexpr const boolean_t* get_impl_ptr(const boolean_t* /*unused*/) const noexcept
+    {
+        return is_boolean() ? &m_value.boolean : nullptr;
+    }
 
-    @liveexample{The example below shows how object elements can be read using
-    `at()`. It also demonstrates the different exceptions that can be thrown.,
-    at__object_t_key_type_const}
-    */
-    const_reference at(const typename object_t::key_type& key) const
+    /// get a pointer to the value (integer number)
+    number_integer_t* get_impl_ptr(number_integer_t* /*unused*/) noexcept
     {
-        // at only works for objects
-        if (is_object())
-        {
-            JSON_TRY
-            {
-                return m_value.object->at(key);
-            }
-            JSON_CATCH (std::out_of_range&)
-            {
-                // create better exception explanation
-                JSON_THROW(out_of_range::create(403, "key '" + key + "' not found"));
-            }
-        }
-        else
-        {
-            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
-        }
+        return is_number_integer() ? &m_value.number_integer : nullptr;
     }
 
-    /*!
-    @brief access specified array element
+    /// get a pointer to the value (integer number)
+    constexpr const number_integer_t* get_impl_ptr(const number_integer_t* /*unused*/) const noexcept
+    {
+        return is_number_integer() ? &m_value.number_integer : nullptr;
+    }
 
-    Returns a reference to the element at specified location @a idx.
+    /// get a pointer to the value (unsigned number)
+    number_unsigned_t* get_impl_ptr(number_unsigned_t* /*unused*/) noexcept
+    {
+        return is_number_unsigned() ? &m_value.number_unsigned : nullptr;
+    }
 
-    @note If @a idx is beyond the range of the array (i.e., `idx >= size()`),
-    then the array is silently filled up with `null` values to make `idx` a
-    valid reference to the last stored element.
+    /// get a pointer to the value (unsigned number)
+    constexpr const number_unsigned_t* get_impl_ptr(const number_unsigned_t* /*unused*/) const noexcept
+    {
+        return is_number_unsigned() ? &m_value.number_unsigned : nullptr;
+    }
 
-    @param[in] idx  index of the element to access
+    /// get a pointer to the value (floating-point number)
+    number_float_t* get_impl_ptr(number_float_t* /*unused*/) noexcept
+    {
+        return is_number_float() ? &m_value.number_float : nullptr;
+    }
 
-    @return reference to the element at index @a idx
+    /// get a pointer to the value (floating-point number)
+    constexpr const number_float_t* get_impl_ptr(const number_float_t* /*unused*/) const noexcept
+    {
+        return is_number_float() ? &m_value.number_float : nullptr;
+    }
 
-    @throw type_error.305 if the JSON value is not an array or null; in that
-    cases, using the [] operator with an index makes no sense.
+    /*!
+    @brief helper function to implement get_ref()
 
-    @complexity Constant if @a idx is in the range of the array. Otherwise
-    linear in `idx - size()`.
+    This function helps to implement get_ref() without code duplication for
+    const and non-const overloads
 
-    @liveexample{The example below shows how array elements can be read and
-    written using `[]` operator. Note the addition of `null`
-    values.,operatorarray__size_type}
+    @tparam ThisType will be deduced as `basic_json` or `const basic_json`
 
-    @since version 1.0.0
+    @throw type_error.303 if ReferenceType does not match underlying value
+    type of the current JSON
     */
-    reference operator[](size_type idx)
+    template<typename ReferenceType, typename ThisType>
+    static ReferenceType get_ref_impl(ThisType& obj)
     {
-        // implicitly convert null value to an empty array
-        if (is_null())
-        {
-            m_type = value_t::array;
-            m_value.array = create<array_t>();
-            assert_invariant();
-        }
+        // helper type
+        using PointerType = typename std::add_pointer<ReferenceType>::type;
 
-        // operator[] only works for arrays
-        if (is_array())
-        {
-            // fill up array with null values if given idx is outside range
-            if (idx >= m_value.array->size())
-            {
-                m_value.array->insert(m_value.array->end(),
-                                      idx - m_value.array->size() + 1,
-                                      basic_json());
-            }
+        // delegate the call to get_ptr<>()
+        auto ptr = obj.template get_ptr<PointerType>();
 
-            return m_value.array->operator[](idx);
+        if (ptr != nullptr)
+        {
+            return *ptr;
         }
 
-        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+        JSON_THROW(type_error::create(303, "incompatible ReferenceType for get_ref, actual type is " + obj.type_name()));
     }
 
-    /*!
-    @brief access specified array element
+  public:
+    /// @name value access
+    /// Direct access to the stored value of a JSON value.
+    /// @{
 
-    Returns a const reference to the element at specified location @a idx.
+    /*!
+    @brief get special-case overload
 
-    @param[in] idx  index of the element to access
+    This overloads avoids a lot of template boilerplate, it can be seen as the
+    identity method
 
-    @return const reference to the element at index @a idx
+    @tparam BasicJsonType == @ref basic_json
 
-    @throw type_error.305 if the JSON value is not an array; in that cases,
-    using the [] operator with an index makes no sense.
+    @return a copy of *this
 
     @complexity Constant.
 
-    @liveexample{The example below shows how array elements can be read using
-    the `[]` operator.,operatorarray__size_type_const}
-
-    @since version 1.0.0
+    @since version 2.1.0
     */
-    const_reference operator[](size_type idx) const
+    template <
+        typename BasicJsonType,
+        detail::enable_if_t<std::is_same<typename std::remove_const<BasicJsonType>::type,
+                                         basic_json_t>::value,
+                            int> = 0 >
+    basic_json get() const
     {
-        // const operator[] only works for arrays
-        if (is_array())
-        {
-            return m_value.array->operator[](idx);
-        }
-
-        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+        return *this;
     }
 
     /*!
-    @brief access specified object element
-
-    Returns a reference to the element at with specified key @a key.
+    @brief get a value (explicit)
 
-    @note If @a key is not found in the object, then it is silently added to
-    the object and filled with a `null` value to make `key` a valid reference.
-    In case the value was `null` before, it is converted to an object.
+    Explicit type conversion between the JSON value and a compatible value
+    which is [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible)
+    and [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible).
+    The value is converted by calling the @ref json_serializer<ValueType>
+    `from_json()` method.
 
-    @param[in] key  key of the element to access
+    The function is equivalent to executing
+    @code {.cpp}
+    ValueType ret;
+    JSONSerializer<ValueType>::from_json(*this, ret);
+    return ret;
+    @endcode
 
-    @return reference to the element at key @a key
+    This overloads is chosen if:
+    - @a ValueType is not @ref basic_json,
+    - @ref json_serializer<ValueType> has a `from_json()` method of the form
+      `void from_json(const basic_json&, ValueType&)`, and
+    - @ref json_serializer<ValueType> does not have a `from_json()` method of
+      the form `ValueType from_json(const basic_json&)`
 
-    @throw type_error.305 if the JSON value is not an object or null; in that
-    cases, using the [] operator with a key makes no sense.
+    @tparam ValueTypeCV the provided value type
+    @tparam ValueType the returned value type
 
-    @complexity Logarithmic in the size of the container.
+    @return copy of the JSON value, converted to @a ValueType
 
-    @liveexample{The example below shows how object elements can be read and
-    written using the `[]` operator.,operatorarray__key_type}
+    @throw what @ref json_serializer<ValueType> `from_json()` method throws
 
-    @sa @ref at(const typename object_t::key_type&) for access by reference
-    with range checking
-    @sa @ref value() for access by value with a default value
+    @liveexample{The example below shows several conversions from JSON values
+    to other types. There a few things to note: (1) Floating-point numbers can
+    be converted to integers\, (2) A JSON array can be converted to a standard
+    `std::vector<short>`\, (3) A JSON object can be converted to C++
+    associative containers such as `std::unordered_map<std::string\,
+    json>`.,get__ValueType_const}
 
-    @since version 1.0.0
+    @since version 2.1.0
     */
-    reference operator[](const typename object_t::key_type& key)
+    template <
+        typename ValueTypeCV,
+        typename ValueType = detail::uncvref_t<ValueTypeCV>,
+        detail::enable_if_t <
+            not std::is_same<basic_json_t, ValueType>::value and
+            detail::has_from_json<basic_json_t, ValueType>::value and
+            not detail::has_non_default_from_json<basic_json_t, ValueType>::value,
+            int > = 0 >
+    ValueType get() const noexcept(noexcept(
+                                       JSONSerializer<ValueType>::from_json(std::declval<const basic_json_t&>(), std::declval<ValueType&>())))
     {
-        // implicitly convert null value to an empty object
-        if (is_null())
-        {
-            m_type = value_t::object;
-            m_value.object = create<object_t>();
-            assert_invariant();
-        }
-
-        // operator[] only works for objects
-        if (is_object())
-        {
-            return m_value.object->operator[](key);
-        }
+        // we cannot static_assert on ValueTypeCV being non-const, because
+        // there is support for get<const basic_json_t>(), which is why we
+        // still need the uncvref
+        static_assert(not std::is_reference<ValueTypeCV>::value,
+                      "get() cannot be used with reference types, you might want to use get_ref()");
+        static_assert(std::is_default_constructible<ValueType>::value,
+                      "types must be DefaultConstructible when used with get()");
 
-        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+        ValueType ret;
+        JSONSerializer<ValueType>::from_json(*this, ret);
+        return ret;
     }
 
     /*!
-    @brief read-only access specified object element
-
-    Returns a const reference to the element at with specified key @a key. No
-    bounds checking is performed.
-
-    @warning If the element with key @a key does not exist, the behavior is
-    undefined.
+    @brief get a value (explicit); special case
 
-    @param[in] key  key of the element to access
+    Explicit type conversion between the JSON value and a compatible value
+    which is **not** [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible)
+    and **not** [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible).
+    The value is converted by calling the @ref json_serializer<ValueType>
+    `from_json()` method.
 
-    @return const reference to the element at key @a key
+    The function is equivalent to executing
+    @code {.cpp}
+    return JSONSerializer<ValueTypeCV>::from_json(*this);
+    @endcode
 
-    @pre The element with key @a key must exist. **This precondition is
-         enforced with an assertion.**
+    This overloads is chosen if:
+    - @a ValueType is not @ref basic_json and
+    - @ref json_serializer<ValueType> has a `from_json()` method of the form
+      `ValueType from_json(const basic_json&)`
 
-    @throw type_error.305 if the JSON value is not an object; in that cases,
-    using the [] operator with a key makes no sense.
+    @note If @ref json_serializer<ValueType> has both overloads of
+    `from_json()`, this one is chosen.
 
-    @complexity Logarithmic in the size of the container.
+    @tparam ValueTypeCV the provided value type
+    @tparam ValueType the returned value type
 
-    @liveexample{The example below shows how object elements can be read using
-    the `[]` operator.,operatorarray__key_type_const}
+    @return copy of the JSON value, converted to @a ValueType
 
-    @sa @ref at(const typename object_t::key_type&) for access by reference
-    with range checking
-    @sa @ref value() for access by value with a default value
+    @throw what @ref json_serializer<ValueType> `from_json()` method throws
 
-    @since version 1.0.0
+    @since version 2.1.0
     */
-    const_reference operator[](const typename object_t::key_type& key) const
+    template <
+        typename ValueTypeCV,
+        typename ValueType = detail::uncvref_t<ValueTypeCV>,
+        detail::enable_if_t<not std::is_same<basic_json_t, ValueType>::value and
+                            detail::has_non_default_from_json<basic_json_t,
+                                    ValueType>::value, int> = 0 >
+    ValueType get() const noexcept(noexcept(
+                                       JSONSerializer<ValueTypeCV>::from_json(std::declval<const basic_json_t&>())))
     {
-        // const operator[] only works for objects
-        if (is_object())
-        {
-            assert(m_value.object->find(key) != m_value.object->end());
-            return m_value.object->find(key)->second;
-        }
-
-        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+        static_assert(not std::is_reference<ValueTypeCV>::value,
+                      "get() cannot be used with reference types, you might want to use get_ref()");
+        return JSONSerializer<ValueTypeCV>::from_json(*this);
     }
 
     /*!
-    @brief access specified object element
-
-    Returns a reference to the element at with specified key @a key.
+    @brief get a pointer value (explicit)
 
-    @note If @a key is not found in the object, then it is silently added to
-    the object and filled with a `null` value to make `key` a valid reference.
-    In case the value was `null` before, it is converted to an object.
+    Explicit pointer access to the internally stored JSON value. No copies are
+    made.
 
-    @param[in] key  key of the element to access
+    @warning The pointer becomes invalid if the underlying JSON object
+    changes.
 
-    @return reference to the element at key @a key
+    @tparam PointerType pointer type; must be a pointer to @ref array_t, @ref
+    object_t, @ref string_t, @ref boolean_t, @ref number_integer_t,
+    @ref number_unsigned_t, or @ref number_float_t.
 
-    @throw type_error.305 if the JSON value is not an object or null; in that
-    cases, using the [] operator with a key makes no sense.
+    @return pointer to the internally stored JSON value if the requested
+    pointer type @a PointerType fits to the JSON value; `nullptr` otherwise
 
-    @complexity Logarithmic in the size of the container.
+    @complexity Constant.
 
-    @liveexample{The example below shows how object elements can be read and
-    written using the `[]` operator.,operatorarray__key_type}
+    @liveexample{The example below shows how pointers to internal values of a
+    JSON value can be requested. Note that no type conversions are made and a
+    `nullptr` is returned if the value and the requested pointer type does not
+    match.,get__PointerType}
 
-    @sa @ref at(const typename object_t::key_type&) for access by reference
-    with range checking
-    @sa @ref value() for access by value with a default value
+    @sa @ref get_ptr() for explicit pointer-member access
 
-    @since version 1.1.0
+    @since version 1.0.0
     */
-    template<typename T>
-    reference operator[](T* key)
+    template<typename PointerType, typename std::enable_if<
+                 std::is_pointer<PointerType>::value, int>::type = 0>
+    PointerType get() noexcept
     {
-        // implicitly convert null to object
-        if (is_null())
-        {
-            m_type = value_t::object;
-            m_value = value_t::object;
-            assert_invariant();
-        }
-
-        // at only works for objects
-        if (is_object())
-        {
-            return m_value.object->operator[](key);
-        }
-
-        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+        // delegate the call to get_ptr
+        return get_ptr<PointerType>();
     }
 
     /*!
-    @brief read-only access specified object element
-
-    Returns a const reference to the element at with specified key @a key. No
-    bounds checking is performed.
-
-    @warning If the element with key @a key does not exist, the behavior is
-    undefined.
+    @brief get a pointer value (explicit)
+    @copydoc get()
+    */
+    template<typename PointerType, typename std::enable_if<
+                 std::is_pointer<PointerType>::value, int>::type = 0>
+    constexpr const PointerType get() const noexcept
+    {
+        // delegate the call to get_ptr
+        return get_ptr<PointerType>();
+    }
 
-    @param[in] key  key of the element to access
+    /*!
+    @brief get a pointer value (implicit)
 
-    @return const reference to the element at key @a key
+    Implicit pointer access to the internally stored JSON value. No copies are
+    made.
 
-    @pre The element with key @a key must exist. **This precondition is
-         enforced with an assertion.**
+    @warning Writing data to the pointee of the result yields an undefined
+    state.
 
-    @throw type_error.305 if the JSON value is not an object; in that cases,
-    using the [] operator with a key makes no sense.
+    @tparam PointerType pointer type; must be a pointer to @ref array_t, @ref
+    object_t, @ref string_t, @ref boolean_t, @ref number_integer_t,
+    @ref number_unsigned_t, or @ref number_float_t. Enforced by a static
+    assertion.
 
-    @complexity Logarithmic in the size of the container.
+    @return pointer to the internally stored JSON value if the requested
+    pointer type @a PointerType fits to the JSON value; `nullptr` otherwise
 
-    @liveexample{The example below shows how object elements can be read using
-    the `[]` operator.,operatorarray__key_type_const}
+    @complexity Constant.
 
-    @sa @ref at(const typename object_t::key_type&) for access by reference
-    with range checking
-    @sa @ref value() for access by value with a default value
+    @liveexample{The example below shows how pointers to internal values of a
+    JSON value can be requested. Note that no type conversions are made and a
+    `nullptr` is returned if the value and the requested pointer type does not
+    match.,get_ptr}
 
-    @since version 1.1.0
+    @since version 1.0.0
     */
-    template<typename T>
-    const_reference operator[](T* key) const
+    template<typename PointerType, typename std::enable_if<
+                 std::is_pointer<PointerType>::value, int>::type = 0>
+    PointerType get_ptr() noexcept
     {
-        // at only works for objects
-        if (is_object())
-        {
-            assert(m_value.object->find(key) != m_value.object->end());
-            return m_value.object->find(key)->second;
-        }
+        // get the type of the PointerType (remove pointer and const)
+        using pointee_t = typename std::remove_const<typename
+                          std::remove_pointer<typename
+                          std::remove_const<PointerType>::type>::type>::type;
+        // make sure the type matches the allowed types
+        static_assert(
+            std::is_same<object_t, pointee_t>::value
+            or std::is_same<array_t, pointee_t>::value
+            or std::is_same<string_t, pointee_t>::value
+            or std::is_same<boolean_t, pointee_t>::value
+            or std::is_same<number_integer_t, pointee_t>::value
+            or std::is_same<number_unsigned_t, pointee_t>::value
+            or std::is_same<number_float_t, pointee_t>::value
+            , "incompatible pointer type");
 
-        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+        // delegate the call to get_impl_ptr<>()
+        return get_impl_ptr(static_cast<PointerType>(nullptr));
     }
 
     /*!
-    @brief access specified object element with default value
-
-    Returns either a copy of an object's element at the specified key @a key
-    or a given default value if no element with key @a key exists.
+    @brief get a pointer value (implicit)
+    @copydoc get_ptr()
+    */
+    template<typename PointerType, typename std::enable_if<
+                 std::is_pointer<PointerType>::value and
+                 std::is_const<typename std::remove_pointer<PointerType>::type>::value, int>::type = 0>
+    constexpr const PointerType get_ptr() const noexcept
+    {
+        // get the type of the PointerType (remove pointer and const)
+        using pointee_t = typename std::remove_const<typename
+                          std::remove_pointer<typename
+                          std::remove_const<PointerType>::type>::type>::type;
+        // make sure the type matches the allowed types
+        static_assert(
+            std::is_same<object_t, pointee_t>::value
+            or std::is_same<array_t, pointee_t>::value
+            or std::is_same<string_t, pointee_t>::value
+            or std::is_same<boolean_t, pointee_t>::value
+            or std::is_same<number_integer_t, pointee_t>::value
+            or std::is_same<number_unsigned_t, pointee_t>::value
+            or std::is_same<number_float_t, pointee_t>::value
+            , "incompatible pointer type");
 
-    The function is basically equivalent to executing
-    @code {.cpp}
-    try {
-        return at(key);
-    } catch(out_of_range) {
-        return default_value;
+        // delegate the call to get_impl_ptr<>() const
+        return get_impl_ptr(static_cast<const PointerType>(nullptr));
     }
-    @endcode
-
-    @note Unlike @ref at(const typename object_t::key_type&), this function
-    does not throw if the given key @a key was not found.
 
-    @note Unlike @ref operator[](const typename object_t::key_type& key), this
-    function does not implicitly add an element to the position defined by @a
-    key. This function is furthermore also applicable to const objects.
+    /*!
+    @brief get a reference value (implicit)
 
-    @param[in] key  key of the element to access
-    @param[in] default_value  the value to return if @a key is not found
+    Implicit reference access to the internally stored JSON value. No copies
+    are made.
 
-    @tparam ValueType type compatible to JSON values, for instance `int` for
-    JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
-    JSON arrays. Note the type of the expected value at @a key and the default
-    value @a default_value must be compatible.
+    @warning Writing data to the referee of the result yields an undefined
+    state.
 
-    @return copy of the element at key @a key or @a default_value if @a key
-    is not found
+    @tparam ReferenceType reference type; must be a reference to @ref array_t,
+    @ref object_t, @ref string_t, @ref boolean_t, @ref number_integer_t, or
+    @ref number_float_t. Enforced by static assertion.
 
-    @throw type_error.306 if the JSON value is not an objec; in that cases,
-    using `value()` with a key makes no sense.
+    @return reference to the internally stored JSON value if the requested
+    reference type @a ReferenceType fits to the JSON value; throws
+    type_error.303 otherwise
 
-    @complexity Logarithmic in the size of the container.
+    @throw type_error.303 in case passed type @a ReferenceType is incompatible
+    with the stored JSON value; see example below
 
-    @liveexample{The example below shows how object elements can be queried
-    with a default value.,basic_json__value}
+    @complexity Constant.
 
-    @sa @ref at(const typename object_t::key_type&) for access by reference
-    with range checking
-    @sa @ref operator[](const typename object_t::key_type&) for unchecked
-    access by reference
+    @liveexample{The example shows several calls to `get_ref()`.,get_ref}
 
-    @since version 1.0.0
+    @since version 1.1.0
     */
-    template<class ValueType, typename std::enable_if<
-                 std::is_convertible<basic_json_t, ValueType>::value, int>::type = 0>
-    ValueType value(const typename object_t::key_type& key, ValueType default_value) const
+    template<typename ReferenceType, typename std::enable_if<
+                 std::is_reference<ReferenceType>::value, int>::type = 0>
+    ReferenceType get_ref()
     {
-        // at only works for objects
-        if (is_object())
-        {
-            // if key is found, return value and given default value otherwise
-            const auto it = find(key);
-            if (it != end())
-            {
-                return *it;
-            }
-
-            return default_value;
-        }
-        else
-        {
-            JSON_THROW(type_error::create(306, "cannot use value() with " + type_name()));
-        }
+        // delegate call to get_ref_impl
+        return get_ref_impl<ReferenceType>(*this);
     }
 
     /*!
-    @brief overload for a default value of type const char*
-    @copydoc basic_json::value(const typename object_t::key_type&, ValueType) const
+    @brief get a reference value (implicit)
+    @copydoc get_ref()
     */
-    string_t value(const typename object_t::key_type& key, const char* default_value) const
+    template<typename ReferenceType, typename std::enable_if<
+                 std::is_reference<ReferenceType>::value and
+                 std::is_const<typename std::remove_reference<ReferenceType>::type>::value, int>::type = 0>
+    ReferenceType get_ref() const
     {
-        return value(key, string_t(default_value));
+        // delegate call to get_ref_impl
+        return get_ref_impl<ReferenceType>(*this);
     }
 
     /*!
-    @brief access specified object element via JSON Pointer with default value
+    @brief get a value (implicit)
 
-    Returns either a copy of an object's element at the specified key @a key
-    or a given default value if no element with key @a key exists.
+    Implicit type conversion between the JSON value and a compatible value.
+    The call is realized by calling @ref get() const.
 
-    The function is basically equivalent to executing
-    @code {.cpp}
-    try {
-        return at(ptr);
-    } catch(out_of_range) {
-        return default_value;
+    @tparam ValueType non-pointer type compatible to the JSON value, for
+    instance `int` for JSON integer numbers, `bool` for JSON booleans, or
+    `std::vector` types for JSON arrays. The character type of @ref string_t
+    as well as an initializer list of this type is excluded to avoid
+    ambiguities as these types implicitly convert to `std::string`.
+
+    @return copy of the JSON value, converted to type @a ValueType
+
+    @throw type_error.302 in case passed type @a ValueType is incompatible
+    to the JSON value type (e.g., the JSON value is of type boolean, but a
+    string is requested); see example below
+
+    @complexity Linear in the size of the JSON value.
+
+    @liveexample{The example below shows several conversions from JSON values
+    to other types. There a few things to note: (1) Floating-point numbers can
+    be converted to integers\, (2) A JSON array can be converted to a standard
+    `std::vector<short>`\, (3) A JSON object can be converted to C++
+    associative containers such as `std::unordered_map<std::string\,
+    json>`.,operator__ValueType}
+
+    @since version 1.0.0
+    */
+    template < typename ValueType, typename std::enable_if <
+                   not std::is_pointer<ValueType>::value and
+                   not std::is_same<ValueType, typename string_t::value_type>::value
+#ifndef _MSC_VER  // fix for issue #167 operator<< ambiguity under VS2015
+                   and not std::is_same<ValueType, std::initializer_list<typename string_t::value_type>>::value
+#endif
+#if (defined(__cplusplus) && __cplusplus >= 201703L) || (defined(_MSC_VER) && _MSC_VER >1900 && defined(_HAS_CXX17) && _HAS_CXX17 == 1) // fix for issue #464
+                   and not std::is_same<ValueType, typename std::string_view>::value
+#endif
+                   , int >::type = 0 >
+    operator ValueType() const
+    {
+        // delegate the call to get<>() const
+        return get<ValueType>();
     }
-    @endcode
 
-    @note Unlike @ref at(const json_pointer&), this function does not throw
-    if the given key @a key was not found.
+    /// @}
 
-    @param[in] ptr  a JSON pointer to the element to access
-    @param[in] default_value  the value to return if @a ptr found no value
 
-    @tparam ValueType type compatible to JSON values, for instance `int` for
-    JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
-    JSON arrays. Note the type of the expected value at @a key and the default
-    value @a default_value must be compatible.
+    ////////////////////
+    // element access //
+    ////////////////////
 
-    @return copy of the element at key @a key or @a default_value if @a key
-    is not found
+    /// @name element access
+    /// Access to the JSON value.
+    /// @{
 
-    @throw type_error.306 if the JSON value is not an objec; in that cases,
-    using `value()` with a key makes no sense.
+    /*!
+    @brief access specified array element with bounds checking
 
-    @complexity Logarithmic in the size of the container.
+    Returns a reference to the element at specified location @a idx, with
+    bounds checking.
 
-    @liveexample{The example below shows how object elements can be queried
-    with a default value.,basic_json__value_ptr}
+    @param[in] idx  index of the element to access
 
-    @sa @ref operator[](const json_pointer&) for unchecked access by reference
+    @return reference to the element at index @a idx
 
-    @since version 2.0.2
+    @throw type_error.304 if the JSON value is not an array; in this case,
+    calling `at` with an index makes no sense. See example below.
+    @throw out_of_range.401 if the index @a idx is out of range of the array;
+    that is, `idx >= size()`. See example below.
+
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
+
+    @complexity Constant.
+
+    @since version 1.0.0
+
+    @liveexample{The example below shows how array elements can be read and
+    written using `at()`. It also demonstrates the different exceptions that
+    can be thrown.,at__size_type}
     */
-    template<class ValueType, typename std::enable_if<
-                 std::is_convertible<basic_json_t, ValueType>::value, int>::type = 0>
-    ValueType value(const json_pointer& ptr, ValueType default_value) const
+    reference at(size_type idx)
     {
-        // at only works for objects
-        if (is_object())
+        // at only works for arrays
+        if (is_array())
         {
-            // if pointer resolves a value, return it or use default value
             JSON_TRY
             {
-                return ptr.get_checked(this);
+                return m_value.array->at(idx);
             }
-            JSON_CATCH (out_of_range&)
+            JSON_CATCH (std::out_of_range&)
             {
-                return default_value;
+                // create better exception explanation
+                JSON_THROW(out_of_range::create(401, "array index " + std::to_string(idx) + " is out of range"));
             }
         }
-
-        JSON_THROW(type_error::create(306, "cannot use value() with " + type_name()));
+        else
+        {
+            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
+        }
     }
 
     /*!
-    @brief overload for a default value of type const char*
-    @copydoc basic_json::value(const json_pointer&, ValueType) const
-    */
-    string_t value(const json_pointer& ptr, const char* default_value) const
-    {
-        return value(ptr, string_t(default_value));
-    }
+    @brief access specified array element with bounds checking
 
-    /*!
-    @brief access the first element
-
-    Returns a reference to the first element in the container. For a JSON
-    container `c`, the expression `c.front()` is equivalent to `*c.begin()`.
-
-    @return In case of a structured type (array or object), a reference to the
-    first element is returned. In case of number, string, or boolean values, a
-    reference to the value is returned.
+    Returns a const reference to the element at specified location @a idx,
+    with bounds checking.
 
-    @complexity Constant.
+    @param[in] idx  index of the element to access
 
-    @pre The JSON value must not be `null` (would throw `std::out_of_range`)
-    or an empty array or object (undefined behavior, **guarded by
-    assertions**).
-    @post The JSON value remains unchanged.
+    @return const reference to the element at index @a idx
 
-    @throw invalid_iterator.214 when called on `null` value
+    @throw type_error.304 if the JSON value is not an array; in this case,
+    calling `at` with an index makes no sense. See example below.
+    @throw out_of_range.401 if the index @a idx is out of range of the array;
+    that is, `idx >= size()`. See example below.
 
-    @liveexample{The following code shows an example for `front()`.,front}
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
 
-    @sa @ref back() -- access the last element
+    @complexity Constant.
 
     @since version 1.0.0
-    */
-    reference front()
-    {
-        return *begin();
-    }
 
-    /*!
-    @copydoc basic_json::front()
+    @liveexample{The example below shows how array elements can be read using
+    `at()`. It also demonstrates the different exceptions that can be thrown.,
+    at__size_type_const}
     */
-    const_reference front() const
+    const_reference at(size_type idx) const
     {
-        return *cbegin();
+        // at only works for arrays
+        if (is_array())
+        {
+            JSON_TRY
+            {
+                return m_value.array->at(idx);
+            }
+            JSON_CATCH (std::out_of_range&)
+            {
+                // create better exception explanation
+                JSON_THROW(out_of_range::create(401, "array index " + std::to_string(idx) + " is out of range"));
+            }
+        }
+        else
+        {
+            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
+        }
     }
 
     /*!
-    @brief access the last element
+    @brief access specified object element with bounds checking
 
-    Returns a reference to the last element in the container. For a JSON
-    container `c`, the expression `c.back()` is equivalent to
-    @code {.cpp}
-    auto tmp = c.end();
-    --tmp;
-    return *tmp;
-    @endcode
+    Returns a reference to the element at with specified key @a key, with
+    bounds checking.
 
-    @return In case of a structured type (array or object), a reference to the
-    last element is returned. In case of number, string, or boolean values, a
-    reference to the value is returned.
+    @param[in] key  key of the element to access
 
-    @complexity Constant.
+    @return reference to the element at key @a key
 
-    @pre The JSON value must not be `null` (would throw `std::out_of_range`)
-    or an empty array or object (undefined behavior, **guarded by
-    assertions**).
-    @post The JSON value remains unchanged.
+    @throw type_error.304 if the JSON value is not an object; in this case,
+    calling `at` with a key makes no sense. See example below.
+    @throw out_of_range.403 if the key @a key is is not stored in the object;
+    that is, `find(key) == end()`. See example below.
 
-    @throw invalid_iterator.214 when called on a `null` value. See example
-    below.
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
 
-    @liveexample{The following code shows an example for `back()`.,back}
+    @complexity Logarithmic in the size of the container.
 
-    @sa @ref front() -- access the first element
+    @sa @ref operator[](const typename object_t::key_type&) for unchecked
+    access by reference
+    @sa @ref value() for access by value with a default value
 
     @since version 1.0.0
-    */
-    reference back()
-    {
-        auto tmp = end();
-        --tmp;
-        return *tmp;
-    }
 
-    /*!
-    @copydoc basic_json::back()
+    @liveexample{The example below shows how object elements can be read and
+    written using `at()`. It also demonstrates the different exceptions that
+    can be thrown.,at__object_t_key_type}
     */
-    const_reference back() const
+    reference at(const typename object_t::key_type& key)
     {
-        auto tmp = cend();
-        --tmp;
-        return *tmp;
+        // at only works for objects
+        if (is_object())
+        {
+            JSON_TRY
+            {
+                return m_value.object->at(key);
+            }
+            JSON_CATCH (std::out_of_range&)
+            {
+                // create better exception explanation
+                JSON_THROW(out_of_range::create(403, "key '" + key + "' not found"));
+            }
+        }
+        else
+        {
+            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
+        }
     }
 
     /*!
-    @brief remove element given an iterator
-
-    Removes the element specified by iterator @a pos. The iterator @a pos must
-    be valid and dereferenceable. Thus the `end()` iterator (which is valid,
-    but is not dereferenceable) cannot be used as a value for @a pos.
-
-    If called on a primitive type other than `null`, the resulting JSON value
-    will be `null`.
+    @brief access specified object element with bounds checking
 
-    @param[in] pos iterator to the element to remove
-    @return Iterator following the last removed element. If the iterator @a
-    pos refers to the last element, the `end()` iterator is returned.
+    Returns a const reference to the element at with specified key @a key,
+    with bounds checking.
 
-    @tparam IteratorType an @ref iterator or @ref const_iterator
+    @param[in] key  key of the element to access
 
-    @post Invalidates iterators and references at or after the point of the
-    erase, including the `end()` iterator.
+    @return const reference to the element at key @a key
 
-    @throw type_error.307 if called on a `null` value; example: `"cannot use
-    erase() with null"`
-    @throw invalid_iterator.202 if called on an iterator which does not belong
-    to the current JSON value; example: `"iterator does not fit current
-    value"`
-    @throw invalid_iterator.205 if called on a primitive type with invalid
-    iterator (i.e., any iterator which is not `begin()`); example: `"iterator
-    out of range"`
+    @throw type_error.304 if the JSON value is not an object; in this case,
+    calling `at` with a key makes no sense. See example below.
+    @throw out_of_range.403 if the key @a key is is not stored in the object;
+    that is, `find(key) == end()`. See example below.
 
-    @complexity The complexity depends on the type:
-    - objects: amortized constant
-    - arrays: linear in distance between @a pos and the end of the container
-    - strings: linear in the length of the string
-    - other types: constant
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
 
-    @liveexample{The example shows the result of `erase()` for different JSON
-    types.,erase__IteratorType}
+    @complexity Logarithmic in the size of the container.
 
-    @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
-    @sa @ref erase(const size_type) -- removes the element from an array at
-    the given index
+    @sa @ref operator[](const typename object_t::key_type&) for unchecked
+    access by reference
+    @sa @ref value() for access by value with a default value
 
     @since version 1.0.0
+
+    @liveexample{The example below shows how object elements can be read using
+    `at()`. It also demonstrates the different exceptions that can be thrown.,
+    at__object_t_key_type_const}
     */
-    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 pos)
+    const_reference at(const typename object_t::key_type& key) const
     {
-        // make sure iterator fits the current value
-        if (this != pos.m_object)
-        {
-            JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
-        }
-
-        IteratorType result = end();
-
-        switch (m_type)
+        // at only works for objects
+        if (is_object())
         {
-            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(invalid_iterator::create(205, "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:
+            JSON_TRY
             {
-                result.m_it.array_iterator = m_value.array->erase(pos.m_it.array_iterator);
-                break;
+                return m_value.object->at(key);
             }
-
-            default:
+            JSON_CATCH (std::out_of_range&)
             {
-                JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
+                // create better exception explanation
+                JSON_THROW(out_of_range::create(403, "key '" + key + "' not found"));
             }
         }
-
-        return result;
+        else
+        {
+            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
+        }
     }
 
     /*!
-    @brief remove elements given an iterator range
+    @brief access specified array element
 
-    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.
+    Returns a reference to the element at specified location @a idx.
 
-    If called on a primitive type other than `null`, the resulting JSON value
-    will be `null`.
+    @note If @a idx is beyond the range of the array (i.e., `idx >= size()`),
+    then the array is silently filled up with `null` values to make `idx` a
+    valid reference to the last stored element.
 
-    @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.
+    @param[in] idx  index of the element to access
 
-    @throw type_error.307 if called on a `null` value; example: `"cannot use
-    erase() with null"`
-    @throw invalid_iterator.203 if called on iterators which does not belong
-    to the current JSON value; example: `"iterators do not fit current value"`
-    @throw invalid_iterator.204 if called on a primitive type with invalid
-    iterators (i.e., if `first != begin()` and `last != end()`); example:
-    `"iterators out of range"`
+    @return reference to the element at index @a idx
 
-    @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
+    @throw type_error.305 if the JSON value is not an array or null; in that
+    cases, using the [] operator with an index makes no sense.
 
-    @liveexample{The example shows the result of `erase()` for different JSON
-    types.,erase__IteratorType_IteratorType}
+    @complexity Constant if @a idx is in the range of the array. Otherwise
+    linear in `idx - size()`.
 
-    @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
+    @liveexample{The example below shows how array elements can be read and
+    written using `[]` operator. Note the addition of `null`
+    values.,operatorarray__size_type}
 
     @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)
+    reference operator[](size_type idx)
     {
-        // make sure iterator fits the current value
-        if (this != first.m_object or this != last.m_object)
+        // implicitly convert null value to an empty array
+        if (is_null())
         {
-            JSON_THROW(invalid_iterator::create(203, "iterators do not fit current value"));
+            m_type = value_t::array;
+            m_value.array = create<array_t>();
+            assert_invariant();
         }
 
-        IteratorType result = end();
-
-        switch (m_type)
+        // operator[] only works for arrays
+        if (is_array())
         {
-            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(invalid_iterator::create(204, "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:
+            // fill up array with null values if given idx is outside range
+            if (idx >= m_value.array->size())
             {
-                result.m_it.array_iterator = m_value.array->erase(first.m_it.array_iterator,
-                                             last.m_it.array_iterator);
-                break;
+                m_value.array->insert(m_value.array->end(),
+                                      idx - m_value.array->size() + 1,
+                                      basic_json());
             }
 
-            default:
-            {
-                JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
-            }
+            return m_value.array->operator[](idx);
         }
 
-        return result;
+        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
     }
 
     /*!
-    @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
+    @brief access specified array element
 
-    @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).
+    Returns a const reference to the element at specified location @a idx.
 
-    @post References and iterators to the erased elements are invalidated.
-    Other references and iterators are not affected.
+    @param[in] idx  index of the element to access
 
-    @throw type_error.307 when called on a type other than JSON object;
-    example: `"cannot use erase() with null"`
+    @return const reference to the element at index @a idx
 
-    @complexity `log(size()) + count(key)`
+    @throw type_error.305 if the JSON value is not an array; in that cases,
+    using the [] operator with an index makes no sense.
 
-    @liveexample{The example shows the effect of `erase()`.,erase__key_type}
+    @complexity Constant.
 
-    @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
+    @liveexample{The example below shows how array elements can be read using
+    the `[]` operator.,operatorarray__size_type_const}
 
     @since version 1.0.0
     */
-    size_type erase(const typename object_t::key_type& key)
+    const_reference operator[](size_type idx) const
     {
-        // this erase only works for objects
-        if (is_object())
+        // const operator[] only works for arrays
+        if (is_array())
         {
-            return m_value.object->erase(key);
+            return m_value.array->operator[](idx);
         }
 
-        JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
+        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
     }
 
     /*!
-    @brief remove element from a JSON array given an index
+    @brief access specified object element
 
-    Removes element from a JSON array at the index @a idx.
+    Returns a reference to the element at with specified key @a key.
 
-    @param[in] idx index of the element to remove
+    @note If @a key is not found in the object, then it is silently added to
+    the object and filled with a `null` value to make `key` a valid reference.
+    In case the value was `null` before, it is converted to an object.
 
-    @throw type_error.307 when called on a type other than JSON object;
-    example: `"cannot use erase() with null"`
-    @throw out_of_range.401 when `idx >= size()`; example: `"array index 17
-    is out of range"`
+    @param[in] key  key of the element to access
 
-    @complexity Linear in distance between @a idx and the end of the container.
+    @return reference to the element at key @a key
 
-    @liveexample{The example shows the effect of `erase()`.,erase__size_type}
+    @throw type_error.305 if the JSON value is not an object or null; in that
+    cases, using the [] operator with a key makes no sense.
 
-    @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
+    @complexity Logarithmic in the size of the container.
+
+    @liveexample{The example below shows how object elements can be read and
+    written using the `[]` operator.,operatorarray__key_type}
+
+    @sa @ref at(const typename object_t::key_type&) for access by reference
+    with range checking
+    @sa @ref value() for access by value with a default value
 
     @since version 1.0.0
     */
-    void erase(const size_type idx)
+    reference operator[](const typename object_t::key_type& key)
     {
-        // this erase only works for arrays
-        if (is_array())
+        // implicitly convert null value to an empty object
+        if (is_null())
         {
-            if (idx >= size())
-            {
-                JSON_THROW(out_of_range::create(401, "array index " + std::to_string(idx) + " is out of range"));
-            }
-
-            m_value.array->erase(m_value.array->begin() + static_cast<difference_type>(idx));
+            m_type = value_t::object;
+            m_value.object = create<object_t>();
+            assert_invariant();
         }
-        else
+
+        // operator[] only works for objects
+        if (is_object())
         {
-            JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
+            return m_value.object->operator[](key);
         }
-    }
 
-    /// @}
+        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+    }
 
+    /*!
+    @brief read-only access specified object element
 
-    ////////////
-    // lookup //
-    ////////////
+    Returns a const reference to the element at with specified key @a key. No
+    bounds checking is performed.
 
-    /// @name lookup
-    /// @{
+    @warning If the element with key @a key does not exist, the behavior is
+    undefined.
 
-    /*!
-    @brief find an element in a JSON object
+    @param[in] key  key of the element to access
 
-    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.
+    @return const reference to the element at key @a key
 
-    @note This method always returns @ref end() when executed on a JSON type
-          that is not an object.
+    @pre The element with key @a key must exist. **This precondition is
+         enforced with an assertion.**
 
-    @param[in] key key value of the element to search for
+    @throw type_error.305 if the JSON value is not an object; in that cases,
+    using the [] operator with a key makes no sense.
 
-    @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 container.
 
-    @complexity Logarithmic in the size of the JSON object.
+    @liveexample{The example below shows how object elements can be read using
+    the `[]` operator.,operatorarray__key_type_const}
 
-    @liveexample{The example shows how `find()` is used.,find__key_type}
+    @sa @ref at(const typename object_t::key_type&) for access by reference
+    with range checking
+    @sa @ref value() for access by value with a default value
 
     @since version 1.0.0
     */
-    iterator find(typename object_t::key_type key)
+    const_reference operator[](const typename object_t::key_type& key) const
     {
-        auto result = end();
-
+        // const operator[] only works for objects
         if (is_object())
         {
-            result.m_it.object_iterator = m_value.object->find(key);
+            assert(m_value.object->find(key) != m_value.object->end());
+            return m_value.object->find(key)->second;
         }
 
-        return result;
+        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
     }
 
     /*!
-    @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();
+    @brief access specified object element
 
-        if (is_object())
-        {
-            result.m_it.object_iterator = m_value.object->find(key);
-        }
+    Returns a reference to the element at with specified key @a key.
 
-        return result;
-    }
-
-    /*!
-    @brief returns the number of occurrences of a key in a JSON object
+    @note If @a key is not found in the object, then it is silently added to
+    the object and filled with a `null` value to make `key` a valid reference.
+    In case the value was `null` before, it is converted to an 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).
+    @param[in] key  key of the element to access
 
-    @note This method always returns `0` when executed on a JSON type that is
-          not an object.
+    @return reference to the element at key @a key
 
-    @param[in] key key value of the element to count
+    @throw type_error.305 if the JSON value is not an object or null; in that
+    cases, using the [] operator with a key makes no sense.
 
-    @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 container.
 
-    @complexity Logarithmic in the size of the JSON object.
+    @liveexample{The example below shows how object elements can be read and
+    written using the `[]` operator.,operatorarray__key_type}
 
-    @liveexample{The example shows how `count()` is used.,count}
+    @sa @ref at(const typename object_t::key_type&) for access by reference
+    with range checking
+    @sa @ref value() for access by value with a default value
 
-    @since version 1.0.0
+    @since version 1.1.0
     */
-    size_type count(typename object_t::key_type key) const
+    template<typename T>
+    reference operator[](T* key)
     {
-        // return 0 for all nonobject types
-        return is_object() ? m_value.object->count(key) : 0;
-    }
+        // implicitly convert null to object
+        if (is_null())
+        {
+            m_type = value_t::object;
+            m_value = value_t::object;
+            assert_invariant();
+        }
 
-    /// @}
+        // at only works for objects
+        if (is_object())
+        {
+            return m_value.object->operator[](key);
+        }
 
+        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+    }
 
-    ///////////////
-    // iterators //
-    ///////////////
+    /*!
+    @brief read-only access specified object element
 
-    /// @name iterators
-    /// @{
+    Returns a const reference to the element at with specified key @a key. No
+    bounds checking is performed.
 
-    /*!
-    @brief returns an iterator to the first element
+    @warning If the element with key @a key does not exist, the behavior is
+    undefined.
 
-    Returns an iterator to the first element.
+    @param[in] key  key of the element to access
 
-    @image html range-begin-end.svg "Illustration from cppreference.com"
+    @return const reference to the element at key @a key
 
-    @return iterator to the first element
+    @pre The element with key @a key must exist. **This precondition is
+         enforced with an assertion.**
 
-    @complexity Constant.
+    @throw type_error.305 if the JSON value is not an object; in that cases,
+    using the [] operator with a key makes no sense.
 
-    @requirement This function helps `basic_json` satisfying the
-    [Container](http://en.cppreference.com/w/cpp/concept/Container)
-    requirements:
-    - The complexity is constant.
+    @complexity Logarithmic in the size of the container.
 
-    @liveexample{The following code shows an example for `begin()`.,begin}
+    @liveexample{The example below shows how object elements can be read using
+    the `[]` operator.,operatorarray__key_type_const}
 
-    @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
+    @sa @ref at(const typename object_t::key_type&) for access by reference
+    with range checking
+    @sa @ref value() for access by value with a default value
 
-    @since version 1.0.0
+    @since version 1.1.0
     */
-    iterator begin() noexcept
+    template<typename T>
+    const_reference operator[](T* key) const
     {
-        iterator result(this);
-        result.set_begin();
-        return result;
-    }
+        // at only works for objects
+        if (is_object())
+        {
+            assert(m_value.object->find(key) != m_value.object->end());
+            return m_value.object->find(key)->second;
+        }
 
-    /*!
-    @copydoc basic_json::cbegin()
-    */
-    const_iterator begin() const noexcept
-    {
-        return cbegin();
+        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
     }
 
     /*!
-    @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}
+    @brief access specified object element with default value
 
-    @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
+    Returns either a copy of an object's element at the specified key @a key
+    or a given default value if no element with key @a key exists.
 
-    @since version 1.0.0
-    */
-    const_iterator cbegin() const noexcept
-    {
-        const_iterator result(this);
-        result.set_begin();
-        return result;
+    The function is basically equivalent to executing
+    @code {.cpp}
+    try {
+        return at(key);
+    } catch(out_of_range) {
+        return default_value;
     }
+    @endcode
 
-    /*!
-    @brief returns an iterator to one past the last element
+    @note Unlike @ref at(const typename object_t::key_type&), this function
+    does not throw if the given key @a key was not found.
 
-    Returns an iterator to one past the last element.
+    @note Unlike @ref operator[](const typename object_t::key_type& key), this
+    function does not implicitly add an element to the position defined by @a
+    key. This function is furthermore also applicable to const objects.
 
-    @image html range-begin-end.svg "Illustration from cppreference.com"
+    @param[in] key  key of the element to access
+    @param[in] default_value  the value to return if @a key is not found
 
-    @return iterator one past the last element
+    @tparam ValueType type compatible to JSON values, for instance `int` for
+    JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
+    JSON arrays. Note the type of the expected value at @a key and the default
+    value @a default_value must be compatible.
 
-    @complexity Constant.
+    @return copy of the element at key @a key or @a default_value if @a key
+    is not found
 
-    @requirement This function helps `basic_json` satisfying the
-    [Container](http://en.cppreference.com/w/cpp/concept/Container)
-    requirements:
-    - The complexity is constant.
+    @throw type_error.306 if the JSON value is not an objec; in that cases,
+    using `value()` with a key makes no sense.
 
-    @liveexample{The following code shows an example for `end()`.,end}
+    @complexity Logarithmic in the size of the container.
 
-    @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
+    @liveexample{The example below shows how object elements can be queried
+    with a default value.,basic_json__value}
+
+    @sa @ref at(const typename object_t::key_type&) for access by reference
+    with range checking
+    @sa @ref operator[](const typename object_t::key_type&) for unchecked
+    access by reference
 
     @since version 1.0.0
     */
-    iterator end() noexcept
+    template<class ValueType, typename std::enable_if<
+                 std::is_convertible<basic_json_t, ValueType>::value, int>::type = 0>
+    ValueType value(const typename object_t::key_type& key, ValueType default_value) const
     {
-        iterator result(this);
-        result.set_end();
-        return result;
+        // at only works for objects
+        if (is_object())
+        {
+            // if key is found, return value and given default value otherwise
+            const auto it = find(key);
+            if (it != end())
+            {
+                return *it;
+            }
+
+            return default_value;
+        }
+        else
+        {
+            JSON_THROW(type_error::create(306, "cannot use value() with " + type_name()));
+        }
     }
 
     /*!
-    @copydoc basic_json::cend()
+    @brief overload for a default value of type const char*
+    @copydoc basic_json::value(const typename object_t::key_type&, ValueType) const
     */
-    const_iterator end() const noexcept
+    string_t value(const typename object_t::key_type& key, const char* default_value) const
     {
-        return cend();
+        return value(key, string_t(default_value));
     }
 
     /*!
-    @brief returns a const iterator to one past the last element
+    @brief access specified object element via JSON Pointer with default value
 
-    Returns a const iterator to one past the last element.
+    Returns either a copy of an object's element at the specified key @a key
+    or a given default value if no element with key @a key exists.
 
-    @image html range-begin-end.svg "Illustration from cppreference.com"
+    The function is basically equivalent to executing
+    @code {.cpp}
+    try {
+        return at(ptr);
+    } catch(out_of_range) {
+        return default_value;
+    }
+    @endcode
 
-    @return const iterator one past the last element
+    @note Unlike @ref at(const json_pointer&), this function does not throw
+    if the given key @a key was not found.
 
-    @complexity Constant.
+    @param[in] ptr  a JSON pointer to the element to access
+    @param[in] default_value  the value to return if @a ptr found no value
 
-    @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()`.
+    @tparam ValueType type compatible to JSON values, for instance `int` for
+    JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
+    JSON arrays. Note the type of the expected value at @a key and the default
+    value @a default_value must be compatible.
 
-    @liveexample{The following code shows an example for `cend()`.,cend}
+    @return copy of the element at key @a key or @a default_value if @a key
+    is not found
 
-    @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
+    @throw type_error.306 if the JSON value is not an objec; in that cases,
+    using `value()` with a key makes no sense.
 
-    @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())`.
+    @complexity Logarithmic in the size of the container.
 
-    @liveexample{The following code shows an example for `rbegin()`.,rbegin}
+    @liveexample{The example below shows how object elements can be queried
+    with a default value.,basic_json__value_ptr}
 
-    @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
+    @sa @ref operator[](const json_pointer&) for unchecked access by reference
 
-    @since version 1.0.0
+    @since version 2.0.2
     */
-    reverse_iterator rbegin() noexcept
+    template<class ValueType, typename std::enable_if<
+                 std::is_convertible<basic_json_t, ValueType>::value, int>::type = 0>
+    ValueType value(const json_pointer& ptr, ValueType default_value) const
     {
-        return reverse_iterator(end());
+        // at only works for objects
+        if (is_object())
+        {
+            // if pointer resolves a value, return it or use default value
+            JSON_TRY
+            {
+                return ptr.get_checked(this);
+            }
+            JSON_CATCH (out_of_range&)
+            {
+                return default_value;
+            }
+        }
+
+        JSON_THROW(type_error::create(306, "cannot use value() with " + type_name()));
     }
 
     /*!
-    @copydoc basic_json::crbegin()
+    @brief overload for a default value of type const char*
+    @copydoc basic_json::value(const json_pointer&, ValueType) const
     */
-    const_reverse_iterator rbegin() const noexcept
+    string_t value(const json_pointer& ptr, const char* default_value) const
     {
-        return crbegin();
+        return value(ptr, string_t(default_value));
     }
 
     /*!
-    @brief returns an iterator to the reverse-end
+    @brief access the first element
 
-    Returns an iterator to the reverse-end; that is, one before the first
-    element.
+    Returns a reference to the first element in the container. For a JSON
+    container `c`, the expression `c.front()` is equivalent to `*c.begin()`.
 
-    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
+    @return In case of a structured type (array or object), a reference to the
+    first element is returned. In case of number, string, or boolean values, a
+    reference to the value is returned.
 
     @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())`.
+    @pre The JSON value must not be `null` (would throw `std::out_of_range`)
+    or an empty array or object (undefined behavior, **guarded by
+    assertions**).
+    @post The JSON value remains unchanged.
 
-    @liveexample{The following code shows an example for `rend()`.,rend}
+    @throw invalid_iterator.214 when called on `null` value
 
-    @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
+    @liveexample{The following code shows an example for `front()`.,front}
+
+    @sa @ref back() -- access the last element
 
     @since version 1.0.0
     */
-    reverse_iterator rend() noexcept
+    reference front()
     {
-        return reverse_iterator(begin());
+        return *begin();
     }
 
     /*!
-    @copydoc basic_json::crend()
+    @copydoc basic_json::front()
     */
-    const_reverse_iterator rend() const noexcept
+    const_reference front() const
     {
-        return crend();
+        return *cbegin();
     }
 
     /*!
-    @brief returns a const reverse iterator to the last element
+    @brief access the last element
 
-    Returns a const iterator to the reverse-beginning; that is, the last
-    element.
+    Returns a reference to the last element in the container. For a JSON
+    container `c`, the expression `c.back()` is equivalent to
+    @code {.cpp}
+    auto tmp = c.end();
+    --tmp;
+    return *tmp;
+    @endcode
 
-    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
+    @return In case of a structured type (array or object), a reference to the
+    last element is returned. In case of number, string, or boolean values, a
+    reference to the value is returned.
 
     @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.
+    @pre The JSON value must not be `null` (would throw `std::out_of_range`)
+    or an empty array or object (undefined behavior, **guarded by
+    assertions**).
+    @post The JSON value remains unchanged.
 
-    @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()`.
+    @throw invalid_iterator.214 when called on a `null` value. See example
+    below.
 
-    @liveexample{The following code shows an example for `crend()`.,crend}
+    @liveexample{The following code shows an example for `back()`.,back}
 
-    @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
+    @sa @ref front() -- access the first element
 
     @since version 1.0.0
     */
-    const_reverse_iterator crend() const noexcept
+    reference back()
     {
-        return const_reverse_iterator(cbegin());
+        auto tmp = end();
+        --tmp;
+        return *tmp;
     }
 
-  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.
-
-    @liveexample{The following code shows how the wrapper is used,iterator_wrapper}
-
-    @note The name of this function is not yet final and may change in the
-    future.
+    @copydoc basic_json::back()
     */
-    static iteration_proxy<iterator> iterator_wrapper(reference cont)
+    const_reference back() const
     {
-        return iteration_proxy<iterator>(cont);
+        auto tmp = cend();
+        --tmp;
+        return *tmp;
     }
 
     /*!
-    @copydoc iterator_wrapper(reference)
-    */
-    static iteration_proxy<const_iterator> iterator_wrapper(const_reference cont)
-    {
-        return iteration_proxy<const_iterator>(cont);
-    }
-
-    /// @}
-
-
-    //////////////
-    // capacity //
-    //////////////
+    @brief remove element given an iterator
 
-    /// @name capacity
-    /// @{
+    Removes the element specified by iterator @a pos. The iterator @a pos must
+    be valid and dereferenceable. Thus the `end()` iterator (which is valid,
+    but is not dereferenceable) cannot be used as a value for @a pos.
 
-    /*!
-    @brief checks whether the container is empty
+    If called on a primitive type other than `null`, the resulting JSON value
+    will be `null`.
 
-    Checks if a JSON value has no elements.
+    @param[in] pos iterator to the element to remove
+    @return Iterator following the last removed element. If the iterator @a
+    pos refers to the last element, the `end()` iterator is returned.
 
-    @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()`
+    @tparam IteratorType an @ref iterator or @ref const_iterator
 
-    @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.
+    @post Invalidates iterators and references at or after the point of the
+    erase, including the `end()` iterator.
 
-    @complexity Constant, as long as @ref array_t and @ref object_t satisfy
-    the Container concept; that is, their `empty()` functions have constant
-    complexity.
+    @throw type_error.307 if called on a `null` value; example: `"cannot use
+    erase() with null"`
+    @throw invalid_iterator.202 if called on an iterator which does not belong
+    to the current JSON value; example: `"iterator does not fit current
+    value"`
+    @throw invalid_iterator.205 if called on a primitive type with invalid
+    iterator (i.e., any iterator which is not `begin()`); example: `"iterator
+    out of range"`
 
-    @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()`.
+    @complexity The complexity depends on the type:
+    - objects: amortized constant
+    - arrays: linear in distance between @a pos and the end of the container
+    - strings: linear in the length of the string
+    - other types: constant
 
-    @liveexample{The following code uses `empty()` to check if a JSON
-    object contains any elements.,empty}
+    @liveexample{The example shows the result of `erase()` for different JSON
+    types.,erase__IteratorType}
 
-    @sa @ref size() -- returns the number of elements
+    @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
+    @sa @ref erase(const size_type) -- removes the element from an array at
+    the given index
 
     @since version 1.0.0
     */
-    bool empty() const noexcept
-    {
-        switch (m_type)
+    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 pos)
+    {
+        // make sure iterator fits the current value
+        if (this != pos.m_object)
         {
-            case value_t::null:
+            JSON_THROW(invalid_iterator::create(202, "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:
             {
-                // null values are empty
-                return true;
+                if (not pos.m_it.primitive_iterator.is_begin())
+                {
+                    JSON_THROW(invalid_iterator::create(205, "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::array:
+            case value_t::object:
             {
-                // delegate call to array_t::empty()
-                return m_value.array->empty();
+                result.m_it.object_iterator = m_value.object->erase(pos.m_it.object_iterator);
+                break;
             }
 
-            case value_t::object:
+            case value_t::array:
             {
-                // delegate call to object_t::empty()
-                return m_value.object->empty();
+                result.m_it.array_iterator = m_value.array->erase(pos.m_it.array_iterator);
+                break;
             }
 
             default:
             {
-                // all other types are nonempty
-                return false;
+                JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
             }
         }
+
+        return result;
     }
 
     /*!
-    @brief returns the number of elements
+    @brief remove elements given an iterator range
 
-    Returns the number of elements in a JSON value.
+    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.
 
-    @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()
+    If called on a primitive type other than `null`, the resulting JSON value
+    will be `null`.
 
-    @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.
+    @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.
 
-    @complexity Constant, as long as @ref array_t and @ref object_t satisfy
-    the Container concept; that is, their size() functions have constant
-    complexity.
+    @tparam IteratorType an @ref iterator or @ref const_iterator
 
-    @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())`.
+    @post Invalidates iterators and references at or after the point of the
+    erase, including the `end()` iterator.
 
-    @liveexample{The following code calls `size()` on the different value
-    types.,size}
+    @throw type_error.307 if called on a `null` value; example: `"cannot use
+    erase() with null"`
+    @throw invalid_iterator.203 if called on iterators which does not belong
+    to the current JSON value; example: `"iterators do not fit current value"`
+    @throw invalid_iterator.204 if called on a primitive type with invalid
+    iterators (i.e., if `first != begin()` and `last != end()`); example:
+    `"iterators out of range"`
 
-    @sa @ref empty() -- checks whether the container is empty
-    @sa @ref max_size() -- returns the maximal number of elements
+    @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
     */
-    size_type size() const noexcept
+    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(invalid_iterator::create(203, "iterators do not fit current value"));
+        }
+
+        IteratorType result = end();
+
         switch (m_type)
         {
-            case value_t::null:
+            case value_t::boolean:
+            case value_t::number_float:
+            case value_t::number_integer:
+            case value_t::number_unsigned:
+            case value_t::string:
             {
-                // null values are empty
-                return 0;
+                if (not first.m_it.primitive_iterator.is_begin() or not last.m_it.primitive_iterator.is_end())
+                {
+                    JSON_THROW(invalid_iterator::create(204, "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::array:
+            case value_t::object:
             {
-                // delegate call to array_t::size()
-                return m_value.array->size();
+                result.m_it.object_iterator = m_value.object->erase(first.m_it.object_iterator,
+                                              last.m_it.object_iterator);
+                break;
             }
 
-            case value_t::object:
+            case value_t::array:
             {
-                // delegate call to object_t::size()
-                return m_value.object->size();
+                result.m_it.array_iterator = m_value.array->erase(first.m_it.array_iterator,
+                                             last.m_it.array_iterator);
+                break;
             }
 
             default:
             {
-                // all other types have size 1
-                return 1;
+                JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
             }
         }
+
+        return result;
     }
 
     /*!
-    @brief returns the maximum possible number of elements
+    @brief remove element from a JSON object given a key
 
-    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.
+    Removes elements from a JSON object with the key value @a key.
 
-    @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()`
+    @param[in] key value of the elements to remove
 
-    @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.
+    @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).
 
-    @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.
+    @post References and iterators to the erased elements are invalidated.
+    Other references and iterators are not affected.
 
-    @liveexample{The following code calls `max_size()` on the different value
-    types. Note the output is implementation specific.,max_size}
+    @throw type_error.307 when called on a type other than JSON object;
+    example: `"cannot use erase() with null"`
 
-    @sa @ref size() -- returns the number of elements
+    @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 max_size() const noexcept
+    size_type erase(const typename object_t::key_type& key)
     {
-        switch (m_type)
+        // this erase only works for objects
+        if (is_object())
         {
-            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();
-            }
+            return m_value.object->erase(key);
         }
-    }
 
-    /// @}
+        JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
+    }
 
+    /*!
+    @brief remove element from a JSON array given an index
 
-    ///////////////
-    // modifiers //
-    ///////////////
+    Removes element from a JSON array at the index @a idx.
 
-    /// @name modifiers
-    /// @{
+    @param[in] idx index of the element to remove
 
-    /*!
-    @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:
+    @throw type_error.307 when called on a type other than JSON object;
+    example: `"cannot use erase() with null"`
+    @throw out_of_range.401 when `idx >= size()`; example: `"array index 17
+    is out of range"`
 
-    Value type  | initial value
-    ----------- | -------------
-    null        | `null`
-    boolean     | `false`
-    string      | `""`
-    number      | `0`
-    object      | `{}`
-    array       | `[]`
+    @complexity Linear in distance between @a idx and the end of the container.
 
-    @complexity Linear in the size of the JSON value.
+    @liveexample{The example shows the effect of `erase()`.,erase__size_type}
 
-    @liveexample{The example below shows the effect of `clear()` to different
-    JSON types.,clear}
+    @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 clear() noexcept
+    void erase(const size_type idx)
     {
-        switch (m_type)
+        // this erase only works for arrays
+        if (is_array())
         {
-            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:
+            if (idx >= size())
             {
-                m_value.number_float = 0.0;
-                break;
+                JSON_THROW(out_of_range::create(401, "array index " + std::to_string(idx) + " is out of range"));
             }
 
-            case value_t::boolean:
-            {
-                m_value.boolean = false;
-                break;
-            }
+            m_value.array->erase(m_value.array->begin() + static_cast<difference_type>(idx));
+        }
+        else
+        {
+            JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
+        }
+    }
 
-            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;
-            }
+    ////////////
+    // lookup //
+    ////////////
 
-            default:
-            {
-                break;
-            }
-        }
-    }
+    /// @name lookup
+    /// @{
 
     /*!
-    @brief add an object to an array
+    @brief find an element in a JSON object
 
-    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.
+    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.
 
-    @param[in] val the value to add to the JSON array
+    @note This method always returns @ref end() when executed on a JSON type
+          that is not an object.
 
-    @throw type_error.308 when called on a type other than JSON array or
-    null; example: `"cannot use push_back() with number"`
+    @param[in] key key value of the element to search for
 
-    @complexity Amortized constant.
+    @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.
 
-    @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}
+    @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
     */
-    void push_back(basic_json&& val)
+    iterator find(typename object_t::key_type key)
     {
-        // push_back only works for null objects or arrays
-        if (not(is_null() or is_array()))
-        {
-            JSON_THROW(type_error::create(308, "cannot use push_back() with " + type_name()));
-        }
+        auto result = end();
 
-        // transform null object into an array
-        if (is_null())
+        if (is_object())
         {
-            m_type = value_t::array;
-            m_value = value_t::array;
-            assert_invariant();
+            result.m_it.object_iterator = m_value.object->find(key);
         }
 
-        // 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;
+        return result;
     }
 
     /*!
-    @brief add an object to an array
-    @copydoc push_back(basic_json&&)
+    @brief find an element in a JSON object
+    @copydoc find(typename object_t::key_type)
     */
-    void push_back(const basic_json& val)
+    const_iterator find(typename object_t::key_type key) const
     {
-        // push_back only works for null objects or arrays
-        if (not(is_null() or is_array()))
-        {
-            JSON_THROW(type_error::create(308, "cannot use push_back() with " + type_name()));
-        }
+        auto result = cend();
 
-        // transform null object into an array
-        if (is_null())
+        if (is_object())
         {
-            m_type = value_t::array;
-            m_value = value_t::array;
-            assert_invariant();
+            result.m_it.object_iterator = m_value.object->find(key);
         }
 
-        // add element to array
-        m_value.array->push_back(val);
+        return result;
     }
 
     /*!
-    @brief add an object to an array
-    @copydoc push_back(basic_json&&)
-    */
-    reference operator+=(const basic_json& val)
-    {
-        push_back(val);
-        return *this;
-    }
+    @brief returns the number of occurrences of a key in a JSON object
 
-    /*!
-    @brief add an object to an 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).
 
-    Inserts the given element @a val to the JSON object. If the function is
-    called on a JSON null value, an empty object is created before inserting
-    @a val.
+    @note This method always returns `0` when executed on a JSON type that is
+          not an object.
 
-    @param[in] val the value to add to the JSON object
+    @param[in] key key value of the element to count
 
-    @throw type_error.308 when called on a type other than JSON object or
-    null; example: `"cannot use push_back() with number"`
+    @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 container, O(log(`size()`)).
+    @complexity Logarithmic in the size of the JSON object.
 
-    @liveexample{The example shows how `push_back()` and `+=` can be used to
-    add elements to a JSON object. Note how the `null` value was silently
-    converted to a JSON object.,push_back__object_t__value}
+    @liveexample{The example shows how `count()` is used.,count}
 
     @since version 1.0.0
     */
-    void push_back(const typename object_t::value_type& val)
+    size_type count(typename object_t::key_type key) const
     {
-        // push_back only works for null objects or objects
-        if (not(is_null() or is_object()))
-        {
-            JSON_THROW(type_error::create(308, "cannot use push_back() with " + type_name()));
-        }
+        // return 0 for all nonobject types
+        return is_object() ? m_value.object->count(key) : 0;
+    }
 
-        // transform null object into an object
-        if (is_null())
-        {
-            m_type = value_t::object;
-            m_value = value_t::object;
-            assert_invariant();
-        }
+    /// @}
 
-        // add element to array
-        m_value.object->insert(val);
-    }
 
-    /*!
-    @brief add an object to an object
-    @copydoc push_back(const typename object_t::value_type&)
-    */
-    reference operator+=(const typename object_t::value_type& val)
-    {
-        push_back(val);
-        return *this;
-    }
+    ///////////////
+    // iterators //
+    ///////////////
+
+    /// @name iterators
+    /// @{
 
     /*!
-    @brief add an object to an object
+    @brief returns an iterator to the first element
 
-    This function allows to use `push_back` with an initializer list. In case
+    Returns an iterator to the first element.
 
-    1. the current value is an object,
-    2. the initializer list @a init contains only two elements, and
-    3. the first element of @a init is a string,
+    @image html range-begin-end.svg "Illustration from cppreference.com"
 
-    @a init is converted into an object element and added using
-    @ref push_back(const typename object_t::value_type&). Otherwise, @a init
-    is converted to a JSON value and added using @ref push_back(basic_json&&).
+    @return iterator to the first element
 
-    @param[in] init  an initializer list
+    @complexity Constant.
 
-    @complexity Linear in the size of the initializer list @a init.
+    @requirement This function helps `basic_json` satisfying the
+    [Container](http://en.cppreference.com/w/cpp/concept/Container)
+    requirements:
+    - The complexity is constant.
 
-    @note This function is required to resolve an ambiguous overload error,
-          because pairs like `{"key", "value"}` can be both interpreted as
-          `object_t::value_type` or `std::initializer_list<basic_json>`, see
-          https://github.com/nlohmann/json/issues/235 for more information.
+    @liveexample{The following code shows an example for `begin()`.,begin}
 
-    @liveexample{The example shows how initializer lists are treated as
-    objects when possible.,push_back__initializer_list}
+    @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
     */
-    void push_back(std::initializer_list<basic_json> init)
+    iterator begin() noexcept
     {
-        if (is_object() and init.size() == 2 and init.begin()->is_string())
-        {
-            const string_t key = *init.begin();
-            push_back(typename object_t::value_type(key, *(init.begin() + 1)));
-        }
-        else
-        {
-            push_back(basic_json(init));
-        }
+        iterator result(this);
+        result.set_begin();
+        return result;
     }
 
     /*!
-    @brief add an object to an object
-    @copydoc push_back(std::initializer_list<basic_json>)
+    @copydoc basic_json::cbegin()
     */
-    reference operator+=(std::initializer_list<basic_json> init)
+    const_iterator begin() const noexcept
     {
-        push_back(init);
-        return *this;
+        return cbegin();
     }
 
     /*!
-    @brief add an object to an array
+    @brief returns a const iterator to the first element
 
-    Creates a JSON value from the passed parameters @a args to the end of the
-    JSON value. If the function is called on a JSON null value, an empty array
-    is created before appending the value created from @a args.
+    Returns a const iterator to the first element.
 
-    @param[in] args arguments to forward to a constructor of @ref basic_json
-    @tparam Args compatible types to create a @ref basic_json object
+    @image html range-begin-end.svg "Illustration from cppreference.com"
 
-    @throw type_error.311 when called on a type other than JSON array or
-    null; example: `"cannot use emplace_back() with number"`
+    @return const iterator to the first element
 
-    @complexity Amortized constant.
+    @complexity Constant.
 
-    @liveexample{The example shows how `push_back()` can be used to add
-    elements to a JSON array. Note how the `null` value was silently converted
-    to a JSON array.,emplace_back}
+    @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()`.
 
-    @since version 2.0.8
-    */
-    template<class... Args>
-    void emplace_back(Args&& ... args)
-    {
-        // emplace_back only works for null objects or arrays
-        if (not(is_null() or is_array()))
-        {
-            JSON_THROW(type_error::create(311, "cannot use emplace_back() with " + type_name()));
-        }
+    @liveexample{The following code shows an example for `cbegin()`.,cbegin}
 
-        // transform null object into an array
-        if (is_null())
-        {
-            m_type = value_t::array;
-            m_value = value_t::array;
-            assert_invariant();
-        }
+    @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
 
-        // add element to array (perfect forwarding)
-        m_value.array->emplace_back(std::forward<Args>(args)...);
+    @since version 1.0.0
+    */
+    const_iterator cbegin() const noexcept
+    {
+        const_iterator result(this);
+        result.set_begin();
+        return result;
     }
 
     /*!
-    @brief add an object to an object if key does not exist
+    @brief returns an iterator to one past the last element
 
-    Inserts a new element into a JSON object constructed in-place with the
-    given @a args if there is no element with the key in the container. If the
-    function is called on a JSON null value, an empty object is created before
-    appending the value created from @a args.
+    Returns an iterator to one past the last element.
 
-    @param[in] args arguments to forward to a constructor of @ref basic_json
-    @tparam Args compatible types to create a @ref basic_json object
+    @image html range-begin-end.svg "Illustration from cppreference.com"
 
-    @return a pair consisting of an iterator to the inserted element, or the
-            already-existing element if no insertion happened, and a bool
-            denoting whether the insertion took place.
+    @return iterator one past the last element
 
-    @throw type_error.311 when called on a type other than JSON object or
-    null; example: `"cannot use emplace() with number"`
+    @complexity Constant.
 
-    @complexity Logarithmic in the size of the container, O(log(`size()`)).
+    @requirement This function helps `basic_json` satisfying the
+    [Container](http://en.cppreference.com/w/cpp/concept/Container)
+    requirements:
+    - The complexity is constant.
 
-    @liveexample{The example shows how `emplace()` can be used to add elements
-    to a JSON object. Note how the `null` value was silently converted to a
-    JSON object. Further note how no value is added if there was already one
-    value stored with the same key.,emplace}
+    @liveexample{The following code shows an example for `end()`.,end}
 
-    @since version 2.0.8
+    @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
     */
-    template<class... Args>
-    std::pair<iterator, bool> emplace(Args&& ... args)
+    iterator end() noexcept
     {
-        // emplace only works for null objects or arrays
-        if (not(is_null() or is_object()))
-        {
-            JSON_THROW(type_error::create(311, "cannot use emplace() with " + type_name()));
-        }
-
-        // transform null object into an object
-        if (is_null())
-        {
-            m_type = value_t::object;
-            m_value = value_t::object;
-            assert_invariant();
-        }
-
-        // add element to array (perfect forwarding)
-        auto res = m_value.object->emplace(std::forward<Args>(args)...);
-        // create result iterator and set iterator to the result of emplace
-        auto it = begin();
-        it.m_it.object_iterator = res.first;
-
-        // return pair of iterator and boolean
-        return {it, res.second};
+        iterator result(this);
+        result.set_end();
+        return result;
     }
 
     /*!
-    @brief inserts element
+    @copydoc basic_json::cend()
+    */
+    const_iterator end() const noexcept
+    {
+        return cend();
+    }
 
-    Inserts element @a val before iterator @a pos.
+    /*!
+    @brief returns a const iterator to one past the last element
 
-    @param[in] pos iterator before which the content will be inserted; may be
-    the end() iterator
-    @param[in] val element to insert
-    @return iterator pointing to the inserted @a val.
+    Returns a const iterator to one past the last element.
 
-    @throw type_error.309 if called on JSON values other than arrays;
-    example: `"cannot use insert() with string"`
-    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
-    example: `"iterator does not fit current value"`
+    @image html range-begin-end.svg "Illustration from cppreference.com"
 
-    @complexity Constant plus linear in the distance between @a pos and end of
-    the container.
+    @return const iterator one past the last element
 
-    @liveexample{The example shows how `insert()` is used.,insert}
+    @complexity Constant.
 
-    @since version 1.0.0
-    */
-    iterator insert(const_iterator pos, const basic_json& val)
-    {
-        // insert only works for arrays
-        if (is_array())
-        {
-            // check if iterator pos fits to this JSON value
-            if (pos.m_object != this)
-            {
-                JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
-            }
+    @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()`.
 
-            // insert to array and return iterator
-            iterator result(this);
-            result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, val);
-            return result;
-        }
+    @liveexample{The following code shows an example for `cend()`.,cend}
 
-        JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
-    }
+    @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
 
-    /*!
-    @brief inserts element
-    @copydoc insert(const_iterator, const basic_json&)
+    @since version 1.0.0
     */
-    iterator insert(const_iterator pos, basic_json&& val)
+    const_iterator cend() const noexcept
     {
-        return insert(pos, val);
+        const_iterator result(this);
+        result.set_end();
+        return result;
     }
 
     /*!
-    @brief inserts elements
+    @brief returns an iterator to the reverse-beginning
 
-    Inserts @a cnt copies of @a val before iterator @a pos.
+    Returns an iterator to the reverse-beginning; that is, the last element.
 
-    @param[in] pos iterator before which the content will be inserted; may be
-    the end() iterator
-    @param[in] cnt number of copies of @a val to insert
-    @param[in] val element to insert
-    @return iterator pointing to the first element inserted, or @a pos if
-    `cnt==0`
+    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
 
-    @throw type_error.309 if called on JSON values other than arrays; example:
-    `"cannot use insert() with string"`
-    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
-    example: `"iterator does not fit current value"`
+    @complexity Constant.
 
-    @complexity Linear in @a cnt plus linear in the distance between @a pos
-    and end of the container.
+    @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 example shows how `insert()` is used.,insert__count}
+    @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
     */
-    iterator insert(const_iterator pos, size_type cnt, const basic_json& val)
+    reverse_iterator rbegin() noexcept
     {
-        // insert only works for arrays
-        if (is_array())
-        {
-            // check if iterator pos fits to this JSON value
-            if (pos.m_object != this)
-            {
-                JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
-            }
-
-            // insert to array and return iterator
-            iterator result(this);
-            result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, cnt, val);
-            return result;
-        }
-
-        JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
+        return reverse_iterator(end());
     }
 
     /*!
-    @brief inserts elements
-
-    Inserts elements from range `[first, last)` before iterator @a pos.
-
-    @param[in] pos iterator before which the content will be inserted; may be
-    the end() iterator
-    @param[in] first begin of the range of elements to insert
-    @param[in] last end of the range of elements to insert
-
-    @throw type_error.309 if called on JSON values other than arrays; example:
-    `"cannot use insert() with string"`
-    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
-    example: `"iterator does not fit current value"`
-    @throw invalid_iterator.210 if @a first and @a last do not belong to the
-    same JSON value; example: `"iterators do not fit"`
-    @throw invalid_iterator.211 if @a first or @a last are iterators into
-    container for which insert is called; example: `"passed iterators may not
-    belong to container"`
-
-    @return iterator pointing to the first element inserted, or @a pos if
-    `first==last`
-
-    @complexity Linear in `std::distance(first, last)` plus linear in the
-    distance between @a pos and end of the container.
-
-    @liveexample{The example shows how `insert()` is used.,insert__range}
-
-    @since version 1.0.0
+    @copydoc basic_json::crbegin()
     */
-    iterator insert(const_iterator pos, const_iterator first, const_iterator last)
+    const_reverse_iterator rbegin() const noexcept
     {
-        // insert only works for arrays
-        if (not is_array())
-        {
-            JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
-        }
-
-        // check if iterator pos fits to this JSON value
-        if (pos.m_object != this)
-        {
-            JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
-        }
-
-        // check if range iterators belong to the same JSON object
-        if (first.m_object != last.m_object)
-        {
-            JSON_THROW(invalid_iterator::create(210, "iterators do not fit"));
-        }
-
-        if (first.m_object == this or last.m_object == this)
-        {
-            JSON_THROW(invalid_iterator::create(211, "passed iterators may not belong to container"));
-        }
-
-        // insert to array and return iterator
-        iterator result(this);
-        result.m_it.array_iterator = m_value.array->insert(
-                                         pos.m_it.array_iterator,
-                                         first.m_it.array_iterator,
-                                         last.m_it.array_iterator);
-        return result;
+        return crbegin();
     }
 
     /*!
-    @brief inserts elements
+    @brief returns an iterator to the reverse-end
 
-    Inserts elements from initializer list @a ilist before iterator @a pos.
+    Returns an iterator to the reverse-end; that is, one before the first
+    element.
 
-    @param[in] pos iterator before which the content will be inserted; may be
-    the end() iterator
-    @param[in] ilist initializer list to insert the values from
+    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
 
-    @throw type_error.309 if called on JSON values other than arrays; example:
-    `"cannot use insert() with string"`
-    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
-    example: `"iterator does not fit current value"`
+    @complexity Constant.
 
-    @return iterator pointing to the first element inserted, or @a pos if
-    `ilist` is empty
+    @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())`.
 
-    @complexity Linear in `ilist.size()` plus linear in the distance between
-    @a pos and end of the container.
+    @liveexample{The following code shows an example for `rend()`.,rend}
 
-    @liveexample{The example shows how `insert()` is used.,insert__ilist}
+    @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
     */
-    iterator insert(const_iterator pos, std::initializer_list<basic_json> ilist)
+    reverse_iterator rend() noexcept
     {
-        // insert only works for arrays
-        if (not is_array())
-        {
-            JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
-        }
-
-        // check if iterator pos fits to this JSON value
-        if (pos.m_object != this)
-        {
-            JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
-        }
+        return reverse_iterator(begin());
+    }
 
-        // insert to array and return iterator
-        iterator result(this);
-        result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, ilist);
-        return result;
+    /*!
+    @copydoc basic_json::crend()
+    */
+    const_reverse_iterator rend() const noexcept
+    {
+        return crend();
     }
 
     /*!
-    @brief inserts elements
+    @brief returns a const reverse iterator to the last element
 
-    Inserts elements from range `[first, last)`.
+    Returns a const iterator to the reverse-beginning; that is, the last
+    element.
 
-    @param[in] first begin of the range of elements to insert
-    @param[in] last end of the range of elements to insert
+    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
 
-    @throw type_error.309 if called on JSON values other than objects; example:
-    `"cannot use insert() with string"`
-    @throw invalid_iterator.202 if iterator @a first or @a last does does not
-    point to an object; example: `"iterators first and last must point to
-    objects"`
-    @throw invalid_iterator.210 if @a first and @a last do not belong to the
-    same JSON value; example: `"iterators do not fit"`
+    @complexity Constant.
 
-    @complexity Logarithmic: `O(N*log(size() + N))`, where `N` is the number
-    of elements to insert.
+    @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 example shows how `insert()` is used.,insert__range_object}
+    @liveexample{The following code shows an example for `crbegin()`.,crbegin}
 
-    @since version 3.0.0
+    @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
     */
-    void insert(const_iterator first, const_iterator last)
+    const_reverse_iterator crbegin() const noexcept
     {
-        // insert only works for objects
-        if (not is_object())
-        {
-            JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
-        }
-
-        // check if range iterators belong to the same JSON object
-        if (first.m_object != last.m_object)
-        {
-            JSON_THROW(invalid_iterator::create(210, "iterators do not fit"));
-        }
-
-        // passed iterators must belong to objects
-        if (not first.m_object->is_object() or not first.m_object->is_object())
-        {
-            JSON_THROW(invalid_iterator::create(202, "iterators first and last must point to objects"));
-        }
-
-        m_value.object->insert(first.m_it.object_iterator, last.m_it.object_iterator);
+        return const_reverse_iterator(cend());
     }
 
     /*!
-    @brief exchanges the values
+    @brief returns a const reverse iterator to one before the first
 
-    Exchanges the contents of the JSON value with those of @a other. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated.
+    Returns a const reverse iterator to the reverse-end; that is, one before
+    the first element.
 
-    @param[in,out] other JSON value to exchange the contents with
+    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
 
     @complexity Constant.
 
-    @liveexample{The example below shows how JSON values can be swapped with
-    `swap()`.,swap__reference}
+    @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
     */
-    void swap(reference other) noexcept (
-        std::is_nothrow_move_constructible<value_t>::value and
-        std::is_nothrow_move_assignable<value_t>::value and
-        std::is_nothrow_move_constructible<json_value>::value and
-        std::is_nothrow_move_assignable<json_value>::value
-    )
+    const_reverse_iterator crend() const noexcept
     {
-        std::swap(m_type, other.m_type);
-        std::swap(m_value, other.m_value);
-        assert_invariant();
+        return const_reverse_iterator(cbegin());
     }
 
+  public:
     /*!
-    @brief exchanges the values
-
-    Exchanges the contents of a JSON array with those of @a other. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated.
-
-    @param[in,out] other array to exchange the contents with
-
-    @throw type_error.310 when JSON value is not an array; example: `"cannot
-    use swap() with string"`
+    @brief wrapper to access iterator member functions in range-based for
 
-    @complexity Constant.
+    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.
 
-    @liveexample{The example below shows how arrays can be swapped with
-    `swap()`.,swap__array_t}
+    @liveexample{The following code shows how the wrapper is used,iterator_wrapper}
 
-    @since version 1.0.0
+    @note The name of this function is not yet final and may change in the
+    future.
     */
-    void swap(array_t& other)
+    static iteration_proxy<iterator> iterator_wrapper(reference cont)
     {
-        // swap only works for arrays
-        if (is_array())
-        {
-            std::swap(*(m_value.array), other);
-        }
-        else
-        {
-            JSON_THROW(type_error::create(310, "cannot use swap() with " + type_name()));
-        }
+        return iteration_proxy<iterator>(cont);
     }
 
     /*!
-    @brief exchanges the values
+    @copydoc iterator_wrapper(reference)
+    */
+    static iteration_proxy<const_iterator> iterator_wrapper(const_reference cont)
+    {
+        return iteration_proxy<const_iterator>(cont);
+    }
 
-    Exchanges the contents of a JSON object with those of @a other. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated.
+    /// @}
 
-    @param[in,out] other object to exchange the contents with
 
-    @throw type_error.310 when JSON value is not an object; example:
-    `"cannot use swap() with string"`
+    //////////////
+    // capacity //
+    //////////////
 
-    @complexity Constant.
+    /// @name capacity
+    /// @{
 
-    @liveexample{The example below shows how objects can be swapped with
-    `swap()`.,swap__object_t}
+    /*!
+    @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
     */
-    void swap(object_t& other)
+    bool empty() const noexcept
     {
-        // swap only works for objects
-        if (is_object())
-        {
-            std::swap(*(m_value.object), other);
-        }
-        else
+        switch (m_type)
         {
-            JSON_THROW(type_error::create(310, "cannot use swap() with " + type_name()));
+            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 exchanges the values
+    @brief returns the number of elements
 
-    Exchanges the contents of a JSON string with those of @a other. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated.
+    Returns the number of elements in a JSON value.
 
-    @param[in,out] other string to exchange the contents with
+    @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()
 
-    @throw type_error.310 when JSON value is not a string; example: `"cannot
-    use swap() with boolean"`
+    @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.
+    @complexity Constant, as long as @ref array_t and @ref object_t satisfy
+    the Container concept; that is, their size() functions have constant
+    complexity.
 
-    @liveexample{The example below shows how strings can be swapped with
-    `swap()`.,swap__string_t}
+    @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
     */
-    void swap(string_t& other)
+    size_type size() const noexcept
     {
-        // swap only works for strings
-        if (is_string())
+        switch (m_type)
         {
-            std::swap(*(m_value.string), other);
+            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;
+            }
         }
-        else
+    }
+
+    /*!
+    @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)
         {
-            JSON_THROW(type_error::create(310, "cannot use swap() with " + type_name()));
+            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();
+            }
         }
     }
 
     /// @}
 
-  public:
-    //////////////////////////////////////////
-    // lexicographical comparison operators //
-    //////////////////////////////////////////
 
-    /// @name lexicographical comparison operators
+    ///////////////
+    // modifiers //
+    ///////////////
+
+    /// @name modifiers
     /// @{
 
     /*!
-    @brief comparison: equal
-
-    Compares two JSON values for equality according to the following rules:
-    - Two JSON values are equal if (1) they are from the same type and (2)
-      their stored values are the same according to their respective
-      `operator==`.
-    - Integer and floating-point numbers are automatically converted before
-      comparison. Note than two NaN values are always treated as unequal.
-    - Two JSON null values are equal.
+    @brief clears the contents
 
-    @note NaN values never compare equal to themselves or to other NaN values.
+    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:
 
-    @param[in] lhs  first JSON value to consider
-    @param[in] rhs  second JSON value to consider
-    @return whether the values @a lhs and @a rhs are equal
+    Value type  | initial value
+    ----------- | -------------
+    null        | `null`
+    boolean     | `false`
+    string      | `""`
+    number      | `0`
+    object      | `{}`
+    array       | `[]`
 
-    @complexity Linear.
+    @complexity Linear in the size of the JSON value.
 
-    @liveexample{The example demonstrates comparing several JSON
-    types.,operator__equal}
+    @liveexample{The example below shows the effect of `clear()` to different
+    JSON types.,clear}
 
     @since version 1.0.0
     */
-    friend bool operator==(const_reference lhs, const_reference rhs) noexcept
+    void clear() noexcept
     {
-        const auto lhs_type = lhs.type();
-        const auto rhs_type = rhs.type();
-
-        if (lhs_type == rhs_type)
+        switch (m_type)
         {
-            switch (lhs_type)
+            case value_t::number_integer:
             {
-                case value_t::array:
-                {
-                    return *lhs.m_value.array == *rhs.m_value.array;
-                }
-                case value_t::object:
-                {
-                    return *lhs.m_value.object == *rhs.m_value.object;
-                }
-                case value_t::null:
-                {
-                    return true;
-                }
-                case value_t::string:
-                {
-                    return *lhs.m_value.string == *rhs.m_value.string;
-                }
-                case value_t::boolean:
-                {
-                    return lhs.m_value.boolean == rhs.m_value.boolean;
-                }
-                case value_t::number_integer:
-                {
-                    return lhs.m_value.number_integer == rhs.m_value.number_integer;
-                }
-                case value_t::number_unsigned:
-                {
-                    return lhs.m_value.number_unsigned == rhs.m_value.number_unsigned;
-                }
-                case value_t::number_float:
-                {
-                    return lhs.m_value.number_float == rhs.m_value.number_float;
-                }
-                default:
-                {
-                    return false;
-                }
+                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;
             }
         }
-        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_float)
-        {
-            return static_cast<number_float_t>(lhs.m_value.number_integer) == rhs.m_value.number_float;
-        }
-        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_integer)
-        {
-            return lhs.m_value.number_float == static_cast<number_float_t>(rhs.m_value.number_integer);
-        }
-        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_float)
-        {
-            return static_cast<number_float_t>(lhs.m_value.number_unsigned) == rhs.m_value.number_float;
-        }
-        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_unsigned)
-        {
-            return lhs.m_value.number_float == static_cast<number_float_t>(rhs.m_value.number_unsigned);
-        }
-        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_integer)
+    }
+
+    /*!
+    @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 type_error.308 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()))
         {
-            return static_cast<number_integer_t>(lhs.m_value.number_unsigned) == rhs.m_value.number_integer;
+            JSON_THROW(type_error::create(308, "cannot use push_back() with " + type_name()));
         }
-        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_unsigned)
+
+        // transform null object into an array
+        if (is_null())
         {
-            return lhs.m_value.number_integer == static_cast<number_integer_t>(rhs.m_value.number_unsigned);
+            m_type = value_t::array;
+            m_value = value_t::array;
+            assert_invariant();
         }
 
-        return false;
+        // add element to array (move semantics)
+        m_value.array->push_back(std::move(val));
+        // invalidate object
+        val.m_type = value_t::null;
     }
 
     /*!
-    @brief comparison: equal
-    @copydoc operator==(const_reference, const_reference)
+    @brief add an object to an array
+    @copydoc push_back(basic_json&&)
     */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator==(const_reference lhs, const ScalarType rhs) noexcept
+    reference operator+=(basic_json&& val)
     {
-        return (lhs == basic_json(rhs));
+        push_back(std::move(val));
+        return *this;
     }
 
     /*!
-    @brief comparison: equal
-    @copydoc operator==(const_reference, const_reference)
+    @brief add an object to an array
+    @copydoc push_back(basic_json&&)
     */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator==(const ScalarType lhs, const_reference rhs) noexcept
+    void push_back(const basic_json& val)
     {
-        return (basic_json(lhs) == rhs);
+        // push_back only works for null objects or arrays
+        if (not(is_null() or is_array()))
+        {
+            JSON_THROW(type_error::create(308, "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
+        m_value.array->push_back(val);
     }
 
     /*!
-    @brief comparison: not equal
+    @brief add an object to an array
+    @copydoc push_back(basic_json&&)
+    */
+    reference operator+=(const basic_json& val)
+    {
+        push_back(val);
+        return *this;
+    }
 
-    Compares two JSON values for inequality by calculating `not (lhs == rhs)`.
+    /*!
+    @brief add an object to an object
 
-    @param[in] lhs  first JSON value to consider
-    @param[in] rhs  second JSON value to consider
-    @return whether the values @a lhs and @a rhs are not equal
+    Inserts the given element @a val to the JSON object. If the function is
+    called on a JSON null value, an empty object is created before inserting
+    @a val.
 
-    @complexity Linear.
+    @param[in] val the value to add to the JSON object
 
-    @liveexample{The example demonstrates comparing several JSON
-    types.,operator__notequal}
+    @throw type_error.308 when called on a type other than JSON object or
+    null; example: `"cannot use push_back() with number"`
+
+    @complexity Logarithmic in the size of the container, O(log(`size()`)).
+
+    @liveexample{The example shows how `push_back()` and `+=` can be used to
+    add elements to a JSON object. Note how the `null` value was silently
+    converted to a JSON object.,push_back__object_t__value}
 
     @since version 1.0.0
     */
-    friend bool operator!=(const_reference lhs, const_reference rhs) noexcept
+    void push_back(const typename object_t::value_type& val)
     {
-        return not (lhs == rhs);
-    }
+        // push_back only works for null objects or objects
+        if (not(is_null() or is_object()))
+        {
+            JSON_THROW(type_error::create(308, "cannot use push_back() with " + type_name()));
+        }
 
-    /*!
-    @brief comparison: not equal
-    @copydoc operator!=(const_reference, const_reference)
-    */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator!=(const_reference lhs, const ScalarType rhs) noexcept
-    {
-        return (lhs != basic_json(rhs));
+        // transform null object into an object
+        if (is_null())
+        {
+            m_type = value_t::object;
+            m_value = value_t::object;
+            assert_invariant();
+        }
+
+        // add element to array
+        m_value.object->insert(val);
     }
 
     /*!
-    @brief comparison: not equal
-    @copydoc operator!=(const_reference, const_reference)
+    @brief add an object to an object
+    @copydoc push_back(const typename object_t::value_type&)
     */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator!=(const ScalarType lhs, const_reference rhs) noexcept
+    reference operator+=(const typename object_t::value_type& val)
     {
-        return (basic_json(lhs) != rhs);
+        push_back(val);
+        return *this;
     }
 
     /*!
-    @brief comparison: less than
+    @brief add an object to an object
 
-    Compares whether one JSON value @a lhs is less than another JSON value @a
-    rhs according to the following rules:
-    - If @a lhs and @a rhs have the same type, the values are compared using
-      the default `<` operator.
-    - Integer and floating-point numbers are automatically converted before
-      comparison
-    - In case @a lhs and @a rhs have different types, the values are ignored
-      and the order of the types is considered, see
-      @ref operator<(const value_t, const value_t).
+    This function allows to use `push_back` with an initializer list. In case
 
-    @param[in] lhs  first JSON value to consider
-    @param[in] rhs  second JSON value to consider
-    @return whether @a lhs is less than @a rhs
+    1. the current value is an object,
+    2. the initializer list @a init contains only two elements, and
+    3. the first element of @a init is a string,
 
-    @complexity Linear.
+    @a init is converted into an object element and added using
+    @ref push_back(const typename object_t::value_type&). Otherwise, @a init
+    is converted to a JSON value and added using @ref push_back(basic_json&&).
 
-    @liveexample{The example demonstrates comparing several JSON
-    types.,operator__less}
+    @param[in] init  an initializer list
 
-    @since version 1.0.0
+    @complexity Linear in the size of the initializer list @a init.
+
+    @note This function is required to resolve an ambiguous overload error,
+          because pairs like `{"key", "value"}` can be both interpreted as
+          `object_t::value_type` or `std::initializer_list<basic_json>`, see
+          https://github.com/nlohmann/json/issues/235 for more information.
+
+    @liveexample{The example shows how initializer lists are treated as
+    objects when possible.,push_back__initializer_list}
     */
-    friend bool operator<(const_reference lhs, const_reference rhs) noexcept
+    void push_back(std::initializer_list<basic_json> init)
     {
-        const auto lhs_type = lhs.type();
-        const auto rhs_type = rhs.type();
-
-        if (lhs_type == rhs_type)
-        {
-            switch (lhs_type)
-            {
-                case value_t::array:
-                {
-                    return (*lhs.m_value.array) < (*rhs.m_value.array);
-                }
-                case value_t::object:
-                {
-                    return *lhs.m_value.object < *rhs.m_value.object;
-                }
-                case value_t::null:
-                {
-                    return false;
-                }
-                case value_t::string:
-                {
-                    return *lhs.m_value.string < *rhs.m_value.string;
-                }
-                case value_t::boolean:
-                {
-                    return lhs.m_value.boolean < rhs.m_value.boolean;
-                }
-                case value_t::number_integer:
-                {
-                    return lhs.m_value.number_integer < rhs.m_value.number_integer;
-                }
-                case value_t::number_unsigned:
-                {
-                    return lhs.m_value.number_unsigned < rhs.m_value.number_unsigned;
-                }
-                case value_t::number_float:
-                {
-                    return lhs.m_value.number_float < rhs.m_value.number_float;
-                }
-                default:
-                {
-                    return false;
-                }
-            }
-        }
-        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_float)
-        {
-            return static_cast<number_float_t>(lhs.m_value.number_integer) < rhs.m_value.number_float;
-        }
-        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_integer)
-        {
-            return lhs.m_value.number_float < static_cast<number_float_t>(rhs.m_value.number_integer);
-        }
-        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_float)
-        {
-            return static_cast<number_float_t>(lhs.m_value.number_unsigned) < rhs.m_value.number_float;
-        }
-        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_unsigned)
-        {
-            return lhs.m_value.number_float < static_cast<number_float_t>(rhs.m_value.number_unsigned);
-        }
-        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_unsigned)
+        if (is_object() and init.size() == 2 and init.begin()->is_string())
         {
-            return lhs.m_value.number_integer < static_cast<number_integer_t>(rhs.m_value.number_unsigned);
+            const string_t key = *init.begin();
+            push_back(typename object_t::value_type(key, *(init.begin() + 1)));
         }
-        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_integer)
+        else
         {
-            return static_cast<number_integer_t>(lhs.m_value.number_unsigned) < rhs.m_value.number_integer;
+            push_back(basic_json(init));
         }
-
-        // We only reach this line if we cannot compare values. In that case,
-        // we compare types. Note we have to call the operator explicitly,
-        // because MSVC has problems otherwise.
-        return operator<(lhs_type, rhs_type);
     }
 
     /*!
-    @brief comparison: less than
-    @copydoc operator<(const_reference, const_reference)
+    @brief add an object to an object
+    @copydoc push_back(std::initializer_list<basic_json>)
     */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator<(const_reference lhs, const ScalarType rhs) noexcept
+    reference operator+=(std::initializer_list<basic_json> init)
     {
-        return (lhs < basic_json(rhs));
+        push_back(init);
+        return *this;
     }
 
     /*!
-    @brief comparison: less than
-    @copydoc operator<(const_reference, const_reference)
-    */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator<(const ScalarType lhs, const_reference rhs) noexcept
-    {
-        return (basic_json(lhs) < rhs);
-    }
+    @brief add an object to an array
 
-    /*!
-    @brief comparison: less than or equal
+    Creates a JSON value from the passed parameters @a args to the end of the
+    JSON value. If the function is called on a JSON null value, an empty array
+    is created before appending the value created from @a args.
 
-    Compares whether one JSON value @a lhs is less than or equal to another
-    JSON value by calculating `not (rhs < lhs)`.
+    @param[in] args arguments to forward to a constructor of @ref basic_json
+    @tparam Args compatible types to create a @ref basic_json object
 
-    @param[in] lhs  first JSON value to consider
-    @param[in] rhs  second JSON value to consider
-    @return whether @a lhs is less than or equal to @a rhs
+    @throw type_error.311 when called on a type other than JSON array or
+    null; example: `"cannot use emplace_back() with number"`
 
-    @complexity Linear.
+    @complexity Amortized constant.
 
-    @liveexample{The example demonstrates comparing several JSON
-    types.,operator__greater}
+    @liveexample{The example shows how `push_back()` can be used to add
+    elements to a JSON array. Note how the `null` value was silently converted
+    to a JSON array.,emplace_back}
 
-    @since version 1.0.0
+    @since version 2.0.8
     */
-    friend bool operator<=(const_reference lhs, const_reference rhs) noexcept
+    template<class... Args>
+    void emplace_back(Args&& ... args)
     {
-        return not (rhs < lhs);
-    }
+        // emplace_back only works for null objects or arrays
+        if (not(is_null() or is_array()))
+        {
+            JSON_THROW(type_error::create(311, "cannot use emplace_back() with " + type_name()));
+        }
 
-    /*!
-    @brief comparison: less than or equal
-    @copydoc operator<=(const_reference, const_reference)
-    */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator<=(const_reference lhs, const ScalarType rhs) noexcept
-    {
-        return (lhs <= basic_json(rhs));
-    }
+        // transform null object into an array
+        if (is_null())
+        {
+            m_type = value_t::array;
+            m_value = value_t::array;
+            assert_invariant();
+        }
 
-    /*!
-    @brief comparison: less than or equal
-    @copydoc operator<=(const_reference, const_reference)
-    */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator<=(const ScalarType lhs, const_reference rhs) noexcept
-    {
-        return (basic_json(lhs) <= rhs);
+        // add element to array (perfect forwarding)
+        m_value.array->emplace_back(std::forward<Args>(args)...);
     }
 
     /*!
-    @brief comparison: greater than
+    @brief add an object to an object if key does not exist
 
-    Compares whether one JSON value @a lhs is greater than another
-    JSON value by calculating `not (lhs <= rhs)`.
+    Inserts a new element into a JSON object constructed in-place with the
+    given @a args if there is no element with the key in the container. If the
+    function is called on a JSON null value, an empty object is created before
+    appending the value created from @a args.
 
-    @param[in] lhs  first JSON value to consider
-    @param[in] rhs  second JSON value to consider
-    @return whether @a lhs is greater than to @a rhs
+    @param[in] args arguments to forward to a constructor of @ref basic_json
+    @tparam Args compatible types to create a @ref basic_json object
 
-    @complexity Linear.
+    @return a pair consisting of an iterator to the inserted element, or the
+            already-existing element if no insertion happened, and a bool
+            denoting whether the insertion took place.
 
-    @liveexample{The example demonstrates comparing several JSON
-    types.,operator__lessequal}
+    @throw type_error.311 when called on a type other than JSON object or
+    null; example: `"cannot use emplace() with number"`
 
-    @since version 1.0.0
-    */
-    friend bool operator>(const_reference lhs, const_reference rhs) noexcept
-    {
-        return not (lhs <= rhs);
-    }
+    @complexity Logarithmic in the size of the container, O(log(`size()`)).
 
-    /*!
-    @brief comparison: greater than
-    @copydoc operator>(const_reference, const_reference)
-    */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator>(const_reference lhs, const ScalarType rhs) noexcept
-    {
-        return (lhs > basic_json(rhs));
-    }
+    @liveexample{The example shows how `emplace()` can be used to add elements
+    to a JSON object. Note how the `null` value was silently converted to a
+    JSON object. Further note how no value is added if there was already one
+    value stored with the same key.,emplace}
 
-    /*!
-    @brief comparison: greater than
-    @copydoc operator>(const_reference, const_reference)
+    @since version 2.0.8
     */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator>(const ScalarType lhs, const_reference rhs) noexcept
+    template<class... Args>
+    std::pair<iterator, bool> emplace(Args&& ... args)
     {
-        return (basic_json(lhs) > rhs);
-    }
+        // emplace only works for null objects or arrays
+        if (not(is_null() or is_object()))
+        {
+            JSON_THROW(type_error::create(311, "cannot use emplace() with " + type_name()));
+        }
 
-    /*!
-    @brief comparison: greater than or equal
+        // transform null object into an object
+        if (is_null())
+        {
+            m_type = value_t::object;
+            m_value = value_t::object;
+            assert_invariant();
+        }
 
-    Compares whether one JSON value @a lhs is greater than or equal to another
-    JSON value by calculating `not (lhs < rhs)`.
+        // add element to array (perfect forwarding)
+        auto res = m_value.object->emplace(std::forward<Args>(args)...);
+        // create result iterator and set iterator to the result of emplace
+        auto it = begin();
+        it.m_it.object_iterator = res.first;
 
-    @param[in] lhs  first JSON value to consider
-    @param[in] rhs  second JSON value to consider
-    @return whether @a lhs is greater than or equal to @a rhs
+        // return pair of iterator and boolean
+        return {it, res.second};
+    }
 
-    @complexity Linear.
+    /*!
+    @brief inserts element
 
-    @liveexample{The example demonstrates comparing several JSON
-    types.,operator__greaterequal}
+    Inserts element @a val before iterator @a pos.
+
+    @param[in] pos iterator before which the content will be inserted; may be
+    the end() iterator
+    @param[in] val element to insert
+    @return iterator pointing to the inserted @a val.
+
+    @throw type_error.309 if called on JSON values other than arrays;
+    example: `"cannot use insert() with string"`
+    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
+    example: `"iterator does not fit current value"`
+
+    @complexity Constant plus linear in the distance between @a pos and end of
+    the container.
+
+    @liveexample{The example shows how `insert()` is used.,insert}
 
     @since version 1.0.0
     */
-    friend bool operator>=(const_reference lhs, const_reference rhs) noexcept
+    iterator insert(const_iterator pos, const basic_json& val)
     {
-        return not (lhs < rhs);
+        // insert only works for arrays
+        if (is_array())
+        {
+            // check if iterator pos fits to this JSON value
+            if (pos.m_object != this)
+            {
+                JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
+            }
+
+            // insert to array and return iterator
+            iterator result(this);
+            result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, val);
+            return result;
+        }
+
+        JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
     }
 
     /*!
-    @brief comparison: greater than or equal
-    @copydoc operator>=(const_reference, const_reference)
+    @brief inserts element
+    @copydoc insert(const_iterator, const basic_json&)
     */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator>=(const_reference lhs, const ScalarType rhs) noexcept
+    iterator insert(const_iterator pos, basic_json&& val)
     {
-        return (lhs >= basic_json(rhs));
+        return insert(pos, val);
     }
 
     /*!
-    @brief comparison: greater than or equal
-    @copydoc operator>=(const_reference, const_reference)
+    @brief inserts elements
+
+    Inserts @a cnt copies of @a val before iterator @a pos.
+
+    @param[in] pos iterator before which the content will be inserted; may be
+    the end() iterator
+    @param[in] cnt number of copies of @a val to insert
+    @param[in] val element to insert
+    @return iterator pointing to the first element inserted, or @a pos if
+    `cnt==0`
+
+    @throw type_error.309 if called on JSON values other than arrays; example:
+    `"cannot use insert() with string"`
+    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
+    example: `"iterator does not fit current value"`
+
+    @complexity Linear in @a cnt plus linear in the distance between @a pos
+    and end of the container.
+
+    @liveexample{The example shows how `insert()` is used.,insert__count}
+
+    @since version 1.0.0
     */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator>=(const ScalarType lhs, const_reference rhs) noexcept
+    iterator insert(const_iterator pos, size_type cnt, const basic_json& val)
     {
-        return (basic_json(lhs) >= rhs);
+        // insert only works for arrays
+        if (is_array())
+        {
+            // check if iterator pos fits to this JSON value
+            if (pos.m_object != this)
+            {
+                JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
+            }
+
+            // insert to array and return iterator
+            iterator result(this);
+            result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, cnt, val);
+            return result;
+        }
+
+        JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
     }
 
-    /// @}
+    /*!
+    @brief inserts elements
 
-  private:
-    /////////////////////
-    // output adapters //
-    /////////////////////
+    Inserts elements from range `[first, last)` before iterator @a pos.
 
-    /// abstract output adapter interface
-    template<typename CharType>
-    class output_adapter
-    {
-      public:
-        virtual void write_character(CharType c) = 0;
-        virtual void write_characters(const CharType* s, size_t length) = 0;
-        virtual ~output_adapter() {}
+    @param[in] pos iterator before which the content will be inserted; may be
+    the end() iterator
+    @param[in] first begin of the range of elements to insert
+    @param[in] last end of the range of elements to insert
 
-        static std::shared_ptr<output_adapter<CharType>> create(std::vector<CharType>& vec)
-        {
-            return std::make_shared<output_vector_adapter<CharType>>(vec);
-        }
+    @throw type_error.309 if called on JSON values other than arrays; example:
+    `"cannot use insert() with string"`
+    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
+    example: `"iterator does not fit current value"`
+    @throw invalid_iterator.210 if @a first and @a last do not belong to the
+    same JSON value; example: `"iterators do not fit"`
+    @throw invalid_iterator.211 if @a first or @a last are iterators into
+    container for which insert is called; example: `"passed iterators may not
+    belong to container"`
 
-        static std::shared_ptr<output_adapter<CharType>> create(std::ostream& s)
-        {
-            return std::make_shared<output_stream_adapter<CharType>>(s);
-        }
+    @return iterator pointing to the first element inserted, or @a pos if
+    `first==last`
 
-        static std::shared_ptr<output_adapter<CharType>> create(std::string& s)
-        {
-            return std::make_shared<output_string_adapter<CharType>>(s);
-        }
-    };
+    @complexity Linear in `std::distance(first, last)` plus linear in the
+    distance between @a pos and end of the container.
 
-    /// a type to simplify interfaces
-    template<typename CharType>
-    using output_adapter_t = std::shared_ptr<output_adapter<CharType>>;
+    @liveexample{The example shows how `insert()` is used.,insert__range}
 
-    /// output adapter for byte vectors
-    template<typename CharType>
-    class output_vector_adapter : public output_adapter<CharType>
+    @since version 1.0.0
+    */
+    iterator insert(const_iterator pos, const_iterator first, const_iterator last)
     {
-      public:
-        output_vector_adapter(std::vector<CharType>& vec)
-            : v(vec)
-        {}
-
-        void write_character(CharType c) override
+        // insert only works for arrays
+        if (not is_array())
         {
-            v.push_back(c);
+            JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
         }
 
-        void write_characters(const CharType* s, size_t length) override
+        // check if iterator pos fits to this JSON value
+        if (pos.m_object != this)
         {
-            std::copy(s, s + length, std::back_inserter(v));
+            JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
         }
 
-      private:
-        std::vector<CharType>& v;
-    };
-
-    /// output adapter for output streams
-    template<typename CharType>
-    class output_stream_adapter : public output_adapter<CharType>
-    {
-      public:
-        output_stream_adapter(std::basic_ostream<CharType>& s)
-            : stream(s)
-        {}
-
-        void write_character(CharType c) override
+        // check if range iterators belong to the same JSON object
+        if (first.m_object != last.m_object)
         {
-            stream.put(c);
+            JSON_THROW(invalid_iterator::create(210, "iterators do not fit"));
         }
 
-        void write_characters(const CharType* s, size_t length) override
+        if (first.m_object == this or last.m_object == this)
         {
-            stream.write(s, static_cast<std::streamsize>(length));
+            JSON_THROW(invalid_iterator::create(211, "passed iterators may not belong to container"));
         }
 
-      private:
-        std::basic_ostream<CharType>& stream;
-    };
+        // insert to array and return iterator
+        iterator result(this);
+        result.m_it.array_iterator = m_value.array->insert(
+                                         pos.m_it.array_iterator,
+                                         first.m_it.array_iterator,
+                                         last.m_it.array_iterator);
+        return result;
+    }
 
-    /// output adapter for basic_string
-    template<typename CharType>
-    class output_string_adapter : public output_adapter<CharType>
-    {
-      public:
-        output_string_adapter(std::string& s)
-            : str(s)
-        {}
+    /*!
+    @brief inserts elements
 
-        void write_character(CharType c) override
+    Inserts elements from initializer list @a ilist before iterator @a pos.
+
+    @param[in] pos iterator before which the content will be inserted; may be
+    the end() iterator
+    @param[in] ilist initializer list to insert the values from
+
+    @throw type_error.309 if called on JSON values other than arrays; example:
+    `"cannot use insert() with string"`
+    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
+    example: `"iterator does not fit current value"`
+
+    @return iterator pointing to the first element inserted, or @a pos if
+    `ilist` is empty
+
+    @complexity Linear in `ilist.size()` plus linear in the distance between
+    @a pos and end of the container.
+
+    @liveexample{The example shows how `insert()` is used.,insert__ilist}
+
+    @since version 1.0.0
+    */
+    iterator insert(const_iterator pos, std::initializer_list<basic_json> ilist)
+    {
+        // insert only works for arrays
+        if (not is_array())
         {
-            str.push_back(c);
+            JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
         }
 
-        void write_characters(const CharType* s, size_t length) override
+        // check if iterator pos fits to this JSON value
+        if (pos.m_object != this)
         {
-            str.append(s, length);
+            JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
         }
 
-      private:
-        std::basic_string<CharType>& str;
-    };
+        // insert to array and return iterator
+        iterator result(this);
+        result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, ilist);
+        return result;
+    }
 
+    /*!
+    @brief inserts elements
 
-    ///////////////////
-    // serialization //
-    ///////////////////
+    Inserts elements from range `[first, last)`.
 
-    /// @name serialization
-    /// @{
+    @param[in] first begin of the range of elements to insert
+    @param[in] last end of the range of elements to insert
 
-  private:
-    /*!
-    @brief wrapper around the serialization functions
-    */
-    class serializer
-    {
-      public:
-        /*!
-        @param[in] s  output stream to serialize to
-        @param[in] ichar  indentation character to use
-        */
-        serializer(output_adapter_t<char> s, const char ichar)
-            : o(s), loc(std::localeconv()),
-              thousands_sep(!loc->thousands_sep ? '\0' : loc->thousands_sep[0]),
-              decimal_point(!loc->decimal_point ? '\0' : loc->decimal_point[0]),
-              indent_char(ichar), indent_string(512, indent_char)
-        {}
+    @throw type_error.309 if called on JSON values other than objects; example:
+    `"cannot use insert() with string"`
+    @throw invalid_iterator.202 if iterator @a first or @a last does does not
+    point to an object; example: `"iterators first and last must point to
+    objects"`
+    @throw invalid_iterator.210 if @a first and @a last do not belong to the
+    same JSON value; example: `"iterators do not fit"`
 
-        // delete because of pointer members
-        serializer(const serializer&) = delete;
-        serializer& operator=(const serializer&) = delete;
+    @complexity Logarithmic: `O(N*log(size() + N))`, where `N` is the number
+    of elements to insert.
 
-        /*!
-        @brief internal implementation of the serialization function
+    @liveexample{The example shows how `insert()` is used.,insert__range_object}
 
-        This function is called by the public member function dump and
-        organizes the serialization internally. The indentation level is
-        propagated as additional parameter. In case of arrays and objects, the
-        function is called recursively.
+    @since version 3.0.0
+    */
+    void insert(const_iterator first, const_iterator last)
+    {
+        // insert only works for objects
+        if (not is_object())
+        {
+            JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
+        }
 
-        - strings and object keys are escaped using `escape_string()`
-        - integer numbers are converted implicitly via `operator<<`
-        - floating-point numbers are converted to a string using `"%g"` format
+        // check if range iterators belong to the same JSON object
+        if (first.m_object != last.m_object)
+        {
+            JSON_THROW(invalid_iterator::create(210, "iterators do not fit"));
+        }
 
-        @param[in] val             value to serialize
-        @param[in] pretty_print    whether the output shall be pretty-printed
-        @param[in] indent_step     the indent level
-        @param[in] current_indent  the current indent level (only used internally)
-        */
-        void dump(const basic_json& val,
-                  const bool pretty_print,
-                  const unsigned int indent_step,
-                  const unsigned int current_indent = 0)
+        // passed iterators must belong to objects
+        if (not first.m_object->is_object() or not first.m_object->is_object())
         {
-            switch (val.m_type)
-            {
-                case value_t::object:
-                {
-                    if (val.m_value.object->empty())
-                    {
-                        o->write_characters("{}", 2);
-                        return;
-                    }
+            JSON_THROW(invalid_iterator::create(202, "iterators first and last must point to objects"));
+        }
 
-                    if (pretty_print)
-                    {
-                        o->write_characters("{\n", 2);
+        m_value.object->insert(first.m_it.object_iterator, last.m_it.object_iterator);
+    }
 
-                        // variable to hold indentation for recursive calls
-                        const auto new_indent = current_indent + indent_step;
-                        if (JSON_UNLIKELY(indent_string.size() < new_indent))
-                        {
-                            indent_string.resize(indent_string.size() * 2, ' ');
-                        }
+    /*!
+    @brief exchanges the values
 
-                        // first n-1 elements
-                        auto i = val.m_value.object->cbegin();
-                        for (size_t cnt = 0; cnt < val.m_value.object->size() - 1; ++cnt, ++i)
-                        {
-                            o->write_characters(indent_string.c_str(), new_indent);
-                            o->write_character('\"');
-                            dump_escaped(i->first);
-                            o->write_characters("\": ", 3);
-                            dump(i->second, true, indent_step, new_indent);
-                            o->write_characters(",\n", 2);
-                        }
+    Exchanges the contents of the JSON value with those of @a other. Does not
+    invoke any move, copy, or swap operations on individual elements. All
+    iterators and references remain valid. The past-the-end iterator is
+    invalidated.
 
-                        // last element
-                        assert(i != val.m_value.object->cend());
-                        o->write_characters(indent_string.c_str(), new_indent);
-                        o->write_character('\"');
-                        dump_escaped(i->first);
-                        o->write_characters("\": ", 3);
-                        dump(i->second, true, indent_step, new_indent);
+    @param[in,out] other JSON value to exchange the contents with
 
-                        o->write_character('\n');
-                        o->write_characters(indent_string.c_str(), current_indent);
-                        o->write_character('}');
-                    }
-                    else
-                    {
-                        o->write_character('{');
+    @complexity Constant.
 
-                        // first n-1 elements
-                        auto i = val.m_value.object->cbegin();
-                        for (size_t cnt = 0; cnt < val.m_value.object->size() - 1; ++cnt, ++i)
-                        {
-                            o->write_character('\"');
-                            dump_escaped(i->first);
-                            o->write_characters("\":", 2);
-                            dump(i->second, false, indent_step, current_indent);
-                            o->write_character(',');
-                        }
+    @liveexample{The example below shows how JSON values can be swapped with
+    `swap()`.,swap__reference}
 
-                        // last element
-                        assert(i != val.m_value.object->cend());
-                        o->write_character('\"');
-                        dump_escaped(i->first);
-                        o->write_characters("\":", 2);
-                        dump(i->second, false, indent_step, current_indent);
+    @since version 1.0.0
+    */
+    void swap(reference other) noexcept (
+        std::is_nothrow_move_constructible<value_t>::value and
+        std::is_nothrow_move_assignable<value_t>::value and
+        std::is_nothrow_move_constructible<json_value>::value and
+        std::is_nothrow_move_assignable<json_value>::value
+    )
+    {
+        std::swap(m_type, other.m_type);
+        std::swap(m_value, other.m_value);
+        assert_invariant();
+    }
 
-                        o->write_character('}');
-                    }
+    /*!
+    @brief exchanges the values
 
-                    return;
-                }
+    Exchanges the contents of a JSON array with those of @a other. Does not
+    invoke any move, copy, or swap operations on individual elements. All
+    iterators and references remain valid. The past-the-end iterator is
+    invalidated.
 
-                case value_t::array:
-                {
-                    if (val.m_value.array->empty())
-                    {
-                        o->write_characters("[]", 2);
-                        return;
-                    }
+    @param[in,out] other array to exchange the contents with
 
-                    if (pretty_print)
-                    {
-                        o->write_characters("[\n", 2);
+    @throw type_error.310 when JSON value is not an array; example: `"cannot
+    use swap() with string"`
 
-                        // variable to hold indentation for recursive calls
-                        const auto new_indent = current_indent + indent_step;
-                        if (indent_string.size() < new_indent)
-                        {
-                            indent_string.resize(new_indent, ' ');
-                        }
+    @complexity Constant.
 
-                        // first n-1 elements
-                        for (auto i = val.m_value.array->cbegin(); i != val.m_value.array->cend() - 1; ++i)
-                        {
-                            o->write_characters(indent_string.c_str(), new_indent);
-                            dump(*i, true, indent_step, new_indent);
-                            o->write_characters(",\n", 2);
-                        }
+    @liveexample{The example below shows how arrays can be swapped with
+    `swap()`.,swap__array_t}
 
-                        // last element
-                        assert(not val.m_value.array->empty());
-                        o->write_characters(indent_string.c_str(), new_indent);
-                        dump(val.m_value.array->back(), true, indent_step, new_indent);
+    @since version 1.0.0
+    */
+    void swap(array_t& other)
+    {
+        // swap only works for arrays
+        if (is_array())
+        {
+            std::swap(*(m_value.array), other);
+        }
+        else
+        {
+            JSON_THROW(type_error::create(310, "cannot use swap() with " + type_name()));
+        }
+    }
 
-                        o->write_character('\n');
-                        o->write_characters(indent_string.c_str(), current_indent);
-                        o->write_character(']');
-                    }
-                    else
-                    {
-                        o->write_character('[');
+    /*!
+    @brief exchanges the values
 
-                        // first n-1 elements
-                        for (auto i = val.m_value.array->cbegin(); i != val.m_value.array->cend() - 1; ++i)
-                        {
-                            dump(*i, false, indent_step, current_indent);
-                            o->write_character(',');
-                        }
+    Exchanges the contents of a JSON object with those of @a other. Does not
+    invoke any move, copy, or swap operations on individual elements. All
+    iterators and references remain valid. The past-the-end iterator is
+    invalidated.
 
-                        // last element
-                        assert(not val.m_value.array->empty());
-                        dump(val.m_value.array->back(), false, indent_step, current_indent);
+    @param[in,out] other object to exchange the contents with
 
-                        o->write_character(']');
-                    }
+    @throw type_error.310 when JSON value is not an object; example:
+    `"cannot use swap() with string"`
 
-                    return;
-                }
+    @complexity Constant.
 
-                case value_t::string:
-                {
-                    o->write_character('\"');
-                    dump_escaped(*val.m_value.string);
-                    o->write_character('\"');
-                    return;
-                }
+    @liveexample{The example below shows how objects can be swapped with
+    `swap()`.,swap__object_t}
 
-                case value_t::boolean:
-                {
-                    if (val.m_value.boolean)
-                    {
-                        o->write_characters("true", 4);
-                    }
-                    else
-                    {
-                        o->write_characters("false", 5);
-                    }
-                    return;
-                }
+    @since version 1.0.0
+    */
+    void swap(object_t& other)
+    {
+        // swap only works for objects
+        if (is_object())
+        {
+            std::swap(*(m_value.object), other);
+        }
+        else
+        {
+            JSON_THROW(type_error::create(310, "cannot use swap() with " + type_name()));
+        }
+    }
+
+    /*!
+    @brief exchanges the values
+
+    Exchanges the contents of a JSON string with those of @a other. Does not
+    invoke any move, copy, or swap operations on individual elements. All
+    iterators and references remain valid. The past-the-end iterator is
+    invalidated.
+
+    @param[in,out] other string to exchange the contents with
+
+    @throw type_error.310 when JSON value is not a string; example: `"cannot
+    use swap() with boolean"`
+
+    @complexity Constant.
+
+    @liveexample{The example below shows how strings can be swapped with
+    `swap()`.,swap__string_t}
+
+    @since version 1.0.0
+    */
+    void swap(string_t& other)
+    {
+        // swap only works for strings
+        if (is_string())
+        {
+            std::swap(*(m_value.string), other);
+        }
+        else
+        {
+            JSON_THROW(type_error::create(310, "cannot use swap() with " + type_name()));
+        }
+    }
+
+    /// @}
+
+  public:
+    //////////////////////////////////////////
+    // lexicographical comparison operators //
+    //////////////////////////////////////////
+
+    /// @name lexicographical comparison operators
+    /// @{
+
+    /*!
+    @brief comparison: equal
+
+    Compares two JSON values for equality according to the following rules:
+    - Two JSON values are equal if (1) they are from the same type and (2)
+      their stored values are the same according to their respective
+      `operator==`.
+    - Integer and floating-point numbers are automatically converted before
+      comparison. Note than two NaN values are always treated as unequal.
+    - Two JSON null values are equal.
+
+    @note NaN values never compare equal to themselves or to other NaN values.
+
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether the values @a lhs and @a rhs are equal
+
+    @complexity Linear.
+
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__equal}
+
+    @since version 1.0.0
+    */
+    friend bool operator==(const_reference lhs, const_reference rhs) noexcept
+    {
+        const auto lhs_type = lhs.type();
+        const auto rhs_type = rhs.type();
 
+        if (lhs_type == rhs_type)
+        {
+            switch (lhs_type)
+            {
+                case value_t::array:
+                {
+                    return *lhs.m_value.array == *rhs.m_value.array;
+                }
+                case value_t::object:
+                {
+                    return *lhs.m_value.object == *rhs.m_value.object;
+                }
+                case value_t::null:
+                {
+                    return true;
+                }
+                case value_t::string:
+                {
+                    return *lhs.m_value.string == *rhs.m_value.string;
+                }
+                case value_t::boolean:
+                {
+                    return lhs.m_value.boolean == rhs.m_value.boolean;
+                }
                 case value_t::number_integer:
                 {
-                    dump_integer(val.m_value.number_integer);
-                    return;
+                    return lhs.m_value.number_integer == rhs.m_value.number_integer;
                 }
-
                 case value_t::number_unsigned:
                 {
-                    dump_integer(val.m_value.number_unsigned);
-                    return;
+                    return lhs.m_value.number_unsigned == rhs.m_value.number_unsigned;
                 }
-
                 case value_t::number_float:
                 {
-                    dump_float(val.m_value.number_float);
-                    return;
-                }
-
-                case value_t::discarded:
-                {
-                    o->write_characters("<discarded>", 11);
-                    return;
+                    return lhs.m_value.number_float == rhs.m_value.number_float;
                 }
-
-                case value_t::null:
+                default:
                 {
-                    o->write_characters("null", 4);
-                    return;
+                    return false;
                 }
             }
         }
+        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_float)
+        {
+            return static_cast<number_float_t>(lhs.m_value.number_integer) == rhs.m_value.number_float;
+        }
+        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_integer)
+        {
+            return lhs.m_value.number_float == static_cast<number_float_t>(rhs.m_value.number_integer);
+        }
+        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_float)
+        {
+            return static_cast<number_float_t>(lhs.m_value.number_unsigned) == rhs.m_value.number_float;
+        }
+        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_unsigned)
+        {
+            return lhs.m_value.number_float == static_cast<number_float_t>(rhs.m_value.number_unsigned);
+        }
+        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_integer)
+        {
+            return static_cast<number_integer_t>(lhs.m_value.number_unsigned) == rhs.m_value.number_integer;
+        }
+        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_unsigned)
+        {
+            return lhs.m_value.number_integer == static_cast<number_integer_t>(rhs.m_value.number_unsigned);
+        }
 
-      private:
-        /*!
-        @brief calculates the extra space to escape a JSON string
+        return false;
+    }
 
-        @param[in] s  the string to escape
-        @return the number of characters required to escape string @a s
+    /*!
+    @brief comparison: equal
+    @copydoc operator==(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator==(const_reference lhs, const ScalarType rhs) noexcept
+    {
+        return (lhs == basic_json(rhs));
+    }
 
-        @complexity Linear in the length of string @a s.
-        */
-        static std::size_t extra_space(const string_t& s) noexcept
-        {
-            return std::accumulate(s.begin(), s.end(), size_t{},
-                                   [](size_t res, typename string_t::value_type c)
-            {
-                switch (c)
-                {
-                    case '"':
-                    case '\\':
-                    case '\b':
-                    case '\f':
-                    case '\n':
-                    case '\r':
-                    case '\t':
-                    {
-                        // from c (1 byte) to \x (2 bytes)
-                        return res + 1;
-                    }
+    /*!
+    @brief comparison: equal
+    @copydoc operator==(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator==(const ScalarType lhs, const_reference rhs) noexcept
+    {
+        return (basic_json(lhs) == rhs);
+    }
 
-                    case 0x00:
-                    case 0x01:
-                    case 0x02:
-                    case 0x03:
-                    case 0x04:
-                    case 0x05:
-                    case 0x06:
-                    case 0x07:
-                    case 0x0b:
-                    case 0x0e:
-                    case 0x0f:
-                    case 0x10:
-                    case 0x11:
-                    case 0x12:
-                    case 0x13:
-                    case 0x14:
-                    case 0x15:
-                    case 0x16:
-                    case 0x17:
-                    case 0x18:
-                    case 0x19:
-                    case 0x1a:
-                    case 0x1b:
-                    case 0x1c:
-                    case 0x1d:
-                    case 0x1e:
-                    case 0x1f:
-                    {
-                        // from c (1 byte) to \uxxxx (6 bytes)
-                        return res + 5;
-                    }
+    /*!
+    @brief comparison: not equal
 
-                    default:
-                    {
-                        return res;
-                    }
-                }
-            });
-        }
+    Compares two JSON values for inequality by calculating `not (lhs == rhs)`.
 
-        /*!
-        @brief dump escaped string
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether the values @a lhs and @a rhs are not equal
 
-        Escape a string by replacing certain special characters by a sequence
-        of an escape character (backslash) and another character and other
-        control characters by a sequence of "\u" followed by a four-digit hex
-        representation. The escaped string is written to output stream @a o.
+    @complexity Linear.
 
-        @param[in] s  the string to escape
-
-        @complexity Linear in the length of string @a s.
-        */
-        void dump_escaped(const string_t& s) const
-        {
-            const auto space = extra_space(s);
-            if (space == 0)
-            {
-                o->write_characters(s.c_str(), s.size());
-                return;
-            }
-
-            // create a result string of necessary size
-            string_t result(s.size() + space, '\\');
-            std::size_t pos = 0;
-
-            for (const auto& c : s)
-            {
-                switch (c)
-                {
-                    // quotation mark (0x22)
-                    case '"':
-                    {
-                        result[pos + 1] = '"';
-                        pos += 2;
-                        break;
-                    }
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__notequal}
 
-                    // reverse solidus (0x5c)
-                    case '\\':
-                    {
-                        // nothing to change
-                        pos += 2;
-                        break;
-                    }
+    @since version 1.0.0
+    */
+    friend bool operator!=(const_reference lhs, const_reference rhs) noexcept
+    {
+        return not (lhs == rhs);
+    }
 
-                    // backspace (0x08)
-                    case '\b':
-                    {
-                        result[pos + 1] = 'b';
-                        pos += 2;
-                        break;
-                    }
+    /*!
+    @brief comparison: not equal
+    @copydoc operator!=(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator!=(const_reference lhs, const ScalarType rhs) noexcept
+    {
+        return (lhs != basic_json(rhs));
+    }
 
-                    // formfeed (0x0c)
-                    case '\f':
-                    {
-                        result[pos + 1] = 'f';
-                        pos += 2;
-                        break;
-                    }
+    /*!
+    @brief comparison: not equal
+    @copydoc operator!=(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator!=(const ScalarType lhs, const_reference rhs) noexcept
+    {
+        return (basic_json(lhs) != rhs);
+    }
 
-                    // newline (0x0a)
-                    case '\n':
-                    {
-                        result[pos + 1] = 'n';
-                        pos += 2;
-                        break;
-                    }
+    /*!
+    @brief comparison: less than
 
-                    // carriage return (0x0d)
-                    case '\r':
-                    {
-                        result[pos + 1] = 'r';
-                        pos += 2;
-                        break;
-                    }
+    Compares whether one JSON value @a lhs is less than another JSON value @a
+    rhs according to the following rules:
+    - If @a lhs and @a rhs have the same type, the values are compared using
+      the default `<` operator.
+    - Integer and floating-point numbers are automatically converted before
+      comparison
+    - In case @a lhs and @a rhs have different types, the values are ignored
+      and the order of the types is considered, see
+      @ref operator<(const value_t, const value_t).
 
-                    // horizontal tab (0x09)
-                    case '\t':
-                    {
-                        result[pos + 1] = 't';
-                        pos += 2;
-                        break;
-                    }
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether @a lhs is less than @a rhs
 
-                    case 0x00:
-                    case 0x01:
-                    case 0x02:
-                    case 0x03:
-                    case 0x04:
-                    case 0x05:
-                    case 0x06:
-                    case 0x07:
-                    case 0x0b:
-                    case 0x0e:
-                    case 0x0f:
-                    case 0x10:
-                    case 0x11:
-                    case 0x12:
-                    case 0x13:
-                    case 0x14:
-                    case 0x15:
-                    case 0x16:
-                    case 0x17:
-                    case 0x18:
-                    case 0x19:
-                    case 0x1a:
-                    case 0x1b:
-                    case 0x1c:
-                    case 0x1d:
-                    case 0x1e:
-                    case 0x1f:
-                    {
-                        // convert a number 0..15 to its hex representation
-                        // (0..f)
-                        static const char hexify[16] =
-                        {
-                            '0', '1', '2', '3', '4', '5', '6', '7',
-                            '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'
-                        };
+    @complexity Linear.
 
-                        // print character c as \uxxxx
-                        for (const char m :
-                    { 'u', '0', '0', hexify[c >> 4], hexify[c & 0x0f]
-                        })
-                        {
-                            result[++pos] = m;
-                        }
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__less}
 
-                        ++pos;
-                        break;
-                    }
+    @since version 1.0.0
+    */
+    friend bool operator<(const_reference lhs, const_reference rhs) noexcept
+    {
+        const auto lhs_type = lhs.type();
+        const auto rhs_type = rhs.type();
 
-                    default:
-                    {
-                        // all other characters are added as-is
-                        result[pos++] = c;
-                        break;
-                    }
+        if (lhs_type == rhs_type)
+        {
+            switch (lhs_type)
+            {
+                case value_t::array:
+                {
+                    return (*lhs.m_value.array) < (*rhs.m_value.array);
+                }
+                case value_t::object:
+                {
+                    return *lhs.m_value.object < *rhs.m_value.object;
+                }
+                case value_t::null:
+                {
+                    return false;
+                }
+                case value_t::string:
+                {
+                    return *lhs.m_value.string < *rhs.m_value.string;
+                }
+                case value_t::boolean:
+                {
+                    return lhs.m_value.boolean < rhs.m_value.boolean;
+                }
+                case value_t::number_integer:
+                {
+                    return lhs.m_value.number_integer < rhs.m_value.number_integer;
+                }
+                case value_t::number_unsigned:
+                {
+                    return lhs.m_value.number_unsigned < rhs.m_value.number_unsigned;
+                }
+                case value_t::number_float:
+                {
+                    return lhs.m_value.number_float < rhs.m_value.number_float;
+                }
+                default:
+                {
+                    return false;
                 }
             }
-
-            assert(pos == s.size() + space);
-            o->write_characters(result.c_str(), result.size());
         }
-
-        /*!
-        @brief dump an integer
-
-        Dump a given integer to output stream @a o. Works internally with
-        @a number_buffer.
-
-        @param[in] x  integer number (signed or unsigned) to dump
-        @tparam NumberType either @a number_integer_t or @a number_unsigned_t
-        */
-        template<typename NumberType, detail::enable_if_t <
-                     std::is_same<NumberType, number_unsigned_t>::value or
-                     std::is_same<NumberType, number_integer_t>::value, int> = 0>
-        void dump_integer(NumberType x)
+        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_float)
         {
-            // special case for "0"
-            if (x == 0)
-            {
-                o->write_character('0');
-                return;
-            }
-
-            const bool is_negative = x < 0;
-            size_t i = 0;
-
-            // spare 1 byte for '\0'
-            while (x != 0 and i < number_buffer.size() - 1)
-            {
-                const auto digit = std::labs(static_cast<long>(x % 10));
-                number_buffer[i++] = static_cast<char>('0' + digit);
-                x /= 10;
-            }
-
-            // make sure the number has been processed completely
-            assert(x == 0);
-
-            if (is_negative)
-            {
-                // make sure there is capacity for the '-'
-                assert(i < number_buffer.size() - 2);
-                number_buffer[i++] = '-';
-            }
-
-            std::reverse(number_buffer.begin(), number_buffer.begin() + i);
-            o->write_characters(number_buffer.data(), i);
+            return static_cast<number_float_t>(lhs.m_value.number_integer) < rhs.m_value.number_float;
+        }
+        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_integer)
+        {
+            return lhs.m_value.number_float < static_cast<number_float_t>(rhs.m_value.number_integer);
+        }
+        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_float)
+        {
+            return static_cast<number_float_t>(lhs.m_value.number_unsigned) < rhs.m_value.number_float;
+        }
+        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_unsigned)
+        {
+            return lhs.m_value.number_float < static_cast<number_float_t>(rhs.m_value.number_unsigned);
+        }
+        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_unsigned)
+        {
+            return lhs.m_value.number_integer < static_cast<number_integer_t>(rhs.m_value.number_unsigned);
+        }
+        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_integer)
+        {
+            return static_cast<number_integer_t>(lhs.m_value.number_unsigned) < rhs.m_value.number_integer;
         }
 
-        /*!
-        @brief dump a floating-point number
-
-        Dump a given floating-point number to output stream @a o. Works
-        internally with @a number_buffer.
+        // We only reach this line if we cannot compare values. In that case,
+        // we compare types. Note we have to call the operator explicitly,
+        // because MSVC has problems otherwise.
+        return operator<(lhs_type, rhs_type);
+    }
 
-        @param[in] x  floating-point number to dump
-        */
-        void dump_float(number_float_t x)
-        {
-            // NaN / inf
-            if (not std::isfinite(x) or std::isnan(x))
-            {
-                o->write_characters("null", 4);
-                return;
-            }
+    /*!
+    @brief comparison: less than
+    @copydoc operator<(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator<(const_reference lhs, const ScalarType rhs) noexcept
+    {
+        return (lhs < basic_json(rhs));
+    }
 
-            // special case for 0.0 and -0.0
-            if (x == 0)
-            {
-                if (std::signbit(x))
-                {
-                    o->write_characters("-0.0", 4);
-                }
-                else
-                {
-                    o->write_characters("0.0", 3);
-                }
-                return;
-            }
+    /*!
+    @brief comparison: less than
+    @copydoc operator<(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator<(const ScalarType lhs, const_reference rhs) noexcept
+    {
+        return (basic_json(lhs) < rhs);
+    }
 
-            // get number of digits for a text -> float -> text round-trip
-            static constexpr auto d = std::numeric_limits<number_float_t>::digits10;
+    /*!
+    @brief comparison: less than or equal
 
-            // the actual conversion
-            std::ptrdiff_t len = snprintf(number_buffer.data(), number_buffer.size(),
-                                          "%.*g", d, x);
+    Compares whether one JSON value @a lhs is less than or equal to another
+    JSON value by calculating `not (rhs < lhs)`.
 
-            // negative value indicates an error
-            assert(len > 0);
-            // check if buffer was large enough
-            assert(static_cast<size_t>(len) < number_buffer.size());
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether @a lhs is less than or equal to @a rhs
 
-            // erase thousands separator
-            if (thousands_sep != '\0')
-            {
-                const auto end = std::remove(number_buffer.begin(),
-                                             number_buffer.begin() + len,
-                                             thousands_sep);
-                std::fill(end, number_buffer.end(), '\0');
-                assert((end - number_buffer.begin()) <= len);
-                len = (end - number_buffer.begin());
-            }
+    @complexity Linear.
 
-            // convert decimal point to '.'
-            if (decimal_point != '\0' and decimal_point != '.')
-            {
-                for (auto& c : number_buffer)
-                {
-                    if (c == decimal_point)
-                    {
-                        c = '.';
-                        break;
-                    }
-                }
-            }
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__greater}
 
-            o->write_characters(number_buffer.data(), static_cast<size_t>(len));
+    @since version 1.0.0
+    */
+    friend bool operator<=(const_reference lhs, const_reference rhs) noexcept
+    {
+        return not (rhs < lhs);
+    }
 
-            // determine if need to append ".0"
-            const bool value_is_int_like = std::none_of(number_buffer.begin(),
-                                           number_buffer.begin() + len + 1,
-                                           [](char c)
-            {
-                return c == '.' or c == 'e';
-            });
+    /*!
+    @brief comparison: less than or equal
+    @copydoc operator<=(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator<=(const_reference lhs, const ScalarType rhs) noexcept
+    {
+        return (lhs <= basic_json(rhs));
+    }
 
-            if (value_is_int_like)
-            {
-                o->write_characters(".0", 2);
-            }
-        }
+    /*!
+    @brief comparison: less than or equal
+    @copydoc operator<=(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator<=(const ScalarType lhs, const_reference rhs) noexcept
+    {
+        return (basic_json(lhs) <= rhs);
+    }
 
-      private:
-        /// the output of the serializer
-        output_adapter_t<char> o = nullptr;
+    /*!
+    @brief comparison: greater than
 
-        /// a (hopefully) large enough character buffer
-        std::array<char, 64> number_buffer{{}};
+    Compares whether one JSON value @a lhs is greater than another
+    JSON value by calculating `not (lhs <= rhs)`.
 
-        /// the locale
-        const std::lconv* loc = nullptr;
-        /// the locale's thousand separator character
-        const char thousands_sep = '\0';
-        /// the locale's decimal point character
-        const char decimal_point = '\0';
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether @a lhs is greater than to @a rhs
 
-        /// the indentation character
-        const char indent_char;
+    @complexity Linear.
 
-        /// the indentation string
-        string_t indent_string;
-    };
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__lessequal}
 
-  public:
-    /*!
-    @brief serialize to stream
+    @since version 1.0.0
+    */
+    friend bool operator>(const_reference lhs, const_reference rhs) noexcept
+    {
+        return not (lhs <= rhs);
+    }
 
-    Serialize the given JSON value @a j to the output stream @a o. The JSON
-    value will be serialized using the @ref dump member function.
+    /*!
+    @brief comparison: greater than
+    @copydoc operator>(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator>(const_reference lhs, const ScalarType rhs) noexcept
+    {
+        return (lhs > basic_json(rhs));
+    }
 
-    - The indentation of the output can be controlled with the member variable
-      `width` of the output stream @a o. For instance, using the manipulator
-      `std::setw(4)` on @a o sets the indentation level to `4` and the
-      serialization result is the same as calling `dump(4)`.
+    /*!
+    @brief comparison: greater than
+    @copydoc operator>(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator>(const ScalarType lhs, const_reference rhs) noexcept
+    {
+        return (basic_json(lhs) > rhs);
+    }
 
-    - The indentation characrer can be controlled with the member variable
-      `fill` of the output stream @a o. For instance, the manipulator
-      `std::setfill('\\t')` sets indentation to use a tab character rather than
-      the default space character.
+    /*!
+    @brief comparison: greater than or equal
 
-    @param[in,out] o  stream to serialize to
-    @param[in] j  JSON value to serialize
+    Compares whether one JSON value @a lhs is greater than or equal to another
+    JSON value by calculating `not (lhs < rhs)`.
 
-    @return the stream @a o
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether @a lhs is greater than or equal to @a rhs
 
     @complexity Linear.
 
-    @liveexample{The example below shows the serialization with different
-    parameters to `width` to adjust the indentation level.,operator_serialize}
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__greaterequal}
 
-    @since version 1.0.0; indentaction character added in version 3.0.0
+    @since version 1.0.0
     */
-    friend std::ostream& operator<<(std::ostream& o, const basic_json& j)
+    friend bool operator>=(const_reference lhs, const_reference rhs) noexcept
     {
-        // read width member and use it as indentation parameter if nonzero
-        const bool pretty_print = (o.width() > 0);
-        const auto indentation = (pretty_print ? o.width() : 0);
-
-        // reset width to 0 for subsequent calls to this stream
-        o.width(0);
+        return not (lhs < rhs);
+    }
 
-        // do the actual serialization
-        serializer s(output_adapter<char>::create(o), o.fill());
-        s.dump(j, pretty_print, static_cast<unsigned int>(indentation));
-        return o;
+    /*!
+    @brief comparison: greater than or equal
+    @copydoc operator>=(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator>=(const_reference lhs, const ScalarType rhs) noexcept
+    {
+        return (lhs >= basic_json(rhs));
     }
 
     /*!
-    @brief serialize to stream
-    @deprecated This stream operator is deprecated and will be removed in a
-                future version of the library. Please use
-                @ref std::ostream& operator<<(std::ostream&, const basic_json&)
-                instead; that is, replace calls like `j >> o;` with `o << j;`.
+    @brief comparison: greater than or equal
+    @copydoc operator>=(const_reference, const_reference)
     */
-    JSON_DEPRECATED
-    friend std::ostream& operator>>(const basic_json& j, std::ostream& o)
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator>=(const ScalarType lhs, const_reference rhs) noexcept
     {
-        return o << j;
+        return (basic_json(lhs) >= rhs);
     }
 
     /// @}
 
-
+  private:
     /////////////////////
-    // deserialization //
+    // output adapters //
     /////////////////////
 
-    /// @name deserialization
-    /// @{
-
-    /*!
-    @brief deserialize from an array
+    /// abstract output adapter interface
+    template<typename CharType>
+    class output_adapter
+    {
+      public:
+        virtual void write_character(CharType c) = 0;
+        virtual void write_characters(const CharType* s, size_t length) = 0;
+        virtual ~output_adapter() {}
 
-    This function reads from an array of 1-byte values.
+        static std::shared_ptr<output_adapter<CharType>> create(std::vector<CharType>& vec)
+        {
+            return std::make_shared<output_vector_adapter<CharType>>(vec);
+        }
 
-    @pre Each element of the container has a size of 1 byte. Violating this
-    precondition yields undefined behavior. **This precondition is enforced
-    with a static assertion.**
+        static std::shared_ptr<output_adapter<CharType>> create(std::ostream& s)
+        {
+            return std::make_shared<output_stream_adapter<CharType>>(s);
+        }
 
-    @param[in] array  array to read from
-    @param[in] cb  a parser callback function of type @ref parser_callback_t
-    which is used to control the deserialization by filtering unwanted values
-    (optional)
+        static std::shared_ptr<output_adapter<CharType>> create(std::string& s)
+        {
+            return std::make_shared<output_string_adapter<CharType>>(s);
+        }
+    };
 
-    @return result of the deserialization
+    /// a type to simplify interfaces
+    template<typename CharType>
+    using output_adapter_t = std::shared_ptr<output_adapter<CharType>>;
 
-    @throw parse_error.101 if a parse error occurs; example: `""unexpected end
-    of input; expected string literal""`
-    @throw parse_error.102 if to_unicode fails or surrogate error
-    @throw parse_error.103 if to_unicode fails
+    /// output adapter for byte vectors
+    template<typename CharType>
+    class output_vector_adapter : public output_adapter<CharType>
+    {
+      public:
+        output_vector_adapter(std::vector<CharType>& vec)
+            : v(vec)
+        {}
 
-    @complexity Linear in the length of the input. The parser is a predictive
-    LL(1) parser. The complexity can be higher if the parser callback function
-    @a cb has a super-linear complexity.
+        void write_character(CharType c) override
+        {
+            v.push_back(c);
+        }
 
-    @note A UTF-8 byte order mark is silently ignored.
+        void write_characters(const CharType* s, size_t length) override
+        {
+            std::copy(s, s + length, std::back_inserter(v));
+        }
 
-    @liveexample{The example below demonstrates the `parse()` function reading
-    from an array.,parse__array__parser_callback_t}
+      private:
+        std::vector<CharType>& v;
+    };
 
-    @since version 2.0.3
-    */
-    template<class T, std::size_t N>
-    static basic_json parse(T (&array)[N],
-                            const parser_callback_t cb = nullptr)
+    /// output adapter for output streams
+    template<typename CharType>
+    class output_stream_adapter : public output_adapter<CharType>
     {
-        // delegate the call to the iterator-range parse overload
-        return parse(std::begin(array), std::end(array), cb);
-    }
+      public:
+        output_stream_adapter(std::basic_ostream<CharType>& s)
+            : stream(s)
+        {}
 
-    template<class T, std::size_t N>
-    static bool accept(T (&array)[N])
-    {
-        // delegate the call to the iterator-range accept overload
-        return accept(std::begin(array), std::end(array));
-    }
+        void write_character(CharType c) override
+        {
+            stream.put(c);
+        }
 
-    /*!
-    @brief deserialize from string literal
+        void write_characters(const CharType* s, size_t length) override
+        {
+            stream.write(s, static_cast<std::streamsize>(length));
+        }
 
-    @tparam CharT character/literal type with size of 1 byte
-    @param[in] s  string literal to read a serialized JSON value from
-    @param[in] cb a parser callback function of type @ref parser_callback_t
-    which is used to control the deserialization by filtering unwanted values
-    (optional)
+      private:
+        std::basic_ostream<CharType>& stream;
+    };
 
-    @return result of the deserialization
+    /// output adapter for basic_string
+    template<typename CharType>
+    class output_string_adapter : public output_adapter<CharType>
+    {
+      public:
+        output_string_adapter(std::string& s)
+            : str(s)
+        {}
 
-    @throw parse_error.101 in case of an unexpected token
-    @throw parse_error.102 if to_unicode fails or surrogate error
-    @throw parse_error.103 if to_unicode fails
+        void write_character(CharType c) override
+        {
+            str.push_back(c);
+        }
 
-    @complexity Linear in the length of the input. The parser is a predictive
-    LL(1) parser. The complexity can be higher if the parser callback function
-    @a cb has a super-linear complexity.
+        void write_characters(const CharType* s, size_t length) override
+        {
+            str.append(s, length);
+        }
 
-    @note A UTF-8 byte order mark is silently ignored.
-    @note String containers like `std::string` or @ref string_t can be parsed
-          with @ref parse(const ContiguousContainer&, const parser_callback_t)
+      private:
+        std::basic_string<CharType>& str;
+    };
 
-    @liveexample{The example below demonstrates the `parse()` function with
-    and without callback function.,parse__string__parser_callback_t}
 
-    @sa @ref parse(std::istream&, const parser_callback_t) for a version that
-    reads from an input stream
+    ///////////////////
+    // serialization //
+    ///////////////////
 
-    @since version 1.0.0 (originally for @ref string_t)
+    /// @name serialization
+    /// @{
+
+  private:
+    /*!
+    @brief wrapper around the serialization functions
     */
-    template<typename CharT, typename std::enable_if<
-                 std::is_pointer<CharT>::value and
-                 std::is_integral<typename std::remove_pointer<CharT>::type>::value and
-                 sizeof(typename std::remove_pointer<CharT>::type) == 1, int>::type = 0>
-    static basic_json parse(const CharT s,
-                            const parser_callback_t cb = nullptr)
+    class serializer
     {
-        return parser(detail::input_adapter_factory::create(s), cb).parse(true);
-    }
+      public:
+        /*!
+        @param[in] s  output stream to serialize to
+        @param[in] ichar  indentation character to use
+        */
+        serializer(output_adapter_t<char> s, const char ichar)
+            : o(s), loc(std::localeconv()),
+              thousands_sep(!loc->thousands_sep ? '\0' : loc->thousands_sep[0]),
+              decimal_point(!loc->decimal_point ? '\0' : loc->decimal_point[0]),
+              indent_char(ichar), indent_string(512, indent_char)
+        {}
 
-    template<typename CharT, typename std::enable_if<
-                 std::is_pointer<CharT>::value and
-                 std::is_integral<typename std::remove_pointer<CharT>::type>::value and
-                 sizeof(typename std::remove_pointer<CharT>::type) == 1, int>::type = 0>
-    static bool accept(const CharT s)
-    {
-        return parser(detail::input_adapter_factory::create(s)).accept(true);
-    }
+        // delete because of pointer members
+        serializer(const serializer&) = delete;
+        serializer& operator=(const serializer&) = delete;
 
-    /*!
-    @brief deserialize from stream
+        /*!
+        @brief internal implementation of the serialization function
 
-    @param[in,out] i  stream to read a serialized JSON value from
-    @param[in] cb a parser callback function of type @ref parser_callback_t
-    which is used to control the deserialization by filtering unwanted values
-    (optional)
+        This function is called by the public member function dump and
+        organizes the serialization internally. The indentation level is
+        propagated as additional parameter. In case of arrays and objects, the
+        function is called recursively.
 
-    @return result of the deserialization
+        - strings and object keys are escaped using `escape_string()`
+        - integer numbers are converted implicitly via `operator<<`
+        - floating-point numbers are converted to a string using `"%g"` format
 
-    @throw parse_error.101 in case of an unexpected token
-    @throw parse_error.102 if to_unicode fails or surrogate error
-    @throw parse_error.103 if to_unicode fails
+        @param[in] val             value to serialize
+        @param[in] pretty_print    whether the output shall be pretty-printed
+        @param[in] indent_step     the indent level
+        @param[in] current_indent  the current indent level (only used internally)
+        */
+        void dump(const basic_json& val,
+                  const bool pretty_print,
+                  const unsigned int indent_step,
+                  const unsigned int current_indent = 0)
+        {
+            switch (val.m_type)
+            {
+                case value_t::object:
+                {
+                    if (val.m_value.object->empty())
+                    {
+                        o->write_characters("{}", 2);
+                        return;
+                    }
 
-    @complexity Linear in the length of the input. The parser is a predictive
-    LL(1) parser. The complexity can be higher if the parser callback function
-    @a cb has a super-linear complexity.
+                    if (pretty_print)
+                    {
+                        o->write_characters("{\n", 2);
 
-    @note A UTF-8 byte order mark is silently ignored.
+                        // variable to hold indentation for recursive calls
+                        const auto new_indent = current_indent + indent_step;
+                        if (JSON_UNLIKELY(indent_string.size() < new_indent))
+                        {
+                            indent_string.resize(indent_string.size() * 2, ' ');
+                        }
 
-    @liveexample{The example below demonstrates the `parse()` function with
-    and without callback function.,parse__istream__parser_callback_t}
+                        // first n-1 elements
+                        auto i = val.m_value.object->cbegin();
+                        for (size_t cnt = 0; cnt < val.m_value.object->size() - 1; ++cnt, ++i)
+                        {
+                            o->write_characters(indent_string.c_str(), new_indent);
+                            o->write_character('\"');
+                            dump_escaped(i->first);
+                            o->write_characters("\": ", 3);
+                            dump(i->second, true, indent_step, new_indent);
+                            o->write_characters(",\n", 2);
+                        }
 
-    @sa @ref parse(const CharT, const parser_callback_t) for a version
-    that reads from a string
+                        // last element
+                        assert(i != val.m_value.object->cend());
+                        o->write_characters(indent_string.c_str(), new_indent);
+                        o->write_character('\"');
+                        dump_escaped(i->first);
+                        o->write_characters("\": ", 3);
+                        dump(i->second, true, indent_step, new_indent);
 
-    @since version 1.0.0
-    */
-    static basic_json parse(std::istream& i,
-                            const parser_callback_t cb = nullptr)
-    {
-        return parser(detail::input_adapter_factory::create(i), cb).parse(true);
-    }
+                        o->write_character('\n');
+                        o->write_characters(indent_string.c_str(), current_indent);
+                        o->write_character('}');
+                    }
+                    else
+                    {
+                        o->write_character('{');
 
-    static bool accept(std::istream& i)
-    {
-        return parser(detail::input_adapter_factory::create(i)).accept(true);
-    }
+                        // first n-1 elements
+                        auto i = val.m_value.object->cbegin();
+                        for (size_t cnt = 0; cnt < val.m_value.object->size() - 1; ++cnt, ++i)
+                        {
+                            o->write_character('\"');
+                            dump_escaped(i->first);
+                            o->write_characters("\":", 2);
+                            dump(i->second, false, indent_step, current_indent);
+                            o->write_character(',');
+                        }
 
-    /*!
-    @copydoc parse(std::istream&, const parser_callback_t)
-    */
-    static basic_json parse(std::istream&& i,
-                            const parser_callback_t cb = nullptr)
-    {
-        return parser(detail::input_adapter_factory::create(i), cb).parse(true);
-    }
+                        // last element
+                        assert(i != val.m_value.object->cend());
+                        o->write_character('\"');
+                        dump_escaped(i->first);
+                        o->write_characters("\":", 2);
+                        dump(i->second, false, indent_step, current_indent);
 
-    static bool accept(std::istream&& i)
-    {
-        return parser(detail::input_adapter_factory::create(i)).accept(true);
-    }
+                        o->write_character('}');
+                    }
 
-    /*!
-    @brief deserialize from an iterator range with contiguous storage
+                    return;
+                }
 
-    This function reads from an iterator range of a container with contiguous
-    storage of 1-byte values. Compatible container types include
-    `std::vector`, `std::string`, `std::array`, `std::valarray`, and
-    `std::initializer_list`. Furthermore, C-style arrays can be used with
-    `std::begin()`/`std::end()`. User-defined containers can be used as long
-    as they implement random-access iterators and a contiguous storage.
+                case value_t::array:
+                {
+                    if (val.m_value.array->empty())
+                    {
+                        o->write_characters("[]", 2);
+                        return;
+                    }
 
-    @pre The iterator range is contiguous. Violating this precondition yields
-    undefined behavior. **This precondition is enforced with an assertion.**
-    @pre Each element in the range has a size of 1 byte. Violating this
-    precondition yields undefined behavior. **This precondition is enforced
-    with a static assertion.**
+                    if (pretty_print)
+                    {
+                        o->write_characters("[\n", 2);
 
-    @warning There is no way to enforce all preconditions at compile-time. If
-             the function is called with noncompliant iterators and with
-             assertions switched off, the behavior is undefined and will most
-             likely yield segmentation violation.
+                        // variable to hold indentation for recursive calls
+                        const auto new_indent = current_indent + indent_step;
+                        if (indent_string.size() < new_indent)
+                        {
+                            indent_string.resize(new_indent, ' ');
+                        }
 
-    @tparam IteratorType iterator of container with contiguous storage
-    @param[in] first  begin of the range to parse (included)
-    @param[in] last  end of the range to parse (excluded)
-    @param[in] cb  a parser callback function of type @ref parser_callback_t
-    which is used to control the deserialization by filtering unwanted values
-    (optional)
+                        // first n-1 elements
+                        for (auto i = val.m_value.array->cbegin(); i != val.m_value.array->cend() - 1; ++i)
+                        {
+                            o->write_characters(indent_string.c_str(), new_indent);
+                            dump(*i, true, indent_step, new_indent);
+                            o->write_characters(",\n", 2);
+                        }
 
-    @return result of the deserialization
+                        // last element
+                        assert(not val.m_value.array->empty());
+                        o->write_characters(indent_string.c_str(), new_indent);
+                        dump(val.m_value.array->back(), true, indent_step, new_indent);
 
-    @throw parse_error.101 in case of an unexpected token
-    @throw parse_error.102 if to_unicode fails or surrogate error
-    @throw parse_error.103 if to_unicode fails
+                        o->write_character('\n');
+                        o->write_characters(indent_string.c_str(), current_indent);
+                        o->write_character(']');
+                    }
+                    else
+                    {
+                        o->write_character('[');
 
-    @complexity Linear in the length of the input. The parser is a predictive
-    LL(1) parser. The complexity can be higher if the parser callback function
-    @a cb has a super-linear complexity.
+                        // first n-1 elements
+                        for (auto i = val.m_value.array->cbegin(); i != val.m_value.array->cend() - 1; ++i)
+                        {
+                            dump(*i, false, indent_step, current_indent);
+                            o->write_character(',');
+                        }
 
-    @note A UTF-8 byte order mark is silently ignored.
+                        // last element
+                        assert(not val.m_value.array->empty());
+                        dump(val.m_value.array->back(), false, indent_step, current_indent);
 
-    @liveexample{The example below demonstrates the `parse()` function reading
-    from an iterator range.,parse__iteratortype__parser_callback_t}
+                        o->write_character(']');
+                    }
 
-    @since version 2.0.3
-    */
-    template<class IteratorType, typename std::enable_if<
-                 std::is_base_of<
-                     std::random_access_iterator_tag,
-                     typename std::iterator_traits<IteratorType>::iterator_category>::value, int>::type = 0>
-    static basic_json parse(IteratorType first, IteratorType last,
-                            const parser_callback_t cb = nullptr)
-    {
-        return parser(detail::input_adapter_factory::create(first, last), cb).parse(true);
-    }
+                    return;
+                }
 
-    template<class IteratorType, typename std::enable_if<
-                 std::is_base_of<
-                     std::random_access_iterator_tag,
-                     typename std::iterator_traits<IteratorType>::iterator_category>::value, int>::type = 0>
-    static bool accept(IteratorType first, IteratorType last)
-    {
-        return parser(detail::input_adapter_factory::create(first, last)).accept(true);
-    }
+                case value_t::string:
+                {
+                    o->write_character('\"');
+                    dump_escaped(*val.m_value.string);
+                    o->write_character('\"');
+                    return;
+                }
 
-    /*!
-    @brief deserialize from a container with contiguous storage
+                case value_t::boolean:
+                {
+                    if (val.m_value.boolean)
+                    {
+                        o->write_characters("true", 4);
+                    }
+                    else
+                    {
+                        o->write_characters("false", 5);
+                    }
+                    return;
+                }
 
-    This function reads from a container with contiguous storage of 1-byte
-    values. Compatible container types include `std::vector`, `std::string`,
-    `std::array`, and `std::initializer_list`. User-defined containers can be
-    used as long as they implement random-access iterators and a contiguous
-    storage.
+                case value_t::number_integer:
+                {
+                    dump_integer(val.m_value.number_integer);
+                    return;
+                }
 
-    @pre The container storage is contiguous. Violating this precondition
-    yields undefined behavior. **This precondition is enforced with an
-    assertion.**
-    @pre Each element of the container has a size of 1 byte. Violating this
-    precondition yields undefined behavior. **This precondition is enforced
-    with a static assertion.**
+                case value_t::number_unsigned:
+                {
+                    dump_integer(val.m_value.number_unsigned);
+                    return;
+                }
 
-    @warning There is no way to enforce all preconditions at compile-time. If
-             the function is called with a noncompliant container and with
-             assertions switched off, the behavior is undefined and will most
-             likely yield segmentation violation.
+                case value_t::number_float:
+                {
+                    dump_float(val.m_value.number_float);
+                    return;
+                }
 
-    @tparam ContiguousContainer container type with contiguous storage
-    @param[in] c  container to read from
-    @param[in] cb  a parser callback function of type @ref parser_callback_t
-    which is used to control the deserialization by filtering unwanted values
-    (optional)
+                case value_t::discarded:
+                {
+                    o->write_characters("<discarded>", 11);
+                    return;
+                }
 
-    @return result of the deserialization
+                case value_t::null:
+                {
+                    o->write_characters("null", 4);
+                    return;
+                }
+            }
+        }
 
-    @throw parse_error.101 in case of an unexpected token
-    @throw parse_error.102 if to_unicode fails or surrogate error
-    @throw parse_error.103 if to_unicode fails
+      private:
+        /*!
+        @brief calculates the extra space to escape a JSON string
 
-    @complexity Linear in the length of the input. The parser is a predictive
-    LL(1) parser. The complexity can be higher if the parser callback function
-    @a cb has a super-linear complexity.
+        @param[in] s  the string to escape
+        @return the number of characters required to escape string @a s
 
-    @note A UTF-8 byte order mark is silently ignored.
+        @complexity Linear in the length of string @a s.
+        */
+        static std::size_t extra_space(const string_t& s) noexcept
+        {
+            return std::accumulate(s.begin(), s.end(), size_t{},
+                                   [](size_t res, typename string_t::value_type c)
+            {
+                switch (c)
+                {
+                    case '"':
+                    case '\\':
+                    case '\b':
+                    case '\f':
+                    case '\n':
+                    case '\r':
+                    case '\t':
+                    {
+                        // from c (1 byte) to \x (2 bytes)
+                        return res + 1;
+                    }
+
+                    case 0x00:
+                    case 0x01:
+                    case 0x02:
+                    case 0x03:
+                    case 0x04:
+                    case 0x05:
+                    case 0x06:
+                    case 0x07:
+                    case 0x0b:
+                    case 0x0e:
+                    case 0x0f:
+                    case 0x10:
+                    case 0x11:
+                    case 0x12:
+                    case 0x13:
+                    case 0x14:
+                    case 0x15:
+                    case 0x16:
+                    case 0x17:
+                    case 0x18:
+                    case 0x19:
+                    case 0x1a:
+                    case 0x1b:
+                    case 0x1c:
+                    case 0x1d:
+                    case 0x1e:
+                    case 0x1f:
+                    {
+                        // from c (1 byte) to \uxxxx (6 bytes)
+                        return res + 5;
+                    }
 
-    @liveexample{The example below demonstrates the `parse()` function reading
-    from a contiguous container.,parse__contiguouscontainer__parser_callback_t}
+                    default:
+                    {
+                        return res;
+                    }
+                }
+            });
+        }
 
-    @since version 2.0.3
-    */
-    template<class ContiguousContainer, typename std::enable_if<
-                 not std::is_pointer<ContiguousContainer>::value and
-                 std::is_base_of<
-                     std::random_access_iterator_tag,
-                     typename std::iterator_traits<decltype(std::begin(std::declval<ContiguousContainer const>()))>::iterator_category>::value
-                 , int>::type = 0>
-    static basic_json parse(const ContiguousContainer& c,
-                            const parser_callback_t cb = nullptr)
-    {
-        // delegate the call to the iterator-range parse overload
-        return parse(std::begin(c), std::end(c), cb);
-    }
+        /*!
+        @brief dump escaped string
 
-    template<class ContiguousContainer, typename std::enable_if<
-                 not std::is_pointer<ContiguousContainer>::value and
-                 std::is_base_of<
-                     std::random_access_iterator_tag,
-                     typename std::iterator_traits<decltype(std::begin(std::declval<ContiguousContainer const>()))>::iterator_category>::value
-                 , int>::type = 0>
-    static bool accept(const ContiguousContainer& c)
-    {
-        // delegate the call to the iterator-range accept overload
-        return accept(std::begin(c), std::end(c));
-    }
+        Escape a string by replacing certain special characters by a sequence
+        of an escape character (backslash) and another character and other
+        control characters by a sequence of "\u" followed by a four-digit hex
+        representation. The escaped string is written to output stream @a o.
 
-    /*!
-    @brief deserialize from stream
-    @deprecated This stream operator is deprecated and will be removed in a
-                future version of the library. Please use
-                @ref std::istream& operator>>(std::istream&, basic_json&)
-                instead; that is, replace calls like `j << i;` with `i >> j;`.
-    */
-    JSON_DEPRECATED
-    friend std::istream& operator<<(basic_json& j, std::istream& i)
-    {
-        j = parser(detail::input_adapter_factory::create(i)).parse(false);
-        return i;
-    }
+        @param[in] s  the string to escape
 
-    /*!
-    @brief deserialize from stream
+        @complexity Linear in the length of string @a s.
+        */
+        void dump_escaped(const string_t& s) const
+        {
+            const auto space = extra_space(s);
+            if (space == 0)
+            {
+                o->write_characters(s.c_str(), s.size());
+                return;
+            }
 
-    Deserializes an input stream to a JSON value.
+            // create a result string of necessary size
+            string_t result(s.size() + space, '\\');
+            std::size_t pos = 0;
 
-    @param[in,out] i  input stream to read a serialized JSON value from
-    @param[in,out] j  JSON value to write the deserialized input to
+            for (const auto& c : s)
+            {
+                switch (c)
+                {
+                    // quotation mark (0x22)
+                    case '"':
+                    {
+                        result[pos + 1] = '"';
+                        pos += 2;
+                        break;
+                    }
 
-    @throw parse_error.101 in case of an unexpected token
-    @throw parse_error.102 if to_unicode fails or surrogate error
-    @throw parse_error.103 if to_unicode fails
+                    // reverse solidus (0x5c)
+                    case '\\':
+                    {
+                        // nothing to change
+                        pos += 2;
+                        break;
+                    }
 
-    @complexity Linear in the length of the input. The parser is a predictive
-    LL(1) parser.
+                    // backspace (0x08)
+                    case '\b':
+                    {
+                        result[pos + 1] = 'b';
+                        pos += 2;
+                        break;
+                    }
 
-    @note A UTF-8 byte order mark is silently ignored.
+                    // formfeed (0x0c)
+                    case '\f':
+                    {
+                        result[pos + 1] = 'f';
+                        pos += 2;
+                        break;
+                    }
 
-    @liveexample{The example below shows how a JSON value is constructed by
-    reading a serialization from a stream.,operator_deserialize}
+                    // newline (0x0a)
+                    case '\n':
+                    {
+                        result[pos + 1] = 'n';
+                        pos += 2;
+                        break;
+                    }
 
-    @sa parse(std::istream&, const parser_callback_t) for a variant with a
-    parser callback function to filter values while parsing
+                    // carriage return (0x0d)
+                    case '\r':
+                    {
+                        result[pos + 1] = 'r';
+                        pos += 2;
+                        break;
+                    }
 
-    @since version 1.0.0
-    */
-    friend std::istream& operator>>(std::istream& i, basic_json& j)
-    {
-        j = parser(detail::input_adapter_factory::create(i)).parse(false);
-        return i;
-    }
+                    // horizontal tab (0x09)
+                    case '\t':
+                    {
+                        result[pos + 1] = 't';
+                        pos += 2;
+                        break;
+                    }
 
-    /// @}
+                    case 0x00:
+                    case 0x01:
+                    case 0x02:
+                    case 0x03:
+                    case 0x04:
+                    case 0x05:
+                    case 0x06:
+                    case 0x07:
+                    case 0x0b:
+                    case 0x0e:
+                    case 0x0f:
+                    case 0x10:
+                    case 0x11:
+                    case 0x12:
+                    case 0x13:
+                    case 0x14:
+                    case 0x15:
+                    case 0x16:
+                    case 0x17:
+                    case 0x18:
+                    case 0x19:
+                    case 0x1a:
+                    case 0x1b:
+                    case 0x1c:
+                    case 0x1d:
+                    case 0x1e:
+                    case 0x1f:
+                    {
+                        // convert a number 0..15 to its hex representation
+                        // (0..f)
+                        static const char hexify[16] =
+                        {
+                            '0', '1', '2', '3', '4', '5', '6', '7',
+                            '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'
+                        };
 
-    ///////////////////////////
-    // convenience functions //
-    ///////////////////////////
+                        // print character c as \uxxxx
+                        for (const char m :
+                    { 'u', '0', '0', hexify[c >> 4], hexify[c & 0x0f]
+                        })
+                        {
+                            result[++pos] = m;
+                        }
 
-    /*!
-    @brief return the type as string
+                        ++pos;
+                        break;
+                    }
 
-    Returns the type name as string to be used in error messages - usually to
-    indicate that a function was called on a wrong JSON type.
+                    default:
+                    {
+                        // all other characters are added as-is
+                        result[pos++] = c;
+                        break;
+                    }
+                }
+            }
 
-    @return basically a string representation of a the @a m_type member
+            assert(pos == s.size() + space);
+            o->write_characters(result.c_str(), result.size());
+        }
 
-    @complexity Constant.
+        /*!
+        @brief dump an integer
 
-    @liveexample{The following code exemplifies `type_name()` for all JSON
-    types.,type_name}
+        Dump a given integer to output stream @a o. Works internally with
+        @a number_buffer.
 
-    @since version 1.0.0, public since 2.1.0
-    */
-    std::string type_name() const
-    {
+        @param[in] x  integer number (signed or unsigned) to dump
+        @tparam NumberType either @a number_integer_t or @a number_unsigned_t
+        */
+        template<typename NumberType, detail::enable_if_t <
+                     std::is_same<NumberType, number_unsigned_t>::value or
+                     std::is_same<NumberType, number_integer_t>::value, int> = 0>
+        void dump_integer(NumberType x)
         {
-            switch (m_type)
+            // special case for "0"
+            if (x == 0)
             {
-                case value_t::null:
-                    return "null";
-                case value_t::object:
-                    return "object";
-                case value_t::array:
-                    return "array";
-                case value_t::string:
-                    return "string";
-                case value_t::boolean:
-                    return "boolean";
-                case value_t::discarded:
-                    return "discarded";
-                default:
-                    return "number";
+                o->write_character('0');
+                return;
             }
-        }
-    }
 
+            const bool is_negative = x < 0;
+            size_t i = 0;
 
-  private:
-    //////////////////////
-    // member variables //
-    //////////////////////
-
-    /// the type of the current element
-    value_t m_type = value_t::null;
+            // spare 1 byte for '\0'
+            while (x != 0 and i < number_buffer.size() - 1)
+            {
+                const auto digit = std::labs(static_cast<long>(x % 10));
+                number_buffer[i++] = static_cast<char>('0' + digit);
+                x /= 10;
+            }
 
-    /// the value of the current element
-    json_value m_value = {};
+            // make sure the number has been processed completely
+            assert(x == 0);
 
+            if (is_negative)
+            {
+                // make sure there is capacity for the '-'
+                assert(i < number_buffer.size() - 2);
+                number_buffer[i++] = '-';
+            }
 
-  private:
-    /*!
-    @brief an iterator value
+            std::reverse(number_buffer.begin(), number_buffer.begin() + i);
+            o->write_characters(number_buffer.data(), i);
+        }
 
-    @note This structure could easily be a union, but MSVC currently does not
-    allow unions members with complex constructors, see
-    https://github.com/nlohmann/json/pull/105.
-    */
-    struct internal_iterator
-    {
-        /// iterator for JSON objects
-        typename object_t::iterator object_iterator;
-        /// iterator for JSON arrays
-        typename array_t::iterator array_iterator;
-        /// generic iterator for all other types
-        primitive_iterator_t primitive_iterator;
+        /*!
+        @brief dump a floating-point number
 
-        /// create an uninitialized internal_iterator
-        internal_iterator() noexcept
-            : object_iterator(), array_iterator(), primitive_iterator()
-        {}
-    };
+        Dump a given floating-point number to output stream @a o. Works
+        internally with @a number_buffer.
 
-    /// proxy class for the iterator_wrapper functions
-    template<typename IteratorType>
-    class iteration_proxy
-    {
-      private:
-        /// helper class for iteration
-        class iteration_proxy_internal
+        @param[in] x  floating-point number to dump
+        */
+        void dump_float(number_float_t x)
         {
-          private:
-            /// the iterator
-            IteratorType anchor;
-            /// an index for arrays (used to create key names)
-            size_t array_index = 0;
-
-          public:
-            explicit iteration_proxy_internal(IteratorType it) noexcept
-                : anchor(it)
-            {}
-
-            /// dereference operator (needed for range-based for)
-            iteration_proxy_internal& operator*()
+            // NaN / inf
+            if (not std::isfinite(x) or std::isnan(x))
             {
-                return *this;
+                o->write_characters("null", 4);
+                return;
             }
 
-            /// increment operator (needed for range-based for)
-            iteration_proxy_internal& operator++()
+            // special case for 0.0 and -0.0
+            if (x == 0)
             {
-                ++anchor;
-                ++array_index;
-
-                return *this;
+                if (std::signbit(x))
+                {
+                    o->write_characters("-0.0", 4);
+                }
+                else
+                {
+                    o->write_characters("0.0", 3);
+                }
+                return;
             }
 
-            /// inequality operator (needed for range-based for)
-            bool operator!= (const iteration_proxy_internal& o) const
+            // get number of digits for a text -> float -> text round-trip
+            static constexpr auto d = std::numeric_limits<number_float_t>::digits10;
+
+            // the actual conversion
+            std::ptrdiff_t len = snprintf(number_buffer.data(), number_buffer.size(),
+                                          "%.*g", d, x);
+
+            // negative value indicates an error
+            assert(len > 0);
+            // check if buffer was large enough
+            assert(static_cast<size_t>(len) < number_buffer.size());
+
+            // erase thousands separator
+            if (thousands_sep != '\0')
             {
-                return anchor != o.anchor;
+                const auto end = std::remove(number_buffer.begin(),
+                                             number_buffer.begin() + len,
+                                             thousands_sep);
+                std::fill(end, number_buffer.end(), '\0');
+                assert((end - number_buffer.begin()) <= len);
+                len = (end - number_buffer.begin());
             }
 
-            /// return key of the iterator
-            typename basic_json::string_t key() const
+            // convert decimal point to '.'
+            if (decimal_point != '\0' and decimal_point != '.')
             {
-                assert(anchor.m_object != nullptr);
-
-                switch (anchor.m_object->type())
+                for (auto& c : number_buffer)
                 {
-                    // use integer array index as key
-                    case value_t::array:
-                    {
-                        return std::to_string(array_index);
-                    }
-
-                    // use key from the object
-                    case value_t::object:
-                    {
-                        return anchor.key();
-                    }
-
-                    // use an empty key for all primitive types
-                    default:
+                    if (c == decimal_point)
                     {
-                        return "";
+                        c = '.';
+                        break;
                     }
                 }
             }
 
-            /// return value of the iterator
-            typename IteratorType::reference value() const
+            o->write_characters(number_buffer.data(), static_cast<size_t>(len));
+
+            // determine if need to append ".0"
+            const bool value_is_int_like = std::none_of(number_buffer.begin(),
+                                           number_buffer.begin() + len + 1,
+                                           [](char c)
+            {
+                return c == '.' or c == 'e';
+            });
+
+            if (value_is_int_like)
             {
-                return anchor.value();
+                o->write_characters(".0", 2);
             }
-        };
+        }
 
-        /// the container to iterate
-        typename IteratorType::reference container;
+      private:
+        /// the output of the serializer
+        output_adapter_t<char> o = nullptr;
 
-      public:
-        /// construct iteration proxy from a container
-        explicit iteration_proxy(typename IteratorType::reference cont)
-            : container(cont)
-        {}
+        /// a (hopefully) large enough character buffer
+        std::array<char, 64> number_buffer{{}};
 
-        /// return iterator begin (needed for range-based for)
-        iteration_proxy_internal begin() noexcept
-        {
-            return iteration_proxy_internal(container.begin());
-        }
+        /// the locale
+        const std::lconv* loc = nullptr;
+        /// the locale's thousand separator character
+        const char thousands_sep = '\0';
+        /// the locale's decimal point character
+        const char decimal_point = '\0';
 
-        /// return iterator end (needed for range-based for)
-        iteration_proxy_internal end() noexcept
-        {
-            return iteration_proxy_internal(container.end());
-        }
+        /// the indentation character
+        const char indent_char;
+
+        /// the indentation string
+        string_t indent_string;
     };
 
   public:
     /*!
-    @brief a template for a random access iterator for the @ref basic_json class
+    @brief serialize to stream
 
-    This class implements a both iterators (iterator and const_iterator) for the
-    @ref basic_json class.
+    Serialize the given JSON value @a j to the output stream @a o. The JSON
+    value will be serialized using the @ref dump member function.
 
-    @note An iterator is called *initialized* when a pointer to a JSON value
-          has been set (e.g., by a constructor or a copy assignment). If the
-          iterator is default-constructed, it is *uninitialized* and most
-          methods are undefined. **The library uses assertions to detect calls
-          on uninitialized iterators.**
+    - The indentation of the output can be controlled with the member variable
+      `width` of the output stream @a o. For instance, using the manipulator
+      `std::setw(4)` on @a o sets the indentation level to `4` and the
+      serialization result is the same as calling `dump(4)`.
 
-    @requirement The class satisfies the following concept requirements:
-    - [RandomAccessIterator](http://en.cppreference.com/w/cpp/concept/RandomAccessIterator):
-      The iterator that can be moved to point (forward and backward) to any
-      element in constant time.
+    - The indentation characrer can be controlled with the member variable
+      `fill` of the output stream @a o. For instance, the manipulator
+      `std::setfill('\\t')` sets indentation to use a tab character rather than
+      the default space character.
+
+    @param[in,out] o  stream to serialize to
+    @param[in] j  JSON value to serialize
+
+    @return the stream @a o
+
+    @complexity Linear.
+
+    @liveexample{The example below shows the serialization with different
+    parameters to `width` to adjust the indentation level.,operator_serialize}
 
-    @since version 1.0.0, simplified in version 2.0.9
+    @since version 1.0.0; indentaction character added in version 3.0.0
     */
-    template<typename U>
-    class iter_impl : public std::iterator<std::random_access_iterator_tag, U>
+    friend std::ostream& operator<<(std::ostream& o, const basic_json& j)
     {
-        /// allow basic_json to access private members
-        friend class basic_json;
+        // read width member and use it as indentation parameter if nonzero
+        const bool pretty_print = (o.width() > 0);
+        const auto indentation = (pretty_print ? o.width() : 0);
 
-        // make sure U is basic_json or const basic_json
-        static_assert(std::is_same<U, basic_json>::value
-                      or std::is_same<U, const basic_json>::value,
-                      "iter_impl only accepts (const) basic_json");
+        // reset width to 0 for subsequent calls to this stream
+        o.width(0);
 
-      public:
-        /// the type of the values when the iterator is dereferenced
-        using value_type = typename basic_json::value_type;
-        /// a type to represent differences between iterators
-        using difference_type = typename basic_json::difference_type;
-        /// defines a pointer to the type iterated over (value_type)
-        using pointer = typename std::conditional<std::is_const<U>::value,
-              typename basic_json::const_pointer,
-              typename basic_json::pointer>::type;
-        /// defines a reference to the type iterated over (value_type)
-        using reference = typename std::conditional<std::is_const<U>::value,
-              typename basic_json::const_reference,
-              typename basic_json::reference>::type;
-        /// the category of the iterator
-        using iterator_category = std::bidirectional_iterator_tag;
-
-        /// default constructor
-        iter_impl() = default;
+        // do the actual serialization
+        serializer s(output_adapter<char>::create(o), o.fill());
+        s.dump(j, pretty_print, static_cast<unsigned int>(indentation));
+        return o;
+    }
 
-        /*!
-        @brief constructor for a given JSON instance
-        @param[in] object  pointer to a JSON object for this iterator
-        @pre object != nullptr
-        @post The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        explicit iter_impl(pointer object) noexcept
-            : m_object(object)
-        {
-            assert(m_object != nullptr);
+    /*!
+    @brief serialize to stream
+    @deprecated This stream operator is deprecated and will be removed in a
+                future version of the library. Please use
+                @ref std::ostream& operator<<(std::ostream&, const basic_json&)
+                instead; that is, replace calls like `j >> o;` with `o << j;`.
+    */
+    JSON_DEPRECATED
+    friend std::ostream& operator>>(const basic_json& j, std::ostream& o)
+    {
+        return o << j;
+    }
 
-            switch (m_object->m_type)
-            {
-                case basic_json::value_t::object:
-                {
-                    m_it.object_iterator = typename object_t::iterator();
-                    break;
-                }
+    /// @}
 
-                case basic_json::value_t::array:
-                {
-                    m_it.array_iterator = typename array_t::iterator();
-                    break;
-                }
 
-                default:
-                {
-                    m_it.primitive_iterator = primitive_iterator_t();
-                    break;
-                }
-            }
-        }
+    /////////////////////
+    // deserialization //
+    /////////////////////
 
-        /*!
-        @note The conventional copy constructor and copy assignment are
-              implicitly defined.
-              Combined with the following converting constructor and assignment,
-              they support: copy from iterator to iterator,
-                            copy from const iterator to const iterator,
-                            and conversion from iterator to const iterator.
-              However conversion from const iterator to iterator is not defined.
-        */
+    /// @name deserialization
+    /// @{
 
-        /*!
-        @brief converting constructor
-        @param[in] other  non-const iterator to copy from
-        @note It is not checked whether @a other is initialized.
-        */
-        iter_impl(const iter_impl<basic_json>& other) noexcept
-            : m_object(other.m_object), m_it(other.m_it)
-        {}
+    /*!
+    @brief deserialize from an array
 
-        /*!
-        @brief converting assignment
-        @param[in,out] other  non-const iterator to copy from
-        @return const/non-const iterator
-        @note It is not checked whether @a other is initialized.
-        */
-        iter_impl& operator=(const iter_impl<basic_json>& other) noexcept
-        {
-            m_object = other.m_object;
-            m_it = other.m_it;
-            return *this;
-        }
+    This function reads from an array of 1-byte values.
+
+    @pre Each element of the container has a size of 1 byte. Violating this
+    precondition yields undefined behavior. **This precondition is enforced
+    with a static assertion.**
+
+    @param[in] array  array to read from
+    @param[in] cb  a parser callback function of type @ref parser_callback_t
+    which is used to control the deserialization by filtering unwanted values
+    (optional)
+
+    @return result of the deserialization
+
+    @throw parse_error.101 if a parse error occurs; example: `""unexpected end
+    of input; expected string literal""`
+    @throw parse_error.102 if to_unicode fails or surrogate error
+    @throw parse_error.103 if to_unicode fails
+
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser. The complexity can be higher if the parser callback function
+    @a cb has a super-linear complexity.
+
+    @note A UTF-8 byte order mark is silently ignored.
+
+    @liveexample{The example below demonstrates the `parse()` function reading
+    from an array.,parse__array__parser_callback_t}
+
+    @since version 2.0.3
+    */
+    template<class T, std::size_t N>
+    static basic_json parse(T (&array)[N],
+                            const parser_callback_t cb = nullptr)
+    {
+        // delegate the call to the iterator-range parse overload
+        return parse(std::begin(array), std::end(array), cb);
+    }
 
-      private:
-        /*!
-        @brief set the iterator to the first value
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        void set_begin() noexcept
-        {
-            assert(m_object != nullptr);
+    template<class T, std::size_t N>
+    static bool accept(T (&array)[N])
+    {
+        // delegate the call to the iterator-range accept overload
+        return accept(std::begin(array), std::end(array));
+    }
 
-            switch (m_object->m_type)
-            {
-                case basic_json::value_t::object:
-                {
-                    m_it.object_iterator = m_object->m_value.object->begin();
-                    break;
-                }
+    /*!
+    @brief deserialize from string literal
 
-                case basic_json::value_t::array:
-                {
-                    m_it.array_iterator = m_object->m_value.array->begin();
-                    break;
-                }
+    @tparam CharT character/literal type with size of 1 byte
+    @param[in] s  string literal to read a serialized JSON value from
+    @param[in] cb a parser callback function of type @ref parser_callback_t
+    which is used to control the deserialization by filtering unwanted values
+    (optional)
 
-                case basic_json::value_t::null:
-                {
-                    // set to end so begin()==end() is true: null is empty
-                    m_it.primitive_iterator.set_end();
-                    break;
-                }
+    @return result of the deserialization
 
-                default:
-                {
-                    m_it.primitive_iterator.set_begin();
-                    break;
-                }
-            }
-        }
+    @throw parse_error.101 in case of an unexpected token
+    @throw parse_error.102 if to_unicode fails or surrogate error
+    @throw parse_error.103 if to_unicode fails
 
-        /*!
-        @brief set the iterator past the last value
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        void set_end() noexcept
-        {
-            assert(m_object != nullptr);
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser. The complexity can be higher if the parser callback function
+    @a cb has a super-linear complexity.
 
-            switch (m_object->m_type)
-            {
-                case basic_json::value_t::object:
-                {
-                    m_it.object_iterator = m_object->m_value.object->end();
-                    break;
-                }
+    @note A UTF-8 byte order mark is silently ignored.
+    @note String containers like `std::string` or @ref string_t can be parsed
+          with @ref parse(const ContiguousContainer&, const parser_callback_t)
 
-                case basic_json::value_t::array:
-                {
-                    m_it.array_iterator = m_object->m_value.array->end();
-                    break;
-                }
+    @liveexample{The example below demonstrates the `parse()` function with
+    and without callback function.,parse__string__parser_callback_t}
 
-                default:
-                {
-                    m_it.primitive_iterator.set_end();
-                    break;
-                }
-            }
-        }
+    @sa @ref parse(std::istream&, const parser_callback_t) for a version that
+    reads from an input stream
 
-      public:
-        /*!
-        @brief return a reference to the value pointed to by the iterator
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        reference operator*() const
-        {
-            assert(m_object != nullptr);
+    @since version 1.0.0 (originally for @ref string_t)
+    */
+    template<typename CharT, typename std::enable_if<
+                 std::is_pointer<CharT>::value and
+                 std::is_integral<typename std::remove_pointer<CharT>::type>::value and
+                 sizeof(typename std::remove_pointer<CharT>::type) == 1, int>::type = 0>
+    static basic_json parse(const CharT s,
+                            const parser_callback_t cb = nullptr)
+    {
+        return parser(detail::input_adapter_factory::create(s), cb).parse(true);
+    }
 
-            switch (m_object->m_type)
-            {
-                case basic_json::value_t::object:
-                {
-                    assert(m_it.object_iterator != m_object->m_value.object->end());
-                    return m_it.object_iterator->second;
-                }
+    template<typename CharT, typename std::enable_if<
+                 std::is_pointer<CharT>::value and
+                 std::is_integral<typename std::remove_pointer<CharT>::type>::value and
+                 sizeof(typename std::remove_pointer<CharT>::type) == 1, int>::type = 0>
+    static bool accept(const CharT s)
+    {
+        return parser(detail::input_adapter_factory::create(s)).accept(true);
+    }
 
-                case basic_json::value_t::array:
-                {
-                    assert(m_it.array_iterator != m_object->m_value.array->end());
-                    return *m_it.array_iterator;
-                }
+    /*!
+    @brief deserialize from stream
 
-                case basic_json::value_t::null:
-                {
-                    JSON_THROW(invalid_iterator::create(214, "cannot get value"));
-                }
+    @param[in,out] i  stream to read a serialized JSON value from
+    @param[in] cb a parser callback function of type @ref parser_callback_t
+    which is used to control the deserialization by filtering unwanted values
+    (optional)
 
-                default:
-                {
-                    if (m_it.primitive_iterator.is_begin())
-                    {
-                        return *m_object;
-                    }
+    @return result of the deserialization
 
-                    JSON_THROW(invalid_iterator::create(214, "cannot get value"));
-                }
-            }
-        }
+    @throw parse_error.101 in case of an unexpected token
+    @throw parse_error.102 if to_unicode fails or surrogate error
+    @throw parse_error.103 if to_unicode fails
 
-        /*!
-        @brief dereference the iterator
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        pointer operator->() const
-        {
-            assert(m_object != nullptr);
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser. The complexity can be higher if the parser callback function
+    @a cb has a super-linear complexity.
 
-            switch (m_object->m_type)
-            {
-                case basic_json::value_t::object:
-                {
-                    assert(m_it.object_iterator != m_object->m_value.object->end());
-                    return &(m_it.object_iterator->second);
-                }
+    @note A UTF-8 byte order mark is silently ignored.
 
-                case basic_json::value_t::array:
-                {
-                    assert(m_it.array_iterator != m_object->m_value.array->end());
-                    return &*m_it.array_iterator;
-                }
+    @liveexample{The example below demonstrates the `parse()` function with
+    and without callback function.,parse__istream__parser_callback_t}
 
-                default:
-                {
-                    if (m_it.primitive_iterator.is_begin())
-                    {
-                        return m_object;
-                    }
+    @sa @ref parse(const CharT, const parser_callback_t) for a version
+    that reads from a string
 
-                    JSON_THROW(invalid_iterator::create(214, "cannot get value"));
-                }
-            }
-        }
+    @since version 1.0.0
+    */
+    static basic_json parse(std::istream& i,
+                            const parser_callback_t cb = nullptr)
+    {
+        return parser(detail::input_adapter_factory::create(i), cb).parse(true);
+    }
 
-        /*!
-        @brief post-increment (it++)
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        iter_impl operator++(int)
-        {
-            auto result = *this;
-            ++(*this);
-            return result;
-        }
+    static bool accept(std::istream& i)
+    {
+        return parser(detail::input_adapter_factory::create(i)).accept(true);
+    }
 
-        /*!
-        @brief pre-increment (++it)
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        iter_impl& operator++()
-        {
-            assert(m_object != nullptr);
+    /*!
+    @copydoc parse(std::istream&, const parser_callback_t)
+    */
+    static basic_json parse(std::istream&& i,
+                            const parser_callback_t cb = nullptr)
+    {
+        return parser(detail::input_adapter_factory::create(i), cb).parse(true);
+    }
 
-            switch (m_object->m_type)
-            {
-                case basic_json::value_t::object:
-                {
-                    std::advance(m_it.object_iterator, 1);
-                    break;
-                }
+    static bool accept(std::istream&& i)
+    {
+        return parser(detail::input_adapter_factory::create(i)).accept(true);
+    }
 
-                case basic_json::value_t::array:
-                {
-                    std::advance(m_it.array_iterator, 1);
-                    break;
-                }
+    /*!
+    @brief deserialize from an iterator range with contiguous storage
 
-                default:
-                {
-                    ++m_it.primitive_iterator;
-                    break;
-                }
-            }
+    This function reads from an iterator range of a container with contiguous
+    storage of 1-byte values. Compatible container types include
+    `std::vector`, `std::string`, `std::array`, `std::valarray`, and
+    `std::initializer_list`. Furthermore, C-style arrays can be used with
+    `std::begin()`/`std::end()`. User-defined containers can be used as long
+    as they implement random-access iterators and a contiguous storage.
 
-            return *this;
-        }
+    @pre The iterator range is contiguous. Violating this precondition yields
+    undefined behavior. **This precondition is enforced with an assertion.**
+    @pre Each element in the range has a size of 1 byte. Violating this
+    precondition yields undefined behavior. **This precondition is enforced
+    with a static assertion.**
 
-        /*!
-        @brief post-decrement (it--)
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        iter_impl operator--(int)
-        {
-            auto result = *this;
-            --(*this);
-            return result;
-        }
+    @warning There is no way to enforce all preconditions at compile-time. If
+             the function is called with noncompliant iterators and with
+             assertions switched off, the behavior is undefined and will most
+             likely yield segmentation violation.
 
-        /*!
-        @brief pre-decrement (--it)
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        iter_impl& operator--()
-        {
-            assert(m_object != nullptr);
+    @tparam IteratorType iterator of container with contiguous storage
+    @param[in] first  begin of the range to parse (included)
+    @param[in] last  end of the range to parse (excluded)
+    @param[in] cb  a parser callback function of type @ref parser_callback_t
+    which is used to control the deserialization by filtering unwanted values
+    (optional)
 
-            switch (m_object->m_type)
-            {
-                case basic_json::value_t::object:
-                {
-                    std::advance(m_it.object_iterator, -1);
-                    break;
-                }
+    @return result of the deserialization
 
-                case basic_json::value_t::array:
-                {
-                    std::advance(m_it.array_iterator, -1);
-                    break;
-                }
+    @throw parse_error.101 in case of an unexpected token
+    @throw parse_error.102 if to_unicode fails or surrogate error
+    @throw parse_error.103 if to_unicode fails
 
-                default:
-                {
-                    --m_it.primitive_iterator;
-                    break;
-                }
-            }
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser. The complexity can be higher if the parser callback function
+    @a cb has a super-linear complexity.
 
-            return *this;
-        }
+    @note A UTF-8 byte order mark is silently ignored.
 
-        /*!
-        @brief  comparison: equal
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        bool operator==(const iter_impl& other) const
-        {
-            // if objects are not the same, the comparison is undefined
-            if (m_object != other.m_object)
-            {
-                JSON_THROW(invalid_iterator::create(212, "cannot compare iterators of different containers"));
-            }
+    @liveexample{The example below demonstrates the `parse()` function reading
+    from an iterator range.,parse__iteratortype__parser_callback_t}
+
+    @since version 2.0.3
+    */
+    template<class IteratorType, typename std::enable_if<
+                 std::is_base_of<
+                     std::random_access_iterator_tag,
+                     typename std::iterator_traits<IteratorType>::iterator_category>::value, int>::type = 0>
+    static basic_json parse(IteratorType first, IteratorType last,
+                            const parser_callback_t cb = nullptr)
+    {
+        return parser(detail::input_adapter_factory::create(first, last), cb).parse(true);
+    }
 
-            assert(m_object != nullptr);
+    template<class IteratorType, typename std::enable_if<
+                 std::is_base_of<
+                     std::random_access_iterator_tag,
+                     typename std::iterator_traits<IteratorType>::iterator_category>::value, int>::type = 0>
+    static bool accept(IteratorType first, IteratorType last)
+    {
+        return parser(detail::input_adapter_factory::create(first, last)).accept(true);
+    }
 
-            switch (m_object->m_type)
-            {
-                case basic_json::value_t::object:
-                {
-                    return (m_it.object_iterator == other.m_it.object_iterator);
-                }
+    /*!
+    @brief deserialize from a container with contiguous storage
 
-                case basic_json::value_t::array:
-                {
-                    return (m_it.array_iterator == other.m_it.array_iterator);
-                }
+    This function reads from a container with contiguous storage of 1-byte
+    values. Compatible container types include `std::vector`, `std::string`,
+    `std::array`, and `std::initializer_list`. User-defined containers can be
+    used as long as they implement random-access iterators and a contiguous
+    storage.
 
-                default:
-                {
-                    return (m_it.primitive_iterator == other.m_it.primitive_iterator);
-                }
-            }
-        }
+    @pre The container storage is contiguous. Violating this precondition
+    yields undefined behavior. **This precondition is enforced with an
+    assertion.**
+    @pre Each element of the container has a size of 1 byte. Violating this
+    precondition yields undefined behavior. **This precondition is enforced
+    with a static assertion.**
 
-        /*!
-        @brief  comparison: not equal
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        bool operator!=(const iter_impl& other) const
-        {
-            return not operator==(other);
-        }
+    @warning There is no way to enforce all preconditions at compile-time. If
+             the function is called with a noncompliant container and with
+             assertions switched off, the behavior is undefined and will most
+             likely yield segmentation violation.
 
-        /*!
-        @brief  comparison: smaller
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        bool operator<(const iter_impl& other) const
-        {
-            // if objects are not the same, the comparison is undefined
-            if (m_object != other.m_object)
-            {
-                JSON_THROW(invalid_iterator::create(212, "cannot compare iterators of different containers"));
-            }
+    @tparam ContiguousContainer container type with contiguous storage
+    @param[in] c  container to read from
+    @param[in] cb  a parser callback function of type @ref parser_callback_t
+    which is used to control the deserialization by filtering unwanted values
+    (optional)
 
-            assert(m_object != nullptr);
+    @return result of the deserialization
 
-            switch (m_object->m_type)
-            {
-                case basic_json::value_t::object:
-                {
-                    JSON_THROW(invalid_iterator::create(213, "cannot compare order of object iterators"));
-                }
+    @throw parse_error.101 in case of an unexpected token
+    @throw parse_error.102 if to_unicode fails or surrogate error
+    @throw parse_error.103 if to_unicode fails
 
-                case basic_json::value_t::array:
-                {
-                    return (m_it.array_iterator < other.m_it.array_iterator);
-                }
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser. The complexity can be higher if the parser callback function
+    @a cb has a super-linear complexity.
 
-                default:
-                {
-                    return (m_it.primitive_iterator < other.m_it.primitive_iterator);
-                }
-            }
-        }
+    @note A UTF-8 byte order mark is silently ignored.
 
-        /*!
-        @brief  comparison: less than or equal
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        bool operator<=(const iter_impl& other) const
-        {
-            return not other.operator < (*this);
-        }
+    @liveexample{The example below demonstrates the `parse()` function reading
+    from a contiguous container.,parse__contiguouscontainer__parser_callback_t}
 
-        /*!
-        @brief  comparison: greater than
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        bool operator>(const iter_impl& other) const
-        {
-            return not operator<=(other);
-        }
+    @since version 2.0.3
+    */
+    template<class ContiguousContainer, typename std::enable_if<
+                 not std::is_pointer<ContiguousContainer>::value and
+                 std::is_base_of<
+                     std::random_access_iterator_tag,
+                     typename std::iterator_traits<decltype(std::begin(std::declval<ContiguousContainer const>()))>::iterator_category>::value
+                 , int>::type = 0>
+    static basic_json parse(const ContiguousContainer& c,
+                            const parser_callback_t cb = nullptr)
+    {
+        // delegate the call to the iterator-range parse overload
+        return parse(std::begin(c), std::end(c), cb);
+    }
 
-        /*!
-        @brief  comparison: greater than or equal
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        bool operator>=(const iter_impl& other) const
-        {
-            return not operator<(other);
-        }
+    template<class ContiguousContainer, typename std::enable_if<
+                 not std::is_pointer<ContiguousContainer>::value and
+                 std::is_base_of<
+                     std::random_access_iterator_tag,
+                     typename std::iterator_traits<decltype(std::begin(std::declval<ContiguousContainer const>()))>::iterator_category>::value
+                 , int>::type = 0>
+    static bool accept(const ContiguousContainer& c)
+    {
+        // delegate the call to the iterator-range accept overload
+        return accept(std::begin(c), std::end(c));
+    }
 
-        /*!
-        @brief  add to iterator
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        iter_impl& operator+=(difference_type i)
-        {
-            assert(m_object != nullptr);
+    /*!
+    @brief deserialize from stream
+    @deprecated This stream operator is deprecated and will be removed in a
+                future version of the library. Please use
+                @ref std::istream& operator>>(std::istream&, basic_json&)
+                instead; that is, replace calls like `j << i;` with `i >> j;`.
+    */
+    JSON_DEPRECATED
+    friend std::istream& operator<<(basic_json& j, std::istream& i)
+    {
+        j = parser(detail::input_adapter_factory::create(i)).parse(false);
+        return i;
+    }
 
-            switch (m_object->m_type)
-            {
-                case basic_json::value_t::object:
-                {
-                    JSON_THROW(invalid_iterator::create(209, "cannot use offsets with object iterators"));
-                }
+    /*!
+    @brief deserialize from stream
 
-                case basic_json::value_t::array:
-                {
-                    std::advance(m_it.array_iterator, i);
-                    break;
-                }
+    Deserializes an input stream to a JSON value.
 
-                default:
-                {
-                    m_it.primitive_iterator += i;
-                    break;
-                }
-            }
+    @param[in,out] i  input stream to read a serialized JSON value from
+    @param[in,out] j  JSON value to write the deserialized input to
 
-            return *this;
-        }
+    @throw parse_error.101 in case of an unexpected token
+    @throw parse_error.102 if to_unicode fails or surrogate error
+    @throw parse_error.103 if to_unicode fails
 
-        /*!
-        @brief  subtract from iterator
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        iter_impl& operator-=(difference_type i)
-        {
-            return operator+=(-i);
-        }
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser.
 
-        /*!
-        @brief  add to iterator
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        iter_impl operator+(difference_type i) const
-        {
-            auto result = *this;
-            result += i;
-            return result;
-        }
+    @note A UTF-8 byte order mark is silently ignored.
 
-        /*!
-        @brief  addition of distance and iterator
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        friend iter_impl operator+(difference_type i, const iter_impl& it)
-        {
-            auto result = it;
-            result += i;
-            return result;
-        }
+    @liveexample{The example below shows how a JSON value is constructed by
+    reading a serialization from a stream.,operator_deserialize}
 
-        /*!
-        @brief  subtract from iterator
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        iter_impl operator-(difference_type i) const
-        {
-            auto result = *this;
-            result -= i;
-            return result;
-        }
+    @sa parse(std::istream&, const parser_callback_t) for a variant with a
+    parser callback function to filter values while parsing
 
-        /*!
-        @brief  return difference
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        difference_type operator-(const iter_impl& other) const
-        {
-            assert(m_object != nullptr);
+    @since version 1.0.0
+    */
+    friend std::istream& operator>>(std::istream& i, basic_json& j)
+    {
+        j = parser(detail::input_adapter_factory::create(i)).parse(false);
+        return i;
+    }
 
-            switch (m_object->m_type)
-            {
-                case basic_json::value_t::object:
-                {
-                    JSON_THROW(invalid_iterator::create(209, "cannot use offsets with object iterators"));
-                }
+    /// @}
 
-                case basic_json::value_t::array:
-                {
-                    return m_it.array_iterator - other.m_it.array_iterator;
-                }
+    ///////////////////////////
+    // convenience functions //
+    ///////////////////////////
 
-                default:
-                {
-                    return m_it.primitive_iterator - other.m_it.primitive_iterator;
-                }
-            }
-        }
+    /*!
+    @brief return the type as string
 
-        /*!
-        @brief  access to successor
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        reference operator[](difference_type n) const
-        {
-            assert(m_object != nullptr);
+    Returns the type name as string to be used in error messages - usually to
+    indicate that a function was called on a wrong JSON type.
 
-            switch (m_object->m_type)
-            {
-                case basic_json::value_t::object:
-                {
-                    JSON_THROW(invalid_iterator::create(208, "cannot use operator[] for object iterators"));
-                }
+    @return basically a string representation of a the @a m_type member
 
-                case basic_json::value_t::array:
-                {
-                    return *std::next(m_it.array_iterator, n);
-                }
+    @complexity Constant.
 
-                case basic_json::value_t::null:
-                {
-                    JSON_THROW(invalid_iterator::create(214, "cannot get value"));
-                }
+    @liveexample{The following code exemplifies `type_name()` for all JSON
+    types.,type_name}
 
+    @since version 1.0.0, public since 2.1.0
+    */
+    std::string type_name() const
+    {
+        {
+            switch (m_type)
+            {
+                case value_t::null:
+                    return "null";
+                case value_t::object:
+                    return "object";
+                case value_t::array:
+                    return "array";
+                case value_t::string:
+                    return "string";
+                case value_t::boolean:
+                    return "boolean";
+                case value_t::discarded:
+                    return "discarded";
                 default:
-                {
-                    if (m_it.primitive_iterator.get_value() == -n)
-                    {
-                        return *m_object;
-                    }
-
-                    JSON_THROW(invalid_iterator::create(214, "cannot get value"));
-                }
+                    return "number";
             }
         }
+    }
 
-        /*!
-        @brief  return the key of an object iterator
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        typename object_t::key_type key() const
-        {
-            assert(m_object != nullptr);
-
-            if (m_object->is_object())
-            {
-                return m_it.object_iterator->first;
-            }
 
-            JSON_THROW(invalid_iterator::create(207, "cannot use key() for non-object iterators"));
-        }
+  private:
+    //////////////////////
+    // member variables //
+    //////////////////////
 
-        /*!
-        @brief  return the value of an iterator
-        @pre The iterator is initialized; i.e. `m_object != nullptr`.
-        */
-        reference value() const
-        {
-            return operator*();
-        }
+    /// the type of the current element
+    value_t m_type = value_t::null;
 
-      private:
-        /// associated JSON instance
-        pointer m_object = nullptr;
-        /// the actual iterator of the associated instance
-        struct internal_iterator m_it = internal_iterator();
-    };
+    /// the value of the current element
+    json_value m_value = {};
 
+  public:
     /*!
     @brief a template for a reverse iterator class
 

From bb752fd30c569ff0c2bc6953fe98622cb7e73dc8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9o=20DELRIEU?= <delrieutheo@gmail.com>
Date: Sun, 9 Jul 2017 17:20:03 +0200
Subject: [PATCH 7/9] move json_reverse_iterator outside of basic_json

---
 src/json.hpp | 215 +++++++++++++++++++++++++--------------------------
 1 file changed, 106 insertions(+), 109 deletions(-)

diff --git a/src/json.hpp b/src/json.hpp
index 1e75b5e251..7ecbe91d05 100644
--- a/src/json.hpp
+++ b/src/json.hpp
@@ -4459,6 +4459,111 @@ template <typename IteratorType> class iteration_proxy
         return iteration_proxy_internal(container.end());
     }
 };
+
+/*!
+@brief a template for a reverse iterator class
+
+@tparam Base the base iterator type to reverse. Valid types are @ref
+iterator (to create @ref reverse_iterator) and @ref const_iterator (to
+create @ref const_reverse_iterator).
+
+@requirement The class satisfies the following concept requirements:
+-
+[RandomAccessIterator](http://en.cppreference.com/w/cpp/concept/RandomAccessIterator):
+  The iterator that can be moved to point (forward and backward) to any
+  element in constant time.
+- [OutputIterator](http://en.cppreference.com/w/cpp/concept/OutputIterator):
+  It is possible to write to the pointed-to element (only if @a Base is
+  @ref iterator).
+
+@since version 1.0.0
+*/
+template <typename Base>
+class json_reverse_iterator : public std::reverse_iterator<Base>
+{
+  public:
+    using difference_type = std::ptrdiff_t;
+    /// shortcut to the reverse iterator adaptor
+    using base_iterator = std::reverse_iterator<Base>;
+    /// the reference type for the pointed-to element
+    using reference = typename Base::reference;
+
+    /// create reverse iterator from iterator
+    json_reverse_iterator(
+        const typename base_iterator::iterator_type& it) noexcept
+        : base_iterator(it) {}
+
+    /// create reverse iterator from base class
+    json_reverse_iterator(const base_iterator& it) noexcept : base_iterator(it) {}
+
+    /// post-increment (it++)
+    json_reverse_iterator operator++(int)
+    {
+        return static_cast<json_reverse_iterator>(base_iterator::operator++(1));
+    }
+
+    /// pre-increment (++it)
+    json_reverse_iterator& operator++()
+    {
+        return static_cast<json_reverse_iterator&>(base_iterator::operator++());
+    }
+
+    /// post-decrement (it--)
+    json_reverse_iterator operator--(int)
+    {
+        return static_cast<json_reverse_iterator>(base_iterator::operator--(1));
+    }
+
+    /// pre-decrement (--it)
+    json_reverse_iterator& operator--()
+    {
+        return static_cast<json_reverse_iterator&>(base_iterator::operator--());
+    }
+
+    /// add to iterator
+    json_reverse_iterator& operator+=(difference_type i)
+    {
+        return static_cast<json_reverse_iterator&>(base_iterator::operator+=(i));
+    }
+
+    /// add to iterator
+    json_reverse_iterator operator+(difference_type i) const
+    {
+        return static_cast<json_reverse_iterator>(base_iterator::operator+(i));
+    }
+
+    /// subtract from iterator
+    json_reverse_iterator operator-(difference_type i) const
+    {
+        return static_cast<json_reverse_iterator>(base_iterator::operator-(i));
+    }
+
+    /// return difference
+    difference_type operator-(const json_reverse_iterator& other) const
+    {
+        return base_iterator(*this) - base_iterator(other);
+    }
+
+    /// access to successor
+    reference operator[](difference_type n) const
+    {
+        return *(this->operator+(n));
+    }
+
+    /// return the key of an object iterator
+    auto key() const -> decltype(std::declval<Base>().key())
+    {
+        auto it = --this->base();
+        return it.key();
+    }
+
+    /// return the value of an iterator
+    reference value() const
+    {
+        auto it = --this->base();
+        return it.operator * ();
+    }
+};
 } // namespace detail
 
 /// namespace to hold default `to_json` / `from_json` functions
@@ -4946,11 +5051,11 @@ class basic_json
     using iter_impl = ::nlohmann::detail::iter_impl<BasicJsonType>;
     template <typename Iterator>
     using iteration_proxy = ::nlohmann::detail::iteration_proxy<Iterator>;
+    template<typename Base> using json_reverse_iterator = ::nlohmann::detail::json_reverse_iterator<Base>;
 
   public:
     using value_t = detail::value_t;
     // forward declarations
-    template<typename Base> class json_reverse_iterator;
     using json_pointer = ::nlohmann::json_pointer;
     template<typename T, typename SFINAE>
     using json_serializer = JSONSerializer<T, SFINAE>;
@@ -11298,114 +11403,6 @@ class basic_json
     /// the value of the current element
     json_value m_value = {};
 
-  public:
-    /*!
-    @brief a template for a reverse iterator class
-
-    @tparam Base the base iterator type to reverse. Valid types are @ref
-    iterator (to create @ref reverse_iterator) and @ref const_iterator (to
-    create @ref const_reverse_iterator).
-
-    @requirement The class satisfies the following concept requirements:
-    - [RandomAccessIterator](http://en.cppreference.com/w/cpp/concept/RandomAccessIterator):
-      The iterator that can be moved to point (forward and backward) to any
-      element in constant time.
-    - [OutputIterator](http://en.cppreference.com/w/cpp/concept/OutputIterator):
-      It is possible to write to the pointed-to element (only if @a Base is
-      @ref iterator).
-
-    @since version 1.0.0
-    */
-    template<typename Base>
-    class json_reverse_iterator : public std::reverse_iterator<Base>
-    {
-      public:
-        /// shortcut to the reverse iterator adaptor
-        using base_iterator = std::reverse_iterator<Base>;
-        /// the reference type for the pointed-to element
-        using reference = typename Base::reference;
-
-        /// create reverse iterator from iterator
-        json_reverse_iterator(const typename base_iterator::iterator_type& it) noexcept
-            : base_iterator(it)
-        {}
-
-        /// create reverse iterator from base class
-        json_reverse_iterator(const base_iterator& it) noexcept
-            : base_iterator(it)
-        {}
-
-        /// post-increment (it++)
-        json_reverse_iterator operator++(int)
-        {
-            return static_cast<json_reverse_iterator>(base_iterator::operator++(1));
-        }
-
-        /// pre-increment (++it)
-        json_reverse_iterator& operator++()
-        {
-            return static_cast<json_reverse_iterator&>(base_iterator::operator++());
-        }
-
-        /// post-decrement (it--)
-        json_reverse_iterator operator--(int)
-        {
-            return static_cast<json_reverse_iterator>(base_iterator::operator--(1));
-        }
-
-        /// pre-decrement (--it)
-        json_reverse_iterator& operator--()
-        {
-            return static_cast<json_reverse_iterator&>(base_iterator::operator--());
-        }
-
-        /// add to iterator
-        json_reverse_iterator& operator+=(difference_type i)
-        {
-            return static_cast<json_reverse_iterator&>(base_iterator::operator+=(i));
-        }
-
-        /// add to iterator
-        json_reverse_iterator operator+(difference_type i) const
-        {
-            return static_cast<json_reverse_iterator>(base_iterator::operator+(i));
-        }
-
-        /// subtract from iterator
-        json_reverse_iterator operator-(difference_type i) const
-        {
-            return static_cast<json_reverse_iterator>(base_iterator::operator-(i));
-        }
-
-        /// return difference
-        difference_type operator-(const json_reverse_iterator& other) const
-        {
-            return base_iterator(*this) - base_iterator(other);
-        }
-
-        /// access to successor
-        reference operator[](difference_type n) const
-        {
-            return *(this->operator+(n));
-        }
-
-        /// return the key of an object iterator
-        typename object_t::key_type key() const
-        {
-            auto it = --this->base();
-            return it.key();
-        }
-
-        /// return the value of an iterator
-        reference value() const
-        {
-            auto it = --this->base();
-            return it.operator * ();
-        }
-    };
-
-
-  private:
     //////////////////////////////////////////
     // binary serialization/deserialization //
     //////////////////////////////////////////

From acff23efb25b13de0e3b8d5d4e01d17dd550c3d2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9o=20DELRIEU?= <delrieutheo@gmail.com>
Date: Sun, 9 Jul 2017 17:31:25 +0200
Subject: [PATCH 8/9] move binary_{reader,writer} outside of basic_json

---
 src/json.hpp                  | 13255 ++++++++++++++++----------------
 test/src/unit-convenience.cpp |     2 +-
 2 files changed, 6651 insertions(+), 6606 deletions(-)

diff --git a/src/json.hpp b/src/json.hpp
index 7ecbe91d05..d3f3571017 100644
--- a/src/json.hpp
+++ b/src/json.hpp
@@ -4564,8522 +4564,8567 @@ class json_reverse_iterator : public std::reverse_iterator<Base>
         return it.operator * ();
     }
 };
-} // namespace detail
 
-/// namespace to hold default `to_json` / `from_json` functions
-namespace
-{
-constexpr const auto& to_json = detail::static_const<detail::to_json_fn>::value;
-constexpr const auto& from_json = detail::static_const<detail::from_json_fn>::value;
-}
+/////////////////////
+// output adapters //
+/////////////////////
 
+/// abstract output adapter interface
+template <typename CharType> class output_adapter
+{
+  public:
+    virtual void write_character(CharType c) = 0;
+    virtual void write_characters(const CharType* s, size_t length) = 0;
+    virtual ~output_adapter() {}
+};
 
-/*!
-@brief default JSONSerializer template argument
+/// a type to simplify interfaces
+template <typename CharType>
+using output_adapter_t = std::shared_ptr<output_adapter<CharType>>;
 
-This serializer ignores the template arguments and uses ADL
-([argument-dependent lookup](http://en.cppreference.com/w/cpp/language/adl))
-for serialization.
-*/
-template<typename, typename>
-struct adl_serializer
+/// output adapter for byte vectors
+template <typename CharType>
+class output_vector_adapter : public output_adapter<CharType>
 {
-    /*!
-    @brief convert a JSON value to any value type
-
-    This function is usually called by the `get()` function of the
-    @ref basic_json class (either explicit or via conversion operators).
+  public:
+    output_vector_adapter(std::vector<CharType>& vec) : v(vec) {}
 
-    @param[in] j         JSON value to read from
-    @param[in,out] val  value to write to
-    */
-    template<typename BasicJsonType, typename ValueType>
-    static void from_json(BasicJsonType&& j, ValueType& val) noexcept(
-        noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), val)))
+    void write_character(CharType c) override
     {
-        ::nlohmann::from_json(std::forward<BasicJsonType>(j), val);
+        v.push_back(c);
     }
 
-    /*!
-    @brief convert any value type to a JSON value
-
-    This function is usually called by the constructors of the @ref basic_json
-    class.
-
-    @param[in,out] j  JSON value to write to
-    @param[in] val     value to read from
-    */
-    template<typename BasicJsonType, typename ValueType>
-    static void to_json(BasicJsonType& j, ValueType&& val) noexcept(
-        noexcept(::nlohmann::to_json(j, std::forward<ValueType>(val))))
+    void write_characters(const CharType* s, size_t length) override
     {
-        ::nlohmann::to_json(j, std::forward<ValueType>(val));
+        std::copy(s, s + length, std::back_inserter(v));
     }
-};
-
-/*!
-@brief JSON Pointer
-
-A JSON pointer defines a string syntax for identifying a specific value
-within a JSON document. It can be used with functions `at` and
-`operator[]`. Furthermore, JSON pointers are the base for JSON patches.
 
-@sa [RFC 6901](https://tools.ietf.org/html/rfc6901)
+  private:
+    std::vector<CharType>& v;
+};
 
-@since version 2.0.0
-*/
-class json_pointer
+/// output adapter for output streams
+template <typename CharType>
+class output_stream_adapter : public output_adapter<CharType>
 {
-    /// allow basic_json to access private members
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    friend class basic_json;
-
   public:
-    /*!
-      @brief create JSON pointer
-
-      Create a JSON pointer according to the syntax described in
-      [Section 3 of RFC6901](https://tools.ietf.org/html/rfc6901#section-3).
-
-      @param[in] s  string representing the JSON pointer; if omitted, the
-      empty string is assumed which references the whole JSON
-      value
-
-      @throw parse_error.107 if the given JSON pointer @a s is nonempty and
-      does not begin with a slash (`/`); see example below
-
-      @throw parse_error.108 if a tilde (`~`) in the given JSON pointer @a s
-      is not followed by `0` (representing `~`) or `1` (representing `/`);
-      see example below
-
-      @liveexample{The example shows the construction several valid JSON
-      pointers as well as the exceptional behavior.,json_pointer}
-
-      @since version 2.0.0
-      */
-    explicit json_pointer(const std::string& s = "") : reference_tokens(split(s)) {}
+    output_stream_adapter(std::basic_ostream<CharType>& s) : stream(s) {}
 
-    /*!
-      @brief return a string representation of the JSON pointer
+    void write_character(CharType c) override
+    {
+        stream.put(c);
+    }
 
-      @invariant For each JSON pointer `ptr`, it holds:
-      @code {.cpp}
-      ptr == json_pointer(ptr.to_string());
-      @endcode
+    void write_characters(const CharType* s, size_t length) override
+    {
+        stream.write(s, static_cast<std::streamsize>(length));
+    }
 
-      @return a string representation of the JSON pointer
+  private:
+    std::basic_ostream<CharType>& stream;
+};
 
-      @liveexample{The example shows the result of `to_string`.,
-      json_pointer__to_string}
+/// output adapter for basic_string
+template <typename CharType>
+class output_string_adapter : public output_adapter<CharType>
+{
+  public:
+    output_string_adapter(std::string& s) : str(s) {}
 
-      @since version 2.0.0
-      */
-    std::string to_string() const noexcept
+    void write_character(CharType c) override
     {
-        return std::accumulate(reference_tokens.begin(), reference_tokens.end(),
-                               std::string{},
-                               [](const std::string & a, const std::string & b)
-        {
-            return a + "/" + escape(b);
-        });
+        str.push_back(c);
     }
 
-    /// @copydoc to_string()
-    operator std::string() const
+    void write_characters(const CharType* s, size_t length) override
     {
-        return to_string();
+        str.append(s, length);
     }
 
   private:
-    /*!
-      @brief remove and return last reference pointer
-      @throw out_of_range.405 if JSON pointer has no parent
-      */
-    std::string pop_back()
-    {
-        if (is_root())
-        {
-            JSON_THROW(
-                detail::out_of_range::create(405, "JSON pointer has no parent"));
-        }
+    std::basic_string<CharType>& str;
+};
 
-        auto last = reference_tokens.back();
-        reference_tokens.pop_back();
-        return last;
+template <typename CharType> struct output_adapter_factory
+{
+    static std::shared_ptr<output_adapter<CharType>>
+            create(std::vector<CharType>& vec)
+    {
+        return std::make_shared<output_vector_adapter<CharType>>(vec);
     }
 
-    /// return whether pointer points to the root document
-    bool is_root() const
+    static std::shared_ptr<output_adapter<CharType>> create(std::ostream& s)
     {
-        return reference_tokens.empty();
+        return std::make_shared<output_stream_adapter<CharType>>(s);
     }
 
-    json_pointer top() const
+    static std::shared_ptr<output_adapter<CharType>> create(std::string& s)
     {
-        if (is_root())
-        {
-            JSON_THROW(detail::out_of_range::create(405, "JSON pointer has no parent"));
-        }
-
-        json_pointer result = *this;
-        result.reference_tokens = {reference_tokens[0]};
-        return result;
+        return std::make_shared<output_string_adapter<CharType>>(s);
     }
+};
 
+//////////////////////////////
+// binary reader and writer //
+//////////////////////////////
 
-    /*!
-      @brief create and return a reference to the pointed to value
+/*!
+@brief deserialization of CBOR and MessagePack values
+*/
+template <typename BasicJsonType>
+class binary_reader
+{
+    using number_integer_t = typename BasicJsonType::number_integer_t;
+    using number_unsigned_t = typename BasicJsonType::number_unsigned_t;
 
-      @complexity Linear in the number of reference tokens.
+  public:
+    /*!
+    @brief create a binary reader
 
-      @throw parse_error.109 if array index is not a number
-      @throw type_error.313 if value cannot be unflattened
-      */
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    NLOHMANN_BASIC_JSON_TPL& get_and_create(NLOHMANN_BASIC_JSON_TPL& j) const;
+    @param[in] adapter  input adapter to read from
+    */
+    explicit binary_reader(input_adapter_t adapter)
+        : ia(adapter), is_little_endian(little_endianess())
+    {
+        assert(ia);
+    }
 
     /*!
-      @brief return a reference to the pointed to value
-
-      @note This version does not throw if a value is not present, but tries
-      to create nested values instead. For instance, calling this function
-      with pointer `"/this/that"` on a null value is equivalent to calling
-      `operator[]("this").operator[]("that")` on that value, effectively
-      changing the null value to an object.
+    @brief create a JSON value from CBOR input
 
-      @param[in] ptr  a JSON value
+    @param[in] get_char  whether a new character should be retrieved from
+                         the input (true, default) or whether the last
+                         read character should be considered instead
 
-      @return reference to the JSON value pointed to by the JSON pointer
+    @return JSON value created from CBOR input
 
-      @complexity Linear in the length of the JSON pointer.
+    @throw parse_error.110 if input ended unexpectedly
+    @throw parse_error.112 if unsupported byte was read
+    */
+    BasicJsonType parse_cbor(const bool get_char = true)
+    {
+        switch (get_char ? get() : current)
+        {
+            // EOF
+            case std::char_traits<char>::eof():
+            {
+                JSON_THROW(
+                    parse_error::create(110, chars_read, "unexpected end of input"));
+            }
 
-      @throw parse_error.106   if an array index begins with '0'
-      @throw parse_error.109   if an array index was not a number
-      @throw out_of_range.404  if the JSON pointer can not be resolved
-      */
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    NLOHMANN_BASIC_JSON_TPL& get_unchecked(NLOHMANN_BASIC_JSON_TPL* ptr) const;
+            // Integer 0x00..0x17 (0..23)
+            case 0x00:
+            case 0x01:
+            case 0x02:
+            case 0x03:
+            case 0x04:
+            case 0x05:
+            case 0x06:
+            case 0x07:
+            case 0x08:
+            case 0x09:
+            case 0x0a:
+            case 0x0b:
+            case 0x0c:
+            case 0x0d:
+            case 0x0e:
+            case 0x0f:
+            case 0x10:
+            case 0x11:
+            case 0x12:
+            case 0x13:
+            case 0x14:
+            case 0x15:
+            case 0x16:
+            case 0x17:
+            {
+                return static_cast<number_unsigned_t>(current);
+            }
 
-    /*!
-      @throw parse_error.106   if an array index begins with '0'
-      @throw parse_error.109   if an array index was not a number
-      @throw out_of_range.402  if the array index '-' is used
-      @throw out_of_range.404  if the JSON pointer can not be resolved
-      */
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    NLOHMANN_BASIC_JSON_TPL& get_checked(NLOHMANN_BASIC_JSON_TPL* ptr) const;
+            case 0x18: // Unsigned integer (one-byte uint8_t follows)
+            {
+                return get_number<uint8_t>();
+            }
 
-    /*!
-      @brief return a const reference to the pointed to value
+            case 0x19: // Unsigned integer (two-byte uint16_t follows)
+            {
+                return get_number<uint16_t>();
+            }
 
-      @param[in] ptr  a JSON value
+            case 0x1a: // Unsigned integer (four-byte uint32_t follows)
+            {
+                return get_number<uint32_t>();
+            }
+
+            case 0x1b: // Unsigned integer (eight-byte uint64_t follows)
+            {
+                return get_number<uint64_t>();
+            }
+
+            // Negative integer -1-0x00..-1-0x17 (-1..-24)
+            case 0x20:
+            case 0x21:
+            case 0x22:
+            case 0x23:
+            case 0x24:
+            case 0x25:
+            case 0x26:
+            case 0x27:
+            case 0x28:
+            case 0x29:
+            case 0x2a:
+            case 0x2b:
+            case 0x2c:
+            case 0x2d:
+            case 0x2e:
+            case 0x2f:
+            case 0x30:
+            case 0x31:
+            case 0x32:
+            case 0x33:
+            case 0x34:
+            case 0x35:
+            case 0x36:
+            case 0x37:
+            {
+                return static_cast<int8_t>(0x20 - 1 - current);
+            }
+
+            case 0x38: // Negative integer (one-byte uint8_t follows)
+            {
+                // must be uint8_t !
+                return static_cast<number_integer_t>(-1) - get_number<uint8_t>();
+            }
+
+            case 0x39: // Negative integer -1-n (two-byte uint16_t follows)
+            {
+                return static_cast<number_integer_t>(-1) - get_number<uint16_t>();
+            }
+
+            case 0x3a: // Negative integer -1-n (four-byte uint32_t follows)
+            {
+                return static_cast<number_integer_t>(-1) - get_number<uint32_t>();
+            }
+
+            case 0x3b: // Negative integer -1-n (eight-byte uint64_t follows)
+            {
+                return static_cast<number_integer_t>(-1) -
+                       static_cast<number_integer_t>(get_number<uint64_t>());
+            }
+
+            // UTF-8 string (0x00..0x17 bytes follow)
+            case 0x60:
+            case 0x61:
+            case 0x62:
+            case 0x63:
+            case 0x64:
+            case 0x65:
+            case 0x66:
+            case 0x67:
+            case 0x68:
+            case 0x69:
+            case 0x6a:
+            case 0x6b:
+            case 0x6c:
+            case 0x6d:
+            case 0x6e:
+            case 0x6f:
+            case 0x70:
+            case 0x71:
+            case 0x72:
+            case 0x73:
+            case 0x74:
+            case 0x75:
+            case 0x76:
+            case 0x77:
+            case 0x78: // UTF-8 string (one-byte uint8_t for n follows)
+            case 0x79: // UTF-8 string (two-byte uint16_t for n follow)
+            case 0x7a: // UTF-8 string (four-byte uint32_t for n follow)
+            case 0x7b: // UTF-8 string (eight-byte uint64_t for n follow)
+            case 0x7f: // UTF-8 string (indefinite length)
+            {
+                return get_cbor_string();
+            }
+
+            // array (0x00..0x17 data items follow)
+            case 0x80:
+            case 0x81:
+            case 0x82:
+            case 0x83:
+            case 0x84:
+            case 0x85:
+            case 0x86:
+            case 0x87:
+            case 0x88:
+            case 0x89:
+            case 0x8a:
+            case 0x8b:
+            case 0x8c:
+            case 0x8d:
+            case 0x8e:
+            case 0x8f:
+            case 0x90:
+            case 0x91:
+            case 0x92:
+            case 0x93:
+            case 0x94:
+            case 0x95:
+            case 0x96:
+            case 0x97:
+            {
+                BasicJsonType result = value_t::array;
+                const auto len = static_cast<size_t>(current & 0x1f);
+                for (size_t i = 0; i < len; ++i)
+                {
+                    result.push_back(parse_cbor());
+                }
+                return result;
+            }
 
-      @return const reference to the JSON value pointed to by the JSON
-      pointer
+            case 0x98: // array (one-byte uint8_t for n follows)
+            {
+                BasicJsonType result = value_t::array;
+                const auto len = static_cast<size_t>(get_number<uint8_t>());
+                for (size_t i = 0; i < len; ++i)
+                {
+                    result.push_back(parse_cbor());
+                }
+                return result;
+            }
 
-      @throw parse_error.106   if an array index begins with '0'
-      @throw parse_error.109   if an array index was not a number
-      @throw out_of_range.402  if the array index '-' is used
-      @throw out_of_range.404  if the JSON pointer can not be resolved
-      */
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    const NLOHMANN_BASIC_JSON_TPL& get_unchecked(const NLOHMANN_BASIC_JSON_TPL* ptr) const;
+            case 0x99: // array (two-byte uint16_t for n follow)
+            {
+                BasicJsonType result = value_t::array;
+                const auto len = static_cast<size_t>(get_number<uint16_t>());
+                for (size_t i = 0; i < len; ++i)
+                {
+                    result.push_back(parse_cbor());
+                }
+                return result;
+            }
 
-    /*!
-      @throw parse_error.106   if an array index begins with '0'
-      @throw parse_error.109   if an array index was not a number
-      @throw out_of_range.402  if the array index '-' is used
-      @throw out_of_range.404  if the JSON pointer can not be resolved
-      */
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    const NLOHMANN_BASIC_JSON_TPL& get_checked(const NLOHMANN_BASIC_JSON_TPL* ptr) const;
+            case 0x9a: // array (four-byte uint32_t for n follow)
+            {
+                BasicJsonType result = value_t::array;
+                const auto len = static_cast<size_t>(get_number<uint32_t>());
+                for (size_t i = 0; i < len; ++i)
+                {
+                    result.push_back(parse_cbor());
+                }
+                return result;
+            }
 
-    /*!
-      @brief split the string input to reference tokens
+            case 0x9b: // array (eight-byte uint64_t for n follow)
+            {
+                BasicJsonType result = value_t::array;
+                const auto len = static_cast<size_t>(get_number<uint64_t>());
+                for (size_t i = 0; i < len; ++i)
+                {
+                    result.push_back(parse_cbor());
+                }
+                return result;
+            }
 
-      @note This function is only called by the json_pointer constructor.
-      All exceptions below are documented there.
+            case 0x9f: // array (indefinite length)
+            {
+                BasicJsonType result = value_t::array;
+                while (get() != 0xff)
+                {
+                    result.push_back(parse_cbor(false));
+                }
+                return result;
+            }
 
-      @throw parse_error.107  if the pointer is not empty or begins with '/'
-      @throw parse_error.108  if character '~' is not followed by '0' or '1'
-      */
-    static std::vector<std::string> split(const std::string& reference_string)
-    {
-        std::vector<std::string> result;
+            // map (0x00..0x17 pairs of data items follow)
+            case 0xa0:
+            case 0xa1:
+            case 0xa2:
+            case 0xa3:
+            case 0xa4:
+            case 0xa5:
+            case 0xa6:
+            case 0xa7:
+            case 0xa8:
+            case 0xa9:
+            case 0xaa:
+            case 0xab:
+            case 0xac:
+            case 0xad:
+            case 0xae:
+            case 0xaf:
+            case 0xb0:
+            case 0xb1:
+            case 0xb2:
+            case 0xb3:
+            case 0xb4:
+            case 0xb5:
+            case 0xb6:
+            case 0xb7:
+            {
+                BasicJsonType result = value_t::object;
+                const auto len = static_cast<size_t>(current & 0x1f);
+                for (size_t i = 0; i < len; ++i)
+                {
+                    get();
+                    auto key = get_cbor_string();
+                    result[key] = parse_cbor();
+                }
+                return result;
+            }
 
-        // special case: empty reference string -> no reference tokens
-        if (reference_string.empty())
-        {
-            return result;
-        }
+            case 0xb8: // map (one-byte uint8_t for n follows)
+            {
+                BasicJsonType result = value_t::object;
+                const auto len = static_cast<size_t>(get_number<uint8_t>());
+                for (size_t i = 0; i < len; ++i)
+                {
+                    get();
+                    auto key = get_cbor_string();
+                    result[key] = parse_cbor();
+                }
+                return result;
+            }
 
-        // check if nonempty reference string begins with slash
-        if (reference_string[0] != '/')
-        {
-            JSON_THROW(detail::parse_error::create(
-                           107, 1,
-                           "JSON pointer must be empty or begin with '/' - was: '" +
-                           reference_string + "'"));
-        }
+            case 0xb9: // map (two-byte uint16_t for n follow)
+            {
+                BasicJsonType result = value_t::object;
+                const auto len = static_cast<size_t>(get_number<uint16_t>());
+                for (size_t i = 0; i < len; ++i)
+                {
+                    get();
+                    auto key = get_cbor_string();
+                    result[key] = parse_cbor();
+                }
+                return result;
+            }
 
-        // extract the reference tokens:
-        // - slash: position of the last read slash (or end of string)
-        // - start: position after the previous slash
-        for (
-            // search for the first slash after the first character
-            size_t slash = reference_string.find_first_of('/', 1),
-            // set the beginning of the first reference token
-            start = 1;
-            // we can stop if start == string::npos+1 = 0
-            start != 0;
-            // set the beginning of the next reference token
-            // (will eventually be 0 if slash == std::string::npos)
-            start = slash + 1,
-            // find next slash
-            slash = reference_string.find_first_of('/', start))
-        {
-            // use the text between the beginning of the reference token
-            // (start) and the last slash (slash).
-            auto reference_token = reference_string.substr(start, slash - start);
+            case 0xba: // map (four-byte uint32_t for n follow)
+            {
+                BasicJsonType result = value_t::object;
+                const auto len = static_cast<size_t>(get_number<uint32_t>());
+                for (size_t i = 0; i < len; ++i)
+                {
+                    get();
+                    auto key = get_cbor_string();
+                    result[key] = parse_cbor();
+                }
+                return result;
+            }
 
-            // check reference tokens are properly escaped
-            for (size_t pos = reference_token.find_first_of('~');
-                    pos != std::string::npos;
-                    pos = reference_token.find_first_of('~', pos + 1))
+            case 0xbb: // map (eight-byte uint64_t for n follow)
             {
-                assert(reference_token[pos] == '~');
+                BasicJsonType result = value_t::object;
+                const auto len = static_cast<size_t>(get_number<uint64_t>());
+                for (size_t i = 0; i < len; ++i)
+                {
+                    get();
+                    auto key = get_cbor_string();
+                    result[key] = parse_cbor();
+                }
+                return result;
+            }
 
-                // ~ must be followed by 0 or 1
-                if (pos == reference_token.size() - 1 or
-                        (reference_token[pos + 1] != '0' and
-                         reference_token[pos + 1] != '1'))
+            case 0xbf: // map (indefinite length)
+            {
+                BasicJsonType result = value_t::object;
+                while (get() != 0xff)
                 {
-                    JSON_THROW(detail::parse_error::create(
-                                   108, 0, "escape character '~' must be followed with '0' or '1'"));
+                    auto key = get_cbor_string();
+                    result[key] = parse_cbor();
                 }
+                return result;
             }
 
-            // finally, store the reference token
-            unescape(reference_token);
-            result.push_back(reference_token);
-        }
+            case 0xf4: // false
+            {
+                return false;
+            }
 
-        return result;
-    }
+            case 0xf5: // true
+            {
+                return true;
+            }
 
-    /*!
-      @brief replace all occurrences of a substring by another string
+            case 0xf6: // null
+            {
+                return value_t::null;
+            }
 
-      @param[in,out] s  the string to manipulate; changed so that all
-      occurrences of @a f are replaced with @a t
-      @param[in]     f  the substring to replace with @a t
-      @param[in]     t  the string to replace @a f
+            case 0xf9: // Half-Precision Float (two-byte IEEE 754)
+            {
+                const int byte1 = get();
+                check_eof();
+                const int byte2 = get();
+                check_eof();
 
-      @pre The search string @a f must not be empty. **This precondition is
-      enforced with an assertion.**
+                // code from RFC 7049, Appendix D, Figure 3:
+                // As half-precision floating-point numbers were only added
+                // to IEEE 754 in 2008, today's programming platforms often
+                // still only have limited support for them. It is very
+                // easy to include at least decoding support for them even
+                // without such support. An example of a small decoder for
+                // half-precision floating-point numbers in the C language
+                // is shown in Fig. 3.
+                const int half = (byte1 << 8) + byte2;
+                const int exp = (half >> 10) & 0x1f;
+                const int mant = half & 0x3ff;
+                double val;
+                if (exp == 0)
+                {
+                    val = std::ldexp(mant, -24);
+                }
+                else if (exp != 31)
+                {
+                    val = std::ldexp(mant + 1024, exp - 25);
+                }
+                else
+                {
+                    val = (mant == 0) ? std::numeric_limits<double>::infinity()
+                          : std::numeric_limits<double>::quiet_NaN();
+                }
+                return (half & 0x8000) != 0 ? -val : val;
+            }
 
-      @since version 2.0.0
-      */
-    static void replace_substring(std::string& s, const std::string& f,
-                                  const std::string& t)
-    {
-        assert(not f.empty());
+            case 0xfa: // Single-Precision Float (four-byte IEEE 754)
+            {
+                return get_number<float>();
+            }
 
-        for (size_t pos = s.find(f);         // find first occurrence of f
-                pos != std::string::npos;       // make sure f was found
-                s.replace(pos, f.size(), t),    // replace with t
-                pos = s.find(f, pos + t.size()) // find next occurrence of f
-            )
-            ;
-    }
+            case 0xfb: // Double-Precision Float (eight-byte IEEE 754)
+            {
+                return get_number<double>();
+            }
 
-    /// escape tilde and slash
-    static std::string escape(std::string s)
-    {
-        // escape "~"" to "~0" and "/" to "~1"
-        replace_substring(s, "~", "~0");
-        replace_substring(s, "/", "~1");
-        return s;
+            default: // anything else (0xFF is handled inside the other types)
+            {
+                std::stringstream ss;
+                ss << std::setw(2) << std::setfill('0') << std::hex << current;
+                JSON_THROW(parse_error::create(
+                               112, chars_read, "error reading CBOR; last byte: 0x" + ss.str()));
+            }
+        }
     }
 
-    /// unescape tilde and slash
-    static void unescape(std::string& s)
+    /*!
+    @brief create a JSON value from MessagePack input
+
+    @return JSON value created from MessagePack input
+
+    @throw parse_error.110 if input ended unexpectedly
+    @throw parse_error.112 if unsupported byte was read
+    */
+    BasicJsonType parse_msgpack()
     {
-        // first transform any occurrence of the sequence '~1' to '/'
-        replace_substring(s, "~1", "/");
-        // then transform any occurrence of the sequence '~0' to '~'
-        replace_substring(s, "~0", "~");
-    }
+        switch (get())
+        {
+            // EOF
+            case std::char_traits<char>::eof():
+            {
+                JSON_THROW(
+                    parse_error::create(110, chars_read, "unexpected end of input"));
+            }
+
+            // positive fixint
+            case 0x00:
+            case 0x01:
+            case 0x02:
+            case 0x03:
+            case 0x04:
+            case 0x05:
+            case 0x06:
+            case 0x07:
+            case 0x08:
+            case 0x09:
+            case 0x0a:
+            case 0x0b:
+            case 0x0c:
+            case 0x0d:
+            case 0x0e:
+            case 0x0f:
+            case 0x10:
+            case 0x11:
+            case 0x12:
+            case 0x13:
+            case 0x14:
+            case 0x15:
+            case 0x16:
+            case 0x17:
+            case 0x18:
+            case 0x19:
+            case 0x1a:
+            case 0x1b:
+            case 0x1c:
+            case 0x1d:
+            case 0x1e:
+            case 0x1f:
+            case 0x20:
+            case 0x21:
+            case 0x22:
+            case 0x23:
+            case 0x24:
+            case 0x25:
+            case 0x26:
+            case 0x27:
+            case 0x28:
+            case 0x29:
+            case 0x2a:
+            case 0x2b:
+            case 0x2c:
+            case 0x2d:
+            case 0x2e:
+            case 0x2f:
+            case 0x30:
+            case 0x31:
+            case 0x32:
+            case 0x33:
+            case 0x34:
+            case 0x35:
+            case 0x36:
+            case 0x37:
+            case 0x38:
+            case 0x39:
+            case 0x3a:
+            case 0x3b:
+            case 0x3c:
+            case 0x3d:
+            case 0x3e:
+            case 0x3f:
+            case 0x40:
+            case 0x41:
+            case 0x42:
+            case 0x43:
+            case 0x44:
+            case 0x45:
+            case 0x46:
+            case 0x47:
+            case 0x48:
+            case 0x49:
+            case 0x4a:
+            case 0x4b:
+            case 0x4c:
+            case 0x4d:
+            case 0x4e:
+            case 0x4f:
+            case 0x50:
+            case 0x51:
+            case 0x52:
+            case 0x53:
+            case 0x54:
+            case 0x55:
+            case 0x56:
+            case 0x57:
+            case 0x58:
+            case 0x59:
+            case 0x5a:
+            case 0x5b:
+            case 0x5c:
+            case 0x5d:
+            case 0x5e:
+            case 0x5f:
+            case 0x60:
+            case 0x61:
+            case 0x62:
+            case 0x63:
+            case 0x64:
+            case 0x65:
+            case 0x66:
+            case 0x67:
+            case 0x68:
+            case 0x69:
+            case 0x6a:
+            case 0x6b:
+            case 0x6c:
+            case 0x6d:
+            case 0x6e:
+            case 0x6f:
+            case 0x70:
+            case 0x71:
+            case 0x72:
+            case 0x73:
+            case 0x74:
+            case 0x75:
+            case 0x76:
+            case 0x77:
+            case 0x78:
+            case 0x79:
+            case 0x7a:
+            case 0x7b:
+            case 0x7c:
+            case 0x7d:
+            case 0x7e:
+            case 0x7f:
+            {
+                return static_cast<number_unsigned_t>(current);
+            }
+
+            // fixmap
+            case 0x80:
+            case 0x81:
+            case 0x82:
+            case 0x83:
+            case 0x84:
+            case 0x85:
+            case 0x86:
+            case 0x87:
+            case 0x88:
+            case 0x89:
+            case 0x8a:
+            case 0x8b:
+            case 0x8c:
+            case 0x8d:
+            case 0x8e:
+            case 0x8f:
+            {
+                BasicJsonType result = value_t::object;
+                const auto len = static_cast<size_t>(current & 0x0f);
+                for (size_t i = 0; i < len; ++i)
+                {
+                    get();
+                    auto key = get_msgpack_string();
+                    result[key] = parse_msgpack();
+                }
+                return result;
+            }
 
-    /*!
-      @param[in] reference_string  the reference string to the current value
-      @param[in] value             the value to consider
-      @param[in,out] result        the result object to insert values to
+            // fixarray
+            case 0x90:
+            case 0x91:
+            case 0x92:
+            case 0x93:
+            case 0x94:
+            case 0x95:
+            case 0x96:
+            case 0x97:
+            case 0x98:
+            case 0x99:
+            case 0x9a:
+            case 0x9b:
+            case 0x9c:
+            case 0x9d:
+            case 0x9e:
+            case 0x9f:
+            {
+                BasicJsonType result = value_t::array;
+                const auto len = static_cast<size_t>(current & 0x0f);
+                for (size_t i = 0; i < len; ++i)
+                {
+                    result.push_back(parse_msgpack());
+                }
+                return result;
+            }
 
-      @note Empty objects or arrays are flattened to `null`.
-      */
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    static void flatten(const std::string& reference_string,
-                        const NLOHMANN_BASIC_JSON_TPL& value,
-                        NLOHMANN_BASIC_JSON_TPL& result);
+            // fixstr
+            case 0xa0:
+            case 0xa1:
+            case 0xa2:
+            case 0xa3:
+            case 0xa4:
+            case 0xa5:
+            case 0xa6:
+            case 0xa7:
+            case 0xa8:
+            case 0xa9:
+            case 0xaa:
+            case 0xab:
+            case 0xac:
+            case 0xad:
+            case 0xae:
+            case 0xaf:
+            case 0xb0:
+            case 0xb1:
+            case 0xb2:
+            case 0xb3:
+            case 0xb4:
+            case 0xb5:
+            case 0xb6:
+            case 0xb7:
+            case 0xb8:
+            case 0xb9:
+            case 0xba:
+            case 0xbb:
+            case 0xbc:
+            case 0xbd:
+            case 0xbe:
+            case 0xbf:
+            {
+                return get_msgpack_string();
+            }
+
+            case 0xc0: // nil
+            {
+                return value_t::null;
+            }
+
+            case 0xc2: // false
+            {
+                return false;
+            }
 
-    /*!
-      @param[in] value  flattened JSON
+            case 0xc3: // true
+            {
+                return true;
+            }
 
-      @return unflattened JSON
+            case 0xca: // float 32
+            {
+                return get_number<float>();
+            }
 
-      @throw parse_error.109 if array index is not a number
-      @throw type_error.314  if value is not an object
-      @throw type_error.315  if object values are not primitive
-      @throw type_error.313  if value cannot be unflattened
-      */
-    NLOHMANN_BASIC_JSON_TPL_DECLARATION
-    static NLOHMANN_BASIC_JSON_TPL
-    unflatten(const NLOHMANN_BASIC_JSON_TPL& value);
+            case 0xcb: // float 64
+            {
+                return get_number<double>();
+            }
 
-    friend bool operator==(json_pointer const& lhs,
-                           json_pointer const& rhs) noexcept;
+            case 0xcc: // uint 8
+            {
+                return get_number<uint8_t>();
+            }
 
-    friend bool operator!=(json_pointer const& lhs,
-                           json_pointer const& rhs) noexcept;
+            case 0xcd: // uint 16
+            {
+                return get_number<uint16_t>();
+            }
 
-    /// the reference tokens
-    std::vector<std::string> reference_tokens;
-};
+            case 0xce: // uint 32
+            {
+                return get_number<uint32_t>();
+            }
 
-/*!
-@brief a class to store JSON values
+            case 0xcf: // uint 64
+            {
+                return get_number<uint64_t>();
+            }
 
-@tparam ObjectType type for JSON objects (`std::map` by default; will be used
-in @ref object_t)
-@tparam ArrayType type for JSON arrays (`std::vector` by default; will be used
-in @ref array_t)
-@tparam StringType type for JSON strings and object keys (`std::string` by
-default; will be used in @ref string_t)
-@tparam BooleanType type for JSON booleans (`bool` by default; will be used
-in @ref boolean_t)
-@tparam NumberIntegerType type for JSON integer numbers (`int64_t` by
-default; will be used in @ref number_integer_t)
-@tparam NumberUnsignedType type for JSON unsigned integer numbers (@c
-`uint64_t` by default; will be used in @ref number_unsigned_t)
-@tparam NumberFloatType type for JSON floating-point numbers (`double` by
-default; will be used in @ref number_float_t)
-@tparam AllocatorType type of the allocator to use (`std::allocator` by
-default)
-@tparam JSONSerializer the serializer to resolve internal calls to `to_json()`
-and `from_json()` (@ref adl_serializer by default)
+            case 0xd0: // int 8
+            {
+                return get_number<int8_t>();
+            }
 
-@requirement The class satisfies the following concept requirements:
-- Basic
- - [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible):
-   JSON values can be default constructed. The result will be a JSON null
-   value.
- - [MoveConstructible](http://en.cppreference.com/w/cpp/concept/MoveConstructible):
-   A JSON value can be constructed from an rvalue argument.
- - [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible):
-   A JSON value can be copy-constructed from an lvalue expression.
- - [MoveAssignable](http://en.cppreference.com/w/cpp/concept/MoveAssignable):
-   A JSON value van be assigned from an rvalue argument.
- - [CopyAssignable](http://en.cppreference.com/w/cpp/concept/CopyAssignable):
-   A JSON value can be copy-assigned from an lvalue expression.
- - [Destructible](http://en.cppreference.com/w/cpp/concept/Destructible):
-   JSON values can be destructed.
-- Layout
- - [StandardLayoutType](http://en.cppreference.com/w/cpp/concept/StandardLayoutType):
-   JSON values have
-   [standard layout](http://en.cppreference.com/w/cpp/language/data_members#Standard_layout):
-   All non-static data members are private and standard layout types, the
-   class has no virtual functions or (virtual) base classes.
-- Library-wide
- - [EqualityComparable](http://en.cppreference.com/w/cpp/concept/EqualityComparable):
-   JSON values can be compared with `==`, see @ref
-   operator==(const_reference,const_reference).
- - [LessThanComparable](http://en.cppreference.com/w/cpp/concept/LessThanComparable):
-   JSON values can be compared with `<`, see @ref
-   operator<(const_reference,const_reference).
- - [Swappable](http://en.cppreference.com/w/cpp/concept/Swappable):
-   Any JSON lvalue or rvalue of can be swapped with any lvalue or rvalue of
-   other compatible types, using unqualified function call @ref swap().
- - [NullablePointer](http://en.cppreference.com/w/cpp/concept/NullablePointer):
-   JSON values can be compared against `std::nullptr_t` objects which are used
-   to model the `null` value.
-- Container
- - [Container](http://en.cppreference.com/w/cpp/concept/Container):
-   JSON values can be used like STL containers and provide iterator access.
- - [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer);
-   JSON values can be used like STL containers and provide reverse iterator
-   access.
+            case 0xd1: // int 16
+            {
+                return get_number<int16_t>();
+            }
 
-@invariant The member variables @a m_value and @a m_type have the following
-relationship:
-- If `m_type == value_t::object`, then `m_value.object != nullptr`.
-- If `m_type == value_t::array`, then `m_value.array != nullptr`.
-- If `m_type == value_t::string`, then `m_value.string != nullptr`.
-The invariants are checked by member function assert_invariant().
+            case 0xd2: // int 32
+            {
+                return get_number<int32_t>();
+            }
 
-@internal
-@note ObjectType trick from http://stackoverflow.com/a/9860911
-@endinternal
+            case 0xd3: // int 64
+            {
+                return get_number<int64_t>();
+            }
 
-@see [RFC 7159: The JavaScript Object Notation (JSON) Data Interchange
-Format](http://rfc7159.net/rfc7159)
+            case 0xd9: // str 8
+            case 0xda: // str 16
+            case 0xdb: // str 32
+            {
+                return get_msgpack_string();
+            }
 
-@since version 1.0.0
+            case 0xdc: // array 16
+            {
+                BasicJsonType result = value_t::array;
+                const auto len = static_cast<size_t>(get_number<uint16_t>());
+                for (size_t i = 0; i < len; ++i)
+                {
+                    result.push_back(parse_msgpack());
+                }
+                return result;
+            }
 
-@nosubgrouping
-*/
-NLOHMANN_BASIC_JSON_TPL_DECLARATION
-class basic_json
-{
-  private:
-    template<detail::value_t> friend struct detail::external_constructor;
-    friend ::nlohmann::json_pointer;
-    friend ::nlohmann::detail::parser<basic_json>;
-    template <typename BasicJsonType>
-    friend class ::nlohmann::detail::iter_impl;
-    /// workaround type for MSVC
-    using basic_json_t = NLOHMANN_BASIC_JSON_TPL;
+            case 0xdd: // array 32
+            {
+                BasicJsonType result = value_t::array;
+                const auto len = static_cast<size_t>(get_number<uint32_t>());
+                for (size_t i = 0; i < len; ++i)
+                {
+                    result.push_back(parse_msgpack());
+                }
+                return result;
+            }
 
-    // convenience aliases for types residing in namespace detail;
-    using lexer = ::nlohmann::detail::lexer<basic_json>;
-    using parser = ::nlohmann::detail::parser<basic_json>;
+            case 0xde: // map 16
+            {
+                BasicJsonType result = value_t::object;
+                const auto len = static_cast<size_t>(get_number<uint16_t>());
+                for (size_t i = 0; i < len; ++i)
+                {
+                    get();
+                    auto key = get_msgpack_string();
+                    result[key] = parse_msgpack();
+                }
+                return result;
+            }
 
-    using primitive_iterator_t = ::nlohmann::detail::primitive_iterator_t;
-    template <typename BasicJsonType>
-    using internal_iterator = ::nlohmann::detail::internal_iterator<BasicJsonType>;
-    template <typename BasicJsonType>
-    using iter_impl = ::nlohmann::detail::iter_impl<BasicJsonType>;
-    template <typename Iterator>
-    using iteration_proxy = ::nlohmann::detail::iteration_proxy<Iterator>;
-    template<typename Base> using json_reverse_iterator = ::nlohmann::detail::json_reverse_iterator<Base>;
+            case 0xdf: // map 32
+            {
+                BasicJsonType result = value_t::object;
+                const auto len = static_cast<size_t>(get_number<uint32_t>());
+                for (size_t i = 0; i < len; ++i)
+                {
+                    get();
+                    auto key = get_msgpack_string();
+                    result[key] = parse_msgpack();
+                }
+                return result;
+            }
 
-  public:
-    using value_t = detail::value_t;
-    // forward declarations
-    using json_pointer = ::nlohmann::json_pointer;
-    template<typename T, typename SFINAE>
-    using json_serializer = JSONSerializer<T, SFINAE>;
+            // positive fixint
+            case 0xe0:
+            case 0xe1:
+            case 0xe2:
+            case 0xe3:
+            case 0xe4:
+            case 0xe5:
+            case 0xe6:
+            case 0xe7:
+            case 0xe8:
+            case 0xe9:
+            case 0xea:
+            case 0xeb:
+            case 0xec:
+            case 0xed:
+            case 0xee:
+            case 0xef:
+            case 0xf0:
+            case 0xf1:
+            case 0xf2:
+            case 0xf3:
+            case 0xf4:
+            case 0xf5:
+            case 0xf6:
+            case 0xf7:
+            case 0xf8:
+            case 0xf9:
+            case 0xfa:
+            case 0xfb:
+            case 0xfc:
+            case 0xfd:
+            case 0xfe:
+            case 0xff:
+            {
+                return static_cast<int8_t>(current);
+            }
+
+            default: // anything else
+            {
+                std::stringstream ss;
+                ss << std::setw(2) << std::setfill('0') << std::hex << current;
+                JSON_THROW(parse_error::create(
+                               112, chars_read,
+                               "error reading MessagePack; last byte: 0x" + ss.str()));
+            }
+        }
+    }
 
+    /*!
+    @brief determine system byte order
 
-    ////////////////
-    // exceptions //
-    ////////////////
+    @return true iff system's byte order is little endian
 
-    /// @name exceptions
-    /// Classes to implement user-defined exceptions.
-    /// @{
+    @note from http://stackoverflow.com/a/1001328/266378
+    */
+    static bool little_endianess() noexcept
+    {
+        int num = 1;
+        return (*reinterpret_cast<char*>(&num) == 1);
+    }
 
-    /// @copydoc detail::exception
-    using exception = detail::exception;
-    /// @copydoc detail::parse_error
-    using parse_error = detail::parse_error;
-    /// @copydoc detail::invalid_iterator
-    using invalid_iterator = detail::invalid_iterator;
-    /// @copydoc detail::type_error
-    using type_error = detail::type_error;
-    /// @copydoc detail::out_of_range
-    using out_of_range = detail::out_of_range;
-    /// @copydoc detail::other_error
-    using other_error = detail::other_error;
+  private:
+    /*!
+    @brief get next character from the input
 
-    /// @}
+    This function provides the interface to the used input adapter. It does
+    not throw in case the input reached EOF, but returns
+    `std::char_traits<char>::eof()` in that case.
 
+    @return character read from the input
+    */
+    int get()
+    {
+        ++chars_read;
+        return (current = ia->get_character());
+    }
 
-    /////////////////////
-    // container types //
-    /////////////////////
+    /*
+    @brief read a number from the input
 
-    /// @name container types
-    /// The canonic container types to use @ref basic_json like any other STL
-    /// container.
-    /// @{
+    @tparam NumberType the type of the number
 
-    /// the type of elements in a basic_json container
-    using value_type = basic_json;
+    @return number of type @a NumberType
 
-    /// the type of an element reference
-    using reference = value_type&;
-    /// the type of an element const reference
-    using const_reference = const value_type&;
+    @note This function needs to respect the system's endianess, because
+          bytes in CBOR and MessagePack are stored in network order (big
+          endian) and therefore need reordering on little endian systems.
 
-    /// a type to represent differences between iterators
-    using difference_type = std::ptrdiff_t;
-    /// a type to represent container sizes
-    using size_type = std::size_t;
+    @throw parse_error.110 if input has less than `sizeof(NumberType)`
+                           bytes
+    */
+    template <typename NumberType> NumberType get_number()
+    {
+        // step 1: read input into array with system's byte order
+        std::array<uint8_t, sizeof(NumberType)> vec;
+        for (size_t i = 0; i < sizeof(NumberType); ++i)
+        {
+            get();
+            check_eof();
 
-    /// the allocator type
-    using allocator_type = AllocatorType<basic_json>;
+            // reverse byte order prior to conversion if necessary
+            if (is_little_endian)
+            {
+                vec[sizeof(NumberType) - i - 1] = static_cast<uint8_t>(current);
+            }
+            else
+            {
+                vec[i] = static_cast<uint8_t>(current); // LCOV_EXCL_LINE
+            }
+        }
 
-    /// the type of an element pointer
-    using pointer = typename std::allocator_traits<allocator_type>::pointer;
-    /// the type of an element const pointer
-    using const_pointer = typename std::allocator_traits<allocator_type>::const_pointer;
+        // step 2: convert array into number of type T and return
+        NumberType result;
+        std::memcpy(&result, vec.data(), sizeof(NumberType));
+        return result;
+    }
 
-    /// an iterator for a basic_json container
-    using iterator = iter_impl<basic_json>;
-    /// a const iterator for a basic_json container
-    using const_iterator = iter_impl<const basic_json>;
-    /// a reverse iterator for a basic_json container
-    using reverse_iterator = json_reverse_iterator<typename basic_json::iterator>;
-    /// a const reverse iterator for a basic_json container
-    using const_reverse_iterator = json_reverse_iterator<typename basic_json::const_iterator>;
+    /*!
+    @brief create a string by reading characters from the input
 
-    /// @}
+    @param[in] len number of bytes to read
 
+    @note We can not reserve @a len bytes for the result, because @a len
+          may be too large. Usually, @ref check_eof() detects the end of
+          the input before we run out of string memory.
 
-    /*!
-    @brief returns the allocator associated with the container
+    @return string created by reading @a len bytes
+
+    @throw parse_error.110 if input has less than @a len bytes
     */
-    static allocator_type get_allocator()
+    std::string get_string(const size_t len)
     {
-        return allocator_type();
+        std::string result;
+        for (size_t i = 0; i < len; ++i)
+        {
+            get();
+            check_eof();
+            result.append(1, static_cast<char>(current));
+        }
+        return result;
     }
 
     /*!
-    @brief returns version information on the library
-
-    This function returns a JSON object with information about the library,
-    including the version number and information on the platform and compiler.
-
-    @return JSON object holding version information
-    key         | description
-    ----------- | ---------------
-    `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).
-    `copyright` | The copyright line for the library as string.
-    `name`      | The name of the library as string.
-    `platform`  | The used platform as string. Possible values are `win32`, `linux`, `apple`, `unix`, and `unknown`.
-    `url`       | The URL of the project as string.
-    `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).
+    @brief reads a CBOR string
 
-    @liveexample{The following code shows an example output of the `meta()`
-    function.,meta}
+    This function first reads starting bytes to determine the expected
+    string length and then copies this number of bytes into a string.
+    Additionally, CBOR's strings with indefinite lengths are supported.
 
-    @complexity Constant.
+    @return string
 
-    @since 2.1.0
+    @throw parse_error.110 if input ended
+    @throw parse_error.113 if an unexpected byte is read
     */
-    static basic_json meta()
+    std::string get_cbor_string()
     {
-        basic_json result;
+        check_eof();
 
-        result["copyright"] = "(C) 2013-2017 Niels Lohmann";
-        result["name"] = "JSON for Modern C++";
-        result["url"] = "https://github.com/nlohmann/json";
-        result["version"] =
+        switch (current)
         {
-            {"string", "2.1.1"}, {"major", 2}, {"minor", 1}, {"patch", 1}
-        };
-
-#ifdef _WIN32
-        result["platform"] = "win32";
-#elif defined __linux__
-        result["platform"] = "linux";
-#elif defined __APPLE__
-        result["platform"] = "apple";
-#elif defined __unix__
-        result["platform"] = "unix";
-#else
-        result["platform"] = "unknown";
-#endif
+            // UTF-8 string (0x00..0x17 bytes follow)
+            case 0x60:
+            case 0x61:
+            case 0x62:
+            case 0x63:
+            case 0x64:
+            case 0x65:
+            case 0x66:
+            case 0x67:
+            case 0x68:
+            case 0x69:
+            case 0x6a:
+            case 0x6b:
+            case 0x6c:
+            case 0x6d:
+            case 0x6e:
+            case 0x6f:
+            case 0x70:
+            case 0x71:
+            case 0x72:
+            case 0x73:
+            case 0x74:
+            case 0x75:
+            case 0x76:
+            case 0x77:
+            {
+                const auto len = static_cast<size_t>(current & 0x1f);
+                return get_string(len);
+            }
 
-#if defined(__clang__)
-        result["compiler"] = {{"family", "clang"}, {"version", __clang_version__}};
-#elif defined(__ICC) || defined(__INTEL_COMPILER)
-        result["compiler"] = {{"family", "icc"}, {"version", __INTEL_COMPILER}};
-#elif defined(__GNUC__) || defined(__GNUG__)
-        result["compiler"] = {{"family", "gcc"}, {"version", std::to_string(__GNUC__) + "." + std::to_string(__GNUC_MINOR__) + "." + std::to_string(__GNUC_PATCHLEVEL__)}};
-#elif defined(__HP_cc) || defined(__HP_aCC)
-        result["compiler"] = "hp"
-#elif defined(__IBMCPP__)
-        result["compiler"] = {{"family", "ilecpp"}, {"version", __IBMCPP__}};
-#elif defined(_MSC_VER)
-        result["compiler"] = {{"family", "msvc"}, {"version", _MSC_VER}};
-#elif defined(__PGI)
-        result["compiler"] = {{"family", "pgcpp"}, {"version", __PGI}};
-#elif defined(__SUNPRO_CC)
-        result["compiler"] = {{"family", "sunpro"}, {"version", __SUNPRO_CC}};
-#else
-        result["compiler"] = {{"family", "unknown"}, {"version", "unknown"}};
-#endif
+            case 0x78: // UTF-8 string (one-byte uint8_t for n follows)
+            {
+                const auto len = static_cast<size_t>(get_number<uint8_t>());
+                return get_string(len);
+            }
 
-#ifdef __cplusplus
-        result["compiler"]["c++"] = std::to_string(__cplusplus);
-#else
-        result["compiler"]["c++"] = "unknown";
-#endif
-        return result;
-    }
+            case 0x79: // UTF-8 string (two-byte uint16_t for n follow)
+            {
+                const auto len = static_cast<size_t>(get_number<uint16_t>());
+                return get_string(len);
+            }
 
+            case 0x7a: // UTF-8 string (four-byte uint32_t for n follow)
+            {
+                const auto len = static_cast<size_t>(get_number<uint32_t>());
+                return get_string(len);
+            }
 
-    ///////////////////////////
-    // JSON value data types //
-    ///////////////////////////
+            case 0x7b: // UTF-8 string (eight-byte uint64_t for n follow)
+            {
+                const auto len = static_cast<size_t>(get_number<uint64_t>());
+                return get_string(len);
+            }
 
-    /// @name JSON value data types
-    /// The data types to store a JSON value. These types are derived from
-    /// the template arguments passed to class @ref basic_json.
-    /// @{
-
-    /*!
-    @brief a type for an object
-
-    [RFC 7159](http://rfc7159.net/rfc7159) describes JSON objects as follows:
-    > An object is an unordered collection of zero or more name/value pairs,
-    > where a name is a string and a value is a string, number, boolean, null,
-    > object, or array.
-
-    To store objects in C++, a type is defined by the template parameters
-    described below.
-
-    @tparam ObjectType  the container to store objects (e.g., `std::map` or
-    `std::unordered_map`)
-    @tparam StringType the type of the keys or names (e.g., `std::string`).
-    The comparison function `std::less<StringType>` is used to order elements
-    inside the container.
-    @tparam AllocatorType the allocator to use for objects (e.g.,
-    `std::allocator`)
+            case 0x7f: // UTF-8 string (indefinite length)
+            {
+                std::string result;
+                while (get() != 0xff)
+                {
+                    check_eof();
+                    result.append(1, static_cast<char>(current));
+                }
+                return result;
+            }
 
-    #### Default type
+            default:
+            {
+                std::stringstream ss;
+                ss << std::setw(2) << std::setfill('0') << std::hex << current;
+                JSON_THROW(parse_error::create(
+                               113, chars_read, "expected a CBOR string; last byte: 0x" + ss.str()));
+            }
+        }
+    }
 
-    With the default values for @a ObjectType (`std::map`), @a StringType
-    (`std::string`), and @a AllocatorType (`std::allocator`), the default
-    value for @a object_t is:
+    /*!
+    @brief reads a MessagePack string
 
-    @code {.cpp}
-    std::map<
-      std::string, // key_type
-      basic_json, // value_type
-      std::less<std::string>, // key_compare
-      std::allocator<std::pair<const std::string, basic_json>> // allocator_type
-    >
-    @endcode
+    This function first reads starting bytes to determine the expected
+    string length and then copies this number of bytes into a string.
 
-    #### Behavior
+    @return string
 
-    The choice of @a object_t influences the behavior of the JSON class. With
-    the default type, objects have the following behavior:
+    @throw parse_error.110 if input ended
+    @throw parse_error.113 if an unexpected byte is read
+    */
+    std::string get_msgpack_string()
+    {
+        check_eof();
 
-    - When all names are unique, objects will be interoperable in the sense
-      that all software implementations receiving that object will agree on
-      the name-value mappings.
-    - When the names within an object are not unique, later stored name/value
-      pairs overwrite previously stored name/value pairs, leaving the used
-      names unique. For instance, `{"key": 1}` and `{"key": 2, "key": 1}` will
-      be treated as equal and both stored as `{"key": 1}`.
-    - Internally, name/value pairs are stored in lexicographical order of the
-      names. Objects will also be serialized (see @ref dump) in this order.
-      For instance, `{"b": 1, "a": 2}` and `{"a": 2, "b": 1}` will be stored
-      and serialized as `{"a": 2, "b": 1}`.
-    - When comparing objects, the order of the name/value pairs is irrelevant.
-      This makes objects interoperable in the sense that they will not be
-      affected by these differences. For instance, `{"b": 1, "a": 2}` and
-      `{"a": 2, "b": 1}` will be treated as equal.
+        switch (current)
+        {
+            // fixstr
+            case 0xa0:
+            case 0xa1:
+            case 0xa2:
+            case 0xa3:
+            case 0xa4:
+            case 0xa5:
+            case 0xa6:
+            case 0xa7:
+            case 0xa8:
+            case 0xa9:
+            case 0xaa:
+            case 0xab:
+            case 0xac:
+            case 0xad:
+            case 0xae:
+            case 0xaf:
+            case 0xb0:
+            case 0xb1:
+            case 0xb2:
+            case 0xb3:
+            case 0xb4:
+            case 0xb5:
+            case 0xb6:
+            case 0xb7:
+            case 0xb8:
+            case 0xb9:
+            case 0xba:
+            case 0xbb:
+            case 0xbc:
+            case 0xbd:
+            case 0xbe:
+            case 0xbf:
+            {
+                const auto len = static_cast<size_t>(current & 0x1f);
+                return get_string(len);
+            }
+
+            case 0xd9: // str 8
+            {
+                const auto len = static_cast<size_t>(get_number<uint8_t>());
+                return get_string(len);
+            }
+
+            case 0xda: // str 16
+            {
+                const auto len = static_cast<size_t>(get_number<uint16_t>());
+                return get_string(len);
+            }
+
+            case 0xdb: // str 32
+            {
+                const auto len = static_cast<size_t>(get_number<uint32_t>());
+                return get_string(len);
+            }
 
-    #### Limits
+            default:
+            {
+                std::stringstream ss;
+                ss << std::setw(2) << std::setfill('0') << std::hex << current;
+                JSON_THROW(parse_error::create(
+                               113, chars_read,
+                               "expected a MessagePack string; last byte: 0x" + ss.str()));
+            }
+        }
+    }
 
-    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
-    > An implementation may set limits on the maximum depth of nesting.
+    /*!
+    @brief check if input ended
+    @throw parse_error.110 if input ended
+    */
+    void check_eof() const
+    {
+        if (JSON_UNLIKELY(current == std::char_traits<char>::eof()))
+        {
+            JSON_THROW(
+                parse_error::create(110, chars_read, "unexpected end of input"));
+        }
+    }
 
-    In this class, the object's limit of nesting is not constraint explicitly.
-    However, a maximum depth of nesting may be introduced by the compiler or
-    runtime environment. A theoretical limit can be queried by calling the
-    @ref max_size function of a JSON object.
+  private:
+    /// input adapter
+    input_adapter_t ia = nullptr;
 
-    #### Storage
+    /// the current character
+    int current = std::char_traits<char>::eof();
 
-    Objects are stored as pointers in a @ref basic_json type. That is, for any
-    access to object values, a pointer of type `object_t*` must be
-    dereferenced.
+    /// the number of characters read
+    size_t chars_read = 0;
 
-    @sa @ref array_t -- type for an array value
+    /// whether we can assume little endianess
+    const bool is_little_endian = true;
+};
 
-    @since version 1.0.0
+/*!
+@brief serialization to CBOR and MessagePack values
+*/
+template <typename BasicJsonType>
+class binary_writer
+{
+  public:
+    /*!
+    @brief create a binary writer
 
-    @note The order name/value pairs are added to the object is *not*
-    preserved by the library. Therefore, iterating an object may return
-    name/value pairs in a different order than they were originally stored. In
-    fact, keys will be traversed in alphabetical order as `std::map` with
-    `std::less` is used by default. Please note this behavior conforms to [RFC
-    7159](http://rfc7159.net/rfc7159), because any order implements the
-    specified "unordered" nature of JSON objects.
+    @param[in] adapter  output adapter to write to
     */
-    using object_t = ObjectType<StringType,
-          basic_json,
-          std::less<StringType>,
-          AllocatorType<std::pair<const StringType,
-          basic_json>>>;
+    explicit binary_writer(output_adapter_t<uint8_t> adapter)
+        : is_little_endian(binary_reader<BasicJsonType>::little_endianess()), oa(adapter)
+    {
+        assert(oa);
+    }
 
     /*!
-    @brief a type for an array
-
-    [RFC 7159](http://rfc7159.net/rfc7159) describes JSON arrays as follows:
-    > An array is an ordered sequence of zero or more values.
-
-    To store objects in C++, a type is defined by the template parameters
-    explained below.
-
-    @tparam ArrayType  container type to store arrays (e.g., `std::vector` or
-    `std::list`)
-    @tparam AllocatorType allocator to use for arrays (e.g., `std::allocator`)
-
-    #### Default type
+    @brief[in] j  JSON value to serialize
+    */
+    void write_cbor(const BasicJsonType& j)
+    {
+        switch (j.type())
+        {
+            case value_t::null:
+            {
+                oa->write_character(0xf6);
+                break;
+            }
 
-    With the default values for @a ArrayType (`std::vector`) and @a
-    AllocatorType (`std::allocator`), the default value for @a array_t is:
+            case value_t::boolean:
+            {
+                oa->write_character(j.m_value.boolean ? 0xf5 : 0xf4);
+                break;
+            }
 
-    @code {.cpp}
-    std::vector<
-      basic_json, // value_type
-      std::allocator<basic_json> // allocator_type
-    >
-    @endcode
+            case value_t::number_integer:
+            {
+                if (j.m_value.number_integer >= 0)
+                {
+                    // CBOR does not differentiate between positive signed
+                    // integers and unsigned integers. Therefore, we used the
+                    // code from the value_t::number_unsigned case here.
+                    if (j.m_value.number_integer <= 0x17)
+                    {
+                        write_number(static_cast<uint8_t>(j.m_value.number_integer));
+                    }
+                    else if (j.m_value.number_integer <=
+                             (std::numeric_limits<uint8_t>::max)())
+                    {
+                        oa->write_character(0x18);
+                        write_number(static_cast<uint8_t>(j.m_value.number_integer));
+                    }
+                    else if (j.m_value.number_integer <=
+                             (std::numeric_limits<uint16_t>::max)())
+                    {
+                        oa->write_character(0x19);
+                        write_number(static_cast<uint16_t>(j.m_value.number_integer));
+                    }
+                    else if (j.m_value.number_integer <=
+                             (std::numeric_limits<uint32_t>::max)())
+                    {
+                        oa->write_character(0x1a);
+                        write_number(static_cast<uint32_t>(j.m_value.number_integer));
+                    }
+                    else
+                    {
+                        oa->write_character(0x1b);
+                        write_number(static_cast<uint64_t>(j.m_value.number_integer));
+                    }
+                }
+                else
+                {
+                    // The conversions below encode the sign in the first
+                    // byte, and the value is converted to a positive number.
+                    const auto positive_number = -1 - j.m_value.number_integer;
+                    if (j.m_value.number_integer >= -24)
+                    {
+                        write_number(static_cast<uint8_t>(0x20 + positive_number));
+                    }
+                    else if (positive_number <= (std::numeric_limits<uint8_t>::max)())
+                    {
+                        oa->write_character(0x38);
+                        write_number(static_cast<uint8_t>(positive_number));
+                    }
+                    else if (positive_number <= (std::numeric_limits<uint16_t>::max)())
+                    {
+                        oa->write_character(0x39);
+                        write_number(static_cast<uint16_t>(positive_number));
+                    }
+                    else if (positive_number <= (std::numeric_limits<uint32_t>::max)())
+                    {
+                        oa->write_character(0x3a);
+                        write_number(static_cast<uint32_t>(positive_number));
+                    }
+                    else
+                    {
+                        oa->write_character(0x3b);
+                        write_number(static_cast<uint64_t>(positive_number));
+                    }
+                }
+                break;
+            }
 
-    #### Limits
+            case value_t::number_unsigned:
+            {
+                if (j.m_value.number_unsigned <= 0x17)
+                {
+                    write_number(static_cast<uint8_t>(j.m_value.number_unsigned));
+                }
+                else if (j.m_value.number_unsigned <=
+                         (std::numeric_limits<uint8_t>::max)())
+                {
+                    oa->write_character(0x18);
+                    write_number(static_cast<uint8_t>(j.m_value.number_unsigned));
+                }
+                else if (j.m_value.number_unsigned <=
+                         (std::numeric_limits<uint16_t>::max)())
+                {
+                    oa->write_character(0x19);
+                    write_number(static_cast<uint16_t>(j.m_value.number_unsigned));
+                }
+                else if (j.m_value.number_unsigned <=
+                         (std::numeric_limits<uint32_t>::max)())
+                {
+                    oa->write_character(0x1a);
+                    write_number(static_cast<uint32_t>(j.m_value.number_unsigned));
+                }
+                else
+                {
+                    oa->write_character(0x1b);
+                    write_number(static_cast<uint64_t>(j.m_value.number_unsigned));
+                }
+                break;
+            }
 
-    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
-    > An implementation may set limits on the maximum depth of nesting.
+            case value_t::number_float:
+            {
+                // Double-Precision Float
+                oa->write_character(0xfb);
+                write_number(j.m_value.number_float);
+                break;
+            }
 
-    In this class, the array's limit of nesting is not constraint explicitly.
-    However, a maximum depth of nesting may be introduced by the compiler or
-    runtime environment. A theoretical limit can be queried by calling the
-    @ref max_size function of a JSON array.
+            case value_t::string:
+            {
+                // step 1: write control byte and the string length
+                const auto N = j.m_value.string->size();
+                if (N <= 0x17)
+                {
+                    write_number(static_cast<uint8_t>(0x60 + N));
+                }
+                else if (N <= 0xff)
+                {
+                    oa->write_character(0x78);
+                    write_number(static_cast<uint8_t>(N));
+                }
+                else if (N <= 0xffff)
+                {
+                    oa->write_character(0x79);
+                    write_number(static_cast<uint16_t>(N));
+                }
+                else if (N <= 0xffffffff)
+                {
+                    oa->write_character(0x7a);
+                    write_number(static_cast<uint32_t>(N));
+                }
+                // LCOV_EXCL_START
+                else if (N <= 0xffffffffffffffff)
+                {
+                    oa->write_character(0x7b);
+                    write_number(static_cast<uint64_t>(N));
+                }
+                // LCOV_EXCL_STOP
 
-    #### Storage
+                // step 2: write the string
+                oa->write_characters(
+                    reinterpret_cast<const uint8_t*>(j.m_value.string->c_str()),
+                    j.m_value.string->size());
+                break;
+            }
 
-    Arrays are stored as pointers in a @ref basic_json type. That is, for any
-    access to array values, a pointer of type `array_t*` must be dereferenced.
+            case value_t::array:
+            {
+                // step 1: write control byte and the array size
+                const auto N = j.m_value.array->size();
+                if (N <= 0x17)
+                {
+                    write_number(static_cast<uint8_t>(0x80 + N));
+                }
+                else if (N <= 0xff)
+                {
+                    oa->write_character(0x98);
+                    write_number(static_cast<uint8_t>(N));
+                }
+                else if (N <= 0xffff)
+                {
+                    oa->write_character(0x99);
+                    write_number(static_cast<uint16_t>(N));
+                }
+                else if (N <= 0xffffffff)
+                {
+                    oa->write_character(0x9a);
+                    write_number(static_cast<uint32_t>(N));
+                }
+                // LCOV_EXCL_START
+                else if (N <= 0xffffffffffffffff)
+                {
+                    oa->write_character(0x9b);
+                    write_number(static_cast<uint64_t>(N));
+                }
+                // LCOV_EXCL_STOP
 
-    @sa @ref object_t -- type for an object value
+                // step 2: write each element
+                for (const auto& el : *j.m_value.array)
+                {
+                    write_cbor(el);
+                }
+                break;
+            }
 
-    @since version 1.0.0
-    */
-    using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;
+            case value_t::object:
+            {
+                // step 1: write control byte and the object size
+                const auto N = j.m_value.object->size();
+                if (N <= 0x17)
+                {
+                    write_number(static_cast<uint8_t>(0xa0 + N));
+                }
+                else if (N <= 0xff)
+                {
+                    oa->write_character(0xb8);
+                    write_number(static_cast<uint8_t>(N));
+                }
+                else if (N <= 0xffff)
+                {
+                    oa->write_character(0xb9);
+                    write_number(static_cast<uint16_t>(N));
+                }
+                else if (N <= 0xffffffff)
+                {
+                    oa->write_character(0xba);
+                    write_number(static_cast<uint32_t>(N));
+                }
+                // LCOV_EXCL_START
+                else if (N <= 0xffffffffffffffff)
+                {
+                    oa->write_character(0xbb);
+                    write_number(static_cast<uint64_t>(N));
+                }
+                // LCOV_EXCL_STOP
+
+                // step 2: write each element
+                for (const auto& el : *j.m_value.object)
+                {
+                    write_cbor(el.first);
+                    write_cbor(el.second);
+                }
+                break;
+            }
+
+            default:
+            {
+                break;
+            }
+        }
+    }
 
     /*!
-    @brief a type for a string
+    @brief[in] j  JSON value to serialize
+    */
+    void write_msgpack(const BasicJsonType& j)
+    {
+        switch (j.type())
+        {
+            case value_t::null:
+            {
+                // nil
+                oa->write_character(0xc0);
+                break;
+            }
 
-    [RFC 7159](http://rfc7159.net/rfc7159) describes JSON strings as follows:
-    > A string is a sequence of zero or more Unicode characters.
+            case value_t::boolean:
+            {
+                // true and false
+                oa->write_character(j.m_value.boolean ? 0xc3 : 0xc2);
+                break;
+            }
 
-    To store objects in C++, a type is defined by the template parameter
-    described below. Unicode values are split by the JSON class into
-    byte-sized characters during deserialization.
+            case value_t::number_integer:
+            {
+                if (j.m_value.number_integer >= 0)
+                {
+                    // MessagePack does not differentiate between positive
+                    // signed integers and unsigned integers. Therefore, we
+                    // used the code from the value_t::number_unsigned case
+                    // here.
+                    if (j.m_value.number_unsigned < 128)
+                    {
+                        // positive fixnum
+                        write_number(static_cast<uint8_t>(j.m_value.number_integer));
+                    }
+                    else if (j.m_value.number_unsigned <=
+                             (std::numeric_limits<uint8_t>::max)())
+                    {
+                        // uint 8
+                        oa->write_character(0xcc);
+                        write_number(static_cast<uint8_t>(j.m_value.number_integer));
+                    }
+                    else if (j.m_value.number_unsigned <=
+                             (std::numeric_limits<uint16_t>::max)())
+                    {
+                        // uint 16
+                        oa->write_character(0xcd);
+                        write_number(static_cast<uint16_t>(j.m_value.number_integer));
+                    }
+                    else if (j.m_value.number_unsigned <=
+                             (std::numeric_limits<uint32_t>::max)())
+                    {
+                        // uint 32
+                        oa->write_character(0xce);
+                        write_number(static_cast<uint32_t>(j.m_value.number_integer));
+                    }
+                    else if (j.m_value.number_unsigned <=
+                             (std::numeric_limits<uint64_t>::max)())
+                    {
+                        // uint 64
+                        oa->write_character(0xcf);
+                        write_number(static_cast<uint64_t>(j.m_value.number_integer));
+                    }
+                }
+                else
+                {
+                    if (j.m_value.number_integer >= -32)
+                    {
+                        // negative fixnum
+                        write_number(static_cast<int8_t>(j.m_value.number_integer));
+                    }
+                    else if (j.m_value.number_integer >=
+                             (std::numeric_limits<int8_t>::min)() and
+                             j.m_value.number_integer <=
+                             (std::numeric_limits<int8_t>::max)())
+                    {
+                        // int 8
+                        oa->write_character(0xd0);
+                        write_number(static_cast<int8_t>(j.m_value.number_integer));
+                    }
+                    else if (j.m_value.number_integer >=
+                             (std::numeric_limits<int16_t>::min)() and
+                             j.m_value.number_integer <=
+                             (std::numeric_limits<int16_t>::max)())
+                    {
+                        // int 16
+                        oa->write_character(0xd1);
+                        write_number(static_cast<int16_t>(j.m_value.number_integer));
+                    }
+                    else if (j.m_value.number_integer >=
+                             (std::numeric_limits<int32_t>::min)() and
+                             j.m_value.number_integer <=
+                             (std::numeric_limits<int32_t>::max)())
+                    {
+                        // int 32
+                        oa->write_character(0xd2);
+                        write_number(static_cast<int32_t>(j.m_value.number_integer));
+                    }
+                    else if (j.m_value.number_integer >=
+                             (std::numeric_limits<int64_t>::min)() and
+                             j.m_value.number_integer <=
+                             (std::numeric_limits<int64_t>::max)())
+                    {
+                        // int 64
+                        oa->write_character(0xd3);
+                        write_number(static_cast<int64_t>(j.m_value.number_integer));
+                    }
+                }
+                break;
+            }
 
-    @tparam StringType  the container to store strings (e.g., `std::string`).
-    Note this container is used for keys/names in objects, see @ref object_t.
+            case value_t::number_unsigned:
+            {
+                if (j.m_value.number_unsigned < 128)
+                {
+                    // positive fixnum
+                    write_number(static_cast<uint8_t>(j.m_value.number_integer));
+                }
+                else if (j.m_value.number_unsigned <=
+                         (std::numeric_limits<uint8_t>::max)())
+                {
+                    // uint 8
+                    oa->write_character(0xcc);
+                    write_number(static_cast<uint8_t>(j.m_value.number_integer));
+                }
+                else if (j.m_value.number_unsigned <=
+                         (std::numeric_limits<uint16_t>::max)())
+                {
+                    // uint 16
+                    oa->write_character(0xcd);
+                    write_number(static_cast<uint16_t>(j.m_value.number_integer));
+                }
+                else if (j.m_value.number_unsigned <=
+                         (std::numeric_limits<uint32_t>::max)())
+                {
+                    // uint 32
+                    oa->write_character(0xce);
+                    write_number(static_cast<uint32_t>(j.m_value.number_integer));
+                }
+                else if (j.m_value.number_unsigned <=
+                         (std::numeric_limits<uint64_t>::max)())
+                {
+                    // uint 64
+                    oa->write_character(0xcf);
+                    write_number(static_cast<uint64_t>(j.m_value.number_integer));
+                }
+                break;
+            }
 
-    #### Default type
+            case value_t::number_float:
+            {
+                // float 64
+                oa->write_character(0xcb);
+                write_number(j.m_value.number_float);
+                break;
+            }
 
-    With the default values for @a StringType (`std::string`), the default
-    value for @a string_t is:
+            case value_t::string:
+            {
+                // step 1: write control byte and the string length
+                const auto N = j.m_value.string->size();
+                if (N <= 31)
+                {
+                    // fixstr
+                    write_number(static_cast<uint8_t>(0xa0 | N));
+                }
+                else if (N <= 255)
+                {
+                    // str 8
+                    oa->write_character(0xd9);
+                    write_number(static_cast<uint8_t>(N));
+                }
+                else if (N <= 65535)
+                {
+                    // str 16
+                    oa->write_character(0xda);
+                    write_number(static_cast<uint16_t>(N));
+                }
+                else if (N <= 4294967295)
+                {
+                    // str 32
+                    oa->write_character(0xdb);
+                    write_number(static_cast<uint32_t>(N));
+                }
 
-    @code {.cpp}
-    std::string
-    @endcode
+                // step 2: write the string
+                oa->write_characters(
+                    reinterpret_cast<const uint8_t*>(j.m_value.string->c_str()),
+                    j.m_value.string->size());
+                break;
+            }
 
-    #### Encoding
+            case value_t::array:
+            {
+                // step 1: write control byte and the array size
+                const auto N = j.m_value.array->size();
+                if (N <= 15)
+                {
+                    // fixarray
+                    write_number(static_cast<uint8_t>(0x90 | N));
+                }
+                else if (N <= 0xffff)
+                {
+                    // array 16
+                    oa->write_character(0xdc);
+                    write_number(static_cast<uint16_t>(N));
+                }
+                else if (N <= 0xffffffff)
+                {
+                    // array 32
+                    oa->write_character(0xdd);
+                    write_number(static_cast<uint32_t>(N));
+                }
 
-    Strings are stored in UTF-8 encoding. Therefore, functions like
-    `std::string::size()` or `std::string::length()` return the number of
-    bytes in the string rather than the number of characters or glyphs.
+                // step 2: write each element
+                for (const auto& el : *j.m_value.array)
+                {
+                    write_msgpack(el);
+                }
+                break;
+            }
 
-    #### String comparison
+            case value_t::object:
+            {
+                // step 1: write control byte and the object size
+                const auto N = j.m_value.object->size();
+                if (N <= 15)
+                {
+                    // fixmap
+                    write_number(static_cast<uint8_t>(0x80 | (N & 0xf)));
+                }
+                else if (N <= 65535)
+                {
+                    // map 16
+                    oa->write_character(0xde);
+                    write_number(static_cast<uint16_t>(N));
+                }
+                else if (N <= 4294967295)
+                {
+                    // map 32
+                    oa->write_character(0xdf);
+                    write_number(static_cast<uint32_t>(N));
+                }
 
-    [RFC 7159](http://rfc7159.net/rfc7159) states:
-    > Software implementations are typically required to test names of object
-    > members for equality. Implementations that transform the textual
-    > representation into sequences of Unicode code units and then perform the
-    > comparison numerically, code unit by code unit, are interoperable in the
-    > sense that implementations will agree in all cases on equality or
-    > inequality of two strings. For example, implementations that compare
-    > strings with escaped characters unconverted may incorrectly find that
-    > `"a\\b"` and `"a\u005Cb"` are not equal.
+                // step 2: write each element
+                for (const auto& el : *j.m_value.object)
+                {
+                    write_msgpack(el.first);
+                    write_msgpack(el.second);
+                }
+                break;
+            }
 
-    This implementation is interoperable as it does compare strings code unit
-    by code unit.
+            default:
+            {
+                break;
+            }
+        }
+    }
 
-    #### Storage
+  private:
+    /*
+    @brief write a number to output input
 
-    String values are stored as pointers in a @ref basic_json type. That is,
-    for any access to string values, a pointer of type `string_t*` must be
-    dereferenced.
+    @param[in] n number of type @a NumberType
+    @tparam NumberType the type of the number
 
-    @since version 1.0.0
+    @note This function needs to respect the system's endianess, because
+          bytes in CBOR and MessagePack are stored in network order (big
+          endian) and therefore need reordering on little endian systems.
     */
-    using string_t = StringType;
+    template <typename NumberType> void write_number(NumberType n)
+    {
+        // step 1: write number to array of length NumberType
+        std::array<uint8_t, sizeof(NumberType)> vec;
+        std::memcpy(vec.data(), &n, sizeof(NumberType));
 
-    /*!
-    @brief a type for a boolean
+        // step 2: write array to output (with possible reordering)
+        if (is_little_endian)
+        {
+            // reverse byte order prior to conversion if necessary
+            std::reverse(vec.begin(), vec.end());
+        }
 
-    [RFC 7159](http://rfc7159.net/rfc7159) implicitly describes a boolean as a
-    type which differentiates the two literals `true` and `false`.
+        oa->write_characters(vec.data(), sizeof(NumberType));
+    }
 
-    To store objects in C++, a type is defined by the template parameter @a
-    BooleanType which chooses the type to use.
+  private:
+    /// whether we can assume little endianess
+    const bool is_little_endian = true;
 
-    #### Default type
+    /// the output
+    output_adapter_t<uint8_t> oa = nullptr;
+};
+} // namespace detail
 
-    With the default values for @a BooleanType (`bool`), the default value for
-    @a boolean_t is:
+/// namespace to hold default `to_json` / `from_json` functions
+namespace
+{
+constexpr const auto& to_json = detail::static_const<detail::to_json_fn>::value;
+constexpr const auto& from_json = detail::static_const<detail::from_json_fn>::value;
+}
 
-    @code {.cpp}
-    bool
-    @endcode
 
-    #### Storage
+/*!
+@brief default JSONSerializer template argument
 
-    Boolean values are stored directly inside a @ref basic_json type.
+This serializer ignores the template arguments and uses ADL
+([argument-dependent lookup](http://en.cppreference.com/w/cpp/language/adl))
+for serialization.
+*/
+template<typename, typename>
+struct adl_serializer
+{
+    /*!
+    @brief convert a JSON value to any value type
 
-    @since version 1.0.0
+    This function is usually called by the `get()` function of the
+    @ref basic_json class (either explicit or via conversion operators).
+
+    @param[in] j         JSON value to read from
+    @param[in,out] val  value to write to
     */
-    using boolean_t = BooleanType;
+    template<typename BasicJsonType, typename ValueType>
+    static void from_json(BasicJsonType&& j, ValueType& val) noexcept(
+        noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), val)))
+    {
+        ::nlohmann::from_json(std::forward<BasicJsonType>(j), val);
+    }
 
     /*!
-    @brief a type for a number (integer)
+    @brief convert any value type to a JSON value
 
-    [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
-    > The representation of numbers is similar to that used in most
-    > programming languages. A number is represented in base 10 using decimal
-    > digits. It contains an integer component that may be prefixed with an
-    > optional minus sign, which may be followed by a fraction part and/or an
-    > exponent part. Leading zeros are not allowed. (...) Numeric values that
-    > cannot be represented in the grammar below (such as Infinity and NaN)
-    > are not permitted.
+    This function is usually called by the constructors of the @ref basic_json
+    class.
 
-    This description includes both integer and floating-point numbers.
-    However, C++ allows more precise storage if it is known whether the number
-    is a signed integer, an unsigned integer or a floating-point number.
-    Therefore, three different types, @ref number_integer_t, @ref
-    number_unsigned_t and @ref number_float_t are used.
+    @param[in,out] j  JSON value to write to
+    @param[in] val     value to read from
+    */
+    template<typename BasicJsonType, typename ValueType>
+    static void to_json(BasicJsonType& j, ValueType&& val) noexcept(
+        noexcept(::nlohmann::to_json(j, std::forward<ValueType>(val))))
+    {
+        ::nlohmann::to_json(j, std::forward<ValueType>(val));
+    }
+};
 
-    To store integer numbers in C++, a type is defined by the template
-    parameter @a NumberIntegerType which chooses the type to use.
-
-    #### Default type
+/*!
+@brief JSON Pointer
 
-    With the default values for @a NumberIntegerType (`int64_t`), the default
-    value for @a number_integer_t is:
+A JSON pointer defines a string syntax for identifying a specific value
+within a JSON document. It can be used with functions `at` and
+`operator[]`. Furthermore, JSON pointers are the base for JSON patches.
 
-    @code {.cpp}
-    int64_t
-    @endcode
+@sa [RFC 6901](https://tools.ietf.org/html/rfc6901)
 
-    #### Default behavior
+@since version 2.0.0
+*/
+class json_pointer
+{
+    /// allow basic_json to access private members
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    friend class basic_json;
 
-    - The restrictions about leading zeros is not enforced in C++. Instead,
-      leading zeros in integer literals lead to an interpretation as octal
-      number. Internally, the value will be stored as decimal number. For
-      instance, the C++ integer literal `010` will be serialized to `8`.
-      During deserialization, leading zeros yield an error.
-    - Not-a-number (NaN) values will be serialized to `null`.
+  public:
+    /*!
+      @brief create JSON pointer
 
-    #### Limits
+      Create a JSON pointer according to the syntax described in
+      [Section 3 of RFC6901](https://tools.ietf.org/html/rfc6901#section-3).
 
-    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
-    > An implementation may set limits on the range and precision of numbers.
+      @param[in] s  string representing the JSON pointer; if omitted, the
+      empty string is assumed which references the whole JSON
+      value
 
-    When the default type is used, the maximal integer number that can be
-    stored is `9223372036854775807` (INT64_MAX) and the minimal integer number
-    that can be stored is `-9223372036854775808` (INT64_MIN). Integer numbers
-    that are out of range will yield over/underflow when used in a
-    constructor. During deserialization, too large or small integer numbers
-    will be automatically be stored as @ref number_unsigned_t or @ref
-    number_float_t.
+      @throw parse_error.107 if the given JSON pointer @a s is nonempty and
+      does not begin with a slash (`/`); see example below
 
-    [RFC 7159](http://rfc7159.net/rfc7159) further states:
-    > Note that when such software is used, numbers that are integers and are
-    > in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
-    > that implementations will agree exactly on their numeric values.
+      @throw parse_error.108 if a tilde (`~`) in the given JSON pointer @a s
+      is not followed by `0` (representing `~`) or `1` (representing `/`);
+      see example below
 
-    As this range is a subrange of the exactly supported range [INT64_MIN,
-    INT64_MAX], this class's integer type is interoperable.
+      @liveexample{The example shows the construction several valid JSON
+      pointers as well as the exceptional behavior.,json_pointer}
 
-    #### Storage
+      @since version 2.0.0
+      */
+    explicit json_pointer(const std::string& s = "") : reference_tokens(split(s)) {}
 
-    Integer number values are stored directly inside a @ref basic_json type.
+    /*!
+      @brief return a string representation of the JSON pointer
 
-    @sa @ref number_float_t -- type for number values (floating-point)
+      @invariant For each JSON pointer `ptr`, it holds:
+      @code {.cpp}
+      ptr == json_pointer(ptr.to_string());
+      @endcode
 
-    @sa @ref number_unsigned_t -- type for number values (unsigned integer)
+      @return a string representation of the JSON pointer
 
-    @since version 1.0.0
-    */
-    using number_integer_t = NumberIntegerType;
+      @liveexample{The example shows the result of `to_string`.,
+      json_pointer__to_string}
 
-    /*!
-    @brief a type for a number (unsigned)
+      @since version 2.0.0
+      */
+    std::string to_string() const noexcept
+    {
+        return std::accumulate(reference_tokens.begin(), reference_tokens.end(),
+                               std::string{},
+                               [](const std::string & a, const std::string & b)
+        {
+            return a + "/" + escape(b);
+        });
+    }
 
-    [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
-    > The representation of numbers is similar to that used in most
-    > programming languages. A number is represented in base 10 using decimal
-    > digits. It contains an integer component that may be prefixed with an
-    > optional minus sign, which may be followed by a fraction part and/or an
-    > exponent part. Leading zeros are not allowed. (...) Numeric values that
-    > cannot be represented in the grammar below (such as Infinity and NaN)
-    > are not permitted.
+    /// @copydoc to_string()
+    operator std::string() const
+    {
+        return to_string();
+    }
 
-    This description includes both integer and floating-point numbers.
-    However, C++ allows more precise storage if it is known whether the number
-    is a signed integer, an unsigned integer or a floating-point number.
-    Therefore, three different types, @ref number_integer_t, @ref
-    number_unsigned_t and @ref number_float_t are used.
+  private:
+    /*!
+      @brief remove and return last reference pointer
+      @throw out_of_range.405 if JSON pointer has no parent
+      */
+    std::string pop_back()
+    {
+        if (is_root())
+        {
+            JSON_THROW(
+                detail::out_of_range::create(405, "JSON pointer has no parent"));
+        }
 
-    To store unsigned integer numbers in C++, a type is defined by the
-    template parameter @a NumberUnsignedType which chooses the type to use.
+        auto last = reference_tokens.back();
+        reference_tokens.pop_back();
+        return last;
+    }
 
-    #### Default type
+    /// return whether pointer points to the root document
+    bool is_root() const
+    {
+        return reference_tokens.empty();
+    }
 
-    With the default values for @a NumberUnsignedType (`uint64_t`), the
-    default value for @a number_unsigned_t is:
+    json_pointer top() const
+    {
+        if (is_root())
+        {
+            JSON_THROW(detail::out_of_range::create(405, "JSON pointer has no parent"));
+        }
 
-    @code {.cpp}
-    uint64_t
-    @endcode
+        json_pointer result = *this;
+        result.reference_tokens = {reference_tokens[0]};
+        return result;
+    }
 
-    #### Default behavior
 
-    - The restrictions about leading zeros is not enforced in C++. Instead,
-      leading zeros in integer literals lead to an interpretation as octal
-      number. Internally, the value will be stored as decimal number. For
-      instance, the C++ integer literal `010` will be serialized to `8`.
-      During deserialization, leading zeros yield an error.
-    - Not-a-number (NaN) values will be serialized to `null`.
+    /*!
+      @brief create and return a reference to the pointed to value
 
-    #### Limits
+      @complexity Linear in the number of reference tokens.
 
-    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
-    > An implementation may set limits on the range and precision of numbers.
+      @throw parse_error.109 if array index is not a number
+      @throw type_error.313 if value cannot be unflattened
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    NLOHMANN_BASIC_JSON_TPL& get_and_create(NLOHMANN_BASIC_JSON_TPL& j) const;
 
-    When the default type is used, the maximal integer number that can be
-    stored is `18446744073709551615` (UINT64_MAX) and the minimal integer
-    number that can be stored is `0`. Integer numbers that are out of range
-    will yield over/underflow when used in a constructor. During
-    deserialization, too large or small integer numbers will be automatically
-    be stored as @ref number_integer_t or @ref number_float_t.
+    /*!
+      @brief return a reference to the pointed to value
 
-    [RFC 7159](http://rfc7159.net/rfc7159) further states:
-    > Note that when such software is used, numbers that are integers and are
-    > in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
-    > that implementations will agree exactly on their numeric values.
+      @note This version does not throw if a value is not present, but tries
+      to create nested values instead. For instance, calling this function
+      with pointer `"/this/that"` on a null value is equivalent to calling
+      `operator[]("this").operator[]("that")` on that value, effectively
+      changing the null value to an object.
 
-    As this range is a subrange (when considered in conjunction with the
-    number_integer_t type) of the exactly supported range [0, UINT64_MAX],
-    this class's integer type is interoperable.
+      @param[in] ptr  a JSON value
 
-    #### Storage
+      @return reference to the JSON value pointed to by the JSON pointer
 
-    Integer number values are stored directly inside a @ref basic_json type.
+      @complexity Linear in the length of the JSON pointer.
 
-    @sa @ref number_float_t -- type for number values (floating-point)
-    @sa @ref number_integer_t -- type for number values (integer)
+      @throw parse_error.106   if an array index begins with '0'
+      @throw parse_error.109   if an array index was not a number
+      @throw out_of_range.404  if the JSON pointer can not be resolved
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    NLOHMANN_BASIC_JSON_TPL& get_unchecked(NLOHMANN_BASIC_JSON_TPL* ptr) const;
 
-    @since version 2.0.0
-    */
-    using number_unsigned_t = NumberUnsignedType;
+    /*!
+      @throw parse_error.106   if an array index begins with '0'
+      @throw parse_error.109   if an array index was not a number
+      @throw out_of_range.402  if the array index '-' is used
+      @throw out_of_range.404  if the JSON pointer can not be resolved
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    NLOHMANN_BASIC_JSON_TPL& get_checked(NLOHMANN_BASIC_JSON_TPL* ptr) const;
 
     /*!
-    @brief a type for a number (floating-point)
+      @brief return a const reference to the pointed to value
 
-    [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
-    > The representation of numbers is similar to that used in most
-    > programming languages. A number is represented in base 10 using decimal
-    > digits. It contains an integer component that may be prefixed with an
-    > optional minus sign, which may be followed by a fraction part and/or an
-    > exponent part. Leading zeros are not allowed. (...) Numeric values that
-    > cannot be represented in the grammar below (such as Infinity and NaN)
-    > are not permitted.
+      @param[in] ptr  a JSON value
 
-    This description includes both integer and floating-point numbers.
-    However, C++ allows more precise storage if it is known whether the number
-    is a signed integer, an unsigned integer or a floating-point number.
-    Therefore, three different types, @ref number_integer_t, @ref
-    number_unsigned_t and @ref number_float_t are used.
+      @return const reference to the JSON value pointed to by the JSON
+      pointer
 
-    To store floating-point numbers in C++, a type is defined by the template
-    parameter @a NumberFloatType which chooses the type to use.
+      @throw parse_error.106   if an array index begins with '0'
+      @throw parse_error.109   if an array index was not a number
+      @throw out_of_range.402  if the array index '-' is used
+      @throw out_of_range.404  if the JSON pointer can not be resolved
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    const NLOHMANN_BASIC_JSON_TPL& get_unchecked(const NLOHMANN_BASIC_JSON_TPL* ptr) const;
 
-    #### Default type
+    /*!
+      @throw parse_error.106   if an array index begins with '0'
+      @throw parse_error.109   if an array index was not a number
+      @throw out_of_range.402  if the array index '-' is used
+      @throw out_of_range.404  if the JSON pointer can not be resolved
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    const NLOHMANN_BASIC_JSON_TPL& get_checked(const NLOHMANN_BASIC_JSON_TPL* ptr) const;
 
-    With the default values for @a NumberFloatType (`double`), the default
-    value for @a number_float_t is:
+    /*!
+      @brief split the string input to reference tokens
 
-    @code {.cpp}
-    double
-    @endcode
+      @note This function is only called by the json_pointer constructor.
+      All exceptions below are documented there.
 
-    #### Default behavior
+      @throw parse_error.107  if the pointer is not empty or begins with '/'
+      @throw parse_error.108  if character '~' is not followed by '0' or '1'
+      */
+    static std::vector<std::string> split(const std::string& reference_string)
+    {
+        std::vector<std::string> result;
 
-    - The restrictions about leading zeros is not enforced in C++. Instead,
-      leading zeros in floating-point literals will be ignored. Internally,
-      the value will be stored as decimal number. For instance, the C++
-      floating-point literal `01.2` will be serialized to `1.2`. During
-      deserialization, leading zeros yield an error.
-    - Not-a-number (NaN) values will be serialized to `null`.
+        // special case: empty reference string -> no reference tokens
+        if (reference_string.empty())
+        {
+            return result;
+        }
 
-    #### Limits
+        // check if nonempty reference string begins with slash
+        if (reference_string[0] != '/')
+        {
+            JSON_THROW(detail::parse_error::create(
+                           107, 1,
+                           "JSON pointer must be empty or begin with '/' - was: '" +
+                           reference_string + "'"));
+        }
 
-    [RFC 7159](http://rfc7159.net/rfc7159) states:
-    > This specification allows implementations to set limits on the range and
-    > precision of numbers accepted. Since software that implements IEEE
-    > 754-2008 binary64 (double precision) numbers is generally available and
-    > widely used, good interoperability can be achieved by implementations
-    > that expect no more precision or range than these provide, in the sense
-    > that implementations will approximate JSON numbers within the expected
-    > precision.
+        // extract the reference tokens:
+        // - slash: position of the last read slash (or end of string)
+        // - start: position after the previous slash
+        for (
+            // search for the first slash after the first character
+            size_t slash = reference_string.find_first_of('/', 1),
+            // set the beginning of the first reference token
+            start = 1;
+            // we can stop if start == string::npos+1 = 0
+            start != 0;
+            // set the beginning of the next reference token
+            // (will eventually be 0 if slash == std::string::npos)
+            start = slash + 1,
+            // find next slash
+            slash = reference_string.find_first_of('/', start))
+        {
+            // use the text between the beginning of the reference token
+            // (start) and the last slash (slash).
+            auto reference_token = reference_string.substr(start, slash - start);
 
-    This implementation does exactly follow this approach, as it uses double
-    precision floating-point numbers. Note values smaller than
-    `-1.79769313486232e+308` and values greater than `1.79769313486232e+308`
-    will be stored as NaN internally and be serialized to `null`.
+            // check reference tokens are properly escaped
+            for (size_t pos = reference_token.find_first_of('~');
+                    pos != std::string::npos;
+                    pos = reference_token.find_first_of('~', pos + 1))
+            {
+                assert(reference_token[pos] == '~');
 
-    #### Storage
+                // ~ must be followed by 0 or 1
+                if (pos == reference_token.size() - 1 or
+                        (reference_token[pos + 1] != '0' and
+                         reference_token[pos + 1] != '1'))
+                {
+                    JSON_THROW(detail::parse_error::create(
+                                   108, 0, "escape character '~' must be followed with '0' or '1'"));
+                }
+            }
 
-    Floating-point number values are stored directly inside a @ref basic_json
-    type.
+            // finally, store the reference token
+            unescape(reference_token);
+            result.push_back(reference_token);
+        }
 
-    @sa @ref number_integer_t -- type for number values (integer)
+        return result;
+    }
 
-    @sa @ref number_unsigned_t -- type for number values (unsigned integer)
+    /*!
+      @brief replace all occurrences of a substring by another string
 
-    @since version 1.0.0
-    */
-    using number_float_t = NumberFloatType;
+      @param[in,out] s  the string to manipulate; changed so that all
+      occurrences of @a f are replaced with @a t
+      @param[in]     f  the substring to replace with @a t
+      @param[in]     t  the string to replace @a f
 
-    /// @}
+      @pre The search string @a f must not be empty. **This precondition is
+      enforced with an assertion.**
 
-  private:
+      @since version 2.0.0
+      */
+    static void replace_substring(std::string& s, const std::string& f,
+                                  const std::string& t)
+    {
+        assert(not f.empty());
 
-    /// helper for exception-safe object creation
-    template<typename T, typename... Args>
-    static T* create(Args&& ... args)
+        for (size_t pos = s.find(f);         // find first occurrence of f
+                pos != std::string::npos;       // make sure f was found
+                s.replace(pos, f.size(), t),    // replace with t
+                pos = s.find(f, pos + t.size()) // find next occurrence of f
+            )
+            ;
+    }
+
+    /// escape tilde and slash
+    static std::string escape(std::string s)
     {
-        AllocatorType<T> alloc;
-        auto deleter = [&](T * object)
-        {
-            alloc.deallocate(object, 1);
-        };
-        std::unique_ptr<T, decltype(deleter)> object(alloc.allocate(1), deleter);
-        alloc.construct(object.get(), std::forward<Args>(args)...);
-        assert(object != nullptr);
-        return object.release();
+        // escape "~"" to "~0" and "/" to "~1"
+        replace_substring(s, "~", "~0");
+        replace_substring(s, "/", "~1");
+        return s;
     }
 
-    ////////////////////////
-    // JSON value storage //
-    ////////////////////////
+    /// unescape tilde and slash
+    static void unescape(std::string& s)
+    {
+        // first transform any occurrence of the sequence '~1' to '/'
+        replace_substring(s, "~1", "/");
+        // then transform any occurrence of the sequence '~0' to '~'
+        replace_substring(s, "~0", "~");
+    }
 
     /*!
-    @brief a JSON value
-
-    The actual storage for a JSON value of the @ref basic_json class. This
-    union combines the different storage types for the JSON value types
-    defined in @ref value_t.
-
-    JSON type | value_t type    | used type
-    --------- | --------------- | ------------------------
-    object    | object          | pointer to @ref object_t
-    array     | array           | pointer to @ref array_t
-    string    | string          | pointer to @ref string_t
-    boolean   | boolean         | @ref boolean_t
-    number    | number_integer  | @ref number_integer_t
-    number    | number_unsigned | @ref number_unsigned_t
-    number    | number_float    | @ref number_float_t
-    null      | null            | *no value is stored*
+      @param[in] reference_string  the reference string to the current value
+      @param[in] value             the value to consider
+      @param[in,out] result        the result object to insert values to
 
-    @note Variable-length types (objects, arrays, and strings) are stored as
-    pointers. The size of the union should not exceed 64 bits if the default
-    value types are used.
+      @note Empty objects or arrays are flattened to `null`.
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    static void flatten(const std::string& reference_string,
+                        const NLOHMANN_BASIC_JSON_TPL& value,
+                        NLOHMANN_BASIC_JSON_TPL& result);
 
-    @since version 1.0.0
-    */
-    union json_value
-    {
-        /// object (stored with pointer to save storage)
-        object_t* object;
-        /// array (stored with pointer to save storage)
-        array_t* array;
-        /// string (stored with pointer to save storage)
-        string_t* string;
-        /// boolean
-        boolean_t boolean;
-        /// number (integer)
-        number_integer_t number_integer;
-        /// number (unsigned integer)
-        number_unsigned_t number_unsigned;
-        /// number (floating-point)
-        number_float_t number_float;
+    /*!
+      @param[in] value  flattened JSON
 
-        /// default constructor (for null values)
-        json_value() = default;
-        /// constructor for booleans
-        json_value(boolean_t v) noexcept : boolean(v) {}
-        /// constructor for numbers (integer)
-        json_value(number_integer_t v) noexcept : number_integer(v) {}
-        /// constructor for numbers (unsigned)
-        json_value(number_unsigned_t v) noexcept : number_unsigned(v) {}
-        /// constructor for numbers (floating-point)
-        json_value(number_float_t v) noexcept : number_float(v) {}
-        /// constructor for empty values of a given type
-        json_value(value_t t)
-        {
-            switch (t)
-            {
-                case value_t::object:
-                {
-                    object = create<object_t>();
-                    break;
-                }
+      @return unflattened JSON
 
-                case value_t::array:
-                {
-                    array = create<array_t>();
-                    break;
-                }
+      @throw parse_error.109 if array index is not a number
+      @throw type_error.314  if value is not an object
+      @throw type_error.315  if object values are not primitive
+      @throw type_error.313  if value cannot be unflattened
+      */
+    NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    static NLOHMANN_BASIC_JSON_TPL
+    unflatten(const NLOHMANN_BASIC_JSON_TPL& value);
 
-                case value_t::string:
-                {
-                    string = create<string_t>("");
-                    break;
-                }
+    friend bool operator==(json_pointer const& lhs,
+                           json_pointer const& rhs) noexcept;
 
-                case value_t::boolean:
-                {
-                    boolean = boolean_t(false);
-                    break;
-                }
+    friend bool operator!=(json_pointer const& lhs,
+                           json_pointer const& rhs) noexcept;
 
-                case value_t::number_integer:
-                {
-                    number_integer = number_integer_t(0);
-                    break;
-                }
+    /// the reference tokens
+    std::vector<std::string> reference_tokens;
+};
 
-                case value_t::number_unsigned:
-                {
-                    number_unsigned = number_unsigned_t(0);
-                    break;
-                }
+/*!
+@brief a class to store JSON values
 
-                case value_t::number_float:
-                {
-                    number_float = number_float_t(0.0);
-                    break;
-                }
+@tparam ObjectType type for JSON objects (`std::map` by default; will be used
+in @ref object_t)
+@tparam ArrayType type for JSON arrays (`std::vector` by default; will be used
+in @ref array_t)
+@tparam StringType type for JSON strings and object keys (`std::string` by
+default; will be used in @ref string_t)
+@tparam BooleanType type for JSON booleans (`bool` by default; will be used
+in @ref boolean_t)
+@tparam NumberIntegerType type for JSON integer numbers (`int64_t` by
+default; will be used in @ref number_integer_t)
+@tparam NumberUnsignedType type for JSON unsigned integer numbers (@c
+`uint64_t` by default; will be used in @ref number_unsigned_t)
+@tparam NumberFloatType type for JSON floating-point numbers (`double` by
+default; will be used in @ref number_float_t)
+@tparam AllocatorType type of the allocator to use (`std::allocator` by
+default)
+@tparam JSONSerializer the serializer to resolve internal calls to `to_json()`
+and `from_json()` (@ref adl_serializer by default)
 
-                case value_t::null:
-                {
-                    break;
-                }
+@requirement The class satisfies the following concept requirements:
+- Basic
+ - [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible):
+   JSON values can be default constructed. The result will be a JSON null
+   value.
+ - [MoveConstructible](http://en.cppreference.com/w/cpp/concept/MoveConstructible):
+   A JSON value can be constructed from an rvalue argument.
+ - [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible):
+   A JSON value can be copy-constructed from an lvalue expression.
+ - [MoveAssignable](http://en.cppreference.com/w/cpp/concept/MoveAssignable):
+   A JSON value van be assigned from an rvalue argument.
+ - [CopyAssignable](http://en.cppreference.com/w/cpp/concept/CopyAssignable):
+   A JSON value can be copy-assigned from an lvalue expression.
+ - [Destructible](http://en.cppreference.com/w/cpp/concept/Destructible):
+   JSON values can be destructed.
+- Layout
+ - [StandardLayoutType](http://en.cppreference.com/w/cpp/concept/StandardLayoutType):
+   JSON values have
+   [standard layout](http://en.cppreference.com/w/cpp/language/data_members#Standard_layout):
+   All non-static data members are private and standard layout types, the
+   class has no virtual functions or (virtual) base classes.
+- Library-wide
+ - [EqualityComparable](http://en.cppreference.com/w/cpp/concept/EqualityComparable):
+   JSON values can be compared with `==`, see @ref
+   operator==(const_reference,const_reference).
+ - [LessThanComparable](http://en.cppreference.com/w/cpp/concept/LessThanComparable):
+   JSON values can be compared with `<`, see @ref
+   operator<(const_reference,const_reference).
+ - [Swappable](http://en.cppreference.com/w/cpp/concept/Swappable):
+   Any JSON lvalue or rvalue of can be swapped with any lvalue or rvalue of
+   other compatible types, using unqualified function call @ref swap().
+ - [NullablePointer](http://en.cppreference.com/w/cpp/concept/NullablePointer):
+   JSON values can be compared against `std::nullptr_t` objects which are used
+   to model the `null` value.
+- Container
+ - [Container](http://en.cppreference.com/w/cpp/concept/Container):
+   JSON values can be used like STL containers and provide iterator access.
+ - [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer);
+   JSON values can be used like STL containers and provide reverse iterator
+   access.
 
-                default:
-                {
-                    if (JSON_UNLIKELY(t == value_t::null))
-                    {
-                        JSON_THROW(other_error::create(500, "961c151d2e87f2686a955a9be24d316f1362bf21 2.1.1")); // LCOV_EXCL_LINE
-                    }
-                    break;
-                }
-            }
-        }
+@invariant The member variables @a m_value and @a m_type have the following
+relationship:
+- If `m_type == value_t::object`, then `m_value.object != nullptr`.
+- If `m_type == value_t::array`, then `m_value.array != nullptr`.
+- If `m_type == value_t::string`, then `m_value.string != nullptr`.
+The invariants are checked by member function assert_invariant().
 
-        /// constructor for strings
-        json_value(const string_t& value)
-        {
-            string = create<string_t>(value);
-        }
+@internal
+@note ObjectType trick from http://stackoverflow.com/a/9860911
+@endinternal
 
-        /// constructor for objects
-        json_value(const object_t& value)
-        {
-            object = create<object_t>(value);
-        }
+@see [RFC 7159: The JavaScript Object Notation (JSON) Data Interchange
+Format](http://rfc7159.net/rfc7159)
 
-        /// constructor for arrays
-        json_value(const array_t& value)
-        {
-            array = create<array_t>(value);
-        }
-    };
+@since version 1.0.0
 
-    /*!
-    @brief checks the class invariants
+@nosubgrouping
+*/
+NLOHMANN_BASIC_JSON_TPL_DECLARATION
+class basic_json
+{
+  private:
+    template<detail::value_t> friend struct detail::external_constructor;
+    friend ::nlohmann::json_pointer;
+    friend ::nlohmann::detail::parser<basic_json>;
+    template <typename BasicJsonType>
+    friend class ::nlohmann::detail::iter_impl;
+    /// workaround type for MSVC
+    using basic_json_t = NLOHMANN_BASIC_JSON_TPL;
 
-    This function asserts the class invariants. It needs to be called at the
-    end of every constructor to make sure that created objects respect the
-    invariant. Furthermore, it has to be called each time the type of a JSON
-    value is changed, because the invariant expresses a relationship between
-    @a m_type and @a m_value.
-    */
-    void assert_invariant() const
-    {
-        assert(m_type != value_t::object or m_value.object != nullptr);
-        assert(m_type != value_t::array or m_value.array != nullptr);
-        assert(m_type != value_t::string or m_value.string != nullptr);
-    }
+    // convenience aliases for types residing in namespace detail;
+    using lexer = ::nlohmann::detail::lexer<basic_json>;
+    using parser = ::nlohmann::detail::parser<basic_json>;
 
-  public:
-    //////////////////////////
-    // JSON parser callback //
-    //////////////////////////
+    using primitive_iterator_t = ::nlohmann::detail::primitive_iterator_t;
+    template <typename BasicJsonType>
+    using internal_iterator = ::nlohmann::detail::internal_iterator<BasicJsonType>;
+    template <typename BasicJsonType>
+    using iter_impl = ::nlohmann::detail::iter_impl<BasicJsonType>;
+    template <typename Iterator>
+    using iteration_proxy = ::nlohmann::detail::iteration_proxy<Iterator>;
+    template<typename Base> using json_reverse_iterator = ::nlohmann::detail::json_reverse_iterator<Base>;
 
-    using parse_event_t = typename parser::parse_event_t;
+    template <typename CharType>
+    using output_adapter_t = ::nlohmann::detail::output_adapter_t<CharType>;
 
-    /*!
-    @brief per-element parser callback type
+    using binary_reader = ::nlohmann::detail::binary_reader<basic_json>;
+    using binary_writer = ::nlohmann::detail::binary_writer<basic_json>;
 
-    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.
+  public:
+    using value_t = detail::value_t;
+    // forward declarations
+    using json_pointer = ::nlohmann::json_pointer;
+    template<typename T, typename SFINAE>
+    using json_serializer = JSONSerializer<T, SFINAE>;
 
-    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
+    ////////////////
+    // exceptions //
+    ////////////////
 
-    @image html callback_events.png "Example when certain parse events are triggered"
+    /// @name exceptions
+    /// Classes to implement user-defined exceptions.
+    /// @{
 
-    Discarding a value (i.e., returning `false`) has different effects
-    depending on the context in which function was called:
+    /// @copydoc detail::exception
+    using exception = detail::exception;
+    /// @copydoc detail::parse_error
+    using parse_error = detail::parse_error;
+    /// @copydoc detail::invalid_iterator
+    using invalid_iterator = detail::invalid_iterator;
+    /// @copydoc detail::type_error
+    using type_error = detail::type_error;
+    /// @copydoc detail::out_of_range
+    using out_of_range = detail::out_of_range;
+    /// @copydoc detail::other_error
+    using other_error = detail::other_error;
 
-    - 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
+    /////////////////////
+    // container types //
+    /////////////////////
 
-    @param[in,out] parsed  the current intermediate parse result; note that
-    writing to this value has no effect for parse_event_t::key events
+    /// @name container types
+    /// The canonic container types to use @ref basic_json like any other STL
+    /// container.
+    /// @{
 
-    @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.
+    /// the type of elements in a basic_json container
+    using value_type = basic_json;
 
-    @sa @ref parse(std::istream&, parser_callback_t) or
-    @ref parse(const CharT, const parser_callback_t) for examples
+    /// the type of an element reference
+    using reference = value_type&;
+    /// the type of an element const reference
+    using const_reference = const value_type&;
 
-    @since version 1.0.0
-    */
-    using parser_callback_t = typename parser::parser_callback_t;
+    /// a type to represent differences between iterators
+    using difference_type = std::ptrdiff_t;
+    /// a type to represent container sizes
+    using size_type = std::size_t;
 
+    /// the allocator type
+    using allocator_type = AllocatorType<basic_json>;
 
-    //////////////////
-    // constructors //
-    //////////////////
+    /// the type of an element pointer
+    using pointer = typename std::allocator_traits<allocator_type>::pointer;
+    /// the type of an element const pointer
+    using const_pointer = typename std::allocator_traits<allocator_type>::const_pointer;
 
-    /// @name constructors and destructors
-    /// Constructors of class @ref basic_json, copy/move constructor, copy
-    /// assignment, static functions creating objects, and the destructor.
-    /// @{
+    /// an iterator for a basic_json container
+    using iterator = iter_impl<basic_json>;
+    /// a const iterator for a basic_json container
+    using const_iterator = iter_impl<const basic_json>;
+    /// a reverse iterator for a basic_json container
+    using reverse_iterator = json_reverse_iterator<typename basic_json::iterator>;
+    /// a const reverse iterator for a basic_json container
+    using const_reverse_iterator = json_reverse_iterator<typename basic_json::const_iterator>;
 
-    /*!
-    @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] v  the type of the value to create
-
-    @complexity Constant.
-
-    @liveexample{The following code shows the constructor for different @ref
-    value_t values,basic_json__value_t}
-
-    @since version 1.0.0
+    /*!
+    @brief returns the allocator associated with the container
     */
-    basic_json(const value_t v)
-        : m_type(v), m_value(v)
+    static allocator_type get_allocator()
     {
-        assert_invariant();
+        return allocator_type();
     }
 
     /*!
-    @brief create a null object
+    @brief returns version information on the library
 
-    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.
+    This function returns a JSON object with information about the library,
+    including the version number and information on the platform and compiler.
 
-    @complexity Constant.
+    @return JSON object holding version information
+    key         | description
+    ----------- | ---------------
+    `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).
+    `copyright` | The copyright line for the library as string.
+    `name`      | The name of the library as string.
+    `platform`  | The used platform as string. Possible values are `win32`, `linux`, `apple`, `unix`, and `unknown`.
+    `url`       | The URL of the project as string.
+    `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).
 
-    @exceptionsafety No-throw guarantee: this constructor never throws
-    exceptions.
+    @liveexample{The following code shows an example output of the `meta()`
+    function.,meta}
 
-    @liveexample{The following code shows the constructor with and without a
-    null pointer parameter.,basic_json__nullptr_t}
+    @complexity Constant.
 
-    @since version 1.0.0
+    @since 2.1.0
     */
-    basic_json(std::nullptr_t = nullptr) noexcept
-        : basic_json(value_t::null)
+    static basic_json meta()
     {
-        assert_invariant();
-    }
-
-    /*!
-    @brief create a JSON value
+        basic_json result;
 
-    This is a "catch all" constructor for all compatible JSON types; that is,
-    types for which a `to_json()` method exsits. The constructor forwards the
-    parameter @a val to that method (to `json_serializer<U>::to_json` method
-    with `U = uncvref_t<CompatibleType>`, to be exact).
+        result["copyright"] = "(C) 2013-2017 Niels Lohmann";
+        result["name"] = "JSON for Modern C++";
+        result["url"] = "https://github.com/nlohmann/json";
+        result["version"] =
+        {
+            {"string", "2.1.1"}, {"major", 2}, {"minor", 1}, {"patch", 1}
+        };
 
-    Template type @a CompatibleType includes, but is not limited to, the
-    following types:
-    - **arrays**: @ref array_t and all kinds of compatible containers such as
-      `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.
-    - **objects**: @ref object_t and all kinds of compatible associative
-      containers such as `std::map`, `std::unordered_map`, `std::multimap`,
-      and `std::unordered_multimap` with a `key_type` compatible to
-      @ref string_t and a `value_type` from which a @ref basic_json value can
-      be constructed.
-    - **strings**: @ref string_t, string literals, and all compatible string
-      containers can be used.
-    - **numbers**: @ref number_integer_t, @ref number_unsigned_t,
-      @ref number_float_t, and all convertible number types such as `int`,
-      `size_t`, `int64_t`, `float` or `double` can be used.
-    - **boolean**: @ref boolean_t / `bool` can be used.
+#ifdef _WIN32
+        result["platform"] = "win32";
+#elif defined __linux__
+        result["platform"] = "linux";
+#elif defined __APPLE__
+        result["platform"] = "apple";
+#elif defined __unix__
+        result["platform"] = "unix";
+#else
+        result["platform"] = "unknown";
+#endif
 
-    See the examples below.
+#if defined(__clang__)
+        result["compiler"] = {{"family", "clang"}, {"version", __clang_version__}};
+#elif defined(__ICC) || defined(__INTEL_COMPILER)
+        result["compiler"] = {{"family", "icc"}, {"version", __INTEL_COMPILER}};
+#elif defined(__GNUC__) || defined(__GNUG__)
+        result["compiler"] = {{"family", "gcc"}, {"version", std::to_string(__GNUC__) + "." + std::to_string(__GNUC_MINOR__) + "." + std::to_string(__GNUC_PATCHLEVEL__)}};
+#elif defined(__HP_cc) || defined(__HP_aCC)
+        result["compiler"] = "hp"
+#elif defined(__IBMCPP__)
+        result["compiler"] = {{"family", "ilecpp"}, {"version", __IBMCPP__}};
+#elif defined(_MSC_VER)
+        result["compiler"] = {{"family", "msvc"}, {"version", _MSC_VER}};
+#elif defined(__PGI)
+        result["compiler"] = {{"family", "pgcpp"}, {"version", __PGI}};
+#elif defined(__SUNPRO_CC)
+        result["compiler"] = {{"family", "sunpro"}, {"version", __SUNPRO_CC}};
+#else
+        result["compiler"] = {{"family", "unknown"}, {"version", "unknown"}};
+#endif
 
-    @tparam CompatibleType a type such that:
-    - @a CompatibleType is not derived from `std::istream`,
-    - @a CompatibleType is not @ref basic_json (to avoid hijacking copy/move
-         constructors),
-    - @a CompatibleType is not a @ref basic_json nested type (e.g.,
-         @ref json_pointer, @ref iterator, etc ...)
-    - @ref @ref json_serializer<U> has a
-         `to_json(basic_json_t&, CompatibleType&&)` method
+#ifdef __cplusplus
+        result["compiler"]["c++"] = std::to_string(__cplusplus);
+#else
+        result["compiler"]["c++"] = "unknown";
+#endif
+        return result;
+    }
 
-    @tparam U = `uncvref_t<CompatibleType>`
 
-    @param[in] val the value to be forwarded
+    ///////////////////////////
+    // JSON value data types //
+    ///////////////////////////
 
-    @complexity Usually linear in the size of the passed @a val, also
-                depending on the implementation of the called `to_json()`
-                method.
+    /// @name JSON value data types
+    /// The data types to store a JSON value. These types are derived from
+    /// the template arguments passed to class @ref basic_json.
+    /// @{
 
-    @throw what `json_serializer<U>::to_json()` throws
+    /*!
+    @brief a type for an object
 
-    @liveexample{The following code shows the constructor with several
-    compatible types.,basic_json__CompatibleType}
+    [RFC 7159](http://rfc7159.net/rfc7159) describes JSON objects as follows:
+    > An object is an unordered collection of zero or more name/value pairs,
+    > where a name is a string and a value is a string, number, boolean, null,
+    > object, or array.
 
-    @since version 2.1.0
-    */
-    template<typename CompatibleType, typename U = detail::uncvref_t<CompatibleType>,
-             detail::enable_if_t<not std::is_base_of<std::istream, U>::value and
-                                 not std::is_same<U, basic_json_t>::value and
-                                 not detail::is_basic_json_nested_type<
-                                     basic_json_t, U>::value and
-                                 detail::has_to_json<basic_json, U>::value,
-                                 int> = 0>
-    basic_json(CompatibleType && val) noexcept(noexcept(JSONSerializer<U>::to_json(
-                std::declval<basic_json_t&>(), std::forward<CompatibleType>(val))))
-    {
-        JSONSerializer<U>::to_json(*this, std::forward<CompatibleType>(val));
-        assert_invariant();
-    }
+    To store objects in C++, a type is defined by the template parameters
+    described below.
 
-    /*!
-    @brief create a container (array or object) from an initializer list
+    @tparam ObjectType  the container to store objects (e.g., `std::map` or
+    `std::unordered_map`)
+    @tparam StringType the type of the keys or names (e.g., `std::string`).
+    The comparison function `std::less<StringType>` is used to order elements
+    inside the container.
+    @tparam AllocatorType the allocator to use for objects (e.g.,
+    `std::allocator`)
 
-    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:
+    #### Default type
 
-    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.
+    With the default values for @a ObjectType (`std::map`), @a StringType
+    (`std::string`), and @a AllocatorType (`std::allocator`), the default
+    value for @a object_t is:
 
-    The rules aim to create the best fit between a C++ initializer list and
-    JSON values. The rationale is as follows:
+    @code {.cpp}
+    std::map<
+      std::string, // key_type
+      basic_json, // value_type
+      std::less<std::string>, // key_compare
+      std::allocator<std::pair<const std::string, basic_json>> // allocator_type
+    >
+    @endcode
 
-    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.
+    #### Behavior
 
-    With the rules described above, the following JSON values cannot be
-    expressed by an initializer list:
+    The choice of @a object_t influences the behavior of the JSON class. With
+    the default type, objects have the following behavior:
 
-    - 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
+    - When all names are unique, objects will be interoperable in the sense
+      that all software implementations receiving that object will agree on
+      the name-value mappings.
+    - When the names within an object are not unique, later stored name/value
+      pairs overwrite previously stored name/value pairs, leaving the used
+      names unique. For instance, `{"key": 1}` and `{"key": 2, "key": 1}` will
+      be treated as equal and both stored as `{"key": 1}`.
+    - Internally, name/value pairs are stored in lexicographical order of the
+      names. Objects will also be serialized (see @ref dump) in this order.
+      For instance, `{"b": 1, "a": 2}` and `{"a": 2, "b": 1}` will be stored
+      and serialized as `{"a": 2, "b": 1}`.
+    - When comparing objects, the order of the name/value pairs is irrelevant.
+      This makes objects interoperable in the sense that they will not be
+      affected by these differences. For instance, `{"b": 1, "a": 2}` and
+      `{"a": 2, "b": 1}` will be treated as equal.
 
-    @note When used without parentheses around an empty initializer list, @ref
-    basic_json() is called instead of this function, yielding the JSON null
-    value.
+    #### Limits
 
-    @param[in] init  initializer list with JSON values
+    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
+    > An implementation may set limits on the maximum depth of nesting.
 
-    @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>).
+    In this class, the object's limit of nesting is not constraint explicitly.
+    However, a maximum depth of nesting may be introduced by the compiler or
+    runtime environment. A theoretical limit can be queried by calling the
+    @ref max_size function of a JSON object.
 
-    @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
+    #### Storage
 
-    @throw type_error.301 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. In this case, the constructor could not
-    create an object. If @a type_deduction would have be `true`, an array
-    would have been created. See @ref object(std::initializer_list<basic_json>)
-    for an example.
-
-    @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}
+    Objects are stored as pointers in a @ref basic_json type. That is, for any
+    access to object values, a pointer of type `object_t*` must be
+    dereferenced.
 
-    @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
+    @sa @ref array_t -- type for an array value
 
     @since version 1.0.0
+
+    @note The order name/value pairs are added to the object is *not*
+    preserved by the library. Therefore, iterating an object may return
+    name/value pairs in a different order than they were originally stored. In
+    fact, keys will be traversed in alphabetical order as `std::map` with
+    `std::less` is used by default. Please note this behavior conforms to [RFC
+    7159](http://rfc7159.net/rfc7159), because any order implements the
+    specified "unordered" nature of JSON objects.
     */
-    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();
-        });
+    using object_t = ObjectType<StringType,
+          basic_json,
+          std::less<StringType>,
+          AllocatorType<std::pair<const StringType,
+          basic_json>>>;
 
-        // 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;
-            }
+    /*!
+    @brief a type for an array
 
-            // if object is wanted but impossible, throw an exception
-            if (manual_type == value_t::object and not is_an_object)
-            {
-                JSON_THROW(type_error::create(301, "cannot create object from initializer list"));
-            }
-        }
+    [RFC 7159](http://rfc7159.net/rfc7159) describes JSON arrays as follows:
+    > An array is an ordered sequence of zero or more values.
 
-        if (is_an_object)
-        {
-            // the initializer list is a list of pairs -> create object
-            m_type = value_t::object;
-            m_value = value_t::object;
+    To store objects in C++, a type is defined by the template parameters
+    explained below.
 
-            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);
-        }
+    @tparam ArrayType  container type to store arrays (e.g., `std::vector` or
+    `std::list`)
+    @tparam AllocatorType allocator to use for arrays (e.g., `std::allocator`)
 
-        assert_invariant();
-    }
+    #### Default type
 
-    /*!
-    @brief explicitly create an array from an initializer list
+    With the default values for @a ArrayType (`std::vector`) and @a
+    AllocatorType (`std::allocator`), the default value for @a array_t is:
 
-    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.
+    @code {.cpp}
+    std::vector<
+      basic_json, // value_type
+      std::allocator<basic_json> // allocator_type
+    >
+    @endcode
 
-    @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
+    #### Limits
 
-    @param[in] init  initializer list with JSON values to create an array from
-    (optional)
+    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
+    > An implementation may set limits on the maximum depth of nesting.
 
-    @return JSON array value
+    In this class, the array's limit of nesting is not constraint explicitly.
+    However, a maximum depth of nesting may be introduced by the compiler or
+    runtime environment. A theoretical limit can be queried by calling the
+    @ref max_size function of a JSON array.
 
-    @complexity Linear in the size of @a init.
+    #### Storage
 
-    @liveexample{The following code shows an example for the `array`
-    function.,array}
+    Arrays are stored as pointers in a @ref basic_json type. That is, for any
+    access to array values, a pointer of type `array_t*` must be dereferenced.
 
-    @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
+    @sa @ref object_t -- type for an object value
 
     @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);
-    }
+    using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;
 
     /*!
-    @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.
+    @brief a type for a string
 
-    @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).
+    [RFC 7159](http://rfc7159.net/rfc7159) describes JSON strings as follows:
+    > A string is a sequence of zero or more Unicode characters.
 
-    @param[in] init  initializer list to create an object from (optional)
+    To store objects in C++, a type is defined by the template parameter
+    described below. Unicode values are split by the JSON class into
+    byte-sized characters during deserialization.
 
-    @return JSON object value
+    @tparam StringType  the container to store strings (e.g., `std::string`).
+    Note this container is used for keys/names in objects, see @ref object_t.
 
-    @throw type_error.301 if @a init is not a list of pairs whose first
-    elements are strings. In this case, no object can be created. When such a
-    value is passed to @ref basic_json(std::initializer_list<basic_json>, bool, value_t),
-    an array would have been created from the passed initializer list @a init.
-    See example below.
+    #### Default type
 
-    @complexity Linear in the size of @a init.
+    With the default values for @a StringType (`std::string`), the default
+    value for @a string_t is:
 
-    @liveexample{The following code shows an example for the `object`
-    function.,object}
+    @code {.cpp}
+    std::string
+    @endcode
 
-    @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
+    #### Encoding
 
-    @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);
-    }
+    Strings are stored in UTF-8 encoding. Therefore, functions like
+    `std::string::size()` or `std::string::length()` return the number of
+    bytes in the string rather than the number of characters or glyphs.
 
-    /*!
-    @brief construct an array with count copies of given value
+    #### String comparison
 
-    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.
+    [RFC 7159](http://rfc7159.net/rfc7159) states:
+    > Software implementations are typically required to test names of object
+    > members for equality. Implementations that transform the textual
+    > representation into sequences of Unicode code units and then perform the
+    > comparison numerically, code unit by code unit, are interoperable in the
+    > sense that implementations will agree in all cases on equality or
+    > inequality of two strings. For example, implementations that compare
+    > strings with escaped characters unconverted may incorrectly find that
+    > `"a\\b"` and `"a\u005Cb"` are not equal.
 
-    @param[in] cnt  the number of JSON copies of @a val to create
-    @param[in] val  the JSON value to copy
+    This implementation is interoperable as it does compare strings code unit
+    by code unit.
 
-    @complexity Linear in @a cnt.
+    #### Storage
 
-    @liveexample{The following code shows examples for the @ref
-    basic_json(size_type\, const basic_json&)
-    constructor.,basic_json__size_type_basic_json}
+    String values are stored as pointers in a @ref basic_json type. That is,
+    for any access to string values, a pointer of type `string_t*` must be
+    dereferenced.
 
     @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();
-    }
+    using string_t = StringType;
 
     /*!
-    @brief construct a JSON container given an iterator range
+    @brief a type for a boolean
 
-    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, invalid_iterator.204 is thrown.
-    - In case of structured types (array, object), the constructor behaves as
-      similar versions for `std::vector`.
-    - In case of a null type, invalid_iterator.206 is thrown.
+    [RFC 7159](http://rfc7159.net/rfc7159) implicitly describes a boolean as a
+    type which differentiates the two literals `true` and `false`.
 
-    @tparam InputIT an input iterator type (@ref iterator or @ref
-    const_iterator)
+    To store objects in C++, a type is defined by the template parameter @a
+    BooleanType which chooses the type to use.
 
-    @param[in] first begin of the range to copy from (included)
-    @param[in] last end of the range to copy from (excluded)
+    #### Default type
 
-    @pre Iterators @a first and @a last must be initialized. **This
-         precondition is enforced with an assertion.**
+    With the default values for @a BooleanType (`bool`), the default value for
+    @a boolean_t is:
 
-    @pre Range `[first, last)` is valid. Usually, this precondition cannot be
-         checked efficiently. Only certain edge cases are detected; see the
-         description of the exceptions below.
+    @code {.cpp}
+    bool
+    @endcode
 
-    @throw invalid_iterator.201 if iterators @a first and @a last are not
-    compatible (i.e., do not belong to the same JSON value). In this case,
-    the range `[first, last)` is undefined.
-    @throw invalid_iterator.204 if iterators @a first and @a last belong to a
-    primitive type (number, boolean, or string), but @a first does not point
-    to the first element any more. In this case, the range `[first, last)` is
-    undefined. See example code below.
-    @throw invalid_iterator.206 if iterators @a first and @a last belong to a
-    null value. In this case, the range `[first, last)` is undefined.
+    #### Storage
 
-    @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}
+    Boolean values are stored directly inside a @ref basic_json type.
 
     @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(invalid_iterator::create(201, "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(invalid_iterator::create(204, "iterators out of range"));
-                }
-                break;
-            }
+    using boolean_t = BooleanType;
 
-            default:
-            {
-                break;
-            }
-        }
+    /*!
+    @brief a type for a number (integer)
 
-        switch (m_type)
-        {
-            case value_t::number_integer:
-            {
-                m_value.number_integer = first.m_object->m_value.number_integer;
-                break;
-            }
+    [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
+    > The representation of numbers is similar to that used in most
+    > programming languages. A number is represented in base 10 using decimal
+    > digits. It contains an integer component that may be prefixed with an
+    > optional minus sign, which may be followed by a fraction part and/or an
+    > exponent part. Leading zeros are not allowed. (...) Numeric values that
+    > cannot be represented in the grammar below (such as Infinity and NaN)
+    > are not permitted.
 
-            case value_t::number_unsigned:
-            {
-                m_value.number_unsigned = first.m_object->m_value.number_unsigned;
-                break;
-            }
+    This description includes both integer and floating-point numbers.
+    However, C++ allows more precise storage if it is known whether the number
+    is a signed integer, an unsigned integer or a floating-point number.
+    Therefore, three different types, @ref number_integer_t, @ref
+    number_unsigned_t and @ref number_float_t are used.
 
-            case value_t::number_float:
-            {
-                m_value.number_float = first.m_object->m_value.number_float;
-                break;
-            }
+    To store integer numbers in C++, a type is defined by the template
+    parameter @a NumberIntegerType which chooses the type to use.
 
-            case value_t::boolean:
-            {
-                m_value.boolean = first.m_object->m_value.boolean;
-                break;
-            }
+    #### Default type
 
-            case value_t::string:
-            {
-                m_value = *first.m_object->m_value.string;
-                break;
-            }
+    With the default values for @a NumberIntegerType (`int64_t`), the default
+    value for @a number_integer_t is:
 
-            case value_t::object:
-            {
-                m_value.object = create<object_t>(first.m_it.object_iterator,
-                                                  last.m_it.object_iterator);
-                break;
-            }
+    @code {.cpp}
+    int64_t
+    @endcode
 
-            case value_t::array:
-            {
-                m_value.array = create<array_t>(first.m_it.array_iterator,
-                                                last.m_it.array_iterator);
-                break;
-            }
+    #### Default behavior
 
-            default:
-            {
-                JSON_THROW(invalid_iterator::create(206, "cannot construct with iterators from " +
-                                                    first.m_object->type_name()));
-            }
-        }
+    - The restrictions about leading zeros is not enforced in C++. Instead,
+      leading zeros in integer literals lead to an interpretation as octal
+      number. Internally, the value will be stored as decimal number. For
+      instance, the C++ integer literal `010` will be serialized to `8`.
+      During deserialization, leading zeros yield an error.
+    - Not-a-number (NaN) values will be serialized to `null`.
 
-        assert_invariant();
-    }
+    #### Limits
 
+    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
+    > An implementation may set limits on the range and precision of numbers.
 
-    ///////////////////////////////////////
-    // other constructors and destructor //
-    ///////////////////////////////////////
+    When the default type is used, the maximal integer number that can be
+    stored is `9223372036854775807` (INT64_MAX) and the minimal integer number
+    that can be stored is `-9223372036854775808` (INT64_MIN). Integer numbers
+    that are out of range will yield over/underflow when used in a
+    constructor. During deserialization, too large or small integer numbers
+    will be automatically be stored as @ref number_unsigned_t or @ref
+    number_float_t.
 
-    /*!
-    @brief copy constructor
+    [RFC 7159](http://rfc7159.net/rfc7159) further states:
+    > Note that when such software is used, numbers that are integers and are
+    > in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
+    > that implementations will agree exactly on their numeric values.
 
-    Creates a copy of a given JSON value.
+    As this range is a subrange of the exactly supported range [INT64_MIN,
+    INT64_MAX], this class's integer type is interoperable.
 
-    @param[in] other  the JSON value to copy
+    #### Storage
 
-    @complexity Linear in the size of @a other.
+    Integer number values are stored directly inside a @ref basic_json type.
 
-    @requirement This function helps `basic_json` satisfying the
-    [Container](http://en.cppreference.com/w/cpp/concept/Container)
-    requirements:
-    - The complexity is linear.
-    - As postcondition, it holds: `other == basic_json(other)`.
+    @sa @ref number_float_t -- type for number values (floating-point)
 
-    @liveexample{The following code shows an example for the copy
-    constructor.,basic_json__basic_json}
+    @sa @ref number_unsigned_t -- type for number values (unsigned integer)
 
     @since version 1.0.0
     */
-    basic_json(const basic_json& other)
-        : m_type(other.m_type)
-    {
-        // check of passed value is valid
-        other.assert_invariant();
-
-        switch (m_type)
-        {
-            case value_t::object:
-            {
-                m_value = *other.m_value.object;
-                break;
-            }
+    using number_integer_t = NumberIntegerType;
 
-            case value_t::array:
-            {
-                m_value = *other.m_value.array;
-                break;
-            }
+    /*!
+    @brief a type for a number (unsigned)
 
-            case value_t::string:
-            {
-                m_value = *other.m_value.string;
-                break;
-            }
+    [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
+    > The representation of numbers is similar to that used in most
+    > programming languages. A number is represented in base 10 using decimal
+    > digits. It contains an integer component that may be prefixed with an
+    > optional minus sign, which may be followed by a fraction part and/or an
+    > exponent part. Leading zeros are not allowed. (...) Numeric values that
+    > cannot be represented in the grammar below (such as Infinity and NaN)
+    > are not permitted.
 
-            case value_t::boolean:
-            {
-                m_value = other.m_value.boolean;
-                break;
-            }
+    This description includes both integer and floating-point numbers.
+    However, C++ allows more precise storage if it is known whether the number
+    is a signed integer, an unsigned integer or a floating-point number.
+    Therefore, three different types, @ref number_integer_t, @ref
+    number_unsigned_t and @ref number_float_t are used.
 
-            case value_t::number_integer:
-            {
-                m_value = other.m_value.number_integer;
-                break;
-            }
+    To store unsigned integer numbers in C++, a type is defined by the
+    template parameter @a NumberUnsignedType which chooses the type to use.
 
-            case value_t::number_unsigned:
-            {
-                m_value = other.m_value.number_unsigned;
-                break;
-            }
+    #### Default type
 
-            case value_t::number_float:
-            {
-                m_value = other.m_value.number_float;
-                break;
-            }
+    With the default values for @a NumberUnsignedType (`uint64_t`), the
+    default value for @a number_unsigned_t is:
 
-            default:
-            {
-                break;
-            }
-        }
+    @code {.cpp}
+    uint64_t
+    @endcode
 
-        assert_invariant();
-    }
+    #### Default behavior
 
-    /*!
-    @brief move constructor
+    - The restrictions about leading zeros is not enforced in C++. Instead,
+      leading zeros in integer literals lead to an interpretation as octal
+      number. Internally, the value will be stored as decimal number. For
+      instance, the C++ integer literal `010` will be serialized to `8`.
+      During deserialization, leading zeros yield an error.
+    - Not-a-number (NaN) values will be serialized to `null`.
 
-    Move constructor. Constructs a JSON value with the contents of the given
-    value @a other using move semantics. It "steals" the resources from @a
-    other and leaves it as JSON null value.
+    #### Limits
 
-    @param[in,out] other  value to move to this object
+    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
+    > An implementation may set limits on the range and precision of numbers.
 
-    @post @a other is a JSON null value
+    When the default type is used, the maximal integer number that can be
+    stored is `18446744073709551615` (UINT64_MAX) and the minimal integer
+    number that can be stored is `0`. Integer numbers that are out of range
+    will yield over/underflow when used in a constructor. During
+    deserialization, too large or small integer numbers will be automatically
+    be stored as @ref number_integer_t or @ref number_float_t.
 
-    @complexity Constant.
+    [RFC 7159](http://rfc7159.net/rfc7159) further states:
+    > Note that when such software is used, numbers that are integers and are
+    > in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
+    > that implementations will agree exactly on their numeric values.
 
-    @liveexample{The code below shows the move constructor explicitly called
-    via std::move.,basic_json__moveconstructor}
-
-    @since version 1.0.0
-    */
-    basic_json(basic_json&& other) noexcept
-        : m_type(std::move(other.m_type)),
-          m_value(std::move(other.m_value))
-    {
-        // check that passed value is valid
-        other.assert_invariant();
-
-        // invalidate payload
-        other.m_type = value_t::null;
-        other.m_value = {};
-
-        assert_invariant();
-    }
-
-    /*!
-    @brief copy assignment
-
-    Copy assignment operator. Copies a JSON value via the "copy and swap"
-    strategy: It is expressed in terms of the copy constructor, destructor,
-    and the swap() member function.
-
-    @param[in] other  value to copy from
+    As this range is a subrange (when considered in conjunction with the
+    number_integer_t type) of the exactly supported range [0, UINT64_MAX],
+    this class's integer type is interoperable.
 
-    @complexity Linear.
+    #### Storage
 
-    @requirement This function helps `basic_json` satisfying the
-    [Container](http://en.cppreference.com/w/cpp/concept/Container)
-    requirements:
-    - The complexity is linear.
+    Integer number values are stored directly inside a @ref basic_json type.
 
-    @liveexample{The code below shows and example for the copy assignment. It
-    creates a copy of value `a` which is then swapped with `b`. Finally\, the
-    copy of `a` (which is the null value after the swap) is
-    destroyed.,basic_json__copyassignment}
+    @sa @ref number_float_t -- type for number values (floating-point)
+    @sa @ref number_integer_t -- type for number values (integer)
 
-    @since version 1.0.0
+    @since version 2.0.0
     */
-    reference& operator=(basic_json other) noexcept (
-        std::is_nothrow_move_constructible<value_t>::value and
-        std::is_nothrow_move_assignable<value_t>::value and
-        std::is_nothrow_move_constructible<json_value>::value and
-        std::is_nothrow_move_assignable<json_value>::value
-    )
-    {
-        // check that passed value is valid
-        other.assert_invariant();
-
-        using std::swap;
-        swap(m_type, other.m_type);
-        swap(m_value, other.m_value);
-
-        assert_invariant();
-        return *this;
-    }
+    using number_unsigned_t = NumberUnsignedType;
 
     /*!
-    @brief destructor
+    @brief a type for a number (floating-point)
 
-    Destroys the JSON value and frees all allocated memory.
+    [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
+    > The representation of numbers is similar to that used in most
+    > programming languages. A number is represented in base 10 using decimal
+    > digits. It contains an integer component that may be prefixed with an
+    > optional minus sign, which may be followed by a fraction part and/or an
+    > exponent part. Leading zeros are not allowed. (...) Numeric values that
+    > cannot be represented in the grammar below (such as Infinity and NaN)
+    > are not permitted.
 
-    @complexity Linear.
+    This description includes both integer and floating-point numbers.
+    However, C++ allows more precise storage if it is known whether the number
+    is a signed integer, an unsigned integer or a floating-point number.
+    Therefore, three different types, @ref number_integer_t, @ref
+    number_unsigned_t and @ref number_float_t are used.
 
-    @requirement This function helps `basic_json` satisfying the
-    [Container](http://en.cppreference.com/w/cpp/concept/Container)
-    requirements:
-    - The complexity is linear.
-    - All stored elements are destroyed and all memory is freed.
+    To store floating-point numbers in C++, a type is defined by the template
+    parameter @a NumberFloatType which chooses the type to use.
 
-    @since version 1.0.0
-    */
-    ~basic_json()
-    {
-        assert_invariant();
+    #### Default type
 
-        switch (m_type)
-        {
-            case value_t::object:
-            {
-                AllocatorType<object_t> alloc;
-                alloc.destroy(m_value.object);
-                alloc.deallocate(m_value.object, 1);
-                break;
-            }
+    With the default values for @a NumberFloatType (`double`), the default
+    value for @a number_float_t is:
 
-            case value_t::array:
-            {
-                AllocatorType<array_t> alloc;
-                alloc.destroy(m_value.array);
-                alloc.deallocate(m_value.array, 1);
-                break;
-            }
+    @code {.cpp}
+    double
+    @endcode
 
-            case value_t::string:
-            {
-                AllocatorType<string_t> alloc;
-                alloc.destroy(m_value.string);
-                alloc.deallocate(m_value.string, 1);
-                break;
-            }
+    #### Default behavior
 
-            default:
-            {
-                // all other types need no specific destructor
-                break;
-            }
-        }
-    }
+    - The restrictions about leading zeros is not enforced in C++. Instead,
+      leading zeros in floating-point literals will be ignored. Internally,
+      the value will be stored as decimal number. For instance, the C++
+      floating-point literal `01.2` will be serialized to `1.2`. During
+      deserialization, leading zeros yield an error.
+    - Not-a-number (NaN) values will be serialized to `null`.
 
-    /// @}
+    #### Limits
 
-  public:
-    ///////////////////////
-    // object inspection //
-    ///////////////////////
+    [RFC 7159](http://rfc7159.net/rfc7159) states:
+    > This specification allows implementations to set limits on the range and
+    > precision of numbers accepted. Since software that implements IEEE
+    > 754-2008 binary64 (double precision) numbers is generally available and
+    > widely used, good interoperability can be achieved by implementations
+    > that expect no more precision or range than these provide, in the sense
+    > that implementations will approximate JSON numbers within the expected
+    > precision.
 
-    /// @name object inspection
-    /// Functions to inspect the type of a JSON value.
-    /// @{
+    This implementation does exactly follow this approach, as it uses double
+    precision floating-point numbers. Note values smaller than
+    `-1.79769313486232e+308` and values greater than `1.79769313486232e+308`
+    will be stored as NaN internally and be serialized to `null`.
 
-    /*!
-    @brief serialization
+    #### Storage
 
-    Serialization function for JSON values. The function tries to mimic
-    Python's `json.dumps()` function, and currently supports its @a indent
-    parameter.
+    Floating-point number values are stored directly inside a @ref basic_json
+    type.
 
-    @param[in] indent If indent is nonnegative, then array elements and object
-    members will be pretty-printed with that indent level. An indent level of
-    `0` will only insert newlines. `-1` (the default) selects the most compact
-    representation.
-    @param[in] indent_char The character to use for indentation if @a indent is
-    greater than `0`. The default is ` ` (space).
+    @sa @ref number_integer_t -- type for number values (integer)
 
-    @return string containing the serialization of the JSON value
+    @sa @ref number_unsigned_t -- type for number values (unsigned integer)
 
-    @complexity Linear.
+    @since version 1.0.0
+    */
+    using number_float_t = NumberFloatType;
 
-    @liveexample{The following example shows the effect of different @a indent
-    parameters to the result of the serialization.,dump}
+    /// @}
 
-    @see https://docs.python.org/2/library/json.html#json.dump
+  private:
 
-    @since version 1.0.0; indentation character added in version 3.0.0
-    */
-    string_t dump(const int indent = -1, const char indent_char = ' ') const
+    /// helper for exception-safe object creation
+    template<typename T, typename... Args>
+    static T* create(Args&& ... args)
     {
-        string_t result;
-        serializer s(output_adapter<char>::create(result), indent_char);
-
-        if (indent >= 0)
-        {
-            s.dump(*this, true, static_cast<unsigned int>(indent));
-        }
-        else
+        AllocatorType<T> alloc;
+        auto deleter = [&](T * object)
         {
-            s.dump(*this, false, 0);
-        }
-
-        return result;
+            alloc.deallocate(object, 1);
+        };
+        std::unique_ptr<T, decltype(deleter)> object(alloc.allocate(1), deleter);
+        alloc.construct(object.get(), std::forward<Args>(args)...);
+        assert(object != nullptr);
+        return object.release();
     }
 
-    /*!
-    @brief return the type of the JSON value (explicit)
-
-    Return the type of the JSON value as a value from the @ref value_t
-    enumeration.
+    ////////////////////////
+    // JSON value storage //
+    ////////////////////////
 
-    @return the type of the JSON value
+    /*!
+    @brief a JSON value
 
-    @complexity Constant.
+    The actual storage for a JSON value of the @ref basic_json class. This
+    union combines the different storage types for the JSON value types
+    defined in @ref value_t.
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    JSON type | value_t type    | used type
+    --------- | --------------- | ------------------------
+    object    | object          | pointer to @ref object_t
+    array     | array           | pointer to @ref array_t
+    string    | string          | pointer to @ref string_t
+    boolean   | boolean         | @ref boolean_t
+    number    | number_integer  | @ref number_integer_t
+    number    | number_unsigned | @ref number_unsigned_t
+    number    | number_float    | @ref number_float_t
+    null      | null            | *no value is stored*
 
-    @liveexample{The following code exemplifies `type()` for all JSON
-    types.,type}
+    @note Variable-length types (objects, arrays, and strings) are stored as
+    pointers. The size of the union should not exceed 64 bits if the default
+    value types are used.
 
     @since version 1.0.0
     */
-    constexpr value_t type() const noexcept
+    union json_value
     {
-        return m_type;
-    }
-
-    /*!
-    @brief return whether type is primitive
-
-    This function returns true iff the JSON type is primitive (string, number,
-    boolean, or null).
-
-    @return `true` if type is primitive (string, number, boolean, or null),
-    `false` otherwise.
-
-    @complexity Constant.
-
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+        /// object (stored with pointer to save storage)
+        object_t* object;
+        /// array (stored with pointer to save storage)
+        array_t* array;
+        /// string (stored with pointer to save storage)
+        string_t* string;
+        /// boolean
+        boolean_t boolean;
+        /// number (integer)
+        number_integer_t number_integer;
+        /// number (unsigned integer)
+        number_unsigned_t number_unsigned;
+        /// number (floating-point)
+        number_float_t number_float;
 
-    @liveexample{The following code exemplifies `is_primitive()` for all JSON
-    types.,is_primitive}
+        /// default constructor (for null values)
+        json_value() = default;
+        /// constructor for booleans
+        json_value(boolean_t v) noexcept : boolean(v) {}
+        /// constructor for numbers (integer)
+        json_value(number_integer_t v) noexcept : number_integer(v) {}
+        /// constructor for numbers (unsigned)
+        json_value(number_unsigned_t v) noexcept : number_unsigned(v) {}
+        /// constructor for numbers (floating-point)
+        json_value(number_float_t v) noexcept : number_float(v) {}
+        /// constructor for empty values of a given type
+        json_value(value_t t)
+        {
+            switch (t)
+            {
+                case value_t::object:
+                {
+                    object = create<object_t>();
+                    break;
+                }
 
-    @sa @ref is_structured() -- returns whether JSON value is structured
-    @sa @ref is_null() -- returns whether JSON value is `null`
-    @sa @ref is_string() -- returns whether JSON value is a string
-    @sa @ref is_boolean() -- returns whether JSON value is a boolean
-    @sa @ref is_number() -- returns whether JSON value is a number
+                case value_t::array:
+                {
+                    array = create<array_t>();
+                    break;
+                }
 
-    @since version 1.0.0
-    */
-    constexpr bool is_primitive() const noexcept
-    {
-        return is_null() or is_string() or is_boolean() or is_number();
-    }
+                case value_t::string:
+                {
+                    string = create<string_t>("");
+                    break;
+                }
 
-    /*!
-    @brief return whether type is structured
+                case value_t::boolean:
+                {
+                    boolean = boolean_t(false);
+                    break;
+                }
 
-    This function returns true iff the JSON type is structured (array or
-    object).
+                case value_t::number_integer:
+                {
+                    number_integer = number_integer_t(0);
+                    break;
+                }
 
-    @return `true` if type is structured (array or object), `false` otherwise.
+                case value_t::number_unsigned:
+                {
+                    number_unsigned = number_unsigned_t(0);
+                    break;
+                }
 
-    @complexity Constant.
+                case value_t::number_float:
+                {
+                    number_float = number_float_t(0.0);
+                    break;
+                }
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+                case value_t::null:
+                {
+                    break;
+                }
 
-    @liveexample{The following code exemplifies `is_structured()` for all JSON
-    types.,is_structured}
+                default:
+                {
+                    if (JSON_UNLIKELY(t == value_t::null))
+                    {
+                        JSON_THROW(other_error::create(500, "961c151d2e87f2686a955a9be24d316f1362bf21 2.1.1")); // LCOV_EXCL_LINE
+                    }
+                    break;
+                }
+            }
+        }
 
-    @sa @ref is_primitive() -- returns whether value is primitive
-    @sa @ref is_array() -- returns whether value is an array
-    @sa @ref is_object() -- returns whether value is an object
+        /// constructor for strings
+        json_value(const string_t& value)
+        {
+            string = create<string_t>(value);
+        }
 
-    @since version 1.0.0
+        /// constructor for objects
+        json_value(const object_t& value)
+        {
+            object = create<object_t>(value);
+        }
+
+        /// constructor for arrays
+        json_value(const array_t& value)
+        {
+            array = create<array_t>(value);
+        }
+    };
+
+    /*!
+    @brief checks the class invariants
+
+    This function asserts the class invariants. It needs to be called at the
+    end of every constructor to make sure that created objects respect the
+    invariant. Furthermore, it has to be called each time the type of a JSON
+    value is changed, because the invariant expresses a relationship between
+    @a m_type and @a m_value.
     */
-    constexpr bool is_structured() const noexcept
+    void assert_invariant() const
     {
-        return is_array() or is_object();
+        assert(m_type != value_t::object or m_value.object != nullptr);
+        assert(m_type != value_t::array or m_value.array != nullptr);
+        assert(m_type != value_t::string or m_value.string != nullptr);
     }
 
+  public:
+    //////////////////////////
+    // JSON parser callback //
+    //////////////////////////
+
+    using parse_event_t = typename parser::parse_event_t;
+
     /*!
-    @brief return whether value is null
+    @brief per-element parser callback type
 
-    This function returns true iff the JSON value is null.
+    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.
 
-    @return `true` if type is null, `false` otherwise.
+    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.
 
-    @complexity Constant.
+    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
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    @image html callback_events.png "Example when certain parse events are triggered"
 
-    @liveexample{The following code exemplifies `is_null()` for all JSON
-    types.,is_null}
+    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
     */
-    constexpr bool is_null() const noexcept
-    {
-        return m_type == value_t::null;
-    }
+    using parser_callback_t = typename parser::parser_callback_t;
+
+
+    //////////////////
+    // constructors //
+    //////////////////
+
+    /// @name constructors and destructors
+    /// Constructors of class @ref basic_json, copy/move constructor, copy
+    /// assignment, static functions creating objects, and the destructor.
+    /// @{
 
     /*!
-    @brief return whether value is a boolean
+    @brief create an empty value with a given type
 
-    This function returns true iff the JSON value is a boolean.
+    Create an empty JSON value with a given type. The value will be default
+    initialized with an empty value which depends on the type:
 
-    @return `true` if type is boolean, `false` otherwise.
+    Value type  | initial value
+    ----------- | -------------
+    null        | `null`
+    boolean     | `false`
+    string      | `""`
+    number      | `0`
+    object      | `{}`
+    array       | `[]`
 
-    @complexity Constant.
+    @param[in] v  the type of the value to create
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    @complexity Constant.
 
-    @liveexample{The following code exemplifies `is_boolean()` for all JSON
-    types.,is_boolean}
+    @liveexample{The following code shows the constructor for different @ref
+    value_t values,basic_json__value_t}
 
     @since version 1.0.0
     */
-    constexpr bool is_boolean() const noexcept
+    basic_json(const value_t v)
+        : m_type(v), m_value(v)
     {
-        return m_type == value_t::boolean;
+        assert_invariant();
     }
 
     /*!
-    @brief return whether value is a number
-
-    This function returns true iff the JSON value is a number. This includes
-    both integer and floating-point values.
+    @brief create a null object
 
-    @return `true` if type is number (regardless whether integer, unsigned
-    integer or floating-type), `false` otherwise.
+    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 member function never throws
+    @exceptionsafety No-throw guarantee: this constructor never throws
     exceptions.
 
-    @liveexample{The following code exemplifies `is_number()` for all JSON
-    types.,is_number}
-
-    @sa @ref is_number_integer() -- check if value is an integer or unsigned
-    integer number
-    @sa @ref is_number_unsigned() -- check if value is an unsigned integer
-    number
-    @sa @ref is_number_float() -- check if value is a floating-point number
+    @liveexample{The following code shows the constructor with and without a
+    null pointer parameter.,basic_json__nullptr_t}
 
     @since version 1.0.0
     */
-    constexpr bool is_number() const noexcept
+    basic_json(std::nullptr_t = nullptr) noexcept
+        : basic_json(value_t::null)
     {
-        return is_number_integer() or is_number_float();
+        assert_invariant();
     }
 
     /*!
-    @brief return whether value is an integer number
+    @brief create a JSON value
 
-    This function returns true iff the JSON value is an integer or unsigned
-    integer number. This excludes floating-point values.
+    This is a "catch all" constructor for all compatible JSON types; that is,
+    types for which a `to_json()` method exsits. The constructor forwards the
+    parameter @a val to that method (to `json_serializer<U>::to_json` method
+    with `U = uncvref_t<CompatibleType>`, to be exact).
 
-    @return `true` if type is an integer or unsigned integer number, `false`
-    otherwise.
+    Template type @a CompatibleType includes, but is not limited to, the
+    following types:
+    - **arrays**: @ref array_t and all kinds of compatible containers such as
+      `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.
+    - **objects**: @ref object_t and all kinds of compatible associative
+      containers such as `std::map`, `std::unordered_map`, `std::multimap`,
+      and `std::unordered_multimap` with a `key_type` compatible to
+      @ref string_t and a `value_type` from which a @ref basic_json value can
+      be constructed.
+    - **strings**: @ref string_t, string literals, and all compatible string
+      containers can be used.
+    - **numbers**: @ref number_integer_t, @ref number_unsigned_t,
+      @ref number_float_t, and all convertible number types such as `int`,
+      `size_t`, `int64_t`, `float` or `double` can be used.
+    - **boolean**: @ref boolean_t / `bool` can be used.
 
-    @complexity Constant.
+    See the examples below.
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    @tparam CompatibleType a type such that:
+    - @a CompatibleType is not derived from `std::istream`,
+    - @a CompatibleType is not @ref basic_json (to avoid hijacking copy/move
+         constructors),
+    - @a CompatibleType is not a @ref basic_json nested type (e.g.,
+         @ref json_pointer, @ref iterator, etc ...)
+    - @ref @ref json_serializer<U> has a
+         `to_json(basic_json_t&, CompatibleType&&)` method
 
-    @liveexample{The following code exemplifies `is_number_integer()` for all
-    JSON types.,is_number_integer}
+    @tparam U = `uncvref_t<CompatibleType>`
 
-    @sa @ref is_number() -- check if value is a number
-    @sa @ref is_number_unsigned() -- check if value is an unsigned integer
-    number
-    @sa @ref is_number_float() -- check if value is a floating-point number
+    @param[in] val the value to be forwarded
 
-    @since version 1.0.0
+    @complexity Usually linear in the size of the passed @a val, also
+                depending on the implementation of the called `to_json()`
+                method.
+
+    @throw what `json_serializer<U>::to_json()` throws
+
+    @liveexample{The following code shows the constructor with several
+    compatible types.,basic_json__CompatibleType}
+
+    @since version 2.1.0
     */
-    constexpr bool is_number_integer() const noexcept
+    template<typename CompatibleType, typename U = detail::uncvref_t<CompatibleType>,
+             detail::enable_if_t<not std::is_base_of<std::istream, U>::value and
+                                 not std::is_same<U, basic_json_t>::value and
+                                 not detail::is_basic_json_nested_type<
+                                     basic_json_t, U>::value and
+                                 detail::has_to_json<basic_json, U>::value,
+                                 int> = 0>
+    basic_json(CompatibleType && val) noexcept(noexcept(JSONSerializer<U>::to_json(
+                std::declval<basic_json_t&>(), std::forward<CompatibleType>(val))))
     {
-        return m_type == value_t::number_integer or m_type == value_t::number_unsigned;
+        JSONSerializer<U>::to_json(*this, std::forward<CompatibleType>(val));
+        assert_invariant();
     }
 
     /*!
-    @brief return whether value is an unsigned integer number
+    @brief create a container (array or object) from an initializer list
 
-    This function returns true iff the JSON value is an unsigned integer
-    number. This excludes floating-point and (signed) integer values.
+    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:
 
-    @return `true` if type is an unsigned integer number, `false` otherwise.
+    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.
 
-    @complexity Constant.
+    The rules aim to create the best fit between a C++ initializer list and
+    JSON values. The rationale is as follows:
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    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.
 
-    @liveexample{The following code exemplifies `is_number_unsigned()` for all
-    JSON types.,is_number_unsigned}
+    With the rules described above, the following JSON values cannot be
+    expressed by an initializer list:
 
-    @sa @ref is_number() -- check if value is a number
-    @sa @ref is_number_integer() -- check if value is an integer or unsigned
-    integer number
-    @sa @ref is_number_float() -- check if value is a floating-point number
+    - 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
 
-    @since version 2.0.0
-    */
-    constexpr bool is_number_unsigned() const noexcept
-    {
-        return m_type == value_t::number_unsigned;
-    }
+    @note When used without parentheses around an empty initializer list, @ref
+    basic_json() is called instead of this function, yielding the JSON null
+    value.
 
-    /*!
-    @brief return whether value is a floating-point number
+    @param[in] init  initializer list with JSON values
 
-    This function returns true iff the JSON value is a floating-point number.
-    This excludes integer and unsigned integer 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>).
 
-    @return `true` if type is a floating-point number, `false` otherwise.
+    @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
 
-    @complexity Constant.
+    @throw type_error.301 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. In this case, the constructor could not
+    create an object. If @a type_deduction would have be `true`, an array
+    would have been created. See @ref object(std::initializer_list<basic_json>)
+    for an example.
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    @complexity Linear in the size of the initializer list @a init.
 
-    @liveexample{The following code exemplifies `is_number_float()` for all
-    JSON types.,is_number_float}
+    @liveexample{The example below shows how JSON values are created from
+    initializer lists.,basic_json__list_init_t}
 
-    @sa @ref is_number() -- check if value is number
-    @sa @ref is_number_integer() -- check if value is an integer number
-    @sa @ref is_number_unsigned() -- check if value is an unsigned integer
-    number
+    @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
     */
-    constexpr bool is_number_float() const noexcept
+    basic_json(std::initializer_list<basic_json> init,
+               bool type_deduction = true,
+               value_t manual_type = value_t::array)
     {
-        return m_type == value_t::number_float;
+        // 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(type_error::create(301, "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 return whether value is an object
+    @brief explicitly create an array from an initializer list
 
-    This function returns true iff the JSON value is an object.
+    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.
 
-    @return `true` if type is object, `false` otherwise.
+    @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
 
-    @complexity Constant.
+    @param[in] init  initializer list with JSON values to create an array from
+    (optional)
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    @return JSON array value
 
-    @liveexample{The following code exemplifies `is_object()` for all JSON
-    types.,is_object}
+    @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
     */
-    constexpr bool is_object() const noexcept
+    static basic_json array(std::initializer_list<basic_json> init =
+                                std::initializer_list<basic_json>())
     {
-        return m_type == value_t::object;
+        return basic_json(init, false, value_t::array);
     }
 
     /*!
-    @brief return whether value is an array
+    @brief explicitly create an object from an initializer list
 
-    This function returns true iff the JSON value is an array.
+    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.
 
-    @return `true` if type is array, `false` otherwise.
+    @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).
 
-    @complexity Constant.
+    @param[in] init  initializer list to create an object from (optional)
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    @return JSON object value
 
-    @liveexample{The following code exemplifies `is_array()` for all JSON
-    types.,is_array}
+    @throw type_error.301 if @a init is not a list of pairs whose first
+    elements are strings. In this case, no object can be created. When such a
+    value is passed to @ref basic_json(std::initializer_list<basic_json>, bool, value_t),
+    an array would have been created from the passed initializer list @a init.
+    See example below.
+
+    @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
     */
-    constexpr bool is_array() const noexcept
+    static basic_json object(std::initializer_list<basic_json> init =
+                                 std::initializer_list<basic_json>())
     {
-        return m_type == value_t::array;
+        return basic_json(init, false, value_t::object);
     }
 
     /*!
-    @brief return whether value is a string
-
-    This function returns true iff the JSON value is a string.
+    @brief construct an array with count copies of given value
 
-    @return `true` if type is string, `false` otherwise.
+    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.
 
-    @complexity Constant.
+    @param[in] cnt  the number of JSON copies of @a val to create
+    @param[in] val  the JSON value to copy
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    @complexity Linear in @a cnt.
 
-    @liveexample{The following code exemplifies `is_string()` for all JSON
-    types.,is_string}
+    @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
     */
-    constexpr bool is_string() const noexcept
+    basic_json(size_type cnt, const basic_json& val)
+        : m_type(value_t::array)
     {
-        return m_type == value_t::string;
+        m_value.array = create<array_t>(cnt, val);
+        assert_invariant();
     }
 
     /*!
-    @brief return whether value is discarded
+    @brief construct a JSON container given an iterator range
 
-    This function returns true iff the JSON value was discarded during parsing
-    with a callback function (see @ref parser_callback_t).
+    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, invalid_iterator.204 is thrown.
+    - In case of structured types (array, object), the constructor behaves as
+      similar versions for `std::vector`.
+    - In case of a null type, invalid_iterator.206 is thrown.
 
-    @note This function will always be `false` for JSON values after parsing.
-    That is, discarded values can only occur during parsing, but will be
-    removed when inside a structured value or replaced by null in other cases.
+    @tparam InputIT an input iterator type (@ref iterator or @ref
+    const_iterator)
 
-    @return `true` if type is discarded, `false` otherwise.
+    @param[in] first begin of the range to copy from (included)
+    @param[in] last end of the range to copy from (excluded)
 
-    @complexity Constant.
+    @pre Iterators @a first and @a last must be initialized. **This
+         precondition is enforced with an assertion.**
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+    @pre Range `[first, last)` is valid. Usually, this precondition cannot be
+         checked efficiently. Only certain edge cases are detected; see the
+         description of the exceptions below.
 
-    @liveexample{The following code exemplifies `is_discarded()` for all JSON
-    types.,is_discarded}
+    @throw invalid_iterator.201 if iterators @a first and @a last are not
+    compatible (i.e., do not belong to the same JSON value). In this case,
+    the range `[first, last)` is undefined.
+    @throw invalid_iterator.204 if iterators @a first and @a last belong to a
+    primitive type (number, boolean, or string), but @a first does not point
+    to the first element any more. In this case, the range `[first, last)` is
+    undefined. See example code below.
+    @throw invalid_iterator.206 if iterators @a first and @a last belong to a
+    null value. In this case, the range `[first, last)` is undefined.
+
+    @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
     */
-    constexpr bool is_discarded() const noexcept
+    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)
     {
-        return m_type == value_t::discarded;
-    }
+        assert(first.m_object != nullptr);
+        assert(last.m_object != nullptr);
 
-    /*!
-    @brief return the type of the JSON value (implicit)
+        // make sure iterator fits the current value
+        if (first.m_object != last.m_object)
+        {
+            JSON_THROW(invalid_iterator::create(201, "iterators are not compatible"));
+        }
 
-    Implicitly return the type of the JSON value as a value from the @ref
-    value_t enumeration.
+        // copy type from first iterator
+        m_type = first.m_object->m_type;
 
-    @return the type of the JSON value
+        // 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(invalid_iterator::create(204, "iterators out of range"));
+                }
+                break;
+            }
 
-    @complexity Constant.
+            default:
+            {
+                break;
+            }
+        }
 
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
+        switch (m_type)
+        {
+            case value_t::number_integer:
+            {
+                m_value.number_integer = first.m_object->m_value.number_integer;
+                break;
+            }
 
-    @liveexample{The following code exemplifies the @ref value_t operator for
-    all JSON types.,operator__value_t}
+            case value_t::number_unsigned:
+            {
+                m_value.number_unsigned = first.m_object->m_value.number_unsigned;
+                break;
+            }
 
-    @since version 1.0.0
-    */
-    constexpr operator value_t() const noexcept
-    {
-        return m_type;
-    }
+            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;
+            }
 
-  private:
-    //////////////////
-    // value access //
-    //////////////////
+            case value_t::string:
+            {
+                m_value = *first.m_object->m_value.string;
+                break;
+            }
 
-    /// get a boolean (explicit)
-    boolean_t get_impl(boolean_t* /*unused*/) const
-    {
-        if (is_boolean())
-        {
-            return m_value.boolean;
+            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);
+                break;
+            }
+
+            default:
+            {
+                JSON_THROW(invalid_iterator::create(206, "cannot construct with iterators from " +
+                                                    first.m_object->type_name()));
+            }
         }
 
-        JSON_THROW(type_error::create(302, "type must be boolean, but is " + type_name()));
+        assert_invariant();
     }
 
-    /// get a pointer to the value (object)
-    object_t* get_impl_ptr(object_t* /*unused*/) noexcept
-    {
-        return is_object() ? m_value.object : nullptr;
-    }
 
-    /// get a pointer to the value (object)
-    constexpr const object_t* get_impl_ptr(const object_t* /*unused*/) const noexcept
-    {
-        return is_object() ? m_value.object : nullptr;
-    }
+    ///////////////////////////////////////
+    // other constructors and destructor //
+    ///////////////////////////////////////
 
-    /// get a pointer to the value (array)
-    array_t* get_impl_ptr(array_t* /*unused*/) noexcept
-    {
-        return is_array() ? m_value.array : nullptr;
-    }
+    /*!
+    @brief copy constructor
 
-    /// get a pointer to the value (array)
-    constexpr const array_t* get_impl_ptr(const array_t* /*unused*/) const noexcept
-    {
-        return is_array() ? m_value.array : nullptr;
-    }
+    Creates a copy of a given JSON value.
 
-    /// get a pointer to the value (string)
-    string_t* get_impl_ptr(string_t* /*unused*/) noexcept
-    {
-        return is_string() ? m_value.string : nullptr;
-    }
+    @param[in] other  the JSON value to copy
 
-    /// get a pointer to the value (string)
-    constexpr const string_t* get_impl_ptr(const string_t* /*unused*/) const noexcept
-    {
-        return is_string() ? m_value.string : nullptr;
-    }
+    @complexity Linear in the size of @a other.
 
-    /// get a pointer to the value (boolean)
-    boolean_t* get_impl_ptr(boolean_t* /*unused*/) noexcept
-    {
-        return is_boolean() ? &m_value.boolean : nullptr;
-    }
-
-    /// get a pointer to the value (boolean)
-    constexpr const boolean_t* get_impl_ptr(const boolean_t* /*unused*/) const noexcept
-    {
-        return is_boolean() ? &m_value.boolean : nullptr;
-    }
-
-    /// get a pointer to the value (integer number)
-    number_integer_t* get_impl_ptr(number_integer_t* /*unused*/) noexcept
-    {
-        return is_number_integer() ? &m_value.number_integer : nullptr;
-    }
-
-    /// get a pointer to the value (integer number)
-    constexpr const number_integer_t* get_impl_ptr(const number_integer_t* /*unused*/) const noexcept
-    {
-        return is_number_integer() ? &m_value.number_integer : nullptr;
-    }
+    @requirement This function helps `basic_json` satisfying the
+    [Container](http://en.cppreference.com/w/cpp/concept/Container)
+    requirements:
+    - The complexity is linear.
+    - As postcondition, it holds: `other == basic_json(other)`.
 
-    /// get a pointer to the value (unsigned number)
-    number_unsigned_t* get_impl_ptr(number_unsigned_t* /*unused*/) noexcept
-    {
-        return is_number_unsigned() ? &m_value.number_unsigned : nullptr;
-    }
+    @liveexample{The following code shows an example for the copy
+    constructor.,basic_json__basic_json}
 
-    /// get a pointer to the value (unsigned number)
-    constexpr const number_unsigned_t* get_impl_ptr(const number_unsigned_t* /*unused*/) const noexcept
+    @since version 1.0.0
+    */
+    basic_json(const basic_json& other)
+        : m_type(other.m_type)
     {
-        return is_number_unsigned() ? &m_value.number_unsigned : nullptr;
-    }
+        // check of passed value is valid
+        other.assert_invariant();
 
-    /// get a pointer to the value (floating-point number)
-    number_float_t* get_impl_ptr(number_float_t* /*unused*/) noexcept
-    {
-        return is_number_float() ? &m_value.number_float : nullptr;
-    }
+        switch (m_type)
+        {
+            case value_t::object:
+            {
+                m_value = *other.m_value.object;
+                break;
+            }
 
-    /// get a pointer to the value (floating-point number)
-    constexpr const number_float_t* get_impl_ptr(const number_float_t* /*unused*/) const noexcept
-    {
-        return is_number_float() ? &m_value.number_float : nullptr;
-    }
+            case value_t::array:
+            {
+                m_value = *other.m_value.array;
+                break;
+            }
 
-    /*!
-    @brief helper function to implement get_ref()
+            case value_t::string:
+            {
+                m_value = *other.m_value.string;
+                break;
+            }
 
-    This function helps to implement get_ref() without code duplication for
-    const and non-const overloads
+            case value_t::boolean:
+            {
+                m_value = other.m_value.boolean;
+                break;
+            }
 
-    @tparam ThisType will be deduced as `basic_json` or `const basic_json`
+            case value_t::number_integer:
+            {
+                m_value = other.m_value.number_integer;
+                break;
+            }
 
-    @throw type_error.303 if ReferenceType does not match underlying value
-    type of the current JSON
-    */
-    template<typename ReferenceType, typename ThisType>
-    static ReferenceType get_ref_impl(ThisType& obj)
-    {
-        // helper type
-        using PointerType = typename std::add_pointer<ReferenceType>::type;
+            case value_t::number_unsigned:
+            {
+                m_value = other.m_value.number_unsigned;
+                break;
+            }
 
-        // delegate the call to get_ptr<>()
-        auto ptr = obj.template get_ptr<PointerType>();
+            case value_t::number_float:
+            {
+                m_value = other.m_value.number_float;
+                break;
+            }
 
-        if (ptr != nullptr)
-        {
-            return *ptr;
+            default:
+            {
+                break;
+            }
         }
 
-        JSON_THROW(type_error::create(303, "incompatible ReferenceType for get_ref, actual type is " + obj.type_name()));
+        assert_invariant();
     }
 
-  public:
-    /// @name value access
-    /// Direct access to the stored value of a JSON value.
-    /// @{
-
     /*!
-    @brief get special-case overload
+    @brief move constructor
 
-    This overloads avoids a lot of template boilerplate, it can be seen as the
-    identity method
+    Move constructor. Constructs a JSON value with the contents of the given
+    value @a other using move semantics. It "steals" the resources from @a
+    other and leaves it as JSON null value.
 
-    @tparam BasicJsonType == @ref basic_json
+    @param[in,out] other  value to move to this object
 
-    @return a copy of *this
+    @post @a other is a JSON null value
 
     @complexity Constant.
 
-    @since version 2.1.0
+    @liveexample{The code below shows the move constructor explicitly called
+    via std::move.,basic_json__moveconstructor}
+
+    @since version 1.0.0
     */
-    template <
-        typename BasicJsonType,
-        detail::enable_if_t<std::is_same<typename std::remove_const<BasicJsonType>::type,
-                                         basic_json_t>::value,
-                            int> = 0 >
-    basic_json get() const
+    basic_json(basic_json&& other) noexcept
+        : m_type(std::move(other.m_type)),
+          m_value(std::move(other.m_value))
     {
-        return *this;
-    }
+        // check that passed value is valid
+        other.assert_invariant();
 
-    /*!
-    @brief get a value (explicit)
+        // invalidate payload
+        other.m_type = value_t::null;
+        other.m_value = {};
 
-    Explicit type conversion between the JSON value and a compatible value
-    which is [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible)
-    and [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible).
-    The value is converted by calling the @ref json_serializer<ValueType>
-    `from_json()` method.
+        assert_invariant();
+    }
 
-    The function is equivalent to executing
-    @code {.cpp}
-    ValueType ret;
-    JSONSerializer<ValueType>::from_json(*this, ret);
-    return ret;
-    @endcode
+    /*!
+    @brief copy assignment
 
-    This overloads is chosen if:
-    - @a ValueType is not @ref basic_json,
-    - @ref json_serializer<ValueType> has a `from_json()` method of the form
-      `void from_json(const basic_json&, ValueType&)`, and
-    - @ref json_serializer<ValueType> does not have a `from_json()` method of
-      the form `ValueType from_json(const basic_json&)`
+    Copy assignment operator. Copies a JSON value via the "copy and swap"
+    strategy: It is expressed in terms of the copy constructor, destructor,
+    and the swap() member function.
 
-    @tparam ValueTypeCV the provided value type
-    @tparam ValueType the returned value type
+    @param[in] other  value to copy from
 
-    @return copy of the JSON value, converted to @a ValueType
+    @complexity Linear.
 
-    @throw what @ref json_serializer<ValueType> `from_json()` method throws
+    @requirement This function helps `basic_json` satisfying the
+    [Container](http://en.cppreference.com/w/cpp/concept/Container)
+    requirements:
+    - The complexity is linear.
 
-    @liveexample{The example below shows several conversions from JSON values
-    to other types. There a few things to note: (1) Floating-point numbers can
-    be converted to integers\, (2) A JSON array can be converted to a standard
-    `std::vector<short>`\, (3) A JSON object can be converted to C++
-    associative containers such as `std::unordered_map<std::string\,
-    json>`.,get__ValueType_const}
+    @liveexample{The code below shows and example for the copy assignment. It
+    creates a copy of value `a` which is then swapped with `b`. Finally\, the
+    copy of `a` (which is the null value after the swap) is
+    destroyed.,basic_json__copyassignment}
 
-    @since version 2.1.0
+    @since version 1.0.0
     */
-    template <
-        typename ValueTypeCV,
-        typename ValueType = detail::uncvref_t<ValueTypeCV>,
-        detail::enable_if_t <
-            not std::is_same<basic_json_t, ValueType>::value and
-            detail::has_from_json<basic_json_t, ValueType>::value and
-            not detail::has_non_default_from_json<basic_json_t, ValueType>::value,
-            int > = 0 >
-    ValueType get() const noexcept(noexcept(
-                                       JSONSerializer<ValueType>::from_json(std::declval<const basic_json_t&>(), std::declval<ValueType&>())))
+    reference& operator=(basic_json other) noexcept (
+        std::is_nothrow_move_constructible<value_t>::value and
+        std::is_nothrow_move_assignable<value_t>::value and
+        std::is_nothrow_move_constructible<json_value>::value and
+        std::is_nothrow_move_assignable<json_value>::value
+    )
     {
-        // we cannot static_assert on ValueTypeCV being non-const, because
-        // there is support for get<const basic_json_t>(), which is why we
-        // still need the uncvref
-        static_assert(not std::is_reference<ValueTypeCV>::value,
-                      "get() cannot be used with reference types, you might want to use get_ref()");
-        static_assert(std::is_default_constructible<ValueType>::value,
-                      "types must be DefaultConstructible when used with get()");
+        // check that passed value is valid
+        other.assert_invariant();
 
-        ValueType ret;
-        JSONSerializer<ValueType>::from_json(*this, ret);
-        return ret;
+        using std::swap;
+        swap(m_type, other.m_type);
+        swap(m_value, other.m_value);
+
+        assert_invariant();
+        return *this;
     }
 
     /*!
-    @brief get a value (explicit); special case
-
-    Explicit type conversion between the JSON value and a compatible value
-    which is **not** [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible)
-    and **not** [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible).
-    The value is converted by calling the @ref json_serializer<ValueType>
-    `from_json()` method.
-
-    The function is equivalent to executing
-    @code {.cpp}
-    return JSONSerializer<ValueTypeCV>::from_json(*this);
-    @endcode
+    @brief destructor
 
-    This overloads is chosen if:
-    - @a ValueType is not @ref basic_json and
-    - @ref json_serializer<ValueType> has a `from_json()` method of the form
-      `ValueType from_json(const basic_json&)`
+    Destroys the JSON value and frees all allocated memory.
 
-    @note If @ref json_serializer<ValueType> has both overloads of
-    `from_json()`, this one is chosen.
+    @complexity Linear.
 
-    @tparam ValueTypeCV the provided value type
-    @tparam ValueType the returned value type
-
-    @return copy of the JSON value, converted to @a ValueType
-
-    @throw what @ref json_serializer<ValueType> `from_json()` method throws
+    @requirement This function helps `basic_json` satisfying the
+    [Container](http://en.cppreference.com/w/cpp/concept/Container)
+    requirements:
+    - The complexity is linear.
+    - All stored elements are destroyed and all memory is freed.
 
-    @since version 2.1.0
+    @since version 1.0.0
     */
-    template <
-        typename ValueTypeCV,
-        typename ValueType = detail::uncvref_t<ValueTypeCV>,
-        detail::enable_if_t<not std::is_same<basic_json_t, ValueType>::value and
-                            detail::has_non_default_from_json<basic_json_t,
-                                    ValueType>::value, int> = 0 >
-    ValueType get() const noexcept(noexcept(
-                                       JSONSerializer<ValueTypeCV>::from_json(std::declval<const basic_json_t&>())))
+    ~basic_json()
     {
-        static_assert(not std::is_reference<ValueTypeCV>::value,
-                      "get() cannot be used with reference types, you might want to use get_ref()");
-        return JSONSerializer<ValueTypeCV>::from_json(*this);
+        assert_invariant();
+
+        switch (m_type)
+        {
+            case value_t::object:
+            {
+                AllocatorType<object_t> alloc;
+                alloc.destroy(m_value.object);
+                alloc.deallocate(m_value.object, 1);
+                break;
+            }
+
+            case value_t::array:
+            {
+                AllocatorType<array_t> alloc;
+                alloc.destroy(m_value.array);
+                alloc.deallocate(m_value.array, 1);
+                break;
+            }
+
+            case value_t::string:
+            {
+                AllocatorType<string_t> alloc;
+                alloc.destroy(m_value.string);
+                alloc.deallocate(m_value.string, 1);
+                break;
+            }
+
+            default:
+            {
+                // all other types need no specific destructor
+                break;
+            }
+        }
     }
 
-    /*!
-    @brief get a pointer value (explicit)
+    /// @}
 
-    Explicit pointer access to the internally stored JSON value. No copies are
-    made.
+  public:
+    ///////////////////////
+    // object inspection //
+    ///////////////////////
 
-    @warning The pointer becomes invalid if the underlying JSON object
-    changes.
+    /// @name object inspection
+    /// Functions to inspect the type of a JSON value.
+    /// @{
 
-    @tparam PointerType pointer type; must be a pointer to @ref array_t, @ref
-    object_t, @ref string_t, @ref boolean_t, @ref number_integer_t,
-    @ref number_unsigned_t, or @ref number_float_t.
+    /*!
+    @brief serialization
 
-    @return pointer to the internally stored JSON value if the requested
-    pointer type @a PointerType fits to the JSON value; `nullptr` otherwise
+    Serialization function for JSON values. The function tries to mimic
+    Python's `json.dumps()` function, and currently supports its @a indent
+    parameter.
 
-    @complexity Constant.
+    @param[in] indent If indent is nonnegative, then array elements and object
+    members will be pretty-printed with that indent level. An indent level of
+    `0` will only insert newlines. `-1` (the default) selects the most compact
+    representation.
+    @param[in] indent_char The character to use for indentation if @a indent is
+    greater than `0`. The default is ` ` (space).
 
-    @liveexample{The example below shows how pointers to internal values of a
-    JSON value can be requested. Note that no type conversions are made and a
-    `nullptr` is returned if the value and the requested pointer type does not
-    match.,get__PointerType}
+    @return string containing the serialization of the JSON value
 
-    @sa @ref get_ptr() for explicit pointer-member access
+    @complexity Linear.
 
-    @since version 1.0.0
+    @liveexample{The following example shows the effect of different @a indent
+    parameters to the result of the serialization.,dump}
+
+    @see https://docs.python.org/2/library/json.html#json.dump
+
+    @since version 1.0.0; indentation character added in version 3.0.0
     */
-    template<typename PointerType, typename std::enable_if<
-                 std::is_pointer<PointerType>::value, int>::type = 0>
-    PointerType get() noexcept
+    string_t dump(const int indent = -1, const char indent_char = ' ') const
     {
-        // delegate the call to get_ptr
-        return get_ptr<PointerType>();
+        string_t result;
+        serializer s(detail::output_adapter_factory<char>::create(result), indent_char);
+
+        if (indent >= 0)
+        {
+            s.dump(*this, true, static_cast<unsigned int>(indent));
+        }
+        else
+        {
+            s.dump(*this, false, 0);
+        }
+
+        return result;
     }
 
     /*!
-    @brief get a pointer value (explicit)
-    @copydoc get()
+    @brief return the type of the JSON value (explicit)
+
+    Return the type of the JSON value as a value from the @ref value_t
+    enumeration.
+
+    @return the type of the JSON value
+
+    @complexity Constant.
+
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
+
+    @liveexample{The following code exemplifies `type()` for all JSON
+    types.,type}
+
+    @since version 1.0.0
     */
-    template<typename PointerType, typename std::enable_if<
-                 std::is_pointer<PointerType>::value, int>::type = 0>
-    constexpr const PointerType get() const noexcept
+    constexpr value_t type() const noexcept
     {
-        // delegate the call to get_ptr
-        return get_ptr<PointerType>();
+        return m_type;
     }
 
     /*!
-    @brief get a pointer value (implicit)
+    @brief return whether type is primitive
 
-    Implicit pointer access to the internally stored JSON value. No copies are
-    made.
+    This function returns true iff the JSON type is primitive (string, number,
+    boolean, or null).
 
-    @warning Writing data to the pointee of the result yields an undefined
-    state.
+    @return `true` if type is primitive (string, number, boolean, or null),
+    `false` otherwise.
 
-    @tparam PointerType pointer type; must be a pointer to @ref array_t, @ref
-    object_t, @ref string_t, @ref boolean_t, @ref number_integer_t,
-    @ref number_unsigned_t, or @ref number_float_t. Enforced by a static
-    assertion.
+    @complexity Constant.
 
-    @return pointer to the internally stored JSON value if the requested
-    pointer type @a PointerType fits to the JSON value; `nullptr` otherwise
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @complexity Constant.
+    @liveexample{The following code exemplifies `is_primitive()` for all JSON
+    types.,is_primitive}
 
-    @liveexample{The example below shows how pointers to internal values of a
-    JSON value can be requested. Note that no type conversions are made and a
-    `nullptr` is returned if the value and the requested pointer type does not
-    match.,get_ptr}
+    @sa @ref is_structured() -- returns whether JSON value is structured
+    @sa @ref is_null() -- returns whether JSON value is `null`
+    @sa @ref is_string() -- returns whether JSON value is a string
+    @sa @ref is_boolean() -- returns whether JSON value is a boolean
+    @sa @ref is_number() -- returns whether JSON value is a number
 
     @since version 1.0.0
     */
-    template<typename PointerType, typename std::enable_if<
-                 std::is_pointer<PointerType>::value, int>::type = 0>
-    PointerType get_ptr() noexcept
+    constexpr bool is_primitive() const noexcept
     {
-        // get the type of the PointerType (remove pointer and const)
-        using pointee_t = typename std::remove_const<typename
-                          std::remove_pointer<typename
-                          std::remove_const<PointerType>::type>::type>::type;
-        // make sure the type matches the allowed types
-        static_assert(
-            std::is_same<object_t, pointee_t>::value
-            or std::is_same<array_t, pointee_t>::value
-            or std::is_same<string_t, pointee_t>::value
-            or std::is_same<boolean_t, pointee_t>::value
-            or std::is_same<number_integer_t, pointee_t>::value
-            or std::is_same<number_unsigned_t, pointee_t>::value
-            or std::is_same<number_float_t, pointee_t>::value
-            , "incompatible pointer type");
-
-        // delegate the call to get_impl_ptr<>()
-        return get_impl_ptr(static_cast<PointerType>(nullptr));
+        return is_null() or is_string() or is_boolean() or is_number();
     }
 
     /*!
-    @brief get a pointer value (implicit)
-    @copydoc get_ptr()
+    @brief return whether type is structured
+
+    This function returns true iff the JSON type is structured (array or
+    object).
+
+    @return `true` if type is structured (array or object), `false` otherwise.
+
+    @complexity Constant.
+
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
+
+    @liveexample{The following code exemplifies `is_structured()` for all JSON
+    types.,is_structured}
+
+    @sa @ref is_primitive() -- returns whether value is primitive
+    @sa @ref is_array() -- returns whether value is an array
+    @sa @ref is_object() -- returns whether value is an object
+
+    @since version 1.0.0
     */
-    template<typename PointerType, typename std::enable_if<
-                 std::is_pointer<PointerType>::value and
-                 std::is_const<typename std::remove_pointer<PointerType>::type>::value, int>::type = 0>
-    constexpr const PointerType get_ptr() const noexcept
+    constexpr bool is_structured() const noexcept
     {
-        // get the type of the PointerType (remove pointer and const)
-        using pointee_t = typename std::remove_const<typename
-                          std::remove_pointer<typename
-                          std::remove_const<PointerType>::type>::type>::type;
-        // make sure the type matches the allowed types
-        static_assert(
-            std::is_same<object_t, pointee_t>::value
-            or std::is_same<array_t, pointee_t>::value
-            or std::is_same<string_t, pointee_t>::value
-            or std::is_same<boolean_t, pointee_t>::value
-            or std::is_same<number_integer_t, pointee_t>::value
-            or std::is_same<number_unsigned_t, pointee_t>::value
-            or std::is_same<number_float_t, pointee_t>::value
-            , "incompatible pointer type");
-
-        // delegate the call to get_impl_ptr<>() const
-        return get_impl_ptr(static_cast<const PointerType>(nullptr));
+        return is_array() or is_object();
     }
 
     /*!
-    @brief get a reference value (implicit)
+    @brief return whether value is null
 
-    Implicit reference access to the internally stored JSON value. No copies
-    are made.
+    This function returns true iff the JSON value is null.
 
-    @warning Writing data to the referee of the result yields an undefined
-    state.
-
-    @tparam ReferenceType reference type; must be a reference to @ref array_t,
-    @ref object_t, @ref string_t, @ref boolean_t, @ref number_integer_t, or
-    @ref number_float_t. Enforced by static assertion.
-
-    @return reference to the internally stored JSON value if the requested
-    reference type @a ReferenceType fits to the JSON value; throws
-    type_error.303 otherwise
-
-    @throw type_error.303 in case passed type @a ReferenceType is incompatible
-    with the stored JSON value; see example below
+    @return `true` if type is null, `false` otherwise.
 
     @complexity Constant.
 
-    @liveexample{The example shows several calls to `get_ref()`.,get_ref}
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @since version 1.1.0
+    @liveexample{The following code exemplifies `is_null()` for all JSON
+    types.,is_null}
+
+    @since version 1.0.0
     */
-    template<typename ReferenceType, typename std::enable_if<
-                 std::is_reference<ReferenceType>::value, int>::type = 0>
-    ReferenceType get_ref()
+    constexpr bool is_null() const noexcept
     {
-        // delegate call to get_ref_impl
-        return get_ref_impl<ReferenceType>(*this);
+        return m_type == value_t::null;
     }
 
     /*!
-    @brief get a reference value (implicit)
-    @copydoc get_ref()
+    @brief return whether value is a boolean
+
+    This function returns true iff the JSON value is a boolean.
+
+    @return `true` if type is boolean, `false` otherwise.
+
+    @complexity Constant.
+
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
+
+    @liveexample{The following code exemplifies `is_boolean()` for all JSON
+    types.,is_boolean}
+
+    @since version 1.0.0
     */
-    template<typename ReferenceType, typename std::enable_if<
-                 std::is_reference<ReferenceType>::value and
-                 std::is_const<typename std::remove_reference<ReferenceType>::type>::value, int>::type = 0>
-    ReferenceType get_ref() const
+    constexpr bool is_boolean() const noexcept
     {
-        // delegate call to get_ref_impl
-        return get_ref_impl<ReferenceType>(*this);
+        return m_type == value_t::boolean;
     }
 
     /*!
-    @brief get a value (implicit)
+    @brief return whether value is a number
 
-    Implicit type conversion between the JSON value and a compatible value.
-    The call is realized by calling @ref get() const.
+    This function returns true iff the JSON value is a number. This includes
+    both integer and floating-point values.
 
-    @tparam ValueType non-pointer type compatible to the JSON value, for
-    instance `int` for JSON integer numbers, `bool` for JSON booleans, or
-    `std::vector` types for JSON arrays. The character type of @ref string_t
-    as well as an initializer list of this type is excluded to avoid
-    ambiguities as these types implicitly convert to `std::string`.
+    @return `true` if type is number (regardless whether integer, unsigned
+    integer or floating-type), `false` otherwise.
 
-    @return copy of the JSON value, converted to type @a ValueType
+    @complexity Constant.
 
-    @throw type_error.302 in case passed type @a ValueType is incompatible
-    to the JSON value type (e.g., the JSON value is of type boolean, but a
-    string is requested); see example below
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @complexity Linear in the size of the JSON value.
+    @liveexample{The following code exemplifies `is_number()` for all JSON
+    types.,is_number}
 
-    @liveexample{The example below shows several conversions from JSON values
-    to other types. There a few things to note: (1) Floating-point numbers can
-    be converted to integers\, (2) A JSON array can be converted to a standard
-    `std::vector<short>`\, (3) A JSON object can be converted to C++
-    associative containers such as `std::unordered_map<std::string\,
-    json>`.,operator__ValueType}
+    @sa @ref is_number_integer() -- check if value is an integer or unsigned
+    integer number
+    @sa @ref is_number_unsigned() -- check if value is an unsigned integer
+    number
+    @sa @ref is_number_float() -- check if value is a floating-point number
 
     @since version 1.0.0
     */
-    template < typename ValueType, typename std::enable_if <
-                   not std::is_pointer<ValueType>::value and
-                   not std::is_same<ValueType, typename string_t::value_type>::value
-#ifndef _MSC_VER  // fix for issue #167 operator<< ambiguity under VS2015
-                   and not std::is_same<ValueType, std::initializer_list<typename string_t::value_type>>::value
-#endif
-#if (defined(__cplusplus) && __cplusplus >= 201703L) || (defined(_MSC_VER) && _MSC_VER >1900 && defined(_HAS_CXX17) && _HAS_CXX17 == 1) // fix for issue #464
-                   and not std::is_same<ValueType, typename std::string_view>::value
-#endif
-                   , int >::type = 0 >
-    operator ValueType() const
+    constexpr bool is_number() const noexcept
     {
-        // delegate the call to get<>() const
-        return get<ValueType>();
+        return is_number_integer() or is_number_float();
     }
 
-    /// @}
+    /*!
+    @brief return whether value is an integer number
 
+    This function returns true iff the JSON value is an integer or unsigned
+    integer number. This excludes floating-point values.
 
-    ////////////////////
-    // element access //
-    ////////////////////
+    @return `true` if type is an integer or unsigned integer number, `false`
+    otherwise.
 
-    /// @name element access
-    /// Access to the JSON value.
-    /// @{
+    @complexity Constant.
 
-    /*!
-    @brief access specified array element with bounds checking
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    Returns a reference to the element at specified location @a idx, with
-    bounds checking.
+    @liveexample{The following code exemplifies `is_number_integer()` for all
+    JSON types.,is_number_integer}
 
-    @param[in] idx  index of the element to access
+    @sa @ref is_number() -- check if value is a number
+    @sa @ref is_number_unsigned() -- check if value is an unsigned integer
+    number
+    @sa @ref is_number_float() -- check if value is a floating-point number
 
-    @return reference to the element at index @a idx
+    @since version 1.0.0
+    */
+    constexpr bool is_number_integer() const noexcept
+    {
+        return m_type == value_t::number_integer or m_type == value_t::number_unsigned;
+    }
 
-    @throw type_error.304 if the JSON value is not an array; in this case,
-    calling `at` with an index makes no sense. See example below.
-    @throw out_of_range.401 if the index @a idx is out of range of the array;
-    that is, `idx >= size()`. See example below.
+    /*!
+    @brief return whether value is an unsigned integer number
 
-    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
-    changes in the JSON value.
+    This function returns true iff the JSON value is an unsigned integer
+    number. This excludes floating-point and (signed) integer values.
+
+    @return `true` if type is an unsigned integer number, `false` otherwise.
 
     @complexity Constant.
 
-    @since version 1.0.0
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @liveexample{The example below shows how array elements can be read and
-    written using `at()`. It also demonstrates the different exceptions that
-    can be thrown.,at__size_type}
+    @liveexample{The following code exemplifies `is_number_unsigned()` for all
+    JSON types.,is_number_unsigned}
+
+    @sa @ref is_number() -- check if value is a number
+    @sa @ref is_number_integer() -- check if value is an integer or unsigned
+    integer number
+    @sa @ref is_number_float() -- check if value is a floating-point number
+
+    @since version 2.0.0
     */
-    reference at(size_type idx)
+    constexpr bool is_number_unsigned() const noexcept
     {
-        // at only works for arrays
-        if (is_array())
-        {
-            JSON_TRY
-            {
-                return m_value.array->at(idx);
-            }
-            JSON_CATCH (std::out_of_range&)
-            {
-                // create better exception explanation
-                JSON_THROW(out_of_range::create(401, "array index " + std::to_string(idx) + " is out of range"));
-            }
-        }
-        else
-        {
-            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
-        }
+        return m_type == value_t::number_unsigned;
     }
 
     /*!
-    @brief access specified array element with bounds checking
+    @brief return whether value is a floating-point number
 
-    Returns a const reference to the element at specified location @a idx,
-    with bounds checking.
+    This function returns true iff the JSON value is a floating-point number.
+    This excludes integer and unsigned integer values.
 
-    @param[in] idx  index of the element to access
+    @return `true` if type is a floating-point number, `false` otherwise.
 
-    @return const reference to the element at index @a idx
+    @complexity Constant.
 
-    @throw type_error.304 if the JSON value is not an array; in this case,
-    calling `at` with an index makes no sense. See example below.
-    @throw out_of_range.401 if the index @a idx is out of range of the array;
-    that is, `idx >= size()`. See example below.
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
-    changes in the JSON value.
+    @liveexample{The following code exemplifies `is_number_float()` for all
+    JSON types.,is_number_float}
 
-    @complexity Constant.
+    @sa @ref is_number() -- check if value is number
+    @sa @ref is_number_integer() -- check if value is an integer number
+    @sa @ref is_number_unsigned() -- check if value is an unsigned integer
+    number
 
     @since version 1.0.0
-
-    @liveexample{The example below shows how array elements can be read using
-    `at()`. It also demonstrates the different exceptions that can be thrown.,
-    at__size_type_const}
     */
-    const_reference at(size_type idx) const
+    constexpr bool is_number_float() const noexcept
     {
-        // at only works for arrays
-        if (is_array())
-        {
-            JSON_TRY
-            {
-                return m_value.array->at(idx);
-            }
-            JSON_CATCH (std::out_of_range&)
-            {
-                // create better exception explanation
-                JSON_THROW(out_of_range::create(401, "array index " + std::to_string(idx) + " is out of range"));
-            }
-        }
-        else
-        {
-            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
-        }
+        return m_type == value_t::number_float;
     }
 
     /*!
-    @brief access specified object element with bounds checking
-
-    Returns a reference to the element at with specified key @a key, with
-    bounds checking.
-
-    @param[in] key  key of the element to access
+    @brief return whether value is an object
 
-    @return reference to the element at key @a key
+    This function returns true iff the JSON value is an object.
 
-    @throw type_error.304 if the JSON value is not an object; in this case,
-    calling `at` with a key makes no sense. See example below.
-    @throw out_of_range.403 if the key @a key is is not stored in the object;
-    that is, `find(key) == end()`. See example below.
+    @return `true` if type is object, `false` otherwise.
 
-    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
-    changes in the JSON value.
+    @complexity Constant.
 
-    @complexity Logarithmic in the size of the container.
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @sa @ref operator[](const typename object_t::key_type&) for unchecked
-    access by reference
-    @sa @ref value() for access by value with a default value
+    @liveexample{The following code exemplifies `is_object()` for all JSON
+    types.,is_object}
 
     @since version 1.0.0
-
-    @liveexample{The example below shows how object elements can be read and
-    written using `at()`. It also demonstrates the different exceptions that
-    can be thrown.,at__object_t_key_type}
     */
-    reference at(const typename object_t::key_type& key)
+    constexpr bool is_object() const noexcept
     {
-        // at only works for objects
-        if (is_object())
-        {
-            JSON_TRY
-            {
-                return m_value.object->at(key);
-            }
-            JSON_CATCH (std::out_of_range&)
-            {
-                // create better exception explanation
-                JSON_THROW(out_of_range::create(403, "key '" + key + "' not found"));
-            }
-        }
-        else
-        {
-            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
-        }
+        return m_type == value_t::object;
     }
 
     /*!
-    @brief access specified object element with bounds checking
-
-    Returns a const reference to the element at with specified key @a key,
-    with bounds checking.
-
-    @param[in] key  key of the element to access
+    @brief return whether value is an array
 
-    @return const reference to the element at key @a key
+    This function returns true iff the JSON value is an array.
 
-    @throw type_error.304 if the JSON value is not an object; in this case,
-    calling `at` with a key makes no sense. See example below.
-    @throw out_of_range.403 if the key @a key is is not stored in the object;
-    that is, `find(key) == end()`. See example below.
+    @return `true` if type is array, `false` otherwise.
 
-    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
-    changes in the JSON value.
+    @complexity Constant.
 
-    @complexity Logarithmic in the size of the container.
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @sa @ref operator[](const typename object_t::key_type&) for unchecked
-    access by reference
-    @sa @ref value() for access by value with a default value
+    @liveexample{The following code exemplifies `is_array()` for all JSON
+    types.,is_array}
 
     @since version 1.0.0
-
-    @liveexample{The example below shows how object elements can be read using
-    `at()`. It also demonstrates the different exceptions that can be thrown.,
-    at__object_t_key_type_const}
     */
-    const_reference at(const typename object_t::key_type& key) const
+    constexpr bool is_array() const noexcept
     {
-        // at only works for objects
-        if (is_object())
-        {
-            JSON_TRY
-            {
-                return m_value.object->at(key);
-            }
-            JSON_CATCH (std::out_of_range&)
-            {
-                // create better exception explanation
-                JSON_THROW(out_of_range::create(403, "key '" + key + "' not found"));
-            }
-        }
-        else
-        {
-            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
-        }
+        return m_type == value_t::array;
     }
 
     /*!
-    @brief access specified array element
-
-    Returns a reference to the element at specified location @a idx.
-
-    @note If @a idx is beyond the range of the array (i.e., `idx >= size()`),
-    then the array is silently filled up with `null` values to make `idx` a
-    valid reference to the last stored element.
+    @brief return whether value is a string
 
-    @param[in] idx  index of the element to access
+    This function returns true iff the JSON value is a string.
 
-    @return reference to the element at index @a idx
+    @return `true` if type is string, `false` otherwise.
 
-    @throw type_error.305 if the JSON value is not an array or null; in that
-    cases, using the [] operator with an index makes no sense.
+    @complexity Constant.
 
-    @complexity Constant if @a idx is in the range of the array. Otherwise
-    linear in `idx - size()`.
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @liveexample{The example below shows how array elements can be read and
-    written using `[]` operator. Note the addition of `null`
-    values.,operatorarray__size_type}
+    @liveexample{The following code exemplifies `is_string()` for all JSON
+    types.,is_string}
 
     @since version 1.0.0
     */
-    reference operator[](size_type idx)
+    constexpr bool is_string() const noexcept
     {
-        // implicitly convert null value to an empty array
-        if (is_null())
-        {
-            m_type = value_t::array;
-            m_value.array = create<array_t>();
-            assert_invariant();
-        }
-
-        // operator[] only works for arrays
-        if (is_array())
-        {
-            // fill up array with null values if given idx is outside range
-            if (idx >= m_value.array->size())
-            {
-                m_value.array->insert(m_value.array->end(),
-                                      idx - m_value.array->size() + 1,
-                                      basic_json());
-            }
-
-            return m_value.array->operator[](idx);
-        }
-
-        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+        return m_type == value_t::string;
     }
 
     /*!
-    @brief access specified array element
-
-    Returns a const reference to the element at specified location @a idx.
+    @brief return whether value is discarded
 
-    @param[in] idx  index of the element to access
+    This function returns true iff the JSON value was discarded during parsing
+    with a callback function (see @ref parser_callback_t).
 
-    @return const reference to the element at index @a idx
+    @note This function will always be `false` for JSON values after parsing.
+    That is, discarded values can only occur during parsing, but will be
+    removed when inside a structured value or replaced by null in other cases.
 
-    @throw type_error.305 if the JSON value is not an array; in that cases,
-    using the [] operator with an index makes no sense.
+    @return `true` if type is discarded, `false` otherwise.
 
     @complexity Constant.
 
-    @liveexample{The example below shows how array elements can be read using
-    the `[]` operator.,operatorarray__size_type_const}
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
+
+    @liveexample{The following code exemplifies `is_discarded()` for all JSON
+    types.,is_discarded}
 
     @since version 1.0.0
     */
-    const_reference operator[](size_type idx) const
+    constexpr bool is_discarded() const noexcept
     {
-        // const operator[] only works for arrays
-        if (is_array())
-        {
-            return m_value.array->operator[](idx);
-        }
-
-        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+        return m_type == value_t::discarded;
     }
 
     /*!
-    @brief access specified object element
+    @brief return the type of the JSON value (implicit)
 
-    Returns a reference to the element at with specified key @a key.
+    Implicitly return the type of the JSON value as a value from the @ref
+    value_t enumeration.
 
-    @note If @a key is not found in the object, then it is silently added to
-    the object and filled with a `null` value to make `key` a valid reference.
-    In case the value was `null` before, it is converted to an object.
+    @return the type of the JSON value
 
-    @param[in] key  key of the element to access
+    @complexity Constant.
 
-    @return reference to the element at key @a key
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
 
-    @throw type_error.305 if the JSON value is not an object or null; in that
-    cases, using the [] operator with a key makes no sense.
+    @liveexample{The following code exemplifies the @ref value_t operator for
+    all JSON types.,operator__value_t}
 
-    @complexity Logarithmic in the size of the container.
+    @since version 1.0.0
+    */
+    constexpr operator value_t() const noexcept
+    {
+        return m_type;
+    }
 
-    @liveexample{The example below shows how object elements can be read and
-    written using the `[]` operator.,operatorarray__key_type}
+    /// @}
 
-    @sa @ref at(const typename object_t::key_type&) for access by reference
-    with range checking
-    @sa @ref value() for access by value with a default value
+  private:
+    //////////////////
+    // value access //
+    //////////////////
 
-    @since version 1.0.0
-    */
-    reference operator[](const typename object_t::key_type& key)
+    /// get a boolean (explicit)
+    boolean_t get_impl(boolean_t* /*unused*/) const
     {
-        // implicitly convert null value to an empty object
-        if (is_null())
+        if (is_boolean())
         {
-            m_type = value_t::object;
-            m_value.object = create<object_t>();
-            assert_invariant();
+            return m_value.boolean;
         }
 
-        // operator[] only works for objects
-        if (is_object())
-        {
-            return m_value.object->operator[](key);
-        }
+        JSON_THROW(type_error::create(302, "type must be boolean, but is " + type_name()));
+    }
 
-        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+    /// get a pointer to the value (object)
+    object_t* get_impl_ptr(object_t* /*unused*/) noexcept
+    {
+        return is_object() ? m_value.object : nullptr;
     }
 
-    /*!
-    @brief read-only access specified object element
+    /// get a pointer to the value (object)
+    constexpr const object_t* get_impl_ptr(const object_t* /*unused*/) const noexcept
+    {
+        return is_object() ? m_value.object : nullptr;
+    }
 
-    Returns a const reference to the element at with specified key @a key. No
-    bounds checking is performed.
+    /// get a pointer to the value (array)
+    array_t* get_impl_ptr(array_t* /*unused*/) noexcept
+    {
+        return is_array() ? m_value.array : nullptr;
+    }
 
-    @warning If the element with key @a key does not exist, the behavior is
-    undefined.
+    /// get a pointer to the value (array)
+    constexpr const array_t* get_impl_ptr(const array_t* /*unused*/) const noexcept
+    {
+        return is_array() ? m_value.array : nullptr;
+    }
 
-    @param[in] key  key of the element to access
+    /// get a pointer to the value (string)
+    string_t* get_impl_ptr(string_t* /*unused*/) noexcept
+    {
+        return is_string() ? m_value.string : nullptr;
+    }
 
-    @return const reference to the element at key @a key
+    /// get a pointer to the value (string)
+    constexpr const string_t* get_impl_ptr(const string_t* /*unused*/) const noexcept
+    {
+        return is_string() ? m_value.string : nullptr;
+    }
 
-    @pre The element with key @a key must exist. **This precondition is
-         enforced with an assertion.**
+    /// get a pointer to the value (boolean)
+    boolean_t* get_impl_ptr(boolean_t* /*unused*/) noexcept
+    {
+        return is_boolean() ? &m_value.boolean : nullptr;
+    }
 
-    @throw type_error.305 if the JSON value is not an object; in that cases,
-    using the [] operator with a key makes no sense.
+    /// get a pointer to the value (boolean)
+    constexpr const boolean_t* get_impl_ptr(const boolean_t* /*unused*/) const noexcept
+    {
+        return is_boolean() ? &m_value.boolean : nullptr;
+    }
 
-    @complexity Logarithmic in the size of the container.
-
-    @liveexample{The example below shows how object elements can be read using
-    the `[]` operator.,operatorarray__key_type_const}
-
-    @sa @ref at(const typename object_t::key_type&) for access by reference
-    with range checking
-    @sa @ref value() for access by value with a default value
-
-    @since version 1.0.0
-    */
-    const_reference operator[](const typename object_t::key_type& key) const
+    /// get a pointer to the value (integer number)
+    number_integer_t* get_impl_ptr(number_integer_t* /*unused*/) noexcept
     {
-        // const operator[] only works for objects
-        if (is_object())
-        {
-            assert(m_value.object->find(key) != m_value.object->end());
-            return m_value.object->find(key)->second;
-        }
-
-        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+        return is_number_integer() ? &m_value.number_integer : nullptr;
     }
 
-    /*!
-    @brief access specified object element
-
-    Returns a reference to the element at with specified key @a key.
+    /// get a pointer to the value (integer number)
+    constexpr const number_integer_t* get_impl_ptr(const number_integer_t* /*unused*/) const noexcept
+    {
+        return is_number_integer() ? &m_value.number_integer : nullptr;
+    }
 
-    @note If @a key is not found in the object, then it is silently added to
-    the object and filled with a `null` value to make `key` a valid reference.
-    In case the value was `null` before, it is converted to an object.
+    /// get a pointer to the value (unsigned number)
+    number_unsigned_t* get_impl_ptr(number_unsigned_t* /*unused*/) noexcept
+    {
+        return is_number_unsigned() ? &m_value.number_unsigned : nullptr;
+    }
 
-    @param[in] key  key of the element to access
+    /// get a pointer to the value (unsigned number)
+    constexpr const number_unsigned_t* get_impl_ptr(const number_unsigned_t* /*unused*/) const noexcept
+    {
+        return is_number_unsigned() ? &m_value.number_unsigned : nullptr;
+    }
 
-    @return reference to the element at key @a key
+    /// get a pointer to the value (floating-point number)
+    number_float_t* get_impl_ptr(number_float_t* /*unused*/) noexcept
+    {
+        return is_number_float() ? &m_value.number_float : nullptr;
+    }
 
-    @throw type_error.305 if the JSON value is not an object or null; in that
-    cases, using the [] operator with a key makes no sense.
+    /// get a pointer to the value (floating-point number)
+    constexpr const number_float_t* get_impl_ptr(const number_float_t* /*unused*/) const noexcept
+    {
+        return is_number_float() ? &m_value.number_float : nullptr;
+    }
 
-    @complexity Logarithmic in the size of the container.
+    /*!
+    @brief helper function to implement get_ref()
 
-    @liveexample{The example below shows how object elements can be read and
-    written using the `[]` operator.,operatorarray__key_type}
+    This function helps to implement get_ref() without code duplication for
+    const and non-const overloads
 
-    @sa @ref at(const typename object_t::key_type&) for access by reference
-    with range checking
-    @sa @ref value() for access by value with a default value
+    @tparam ThisType will be deduced as `basic_json` or `const basic_json`
 
-    @since version 1.1.0
+    @throw type_error.303 if ReferenceType does not match underlying value
+    type of the current JSON
     */
-    template<typename T>
-    reference operator[](T* key)
+    template<typename ReferenceType, typename ThisType>
+    static ReferenceType get_ref_impl(ThisType& obj)
     {
-        // implicitly convert null to object
-        if (is_null())
-        {
-            m_type = value_t::object;
-            m_value = value_t::object;
-            assert_invariant();
-        }
+        // helper type
+        using PointerType = typename std::add_pointer<ReferenceType>::type;
 
-        // at only works for objects
-        if (is_object())
+        // delegate the call to get_ptr<>()
+        auto ptr = obj.template get_ptr<PointerType>();
+
+        if (ptr != nullptr)
         {
-            return m_value.object->operator[](key);
+            return *ptr;
         }
 
-        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+        JSON_THROW(type_error::create(303, "incompatible ReferenceType for get_ref, actual type is " + obj.type_name()));
     }
 
+  public:
+    /// @name value access
+    /// Direct access to the stored value of a JSON value.
+    /// @{
+
     /*!
-    @brief read-only access specified object element
+    @brief get special-case overload
 
-    Returns a const reference to the element at with specified key @a key. No
-    bounds checking is performed.
+    This overloads avoids a lot of template boilerplate, it can be seen as the
+    identity method
 
-    @warning If the element with key @a key does not exist, the behavior is
-    undefined.
+    @tparam BasicJsonType == @ref basic_json
 
-    @param[in] key  key of the element to access
+    @return a copy of *this
 
-    @return const reference to the element at key @a key
+    @complexity Constant.
 
-    @pre The element with key @a key must exist. **This precondition is
-         enforced with an assertion.**
+    @since version 2.1.0
+    */
+    template <
+        typename BasicJsonType,
+        detail::enable_if_t<std::is_same<typename std::remove_const<BasicJsonType>::type,
+                                         basic_json_t>::value,
+                            int> = 0 >
+    basic_json get() const
+    {
+        return *this;
+    }
 
-    @throw type_error.305 if the JSON value is not an object; in that cases,
-    using the [] operator with a key makes no sense.
+    /*!
+    @brief get a value (explicit)
 
-    @complexity Logarithmic in the size of the container.
+    Explicit type conversion between the JSON value and a compatible value
+    which is [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible)
+    and [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible).
+    The value is converted by calling the @ref json_serializer<ValueType>
+    `from_json()` method.
 
-    @liveexample{The example below shows how object elements can be read using
-    the `[]` operator.,operatorarray__key_type_const}
+    The function is equivalent to executing
+    @code {.cpp}
+    ValueType ret;
+    JSONSerializer<ValueType>::from_json(*this, ret);
+    return ret;
+    @endcode
 
-    @sa @ref at(const typename object_t::key_type&) for access by reference
-    with range checking
-    @sa @ref value() for access by value with a default value
+    This overloads is chosen if:
+    - @a ValueType is not @ref basic_json,
+    - @ref json_serializer<ValueType> has a `from_json()` method of the form
+      `void from_json(const basic_json&, ValueType&)`, and
+    - @ref json_serializer<ValueType> does not have a `from_json()` method of
+      the form `ValueType from_json(const basic_json&)`
 
-    @since version 1.1.0
+    @tparam ValueTypeCV the provided value type
+    @tparam ValueType the returned value type
+
+    @return copy of the JSON value, converted to @a ValueType
+
+    @throw what @ref json_serializer<ValueType> `from_json()` method throws
+
+    @liveexample{The example below shows several conversions from JSON values
+    to other types. There a few things to note: (1) Floating-point numbers can
+    be converted to integers\, (2) A JSON array can be converted to a standard
+    `std::vector<short>`\, (3) A JSON object can be converted to C++
+    associative containers such as `std::unordered_map<std::string\,
+    json>`.,get__ValueType_const}
+
+    @since version 2.1.0
     */
-    template<typename T>
-    const_reference operator[](T* key) const
+    template <
+        typename ValueTypeCV,
+        typename ValueType = detail::uncvref_t<ValueTypeCV>,
+        detail::enable_if_t <
+            not std::is_same<basic_json_t, ValueType>::value and
+            detail::has_from_json<basic_json_t, ValueType>::value and
+            not detail::has_non_default_from_json<basic_json_t, ValueType>::value,
+            int > = 0 >
+    ValueType get() const noexcept(noexcept(
+                                       JSONSerializer<ValueType>::from_json(std::declval<const basic_json_t&>(), std::declval<ValueType&>())))
     {
-        // at only works for objects
-        if (is_object())
-        {
-            assert(m_value.object->find(key) != m_value.object->end());
-            return m_value.object->find(key)->second;
-        }
+        // we cannot static_assert on ValueTypeCV being non-const, because
+        // there is support for get<const basic_json_t>(), which is why we
+        // still need the uncvref
+        static_assert(not std::is_reference<ValueTypeCV>::value,
+                      "get() cannot be used with reference types, you might want to use get_ref()");
+        static_assert(std::is_default_constructible<ValueType>::value,
+                      "types must be DefaultConstructible when used with get()");
 
-        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+        ValueType ret;
+        JSONSerializer<ValueType>::from_json(*this, ret);
+        return ret;
     }
 
     /*!
-    @brief access specified object element with default value
+    @brief get a value (explicit); special case
 
-    Returns either a copy of an object's element at the specified key @a key
-    or a given default value if no element with key @a key exists.
+    Explicit type conversion between the JSON value and a compatible value
+    which is **not** [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible)
+    and **not** [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible).
+    The value is converted by calling the @ref json_serializer<ValueType>
+    `from_json()` method.
 
-    The function is basically equivalent to executing
+    The function is equivalent to executing
     @code {.cpp}
-    try {
-        return at(key);
-    } catch(out_of_range) {
-        return default_value;
-    }
+    return JSONSerializer<ValueTypeCV>::from_json(*this);
     @endcode
 
-    @note Unlike @ref at(const typename object_t::key_type&), this function
-    does not throw if the given key @a key was not found.
-
-    @note Unlike @ref operator[](const typename object_t::key_type& key), this
-    function does not implicitly add an element to the position defined by @a
-    key. This function is furthermore also applicable to const objects.
-
-    @param[in] key  key of the element to access
-    @param[in] default_value  the value to return if @a key is not found
-
-    @tparam ValueType type compatible to JSON values, for instance `int` for
-    JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
-    JSON arrays. Note the type of the expected value at @a key and the default
-    value @a default_value must be compatible.
-
-    @return copy of the element at key @a key or @a default_value if @a key
-    is not found
+    This overloads is chosen if:
+    - @a ValueType is not @ref basic_json and
+    - @ref json_serializer<ValueType> has a `from_json()` method of the form
+      `ValueType from_json(const basic_json&)`
 
-    @throw type_error.306 if the JSON value is not an objec; in that cases,
-    using `value()` with a key makes no sense.
+    @note If @ref json_serializer<ValueType> has both overloads of
+    `from_json()`, this one is chosen.
 
-    @complexity Logarithmic in the size of the container.
+    @tparam ValueTypeCV the provided value type
+    @tparam ValueType the returned value type
 
-    @liveexample{The example below shows how object elements can be queried
-    with a default value.,basic_json__value}
+    @return copy of the JSON value, converted to @a ValueType
 
-    @sa @ref at(const typename object_t::key_type&) for access by reference
-    with range checking
-    @sa @ref operator[](const typename object_t::key_type&) for unchecked
-    access by reference
+    @throw what @ref json_serializer<ValueType> `from_json()` method throws
 
-    @since version 1.0.0
+    @since version 2.1.0
     */
-    template<class ValueType, typename std::enable_if<
-                 std::is_convertible<basic_json_t, ValueType>::value, int>::type = 0>
-    ValueType value(const typename object_t::key_type& key, ValueType default_value) const
-    {
-        // at only works for objects
-        if (is_object())
-        {
-            // if key is found, return value and given default value otherwise
-            const auto it = find(key);
-            if (it != end())
-            {
-                return *it;
-            }
-
-            return default_value;
-        }
-        else
-        {
-            JSON_THROW(type_error::create(306, "cannot use value() with " + type_name()));
-        }
-    }
-
-    /*!
-    @brief overload for a default value of type const char*
-    @copydoc basic_json::value(const typename object_t::key_type&, ValueType) const
-    */
-    string_t value(const typename object_t::key_type& key, const char* default_value) const
+    template <
+        typename ValueTypeCV,
+        typename ValueType = detail::uncvref_t<ValueTypeCV>,
+        detail::enable_if_t<not std::is_same<basic_json_t, ValueType>::value and
+                            detail::has_non_default_from_json<basic_json_t,
+                                    ValueType>::value, int> = 0 >
+    ValueType get() const noexcept(noexcept(
+                                       JSONSerializer<ValueTypeCV>::from_json(std::declval<const basic_json_t&>())))
     {
-        return value(key, string_t(default_value));
+        static_assert(not std::is_reference<ValueTypeCV>::value,
+                      "get() cannot be used with reference types, you might want to use get_ref()");
+        return JSONSerializer<ValueTypeCV>::from_json(*this);
     }
 
     /*!
-    @brief access specified object element via JSON Pointer with default value
-
-    Returns either a copy of an object's element at the specified key @a key
-    or a given default value if no element with key @a key exists.
-
-    The function is basically equivalent to executing
-    @code {.cpp}
-    try {
-        return at(ptr);
-    } catch(out_of_range) {
-        return default_value;
-    }
-    @endcode
-
-    @note Unlike @ref at(const json_pointer&), this function does not throw
-    if the given key @a key was not found.
+    @brief get a pointer value (explicit)
 
-    @param[in] ptr  a JSON pointer to the element to access
-    @param[in] default_value  the value to return if @a ptr found no value
+    Explicit pointer access to the internally stored JSON value. No copies are
+    made.
 
-    @tparam ValueType type compatible to JSON values, for instance `int` for
-    JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
-    JSON arrays. Note the type of the expected value at @a key and the default
-    value @a default_value must be compatible.
+    @warning The pointer becomes invalid if the underlying JSON object
+    changes.
 
-    @return copy of the element at key @a key or @a default_value if @a key
-    is not found
+    @tparam PointerType pointer type; must be a pointer to @ref array_t, @ref
+    object_t, @ref string_t, @ref boolean_t, @ref number_integer_t,
+    @ref number_unsigned_t, or @ref number_float_t.
 
-    @throw type_error.306 if the JSON value is not an objec; in that cases,
-    using `value()` with a key makes no sense.
+    @return pointer to the internally stored JSON value if the requested
+    pointer type @a PointerType fits to the JSON value; `nullptr` otherwise
 
-    @complexity Logarithmic in the size of the container.
+    @complexity Constant.
 
-    @liveexample{The example below shows how object elements can be queried
-    with a default value.,basic_json__value_ptr}
+    @liveexample{The example below shows how pointers to internal values of a
+    JSON value can be requested. Note that no type conversions are made and a
+    `nullptr` is returned if the value and the requested pointer type does not
+    match.,get__PointerType}
 
-    @sa @ref operator[](const json_pointer&) for unchecked access by reference
+    @sa @ref get_ptr() for explicit pointer-member access
 
-    @since version 2.0.2
+    @since version 1.0.0
     */
-    template<class ValueType, typename std::enable_if<
-                 std::is_convertible<basic_json_t, ValueType>::value, int>::type = 0>
-    ValueType value(const json_pointer& ptr, ValueType default_value) const
+    template<typename PointerType, typename std::enable_if<
+                 std::is_pointer<PointerType>::value, int>::type = 0>
+    PointerType get() noexcept
     {
-        // at only works for objects
-        if (is_object())
-        {
-            // if pointer resolves a value, return it or use default value
-            JSON_TRY
-            {
-                return ptr.get_checked(this);
-            }
-            JSON_CATCH (out_of_range&)
-            {
-                return default_value;
-            }
-        }
-
-        JSON_THROW(type_error::create(306, "cannot use value() with " + type_name()));
+        // delegate the call to get_ptr
+        return get_ptr<PointerType>();
     }
 
     /*!
-    @brief overload for a default value of type const char*
-    @copydoc basic_json::value(const json_pointer&, ValueType) const
+    @brief get a pointer value (explicit)
+    @copydoc get()
     */
-    string_t value(const json_pointer& ptr, const char* default_value) const
+    template<typename PointerType, typename std::enable_if<
+                 std::is_pointer<PointerType>::value, int>::type = 0>
+    constexpr const PointerType get() const noexcept
     {
-        return value(ptr, string_t(default_value));
+        // delegate the call to get_ptr
+        return get_ptr<PointerType>();
     }
 
     /*!
-    @brief access the first element
-
-    Returns a reference to the first element in the container. For a JSON
-    container `c`, the expression `c.front()` is equivalent to `*c.begin()`.
+    @brief get a pointer value (implicit)
 
-    @return In case of a structured type (array or object), a reference to the
-    first element is returned. In case of number, string, or boolean values, a
-    reference to the value is returned.
+    Implicit pointer access to the internally stored JSON value. No copies are
+    made.
 
-    @complexity Constant.
+    @warning Writing data to the pointee of the result yields an undefined
+    state.
 
-    @pre The JSON value must not be `null` (would throw `std::out_of_range`)
-    or an empty array or object (undefined behavior, **guarded by
-    assertions**).
-    @post The JSON value remains unchanged.
+    @tparam PointerType pointer type; must be a pointer to @ref array_t, @ref
+    object_t, @ref string_t, @ref boolean_t, @ref number_integer_t,
+    @ref number_unsigned_t, or @ref number_float_t. Enforced by a static
+    assertion.
 
-    @throw invalid_iterator.214 when called on `null` value
+    @return pointer to the internally stored JSON value if the requested
+    pointer type @a PointerType fits to the JSON value; `nullptr` otherwise
 
-    @liveexample{The following code shows an example for `front()`.,front}
+    @complexity Constant.
 
-    @sa @ref back() -- access the last element
+    @liveexample{The example below shows how pointers to internal values of a
+    JSON value can be requested. Note that no type conversions are made and a
+    `nullptr` is returned if the value and the requested pointer type does not
+    match.,get_ptr}
 
     @since version 1.0.0
     */
-    reference front()
+    template<typename PointerType, typename std::enable_if<
+                 std::is_pointer<PointerType>::value, int>::type = 0>
+    PointerType get_ptr() noexcept
     {
-        return *begin();
+        // get the type of the PointerType (remove pointer and const)
+        using pointee_t = typename std::remove_const<typename
+                          std::remove_pointer<typename
+                          std::remove_const<PointerType>::type>::type>::type;
+        // make sure the type matches the allowed types
+        static_assert(
+            std::is_same<object_t, pointee_t>::value
+            or std::is_same<array_t, pointee_t>::value
+            or std::is_same<string_t, pointee_t>::value
+            or std::is_same<boolean_t, pointee_t>::value
+            or std::is_same<number_integer_t, pointee_t>::value
+            or std::is_same<number_unsigned_t, pointee_t>::value
+            or std::is_same<number_float_t, pointee_t>::value
+            , "incompatible pointer type");
+
+        // delegate the call to get_impl_ptr<>()
+        return get_impl_ptr(static_cast<PointerType>(nullptr));
     }
 
     /*!
-    @copydoc basic_json::front()
+    @brief get a pointer value (implicit)
+    @copydoc get_ptr()
     */
-    const_reference front() const
+    template<typename PointerType, typename std::enable_if<
+                 std::is_pointer<PointerType>::value and
+                 std::is_const<typename std::remove_pointer<PointerType>::type>::value, int>::type = 0>
+    constexpr const PointerType get_ptr() const noexcept
     {
-        return *cbegin();
+        // get the type of the PointerType (remove pointer and const)
+        using pointee_t = typename std::remove_const<typename
+                          std::remove_pointer<typename
+                          std::remove_const<PointerType>::type>::type>::type;
+        // make sure the type matches the allowed types
+        static_assert(
+            std::is_same<object_t, pointee_t>::value
+            or std::is_same<array_t, pointee_t>::value
+            or std::is_same<string_t, pointee_t>::value
+            or std::is_same<boolean_t, pointee_t>::value
+            or std::is_same<number_integer_t, pointee_t>::value
+            or std::is_same<number_unsigned_t, pointee_t>::value
+            or std::is_same<number_float_t, pointee_t>::value
+            , "incompatible pointer type");
+
+        // delegate the call to get_impl_ptr<>() const
+        return get_impl_ptr(static_cast<const PointerType>(nullptr));
     }
 
     /*!
-    @brief access the last element
+    @brief get a reference value (implicit)
 
-    Returns a reference to the last element in the container. For a JSON
-    container `c`, the expression `c.back()` is equivalent to
-    @code {.cpp}
-    auto tmp = c.end();
-    --tmp;
-    return *tmp;
-    @endcode
+    Implicit reference access to the internally stored JSON value. No copies
+    are made.
 
-    @return In case of a structured type (array or object), a reference to the
-    last element is returned. In case of number, string, or boolean values, a
-    reference to the value is returned.
+    @warning Writing data to the referee of the result yields an undefined
+    state.
 
-    @complexity Constant.
+    @tparam ReferenceType reference type; must be a reference to @ref array_t,
+    @ref object_t, @ref string_t, @ref boolean_t, @ref number_integer_t, or
+    @ref number_float_t. Enforced by static assertion.
 
-    @pre The JSON value must not be `null` (would throw `std::out_of_range`)
-    or an empty array or object (undefined behavior, **guarded by
-    assertions**).
-    @post The JSON value remains unchanged.
+    @return reference to the internally stored JSON value if the requested
+    reference type @a ReferenceType fits to the JSON value; throws
+    type_error.303 otherwise
 
-    @throw invalid_iterator.214 when called on a `null` value. See example
-    below.
+    @throw type_error.303 in case passed type @a ReferenceType is incompatible
+    with the stored JSON value; see example below
 
-    @liveexample{The following code shows an example for `back()`.,back}
+    @complexity Constant.
 
-    @sa @ref front() -- access the first element
+    @liveexample{The example shows several calls to `get_ref()`.,get_ref}
 
-    @since version 1.0.0
+    @since version 1.1.0
     */
-    reference back()
+    template<typename ReferenceType, typename std::enable_if<
+                 std::is_reference<ReferenceType>::value, int>::type = 0>
+    ReferenceType get_ref()
     {
-        auto tmp = end();
-        --tmp;
-        return *tmp;
+        // delegate call to get_ref_impl
+        return get_ref_impl<ReferenceType>(*this);
     }
 
     /*!
-    @copydoc basic_json::back()
+    @brief get a reference value (implicit)
+    @copydoc get_ref()
     */
-    const_reference back() const
+    template<typename ReferenceType, typename std::enable_if<
+                 std::is_reference<ReferenceType>::value and
+                 std::is_const<typename std::remove_reference<ReferenceType>::type>::value, int>::type = 0>
+    ReferenceType get_ref() const
     {
-        auto tmp = cend();
-        --tmp;
-        return *tmp;
-    }
+        // delegate call to get_ref_impl
+        return get_ref_impl<ReferenceType>(*this);
+    }
 
     /*!
-    @brief remove element given an iterator
+    @brief get a value (implicit)
 
-    Removes the element specified by iterator @a pos. The iterator @a pos must
-    be valid and dereferenceable. Thus the `end()` iterator (which is valid,
-    but is not dereferenceable) cannot be used as a value for @a pos.
+    Implicit type conversion between the JSON value and a compatible value.
+    The call is realized by calling @ref get() const.
 
-    If called on a primitive type other than `null`, the resulting JSON value
-    will be `null`.
+    @tparam ValueType non-pointer type compatible to the JSON value, for
+    instance `int` for JSON integer numbers, `bool` for JSON booleans, or
+    `std::vector` types for JSON arrays. The character type of @ref string_t
+    as well as an initializer list of this type is excluded to avoid
+    ambiguities as these types implicitly convert to `std::string`.
 
-    @param[in] pos iterator to the element to remove
-    @return Iterator following the last removed element. If the iterator @a
-    pos refers to the last element, the `end()` iterator is returned.
+    @return copy of the JSON value, converted to type @a ValueType
 
-    @tparam IteratorType an @ref iterator or @ref const_iterator
+    @throw type_error.302 in case passed type @a ValueType is incompatible
+    to the JSON value type (e.g., the JSON value is of type boolean, but a
+    string is requested); see example below
 
-    @post Invalidates iterators and references at or after the point of the
-    erase, including the `end()` iterator.
+    @complexity Linear in the size of the JSON value.
 
-    @throw type_error.307 if called on a `null` value; example: `"cannot use
-    erase() with null"`
-    @throw invalid_iterator.202 if called on an iterator which does not belong
-    to the current JSON value; example: `"iterator does not fit current
-    value"`
-    @throw invalid_iterator.205 if called on a primitive type with invalid
-    iterator (i.e., any iterator which is not `begin()`); example: `"iterator
-    out of range"`
+    @liveexample{The example below shows several conversions from JSON values
+    to other types. There a few things to note: (1) Floating-point numbers can
+    be converted to integers\, (2) A JSON array can be converted to a standard
+    `std::vector<short>`\, (3) A JSON object can be converted to C++
+    associative containers such as `std::unordered_map<std::string\,
+    json>`.,operator__ValueType}
 
-    @complexity The complexity depends on the type:
-    - objects: amortized constant
-    - arrays: linear in distance between @a pos and the end of the container
-    - strings: linear in the length of the string
-    - other types: constant
+    @since version 1.0.0
+    */
+    template < typename ValueType, typename std::enable_if <
+                   not std::is_pointer<ValueType>::value and
+                   not std::is_same<ValueType, typename string_t::value_type>::value
+#ifndef _MSC_VER  // fix for issue #167 operator<< ambiguity under VS2015
+                   and not std::is_same<ValueType, std::initializer_list<typename string_t::value_type>>::value
+#endif
+#if (defined(__cplusplus) && __cplusplus >= 201703L) || (defined(_MSC_VER) && _MSC_VER >1900 && defined(_HAS_CXX17) && _HAS_CXX17 == 1) // fix for issue #464
+                   and not std::is_same<ValueType, typename std::string_view>::value
+#endif
+                   , int >::type = 0 >
+    operator ValueType() const
+    {
+        // delegate the call to get<>() const
+        return get<ValueType>();
+    }
 
-    @liveexample{The example shows the result of `erase()` for different JSON
-    types.,erase__IteratorType}
+    /// @}
 
-    @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
-    @sa @ref erase(const size_type) -- removes the element from an array at
-    the given index
+
+    ////////////////////
+    // element access //
+    ////////////////////
+
+    /// @name element access
+    /// Access to the JSON value.
+    /// @{
+
+    /*!
+    @brief access specified array element with bounds checking
+
+    Returns a reference to the element at specified location @a idx, with
+    bounds checking.
+
+    @param[in] idx  index of the element to access
+
+    @return reference to the element at index @a idx
+
+    @throw type_error.304 if the JSON value is not an array; in this case,
+    calling `at` with an index makes no sense. See example below.
+    @throw out_of_range.401 if the index @a idx is out of range of the array;
+    that is, `idx >= size()`. See example below.
+
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
+
+    @complexity Constant.
 
     @since version 1.0.0
+
+    @liveexample{The example below shows how array elements can be read and
+    written using `at()`. It also demonstrates the different exceptions that
+    can be thrown.,at__size_type}
     */
-    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 pos)
+    reference at(size_type idx)
     {
-        // make sure iterator fits the current value
-        if (this != pos.m_object)
+        // at only works for arrays
+        if (is_array())
         {
-            JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
+            JSON_TRY
+            {
+                return m_value.array->at(idx);
+            }
+            JSON_CATCH (std::out_of_range&)
+            {
+                // create better exception explanation
+                JSON_THROW(out_of_range::create(401, "array index " + std::to_string(idx) + " is out of range"));
+            }
+        }
+        else
+        {
+            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
         }
+    }
 
-        IteratorType result = end();
+    /*!
+    @brief access specified array element with bounds checking
 
-        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(invalid_iterator::create(205, "iterator out of range"));
-                }
+    Returns a const reference to the element at specified location @a idx,
+    with bounds checking.
 
-                if (is_string())
-                {
-                    AllocatorType<string_t> alloc;
-                    alloc.destroy(m_value.string);
-                    alloc.deallocate(m_value.string, 1);
-                    m_value.string = nullptr;
-                }
+    @param[in] idx  index of the element to access
 
-                m_type = value_t::null;
-                assert_invariant();
-                break;
-            }
+    @return const reference to the element at index @a idx
 
-            case value_t::object:
-            {
-                result.m_it.object_iterator = m_value.object->erase(pos.m_it.object_iterator);
-                break;
-            }
+    @throw type_error.304 if the JSON value is not an array; in this case,
+    calling `at` with an index makes no sense. See example below.
+    @throw out_of_range.401 if the index @a idx is out of range of the array;
+    that is, `idx >= size()`. See example below.
 
-            case value_t::array:
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
+
+    @complexity Constant.
+
+    @since version 1.0.0
+
+    @liveexample{The example below shows how array elements can be read using
+    `at()`. It also demonstrates the different exceptions that can be thrown.,
+    at__size_type_const}
+    */
+    const_reference at(size_type idx) const
+    {
+        // at only works for arrays
+        if (is_array())
+        {
+            JSON_TRY
             {
-                result.m_it.array_iterator = m_value.array->erase(pos.m_it.array_iterator);
-                break;
+                return m_value.array->at(idx);
             }
-
-            default:
+            JSON_CATCH (std::out_of_range&)
             {
-                JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
+                // create better exception explanation
+                JSON_THROW(out_of_range::create(401, "array index " + std::to_string(idx) + " is out of range"));
             }
         }
-
-        return result;
+        else
+        {
+            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
+        }
     }
 
     /*!
-    @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`.
+    @brief access specified object element with bounds checking
 
-    @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.
+    Returns a reference to the element at with specified key @a key, with
+    bounds checking.
 
-    @tparam IteratorType an @ref iterator or @ref const_iterator
+    @param[in] key  key of the element to access
 
-    @post Invalidates iterators and references at or after the point of the
-    erase, including the `end()` iterator.
+    @return reference to the element at key @a key
 
-    @throw type_error.307 if called on a `null` value; example: `"cannot use
-    erase() with null"`
-    @throw invalid_iterator.203 if called on iterators which does not belong
-    to the current JSON value; example: `"iterators do not fit current value"`
-    @throw invalid_iterator.204 if called on a primitive type with invalid
-    iterators (i.e., if `first != begin()` and `last != end()`); example:
-    `"iterators out of range"`
+    @throw type_error.304 if the JSON value is not an object; in this case,
+    calling `at` with a key makes no sense. See example below.
+    @throw out_of_range.403 if the key @a key is is not stored in the object;
+    that is, `find(key) == end()`. See example below.
 
-    @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
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
 
-    @liveexample{The example shows the result of `erase()` for different JSON
-    types.,erase__IteratorType_IteratorType}
+    @complexity Logarithmic in the size of the container.
 
-    @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
+    @sa @ref operator[](const typename object_t::key_type&) for unchecked
+    access by reference
+    @sa @ref value() for access by value with a default value
 
     @since version 1.0.0
+
+    @liveexample{The example below shows how object elements can be read and
+    written using `at()`. It also demonstrates the different exceptions that
+    can be thrown.,at__object_t_key_type}
     */
-    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)
+    reference at(const typename object_t::key_type& key)
     {
-        // make sure iterator fits the current value
-        if (this != first.m_object or this != last.m_object)
-        {
-            JSON_THROW(invalid_iterator::create(203, "iterators do not fit current value"));
-        }
-
-        IteratorType result = end();
-
-        switch (m_type)
+        // at only works for objects
+        if (is_object())
         {
-            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(invalid_iterator::create(204, "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:
+            JSON_TRY
             {
-                result.m_it.array_iterator = m_value.array->erase(first.m_it.array_iterator,
-                                             last.m_it.array_iterator);
-                break;
+                return m_value.object->at(key);
             }
-
-            default:
+            JSON_CATCH (std::out_of_range&)
             {
-                JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
+                // create better exception explanation
+                JSON_THROW(out_of_range::create(403, "key '" + key + "' not found"));
             }
         }
-
-        return result;
+        else
+        {
+            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
+        }
     }
 
     /*!
-    @brief remove element from a JSON object given a key
-
-    Removes elements from a JSON object with the key value @a key.
+    @brief access specified object element with bounds checking
 
-    @param[in] key value of the elements to remove
+    Returns a const reference to the element at with specified key @a key,
+    with bounds checking.
 
-    @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).
+    @param[in] key  key of the element to access
 
-    @post References and iterators to the erased elements are invalidated.
-    Other references and iterators are not affected.
+    @return const reference to the element at key @a key
 
-    @throw type_error.307 when called on a type other than JSON object;
-    example: `"cannot use erase() with null"`
+    @throw type_error.304 if the JSON value is not an object; in this case,
+    calling `at` with a key makes no sense. See example below.
+    @throw out_of_range.403 if the key @a key is is not stored in the object;
+    that is, `find(key) == end()`. See example below.
 
-    @complexity `log(size()) + count(key)`
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
 
-    @liveexample{The example shows the effect of `erase()`.,erase__key_type}
+    @complexity Logarithmic in the size of the container.
 
-    @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
+    @sa @ref operator[](const typename object_t::key_type&) for unchecked
+    access by reference
+    @sa @ref value() for access by value with a default value
 
     @since version 1.0.0
+
+    @liveexample{The example below shows how object elements can be read using
+    `at()`. It also demonstrates the different exceptions that can be thrown.,
+    at__object_t_key_type_const}
     */
-    size_type erase(const typename object_t::key_type& key)
+    const_reference at(const typename object_t::key_type& key) const
     {
-        // this erase only works for objects
+        // at only works for objects
         if (is_object())
         {
-            return m_value.object->erase(key);
+            JSON_TRY
+            {
+                return m_value.object->at(key);
+            }
+            JSON_CATCH (std::out_of_range&)
+            {
+                // create better exception explanation
+                JSON_THROW(out_of_range::create(403, "key '" + key + "' not found"));
+            }
+        }
+        else
+        {
+            JSON_THROW(type_error::create(304, "cannot use at() with " + type_name()));
         }
-
-        JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
     }
 
     /*!
-    @brief remove element from a JSON array given an index
+    @brief access specified array element
 
-    Removes element from a JSON array at the index @a idx.
+    Returns a reference to the element at specified location @a idx.
 
-    @param[in] idx index of the element to remove
+    @note If @a idx is beyond the range of the array (i.e., `idx >= size()`),
+    then the array is silently filled up with `null` values to make `idx` a
+    valid reference to the last stored element.
 
-    @throw type_error.307 when called on a type other than JSON object;
-    example: `"cannot use erase() with null"`
-    @throw out_of_range.401 when `idx >= size()`; example: `"array index 17
-    is out of range"`
+    @param[in] idx  index of the element to access
 
-    @complexity Linear in distance between @a idx and the end of the container.
+    @return reference to the element at index @a idx
 
-    @liveexample{The example shows the effect of `erase()`.,erase__size_type}
+    @throw type_error.305 if the JSON value is not an array or null; in that
+    cases, using the [] operator with an index makes no sense.
 
-    @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
+    @complexity Constant if @a idx is in the range of the array. Otherwise
+    linear in `idx - size()`.
+
+    @liveexample{The example below shows how array elements can be read and
+    written using `[]` operator. Note the addition of `null`
+    values.,operatorarray__size_type}
 
     @since version 1.0.0
     */
-    void erase(const size_type idx)
+    reference operator[](size_type idx)
     {
-        // this erase only works for arrays
+        // implicitly convert null value to an empty array
+        if (is_null())
+        {
+            m_type = value_t::array;
+            m_value.array = create<array_t>();
+            assert_invariant();
+        }
+
+        // operator[] only works for arrays
         if (is_array())
         {
-            if (idx >= size())
+            // fill up array with null values if given idx is outside range
+            if (idx >= m_value.array->size())
             {
-                JSON_THROW(out_of_range::create(401, "array index " + std::to_string(idx) + " is out of range"));
+                m_value.array->insert(m_value.array->end(),
+                                      idx - m_value.array->size() + 1,
+                                      basic_json());
             }
 
-            m_value.array->erase(m_value.array->begin() + static_cast<difference_type>(idx));
-        }
-        else
-        {
-            JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
+            return m_value.array->operator[](idx);
         }
-    }
-
-    /// @}
-
-
-    ////////////
-    // lookup //
-    ////////////
 
-    /// @name lookup
-    /// @{
+        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+    }
 
     /*!
-    @brief find an element in a JSON object
+    @brief access specified array element
 
-    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.
+    Returns a const reference to the element at specified location @a idx.
 
-    @note This method always returns @ref end() when executed on a JSON type
-          that is not an object.
+    @param[in] idx  index of the element to access
 
-    @param[in] key key value of the element to search for
+    @return const reference to the element at index @a idx
 
-    @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.
+    @throw type_error.305 if the JSON value is not an array; in that cases,
+    using the [] operator with an index makes no sense.
 
-    @complexity Logarithmic in the size of the JSON object.
+    @complexity Constant.
 
-    @liveexample{The example shows how `find()` is used.,find__key_type}
+    @liveexample{The example below shows how array elements can be read using
+    the `[]` operator.,operatorarray__size_type_const}
 
     @since version 1.0.0
     */
-    iterator find(typename object_t::key_type key)
+    const_reference operator[](size_type idx) const
     {
-        auto result = end();
-
-        if (is_object())
+        // const operator[] only works for arrays
+        if (is_array())
         {
-            result.m_it.object_iterator = m_value.object->find(key);
+            return m_value.array->operator[](idx);
         }
 
-        return result;
+        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
     }
 
     /*!
-    @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();
+    @brief access specified object element
 
-        if (is_object())
-        {
-            result.m_it.object_iterator = m_value.object->find(key);
-        }
+    Returns a reference to the element at with specified key @a key.
 
-        return result;
-    }
+    @note If @a key is not found in the object, then it is silently added to
+    the object and filled with a `null` value to make `key` a valid reference.
+    In case the value was `null` before, it is converted to an object.
 
-    /*!
-    @brief returns the number of occurrences of a key in a JSON object
+    @param[in] key  key of the element to access
 
-    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).
+    @return reference to the element at key @a key
 
-    @note This method always returns `0` when executed on a JSON type that is
-          not an object.
+    @throw type_error.305 if the JSON value is not an object or null; in that
+    cases, using the [] operator with a key makes no sense.
 
-    @param[in] key key value of the element to count
+    @complexity Logarithmic in the size of the container.
 
-    @return Number of elements with key @a key. If the JSON value is not an
-    object, the return value will be `0`.
+    @liveexample{The example below shows how object elements can be read and
+    written using the `[]` operator.,operatorarray__key_type}
 
-    @complexity Logarithmic in the size of the JSON object.
-
-    @liveexample{The example shows how `count()` is used.,count}
+    @sa @ref at(const typename object_t::key_type&) for access by reference
+    with range checking
+    @sa @ref value() for access by value with a default value
 
     @since version 1.0.0
     */
-    size_type count(typename object_t::key_type key) const
+    reference operator[](const typename object_t::key_type& key)
     {
-        // return 0 for all nonobject types
-        return is_object() ? m_value.object->count(key) : 0;
-    }
+        // implicitly convert null value to an empty object
+        if (is_null())
+        {
+            m_type = value_t::object;
+            m_value.object = create<object_t>();
+            assert_invariant();
+        }
 
-    /// @}
+        // operator[] only works for objects
+        if (is_object())
+        {
+            return m_value.object->operator[](key);
+        }
 
+        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
+    }
 
-    ///////////////
-    // iterators //
-    ///////////////
+    /*!
+    @brief read-only access specified object element
 
-    /// @name iterators
-    /// @{
+    Returns a const reference to the element at with specified key @a key. No
+    bounds checking is performed.
 
-    /*!
-    @brief returns an iterator to the first element
+    @warning If the element with key @a key does not exist, the behavior is
+    undefined.
 
-    Returns an iterator to the first element.
+    @param[in] key  key of the element to access
 
-    @image html range-begin-end.svg "Illustration from cppreference.com"
+    @return const reference to the element at key @a key
 
-    @return iterator to the first element
+    @pre The element with key @a key must exist. **This precondition is
+         enforced with an assertion.**
 
-    @complexity Constant.
+    @throw type_error.305 if the JSON value is not an object; in that cases,
+    using the [] operator with a key makes no sense.
 
-    @requirement This function helps `basic_json` satisfying the
-    [Container](http://en.cppreference.com/w/cpp/concept/Container)
-    requirements:
-    - The complexity is constant.
+    @complexity Logarithmic in the size of the container.
 
-    @liveexample{The following code shows an example for `begin()`.,begin}
+    @liveexample{The example below shows how object elements can be read using
+    the `[]` operator.,operatorarray__key_type_const}
 
-    @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
+    @sa @ref at(const typename object_t::key_type&) for access by reference
+    with range checking
+    @sa @ref value() for access by value with a default value
 
     @since version 1.0.0
     */
-    iterator begin() noexcept
+    const_reference operator[](const typename object_t::key_type& key) const
     {
-        iterator result(this);
-        result.set_begin();
-        return result;
-    }
+        // const operator[] only works for objects
+        if (is_object())
+        {
+            assert(m_value.object->find(key) != m_value.object->end());
+            return m_value.object->find(key)->second;
+        }
 
-    /*!
-    @copydoc basic_json::cbegin()
-    */
-    const_iterator begin() const noexcept
-    {
-        return cbegin();
+        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
     }
 
     /*!
-    @brief returns a const iterator to the first element
+    @brief access specified object element
 
-    Returns a const iterator to the first element.
+    Returns a reference to the element at with specified key @a key.
 
-    @image html range-begin-end.svg "Illustration from cppreference.com"
+    @note If @a key is not found in the object, then it is silently added to
+    the object and filled with a `null` value to make `key` a valid reference.
+    In case the value was `null` before, it is converted to an object.
 
-    @return const iterator to the first element
+    @param[in] key  key of the element to access
 
-    @complexity Constant.
+    @return reference to the element at key @a key
 
-    @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()`.
+    @throw type_error.305 if the JSON value is not an object or null; in that
+    cases, using the [] operator with a key makes no sense.
 
-    @liveexample{The following code shows an example for `cbegin()`.,cbegin}
+    @complexity Logarithmic in the size of the container.
 
-    @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
+    @liveexample{The example below shows how object elements can be read and
+    written using the `[]` operator.,operatorarray__key_type}
 
-    @since version 1.0.0
+    @sa @ref at(const typename object_t::key_type&) for access by reference
+    with range checking
+    @sa @ref value() for access by value with a default value
+
+    @since version 1.1.0
     */
-    const_iterator cbegin() const noexcept
+    template<typename T>
+    reference operator[](T* key)
     {
-        const_iterator result(this);
-        result.set_begin();
-        return result;
+        // implicitly convert null to object
+        if (is_null())
+        {
+            m_type = value_t::object;
+            m_value = value_t::object;
+            assert_invariant();
+        }
+
+        // at only works for objects
+        if (is_object())
+        {
+            return m_value.object->operator[](key);
+        }
+
+        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
     }
 
     /*!
-    @brief returns an iterator to one past the last element
+    @brief read-only access specified object element
 
-    Returns an iterator to one past the last element.
+    Returns a const reference to the element at with specified key @a key. No
+    bounds checking is performed.
 
-    @image html range-begin-end.svg "Illustration from cppreference.com"
+    @warning If the element with key @a key does not exist, the behavior is
+    undefined.
 
-    @return iterator one past the last element
+    @param[in] key  key of the element to access
 
-    @complexity Constant.
+    @return const reference to the element at key @a key
 
-    @requirement This function helps `basic_json` satisfying the
-    [Container](http://en.cppreference.com/w/cpp/concept/Container)
-    requirements:
-    - The complexity is constant.
+    @pre The element with key @a key must exist. **This precondition is
+         enforced with an assertion.**
 
-    @liveexample{The following code shows an example for `end()`.,end}
+    @throw type_error.305 if the JSON value is not an object; in that cases,
+    using the [] operator with a key makes no sense.
 
-    @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
+    @complexity Logarithmic in the size of the container.
 
-    @since version 1.0.0
+    @liveexample{The example below shows how object elements can be read using
+    the `[]` operator.,operatorarray__key_type_const}
+
+    @sa @ref at(const typename object_t::key_type&) for access by reference
+    with range checking
+    @sa @ref value() for access by value with a default value
+
+    @since version 1.1.0
     */
-    iterator end() noexcept
+    template<typename T>
+    const_reference operator[](T* key) const
     {
-        iterator result(this);
-        result.set_end();
-        return result;
+        // at only works for objects
+        if (is_object())
+        {
+            assert(m_value.object->find(key) != m_value.object->end());
+            return m_value.object->find(key)->second;
+        }
+
+        JSON_THROW(type_error::create(305, "cannot use operator[] with " + type_name()));
     }
 
     /*!
-    @copydoc basic_json::cend()
-    */
-    const_iterator end() const noexcept
-    {
-        return cend();
+    @brief access specified object element with default value
+
+    Returns either a copy of an object's element at the specified key @a key
+    or a given default value if no element with key @a key exists.
+
+    The function is basically equivalent to executing
+    @code {.cpp}
+    try {
+        return at(key);
+    } catch(out_of_range) {
+        return default_value;
     }
+    @endcode
 
-    /*!
-    @brief returns a const iterator to one past the last element
+    @note Unlike @ref at(const typename object_t::key_type&), this function
+    does not throw if the given key @a key was not found.
 
-    Returns a const iterator to one past the last element.
+    @note Unlike @ref operator[](const typename object_t::key_type& key), this
+    function does not implicitly add an element to the position defined by @a
+    key. This function is furthermore also applicable to const objects.
 
-    @image html range-begin-end.svg "Illustration from cppreference.com"
+    @param[in] key  key of the element to access
+    @param[in] default_value  the value to return if @a key is not found
 
-    @return const iterator one past the last element
+    @tparam ValueType type compatible to JSON values, for instance `int` for
+    JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
+    JSON arrays. Note the type of the expected value at @a key and the default
+    value @a default_value must be compatible.
 
-    @complexity Constant.
+    @return copy of the element at key @a key or @a default_value if @a key
+    is not found
 
-    @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()`.
+    @throw type_error.306 if the JSON value is not an objec; in that cases,
+    using `value()` with a key makes no sense.
 
-    @liveexample{The following code shows an example for `cend()`.,cend}
+    @complexity Logarithmic in the size of the container.
 
-    @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
+    @liveexample{The example below shows how object elements can be queried
+    with a default value.,basic_json__value}
+
+    @sa @ref at(const typename object_t::key_type&) for access by reference
+    with range checking
+    @sa @ref operator[](const typename object_t::key_type&) for unchecked
+    access by reference
 
     @since version 1.0.0
     */
-    const_iterator cend() const noexcept
+    template<class ValueType, typename std::enable_if<
+                 std::is_convertible<basic_json_t, ValueType>::value, int>::type = 0>
+    ValueType value(const typename object_t::key_type& key, ValueType default_value) const
     {
-        const_iterator result(this);
-        result.set_end();
-        return result;
-    }
+        // at only works for objects
+        if (is_object())
+        {
+            // if key is found, return value and given default value otherwise
+            const auto it = find(key);
+            if (it != end())
+            {
+                return *it;
+            }
 
-    /*!
-    @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());
+            return default_value;
+        }
+        else
+        {
+            JSON_THROW(type_error::create(306, "cannot use value() with " + type_name()));
+        }
     }
 
     /*!
-    @copydoc basic_json::crbegin()
+    @brief overload for a default value of type const char*
+    @copydoc basic_json::value(const typename object_t::key_type&, ValueType) const
     */
-    const_reverse_iterator rbegin() const noexcept
+    string_t value(const typename object_t::key_type& key, const char* default_value) const
     {
-        return crbegin();
+        return value(key, string_t(default_value));
     }
 
     /*!
-    @brief returns an iterator to the reverse-end
+    @brief access specified object element via JSON Pointer with default value
 
-    Returns an iterator to the reverse-end; that is, one before the first
-    element.
+    Returns either a copy of an object's element at the specified key @a key
+    or a given default value if no element with key @a key exists.
 
-    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
+    The function is basically equivalent to executing
+    @code {.cpp}
+    try {
+        return at(ptr);
+    } catch(out_of_range) {
+        return default_value;
+    }
+    @endcode
 
-    @complexity Constant.
+    @note Unlike @ref at(const json_pointer&), this function does not throw
+    if the given key @a key was not found.
 
-    @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())`.
+    @param[in] ptr  a JSON pointer to the element to access
+    @param[in] default_value  the value to return if @a ptr found no value
 
-    @liveexample{The following code shows an example for `rend()`.,rend}
+    @tparam ValueType type compatible to JSON values, for instance `int` for
+    JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
+    JSON arrays. Note the type of the expected value at @a key and the default
+    value @a default_value must be compatible.
 
-    @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
+    @return copy of the element at key @a key or @a default_value if @a key
+    is not found
 
-    @since version 1.0.0
+    @throw type_error.306 if the JSON value is not an objec; in that cases,
+    using `value()` with a key makes no sense.
+
+    @complexity Logarithmic in the size of the container.
+
+    @liveexample{The example below shows how object elements can be queried
+    with a default value.,basic_json__value_ptr}
+
+    @sa @ref operator[](const json_pointer&) for unchecked access by reference
+
+    @since version 2.0.2
     */
-    reverse_iterator rend() noexcept
+    template<class ValueType, typename std::enable_if<
+                 std::is_convertible<basic_json_t, ValueType>::value, int>::type = 0>
+    ValueType value(const json_pointer& ptr, ValueType default_value) const
     {
-        return reverse_iterator(begin());
+        // at only works for objects
+        if (is_object())
+        {
+            // if pointer resolves a value, return it or use default value
+            JSON_TRY
+            {
+                return ptr.get_checked(this);
+            }
+            JSON_CATCH (out_of_range&)
+            {
+                return default_value;
+            }
+        }
+
+        JSON_THROW(type_error::create(306, "cannot use value() with " + type_name()));
     }
 
     /*!
-    @copydoc basic_json::crend()
+    @brief overload for a default value of type const char*
+    @copydoc basic_json::value(const json_pointer&, ValueType) const
     */
-    const_reverse_iterator rend() const noexcept
+    string_t value(const json_pointer& ptr, const char* default_value) const
     {
-        return crend();
+        return value(ptr, string_t(default_value));
     }
 
     /*!
-    @brief returns a const reverse iterator to the last element
+    @brief access the first element
 
-    Returns a const iterator to the reverse-beginning; that is, the last
-    element.
+    Returns a reference to the first element in the container. For a JSON
+    container `c`, the expression `c.front()` is equivalent to `*c.begin()`.
 
-    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
+    @return In case of a structured type (array or object), a reference to the
+    first element is returned. In case of number, string, or boolean values, a
+    reference to the value is returned.
 
     @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()`.
+    @pre The JSON value must not be `null` (would throw `std::out_of_range`)
+    or an empty array or object (undefined behavior, **guarded by
+    assertions**).
+    @post The JSON value remains unchanged.
 
-    @liveexample{The following code shows an example for `crbegin()`.,crbegin}
+    @throw invalid_iterator.214 when called on `null` value
 
-    @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
+    @liveexample{The following code shows an example for `front()`.,front}
+
+    @sa @ref back() -- access the last element
 
     @since version 1.0.0
     */
-    const_reverse_iterator crbegin() const noexcept
+    reference front()
     {
-        return const_reverse_iterator(cend());
+        return *begin();
     }
 
     /*!
-    @brief returns a const reverse iterator to one before the first
+    @copydoc basic_json::front()
+    */
+    const_reference front() const
+    {
+        return *cbegin();
+    }
 
-    Returns a const reverse iterator to the reverse-end; that is, one before
-    the first element.
+    /*!
+    @brief access the last element
 
-    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
+    Returns a reference to the last element in the container. For a JSON
+    container `c`, the expression `c.back()` is equivalent to
+    @code {.cpp}
+    auto tmp = c.end();
+    --tmp;
+    return *tmp;
+    @endcode
+
+    @return In case of a structured type (array or object), a reference to the
+    last element is returned. In case of number, string, or boolean values, a
+    reference to the value is returned.
 
     @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()`.
+    @pre The JSON value must not be `null` (would throw `std::out_of_range`)
+    or an empty array or object (undefined behavior, **guarded by
+    assertions**).
+    @post The JSON value remains unchanged.
 
-    @liveexample{The following code shows an example for `crend()`.,crend}
+    @throw invalid_iterator.214 when called on a `null` value. See example
+    below.
 
-    @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
+    @liveexample{The following code shows an example for `back()`.,back}
+
+    @sa @ref front() -- access the first element
 
     @since version 1.0.0
     */
-    const_reverse_iterator crend() const noexcept
+    reference back()
     {
-        return const_reverse_iterator(cbegin());
+        auto tmp = end();
+        --tmp;
+        return *tmp;
     }
 
-  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.
-
-    @liveexample{The following code shows how the wrapper is used,iterator_wrapper}
-
-    @note The name of this function is not yet final and may change in the
-    future.
+    @copydoc basic_json::back()
     */
-    static iteration_proxy<iterator> iterator_wrapper(reference cont)
+    const_reference back() const
     {
-        return iteration_proxy<iterator>(cont);
+        auto tmp = cend();
+        --tmp;
+        return *tmp;
     }
 
     /*!
-    @copydoc iterator_wrapper(reference)
-    */
-    static iteration_proxy<const_iterator> iterator_wrapper(const_reference cont)
-    {
-        return iteration_proxy<const_iterator>(cont);
-    }
-
-    /// @}
+    @brief remove element given an iterator
 
+    Removes the element specified by iterator @a pos. The iterator @a pos must
+    be valid and dereferenceable. Thus the `end()` iterator (which is valid,
+    but is not dereferenceable) cannot be used as a value for @a pos.
 
-    //////////////
-    // capacity //
-    //////////////
+    If called on a primitive type other than `null`, the resulting JSON value
+    will be `null`.
 
-    /// @name capacity
-    /// @{
+    @param[in] pos iterator to the element to remove
+    @return Iterator following the last removed element. If the iterator @a
+    pos refers to the last element, the `end()` iterator is returned.
 
-    /*!
-    @brief checks whether the container is empty
+    @tparam IteratorType an @ref iterator or @ref const_iterator
 
-    Checks if a JSON value has no elements.
+    @post Invalidates iterators and references at or after the point of the
+    erase, including the `end()` iterator.
 
-    @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()`
+    @throw type_error.307 if called on a `null` value; example: `"cannot use
+    erase() with null"`
+    @throw invalid_iterator.202 if called on an iterator which does not belong
+    to the current JSON value; example: `"iterator does not fit current
+    value"`
+    @throw invalid_iterator.205 if called on a primitive type with invalid
+    iterator (i.e., any iterator which is not `begin()`); example: `"iterator
+    out of range"`
 
-    @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()`.
+    @complexity The complexity depends on the type:
+    - objects: amortized constant
+    - arrays: linear in distance between @a pos and the end of the container
+    - strings: linear in the length of the string
+    - other types: constant
 
-    @liveexample{The following code uses `empty()` to check if a JSON
-    object contains any elements.,empty}
+    @liveexample{The example shows the result of `erase()` for different JSON
+    types.,erase__IteratorType}
 
-    @sa @ref size() -- returns the number of elements
+    @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
+    @sa @ref erase(const size_type) -- removes the element from an array at
+    the given index
 
     @since version 1.0.0
     */
-    bool empty() const noexcept
+    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 pos)
     {
+        // make sure iterator fits the current value
+        if (this != pos.m_object)
+        {
+            JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
+        }
+
+        IteratorType result = end();
+
         switch (m_type)
         {
-            case value_t::null:
+            case value_t::boolean:
+            case value_t::number_float:
+            case value_t::number_integer:
+            case value_t::number_unsigned:
+            case value_t::string:
             {
-                // null values are empty
-                return true;
+                if (not pos.m_it.primitive_iterator.is_begin())
+                {
+                    JSON_THROW(invalid_iterator::create(205, "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::array:
+            case value_t::object:
             {
-                // delegate call to array_t::empty()
-                return m_value.array->empty();
+                result.m_it.object_iterator = m_value.object->erase(pos.m_it.object_iterator);
+                break;
             }
 
-            case value_t::object:
+            case value_t::array:
             {
-                // delegate call to object_t::empty()
-                return m_value.object->empty();
+                result.m_it.array_iterator = m_value.array->erase(pos.m_it.array_iterator);
+                break;
             }
 
             default:
             {
-                // all other types are nonempty
-                return false;
+                JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
             }
         }
+
+        return result;
     }
 
     /*!
-    @brief returns the number of elements
+    @brief remove elements given an iterator range
 
-    Returns the number of elements in a JSON value.
+    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.
 
-    @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()
+    If called on a primitive type other than `null`, the resulting JSON value
+    will be `null`.
 
-    @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.
+    @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.
 
-    @complexity Constant, as long as @ref array_t and @ref object_t satisfy
-    the Container concept; that is, their size() functions have constant
-    complexity.
+    @tparam IteratorType an @ref iterator or @ref const_iterator
 
-    @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())`.
+    @post Invalidates iterators and references at or after the point of the
+    erase, including the `end()` iterator.
 
-    @liveexample{The following code calls `size()` on the different value
-    types.,size}
+    @throw type_error.307 if called on a `null` value; example: `"cannot use
+    erase() with null"`
+    @throw invalid_iterator.203 if called on iterators which does not belong
+    to the current JSON value; example: `"iterators do not fit current value"`
+    @throw invalid_iterator.204 if called on a primitive type with invalid
+    iterators (i.e., if `first != begin()` and `last != end()`); example:
+    `"iterators out of range"`
 
-    @sa @ref empty() -- checks whether the container is empty
-    @sa @ref max_size() -- returns the maximal number of elements
+    @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
     */
-    size_type size() const noexcept
+    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(invalid_iterator::create(203, "iterators do not fit current value"));
+        }
+
+        IteratorType result = end();
+
         switch (m_type)
         {
-            case value_t::null:
+            case value_t::boolean:
+            case value_t::number_float:
+            case value_t::number_integer:
+            case value_t::number_unsigned:
+            case value_t::string:
             {
-                // null values are empty
-                return 0;
+                if (not first.m_it.primitive_iterator.is_begin() or not last.m_it.primitive_iterator.is_end())
+                {
+                    JSON_THROW(invalid_iterator::create(204, "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::array:
+            case value_t::object:
             {
-                // delegate call to array_t::size()
-                return m_value.array->size();
+                result.m_it.object_iterator = m_value.object->erase(first.m_it.object_iterator,
+                                              last.m_it.object_iterator);
+                break;
             }
 
-            case value_t::object:
+            case value_t::array:
             {
-                // delegate call to object_t::size()
-                return m_value.object->size();
+                result.m_it.array_iterator = m_value.array->erase(first.m_it.array_iterator,
+                                             last.m_it.array_iterator);
+                break;
             }
 
             default:
             {
-                // all other types have size 1
-                return 1;
+                JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
             }
         }
+
+        return result;
     }
 
     /*!
-    @brief returns the maximum possible number of elements
+    @brief remove element from a JSON object given a key
 
-    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.
+    Removes elements from a JSON object with the key value @a key.
 
-    @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()`
+    @param[in] key value of the elements to remove
 
-    @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.
+    @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).
 
-    @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.
+    @post References and iterators to the erased elements are invalidated.
+    Other references and iterators are not affected.
 
-    @liveexample{The following code calls `max_size()` on the different value
-    types. Note the output is implementation specific.,max_size}
+    @throw type_error.307 when called on a type other than JSON object;
+    example: `"cannot use erase() with null"`
 
-    @sa @ref size() -- returns the number of elements
+    @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 max_size() const noexcept
+    size_type erase(const typename object_t::key_type& key)
     {
-        switch (m_type)
+        // this erase only works for objects
+        if (is_object())
         {
-            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();
-            }
+            return m_value.object->erase(key);
         }
-    }
-
-    /// @}
 
+        JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
+    }
 
-    ///////////////
-    // modifiers //
-    ///////////////
+    /*!
+    @brief remove element from a JSON array given an index
 
-    /// @name modifiers
-    /// @{
+    Removes element from a JSON array at the index @a idx.
 
-    /*!
-    @brief clears the contents
+    @param[in] idx index of the element to remove
 
-    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:
+    @throw type_error.307 when called on a type other than JSON object;
+    example: `"cannot use erase() with null"`
+    @throw out_of_range.401 when `idx >= size()`; example: `"array index 17
+    is out of range"`
 
-    Value type  | initial value
-    ----------- | -------------
-    null        | `null`
-    boolean     | `false`
-    string      | `""`
-    number      | `0`
-    object      | `{}`
-    array       | `[]`
+    @complexity Linear in distance between @a idx and the end of the container.
 
-    @complexity Linear in the size of the JSON value.
+    @liveexample{The example shows the effect of `erase()`.,erase__size_type}
 
-    @liveexample{The example below shows the effect of `clear()` to different
-    JSON types.,clear}
+    @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 clear() noexcept
+    void erase(const size_type idx)
     {
-        switch (m_type)
+        // this erase only works for arrays
+        if (is_array())
         {
-            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:
+            if (idx >= size())
             {
-                m_value.number_float = 0.0;
-                break;
+                JSON_THROW(out_of_range::create(401, "array index " + std::to_string(idx) + " is out of range"));
             }
 
-            case value_t::boolean:
-            {
-                m_value.boolean = false;
-                break;
-            }
+            m_value.array->erase(m_value.array->begin() + static_cast<difference_type>(idx));
+        }
+        else
+        {
+            JSON_THROW(type_error::create(307, "cannot use erase() with " + type_name()));
+        }
+    }
 
-            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;
-            }
+    ////////////
+    // lookup //
+    ////////////
 
-            default:
-            {
-                break;
-            }
-        }
-    }
+    /// @name lookup
+    /// @{
 
     /*!
-    @brief add an object to an array
+    @brief find an element in a JSON object
 
-    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.
+    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.
 
-    @param[in] val the value to add to the JSON array
+    @note This method always returns @ref end() when executed on a JSON type
+          that is not an object.
 
-    @throw type_error.308 when called on a type other than JSON array or
-    null; example: `"cannot use push_back() with number"`
+    @param[in] key key value of the element to search for
 
-    @complexity Amortized constant.
+    @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.
 
-    @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}
+    @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
     */
-    void push_back(basic_json&& val)
+    iterator find(typename object_t::key_type key)
     {
-        // push_back only works for null objects or arrays
-        if (not(is_null() or is_array()))
-        {
-            JSON_THROW(type_error::create(308, "cannot use push_back() with " + type_name()));
-        }
+        auto result = end();
 
-        // transform null object into an array
-        if (is_null())
+        if (is_object())
         {
-            m_type = value_t::array;
-            m_value = value_t::array;
-            assert_invariant();
+            result.m_it.object_iterator = m_value.object->find(key);
         }
 
-        // 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;
+        return result;
     }
 
     /*!
-    @brief add an object to an array
-    @copydoc push_back(basic_json&&)
+    @brief find an element in a JSON object
+    @copydoc find(typename object_t::key_type)
     */
-    void push_back(const basic_json& val)
+    const_iterator find(typename object_t::key_type key) const
     {
-        // push_back only works for null objects or arrays
-        if (not(is_null() or is_array()))
-        {
-            JSON_THROW(type_error::create(308, "cannot use push_back() with " + type_name()));
-        }
+        auto result = cend();
 
-        // transform null object into an array
-        if (is_null())
+        if (is_object())
         {
-            m_type = value_t::array;
-            m_value = value_t::array;
-            assert_invariant();
+            result.m_it.object_iterator = m_value.object->find(key);
         }
 
-        // add element to array
-        m_value.array->push_back(val);
+        return result;
     }
 
     /*!
-    @brief add an object to an array
-    @copydoc push_back(basic_json&&)
-    */
-    reference operator+=(const basic_json& val)
-    {
-        push_back(val);
-        return *this;
-    }
+    @brief returns the number of occurrences of a key in a JSON object
 
-    /*!
-    @brief add an object to an 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).
 
-    Inserts the given element @a val to the JSON object. If the function is
-    called on a JSON null value, an empty object is created before inserting
-    @a val.
+    @note This method always returns `0` when executed on a JSON type that is
+          not an object.
 
-    @param[in] val the value to add to the JSON object
+    @param[in] key key value of the element to count
 
-    @throw type_error.308 when called on a type other than JSON object or
-    null; example: `"cannot use push_back() with number"`
+    @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 container, O(log(`size()`)).
+    @complexity Logarithmic in the size of the JSON object.
 
-    @liveexample{The example shows how `push_back()` and `+=` can be used to
-    add elements to a JSON object. Note how the `null` value was silently
-    converted to a JSON object.,push_back__object_t__value}
+    @liveexample{The example shows how `count()` is used.,count}
 
     @since version 1.0.0
     */
-    void push_back(const typename object_t::value_type& val)
-    {
-        // push_back only works for null objects or objects
-        if (not(is_null() or is_object()))
-        {
-            JSON_THROW(type_error::create(308, "cannot use push_back() with " + type_name()));
-        }
-
-        // transform null object into an object
-        if (is_null())
-        {
-            m_type = value_t::object;
-            m_value = value_t::object;
-            assert_invariant();
-        }
-
-        // add element to array
-        m_value.object->insert(val);
-    }
-
-    /*!
-    @brief add an object to an object
-    @copydoc push_back(const typename object_t::value_type&)
-    */
-    reference operator+=(const typename object_t::value_type& val)
+    size_type count(typename object_t::key_type key) const
     {
-        push_back(val);
-        return *this;
+        // return 0 for all nonobject types
+        return is_object() ? m_value.object->count(key) : 0;
     }
 
-    /*!
-    @brief add an object to an object
+    /// @}
 
-    This function allows to use `push_back` with an initializer list. In case
 
-    1. the current value is an object,
-    2. the initializer list @a init contains only two elements, and
-    3. the first element of @a init is a string,
+    ///////////////
+    // iterators //
+    ///////////////
 
-    @a init is converted into an object element and added using
-    @ref push_back(const typename object_t::value_type&). Otherwise, @a init
-    is converted to a JSON value and added using @ref push_back(basic_json&&).
+    /// @name iterators
+    /// @{
 
-    @param[in] init  an initializer list
+    /*!
+    @brief returns an iterator to the first element
 
-    @complexity Linear in the size of the initializer list @a init.
+    Returns an iterator to the first element.
 
-    @note This function is required to resolve an ambiguous overload error,
-          because pairs like `{"key", "value"}` can be both interpreted as
-          `object_t::value_type` or `std::initializer_list<basic_json>`, see
-          https://github.com/nlohmann/json/issues/235 for more information.
+    @image html range-begin-end.svg "Illustration from cppreference.com"
 
-    @liveexample{The example shows how initializer lists are treated as
-    objects when possible.,push_back__initializer_list}
+    @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
     */
-    void push_back(std::initializer_list<basic_json> init)
+    iterator begin() noexcept
     {
-        if (is_object() and init.size() == 2 and init.begin()->is_string())
-        {
-            const string_t key = *init.begin();
-            push_back(typename object_t::value_type(key, *(init.begin() + 1)));
-        }
-        else
-        {
-            push_back(basic_json(init));
-        }
+        iterator result(this);
+        result.set_begin();
+        return result;
     }
 
     /*!
-    @brief add an object to an object
-    @copydoc push_back(std::initializer_list<basic_json>)
+    @copydoc basic_json::cbegin()
     */
-    reference operator+=(std::initializer_list<basic_json> init)
+    const_iterator begin() const noexcept
     {
-        push_back(init);
-        return *this;
+        return cbegin();
     }
 
     /*!
-    @brief add an object to an array
+    @brief returns a const iterator to the first element
 
-    Creates a JSON value from the passed parameters @a args to the end of the
-    JSON value. If the function is called on a JSON null value, an empty array
-    is created before appending the value created from @a args.
+    Returns a const iterator to the first element.
 
-    @param[in] args arguments to forward to a constructor of @ref basic_json
-    @tparam Args compatible types to create a @ref basic_json object
+    @image html range-begin-end.svg "Illustration from cppreference.com"
 
-    @throw type_error.311 when called on a type other than JSON array or
-    null; example: `"cannot use emplace_back() with number"`
+    @return const iterator to the first element
 
-    @complexity Amortized constant.
+    @complexity Constant.
 
-    @liveexample{The example shows how `push_back()` can be used to add
-    elements to a JSON array. Note how the `null` value was silently converted
-    to a JSON array.,emplace_back}
+    @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()`.
 
-    @since version 2.0.8
-    */
-    template<class... Args>
-    void emplace_back(Args&& ... args)
-    {
-        // emplace_back only works for null objects or arrays
-        if (not(is_null() or is_array()))
-        {
-            JSON_THROW(type_error::create(311, "cannot use emplace_back() with " + type_name()));
-        }
+    @liveexample{The following code shows an example for `cbegin()`.,cbegin}
 
-        // transform null object into an array
-        if (is_null())
-        {
-            m_type = value_t::array;
-            m_value = value_t::array;
-            assert_invariant();
-        }
+    @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
 
-        // add element to array (perfect forwarding)
-        m_value.array->emplace_back(std::forward<Args>(args)...);
+    @since version 1.0.0
+    */
+    const_iterator cbegin() const noexcept
+    {
+        const_iterator result(this);
+        result.set_begin();
+        return result;
     }
 
     /*!
-    @brief add an object to an object if key does not exist
+    @brief returns an iterator to one past the last element
 
-    Inserts a new element into a JSON object constructed in-place with the
-    given @a args if there is no element with the key in the container. If the
-    function is called on a JSON null value, an empty object is created before
-    appending the value created from @a args.
+    Returns an iterator to one past the last element.
 
-    @param[in] args arguments to forward to a constructor of @ref basic_json
-    @tparam Args compatible types to create a @ref basic_json object
+    @image html range-begin-end.svg "Illustration from cppreference.com"
 
-    @return a pair consisting of an iterator to the inserted element, or the
-            already-existing element if no insertion happened, and a bool
-            denoting whether the insertion took place.
+    @return iterator one past the last element
 
-    @throw type_error.311 when called on a type other than JSON object or
-    null; example: `"cannot use emplace() with number"`
+    @complexity Constant.
 
-    @complexity Logarithmic in the size of the container, O(log(`size()`)).
+    @requirement This function helps `basic_json` satisfying the
+    [Container](http://en.cppreference.com/w/cpp/concept/Container)
+    requirements:
+    - The complexity is constant.
 
-    @liveexample{The example shows how `emplace()` can be used to add elements
-    to a JSON object. Note how the `null` value was silently converted to a
-    JSON object. Further note how no value is added if there was already one
-    value stored with the same key.,emplace}
+    @liveexample{The following code shows an example for `end()`.,end}
 
-    @since version 2.0.8
+    @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
     */
-    template<class... Args>
-    std::pair<iterator, bool> emplace(Args&& ... args)
+    iterator end() noexcept
     {
-        // emplace only works for null objects or arrays
-        if (not(is_null() or is_object()))
-        {
-            JSON_THROW(type_error::create(311, "cannot use emplace() with " + type_name()));
-        }
-
-        // transform null object into an object
-        if (is_null())
-        {
-            m_type = value_t::object;
-            m_value = value_t::object;
-            assert_invariant();
-        }
-
-        // add element to array (perfect forwarding)
-        auto res = m_value.object->emplace(std::forward<Args>(args)...);
-        // create result iterator and set iterator to the result of emplace
-        auto it = begin();
-        it.m_it.object_iterator = res.first;
-
-        // return pair of iterator and boolean
-        return {it, res.second};
+        iterator result(this);
+        result.set_end();
+        return result;
     }
 
     /*!
-    @brief inserts element
+    @copydoc basic_json::cend()
+    */
+    const_iterator end() const noexcept
+    {
+        return cend();
+    }
 
-    Inserts element @a val before iterator @a pos.
+    /*!
+    @brief returns a const iterator to one past the last element
 
-    @param[in] pos iterator before which the content will be inserted; may be
-    the end() iterator
-    @param[in] val element to insert
-    @return iterator pointing to the inserted @a val.
+    Returns a const iterator to one past the last element.
 
-    @throw type_error.309 if called on JSON values other than arrays;
-    example: `"cannot use insert() with string"`
-    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
-    example: `"iterator does not fit current value"`
+    @image html range-begin-end.svg "Illustration from cppreference.com"
 
-    @complexity Constant plus linear in the distance between @a pos and end of
-    the container.
+    @return const iterator one past the last element
 
-    @liveexample{The example shows how `insert()` is used.,insert}
+    @complexity Constant.
 
-    @since version 1.0.0
-    */
-    iterator insert(const_iterator pos, const basic_json& val)
-    {
-        // insert only works for arrays
-        if (is_array())
-        {
-            // check if iterator pos fits to this JSON value
-            if (pos.m_object != this)
-            {
-                JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
-            }
+    @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()`.
 
-            // insert to array and return iterator
-            iterator result(this);
-            result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, val);
-            return result;
-        }
+    @liveexample{The following code shows an example for `cend()`.,cend}
 
-        JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
-    }
+    @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
 
-    /*!
-    @brief inserts element
-    @copydoc insert(const_iterator, const basic_json&)
+    @since version 1.0.0
     */
-    iterator insert(const_iterator pos, basic_json&& val)
+    const_iterator cend() const noexcept
     {
-        return insert(pos, val);
+        const_iterator result(this);
+        result.set_end();
+        return result;
     }
 
     /*!
-    @brief inserts elements
-
-    Inserts @a cnt copies of @a val before iterator @a pos.
+    @brief returns an iterator to the reverse-beginning
 
-    @param[in] pos iterator before which the content will be inserted; may be
-    the end() iterator
-    @param[in] cnt number of copies of @a val to insert
-    @param[in] val element to insert
-    @return iterator pointing to the first element inserted, or @a pos if
-    `cnt==0`
+    Returns an iterator to the reverse-beginning; that is, the last element.
 
-    @throw type_error.309 if called on JSON values other than arrays; example:
-    `"cannot use insert() with string"`
-    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
-    example: `"iterator does not fit current value"`
+    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
 
-    @complexity Linear in @a cnt plus linear in the distance between @a pos
-    and end of the container.
+    @complexity Constant.
 
-    @liveexample{The example shows how `insert()` is used.,insert__count}
+    @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
     */
-    iterator insert(const_iterator pos, size_type cnt, const basic_json& val)
+    reverse_iterator rbegin() noexcept
     {
-        // insert only works for arrays
-        if (is_array())
-        {
-            // check if iterator pos fits to this JSON value
-            if (pos.m_object != this)
-            {
-                JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
-            }
-
-            // insert to array and return iterator
-            iterator result(this);
-            result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, cnt, val);
-            return result;
-        }
+        return reverse_iterator(end());
+    }
 
-        JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
+    /*!
+    @copydoc basic_json::crbegin()
+    */
+    const_reverse_iterator rbegin() const noexcept
+    {
+        return crbegin();
     }
 
     /*!
-    @brief inserts elements
+    @brief returns an iterator to the reverse-end
 
-    Inserts elements from range `[first, last)` before iterator @a pos.
+    Returns an iterator to the reverse-end; that is, one before the first
+    element.
 
-    @param[in] pos iterator before which the content will be inserted; may be
-    the end() iterator
-    @param[in] first begin of the range of elements to insert
-    @param[in] last end of the range of elements to insert
+    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
 
-    @throw type_error.309 if called on JSON values other than arrays; example:
-    `"cannot use insert() with string"`
-    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
-    example: `"iterator does not fit current value"`
-    @throw invalid_iterator.210 if @a first and @a last do not belong to the
-    same JSON value; example: `"iterators do not fit"`
-    @throw invalid_iterator.211 if @a first or @a last are iterators into
-    container for which insert is called; example: `"passed iterators may not
-    belong to container"`
+    @complexity Constant.
 
-    @return iterator pointing to the first element inserted, or @a pos if
-    `first==last`
+    @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())`.
 
-    @complexity Linear in `std::distance(first, last)` plus linear in the
-    distance between @a pos and end of the container.
+    @liveexample{The following code shows an example for `rend()`.,rend}
 
-    @liveexample{The example shows how `insert()` is used.,insert__range}
+    @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
     */
-    iterator insert(const_iterator pos, const_iterator first, const_iterator last)
+    reverse_iterator rend() noexcept
     {
-        // insert only works for arrays
-        if (not is_array())
-        {
-            JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
-        }
-
-        // check if iterator pos fits to this JSON value
-        if (pos.m_object != this)
-        {
-            JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
-        }
-
-        // check if range iterators belong to the same JSON object
-        if (first.m_object != last.m_object)
-        {
-            JSON_THROW(invalid_iterator::create(210, "iterators do not fit"));
-        }
-
-        if (first.m_object == this or last.m_object == this)
-        {
-            JSON_THROW(invalid_iterator::create(211, "passed iterators may not belong to container"));
-        }
+        return reverse_iterator(begin());
+    }
 
-        // insert to array and return iterator
-        iterator result(this);
-        result.m_it.array_iterator = m_value.array->insert(
-                                         pos.m_it.array_iterator,
-                                         first.m_it.array_iterator,
-                                         last.m_it.array_iterator);
-        return result;
+    /*!
+    @copydoc basic_json::crend()
+    */
+    const_reverse_iterator rend() const noexcept
+    {
+        return crend();
     }
 
     /*!
-    @brief inserts elements
+    @brief returns a const reverse iterator to the last element
 
-    Inserts elements from initializer list @a ilist before iterator @a pos.
+    Returns a const iterator to the reverse-beginning; that is, the last
+    element.
 
-    @param[in] pos iterator before which the content will be inserted; may be
-    the end() iterator
-    @param[in] ilist initializer list to insert the values from
+    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
 
-    @throw type_error.309 if called on JSON values other than arrays; example:
-    `"cannot use insert() with string"`
-    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
-    example: `"iterator does not fit current value"`
+    @complexity Constant.
 
-    @return iterator pointing to the first element inserted, or @a pos if
-    `ilist` is empty
+    @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()`.
 
-    @complexity Linear in `ilist.size()` plus linear in the distance between
-    @a pos and end of the container.
+    @liveexample{The following code shows an example for `crbegin()`.,crbegin}
 
-    @liveexample{The example shows how `insert()` is used.,insert__ilist}
+    @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
     */
-    iterator insert(const_iterator pos, std::initializer_list<basic_json> ilist)
+    const_reverse_iterator crbegin() const noexcept
     {
-        // insert only works for arrays
-        if (not is_array())
-        {
-            JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
-        }
-
-        // check if iterator pos fits to this JSON value
-        if (pos.m_object != this)
-        {
-            JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
-        }
-
-        // insert to array and return iterator
-        iterator result(this);
-        result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, ilist);
-        return result;
+        return const_reverse_iterator(cend());
     }
 
     /*!
-    @brief inserts elements
+    @brief returns a const reverse iterator to one before the first
 
-    Inserts elements from range `[first, last)`.
+    Returns a const reverse iterator to the reverse-end; that is, one before
+    the first element.
 
-    @param[in] first begin of the range of elements to insert
-    @param[in] last end of the range of elements to insert
+    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
 
-    @throw type_error.309 if called on JSON values other than objects; example:
-    `"cannot use insert() with string"`
-    @throw invalid_iterator.202 if iterator @a first or @a last does does not
-    point to an object; example: `"iterators first and last must point to
-    objects"`
-    @throw invalid_iterator.210 if @a first and @a last do not belong to the
-    same JSON value; example: `"iterators do not fit"`
+    @complexity Constant.
 
-    @complexity Logarithmic: `O(N*log(size() + N))`, where `N` is the number
-    of elements to insert.
+    @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 example shows how `insert()` is used.,insert__range_object}
+    @liveexample{The following code shows an example for `crend()`.,crend}
 
-    @since version 3.0.0
+    @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
     */
-    void insert(const_iterator first, const_iterator last)
+    const_reverse_iterator crend() const noexcept
     {
-        // insert only works for objects
-        if (not is_object())
-        {
-            JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
-        }
-
-        // check if range iterators belong to the same JSON object
-        if (first.m_object != last.m_object)
-        {
-            JSON_THROW(invalid_iterator::create(210, "iterators do not fit"));
-        }
-
-        // passed iterators must belong to objects
-        if (not first.m_object->is_object() or not first.m_object->is_object())
-        {
-            JSON_THROW(invalid_iterator::create(202, "iterators first and last must point to objects"));
-        }
-
-        m_value.object->insert(first.m_it.object_iterator, last.m_it.object_iterator);
+        return const_reverse_iterator(cbegin());
     }
 
+  public:
     /*!
-    @brief exchanges the values
-
-    Exchanges the contents of the JSON value with those of @a other. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated.
-
-    @param[in,out] other JSON value to exchange the contents with
+    @brief wrapper to access iterator member functions in range-based for
 
-    @complexity Constant.
+    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.
 
-    @liveexample{The example below shows how JSON values can be swapped with
-    `swap()`.,swap__reference}
+    @liveexample{The following code shows how the wrapper is used,iterator_wrapper}
 
-    @since version 1.0.0
+    @note The name of this function is not yet final and may change in the
+    future.
     */
-    void swap(reference other) noexcept (
-        std::is_nothrow_move_constructible<value_t>::value and
-        std::is_nothrow_move_assignable<value_t>::value and
-        std::is_nothrow_move_constructible<json_value>::value and
-        std::is_nothrow_move_assignable<json_value>::value
-    )
+    static iteration_proxy<iterator> iterator_wrapper(reference cont)
     {
-        std::swap(m_type, other.m_type);
-        std::swap(m_value, other.m_value);
-        assert_invariant();
+        return iteration_proxy<iterator>(cont);
     }
 
     /*!
-    @brief exchanges the values
+    @copydoc iterator_wrapper(reference)
+    */
+    static iteration_proxy<const_iterator> iterator_wrapper(const_reference cont)
+    {
+        return iteration_proxy<const_iterator>(cont);
+    }
 
-    Exchanges the contents of a JSON array with those of @a other. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated.
+    /// @}
 
-    @param[in,out] other array to exchange the contents with
 
-    @throw type_error.310 when JSON value is not an array; example: `"cannot
-    use swap() with string"`
+    //////////////
+    // capacity //
+    //////////////
 
-    @complexity Constant.
+    /// @name capacity
+    /// @{
 
-    @liveexample{The example below shows how arrays can be swapped with
-    `swap()`.,swap__array_t}
+    /*!
+    @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
     */
-    void swap(array_t& other)
+    bool empty() const noexcept
     {
-        // swap only works for arrays
-        if (is_array())
-        {
-            std::swap(*(m_value.array), other);
-        }
-        else
+        switch (m_type)
         {
-            JSON_THROW(type_error::create(310, "cannot use swap() with " + type_name()));
+            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 exchanges the values
+    @brief returns the number of elements
 
-    Exchanges the contents of a JSON object with those of @a other. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated.
+    Returns the number of elements in a JSON value.
 
-    @param[in,out] other object to exchange the contents with
+    @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()
 
-    @throw type_error.310 when JSON value is not an object; example:
-    `"cannot use swap() with string"`
+    @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.
+    @complexity Constant, as long as @ref array_t and @ref object_t satisfy
+    the Container concept; that is, their size() functions have constant
+    complexity.
 
-    @liveexample{The example below shows how objects can be swapped with
-    `swap()`.,swap__object_t}
+    @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
     */
-    void swap(object_t& other)
+    size_type size() const noexcept
     {
-        // swap only works for objects
-        if (is_object())
-        {
-            std::swap(*(m_value.object), other);
-        }
-        else
+        switch (m_type)
         {
-            JSON_THROW(type_error::create(310, "cannot use swap() with " + type_name()));
+            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 exchanges the values
+    @brief returns the maximum possible number of elements
 
-    Exchanges the contents of a JSON string with those of @a other. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated.
+    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.
 
-    @param[in,out] other string to exchange the contents with
+    @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()`
 
-    @throw type_error.310 when JSON value is not a string; example: `"cannot
-    use swap() with boolean"`
+    @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.
 
-    @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 returning `b.size()` where `b` is the largest
+      possible JSON value.
 
-    @liveexample{The example below shows how strings can be swapped with
-    `swap()`.,swap__string_t}
+    @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
     */
-    void swap(string_t& other)
+    size_type max_size() const noexcept
     {
-        // swap only works for strings
-        if (is_string())
-        {
-            std::swap(*(m_value.string), other);
-        }
-        else
+        switch (m_type)
         {
-            JSON_THROW(type_error::create(310, "cannot use swap() with " + type_name()));
+            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();
+            }
         }
     }
 
     /// @}
 
-  public:
-    //////////////////////////////////////////
-    // lexicographical comparison operators //
-    //////////////////////////////////////////
 
-    /// @name lexicographical comparison operators
+    ///////////////
+    // modifiers //
+    ///////////////
+
+    /// @name modifiers
     /// @{
 
     /*!
-    @brief comparison: equal
-
-    Compares two JSON values for equality according to the following rules:
-    - Two JSON values are equal if (1) they are from the same type and (2)
-      their stored values are the same according to their respective
-      `operator==`.
-    - Integer and floating-point numbers are automatically converted before
-      comparison. Note than two NaN values are always treated as unequal.
-    - Two JSON null values are equal.
+    @brief clears the contents
 
-    @note NaN values never compare equal to themselves or to other NaN values.
+    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:
 
-    @param[in] lhs  first JSON value to consider
-    @param[in] rhs  second JSON value to consider
-    @return whether the values @a lhs and @a rhs are equal
+    Value type  | initial value
+    ----------- | -------------
+    null        | `null`
+    boolean     | `false`
+    string      | `""`
+    number      | `0`
+    object      | `{}`
+    array       | `[]`
 
-    @complexity Linear.
+    @complexity Linear in the size of the JSON value.
 
-    @liveexample{The example demonstrates comparing several JSON
-    types.,operator__equal}
+    @liveexample{The example below shows the effect of `clear()` to different
+    JSON types.,clear}
 
     @since version 1.0.0
     */
-    friend bool operator==(const_reference lhs, const_reference rhs) noexcept
+    void clear() noexcept
     {
-        const auto lhs_type = lhs.type();
-        const auto rhs_type = rhs.type();
-
-        if (lhs_type == rhs_type)
+        switch (m_type)
         {
-            switch (lhs_type)
+            case value_t::number_integer:
             {
-                case value_t::array:
-                {
-                    return *lhs.m_value.array == *rhs.m_value.array;
-                }
-                case value_t::object:
-                {
-                    return *lhs.m_value.object == *rhs.m_value.object;
-                }
-                case value_t::null:
-                {
-                    return true;
-                }
-                case value_t::string:
-                {
-                    return *lhs.m_value.string == *rhs.m_value.string;
-                }
-                case value_t::boolean:
-                {
-                    return lhs.m_value.boolean == rhs.m_value.boolean;
-                }
-                case value_t::number_integer:
-                {
-                    return lhs.m_value.number_integer == rhs.m_value.number_integer;
-                }
-                case value_t::number_unsigned:
-                {
-                    return lhs.m_value.number_unsigned == rhs.m_value.number_unsigned;
-                }
-                case value_t::number_float:
-                {
-                    return lhs.m_value.number_float == rhs.m_value.number_float;
-                }
-                default:
-                {
-                    return false;
-                }
+                m_value.number_integer = 0;
+                break;
             }
-        }
-        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_float)
-        {
-            return static_cast<number_float_t>(lhs.m_value.number_integer) == rhs.m_value.number_float;
-        }
-        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_integer)
-        {
-            return lhs.m_value.number_float == static_cast<number_float_t>(rhs.m_value.number_integer);
-        }
-        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_float)
-        {
-            return static_cast<number_float_t>(lhs.m_value.number_unsigned) == rhs.m_value.number_float;
-        }
-        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_unsigned)
-        {
-            return lhs.m_value.number_float == static_cast<number_float_t>(rhs.m_value.number_unsigned);
-        }
-        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_integer)
-        {
-            return static_cast<number_integer_t>(lhs.m_value.number_unsigned) == rhs.m_value.number_integer;
-        }
-        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_unsigned)
-        {
-            return lhs.m_value.number_integer == static_cast<number_integer_t>(rhs.m_value.number_unsigned);
-        }
 
-        return false;
-    }
+            case value_t::number_unsigned:
+            {
+                m_value.number_unsigned = 0;
+                break;
+            }
 
-    /*!
-    @brief comparison: equal
-    @copydoc operator==(const_reference, const_reference)
-    */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator==(const_reference lhs, const ScalarType rhs) noexcept
-    {
-        return (lhs == basic_json(rhs));
-    }
+            case value_t::number_float:
+            {
+                m_value.number_float = 0.0;
+                break;
+            }
 
-    /*!
-    @brief comparison: equal
-    @copydoc operator==(const_reference, const_reference)
-    */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator==(const ScalarType lhs, const_reference rhs) noexcept
-    {
-        return (basic_json(lhs) == rhs);
+            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 comparison: not equal
+    @brief add an object to an array
 
-    Compares two JSON values for inequality by calculating `not (lhs == rhs)`.
+    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] lhs  first JSON value to consider
-    @param[in] rhs  second JSON value to consider
-    @return whether the values @a lhs and @a rhs are not equal
+    @param[in] val the value to add to the JSON array
 
-    @complexity Linear.
+    @throw type_error.308 when called on a type other than JSON array or
+    null; example: `"cannot use push_back() with number"`
 
-    @liveexample{The example demonstrates comparing several JSON
-    types.,operator__notequal}
+    @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
     */
-    friend bool operator!=(const_reference lhs, const_reference rhs) noexcept
+    void push_back(basic_json&& val)
     {
-        return not (lhs == rhs);
+        // push_back only works for null objects or arrays
+        if (not(is_null() or is_array()))
+        {
+            JSON_THROW(type_error::create(308, "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 comparison: not equal
-    @copydoc operator!=(const_reference, const_reference)
+    @brief add an object to an array
+    @copydoc push_back(basic_json&&)
     */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator!=(const_reference lhs, const ScalarType rhs) noexcept
+    reference operator+=(basic_json&& val)
     {
-        return (lhs != basic_json(rhs));
+        push_back(std::move(val));
+        return *this;
     }
 
     /*!
-    @brief comparison: not equal
-    @copydoc operator!=(const_reference, const_reference)
+    @brief add an object to an array
+    @copydoc push_back(basic_json&&)
     */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator!=(const ScalarType lhs, const_reference rhs) noexcept
+    void push_back(const basic_json& val)
     {
-        return (basic_json(lhs) != rhs);
+        // push_back only works for null objects or arrays
+        if (not(is_null() or is_array()))
+        {
+            JSON_THROW(type_error::create(308, "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
+        m_value.array->push_back(val);
     }
 
     /*!
-    @brief comparison: less than
+    @brief add an object to an array
+    @copydoc push_back(basic_json&&)
+    */
+    reference operator+=(const basic_json& val)
+    {
+        push_back(val);
+        return *this;
+    }
 
-    Compares whether one JSON value @a lhs is less than another JSON value @a
-    rhs according to the following rules:
-    - If @a lhs and @a rhs have the same type, the values are compared using
-      the default `<` operator.
-    - Integer and floating-point numbers are automatically converted before
-      comparison
-    - In case @a lhs and @a rhs have different types, the values are ignored
-      and the order of the types is considered, see
-      @ref operator<(const value_t, const value_t).
+    /*!
+    @brief add an object to an object
 
-    @param[in] lhs  first JSON value to consider
-    @param[in] rhs  second JSON value to consider
-    @return whether @a lhs is less than @a rhs
+    Inserts the given element @a val to the JSON object. If the function is
+    called on a JSON null value, an empty object is created before inserting
+    @a val.
 
-    @complexity Linear.
+    @param[in] val the value to add to the JSON object
 
-    @liveexample{The example demonstrates comparing several JSON
-    types.,operator__less}
+    @throw type_error.308 when called on a type other than JSON object or
+    null; example: `"cannot use push_back() with number"`
+
+    @complexity Logarithmic in the size of the container, O(log(`size()`)).
+
+    @liveexample{The example shows how `push_back()` and `+=` can be used to
+    add elements to a JSON object. Note how the `null` value was silently
+    converted to a JSON object.,push_back__object_t__value}
 
     @since version 1.0.0
     */
-    friend bool operator<(const_reference lhs, const_reference rhs) noexcept
+    void push_back(const typename object_t::value_type& val)
     {
-        const auto lhs_type = lhs.type();
-        const auto rhs_type = rhs.type();
+        // push_back only works for null objects or objects
+        if (not(is_null() or is_object()))
+        {
+            JSON_THROW(type_error::create(308, "cannot use push_back() with " + type_name()));
+        }
 
-        if (lhs_type == rhs_type)
+        // transform null object into an object
+        if (is_null())
         {
-            switch (lhs_type)
-            {
-                case value_t::array:
-                {
-                    return (*lhs.m_value.array) < (*rhs.m_value.array);
-                }
-                case value_t::object:
-                {
-                    return *lhs.m_value.object < *rhs.m_value.object;
-                }
-                case value_t::null:
-                {
-                    return false;
-                }
-                case value_t::string:
-                {
-                    return *lhs.m_value.string < *rhs.m_value.string;
-                }
-                case value_t::boolean:
-                {
-                    return lhs.m_value.boolean < rhs.m_value.boolean;
-                }
-                case value_t::number_integer:
-                {
-                    return lhs.m_value.number_integer < rhs.m_value.number_integer;
-                }
-                case value_t::number_unsigned:
-                {
-                    return lhs.m_value.number_unsigned < rhs.m_value.number_unsigned;
-                }
-                case value_t::number_float:
-                {
-                    return lhs.m_value.number_float < rhs.m_value.number_float;
-                }
-                default:
-                {
-                    return false;
-                }
-            }
-        }
-        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_float)
-        {
-            return static_cast<number_float_t>(lhs.m_value.number_integer) < rhs.m_value.number_float;
-        }
-        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_integer)
-        {
-            return lhs.m_value.number_float < static_cast<number_float_t>(rhs.m_value.number_integer);
-        }
-        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_float)
-        {
-            return static_cast<number_float_t>(lhs.m_value.number_unsigned) < rhs.m_value.number_float;
-        }
-        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_unsigned)
-        {
-            return lhs.m_value.number_float < static_cast<number_float_t>(rhs.m_value.number_unsigned);
-        }
-        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_unsigned)
-        {
-            return lhs.m_value.number_integer < static_cast<number_integer_t>(rhs.m_value.number_unsigned);
-        }
-        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_integer)
-        {
-            return static_cast<number_integer_t>(lhs.m_value.number_unsigned) < rhs.m_value.number_integer;
+            m_type = value_t::object;
+            m_value = value_t::object;
+            assert_invariant();
         }
 
-        // We only reach this line if we cannot compare values. In that case,
-        // we compare types. Note we have to call the operator explicitly,
-        // because MSVC has problems otherwise.
-        return operator<(lhs_type, rhs_type);
+        // add element to array
+        m_value.object->insert(val);
     }
 
     /*!
-    @brief comparison: less than
-    @copydoc operator<(const_reference, const_reference)
+    @brief add an object to an object
+    @copydoc push_back(const typename object_t::value_type&)
     */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator<(const_reference lhs, const ScalarType rhs) noexcept
+    reference operator+=(const typename object_t::value_type& val)
     {
-        return (lhs < basic_json(rhs));
+        push_back(val);
+        return *this;
     }
 
     /*!
-    @brief comparison: less than
-    @copydoc operator<(const_reference, const_reference)
-    */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator<(const ScalarType lhs, const_reference rhs) noexcept
-    {
-        return (basic_json(lhs) < rhs);
-    }
+    @brief add an object to an object
 
-    /*!
-    @brief comparison: less than or equal
+    This function allows to use `push_back` with an initializer list. In case
 
-    Compares whether one JSON value @a lhs is less than or equal to another
-    JSON value by calculating `not (rhs < lhs)`.
+    1. the current value is an object,
+    2. the initializer list @a init contains only two elements, and
+    3. the first element of @a init is a string,
 
-    @param[in] lhs  first JSON value to consider
-    @param[in] rhs  second JSON value to consider
-    @return whether @a lhs is less than or equal to @a rhs
+    @a init is converted into an object element and added using
+    @ref push_back(const typename object_t::value_type&). Otherwise, @a init
+    is converted to a JSON value and added using @ref push_back(basic_json&&).
 
-    @complexity Linear.
+    @param[in] init  an initializer list
 
-    @liveexample{The example demonstrates comparing several JSON
-    types.,operator__greater}
+    @complexity Linear in the size of the initializer list @a init.
 
-    @since version 1.0.0
-    */
-    friend bool operator<=(const_reference lhs, const_reference rhs) noexcept
-    {
-        return not (rhs < lhs);
-    }
+    @note This function is required to resolve an ambiguous overload error,
+          because pairs like `{"key", "value"}` can be both interpreted as
+          `object_t::value_type` or `std::initializer_list<basic_json>`, see
+          https://github.com/nlohmann/json/issues/235 for more information.
 
-    /*!
-    @brief comparison: less than or equal
-    @copydoc operator<=(const_reference, const_reference)
+    @liveexample{The example shows how initializer lists are treated as
+    objects when possible.,push_back__initializer_list}
     */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator<=(const_reference lhs, const ScalarType rhs) noexcept
+    void push_back(std::initializer_list<basic_json> init)
     {
-        return (lhs <= basic_json(rhs));
+        if (is_object() and init.size() == 2 and init.begin()->is_string())
+        {
+            const string_t key = *init.begin();
+            push_back(typename object_t::value_type(key, *(init.begin() + 1)));
+        }
+        else
+        {
+            push_back(basic_json(init));
+        }
     }
 
     /*!
-    @brief comparison: less than or equal
-    @copydoc operator<=(const_reference, const_reference)
+    @brief add an object to an object
+    @copydoc push_back(std::initializer_list<basic_json>)
     */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator<=(const ScalarType lhs, const_reference rhs) noexcept
+    reference operator+=(std::initializer_list<basic_json> init)
     {
-        return (basic_json(lhs) <= rhs);
+        push_back(init);
+        return *this;
     }
 
     /*!
-    @brief comparison: greater than
+    @brief add an object to an array
 
-    Compares whether one JSON value @a lhs is greater than another
-    JSON value by calculating `not (lhs <= rhs)`.
+    Creates a JSON value from the passed parameters @a args to the end of the
+    JSON value. If the function is called on a JSON null value, an empty array
+    is created before appending the value created from @a args.
 
-    @param[in] lhs  first JSON value to consider
-    @param[in] rhs  second JSON value to consider
-    @return whether @a lhs is greater than to @a rhs
+    @param[in] args arguments to forward to a constructor of @ref basic_json
+    @tparam Args compatible types to create a @ref basic_json object
 
-    @complexity Linear.
+    @throw type_error.311 when called on a type other than JSON array or
+    null; example: `"cannot use emplace_back() with number"`
 
-    @liveexample{The example demonstrates comparing several JSON
-    types.,operator__lessequal}
+    @complexity Amortized constant.
 
-    @since version 1.0.0
-    */
-    friend bool operator>(const_reference lhs, const_reference rhs) noexcept
-    {
-        return not (lhs <= rhs);
-    }
+    @liveexample{The example shows how `push_back()` can be used to add
+    elements to a JSON array. Note how the `null` value was silently converted
+    to a JSON array.,emplace_back}
 
-    /*!
-    @brief comparison: greater than
-    @copydoc operator>(const_reference, const_reference)
+    @since version 2.0.8
     */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator>(const_reference lhs, const ScalarType rhs) noexcept
+    template<class... Args>
+    void emplace_back(Args&& ... args)
     {
-        return (lhs > basic_json(rhs));
-    }
+        // emplace_back only works for null objects or arrays
+        if (not(is_null() or is_array()))
+        {
+            JSON_THROW(type_error::create(311, "cannot use emplace_back() with " + type_name()));
+        }
 
-    /*!
-    @brief comparison: greater than
-    @copydoc operator>(const_reference, const_reference)
-    */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator>(const ScalarType lhs, const_reference rhs) noexcept
-    {
-        return (basic_json(lhs) > rhs);
+        // 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 (perfect forwarding)
+        m_value.array->emplace_back(std::forward<Args>(args)...);
     }
 
     /*!
-    @brief comparison: greater than or equal
+    @brief add an object to an object if key does not exist
 
-    Compares whether one JSON value @a lhs is greater than or equal to another
-    JSON value by calculating `not (lhs < rhs)`.
+    Inserts a new element into a JSON object constructed in-place with the
+    given @a args if there is no element with the key in the container. If the
+    function is called on a JSON null value, an empty object is created before
+    appending the value created from @a args.
 
-    @param[in] lhs  first JSON value to consider
-    @param[in] rhs  second JSON value to consider
-    @return whether @a lhs is greater than or equal to @a rhs
+    @param[in] args arguments to forward to a constructor of @ref basic_json
+    @tparam Args compatible types to create a @ref basic_json object
 
-    @complexity Linear.
+    @return a pair consisting of an iterator to the inserted element, or the
+            already-existing element if no insertion happened, and a bool
+            denoting whether the insertion took place.
 
-    @liveexample{The example demonstrates comparing several JSON
-    types.,operator__greaterequal}
+    @throw type_error.311 when called on a type other than JSON object or
+    null; example: `"cannot use emplace() with number"`
 
-    @since version 1.0.0
-    */
-    friend bool operator>=(const_reference lhs, const_reference rhs) noexcept
-    {
-        return not (lhs < rhs);
-    }
+    @complexity Logarithmic in the size of the container, O(log(`size()`)).
 
-    /*!
-    @brief comparison: greater than or equal
-    @copydoc operator>=(const_reference, const_reference)
+    @liveexample{The example shows how `emplace()` can be used to add elements
+    to a JSON object. Note how the `null` value was silently converted to a
+    JSON object. Further note how no value is added if there was already one
+    value stored with the same key.,emplace}
+
+    @since version 2.0.8
     */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator>=(const_reference lhs, const ScalarType rhs) noexcept
+    template<class... Args>
+    std::pair<iterator, bool> emplace(Args&& ... args)
     {
-        return (lhs >= basic_json(rhs));
+        // emplace only works for null objects or arrays
+        if (not(is_null() or is_object()))
+        {
+            JSON_THROW(type_error::create(311, "cannot use emplace() with " + type_name()));
+        }
+
+        // transform null object into an object
+        if (is_null())
+        {
+            m_type = value_t::object;
+            m_value = value_t::object;
+            assert_invariant();
+        }
+
+        // add element to array (perfect forwarding)
+        auto res = m_value.object->emplace(std::forward<Args>(args)...);
+        // create result iterator and set iterator to the result of emplace
+        auto it = begin();
+        it.m_it.object_iterator = res.first;
+
+        // return pair of iterator and boolean
+        return {it, res.second};
     }
 
     /*!
-    @brief comparison: greater than or equal
-    @copydoc operator>=(const_reference, const_reference)
-    */
-    template<typename ScalarType, typename std::enable_if<
-                 std::is_scalar<ScalarType>::value, int>::type = 0>
-    friend bool operator>=(const ScalarType lhs, const_reference rhs) noexcept
-    {
-        return (basic_json(lhs) >= rhs);
-    }
+    @brief inserts element
 
-    /// @}
+    Inserts element @a val before iterator @a pos.
 
-  private:
-    /////////////////////
-    // output adapters //
-    /////////////////////
+    @param[in] pos iterator before which the content will be inserted; may be
+    the end() iterator
+    @param[in] val element to insert
+    @return iterator pointing to the inserted @a val.
 
-    /// abstract output adapter interface
-    template<typename CharType>
-    class output_adapter
-    {
-      public:
-        virtual void write_character(CharType c) = 0;
-        virtual void write_characters(const CharType* s, size_t length) = 0;
-        virtual ~output_adapter() {}
+    @throw type_error.309 if called on JSON values other than arrays;
+    example: `"cannot use insert() with string"`
+    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
+    example: `"iterator does not fit current value"`
 
-        static std::shared_ptr<output_adapter<CharType>> create(std::vector<CharType>& vec)
-        {
-            return std::make_shared<output_vector_adapter<CharType>>(vec);
-        }
+    @complexity Constant plus linear in the distance between @a pos and end of
+    the container.
 
-        static std::shared_ptr<output_adapter<CharType>> create(std::ostream& s)
-        {
-            return std::make_shared<output_stream_adapter<CharType>>(s);
-        }
+    @liveexample{The example shows how `insert()` is used.,insert}
 
-        static std::shared_ptr<output_adapter<CharType>> create(std::string& s)
+    @since version 1.0.0
+    */
+    iterator insert(const_iterator pos, const basic_json& val)
+    {
+        // insert only works for arrays
+        if (is_array())
         {
-            return std::make_shared<output_string_adapter<CharType>>(s);
+            // check if iterator pos fits to this JSON value
+            if (pos.m_object != this)
+            {
+                JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
+            }
+
+            // insert to array and return iterator
+            iterator result(this);
+            result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, val);
+            return result;
         }
-    };
 
-    /// a type to simplify interfaces
-    template<typename CharType>
-    using output_adapter_t = std::shared_ptr<output_adapter<CharType>>;
+        JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
+    }
 
-    /// output adapter for byte vectors
-    template<typename CharType>
-    class output_vector_adapter : public output_adapter<CharType>
+    /*!
+    @brief inserts element
+    @copydoc insert(const_iterator, const basic_json&)
+    */
+    iterator insert(const_iterator pos, basic_json&& val)
     {
-      public:
-        output_vector_adapter(std::vector<CharType>& vec)
-            : v(vec)
-        {}
+        return insert(pos, val);
+    }
 
-        void write_character(CharType c) override
-        {
-            v.push_back(c);
-        }
+    /*!
+    @brief inserts elements
+
+    Inserts @a cnt copies of @a val before iterator @a pos.
+
+    @param[in] pos iterator before which the content will be inserted; may be
+    the end() iterator
+    @param[in] cnt number of copies of @a val to insert
+    @param[in] val element to insert
+    @return iterator pointing to the first element inserted, or @a pos if
+    `cnt==0`
 
-        void write_characters(const CharType* s, size_t length) override
+    @throw type_error.309 if called on JSON values other than arrays; example:
+    `"cannot use insert() with string"`
+    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
+    example: `"iterator does not fit current value"`
+
+    @complexity Linear in @a cnt plus linear in the distance between @a pos
+    and end of the container.
+
+    @liveexample{The example shows how `insert()` is used.,insert__count}
+
+    @since version 1.0.0
+    */
+    iterator insert(const_iterator pos, size_type cnt, const basic_json& val)
+    {
+        // insert only works for arrays
+        if (is_array())
         {
-            std::copy(s, s + length, std::back_inserter(v));
+            // check if iterator pos fits to this JSON value
+            if (pos.m_object != this)
+            {
+                JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
+            }
+
+            // insert to array and return iterator
+            iterator result(this);
+            result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, cnt, val);
+            return result;
         }
 
-      private:
-        std::vector<CharType>& v;
-    };
+        JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
+    }
 
-    /// output adapter for output streams
-    template<typename CharType>
-    class output_stream_adapter : public output_adapter<CharType>
-    {
-      public:
-        output_stream_adapter(std::basic_ostream<CharType>& s)
-            : stream(s)
-        {}
+    /*!
+    @brief inserts elements
+
+    Inserts elements from range `[first, last)` before iterator @a pos.
+
+    @param[in] pos iterator before which the content will be inserted; may be
+    the end() iterator
+    @param[in] first begin of the range of elements to insert
+    @param[in] last end of the range of elements to insert
+
+    @throw type_error.309 if called on JSON values other than arrays; example:
+    `"cannot use insert() with string"`
+    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
+    example: `"iterator does not fit current value"`
+    @throw invalid_iterator.210 if @a first and @a last do not belong to the
+    same JSON value; example: `"iterators do not fit"`
+    @throw invalid_iterator.211 if @a first or @a last are iterators into
+    container for which insert is called; example: `"passed iterators may not
+    belong to container"`
+
+    @return iterator pointing to the first element inserted, or @a pos if
+    `first==last`
+
+    @complexity Linear in `std::distance(first, last)` plus linear in the
+    distance between @a pos and end of the container.
+
+    @liveexample{The example shows how `insert()` is used.,insert__range}
 
-        void write_character(CharType c) override
+    @since version 1.0.0
+    */
+    iterator insert(const_iterator pos, const_iterator first, const_iterator last)
+    {
+        // insert only works for arrays
+        if (not is_array())
         {
-            stream.put(c);
+            JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
         }
 
-        void write_characters(const CharType* s, size_t length) override
+        // check if iterator pos fits to this JSON value
+        if (pos.m_object != this)
         {
-            stream.write(s, static_cast<std::streamsize>(length));
+            JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
         }
 
-      private:
-        std::basic_ostream<CharType>& stream;
-    };
-
-    /// output adapter for basic_string
-    template<typename CharType>
-    class output_string_adapter : public output_adapter<CharType>
-    {
-      public:
-        output_string_adapter(std::string& s)
-            : str(s)
-        {}
-
-        void write_character(CharType c) override
+        // check if range iterators belong to the same JSON object
+        if (first.m_object != last.m_object)
         {
-            str.push_back(c);
+            JSON_THROW(invalid_iterator::create(210, "iterators do not fit"));
         }
 
-        void write_characters(const CharType* s, size_t length) override
+        if (first.m_object == this or last.m_object == this)
         {
-            str.append(s, length);
+            JSON_THROW(invalid_iterator::create(211, "passed iterators may not belong to container"));
         }
 
-      private:
-        std::basic_string<CharType>& str;
-    };
+        // insert to array and return iterator
+        iterator result(this);
+        result.m_it.array_iterator = m_value.array->insert(
+                                         pos.m_it.array_iterator,
+                                         first.m_it.array_iterator,
+                                         last.m_it.array_iterator);
+        return result;
+    }
 
+    /*!
+    @brief inserts elements
 
-    ///////////////////
-    // serialization //
-    ///////////////////
+    Inserts elements from initializer list @a ilist before iterator @a pos.
 
-    /// @name serialization
-    /// @{
+    @param[in] pos iterator before which the content will be inserted; may be
+    the end() iterator
+    @param[in] ilist initializer list to insert the values from
 
-  private:
-    /*!
-    @brief wrapper around the serialization functions
+    @throw type_error.309 if called on JSON values other than arrays; example:
+    `"cannot use insert() with string"`
+    @throw invalid_iterator.202 if @a pos is not an iterator of *this;
+    example: `"iterator does not fit current value"`
+
+    @return iterator pointing to the first element inserted, or @a pos if
+    `ilist` is empty
+
+    @complexity Linear in `ilist.size()` plus linear in the distance between
+    @a pos and end of the container.
+
+    @liveexample{The example shows how `insert()` is used.,insert__ilist}
+
+    @since version 1.0.0
     */
-    class serializer
+    iterator insert(const_iterator pos, std::initializer_list<basic_json> ilist)
     {
-      public:
-        /*!
-        @param[in] s  output stream to serialize to
-        @param[in] ichar  indentation character to use
-        */
-        serializer(output_adapter_t<char> s, const char ichar)
-            : o(s), loc(std::localeconv()),
-              thousands_sep(!loc->thousands_sep ? '\0' : loc->thousands_sep[0]),
-              decimal_point(!loc->decimal_point ? '\0' : loc->decimal_point[0]),
-              indent_char(ichar), indent_string(512, indent_char)
-        {}
+        // insert only works for arrays
+        if (not is_array())
+        {
+            JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
+        }
 
-        // delete because of pointer members
-        serializer(const serializer&) = delete;
-        serializer& operator=(const serializer&) = delete;
+        // check if iterator pos fits to this JSON value
+        if (pos.m_object != this)
+        {
+            JSON_THROW(invalid_iterator::create(202, "iterator does not fit current value"));
+        }
 
-        /*!
-        @brief internal implementation of the serialization function
+        // insert to array and return iterator
+        iterator result(this);
+        result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, ilist);
+        return result;
+    }
 
-        This function is called by the public member function dump and
-        organizes the serialization internally. The indentation level is
-        propagated as additional parameter. In case of arrays and objects, the
-        function is called recursively.
+    /*!
+    @brief inserts elements
 
-        - strings and object keys are escaped using `escape_string()`
-        - integer numbers are converted implicitly via `operator<<`
-        - floating-point numbers are converted to a string using `"%g"` format
+    Inserts elements from range `[first, last)`.
 
-        @param[in] val             value to serialize
-        @param[in] pretty_print    whether the output shall be pretty-printed
-        @param[in] indent_step     the indent level
-        @param[in] current_indent  the current indent level (only used internally)
-        */
-        void dump(const basic_json& val,
-                  const bool pretty_print,
-                  const unsigned int indent_step,
-                  const unsigned int current_indent = 0)
-        {
-            switch (val.m_type)
-            {
-                case value_t::object:
-                {
-                    if (val.m_value.object->empty())
-                    {
-                        o->write_characters("{}", 2);
-                        return;
-                    }
+    @param[in] first begin of the range of elements to insert
+    @param[in] last end of the range of elements to insert
 
-                    if (pretty_print)
-                    {
-                        o->write_characters("{\n", 2);
+    @throw type_error.309 if called on JSON values other than objects; example:
+    `"cannot use insert() with string"`
+    @throw invalid_iterator.202 if iterator @a first or @a last does does not
+    point to an object; example: `"iterators first and last must point to
+    objects"`
+    @throw invalid_iterator.210 if @a first and @a last do not belong to the
+    same JSON value; example: `"iterators do not fit"`
 
-                        // variable to hold indentation for recursive calls
-                        const auto new_indent = current_indent + indent_step;
-                        if (JSON_UNLIKELY(indent_string.size() < new_indent))
-                        {
-                            indent_string.resize(indent_string.size() * 2, ' ');
-                        }
+    @complexity Logarithmic: `O(N*log(size() + N))`, where `N` is the number
+    of elements to insert.
 
-                        // first n-1 elements
-                        auto i = val.m_value.object->cbegin();
-                        for (size_t cnt = 0; cnt < val.m_value.object->size() - 1; ++cnt, ++i)
-                        {
-                            o->write_characters(indent_string.c_str(), new_indent);
-                            o->write_character('\"');
-                            dump_escaped(i->first);
-                            o->write_characters("\": ", 3);
-                            dump(i->second, true, indent_step, new_indent);
-                            o->write_characters(",\n", 2);
-                        }
+    @liveexample{The example shows how `insert()` is used.,insert__range_object}
 
-                        // last element
-                        assert(i != val.m_value.object->cend());
-                        o->write_characters(indent_string.c_str(), new_indent);
-                        o->write_character('\"');
-                        dump_escaped(i->first);
-                        o->write_characters("\": ", 3);
-                        dump(i->second, true, indent_step, new_indent);
+    @since version 3.0.0
+    */
+    void insert(const_iterator first, const_iterator last)
+    {
+        // insert only works for objects
+        if (not is_object())
+        {
+            JSON_THROW(type_error::create(309, "cannot use insert() with " + type_name()));
+        }
 
-                        o->write_character('\n');
-                        o->write_characters(indent_string.c_str(), current_indent);
-                        o->write_character('}');
-                    }
-                    else
-                    {
-                        o->write_character('{');
+        // check if range iterators belong to the same JSON object
+        if (first.m_object != last.m_object)
+        {
+            JSON_THROW(invalid_iterator::create(210, "iterators do not fit"));
+        }
 
-                        // first n-1 elements
-                        auto i = val.m_value.object->cbegin();
-                        for (size_t cnt = 0; cnt < val.m_value.object->size() - 1; ++cnt, ++i)
-                        {
-                            o->write_character('\"');
-                            dump_escaped(i->first);
-                            o->write_characters("\":", 2);
-                            dump(i->second, false, indent_step, current_indent);
-                            o->write_character(',');
-                        }
+        // passed iterators must belong to objects
+        if (not first.m_object->is_object() or not first.m_object->is_object())
+        {
+            JSON_THROW(invalid_iterator::create(202, "iterators first and last must point to objects"));
+        }
 
-                        // last element
-                        assert(i != val.m_value.object->cend());
-                        o->write_character('\"');
-                        dump_escaped(i->first);
-                        o->write_characters("\":", 2);
-                        dump(i->second, false, indent_step, current_indent);
+        m_value.object->insert(first.m_it.object_iterator, last.m_it.object_iterator);
+    }
 
-                        o->write_character('}');
-                    }
+    /*!
+    @brief exchanges the values
 
-                    return;
-                }
+    Exchanges the contents of the JSON value with those of @a other. Does not
+    invoke any move, copy, or swap operations on individual elements. All
+    iterators and references remain valid. The past-the-end iterator is
+    invalidated.
 
-                case value_t::array:
-                {
-                    if (val.m_value.array->empty())
-                    {
-                        o->write_characters("[]", 2);
-                        return;
-                    }
+    @param[in,out] other JSON value to exchange the contents with
 
-                    if (pretty_print)
-                    {
-                        o->write_characters("[\n", 2);
+    @complexity Constant.
 
-                        // variable to hold indentation for recursive calls
-                        const auto new_indent = current_indent + indent_step;
-                        if (indent_string.size() < new_indent)
-                        {
-                            indent_string.resize(new_indent, ' ');
-                        }
+    @liveexample{The example below shows how JSON values can be swapped with
+    `swap()`.,swap__reference}
 
-                        // first n-1 elements
-                        for (auto i = val.m_value.array->cbegin(); i != val.m_value.array->cend() - 1; ++i)
-                        {
-                            o->write_characters(indent_string.c_str(), new_indent);
-                            dump(*i, true, indent_step, new_indent);
-                            o->write_characters(",\n", 2);
-                        }
+    @since version 1.0.0
+    */
+    void swap(reference other) noexcept (
+        std::is_nothrow_move_constructible<value_t>::value and
+        std::is_nothrow_move_assignable<value_t>::value and
+        std::is_nothrow_move_constructible<json_value>::value and
+        std::is_nothrow_move_assignable<json_value>::value
+    )
+    {
+        std::swap(m_type, other.m_type);
+        std::swap(m_value, other.m_value);
+        assert_invariant();
+    }
 
-                        // last element
-                        assert(not val.m_value.array->empty());
-                        o->write_characters(indent_string.c_str(), new_indent);
-                        dump(val.m_value.array->back(), true, indent_step, new_indent);
+    /*!
+    @brief exchanges the values
 
-                        o->write_character('\n');
-                        o->write_characters(indent_string.c_str(), current_indent);
-                        o->write_character(']');
-                    }
-                    else
-                    {
-                        o->write_character('[');
+    Exchanges the contents of a JSON array with those of @a other. Does not
+    invoke any move, copy, or swap operations on individual elements. All
+    iterators and references remain valid. The past-the-end iterator is
+    invalidated.
 
-                        // first n-1 elements
-                        for (auto i = val.m_value.array->cbegin(); i != val.m_value.array->cend() - 1; ++i)
-                        {
-                            dump(*i, false, indent_step, current_indent);
-                            o->write_character(',');
-                        }
+    @param[in,out] other array to exchange the contents with
 
-                        // last element
-                        assert(not val.m_value.array->empty());
-                        dump(val.m_value.array->back(), false, indent_step, current_indent);
+    @throw type_error.310 when JSON value is not an array; example: `"cannot
+    use swap() with string"`
 
-                        o->write_character(']');
-                    }
+    @complexity Constant.
 
-                    return;
-                }
+    @liveexample{The example below shows how arrays can be swapped with
+    `swap()`.,swap__array_t}
 
-                case value_t::string:
-                {
-                    o->write_character('\"');
-                    dump_escaped(*val.m_value.string);
-                    o->write_character('\"');
-                    return;
-                }
+    @since version 1.0.0
+    */
+    void swap(array_t& other)
+    {
+        // swap only works for arrays
+        if (is_array())
+        {
+            std::swap(*(m_value.array), other);
+        }
+        else
+        {
+            JSON_THROW(type_error::create(310, "cannot use swap() with " + type_name()));
+        }
+    }
 
-                case value_t::boolean:
-                {
-                    if (val.m_value.boolean)
-                    {
-                        o->write_characters("true", 4);
-                    }
-                    else
-                    {
-                        o->write_characters("false", 5);
-                    }
-                    return;
-                }
+    /*!
+    @brief exchanges the values
 
-                case value_t::number_integer:
-                {
-                    dump_integer(val.m_value.number_integer);
-                    return;
-                }
+    Exchanges the contents of a JSON object with those of @a other. Does not
+    invoke any move, copy, or swap operations on individual elements. All
+    iterators and references remain valid. The past-the-end iterator is
+    invalidated.
 
-                case value_t::number_unsigned:
-                {
-                    dump_integer(val.m_value.number_unsigned);
-                    return;
-                }
+    @param[in,out] other object to exchange the contents with
 
-                case value_t::number_float:
-                {
-                    dump_float(val.m_value.number_float);
-                    return;
-                }
+    @throw type_error.310 when JSON value is not an object; example:
+    `"cannot use swap() with string"`
 
-                case value_t::discarded:
-                {
-                    o->write_characters("<discarded>", 11);
-                    return;
-                }
+    @complexity Constant.
 
-                case value_t::null:
-                {
-                    o->write_characters("null", 4);
-                    return;
-                }
-            }
-        }
-
-      private:
-        /*!
-        @brief calculates the extra space to escape a JSON string
-
-        @param[in] s  the string to escape
-        @return the number of characters required to escape string @a s
-
-        @complexity Linear in the length of string @a s.
-        */
-        static std::size_t extra_space(const string_t& s) noexcept
-        {
-            return std::accumulate(s.begin(), s.end(), size_t{},
-                                   [](size_t res, typename string_t::value_type c)
-            {
-                switch (c)
-                {
-                    case '"':
-                    case '\\':
-                    case '\b':
-                    case '\f':
-                    case '\n':
-                    case '\r':
-                    case '\t':
-                    {
-                        // from c (1 byte) to \x (2 bytes)
-                        return res + 1;
-                    }
-
-                    case 0x00:
-                    case 0x01:
-                    case 0x02:
-                    case 0x03:
-                    case 0x04:
-                    case 0x05:
-                    case 0x06:
-                    case 0x07:
-                    case 0x0b:
-                    case 0x0e:
-                    case 0x0f:
-                    case 0x10:
-                    case 0x11:
-                    case 0x12:
-                    case 0x13:
-                    case 0x14:
-                    case 0x15:
-                    case 0x16:
-                    case 0x17:
-                    case 0x18:
-                    case 0x19:
-                    case 0x1a:
-                    case 0x1b:
-                    case 0x1c:
-                    case 0x1d:
-                    case 0x1e:
-                    case 0x1f:
-                    {
-                        // from c (1 byte) to \uxxxx (6 bytes)
-                        return res + 5;
-                    }
-
-                    default:
-                    {
-                        return res;
-                    }
-                }
-            });
-        }
-
-        /*!
-        @brief dump escaped string
-
-        Escape a string by replacing certain special characters by a sequence
-        of an escape character (backslash) and another character and other
-        control characters by a sequence of "\u" followed by a four-digit hex
-        representation. The escaped string is written to output stream @a o.
-
-        @param[in] s  the string to escape
-
-        @complexity Linear in the length of string @a s.
-        */
-        void dump_escaped(const string_t& s) const
-        {
-            const auto space = extra_space(s);
-            if (space == 0)
-            {
-                o->write_characters(s.c_str(), s.size());
-                return;
-            }
-
-            // create a result string of necessary size
-            string_t result(s.size() + space, '\\');
-            std::size_t pos = 0;
-
-            for (const auto& c : s)
-            {
-                switch (c)
-                {
-                    // quotation mark (0x22)
-                    case '"':
-                    {
-                        result[pos + 1] = '"';
-                        pos += 2;
-                        break;
-                    }
-
-                    // reverse solidus (0x5c)
-                    case '\\':
-                    {
-                        // nothing to change
-                        pos += 2;
-                        break;
-                    }
-
-                    // backspace (0x08)
-                    case '\b':
-                    {
-                        result[pos + 1] = 'b';
-                        pos += 2;
-                        break;
-                    }
-
-                    // formfeed (0x0c)
-                    case '\f':
-                    {
-                        result[pos + 1] = 'f';
-                        pos += 2;
-                        break;
-                    }
-
-                    // newline (0x0a)
-                    case '\n':
-                    {
-                        result[pos + 1] = 'n';
-                        pos += 2;
-                        break;
-                    }
-
-                    // carriage return (0x0d)
-                    case '\r':
-                    {
-                        result[pos + 1] = 'r';
-                        pos += 2;
-                        break;
-                    }
-
-                    // horizontal tab (0x09)
-                    case '\t':
-                    {
-                        result[pos + 1] = 't';
-                        pos += 2;
-                        break;
-                    }
-
-                    case 0x00:
-                    case 0x01:
-                    case 0x02:
-                    case 0x03:
-                    case 0x04:
-                    case 0x05:
-                    case 0x06:
-                    case 0x07:
-                    case 0x0b:
-                    case 0x0e:
-                    case 0x0f:
-                    case 0x10:
-                    case 0x11:
-                    case 0x12:
-                    case 0x13:
-                    case 0x14:
-                    case 0x15:
-                    case 0x16:
-                    case 0x17:
-                    case 0x18:
-                    case 0x19:
-                    case 0x1a:
-                    case 0x1b:
-                    case 0x1c:
-                    case 0x1d:
-                    case 0x1e:
-                    case 0x1f:
-                    {
-                        // convert a number 0..15 to its hex representation
-                        // (0..f)
-                        static const char hexify[16] =
-                        {
-                            '0', '1', '2', '3', '4', '5', '6', '7',
-                            '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'
-                        };
-
-                        // print character c as \uxxxx
-                        for (const char m :
-                    { 'u', '0', '0', hexify[c >> 4], hexify[c & 0x0f]
-                        })
-                        {
-                            result[++pos] = m;
-                        }
-
-                        ++pos;
-                        break;
-                    }
-
-                    default:
-                    {
-                        // all other characters are added as-is
-                        result[pos++] = c;
-                        break;
-                    }
-                }
-            }
-
-            assert(pos == s.size() + space);
-            o->write_characters(result.c_str(), result.size());
-        }
-
-        /*!
-        @brief dump an integer
-
-        Dump a given integer to output stream @a o. Works internally with
-        @a number_buffer.
-
-        @param[in] x  integer number (signed or unsigned) to dump
-        @tparam NumberType either @a number_integer_t or @a number_unsigned_t
-        */
-        template<typename NumberType, detail::enable_if_t <
-                     std::is_same<NumberType, number_unsigned_t>::value or
-                     std::is_same<NumberType, number_integer_t>::value, int> = 0>
-        void dump_integer(NumberType x)
-        {
-            // special case for "0"
-            if (x == 0)
-            {
-                o->write_character('0');
-                return;
-            }
-
-            const bool is_negative = x < 0;
-            size_t i = 0;
-
-            // spare 1 byte for '\0'
-            while (x != 0 and i < number_buffer.size() - 1)
-            {
-                const auto digit = std::labs(static_cast<long>(x % 10));
-                number_buffer[i++] = static_cast<char>('0' + digit);
-                x /= 10;
-            }
-
-            // make sure the number has been processed completely
-            assert(x == 0);
-
-            if (is_negative)
-            {
-                // make sure there is capacity for the '-'
-                assert(i < number_buffer.size() - 2);
-                number_buffer[i++] = '-';
-            }
-
-            std::reverse(number_buffer.begin(), number_buffer.begin() + i);
-            o->write_characters(number_buffer.data(), i);
-        }
-
-        /*!
-        @brief dump a floating-point number
-
-        Dump a given floating-point number to output stream @a o. Works
-        internally with @a number_buffer.
-
-        @param[in] x  floating-point number to dump
-        */
-        void dump_float(number_float_t x)
-        {
-            // NaN / inf
-            if (not std::isfinite(x) or std::isnan(x))
-            {
-                o->write_characters("null", 4);
-                return;
-            }
-
-            // special case for 0.0 and -0.0
-            if (x == 0)
-            {
-                if (std::signbit(x))
-                {
-                    o->write_characters("-0.0", 4);
-                }
-                else
-                {
-                    o->write_characters("0.0", 3);
-                }
-                return;
-            }
-
-            // get number of digits for a text -> float -> text round-trip
-            static constexpr auto d = std::numeric_limits<number_float_t>::digits10;
-
-            // the actual conversion
-            std::ptrdiff_t len = snprintf(number_buffer.data(), number_buffer.size(),
-                                          "%.*g", d, x);
-
-            // negative value indicates an error
-            assert(len > 0);
-            // check if buffer was large enough
-            assert(static_cast<size_t>(len) < number_buffer.size());
-
-            // erase thousands separator
-            if (thousands_sep != '\0')
-            {
-                const auto end = std::remove(number_buffer.begin(),
-                                             number_buffer.begin() + len,
-                                             thousands_sep);
-                std::fill(end, number_buffer.end(), '\0');
-                assert((end - number_buffer.begin()) <= len);
-                len = (end - number_buffer.begin());
-            }
-
-            // convert decimal point to '.'
-            if (decimal_point != '\0' and decimal_point != '.')
-            {
-                for (auto& c : number_buffer)
-                {
-                    if (c == decimal_point)
-                    {
-                        c = '.';
-                        break;
-                    }
-                }
-            }
-
-            o->write_characters(number_buffer.data(), static_cast<size_t>(len));
-
-            // determine if need to append ".0"
-            const bool value_is_int_like = std::none_of(number_buffer.begin(),
-                                           number_buffer.begin() + len + 1,
-                                           [](char c)
-            {
-                return c == '.' or c == 'e';
-            });
+    @liveexample{The example below shows how objects can be swapped with
+    `swap()`.,swap__object_t}
 
-            if (value_is_int_like)
-            {
-                o->write_characters(".0", 2);
-            }
+    @since version 1.0.0
+    */
+    void swap(object_t& other)
+    {
+        // swap only works for objects
+        if (is_object())
+        {
+            std::swap(*(m_value.object), other);
         }
+        else
+        {
+            JSON_THROW(type_error::create(310, "cannot use swap() with " + type_name()));
+        }
+    }
 
-      private:
-        /// the output of the serializer
-        output_adapter_t<char> o = nullptr;
-
-        /// a (hopefully) large enough character buffer
-        std::array<char, 64> number_buffer{{}};
-
-        /// the locale
-        const std::lconv* loc = nullptr;
-        /// the locale's thousand separator character
-        const char thousands_sep = '\0';
-        /// the locale's decimal point character
-        const char decimal_point = '\0';
-
-        /// the indentation character
-        const char indent_char;
-
-        /// the indentation string
-        string_t indent_string;
-    };
-
-  public:
     /*!
-    @brief serialize to stream
-
-    Serialize the given JSON value @a j to the output stream @a o. The JSON
-    value will be serialized using the @ref dump member function.
-
-    - The indentation of the output can be controlled with the member variable
-      `width` of the output stream @a o. For instance, using the manipulator
-      `std::setw(4)` on @a o sets the indentation level to `4` and the
-      serialization result is the same as calling `dump(4)`.
-
-    - The indentation characrer can be controlled with the member variable
-      `fill` of the output stream @a o. For instance, the manipulator
-      `std::setfill('\\t')` sets indentation to use a tab character rather than
-      the default space character.
-
-    @param[in,out] o  stream to serialize to
-    @param[in] j  JSON value to serialize
-
-    @return the stream @a o
+    @brief exchanges the values
 
-    @complexity Linear.
+    Exchanges the contents of a JSON string with those of @a other. Does not
+    invoke any move, copy, or swap operations on individual elements. All
+    iterators and references remain valid. The past-the-end iterator is
+    invalidated.
 
-    @liveexample{The example below shows the serialization with different
-    parameters to `width` to adjust the indentation level.,operator_serialize}
+    @param[in,out] other string to exchange the contents with
 
-    @since version 1.0.0; indentaction character added in version 3.0.0
-    */
-    friend std::ostream& operator<<(std::ostream& o, const basic_json& j)
-    {
-        // read width member and use it as indentation parameter if nonzero
-        const bool pretty_print = (o.width() > 0);
-        const auto indentation = (pretty_print ? o.width() : 0);
+    @throw type_error.310 when JSON value is not a string; example: `"cannot
+    use swap() with boolean"`
 
-        // reset width to 0 for subsequent calls to this stream
-        o.width(0);
+    @complexity Constant.
 
-        // do the actual serialization
-        serializer s(output_adapter<char>::create(o), o.fill());
-        s.dump(j, pretty_print, static_cast<unsigned int>(indentation));
-        return o;
-    }
+    @liveexample{The example below shows how strings can be swapped with
+    `swap()`.,swap__string_t}
 
-    /*!
-    @brief serialize to stream
-    @deprecated This stream operator is deprecated and will be removed in a
-                future version of the library. Please use
-                @ref std::ostream& operator<<(std::ostream&, const basic_json&)
-                instead; that is, replace calls like `j >> o;` with `o << j;`.
+    @since version 1.0.0
     */
-    JSON_DEPRECATED
-    friend std::ostream& operator>>(const basic_json& j, std::ostream& o)
+    void swap(string_t& other)
     {
-        return o << j;
+        // swap only works for strings
+        if (is_string())
+        {
+            std::swap(*(m_value.string), other);
+        }
+        else
+        {
+            JSON_THROW(type_error::create(310, "cannot use swap() with " + type_name()));
+        }
     }
 
     /// @}
 
+  public:
+    //////////////////////////////////////////
+    // lexicographical comparison operators //
+    //////////////////////////////////////////
 
-    /////////////////////
-    // deserialization //
-    /////////////////////
-
-    /// @name deserialization
+    /// @name lexicographical comparison operators
     /// @{
 
     /*!
-    @brief deserialize from an array
+    @brief comparison: equal
 
-    This function reads from an array of 1-byte values.
+    Compares two JSON values for equality according to the following rules:
+    - Two JSON values are equal if (1) they are from the same type and (2)
+      their stored values are the same according to their respective
+      `operator==`.
+    - Integer and floating-point numbers are automatically converted before
+      comparison. Note than two NaN values are always treated as unequal.
+    - Two JSON null values are equal.
 
-    @pre Each element of the container has a size of 1 byte. Violating this
-    precondition yields undefined behavior. **This precondition is enforced
-    with a static assertion.**
+    @note NaN values never compare equal to themselves or to other NaN values.
 
-    @param[in] array  array to read from
-    @param[in] cb  a parser callback function of type @ref parser_callback_t
-    which is used to control the deserialization by filtering unwanted values
-    (optional)
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether the values @a lhs and @a rhs are equal
 
-    @return result of the deserialization
+    @complexity Linear.
 
-    @throw parse_error.101 if a parse error occurs; example: `""unexpected end
-    of input; expected string literal""`
-    @throw parse_error.102 if to_unicode fails or surrogate error
-    @throw parse_error.103 if to_unicode fails
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__equal}
 
-    @complexity Linear in the length of the input. The parser is a predictive
-    LL(1) parser. The complexity can be higher if the parser callback function
-    @a cb has a super-linear complexity.
+    @since version 1.0.0
+    */
+    friend bool operator==(const_reference lhs, const_reference rhs) noexcept
+    {
+        const auto lhs_type = lhs.type();
+        const auto rhs_type = rhs.type();
 
-    @note A UTF-8 byte order mark is silently ignored.
+        if (lhs_type == rhs_type)
+        {
+            switch (lhs_type)
+            {
+                case value_t::array:
+                {
+                    return *lhs.m_value.array == *rhs.m_value.array;
+                }
+                case value_t::object:
+                {
+                    return *lhs.m_value.object == *rhs.m_value.object;
+                }
+                case value_t::null:
+                {
+                    return true;
+                }
+                case value_t::string:
+                {
+                    return *lhs.m_value.string == *rhs.m_value.string;
+                }
+                case value_t::boolean:
+                {
+                    return lhs.m_value.boolean == rhs.m_value.boolean;
+                }
+                case value_t::number_integer:
+                {
+                    return lhs.m_value.number_integer == rhs.m_value.number_integer;
+                }
+                case value_t::number_unsigned:
+                {
+                    return lhs.m_value.number_unsigned == rhs.m_value.number_unsigned;
+                }
+                case value_t::number_float:
+                {
+                    return lhs.m_value.number_float == rhs.m_value.number_float;
+                }
+                default:
+                {
+                    return false;
+                }
+            }
+        }
+        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_float)
+        {
+            return static_cast<number_float_t>(lhs.m_value.number_integer) == rhs.m_value.number_float;
+        }
+        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_integer)
+        {
+            return lhs.m_value.number_float == static_cast<number_float_t>(rhs.m_value.number_integer);
+        }
+        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_float)
+        {
+            return static_cast<number_float_t>(lhs.m_value.number_unsigned) == rhs.m_value.number_float;
+        }
+        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_unsigned)
+        {
+            return lhs.m_value.number_float == static_cast<number_float_t>(rhs.m_value.number_unsigned);
+        }
+        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_integer)
+        {
+            return static_cast<number_integer_t>(lhs.m_value.number_unsigned) == rhs.m_value.number_integer;
+        }
+        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_unsigned)
+        {
+            return lhs.m_value.number_integer == static_cast<number_integer_t>(rhs.m_value.number_unsigned);
+        }
 
-    @liveexample{The example below demonstrates the `parse()` function reading
-    from an array.,parse__array__parser_callback_t}
+        return false;
+    }
 
-    @since version 2.0.3
+    /*!
+    @brief comparison: equal
+    @copydoc operator==(const_reference, const_reference)
     */
-    template<class T, std::size_t N>
-    static basic_json parse(T (&array)[N],
-                            const parser_callback_t cb = nullptr)
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator==(const_reference lhs, const ScalarType rhs) noexcept
     {
-        // delegate the call to the iterator-range parse overload
-        return parse(std::begin(array), std::end(array), cb);
+        return (lhs == basic_json(rhs));
     }
 
-    template<class T, std::size_t N>
-    static bool accept(T (&array)[N])
+    /*!
+    @brief comparison: equal
+    @copydoc operator==(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator==(const ScalarType lhs, const_reference rhs) noexcept
     {
-        // delegate the call to the iterator-range accept overload
-        return accept(std::begin(array), std::end(array));
+        return (basic_json(lhs) == rhs);
     }
 
     /*!
-    @brief deserialize from string literal
-
-    @tparam CharT character/literal type with size of 1 byte
-    @param[in] s  string literal to read a serialized JSON value from
-    @param[in] cb a parser callback function of type @ref parser_callback_t
-    which is used to control the deserialization by filtering unwanted values
-    (optional)
-
-    @return result of the deserialization
-
-    @throw parse_error.101 in case of an unexpected token
-    @throw parse_error.102 if to_unicode fails or surrogate error
-    @throw parse_error.103 if to_unicode fails
+    @brief comparison: not equal
 
-    @complexity Linear in the length of the input. The parser is a predictive
-    LL(1) parser. The complexity can be higher if the parser callback function
-    @a cb has a super-linear complexity.
+    Compares two JSON values for inequality by calculating `not (lhs == rhs)`.
 
-    @note A UTF-8 byte order mark is silently ignored.
-    @note String containers like `std::string` or @ref string_t can be parsed
-          with @ref parse(const ContiguousContainer&, const parser_callback_t)
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether the values @a lhs and @a rhs are not equal
 
-    @liveexample{The example below demonstrates the `parse()` function with
-    and without callback function.,parse__string__parser_callback_t}
+    @complexity Linear.
 
-    @sa @ref parse(std::istream&, const parser_callback_t) for a version that
-    reads from an input stream
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__notequal}
 
-    @since version 1.0.0 (originally for @ref string_t)
+    @since version 1.0.0
     */
-    template<typename CharT, typename std::enable_if<
-                 std::is_pointer<CharT>::value and
-                 std::is_integral<typename std::remove_pointer<CharT>::type>::value and
-                 sizeof(typename std::remove_pointer<CharT>::type) == 1, int>::type = 0>
-    static basic_json parse(const CharT s,
-                            const parser_callback_t cb = nullptr)
+    friend bool operator!=(const_reference lhs, const_reference rhs) noexcept
     {
-        return parser(detail::input_adapter_factory::create(s), cb).parse(true);
+        return not (lhs == rhs);
     }
 
-    template<typename CharT, typename std::enable_if<
-                 std::is_pointer<CharT>::value and
-                 std::is_integral<typename std::remove_pointer<CharT>::type>::value and
-                 sizeof(typename std::remove_pointer<CharT>::type) == 1, int>::type = 0>
-    static bool accept(const CharT s)
+    /*!
+    @brief comparison: not equal
+    @copydoc operator!=(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator!=(const_reference lhs, const ScalarType rhs) noexcept
     {
-        return parser(detail::input_adapter_factory::create(s)).accept(true);
+        return (lhs != basic_json(rhs));
     }
 
     /*!
-    @brief deserialize from stream
-
-    @param[in,out] i  stream to read a serialized JSON value from
-    @param[in] cb a parser callback function of type @ref parser_callback_t
-    which is used to control the deserialization by filtering unwanted values
-    (optional)
-
-    @return result of the deserialization
+    @brief comparison: not equal
+    @copydoc operator!=(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator!=(const ScalarType lhs, const_reference rhs) noexcept
+    {
+        return (basic_json(lhs) != rhs);
+    }
 
-    @throw parse_error.101 in case of an unexpected token
-    @throw parse_error.102 if to_unicode fails or surrogate error
-    @throw parse_error.103 if to_unicode fails
+    /*!
+    @brief comparison: less than
 
-    @complexity Linear in the length of the input. The parser is a predictive
-    LL(1) parser. The complexity can be higher if the parser callback function
-    @a cb has a super-linear complexity.
+    Compares whether one JSON value @a lhs is less than another JSON value @a
+    rhs according to the following rules:
+    - If @a lhs and @a rhs have the same type, the values are compared using
+      the default `<` operator.
+    - Integer and floating-point numbers are automatically converted before
+      comparison
+    - In case @a lhs and @a rhs have different types, the values are ignored
+      and the order of the types is considered, see
+      @ref operator<(const value_t, const value_t).
 
-    @note A UTF-8 byte order mark is silently ignored.
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether @a lhs is less than @a rhs
 
-    @liveexample{The example below demonstrates the `parse()` function with
-    and without callback function.,parse__istream__parser_callback_t}
+    @complexity Linear.
 
-    @sa @ref parse(const CharT, const parser_callback_t) for a version
-    that reads from a string
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__less}
 
     @since version 1.0.0
     */
-    static basic_json parse(std::istream& i,
-                            const parser_callback_t cb = nullptr)
+    friend bool operator<(const_reference lhs, const_reference rhs) noexcept
     {
-        return parser(detail::input_adapter_factory::create(i), cb).parse(true);
-    }
+        const auto lhs_type = lhs.type();
+        const auto rhs_type = rhs.type();
 
-    static bool accept(std::istream& i)
-    {
-        return parser(detail::input_adapter_factory::create(i)).accept(true);
+        if (lhs_type == rhs_type)
+        {
+            switch (lhs_type)
+            {
+                case value_t::array:
+                {
+                    return (*lhs.m_value.array) < (*rhs.m_value.array);
+                }
+                case value_t::object:
+                {
+                    return *lhs.m_value.object < *rhs.m_value.object;
+                }
+                case value_t::null:
+                {
+                    return false;
+                }
+                case value_t::string:
+                {
+                    return *lhs.m_value.string < *rhs.m_value.string;
+                }
+                case value_t::boolean:
+                {
+                    return lhs.m_value.boolean < rhs.m_value.boolean;
+                }
+                case value_t::number_integer:
+                {
+                    return lhs.m_value.number_integer < rhs.m_value.number_integer;
+                }
+                case value_t::number_unsigned:
+                {
+                    return lhs.m_value.number_unsigned < rhs.m_value.number_unsigned;
+                }
+                case value_t::number_float:
+                {
+                    return lhs.m_value.number_float < rhs.m_value.number_float;
+                }
+                default:
+                {
+                    return false;
+                }
+            }
+        }
+        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_float)
+        {
+            return static_cast<number_float_t>(lhs.m_value.number_integer) < rhs.m_value.number_float;
+        }
+        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_integer)
+        {
+            return lhs.m_value.number_float < static_cast<number_float_t>(rhs.m_value.number_integer);
+        }
+        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_float)
+        {
+            return static_cast<number_float_t>(lhs.m_value.number_unsigned) < rhs.m_value.number_float;
+        }
+        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_unsigned)
+        {
+            return lhs.m_value.number_float < static_cast<number_float_t>(rhs.m_value.number_unsigned);
+        }
+        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_unsigned)
+        {
+            return lhs.m_value.number_integer < static_cast<number_integer_t>(rhs.m_value.number_unsigned);
+        }
+        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_integer)
+        {
+            return static_cast<number_integer_t>(lhs.m_value.number_unsigned) < rhs.m_value.number_integer;
+        }
+
+        // We only reach this line if we cannot compare values. In that case,
+        // we compare types. Note we have to call the operator explicitly,
+        // because MSVC has problems otherwise.
+        return operator<(lhs_type, rhs_type);
     }
 
     /*!
-    @copydoc parse(std::istream&, const parser_callback_t)
+    @brief comparison: less than
+    @copydoc operator<(const_reference, const_reference)
     */
-    static basic_json parse(std::istream&& i,
-                            const parser_callback_t cb = nullptr)
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator<(const_reference lhs, const ScalarType rhs) noexcept
     {
-        return parser(detail::input_adapter_factory::create(i), cb).parse(true);
+        return (lhs < basic_json(rhs));
     }
 
-    static bool accept(std::istream&& i)
+    /*!
+    @brief comparison: less than
+    @copydoc operator<(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator<(const ScalarType lhs, const_reference rhs) noexcept
     {
-        return parser(detail::input_adapter_factory::create(i)).accept(true);
+        return (basic_json(lhs) < rhs);
     }
 
     /*!
-    @brief deserialize from an iterator range with contiguous storage
-
-    This function reads from an iterator range of a container with contiguous
-    storage of 1-byte values. Compatible container types include
-    `std::vector`, `std::string`, `std::array`, `std::valarray`, and
-    `std::initializer_list`. Furthermore, C-style arrays can be used with
-    `std::begin()`/`std::end()`. User-defined containers can be used as long
-    as they implement random-access iterators and a contiguous storage.
-
-    @pre The iterator range is contiguous. Violating this precondition yields
-    undefined behavior. **This precondition is enforced with an assertion.**
-    @pre Each element in the range has a size of 1 byte. Violating this
-    precondition yields undefined behavior. **This precondition is enforced
-    with a static assertion.**
-
-    @warning There is no way to enforce all preconditions at compile-time. If
-             the function is called with noncompliant iterators and with
-             assertions switched off, the behavior is undefined and will most
-             likely yield segmentation violation.
-
-    @tparam IteratorType iterator of container with contiguous storage
-    @param[in] first  begin of the range to parse (included)
-    @param[in] last  end of the range to parse (excluded)
-    @param[in] cb  a parser callback function of type @ref parser_callback_t
-    which is used to control the deserialization by filtering unwanted values
-    (optional)
-
-    @return result of the deserialization
+    @brief comparison: less than or equal
 
-    @throw parse_error.101 in case of an unexpected token
-    @throw parse_error.102 if to_unicode fails or surrogate error
-    @throw parse_error.103 if to_unicode fails
+    Compares whether one JSON value @a lhs is less than or equal to another
+    JSON value by calculating `not (rhs < lhs)`.
 
-    @complexity Linear in the length of the input. The parser is a predictive
-    LL(1) parser. The complexity can be higher if the parser callback function
-    @a cb has a super-linear complexity.
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether @a lhs is less than or equal to @a rhs
 
-    @note A UTF-8 byte order mark is silently ignored.
+    @complexity Linear.
 
-    @liveexample{The example below demonstrates the `parse()` function reading
-    from an iterator range.,parse__iteratortype__parser_callback_t}
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__greater}
 
-    @since version 2.0.3
+    @since version 1.0.0
     */
-    template<class IteratorType, typename std::enable_if<
-                 std::is_base_of<
-                     std::random_access_iterator_tag,
-                     typename std::iterator_traits<IteratorType>::iterator_category>::value, int>::type = 0>
-    static basic_json parse(IteratorType first, IteratorType last,
-                            const parser_callback_t cb = nullptr)
+    friend bool operator<=(const_reference lhs, const_reference rhs) noexcept
     {
-        return parser(detail::input_adapter_factory::create(first, last), cb).parse(true);
+        return not (rhs < lhs);
     }
 
-    template<class IteratorType, typename std::enable_if<
-                 std::is_base_of<
-                     std::random_access_iterator_tag,
-                     typename std::iterator_traits<IteratorType>::iterator_category>::value, int>::type = 0>
-    static bool accept(IteratorType first, IteratorType last)
+    /*!
+    @brief comparison: less than or equal
+    @copydoc operator<=(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator<=(const_reference lhs, const ScalarType rhs) noexcept
     {
-        return parser(detail::input_adapter_factory::create(first, last)).accept(true);
+        return (lhs <= basic_json(rhs));
     }
 
     /*!
-    @brief deserialize from a container with contiguous storage
-
-    This function reads from a container with contiguous storage of 1-byte
-    values. Compatible container types include `std::vector`, `std::string`,
-    `std::array`, and `std::initializer_list`. User-defined containers can be
-    used as long as they implement random-access iterators and a contiguous
-    storage.
-
-    @pre The container storage is contiguous. Violating this precondition
-    yields undefined behavior. **This precondition is enforced with an
-    assertion.**
-    @pre Each element of the container has a size of 1 byte. Violating this
-    precondition yields undefined behavior. **This precondition is enforced
-    with a static assertion.**
-
-    @warning There is no way to enforce all preconditions at compile-time. If
-             the function is called with a noncompliant container and with
-             assertions switched off, the behavior is undefined and will most
-             likely yield segmentation violation.
-
-    @tparam ContiguousContainer container type with contiguous storage
-    @param[in] c  container to read from
-    @param[in] cb  a parser callback function of type @ref parser_callback_t
-    which is used to control the deserialization by filtering unwanted values
-    (optional)
+    @brief comparison: less than or equal
+    @copydoc operator<=(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator<=(const ScalarType lhs, const_reference rhs) noexcept
+    {
+        return (basic_json(lhs) <= rhs);
+    }
 
-    @return result of the deserialization
+    /*!
+    @brief comparison: greater than
 
-    @throw parse_error.101 in case of an unexpected token
-    @throw parse_error.102 if to_unicode fails or surrogate error
-    @throw parse_error.103 if to_unicode fails
+    Compares whether one JSON value @a lhs is greater than another
+    JSON value by calculating `not (lhs <= rhs)`.
 
-    @complexity Linear in the length of the input. The parser is a predictive
-    LL(1) parser. The complexity can be higher if the parser callback function
-    @a cb has a super-linear complexity.
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether @a lhs is greater than to @a rhs
 
-    @note A UTF-8 byte order mark is silently ignored.
+    @complexity Linear.
 
-    @liveexample{The example below demonstrates the `parse()` function reading
-    from a contiguous container.,parse__contiguouscontainer__parser_callback_t}
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__lessequal}
 
-    @since version 2.0.3
+    @since version 1.0.0
     */
-    template<class ContiguousContainer, typename std::enable_if<
-                 not std::is_pointer<ContiguousContainer>::value and
-                 std::is_base_of<
-                     std::random_access_iterator_tag,
-                     typename std::iterator_traits<decltype(std::begin(std::declval<ContiguousContainer const>()))>::iterator_category>::value
-                 , int>::type = 0>
-    static basic_json parse(const ContiguousContainer& c,
-                            const parser_callback_t cb = nullptr)
+    friend bool operator>(const_reference lhs, const_reference rhs) noexcept
     {
-        // delegate the call to the iterator-range parse overload
-        return parse(std::begin(c), std::end(c), cb);
+        return not (lhs <= rhs);
     }
 
-    template<class ContiguousContainer, typename std::enable_if<
-                 not std::is_pointer<ContiguousContainer>::value and
-                 std::is_base_of<
-                     std::random_access_iterator_tag,
-                     typename std::iterator_traits<decltype(std::begin(std::declval<ContiguousContainer const>()))>::iterator_category>::value
-                 , int>::type = 0>
-    static bool accept(const ContiguousContainer& c)
+    /*!
+    @brief comparison: greater than
+    @copydoc operator>(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator>(const_reference lhs, const ScalarType rhs) noexcept
     {
-        // delegate the call to the iterator-range accept overload
-        return accept(std::begin(c), std::end(c));
+        return (lhs > basic_json(rhs));
     }
 
     /*!
-    @brief deserialize from stream
-    @deprecated This stream operator is deprecated and will be removed in a
-                future version of the library. Please use
-                @ref std::istream& operator>>(std::istream&, basic_json&)
-                instead; that is, replace calls like `j << i;` with `i >> j;`.
+    @brief comparison: greater than
+    @copydoc operator>(const_reference, const_reference)
     */
-    JSON_DEPRECATED
-    friend std::istream& operator<<(basic_json& j, std::istream& i)
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator>(const ScalarType lhs, const_reference rhs) noexcept
     {
-        j = parser(detail::input_adapter_factory::create(i)).parse(false);
-        return i;
+        return (basic_json(lhs) > rhs);
     }
 
     /*!
-    @brief deserialize from stream
-
-    Deserializes an input stream to a JSON value.
+    @brief comparison: greater than or equal
 
-    @param[in,out] i  input stream to read a serialized JSON value from
-    @param[in,out] j  JSON value to write the deserialized input to
+    Compares whether one JSON value @a lhs is greater than or equal to another
+    JSON value by calculating `not (lhs < rhs)`.
 
-    @throw parse_error.101 in case of an unexpected token
-    @throw parse_error.102 if to_unicode fails or surrogate error
-    @throw parse_error.103 if to_unicode fails
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether @a lhs is greater than or equal to @a rhs
 
-    @complexity Linear in the length of the input. The parser is a predictive
-    LL(1) parser.
+    @complexity Linear.
 
-    @note A UTF-8 byte order mark is silently ignored.
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__greaterequal}
 
-    @liveexample{The example below shows how a JSON value is constructed by
-    reading a serialization from a stream.,operator_deserialize}
+    @since version 1.0.0
+    */
+    friend bool operator>=(const_reference lhs, const_reference rhs) noexcept
+    {
+        return not (lhs < rhs);
+    }
 
-    @sa parse(std::istream&, const parser_callback_t) for a variant with a
-    parser callback function to filter values while parsing
+    /*!
+    @brief comparison: greater than or equal
+    @copydoc operator>=(const_reference, const_reference)
+    */
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator>=(const_reference lhs, const ScalarType rhs) noexcept
+    {
+        return (lhs >= basic_json(rhs));
+    }
 
-    @since version 1.0.0
+    /*!
+    @brief comparison: greater than or equal
+    @copydoc operator>=(const_reference, const_reference)
     */
-    friend std::istream& operator>>(std::istream& i, basic_json& j)
+    template<typename ScalarType, typename std::enable_if<
+                 std::is_scalar<ScalarType>::value, int>::type = 0>
+    friend bool operator>=(const ScalarType lhs, const_reference rhs) noexcept
     {
-        j = parser(detail::input_adapter_factory::create(i)).parse(false);
-        return i;
+        return (basic_json(lhs) >= rhs);
     }
 
     /// @}
 
-    ///////////////////////////
-    // convenience functions //
-    ///////////////////////////
+    ///////////////////
+    // serialization //
+    ///////////////////
+
+    /// @name serialization
+    /// @{
 
+  private:
     /*!
-    @brief return the type as string
+    @brief wrapper around the serialization functions
+    */
+    class serializer
+    {
+      public:
+        /*!
+        @param[in] s  output stream to serialize to
+        @param[in] ichar  indentation character to use
+        */
+        serializer(output_adapter_t<char> s, const char ichar)
+            : o(s), loc(std::localeconv()),
+              thousands_sep(!loc->thousands_sep ? '\0' : loc->thousands_sep[0]),
+              decimal_point(!loc->decimal_point ? '\0' : loc->decimal_point[0]),
+              indent_char(ichar), indent_string(512, indent_char)
+        {}
 
-    Returns the type name as string to be used in error messages - usually to
-    indicate that a function was called on a wrong JSON type.
+        // delete because of pointer members
+        serializer(const serializer&) = delete;
+        serializer& operator=(const serializer&) = delete;
 
-    @return basically a string representation of a the @a m_type member
+        /*!
+        @brief internal implementation of the serialization function
 
-    @complexity Constant.
+        This function is called by the public member function dump and
+        organizes the serialization internally. The indentation level is
+        propagated as additional parameter. In case of arrays and objects, the
+        function is called recursively.
+
+        - strings and object keys are escaped using `escape_string()`
+        - integer numbers are converted implicitly via `operator<<`
+        - floating-point numbers are converted to a string using `"%g"` format
+
+        @param[in] val             value to serialize
+        @param[in] pretty_print    whether the output shall be pretty-printed
+        @param[in] indent_step     the indent level
+        @param[in] current_indent  the current indent level (only used internally)
+        */
+        void dump(const basic_json& val,
+                  const bool pretty_print,
+                  const unsigned int indent_step,
+                  const unsigned int current_indent = 0)
+        {
+            switch (val.m_type)
+            {
+                case value_t::object:
+                {
+                    if (val.m_value.object->empty())
+                    {
+                        o->write_characters("{}", 2);
+                        return;
+                    }
+
+                    if (pretty_print)
+                    {
+                        o->write_characters("{\n", 2);
+
+                        // variable to hold indentation for recursive calls
+                        const auto new_indent = current_indent + indent_step;
+                        if (JSON_UNLIKELY(indent_string.size() < new_indent))
+                        {
+                            indent_string.resize(indent_string.size() * 2, ' ');
+                        }
 
-    @liveexample{The following code exemplifies `type_name()` for all JSON
-    types.,type_name}
+                        // first n-1 elements
+                        auto i = val.m_value.object->cbegin();
+                        for (size_t cnt = 0; cnt < val.m_value.object->size() - 1; ++cnt, ++i)
+                        {
+                            o->write_characters(indent_string.c_str(), new_indent);
+                            o->write_character('\"');
+                            dump_escaped(i->first);
+                            o->write_characters("\": ", 3);
+                            dump(i->second, true, indent_step, new_indent);
+                            o->write_characters(",\n", 2);
+                        }
 
-    @since version 1.0.0, public since 2.1.0
-    */
-    std::string type_name() const
-    {
-        {
-            switch (m_type)
-            {
-                case value_t::null:
-                    return "null";
-                case value_t::object:
-                    return "object";
-                case value_t::array:
-                    return "array";
-                case value_t::string:
-                    return "string";
-                case value_t::boolean:
-                    return "boolean";
-                case value_t::discarded:
-                    return "discarded";
-                default:
-                    return "number";
-            }
-        }
-    }
+                        // last element
+                        assert(i != val.m_value.object->cend());
+                        o->write_characters(indent_string.c_str(), new_indent);
+                        o->write_character('\"');
+                        dump_escaped(i->first);
+                        o->write_characters("\": ", 3);
+                        dump(i->second, true, indent_step, new_indent);
 
+                        o->write_character('\n');
+                        o->write_characters(indent_string.c_str(), current_indent);
+                        o->write_character('}');
+                    }
+                    else
+                    {
+                        o->write_character('{');
 
-  private:
-    //////////////////////
-    // member variables //
-    //////////////////////
+                        // first n-1 elements
+                        auto i = val.m_value.object->cbegin();
+                        for (size_t cnt = 0; cnt < val.m_value.object->size() - 1; ++cnt, ++i)
+                        {
+                            o->write_character('\"');
+                            dump_escaped(i->first);
+                            o->write_characters("\":", 2);
+                            dump(i->second, false, indent_step, current_indent);
+                            o->write_character(',');
+                        }
 
-    /// the type of the current element
-    value_t m_type = value_t::null;
+                        // last element
+                        assert(i != val.m_value.object->cend());
+                        o->write_character('\"');
+                        dump_escaped(i->first);
+                        o->write_characters("\":", 2);
+                        dump(i->second, false, indent_step, current_indent);
 
-    /// the value of the current element
-    json_value m_value = {};
+                        o->write_character('}');
+                    }
 
-    //////////////////////////////////////////
-    // binary serialization/deserialization //
-    //////////////////////////////////////////
+                    return;
+                }
 
-    /// @name binary serialization/deserialization support
-    /// @{
+                case value_t::array:
+                {
+                    if (val.m_value.array->empty())
+                    {
+                        o->write_characters("[]", 2);
+                        return;
+                    }
 
-    /*!
-    @brief deserialization of CBOR and MessagePack values
-    */
-    class binary_reader
-    {
-      public:
-        /*!
-        @brief create a binary reader
+                    if (pretty_print)
+                    {
+                        o->write_characters("[\n", 2);
 
-        @param[in] adapter  input adapter to read from
-        */
-        explicit binary_reader(detail::input_adapter_t adapter)
-            : ia(adapter), is_little_endian(little_endianess())
-        {
-            assert(ia);
-        }
+                        // variable to hold indentation for recursive calls
+                        const auto new_indent = current_indent + indent_step;
+                        if (indent_string.size() < new_indent)
+                        {
+                            indent_string.resize(new_indent, ' ');
+                        }
 
-        /*!
-        @brief create a JSON value from CBOR input
+                        // first n-1 elements
+                        for (auto i = val.m_value.array->cbegin(); i != val.m_value.array->cend() - 1; ++i)
+                        {
+                            o->write_characters(indent_string.c_str(), new_indent);
+                            dump(*i, true, indent_step, new_indent);
+                            o->write_characters(",\n", 2);
+                        }
 
-        @param[in] get_char  whether a new character should be retrieved from
-                             the input (true, default) or whether the last
-                             read character should be considered instead
+                        // last element
+                        assert(not val.m_value.array->empty());
+                        o->write_characters(indent_string.c_str(), new_indent);
+                        dump(val.m_value.array->back(), true, indent_step, new_indent);
 
-        @return JSON value created from CBOR input
+                        o->write_character('\n');
+                        o->write_characters(indent_string.c_str(), current_indent);
+                        o->write_character(']');
+                    }
+                    else
+                    {
+                        o->write_character('[');
 
-        @throw parse_error.110 if input ended unexpectedly
-        @throw parse_error.112 if unsupported byte was read
-        */
-        basic_json parse_cbor(const bool get_char = true)
-        {
-            switch (get_char ? get() : current)
-            {
-                // EOF
-                case std::char_traits<char>::eof():
-                {
-                    JSON_THROW(parse_error::create(110, chars_read, "unexpected end of input"));
-                }
+                        // first n-1 elements
+                        for (auto i = val.m_value.array->cbegin(); i != val.m_value.array->cend() - 1; ++i)
+                        {
+                            dump(*i, false, indent_step, current_indent);
+                            o->write_character(',');
+                        }
 
-                // Integer 0x00..0x17 (0..23)
-                case 0x00:
-                case 0x01:
-                case 0x02:
-                case 0x03:
-                case 0x04:
-                case 0x05:
-                case 0x06:
-                case 0x07:
-                case 0x08:
-                case 0x09:
-                case 0x0a:
-                case 0x0b:
-                case 0x0c:
-                case 0x0d:
-                case 0x0e:
-                case 0x0f:
-                case 0x10:
-                case 0x11:
-                case 0x12:
-                case 0x13:
-                case 0x14:
-                case 0x15:
-                case 0x16:
-                case 0x17:
-                {
-                    return static_cast<number_unsigned_t>(current);
-                }
+                        // last element
+                        assert(not val.m_value.array->empty());
+                        dump(val.m_value.array->back(), false, indent_step, current_indent);
 
-                case 0x18: // Unsigned integer (one-byte uint8_t follows)
-                {
-                    return get_number<uint8_t>();
-                }
+                        o->write_character(']');
+                    }
 
-                case 0x19: // Unsigned integer (two-byte uint16_t follows)
-                {
-                    return get_number<uint16_t>();
+                    return;
                 }
 
-                case 0x1a: // Unsigned integer (four-byte uint32_t follows)
+                case value_t::string:
                 {
-                    return get_number<uint32_t>();
+                    o->write_character('\"');
+                    dump_escaped(*val.m_value.string);
+                    o->write_character('\"');
+                    return;
                 }
 
-                case 0x1b: // Unsigned integer (eight-byte uint64_t follows)
+                case value_t::boolean:
                 {
-                    return get_number<uint64_t>();
+                    if (val.m_value.boolean)
+                    {
+                        o->write_characters("true", 4);
+                    }
+                    else
+                    {
+                        o->write_characters("false", 5);
+                    }
+                    return;
                 }
 
-                // Negative integer -1-0x00..-1-0x17 (-1..-24)
-                case 0x20:
-                case 0x21:
-                case 0x22:
-                case 0x23:
-                case 0x24:
-                case 0x25:
-                case 0x26:
-                case 0x27:
-                case 0x28:
-                case 0x29:
-                case 0x2a:
-                case 0x2b:
-                case 0x2c:
-                case 0x2d:
-                case 0x2e:
-                case 0x2f:
-                case 0x30:
-                case 0x31:
-                case 0x32:
-                case 0x33:
-                case 0x34:
-                case 0x35:
-                case 0x36:
-                case 0x37:
+                case value_t::number_integer:
                 {
-                    return static_cast<int8_t>(0x20 - 1 - current);
+                    dump_integer(val.m_value.number_integer);
+                    return;
                 }
 
-                case 0x38: // Negative integer (one-byte uint8_t follows)
+                case value_t::number_unsigned:
                 {
-                    // must be uint8_t !
-                    return static_cast<number_integer_t>(-1) - get_number<uint8_t>();
+                    dump_integer(val.m_value.number_unsigned);
+                    return;
                 }
 
-                case 0x39: // Negative integer -1-n (two-byte uint16_t follows)
+                case value_t::number_float:
                 {
-                    return static_cast<number_integer_t>(-1) - get_number<uint16_t>();
+                    dump_float(val.m_value.number_float);
+                    return;
                 }
 
-                case 0x3a: // Negative integer -1-n (four-byte uint32_t follows)
+                case value_t::discarded:
                 {
-                    return static_cast<number_integer_t>(-1) - get_number<uint32_t>();
+                    o->write_characters("<discarded>", 11);
+                    return;
                 }
 
-                case 0x3b: // Negative integer -1-n (eight-byte uint64_t follows)
+                case value_t::null:
                 {
-                    return static_cast<number_integer_t>(-1) - static_cast<number_integer_t>(get_number<uint64_t>());
+                    o->write_characters("null", 4);
+                    return;
                 }
+            }
+        }
 
-                // UTF-8 string (0x00..0x17 bytes follow)
-                case 0x60:
-                case 0x61:
-                case 0x62:
-                case 0x63:
-                case 0x64:
-                case 0x65:
-                case 0x66:
-                case 0x67:
-                case 0x68:
-                case 0x69:
-                case 0x6a:
-                case 0x6b:
-                case 0x6c:
-                case 0x6d:
-                case 0x6e:
-                case 0x6f:
-                case 0x70:
-                case 0x71:
-                case 0x72:
-                case 0x73:
-                case 0x74:
-                case 0x75:
-                case 0x76:
-                case 0x77:
-                case 0x78: // UTF-8 string (one-byte uint8_t for n follows)
-                case 0x79: // UTF-8 string (two-byte uint16_t for n follow)
-                case 0x7a: // UTF-8 string (four-byte uint32_t for n follow)
-                case 0x7b: // UTF-8 string (eight-byte uint64_t for n follow)
-                case 0x7f: // UTF-8 string (indefinite length)
-                {
-                    return get_cbor_string();
-                }
-
-                // array (0x00..0x17 data items follow)
-                case 0x80:
-                case 0x81:
-                case 0x82:
-                case 0x83:
-                case 0x84:
-                case 0x85:
-                case 0x86:
-                case 0x87:
-                case 0x88:
-                case 0x89:
-                case 0x8a:
-                case 0x8b:
-                case 0x8c:
-                case 0x8d:
-                case 0x8e:
-                case 0x8f:
-                case 0x90:
-                case 0x91:
-                case 0x92:
-                case 0x93:
-                case 0x94:
-                case 0x95:
-                case 0x96:
-                case 0x97:
-                {
-                    basic_json result = value_t::array;
-                    const auto len = static_cast<size_t>(current & 0x1f);
-                    for (size_t i = 0; i < len; ++i)
+      private:
+        /*!
+        @brief calculates the extra space to escape a JSON string
+
+        @param[in] s  the string to escape
+        @return the number of characters required to escape string @a s
+
+        @complexity Linear in the length of string @a s.
+        */
+        static std::size_t extra_space(const string_t& s) noexcept
+        {
+            return std::accumulate(s.begin(), s.end(), size_t{},
+                                   [](size_t res, typename string_t::value_type c)
+            {
+                switch (c)
+                {
+                    case '"':
+                    case '\\':
+                    case '\b':
+                    case '\f':
+                    case '\n':
+                    case '\r':
+                    case '\t':
                     {
-                        result.push_back(parse_cbor());
+                        // from c (1 byte) to \x (2 bytes)
+                        return res + 1;
                     }
-                    return result;
-                }
 
-                case 0x98: // array (one-byte uint8_t for n follows)
-                {
-                    basic_json result = value_t::array;
-                    const auto len = static_cast<size_t>(get_number<uint8_t>());
-                    for (size_t i = 0; i < len; ++i)
+                    case 0x00:
+                    case 0x01:
+                    case 0x02:
+                    case 0x03:
+                    case 0x04:
+                    case 0x05:
+                    case 0x06:
+                    case 0x07:
+                    case 0x0b:
+                    case 0x0e:
+                    case 0x0f:
+                    case 0x10:
+                    case 0x11:
+                    case 0x12:
+                    case 0x13:
+                    case 0x14:
+                    case 0x15:
+                    case 0x16:
+                    case 0x17:
+                    case 0x18:
+                    case 0x19:
+                    case 0x1a:
+                    case 0x1b:
+                    case 0x1c:
+                    case 0x1d:
+                    case 0x1e:
+                    case 0x1f:
                     {
-                        result.push_back(parse_cbor());
+                        // from c (1 byte) to \uxxxx (6 bytes)
+                        return res + 5;
                     }
-                    return result;
-                }
 
-                case 0x99: // array (two-byte uint16_t for n follow)
-                {
-                    basic_json result = value_t::array;
-                    const auto len = static_cast<size_t>(get_number<uint16_t>());
-                    for (size_t i = 0; i < len; ++i)
+                    default:
                     {
-                        result.push_back(parse_cbor());
+                        return res;
                     }
-                    return result;
                 }
+            });
+        }
 
-                case 0x9a: // array (four-byte uint32_t for n follow)
+        /*!
+        @brief dump escaped string
+
+        Escape a string by replacing certain special characters by a sequence
+        of an escape character (backslash) and another character and other
+        control characters by a sequence of "\u" followed by a four-digit hex
+        representation. The escaped string is written to output stream @a o.
+
+        @param[in] s  the string to escape
+
+        @complexity Linear in the length of string @a s.
+        */
+        void dump_escaped(const string_t& s) const
+        {
+            const auto space = extra_space(s);
+            if (space == 0)
+            {
+                o->write_characters(s.c_str(), s.size());
+                return;
+            }
+
+            // create a result string of necessary size
+            string_t result(s.size() + space, '\\');
+            std::size_t pos = 0;
+
+            for (const auto& c : s)
+            {
+                switch (c)
                 {
-                    basic_json result = value_t::array;
-                    const auto len = static_cast<size_t>(get_number<uint32_t>());
-                    for (size_t i = 0; i < len; ++i)
+                    // quotation mark (0x22)
+                    case '"':
                     {
-                        result.push_back(parse_cbor());
+                        result[pos + 1] = '"';
+                        pos += 2;
+                        break;
                     }
-                    return result;
-                }
 
-                case 0x9b: // array (eight-byte uint64_t for n follow)
-                {
-                    basic_json result = value_t::array;
-                    const auto len = static_cast<size_t>(get_number<uint64_t>());
-                    for (size_t i = 0; i < len; ++i)
+                    // reverse solidus (0x5c)
+                    case '\\':
                     {
-                        result.push_back(parse_cbor());
+                        // nothing to change
+                        pos += 2;
+                        break;
                     }
-                    return result;
-                }
 
-                case 0x9f: // array (indefinite length)
-                {
-                    basic_json result = value_t::array;
-                    while (get() != 0xff)
+                    // backspace (0x08)
+                    case '\b':
                     {
-                        result.push_back(parse_cbor(false));
+                        result[pos + 1] = 'b';
+                        pos += 2;
+                        break;
                     }
-                    return result;
-                }
 
-                // map (0x00..0x17 pairs of data items follow)
-                case 0xa0:
-                case 0xa1:
-                case 0xa2:
-                case 0xa3:
-                case 0xa4:
-                case 0xa5:
-                case 0xa6:
-                case 0xa7:
-                case 0xa8:
-                case 0xa9:
-                case 0xaa:
-                case 0xab:
-                case 0xac:
-                case 0xad:
-                case 0xae:
-                case 0xaf:
-                case 0xb0:
-                case 0xb1:
-                case 0xb2:
-                case 0xb3:
-                case 0xb4:
-                case 0xb5:
-                case 0xb6:
-                case 0xb7:
-                {
-                    basic_json result = value_t::object;
-                    const auto len = static_cast<size_t>(current & 0x1f);
-                    for (size_t i = 0; i < len; ++i)
+                    // formfeed (0x0c)
+                    case '\f':
                     {
-                        get();
-                        auto key = get_cbor_string();
-                        result[key] = parse_cbor();
+                        result[pos + 1] = 'f';
+                        pos += 2;
+                        break;
                     }
-                    return result;
-                }
 
-                case 0xb8: // map (one-byte uint8_t for n follows)
-                {
-                    basic_json result = value_t::object;
-                    const auto len = static_cast<size_t>(get_number<uint8_t>());
-                    for (size_t i = 0; i < len; ++i)
+                    // newline (0x0a)
+                    case '\n':
                     {
-                        get();
-                        auto key = get_cbor_string();
-                        result[key] = parse_cbor();
+                        result[pos + 1] = 'n';
+                        pos += 2;
+                        break;
                     }
-                    return result;
-                }
 
-                case 0xb9: // map (two-byte uint16_t for n follow)
-                {
-                    basic_json result = value_t::object;
-                    const auto len = static_cast<size_t>(get_number<uint16_t>());
-                    for (size_t i = 0; i < len; ++i)
+                    // carriage return (0x0d)
+                    case '\r':
                     {
-                        get();
-                        auto key = get_cbor_string();
-                        result[key] = parse_cbor();
+                        result[pos + 1] = 'r';
+                        pos += 2;
+                        break;
                     }
-                    return result;
-                }
 
-                case 0xba: // map (four-byte uint32_t for n follow)
-                {
-                    basic_json result = value_t::object;
-                    const auto len = static_cast<size_t>(get_number<uint32_t>());
-                    for (size_t i = 0; i < len; ++i)
+                    // horizontal tab (0x09)
+                    case '\t':
                     {
-                        get();
-                        auto key = get_cbor_string();
-                        result[key] = parse_cbor();
+                        result[pos + 1] = 't';
+                        pos += 2;
+                        break;
                     }
-                    return result;
-                }
 
-                case 0xbb: // map (eight-byte uint64_t for n follow)
-                {
-                    basic_json result = value_t::object;
-                    const auto len = static_cast<size_t>(get_number<uint64_t>());
-                    for (size_t i = 0; i < len; ++i)
+                    case 0x00:
+                    case 0x01:
+                    case 0x02:
+                    case 0x03:
+                    case 0x04:
+                    case 0x05:
+                    case 0x06:
+                    case 0x07:
+                    case 0x0b:
+                    case 0x0e:
+                    case 0x0f:
+                    case 0x10:
+                    case 0x11:
+                    case 0x12:
+                    case 0x13:
+                    case 0x14:
+                    case 0x15:
+                    case 0x16:
+                    case 0x17:
+                    case 0x18:
+                    case 0x19:
+                    case 0x1a:
+                    case 0x1b:
+                    case 0x1c:
+                    case 0x1d:
+                    case 0x1e:
+                    case 0x1f:
                     {
-                        get();
-                        auto key = get_cbor_string();
-                        result[key] = parse_cbor();
+                        // convert a number 0..15 to its hex representation
+                        // (0..f)
+                        static const char hexify[16] =
+                        {
+                            '0', '1', '2', '3', '4', '5', '6', '7',
+                            '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'
+                        };
+
+                        // print character c as \uxxxx
+                        for (const char m :
+                    { 'u', '0', '0', hexify[c >> 4], hexify[c & 0x0f]
+                        })
+                        {
+                            result[++pos] = m;
+                        }
+
+                        ++pos;
+                        break;
                     }
-                    return result;
-                }
 
-                case 0xbf: // map (indefinite length)
-                {
-                    basic_json result = value_t::object;
-                    while (get() != 0xff)
+                    default:
                     {
-                        auto key = get_cbor_string();
-                        result[key] = parse_cbor();
+                        // all other characters are added as-is
+                        result[pos++] = c;
+                        break;
                     }
-                    return result;
                 }
+            }
 
-                case 0xf4: // false
-                {
-                    return false;
-                }
+            assert(pos == s.size() + space);
+            o->write_characters(result.c_str(), result.size());
+        }
 
-                case 0xf5: // true
-                {
-                    return true;
-                }
+        /*!
+        @brief dump an integer
 
-                case 0xf6: // null
-                {
-                    return value_t::null;
-                }
+        Dump a given integer to output stream @a o. Works internally with
+        @a number_buffer.
 
-                case 0xf9: // Half-Precision Float (two-byte IEEE 754)
-                {
-                    const int byte1 = get();
-                    check_eof();
-                    const int byte2 = get();
-                    check_eof();
+        @param[in] x  integer number (signed or unsigned) to dump
+        @tparam NumberType either @a number_integer_t or @a number_unsigned_t
+        */
+        template<typename NumberType, detail::enable_if_t <
+                     std::is_same<NumberType, number_unsigned_t>::value or
+                     std::is_same<NumberType, number_integer_t>::value, int> = 0>
+        void dump_integer(NumberType x)
+        {
+            // special case for "0"
+            if (x == 0)
+            {
+                o->write_character('0');
+                return;
+            }
 
-                    // code from RFC 7049, Appendix D, Figure 3:
-                    // As half-precision floating-point numbers were only added
-                    // to IEEE 754 in 2008, today's programming platforms often
-                    // still only have limited support for them. It is very
-                    // easy to include at least decoding support for them even
-                    // without such support. An example of a small decoder for
-                    // half-precision floating-point numbers in the C language
-                    // is shown in Fig. 3.
-                    const int half = (byte1 << 8) + byte2;
-                    const int exp = (half >> 10) & 0x1f;
-                    const int mant = half & 0x3ff;
-                    double val;
-                    if (exp == 0)
-                    {
-                        val = std::ldexp(mant, -24);
-                    }
-                    else if (exp != 31)
-                    {
-                        val = std::ldexp(mant + 1024, exp - 25);
-                    }
-                    else
-                    {
-                        val = (mant == 0)
-                              ? std::numeric_limits<double>::infinity()
-                              : std::numeric_limits<double>::quiet_NaN();
-                    }
-                    return (half & 0x8000) != 0 ? -val : val;
-                }
+            const bool is_negative = x < 0;
+            size_t i = 0;
 
-                case 0xfa: // Single-Precision Float (four-byte IEEE 754)
-                {
-                    return get_number<float>();
-                }
+            // spare 1 byte for '\0'
+            while (x != 0 and i < number_buffer.size() - 1)
+            {
+                const auto digit = std::labs(static_cast<long>(x % 10));
+                number_buffer[i++] = static_cast<char>('0' + digit);
+                x /= 10;
+            }
 
-                case 0xfb: // Double-Precision Float (eight-byte IEEE 754)
-                {
-                    return get_number<double>();
-                }
+            // make sure the number has been processed completely
+            assert(x == 0);
 
-                default: // anything else (0xFF is handled inside the other types)
-                {
-                    std::stringstream ss;
-                    ss << std::setw(2) << std::setfill('0') << std::hex << current;
-                    JSON_THROW(parse_error::create(112, chars_read, "error reading CBOR; last byte: 0x" + ss.str()));
-                }
+            if (is_negative)
+            {
+                // make sure there is capacity for the '-'
+                assert(i < number_buffer.size() - 2);
+                number_buffer[i++] = '-';
             }
+
+            std::reverse(number_buffer.begin(), number_buffer.begin() + i);
+            o->write_characters(number_buffer.data(), i);
         }
 
         /*!
-        @brief create a JSON value from MessagePack input
+        @brief dump a floating-point number
 
-        @return JSON value created from MessagePack input
+        Dump a given floating-point number to output stream @a o. Works
+        internally with @a number_buffer.
 
-        @throw parse_error.110 if input ended unexpectedly
-        @throw parse_error.112 if unsupported byte was read
+        @param[in] x  floating-point number to dump
         */
-        basic_json parse_msgpack()
+        void dump_float(number_float_t x)
         {
-            switch (get())
+            // NaN / inf
+            if (not std::isfinite(x) or std::isnan(x))
             {
-                // EOF
-                case std::char_traits<char>::eof():
+                o->write_characters("null", 4);
+                return;
+            }
+
+            // special case for 0.0 and -0.0
+            if (x == 0)
+            {
+                if (std::signbit(x))
                 {
-                    JSON_THROW(parse_error::create(110, chars_read, "unexpected end of input"));
+                    o->write_characters("-0.0", 4);
                 }
-
-                // positive fixint
-                case 0x00:
-                case 0x01:
-                case 0x02:
-                case 0x03:
-                case 0x04:
-                case 0x05:
-                case 0x06:
-                case 0x07:
-                case 0x08:
-                case 0x09:
-                case 0x0a:
-                case 0x0b:
-                case 0x0c:
-                case 0x0d:
-                case 0x0e:
-                case 0x0f:
-                case 0x10:
-                case 0x11:
-                case 0x12:
-                case 0x13:
-                case 0x14:
-                case 0x15:
-                case 0x16:
-                case 0x17:
-                case 0x18:
-                case 0x19:
-                case 0x1a:
-                case 0x1b:
-                case 0x1c:
-                case 0x1d:
-                case 0x1e:
-                case 0x1f:
-                case 0x20:
-                case 0x21:
-                case 0x22:
-                case 0x23:
-                case 0x24:
-                case 0x25:
-                case 0x26:
-                case 0x27:
-                case 0x28:
-                case 0x29:
-                case 0x2a:
-                case 0x2b:
-                case 0x2c:
-                case 0x2d:
-                case 0x2e:
-                case 0x2f:
-                case 0x30:
-                case 0x31:
-                case 0x32:
-                case 0x33:
-                case 0x34:
-                case 0x35:
-                case 0x36:
-                case 0x37:
-                case 0x38:
-                case 0x39:
-                case 0x3a:
-                case 0x3b:
-                case 0x3c:
-                case 0x3d:
-                case 0x3e:
-                case 0x3f:
-                case 0x40:
-                case 0x41:
-                case 0x42:
-                case 0x43:
-                case 0x44:
-                case 0x45:
-                case 0x46:
-                case 0x47:
-                case 0x48:
-                case 0x49:
-                case 0x4a:
-                case 0x4b:
-                case 0x4c:
-                case 0x4d:
-                case 0x4e:
-                case 0x4f:
-                case 0x50:
-                case 0x51:
-                case 0x52:
-                case 0x53:
-                case 0x54:
-                case 0x55:
-                case 0x56:
-                case 0x57:
-                case 0x58:
-                case 0x59:
-                case 0x5a:
-                case 0x5b:
-                case 0x5c:
-                case 0x5d:
-                case 0x5e:
-                case 0x5f:
-                case 0x60:
-                case 0x61:
-                case 0x62:
-                case 0x63:
-                case 0x64:
-                case 0x65:
-                case 0x66:
-                case 0x67:
-                case 0x68:
-                case 0x69:
-                case 0x6a:
-                case 0x6b:
-                case 0x6c:
-                case 0x6d:
-                case 0x6e:
-                case 0x6f:
-                case 0x70:
-                case 0x71:
-                case 0x72:
-                case 0x73:
-                case 0x74:
-                case 0x75:
-                case 0x76:
-                case 0x77:
-                case 0x78:
-                case 0x79:
-                case 0x7a:
-                case 0x7b:
-                case 0x7c:
-                case 0x7d:
-                case 0x7e:
-                case 0x7f:
+                else
                 {
-                    return static_cast<number_unsigned_t>(current);
-                }
-
-                // fixmap
-                case 0x80:
-                case 0x81:
-                case 0x82:
-                case 0x83:
-                case 0x84:
-                case 0x85:
-                case 0x86:
-                case 0x87:
-                case 0x88:
-                case 0x89:
-                case 0x8a:
-                case 0x8b:
-                case 0x8c:
-                case 0x8d:
-                case 0x8e:
-                case 0x8f:
-                {
-                    basic_json result = value_t::object;
-                    const auto len = static_cast<size_t>(current & 0x0f);
-                    for (size_t i = 0; i < len; ++i)
-                    {
-                        get();
-                        auto key = get_msgpack_string();
-                        result[key] = parse_msgpack();
-                    }
-                    return result;
+                    o->write_characters("0.0", 3);
                 }
+                return;
+            }
+
+            // get number of digits for a text -> float -> text round-trip
+            static constexpr auto d = std::numeric_limits<number_float_t>::digits10;
+
+            // the actual conversion
+            std::ptrdiff_t len = snprintf(number_buffer.data(), number_buffer.size(),
+                                          "%.*g", d, x);
+
+            // negative value indicates an error
+            assert(len > 0);
+            // check if buffer was large enough
+            assert(static_cast<size_t>(len) < number_buffer.size());
+
+            // erase thousands separator
+            if (thousands_sep != '\0')
+            {
+                const auto end = std::remove(number_buffer.begin(),
+                                             number_buffer.begin() + len,
+                                             thousands_sep);
+                std::fill(end, number_buffer.end(), '\0');
+                assert((end - number_buffer.begin()) <= len);
+                len = (end - number_buffer.begin());
+            }
 
-                // fixarray
-                case 0x90:
-                case 0x91:
-                case 0x92:
-                case 0x93:
-                case 0x94:
-                case 0x95:
-                case 0x96:
-                case 0x97:
-                case 0x98:
-                case 0x99:
-                case 0x9a:
-                case 0x9b:
-                case 0x9c:
-                case 0x9d:
-                case 0x9e:
-                case 0x9f:
-                {
-                    basic_json result = value_t::array;
-                    const auto len = static_cast<size_t>(current & 0x0f);
-                    for (size_t i = 0; i < len; ++i)
+            // convert decimal point to '.'
+            if (decimal_point != '\0' and decimal_point != '.')
+            {
+                for (auto& c : number_buffer)
+                {
+                    if (c == decimal_point)
                     {
-                        result.push_back(parse_msgpack());
+                        c = '.';
+                        break;
                     }
-                    return result;
                 }
+            }
 
-                // fixstr
-                case 0xa0:
-                case 0xa1:
-                case 0xa2:
-                case 0xa3:
-                case 0xa4:
-                case 0xa5:
-                case 0xa6:
-                case 0xa7:
-                case 0xa8:
-                case 0xa9:
-                case 0xaa:
-                case 0xab:
-                case 0xac:
-                case 0xad:
-                case 0xae:
-                case 0xaf:
-                case 0xb0:
-                case 0xb1:
-                case 0xb2:
-                case 0xb3:
-                case 0xb4:
-                case 0xb5:
-                case 0xb6:
-                case 0xb7:
-                case 0xb8:
-                case 0xb9:
-                case 0xba:
-                case 0xbb:
-                case 0xbc:
-                case 0xbd:
-                case 0xbe:
-                case 0xbf:
-                {
-                    return get_msgpack_string();
-                }
-
-                case 0xc0: // nil
-                {
-                    return value_t::null;
-                }
-
-                case 0xc2: // false
-                {
-                    return false;
-                }
+            o->write_characters(number_buffer.data(), static_cast<size_t>(len));
 
-                case 0xc3: // true
-                {
-                    return true;
-                }
+            // determine if need to append ".0"
+            const bool value_is_int_like = std::none_of(number_buffer.begin(),
+                                           number_buffer.begin() + len + 1,
+                                           [](char c)
+            {
+                return c == '.' or c == 'e';
+            });
 
-                case 0xca: // float 32
-                {
-                    return get_number<float>();
-                }
+            if (value_is_int_like)
+            {
+                o->write_characters(".0", 2);
+            }
+        }
 
-                case 0xcb: // float 64
-                {
-                    return get_number<double>();
-                }
+      private:
+        /// the output of the serializer
+        output_adapter_t<char> o = nullptr;
 
-                case 0xcc: // uint 8
-                {
-                    return get_number<uint8_t>();
-                }
+        /// a (hopefully) large enough character buffer
+        std::array<char, 64> number_buffer{{}};
 
-                case 0xcd: // uint 16
-                {
-                    return get_number<uint16_t>();
-                }
+        /// the locale
+        const std::lconv* loc = nullptr;
+        /// the locale's thousand separator character
+        const char thousands_sep = '\0';
+        /// the locale's decimal point character
+        const char decimal_point = '\0';
+
+        /// the indentation character
+        const char indent_char;
+
+        /// the indentation string
+        string_t indent_string;
+    };
+
+  public:
+    /*!
+    @brief serialize to stream
+
+    Serialize the given JSON value @a j to the output stream @a o. The JSON
+    value will be serialized using the @ref dump member function.
+
+    - The indentation of the output can be controlled with the member variable
+      `width` of the output stream @a o. For instance, using the manipulator
+      `std::setw(4)` on @a o sets the indentation level to `4` and the
+      serialization result is the same as calling `dump(4)`.
 
-                case 0xce: // uint 32
-                {
-                    return get_number<uint32_t>();
-                }
+    - The indentation characrer can be controlled with the member variable
+      `fill` of the output stream @a o. For instance, the manipulator
+      `std::setfill('\\t')` sets indentation to use a tab character rather than
+      the default space character.
 
-                case 0xcf: // uint 64
-                {
-                    return get_number<uint64_t>();
-                }
+    @param[in,out] o  stream to serialize to
+    @param[in] j  JSON value to serialize
 
-                case 0xd0: // int 8
-                {
-                    return get_number<int8_t>();
-                }
+    @return the stream @a o
 
-                case 0xd1: // int 16
-                {
-                    return get_number<int16_t>();
-                }
+    @complexity Linear.
 
-                case 0xd2: // int 32
-                {
-                    return get_number<int32_t>();
-                }
+    @liveexample{The example below shows the serialization with different
+    parameters to `width` to adjust the indentation level.,operator_serialize}
 
-                case 0xd3: // int 64
-                {
-                    return get_number<int64_t>();
-                }
+    @since version 1.0.0; indentaction character added in version 3.0.0
+    */
+    friend std::ostream& operator<<(std::ostream& o, const basic_json& j)
+    {
+        // read width member and use it as indentation parameter if nonzero
+        const bool pretty_print = (o.width() > 0);
+        const auto indentation = (pretty_print ? o.width() : 0);
 
-                case 0xd9: // str 8
-                case 0xda: // str 16
-                case 0xdb: // str 32
-                {
-                    return get_msgpack_string();
-                }
+        // reset width to 0 for subsequent calls to this stream
+        o.width(0);
 
-                case 0xdc: // array 16
-                {
-                    basic_json result = value_t::array;
-                    const auto len = static_cast<size_t>(get_number<uint16_t>());
-                    for (size_t i = 0; i < len; ++i)
-                    {
-                        result.push_back(parse_msgpack());
-                    }
-                    return result;
-                }
+        // do the actual serialization
+        serializer s(detail::output_adapter_factory<char>::create(o), o.fill());
+        s.dump(j, pretty_print, static_cast<unsigned int>(indentation));
+        return o;
+    }
 
-                case 0xdd: // array 32
-                {
-                    basic_json result = value_t::array;
-                    const auto len = static_cast<size_t>(get_number<uint32_t>());
-                    for (size_t i = 0; i < len; ++i)
-                    {
-                        result.push_back(parse_msgpack());
-                    }
-                    return result;
-                }
+    /*!
+    @brief serialize to stream
+    @deprecated This stream operator is deprecated and will be removed in a
+                future version of the library. Please use
+                @ref std::ostream& operator<<(std::ostream&, const basic_json&)
+                instead; that is, replace calls like `j >> o;` with `o << j;`.
+    */
+    JSON_DEPRECATED
+    friend std::ostream& operator>>(const basic_json& j, std::ostream& o)
+    {
+        return o << j;
+    }
 
-                case 0xde: // map 16
-                {
-                    basic_json result = value_t::object;
-                    const auto len = static_cast<size_t>(get_number<uint16_t>());
-                    for (size_t i = 0; i < len; ++i)
-                    {
-                        get();
-                        auto key = get_msgpack_string();
-                        result[key] = parse_msgpack();
-                    }
-                    return result;
-                }
+    /// @}
 
-                case 0xdf: // map 32
-                {
-                    basic_json result = value_t::object;
-                    const auto len = static_cast<size_t>(get_number<uint32_t>());
-                    for (size_t i = 0; i < len; ++i)
-                    {
-                        get();
-                        auto key = get_msgpack_string();
-                        result[key] = parse_msgpack();
-                    }
-                    return result;
-                }
 
-                // positive fixint
-                case 0xe0:
-                case 0xe1:
-                case 0xe2:
-                case 0xe3:
-                case 0xe4:
-                case 0xe5:
-                case 0xe6:
-                case 0xe7:
-                case 0xe8:
-                case 0xe9:
-                case 0xea:
-                case 0xeb:
-                case 0xec:
-                case 0xed:
-                case 0xee:
-                case 0xef:
-                case 0xf0:
-                case 0xf1:
-                case 0xf2:
-                case 0xf3:
-                case 0xf4:
-                case 0xf5:
-                case 0xf6:
-                case 0xf7:
-                case 0xf8:
-                case 0xf9:
-                case 0xfa:
-                case 0xfb:
-                case 0xfc:
-                case 0xfd:
-                case 0xfe:
-                case 0xff:
-                {
-                    return static_cast<int8_t>(current);
-                }
+    /////////////////////
+    // deserialization //
+    /////////////////////
 
-                default: // anything else
-                {
-                    std::stringstream ss;
-                    ss << std::setw(2) << std::setfill('0') << std::hex << current;
-                    JSON_THROW(parse_error::create(112, chars_read, "error reading MessagePack; last byte: 0x" + ss.str()));
-                }
-            }
-        }
+    /// @name deserialization
+    /// @{
 
-        /*!
-        @brief determine system byte order
+    /*!
+    @brief deserialize from an array
 
-        @return true iff system's byte order is little endian
+    This function reads from an array of 1-byte values.
 
-        @note from http://stackoverflow.com/a/1001328/266378
-        */
-        static bool little_endianess() noexcept
-        {
-            int num = 1;
-            return (*reinterpret_cast<char*>(&num) == 1);
-        }
+    @pre Each element of the container has a size of 1 byte. Violating this
+    precondition yields undefined behavior. **This precondition is enforced
+    with a static assertion.**
 
-      private:
-        /*!
-        @brief get next character from the input
+    @param[in] array  array to read from
+    @param[in] cb  a parser callback function of type @ref parser_callback_t
+    which is used to control the deserialization by filtering unwanted values
+    (optional)
 
-        This function provides the interface to the used input adapter. It does
-        not throw in case the input reached EOF, but returns
-        `std::char_traits<char>::eof()` in that case.
+    @return result of the deserialization
 
-        @return character read from the input
-        */
-        int get()
-        {
-            ++chars_read;
-            return (current = ia->get_character());
-        }
+    @throw parse_error.101 if a parse error occurs; example: `""unexpected end
+    of input; expected string literal""`
+    @throw parse_error.102 if to_unicode fails or surrogate error
+    @throw parse_error.103 if to_unicode fails
 
-        /*
-        @brief read a number from the input
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser. The complexity can be higher if the parser callback function
+    @a cb has a super-linear complexity.
 
-        @tparam NumberType the type of the number
+    @note A UTF-8 byte order mark is silently ignored.
 
-        @return number of type @a NumberType
+    @liveexample{The example below demonstrates the `parse()` function reading
+    from an array.,parse__array__parser_callback_t}
 
-        @note This function needs to respect the system's endianess, because
-              bytes in CBOR and MessagePack are stored in network order (big
-              endian) and therefore need reordering on little endian systems.
+    @since version 2.0.3
+    */
+    template<class T, std::size_t N>
+    static basic_json parse(T (&array)[N],
+                            const parser_callback_t cb = nullptr)
+    {
+        // delegate the call to the iterator-range parse overload
+        return parse(std::begin(array), std::end(array), cb);
+    }
 
-        @throw parse_error.110 if input has less than `sizeof(NumberType)`
-                               bytes
-        */
-        template<typename NumberType>
-        NumberType get_number()
-        {
-            // step 1: read input into array with system's byte order
-            std::array<uint8_t, sizeof(NumberType)> vec;
-            for (size_t i = 0; i < sizeof(NumberType); ++i)
-            {
-                get();
-                check_eof();
+    template<class T, std::size_t N>
+    static bool accept(T (&array)[N])
+    {
+        // delegate the call to the iterator-range accept overload
+        return accept(std::begin(array), std::end(array));
+    }
 
-                // reverse byte order prior to conversion if necessary
-                if (is_little_endian)
-                {
-                    vec[sizeof(NumberType) - i - 1] = static_cast<uint8_t>(current);
-                }
-                else
-                {
-                    vec[i] = static_cast<uint8_t>(current);  // LCOV_EXCL_LINE
-                }
-            }
+    /*!
+    @brief deserialize from string literal
 
-            // step 2: convert array into number of type T and return
-            NumberType result;
-            std::memcpy(&result, vec.data(), sizeof(NumberType));
-            return result;
-        }
+    @tparam CharT character/literal type with size of 1 byte
+    @param[in] s  string literal to read a serialized JSON value from
+    @param[in] cb a parser callback function of type @ref parser_callback_t
+    which is used to control the deserialization by filtering unwanted values
+    (optional)
 
-        /*!
-        @brief create a string by reading characters from the input
+    @return result of the deserialization
 
-        @param[in] len number of bytes to read
+    @throw parse_error.101 in case of an unexpected token
+    @throw parse_error.102 if to_unicode fails or surrogate error
+    @throw parse_error.103 if to_unicode fails
 
-        @note We can not reserve @a len bytes for the result, because @a len
-              may be too large. Usually, @ref check_eof() detects the end of
-              the input before we run out of string memory.
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser. The complexity can be higher if the parser callback function
+    @a cb has a super-linear complexity.
 
-        @return string created by reading @a len bytes
+    @note A UTF-8 byte order mark is silently ignored.
+    @note String containers like `std::string` or @ref string_t can be parsed
+          with @ref parse(const ContiguousContainer&, const parser_callback_t)
 
-        @throw parse_error.110 if input has less than @a len bytes
-        */
-        std::string get_string(const size_t len)
-        {
-            std::string result;
-            for (size_t i = 0; i < len; ++i)
-            {
-                get();
-                check_eof();
-                result.append(1, static_cast<char>(current));
-            }
-            return result;
-        }
+    @liveexample{The example below demonstrates the `parse()` function with
+    and without callback function.,parse__string__parser_callback_t}
 
-        /*!
-        @brief reads a CBOR string
+    @sa @ref parse(std::istream&, const parser_callback_t) for a version that
+    reads from an input stream
 
-        This function first reads starting bytes to determine the expected
-        string length and then copies this number of bytes into a string.
-        Additionally, CBOR's strings with indefinite lengths are supported.
+    @since version 1.0.0 (originally for @ref string_t)
+    */
+    template<typename CharT, typename std::enable_if<
+                 std::is_pointer<CharT>::value and
+                 std::is_integral<typename std::remove_pointer<CharT>::type>::value and
+                 sizeof(typename std::remove_pointer<CharT>::type) == 1, int>::type = 0>
+    static basic_json parse(const CharT s,
+                            const parser_callback_t cb = nullptr)
+    {
+        return parser(detail::input_adapter_factory::create(s), cb).parse(true);
+    }
 
-        @return string
+    template<typename CharT, typename std::enable_if<
+                 std::is_pointer<CharT>::value and
+                 std::is_integral<typename std::remove_pointer<CharT>::type>::value and
+                 sizeof(typename std::remove_pointer<CharT>::type) == 1, int>::type = 0>
+    static bool accept(const CharT s)
+    {
+        return parser(detail::input_adapter_factory::create(s)).accept(true);
+    }
 
-        @throw parse_error.110 if input ended
-        @throw parse_error.113 if an unexpected byte is read
-        */
-        std::string get_cbor_string()
-        {
-            check_eof();
+    /*!
+    @brief deserialize from stream
 
-            switch (current)
-            {
-                // UTF-8 string (0x00..0x17 bytes follow)
-                case 0x60:
-                case 0x61:
-                case 0x62:
-                case 0x63:
-                case 0x64:
-                case 0x65:
-                case 0x66:
-                case 0x67:
-                case 0x68:
-                case 0x69:
-                case 0x6a:
-                case 0x6b:
-                case 0x6c:
-                case 0x6d:
-                case 0x6e:
-                case 0x6f:
-                case 0x70:
-                case 0x71:
-                case 0x72:
-                case 0x73:
-                case 0x74:
-                case 0x75:
-                case 0x76:
-                case 0x77:
-                {
-                    const auto len = static_cast<size_t>(current & 0x1f);
-                    return get_string(len);
-                }
+    @param[in,out] i  stream to read a serialized JSON value from
+    @param[in] cb a parser callback function of type @ref parser_callback_t
+    which is used to control the deserialization by filtering unwanted values
+    (optional)
 
-                case 0x78: // UTF-8 string (one-byte uint8_t for n follows)
-                {
-                    const auto len = static_cast<size_t>(get_number<uint8_t>());
-                    return get_string(len);
-                }
+    @return result of the deserialization
 
-                case 0x79: // UTF-8 string (two-byte uint16_t for n follow)
-                {
-                    const auto len = static_cast<size_t>(get_number<uint16_t>());
-                    return get_string(len);
-                }
+    @throw parse_error.101 in case of an unexpected token
+    @throw parse_error.102 if to_unicode fails or surrogate error
+    @throw parse_error.103 if to_unicode fails
 
-                case 0x7a: // UTF-8 string (four-byte uint32_t for n follow)
-                {
-                    const auto len = static_cast<size_t>(get_number<uint32_t>());
-                    return get_string(len);
-                }
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser. The complexity can be higher if the parser callback function
+    @a cb has a super-linear complexity.
 
-                case 0x7b: // UTF-8 string (eight-byte uint64_t for n follow)
-                {
-                    const auto len = static_cast<size_t>(get_number<uint64_t>());
-                    return get_string(len);
-                }
+    @note A UTF-8 byte order mark is silently ignored.
 
-                case 0x7f: // UTF-8 string (indefinite length)
-                {
-                    std::string result;
-                    while (get() != 0xff)
-                    {
-                        check_eof();
-                        result.append(1, static_cast<char>(current));
-                    }
-                    return result;
-                }
+    @liveexample{The example below demonstrates the `parse()` function with
+    and without callback function.,parse__istream__parser_callback_t}
 
-                default:
-                {
-                    std::stringstream ss;
-                    ss << std::setw(2) << std::setfill('0') << std::hex << current;
-                    JSON_THROW(parse_error::create(113, chars_read, "expected a CBOR string; last byte: 0x" + ss.str()));
-                }
-            }
-        }
+    @sa @ref parse(const CharT, const parser_callback_t) for a version
+    that reads from a string
 
-        /*!
-        @brief reads a MessagePack string
+    @since version 1.0.0
+    */
+    static basic_json parse(std::istream& i,
+                            const parser_callback_t cb = nullptr)
+    {
+        return parser(detail::input_adapter_factory::create(i), cb).parse(true);
+    }
 
-        This function first reads starting bytes to determine the expected
-        string length and then copies this number of bytes into a string.
+    static bool accept(std::istream& i)
+    {
+        return parser(detail::input_adapter_factory::create(i)).accept(true);
+    }
 
-        @return string
+    /*!
+    @copydoc parse(std::istream&, const parser_callback_t)
+    */
+    static basic_json parse(std::istream&& i,
+                            const parser_callback_t cb = nullptr)
+    {
+        return parser(detail::input_adapter_factory::create(i), cb).parse(true);
+    }
 
-        @throw parse_error.110 if input ended
-        @throw parse_error.113 if an unexpected byte is read
-        */
-        std::string get_msgpack_string()
-        {
-            check_eof();
+    static bool accept(std::istream&& i)
+    {
+        return parser(detail::input_adapter_factory::create(i)).accept(true);
+    }
 
-            switch (current)
-            {
-                // fixstr
-                case 0xa0:
-                case 0xa1:
-                case 0xa2:
-                case 0xa3:
-                case 0xa4:
-                case 0xa5:
-                case 0xa6:
-                case 0xa7:
-                case 0xa8:
-                case 0xa9:
-                case 0xaa:
-                case 0xab:
-                case 0xac:
-                case 0xad:
-                case 0xae:
-                case 0xaf:
-                case 0xb0:
-                case 0xb1:
-                case 0xb2:
-                case 0xb3:
-                case 0xb4:
-                case 0xb5:
-                case 0xb6:
-                case 0xb7:
-                case 0xb8:
-                case 0xb9:
-                case 0xba:
-                case 0xbb:
-                case 0xbc:
-                case 0xbd:
-                case 0xbe:
-                case 0xbf:
-                {
-                    const auto len = static_cast<size_t>(current & 0x1f);
-                    return get_string(len);
-                }
+    /*!
+    @brief deserialize from an iterator range with contiguous storage
 
-                case 0xd9: // str 8
-                {
-                    const auto len = static_cast<size_t>(get_number<uint8_t>());
-                    return get_string(len);
-                }
+    This function reads from an iterator range of a container with contiguous
+    storage of 1-byte values. Compatible container types include
+    `std::vector`, `std::string`, `std::array`, `std::valarray`, and
+    `std::initializer_list`. Furthermore, C-style arrays can be used with
+    `std::begin()`/`std::end()`. User-defined containers can be used as long
+    as they implement random-access iterators and a contiguous storage.
 
-                case 0xda: // str 16
-                {
-                    const auto len = static_cast<size_t>(get_number<uint16_t>());
-                    return get_string(len);
-                }
+    @pre The iterator range is contiguous. Violating this precondition yields
+    undefined behavior. **This precondition is enforced with an assertion.**
+    @pre Each element in the range has a size of 1 byte. Violating this
+    precondition yields undefined behavior. **This precondition is enforced
+    with a static assertion.**
 
-                case 0xdb: // str 32
-                {
-                    const auto len = static_cast<size_t>(get_number<uint32_t>());
-                    return get_string(len);
-                }
+    @warning There is no way to enforce all preconditions at compile-time. If
+             the function is called with noncompliant iterators and with
+             assertions switched off, the behavior is undefined and will most
+             likely yield segmentation violation.
 
-                default:
-                {
-                    std::stringstream ss;
-                    ss << std::setw(2) << std::setfill('0') << std::hex << current;
-                    JSON_THROW(parse_error::create(113, chars_read, "expected a MessagePack string; last byte: 0x" + ss.str()));
-                }
-            }
-        }
+    @tparam IteratorType iterator of container with contiguous storage
+    @param[in] first  begin of the range to parse (included)
+    @param[in] last  end of the range to parse (excluded)
+    @param[in] cb  a parser callback function of type @ref parser_callback_t
+    which is used to control the deserialization by filtering unwanted values
+    (optional)
 
-        /*!
-        @brief check if input ended
-        @throw parse_error.110 if input ended
-        */
-        void check_eof() const
-        {
-            if (JSON_UNLIKELY(current == std::char_traits<char>::eof()))
-            {
-                JSON_THROW(parse_error::create(110, chars_read, "unexpected end of input"));
-            }
-        }
+    @return result of the deserialization
 
-      private:
-        /// input adapter
-        detail::input_adapter_t ia = nullptr;
+    @throw parse_error.101 in case of an unexpected token
+    @throw parse_error.102 if to_unicode fails or surrogate error
+    @throw parse_error.103 if to_unicode fails
 
-        /// the current character
-        int current = std::char_traits<char>::eof();
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser. The complexity can be higher if the parser callback function
+    @a cb has a super-linear complexity.
 
-        /// the number of characters read
-        size_t chars_read = 0;
+    @note A UTF-8 byte order mark is silently ignored.
 
-        /// whether we can assume little endianess
-        const bool is_little_endian = true;
-    };
+    @liveexample{The example below demonstrates the `parse()` function reading
+    from an iterator range.,parse__iteratortype__parser_callback_t}
 
-    /*!
-    @brief serialization to CBOR and MessagePack values
+    @since version 2.0.3
     */
-    class binary_writer
+    template<class IteratorType, typename std::enable_if<
+                 std::is_base_of<
+                     std::random_access_iterator_tag,
+                     typename std::iterator_traits<IteratorType>::iterator_category>::value, int>::type = 0>
+    static basic_json parse(IteratorType first, IteratorType last,
+                            const parser_callback_t cb = nullptr)
     {
-      public:
-        /*!
-        @brief create a binary writer
+        return parser(detail::input_adapter_factory::create(first, last), cb).parse(true);
+    }
 
-        @param[in] adapter  output adapter to write to
-        */
-        explicit binary_writer(output_adapter_t<uint8_t> adapter)
-            : is_little_endian(binary_reader::little_endianess()), oa(adapter)
-        {
-            assert(oa);
-        }
+    template<class IteratorType, typename std::enable_if<
+                 std::is_base_of<
+                     std::random_access_iterator_tag,
+                     typename std::iterator_traits<IteratorType>::iterator_category>::value, int>::type = 0>
+    static bool accept(IteratorType first, IteratorType last)
+    {
+        return parser(detail::input_adapter_factory::create(first, last)).accept(true);
+    }
 
-        /*!
-        @brief[in] j  JSON value to serialize
-        */
-        void write_cbor(const basic_json& j)
-        {
-            switch (j.type())
-            {
-                case value_t::null:
-                {
-                    oa->write_character(0xf6);
-                    break;
-                }
+    /*!
+    @brief deserialize from a container with contiguous storage
 
-                case value_t::boolean:
-                {
-                    oa->write_character(j.m_value.boolean ? 0xf5 : 0xf4);
-                    break;
-                }
+    This function reads from a container with contiguous storage of 1-byte
+    values. Compatible container types include `std::vector`, `std::string`,
+    `std::array`, and `std::initializer_list`. User-defined containers can be
+    used as long as they implement random-access iterators and a contiguous
+    storage.
 
-                case value_t::number_integer:
-                {
-                    if (j.m_value.number_integer >= 0)
-                    {
-                        // CBOR does not differentiate between positive signed
-                        // integers and unsigned integers. Therefore, we used the
-                        // code from the value_t::number_unsigned case here.
-                        if (j.m_value.number_integer <= 0x17)
-                        {
-                            write_number(static_cast<uint8_t>(j.m_value.number_integer));
-                        }
-                        else if (j.m_value.number_integer <= (std::numeric_limits<uint8_t>::max)())
-                        {
-                            oa->write_character(0x18);
-                            write_number(static_cast<uint8_t>(j.m_value.number_integer));
-                        }
-                        else if (j.m_value.number_integer <= (std::numeric_limits<uint16_t>::max)())
-                        {
-                            oa->write_character(0x19);
-                            write_number(static_cast<uint16_t>(j.m_value.number_integer));
-                        }
-                        else if (j.m_value.number_integer <= (std::numeric_limits<uint32_t>::max)())
-                        {
-                            oa->write_character(0x1a);
-                            write_number(static_cast<uint32_t>(j.m_value.number_integer));
-                        }
-                        else
-                        {
-                            oa->write_character(0x1b);
-                            write_number(static_cast<uint64_t>(j.m_value.number_integer));
-                        }
-                    }
-                    else
-                    {
-                        // The conversions below encode the sign in the first
-                        // byte, and the value is converted to a positive number.
-                        const auto positive_number = -1 - j.m_value.number_integer;
-                        if (j.m_value.number_integer >= -24)
-                        {
-                            write_number(static_cast<uint8_t>(0x20 + positive_number));
-                        }
-                        else if (positive_number <= (std::numeric_limits<uint8_t>::max)())
-                        {
-                            oa->write_character(0x38);
-                            write_number(static_cast<uint8_t>(positive_number));
-                        }
-                        else if (positive_number <= (std::numeric_limits<uint16_t>::max)())
-                        {
-                            oa->write_character(0x39);
-                            write_number(static_cast<uint16_t>(positive_number));
-                        }
-                        else if (positive_number <= (std::numeric_limits<uint32_t>::max)())
-                        {
-                            oa->write_character(0x3a);
-                            write_number(static_cast<uint32_t>(positive_number));
-                        }
-                        else
-                        {
-                            oa->write_character(0x3b);
-                            write_number(static_cast<uint64_t>(positive_number));
-                        }
-                    }
-                    break;
-                }
+    @pre The container storage is contiguous. Violating this precondition
+    yields undefined behavior. **This precondition is enforced with an
+    assertion.**
+    @pre Each element of the container has a size of 1 byte. Violating this
+    precondition yields undefined behavior. **This precondition is enforced
+    with a static assertion.**
 
-                case value_t::number_unsigned:
-                {
-                    if (j.m_value.number_unsigned <= 0x17)
-                    {
-                        write_number(static_cast<uint8_t>(j.m_value.number_unsigned));
-                    }
-                    else if (j.m_value.number_unsigned <= (std::numeric_limits<uint8_t>::max)())
-                    {
-                        oa->write_character(0x18);
-                        write_number(static_cast<uint8_t>(j.m_value.number_unsigned));
-                    }
-                    else if (j.m_value.number_unsigned <= (std::numeric_limits<uint16_t>::max)())
-                    {
-                        oa->write_character(0x19);
-                        write_number(static_cast<uint16_t>(j.m_value.number_unsigned));
-                    }
-                    else if (j.m_value.number_unsigned <= (std::numeric_limits<uint32_t>::max)())
-                    {
-                        oa->write_character(0x1a);
-                        write_number(static_cast<uint32_t>(j.m_value.number_unsigned));
-                    }
-                    else
-                    {
-                        oa->write_character(0x1b);
-                        write_number(static_cast<uint64_t>(j.m_value.number_unsigned));
-                    }
-                    break;
-                }
+    @warning There is no way to enforce all preconditions at compile-time. If
+             the function is called with a noncompliant container and with
+             assertions switched off, the behavior is undefined and will most
+             likely yield segmentation violation.
 
-                case value_t::number_float:
-                {
-                    // Double-Precision Float
-                    oa->write_character(0xfb);
-                    write_number(j.m_value.number_float);
-                    break;
-                }
+    @tparam ContiguousContainer container type with contiguous storage
+    @param[in] c  container to read from
+    @param[in] cb  a parser callback function of type @ref parser_callback_t
+    which is used to control the deserialization by filtering unwanted values
+    (optional)
 
-                case value_t::string:
-                {
-                    // step 1: write control byte and the string length
-                    const auto N = j.m_value.string->size();
-                    if (N <= 0x17)
-                    {
-                        write_number(static_cast<uint8_t>(0x60 + N));
-                    }
-                    else if (N <= 0xff)
-                    {
-                        oa->write_character(0x78);
-                        write_number(static_cast<uint8_t>(N));
-                    }
-                    else if (N <= 0xffff)
-                    {
-                        oa->write_character(0x79);
-                        write_number(static_cast<uint16_t>(N));
-                    }
-                    else if (N <= 0xffffffff)
-                    {
-                        oa->write_character(0x7a);
-                        write_number(static_cast<uint32_t>(N));
-                    }
-                    // LCOV_EXCL_START
-                    else if (N <= 0xffffffffffffffff)
-                    {
-                        oa->write_character(0x7b);
-                        write_number(static_cast<uint64_t>(N));
-                    }
-                    // LCOV_EXCL_STOP
+    @return result of the deserialization
+
+    @throw parse_error.101 in case of an unexpected token
+    @throw parse_error.102 if to_unicode fails or surrogate error
+    @throw parse_error.103 if to_unicode fails
+
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser. The complexity can be higher if the parser callback function
+    @a cb has a super-linear complexity.
+
+    @note A UTF-8 byte order mark is silently ignored.
+
+    @liveexample{The example below demonstrates the `parse()` function reading
+    from a contiguous container.,parse__contiguouscontainer__parser_callback_t}
+
+    @since version 2.0.3
+    */
+    template<class ContiguousContainer, typename std::enable_if<
+                 not std::is_pointer<ContiguousContainer>::value and
+                 std::is_base_of<
+                     std::random_access_iterator_tag,
+                     typename std::iterator_traits<decltype(std::begin(std::declval<ContiguousContainer const>()))>::iterator_category>::value
+                 , int>::type = 0>
+    static basic_json parse(const ContiguousContainer& c,
+                            const parser_callback_t cb = nullptr)
+    {
+        // delegate the call to the iterator-range parse overload
+        return parse(std::begin(c), std::end(c), cb);
+    }
 
-                    // step 2: write the string
-                    oa->write_characters(reinterpret_cast<const uint8_t*>(j.m_value.string->c_str()),
-                                         j.m_value.string->size());
-                    break;
-                }
+    template<class ContiguousContainer, typename std::enable_if<
+                 not std::is_pointer<ContiguousContainer>::value and
+                 std::is_base_of<
+                     std::random_access_iterator_tag,
+                     typename std::iterator_traits<decltype(std::begin(std::declval<ContiguousContainer const>()))>::iterator_category>::value
+                 , int>::type = 0>
+    static bool accept(const ContiguousContainer& c)
+    {
+        // delegate the call to the iterator-range accept overload
+        return accept(std::begin(c), std::end(c));
+    }
 
-                case value_t::array:
-                {
-                    // step 1: write control byte and the array size
-                    const auto N = j.m_value.array->size();
-                    if (N <= 0x17)
-                    {
-                        write_number(static_cast<uint8_t>(0x80 + N));
-                    }
-                    else if (N <= 0xff)
-                    {
-                        oa->write_character(0x98);
-                        write_number(static_cast<uint8_t>(N));
-                    }
-                    else if (N <= 0xffff)
-                    {
-                        oa->write_character(0x99);
-                        write_number(static_cast<uint16_t>(N));
-                    }
-                    else if (N <= 0xffffffff)
-                    {
-                        oa->write_character(0x9a);
-                        write_number(static_cast<uint32_t>(N));
-                    }
-                    // LCOV_EXCL_START
-                    else if (N <= 0xffffffffffffffff)
-                    {
-                        oa->write_character(0x9b);
-                        write_number(static_cast<uint64_t>(N));
-                    }
-                    // LCOV_EXCL_STOP
+    /*!
+    @brief deserialize from stream
+    @deprecated This stream operator is deprecated and will be removed in a
+                future version of the library. Please use
+                @ref std::istream& operator>>(std::istream&, basic_json&)
+                instead; that is, replace calls like `j << i;` with `i >> j;`.
+    */
+    JSON_DEPRECATED
+    friend std::istream& operator<<(basic_json& j, std::istream& i)
+    {
+        j = parser(detail::input_adapter_factory::create(i)).parse(false);
+        return i;
+    }
 
-                    // step 2: write each element
-                    for (const auto& el : *j.m_value.array)
-                    {
-                        write_cbor(el);
-                    }
-                    break;
-                }
+    /*!
+    @brief deserialize from stream
 
-                case value_t::object:
-                {
-                    // step 1: write control byte and the object size
-                    const auto N = j.m_value.object->size();
-                    if (N <= 0x17)
-                    {
-                        write_number(static_cast<uint8_t>(0xa0 + N));
-                    }
-                    else if (N <= 0xff)
-                    {
-                        oa->write_character(0xb8);
-                        write_number(static_cast<uint8_t>(N));
-                    }
-                    else if (N <= 0xffff)
-                    {
-                        oa->write_character(0xb9);
-                        write_number(static_cast<uint16_t>(N));
-                    }
-                    else if (N <= 0xffffffff)
-                    {
-                        oa->write_character(0xba);
-                        write_number(static_cast<uint32_t>(N));
-                    }
-                    // LCOV_EXCL_START
-                    else if (N <= 0xffffffffffffffff)
-                    {
-                        oa->write_character(0xbb);
-                        write_number(static_cast<uint64_t>(N));
-                    }
-                    // LCOV_EXCL_STOP
+    Deserializes an input stream to a JSON value.
 
-                    // step 2: write each element
-                    for (const auto& el : *j.m_value.object)
-                    {
-                        write_cbor(el.first);
-                        write_cbor(el.second);
-                    }
-                    break;
-                }
+    @param[in,out] i  input stream to read a serialized JSON value from
+    @param[in,out] j  JSON value to write the deserialized input to
 
-                default:
-                {
-                    break;
-                }
-            }
-        }
+    @throw parse_error.101 in case of an unexpected token
+    @throw parse_error.102 if to_unicode fails or surrogate error
+    @throw parse_error.103 if to_unicode fails
 
-        /*!
-        @brief[in] j  JSON value to serialize
-        */
-        void write_msgpack(const basic_json& j)
-        {
-            switch (j.type())
-            {
-                case value_t::null:
-                {
-                    // nil
-                    oa->write_character(0xc0);
-                    break;
-                }
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser.
 
-                case value_t::boolean:
-                {
-                    // true and false
-                    oa->write_character(j.m_value.boolean ? 0xc3 : 0xc2);
-                    break;
-                }
+    @note A UTF-8 byte order mark is silently ignored.
 
-                case value_t::number_integer:
-                {
-                    if (j.m_value.number_integer >= 0)
-                    {
-                        // MessagePack does not differentiate between positive
-                        // signed integers and unsigned integers. Therefore, we
-                        // used the code from the value_t::number_unsigned case
-                        // here.
-                        if (j.m_value.number_unsigned < 128)
-                        {
-                            // positive fixnum
-                            write_number(static_cast<uint8_t>(j.m_value.number_integer));
-                        }
-                        else if (j.m_value.number_unsigned <= (std::numeric_limits<uint8_t>::max)())
-                        {
-                            // uint 8
-                            oa->write_character(0xcc);
-                            write_number(static_cast<uint8_t>(j.m_value.number_integer));
-                        }
-                        else if (j.m_value.number_unsigned <= (std::numeric_limits<uint16_t>::max)())
-                        {
-                            // uint 16
-                            oa->write_character(0xcd);
-                            write_number(static_cast<uint16_t>(j.m_value.number_integer));
-                        }
-                        else if (j.m_value.number_unsigned <= (std::numeric_limits<uint32_t>::max)())
-                        {
-                            // uint 32
-                            oa->write_character(0xce);
-                            write_number(static_cast<uint32_t>(j.m_value.number_integer));
-                        }
-                        else if (j.m_value.number_unsigned <= (std::numeric_limits<uint64_t>::max)())
-                        {
-                            // uint 64
-                            oa->write_character(0xcf);
-                            write_number(static_cast<uint64_t>(j.m_value.number_integer));
-                        }
-                    }
-                    else
-                    {
-                        if (j.m_value.number_integer >= -32)
-                        {
-                            // negative fixnum
-                            write_number(static_cast<int8_t>(j.m_value.number_integer));
-                        }
-                        else if (j.m_value.number_integer >= (std::numeric_limits<int8_t>::min)() and j.m_value.number_integer <= (std::numeric_limits<int8_t>::max)())
-                        {
-                            // int 8
-                            oa->write_character(0xd0);
-                            write_number(static_cast<int8_t>(j.m_value.number_integer));
-                        }
-                        else if (j.m_value.number_integer >= (std::numeric_limits<int16_t>::min)() and j.m_value.number_integer <= (std::numeric_limits<int16_t>::max)())
-                        {
-                            // int 16
-                            oa->write_character(0xd1);
-                            write_number(static_cast<int16_t>(j.m_value.number_integer));
-                        }
-                        else if (j.m_value.number_integer >= (std::numeric_limits<int32_t>::min)() and j.m_value.number_integer <= (std::numeric_limits<int32_t>::max)())
-                        {
-                            // int 32
-                            oa->write_character(0xd2);
-                            write_number(static_cast<int32_t>(j.m_value.number_integer));
-                        }
-                        else if (j.m_value.number_integer >= (std::numeric_limits<int64_t>::min)() and j.m_value.number_integer <= (std::numeric_limits<int64_t>::max)())
-                        {
-                            // int 64
-                            oa->write_character(0xd3);
-                            write_number(static_cast<int64_t>(j.m_value.number_integer));
-                        }
-                    }
-                    break;
-                }
+    @liveexample{The example below shows how a JSON value is constructed by
+    reading a serialization from a stream.,operator_deserialize}
 
-                case value_t::number_unsigned:
-                {
-                    if (j.m_value.number_unsigned < 128)
-                    {
-                        // positive fixnum
-                        write_number(static_cast<uint8_t>(j.m_value.number_integer));
-                    }
-                    else if (j.m_value.number_unsigned <= (std::numeric_limits<uint8_t>::max)())
-                    {
-                        // uint 8
-                        oa->write_character(0xcc);
-                        write_number(static_cast<uint8_t>(j.m_value.number_integer));
-                    }
-                    else if (j.m_value.number_unsigned <= (std::numeric_limits<uint16_t>::max)())
-                    {
-                        // uint 16
-                        oa->write_character(0xcd);
-                        write_number(static_cast<uint16_t>(j.m_value.number_integer));
-                    }
-                    else if (j.m_value.number_unsigned <= (std::numeric_limits<uint32_t>::max)())
-                    {
-                        // uint 32
-                        oa->write_character(0xce);
-                        write_number(static_cast<uint32_t>(j.m_value.number_integer));
-                    }
-                    else if (j.m_value.number_unsigned <= (std::numeric_limits<uint64_t>::max)())
-                    {
-                        // uint 64
-                        oa->write_character(0xcf);
-                        write_number(static_cast<uint64_t>(j.m_value.number_integer));
-                    }
-                    break;
-                }
+    @sa parse(std::istream&, const parser_callback_t) for a variant with a
+    parser callback function to filter values while parsing
 
-                case value_t::number_float:
-                {
-                    // float 64
-                    oa->write_character(0xcb);
-                    write_number(j.m_value.number_float);
-                    break;
-                }
+    @since version 1.0.0
+    */
+    friend std::istream& operator>>(std::istream& i, basic_json& j)
+    {
+        j = parser(detail::input_adapter_factory::create(i)).parse(false);
+        return i;
+    }
 
-                case value_t::string:
-                {
-                    // step 1: write control byte and the string length
-                    const auto N = j.m_value.string->size();
-                    if (N <= 31)
-                    {
-                        // fixstr
-                        write_number(static_cast<uint8_t>(0xa0 | N));
-                    }
-                    else if (N <= 255)
-                    {
-                        // str 8
-                        oa->write_character(0xd9);
-                        write_number(static_cast<uint8_t>(N));
-                    }
-                    else if (N <= 65535)
-                    {
-                        // str 16
-                        oa->write_character(0xda);
-                        write_number(static_cast<uint16_t>(N));
-                    }
-                    else if (N <= 4294967295)
-                    {
-                        // str 32
-                        oa->write_character(0xdb);
-                        write_number(static_cast<uint32_t>(N));
-                    }
+    /// @}
 
-                    // step 2: write the string
-                    oa->write_characters(reinterpret_cast<const uint8_t*>(j.m_value.string->c_str()),
-                                         j.m_value.string->size());
-                    break;
-                }
+    ///////////////////////////
+    // convenience functions //
+    ///////////////////////////
 
-                case value_t::array:
-                {
-                    // step 1: write control byte and the array size
-                    const auto N = j.m_value.array->size();
-                    if (N <= 15)
-                    {
-                        // fixarray
-                        write_number(static_cast<uint8_t>(0x90 | N));
-                    }
-                    else if (N <= 0xffff)
-                    {
-                        // array 16
-                        oa->write_character(0xdc);
-                        write_number(static_cast<uint16_t>(N));
-                    }
-                    else if (N <= 0xffffffff)
-                    {
-                        // array 32
-                        oa->write_character(0xdd);
-                        write_number(static_cast<uint32_t>(N));
-                    }
+    /*!
+    @brief return the type as string
 
-                    // step 2: write each element
-                    for (const auto& el : *j.m_value.array)
-                    {
-                        write_msgpack(el);
-                    }
-                    break;
-                }
+    Returns the type name as string to be used in error messages - usually to
+    indicate that a function was called on a wrong JSON type.
 
-                case value_t::object:
-                {
-                    // step 1: write control byte and the object size
-                    const auto N = j.m_value.object->size();
-                    if (N <= 15)
-                    {
-                        // fixmap
-                        write_number(static_cast<uint8_t>(0x80 | (N & 0xf)));
-                    }
-                    else if (N <= 65535)
-                    {
-                        // map 16
-                        oa->write_character(0xde);
-                        write_number(static_cast<uint16_t>(N));
-                    }
-                    else if (N <= 4294967295)
-                    {
-                        // map 32
-                        oa->write_character(0xdf);
-                        write_number(static_cast<uint32_t>(N));
-                    }
+    @return basically a string representation of a the @a m_type member
 
-                    // step 2: write each element
-                    for (const auto& el : *j.m_value.object)
-                    {
-                        write_msgpack(el.first);
-                        write_msgpack(el.second);
-                    }
-                    break;
-                }
+    @complexity Constant.
+
+    @liveexample{The following code exemplifies `type_name()` for all JSON
+    types.,type_name}
 
+    @since version 1.0.0, public since 2.1.0
+    */
+    std::string type_name() const
+    {
+        {
+            switch (m_type)
+            {
+                case value_t::null:
+                    return "null";
+                case value_t::object:
+                    return "object";
+                case value_t::array:
+                    return "array";
+                case value_t::string:
+                    return "string";
+                case value_t::boolean:
+                    return "boolean";
+                case value_t::discarded:
+                    return "discarded";
                 default:
-                {
-                    break;
-                }
+                    return "number";
             }
         }
+    }
 
-      private:
-        /*
-        @brief write a number to output input
-
-        @param[in] n number of type @a NumberType
-        @tparam NumberType the type of the number
 
-        @note This function needs to respect the system's endianess, because
-              bytes in CBOR and MessagePack are stored in network order (big
-              endian) and therefore need reordering on little endian systems.
-        */
-        template<typename NumberType>
-        void write_number(NumberType n)
-        {
-            // step 1: write number to array of length NumberType
-            std::array<uint8_t, sizeof(NumberType)> vec;
-            std::memcpy(vec.data(), &n, sizeof(NumberType));
+  private:
+    //////////////////////
+    // member variables //
+    //////////////////////
 
-            // step 2: write array to output (with possible reordering)
-            if (is_little_endian)
-            {
-                // reverse byte order prior to conversion if necessary
-                std::reverse(vec.begin(), vec.end());
-            }
+    /// the type of the current element
+    value_t m_type = value_t::null;
 
-            oa->write_characters(vec.data(), sizeof(NumberType));
-        }
+    /// the value of the current element
+    json_value m_value = {};
 
-      private:
-        /// whether we can assume little endianess
-        const bool is_little_endian = true;
+    //////////////////////////////////////////
+    // binary serialization/deserialization //
+    //////////////////////////////////////////
 
-        /// the output
-        output_adapter_t<uint8_t> oa = nullptr;
-    };
+    /// @name binary serialization/deserialization support
+    /// @{
 
   public:
     /*!
@@ -13167,7 +13212,7 @@ class basic_json
     static std::vector<uint8_t> to_cbor(const basic_json& j)
     {
         std::vector<uint8_t> result;
-        binary_writer bw(output_adapter<uint8_t>::create(result));
+        binary_writer bw(detail::output_adapter_factory<uint8_t>::create(result));
         bw.write_cbor(j);
         return result;
     }
@@ -13249,7 +13294,7 @@ class basic_json
     static std::vector<uint8_t> to_msgpack(const basic_json& j)
     {
         std::vector<uint8_t> result;
-        binary_writer bw(output_adapter<uint8_t>::create(result));
+        binary_writer bw(detail::output_adapter_factory<uint8_t>::create(result));
         bw.write_msgpack(j);
         return result;
     }
diff --git a/test/src/unit-convenience.cpp b/test/src/unit-convenience.cpp
index f757541d9e..52746028ea 100644
--- a/test/src/unit-convenience.cpp
+++ b/test/src/unit-convenience.cpp
@@ -53,7 +53,7 @@ TEST_CASE("convenience functions")
                                       const char* escaped)
         {
             std::stringstream ss;
-            json::serializer s(json::output_adapter<char>::create(ss), ' ');
+            json::serializer s(nlohmann::detail::output_adapter_factory<char>::create(ss), ' ');
             s.dump_escaped(original);
             CHECK(ss.str() == escaped);
         };

From 8585d35c924f3a14e596af46da50688637f9ddf0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9o=20DELRIEU?= <delrieutheo@gmail.com>
Date: Sun, 9 Jul 2017 17:43:59 +0200
Subject: [PATCH 9/9] move serializer outside of basic_json

---
 src/json.hpp | 1191 +++++++++++++++++++++++++-------------------------
 1 file changed, 599 insertions(+), 592 deletions(-)

diff --git a/src/json.hpp b/src/json.hpp
index d3f3571017..39db611c6e 100644
--- a/src/json.hpp
+++ b/src/json.hpp
@@ -6378,6 +6378,601 @@ class binary_writer
     /// the output
     output_adapter_t<uint8_t> oa = nullptr;
 };
+
+///////////////////
+// serialization //
+///////////////////
+
+template <typename BasicJsonType>
+class serializer
+{
+    using string_t = typename BasicJsonType::string_t;
+    using number_float_t = typename BasicJsonType::number_float_t;
+    using number_integer_t = typename BasicJsonType::number_integer_t;
+    using number_unsigned_t = typename BasicJsonType::number_unsigned_t;
+  public:
+    /*!
+    @param[in] s  output stream to serialize to
+    @param[in] ichar  indentation character to use
+    */
+    serializer(output_adapter_t<char> s, const char ichar)
+        : o(s), loc(std::localeconv()),
+          thousands_sep(!loc->thousands_sep ? '\0' : loc->thousands_sep[0]),
+          decimal_point(!loc->decimal_point ? '\0' : loc->decimal_point[0]),
+          indent_char(ichar), indent_string(512, indent_char) {}
+
+    // delete because of pointer members
+    serializer(const serializer&) = delete;
+    serializer& operator=(const serializer&) = delete;
+
+    /*!
+    @brief internal implementation of the serialization function
+
+    This function is called by the public member function dump and
+    organizes the serialization internally. The indentation level is
+    propagated as additional parameter. In case of arrays and objects, the
+    function is called recursively.
+
+    - strings and object keys are escaped using `escape_string()`
+    - integer numbers are converted implicitly via `operator<<`
+    - floating-point numbers are converted to a string using `"%g"` format
+
+    @param[in] val             value to serialize
+    @param[in] pretty_print    whether the output shall be pretty-printed
+    @param[in] indent_step     the indent level
+    @param[in] current_indent  the current indent level (only used internally)
+    */
+    void dump(const BasicJsonType& val, const bool pretty_print,
+              const unsigned int indent_step,
+              const unsigned int current_indent = 0)
+    {
+        switch (val.m_type)
+        {
+            case value_t::object:
+            {
+                if (val.m_value.object->empty())
+                {
+                    o->write_characters("{}", 2);
+                    return;
+                }
+
+                if (pretty_print)
+                {
+                    o->write_characters("{\n", 2);
+
+                    // variable to hold indentation for recursive calls
+                    const auto new_indent = current_indent + indent_step;
+                    if (JSON_UNLIKELY(indent_string.size() < new_indent))
+                    {
+                        indent_string.resize(indent_string.size() * 2, ' ');
+                    }
+
+                    // first n-1 elements
+                    auto i = val.m_value.object->cbegin();
+                    for (size_t cnt = 0; cnt < val.m_value.object->size() - 1; ++cnt, ++i)
+                    {
+                        o->write_characters(indent_string.c_str(), new_indent);
+                        o->write_character('\"');
+                        dump_escaped(i->first);
+                        o->write_characters("\": ", 3);
+                        dump(i->second, true, indent_step, new_indent);
+                        o->write_characters(",\n", 2);
+                    }
+
+                    // last element
+                    assert(i != val.m_value.object->cend());
+                    o->write_characters(indent_string.c_str(), new_indent);
+                    o->write_character('\"');
+                    dump_escaped(i->first);
+                    o->write_characters("\": ", 3);
+                    dump(i->second, true, indent_step, new_indent);
+
+                    o->write_character('\n');
+                    o->write_characters(indent_string.c_str(), current_indent);
+                    o->write_character('}');
+                }
+                else
+                {
+                    o->write_character('{');
+
+                    // first n-1 elements
+                    auto i = val.m_value.object->cbegin();
+                    for (size_t cnt = 0; cnt < val.m_value.object->size() - 1; ++cnt, ++i)
+                    {
+                        o->write_character('\"');
+                        dump_escaped(i->first);
+                        o->write_characters("\":", 2);
+                        dump(i->second, false, indent_step, current_indent);
+                        o->write_character(',');
+                    }
+
+                    // last element
+                    assert(i != val.m_value.object->cend());
+                    o->write_character('\"');
+                    dump_escaped(i->first);
+                    o->write_characters("\":", 2);
+                    dump(i->second, false, indent_step, current_indent);
+
+                    o->write_character('}');
+                }
+
+                return;
+            }
+
+            case value_t::array:
+            {
+                if (val.m_value.array->empty())
+                {
+                    o->write_characters("[]", 2);
+                    return;
+                }
+
+                if (pretty_print)
+                {
+                    o->write_characters("[\n", 2);
+
+                    // variable to hold indentation for recursive calls
+                    const auto new_indent = current_indent + indent_step;
+                    if (indent_string.size() < new_indent)
+                    {
+                        indent_string.resize(new_indent, ' ');
+                    }
+
+                    // first n-1 elements
+                    for (auto i = val.m_value.array->cbegin();
+                            i != val.m_value.array->cend() - 1; ++i)
+                    {
+                        o->write_characters(indent_string.c_str(), new_indent);
+                        dump(*i, true, indent_step, new_indent);
+                        o->write_characters(",\n", 2);
+                    }
+
+                    // last element
+                    assert(not val.m_value.array->empty());
+                    o->write_characters(indent_string.c_str(), new_indent);
+                    dump(val.m_value.array->back(), true, indent_step, new_indent);
+
+                    o->write_character('\n');
+                    o->write_characters(indent_string.c_str(), current_indent);
+                    o->write_character(']');
+                }
+                else
+                {
+                    o->write_character('[');
+
+                    // first n-1 elements
+                    for (auto i = val.m_value.array->cbegin();
+                            i != val.m_value.array->cend() - 1; ++i)
+                    {
+                        dump(*i, false, indent_step, current_indent);
+                        o->write_character(',');
+                    }
+
+                    // last element
+                    assert(not val.m_value.array->empty());
+                    dump(val.m_value.array->back(), false, indent_step, current_indent);
+
+                    o->write_character(']');
+                }
+
+                return;
+            }
+
+            case value_t::string:
+            {
+                o->write_character('\"');
+                dump_escaped(*val.m_value.string);
+                o->write_character('\"');
+                return;
+            }
+
+            case value_t::boolean:
+            {
+                if (val.m_value.boolean)
+                {
+                    o->write_characters("true", 4);
+                }
+                else
+                {
+                    o->write_characters("false", 5);
+                }
+                return;
+            }
+
+            case value_t::number_integer:
+            {
+                dump_integer(val.m_value.number_integer);
+                return;
+            }
+
+            case value_t::number_unsigned:
+            {
+                dump_integer(val.m_value.number_unsigned);
+                return;
+            }
+
+            case value_t::number_float:
+            {
+                dump_float(val.m_value.number_float);
+                return;
+            }
+
+            case value_t::discarded:
+            {
+                o->write_characters("<discarded>", 11);
+                return;
+            }
+
+            case value_t::null:
+            {
+                o->write_characters("null", 4);
+                return;
+            }
+        }
+    }
+
+  private:
+    /*!
+    @brief calculates the extra space to escape a JSON string
+
+    @param[in] s  the string to escape
+    @return the number of characters required to escape string @a s
+
+    @complexity Linear in the length of string @a s.
+    */
+    static std::size_t extra_space(const string_t& s) noexcept
+    {
+        return std::accumulate(s.begin(), s.end(), size_t{},
+                               [](size_t res, typename string_t::value_type c)
+        {
+            switch (c)
+            {
+                case '"':
+                case '\\':
+                case '\b':
+                case '\f':
+                case '\n':
+                case '\r':
+                case '\t':
+                {
+                    // from c (1 byte) to \x (2 bytes)
+                    return res + 1;
+                }
+
+                case 0x00:
+                case 0x01:
+                case 0x02:
+                case 0x03:
+                case 0x04:
+                case 0x05:
+                case 0x06:
+                case 0x07:
+                case 0x0b:
+                case 0x0e:
+                case 0x0f:
+                case 0x10:
+                case 0x11:
+                case 0x12:
+                case 0x13:
+                case 0x14:
+                case 0x15:
+                case 0x16:
+                case 0x17:
+                case 0x18:
+                case 0x19:
+                case 0x1a:
+                case 0x1b:
+                case 0x1c:
+                case 0x1d:
+                case 0x1e:
+                case 0x1f:
+                {
+                    // from c (1 byte) to \uxxxx (6 bytes)
+                    return res + 5;
+                }
+
+                default:
+                {
+                    return res;
+                }
+            }
+        });
+    }
+
+    /*!
+    @brief dump escaped string
+
+    Escape a string by replacing certain special characters by a sequence
+    of an escape character (backslash) and another character and other
+    control characters by a sequence of "\u" followed by a four-digit hex
+    representation. The escaped string is written to output stream @a o.
+
+    @param[in] s  the string to escape
+
+    @complexity Linear in the length of string @a s.
+    */
+    void dump_escaped(const string_t& s) const
+    {
+        const auto space = extra_space(s);
+        if (space == 0)
+        {
+            o->write_characters(s.c_str(), s.size());
+            return;
+        }
+
+        // create a result string of necessary size
+        string_t result(s.size() + space, '\\');
+        std::size_t pos = 0;
+
+        for (const auto& c : s)
+        {
+            switch (c)
+            {
+                // quotation mark (0x22)
+                case '"':
+                {
+                    result[pos + 1] = '"';
+                    pos += 2;
+                    break;
+                }
+
+                // reverse solidus (0x5c)
+                case '\\':
+                {
+                    // nothing to change
+                    pos += 2;
+                    break;
+                }
+
+                // backspace (0x08)
+                case '\b':
+                {
+                    result[pos + 1] = 'b';
+                    pos += 2;
+                    break;
+                }
+
+                // formfeed (0x0c)
+                case '\f':
+                {
+                    result[pos + 1] = 'f';
+                    pos += 2;
+                    break;
+                }
+
+                // newline (0x0a)
+                case '\n':
+                {
+                    result[pos + 1] = 'n';
+                    pos += 2;
+                    break;
+                }
+
+                // carriage return (0x0d)
+                case '\r':
+                {
+                    result[pos + 1] = 'r';
+                    pos += 2;
+                    break;
+                }
+
+                // horizontal tab (0x09)
+                case '\t':
+                {
+                    result[pos + 1] = 't';
+                    pos += 2;
+                    break;
+                }
+
+                case 0x00:
+                case 0x01:
+                case 0x02:
+                case 0x03:
+                case 0x04:
+                case 0x05:
+                case 0x06:
+                case 0x07:
+                case 0x0b:
+                case 0x0e:
+                case 0x0f:
+                case 0x10:
+                case 0x11:
+                case 0x12:
+                case 0x13:
+                case 0x14:
+                case 0x15:
+                case 0x16:
+                case 0x17:
+                case 0x18:
+                case 0x19:
+                case 0x1a:
+                case 0x1b:
+                case 0x1c:
+                case 0x1d:
+                case 0x1e:
+                case 0x1f:
+                {
+                    // convert a number 0..15 to its hex representation
+                    // (0..f)
+                    static const char hexify[16] = {'0', '1', '2', '3', '4', '5', '6', '7',
+                                                    '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'
+                                                   };
+
+                    // print character c as \uxxxx
+                    for (const char m :
+                {'u', '0', '0', hexify[c >> 4], hexify[c & 0x0f]
+                    })
+                    {
+                        result[++pos] = m;
+                    }
+
+                    ++pos;
+                    break;
+                }
+
+                default:
+                {
+                    // all other characters are added as-is
+                    result[pos++] = c;
+                    break;
+                }
+            }
+        }
+
+        assert(pos == s.size() + space);
+        o->write_characters(result.c_str(), result.size());
+    }
+
+    /*!
+    @brief dump an integer
+
+    Dump a given integer to output stream @a o. Works internally with
+    @a number_buffer.
+
+    @param[in] x  integer number (signed or unsigned) to dump
+    @tparam NumberType either @a number_integer_t or @a number_unsigned_t
+    */
+    template <
+        typename NumberType,
+        detail::enable_if_t<std::is_same<NumberType, number_unsigned_t>::value or
+                            std::is_same<NumberType, number_integer_t>::value,
+                            int> = 0 >
+    void dump_integer(NumberType x)
+    {
+        // special case for "0"
+        if (x == 0)
+        {
+            o->write_character('0');
+            return;
+        }
+
+        const bool is_negative = x < 0;
+        size_t i = 0;
+
+        // spare 1 byte for '\0'
+        while (x != 0 and i < number_buffer.size() - 1)
+        {
+            const auto digit = std::labs(static_cast<long>(x % 10));
+            number_buffer[i++] = static_cast<char>('0' + digit);
+            x /= 10;
+        }
+
+        // make sure the number has been processed completely
+        assert(x == 0);
+
+        if (is_negative)
+        {
+            // make sure there is capacity for the '-'
+            assert(i < number_buffer.size() - 2);
+            number_buffer[i++] = '-';
+        }
+
+        std::reverse(number_buffer.begin(), number_buffer.begin() + i);
+        o->write_characters(number_buffer.data(), i);
+    }
+
+    /*!
+    @brief dump a floating-point number
+
+    Dump a given floating-point number to output stream @a o. Works
+    internally with @a number_buffer.
+
+    @param[in] x  floating-point number to dump
+    */
+    void dump_float(number_float_t x)
+    {
+        // NaN / inf
+        if (not std::isfinite(x) or std::isnan(x))
+        {
+            o->write_characters("null", 4);
+            return;
+        }
+
+        // special case for 0.0 and -0.0
+        if (x == 0)
+        {
+            if (std::signbit(x))
+            {
+                o->write_characters("-0.0", 4);
+            }
+            else
+            {
+                o->write_characters("0.0", 3);
+            }
+            return;
+        }
+
+        // get number of digits for a text -> float -> text round-trip
+        static constexpr auto d = std::numeric_limits<number_float_t>::digits10;
+
+        // the actual conversion
+        std::ptrdiff_t len =
+            snprintf(number_buffer.data(), number_buffer.size(), "%.*g", d, x);
+
+        // negative value indicates an error
+        assert(len > 0);
+        // check if buffer was large enough
+        assert(static_cast<size_t>(len) < number_buffer.size());
+
+        // erase thousands separator
+        if (thousands_sep != '\0')
+        {
+            const auto end = std::remove(number_buffer.begin(),
+                                         number_buffer.begin() + len, thousands_sep);
+            std::fill(end, number_buffer.end(), '\0');
+            assert((end - number_buffer.begin()) <= len);
+            len = (end - number_buffer.begin());
+        }
+
+        // convert decimal point to '.'
+        if (decimal_point != '\0' and decimal_point != '.')
+        {
+            for (auto& c : number_buffer)
+            {
+                if (c == decimal_point)
+                {
+                    c = '.';
+                    break;
+                }
+            }
+        }
+
+        o->write_characters(number_buffer.data(), static_cast<size_t>(len));
+
+        // determine if need to append ".0"
+        const bool value_is_int_like =
+            std::none_of(number_buffer.begin(), number_buffer.begin() + len + 1,
+                         [](char c)
+        {
+            return c == '.' or c == 'e';
+        });
+
+        if (value_is_int_like)
+        {
+            o->write_characters(".0", 2);
+        }
+    }
+
+  private:
+    /// the output of the serializer
+    output_adapter_t<char> o = nullptr;
+
+    /// a (hopefully) large enough character buffer
+    std::array<char, 64> number_buffer{{}};
+
+    /// the locale
+    const std::lconv* loc = nullptr;
+    /// the locale's thousand separator character
+    const char thousands_sep = '\0';
+    /// the locale's decimal point character
+    const char decimal_point = '\0';
+
+    /// the indentation character
+    const char indent_char;
+
+    /// the indentation string
+    string_t indent_string;
+};
 } // namespace detail
 
 /// namespace to hold default `to_json` / `from_json` functions
@@ -6849,8 +7444,10 @@ class basic_json
     template<detail::value_t> friend struct detail::external_constructor;
     friend ::nlohmann::json_pointer;
     friend ::nlohmann::detail::parser<basic_json>;
+    friend ::nlohmann::detail::serializer<basic_json>;
     template <typename BasicJsonType>
     friend class ::nlohmann::detail::iter_impl;
+    friend ::nlohmann::detail::binary_writer<basic_json>;
     /// workaround type for MSVC
     using basic_json_t = NLOHMANN_BASIC_JSON_TPL;
 
@@ -6873,6 +7470,8 @@ class basic_json
     using binary_reader = ::nlohmann::detail::binary_reader<basic_json>;
     using binary_writer = ::nlohmann::detail::binary_writer<basic_json>;
 
+    using serializer = ::nlohmann::detail::serializer<basic_json>;
+
   public:
     using value_t = detail::value_t;
     // forward declarations
@@ -12077,598 +12676,6 @@ class basic_json
     /// @name serialization
     /// @{
 
-  private:
-    /*!
-    @brief wrapper around the serialization functions
-    */
-    class serializer
-    {
-      public:
-        /*!
-        @param[in] s  output stream to serialize to
-        @param[in] ichar  indentation character to use
-        */
-        serializer(output_adapter_t<char> s, const char ichar)
-            : o(s), loc(std::localeconv()),
-              thousands_sep(!loc->thousands_sep ? '\0' : loc->thousands_sep[0]),
-              decimal_point(!loc->decimal_point ? '\0' : loc->decimal_point[0]),
-              indent_char(ichar), indent_string(512, indent_char)
-        {}
-
-        // delete because of pointer members
-        serializer(const serializer&) = delete;
-        serializer& operator=(const serializer&) = delete;
-
-        /*!
-        @brief internal implementation of the serialization function
-
-        This function is called by the public member function dump and
-        organizes the serialization internally. The indentation level is
-        propagated as additional parameter. In case of arrays and objects, the
-        function is called recursively.
-
-        - strings and object keys are escaped using `escape_string()`
-        - integer numbers are converted implicitly via `operator<<`
-        - floating-point numbers are converted to a string using `"%g"` format
-
-        @param[in] val             value to serialize
-        @param[in] pretty_print    whether the output shall be pretty-printed
-        @param[in] indent_step     the indent level
-        @param[in] current_indent  the current indent level (only used internally)
-        */
-        void dump(const basic_json& val,
-                  const bool pretty_print,
-                  const unsigned int indent_step,
-                  const unsigned int current_indent = 0)
-        {
-            switch (val.m_type)
-            {
-                case value_t::object:
-                {
-                    if (val.m_value.object->empty())
-                    {
-                        o->write_characters("{}", 2);
-                        return;
-                    }
-
-                    if (pretty_print)
-                    {
-                        o->write_characters("{\n", 2);
-
-                        // variable to hold indentation for recursive calls
-                        const auto new_indent = current_indent + indent_step;
-                        if (JSON_UNLIKELY(indent_string.size() < new_indent))
-                        {
-                            indent_string.resize(indent_string.size() * 2, ' ');
-                        }
-
-                        // first n-1 elements
-                        auto i = val.m_value.object->cbegin();
-                        for (size_t cnt = 0; cnt < val.m_value.object->size() - 1; ++cnt, ++i)
-                        {
-                            o->write_characters(indent_string.c_str(), new_indent);
-                            o->write_character('\"');
-                            dump_escaped(i->first);
-                            o->write_characters("\": ", 3);
-                            dump(i->second, true, indent_step, new_indent);
-                            o->write_characters(",\n", 2);
-                        }
-
-                        // last element
-                        assert(i != val.m_value.object->cend());
-                        o->write_characters(indent_string.c_str(), new_indent);
-                        o->write_character('\"');
-                        dump_escaped(i->first);
-                        o->write_characters("\": ", 3);
-                        dump(i->second, true, indent_step, new_indent);
-
-                        o->write_character('\n');
-                        o->write_characters(indent_string.c_str(), current_indent);
-                        o->write_character('}');
-                    }
-                    else
-                    {
-                        o->write_character('{');
-
-                        // first n-1 elements
-                        auto i = val.m_value.object->cbegin();
-                        for (size_t cnt = 0; cnt < val.m_value.object->size() - 1; ++cnt, ++i)
-                        {
-                            o->write_character('\"');
-                            dump_escaped(i->first);
-                            o->write_characters("\":", 2);
-                            dump(i->second, false, indent_step, current_indent);
-                            o->write_character(',');
-                        }
-
-                        // last element
-                        assert(i != val.m_value.object->cend());
-                        o->write_character('\"');
-                        dump_escaped(i->first);
-                        o->write_characters("\":", 2);
-                        dump(i->second, false, indent_step, current_indent);
-
-                        o->write_character('}');
-                    }
-
-                    return;
-                }
-
-                case value_t::array:
-                {
-                    if (val.m_value.array->empty())
-                    {
-                        o->write_characters("[]", 2);
-                        return;
-                    }
-
-                    if (pretty_print)
-                    {
-                        o->write_characters("[\n", 2);
-
-                        // variable to hold indentation for recursive calls
-                        const auto new_indent = current_indent + indent_step;
-                        if (indent_string.size() < new_indent)
-                        {
-                            indent_string.resize(new_indent, ' ');
-                        }
-
-                        // first n-1 elements
-                        for (auto i = val.m_value.array->cbegin(); i != val.m_value.array->cend() - 1; ++i)
-                        {
-                            o->write_characters(indent_string.c_str(), new_indent);
-                            dump(*i, true, indent_step, new_indent);
-                            o->write_characters(",\n", 2);
-                        }
-
-                        // last element
-                        assert(not val.m_value.array->empty());
-                        o->write_characters(indent_string.c_str(), new_indent);
-                        dump(val.m_value.array->back(), true, indent_step, new_indent);
-
-                        o->write_character('\n');
-                        o->write_characters(indent_string.c_str(), current_indent);
-                        o->write_character(']');
-                    }
-                    else
-                    {
-                        o->write_character('[');
-
-                        // first n-1 elements
-                        for (auto i = val.m_value.array->cbegin(); i != val.m_value.array->cend() - 1; ++i)
-                        {
-                            dump(*i, false, indent_step, current_indent);
-                            o->write_character(',');
-                        }
-
-                        // last element
-                        assert(not val.m_value.array->empty());
-                        dump(val.m_value.array->back(), false, indent_step, current_indent);
-
-                        o->write_character(']');
-                    }
-
-                    return;
-                }
-
-                case value_t::string:
-                {
-                    o->write_character('\"');
-                    dump_escaped(*val.m_value.string);
-                    o->write_character('\"');
-                    return;
-                }
-
-                case value_t::boolean:
-                {
-                    if (val.m_value.boolean)
-                    {
-                        o->write_characters("true", 4);
-                    }
-                    else
-                    {
-                        o->write_characters("false", 5);
-                    }
-                    return;
-                }
-
-                case value_t::number_integer:
-                {
-                    dump_integer(val.m_value.number_integer);
-                    return;
-                }
-
-                case value_t::number_unsigned:
-                {
-                    dump_integer(val.m_value.number_unsigned);
-                    return;
-                }
-
-                case value_t::number_float:
-                {
-                    dump_float(val.m_value.number_float);
-                    return;
-                }
-
-                case value_t::discarded:
-                {
-                    o->write_characters("<discarded>", 11);
-                    return;
-                }
-
-                case value_t::null:
-                {
-                    o->write_characters("null", 4);
-                    return;
-                }
-            }
-        }
-
-      private:
-        /*!
-        @brief calculates the extra space to escape a JSON string
-
-        @param[in] s  the string to escape
-        @return the number of characters required to escape string @a s
-
-        @complexity Linear in the length of string @a s.
-        */
-        static std::size_t extra_space(const string_t& s) noexcept
-        {
-            return std::accumulate(s.begin(), s.end(), size_t{},
-                                   [](size_t res, typename string_t::value_type c)
-            {
-                switch (c)
-                {
-                    case '"':
-                    case '\\':
-                    case '\b':
-                    case '\f':
-                    case '\n':
-                    case '\r':
-                    case '\t':
-                    {
-                        // from c (1 byte) to \x (2 bytes)
-                        return res + 1;
-                    }
-
-                    case 0x00:
-                    case 0x01:
-                    case 0x02:
-                    case 0x03:
-                    case 0x04:
-                    case 0x05:
-                    case 0x06:
-                    case 0x07:
-                    case 0x0b:
-                    case 0x0e:
-                    case 0x0f:
-                    case 0x10:
-                    case 0x11:
-                    case 0x12:
-                    case 0x13:
-                    case 0x14:
-                    case 0x15:
-                    case 0x16:
-                    case 0x17:
-                    case 0x18:
-                    case 0x19:
-                    case 0x1a:
-                    case 0x1b:
-                    case 0x1c:
-                    case 0x1d:
-                    case 0x1e:
-                    case 0x1f:
-                    {
-                        // from c (1 byte) to \uxxxx (6 bytes)
-                        return res + 5;
-                    }
-
-                    default:
-                    {
-                        return res;
-                    }
-                }
-            });
-        }
-
-        /*!
-        @brief dump escaped string
-
-        Escape a string by replacing certain special characters by a sequence
-        of an escape character (backslash) and another character and other
-        control characters by a sequence of "\u" followed by a four-digit hex
-        representation. The escaped string is written to output stream @a o.
-
-        @param[in] s  the string to escape
-
-        @complexity Linear in the length of string @a s.
-        */
-        void dump_escaped(const string_t& s) const
-        {
-            const auto space = extra_space(s);
-            if (space == 0)
-            {
-                o->write_characters(s.c_str(), s.size());
-                return;
-            }
-
-            // create a result string of necessary size
-            string_t result(s.size() + space, '\\');
-            std::size_t pos = 0;
-
-            for (const auto& c : s)
-            {
-                switch (c)
-                {
-                    // quotation mark (0x22)
-                    case '"':
-                    {
-                        result[pos + 1] = '"';
-                        pos += 2;
-                        break;
-                    }
-
-                    // reverse solidus (0x5c)
-                    case '\\':
-                    {
-                        // nothing to change
-                        pos += 2;
-                        break;
-                    }
-
-                    // backspace (0x08)
-                    case '\b':
-                    {
-                        result[pos + 1] = 'b';
-                        pos += 2;
-                        break;
-                    }
-
-                    // formfeed (0x0c)
-                    case '\f':
-                    {
-                        result[pos + 1] = 'f';
-                        pos += 2;
-                        break;
-                    }
-
-                    // newline (0x0a)
-                    case '\n':
-                    {
-                        result[pos + 1] = 'n';
-                        pos += 2;
-                        break;
-                    }
-
-                    // carriage return (0x0d)
-                    case '\r':
-                    {
-                        result[pos + 1] = 'r';
-                        pos += 2;
-                        break;
-                    }
-
-                    // horizontal tab (0x09)
-                    case '\t':
-                    {
-                        result[pos + 1] = 't';
-                        pos += 2;
-                        break;
-                    }
-
-                    case 0x00:
-                    case 0x01:
-                    case 0x02:
-                    case 0x03:
-                    case 0x04:
-                    case 0x05:
-                    case 0x06:
-                    case 0x07:
-                    case 0x0b:
-                    case 0x0e:
-                    case 0x0f:
-                    case 0x10:
-                    case 0x11:
-                    case 0x12:
-                    case 0x13:
-                    case 0x14:
-                    case 0x15:
-                    case 0x16:
-                    case 0x17:
-                    case 0x18:
-                    case 0x19:
-                    case 0x1a:
-                    case 0x1b:
-                    case 0x1c:
-                    case 0x1d:
-                    case 0x1e:
-                    case 0x1f:
-                    {
-                        // convert a number 0..15 to its hex representation
-                        // (0..f)
-                        static const char hexify[16] =
-                        {
-                            '0', '1', '2', '3', '4', '5', '6', '7',
-                            '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'
-                        };
-
-                        // print character c as \uxxxx
-                        for (const char m :
-                    { 'u', '0', '0', hexify[c >> 4], hexify[c & 0x0f]
-                        })
-                        {
-                            result[++pos] = m;
-                        }
-
-                        ++pos;
-                        break;
-                    }
-
-                    default:
-                    {
-                        // all other characters are added as-is
-                        result[pos++] = c;
-                        break;
-                    }
-                }
-            }
-
-            assert(pos == s.size() + space);
-            o->write_characters(result.c_str(), result.size());
-        }
-
-        /*!
-        @brief dump an integer
-
-        Dump a given integer to output stream @a o. Works internally with
-        @a number_buffer.
-
-        @param[in] x  integer number (signed or unsigned) to dump
-        @tparam NumberType either @a number_integer_t or @a number_unsigned_t
-        */
-        template<typename NumberType, detail::enable_if_t <
-                     std::is_same<NumberType, number_unsigned_t>::value or
-                     std::is_same<NumberType, number_integer_t>::value, int> = 0>
-        void dump_integer(NumberType x)
-        {
-            // special case for "0"
-            if (x == 0)
-            {
-                o->write_character('0');
-                return;
-            }
-
-            const bool is_negative = x < 0;
-            size_t i = 0;
-
-            // spare 1 byte for '\0'
-            while (x != 0 and i < number_buffer.size() - 1)
-            {
-                const auto digit = std::labs(static_cast<long>(x % 10));
-                number_buffer[i++] = static_cast<char>('0' + digit);
-                x /= 10;
-            }
-
-            // make sure the number has been processed completely
-            assert(x == 0);
-
-            if (is_negative)
-            {
-                // make sure there is capacity for the '-'
-                assert(i < number_buffer.size() - 2);
-                number_buffer[i++] = '-';
-            }
-
-            std::reverse(number_buffer.begin(), number_buffer.begin() + i);
-            o->write_characters(number_buffer.data(), i);
-        }
-
-        /*!
-        @brief dump a floating-point number
-
-        Dump a given floating-point number to output stream @a o. Works
-        internally with @a number_buffer.
-
-        @param[in] x  floating-point number to dump
-        */
-        void dump_float(number_float_t x)
-        {
-            // NaN / inf
-            if (not std::isfinite(x) or std::isnan(x))
-            {
-                o->write_characters("null", 4);
-                return;
-            }
-
-            // special case for 0.0 and -0.0
-            if (x == 0)
-            {
-                if (std::signbit(x))
-                {
-                    o->write_characters("-0.0", 4);
-                }
-                else
-                {
-                    o->write_characters("0.0", 3);
-                }
-                return;
-            }
-
-            // get number of digits for a text -> float -> text round-trip
-            static constexpr auto d = std::numeric_limits<number_float_t>::digits10;
-
-            // the actual conversion
-            std::ptrdiff_t len = snprintf(number_buffer.data(), number_buffer.size(),
-                                          "%.*g", d, x);
-
-            // negative value indicates an error
-            assert(len > 0);
-            // check if buffer was large enough
-            assert(static_cast<size_t>(len) < number_buffer.size());
-
-            // erase thousands separator
-            if (thousands_sep != '\0')
-            {
-                const auto end = std::remove(number_buffer.begin(),
-                                             number_buffer.begin() + len,
-                                             thousands_sep);
-                std::fill(end, number_buffer.end(), '\0');
-                assert((end - number_buffer.begin()) <= len);
-                len = (end - number_buffer.begin());
-            }
-
-            // convert decimal point to '.'
-            if (decimal_point != '\0' and decimal_point != '.')
-            {
-                for (auto& c : number_buffer)
-                {
-                    if (c == decimal_point)
-                    {
-                        c = '.';
-                        break;
-                    }
-                }
-            }
-
-            o->write_characters(number_buffer.data(), static_cast<size_t>(len));
-
-            // determine if need to append ".0"
-            const bool value_is_int_like = std::none_of(number_buffer.begin(),
-                                           number_buffer.begin() + len + 1,
-                                           [](char c)
-            {
-                return c == '.' or c == 'e';
-            });
-
-            if (value_is_int_like)
-            {
-                o->write_characters(".0", 2);
-            }
-        }
-
-      private:
-        /// the output of the serializer
-        output_adapter_t<char> o = nullptr;
-
-        /// a (hopefully) large enough character buffer
-        std::array<char, 64> number_buffer{{}};
-
-        /// the locale
-        const std::lconv* loc = nullptr;
-        /// the locale's thousand separator character
-        const char thousands_sep = '\0';
-        /// the locale's decimal point character
-        const char decimal_point = '\0';
-
-        /// the indentation character
-        const char indent_char;
-
-        /// the indentation string
-        string_t indent_string;
-    };
-
-  public:
     /*!
     @brief serialize to stream