Skip to main content

Crate iso_8583_rs

Crate iso_8583_rs 

Source
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

StepTypeWhat it does
1CompiledSpecReads the YAML spec once at startup and turns it into a flat lookup table.
2BuilderAssembles an outgoing message, validates each field, and writes it to a buffer.
3MessageParses 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

MethodReturns
Message::getthe raw bytes, Option<&[u8]>
Message::get_strOption<&str>
Message::get_u64Option<u64> for numeric fields (amount, STAN, dates)
Message::get_validatedthe raw bytes after checking them against the spec
Message::fieldsevery 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

ModuleContents
messageMessage: parse and read messages
builderBuilder: build and pack messages
specCompiledSpec: ready-to-use spec, FieldDef, LenType, ContentType
specfileYAML file format and spec_from_file
charsetn / a / an / ans character validation (SWAR)
numericASCII digits → u64 (SWAR)
errorError
iso8583, converter, validators, strpadlegacy 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.