amorfo77/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2026-07-11 13:05:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add iterator+sentinel tests and docs for binary deserializers

Browse Source 
This commit extends the C++20 ranges support (iterator+sentinel pairs) to the
binary format deserializers from_cbor, from_msgpack, from_ubjson, from_bjdata,
and from_bson, matching what was already done for parse(), accept(), and
sax_parse().

Changes:
- Add istreambuf_sentinel helper to test_utils.hpp for EOF detection in tests
- Add 5 new test cases that read binary files directly via
  std::istreambuf_iterator<char> + sentinel, without pre-buffering
- Update documentation for all 5 from_* functions to document overload (3)
  with SentinelType parameter
- All tests pass; verified against existing test suite data
- Fix potential buffer over-read warning in heterogeneous iterator test

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This commit is contained in:
Niels Lohmann
2026-07-10 19:43:05 +02:00
parent 6ba332c7df
commit 2269656bc6
18 changed files with 612 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/mkdocs/docs/api/basic_json/accept.md
+19 -2
View File
@@ -12,15 +12,25 @@ template<typename IteratorType>
static bool accept(IteratorType first, IteratorType last,
const bool ignore_comments = false,
const bool ignore_trailing_commas = false);
// (3)
template<typename IteratorType, typename SentinelType>
static bool accept(IteratorType first, SentinelType last,
const bool ignore_comments = false,
const bool ignore_trailing_commas = false);
```
Checks whether the input is valid JSON.
1. Reads from a compatible input.
2. Reads from a pair of character iterators
2. Reads from a pair of character iterators (same type)
The value_type of the iterator must be an integral type with a size of 1, 2, or 4 bytes, which will be interpreted
respectively as UTF-8, UTF-16, and UTF-32.
3. Reads from an iterator and a sentinel (different types, C++20 ranges support)
The value_type of the iterator must be an integral type with a size of 1, 2, or 4 bytes, which will be interpreted
respectively as UTF-8, UTF-16, and UTF-32. The sentinel type must be comparable to the iterator type with `operator!=`.
Unlike the [`parse()`](parse.md) function, this function neither throws an exception in case of invalid JSON input
(i.e., a parse error) nor creates diagnostic information.
@@ -44,6 +54,12 @@ Unlike the [`parse()`](parse.md) function, this function neither throws an excep
- a pair of `std::string::iterator` or `std::vector<std::uint8_t>::iterator`
- a pair of pointers such as `ptr` and `ptr + len`
`SentinelType`
: a sentinel type compatible with `IteratorType` (different from `IteratorType` and comparable via `operator!=`), for instance.
- a custom sentinel type for C++20 ranges
- `std::counted_iterator` with a different sentinel type
## Parameters
`i` (in)
@@ -61,7 +77,7 @@ Unlike the [`parse()`](parse.md) function, this function neither throws an excep
: iterator to the start of the character range
`last` (in)
: iterator to the end of the character range
: iterator to the end of the character range, or a sentinel value that compares equal to the end iterator with `operator!=`
## Return value
@@ -112,6 +128,7 @@ A UTF-8 byte order mark is silently ignored.
- Changed [runtime assertion](../../features/assertions.md) in case of `FILE*` null pointers to exception in version 3.12.0.
- Added `ignore_trailing_commas` in version 3.13.0.
- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
- Added overload (3) for heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
!!! warning "Deprecation"
docs/mkdocs/docs/api/basic_json/from_bjdata.md
+12 -1
View File
@@ -11,12 +11,19 @@ template<typename IteratorType>
static basic_json from_bjdata(IteratorType first, IteratorType last,
const bool strict = true,
const bool allow_exceptions = true);
// (3)
template<typename IteratorType, typename SentinelType>
static basic_json from_bjdata(IteratorType first, SentinelType last,
const bool strict = true,
const bool allow_exceptions = true);
```
Deserializes a given input to a JSON value using the BJData (Binary JData) serialization format.
1. Reads from a compatible input.
2. Reads from an iterator range.
3. Reads from an iterator and a sentinel (different types, C++20 ranges support).
The exact mapping and its limitations are described on a [dedicated page](../../features/binary_formats/bjdata.md).
@@ -35,6 +42,9 @@ The exact mapping and its limitations are described on a [dedicated page](../../
`IteratorType`
: a compatible iterator type
`SentinelType`
: a sentinel type compatible with `IteratorType` (different from `IteratorType` and comparable via `operator!=`), for instance a custom sentinel type for C++20 ranges
## Parameters
`i` (in)
@@ -44,7 +54,7 @@ The exact mapping and its limitations are described on a [dedicated page](../../
: iterator to the start of the input
`last` (in)
: iterator to the end of the input
: iterator to the end of the input, or a sentinel value that compares equal to the end iterator with `operator!=`
`strict` (in)
: whether to expect the input to be consumed until EOF (`#!cpp true` by default)
@@ -103,3 +113,4 @@ Linear in the size of the input.
- Added in version 3.11.0.
- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
- Added overload (3) for heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
docs/mkdocs/docs/api/basic_json/from_bson.md
+12 -1
View File
@@ -11,12 +11,19 @@ template<typename IteratorType>
static basic_json from_bson(IteratorType first, IteratorType last,
const bool strict = true,
const bool allow_exceptions = true);
// (3)
template<typename IteratorType, typename SentinelType>
static basic_json from_bson(IteratorType first, SentinelType last,
const bool strict = true,
const bool allow_exceptions = true);
```
Deserializes a given input to a JSON value using the BSON (Binary JSON) serialization format.
1. Reads from a compatible input.
2. Reads from an iterator range.
3. Reads from an iterator and a sentinel (different types, C++20 ranges support).
The exact mapping and its limitations are described on a [dedicated page](../../features/binary_formats/bson.md).
@@ -35,6 +42,9 @@ The exact mapping and its limitations are described on a [dedicated page](../../
`IteratorType`
: a compatible iterator type
`SentinelType`
: a sentinel type compatible with `IteratorType` (different from `IteratorType` and comparable via `operator!=`), for instance a custom sentinel type for C++20 ranges
## Parameters
`i` (in)
@@ -44,7 +54,7 @@ The exact mapping and its limitations are described on a [dedicated page](../../
: iterator to the start of the input
`last` (in)
: iterator to the end of the input
: iterator to the end of the input, or a sentinel value that compares equal to the end iterator with `operator!=`
`strict` (in)
: whether to expect the input to be consumed until EOF (`#!cpp true` by default)
@@ -103,6 +113,7 @@ Linear in the size of the input.
- Added in version 3.4.0.
- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
- Added overload (3) for heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
!!! warning "Deprecation"
docs/mkdocs/docs/api/basic_json/from_cbor.md
+13 -1
View File
@@ -14,12 +14,20 @@ static basic_json from_cbor(IteratorType first, IteratorType last,
const bool strict = true,
const bool allow_exceptions = true,
const cbor_tag_handler_t tag_handler = cbor_tag_handler_t::error);
// (3)
template<typename IteratorType, typename SentinelType>
static basic_json from_cbor(IteratorType first, SentinelType last,
const bool strict = true,
const bool allow_exceptions = true,
const cbor_tag_handler_t tag_handler = cbor_tag_handler_t::error);
```
Deserializes a given input to a JSON value using the CBOR (Concise Binary Object Representation) serialization format.
1. Reads from a compatible input.
2. Reads from an iterator range.
3. Reads from an iterator and a sentinel (different types, C++20 ranges support).
The exact mapping and its limitations are described on a [dedicated page](../../features/binary_formats/cbor.md).
@@ -38,6 +46,9 @@ The exact mapping and its limitations are described on a [dedicated page](../../
`IteratorType`
: a compatible iterator type
`SentinelType`
: a sentinel type compatible with `IteratorType` (different from `IteratorType` and comparable via `operator!=`), for instance a custom sentinel type for C++20 ranges
## Parameters
`i` (in)
@@ -47,7 +58,7 @@ The exact mapping and its limitations are described on a [dedicated page](../../
: iterator to the start of the input
`last` (in)
: iterator to the end of the input
: iterator to the end of the input, or a sentinel value that compares equal to the end iterator with `operator!=`
`strict` (in)
: whether to expect the input to be consumed until EOF (`#!cpp true` by default)
@@ -113,6 +124,7 @@ Linear in the size of the input.
- Added `allow_exceptions` parameter in version 3.2.0.
- Added `tag_handler` parameter in version 3.9.0.
- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
- Added overload (3) for heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
!!! warning "Deprecation"
docs/mkdocs/docs/api/basic_json/from_msgpack.md
+12 -1
View File
@@ -11,12 +11,19 @@ template<typename IteratorType>
static basic_json from_msgpack(IteratorType first, IteratorType last,
const bool strict = true,
const bool allow_exceptions = true);
// (3)
template<typename IteratorType, typename SentinelType>
static basic_json from_msgpack(IteratorType first, SentinelType last,
const bool strict = true,
const bool allow_exceptions = true);
```
Deserializes a given input to a JSON value using the MessagePack serialization format.
1. Reads from a compatible input.
2. Reads from an iterator range.
3. Reads from an iterator and a sentinel (different types, C++20 ranges support).
The exact mapping and its limitations are described on a [dedicated page](../../features/binary_formats/messagepack.md).
@@ -35,6 +42,9 @@ The exact mapping and its limitations are described on a [dedicated page](../../
`IteratorType`
: a compatible iterator type
`SentinelType`
: a sentinel type compatible with `IteratorType` (different from `IteratorType` and comparable via `operator!=`), for instance a custom sentinel type for C++20 ranges
## Parameters
`i` (in)
@@ -44,7 +54,7 @@ The exact mapping and its limitations are described on a [dedicated page](../../
: iterator to the start of the input
`last` (in)
: iterator to the end of the input
: iterator to the end of the input, or a sentinel value that compares equal to the end iterator with `operator!=`
`strict` (in)
: whether to expect the input to be consumed until EOF (`#!cpp true` by default)
@@ -105,6 +115,7 @@ Linear in the size of the input.
- Changed to consume input adapters, removed `start_index` parameter, and added `strict` parameter in version 3.0.0.
- Added `allow_exceptions` parameter in version 3.2.0.
- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
- Added overload (3) for heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
!!! warning "Deprecation"
docs/mkdocs/docs/api/basic_json/from_ubjson.md
+12 -1
View File
@@ -11,12 +11,19 @@ template<typename IteratorType>
static basic_json from_ubjson(IteratorType first, IteratorType last,
const bool strict = true,
const bool allow_exceptions = true);
// (3)
template<typename IteratorType, typename SentinelType>
static basic_json from_ubjson(IteratorType first, SentinelType last,
const bool strict = true,
const bool allow_exceptions = true);
```
Deserializes a given input to a JSON value using the UBJSON (Universal Binary JSON) serialization format.
1. Reads from a compatible input.
2. Reads from an iterator range.
3. Reads from an iterator and a sentinel (different types, C++20 ranges support).
The exact mapping and its limitations are described on a [dedicated page](../../features/binary_formats/ubjson.md).
@@ -35,6 +42,9 @@ The exact mapping and its limitations are described on a [dedicated page](../../
`IteratorType`
: a compatible iterator type
`SentinelType`
: a sentinel type compatible with `IteratorType` (different from `IteratorType` and comparable via `operator!=`), for instance a custom sentinel type for C++20 ranges
## Parameters
`i` (in)
@@ -44,7 +54,7 @@ The exact mapping and its limitations are described on a [dedicated page](../../
: iterator to the start of the input
`last` (in)
: iterator to the end of the input
: iterator to the end of the input, or a sentinel value that compares equal to the end iterator with `operator!=`
`strict` (in)
: whether to expect the input to be consumed until EOF (`#!cpp true` by default)
@@ -104,6 +114,7 @@ Linear in the size of the input.
- Added in version 3.1.0.
- Added `allow_exceptions` parameter in version 3.2.0.
- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
- Added overload (3) for heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
!!! warning "Deprecation"
docs/mkdocs/docs/api/basic_json/parse.md
+21 -2
View File
@@ -16,13 +16,25 @@ static basic_json parse(IteratorType first, IteratorType last,
const bool allow_exceptions = true,
const bool ignore_comments = false,
const bool ignore_trailing_commas = false);
// (3)
template<typename IteratorType, typename SentinelType>
static basic_json parse(IteratorType first, SentinelType last,
const parser_callback_t cb = nullptr,
const bool allow_exceptions = true,
const bool ignore_comments = false,
const bool ignore_trailing_commas = false);
```
1. Deserialize from a compatible input.
2. Deserialize from a pair of character iterators
2. Deserialize from a pair of character iterators (same type)
The `value_type` of the iterator must be an integral type with size of 1, 2, or 4 bytes, which will be interpreted
respectively as UTF-8, UTF-16, and UTF-32.
3. Deserialize from an iterator and a sentinel (different types, C++20 ranges support)
The `value_type` of the iterator must be an integral type with size of 1, 2, or 4 bytes, which will be interpreted
respectively as UTF-8, UTF-16, and UTF-32. The sentinel type must be comparable to the iterator type with `operator!=`.
## Template parameters
@@ -43,6 +55,12 @@ static basic_json parse(IteratorType first, IteratorType last,
- a pair of `std::string::iterator` or `std::vector<std::uint8_t>::iterator`
- a pair of pointers such as `ptr` and `ptr + len`
`SentinelType`
: a sentinel type compatible with `IteratorType` (different from `IteratorType` and comparable via `operator!=`), for instance.
- a custom sentinel type for C++20 ranges
- `std::counted_iterator` with a different sentinel type
## Parameters
`i` (in)
@@ -67,7 +85,7 @@ static basic_json parse(IteratorType first, IteratorType last,
: iterator to the start of a character range
`last` (in)
: iterator to the end of a character range
: iterator to the end of a character range, or a sentinel value that compares equal to the end iterator with `operator!=`
## Return value
@@ -238,6 +256,7 @@ Invalid Unicode escapes and unpaired surrogates in the input are reported as
- Changed [runtime assertion](../../features/assertions.md) in case of `FILE*` null pointers to exception in version 3.12.0.
- Added `ignore_trailing_commas` in version 3.13.0.
- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
- Added overload (3) for heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
!!! warning "Deprecation"
docs/mkdocs/docs/api/basic_json/sax_parse.md
+20 -3
View File
@@ -18,15 +18,28 @@ static bool sax_parse(IteratorType first, IteratorType last,
const bool strict = true,
const bool ignore_comments = false,
const bool ignore_trailing_commas = false);
// (3)
template<class IteratorType, class SentinelType, class SAX>
static bool sax_parse(IteratorType first, SentinelType last,
SAX* sax,
input_format_t format = input_format_t::json,
const bool strict = true,
const bool ignore_comments = false,
const bool ignore_trailing_commas = false);
```
Read from input and generate SAX events
1. Read from a compatible input.
2. Read from a pair of character iterators
2. Read from a pair of character iterators (same type)
The value_type of the iterator must be an integral type with a size of 1, 2, or 4 bytes, which will be interpreted
respectively as UTF-8, UTF-16, and UTF-32.
3. Read from an iterator and a sentinel (different types, C++20 ranges support)
The value_type of the iterator must be an integral type with a size of 1, 2, or 4 bytes, which will be interpreted
respectively as UTF-8, UTF-16, and UTF-32. The sentinel type must be comparable to the iterator type with `operator!=`.
The SAX event lister must follow the interface of [`json_sax`](../json_sax/index.md).
@@ -43,9 +56,12 @@ The SAX event lister must follow the interface of [`json_sax`](../json_sax/index
(as found via ADL or member functions, with semantics compatible to `std::begin` and `std::end`)
`IteratorType`
: a compatible iterator type for overload (2); a pair of character iterators whose `value_type` is an integral type
: a compatible iterator type for overloads (2) and (3); a pair of character iterators whose `value_type` is an integral type
with a size of 1, 2, or 4 bytes (interpreted respectively as UTF-8, UTF-16, and UTF-32)
`SentinelType`
: a sentinel type compatible with `IteratorType` (different from `IteratorType` and comparable via `operator!=`) for overload (3)
`SAX`
: a class fulfilling the SAX event listener interface; see [`json_sax`](../json_sax/index.md)
@@ -76,7 +92,7 @@ The SAX event lister must follow the interface of [`json_sax`](../json_sax/index
: iterator to the start of a character range
`last` (in)
: iterator to the end of a character range
: iterator to the end of a character range, or a sentinel value that compares equal to the end iterator with `operator!=`
## Return value
@@ -128,6 +144,7 @@ A UTF-8 byte order mark is silently ignored.
- Ignoring comments via `ignore_comments` added in version 3.9.0.
- Added `ignore_trailing_commas` in version 3.13.0.
- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
- Added overload (3) for heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
!!! warning "Deprecation"