structio 0.6.0

Two new declarations: a field or a variant that answers to more than one name, and a one-field struct written as that field alone. Plus ReadOwned, the bound for a read out of a buffer you own, and a json::Raw that can be built from a String you already hold. No breaking changes.

[dependencies]
structio = "0.6"

# The derive is off by default:
structio = { version = "0.6", features = ["derive"] }

Added

• A field or a variant may answer to more than one name. object!(Settings { timeout | "timeout_ms" }) and tagged_enum!(Mode { Idle | "idle" }), repeatable, with #[structio(alias = "..")] as the derive's spelling. The declared name is the one written and an alias is only ever read, so adding one cannot change a byte the program writes: it is how a key or a variant is renamed without breaking the documents already written under the old spelling. A case rule leaves an alias alone, as it leaves an explicit key alone; a #[required] member is satisfied by any of its names; a write_only declaration refuses one, never reading. Keys::ALIASES and Variants::ALIASES are the new associated consts that carry it, both defaulted to empty, so a hand-written impl is unchanged. docs/schemas.md has the rest.

• transparent!, a one-field struct written as that field alone. UserId(7) is 7, not [7] and not {"0":7}: reading and writing delegate to the field, with no object, no keys and no array around it. That is the declaration for the newtype that exists to keep two u64s apart in Rust and means nothing to either format, which array! writes as a one-element array and an object cannot write at all, having no name for its key to be. json_transparent! and beve_transparent! narrow it to one format and write_only to one direction; it takes an adapter, transparent!(Timeout { 0 as Millis }), which is the whole newtype-around-a-foreign-type case in one line; #[structio(transparent)] is the derive's spelling. is_null is forwarded in both formats, and BEVE's typed-array path deliberately is not, that one being a layout claim a declaration cannot make. docs/schemas.md has the rest.

• ReadOwned, the bound for parsing a value out of a buffer you own. At the crate root and per format, as ReadWrite's read-side counterpart. A function that holds the document and hands a T back needs for<'de> Read<'de> + Default: higher-ranked because a type may borrow out of the input and a caller owning the buffer cannot allow that, and Default because reading fills a value rather than constructing one. The crate spelled that pair out in ten of its own signatures, and a downstream extractor had to work it out from scratch; ReadOwned is the name for it. from_str still takes Read<'de>, tied to the input's lifetime so a borrowing type can be read, exactly as serde keeps DeserializeOwned to from_reader. docs/schemas.md has the rest.

• json::Raw::from_string and from_string_unchecked, the way in from a String. Text this program produced rather than read had no entry point: Raw::new_unchecked(&text).into_owned() copied a buffer the caller already owned, there being no way to hand the String over. These take it, so the buffer becomes the span with nothing reallocated and the span never copied out of it, from_string trimming by shifting bytes inside it. The check and the trimming are new's, being the same walk. The Raw then holds the caller's whole allocation rather than just the span, so new(&s)?.into_owned() is still the call for a long-lived value whittled out of a much larger buffer. A rejected value is dropped rather than handed back, so check with new first where the text has to survive its own rejection. There is still no From<String>, for the reason there is no From<&str>.

