Dicom.P10.Stream.Source (Dicom v0.9.1)

Data source abstraction for the streaming DICOM parser.

Provides a uniform interface over binary buffers and file I/O with read-ahead buffering. The source supports three operations:

ensure/2 -- guarantee N bytes are available in the buffer
consume/2 -- consume N bytes from the buffer
peek/2 -- read N bytes without consuming

Source Types

Binary: wraps an in-memory binary, no I/O
File: reads from a file handle with configurable read-ahead buffering

Stability

This module may change. It is an internal implementation detail of the streaming parser and should not be relied on directly by consumers.

Summary

Types

io_device()

t()

Functions

available(source)

Returns the number of bytes currently available in the buffer.

bytes_consumed(source)

Returns the total bytes consumed from this source.

consume(source, n)

Consumes n bytes from the buffer, returning them and the updated source.

consume_until(source, marker)

Consumes bytes until marker is found, excluding the marker from the returned data.

consume_until_required(source, marker)

Consumes bytes until marker is found, excluding the marker from the returned data.

ensure(source, n)

Ensures at least n bytes are available in the buffer.

eof?(arg1)

Returns true if the source is exhausted (EOF and empty buffer).

from_binary(binary)

Creates a source from an in-memory binary.

from_io(io, opts \\ [])

Creates a source from an open file handle (opened in :raw, :binary, :read mode).

peek(arg1, n)

Peeks at the next n bytes without consuming them.

Types

io_device()

@type io_device() :: pid() | {:file_descriptor, atom(), term()}

t()

@type t() :: %Dicom.P10.Stream.Source{
  buffer: binary(),
  io: :eof | io_device() | nil,
  offset: non_neg_integer(),
  read_ahead: pos_integer()
}

Functions

available(source)

@spec available(t()) :: non_neg_integer()

Returns the number of bytes currently available in the buffer.

bytes_consumed(source)

@spec bytes_consumed(t()) :: non_neg_integer()

Returns the total bytes consumed from this source.

consume(source, n)

@spec consume(t(), non_neg_integer()) :: {:ok, binary(), t()}

Consumes n bytes from the buffer, returning them and the updated source.

consume_until(source, marker)

@spec consume_until(t(), binary()) :: {:ok, binary(), t()}

Consumes bytes until marker is found, excluding the marker from the returned data.

If the marker is not found before EOF, consumes and returns the remaining buffer.

consume_until_required(source, marker)

@spec consume_until_required(t(), binary()) ::
  {:ok, binary(), t()} | {:error, :unexpected_end}

Consumes bytes until marker is found, excluding the marker from the returned data.

Returns {:error, :unexpected_end} if EOF is reached before the marker appears.

ensure(source, n)

@spec ensure(t(), non_neg_integer()) :: {:ok, t()} | {:error, :unexpected_end}

Ensures at least n bytes are available in the buffer.

Returns {:ok, source} if the buffer has >= n bytes after filling, or {:error, :unexpected_end} if the source is exhausted.

eof?(arg1)

@spec eof?(t()) :: boolean()

Returns true if the source is exhausted (EOF and empty buffer).

from_binary(binary)

@spec from_binary(binary()) :: t()

Creates a source from an in-memory binary.

from_io(io, opts \\ [])

@spec from_io(
  io_device(),
  keyword()
) :: t()

Creates a source from an open file handle (opened in :raw, :binary, :read mode).

Options

:read_ahead -- preferred read-ahead buffer size in bytes (default: 65536)

peek(arg1, n)

@spec peek(t(), non_neg_integer()) :: {:ok, binary()} | {:error, :unexpected_end}

Peeks at the next n bytes without consuming them.