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

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:

def deps do
  [{:extractable, "~> 1.0.0"}]
end

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at 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.