MapList (passive_support v0.8.0)

This moduledoc is provided to give insight into the ideal working shape of the MapList. It is not yet implemented. There's literally nothing to see here as of now, besides this, what is very possibly the first ever recorded instance of technical documentation fiction.

Functions for interacting with a list of data in an indexed manner. Because Maps are not a lightweight structure, this module is recommended for edge cases in which normal traversal of a List would otherwise be too time inefficient for frequent tasks.

MapLists are implemented to behave as a List in almost all cases. The notable exception being that a MapList provides a tuple of {index, item} to its implementation of Enumerable, and always returns a MapList for further transformation. To get the list of items from a MapList, use MapList.values/1. You can also call MapList.to_list/1 to get a list of the {index, item} pairs.

iex> MapList.new(["Hello","elixir","world!"])
%MapList["Hello", "elixir", "world!"]

Since MapLists can't be destructured, functions are provided to apply transformations to them. Adding elements to either the head or the tail of a MapList can be done quickly, as indices will not need to be internally recalculated in these operations.

iex> map_list = MapList.push(MapList.new([1,2,3,4]), 5)
%MapList[1, 2, 3, 4, 5]
iex> map_list = MapList.unshift(map_list, 0)
%MapList[0, 1, 2, 3, 4, 5]

Removing elements from the head or tail is similarly fast.

iex> map_list = MapList.new(1..10)
%MapList[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
iex> {last, map_list} = MapList.pop(map_list)
{10, %MapList[1, 2, 3, 4, 5, 6, 7, 8, 9]}
iex> {first, map_list} = MapList.shift
{1, %MapList[2, 3, 4, 5, 6, 7, 8, 9]}

Replacing an element in the middle of the MapList is similarly uncostly, but inserting or removing an element from the middle of a MapList will cause the indices to be internally recalculated, to avoid requiring to traverse and ignore a sentinel value (or stop at the sentinel value, as parts of the :array module do).

iex> map_list = MapList.new(~W"Hello elixir world!")
...>  |> MapList.insert_at(1, "brave")
%MapList["Hello", "brave", "elixir", "world!"]
iex> map_list
...>  |> MapList.replace_at(1, "awesome")
%MapList["Hello", "awesome", "elixir", "world!"]