ojitoss/bitack

Purpose and Public API

Bitack is a Rust library for declaratively describing compact binary bit layouts, then serializing u32 values into bytes and deserializing bytes back into values. The crate entry point is src/lib.rs; its public model centers on schemes and fields in src/schemes.rs and src/fields.rs.

Scheme Model

BitScheme represents an ordered binary layout composed of BitField entries. Fields encode both width and behavior: value-consuming fields such as Next, structural gaps such as Skip, and prefix-oriented encodings such as leading-one/leading-zero fields. This declarative layer is defined across:

• src/schemes.rs

• src/fields.rs

A scheme is the boundary between caller-provided logical values and the library’s bit-level representation.

Write Pipeline

Writing begins with a BitScheme plus a vector of values. The scheme traverses fields in layout order; only fields that represent stored values consume input elements, while skipped/reserved fields emit ignored or padded bits. Bit-level emission and field-specific encoding are implemented in:

• src/schemes/writter.rs

• src/fields.rs

• src/utils/bitmask.rs

The result is a byte-oriented buffer suitable for external sinks such as files. Output is padded/aligned to four-byte blocks, and internal field operations are constrained to u32.

Read Pipeline

Reading accepts a byte buffer and applies the same ordered scheme to recover logical field values. The reader interprets bit positions, ignores Skip regions, and decodes the field encoding rules before returning values in scheme order. The decoding stage is isolated in:

• src/schemes/reader.rs

• src/schemes.rs

• src/fields.rs

This makes the scheme itself the shared contract between producer and consumer; no file, network, or persistence runtime is built into the crate.

Bit Manipulation Foundation

Low-level masks, bit extraction, and related primitives support both directions of conversion. Shared abstraction traits and utilities likely separate reusable bit operations from scheme traversal:

• src/utils.rs

• src/utils/bitmask.rs

• src/utils/traits.rs

These utilities are an internal implementation boundary: callers describe fields and invoke scheme read/write APIs rather than manually shifting and masking bits.

Runtime and Integration Boundary

The repository is a Cargo Rust library (Cargo.toml) with no service runtime or external infrastructure dependency shown. Consumers supply input values and choose output destinations; the file-system integration shown by the project is consumer-side usage:

• examples/fs.rs

• examples/fs.rs

The primary external integration is therefore any Rust application that imports the crate, writes returned bytes to a transport/storage system, and later feeds bytes back to the same compatible scheme.