Skip to content

docs: document size-mismatch behavior of fixed-size conversions - #5352

Open
nlohmann wants to merge 1 commit into
developfrom
claude/todo-244-size-mismatch-docs
Open

docs: document size-mismatch behavior of fixed-size conversions#5352
nlohmann wants to merge 1 commit into
developfrom
claude/todo-244-size-mismatch-docs

Conversation

@nlohmann

@nlohmann nlohmann commented Aug 3, 2026

Copy link
Copy Markdown
Owner

Summary

Conversions whose element count is fixed by the destination C++ type rather than by the JSON value read exactly the elements they need via at(i) and never compare that number to the JSON array's size. This affects:

  • get<std::pair<A, B>>
  • get<std::tuple<Ts...>>
  • get<std::array<T, N>>
  • the C-array from_json overloads (T[N])
  • std::map / std::unordered_map with a non-string key type (read from an array of two-element arrays)

The two mismatch directions behave differently, and neither was documented in conversions.md, get.md, or from_json.md:

  • too many elements → the surplus is silently discarded, no exception;
  • too few elements → at throws out_of_range.401, i.e. an out-of-range error rather than a type_error, even though the cause is a shape mismatch.

Verified against current develop for all five destination kinds in both directions:

pair excess: 1,2                    pair short:    out_of_range.401
tuple excess: 1,2                   tuple short:   out_of_range.401
array excess: 1,2                   array short:   out_of_range.401
C-array excess: 1,2                 C-array short: out_of_range.401
map<int,int> excess: {1: 2}         map short:     out_of_range.401

Correction to an existing warning

conversions.md already carried a warning, but it covered only std::array and claimed that a too-short JSON array leaves the remaining elements default-constructed with no exception thrown. That is not what happens — from_json_array_impl for std::array uses j.at(i), so it throws out_of_range.401 like the others. This PR generalizes the warning to every fixed-size destination and corrects the shortfall direction.

Non-goals

This documents the current behavior only. Making these conversions strict about size would break working code and belongs in the 4.0 bucket.

Breaking changes to the public API

None — documentation only, no code or headers touched.


This pull request was prepared by Claude Code.

Conversions whose element count is fixed by the destination C++ type --
`std::pair`, `std::tuple`, `std::array<T, N>`, C arrays, and
`std::map`/`std::unordered_map` with a non-string key -- read exactly the
elements they need via `at` and never compare the JSON array's size to
that number. Excess elements are silently discarded, while a shortfall
throws `out_of_range.401` rather than a `type_error`. Neither direction
was documented in `conversions.md`, `get.md`, or `from_json.md`.

The existing warning covered only `std::array` and stated that a too-short
JSON array leaves the remaining elements default-constructed with no
exception thrown; that is not what happens. Generalize it to all
fixed-size destinations and correct the shortfall direction.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
@nlohmann nlohmann added this to the Release 3.13.0 milestone Aug 3, 2026
@nlohmann nlohmann added the 🚀 ready to merge Ready to merge - just waiting for CI to complete. label Aug 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation M 🚀 ready to merge Ready to merge - just waiting for CI to complete.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant