Merge branch 'develop' into feature/issue698

doc/Doxyfile

@@ -1,4 +1,4 @@
-# Doxyfile 1.8.9.1
+# Doxyfile 1.8.14
 
 #---------------------------------------------------------------------------
 # Project related configuration options
@@ -27,10 +27,11 @@ MULTILINE_CPP_IS_BRIEF = NO
 INHERIT_DOCS           = YES
 SEPARATE_MEMBER_PAGES  = YES
 TAB_SIZE               = 4
-ALIASES                = "complexity=@par Complexity\n"
+ALIASES                = "complexity=@par Complexity\n" \
-ALIASES                += liveexample{2}="@par Example\n \1 \n @includelineno \2.cpp \n Output (play with this example @htmlinclude \2.link):\n @verbinclude \2.output \n The example code above can be translated with @verbatim g++ -std=c++11 -Isrc doc/examples/\2.cpp -o \2 @endverbatim"
+                         "liveexample{2}=@par Example\n \1 \n @includelineno \2.cpp \n Output (play with this example @htmlinclude \2.link):\n @verbinclude \2.output \n The <a href= https://github.com/nlohmann/json/blob/develop/doc/examples/\2.cpp>example code</a> above can be translated with @verbatim g++ -std=c++11 -Isrc doc/examples/\2.cpp -o \2 @endverbatim" \
-ALIASES                += requirement="@par Requirements\n"
+                         "requirement=@par Requirements\n" \
-ALIASES                += exceptionsafety="@par Exception safety\n"
+                         "exceptionsafety=@par Exception safety\n" \
+                         "iterators=@par Iterator validity\n"
 TCL_SUBST              =
 OPTIMIZE_OUTPUT_FOR_C  = NO
 OPTIMIZE_OUTPUT_JAVA   = NO
@@ -38,12 +39,14 @@ OPTIMIZE_FOR_FORTRAN   = NO
 OPTIMIZE_OUTPUT_VHDL   = NO
 EXTENSION_MAPPING      =
 MARKDOWN_SUPPORT       = YES
+TOC_INCLUDE_HEADINGS   = 0
 AUTOLINK_SUPPORT       = NO
 BUILTIN_STL_SUPPORT    = YES
 CPP_CLI_SUPPORT        = NO
 SIP_SUPPORT            = NO
 IDL_PROPERTY_SUPPORT   = YES
 DISTRIBUTE_GROUP_DOC   = NO
+GROUP_NESTED_COMPOUNDS = NO
 SUBGROUPING            = YES
 INLINE_GROUPED_CLASSES = NO
 INLINE_SIMPLE_STRUCTS  = NO
@@ -97,12 +100,14 @@ WARNINGS               = YES
 WARN_IF_UNDOCUMENTED   = YES
 WARN_IF_DOC_ERROR      = YES
 WARN_NO_PARAMDOC       = YES
+WARN_AS_ERROR          = NO
 WARN_FORMAT            = "$file:$line: $text"
 WARN_LOGFILE           =
 #---------------------------------------------------------------------------
 # Configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT                  = ../src/json.hpp index.md
+INPUT                  = ../src/json.hpp \
+                         index.md
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          =
 RECURSIVE              = NO
@@ -131,6 +136,8 @@ REFERENCES_LINK_SOURCE = NO
 SOURCE_TOOLTIPS        = YES
 USE_HTAGS              = NO
 VERBATIM_HEADERS       = NO
+CLANG_ASSISTED_PARSING = YES
+CLANG_OPTIONS          = -std=c++11
 #---------------------------------------------------------------------------
 # Configuration options related to the alphabetical class index
 #---------------------------------------------------------------------------
@@ -152,13 +159,14 @@ HTML_COLORSTYLE_HUE    = 220
 HTML_COLORSTYLE_SAT    = 100
 HTML_COLORSTYLE_GAMMA  = 80
 HTML_TIMESTAMP         = YES
+HTML_DYNAMIC_MENUS     = YES
 HTML_DYNAMIC_SECTIONS  = YES
 HTML_INDEX_NUM_ENTRIES = 100
 GENERATE_DOCSET        = YES
 DOCSET_FEEDNAME        = "Doxygen generated docs"
 DOCSET_BUNDLE_ID       = me.nlohmann.json
 DOCSET_PUBLISHER_ID    = me.nlohmann
-DOCSET_PUBLISHER_NAME  = Niels Lohmann
+DOCSET_PUBLISHER_NAME  = NielsLohmann
 GENERATE_HTMLHELP      = NO
 CHM_FILE               =
 HHC_LOCATION           =
@@ -215,6 +223,7 @@ LATEX_BATCHMODE        = NO
 LATEX_HIDE_INDICES     = NO
 LATEX_SOURCE_CODE      = NO
 LATEX_BIB_STYLE        = plain
+LATEX_TIMESTAMP        = NO
 #---------------------------------------------------------------------------
 # Configuration options related to the RTF output
 #---------------------------------------------------------------------------
@@ -308,6 +317,7 @@ DOTFILE_DIRS           =
 MSCFILE_DIRS           =
 DIAFILE_DIRS           =
 PLANTUML_JAR_PATH      =
+PLANTUML_CFG_FILE      =
 PLANTUML_INCLUDE_PATH  =
 DOT_GRAPH_MAX_NODES    = 50
 MAX_DOT_GRAPH_DEPTH    = 0

doc/examples/basic_json__CompatibleType.cpp

@@ -5,6 +5,7 @@
 #include <set>
 #include <unordered_map>
 #include <unordered_set>
+#include <valarray>
 #include "json.hpp"
 
 using json = nlohmann::json;
@@ -67,6 +68,10 @@ int main()
     std::vector<int> c_vector {1, 2, 3, 4};
     json j_vec(c_vector);
 
+    // create an array from std::valarray
+    std::valarray<short> c_valarray {10, 9, 8, 7};
+    json j_valarray(c_valarray);
+
     // create an array from std::deque
     std::deque<double> c_deque {1.2, 2.3, 3.4, 5.6};
     json j_deque(c_deque);
@@ -102,6 +107,7 @@ int main()
     // serialize the JSON arrays
     std::cout << j_array_t << '\n';
     std::cout << j_vec << '\n';
+    std::cout << j_valarray << '\n';
     std::cout << j_deque << '\n';
     std::cout << j_list << '\n';
     std::cout << j_flist << '\n';

doc/examples/basic_json__CompatibleType.link

@@ -1 +1 @@
-<a target="_blank" href="https://wandbox.org/permlink/chmc1rH7aNZTIVSp"><b>online</b></a>
+<a target="_blank" href="https://wandbox.org/permlink/s7Ecy7hDYSmUWHyx"><b>online</b></a>

doc/examples/basic_json__CompatibleType.output

