Struct Message 

pub struct Message { /* private fields */ }

One parsed HL7 v2 message.

Built by crate::parse or crate::parse_with_options; see the crate documentation for the three modes that read it.

Implementations

impl Message

pub fn version(&self) -> Version

The HL7 release this message is read as: MSH-12 resolved through Version::nearest, or whatever Options::version forced.

pub fn dictionary(&self) -> &Dictionary

The dictionary this message is read through.

pub fn structure_id(&self) -> String

The message structure ID: MSH-9.3 when the sender supplied one, otherwise derived from MSH-9.1 and MSH-9.2 through the dictionary — ORU_R01, ADT_A01, ACK.

Read from the message each time rather than cached at parse, so a message whose header was changed — by Message::set or by crate::Builder — reports what it now says it is.

pub fn separators(&self) -> &Separators

The delimiters this message declared in MSH-1 and MSH-2.

pub fn raw(&self) -> &Message

The underlying er7 message — the escape hatch.

Everything this crate knows is derived from here, and nothing is lost on the way in, so a caller who needs a field no mode models reads it here rather than parsing the text a second time.

pub fn raw_mut(&mut self) -> &mut Message

The underlying er7 message, mutably. Changes are visible to every other method immediately, including Message::to_er7.

pub fn into_raw(self) -> Message

Take the underlying er7 message, dropping the dictionary.

pub fn segments(&self) -> impl Iterator<Item = &Segment>

Every segment, in message order.

pub fn segment(&self, name: &str) -> Option<&Segment>

The first segment named name.

pub fn segment_at(&self, name: &str, occurrence: usize) -> Option<&Segment>

The occurrence-th (1-based) segment named name.

pub fn to_er7(&self) -> String

Write the message back as ER7.

For a message parsed and not modified this reproduces the input, differing only where the input was not canonical (other segment terminators, blank lines, leading whitespace) — that guarantee is er7’s, and this crate does not weaken it.

pub fn to_er7_with(&self, options: RenderOptions) -> String

Write the message back as ER7, choosing the segment terminator; see er7::RenderOptions.

pub fn tree(&self) -> Node

The whole message as a navigable tree, with segments grouped into the message structure when they fit it and left flat when they do not. See crate::generic for the naming rules.

pub fn tree_with_options(&self, grouped: bool) -> Node

The message as a tree, with message-structure grouping optionally suppressed. A flat tree is one node per segment under the root, and is what a caller who navigates by segment name wants.

pub fn layout(&self) -> Option<Vec<Layout>>

How this message’s segments fit its structure, or None when the dictionary has no grammar for it or the segments do not fit.

pub fn get(&self, path: &str) -> Result<Option<String>, Error>

The value at path, e.g. PID-5.1, OBX[2]-5, MSH-9.3.

Returns the decoded text of the first match, or None when the path names nothing in this message. Path syntax is er7’s; see er7::Path.

Errors

Error::Path when path is not a valid HL7 path.

pub fn get_all(&self, path: &str) -> Result<Vec<String>, Error>

Every value matching path. A path that omits an occurrence or a repetition matches all of them, so OBX-5 reads every result in the message in one call.

Errors

Error::Path when path is not a valid HL7 path.

pub fn repetitions(&self, path: &str) -> Result<Vec<String>, Error>

Every repetition of the field at path, in message order.

This differs from Message::get_all at exactly one point: a path that names a whole field, such as PID-3, is one value to er7 — the field’s text, repetition separators and all — because that is what the field is. Here it is the repetitions, because a caller asking for a list of them is asking about 241900~99~7 as three identifiers rather than one string. Paths that already name a repetition or a component behave as Message::get_all.

let message = hl7_2::parse("MSH|^~\\&|A||||1||ADT^A01|1|P|2.5\rPID|1||241900~99~7")?;
assert_eq!(message.repetitions("PID-3")?, ["241900", "99", "7"]);
assert_eq!(message.get("PID-3")?.as_deref(), Some("241900~99~7"));

Errors

Error::Path when path is not a valid HL7 path.

pub fn type_of(&self, path: &str) -> Result<Option<String>, Error>

The data type the dictionary gives the field at path, resolving OBX-5 through OBX-2. None when the segment or field is unknown.

Errors

Error::Path when path is not a valid HL7 path.

