deploy: 54f6b3ef06

api/basic_json/at.md

@@ -90,7 +90,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
 1. Constant.
 2. Logarithmic in the size of the container.
 3. Logarithmic in the size of the container.
-4. Logarithmic in the size of the container.
+4. Linear in the number of reference tokens of `ptr`; for each of them, logarithmic in the size of the object, or
+   constant for an array.
 
 ## Notes
 

api/basic_json/at/index.md

@@ -71,7 +71,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
 1. Constant.
 1. Logarithmic in the size of the container.
 1. Logarithmic in the size of the container.
-1. Logarithmic in the size of the container.
+1. Linear in the number of reference tokens of `ptr`; for each of them, logarithmic in the size of the object, or constant for an array.
 
 ## Notes
 

api/basic_json/diff.md

@@ -19,9 +19,10 @@ The equality holds up to [`operator==`](operator_eq.md), so it has the following
 - A value that is not equal to itself cannot round-trip. This applies to `NaN` (also nested in an array or object) and
   to [discarded](is_discarded.md) values: `diff` emits a `replace` operation for them. A `NaN` in the patch is
   serialized as `#!json null`, so a patch that was dumped and parsed again would set `#!json null`.
-- Numbers that compare equal produce no operation, even if their types or signs differ: `diff(1, 1.0)`,
-  `diff(1u, 1)` (unsigned and signed integer) and `diff(0.0, -0.0)` all return `#!json []`. The patched value is then
-  the `source` and keeps its number type.
+- Numbers that compare equal produce no operation, even if their types differ or if one is zero and the other is
+  negative zero: `diff(1, 1.0)` (integer and floating-point), `diff(1u, 1)` (unsigned and signed integer) and
+  `diff(0.0, -0.0)` (positive and negative zero) all return `#!json []`. The patched value is then the `source` and
+  keeps its number type and sign.
 
 ## Parameters
 

api/basic_json/diff/index.md

