Expand description
§binlayout
Calculate the size, alignment, field offsets, and padding of binary structures without reading or writing their data. Intended for binary format and protocol implementations, compiler tooling, and guest data models in emulators and VMs.
Host layout and target layout are independent. All byte sizes, offsets,
alignments, and array counts use u64, including on a 32-bit host. There are no
dependencies and no unsafe code. Rust 1.85 or newer is required.
§Installation
[dependencies]
binlayout = "0.1"The API reference is available with cargo doc --open.
§Basic layouts
Layout describes byte geometry. Construction validates alignment, which must
be a nonzero power of two. Size can be zero or an unpadded intermediate size.
use binlayout::Layout;
let a = Layout::new(1, 1)?;
let b = Layout::new(4, 4)?;
let (combined, offset) = a.extend(b)?;
assert_eq!(offset, 4);
assert_eq!(combined.size(), 8);
assert_eq!(combined.align(), 4);extend inserts padding before the next field. pad_to_align adds trailing
padding when a record is finished. repeat(count) returns an array layout and
element stride, including trailing padding for every element.
Calculations that exceed u64 return LayoutError::Overflow.
§Named structures
use binlayout::{Layout, StructLayout};
let header = StructLayout::builder()
.field("tag", Layout::new(1, 1)?)
.field("length", Layout::new(4, 4)?)
.field("flags", Layout::new(2, 2)?)
.build()?;
assert_eq!((header.size(), header.align()), (12, 4));
assert_eq!(header.offset("tag"), Some(0));
assert_eq!(header.offset("length"), Some(4));
assert_eq!(header.offset("flags"), Some(8));
assert_eq!(header.fields()[1].padding_before(), 3);
assert_eq!(header.tail_padding(), 2);| Byte range | Contents |
|---|---|
| 0 | tag |
| 1–3 | padding |
| 4–7 | length |
| 8–9 | flags |
| 10–11 | tail padding |
Fields retain declaration order. Duplicate names are errors; unknown names
return None. header.layout() can be nested in another structure or repeated
as an array.
For byte-packed wire formats, use .packed(1) on the builder: this header then
has offsets 0, 1, 5, size 7, and alignment 1. A larger power-of-two packing
value caps field alignment at that value. .align(n) imposes a minimum aggregate
alignment. Packing does not alter padding already inside a nested layout.
FieldLayout::layout() preserves the original layout while FieldLayout::align()
reports the effective placement alignment.
§Types and targets
Type describes fixed-width unsigned/signed integers, floats, pointers, arrays,
ordered structures, and unions. A target supplies scalar and pointer alignment rules.
use binlayout::{TargetLayout, Type};
let foo = Type::Struct(vec![Type::U8, Type::Pointer]);
let wasm32 = TargetLayout::wasm32();
let x86_64 = TargetLayout::x86_64();
let a = wasm32.layout_of(&foo)?;
let b = x86_64.layout_of(&foo)?;
assert_eq!((a.size(), a.align()), (8, 4));
assert_eq!((b.size(), b.align()), (16, 8));
// Use named types when you also need field offsets.
let named = x86_64.struct_layout([
("tag", Type::U8),
("data", Type::Pointer),
])?;
assert_eq!(named.offset("data"), Some(8));
let records = Type::array(foo, 3);
assert_eq!(wasm32.layout_of(&records)?.size(), 24);
assert_eq!(x86_64.layout_of(&records)?.size(), 48);Custom targets require explicit pointer size and alignment. Scalar alignments default to their byte sizes, and can be overridden individually:
use binlayout::{Scalar, TargetLayout, Type};
let target = TargetLayout::builder()
.pointer_size(4)
.pointer_align(4)
.scalar_alignment(Scalar::U64, 4)
.scalar_alignment(Scalar::I64, 4)
.scalar_alignment(Scalar::F64, 4)
.build()?;
let record = Type::Struct(vec![Type::U8, Type::U64]);
assert_eq!(target.layout_of(&record)?.size(), 12);Scalar and pointer sizes must be nonzero multiples of alignment. Signed and
unsigned scalar overrides are independent. For a packed target-specific record,
pass target.layout_of(&ty)? into StructLayout::builder().field(...).
The wasm32 and x86-64 presets cover scalar, pointer, and aggregate layouts; they do not implement complete calling conventions or bit-field rules.
§Unions
Unions place every member at offset zero and round the largest member size up to the union alignment. They do not add a tag or discriminant.
use binlayout::{Layout, UnionLayout};
let payload = UnionLayout::builder()
.field("bytes", Layout::new(9, 1)?)
.field("number", Layout::new(8, 8)?)
.build()?;
assert_eq!((payload.size(), payload.align()), (16, 8));
assert_eq!(payload.offset("bytes"), Some(0));
assert_eq!(payload.offset("number"), Some(0));
assert_eq!(payload.tail_padding(), 7);UnionLayout supports the same .packed(n) and .align(n) builder options as
structures. Type::Union(vec![...]) and target.union_layout([("name", ty), ...])
provide target-dependent union calculations. tail_padding() counts bytes past
the largest member, not unused bytes after a smaller alternative.
§Format examples
cargo run --example header: padding and 32/64-bit pointer layouts.cargo run --example elf: ELF32 and ELF64 headers, with every field offset.cargo run --example protocol: a byte-packed tagged union.
§no_std
Disable the default std feature:
[dependencies]
binlayout = { version = "0.1", default-features = false }alloc is still required for names and type/field collections. Basic Layout
arithmetic does not allocate.
§License
This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. See LICENSE or https://mozilla.org/MPL/2.0/.
Structs§
- Field
Layout - One named field’s placement within a structure or union.
- Layout
- Size and alignment in bytes, independent of the host’s address space.
- Struct
Layout - A declaration-order structure with field offsets and trailing padding.
- Struct
Layout Builder - Builds a structure. Validation and arithmetic errors are returned by
build. - Target
Layout - Explicit scalar and pointer rules for an external data model.
- Target
Layout Builder - Configures a target without inspecting the host.
- Union
Layout - Overlapping named fields, all starting at offset zero.
- Union
Layout Builder - Builds a union, reporting validation and arithmetic errors at
build.
Enums§
- Layout
Error - A layout could not be constructed or represented in
u64bytes. - Scalar
- A fixed-width scalar whose alignment can be customized for a target.
- Type
- A target-independent type description; no binary data is stored or decoded.