mirror of
https://github.com/nlohmann/json.git
synced 2026-10-04 21:50:33 +00:00
Review and extend the documentation, and check it in CI (#5638)
* Review and extend the documentation, and check it in CI A review of all documentation pages found factual errors, dead links, missing cross-references, and gaps in examples. This fixes them and adds checks so the same problems are caught automatically. Fixes: - wrong signatures and version histories (operator!= C++20 member, binary() subtype type, get<PointerType>(), JSON_NO_THREAD_LOCAL, ...) - stale descriptions (number parsing since #5283, UBJSON table, SAX example that no longer compiled, tsl::ordered_map advice) - dead internal and external links; repology.org badges (the domain is suspended) replaced by badges that query the registries directly - deprecation notes link the migration guide; the guide itself fixed Additions: - "See also" sections, cross-references, 25 runnable examples, 12 Mermaid diagrams, new API pages for json_pointer::operator<=> and byte_container_with_subtype::operator==/!= - landing page, guides for untrusted input and performance - "unreleased" badge after versions newer than the latest release Checks: - strict documentation build (broken links/anchors fail it); CI and the publish workflow fetch the full history the build needs - weekly external link check, Mermaid syntax check in CI - check_structure.py: example titles, heading levels, alt texts, header links, docset index coverage; its unused-example check works again - all examples produce the same output on every platform Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Keep the customer links that could not be fixed A dead link on the customers page is still the evidence of where the use of the library was documented. Keep the original URLs of the entries without a working replacement (Marne, Cisco Webex Desk Camera, Philips Hue, CyberArk) and exclude exactly these URLs from the link check. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Correct the duplicate-key recipe's claim about SAX positions The SAX interface's key() receives no position either; only parse_error() does. Also note that the recipe does not report the path to the repeated key (see discussion #5085). Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Say the library is available as a single header and mention json_fwd.hpp Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Correct documentation errors found while hunting for bugs - patch/patch_inplace: list the JSON pointer errors parse_error.106-109 and out_of_range.402/404, and quote the actual parse_error.105 message. - unflatten: list parse_error.106/107/108 and out_of_range.404. - to_bson: list out_of_range.415 (binary subtype above 255) and note that 412 and 415 are new in 3.13.0. - to_string: state that string_t must be convertible to std::string, also in the StringType requirements table. - JSON Lines: a `while (input >> j)` loop also throws after the last value for concatenated JSON values; show a loop that works for both. - BON8: a string gets 0xFF only if nothing follows it in the message; a string at the end of an array or object is ended by 0xFE. - custom_string_type.hpp: add operator+=(char), which the "Always required" list asks for (json_pointer::to_string, flatten, unflatten, and diff did not compile), and an ADL int_to_string for diff and items. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Cache the release headers with functools.lru_cache Codacy (Pylint) flagged the mutable default argument that header() used as its cache. functools.lru_cache keeps the same memoization without it. The script's output is unchanged. Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This commit is contained in:
Niels Lohmann
@@ -10,6 +10,10 @@ Return the last reference token.
|
||||
|
||||
Last reference token.
|
||||
|
||||
## Exception safety
|
||||
|
||||
Strong exception safety: if an exception occurs, the original value stays intact.
|
||||
|
||||
## Exceptions
|
||||
|
||||
Throws [out_of_range.405](../../home/exceptions.md#jsonexceptionout_of_range405) if the JSON pointer has no parent.
|
||||
@@ -34,6 +38,13 @@ Constant.
|
||||
--8<-- "examples/json_pointer__back.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [front](front.md) return first reference token
|
||||
- [pop_back](pop_back.md) remove the last reference token
|
||||
- [push_back](push_back.md) append an unescaped token at the end of the pointer
|
||||
- [parent_pointer](parent_pointer.md) returns the parent of this JSON pointer
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.6.0.
|
||||
|
||||
@@ -34,6 +34,12 @@ Constant.
|
||||
--8<-- "examples/json_pointer__empty.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [front](front.md) return first reference token
|
||||
- [back](back.md) return last reference token
|
||||
- [to_string](to_string.md) return a string representation of the JSON pointer
|
||||
|
||||
## Version history
|
||||
|
||||
Added in version 3.6.0.
|
||||
|
||||
@@ -10,6 +10,10 @@ Return the first reference token.
|
||||
|
||||
First reference token.
|
||||
|
||||
## Exception safety
|
||||
|
||||
Strong exception safety: if an exception occurs, the original value stays intact.
|
||||
|
||||
## Exceptions
|
||||
|
||||
Throws [out_of_range.405](../../home/exceptions.md#jsonexceptionout_of_range405) if the JSON pointer has no parent.
|
||||
@@ -34,6 +38,12 @@ Constant.
|
||||
--8<-- "examples/json_pointer__front.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [back](back.md) return last reference token
|
||||
- [pop_front](pop_front.md) remove the first reference token
|
||||
- [push_front](push_front.md) append an unescaped token at the start of the pointer
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
|
||||
@@ -20,6 +20,24 @@ are the base for JSON patches.
|
||||
in which case `string_t` will be deduced as [`basic_json::string_t`](../basic_json/string_t.md). This feature is
|
||||
deprecated and may be removed in a future major version.
|
||||
|
||||
See the [migration guide](../../integration/migration_guide.md#json-pointers) for how to update existing code.
|
||||
|
||||
A JSON pointer is internally a sequence of reference tokens. [`front`](front.md), [`pop_front`](pop_front.md), and
|
||||
[`push_front`](push_front.md) act on the first reference token, whereas [`back`](back.md), [`pop_back`](pop_back.md),
|
||||
and [`push_back`](push_back.md) act on the last one. [`parent_pointer`](parent_pointer.md) returns a new JSON pointer
|
||||
with the last reference token removed (like a non-mutating [`pop_back`](pop_back.md)):
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["a"] --> B["b"] --> C["c"]
|
||||
|
||||
front["front() / pop_front() / push_front()"] -.-> A
|
||||
back["back() / pop_back() / push_back()"] -.-> C
|
||||
parent["parent_pointer() returns /a/b"] -.-> B
|
||||
```
|
||||
|
||||
The diagram shows the reference tokens of the JSON pointer `/a/b/c`.
|
||||
|
||||
## Member types
|
||||
|
||||
- [**string_t**](string_t.md) - the string type used for the reference tokens
|
||||
@@ -28,9 +46,10 @@ are the base for JSON patches.
|
||||
|
||||
- [(constructor)](json_pointer.md)
|
||||
- [**to_string**](to_string.md) - return a string representation of the JSON pointer
|
||||
- [**operator string_t**](operator_string_t.md) - return a string representation of the JSON pointer
|
||||
- [**operator string_t**](operator_string_t.md) - return a string representation of the JSON pointer (deprecated)
|
||||
- [**operator==**](operator_eq.md) - compare: equal
|
||||
- [**operator!=**](operator_ne.md) - compare: not equal
|
||||
- [**operator<=>**](operator_spaceship.md) - compare: 3-way (C++20)
|
||||
- [**operator/=**](operator_slasheq.md) - append to the end of the JSON pointer
|
||||
- [**operator/**](operator_slash.md) - create JSON Pointer by appending
|
||||
- [**parent_pointer**](parent_pointer.md) - returns the parent of this JSON pointer
|
||||
@@ -45,6 +64,7 @@ are the base for JSON patches.
|
||||
## Literals
|
||||
|
||||
- [**operator""_json_pointer**](../operator_literal_json_pointer.md) - user-defined string literal for JSON pointers
|
||||
|
||||
## See also
|
||||
|
||||
- [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901)
|
||||
|
||||
@@ -12,6 +12,10 @@ Create a JSON pointer according to the syntax described in
|
||||
`s` (in)
|
||||
: string representing the JSON pointer; if omitted, the empty string is assumed which references the whole JSON value
|
||||
|
||||
## Exception safety
|
||||
|
||||
Strong guarantee: if an exception is thrown, there are no changes to any JSON pointer.
|
||||
|
||||
## Exceptions
|
||||
|
||||
- Throws [parse_error.107](../../home/exceptions.md#jsonexceptionparse_error107) if the given JSON pointer `s` is
|
||||
@@ -19,6 +23,10 @@ Create a JSON pointer according to the syntax described in
|
||||
- Throws [parse_error.108](../../home/exceptions.md#jsonexceptionparse_error108) if a tilde (`~`) in the given JSON
|
||||
pointer `s` is not followed by `0` (representing `~`) or `1` (representing `/`); see example below.
|
||||
|
||||
## Complexity
|
||||
|
||||
Linear in the length of `s`.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
@@ -35,6 +43,11 @@ Create a JSON pointer according to the syntax described in
|
||||
--8<-- "examples/json_pointer.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [JSON Pointer](../../features/json_pointer.md) - the article on JSON Pointer support
|
||||
- [operator""_json_pointer](../operator_literal_json_pointer.md) user-defined string literal for JSON pointers
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 2.0.0.
|
||||
|
||||
@@ -77,6 +77,8 @@ tokens.
|
||||
|
||||
Overload 2 is deprecated and will be removed in a future major version release.
|
||||
|
||||
See the [migration guide](../../integration/migration_guide.md#json-pointers) for how to update existing code.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example "Example: (1) Comparing JSON pointers"
|
||||
@@ -107,6 +109,11 @@ tokens.
|
||||
--8<-- "examples/json_pointer__operator__equal_stringtype.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [operator!=](operator_ne.md) compare for inequality
|
||||
- [operator<=>](operator_spaceship.md) comparison: 3-way (C++20)
|
||||
|
||||
## Version history
|
||||
|
||||
1. Added in version 2.1.0. Added C++20 member functions in version 3.11.2.
|
||||
|
||||
@@ -73,6 +73,8 @@ tokens.
|
||||
|
||||
Overload 2 is deprecated and will be removed in a future major version release.
|
||||
|
||||
See the [migration guide](../../integration/migration_guide.md#json-pointers) for how to update existing code.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example "Example: (1) Comparing JSON pointers"
|
||||
@@ -103,6 +105,11 @@ tokens.
|
||||
--8<-- "examples/json_pointer__operator__notequal_stringtype.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [operator==](operator_eq.md) compare for equality
|
||||
- [operator<=>](operator_spaceship.md) comparison: 3-way (C++20)
|
||||
|
||||
## Version history
|
||||
|
||||
1. Added in version 2.1.0.
|
||||
|
||||
@@ -35,6 +35,11 @@ json_pointer operator/(const json_pointer& lhs, std::size_t array_idx);
|
||||
2. a new JSON pointer with unescaped `token` appended to `lhs`
|
||||
3. a new JSON pointer with `array_idx` appended to `lhs`
|
||||
|
||||
## Exception safety
|
||||
|
||||
Strong guarantee: if an exception is thrown, there are no changes to any JSON pointer. The operands are not modified;
|
||||
a new JSON pointer is built from a copy of `lhs`.
|
||||
|
||||
## Complexity
|
||||
|
||||
1. Linear in the length of `lhs` and `rhs`.
|
||||
@@ -57,6 +62,11 @@ json_pointer operator/(const json_pointer& lhs, std::size_t array_idx);
|
||||
--8<-- "examples/json_pointer__operator_add_binary.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [operator/=](operator_slasheq.md) append to the end of the JSON pointer
|
||||
- [push_back](push_back.md) append an unescaped token at the end of the pointer
|
||||
|
||||
## Version history
|
||||
|
||||
1. Added in version 3.6.0.
|
||||
|
||||
@@ -32,6 +32,13 @@ json_pointer& operator/=(std::size_t array_idx)
|
||||
2. JSON pointer with `token` appended without escaping `token`
|
||||
3. JSON pointer with `array_idx` appended
|
||||
|
||||
## Exception safety
|
||||
|
||||
1. Basic guarantee: if an exception is thrown (for instance, if copying a reference token fails), the JSON pointer is
|
||||
left in a valid state, but it may contain some of the reference tokens of `ptr`.
|
||||
2. Strong guarantee: if an exception is thrown, there are no changes to the JSON pointer.
|
||||
3. Strong guarantee: if an exception is thrown, there are no changes to the JSON pointer.
|
||||
|
||||
## Complexity
|
||||
|
||||
1. Linear in the length of `ptr`.
|
||||
@@ -54,6 +61,11 @@ json_pointer& operator/=(std::size_t array_idx)
|
||||
--8<-- "examples/json_pointer__operator_add.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [operator/](operator_slash.md) create JSON Pointer by appending
|
||||
- [push_back](push_back.md) append an unescaped token at the end of the pointer
|
||||
|
||||
## Version history
|
||||
|
||||
1. Added in version 3.6.0.
|
||||
|
||||
@@ -0,0 +1,74 @@
|
||||
# <small>nlohmann::json_pointer::</small>operator<=>
|
||||
|
||||
```cpp
|
||||
// since C++20
|
||||
class json_pointer {
|
||||
template<typename RefStringTypeRhs>
|
||||
std::strong_ordering operator<=>(const json_pointer<RefStringTypeRhs>& rhs) const noexcept; // *NOPAD*
|
||||
};
|
||||
```
|
||||
|
||||
3-way compares two JSON pointers by lexicographically comparing their sequences of reference tokens: corresponding
|
||||
reference tokens are compared with `string_t`'s own `operator<=>`, and the first pair of tokens that differs
|
||||
determines the result. If all corresponding reference tokens compare equal, the JSON pointer with fewer reference
|
||||
tokens is ordered first.
|
||||
|
||||
## Template parameters
|
||||
|
||||
`RefStringTypeRhs`
|
||||
: the string type of the right-hand side JSON pointer
|
||||
|
||||
## Parameters
|
||||
|
||||
`rhs` (in)
|
||||
: JSON pointer to compare `*this` with
|
||||
|
||||
## Return value
|
||||
|
||||
the `std::strong_ordering` of the 3-way comparison of `*this` and `rhs`
|
||||
|
||||
## Exception safety
|
||||
|
||||
No-throw guarantee: this function never throws exceptions.
|
||||
|
||||
## Complexity
|
||||
|
||||
Linear in the number of reference tokens.
|
||||
|
||||
## Notes
|
||||
|
||||
!!! note "Ordering enables use as an associative container key"
|
||||
|
||||
Together with [`operator==`](operator_eq.md), `operator<=>` makes `json_pointer` a `LessThanComparable` type, so
|
||||
it can be used as the key type of ordered associative containers such as `std::map` or `std::set`.
|
||||
|
||||
!!! note "Before C++20"
|
||||
|
||||
Without C++20's three-way comparison, `json_pointer` provides a non-member `operator<` instead, which orders JSON
|
||||
pointers the same way. JSON pointers can therefore be used as keys of ordered associative containers with any
|
||||
supported C++ standard.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example demonstrates 3-way comparing JSON pointers.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/json_pointer__operator_spaceship.c++20.cpp"
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
--8<-- "examples/json_pointer__operator_spaceship.c++20.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [operator==](operator_eq.md) compare: equal
|
||||
- [operator!=](operator_ne.md) compare: not equal
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.11.2.
|
||||
@@ -26,6 +26,8 @@ operator string_t() const
|
||||
This function is deprecated in favor of [`to_string`](to_string.md) and will be removed in a future major version
|
||||
release.
|
||||
|
||||
See the [migration guide](../../integration/migration_guide.md#json-pointers) for how to update existing code.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
@@ -44,7 +46,8 @@ operator string_t() const
|
||||
|
||||
## See also
|
||||
|
||||
- [string_t](../basic_json/string_t.md)- type for strings
|
||||
- [to_string](to_string.md) return a string representation of the JSON pointer
|
||||
- [string_t](../basic_json/string_t.md) - type for strings
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -6,6 +6,10 @@ void pop_back();
|
||||
|
||||
Remove the last reference token.
|
||||
|
||||
## Exception safety
|
||||
|
||||
Strong exception safety: if an exception occurs, the original value stays intact.
|
||||
|
||||
## Exceptions
|
||||
|
||||
Throws [out_of_range.405](../../home/exceptions.md#jsonexceptionout_of_range405) if the JSON pointer has no parent.
|
||||
@@ -30,6 +34,12 @@ Constant.
|
||||
--8<-- "examples/json_pointer__pop_back.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [back](back.md) return last reference token
|
||||
- [push_back](push_back.md) append an unescaped token at the end of the pointer
|
||||
- [parent_pointer](parent_pointer.md) returns the parent of this JSON pointer
|
||||
|
||||
## Version history
|
||||
|
||||
Added in version 3.6.0.
|
||||
|
||||
@@ -6,6 +6,10 @@ void pop_front();
|
||||
|
||||
Remove the first reference token.
|
||||
|
||||
## Exception safety
|
||||
|
||||
Strong exception safety: if an exception occurs, the original value stays intact.
|
||||
|
||||
## Exceptions
|
||||
|
||||
Throws [out_of_range.405](../../home/exceptions.md#jsonexceptionout_of_range405) if the JSON pointer has no parent.
|
||||
@@ -30,6 +34,11 @@ Linear in the number of reference tokens in the `json_pointer`.
|
||||
--8<-- "examples/json_pointer__pop_front.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [front](front.md) return first reference token
|
||||
- [push_front](push_front.md) append an unescaped token at the start of the pointer
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
|
||||
@@ -13,6 +13,10 @@ Append an unescaped token at the end of the reference pointer.
|
||||
`token` (in)
|
||||
: token to add
|
||||
|
||||
## Exception safety
|
||||
|
||||
Strong exception safety: if an exception occurs, the original value stays intact.
|
||||
|
||||
## Complexity
|
||||
|
||||
Amortized constant.
|
||||
@@ -33,6 +37,13 @@ Amortized constant.
|
||||
--8<-- "examples/json_pointer__push_back.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [back](back.md) return last reference token
|
||||
- [pop_back](pop_back.md) remove the last reference token
|
||||
- [operator/=](operator_slasheq.md) append to the end of the JSON pointer
|
||||
- [operator/](operator_slash.md) create JSON Pointer by appending
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.6.0.
|
||||
|
||||
@@ -13,6 +13,11 @@ Append an unescaped token at the start of the reference pointer.
|
||||
`token` (in)
|
||||
: token to add
|
||||
|
||||
## Exception safety
|
||||
|
||||
Basic guarantee: if an exception is thrown (for instance, if copying the reference token fails), the JSON pointer is
|
||||
left in a valid state, but its reference tokens may have changed.
|
||||
|
||||
## Complexity
|
||||
|
||||
Linear in the number of reference tokens in the `json_pointer`.
|
||||
@@ -33,6 +38,11 @@ Linear in the number of reference tokens in the `json_pointer`.
|
||||
--8<-- "examples/json_pointer__push_front.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [front](front.md) return first reference token
|
||||
- [pop_front](pop_front.md) remove the first reference token
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
|
||||
@@ -23,6 +23,11 @@ See [`basic_json::string_t`](../basic_json/string_t.md) for more information.
|
||||
--8<-- "examples/json_pointer__string_t.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [basic_json::string_t](../basic_json/string_t.md) type used to store JSON strings
|
||||
- [to_string](to_string.md) return a string representation of the JSON pointer
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.11.0.
|
||||
|
||||
@@ -10,6 +10,14 @@ Return a string representation of the JSON pointer.
|
||||
|
||||
A string representation of the JSON pointer
|
||||
|
||||
## Exception safety
|
||||
|
||||
Strong exception safety: if an exception occurs, the original value stays intact.
|
||||
|
||||
## Complexity
|
||||
|
||||
Linear in the total length of the reference tokens.
|
||||
|
||||
## Notes
|
||||
|
||||
For each JSON pointer `ptr`, it holds:
|
||||
@@ -34,6 +42,11 @@ ptr == json_pointer(ptr.to_string());
|
||||
--8<-- "examples/json_pointer__to_string.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [operator string_t](operator_string_t.md) return a string representation of the JSON pointer (deprecated)
|
||||
- [operator<<](../operator_ltlt.md) write a JSON pointer to a stream
|
||||
|
||||
## Version history
|
||||
|
||||
- Since version 2.0.0.
|
||||
|
||||
Reference in New Issue
Block a user