hl7-net

A lightweight HL7 v2 message parser and writer for Rust.

hl7-net is an idiomatic Rust port of the Efferent HL7-V2 .NET library. It keeps the original library's HL7 semantics — delimiter handling, escaping, "present but null" values, MLLP framing and the round-trip self-check — while reworking the API around Rust conventions (snake_case, Result-based error handling, and a pure-data element tree).

Features

• Parse HL7 v2 messages into a Segment / Field / Component / SubComponent tree.
• Read and write values by path (PID.5.1, MSH.9.3, PID(2).3.1).
• Full HL7 escaping/unescaping (\F\, \S\, \R\, \E\, \T\, \Xnn\ hex, and the <B>/</B>/<BR> formatting sequences).
• "Present but null" ("") values modelled as Option<String>.
• Generate ACK / NACK responses.
• MLLP framing helpers (<VT> … <FS><CR>) for stream transport.
• HL7 date/time parsing and formatting via jiff.
• A parse-time round-trip check: a message is only considered valid if re-serializing it reproduces the (hex-normalized) original.

Installation

Add the crate with Cargo:

cargo add hl7-net

Or add it to Cargo.toml manually:

[dependencies]
hl7-net = "0.1"

The minimum supported Rust version (MSRV) is 1.88 (Rust 2024 edition).

Usage

Parsing a message and reading values

use hl7_net::Message;

let text = "MSH|^~\\&|App|Fac|App2|Fac2|20200101000000||ADT^A01^ADT_A01|MSGID|P|2.5\r\
            PID|1||PATID1234^5^M11||EVERYMAN^ADAM^A^III||19610615|M\r";

let mut message = Message::with_message(text);

// `parse` returns Ok(true) when the message round-trips cleanly.
assert!(message.parse(false).unwrap());

// Read by path: segment.field.component.subcomponent (all 1-based).
assert_eq!(message.get_value("MSH.9.1").unwrap(), "ADT");
assert_eq!(message.get_value("PID.5.1").unwrap(), "EVERYMAN");

// Message-level metadata extracted from MSH.
assert_eq!(message.version, "2.5");
assert_eq!(message.message_control_id, "MSGID");

Updating values

use hl7_net::Message;

let mut message = Message::parse_str(
    "MSH|^~\\&|App|Fac|App2|Fac2|20200101000000||ADT^A01^ADT_A01|MSGID|P|2.5\r\
     PID|1||PATID1234^5^M11||EVERYMAN^ADAM^A^III||19610615|M\r",
    false,
).unwrap();

message.set_value("PID.5.1", "SMITH").unwrap();
assert_eq!(message.get_value("PID.5.1").unwrap(), "SMITH");

// Serialize back to HL7 text.
let out = message.serialize().unwrap();
assert!(out.contains("SMITH^ADAM"));

Acknowledgements and MLLP framing

use hl7_net::Message;

let message = Message::parse_str(
    "MSH|^~\\&|App|Fac|App2|Fac2|20200101000000||ADT^A01^ADT_A01|MSGID|P|2.5\r",
    false,
).unwrap();

// Positive acknowledgement (sender/receiver swapped, MSA|AA).
let ack = message.get_ack(false).unwrap();
assert_eq!(ack.get_value("MSA.1").unwrap(), "AA");

// Wrap a message in an MLLP frame for transport over a socket.
let framed: Vec<u8> = message.get_mllp().unwrap();
assert_eq!(framed[0], 0x0B); // <VT>

Encoding helpers and date handling

use hl7_net::HL7Encoding;
use hl7_net::helper;

let enc = HL7Encoding::default();
let encoded = enc.encode("Smith & Sons");
assert_eq!(enc.decode(&encoded), "Smith & Sons");

// Parse an HL7 timestamp (with optional fraction and timezone offset).
let dt = helper::parse_date_time("20200101120000.5+0100").unwrap();
assert_eq!(dt.to_utc().unwrap().to_string(), "2020-01-01T11:00:00.5Z");

API overview

The element tree is pure data: HL7Encoding is threaded into the parse, serialize and value methods (e.g. field.value(&enc)) rather than stored on each node, which keeps the tree borrow-friendly and cheap to clone.

Building from source

git clone https://github.com/Tirax-Tech/hl7-net.git
cd hl7-net
cargo build
cargo test       # unit tests, helper tests and doc tests
cargo clippy --all-targets

License

Licensed under the MIT License.

This project is a derivative work of the Efferent HL7-V2 .NET library, which is also MIT licensed; the original copyright notice is retained in LICENSE.txt.