iv

iv

iv is an immutable array structure written in Gleam. You can use it like you would use an array in other programming languages and expect comparable or better runtime characteristics.

Tip: Hover the links for short summaries!

Create & Convert

new, wrap, repeat, range, from_list, from_yielder, initialise
to_list, to_yielder

Query

is_empty, length, equal, any, all
contains, index_of, last_index_of, get, get_or_default, first, last, find, find_index, find_last, find_last_index, find_map

Manipulate

set, try_set, update, try_update insert, insert_clamped, insert_list, insert_list_clamped, delete, try_delete
append, append_list, prepend, prepend_list, replace, splice

Concatenate & Split

concat, concat_list, flatten, split, slice, drop_first, drop_last, take_first, take_last, leading, rest

Transform

reverse, map, try_map, index_map, flat_map, filter, filter_map, zip, map2

Looping

each, try_each, each_right, fold, index_fold, try_fold, fold_right

Types

Array

opaque </>

A fast immutable array.

pub opaque type Array(item)

Functions

all

</> 
pub fn all(
  in array: Array(a),
  satisfying predicate: fn(a) -> Bool,
) -> Bool

Check if a fuction returns True for every element in the array.

all(new(), int.is_even)
 // --> True

all(from_list([1, 2, 3]), int.is_even)
// --> False

all(from_list([2, 4, 6]), int.is_even)
// --> True

any

</> 
pub fn any(
  in array: Array(a),
  satisfying predicate: fn(a) -> Bool,
) -> Bool

Check if a function returns True for at least one of the elements in the array.

any(new(), int.is_even)
// --> False

any(from_list([1, 3, 5]), int.is_even)
// --> False

any(from_list([1, 2, 3]), int.is_even)
// --> True

append

</> 
pub fn append(to array: Array(a), this item: a) -> Array(a)

Add an element to the end of an array.

from_list(["hello"]) |> append("joe")
// --> from_list(["hello", "joe"])

from_list([1, 2, 3]) |> append(4) |> append(0)
// --> from_list([1, 2, 3, 4, 0])

append_list

</> 
pub fn append_list(
  to array: Array(a),
  these items: List(a),
) -> Array(a)

Add all elements in a list to the end of the array.

This more efficient than append-ing all elements individually.

This function runs in O(n) time, only depending on the size of the appended list.

from_list([1, 2, 3]) |> append_list([4, 0])
// --> from_list([1, 2, 3, 4, 0])

concat

</> 
pub fn concat(
  left left: Array(a),
  right right: Array(a),
) -> Array(a)

Concatenate two arrays.

This function runs in O(log n) time.

concat(from_list([1, 2, 3]), from_list([4, 5, 6]))
// --> from_list([1, 2, 3, 4, 5, 6])

concat_list

</> 
pub fn concat_list(arrays: List(Array(a))) -> Array(a)

Concatenate many array, joining them up to form a single array.

This function runs in O(n) time, only depending on the number of arrays.

concat_list([from_list([1]), new(), from_list([2, 3])])
// --> from_list([1, 2, 3])

contains

</> 
pub fn contains(in array: Array(a), any item: a) -> Bool

Linearly search through the array to check if it contains an item.

contains(in: new(), any: 0)
// --> False

contains(in: from_list([1, 2, 3]), any: 2)
// --> True

contains(in: from_list([1, 2, 3]), any: 5)
// --> False

delete

</> 
pub fn delete(
  from array: Array(a),
  at index: Int,
) -> Result(Array(a), Nil)

Remove the element at a given index, moving all subsequent elements to the left.

This function runs in O(log n) time.

from_list([1, 2, 3]) |> delete(at: 1)
// --> Ok(from_list([1, 3]))

from_list([1, 2, 3]) |> delete(at: 3)
// --> Error(Nil)

from_list([]) |> delete(at: 0)
// --> Error(Nil)

drop_first

</> 
pub fn drop_first(from array: Array(a), up_to n: Int) -> Array(a)

Remove up to n elements from the start of the array.

If the array has less than n elements an empty array is returned.

This function runs in O(log n) time.