pub fn set(&mut self, path: &str, value: &str) -> Result<(), Error>

Set the value at path, creating whatever the path names and the message does not yet have.

value is data, not wire format: delimiters inside it are escaped, so setting SMITH^JOHN writes one component containing a literal caret. Use Message::set_er7 to write text that is already encoded, and note that setting a level replaces everything beneath it — set("PID-5", ...) discards the components PID-5 had.

The segment must already exist; Message::append_segment and crate::Builder create segments.

let mut message = hl7_2::parse("MSH|^~\\&|A||||1||ADT^A01|1|P|2.5\rPID|1")?;
message.set("PID-5.1", "SMITH")?;
message.set("PID-5.2", "JOHN")?;
assert_eq!(message.get("PID-5")?.as_deref(), Some("SMITH^JOHN"));

Errors

Error::Path when path is not a valid HL7 path, or names a position that cannot be written.

pub fn set_er7(&mut self, path: &str, er7_text: &str) -> Result<(), Error>

Set the value at path to text that is already ER7-encoded, so its delimiters keep their structural meaning: set_er7("PID-5", "SMITH^JOHN") writes two components.

The text is parsed only down to the levels the path leaves open — writing to PID-5.1.2 treats the text as a single subcomponent value, because there is no level left for a delimiter to divide.

Errors

Error::Path when path is not a valid HL7 path, or names a position that cannot be written.

pub fn set_null(&mut self, path: &str) -> Result<(), Error>

Set the value at path to the HL7 explicit null "", which tells the receiver to clear the value rather than leave it alone. This is not the same as Message::clear.

Errors

Error::Path when path is not a valid HL7 path, or names a position that cannot be written.

pub fn clear(&mut self, path: &str) -> Result<(), Error>

Empty the value at path, as if the sender had never populated it. Compare Message::set_null, which says “clear this” out loud.

Clearing what is already absent does nothing and succeeds — it does not create the empty field it would then be emptying, and it does not fail on a missing segment. That is what makes writing an Option::None in struct mode a no-op rather than a message full of empty components.

Errors

Error::Path when path is not a valid HL7 path, or names a position that cannot be written.

pub fn append_segment(&mut self, name: &str) -> &mut Segment

Append an empty segment named name and return it for populating.

let mut message = hl7_2::parse("MSH|^~\\&|A||||1||ADT^A01|1|P|2.5")?;
message.append_segment("PID");
message.set("PID-3.1", "241900")?;
assert!(message.to_er7().ends_with("\rPID|||241900"));

pub fn insert_segment(&mut self, index: usize, name: &str) -> &mut Segment

Insert an empty segment named name at index in the segment list, clamped to the end. Inserting is how a segment lands in the place its structure expects rather than after everything else.

pub fn remove_segment( &mut self, name: &str, occurrence: usize, ) -> Option<Segment>

Remove the occurrence-th (1-based) segment named name, returning it. The MSH header cannot be removed.

pub fn remove_segments(&mut self, name: &str) -> usize

Remove every segment named name, returning how many went. The MSH header is never removed.

pub fn validate(&self) -> Vec<Diagnostic>

Check this message against its dictionary; see crate::validate.

Never fails and never changes the message: it reports. Parsing with Options::strict runs the same check and turns any Severity::Error into a parse failure.

pub fn decode<T: FromHl7>(&self) -> Result<T, Error>

Decode into a type that implements crate::FromHl7 — struct mode.

use hl7_2::FromHl7;

#[derive(FromHl7)]
struct Patient {
    #[hl7("PID-3.1")]
    id: String,
    #[hl7("PID-5.1.1")]
    family_name: String,
}

let message = hl7_2::parse("MSH|^~\\&|A||||1||ADT^A01|1|P|2.5\rPID|1||241900||SMITH^JOHN")?;
let patient: Patient = message.decode()?;
assert_eq!(patient.id, "241900");
assert_eq!(patient.family_name, "SMITH");

Errors

Whatever the type’s FromHl7 implementation reports: a path it could not read, or a value it could not convert.

Trait Implementations

impl Clone for Message

fn clone(&self) -> Message

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Message

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Message

fn fmt(&self, f: &mut Formatter<'_>) -> Result

The message as ER7; see Message::to_er7.