@@ -6,6 +6,7 @@
 
 ["one","two",3,4.5,false]
 [1,2,3,4]
+[10,9,8,7]
 [1.2,2.3,3.4,5.6]
 [true,true,false,true]
 [12345678909876,23456789098765,34567890987654,45678909876543]

doc/examples/dump.cpp

@@ -8,16 +8,24 @@ int main()
     // create JSON values
     json j_object = {{"one", 1}, {"two", 2}};
     json j_array = {1, 2, 4, 8, 16};
+    json j_string = "Hellö 😀!";
 
     // call dump()
-    std::cout << j_object.dump() << "\n\n";
+    std::cout << "objects:" << '\n'
-    std::cout << j_object.dump(-1) << "\n\n";
+              << j_object.dump() << "\n\n"
-    std::cout << j_object.dump(0) << "\n\n";
+              << j_object.dump(-1) << "\n\n"
-    std::cout << j_object.dump(4) << "\n\n";
+              << j_object.dump(0) << "\n\n"
-    std::cout << j_object.dump(1, '\t') << "\n\n";
+              << j_object.dump(4) << "\n\n"
-    std::cout << j_array.dump() << "\n\n";
+              << j_object.dump(1, '\t') << "\n\n";
-    std::cout << j_array.dump(-1) << "\n\n";
+
-    std::cout << j_array.dump(0) << "\n\n";
+    std::cout << "arrays:" << '\n'
-    std::cout << j_array.dump(4) << "\n\n";
+              << j_array.dump() << "\n\n"
-    std::cout << j_array.dump(1, '\t') << "\n\n";
+              << j_array.dump(-1) << "\n\n"
+              << j_array.dump(0) << "\n\n"
+              << j_array.dump(4) << "\n\n"
+              << j_array.dump(1, '\t') << "\n\n";
+
+    std::cout << "strings:" << '\n'
+              << j_string.dump() << '\n'
+              << j_string.dump(-1, ' ', true) << '\n';
 }

doc/examples/dump.link

@@ -1 +1 @@
-<a target="_blank" href="https://wandbox.org/permlink/0rB2LKUCjPlU90XK"><b>online</b></a>
+<a target="_blank" href="https://wandbox.org/permlink/UnV6etCOZZRZpYyB"><b>online</b></a>

doc/examples/dump.output

@@ -1,3 +1,4 @@
+objects:
 {"one":1,"two":2}
 
 {"one":1,"two":2}
@@ -17,6 +18,7 @@
 	"two": 2
 }
 
+arrays:
 [1,2,4,8,16]
 
 [1,2,4,8,16]
@@ -45,3 +47,6 @@
 	16
 ]
 
+strings:
+"Hellö 😀!"
+"Hell\u00f6 \ud83d\ude00!"

doc/examples/exception.cpp

@@ -0,0 +1,20 @@
+#include <iostream>
+#include "json.hpp"
+
+using json = nlohmann::json;
+
+int main()
+{
+    try
+    {
+        // calling at() for a non-existing key
+        json j = {{"foo", "bar"}};
+        json k = j.at("non-existing");
+    }
+    catch (json::exception& e)
+    {
+        // output exception information
+        std::cout << "message: " << e.what() << '\n'
+                  << "exception id: " << e.id << std::endl;
+    }
+}

doc/examples/exception.link

@@ -0,0 +1 @@
+<a target="_blank" href="https://wandbox.org/permlink/yHjdsKGTYSRFNzD7"><b>online</b></a>

doc/examples/exception.output

@@ -0,0 +1,2 @@
+message: [json.exception.out_of_range.403] key 'non-existing' not found
+exception id: 403

doc/examples/invalid_iterator.cpp

@@ -0,0 +1,21 @@
+#include <iostream>
+#include "json.hpp"
+
+using json = nlohmann::json;
+
+int main()
+{
+    try
+    {
+        // calling iterator::key() on non-object iterator
+        json j = "string";
+        json::iterator it = j.begin();
+        auto k = it.key();
+    }
+    catch (json::invalid_iterator& e)
+    {
+        // output exception information
+        std::cout << "message: " << e.what() << '\n'
+                  << "exception id: " << e.id << std::endl;
+    }
+}

doc/examples/invalid_iterator.link

@@ -0,0 +1 @@
+<a target="_blank" href="https://wandbox.org/permlink/PW9dQWFyNaUxzEVY"><b>online</b></a>

doc/examples/invalid_iterator.output

@@ -0,0 +1,2 @@
+message: [json.exception.invalid_iterator.207] cannot use key() for non-object iterators
+exception id: 207

doc/examples/operator__value_t.cpp

@@ -8,7 +8,8 @@ int main()
     // create JSON values
     json j_null;
     json j_boolean = true;
-    json j_number_integer = 17;
+    json j_number_integer = -17;
+    json j_number_unsigned = 42u;
     json j_number_float = 23.42;
     json j_object = {{"one", 1}, {"two", 2}};
     json j_array = {1, 2, 4, 8, 16};
@@ -18,6 +19,7 @@ int main()
     json::value_t t_null = j_null;
     json::value_t t_boolean = j_boolean;
     json::value_t t_number_integer = j_number_integer;
+    json::value_t t_number_unsigned = j_number_unsigned;
     json::value_t t_number_float = j_number_float;
     json::value_t t_object = j_object;
     json::value_t t_array = j_array;
@@ -28,6 +30,7 @@ int main()
     std::cout << (t_null == json::value_t::null) << '\n';
     std::cout << (t_boolean == json::value_t::boolean) << '\n';
     std::cout << (t_number_integer == json::value_t::number_integer) << '\n';
+    std::cout << (t_number_unsigned == json::value_t::number_unsigned) << '\n';
     std::cout << (t_number_float == json::value_t::number_float) << '\n';
     std::cout << (t_object == json::value_t::object) << '\n';
     std::cout << (t_array == json::value_t::array) << '\n';

doc/examples/operator__value_t.link

@@ -1 +1 @@
-<a target="_blank" href="https://wandbox.org/permlink/daNU6Fj8JuV07nBn"><b>online</b></a>
+<a target="_blank" href="https://wandbox.org/permlink/aUlH5rQeIA002APo"><b>online</b></a>

doc/examples/operator__value_t.output

@@ -5,3 +5,4 @@ true
 true
 true
 true
+true

doc/examples/other_error.cpp

@@ -0,0 +1,29 @@
+#include <iostream>
+#include "json.hpp"
+
+using json = nlohmann::json;
+
+int main()
+{
+    try
+    {
+        // executing a failing JSON Patch operation
+        json value = R"({
+            "best_biscuit": {
+                "name": "Oreo"
+            }
+        })"_json;
+        json patch = R"([{
+            "op": "test",
+            "path": "/best_biscuit/name",
+            "value": "Choco Leibniz"
+        }])"_json;
+        value.patch(patch);
+    }
+    catch (json::other_error& e)
+    {
+        // output exception information
+        std::cout << "message: " << e.what() << '\n'
+                  << "exception id: " << e.id << std::endl;
+    }
+}