drop_first(from_list([1, 2, 3, 4]), up_to: 2)
// --> from_list([3, 4])

drop_first(from_list([1, 2, 3, 4]), up_to: 5)
// --> new()

drop_last

</> 
pub fn drop_last(from array: Array(a), up_to n: Int) -> Array(a)

Remove up to n elements from the end of the array.

If the array has less than n elements an empty array is returned.

This function runs in O(log n) time.

drop_last(from_list([1, 2, 3, 4]), up_to: 2)
// --> from_list([1, 2])

drop_last(from_list([1, 2, 3, 4]), up_to: 5)
// --> new()

each

</> 
pub fn each(in array: Array(a), do something: fn(a) -> b) -> Nil

Loop through the elements from the start to the end, calling a function and discarding the result.

Useful for performing some side-effects for every element.

use item <- each(from_list([1, 2, 3]))
io.println(int.to_string(item))
// 1
// 2
// 3
// --> Nil

each_right

</> 
pub fn each_right(
  in array: Array(a),
  do something: fn(a) -> b,
) -> Nil

Loop through the elements in reverse order from the end to the start, calling a function on each element and discarding the result.

Useful for performing some side-effects for every element.

use item <- each(from_list([1, 2, 3]))
io.println(int.to_string(item))
// 3
// 2
// 1
// --> Nil

equal

</> 
pub fn equal(a: Array(a), b: Array(a)) -> Bool

Checks whether or not two arrays are equal. Arrays are considered to be equal if they have the same length, and their elements are pairwise equal.

Important: Always use this function instead of the == operator!
Arrays containing the same elements can have different runtime representations.

equal(from_list([1, 2, 3]), range(1, 3))
// --> True

equal(from_list([1, 2, 3]), from_list([1]))
// --> False

equal(from_list([1, 2, 3]), from_list([1, 2, 4]))
// --> False

filter

</> 
pub fn filter(
  array: Array(a),
  keeping predicate: fn(a) -> Bool,
) -> Array(a)

Build a new array containing only the elements for which the given function returns True.

filter(from_list([1, 2, 3, 4]), int.is_even)
// --> from_list([2, 4])

filter(from_list([1, 2, 3, 4]), fn(x) { x > 6 })
// --> new()

filter_map

</> 
pub fn filter_map(
  array: Array(a),
  with fun: fn(a) -> Result(b, c),
) -> Array(b)

Build a new array containing only the values for which the given function returns Ok(_).

filter_map(from_list([[], [1], [2, 3]]), list.first)
// --> from_list([1, 2])

filter_map(from_list([1, 2, 3]), Error)
// --> new()

find

</> 
pub fn find(
  in array: Array(a),
  one_that is_desired: fn(a) -> Bool,
) -> Result(a, Nil)

Find the first element from the start of the array for which the given function returns True, and return it.

find(from_list([1, 2, 3, 4]), fn(x) { x > 2 })
// --> Ok(3)

find(from_list([1, 2, 3, 4]), fn(x) { x > 4 })
// --> Error(Nil)

find(new(), fn(_) { True })
// --> Error(Nil)

find_index

</> 
pub fn find_index(
  in array: Array(a),
  one_that is_desired: fn(a) -> Bool,
) -> Result(Int, Nil)

Return the index of the first element in the array for which the given function returns True, or Error(Nil) if no such element can be found.

find_index(from_list([4, 5, 6, 5]), fn(x) { x > 5 })
// --> Ok(2)

find_last_index

</> 
pub fn find_last_index(
  in array: Array(a),
  one_that is_desired: fn(a) -> Bool,
) -> Result(Int, Nil)

Return the index of the last element in the array for which the given function returns True, or Error(Nil) if no such element can be found.

find_last_index(from_list([4, 5, 6, 7]), fn(x) { x > 5 })
// --> Ok(3)

find_map

</> 
pub fn find_map(
  in array: Array(a),
  one_that is_desired: fn(a) -> Result(b, Nil),
) -> Result(b, Nil)

Find the first element for which the given function returns Ok(value), and return the wrapped value.

find_map(from_list([[], [2], [3]]), list.first)
// --> Ok(2)

