Struct Segment 

#[non_exhaustive]
pub struct Segment<'a> {
    pub tag: Cow<'a, str>,
    pub span: Span,
    pub tag_span: Span,
    pub elements: Vec<Element<'a>>,
}

A single EDIFACT segment.

Borrows its text from the parsed input where it can, and owns it where it cannot: from_bytes yields Segment<'input>, while from_reader yields Segment<'static> — aliased as OwnedSegment. Covariance in 'a means one is accepted wherever the other is, so every API in this crate takes a single shape.

#[non_exhaustive]: build one with Segment::new rather than a struct literal, so a future field stays additive. The fields stay public, so reading and .. destructuring are unaffected.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

tag: Cow<'a, str>

Segment tag — three ASCII uppercase letters for anything this crate parses.

span: Span

Span covering the whole segment payload.

tag_span: Span

Span covering only the segment tag.

elements: Vec<Element<'a>>

Segment elements in positional order.

Implementations

impl<'a> Segment<'a>

pub fn new(tag: impl Into<Cow<'a, str>>, elements: Vec<Element<'a>>) -> Self

Build a segment from a tag and its data elements.

Spans default to Span::default, which is what a segment synthesised from a non-EDIFACT source should carry — there is no input to point at. Use with_spans when there is.

The tag is not checked here; it is checked when the segment is written. A tag is emitted verbatim, so one the parser would reject is refused as EdifactError::InvalidSegmentTag by Writer::write_segment rather than written out as bytes that do not read back.

Example

use edifact_rs::{Element, Segment, segments_to_bytes};

let segment = Segment::new("BGM", vec![Element::of(&["220"])]);
assert_eq!(segments_to_bytes(&[segment])?, b"BGM+220'".to_vec());

pub fn with_spans(self, span: Span, tag_span: Span) -> Self

Set the segment and tag spans.

pub fn tag(&self) -> &str

The segment tag as a plain &str.

segment.tag compares directly against a string literal (segment.tag == "BGM"); this is for the places that need a &str, such as a match.

pub fn get_element(&self, n: usize) -> Option<&Element<'a>>

Return the element at position n (0-indexed), if it exists.

pub fn element_str(&self, n: usize) -> Option<&str>

Shorthand: component 0 of element n — the most common access pattern.

pub fn component_str(&self, elem: usize, comp: usize) -> Option<&str>

Get component comp of element elem (both 0-based), or None if absent.

pub fn element_span(&self, n: usize) -> Option<Span>

Return the byte span of the element at position n, if it exists.

pub fn repeated_component( &self, element: usize, component: usize, ) -> impl Iterator<Item = &str>

Read component component from every occurrence of element element.

Yields nothing when the element is absent. See Element::repeated_component.

Example

// `UNA` position 050 declares `*` as the repetition separator.
let segments: Vec<_> = edifact_rs::from_bytes(b"UNA:+.?*'RFF+ON:1*ON:2*ON:3'")
    .collect::<Result<Vec<_>, _>>()?;

let references: Vec<&str> = segments[0].repeated_component(0, 1).collect();
assert_eq!(references, ["1", "2", "3"]);

pub fn offset(self, delta: usize) -> Self

Shift every stored span by delta bytes.

pub fn into_owned(self) -> OwnedSegment

Detach this segment from the input buffer, cloning any borrowed text.

Use it to keep a segment alive past the buffer it was parsed from.

pub fn required_element(&self, idx: usize) -> Result<&str, EdifactError>

Read element idx, treating an empty value as absent.