• Display for json::Raw and json::JsonStr. Raw displays its span, which is what as_str gives and what a compact write emits, escapes and quotes included, since the type is about the spelling. {:#} is that same text rather than a laid-out one: a span new_unchecked accepted may have no layout, and Display has nowhere to report that, so prettify stays the named way to ask. JsonStr displays the string the document meant, with its escapes already resolved.

• Debug, Clone, PartialEq, Eq and Hash for json::JsonStr. It had none, so a test could not assert_eq! on one or print one, and the key Error::key_in hands back could not be looked up in a set of the names a schema knows. Equality and hashing are the text rather than the variant: a key written "a" and one written "\u0061" are the same key, which deriving either would have denied.

Fixed

• ReadWrite's doc example was missing + Default and could not compile. It was marked ignore, so nothing caught it. Now compiled, and the same example in the object! docs already had the bound. Write's example, the crate's only other ignore, is compiled too.

structio 0.5.0

Ordered objects, JSON carried through as its text, a write-only declaration, and Value comparisons that cover the whole table. Two breaking changes, both narrow: Value::Object is an OrderedMap<Value>, and the new comparison impls can make a bare .into() ambiguous.

[dependencies]
structio = "0.5"

# The derive is off by default:
structio = { version = "0.5", features = ["derive"] }

Changed

• Value::Object keeps its member order. It is an OrderedMap<Value> rather than a BTreeMap<String, Value>, so a document read into a Value and written back out lists its members in the order it arrived in, and to_value yields a declared type's field order. Equality is unchanged in meaning and ignores order, so two values can compare equal and write different text. sort_keys() on the object gives back the sorted output. Breaking for code naming BTreeMap where structio::Object is expected, or relying on sorted output.

• transparent is stage 2 of the derive, not stage 3. It describes the whole type rather than one field: stage 2 is for a shape the macros cannot declare, stage 3 for per-field policy. It is not implemented and the derive still refuses it, now naming stage 2.

Added

• A Value compares with the primitive it holds. doc["port"] == 8080 and 8080 == doc.get("port").unwrap() are comparisons now rather than a value!(8080) to wrap the right-hand side in: every integer width, f32, f64, bool, str, &str, String and &String, on either side, with the value owned or behind either reference the accessors hand back. Only str, &str and bool had an impl before, and only against an owned value, so most of the table was a compile error and which part was a matter of luck. A number is met at the comparand's width: value!(1) == 1.0 and value!(1.0) != 1, being the different numbers this crate keeps them, and against an f32 the stored number rounds to that width, so a document's 0.1 equals 0.1f32 while one too large or too small to round to an f32 equals none. Breaking for a caller whose right-hand type was pinned by there being one PartialEq impl within reach: with n: u64, n == w.into() is now ambiguous between u64 and Value and needs the type named.

• Error::key_in, the name an unknown key had. UnknownKey and UnknownVariant carry no name, a name the document chose being no &'static str, so the error winds back to it and reports the offset. This reads it back out of the document at that offset, unescaping as the reader would, and hands a MissingKey the static name it already carries. The lifetime is the document argument's, not the error's, so Error stays Copy and independent of the buffer. JSON only: a BEVE key's length lives in a prefix the offset is already past.

• read_map_located, on json::Parser and beve::Reader. read_map calls back after the colon, so a hand-written map reader could see a key's name but not its position, and hand-rolling the loop was no way out either, the depth counter that bounds nesting not being public. This reports the offset alongside the key: the same byte a generated reader's UnknownKey names, so an error raised by hand reads like one the crate raised.

• structio::OrderedMap<V>, a string-keyed map that keeps its insertion order. Entries live in one vector in the order they arrived; below nine keys a lookup scans it, above that a robin hood hash table indexes it. It reads and writes in both formats, so it works as a whole document or as a declared field where BTreeMap would, and Object is OrderedMap<Value>. Equality ignores order; sort_keys() reorders by key.

• write_only, a declaration of the write half alone. object!(write_only ..), and the same token in front of array!, unit_enum!, tagged_enum! and the one-format macros, generate the writing impls and no read at all, so a field's type needs no Read impl and no Default. #[structio(write_only)] is the derive's spelling of it, and the bytes written are unchanged either way. A generic one bounds its type parameters by the new structio::Write rather than by structio::ReadWrite and Default. #[required] is refused, being a rule about reading, and there is no read_only. docs/schemas.md has the rest.

• A failed Read or Write bound now explains the direction axis. Read, Write, ReadAs and WriteAs, in both formats, carry #[diagnostic::on_unimplemented] notes naming what discharges the bound: write_only where the struct is only ever written, a skip_value() stub where one field is, and on the write side write_null() with is_null returning true, since a member that writes nothing truncates the object.

• json::Raw, one JSON value carried through as its text. A field that captures the exact bytes of a value on read and emits them unchanged on write, so a forwarded body keeps its key order, its number spellings and its escapes: what Value is not, being a tree that respells its numbers and decodes its escapes. Reading borrows the span out of the document, and under ALLOW_COMMENTS strips the comments out of a span that carries any, owning that one; writing is one copy of those bytes, laid out again at the right depth under PRETTY. JSON only, so a struct with one is declared with json_object!. docs/schemas.md has the rest.

• json::prettify_value_into. Lays one JSON value out into a Writer that is already part-way through a document, at that writer's current depth and under its policy. json::Raw writes through it under PRETTY, and it is what a passthrough type of your own needs so that a forwarded value is indented against its neighbours rather than emitted as a blob.

• Tuple structs, in array! and in the derive. A positional declaration names a field by its position, array!(Entry [0, 1]), so the shape that has no field names is now the shape it takes most naturally: #[derive(Structio)] with #[structio(array)] accepts a tuple struct, with the order, .., an element type and generics all as they are for a named struct. The bytes are the tuple's, as they always were. Declared as an object it is still refused, an object having nothing for its keys to be, and the message now names #[structio(array)].

• Writer::member_key, for an object key known only at run time. member takes the key already prepared, quoted with its colon in JSON and length-prefixed in BEVE, because that is what a declaration assembles at compile time. A hand-written WriteObject whose keys come off a walk had to build those bytes itself, and it went wrong differently in each format: nothing escapes a JSON key on that path, so a key holding a " or a \ wrote a document no reader takes, and a BEVE member laid down with size and raw is not counted, which a debug build catches against the header the object already committed to. This takes the key itself, escapes or length-prefixes it, counts the member, and honours SkipNull exactly as member does; member_key_with is the adapter form. The policy's boundary is a struct's member against a map's entry, not a compile-time key against a computed one, and write_keyed is still the map. docs/schemas.md has the rest.

• json::Parser::rest_str. The &str counterpart of rest, for a hand-written Read impl capturing a span: the input's UTF-8 validity is already known, so nothing has to establish it a second time.

Fixed

• A Matrix names the unknown key it refused. It reads its three members by hand through a map callback, which runs after the colon, so its UnknownKey reported the offending member's value rather than its key: a caret under the value, and key_in reading a name off it. It winds back to the key, so every UnknownKey in the crate now names a key. The reported offset for this one code on this one type moves.

• The whole-key hash now folds in the key length. It read whole 8-byte chunks and then an overlapping tail, so two keys differing only in the bytes between them, such as field_name_10500_value and field_name_105000_value, hashed the same under every seed and cost the object its hash: it read under a linear scan instead. Keys shorter than 8 bytes were zero filled, so trailing NULs vanished the same way. Never a wrong field, since a candidate is always confirmed by a full comparison, only a slower read.

• A declared type does not need Default. docs/derive.md said it did, flatly, contradicting docs/schemas.md. Default is required where a read constructs a value: the entry points that return one, an Option's payload, a growing Vec's tail, a map's values, an enum variant's payload. A type that is only ever written needs none, and the derive's examples no longer imply otherwise.

• Where an error out of a declaration lands. The same file promised that a field whose type has no Read impl is reported at that field. One macro call covers every field, so it is reported at the declaration: the struct's name under the derive, the whole invocation under a hand-written one. What does land where it was written is the derive's own refusals and an adapter named by with = "..".

• The same rule, in the README. It read as though reaching for read_into lifted the Default requirement. It lifts it for the value handed in and for nothing beneath it, so read_into(&mut Vec<T>, ..) still asks T for one and no spelling of the read avoids it; Box<T> and [T; N] do escape it, having no element to bui...

structio 0.4.0

#[derive(Structio)] behind an optional feature, a Value tree, and a late enum tag. One breaking change: a raw identifier's r# is no longer part of its key.

[dependencies]
structio = "0.4"

# The derive is off by default:
structio = { version = "0.4", features = ["derive"] }

Changed

• A raw identifier's r# is no longer part of its key. A field or variant written r#type had the key r#type, because that is what stringify! hands the macro. It is now type, before any case rule runs, since the prefix is how Rust spells a name that collides with a keyword rather than part of the name: r#type is how you write a field for a "type" key. Both formats, fields and variants, derived and declared. An explicit "r#type" => field is a literal and is unchanged. Breaking for a declaration with a raw identifier and no explicit key, which now reads and writes a different key.

• An internally tagged enum's tag no longer has to come first. tagged_enum!(.. as tag "kind") used to refuse an object whose first member was not the tag with ExpectedTag, which refused every document from a sorted-key writer the moment a member sorted before the tag. The reader now steps over the members before the tag, dispatches on it, reads the members after it, and then reads the ones it stepped over, nesting as deep as the payloads do. A tag that is first still costs one pass; the members before a late tag are walked twice, and a key on both sides of the tag keeps its earlier value. Required-field and unknown-key rules apply to the deferred members as to any other. An object with no tag at all is still ExpectedTag, reported against its first key.

Added

• #[derive(Structio)], behind the derive feature. A front end to object!, array!, unit_enum! and tagged_enum!: it reads the type and emits the declaration, so a derived type and a declared type are the same impls. rename_all, tag, array, element, json, beve and crate on the type; rename, skip, required and with on a field; rename on a variant. Generics and their bounds are read off the type. The feature is off by default and the derive crate has no dependencies. docs/derive.md has the rest, including what later stages add.
• BEVE containers reserve on the wire count. Reader::read_seq_counted and read_map_counted hand the element count to the caller before the first element, clipped to what the input could hold, and beve::cautious::<T> clips it again to a megabyte of T. Vec, VecDeque, HashMap and HashSet, adapted or not, reserve once instead of doubling up; a hostile count can waste at most that megabyte.
• Value, a tree for a value with no declared type. Null, bool, number, string, array, object, with get, pointer/pointer_mut, the as_*/is_* accessors, Index/IndexMut by key or position, and the value! macro to build one. It reads and writes through both formats like any other type, so it can be a field of an object! declaration or a whole document; a BEVE typed array, complex run or matrix reads into the same shape beve_to_json writes. Number keeps whether it was an unsigned integer, a negative integer or a float, and writes a whole-valued float as 1.0 so the kind survives a trip through text. to_value and from_value move a declared type in and out, through JSON text. This is for the value nothing decodes, a register tree walked by path or a body forwarded unread, not a substitute for a declared type, and the crate's stance on that is unchanged.

Upgrading

The break is narrow. A declaration with a raw identifier and no explicit key changes the key it reads and writes: a field written r#type was keyed r#type and is now keyed type. Nothing else about a 0.3.2 declaration changes its bytes. If you were working around the old behaviour with "r#type" => r#type, that explicit key still means exactly what it says and will keep the old wire format.

The derive feature is additive and off by default, so a crate that does not enable it builds structio with no dependencies and no proc-macro, as before.

structio 0.3.2

Faster JSON reading and string writing. No API or output change.

[dependencies]
structio = "0.3"

Changed

• Faster JSON reading and string writing. Against Glaze on the benchmark documents, reading doubles went from 58% to 87% of its speed, mixed documents from 78% to over 100%, and signed integers, bools and strings moved up with them; string writing went from 91% to 94%. The float reader is now inlined into the array loop rather than called per element, out-of-line helpers no longer pin the parser's cursor to the stack, signs and bools are read without a branch on the data, digits are folded a word at a time rather than one at a time, integers of up to fifteen digits stay on the inlined path, and strings are copied as they are scanned. docs/performance.md has the measurements and the mechanisms.

Output and accepted input are unchanged, and the float scanner is checked bit for bit against the standard library on 200,000 generated literals. A 0.3.1 declaration reads and writes exactly the bytes it did.

structio 0.3.1

Borrowing declarations accept any lifetime name, and the readers' nesting limit is exported.

[dependencies]
structio = "0.3"

Changed

• A borrowing type names its lifetime as it likes. object!(['a] Borrowed<'a> { .. }) now works, as do array!, tagged_enum! and their single-format forms: the first lifetime in the bracket is the input lifetime, whatever it is called. It had to be spelled 'de, and any other name failed from inside the expansion with "lifetime may not live long enough" and no hint about why. Declarations written with 'de are unchanged.

Added

• json::MAX_DEPTH and beve::MAX_DEPTH, the nesting limit each reader enforces, re-exported at the module root. They were reachable only through json::parser and beve::reader.

Nothing existing changed shape; a 0.3.0 declaration reads and writes exactly the bytes it did.

structio 0.3.0

Internally tagged enums: the variant name goes inside the payload's object, the convention most JSON APIs use.

[dependencies]
structio = "0.3"

Added

• Internal tagging, a second convention for tagged_enum!, asked for with a tag clause: tagged_enum!(Shape as tag "kind" { .. }). The variant name goes inside the payload's object as a member rather than wrapping it, giving {"kind":"Circle","radius":1} where the clause-free form writes {"Circle":{"radius":1}}. This is what most JSON APIs use, and the only form here that a C++ Glaze std::variant can be made to agree with, external tagging having nowhere to put the payload's own keys. The clause works on json_tagged_enum! and beve_tagged_enum! too.

  The tag has to be the object's first member, and a document that puts it elsewhere is the new ErrorCode::ExpectedTag, reported against the offending key. Reading is one pass with no lookahead, so a tag arriving after the members it gives meaning to could only be used by holding the object or walking it twice. Writing always emits the tag first, so this crate's own output round-trips unconditionally, as does any producer that emits its tag first - the conventional ordering. The refusal is loud and positioned rather than a misparse.

  A payload must be an object (a compile error naming WriteObject otherwise), since its members share the object with the tag. Everything else carries over: renaming, case rules, generics, borrowed payloads, reading into an existing value, and the policies. The result is an ordinary object, so pointers, validation and transcoding walk it with no knowledge of enums at all. See docs/enums.md.

• A tag that is also a field of a variant's payload is a compile error. The two share one object, so it would write the name twice; structio reads that back and a last-wins parser does not, keeping the field and losing the variant. The comparison is of wire names, so a collision that only appears after a case rule is caught too. cargo check refuses a declaration with no generics; a generic one is refused when the crate is built, a generic payload having no keys until it is instantiated.

• Parser::read_object_rest and Parser::finish_internally_tagged, their Reader counterparts, and Writer::write_internally_tagged in both formats, for hand-written impls of the two new ReadInternallyTagged traits. A variant carrying nothing writes through the existing write_tagged, the bytes being the same object of one member.

Nothing existing changed shape: an externally tagged declaration reads and writes exactly the bytes it did in 0.2.2. The minor bump is for the added ErrorCode variant.

structio 0.2.2

Integer reading is 38-43% faster, and a streaming block read now accepts a complex array.

[dependencies]
structio = "0.2"

Changed

• Reading arrays of integers is 38-43% faster, and the representative mixed document 11%. The element loop was making a function call per element, which is dearer than it sounds: the parser's cursor spilled to the stack and reloaded on every return. parse_u64 now keeps a small fast path for the common short number and hands the rare cases to an out-of-line one, which is enough for the whole read to inline. Separately, JSON whitespace is answered from a table rather than a bitmask, which needed a range guard in front of it because a byte of 64 or more would shift out of the word. Against Glaze, reading uints went from 50% to 80% and ints from 53% to 86%. The measurements, the two rewrites of the digit conversion that were tried first and were both slower, and the disassembly that pointed at the call rather than the digits are in docs/performance.md. No API or output change.

Fixed

• read_array_into and from_reader_array read a complex array. They read the typed-array tag and stopped at the extension's, so the one shape that most needs a streaming block read - a buffer of IQ samples, which a consumer can least afford to hold twice - had to go through from_reader and hold the encoded document alongside the vector. The payload was always a block: interleaved (re, im) components are the in-memory form of [Complex<T>] for the same reason a typed array's payload is the in-memory form of [T]. Only the preamble differed.

  The aligned complex form is byte-identical to the plain one, so both arrive by the same path. COMPLEX_ONE is refused as InvalidHeader, being a lone value with no count rather than an array, as are the six undefined forms of the class byte. A generic array stays ExpectedArray and a boolean or string array stays ElementTypeMismatch.

• The big-endian conversion in the same read reverses each component rather than each element. It could not have fired before, no complex array having reached it, but a Complex<f32> is eight bytes and reversing all eight would have transposed re and im as well as swapping the bytes of each. For every other numeric type the component is the element, so one stride serves both.

No API was added, removed or changed. Nothing needs editing to move from 0.2.1.

structio 0.2.1

A read size that sizes the window, so a small document does not cost a 64 KiB buffer, and a hazard on read_seq written down.

[dependencies]
structio = "0.2"

Changed

• Documents::read_size sizes the window as well as the read. The buffer is allocated on the first fill and holds one chunk, so Documents::array(bytes).read_size(4096) costs 4 KiB rather than the 64 KiB it allocated up front before, whatever the read size said. That matters where streaming is not the point: a document already in memory can still be worth reading through Documents, which is what hands out the elements of a typed array one at a time with their headers installed, and there the default window was a thousand times the document. Applies to both json::Documents and beve::Documents; Feed is unchanged, having no chunk size to go by.
• beve::Reader::read_seq documents that element positions do not bound documents. A typed array's element headers, a complex array's, and a boolean run's are supplied by the reader rather than present in the input, so a span cut between two position() calls is not a value Reader::new can read. A caller slicing spans out of a walk has to check the array's header type first; Documents::array is the way to take elements as documents of their own, and accepts every array shape.

No API was added, removed or changed. Nothing needs editing to move from 0.2.0.

structio 0.2.0

Writing a document after what a buffer already holds, in JSON as well as BEVE, and a buffer that survives a panic out of the value being written.

[dependencies]
structio = "0.2"

Added

• json::append(&T, &mut Vec<u8>) writes a document after what a buffer already holds, the counterpart of beve::append. write_into replaces a buffer's contents, so a value that has to sit behind a protocol header, or behind the entries already in a listing, needed a second buffer and a copy out of it. json::Writer::appending is the same thing with the writer in hand.

Changed

• json::append, beve::append and beve::append_aligned leave the buffer exactly as they found it if writing the value panics. The buffer moves into the writer, so an unwind used to drop it along with the bytes in front of the document. A Write impl may panic by design: an adapter whose target has values it cannot encode is told to substitute or panic. write_into still leaves its buffer empty there, its contents being the call's to replace, and now says so.
• json::Writer::into_string checks the bytes handed to Writer::appending, and panics if they are not UTF-8. Every other byte in the buffer is UTF-8 by construction; those are the only ones the writer did not produce. Use into_vec to append JSON behind a binary prefix.

The full list is in CHANGELOG.md.

structio 0.1.0

First release. JSON and BEVE read straight into your structs and written straight out of them: no Value enum, no token stream, no document model.

[dependencies]
structio = "0.1"

• JSON and BEVE from one schema. object!, array!, unit_enum! and tagged_enum! declare a type's fields once; both formats read and write against that declaration. Keys are hashed at compile time into a perfect hash chosen to fit the key set.
• No dependencies and no proc-macros. Standard library only. Rust 2024 edition, MSRV 1.96.
• Declarations are checked against the type. Leaving out a field, or naming the same key twice, is a compile error that names what is wrong. End a declaration with .. where the omission is deliberate.
• Case rules. object!(Root as "camelCase" { .. }) converts every key the declaration does not spell out, during compilation.
• Reads reuse allocations. read_into and write_into refill the buffers a value already holds, so a loop over records of one shape settles into no allocation.
• Compile-time options. Indentation, inline arrays, skipping null members, refusing unknown keys, requiring declared keys, and JSONC comments. Unused settings cost nothing.
• BEVE beyond whole-document decoding. Read the one value a JSON Pointer names, validate without decoding, write numeric arrays a reader can borrow rather than copy.
• Streaming in both formats, both directions, and beve_to_json rewrites a BEVE document as JSON in one walk with no schema and no tree.
• Errors locate themselves. A byte offset, a line/column/caret rendering against the input, and a named key for a missing one.

The API is not frozen before 1.0. Full notes in CHANGELOG.md, documentation in docs/.