# `HL7v2.Standard.Version`
[🔗](https://github.com/Balneario-de-Cofrentes/hl7v2/blob/v3.10.1/lib/hl7v2/standard/version.ex#L1)

HL7 v2.x version utilities.

Pure helpers for normalizing, comparing, and gating on HL7 version strings.

This module is intentionally lightweight and side-effect free. It is the
foundation for future version-aware validation rules — callers can use it
today to detect, normalize, and compare versions, even though no validation
rule yet branches on version.

## Supported range

The library targets HL7 v2.3 through v2.8 inclusive. `supported?/1` returns
`true` for any canonical version that falls within that range.

## Examples

    iex> HL7v2.Standard.Version.normalize("v2.5.1")
    "2.5.1"

    iex> HL7v2.Standard.Version.compare("2.5", "2.7")
    :lt

    iex> HL7v2.Standard.Version.at_least?("2.7", "2.5")
    true

    iex> HL7v2.Standard.Version.supported?("2.5.1")
    true

# `at_least?`

```elixir
@spec at_least?(binary(), binary()) :: boolean()
```

Returns `true` when `version` is greater than or equal to `target`.

## Examples

    iex> HL7v2.Standard.Version.at_least?("2.7", "2.5")
    true

    iex> HL7v2.Standard.Version.at_least?("2.5.1", "2.5.1")
    true

    iex> HL7v2.Standard.Version.at_least?("2.5", "2.7")
    false

# `compare`

```elixir
@spec compare(binary(), binary()) :: :lt | :eq | :gt
```

Compares two HL7 version strings, returning `:lt`, `:eq`, or `:gt`.

Inputs are normalized first via `normalize/1`. Missing trailing components
are treated as `0`, so `"2.5"` and `"2.5.0"` compare equal.

Raises `ArgumentError` if either input is not a recognizable version.

## Examples

    iex> HL7v2.Standard.Version.compare("2.5", "2.7")
    :lt

    iex> HL7v2.Standard.Version.compare("2.7", "2.5.1")
    :gt

    iex> HL7v2.Standard.Version.compare("2.5", "2.5.0")
    :eq

    iex> HL7v2.Standard.Version.compare("v2.5.1", "2.5.1")
    :eq

# `normalize`

```elixir
@spec normalize(binary() | nil) :: binary() | nil
```

Normalizes an HL7 version string to its canonical form.

Strips an optional `v`/`V` prefix and surrounding whitespace, and validates
that the result looks like a dotted numeric version (e.g. `2`, `2.5`,
`2.5.1`). Returns the canonical string on success, or `nil` for `nil`,
empty, or unrecognized inputs.

## Examples

    iex> HL7v2.Standard.Version.normalize("2.5.1")
    "2.5.1"

    iex> HL7v2.Standard.Version.normalize("v2.7")
    "2.7"

    iex> HL7v2.Standard.Version.normalize("  V2.5  ")
    "2.5"

    iex> HL7v2.Standard.Version.normalize(nil)
    nil

    iex> HL7v2.Standard.Version.normalize("garbage")
    nil

# `supported?`

```elixir
@spec supported?(binary() | nil) :: boolean()
```

Returns `true` when the given version is within the library's supported
range (HL7 v2.3 through v2.8 inclusive).

Inputs are normalized first. Unparseable, missing, or out-of-range versions
return `false`.

## Examples

    iex> HL7v2.Standard.Version.supported?("2.5.1")
    true

    iex> HL7v2.Standard.Version.supported?("2.3")
    true

    iex> HL7v2.Standard.Version.supported?("2.8")
    true

    iex> HL7v2.Standard.Version.supported?("2.2")
    false

    iex> HL7v2.Standard.Version.supported?("3.0")
    false

    iex> HL7v2.Standard.Version.supported?(nil)
    false

---

*Consult [api-reference.md](api-reference.md) for complete listing*