EDIFACT lets an element be syntactically present but empty (SEG++'). A mandatory data element must carry a value, so this reports EdifactError::MissingRequiredElement for both cases.

Errors

EdifactError::MissingRequiredElement when the element is absent or empty.

pub fn optional_element(&self, idx: usize) -> Option<&str>

Read element idx, treating an empty value as absent.

pub fn required_component( &self, elem: usize, comp: usize, ) -> Result<&str, EdifactError>

Read component comp of element elem, treating an empty value as absent.

Errors

EdifactError::MissingRequiredElement when the element itself is absent, and EdifactError::MissingRequiredComponent when the element is present but the component is absent or empty. The distinction matters: the first says the segment is too short, the second that one composite is incomplete.

pub fn optional_component(&self, elem: usize, comp: usize) -> Option<&str>

Read component comp of element elem, treating an empty value as absent.

pub fn parsed_element<T: FromStr>(&self, idx: usize) -> Result<T, EdifactError>

Read element idx and parse it into T.

Errors

As required_element, plus EdifactError::InvalidText when the value does not parse.

pub fn value_at(&self, path: ElementPath) -> Option<&str>

Read the value at an already-resolved ElementPath.

Use this when the same path is reused across many segments — resolve once with SegmentLayout::resolve_code, then read without repeating the lookup.

pub fn span_at(&self, path: ElementPath) -> Option<Span>

Byte span of the value at an already-resolved ElementPath.

pub fn value_by_code<L: SegmentLayout + ?Sized>( &self, layout: &L, data_element: &str, ) -> Result<Option<&str>, EdifactError>

Read a value by its UN/EDIFACT data element identifier.

Positional access (seg.element_str(4)) fails silently when the index is wrong: it reads a different, usually still-plausible value. Code-addressed access cannot — a stale or mistyped identifier is a EdifactError::UnknownDataElement, checked against the directory.

Ok(None) means the identifier is valid for this segment but the value is absent from this instance, which is the normal state for a conditional element.

Performance

Each call scans the layout for the identifier. That is a handful of short string comparisons and fine for one-off reads, but when pulling the same identifier out of many segments, resolve once with SegmentLayout::resolve_code and read with value_at.

Example

use edifact_rs::{ComponentRef, ElementRef, SegmentDefinition, Status};

static C507: &[ComponentRef] = &[
    ComponentRef::new(1, "2005", Status::Mandatory),
    ComponentRef::new(2, "2380", Status::Conditional),
    ComponentRef::new(3, "2379", Status::Conditional),
];
static DTM_ELEMENTS: &[ElementRef] =
    &[ElementRef::composite(1, "C507", Status::Mandatory, 1, C507)];
static DTM: SegmentDefinition =
    SegmentDefinition::new("DTM", "Date/time/period", DTM_ELEMENTS);

let segments: Vec<_> = edifact_rs::from_bytes(b"DTM+137:20260101:102'")
    .collect::<Result<Vec<_>, _>>()?;
let dtm = &segments[0];

assert_eq!(dtm.value_by_code(&DTM, "2380")?, Some("20260101"));
// A data element that this segment does not define is a hard error,
// not a wrong-but-quiet read.
assert!(dtm.value_by_code(&DTM, "3055").is_err());

Errors

Returns EdifactError::SegmentLayoutMismatch when layout describes a different segment tag, EdifactError::UnknownDataElement when the identifier is not in the definition, and EdifactError::AmbiguousDataElement when it appears more than once.

pub fn span_by_code<L: SegmentLayout + ?Sized>( &self, layout: &L, data_element: &str, ) -> Result<Option<Span>, EdifactError>

Byte span of a value addressed by its UN/EDIFACT data element identifier.

Use this to attach a precise Span to a ValidationIssue without hand-counting indices.

Errors

As value_by_code.

pub fn element_by_code<L: SegmentLayout + ?Sized>( &self, layout: &L, data_element: &str, ) -> Result<Option<&Element<'a>>, EdifactError>

Return the whole Element addressed by a data element identifier.

When the identifier names a component inside a composite, the enclosing composite element is returned.

Errors

As value_by_code.

Trait Implementations

impl<'a> Clone for Segment<'a>

fn clone(&self) -> Segment<'a>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for Segment<'a>

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

Formats the value using the given formatter.

impl<'a> Eq for Segment<'a>

impl<'a> PartialEq for Segment<'a>

fn eq(&self, other: &Segment<'a>) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<'a> StructuralPartialEq for Segment<'a>