IOData

A protocol for efficiently working with data (like binaries and iolists) with minimal copying.

Implementations are provided for

• binaries
• iolists
• files (both regular and :raw handles)
• slices of other iodata

Usage

Splitting a binary or iolist at a given index:

iex> IOData.split!("hello world", 5)
{"hello", " world"}

iex> IOData.split!(["h", "ello", [[" "], "world"]], 5)
{["h", "ello"], [[[" "], "world"]]}

Slicing out a section of a binary or iolist:

iex> IOData.to_iodata!("hello world", 4, 5)
"o wor"

iex> IOData.to_iodata!(["h", "ello", [[" "], "world"]], 4, 5)
["o", " ", "wor"]

Slicing out a section of a binary or iolist while converting it to a binary:

iex> IOData.to_binary!("hello world", 4, 5)
"o wor"

iex> IOData.to_binary!(["h", "ello", [[" "], "world"]], 4, 5)
"o wor"

Determining whether an IOData has at least n bytes (without counting them all):

iex> IOData.at_least?("hello world", 4)
true

iex> IOData.at_least?(["h", "ello", [[" "], "world"]], 4)
true

Working with files without reading them up front — slice!/3 does no I/O and split!/2 only checks the file size; reads touch just the requested range. Open files in :binary mode; :raw handles skip the file-server process (roughly 3-5x cheaper per read) but can only be used from the process that opened them:

iex> {:ok, file} = :file.open(path, [:read, :binary, :raw])
iex> {header, rest} = IOData.split!(file, 64)
iex> IOData.to_binary!(header)
<<...64 bytes...>>