From 00a26cf09c64c86255114472015f3b5f59394063 Mon Sep 17 00:00:00 2001 From: 0xshubh4m Date: Fri, 13 Nov 2026 21:41:29 +0530 Subject: [PATCH] docs: correct erase() empty-range and initializer-list move documentation erase(first, last) on a primitive value only accepts [begin(); end()); the empty ranges [begin(); begin()) and [end(); end()) throw invalid_iterator.204, and the exceptions list now says "or" like the code does. The strong guarantee of json::object() and the initializer-list constructor does not cover values moved into the initializer list, which are moved before the constructor runs. Part of #6114 Signed-off-by: 0xshubh4m --- 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 c029f519c2e..48c89dd200a 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 68eccc5a379..728ba4ace4d 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 53d969e5608..2378910d840 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