append

Appends value, re-expressed against this builder's dictionary.

This is how a stored document moves into a segment. Documents arrive carrying a dictionary of their own; a segment holds one dictionary for all of them, so every field id has to be translated, and translating an id changes the lexicographic ordering the specification requires of the id list. Re-emitting through the builder is what gets both right: field interns the name into the target dictionary and endObject re-sorts by name, exactly as it does for a freshly parsed document.

Scalars are copied byte for byte, header included, rather than read out and re-appended. A roundtrip through appendLong or appendDecimal would re-derive the physical type, so a value stored as int32 by a caller who chose that width would come back as int8 — a silent rewrite of somebody's bytes. Copying also means an unknown primitive id fails here, in Variant.byteSize, instead of being quietly re-encoded as something else.

Recursion follows the value's nesting, which ingest bounds at DEFAULT_MAX_JSON_DEPTH.

Throws