Iteraptor.Array (iteraptor v1.13.1) View Source

Array emulation implementing Access behaviour. Index in array is zero-based.

Array is the "go to" array data structure in Elixir. An array can be constructed using Array.new/{0,1}:

iex> Iteraptor.Array.new()
#Array<[]>

iex> Iteraptor.Array.new(2)
#Array<[nil, nil]>

iex> Iteraptor.Array.new([:foo, :bar])
#Array<[:foo, :bar]>

An array can contain any kind of elements, and elements in an array don't have to be of the same type. By definition, arrays have keys in 0..size-1 range. Arrays are implicitly expandable, which means adding an element at index 100 to the array currently containing 1 element would increase the size of the array to 100.

iex> array = Iteraptor.Array.new([:foo])
iex> Iteraptor.Array.set(array, 3, :bar)
#Array<[:foo, nil, nil, :bar]>

An Array is represented internally using the %Array{} struct. Note that, however, the struct fields are private and must not be accessed directly; use the functions in this module to perform operations on arrays.

Arrays can also be constructed starting from other collection-type data structures: for example, see Array.new/1 or Enum.into/2.

iex> Enum.into([1, 2, 3], Iteraptor.Array.new())
#Array<[1, 2, 3]>

Arrays do implement Access behaviour.

iex> array = Iteraptor.Array.new([%{foo: 42}, %{bar: :baz}])
iex> get_in(array, [0, :foo])
42

Link to this section Summary

Functions

Appends another enumerable to the array.

Converts a tuple given as parameter to array.

Returns the value at index in array, or default if index is out of array bounds.

Pops (deletes) value at index from array, setting the value at the respective index to nil. Returns a tuple containing the value removed and the new array.

Sets the value at index in array, expanding the array if necessary. Returns a new array.

Returns the number of elements in array.

Converts array to a list.

Trims nil values from the tail of the Array. Returns a trimmed array.

Link to this section Types

Specs

t() :: %Iteraptor.Array{
  map: %{required(non_neg_integer()) => any()},
  version: term()
}

Specs

value() :: term()

Link to this section Functions

Specs

append(t(), any()) :: t()

Appends another enumerable to the array.

iex> array = Iteraptor.Array.new([1, 2, 3])
iex> Iteraptor.Array.append(array, [4, 5])
#Array<[1, 2, 3, 4, 5]>

Specs

from_tuple(tuple :: tuple()) :: t()

Converts a tuple given as parameter to array.

iex> Iteraptor.Array.from_tuple({1, 2, 3})
#Array<[1, 2, 3]>
Link to this function

get(array, index, default \\ nil)

View Source

Specs

get(t(), non_neg_integer(), any()) :: any()

Returns the value at index in array, or default if index is out of array bounds.

iex> array = Iteraptor.Array.new([42])
iex> Iteraptor.Array.get(array, 0)
42
iex> Iteraptor.Array.get(array, 2, 42)
42
Link to this function

new(enumerable \\ nil, transform \\ nil)

View Source

Returns a new array.

iex> Iteraptor.Array.new()
#Array<[]>

Creates an array of the given length or from enumerable. Might we used to wrap the existing instance of Iteraptor.Array.

iex> Iteraptor.Array.new(3)
#Array<[nil, nil, nil]>

iex> Iteraptor.Array.new([:foo, :bar, 42])
#Array<[:foo, :bar, 42]>

Also the transformation function might be passed via second argument.

iex> Iteraptor.Array.new([1, 2, 3], fn x -> 2 * x end)
#Array<[2, 4, 6]>

Specs

pop(t(), non_neg_integer()) :: {any(), t()}

Pops (deletes) value at index from array, setting the value at the respective index to nil. Returns a tuple containing the value removed and the new array.

iex> array = Iteraptor.Array.new([1, 2, 3])
iex> {elem, array} = Iteraptor.Array.pop(array, 1)
iex> elem
2
iex> array
#Array<[1, nil, 3]>
Link to this function

set(array, index, value)

View Source

Specs

set(t(), non_neg_integer(), any()) :: t()

Sets the value at index in array, expanding the array if necessary. Returns a new array.

iex> array = Iteraptor.Array.new([42])
iex> Iteraptor.Array.set(array, 0, :foo)
#Array<[:foo]>
iex> Iteraptor.Array.set(array, 2, :bar)
#Array<[42, nil, :bar]>

Specs

size(t()) :: non_neg_integer()

Returns the number of elements in array.

iex> Iteraptor.Array.size(Iteraptor.Array.new([1, 2, 3]))
3

Specs

to_list(t()) :: [any()]

Converts array to a list.

iex> Iteraptor.Array.to_list(Iteraptor.Array.new([1, 2, 3]))
[1, 2, 3]

Specs

trim(array :: t()) :: t()

Trims nil values from the tail of the Array. Returns a trimmed array.

iex> array = Iteraptor.Array.new([42, nil, nil])
#Array<[42, nil, nil]>
iex> Iteraptor.Array.trim(array)
#Array<[42]>