iodata

[![Build Status](https://github.com/jallum/iodata/workflows/CI/badge.svg)](https://github.com/jallum/iodata/actions) [![Coverage Status](https://coveralls.io/repos/github/jallum/iodata/badge.svg?branch=main)](https://coveralls.io/github/jallum/iodata?branch=main) [![Hex.pm](https://img.shields.io/hexpm/v/iodata.svg)](https://hex.pm/packages/iodata) [![Documentation](https://img.shields.io/badge/documentation-gray)](https://hexdocs.pm/iodata/)

---

# 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:

```elixir
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:

```elixir
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:

```elixir
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_):

```elixir
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:

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