Overwork documentation (#4516)

docs/mkdocs/docs/api/basic_json/accept.md

@@ -29,9 +29,9 @@ Unlike the [`parse`](parse.md) function, this function neither throws an excepti
 :   A compatible input, for instance:
     
     - an `std::istream` object
-    - a `FILE` pointer (must not be null)
+    - a `FILE` pointer (throws if null)
     - a C-style array of characters
-    - a pointer to a null-terminated string of single byte characters
+    - a pointer to a null-terminated string of single byte characters (throws if null)
     - a `std::string`
     - an object `obj` for which `begin(obj)` and `end(obj)` produces a valid pair of iterators.
 
@@ -64,18 +64,17 @@ Whether the input is valid JSON.
 
 Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
 
+## Exceptions
+
+Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an empty input like a null `FILE*` or `char*` pointer.
+
 ## Complexity
 
 Linear in the length of the input. The parser is a predictive LL(1) parser.
 
 ## Notes
 
-(1) A UTF-8 byte order mark is silently ignored.
-
-!!! danger "Runtime assertion"
-
-    The precondition that a passed `#!cpp FILE` pointer must not be null is enforced with a
-    [runtime assertion](../../features/assertions.md).
+A UTF-8 byte order mark is silently ignored.
 
 ## Examples
 
@@ -102,6 +101,7 @@ Linear in the length of the input. The parser is a predictive LL(1) parser.
 
 - Added in version 3.0.0.
 - Ignoring comments via `ignore_comments` added in version 3.9.0.
+- Changed [runtime assertion](../../features/assertions.md) in case of `FILE*` null pointers to exception in version 3.11.4.
 
 !!! warning "Deprecation"
 

docs/mkdocs/docs/api/basic_json/emplace.md

@@ -14,6 +14,11 @@ created from `args`.
 `Args`
 :   compatible types to create a `basic_json` object
 
+## Iterator invalidation
+
+For [`ordered_json`](../ordered_json.md), adding a value to an object can yield a reallocation, in which case all
+iterators (including the `end()` iterator) and all references to the elements are invalidated.
+
 ## Parameters
 
 `args` (in)

docs/mkdocs/docs/api/basic_json/emplace_back.md

@@ -13,6 +13,12 @@ Creates a JSON value from the passed parameters `args` to the end of the JSON va
 `Args`
 :   compatible types to create a `basic_json` object
 
+## Iterator invalidation
+
+By adding an element to the end of the array, a reallocation can happen, in which case all iterators (including the
+[`end()`](end.md) iterator) and all references to the elements are invalidated. Otherwise, only the [`end()`](end.md)
+iterator is invalidated.
+
 ## Parameters
 
 `args` (in)
@@ -48,6 +54,11 @@ Amortized constant.
     --8<-- "examples/emplace_back.output"
     ```
 
+## See also
+
+- [operator+=](operator+=.md) add a value to an array/object
+- [push_back](push_back.md) add a value to an array/object
+
 ## Version history
 
 - Since version 2.0.8.

docs/mkdocs/docs/api/basic_json/exception.md

@@ -8,24 +8,36 @@ This class is an extension of [`std::exception`](https://en.cppreference.com/w/c
 member `id` for exception ids. It is used as the base class for all exceptions thrown by the `basic_json` class. This
 class can hence be used as "wildcard" to catch exceptions, see example below.
 
-```plantuml
-std::exception <|-- basic_json::exception
-basic_json::exception <|-- basic_json::parse_error
-basic_json::exception <|-- basic_json::invalid_iterator
-basic_json::exception <|-- basic_json::type_error
-basic_json::exception <|-- basic_json::out_of_range
-basic_json::exception <|-- basic_json::other_error
+```mermaid
+classDiagram
+  direction LR
+  
+    class std_exception ["std::exception"] {
+        <<interface>>
+    }
 
-interface std::exception {}
+    class json_exception ["basic_json::exception"] {
+        +const int id
+        +const char* what() const
+    }
+    
+    class json_parse_error ["basic_json::parse_error"] {
+        +const std::size_t byte
+    }
 
-class basic_json::exception #FFFF00 {
-    + const int id
-    + const char* what() const
-}
+    class json_invalid_iterator ["basic_json::invalid_iterator"]
+    class json_type_error ["basic_json::type_error"]
+    class json_out_of_range ["basic_json::out_of_range"]
+    class json_other_error ["basic_json::other_error"]
 
-class basic_json::parse_error {
-    + const std::size_t byte
-}
+    std_exception <|-- json_exception
+    json_exception <|-- json_parse_error
+    json_exception <|-- json_invalid_iterator
+    json_exception <|-- json_type_error
+    json_exception <|-- json_out_of_range
+    json_exception <|-- json_other_error
+
+    style json_exception fill:#CCCCFF
 ```
 
 Subclasses:

docs/mkdocs/docs/api/basic_json/get_ptr.md

@@ -37,7 +37,9 @@ Constant.
 
     The pointer becomes invalid if the underlying JSON object changes.
 
-    Consider the following example code where the pointer `ptr` changes after the array is resized. As a result, reading or writing to `ptr` after the array change would be undefined behavior. The address of the first array element changes, because the underlying `std::vector` is resized after adding a fifth element.
+    Consider the following example code where the pointer `ptr` changes after the array is resized. As a result,
+    reading or writing to `ptr` after the array change would be undefined behavior. The address of the first array
+    element changes, because the underlying `std::vector` is resized after adding a fifth element.
 
     ```cpp
     #include <iostream>

docs/mkdocs/docs/api/basic_json/index.md

@@ -42,7 +42,15 @@ class basic_json;
 
 ## Iterator invalidation
 
-Todo
+All operations that add values to an **array** ([`push_back`](push_back.md) , [`operator+=`](operator+=.md),
+[`emplace_back`](emplace_back.md), [`insert`](insert.md), and [`operator[]`](operator%5B%5D.md) for a non-existing
+index) can yield a reallocation, in which case all iterators (including the [`end()`](end.md) iterator) and all
+references to the elements are invalidated.
+
+For [`ordered_json`](../ordered_json.md), also all operations that add a value to an **object**
+([`push_back`](push_back.md), [`operator+=`](operator+=.md), [`emplace`](emplace.md), [`insert`](insert.md),
+[`update`](update.md), and [`operator[]`](operator%5B%5D.md) for a non-existing key) can yield a reallocation, in
+which case all iterators (including the [`end()`](end.md) iterator) and all references to the elements are invalidated.
 
 ## Requirements
 

docs/mkdocs/docs/api/basic_json/insert.md

@@ -24,6 +24,17 @@ void insert(const_iterator first, const_iterator last);
 4. Inserts elements from initializer list `ilist` into array before iterator `pos`.
 5. Inserts elements from range `[first, last)` into object.
 
+## Iterator invalidation
+
+For all cases where an element is added to an **array**, a reallocation can happen, in which case all iterators
+(including the [`end()`](end.md) iterator) and all references to the elements are invalidated. Otherwise, only the
+[`end()`](end.md) iterator is invalidated. Also, any iterator or reference after the insertion point will point to the
+same index which is now a different value.
+
+For [`ordered_json`](../ordered_json.md), also adding an element to an **object** can yield a reallocation which again
+invalidates all iterators and all references. Also, any iterator or reference after the insertion point will point to
+the same index which is now a different value.
+
 ## Parameters
 
 `pos` (in)

docs/mkdocs/docs/api/basic_json/invalid_iterator.md

@@ -8,26 +8,36 @@ This exception is thrown if iterators passed to a library function do not match
 
 Exceptions have ids 2xx (see [list of iterator errors](../../home/exceptions.md#iterator-errors)).
 
-```plantuml
-std::exception <|-- basic_json::exception
-basic_json::exception <|-- basic_json::parse_error
-basic_json::exception <|-- basic_json::invalid_iterator
-basic_json::exception <|-- basic_json::type_error
-basic_json::exception <|-- basic_json::out_of_range
-basic_json::exception <|-- basic_json::other_error
+```mermaid
+classDiagram
+  direction LR
+  
+    class std_exception ["std::exception"] {
+        <<interface>>
+    }
 
-interface std::exception {}
+    class json_exception ["basic_json::exception"] {
+        +const int id
+        +const char* what() const
+    }
+    
+    class json_parse_error ["basic_json::parse_error"] {
+        +const std::size_t byte
+    }
 
-class basic_json::exception {
-    + const int id
-    + const char* what() const
-}
+    class json_invalid_iterator ["basic_json::invalid_iterator"]
+    class json_type_error ["basic_json::type_error"]
+    class json_out_of_range ["basic_json::out_of_range"]
+    class json_other_error ["basic_json::other_error"]
 
-class basic_json::parse_error {
-    + const std::size_t byte
-}
+    std_exception <|-- json_exception
+    json_exception <|-- json_parse_error
+    json_exception <|-- json_invalid_iterator
+    json_exception <|-- json_type_error
+    json_exception <|-- json_out_of_range
+    json_exception <|-- json_other_error
 
-class basic_json::invalid_iterator #FFFF00 {}
+    style json_invalid_iterator fill:#CCCCFF
 ```
 
 ## Member functions

docs/mkdocs/docs/api/basic_json/items.md

@@ -66,7 +66,7 @@ When iterating over an array, `key()` will return the index of the element as st
 !!! danger "Lifetime issues"
 
     Using `items()` on temporary objects is dangerous. Make sure the object's lifetime exceeds the iteration. See
-    <https://github.com/nlohmann/json/issues/2040> for more information.
+    [#2040](https://github.com/nlohmann/json/issues/2040) for more information.
 
 ## Examples
 

docs/mkdocs/docs/api/basic_json/operator+=.md

@@ -27,6 +27,15 @@ reference operator+=(initializer_list_t init);
     `init` is converted into an object element and added using `operator+=(const typename object_t::value_type&)`.
     Otherwise, `init` is converted to a JSON value and added using `operator+=(basic_json&&)`.
 
+## Iterator invalidation
+
+For all cases where an element is added to an **array**, a reallocation can happen, in which case all iterators (including
+the [`end()`](end.md) iterator) and all references to the elements are invalidated. Otherwise, only the
+[`end()`](end.md) iterator is invalidated.
+
+For [`ordered_json`](../ordered_json.md), also adding an element to an **object** can yield a reallocation which again
+invalidates all iterators and all references.
+
 ## Parameters
 
 `val` (in)
@@ -103,6 +112,11 @@ interpreted as `object_t::value_type` or `std::initializer_list<basic_json>`, se
     --8<-- "examples/push_back__initializer_list.output"
     ```
 
+## See also
+
+- [emplace_back](emplace_back.md) add a value to an array
+- [push_back](push_back.md) add a value to an array/object
+
 ## Version history
 
 1. Since version 1.0.0.

docs/mkdocs/docs/api/basic_json/operator[].md

@@ -34,6 +34,15 @@ const_reference operator[](const json_pointer& ptr) const;
     [`string_t`](string_t.md) using  [`object_comparator_t`](object_comparator_t.md).
     This can also be a string view (C++17).
 
+## Iterator invalidation
+
+For the non-const versions 1. and 4., when passing an **array** index that does not exist, it is created and filled with
+a `#!json null` value before a reference to it is returned. For this, a reallocation can happen, in which case all
+iterators (including the [`end()`](end.md) iterator) and all references to the elements are invalidated.
+
+For [`ordered_json`](../ordered_json.md), also passing an **object key** to the non-const versions 2., 3., and 4., a
+reallocation can happen which again invalidates all iterators and all references.
+
 ## Parameters
 
 `idx` (in)

docs/mkdocs/docs/api/basic_json/other_error.md

@@ -8,26 +8,36 @@ This exception is thrown in case of errors that cannot be classified with the ot
 
 Exceptions have ids 5xx (see [list of other errors](../../home/exceptions.md#further-exceptions)).
 
-```plantuml
-std::exception <|-- basic_json::exception
-basic_json::exception <|-- basic_json::parse_error
-basic_json::exception <|-- basic_json::invalid_iterator
-basic_json::exception <|-- basic_json::type_error
-basic_json::exception <|-- basic_json::out_of_range
-basic_json::exception <|-- basic_json::other_error
+```mermaid
+classDiagram
+  direction LR
+  
+    class std_exception ["std::exception"] {
+        <<interface>>
+    }
 
-interface std::exception {}
+    class json_exception ["basic_json::exception"] {
+        +const int id
+        +const char* what() const
+    }
+    
+    class json_parse_error ["basic_json::parse_error"] {
+        +const std::size_t byte
+    }
 
-class basic_json::exception {
-    + const int id
-    + const char* what() const
-}
+    class json_invalid_iterator ["basic_json::invalid_iterator"]
+    class json_type_error ["basic_json::type_error"]
+    class json_out_of_range ["basic_json::out_of_range"]
+    class json_other_error ["basic_json::other_error"]
 
-class basic_json::parse_error {
-    + const std::size_t byte
-}
+    std_exception <|-- json_exception
+    json_exception <|-- json_parse_error
+    json_exception <|-- json_invalid_iterator
+    json_exception <|-- json_type_error
+    json_exception <|-- json_out_of_range
+    json_exception <|-- json_other_error
 
-class basic_json::other_error #FFFF00 {}
+    style json_other_error fill:#CCCCFF
 ```
 
 ## Member functions

docs/mkdocs/docs/api/basic_json/out_of_range.md

@@ -9,26 +9,36 @@ instance in case of array indices or nonexisting object keys.
 
 Exceptions have ids 4xx (see [list of out-of-range errors](../../home/exceptions.md#out-of-range)).
 
-```plantuml
-std::exception <|-- basic_json::exception
-basic_json::exception <|-- basic_json::parse_error
-basic_json::exception <|-- basic_json::invalid_iterator
-basic_json::exception <|-- basic_json::type_error
-basic_json::exception <|-- basic_json::out_of_range
-basic_json::exception <|-- basic_json::other_error
+```mermaid
+classDiagram
+  direction LR
+  
+    class std_exception ["std::exception"] {
+        <<interface>>
+    }
 
-interface std::exception {}
+    class json_exception ["basic_json::exception"] {
+        +const int id
+        +const char* what() const
+    }
+    
+    class json_parse_error ["basic_json::parse_error"] {
+        +const std::size_t byte
+    }
 
-class basic_json::exception {
-    + const int id
-    + const char* what() const
-}
+    class json_invalid_iterator ["basic_json::invalid_iterator"]
+    class json_type_error ["basic_json::type_error"]
+    class json_out_of_range ["basic_json::out_of_range"]
+    class json_other_error ["basic_json::other_error"]
 
-class basic_json::parse_error {
-    + const std::size_t byte
-}
+    std_exception <|-- json_exception
+    json_exception <|-- json_parse_error
+    json_exception <|-- json_invalid_iterator
+    json_exception <|-- json_type_error
+    json_exception <|-- json_out_of_range
+    json_exception <|-- json_other_error
 
-class basic_json::out_of_range #FFFF00 {}
+    style json_out_of_range fill:#CCCCFF
 ```
 
 ## Member functions

docs/mkdocs/docs/api/basic_json/parse.md

@@ -28,9 +28,9 @@ static basic_json parse(IteratorType first, IteratorType last,
 :   A compatible input, for instance:
     
     - an `std::istream` object
-    - a `FILE` pointer (must not be null)
+    - a `FILE` pointer (throws if null)
     - a C-style array of characters
-    - a pointer to a null-terminated string of single byte characters
+    - a pointer to a null-terminated string of single byte characters (throws if null)
     - a `std::string`
     - an object `obj` for which `begin(obj)` and `end(obj)` produces a valid pair of iterators.
 
@@ -73,10 +73,11 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 
 ## Exceptions
 
-- Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token.
-- Throws [`parse_error.102`](../../home/exceptions.md#jsonexceptionparse_error102) if to_unicode fails or surrogate
+- Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token, or
+  empty input like a null `FILE*` or `char*` pointer.
+- Throws [`parse_error.102`](../../home/exceptions.md#jsonexceptionparse_error102) if `to_unicode` fails or surrogate
   error.
-- Throws [`parse_error.103`](../../home/exceptions.md#jsonexceptionparse_error103) if to_unicode fails.
+- Throws [`parse_error.103`](../../home/exceptions.md#jsonexceptionparse_error103) if `to_unicode` fails.
 
 ## Complexity
 
@@ -86,12 +87,7 @@ super-linear complexity.
 
 ## Notes
 
-(1) A UTF-8 byte order mark is silently ignored.
-
-!!! danger "Runtime assertion"
-
-    The precondition that a passed `#!cpp FILE` pointer must not be null is enforced with a
-    [runtime assertion](../../features/assertions.md).
+A UTF-8 byte order mark is silently ignored.
 
 ## Examples
 
@@ -203,6 +199,7 @@ super-linear complexity.
 - Added in version 1.0.0.
 - Overload for contiguous containers (1) added in version 2.0.3.
 - Ignoring comments via `ignore_comments` added in version 3.9.0.
+- Changed [runtime assertion](../../features/assertions.md) in case of `FILE*` null pointers to exception in version 3.11.4.
 
 !!! warning "Deprecation"
 

docs/mkdocs/docs/api/basic_json/parse_error.md

@@ -11,24 +11,36 @@ Member `byte` holds the byte index of the last read character in the input file
 
 Exceptions have ids 1xx (see [list of parse errors](../../home/exceptions.md#parse-errors)).
 
-```plantuml
-std::exception <|-- basic_json::exception
-basic_json::exception <|-- basic_json::parse_error
-basic_json::exception <|-- basic_json::invalid_iterator
-basic_json::exception <|-- basic_json::type_error
-basic_json::exception <|-- basic_json::out_of_range
-basic_json::exception <|-- basic_json::other_error
+```mermaid
+classDiagram
+  direction LR
+  
+    class std_exception ["std::exception"] {
+        <<interface>>
+    }
 
-interface std::exception {}
+    class json_exception ["basic_json::exception"] {
+        +const int id
+        +const char* what() const
+    }
+    
+    class json_parse_error ["basic_json::parse_error"] {
+        +const std::size_t byte
+    }
 
-class basic_json::exception {
-    + const int id
-    + const char* what() const
-}
+    class json_invalid_iterator ["basic_json::invalid_iterator"]
+    class json_type_error ["basic_json::type_error"]
+    class json_out_of_range ["basic_json::out_of_range"]
+    class json_other_error ["basic_json::other_error"]
 
-class basic_json::parse_error #FFFF00 {
-    + const std::size_t byte
-}
+    std_exception <|-- json_exception
+    json_exception <|-- json_parse_error
+    json_exception <|-- json_invalid_iterator
+    json_exception <|-- json_type_error
+    json_exception <|-- json_out_of_range
+    json_exception <|-- json_other_error
+
+    style json_parse_error fill:#CCCCFF
 ```
 
 ## Member functions

docs/mkdocs/docs/api/basic_json/push_back.md

@@ -27,6 +27,15 @@ void push_back(initializer_list_t init);
     `init` is converted into an object element and added using `push_back(const typename object_t::value_type&)`.
     Otherwise, `init` is converted to a JSON value and added using `push_back(basic_json&&)`.
 
+## Iterator invalidation
+
+For all cases where an element is added to an **array**, a reallocation can happen, in which case all iterators (including
+the [`end()`](end.md) iterator) and all references to the elements are invalidated. Otherwise, only the
+[`end()`](end.md) iterator is invalidated.
+
+For [`ordered_json`](../ordered_json.md), also adding an element to an **object** can yield a reallocation which again
+invalidates all iterators and all references.
+
 ## Parameters
 
 `val` (in)
@@ -99,6 +108,11 @@ All functions can throw the following exception:
     --8<-- "examples/push_back__initializer_list.output"
     ```
 
+## See also
+
+- [emplace_back](emplace_back.md) add a value to an array
+- [operator+=](operator+=.md) add a value to an array/object
+
 ## Version history
 
 1. Since version 1.0.0.

docs/mkdocs/docs/api/basic_json/type_error.md

@@ -9,26 +9,36 @@ does not match the expected semantics.
 
 Exceptions have ids 3xx (see [list of type errors](../../home/exceptions.md#type-errors)).
 
-```plantuml
-std::exception <|-- basic_json::exception
-basic_json::exception <|-- basic_json::parse_error
-basic_json::exception <|-- basic_json::invalid_iterator
-basic_json::exception <|-- basic_json::type_error
-basic_json::exception <|-- basic_json::out_of_range
-basic_json::exception <|-- basic_json::other_error
+```mermaid
+classDiagram
+  direction LR
+  
+    class std_exception ["std::exception"] {
+        <<interface>>
+    }
 
-interface std::exception {}
+    class json_exception ["basic_json::exception"] {
+        +const int id
+        +const char* what() const
+    }
+    
+    class json_parse_error ["basic_json::parse_error"] {
+        +const std::size_t byte
+    }
 
-class basic_json::exception {
-    + const int id
-    + const char* what() const
-}
+    class json_invalid_iterator ["basic_json::invalid_iterator"]
+    class json_type_error ["basic_json::type_error"]
+    class json_out_of_range ["basic_json::out_of_range"]
+    class json_other_error ["basic_json::other_error"]
 
-class basic_json::parse_error {
-    + const std::size_t byte
-}
+    std_exception <|-- json_exception
+    json_exception <|-- json_parse_error
+    json_exception <|-- json_invalid_iterator
+    json_exception <|-- json_type_error
+    json_exception <|-- json_out_of_range
+    json_exception <|-- json_other_error
 
-class basic_json::type_error #FFFF00 {}
+    style json_type_error fill:#CCCCFF
 ```
 
 ## Member functions

docs/mkdocs/docs/api/basic_json/update.md

@@ -17,6 +17,11 @@ recursively merges objects with common keys.
 The function is motivated by Python's [dict.update](https://docs.python.org/3.6/library/stdtypes.html#dict.update)
 function.
 
+## Iterator invalidation
+
+For [`ordered_json`](../ordered_json.md), adding a value to an object can yield a reallocation, in which case all
+iterators (including the `end()` iterator) and all references to the elements are invalidated.
+
 ## Parameters
 
 `j` (in)