# Extractable
[](https://hex.pm/packages/extractable)
[](https://travis-ci.org/Qqwy/elixir-extractable)
A lightweight reusable Extractable protocol, allowing extracting elements one-at-a-time from a collection.
## Description
Extractable is a simple protocol that allows for the extraction of elements from a collection,
one element at a time.
This is the major difference with the Enumerable protocol:
Enumerable only works with whole collections at a time,
so extracting a few items and then returning the rest of the unconsumed collection is impossible.
This is exactly what Extractable _does_ allow.
Extractable is however slower if used repeatedly,
because the wrapping/unwrapping of certain structures has to happen once per extracted element,
rather than once per collection.
Extractable.extract/2 returns `{:ok, {item, collection}}` if it was possible to extract an item from the collection.
`:error` is returned when the `collection` is for instance (currently) empty.
What item is extracted depends on the collection: For collections where it matters, the most logical or efficient approach is taken.
Some examples:
- For Lists, the _head_ of the list is returned as item.
- For Maps, an arbitrary `{key, value}` is returned as item.
- For MapSets, an arbitrary value is returned as item.
- For Ranges the first item of the range is returned.
## Examples
```elixir
iex> Extractable.extract([])
:error
iex> Extractable.extract([1, 2, 3])
{:ok, {1, [2, 3]}}
iex> Extractable.extract(%{a: 1, b: 2, c: 3})
{:ok, {{:a, 1}, %{b: 2, c: 3}}}
iex> Extractable.extract(MapSet.new())
:error
iex> Extractable.extract(MapSet.new([1, 2, 3]))
{:ok, {1, #MapSet<[2, 3]>}}
iex> Extractable.extract(200..100)
{:ok, {200, 199..100}}
iex> Extractable.extract(42..42)
{:ok, {42, 43..42//1}}
```
## Installation
The package can be installed
by adding `extractable` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[{:extractable, "~> 1.0.0"}]
end
```
Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
be found at [https://hexdocs.pm/extractable](https://hexdocs.pm/extractable).
## Changelog
- 1.0.0 -
- Inclusion of `TypeCheck` for nice errors when the library is used incorrectly.
- Implementation for ranges.
- 0.2.1 - Fixing incorrect typespec on `extract/1` callback. Thank you, @brandonhamilton!
- 0.2.0 - Cleaner documentation.
- 0.1.0 - Initial release.
