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

An ordered collection of DICOM Data Elements.

A Data Set represents the core content of a DICOM object — all the
attributes describing a patient, study, series, or instance. Elements
are stored ordered by tag for conformant serialization.

## Usage

    data_set = Dicom.DataSet.new()
    data_set = Dicom.DataSet.put(data_set, {0x0010, 0x0010}, :PN, "DOE^JOHN")
    "DOE^JOHN" = Dicom.DataSet.get(data_set, {0x0010, 0x0010})

Reference: DICOM PS3.5 Section 7.

# `t`

```elixir
@type t() :: %Dicom.DataSet{
  elements: %{required(Dicom.DataElement.tag()) => Dicom.DataElement.t()},
  file_meta: %{required(Dicom.DataElement.tag()) => Dicom.DataElement.t()}
}
```

# `decoded_value`

```elixir
@spec decoded_value(t(), Dicom.DataElement.tag()) :: term() | nil
```

Gets a VR-decoded value for a tag using `Dicom.Value.decode/2`.

Returns `nil` if the tag is absent or if a fixed-width numeric payload
cannot be decoded safely.

# `delete`

```elixir
@spec delete(t(), Dicom.DataElement.tag()) :: t()
```

Deletes a data element from the data set by tag.

# `fetch`

```elixir
@spec fetch(t(), Dicom.DataElement.tag()) :: {:ok, term()} | :error
```

Fetches the value of a data element by tag.

Returns `{:ok, value}` or `:error`. Implements `Access.fetch/2`.

# `from_list`

```elixir
@spec from_list([{Dicom.DataElement.tag(), Dicom.VR.t(), term()}]) :: t()
```

Builds a data set from a list of `{tag, vr, value}` tuples.

## Examples

    iex> ds = Dicom.DataSet.from_list([{{0x0010, 0x0010}, :PN, "DOE^JOHN"}])
    iex> Dicom.DataSet.get(ds, {0x0010, 0x0010})
    "DOE^JOHN"

# `get`

```elixir
@spec get(t(), Dicom.DataElement.tag()) :: term() | nil
```

Gets the value of a data element by tag.

Returns `nil` if the tag is not present.

# `get`

```elixir
@spec get(t(), Dicom.DataElement.tag(), term()) :: term()
```

Gets the value of a data element by tag, returning `default` if absent.

# `get_and_update`

Gets and updates a value in the data set. Implements `Access.get_and_update/3`.

The function receives the current value (or nil) and must return
`{current_value, new_value}` or `:pop`.

# `get_element`

```elixir
@spec get_element(t(), Dicom.DataElement.tag()) :: Dicom.DataElement.t() | nil
```

Gets the raw DataElement struct by tag.

Returns `nil` if the tag is not present.

# `has_tag?`

```elixir
@spec has_tag?(t(), Dicom.DataElement.tag()) :: boolean()
```

Returns true if the tag is present in the data set.

# `merge`

```elixir
@spec merge(t(), t()) :: t()
```

Merges two data sets. Elements in `other` take precedence.

# `new`

```elixir
@spec new() :: t()
```

Creates a new empty data set.

# `pop`

Pops a value from the data set. Implements `Access.pop/2`.

# `put`

```elixir
@spec put(t(), Dicom.DataElement.tag(), Dicom.VR.t(), term()) :: t()
```

Puts a data element into the data set.

# `size`

```elixir
@spec size(t()) :: non_neg_integer()
```

Returns the number of elements in the data set (including file meta).

# `tags`

```elixir
@spec tags(t()) :: [Dicom.DataElement.tag()]
```

Returns all tags present in the data set.

# `to_map`

```elixir
@spec to_map(t()) :: map()
```

Converts the data set to a plain map of `tag => value`.

# `validate_private_tags`

```elixir
@spec validate_private_tags(t()) ::
  {:ok, t()} | {:error, [{Dicom.DataElement.tag(), :missing_creator}]}
```

Validates that every private data element has a corresponding creator element.

Delegates to `Dicom.PrivateTag.validate_creators/1`.
See `Dicom.PrivateTag` for details on PS3.6 Section 6.1.2.1.

---

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