find_map(from_list([[], []]), list.first)
// --> Error(Nil)

find_map(new(), first)
// --> Error(Nil)

first

</> 
pub fn first(from array: Array(a)) -> Result(a, Nil)

Get the first element from the start of the array, if there is one.

first(new())
// --> Error(Nil)

first(from_list([1, 2, 3]))
// --> Ok(1)

flat_map

</> 
pub fn flat_map(
  array: Array(a),
  with fun: fn(a) -> Array(b),
) -> Array(b)

Map every element in the array to a new array, and then flatten them.

flat_map(from_list([2, 4, 6]), fn(x) { from_list([x, x + 1]) })
// --> from_list([2, 3, 4, 5, 6, 7])

flatten

</> 
pub fn flatten(arrays: Array(Array(a))) -> Array(a)

Concatenate many arrays, joining them up to form a single array.

This function runs in O(n) time, only depending on the number of arrays.

flatten(from_list([from_list([1]), new(), from_list([2, 3])]))
// --> from_list([1, 2, 3])

fold

</> 
pub fn fold(
  over array: Array(a),
  from state: b,
  with fun: fn(b, a) -> b,
) -> b

Build up a new value by looping through each of the elements from the start to the end.

fold(from_list([6, 7, 8]), from: 0, with: int.add)
// --> 21

fold(from_list([6, 7, 8]), from: [], with: list.prepend)
// --> [8, 7, 6]

fold_right

</> 
pub fn fold_right(
  over array: Array(a),
  from state: b,
  with fun: fn(b, a) -> b,
) -> b

Build up a new value by looping in reverse from the end to the start through the array.

fold_right(from_list([6, 7, 8]), from: 0, with: int.add)
// --> 21

fold_right(from_list([6, 7, 8]), from: [], with: list.prepend)
// --> [6, 7, 8]

from_list

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

Converts the given list to an array.

length(from_list([1, 2, 3]))
// --> 3

from_yielder

</> 
pub fn from_yielder(source: Yielder(a)) -> Array(a)

Consume the given yielder, collecting all elements into a new array.

from_yielder(
  yielder.range(1, 3)
  |> yielder.cycle()
  |> yielder.take(10)
)
// --> from_list([1, 2, 3, 1, 2, 3, 1, 2, 3, 1])

get

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

Get the element at a specific index.

Arrays are 0-based, so the first element is at index 0, the second is at index 1, the third is at index 2, and so forth, up to length - 1.

let array = from_list(["trans", "rights", "are", "human", "rights"])

get(from: array, at: 1)
// --> Ok("rights")

get(from: array, at: 3)
// --> Ok("human")

get(from: array, at: -1)
// --> Error(Nil)

get(from: array, at: 5)
// --> Error(Nil)

get_or_default

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

Get the element at a specific index, or a default value if the index is out of range.

Arrays are 0-based, so the first element is at index 0, the second is at index 1, the third is at index 2, and so forth, up to length - 1.

let array = from_list(["trans", "rights", "are", "human", "rights"])

get_or_default(from: array, at: 1, or: "")
// --> "rights"

get_or_default(from: array, at: 3, or: "")
// --> "human"

get_or_default(from: array, at: -1, or: "")
// --> ""

get_or_default(from: array, at: 5, or: "")
// --> ""

index_fold

</> 
pub fn index_fold(
  over array: Array(a),
  from state: b,
  with fun: fn(b, a, Int) -> b,
) -> b

Like fold, but also passes the index of the current element.

index_map

</> 
pub fn index_map(
  array: Array(a),
  with fun: fn(a, Int) -> b,
) -> Array(b)

Return a copy of the array, where each element is replaced by the result of applying a function to the index and the element at that index.