doc/examples/other_error.link

@@ -0,0 +1 @@
+<a target="_blank" href="https://wandbox.org/permlink/UcADWdVMPA9GZbRP"><b>online</b></a>

doc/examples/other_error.output

@@ -0,0 +1,2 @@
+message: [json.exception.other_error.501] unsuccessful: {"op":"test","path":"/best_biscuit/name","value":"Choco Leibniz"}
+exception id: 501

doc/examples/out_of_range.cpp

@@ -0,0 +1,20 @@
+#include <iostream>
+#include "json.hpp"
+
+using json = nlohmann::json;
+
+int main()
+{
+    try
+    {
+        // calling at() for an invalid index
+        json j = {1, 2, 3, 4};
+        j.at(4) = 10;
+    }
+    catch (json::out_of_range& e)
+    {
+        // output exception information
+        std::cout << "message: " << e.what() << '\n'
+                  << "exception id: " << e.id << std::endl;
+    }
+}

doc/examples/out_of_range.link

@@ -0,0 +1 @@
+<a target="_blank" href="https://wandbox.org/permlink/VrsKXxX3CuHeqKq7"><b>online</b></a>

doc/examples/out_of_range.output

@@ -0,0 +1,2 @@
+message: [json.exception.out_of_range.401] array index 4 is out of range
+exception id: 401

doc/examples/parse_error.cpp

@@ -0,0 +1,20 @@
+#include <iostream>
+#include "json.hpp"
+
+using json = nlohmann::json;
+
+int main()
+{
+    try
+    {
+        // parsing input with a syntax error
+        json::parse("[1,2,3,]");
+    }
+    catch (json::parse_error& e)
+    {
+        // output exception information
+        std::cout << "message: " << e.what() << '\n'
+                  << "exception id: " << e.id << '\n'
+                  << "byte position of error: " << e.byte << std::endl;
+    }
+}

doc/examples/parse_error.link

@@ -0,0 +1 @@
+<a target="_blank" href="https://wandbox.org/permlink/74sQTauZsM8tWyuM"><b>online</b></a>

doc/examples/parse_error.output

@@ -0,0 +1,3 @@
+message: [json.exception.parse_error.101] parse error at 8: syntax error - unexpected ']'; expected '[', '{', or a literal
+exception id: 101
+byte position of error: 8

doc/examples/type.cpp

@@ -8,7 +8,8 @@ int main()
     // create JSON values
     json j_null;
     json j_boolean = true;
-    json j_number_integer = 17;
+    json j_number_integer = -17;
+    json j_number_unsigned = 42u;
     json j_number_float = 23.42;
     json j_object = {{"one", 1}, {"two", 2}};
     json j_array = {1, 2, 4, 8, 16};
@@ -19,6 +20,7 @@ int main()
     std::cout << (j_null.type() == json::value_t::null) << '\n';
     std::cout << (j_boolean.type() == json::value_t::boolean) << '\n';
     std::cout << (j_number_integer.type() == json::value_t::number_integer) << '\n';
+    std::cout << (j_number_unsigned.type() == json::value_t::number_unsigned) << '\n';
     std::cout << (j_number_float.type() == json::value_t::number_float) << '\n';
     std::cout << (j_object.type() == json::value_t::object) << '\n';
     std::cout << (j_array.type() == json::value_t::array) << '\n';

doc/examples/type.link

@@ -1 +1 @@
-<a target="_blank" href="https://wandbox.org/permlink/zlWezYhiRTnLzrSj"><b>online</b></a>
+<a target="_blank" href="https://wandbox.org/permlink/LqgeAtdIMLSpGzkE"><b>online</b></a>

doc/examples/type.output

@@ -5,3 +5,4 @@ true
 true
 true
 true
+true

doc/examples/type_error.cpp

@@ -0,0 +1,20 @@
+#include <iostream>
+#include "json.hpp"
+
+using json = nlohmann::json;
+
+int main()
+{
+    try
+    {
+        // calling push_back() on a string value
+        json j = "string";
+        j.push_back("another string");
+    }
+    catch (json::type_error& e)
+    {
+        // output exception information
+        std::cout << "message: " << e.what() << '\n'
+                  << "exception id: " << e.id << std::endl;
+    }
+}

doc/examples/type_error.link

@@ -0,0 +1 @@
+<a target="_blank" href="https://wandbox.org/permlink/HVfmgdIq73ztfCHY"><b>online</b></a>

doc/examples/type_error.output

@@ -0,0 +1,2 @@
+message: [json.exception.type_error.308] cannot use push_back() with string
+exception id: 308

doc/examples/type_name.cpp

@@ -8,18 +8,20 @@ int main()
     // create JSON values
     json j_null;
     json j_boolean = true;
-    json j_number_integer = 17;
+    json j_number_integer = -17;
+    json j_number_unsigned = 42u;
     json j_number_float = 23.42;
     json j_object = {{"one", 1}, {"two", 2}};
     json j_array = {1, 2, 4, 8, 16};
     json j_string = "Hello, world";
 
     // call type_name()
-    std::cout << j_null.type_name() << '\n';
+    std::cout << j_null << " is a " << j_null.type_name() << '\n';
-    std::cout << j_boolean.type_name() << '\n';
+    std::cout << j_boolean << " is a " << j_boolean.type_name() << '\n';
-    std::cout << j_number_integer.type_name() << '\n';
+    std::cout << j_number_integer << " is a " << j_number_integer.type_name() << '\n';
-    std::cout << j_number_float.type_name() << '\n';
+    std::cout << j_number_unsigned << " is a " << j_number_unsigned.type_name() << '\n';
-    std::cout << j_object.type_name() << '\n';
+    std::cout << j_number_float << " is a " << j_number_float.type_name() << '\n';
-    std::cout << j_array.type_name() << '\n';
+    std::cout << j_object << " is an " << j_object.type_name() << '\n';
-    std::cout << j_string.type_name() << '\n';
+    std::cout << j_array << " is an " << j_array.type_name() << '\n';
+    std::cout << j_string << " is a " << j_string.type_name() << '\n';
 }

doc/examples/type_name.link

@@ -1 +1 @@
-<a target="_blank" href="https://wandbox.org/permlink/dKXdftLJYVnkE3Vg"><b>online</b></a>
+<a target="_blank" href="https://wandbox.org/permlink/UqDa9aT5fHaK6dPQ"><b>online</b></a>

doc/examples/type_name.output

@@ -1,7 +1,8 @@
-null
+null is a null
-boolean
+true is a boolean
-number
+-17 is a number
-number
+42 is a number
-object
+23.42 is a number
-array
+{"one":1,"two":2} is an object
-string
+[1,2,4,8,16] is an array
+"Hello, world" is a string

