HL7v2.Type behaviour (HL7v2 v3.10.1)

Base behaviour for HL7v2 data types.

Every data type module (primitive and composite) implements this behaviour, providing parse/1 and encode/1 for converting between wire-format representations and typed Elixir values.

Primitive types (ST, NM, DT, etc.) work with binaries. Composite types (CX, XPN, HD, etc.) work with lists of component strings and return/accept structs.

Sub-Component Separator

By default, sub-component fields are split/joined with &. When a message declares a non-default sub-component separator (e.g., $ in MSH-2 ^~\$), call with_sub_component_separator/2 to set it for the duration of a parse or encode operation. Composite types read the active separator via sub_component_separator/0.

Summary

Callbacks

encode(arg1)

Encodes a typed Elixir value back to wire format.

parse(arg1)

Parses a wire-format value into a typed Elixir value.

Functions

all_nil?(struct)

Returns true if every field in the given struct is nil.

encode_sub(module, struct)

Encodes a sub-component struct back to a sub-component-separated string.

encode_sub_ts(ts)

Encodes a sub-component TS or DTM value to a sub-component-separated string.

get_component(components, index)

Extracts a string value from a component, returning nil for empty/nil inputs.

pad_components(components, length)

Pads a list of components to the given length with nils.

parse_sub(module, value)

Parses a sub-component string into the given composite type's struct.

parse_sub_ts(value)

Parses a sub-component TS (Time Stamp) value.

sub_component_separator()

Returns the active sub-component separator string.

trim_trailing(components)

Trims trailing nil/empty values from a list of components for compact encoding.

with_sub_component_separator(sep, fun)

Executes fun with the given sub-component separator active.

Callbacks

encode(arg1)

@callback encode(struct() | binary() | nil) :: list() | binary()

Encodes a typed Elixir value back to wire format.

parse(arg1)

@callback parse(list() | binary()) :: struct() | binary() | nil

Parses a wire-format value into a typed Elixir value.

Functions

all_nil?(struct)

@spec all_nil?(struct()) :: boolean()

Returns true if every field in the given struct is nil.

Used after parsing a sub-component to decide whether the result is effectively empty and should be returned as nil.

Examples

iex> HL7v2.Type.all_nil?(%HL7v2.Type.HD{})
true

iex> HL7v2.Type.all_nil?(%HL7v2.Type.HD{namespace_id: "MRN"})
false

encode_sub(module, struct)

@spec encode_sub(module(), struct() | nil) :: binary()

Encodes a sub-component struct back to a sub-component-separated string.

Delegates to module.encode/1 and joins the result with the active sub-component separator.

Returns "" for nil input.

Examples

iex> HL7v2.Type.encode_sub(HL7v2.Type.HD, %HL7v2.Type.HD{namespace_id: "MRN", universal_id: "1.2.3", universal_id_type: "ISO"})
"MRN&1.2.3&ISO"

iex> HL7v2.Type.encode_sub(HL7v2.Type.HD, nil)
""

encode_sub_ts(ts)

@spec encode_sub_ts(HL7v2.Type.TS.t() | HL7v2.Type.DTM.t() | nil) :: binary()

Encodes a sub-component TS or DTM value to a sub-component-separated string.

Handles both %TS{} structs (encoded as sub-component list) and bare %DTM{} structs (encoded directly as a date-time string).

Returns "" for nil input.

Examples

iex> HL7v2.Type.encode_sub_ts(%HL7v2.Type.TS{time: %HL7v2.Type.DTM{year: 2026, month: 3, day: 22}})
"20260322"

iex> HL7v2.Type.encode_sub_ts(%HL7v2.Type.DTM{year: 2026, month: 3, day: 22})
"20260322"

iex> HL7v2.Type.encode_sub_ts(nil)
""

get_component(components, index)

@spec get_component(list(), non_neg_integer()) :: binary() | nil

Extracts a string value from a component, returning nil for empty/nil inputs.

Used internally by composite type parsers to normalize component access.

pad_components(components, length)

@spec pad_components(list(), non_neg_integer()) :: list()

Pads a list of components to the given length with nils.

parse_sub(module, value)

@spec parse_sub(module(), binary() | nil) :: struct() | nil

Parses a sub-component string into the given composite type's struct.

Splits value on the active sub-component separator, delegates to module.parse/1, and returns nil if all fields in the resulting struct are nil.

Returns nil for nil input.

Examples

iex> HL7v2.Type.parse_sub(HL7v2.Type.HD, "MRN&1.2.3&ISO")
%HL7v2.Type.HD{namespace_id: "MRN", universal_id: "1.2.3", universal_id_type: "ISO"}

iex> HL7v2.Type.parse_sub(HL7v2.Type.HD, nil)
nil

parse_sub_ts(value)

@spec parse_sub_ts(binary() | nil) :: HL7v2.Type.TS.t() | nil

Parses a sub-component TS (Time Stamp) value.

Like parse_sub/2 but uses the TS-specific nil check: a TS is considered nil when both time and degree_of_precision are nil.

Examples

iex> HL7v2.Type.parse_sub_ts("20260322143000")
%HL7v2.Type.TS{time: %HL7v2.Type.DTM{year: 2026, month: 3, day: 22, hour: 14, minute: 30, second: 0}}

iex> HL7v2.Type.parse_sub_ts(nil)
nil

sub_component_separator()

@spec sub_component_separator() :: binary()

Returns the active sub-component separator string.

Defaults to "&" when no separator context has been set via with_sub_component_separator/2.

trim_trailing(components)

@spec trim_trailing(list()) :: list()

Trims trailing nil/empty values from a list of components for compact encoding.

with_sub_component_separator(sep, fun)

@spec with_sub_component_separator(binary(), (-> result)) :: result
when result: term()

Executes fun with the given sub-component separator active.

The separator is stored in the process dictionary for the duration of fun and restored to its previous value afterwards. This is used by segment parse/encode to propagate the message's actual sub-component delimiter to all composite type helpers.