From 0ac14610d6e5f194129a50ec0dc0030a07d5681a Mon Sep 17 00:00:00 2001 From: Shubham Shakti <130799986+0xmyst3ry@users.noreply.github.com> Date: Wed, 18 Nov 2026 13:26:46 +0530 Subject: [PATCH] docs: correct erase() empty-range and initializer-list move documentation (#6122) Signed-off-by: Niels Lohmann --- docs/mkdocs/docs/api/basic_json/basic_json.md | 4 +++- docs/mkdocs/docs/api/basic_json/erase.md | 12 +++++++----- docs/mkdocs/docs/api/basic_json/object.md | 4 +++- 3 files changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/mkdocs/docs/api/basic_json/basic_json.md b/docs/mkdocs/docs/api/basic_json/basic_json.md index c029f519c..48c89dd20 100644 --- a/docs/mkdocs/docs/api/basic_json/basic_json.md +++ b/docs/mkdocs/docs/api/basic_json/basic_json.md @@ -265,7 +265,9 @@ basic_json(basic_json&& other) noexcept; 4. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no `to_json()` function was provided), a strong guarantee holds: if an exception is thrown, there are no changes to any JSON value. -5. Strong guarantee: if an exception is thrown, there are no changes to any JSON value. +5. Strong guarantee: if an exception is thrown, there are no changes to any JSON value. Values that are moved into + `init` (e.g., `a` in `#!cpp json::object({std::move(a), 5})`) are moved when the initializer list is created, + before the constructor runs, and stay moved-from if it throws. 6. Strong guarantee: if an exception is thrown, there are no changes to any JSON value. 7. Strong guarantee: if an exception is thrown, there are no changes to any JSON value. 8. Strong guarantee: if an exception is thrown, there are no changes to any JSON value. diff --git a/docs/mkdocs/docs/api/basic_json/erase.md b/docs/mkdocs/docs/api/basic_json/erase.md index 68eccc5a3..728ba4ace 100644 --- a/docs/mkdocs/docs/api/basic_json/erase.md +++ b/docs/mkdocs/docs/api/basic_json/erase.md @@ -26,10 +26,12 @@ void erase(const size_type idx); If called on a primitive type other than `#!json null`, the resulting JSON value will be `#!json null`. -2. Remove an element range specified by `[first; last)` from a JSON value. The iterator `first` does not need to be - dereferenceable if `first == last`: erasing an empty range is a no-op. +2. Remove an element range specified by `[first; last)` from a JSON value. For arrays and objects, the iterator `first` + does not need to be dereferenceable if `first == last`: erasing an empty range is a no-op. - If called on a primitive type other than `#!json null`, the resulting JSON value will be `#!json null`. + If called on a primitive type other than `#!json null`, the range must be `[begin(); end())`, and the resulting JSON + value will be `#!json null`. Any other range, including the empty ranges `[begin(); begin())` and + `[end(); end())`, throws [`invalid_iterator.204`](../../home/exceptions.md#jsonexceptioninvalid_iterator204). 3. Removes an element from a JSON object by key. @@ -93,8 +95,8 @@ Strong exception safety: if an exception occurs, the original value stays intact - Throws [`invalid_iterator.203`](../../home/exceptions.md#jsonexceptioninvalid_iterator203) if called on iterators which does not belong to the current JSON value; example: `"iterators do not fit current value"` - Throws [`invalid_iterator.204`](../../home/exceptions.md#jsonexceptioninvalid_iterator204) if called on a - primitive type with invalid iterators (i.e., if `first != begin()` and `last != end()`); example: `"iterators out - of range"` + primitive type with invalid iterators (i.e., if `first != begin()` or `last != end()`, which includes the empty + ranges `[begin(); begin())` and `[end(); end())`); example: `"iterators out of range"` 3. The function can throw the following exceptions: - Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) when called on a type other than JSON object; example: `"cannot use erase() with null"` diff --git a/docs/mkdocs/docs/api/basic_json/object.md b/docs/mkdocs/docs/api/basic_json/object.md index 53d969e56..2378910d8 100644 --- a/docs/mkdocs/docs/api/basic_json/object.md +++ b/docs/mkdocs/docs/api/basic_json/object.md @@ -18,7 +18,9 @@ JSON object value ## Exception safety -Strong guarantee: if an exception is thrown, there are no changes in the JSON value. +Strong guarantee: if an exception is thrown, there are no changes in the JSON value. Values that are moved into `init` +(e.g., `a` in `#!cpp json::object({std::move(a), 5})`) are moved when the initializer list is created, before this +function runs, and stay moved-from if it throws. ## Exceptions