# `Dicom.Value`
[🔗](https://github.com/Balneario-de-Cofrentes/dicom/blob/v0.9.1/lib/dicom/value.ex#L1)

DICOM value decoding and encoding.

Converts between raw binary data element values and native Elixir types
based on the Value Representation (VR).

Reference: DICOM PS3.5 Section 6.2.

# `decode`

```elixir
@spec decode(binary(), Dicom.VR.t()) :: term()
```

Decodes a raw binary value to a native Elixir type based on VR.

Returns `nil` for empty binaries.

# `decode`

```elixir
@spec decode(binary(), Dicom.VR.t(), :little | :big) :: term()
```

Decodes a raw binary value using the given endianness.

# `encode`

```elixir
@spec encode(term(), Dicom.VR.t()) :: binary()
```

Encodes a native Elixir value to binary for a given VR.

# `encode`

```elixir
@spec encode(term(), Dicom.VR.t(), :little | :big) :: binary()
```

Encodes a native Elixir value using the given endianness.

# `from_date`

```elixir
@spec from_date(Date.t()) :: String.t()
```

Converts an Elixir `Date` to a DICOM DA string ("YYYYMMDD").

## Examples

    iex> Dicom.Value.from_date(~D[2024-03-15])
    "20240315"

# `from_datetime`

```elixir
@spec from_datetime(DateTime.t() | NaiveDateTime.t()) :: String.t()
```

Converts a `DateTime` or `NaiveDateTime` to a DICOM DT string.

## Examples

    iex> Dicom.Value.from_datetime(~N[2024-03-15 14:30:22])
    "20240315143022"

# `from_time`

```elixir
@spec from_time(Time.t()) :: String.t()
```

Converts an Elixir `Time` to a DICOM TM string.

Includes fractional seconds if microsecond precision > 0.

## Examples

    iex> Dicom.Value.from_time(~T[14:30:22])
    "143022"

# `to_date`

```elixir
@spec to_date(String.t()) :: {:ok, Date.t()} | {:error, :invalid_date}
```

Converts a DICOM DA string ("YYYYMMDD") to an Elixir `Date`.

## Examples

    iex> Dicom.Value.to_date("20240315")
    {:ok, ~D[2024-03-15]}

    iex> Dicom.Value.to_date("invalid")
    {:error, :invalid_date}

# `to_datetime`

```elixir
@spec to_datetime(String.t()) ::
  {:ok, DateTime.t() | NaiveDateTime.t()} | {:error, :invalid_datetime}
```

Converts a DICOM DT string to `DateTime` (with TZ offset) or `NaiveDateTime` (without).

## Examples

    iex> Dicom.Value.to_datetime("20240315143022")
    {:ok, ~N[2024-03-15 14:30:22]}

# `to_time`

```elixir
@spec to_time(String.t()) :: {:ok, Time.t()} | {:error, :invalid_time}
```

Converts a DICOM TM string to an Elixir `Time`.

Supports full ("HHMMSS.FFFFFF") and partial ("HHMM", "HH") formats.

## Examples

    iex> Dicom.Value.to_time("143022")
    {:ok, ~T[14:30:22]}

    iex> Dicom.Value.to_time("1430")
    {:ok, ~T[14:30:00]}

---

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