IOData protocol (iodata v0.7.0)

A protocol for working with various data types such as binaries and iolists.

This protocol defines a set of functions for performing common operations on data, including:

  • Checking if the data has at least a specified number of bytes.
  • Retrieving the size of the data in bytes.
  • Splitting the data at a specified byte offset.
  • Checking if the data starts with a given binary prefix.
  • Converting the data to iodata or binary formats.
  • Extracting portions of the data as iodata or binary.

Implementations of this protocol should be efficient and avoid unnecessary copying of data whenever possible.

Summary

Functions

Checks if the given data has at least the specified number of bytes.

Returns the total size, in bytes, of the given data.

Splits data at the specified byte offset if possible, returning either {:ok, {prefix, suffix}} or an error tuple.

Checks if the given data starts with the specified binary prefix.

Converts the entire data into a binary.

Extracts a portion of the data as a binary, starting at 'start' for 'count' bytes. Returns an ok/error tuple.

Same as to_binary/0 but raises an error if the data is insufficient.

Same as to_binary/3 but raises an error if the data is insufficient.

Returns the data in iodata form without modifying it.

Extracts a portion of the data as iodata, starting at 'start' for 'count' bytes. Returns an ok/error tuple.

Same as to_iodata/0 but raises an error if the data is insufficient.

Same as to_iodata/3 but raises an error if the data is insufficient.

Types

t()

@type t() :: term()

Functions

at_least?(data, n_bytes)

@spec at_least?(t(), n_bytes :: non_neg_integer()) :: boolean()

Checks if the given data has at least the specified number of bytes.

size(data)

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

Returns the total size, in bytes, of the given data.

split(data, at)

@spec split(t(), non_neg_integer()) ::
  {:ok, {t(), t()}} | {:error, :insufficient_data}

Splits data at the specified byte offset if possible, returning either {:ok, {prefix, suffix}} or an error tuple.

starts_with?(data, binary)

@spec starts_with?(t(), binary()) :: boolean()

Checks if the given data starts with the specified binary prefix.

to_binary(data)

@spec to_binary(t()) :: {:ok, binary()} | {:error, reason :: term()}

Converts the entire data into a binary.

to_binary(data, start, count)

@spec to_binary(t(), start :: non_neg_integer(), count :: non_neg_integer()) ::
  {:ok, binary()} | {:error, :insufficient_data}

Extracts a portion of the data as a binary, starting at 'start' for 'count' bytes. Returns an ok/error tuple.

to_binary!(data)

@spec to_binary!(t()) :: binary()

Same as to_binary/0 but raises an error if the data is insufficient.

to_binary!(data, start, count)

@spec to_binary!(t(), start :: non_neg_integer(), count :: non_neg_integer()) ::
  binary()

Same as to_binary/3 but raises an error if the data is insufficient.

to_iodata(data)

@spec to_iodata(t()) :: {:ok, iodata()} | {:error, reason :: term()}

Returns the data in iodata form without modifying it.

to_iodata(data, start, count)

@spec to_iodata(t(), start :: non_neg_integer(), count :: non_neg_integer()) ::
  {:ok, t()} | {:error, :insufficient_data}

Extracts a portion of the data as iodata, starting at 'start' for 'count' bytes. Returns an ok/error tuple.

to_iodata!(data)

@spec to_iodata!(t()) :: iodata()

Same as to_iodata/0 but raises an error if the data is insufficient.

to_iodata!(data, start, count)

@spec to_iodata!(t(), start :: non_neg_integer(), count :: non_neg_integer()) ::
  iodata()

Same as to_iodata/3 but raises an error if the data is insufficient.