src/json.hpp

@@ -166,12 +166,28 @@ namespace detail
 /*!
 @brief general exception of the @ref basic_json class
 
-Extension of std::exception objects with a member @a id for exception ids.
+This class is an extension of `std::exception` objects with a member @a id for
+exception ids. It is used as the base class for all exceptions thrown by the
+@ref basic_json class. This class can hence be used as "wildcard" to catch
+exceptions.
 
+Subclasses:
+- @ref parse_error for exceptions indicating a parse error
+- @ref invalid_iterator for exceptions indicating errors with iterators
+- @ref type_error for exceptions indicating executing a member function with
+                  a wrong type
+- @ref out_of_range for exceptions indicating access out of the defined range
+- @ref other_error for exceptions indicating other library errors
+
+@internal
 @note To have nothrow-copy-constructible exceptions, we internally use
-      std::runtime_error which can cope with arbitrary-length error messages.
+      `std::runtime_error` which can cope with arbitrary-length error messages.
       Intermediate strings are built with static functions and then passed to
       the actual constructor.
+@endinternal
+
+@liveexample{The following code shows how arbitrary library exceptions can be
+caught.,exception}
 
 @since version 3.0.0
 */
@@ -204,16 +220,12 @@ class exception : public std::exception
 @brief exception indicating a parse error
 
 This excpetion is thrown by the library when a parse error occurs. Parse errors
-can occur during the deserialization of JSON text as well as when using JSON
+can occur during the deserialization of JSON text, CBOR, MessagePack, as well
-Patch.
+as when using JSON Patch.
 
 Member @a byte holds the byte index of the last read character in the input
 file.
 
-@note For an input with n bytes, 1 is the index of the first character and n+1
-      is the index of the terminating null byte or the end of file. This also
-      holds true when reading a byte vector (CBOR or MessagePack).
-
 Exceptions have ids 1xx.
 
 name / id                      | example message | description
@@ -231,6 +243,20 @@ json.exception.parse_error.110 | parse error at 1: cannot read 2 bytes from vect
 json.exception.parse_error.112 | parse error at 1: error reading CBOR; last byte: 0xf8 | Not all types of CBOR or MessagePack are supported. This exception occurs if an unsupported byte was read.
 json.exception.parse_error.113 | parse error at 2: expected a CBOR string; last byte: 0x98 | While parsing a map key, a value that is not a string has been read.
 
+@note For an input with n bytes, 1 is the index of the first character and n+1
+      is the index of the terminating null byte or the end of file. This also
+      holds true when reading a byte vector (CBOR or MessagePack).
+
+@liveexample{The following code shows how a `parse_error` exception can be
+caught.,parse_error}
+
+@sa @ref exception for the base class of the library exceptions
+@sa @ref invalid_iterator for exceptions indicating errors with iterators
+@sa @ref type_error for exceptions indicating executing a member function with
+                    a wrong type
+@sa @ref out_of_range for exceptions indicating access out of the defined range
+@sa @ref other_error for exceptions indicating other library errors
+
 @since version 3.0.0
 */
 class parse_error : public exception
@@ -271,6 +297,9 @@ class parse_error : public exception
 /*!
 @brief exception indicating errors with iterators
 
+This exception is thrown if iterators passed to a library function do not match
+the expected semantics.
+
 Exceptions have ids 2xx.
 
 name / id                           | example message | description
@@ -290,6 +319,16 @@ json.exception.invalid_iterator.212 | cannot compare iterators of different cont
 json.exception.invalid_iterator.213 | cannot compare order of object iterators | The order of object iterators cannot be compared, because JSON objects are unordered.
 json.exception.invalid_iterator.214 | cannot get value | Cannot get value for iterator: Either the iterator belongs to a null value or it is an iterator to a primitive type (number, boolean, or string), but the iterator is different to @ref begin().
 
+@liveexample{The following code shows how an `invalid_iterator` exception can be
+caught.,invalid_iterator}
+
+@sa @ref exception for the base class of the library exceptions
+@sa @ref parse_error for exceptions indicating a parse error
+@sa @ref type_error for exceptions indicating executing a member function with
+                    a wrong type
+@sa @ref out_of_range for exceptions indicating access out of the defined range
+@sa @ref other_error for exceptions indicating other library errors
+
 @since version 3.0.0
 */
 class invalid_iterator : public exception
@@ -309,6 +348,9 @@ class invalid_iterator : public exception
 /*!
 @brief exception indicating executing a member function with a wrong type
 
+This exception is thrown in case of a type error; that is, a library function is
+executed on a JSON value whose type does not match the expected semantics.
+
 Exceptions have ids 3xx.
 
 name / id                     | example message | description
@@ -329,6 +371,15 @@ json.exception.type_error.313 | invalid value to unflatten | The @ref unflatten
 json.exception.type_error.314 | only objects can be unflattened | The @ref unflatten function only works for an object whose keys are JSON Pointers.
 json.exception.type_error.315 | values in object must be primitive | The @ref unflatten function only works for an object whose keys are JSON Pointers and whose values are primitive.
 
+@liveexample{The following code shows how a `type_error` exception can be
+caught.,type_error}
+
+@sa @ref exception for the base class of the library exceptions
+@sa @ref parse_error for exceptions indicating a parse error
+@sa @ref invalid_iterator for exceptions indicating errors with iterators
+@sa @ref out_of_range for exceptions indicating access out of the defined range
+@sa @ref other_error for exceptions indicating other library errors
+
 @since version 3.0.0
 */
 class type_error : public exception
@@ -347,6 +398,10 @@ class type_error : public exception
 /*!
 @brief exception indicating access out of the defined range
 
+This exception is thrown in case a library function is called on an input
+parameter that exceeds the expected range, for instance in case of array
+indices or nonexisting object keys.
+
 Exceptions have ids 4xx.
 
 name / id                       | example message | description
@@ -358,6 +413,16 @@ json.exception.out_of_range.404 | unresolved reference token 'foo' | A reference
 json.exception.out_of_range.405 | JSON pointer has no parent | The JSON Patch operations 'remove' and 'add' can not be applied to the root element of the JSON value.
 json.exception.out_of_range.406 | number overflow parsing '10E1000' | A parsed number could not be stored as without changing it to NaN or INF.
 
+@liveexample{The following code shows how an `out_of_range` exception can be
+caught.,out_of_range}
+
+@sa @ref exception for the base class of the library exceptions
+@sa @ref parse_error for exceptions indicating a parse error
+@sa @ref invalid_iterator for exceptions indicating errors with iterators
+@sa @ref type_error for exceptions indicating executing a member function with
+                    a wrong type
+@sa @ref other_error for exceptions indicating other library errors
+
 @since version 3.0.0
 */
 class out_of_range : public exception
