fix: restore the character that terminates a number (#5340)

operator>> is documented to leave the stream positioned right after the
parsed value, so that concatenated JSON values can be read back to back.
That did not hold for numbers: a number is only terminated by the
character following it, and lexer::scan_number() reads that character
and calls unget() -- which is simulated and rewinds only the lexer's own
bookkeeping. input_stream_adapter consumes via sbumpc() with no matching
sungetc(), so the terminating character stayed consumed and the next
extraction started one byte too late ('1true' left the stream at 'rue').

Propagating unget() to the adapter directly does not work: next_unget
makes the following get() replay the cached character, so the terminator
would be delivered twice. Instead, restore the still-pending character
once at the end of a non-strict parse, where the input is handed back to
the caller:

- input_stream_adapter gains unget_character() (sungetc()) and advertises
  it via supports_unget, detected the same way as supports_seek.
- lexer::restore_pending_unget() turns a pending simulated unget of a
  real (non-EOF) character into a real one and clears next_unget so the
  character is not also replayed. It is a no-op for adapters that cannot
  unget, and reports failure when sungetc() fails, in which case the
  input is left as it was before.
- parser calls it on the three non-strict paths, i.e. for operator>> and
  sax_parse(strict = false).

Strict parse()/accept() are unaffected: they require the input to end
after the value, so the character is consumed by the end-of-input check
anyway. Parse error messages and reported positions are unchanged.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

docs/mkdocs/docs/api/basic_json/sax_parse.md

@@ -69,7 +69,8 @@ The SAX event lister must follow the interface of [`json_sax`](../json_sax/index
      [`input_format_t`](input_format_t.md) for more information
 
 `strict` (in)
-:   whether the input has to be consumed completely (optional, `#!cpp true` by default)
+:   whether the input has to be consumed completely (optional, `#!cpp true` by default); when `#!cpp false` and the
+    input is a `#!cpp std::istream`, the stream is left positioned right after the parsed value
 
 `ignore_comments` (in)
 :   whether comments should be ignored and treated like whitespace (`#!cpp true`) or yield a parse error
@@ -136,6 +137,8 @@ A UTF-8 byte order mark is silently ignored.
 - 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.
 - Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
+- Changed in version 4.0.0 to leave a `#!cpp std::istream` positioned right after the parsed value when `strict` is
+  `#!cpp false`; see [`operator>>`](../operator_gtgt.md#notes).
 
 !!! warning "Deprecation"
 

docs/mkdocs/docs/api/operator_gtgt.md

@@ -33,41 +33,29 @@ A UTF-8 byte order mark is silently ignored.
 Invalid Unicode escapes and unpaired surrogates in the input are reported as
 [`parse_error.101`](../home/exceptions.md#jsonexceptionparse_error101) with a detailed message.
 
-`operator>>` parses exactly one JSON value, so it can be called repeatedly to read a sequence of concatenated JSON
-values from the same stream:
+`operator>>` parses exactly one JSON value and leaves the stream positioned right after it, so it can be called
+repeatedly to read a sequence of concatenated JSON values from the same stream:
 
 ```cpp
-json j1, j2;
-input >> j1;  // parses the first value
-input >> j2;  // parses the next value
+std::istringstream input("1true[2]");
+json j1, j2, j3;
+input >> j1;  // j1 == 1,      stream now positioned right after it
+input >> j2;  // j2 == true
+input >> j3;  // j3 == [2]
 ```
 
-!!! warning "A number must be followed by whitespace"
+!!! note "Changed behavior for numbers"
 
-    A number is only terminated by the character that follows it. That character is read from the stream to detect the
-    end of the number, and it is **not** put back. When a value that is a number is immediately followed by the next
-    value, the first character of that next value is lost:
+    A number is the only value whose end can be detected solely by reading the character that follows it. Up to
+    version 3.13.0 that character was consumed and not put back, so the stream was left one byte too far whenever a
+    number was immediately followed by another value: reading `1true` yielded `1` and left the stream at `rue`.
+    Values had to be separated by whitespace to work around this.
 
-    ```cpp
-    std::istringstream input("1true");
-    json j1, j2;
-    input >> j1;  // j1 == 1
-    input >> j2;  // throws parse_error.101: the stream now starts at "rue"
-    ```
+    The terminating character is now returned to the stream, so no separator is required. Code that relied on the
+    extra byte being swallowed will observe it again.
 
-    Separating the values with whitespace avoids this, because the character that is eaten is then the separator:
-
-    ```cpp
-    std::istringstream input("1 true");
-    json j1, j2;
-    input >> j1;  // j1 == 1
-    input >> j2;  // j2 == true
-    ```
-
-    Only numbers are affected. Values ending in a self-delimiting character do not read past themselves, so
-    `truefalse`, `[1][2]`, `{"a":1}{"b":2}`, and `"a""b"` can be read back to back without a separator.
-
-    This is tracked in [#5340](https://github.com/nlohmann/json/issues/5340).
+    If the stream's `#!cpp std::streambuf` cannot put the character back (its `pbackfail` fails, which does not happen
+    for `#!cpp std::stringbuf` or `#!cpp std::filebuf`), the character is lost as before.
 
 Note that reading concatenated values does **not** work for [JSON Lines](../features/parsing/json_lines.md)
 (newline-delimited JSON) input -- see that page for why and for the recommended alternative.
@@ -102,3 +90,5 @@ Note that reading concatenated values does **not** work for [JSON Lines](../feat
 ## Version history
 
 - Added in version 1.0.0.
+- Changed in version 4.0.0 to return the character that terminates a number to the stream, so that the stream is
+  positioned right after the parsed value for every value type.

docs/mkdocs/docs/features/parsing/json_lines.md

@@ -49,5 +49,4 @@ JSON Lines input with more than one value is treated as invalid JSON by the [`pa
     with a JSON Lines input does not work, because the parser will try to parse one value after the last one.
 
     This is different from parsing a stream of *concatenated* (non-newline-delimited) JSON values, for which
-    `operator>>` does work, provided that a value that is a number is followed by whitespace -- see its
-    [notes](../../api/operator_gtgt.md#notes) for details.
+    `operator>>` does work -- see its [notes](../../api/operator_gtgt.md#notes) for details.