@@ -17,7 +17,7 @@ source.patch(diff(source, target)) == target;
 The equality holds up to [`operator==`](https://json.nlohmann.me/api/basic_json/operator_eq/index.md), so it has the following exceptions:
 
 - A value that is not equal to itself cannot round-trip. This applies to `NaN` (also nested in an array or object) and to [discarded](https://json.nlohmann.me/api/basic_json/is_discarded/index.md) values: `diff` emits a `replace` operation for them. A `NaN` in the patch is serialized as `null`, so a patch that was dumped and parsed again would set `null`.
-- Numbers that compare equal produce no operation, even if their types or signs differ: `diff(1, 1.0)`, `diff(1u, 1)` (unsigned and signed integer) and `diff(0.0, -0.0)` all return `[]`. The patched value is then the `source` and keeps its number type.
+- Numbers that compare equal produce no operation, even if their types differ or if one is zero and the other is negative zero: `diff(1, 1.0)` (integer and floating-point), `diff(1u, 1)` (unsigned and signed integer) and `diff(0.0, -0.0)` (positive and negative zero) all return `[]`. The patched value is then the `source` and keeps its number type and sign.
 
 ## Parameters
 

api/basic_json/operator%5B%5D.md

@@ -92,12 +92,20 @@ Strong exception safety: if an exception occurs, the original value stays intact
     For the **const** version, an object key or array index in `ptr` that does not exist is not reported by an
     exception, but is undefined behavior (see the notes below). Use [`at`](at.md) for checked access.
 
+    If the **non-const** version throws, the value is left unchanged: values it created for earlier reference tokens
+    of `ptr` are removed again. This also holds for exceptions such as `#!cpp std::bad_alloc` or
+    `#!cpp std::length_error` thrown while padding an array up to a very large index. With custom
+    [template parameters](../../features/types/template_parameters.md), this requires that `erase()` of the object and
+    array types and the move operations of the custom base class do not throw.
+
 ## Complexity
 
 1. Constant if `idx` is in the range of the array. Otherwise, linear in `idx - size()`.
 2. Logarithmic in the size of the container.
 3. Logarithmic in the size of the container.
-4. Logarithmic in the size of the container.
+4. Linear in the number of reference tokens of `ptr`; for each of them, logarithmic in the size of the object, or
+   constant for an array. When the non-const version pads an array with `#!json null` values, it is additionally
+   linear in `idx - size()` for that array.
 
 ## Notes
 
@@ -145,6 +153,14 @@ Strong exception safety: if an exception occurs, the original value stays intact
         specified by the JSON Pointer RFC; it is this library's own, intentional disambiguation rule. See also
         [JSON Pointer](../../features/json_pointer.md).
 
+    !!! warning "Large array indices"
+
+        As the array is filled up with `#!json null` values to the given index, the memory used grows with the index
+        and not with the size of the pointer: on a 64-bit platform, the index `10000000` allocates about 160 MB.
+        The library does not limit the index, so check the array indices of a JSON pointer from untrusted input
+        before using it with the non-const version. See
+        [Parsing untrusted input](../../features/parsing/untrusted_input.md#json-pointers-and-flattened-keys).
+
 !!! warning "Deprecation"
 
     Overload (4) also accepts a [`json_pointer`](../json_pointer/index.md) whose template argument is a `basic_json`
@@ -564,4 +580,6 @@ Strong exception safety: if an exception occurs, the original value stays intact
 4. Added in version 2.0.0. A missing array index in the const version is guarded by a runtime assertion since
    version 3.13.0. Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) instead of
 [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) for a one-character array index that is not
-a digit (e.g., `/x`) in version 3.13.0, as it already did for longer ones.
+a digit (e.g., `/x`) in version 3.13.0, as it already did for longer ones. Fixed in version 3.13.0 to leave the value
+unchanged if the non-const version throws (strong exception safety, as documented); before, values created for earlier
+reference tokens of `ptr` were kept.

api/basic_json/operator[]/index.md

@@ -77,12 +77,14 @@ Strong exception safety: if an exception occurs, the original value stays intact
 
    For the **const** version, an object key or array index in `ptr` that does not exist is not reported by an exception, but is undefined behavior (see the notes below). Use [`at`](https://json.nlohmann.me/api/basic_json/at/index.md) for checked access.
 
+   If the **non-const** version throws, the value is left unchanged: values it created for earlier reference tokens of `ptr` are removed again. This also holds for exceptions such as `std::bad_alloc` or `std::length_error` thrown while padding an array up to a very large index. With custom [template parameters](https://json.nlohmann.me/features/types/template_parameters/index.md), this requires that `erase()` of the object and array types and the move operations of the custom base class do not throw.
+
 ## Complexity
 
 1. Constant if `idx` is in the range of the array. Otherwise, linear in `idx - size()`.
 1. Logarithmic in the size of the container.
 1. Logarithmic in the size of the container.
-1. Logarithmic in the size of the container.
+1. Linear in the number of reference tokens of `ptr`; for each of them, logarithmic in the size of the object, or constant for an array. When the non-const version pads an array with `null` values, it is additionally linear in `idx - size()` for that array.
 
 ## Notes
 
@@ -114,6 +116,10 @@ The following cases apply to the **const** overloads; the non-const overloads in
 
    When the JSON pointer traverses intermediate levels that don't exist at all yet (not just a missing leaf), each missing level is created as an array or an object depending on whether the corresponding pointer token is a valid array index: the token `0`, a sequence of digits that does not begin with `0`, or the token `-` creates an array, and every other token creates an object. For example, on an initially `null` value, `/foo/0/0/0` creates nested arrays, while `/foo/one/one/one` creates nested objects. Tokens such as `01` or the empty token cannot be array indices (cf. RFC 6901, Sect. 4) and therefore create objects, just as they would if the level already existed as an object. This is not specified by the JSON Pointer RFC; it is this library's own, intentional disambiguation rule. See also [JSON Pointer](https://json.nlohmann.me/features/json_pointer/index.md).
 
+   Large array indices
+
+   As the array is filled up with `null` values to the given index, the memory used grows with the index and not with the size of the pointer: on a 64-bit platform, the index `10000000` allocates about 160 MB. The library does not limit the index, so check the array indices of a JSON pointer from untrusted input before using it with the non-const version. See [Parsing untrusted input](https://json.nlohmann.me/features/parsing/untrusted_input/#json-pointers-and-flattened-keys).
+
 Deprecation
 
 Overload (4) also accepts a [`json_pointer`](https://json.nlohmann.me/api/json_pointer/index.md) whose template argument is a `basic_json` specialization (e.g., `nlohmann::json_pointer<nlohmann::json>`) instead of a string type. This is deprecated since version 3.11.0 and will be removed in a future major version; use `basic_json::json_pointer` (for `json`, `nlohmann::json_pointer<std::string>`) instead.
@@ -503,4 +509,4 @@ Output:
 1. Added in version 1.0.0. Fixed in version 3.13.0 unreleased to throw `std::length_error` instead of emptying the array and accessing it out of bounds when `idx` equals the maximum value of `size_type`. A missing index in the const version is guarded by a runtime assertion since version 3.13.0 unreleased.
 1. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. The `T* key` overloads forward to overload 3 since version 3.11.0.
 1. Added in version 3.11.0. Support for keys convertible to `std::string_view` added in version 3.13.0 unreleased, consistently across the lookup functions.
-1. Added in version 2.0.0. A missing array index in the const version is guarded by a runtime assertion since version 3.13.0 unreleased. Throws [`parse_error.109`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error109) instead of [`out_of_range.404`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range404) for a one-character array index that is not a digit (e.g., `/x`) in version 3.13.0 unreleased, as it already did for longer ones.
+1. Added in version 2.0.0. A missing array index in the const version is guarded by a runtime assertion since version 3.13.0 unreleased. Throws [`parse_error.109`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error109) instead of [`out_of_range.404`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range404) for a one-character array index that is not a digit (e.g., `/x`) in version 3.13.0 unreleased, as it already did for longer ones. Fixed in version 3.13.0 unreleased to leave the value unchanged if the non-const version throws (strong exception safety, as documented); before, values created for earlier reference tokens of `ptr` were kept.

api/basic_json/patch_inplace.md

@@ -69,6 +69,19 @@ Duplicate member names inside an operation object are resolved by the parser bef
 is kept, see [`object_t`](object_t.md#behavior)), so `#!json {"op": "add", "op": "remove", "path": "/a"}` is a
 `remove` operation.
 
+The JSON patch may be the JSON value itself (`#!cpp j.patch_inplace(j)`): the operations are then read from a copy of
+the patch made before the first operation is applied, so the result is the same as that of
+`#!cpp j = j.patch(j)`, and the exception safety is the same as above.
+
+If [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) is enabled, the same holds for a JSON patch stored inside the
+JSON value (e.g., `#!cpp j.patch_inplace(j["patch"])`): it is detected via the parent pointers.
+
+!!! danger "Undefined behavior"
+
+    Without [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md), the JSON patch must not be a value stored inside the
+    JSON value (e.g., `#!cpp j.patch_inplace(j["patch"])`), as the operations may change or destroy it while it is
+    read. Pass a copy (`#!cpp j.patch_inplace(json(j["patch"]))`) or use [`patch`](patch.md) instead.
+
 ## Examples
 
 ??? example "Example: apply a JSON patch in place"
@@ -213,3 +226,5 @@ is kept, see [`object_t`](object_t.md#behavior)), so `#!json {"op": "add", "op":
 - Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) instead of
   [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) for a one-character array index that is
   not a digit (e.g., `/x`) in version 3.13.0, as it already did for longer ones.
+- Applying a JSON value as patch to itself (or, with `JSON_DIAGNOSTICS`, to a value stored inside it) no longer results
+  in undefined behavior in version 3.13.0.

api/basic_json/patch_inplace/index.md

@@ -42,6 +42,14 @@ Unlike [`patch`](https://json.nlohmann.me/api/basic_json/patch/index.md), `patch
 
 Duplicate member names inside an operation object are resolved by the parser before the patch is applied (the last one is kept, see [`object_t`](https://json.nlohmann.me/api/basic_json/object_t/#behavior)), so `{"op": "add", "op": "remove", "path": "/a"}` is a `remove` operation.
 
+The JSON patch may be the JSON value itself (`j.patch_inplace(j)`): the operations are then read from a copy of the patch made before the first operation is applied, so the result is the same as that of `j = j.patch(j)`, and the exception safety is the same as above.
+
+If [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) is enabled, the same holds for a JSON patch stored inside the JSON value (e.g., `j.patch_inplace(j["patch"])`): it is detected via the parent pointers.
+
+Undefined behavior
+
+Without [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md), the JSON patch must not be a value stored inside the JSON value (e.g., `j.patch_inplace(j["patch"])`), as the operations may change or destroy it while it is read. Pass a copy (`j.patch_inplace(json(j["patch"]))`) or use [`patch`](https://json.nlohmann.me/api/basic_json/patch/index.md) instead.
+
 ## Examples
 
 Example: apply a JSON patch in place
@@ -174,3 +182,4 @@ Output:
 - Added [`out_of_range.413`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range413) and stopped silently ignoring a "remove" operation whose target location has a non-object/non-array parent in version 3.13.0 unreleased.
 - Added [`out_of_range.414`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range414) and rejected a "move" operation whose "from" location is a proper prefix of its "path" location instead of silently producing a corrupted result in version 3.13.0 unreleased.
 - Throws [`parse_error.109`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error109) instead of [`out_of_range.404`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range404) for a one-character array index that is not a digit (e.g., `/x`) in version 3.13.0 unreleased, as it already did for longer ones.
+- Applying a JSON value as patch to itself (or, with `JSON_DIAGNOSTICS`, to a value stored inside it) no longer results in undefined behavior in version 3.13.0 unreleased.