docs: document size-mismatch behavior of fixed-size conversions - #5352
Open
nlohmann wants to merge 1 commit into
Open
docs: document size-mismatch behavior of fixed-size conversions#5352nlohmann wants to merge 1 commit into
nlohmann wants to merge 1 commit into
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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>>from_jsonoverloads (T[N])std::map/std::unordered_mapwith 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, orfrom_json.md:atthrowsout_of_range.401, i.e. an out-of-range error rather than atype_error, even though the cause is a shape mismatch.Verified against current
developfor all five destination kinds in both directions:Correction to an existing warning
conversions.mdalready carried a warning, but it covered onlystd::arrayand 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_implforstd::arrayusesj.at(i), so it throwsout_of_range.401like 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.