Merge upstream/develop; reconcile operator>> caveat with #5343

#5343 landed the authoritative operator>> number-terminator caveat in
operator_gtgt.md, so take that version and replace the now-redundant caveat on
the parsing feature page with a pointer to it. README corrections (test-data is
downloaded not vendored; strict parse() coverage attributed to the updated
suite) are unaffected.

Signed-off-by: manon <youdie006@users.noreply.github.com>

Author: youdie006

.github/workflows/codeql-analysis.yml

@@ -38,14 +38,14 @@ jobs:
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@7188fc363630916deb702c7fdcf4e481b751f97a # v4.37.1
+      uses: github/codeql-action/init@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3
       with:
         languages: c-cpp
 
     # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@7188fc363630916deb702c7fdcf4e481b751f97a # v4.37.1
+      uses: github/codeql-action/autobuild@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@7188fc363630916deb702c7fdcf4e481b751f97a # v4.37.1
+      uses: github/codeql-action/analyze@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3

.github/workflows/flawfinder.yml

@@ -43,6 +43,6 @@ jobs:
           output: 'flawfinder_results.sarif'
 
       - name: Upload analysis results to GitHub Security tab
-        uses: github/codeql-action/upload-sarif@7188fc363630916deb702c7fdcf4e481b751f97a # v4.37.1
+        uses: github/codeql-action/upload-sarif@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3
         with:
           sarif_file: ${{github.workspace}}/flawfinder_results.sarif

.github/workflows/scorecards.yml

@@ -46,7 +46,7 @@ jobs:
           persist-credentials: false
 
       - name: "Run analysis"
-        uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
+        uses: ossf/scorecard-action@2d1146689b8cda280b9bc96326124645441f03bc # v2.4.4
         with:
           results_file: results.sarif
           results_format: sarif
@@ -76,6 +76,6 @@ jobs:
 
       # Upload the results to GitHub's code scanning dashboard.
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@7188fc363630916deb702c7fdcf4e481b751f97a # v4.37.1
+        uses: github/codeql-action/upload-sarif@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3
         with:
           sarif_file: results.sarif

.github/workflows/semgrep.yml

@@ -61,7 +61,7 @@ jobs:
 
       # Upload SARIF file generated in previous step
       - name: Upload SARIF file
-        uses: github/codeql-action/upload-sarif@7188fc363630916deb702c7fdcf4e481b751f97a # v4.37.1
+        uses: github/codeql-action/upload-sarif@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3
         with:
           sarif_file: semgrep.sarif
         if: always()

docs/mkdocs/docs/api/basic_json/binary_t.md

@@ -13,9 +13,8 @@ is compatible with both of the binary data formats that use binary subtyping, (t
 incompatible with each other, and it is up to the user to translate between them). The subtype is added to `BinaryType`
 via the helper type [byte_container_with_subtype](../byte_container_with_subtype/index.md).
 
-[CBOR's RFC 7049](https://tools.ietf.org/html/rfc7049) describes this type as:
-> Major type 2: a byte string. The string's length in bytes is represented following the rules for positive integers
-> (major type 0).
+[CBOR's RFC 8949](https://www.rfc-editor.org/rfc/rfc8949.html#section-3.1) describes this type as:
+> Major type 2: A byte string. The number of bytes in the string is equal to the argument.
 
 [MessagePack's documentation on the bin type
 family](https://github.com/msgpack/msgpack/blob/master/spec.md#bin-format-family) describes this type as:

docs/mkdocs/docs/api/basic_json/to_bson.md

@@ -40,6 +40,9 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
   is not an object; example: `"to serialize to BSON, top-level type must be object, but is string"`
 - Throws [`out_of_range.409`](../../home/exceptions.md#jsonexceptionout_of_range409) if a key in the JSON object contains
   a null byte (code point U+0000); example: `"BSON key cannot contain code point U+0000 (at byte 2)"`
+- Throws [`out_of_range.412`](../../home/exceptions.md#jsonexceptionout_of_range412) if the length of a document, array,
+  string, or binary value exceeds the range of the 32-bit BSON length field; example:
+  `"BSON length 2147483661 exceeds maximum of 2147483647"`
 
 ## Complexity
 

docs/mkdocs/docs/api/operator_gtgt.md

@@ -33,22 +33,44 @@ 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 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:
+`operator>>` parses exactly one JSON value, 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, stream now positioned right after it
+input >> j1;  // parses the first value
 input >> j2;  // parses the next value
 ```
 
-A number is terminated only by the character that follows it, and `operator>>` consumes that character, so consecutive
-numbers must be whitespace-separated: `1 2` reads as two values, but in `1true` the terminating `t` is consumed together
-with the `1`, leaving `rue` in the stream so the next extraction fails. Structural and literal values are self-delimiting
-and are not affected.
+!!! warning "A number must be followed by whitespace"
 
-Note this 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.
+    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:
+
+    ```cpp
+    std::istringstream input("1true");
+    json j1, j2;
+    input >> j1;  // j1 == 1
+    input >> j2;  // throws parse_error.101: the stream now starts at "rue"
+    ```
+
+    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).
+
+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.
 
 !!! warning "Deprecation"
 

docs/mkdocs/docs/features/binary_formats/bson.md

@@ -35,6 +35,19 @@ The library uses the following mapping from JSON values types to BSON types:
     The mapping is **incomplete**, since only JSON-objects (and things contained therein) can be serialized to BSON.
     Also, keys may not contain U+0000, since they are serialized a zero-terminated c-strings.
 
+!!! warning "BSON type 0x11 interoperability"
+
+    The BSON specification defines type `0x11` as a Timestamp. This library uses marker `0x11` when serializing
+    `number_unsigned` values in the range `9223372036854775808..18446744073709551615`. Other BSON implementations may
+    therefore interpret these values as Timestamps instead of unsigned integers.
+
+!!! info "Binary values without a subtype"
+
+    BSON requires every binary value to have a subtype. If a binary value has no subtype, this library serializes it
+    with the generic subtype `0x00`. After deserialization, `has_subtype()` returns `true` and `subtype()` returns `0`.
+    As a result, serializing and deserializing a JSON object containing such a value produces a different JSON object,
+    even though the binary data is unchanged.
+
 ??? example
 
     ```cpp
@@ -82,8 +95,8 @@ The library maps BSON record types to JSON value types as follows:
 
 !!! note "Handling of BSON type 0x11"
 
-    BSON type 0x11 is used to represent uint64 numbers. This library treats these values purely as uint64 numbers 
-    and does not parse them into date-related formats.
+    This library deserializes BSON type `0x11` (Timestamp) as a `number_unsigned` value. The 64-bit value is preserved,
+    but the Timestamp type information is not.
 
 ??? example
 

docs/mkdocs/docs/features/binary_formats/cbor.md

@@ -7,12 +7,12 @@ extremely small code sizes, fairly small message size, and extensibility without
 
     - [CBOR Website](http://cbor.io) - the main source on CBOR
     - [CBOR Playground](http://cbor.me) - an interactive webpage to translate between JSON and CBOR
-    - [RFC 7049](https://tools.ietf.org/html/rfc7049) - the CBOR specification
+    - [RFC 8949](https://www.rfc-editor.org/rfc/rfc8949.html) - the CBOR specification
 
 ## Serialization
 
 The library uses the following mapping from JSON values types to CBOR types according to the CBOR specification
-([RFC 7049](https://www.rfc-editor.org/rfc/rfc7049.html)):
+([RFC 8949](https://www.rfc-editor.org/rfc/rfc8949.html)):
 
 | JSON value type | value/range                                | CBOR type                         | first byte |
 |-----------------|--------------------------------------------|-----------------------------------|------------|

docs/mkdocs/docs/features/parsing/index.md

@@ -40,11 +40,9 @@ what makes it possible to read several concatenated values from the same stream,
 document followed by trailing bytes" is accepted rather than rejected. If you are validating conformance, or need to
 reject any input that is not exactly one JSON document, prefer `parse`.
 
-One caveat when relying on this for concatenated values: a number is terminated only by the character that follows it,
-and `operator>>` consumes that character, so consecutive numbers must be whitespace-separated. `1 2` reads as two
-values, but in `1true` the terminating `t` is consumed together with the `1`, leaving `rue` in the stream, so the next
-extraction fails. Structural and literal values (objects, arrays, strings, `true`/`false`/`null`) are self-delimiting
-and are not affected.
+When using `operator>>` to read several concatenated values this way, a value that is a number must be followed by
+whitespace, because `operator>>` consumes the character that terminates a number — see the
+[`operator>>` notes](../../api/operator_gtgt.md#notes) for details and examples.
 
 ## SAX vs. DOM parsing