Expand description
Fast, zero-copy, zero-allocation ISO 8583 parser and builder driven by a YAML spec.
ISO 8583 is the message format behind card payments (ATM, POS, switch-to-switch). Every host defines its own layout, so here the layout is a YAML file: you load it once, then parse and build messages against it without allocating.
§How it fits together
| Step | Type | What it does |
|---|---|---|
| 1 | CompiledSpec | Reads the YAML spec once at startup and turns it into a flat lookup table. |
| 2 | Builder | Assembles an outgoing message, validates each field, and writes it to a buffer. |
| 3 | Message | Parses an incoming message and lets you read its fields without copying. |
§Quick start
use iso_8583_rs::{Builder, CompiledSpec, Message};
// Load and compile the spec once at startup.
let spec = CompiledSpec::from_file("spec1987.yml")?;
// Build: values are borrowed and validated once on `set`.
let mut req = Builder::new(&spec, b"0200")?;
req.set(2, b"4111111111111111")?.set(4, b"000000010000")?;
let mut buf = Vec::new();
req.pack_into(&mut buf);
// Parse: no copies, field values are slices into `buf`.
let msg = Message::parse(&spec, &buf)?;
assert_eq!(msg.get(2), Some(&b"4111111111111111"[..]));
assert_eq!(msg.get_u64(4), Some(10_000));§Reading fields
| Method | Returns |
|---|---|
Message::get | the raw bytes, Option<&[u8]> |
Message::get_str | Option<&str> |
Message::get_u64 | Option<u64> for numeric fields (amount, STAN, dates) |
Message::get_validated | the raw bytes after checking them against the spec |
Message::fields | every present field, in field-number order |
§Strict or lazy parsing
Message::parse checks the structure and every field’s content in a single pass; use
it for input from outside. Message::parse_lazy checks only the structure and leaves
content checks to Message::get_validated, which suits a router that reads a few fields.
Buffer bounds are checked in both modes, so neither can panic on malformed input.
§Handling errors
Every failure is a small Copy Error you can match on. Errors never allocate, and
malformed messages return an error instead of panicking.
§Limitations
ASCII encoding only (no BCD/EBCDIC), hex ASCII bitmap, fields 1–128, messages up to 65 535 bytes. See the README for the full list and for a usage guide with more examples.
§Modules
| Module | Contents |
|---|---|
message | Message: parse and read messages |
builder | Builder: build and pack messages |
spec | CompiledSpec: ready-to-use spec, FieldDef, LenType, ContentType |
specfile | YAML file format and spec_from_file |
charset | n / a / an / ans character validation (SWAR) |
numeric | ASCII digits → u64 (SWAR) |
error | Error |
iso8583, converter, validators, strpad | legacy API, kept for compatibility |
Re-exports§
pub use builder::Builder;pub use error::Error;pub use message::Message;pub use numeric::parse_digits_u64;pub use spec::CompiledSpec;pub use spec::ContentType;pub use spec::FieldDef;pub use spec::LenType;
Modules§
- builder
Builder: assemble an ISO 8583 message and write (pack) it into a buffer, without allocating.- charset
- Character validation per ISO 8583 content type (
n,a,an,ans). - converter
- Legacy API. Convert a bitmap in bit-array form (
Vec<i64>of 0/1) ↔ hex. - error
- Error type for parsing, building, and loading specs.
- iso8583
- Legacy API.
IsoStruct: a message in owned form (String,HashMap,Vec<i64>bitmap). - message
Message: parse an ISO 8583 message and read its fields, without copying or allocating.- numeric
- Convert numeric ASCII fields (amount, STAN, dates) into numbers without
str::parse. - spec
- “Compiled” spec: the
[FieldDef; 129]table used by the parser and the builder. - specfile
- YAML spec file format, exactly as written in the file.
- strpad
- Legacy API. String padding. No longer used inside the library; kept because it is public.
- validators
- Legacy API. First-version MTI and field-length validators, kept for compatibility.