Skip to content

serialize 2.1.4: a read refuses a value its destination cannot hold

Latest

Choose a tag to compare

@rowan-claude rowan-claude released this 10 Nov 17:01
65e43ca

Format 2.0. No byte a writer emits changed. STANDARD.md and conformance/ are unchanged, so ports need not re-vendor them. IMPLEMENTING.md U7, U11 and U16 state the behaviours below for every port.

  • A read refuses a value its destination cannot hold (U16). The read returns value_out_of_range and leaves the destination unwritten.
    • Ranged reads (serialize_int, serialize_int64, serialize_int128, their read_ and compile time forms) judge the value with its sign: 300 over [0,1000] into a uint8_t refuses.
    • int_relative judges the reconstruction: 135000 into a uint16_t current refuses.
    • Raw bit reads (serialize_bits, the uintN and bool forms, read_bits, the compile time bits forms) judge the bit pattern. They accept when the low bits bits of the destination's two's complement value equal the bits read. So ff ff ff ff in 32 bits reads into an int32_t as -1, and 300 in 16 bits into a uint8_t refuses.
    • Writing a negative value through a raw bit field stays caller error.
    • A C++ bit-field destination is checked against its declared type, not its width.
  • bytes. A null destination with a positive count refuses on read (U7). A zero-length block with a null pointer, nullptr included, is accepted on every stream and still aligns.
  • string. A read refused for its payload's content leaves the buffer NUL terminated after the bytes read.
  • A write after a flush that stored a partial word asserts (U11).
  • serialize_int, serialize_int64, serialize_bits and their read_ and write_ forms evaluate value, min, max and bits once.
  • read_string resolves for stream types declared outside namespace serialize.
  • The compile time int forms take Min == Max as a zero-bit field, as the runtime forms do.
  • compressed_float rounds every intermediate to float32.
  • BitsRequired, PopCount and Log2 take uint64_t and count ranges wider than 32 bits (BitsRequired<0,4294967296> is 33).
  • Macro locals are named serialize_macro_*_, and the header is clean under -Wshadow, GCC's broader set and clang's -Weverything on the consumer translation unit.