binlayout 0.1.0

Host-independent size, alignment, padding, and offset calculations for binary data models
Documentation
  • Coverage
  • 100%
    43 out of 43 items documented1 out of 1 items with examples
  • Size
  • Source code size: 91.9 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 1.2 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 1s Average build duration of successful builds.
  • all releases: 1s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • LunaStev/binlayout
    0 2 26
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • LunaStev

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);
# Ok::<(), binlayout::LayoutError>(())

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);
# Ok::<(), binlayout::LayoutError>(())
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);
# Ok::<(), binlayout::LayoutError>(())

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);
# Ok::<(), binlayout::LayoutError>(())

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);
# Ok::<(), binlayout::LayoutError>(())

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/.