@@ -374,7 +439,10 @@ class out_of_range : public exception
 };
 
 /*!
-@brief exception indicating other errors
+@brief exception indicating other library errors
+
+This exception is thrown in case of errors that cannot be classified with the
+other exception types.
 
 Exceptions have ids 5xx.
 
@@ -383,6 +451,16 @@ name / id                      | example message | description
 json.exception.other_error.501 | unsuccessful: {"op":"test","path":"/baz", "value":"bar"} | A JSON Patch operation 'test' failed. The unsuccessful operation is also printed.
 json.exception.other_error.502 | invalid object size for conversion | Some conversions to user-defined types impose constraints on the object size (e.g. std::pair)
 
+@sa @ref exception for the base class of the library exceptions
+@sa @ref parse_error for exceptions indicating a parse error
+@sa @ref invalid_iterator for exceptions indicating errors with iterators
+@sa @ref type_error for exceptions indicating executing a member function with
+                    a wrong type
+@sa @ref out_of_range for exceptions indicating access out of the defined range
+
+@liveexample{The following code shows how an `other_error` exception can be
+caught.,other_error}
+
 @since version 3.0.0
 */
 class other_error : public exception
@@ -1739,7 +1817,7 @@ class lexer
     checks if it is inside the range. If a violation was detected, set up an
     error message and return false. Otherwise, return true.
 
