gary/array

Functional, extendible arrays, provided by Erlang’s array module. Arrays can have fixed size, or can grow automatically as needed (“extensible”). A default value is used for entries that have not been explicitly set.

Erlang arrays are 0-indexed. The maximum index for a fixed-size array of size n is n - 1. There is no maximum index for a extensible array; the array resizes to fit as necessary. Negative indices aren’t supported.

Erlang doesn’t distinguish between an unset entry and a entry that’s been explicitly set to the array’s defined default value, which can cause issues when using functions that drop unset entries like sparse_map or sparse_to_list. Use a type like Option(t) to ensure that you can’t accidentally cause this kind of collision.

See the Erlang docs for more information and caveats.

Types

ArrayError

</>

Types representing invalid situations that would otherwise cause the function call to fail with a badarg exception in Erlang.

pub type ArrayError {
  IndexOutOfRange
  BadSize
}

Constructors

```
IndexOutOfRange
```
attempted to access a negative index, or an index beyond the size of a fixed-size array
```
BadSize
```
tried to make an array with a negative size

Functions

create

</>

pub fn create(default default: a) -> ErlangArray(a)

Creates a new, extensible sparse array with a default value of default for any indices without an assigned value.

create_fixed_size

</>

pub fn create_fixed_size(
  size size: Int,
  default default: a,
) -> Result(ErlangArray(a), ArrayError)

Creates a new, fixed-size sparse array of size size with a default value of default for any indices without an assigned value. Returns a BadSize error if size is negative.

drop

</>

pub fn drop(
  from array: ErlangArray(a),
  at index: Int,
) -> Result(ErlangArray(a), ArrayError)

Returns a new array where the value at index index has been set to the array’s default.
Returns Error(IndexOutOfRange) if the index is negative, or if it exceeds the size of a fixed-size array.

fold

</>

pub fn fold(
  over array: ErlangArray(a),
  from initial: b,
  with function: fn(Int, a, b) -> b,
) -> b

Reduces the array values into a single value by calling function on each array value, including default values, from left to right (beginning at index 0).

fold_right

</>

pub fn fold_right(
  over array: ErlangArray(a),
  from initial: b,
  with function: fn(Int, a, b) -> b,
) -> b

Reduces the array values into a single value by calling function on each array value, including default values, from right to left (ending at index 0).

from_dict

</>

pub fn from_dict(
  from dict: Dict(Int, a),
  default default: a,
) -> Result(ErlangArray(a), ArrayError)

Converts a dict with integer keys representing array indices to an extensible sparse array.
Returns IndexOutOfRange if any of the keys are negative.

from_list

</>

pub fn from_list(
  from list: List(a),
  default default: a,
) -> ErlangArray(a)

Converts a list to an extensible sparse array, assigning list members to indices starting at an index of 0.

get

</>

pub fn get(
  from array: ErlangArray(a),
  at index: Int,
) -> Result(a, ArrayError)

Returns the value at index index. Returns Error(IndexOutOfRange) if the index is negative, or if it exceeds the size of a fixed-size array.

get_count

</>

pub fn get_count(array: ErlangArray(a)) -> Int

Returns the number of defined elements in the array.

get_default

</>

pub fn get_default(array: ErlangArray(a)) -> a

Returns the array’s default for unset values.

get_size

</>

pub fn get_size(array: ErlangArray(a)) -> Int

Returns the size of the array. For fixed-size arrays, this is the defined size of the array. For extensible arrays, if the greatest index with a defined value is n, the size is n + 1.

is_fixed_size

</>

pub fn is_fixed_size(array: ErlangArray(a)) -> Bool

Returns True if the array is fixed-size, and False if it’s extensible.

make_extensible

</>

pub fn make_extensible(array: ErlangArray(a)) -> ErlangArray(a)

Returns an extensible version of the array.

make_fixed

</>

pub fn make_fixed(array: ErlangArray(a)) -> ErlangArray(a)

Returns a fixed-size version of the array, sized to fit the set values.

map

</>

pub fn map(
  over array: ErlangArray(a),
  with function: fn(Int, a) -> b,
) -> ErlangArray(b)

Returns a new array that applies function to each array value, including default values within the current size of the array (see get_size for what this means for extensible arrays).

resize_to_fit

</>

pub fn resize_to_fit(array: ErlangArray(a)) -> ErlangArray(a)

If array is fixed-size, returns an array with its bounds resized to exactly fit the set values. Has no effect on extensible arrays; just returns the original array.

set

</>

pub fn set(
  into array: ErlangArray(a),
  at index: Int,
  put item: a,
) -> Result(ErlangArray(a), ArrayError)

Returns a new array with item assigned to index index. Returns Error(IndexOutOfRange) if the index is negative, or if it exceeds the size of a fixed-size array.

set_size

</>

pub fn set_size(
  array: ErlangArray(a),
  size: Int,
) -> Result(ErlangArray(a), ArrayError)

Returns a fixed-size version of the array with its size set to size. Returns a BadSize error if size is negative.

sparse_fold

</>

pub fn sparse_fold(
  over array: ErlangArray(a),
  from initial: b,
  with function: fn(Int, a, b) -> b,
) -> b

Reduces the array values into a single value by calling function on each array value, excluding default values, from left to right (beginning at index 0).

sparse_fold_right

</>

pub fn sparse_fold_right(
  over array: ErlangArray(a),
  from initial: b,
  with function: fn(Int, a, b) -> b,
) -> b

Reduces the array values into a single value by calling function on each array value, excluding default values, from right to left (ending at index 0).

sparse_map

</>

pub fn sparse_map(
  over array: ErlangArray(a),
  with function: fn(Int, a) -> b,
) -> ErlangArray(b)

Returns a new array that applies function to each array value, excluding default values.

to_dict

</>

pub fn to_dict(array: ErlangArray(a)) -> Dict(Int, a)

Converts the array to a dict with integer keys, including the default value for any keys between 0 and the maximum that don’t have values.

to_dict_without_defaults

</>

pub fn to_dict_without_defaults(
  array: ErlangArray(a),
) -> Dict(Int, a)

Converts the array to a dict with integer keys, omitting default values.

to_list

</>

pub fn to_list(array: ErlangArray(a)) -> List(a)

Converts the array’s values to a list, in order from index 0 to the maximum, including the default value for any keys between 0 and the maximum that don’t have values.

to_list_without_defaults

</>

pub fn to_list_without_defaults(array: ErlangArray(a)) -> List(a)

Converts the array’s values to a list, in order from lowest to highest index, omitting default values.