fixed-record
fixed-record generates parsers, builders, field accessors, Reader/Writer support, and searchable List APIs from Rust struct definitions for fixed-width records.
Most users only need to depend on fixed-record. The fixed-record-macros crate is an implementation detail and is re-exported by fixed-record.
Japanese documentation is available in README.ja.md.
API documentation is published at https://tomi-912.github.io/fixed-record/.
Why fixed-record?
Fixed-width records show up in bank files, host integrations, legacy batch jobs, and line-oriented data exchanges where every field has a byte width. fixed-record keeps the record layout in one Rust struct and generates the repetitive code around it.
The main benefits are:
- define byte layouts once with
Fixed<N>fields - get generated builders, getters, setters, parsing, serialization, and metadata
- keep fields private while using generated methods as the public API
- read and write record streams with
ReaderandWriter - search and sort records with generated
{StructName}ListAPIs when the defaultlistfeature is enabled - use safe zerocopy views through
zerocopytraits without writing unsafe code
Record Shape
#[fixed_record] supports structs with named fields, and every field must be Fixed<N>.
Non-Fixed<N> fields, tuple structs, zero-width fields, negative widths, and non-literal widths are rejected at compile time.
Installation
Add the versioned crate from crates.io.
[]
= "0.1"
Quick Start
use *;
let user = builder
.with_id
.with_name
.with_age_int
.build;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
Generated API
Applying #[fixed_record] to a struct mainly generates:
- the record struct with basic derives
- a
{StructName}Fieldenum with the same visibility as the record struct - metadata such as
TOTAL_LEN, field lengths, and offsets builder,with_*,try_with_*_int, andwith_*_int_truncatedparse/parse_str/to_bytes- dynamic field operations such as
get_field_*andset_field_* - bulk application helpers such as
apply_* - a
FixedRecordtrait implementation Reader/Writerinteroperability- when the
listfeature is enabled,{StructName}Listconstruction fromVec<Record>, append, indexed insertion, indexed lookup, index-aware mutation, removal,pop,clear, and sorting, with the same visibility as the record struct compare_all_fields/compare_by_fields/to_dump_string
List Search and Editing
{StructName}List is an optional helper generated by the default list feature. It stores records as Vec<Box<Record>>. The macro also generates a private {StructName}ListIndices type whose fields are typed indexes such as BTreeMap<Fixed<8>, Vec<usize>> and BTreeMap<Fixed<16>, Vec<usize>>. This private type cannot be named from outside the defining module. Each key is copied directly from its record field without allocating a Vec<u8>, and each value contains the current indexes of all matching records. Sorting moves boxes in the vector, not the record values allocated behind them.
Fallible search methods consistently use the try_ prefix; search methods without it return Option, Vec, or an iterator directly. Exact lookup uses the field index instead of scanning every record. try_find_by requires exactly the selected field width: shorter input returns Error::TooShort, while wider input returns Error::FieldOverflow. Prefix, padded-value, range, and sorted lookup use ordered index ranges. try_find_range_by accepts standard Rust ranges whose bounds implement AsRef<[u8]>. A short start bound is extended with 0x00, and a short end bound is extended with 0xFF, so trailing bytes are unrestricted. Either bound being too wide returns FieldOverflow; a start greater than the end returns InvalidRange. from_records(records) consumes a Vec<Record>, preserves its order, boxes the records, and builds every field index once. The generated From<Vec<Record>> implementation delegates to the same construction path, allowing let list: UserList = records.into(). read_from(reader) consumes a configured Reader<R, Record> and collects its remaining records into the indexed List. push(record) appends and indexes one record. insert(index, record) inserts at a specific position, increments existing indexed IDs at or after that position, and returns false when index > len(). update changes only the affected entries. remove unindexes the removed record and decrements later IDs; sort and sort_by rebuild indexes because record indexes can change. pop removes only the last record's index entries because other indexes do not change. clear removes all records and clears all indexes. This makes repeated searches faster at the cost of additional memory for copied field keys and record indexes.
find(predicate), find_all(predicate), and retain(predicate) are deprecated because they scan every record; retain also rebuilds every field index. Prefer the indexed try_first_by*, try_find_by*, and try_find_range_by APIs.
Mutable record references are not exposed through iter_mut, because arbitrary changes would leave field indexes stale. for_each_mut confines each mutable reference to a callback and rebuilds all indexes afterward. The try_edit_by*, try_edit_range_by, and try_edit_first_by* methods select private current indexes through the same lookup logic as their try_find* counterparts, mutate only the matching records, and repair the affected index entries. They return an edited count or a boolean instead of exposing indexes. Drop guards repair indexes if a callback unwinds.
List IDs are the current vector indexes. This keeps the helper simple, but indexes can change after remove, sort, or sort_by.
If your application only needs record parsing, field access, Reader, and Writer, disable default features and the List type will not be generated.
let mut list: UserList = vec!.into;
let exact = list.try_find_by?;
let first_exact = list.try_first_by?;
let padded = list.try_find_by_padded?;
let ages_in_20s_and_30s = list.try_find_range_by?;
let first_padded = list.try_first_by_padded?;
let edited = list.try_edit_by?;
list.for_each_mut;
try_find_by / try_first_by require the exact field width. try_find_by_padded / try_first_by_padded accept shorter input when the remaining field bytes are spaces or 0x00. Use first_sorted_by(field) to retrieve the lowest indexed field value without a Result.
Use try_find_by_prefix / try_first_by_prefix for shorter prefix searches.
Editing equivalents are try_edit_by, try_edit_by_padded, try_edit_by_prefix, try_edit_range_by, try_edit_first_by, try_edit_first_by_padded, and try_edit_first_by_prefix. Multiple-record methods return the edited count; first-record methods return whether one record was edited.
Reader / Writer
Reader reads fixed-width records sequentially. Reader::new expects LF (\n) after records, matching Writer::new. If the input uses a different separator or no separator, specify it explicitly. A configured separator is required after every record, including the final record. With the default list feature, both Reader::collect_list() and UserList::read_from(reader) collect all remaining records after applying Reader configuration. Both return the first Reader error without producing a partial List.
let reader = new
.with_sequence_check;
let list = read_from?;
let mut reader = new
.with_separator
.with_sequence_check_options;
Sequence checks return Error::SequenceError when the current record is smaller than the previous record. Equal keys are allowed by default.
Use RecordSeparator::None when records are adjacent with no separator. Writer::new writes to_bytes() output and appends LF by default. Writer::write_all(records) writes borrowed records in iterator order, so a generated List can be written with writer.write_all(list.iter()).
Use RecordSeparator to choose the separator written after each record.
let mut writer = new
.with_separator;
writer.write_all?;
let mut csv_like_writer = new
.with_separator;
let mut cr_writer = new
.with_separator;
Feature Flags
list: enabled by default. Generates the optional{StructName}Listhelper and enablesReader::collect_list().
Disable default features when you only want the record type, field operations, parsing, Reader, and Writer.
[]
= { = "0.1", = false }
Zerocopy Support
#[fixed_record] records are always generated with #[repr(C)] and derive zerocopy::FromBytes, zerocopy::IntoBytes, zerocopy::Immutable, and zerocopy::KnownLayout. The zerocopy traits are re-exported from fixed_record::prelude, so applications can use safe zerocopy APIs without adding a direct zerocopy dependency.
use *;
ref_from_bytes requires the input length to be exactly one record. Use ref_from_bytes_prefix when the input may contain trailing bytes after the first record.
use *;
Use ref_from_str when the input is a UTF-8 string whose byte length is exactly one record.
use *;
Field Initialization
set_field_* clears the target field with CLEAR_BYTE before writing. When unspecified, CLEAR_BYTE is a space byte (0x20).
Use clear_byte = ZERO or clear_byte = 0 when set_field_*, builder(), default(), and cleared() should initialize fields with 0x00.
For explicit initialization, use zeroed(), spaced(), or cleared(). zeroed() always uses 0x00, spaced() always uses spaces, and cleared() uses CLEAR_BYTE.
Use set_field_bytes_no_clear / set_field_str_no_clear when you want to preserve existing trailing bytes. The builder-style with_* methods also perform partial overwrites without clearing first.
Examples
License
This project is licensed under the MIT No Attribution License (MIT-0). See LICENSE.