Binary data glossary
| Term | Meaning in these guides |
|---|---|
| Byte | Eight bits; shown as two hexadecimal digits, such as 2A |
| Offset | Position measured from the start of the input; the first byte has offset 0 |
| Width | Number of bytes a field occupies |
| Endianness or byte order | Order of bytes within a number; little-endian stores the least significant byte first |
| Padding | Unused bytes inserted between fields or at the end to satisfy alignment rules |
| Alignment | A rule that a value starts at an offset divisible by a number, such as 4 for a uint32 in an aligned layout |
| Packed | Fields follow each other without alignment gaps |
| Layout | Text describing field names, types, and placement |
| Portable | The name of the layout language CStructSharp reads; its widths and placement rules do not depend on the host machine |
| Struct | A record whose members are stored one after another in declaration order |
| Union | A declaration whose members all start at the same offset, giving several readings of the same bytes |
| Bitfield | A member that occupies a number of bits inside a larger integer, such as uint8 flag : 1; |
| Enum | A set of named integer values with a declared storage type, such as enum kind : uint8 { A = 1 }; |
| Pointer | A stored number that gives the position of another value; CStructSharp reads it with an explicit width and origin |
| Variable | A named integer an expression can use: an earlier field, a #define constant, or a value the caller supplies |
| Root | Named declaration selected as the starting point for an operation |
| Path | A selection such as packet.header.kind or packet.items[1] |
| Parse | Read bytes according to a layout and produce values |
| Serialize | Turn values into bytes according to a layout |
| Update | Replace a field in existing bytes without moving later fields |
| ABI | Application binary interface: a compiler and platform's rules for native data and calls |
| Span | A temporary view over a region of memory |
| Mapped class | A class implementing ICStructMapped<T> - generated by [CStructMapped] or written by hand - that ReadValue<T>, Get<T>, and the write operations map to and from without reflection |
| Base64 | A text encoding that writes every three bytes as four letters, digits, or symbols; the browser API uses it for a union's rawStorage |
| Stride | Distance in bytes between adjacent array elements, including their tail padding |
| Codec | The rule that converts one primitive type between bytes and a .NET value, such as a little-endian uint16 |
| Custom codec | A codec your program supplies through ICustomCodec, so a layout can use a format-specific type by name |
| Accessor | A path such as packet.header.kind resolved once by GetAccessor<T>, so repeated reads skip the path lookup |
| View | A wrapper over bytes, created by CreateView or generated code, that reads members on request instead of decoding the whole record |
| Virtual address | A location in a process address space, distinct from a file offset |
| Code unit | A storage unit of a text encoding; UTF-16 uses 16-bit code units |
| Discriminator | A field identifying which record or union interpretation is meaningful |
| Cache | Retained reusable work, such as a prepared layout, to avoid repeating it |
| Envelope | The outer result object containing success, data, and error information |
| Round trip | Read data and write it back, checking which bytes and values are preserved |
ValueTask |
A lightweight promise of a result that await waits for; already complete when the bytes were in memory |
CancellationToken |
A signal an operation checks for "stop now", created from a CancellationTokenSource (a timer, a shutdown); cancellation is an OperationCanceledException, never a read failure |
ReadOnlySequence<byte> |
Bytes in one or several segments, such as a PipeReader's buffer; one segment is read in place, several through a pooled copy |
PipeReader |
A reader over bytes that arrive in pieces: ReadAsync hands over what has arrived, AdvanceTo reports what was consumed and examined |
| Record sequence | One root struct after another with nothing between them, read one per step by ParseMany or the generated Records |
| Iterator | A method that produces values one at a time as a loop asks for them (IEnumerable<T>, IAsyncEnumerable<T> for await foreach); a record is parsed only when the loop reaches it |
ref struct enumerator |
A stack-only GetEnumerator/MoveNext/Current set that foreach accepts without IEnumerable<T>, so an enumeration over views allocates nothing |
Start with binary layout basics to see these ideas applied to six bytes.