-    @return true iff no range violation was detected
+    @return true if and only if no range violation was detected
     */
     bool next_byte_in_range(std::initializer_list<int> ranges)
     {
@@ -4485,7 +4563,7 @@ class binary_reader
     /*!
     @brief determine system byte order
 
-    @return true iff system's byte order is little endian
+    @return true if and only if system's byte order is little endian
 
     @note from http://stackoverflow.com/a/1001328/266378
     */
@@ -7378,6 +7456,9 @@ class basic_json
     @liveexample{The following code shows an example output of the `meta()`
     function.,meta}
 
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes to any JSON value.
+
     @complexity Constant.
 
     @since 2.1.0
@@ -8184,9 +8265,14 @@ class basic_json
 
     @complexity Constant.
 
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes to any JSON value.
+
     @liveexample{The following code shows the constructor for different @ref
     value_t values,basic_json__value_t}
 
+    @sa @ref clear() -- restores the postcondition of this constructor
+
     @since version 1.0.0
     */
     basic_json(const value_t v)
@@ -8231,9 +8317,9 @@ class basic_json
     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
+      `std::array`, `std::valarray`, `std::set`, `std::unordered_set`,
-      `unordered_multiset` with a `value_type` from which a @ref basic_json
+      `std::multiset`, and `std::unordered_multiset` with a `value_type` from
-      value can be constructed.
+      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
@@ -8259,13 +8345,16 @@ class basic_json
 
     @tparam U = `uncvref_t<CompatibleType>`
 
-    @param[in] val the value to be forwarded
+    @param[in] val the value to be forwarded to the respective constructor
 
     @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
+    @exceptionsafety Depends on the called constructor. For types directly
+    supported by the library (i.e., all types for which no `to_json()` function
+    was provided), strong guarantee holds: if an exception is thrown, there are
+    no changes to any JSON value.
 
     @liveexample{The following code shows the constructor with several
     compatible types.,basic_json__CompatibleType}
@@ -8305,7 +8394,7 @@ class basic_json
 
     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
+    2. C++ has no 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.
@@ -8347,6 +8436,9 @@ class basic_json
 
     @complexity Linear in the size of the initializer list @a init.
 
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes to any JSON value.
+
     @liveexample{The example below shows how JSON values are created from
     initializer lists.,basic_json__list_init_t}
 
@@ -8433,6 +8525,9 @@ class basic_json
 
     @complexity Linear in the size of @a init.
 
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes to any JSON value.
+
     @liveexample{The following code shows an example for the `array`
     function.,array}
 
@@ -8473,6 +8568,9 @@ class basic_json
 
     @complexity Linear in the size of @a init.
 
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes to any JSON value.
+
     @liveexample{The following code shows an example for the `object`
     function.,object}
 
@@ -8492,14 +8590,18 @@ class basic_json
     @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,
+    In case @a cnt is `0`, an empty array is created.
-    `std::distance(begin(),end()) == cnt` holds.
 
     @param[in] cnt  the number of JSON copies of @a val to create
     @param[in] val  the JSON value to copy
 
+    @post `std::distance(begin(),end()) == cnt` holds.
+
     @complexity Linear in @a cnt.
 
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes to any JSON value.
+
     @liveexample{The following code shows examples for the @ref
     basic_json(size_type\, const basic_json&)
     constructor.,basic_json__size_type_basic_json}
@@ -8518,12 +8620,13 @@ class basic_json
 
     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
+    - In case of a null type, invalid_iterator.206 is thrown.
-      be `begin()` and @a last must be `end()`. In this case, the value is
+    - In case of other 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`.
+      similar versions for `std::vector` or `std::map`; that is, a JSON array
-    - In case of a null type, invalid_iterator.206 is thrown.
+      or object is constructed from the values in the range.
 
     @tparam InputIT an input iterator type (@ref iterator or @ref
     const_iterator)
@@ -8532,11 +8635,20 @@ class basic_json
     @param[in] last end of the range to copy from (excluded)
 
     @pre Iterators @a first and @a last must be initialized. **This
-         precondition is enforced with an assertion.**
+         precondition is enforced with an assertion (see warning).** If
+         assertions are switched off, a violation of this precondition yields
+         undefined behavior.
 
     @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.
+         description of the exceptions below. A violation of this precondition
+         yields undefined behavior.
+
+    @warning A precondition is enforced with a runtime assertion that will
+             result in calling `std::abort` if this precondition is not met.
+             Assertions can be disabled by defining `NDEBUG` at compile time.
+             See http://en.cppreference.com/w/cpp/error/assert for more
+             information.
 
     @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,
@@ -8550,6 +8662,9 @@ class basic_json
 
     @complexity Linear in distance between @a first and @a last.
 
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes to any JSON value.
+
     @liveexample{The example below shows several ways to create JSON values by
     specifying a subrange with iterators.,basic_json__InputIt_InputIt}
 
@@ -8652,6 +8767,7 @@ class basic_json
     // other constructors and destructor //
     ///////////////////////////////////////
 
+    /// @private
     basic_json(const detail::json_ref<basic_json>& ref)
         : basic_json(ref.moved_or_copied())
     {}
@@ -8663,8 +8779,13 @@ class basic_json
 
     @param[in] other  the JSON value to copy
 
+    @post `*this == other`
+
     @complexity Linear in the size of @a other.
 
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes to any JSON value.
+
     @requirement This function helps `basic_json` satisfying the
     [Container](http://en.cppreference.com/w/cpp/concept/Container)
     requirements:
@@ -8742,10 +8863,18 @@ class basic_json
 
     @param[in,out] other  value to move to this object
 
-    @post @a other is a JSON null value
+    @post `*this` has the same value as @a other before the call.
+    @post @a other is a JSON null value.
 
     @complexity Constant.
 
+    @exceptionsafety No-throw guarantee: this constructor never throws
+    exceptions.
+
+    @requirement This function helps `basic_json` satisfying the
+    [MoveConstructible](http://en.cppreference.com/w/cpp/concept/MoveConstructible)
+    requirements.
+
     @liveexample{The code below shows the move constructor explicitly called
     via std::move.,basic_json__moveconstructor}
 
@@ -8770,7 +8899,7 @@ class 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.
+    and the `swap()` member function.
 
     @param[in] other  value to copy from
 
@@ -8851,7 +8980,7 @@ class basic_json
     representation.
     @param[in] indent_char The character to use for indentation if @a indent is
     greater than `0`. The default is ` ` (space).
-    @param[in] ensure_ascii If ensure_ascii is true, all non-ASCII characters
+    @param[in] ensure_ascii If @a ensure_ascii is true, all non-ASCII characters
     in the output are escaped with \uXXXX sequences, and the result consists
     of ASCII characters only.
 
@@ -8859,12 +8988,17 @@ class basic_json
 
     @complexity Linear.
 
-    @liveexample{The following example shows the effect of different @a indent
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
-    parameters to the result of the serialization.,dump}
+    changes in the JSON value.
+
+    @liveexample{The following example shows the effect of different @a indent\,
+    @a indent_char\, and @a ensure_ascii 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
+    @since version 1.0.0; indentation character @a indent_char and option
+           @a ensure_ascii added in version 3.0.0
     */
     string_t dump(const int indent = -1, const char indent_char = ' ',
                   const bool ensure_ascii = false) const
@@ -8891,6 +9025,17 @@ class basic_json
     enumeration.
 
     @return the type of the JSON value
+            Value type                | return value
+            ------------------------- | -------------------------
+            null                      | value_t::null
+            boolean                   | value_t::boolean
+            string                    | value_t::string
+            number (integer)          | value_t::number_integer
+            number (unsigned integer) | value_t::number_unsigned
+            number (foating-point)    | value_t::number_float
+            object                    | value_t::object
+            array                     | value_t::array
+            discarded                 | value_t::discarded
 
     @complexity Constant.
 
@@ -8900,6 +9045,9 @@ class basic_json
     @liveexample{The following code exemplifies `type()` for all JSON
     types.,type}
 
+    @sa @ref operator value_t() -- return the type of the JSON value (implicit) 
+    @sa @ref type_name() -- return the type as string
+
     @since version 1.0.0
     */
     constexpr value_t type() const noexcept
@@ -8910,8 +9058,8 @@ class basic_json
     /*!
     @brief return whether type is primitive
 
-    This function returns true iff the JSON type is primitive (string, number,
+    This function returns true if and only if the JSON type is primitive
-    boolean, or null).
+    (string, number, boolean, or null).
 
     @return `true` if type is primitive (string, number, boolean, or null),
     `false` otherwise.
@@ -8940,8 +9088,8 @@ class basic_json
     /*!
     @brief return whether type is structured
 
-    This function returns true iff the JSON type is structured (array or
+    This function returns true if and only if the JSON type is structured
-    object).
+    (array or object).
 
     @return `true` if type is structured (array or object), `false` otherwise.
 
@@ -8967,7 +9115,7 @@ class basic_json
     /*!
     @brief return whether value is null
 
-    This function returns true iff the JSON value is null.
+    This function returns true if and only if the JSON value is null.
 
     @return `true` if type is null, `false` otherwise.
 
@@ -8989,7 +9137,7 @@ class basic_json
     /*!
     @brief return whether value is a boolean
 
-    This function returns true iff the JSON value is a boolean.
+    This function returns true if and only if the JSON value is a boolean.
 
     @return `true` if type is boolean, `false` otherwise.
 
@@ -9011,8 +9159,8 @@ class basic_json
     /*!
     @brief return whether value is a number
 
-    This function returns true iff the JSON value is a number. This includes
+    This function returns true if and only if the JSON value is a number. This
-    both integer and floating-point values.
+    includes both integer (signed and unsigned) and floating-point values.
 
     @return `true` if type is number (regardless whether integer, unsigned
     integer or floating-type), `false` otherwise.
@@ -9041,8 +9189,8 @@ class basic_json
     /*!
     @brief return whether value is an integer number
 
-    This function returns true iff the JSON value is an integer or unsigned
+    This function returns true if and only if the JSON value is a signed or
-    integer number. This excludes floating-point values.
+    unsigned integer number. This excludes floating-point values.
 
     @return `true` if type is an integer or unsigned integer number, `false`
     otherwise.
@@ -9070,8 +9218,8 @@ class basic_json
     /*!
     @brief return whether value is an unsigned integer number
 
-    This function returns true iff the JSON value is an unsigned integer
+    This function returns true if and only if the JSON value is an unsigned
-    number. This excludes floating-point and (signed) integer values.
+    integer number. This excludes floating-point and signed integer values.
 
     @return `true` if type is an unsigned integer number, `false` otherwise.
 
@@ -9098,8 +9246,8 @@ class basic_json
     /*!
     @brief return whether value is a floating-point number
 
-    This function returns true iff the JSON value is a floating-point number.
+    This function returns true if and only if the JSON value is a
-    This excludes integer and unsigned integer values.
+    floating-point number. This excludes signed and unsigned integer values.
 
     @return `true` if type is a floating-point number, `false` otherwise.
 
@@ -9126,7 +9274,7 @@ class basic_json
     /*!
     @brief return whether value is an object
 
-    This function returns true iff the JSON value is an object.
+    This function returns true if and only if the JSON value is an object.
 
     @return `true` if type is object, `false` otherwise.
 
@@ -9148,7 +9296,7 @@ class basic_json
     /*!
     @brief return whether value is an array
 
-    This function returns true iff the JSON value is an array.
+    This function returns true if and only if the JSON value is an array.
 
     @return `true` if type is array, `false` otherwise.
 
@@ -9170,7 +9318,7 @@ class basic_json
     /*!
     @brief return whether value is a string
 
-    This function returns true iff the JSON value is a string.
+    This function returns true if and only if the JSON value is a string.
 
     @return `true` if type is string, `false` otherwise.
 
@@ -9192,8 +9340,8 @@ class basic_json
     /*!
     @brief return whether value is discarded
 
-    This function returns true iff the JSON value was discarded during parsing
+    This function returns true if and only if the JSON value was discarded
-    with a callback function (see @ref parser_callback_t).
+    during parsing with a callback function (see @ref parser_callback_t).
 
     @note This function will always be `false` for JSON values after parsing.
     That is, discarded values can only occur during parsing, but will be
@@ -9232,6 +9380,9 @@ class basic_json
     @liveexample{The following code exemplifies the @ref value_t operator for
     all JSON types.,operator__value_t}
 
+    @sa @ref type() -- return the type of the JSON value (explicit)
+    @sa @ref type_name() -- return the type as string
+
     @since version 1.0.0
     */
     constexpr operator value_t() const noexcept
@@ -11124,9 +11275,9 @@ class basic_json
     /// @{
 
     /*!
-    @brief checks whether the container is empty
+    @brief checks whether the container is empty.
 
-    Checks if a JSON value has no elements.
+    Checks if a JSON value has no elements (i.e. whether its @ref size is `0`).
 
     @return The return value depends on the different types and is
             defined as follows:
@@ -11139,23 +11290,27 @@ class basic_json
             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
+    @liveexample{The following code uses `empty()` to check if a JSON
-    is empty - it returns whether the JSON container itself is empty which is
+    object contains any elements.,empty}
-    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.
 
+    @iterators No changes.
+
+    @exceptionsafety No-throw guarantee: this function never throws exceptions.
+
+    @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.
+
     @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
@@ -11206,23 +11361,27 @@ class basic_json
             object      | result of function object_t::size()
             array       | result of function array_t::size()
 
-    @note This function does not return the length of a string stored as JSON
+    @liveexample{The following code calls `size()` on the different value
-    value - it returns the number of elements in the JSON value which is 1 in
+    types.,size}
-    the case of a string.
 
     @complexity Constant, as long as @ref array_t and @ref object_t satisfy
     the Container concept; that is, their size() functions have constant
     complexity.
 
+    @iterators No changes.
+
+    @exceptionsafety No-throw guarantee: this function never throws exceptions.
+
+    @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.
+
     @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
 
@@ -11276,10 +11435,17 @@ class basic_json
             object      | result of function `object_t::max_size()`
             array       | result of function `array_t::max_size()`
 
+    @liveexample{The following code calls `max_size()` on the different value
+    types. Note the output is implementation specific.,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.
 
+    @iterators No changes.
+
+    @exceptionsafety No-throw guarantee: this function never throws exceptions.
+
     @requirement This function helps `basic_json` satisfying the
     [Container](http://en.cppreference.com/w/cpp/concept/Container)
     requirements:
@@ -11287,9 +11453,6 @@ class basic_json
     - 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
@@ -11332,7 +11495,8 @@ class basic_json
     @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:
+    if @ref basic_json(value_t) would have been called with the current value
+    type from @ref type():
 
     Value type  | initial value
     ----------- | -------------
@@ -11343,11 +11507,24 @@ class basic_json
     object      | `{}`
     array       | `[]`
 
-    @complexity Linear in the size of the JSON value.
+    @post Has the same effect as calling
+    @code {.cpp}
+    *this = basic_json(type());
+    @endcode
 
     @liveexample{The example below shows the effect of `clear()` to different
     JSON types.,clear}
 
+    @complexity Linear in the size of the JSON value.
+
+    @iterators All iterators, pointers and references related to this container
+               are invalidated.
+
+    @exceptionsafety No-throw guarantee: this function never throws exceptions.
+
+    @sa @ref basic_json(value_t) -- constructor that creates an object with the
+        same value than calling `clear()`
+
     @since version 1.0.0
     */
     void clear() noexcept
@@ -12185,12 +12362,27 @@ class basic_json
       comparison. Note than two NaN values are always treated as unequal.
     - Two JSON null values are equal.
 
+    @note Floating-point inside JSON values numbers are compared with
+    `json::number_float_t::operator==` which is `double::operator==` by
+    default. To compare floating-point while respecting an epsilon, an alternative
+    [comparison function](https://github.com/mariokonrad/marnav/blob/master/src/marnav/math/floatingpoint.hpp#L34-#L39)
+    could be used, for instance
+    @code {.cpp}
+    template <typename T, typename = typename std::enable_if<std::is_floating_point<T>::value, T>::type>
+    inline bool is_same(T a, T b, T epsilon = std::numeric_limits<T>::epsilon()) noexcept
+    {
+        return std::abs(a - b) <= epsilon;
+    }
+    @endcode
+
     @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
 
+    @exceptionsafety No-throw guarantee: this function never throws exceptions.
+
     @complexity Linear.
 
     @liveexample{The example demonstrates comparing several JSON
@@ -12296,6 +12488,8 @@ class basic_json
 
     @complexity Linear.
 
+    @exceptionsafety No-throw guarantee: this function never throws exceptions.
+
     @liveexample{The example demonstrates comparing several JSON
     types.,operator__notequal}
 
@@ -12347,6 +12541,8 @@ class basic_json
 
     @complexity Linear.
 
+    @exceptionsafety No-throw guarantee: this function never throws exceptions.
+
     @liveexample{The example demonstrates comparing several JSON
     types.,operator__less}
 
@@ -12454,6 +12650,8 @@ class basic_json
 
     @complexity Linear.
 
+    @exceptionsafety No-throw guarantee: this function never throws exceptions.
+
     @liveexample{The example demonstrates comparing several JSON
     types.,operator__greater}
 
@@ -12498,6 +12696,8 @@ class basic_json
 
     @complexity Linear.
 
+    @exceptionsafety No-throw guarantee: this function never throws exceptions.
+
     @liveexample{The example demonstrates comparing several JSON
     types.,operator__lessequal}
 
@@ -12542,6 +12742,8 @@ class basic_json
 
     @complexity Linear.
 
+    @exceptionsafety No-throw guarantee: this function never throws exceptions.
+
     @liveexample{The example demonstrates comparing several JSON
     types.,operator__greaterequal}
 
@@ -12630,7 +12832,7 @@ class basic_json
     @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&)
+                @ref operator<<(std::ostream&, const basic_json&)
                 instead; that is, replace calls like `j >> o;` with `o << j;`.
     */
     JSON_DEPRECATED
@@ -12813,7 +13015,7 @@ class basic_json
     @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&)
+                @ref operator>>(std::istream&, basic_json&)
                 instead; that is, replace calls like `j << i;` with `i >> j;`.
     */
     JSON_DEPRECATED
@@ -12865,16 +13067,31 @@ class basic_json
     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.
 
-    @return basically a string representation of a the @a m_type member
+    @return a string representation of a the @a m_type member:
+            Value type  | return value
+            ----------- | -------------
+            null        | `"null"`
+            boolean     | `"boolean"`
+            string      | `"string"`
+            number      | `"number"` (for all number types)
+            object      | `"object"`
+            array       | `"array"`
+            discarded   | `"discarded"`
+
+    @exceptionsafety No-throw guarantee: this function never throws exceptions.
 
     @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, const char* since 3.0.0
+    @sa @ref type() -- return the type of the JSON value
+    @sa @ref operator value_t() -- return the type of the JSON value (implicit) 
+
+    @since version 1.0.0, public since 2.1.0, `const char*` and `noexcept`
+    since 3.0.0
     */
-    const char* type_name() const
+    const char* type_name() const noexcept
     {
         {
             switch (m_type)

test/src/unit-class_parser.cpp

@@ -173,6 +173,38 @@ TEST_CASE("parser class")
                 CHECK_THROWS_AS(parser_helper("\"\x1d\""), json::parse_error&);
                 CHECK_THROWS_AS(parser_helper("\"\x1e\""), json::parse_error&);
                 CHECK_THROWS_AS(parser_helper("\"\x1f\""), json::parse_error&);
+                CHECK_THROWS_WITH(parser_helper("\"\x00\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: missing closing quote; last read: '\"'");
+                CHECK_THROWS_WITH(parser_helper("\"\x01\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+0001>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x02\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+0002>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x03\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+0003>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x04\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+0004>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x05\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+0005>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x06\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+0006>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x07\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+0007>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x08\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+0008>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x09\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+0009>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x0a\""), "[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(parser_helper("\"\x0b\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+000B>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x0c\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+000C>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x0d\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+000D>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x0e\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+000E>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x0f\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+000F>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x10\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+0010>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x11\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+0011>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x12\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+0012>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x13\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+0013>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x14\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+0014>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x15\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+0015>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x16\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+0016>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x17\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+0017>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x18\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+0018>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x19\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+0019>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x1a\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+001A>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x1b\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+001B>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x1c\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+001C>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x1d\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+001D>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x1e\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+001E>'");
+                CHECK_THROWS_WITH(parser_helper("\"\x1f\""), "[json.exception.parse_error.101] parse error at 2: syntax error - invalid string: control character must be escaped; last read: '\"<U+001F>'");
             }
 
             SECTION("escaped")

test/src/unit-concepts.cpp

@@ -94,6 +94,7 @@ TEST_CASE("concepts")
 
         SECTION("MoveConstructible")
         {
+            CHECK(std::is_move_constructible<json>::value);
             CHECK(std::is_nothrow_move_constructible<json>::value);
         }
 

test/src/unit-constructor1.cpp

@@ -1180,6 +1180,26 @@ TEST_CASE("constructors")
     }
 
     SECTION("create an array of n copies of a given value")
+    {
+        SECTION("cnt = 0")
+        {
+            json v = {1, "foo", 34.23, {1, 2, 3}, {{"A", 1}, {"B", 2u}}};
+            json arr(0, v);
+            CHECK(arr.size() == 0);
+        }
+
+        SECTION("cnt = 1")
+        {
+            json v = {1, "foo", 34.23, {1, 2, 3}, {{"A", 1}, {"B", 2u}}};
+            json arr(1, v);
+            CHECK(arr.size() == 1);
+            for (auto& x : arr)
+            {
+                CHECK(x == v);
+            }
+        }
+
+        SECTION("cnt = 3")
         {
             json v = {1, "foo", 34.23, {1, 2, 3}, {{"A", 1}, {"B", 2u}}};
             json arr(3, v);
@@ -1189,6 +1209,7 @@ TEST_CASE("constructors")
                 CHECK(x == v);
             }
         }
+    }
 
     SECTION("create a JSON container from an iterator range")
     {

test/src/unit-deserialization.cpp

@@ -323,6 +323,8 @@ TEST_CASE("deserialization")
             {
                 uint8_t v[] = {'\"', 0x7F, 0xDF, 0x7F};
                 CHECK_THROWS_AS(json::parse(std::begin(v), std::end(v)), json::parse_error&);
+                CHECK_THROWS_WITH(json::parse(std::begin(v), std::end(v)),
+                    "[json.exception.parse_error.101] parse error at 4: syntax error - invalid string: ill-formed UTF-8 byte; last read: '\"\x7f\xdf\x7f'");
                 CHECK(not json::accept(std::begin(v), std::end(v)));
 
                 json j_error;

test/src/unit-modifiers.cpp

@@ -38,17 +38,21 @@ TEST_CASE("modifiers")
         SECTION("boolean")
         {
             json j = true;
+            json k = j;
 
             j.clear();
             CHECK(j == json(json::value_t::boolean));
+            CHECK(j == json(k.type()));
         }
 
         SECTION("string")
         {
             json j = "hello world";
+            json k = j;
 
             j.clear();
             CHECK(j == json(json::value_t::string));
+            CHECK(j == json(k.type()));
         }
 
         SECTION("array")
@@ -56,19 +60,23 @@ TEST_CASE("modifiers")
             SECTION("empty array")
             {
                 json j = json::array();
+                json k = j;
 
                 j.clear();
                 CHECK(j.empty());
                 CHECK(j == json(json::value_t::array));
+                CHECK(j == json(k.type()));
             }
 
             SECTION("filled array")
             {
                 json j = {1, 2, 3};
+                json k = j;
 
                 j.clear();
                 CHECK(j.empty());
                 CHECK(j == json(json::value_t::array));
+                CHECK(j == json(k.type()));
             }
         }
 
@@ -77,52 +85,64 @@ TEST_CASE("modifiers")
             SECTION("empty object")
             {
                 json j = json::object();
+                json k = j;
 
                 j.clear();
                 CHECK(j.empty());
                 CHECK(j == json(json::value_t::object));
+                CHECK(j == json(k.type()));
             }
 
             SECTION("filled object")
             {
                 json j = {{"one", 1}, {"two", 2}, {"three", 3}};
+                json k = j;
 
                 j.clear();
                 CHECK(j.empty());
                 CHECK(j == json(json::value_t::object));
+                CHECK(j == json(k.type()));
             }
         }
 
         SECTION("number (integer)")
         {
             json j = 23;
+            json k = j;
 
             j.clear();
             CHECK(j == json(json::value_t::number_integer));
+            CHECK(j == json(k.type()));
         }
 
         SECTION("number (unsigned)")
         {
             json j = 23u;
+            json k = j;
 
             j.clear();
             CHECK(j == json(json::value_t::number_integer));
+            CHECK(j == json(k.type()));
         }
 
         SECTION("number (float)")
         {
             json j = 23.42;
+            json k = j;
 
             j.clear();
             CHECK(j == json(json::value_t::number_float));
+            CHECK(j == json(k.type()));
         }
 
         SECTION("null")
         {
             json j = nullptr;
+            json k = j;
 
             j.clear();
             CHECK(j == json(json::value_t::null));
+            CHECK(j == json(k.type()));
         }
     }