glearray

Types

Array

Arrays are ordered sequences of elements, similar to lists.

Like everything in Gleam, arrays are immutable. As opposed to linked lists, arrays store their elements in a contiguous slice of memory, therefore allowing very fast indexed access.

Modifying an array however takes linear time and memory because it requires copying the entire array.

Implementation

Arrays are represented as tuples when compiled to Erlang, and JavaScript arrays when compiled to JavaScript.

Also note that this library has no connection to Erlang’s array module, which implements a tree structure for efficient reading and writing.

pub type Array(a)

Values

copy_insert

</>

pub fn copy_insert(
  into array: Array(a),
  at index: Int,
  value value: a,
) -> Result(Array(a), Nil)

Inserts an element into the array at the given index.

All following elements are shifted to the right, having their index incremented by one.

Error(Nil) is returned if the index is less than 0 or greater than length(array). If the index is equal to length(array), this function behaves like copy_push.

Performance

This function has to copy the entire array, making it very inefficient especially for larger arrays.

Examples

> from_list(["a", "b"]) |> copy_insert(0, "c")
Ok(from_list(["c", "a", "b"]))

> from_list(["a", "b"]) |> copy_insert(1, "c")
Ok(from_list(["a", "c", "b"]))

> from_list(["a", "b"]) |> copy_insert(2, "c")
Ok(from_list(["a", "b", "c"]))

> from_list(["a", "b"]) |> copy_insert(3, "c")
Error(Nil)

copy_push

</>

pub fn copy_push(
  onto array: Array(a),
  value value: a,
) -> Array(a)

Adds a single element to the back of the given array.

Performance

This function has to copy the entire array, making it very inefficient especially for larger arrays.

Examples

> new() |> copy_push(1) |> copy_push(2) |> to_list
[1, 2]

copy_set

</>

pub fn copy_set(
  in array: Array(a),
  at index: Int,
  value value: a,
) -> Result(Array(a), Nil)

Replaces the element at the given index with value.

This function cannot extend an array and returns Error(Nil) if index is not valid. See also copy_insert and copy_push.

Performance

This function has to copy the entire array, making it very inefficient especially for larger arrays.

Examples

> from_list(["a", "b", "c"]) |> copy_set(1, "x")
Ok(from_list(["a", "x", "c"]))

> from_list(["a", "b", "c"]) |> copy_set(3, "x")
Error(Nil)

from_list

</>

pub fn from_list(list: List(a)) -> Array(a)

Converts a list to an array.

get

</>

pub fn get(in array: Array(a), at index: Int) -> Result(a, Nil)

Returns the element at the specified index, starting from 0.

Error(Nil) is returned if index is less than 0 or greater than or equal to length(array).

Performance

This function is very efficient and runs in constant time.

Examples

> from_list([5, 6, 7]) |> get(1)
Ok(6)

> from_list([5, 6, 7]) |> get(3)
Error(Nil)

get_or_default

</>

pub fn get_or_default(
  in array: Array(a),
  at index: Int,
  or default: a,
) -> a

Returns the element at the specified index, starting from 0.

The specified default is returned if index is less than 0 or greater than / or equal to length(array).

Performance

This function is very efficient and runs in constant time.

Examples

> from_list([5, 6, 7]) |> get_or_default(1, -1)
6

> from_list([5, 6, 7]) |> get_or_default(3, -1)
-1

length

</>

pub fn length(of array: Array(a)) -> Int

Returns the number of elements in the array.

Performance

This function is very efficient and runs in constant time.

Examples

> length(new())
0

> from_list([8, 0, 0]) |> length
3

new

</>

pub fn new() -> Array(a)

Returns an empty array.

Examples

> new()
from_list([])

to_list

</>

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

Converts an array to a list.