index_map(from_list([6, 7, 8]), fn(x, i) { #(i, x) })
// --> from_list([#(0, 6), #(1, 7), #(2, 8)])

index_of

</> 
pub fn index_of(
  in array: Array(a),
  of item: a,
) -> Result(Int, Nil)

Return the index of the first occurrence of the given element in the array, or Error(Nil) if the array doesn’t contain the element.

index_of(from_list([4, 5, 6, 5]), of: 5)
// --> Ok(1)

index_of(from_list([4, 5, 6, 5]), of: 1)
// --> Error(Nil)

initialise

</> 
pub fn initialise(
  length length: Int,
  with fun: fn(Int) -> a,
) -> Array(a)

Create a list using a constructor function for each element. The function receives the current index as an input.

initialise(5, fn(i) { i * 2 })
// --> from_list([0, 2, 4, 6, 8])

insert

</> 
pub fn insert(
  into array: Array(a),
  at index: Int,
  this item: a,
) -> Result(Array(a), Nil)

Insert an element at an index into the array, moving all existing elements.

This function runs in O(log n) time.

new() |> insert(at: 0, this: "hi")
// --> Ok(from_list(["hi"]))

from_list([1, 2, 3]) |> insert(at: 1, this: 50)
// --> Ok(from_list([1, 50, 2, 3]))

from_list([1, 2, 3]) |> insert(at: 3, this: 4)
// --> Ok(from_list([1, 2, 3, 4]))

from_list([1, 2, 3]) |> insert(at: 5, this: 100)
// --> Error(Nil)

from_list([1, 2, 3]) |> insert(at: -1, this: 0)
// --> Error(Nil)

insert_clamped

</> 
pub fn insert_clamped(
  into array: Array(a),
  at index: Int,
  this item: a,
) -> Array(a)

Insert an element at an index into the array, moving all existing elements. If the index is less than 0 prepend, and if it’s greater than the number of elements in the array append instead.

This function runs in O(log n) time.

new() |> insert_clamped(at: 0, this: "hi")
// --> from_list(["hi"])

from_list([1, 2, 3]) |> insert_clamped(at: 1, this: 50)
// --> from_list([1, 50, 2, 3])

from_list([1, 2, 3]) |> insert_clamped(at: 3, this: 4)
// --> from_list([1, 2, 3, 4])

from_list([1, 2, 3]) |> insert_clamped(at: 5, this: 100)
// --> from_list([1, 2, 3, 100])

from_list([1, 2, 3]) |> insert(at: -1, this: 0)
// --> from_list([0, 1, 2, 3])

insert_list

</> 
pub fn insert_list(
  into array: Array(a),
  at index: Int,
  these items: List(a),
) -> Result(Array(a), Nil)

Insert all elements in a given list to the array at a specific index, in the same order they appear in the list.

This is more efficient than inserting all elements individually.

This function runs in O(n) time, only depending on the size of the inserted list.

from_list([1, 2, 3]) |> insert_list(at: 1, these: [34, 35])
// --> Ok(from_list([1, 34, 35, 2, 3]))

insert_list_clamped

</> 
pub fn insert_list_clamped(
  into array: Array(a),
  at index: Int,
  these items: List(a),
) -> Array(a)

Insert elements at an index into the array, moving all existing elements. If the index is less than 0 prepend, and if it’s greater than the number of elements in the array append instead.

This is more efficient than inserting all elements individually.

This function runs in O(n) time, only depending on the size of the inserted list.

from_list([1, 2, 3]) |> insert_list_clamped(at: 1, these: [34, 35])
// --> from_list([1, 34, 35, 2, 3])

from_list([1, 2, 3]) |> insert_list_clamped(at: 100, these: [100, 101])
// --> from_list([1, 2, 3, 100, 101])

is_empty

</> 
pub fn is_empty(array: Array(a)) -> Bool

Check whether or not an array is empty.

is_empty(from_list([]))
 // --> True

is_empty(from_list([1, 2, 3]))
// --> False

last

</> 
pub fn last(from array: Array(a)) -> Result(a, Nil)

Get the last element in the array, if there is one.

last(new())
// --> Error(Nil)

last(from_list([1]))
// --> Ok(1)

last(from_list([1, 2, 3]))
// --> Ok(3)

last_index_of

</> 
pub fn last_index_of(
  in array: Array(a),
  of item: a,
) -> Result(Int, Nil)

Return the index of the last occurrence of the given element in the array, or Error(Nil) if the array doesn’t contain the element.

last_index_of(from_list([4, 5, 6, 5]), of: 5)
// --> Ok(3)

last_index_of(from_list([4, 5, 6, 5]), of: 1)
// --> Error(Nil)

leading

</> 
pub fn leading(array: Array(a)) -> Result(Array(a), Nil)

Return the array without the last element. If the array is empty, Error(Nil) is returned.

leading(from_list([1, 2, 3]))
// --> Ok(from_list([1, 2]))

leading(new())
// --> Error(Nil)

length

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

Returns the number of items in the array.

length(from_list([]))
// --> 0

length(from_list(["hello", "joe"]))
// --> 2

map

</> 
pub fn map(array: Array(a), with fun: fn(a) -> b) -> Array(b)

Return a copy of the array, where each element is replaced by the result of a function.

map(from_list([6, 7, 8]), fn(x) { x * 2 })
// --> from_list([12, 14, 16])

map2

</> 
pub fn map2(
  a: Array(a),
  b: Array(b),
  with fun: fn(a, b) -> c,
) -> Array(c)

Combine 2 arrays into a single array using the given function.

If one array is longer than the other, the extra elements are dropped from the end.

map2(from_list([1, 2, 3]), from_list([4, 5, 6]), int.add)
// --> from_list([5, 7, 9])

map2(from_list([1, 2]), from_list(["a", "b", "c"]), fn(a, b) { #(a, b) })
// --> from_list([#(1, "a"), #(2, "b")])

new

</> 
pub fn new() -> Array(a)

Returns a new empty array.

new()
// --> from_list([])

prepend

</> 
pub fn prepend(to array: Array(a), this item: a) -> Array(a)

Add an element to the start of the array, making it the first element.

This function runs in O(log n) time.

from_list(["joe"]) |> prepend("hello")
// --> from_list(["hello", "joe"])

from_list([1, 2, 3]) |> prepend(4) |> prepend(0)
// --> from_list([0, 4, 1, 2, 3])

prepend_list

</> 
pub fn prepend_list(
  to array: Array(a),
  these items: List(a),
) -> Array(a)

Add many elements to the start of the array, in the same order they appear in the list.

This is more efficient than inserting all elements individually.

This function runs in O(n) time, only depending on the size of the prepended list.

from_list([1, 2, 3]) |> prepend_list([4, 5, 6])
// --> from_list([4, 5, 6, 1, 2, 3])

range

</> 
pub fn range(from start: Int, to stop: Int) -> Array(Int)

Creates a list of ints ranging from a given start and finish.

range(1, 3)
// --> from_list([1, 2, 3])

range(10, 1)
// --> from_list([10, 9, 8, 7, 6, 5, 4, 3, 2, 1])

repeat

</> 
pub fn repeat(item item: a, times times: Int) -> Array(a)

Build an array by repeating the given element a number of times.

repeat("hi", times: 3)
// --> from_list(["hi", "hi", "hi"])

replace

</> 
pub fn replace(
  from array: Array(a),
  at index: Int,
  replace count: Int,
  with replacements: Array(a),
) -> Result(Array(a), Nil)

Replace a slice with a different array.

The entire slice has to exist in the array. Otherwise, Error(Nil) is returned.

This function runs in O(log n) time.

from_list([1, 2, 3, 4]) |> replace(at: 1, replace: 2, with: from_list([7, 8, 9]))
// --> Ok(from_list([1, 7, 8, 9, 4]))

from_list([1, 2, 3]) |> replace(at: 2, replace: 1, with: from_list([7, 8, 9]))
// --> Ok(from_list([1, 2, 7, 8, 9]))

from_list([1, 2, 3]) |> replace(at: 2, replace: 2, with: from_list([8, 8, 9]))
// --> Error(Nil)

rest

</> 
pub fn rest(array: Array(a)) -> Result(Array(a), Nil)

Return the array without the first element. If the array is empty, Error(Nil) is returned.

rest(from_list([1, 2, 3]))
// --> Ok(from_list([2, 3]))

rest(new())
// --> Error(Nil)

reverse

</> 
pub fn reverse(array: Array(a)) -> Array(a)

Create a new array containing the same elements, but in the opposite order.

reverse(from_list([6, 7, 8]))
// --> from_list([8, 7, 6])

reverse(from_list([1]))
// --> from_list([1])

reverse(new())
// --> new()

set

</> 
pub fn set(
  in array: Array(a),
  at index: Int,
  to item: a,
) -> Result(Array(a), Nil)

Store a new value at a given index and return the new array, or Error(Nil) if the index cannot be found in the array.

from_list([1, 2, 3]) |> set(at: 1, to: 50)
// --> Ok(from_list([1, 50, 3]))

from_list([1, 2, 3]) |> set(at: -1, to: 50)
// --> Error(Nil)

from_list([]) |> set(at: 0, to: 1)
// --> Error(Nil)

slice

</> 
pub fn slice(
  from array: Array(a),
  start start: Int,
  size size: Int,
) -> Result(Array(a), Nil)

Extract a sub-slice from the array. If the start is not part of the array or if the array does not contain enough elements, Error(Nil) is returned.

This function runs in O(log n) time.

let array = from_list([6, 7, 8, 9])

slice(from: array, start: 1, size: 2)
// --> Ok(from_list([7, 8]))

slice(from: array, start: 2, size: 3)
// --> Error(Nil)

slice(from: array, start: 5, size: 0)
// --> Error(Nil)

splice

</> 
pub fn splice(
  from array: Array(a),
  at index: Int,
  replace count: Int,
  with replacer: fn(Array(a)) -> Array(a),
) -> Result(Array(a), Nil)

Replace a slice using a function, returning the new elements.

The entire slice has to exist in the array. Otherwise, Error(Nil) is returned.

This function runs in O(log n) time.

from_list([1, 2, 3, 4]) |> splice(at: 1, replace: 2, with: fn(slice) {
  map(slice, fn(x) { x * 2 })
})
// --> Ok(from_list([1, 4, 6, 4]))

split

</> 
pub fn split(
  array: Array(a),
  at index: Int,
) -> #(Array(a), Array(a))

Split an array in two before the given index.

If the list is not long enough to have the given index the before list will be the input list, and the after list will be empty.

split(from_list([6, 7, 8, 9]), at: 0)
// --> #(new(), from_list([6, 7, 8, 9]))

split(from_list([6, 7, 8, 9]), at: 2)
// --> #(from_list([6, 7]), from_list([8, 9]))

split(from_list([6, 7, 8, 9]), at: 4)
// --> #(from_list([6, 7, 8, 9]), new())

take_first

</> 
pub fn take_first(from array: Array(a), up_to n: Int) -> Array(a)

Return up to the first n elements from the start of the array.

If the array has less than n elements, the original array is returned.

This function runs in O(log n) time.

take_first(from_list([6, 7, 8, 9]), up_to: 3)
// --> from_list([6, 7, 8])

take_first(from_list([6, 7, 8, 9]), up_to: 10)
// --> from_list([6, 7, 8, 9])

take_last

</> 
pub fn take_last(from array: Array(a), up_to n: Int) -> Array(a)

Return up n elements from the end of the array.

If the array has less than n elements, the original array is returned.

This function runs in O(log n) time.

take_last(from_list([6, 7, 8, 9]), up_to: 3)
// --> from_list([7, 8, 9])

take_last(from_list([6, 7, 8, 9]), up_to: 10)
// --> from_list([6, 7, 8, 9])

to_list

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

Convert an array to a standard Gleam list.

to_list(range(1, 5))
// --> [1, 2, 3, 4, 5]

to_yielder

</> 
pub fn to_yielder(array: Array(a)) -> Yielder(a)

Return a yielder iterating through an array.

Yielders are more efficient then repeatetly querying the index, but slower than using more specialised functions like each or fold. Only use this if you need to pause or iterate through many arrays at once.

to_yielder(from_list([1, 2, 3]))
|> yielder.cycle
|> yielder.take(10)
|> yielder.to_list
// --> [1, 2, 3, 1, 2, 3, 1, 2, 3, 1]

try_delete

</> 
pub fn try_delete(
  from array: Array(a),
  at index: Int,
) -> Array(a)

Remove the element at a given index, moving all subsequent elements to the left. If the index does not exist, return the array unchanged.

This function runs in O(log n) time.

from_list([1, 2, 3]) |> try_delete(at: 1)
// --> from_list([1, 3])

from_list([1, 2, 3]) |> try_delete(at: 3)
// --> from_list([1, 2, 3])

from_list([]) |> try_delete(at: 0)
// --> from_list([])

try_each

</> 
pub fn try_each(
  in array: Array(a),
  do something: fn(a) -> Result(b, c),
) -> Result(Nil, c)

Loop through the elements from the start to the end, calling a result-returning function for all of them. As soon as the function returns Error(_), iteration is stopped and the error is returned.

try_fold

</> 
pub fn try_fold(
  over array: Array(a),
  from state: b,
  with fun: fn(b, a) -> Result(b, c),
) -> Result(b, c)

A variant of fold that builds up a new value using a function that can fail.

If the function returns Error(_), iteration is stopped and the error is returned immediately. Otherwise, the final built-up value is returned.

try_map

</> 
pub fn try_map(
  over array: Array(a),
  with fun: fn(a) -> Result(b, c),
) -> Result(Array(b), c)

Return a copy of the array, where each element is replaced by the Ok(_) result of applying a function to each element.

If the fuction returns Error(_) for any of the elements, that error is immediately returned instead.

try_map(from_list([[1], [2, 3]]), list.first)
// --> Ok(from_list([1, 2]))

try_map(from_list([[1], [], [2, 3]]), list.first)
// --> Error(Nil)

try_set

</> 
pub fn try_set(
  in array: Array(a),
  at index: Int,
  to item: a,
) -> Array(a)

Store a new value at a given index and return the new array, or return the given array unchanged if the index cannot be found.

from_list([1, 2, 3]) |> try_set(at: 1, to: 50)
// --> from_list([1, 50, 3])

from_list([1, 2, 3]) |> try_set(at: -1, to: 50)
// --> from_list([1, 2, 3])

from_list([]) |> try_set(at: 0, to: 1)
// --> from_list([])

try_update

</> 
pub fn try_update(
  in array: Array(a),
  at index: Int,
  with fun: fn(a) -> a,
) -> Array(a)

Update the element at a given index and return a new array, or return the given array unchanged if the index cannot be found in the array.

This is more efficient than get-ing and then try_set-ing the element.

from_list([1, 2, 3]) |> try_update(at: 1, with: fn(x) { x * 2 })
// --> from_list([1, 4, 3])

from_list([1, 2, 3]) |> try_update(at: -1, with: fn(x) { x + 1 })
// --> from_list([1, 2, 3])

update

</> 
pub fn update(
  in array: Array(a),
  at index: Int,
  with fun: fn(a) -> a,
) -> Result(Array(a), Nil)

Update the element at a given index and return a new array, or return Error(Nil) if the index cannot be found in the array.

This is slightly more efficient than get-ing and then set-ing the element.

from_list([1, 2, 3]) |> update(at: 1, with: fn(x) { x * 2 })
// --> Ok(from_list([1, 4, 3]))

from_list([1, 2, 3]) |> update(at: -1, with: fn(x) { x + 1 })
// --> Error(Nil)

wrap

</> 
pub fn wrap(of item: a) -> Array(a)

Returns the given item wrapped in a list.

wrap(42)
// --> from_list([42])

wrap(from_list([1, 2, 3]))
// --> from_list([from_list([1, 2, 3])])

zip

</> 
pub fn zip(a: Array(a), b: Array(b)) -> Array(#(a, b))

Combine 2 arrays into a single array of 2-element tuples.

If one array is longer than the other, the extra elements are dropped from the end.

zip(from_list([1, 2, 3]), from_list(["a", "b", "c"]))
// --> from_list([#(1, "a"), #(2, "b"), #(3, "c")])

zip(from_list([]), from_list(["a", "b", "c"]))
// --> new()
✨ Search Document