toJsonSummaryString
The first limit top-level children, with everything below them elided.
{"id":42,"name":"ada","tags":[…1024],"blob":…4200000 bytes,…9 more}This is not JSON, and making it into JSON would be worse rather than better. It is JSON-shaped so that anyone who reads JSON can skim it, and every elision is spelled with a … that JSON has no production for — deliberately, so the output cannot be mistaken for the value. The alternative is to elide into something JSON can express, and an elided array rendered [] is readable and wrong: nothing distinguishes it from an empty one. Use toJsonString when you want JSON.
A container child shows its shape and its own child count ({…12}, […1024], or {} and [] when genuinely empty); a scalar too large to show is reported by size (…4200000 bytes); the children past limit are counted (…9 more). A small value elides nothing and therefore does come out as JSON — that agreement is a consequence of sharing one scalar renderer with toJsonString rather than a promise, and the suite asserts it as a consequence.
Both the length of the result and the bytes read are bounded by a function of limit and SUMMARY_VALUE_LIMIT alone. Both are the point: this exists to be called on a value whose size is the reason you cannot call toJsonString.
Parameters
top-level children to show. 0 shows only the count, which is the "just tell me the shape" form. Unlimited is deliberately not offered — that is toJsonString, which already exists, and a second spelling of it would be the worse one.
Throws
if limit is negative.
if the bytes do not decode. A summary reports unreadable data rather than eliding it: eliding would be a default invented for exactly the thing that has to be signalled, and would report "here are eight children" about bytes that have none. Reach for toSummaryString when you need something that cannot throw.
for a non-finite double among the children shown, as toJsonString does for the same value. It cannot throw for depth: it does not recurse.