Arrays.Protocol protocol (Arrays v2.0.0) View Source

This protocol is implemented by all array types.

Do not call functions in this module directly if you want to use an array in your code. Instead, use the functions in the Arrays module, which will use the methods of this protocol.

Link to this section Summary

Types

array()

Any datatype implementing the Arrays.Protocol.

index()

An array index can be either a nonnegative index (up to the size of the array), or a negative index (then we count backwards from the size.)

options()

A list of options passed to empty/1.

t()

value()

Type of the kind of value stored in the array. In practice, arrays can store anything so this is an alias for any.

Functions

append(array, item)

Appends ('pushes') a single element to the end of the array.

empty(options)

Should create a new instance of your custom array type.

extract(array)

Extracts ('pops') a single element from the end of the array.

get(array, index)

Retrieves the value stored in array of the element at index.

map(array, fun)

Maps a function over an array, returning a new array.

reduce(array, acc, fun)

Reduce an array to a single value, by calling the provided accumulation function for each element, left-to-right.

reduce_right(array, acc, fun)

Reduce an array to a single value, by calling the provided accumulation function for each element, right-to-left.

replace(array, index, item)

Replaces the element in array at index with value.

resize(array, size, default)

Changes the size of the array.

size(array)

The number of elements in the array.

slice(array, start_index, amount)

Return a contiguous slice of some elements in the array.

to_list(array)

Transforms the array into a list.

Link to this section Types

array()

Specs

array() :: t()

Any datatype implementing the Arrays.Protocol.

index()

Specs

index() :: integer()

An array index can be either a nonnegative index (up to the size of the array), or a negative index (then we count backwards from the size.)

options()

Specs

options() :: Keyword.t()

A list of options passed to empty/1.

What options are recognized by a particular implementation varies.

t()

Specs

t() :: term()

value()

Specs

value() :: any()

Type of the kind of value stored in the array. In practice, arrays can store anything so this is an alias for any.

Link to this section Functions

append(array, item)

Specs

append(array(), item :: any()) :: array()

Appends ('pushes') a single element to the end of the array.

Called by Arrays.append/2

empty(options)

Specs

empty(options()) :: array()

Should create a new instance of your custom array type.

This is called internally by functions such as Arrays.new/0 and Arrays.empty/1.

NOTE: This function will not be dispatched by normal protocol handling. It will be called directly: The first (and only) parameter will be a list of options.

c.f. t:options.

extract(array)

Specs

extract(array()) :: {:ok, {item :: any(), array()}} | {:error, :empty}

Extracts ('pops') a single element from the end of the array.

Called by Arrays.extract/1

get(array, index)

Specs

get(array(), index()) :: any()

Retrieves the value stored in array of the element at index.

Called by Arrays.get/2

map(array, fun)

Specs

map(array(), (index(), current_value :: value() -> updated_value :: value())) ::
  array()

Maps a function over an array, returning a new array.

Called by Arrays.map/2

reduce(array, acc, fun)

Specs

reduce(array(), acc :: any(), (item :: any(), acc :: any() -> any())) :: array()

Reduce an array to a single value, by calling the provided accumulation function for each element, left-to-right.

Note that fun takes the accumulator as second (right) parameter and the item as first (left) parameter.

Called by Arrays.reduce/3

reduce_right(array, acc, fun)

Specs

reduce_right(array(), acc :: any(), (acc :: any(), item :: any() -> any())) ::
  array()

Reduce an array to a single value, by calling the provided accumulation function for each element, right-to-left.

Note that fun takes the accumulator as first (left) parameter and the item as second (right) parameter.

Called by Arrays.reduce_right/3

replace(array, index, item)

Specs

replace(array(), index(), item :: any()) :: array()

Replaces the element in array at index with value.

Called by Arrays.replace/3

resize(array, size, default)

Specs

resize(array(), size :: non_neg_integer(), default :: any()) :: array()

Changes the size of the array.

When made smaller, truncates elements beyond the first size elements will be removed. When made larger, new elements will receive default as value.

Called by Arrays.resize/2

size(array)

Specs

size(array()) :: non_neg_integer()

The number of elements in the array.

Called by Arrays.size/1

slice(array, start_index, amount)

Specs

slice(array(), index(), non_neg_integer()) :: array()

Return a contiguous slice of some elements in the array.

Handling of bounds is handled in the Arrays module, so we know for certain that 0 <= start_index < size(array) and start_index + length < size(array).

to_list(array)

Specs

to_list(array()) :: list()

Transforms the array into a list.

Called by Arrays.to_list/1