gossamer/array

Types

Array

A JS Array — an indexed, ordered, mutable list of values.

For most Gleam use cases, prefer List. This binding exists for JS interop where a JS Array is specifically required.

Value-based search functions (includes, index_of, last_index_of) match object values (records, lists, tuples) by JS reference identity, not value equality — two equal-by-value tuples constructed separately are distinct. Primitive values use value equality. Predicate-based search (find, every, some, etc.) is unaffected.

See Array on MDN.

pub type Array(a)

Values

at

</>

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

Returns the element at index, or Error(Nil) if the index is out of range. Negative indices count from the end.

concat

</>

pub fn concat(array: Array(a), and other: Array(a)) -> Array(a)

copy_within

</>

pub fn copy_within(
  array: Array(a),
  to target: Int,
  from start: Int,
) -> Array(a)

copy_within_range

</>

pub fn copy_within_range(
  array: Array(a),
  to target: Int,
  from start: Int,
  up_to end: Int,
) -> Array(a)

entries

</>

pub fn entries(
  of array: Array(a),
) -> iterator.Iterator(#(Int, a), Nil, Nil)

every

</>

pub fn every(
  in array: Array(a),
  satisfying predicate: fn(a) -> Bool,
) -> Bool

fill

</>

pub fn fill(array: Array(a), with value: a) -> Array(a)

fill_range

</>

pub fn fill_range(
  array: Array(a),
  with value: a,
  from start: Int,
  to end: Int,
) -> Array(a)

filter

</>

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

find

</>

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

Returns the first value matching predicate, or Error(Nil) if none match.

find_index

</>

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

Returns the index of the first value matching predicate, or Error(Nil) if none match.

find_last

</>

pub fn find_last(
  in array: Array(a),
  one_that predicate: fn(a) -> Bool,
) -> Result(a, Nil)

Returns the last value matching predicate, or Error(Nil) if none match.

find_last_index

</>

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

Returns the index of the last value matching predicate, or Error(Nil) if none match.

flat

</>

pub fn flat(array: Array(Array(a))) -> Array(a)

flat_map

</>

pub fn flat_map(
  over array: Array(a),
  with callback: fn(a) -> Array(b),
) -> Array(b)

for_each

</>

pub fn for_each(
  in array: Array(a),
  run callback: fn(a) -> b,
) -> Nil

from_list

</>

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

from_list_mapped

</>

pub fn from_list_mapped(
  list: List(a),
  with mapper: fn(a) -> b,
) -> Array(b)

includes

</>

pub fn includes(in array: Array(a), value value: a) -> Bool

includes_from

</>

pub fn includes_from(
  in array: Array(a),
  value value: a,
  from index: Int,
) -> Bool

index_every

</>

pub fn index_every(
  in array: Array(a),
  satisfying predicate: fn(a, Int) -> Bool,
) -> Bool

index_filter

</>

pub fn index_filter(
  in array: Array(a),
  keeping predicate: fn(a, Int) -> Bool,
) -> Array(a)

index_find

</>

pub fn index_find(
  in array: Array(a),
  one_that predicate: fn(a, Int) -> Bool,
) -> Result(a, Nil)

Like find, but passes the index alongside each value to predicate.

index_find_index

</>

pub fn index_find_index(
  in array: Array(a),
  one_that predicate: fn(a, Int) -> Bool,
) -> Result(Int, Nil)

Like find_index, but passes the index alongside each value to predicate.

index_find_last

</>

pub fn index_find_last(
  in array: Array(a),
  one_that predicate: fn(a, Int) -> Bool,
) -> Result(a, Nil)

Like find_last, but passes the index alongside each value to predicate.

index_find_last_index

</>

pub fn index_find_last_index(
  in array: Array(a),
  one_that predicate: fn(a, Int) -> Bool,
) -> Result(Int, Nil)

Like find_last_index, but passes the index alongside each value to predicate.

index_for_each

</>

pub fn index_for_each(
  in array: Array(a),
  run callback: fn(a, Int) -> b,
) -> Nil

index_map

</>

pub fn index_map(
  over array: Array(a),
  with callback: fn(a, Int) -> b,
) -> Array(b)

index_of

</>

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

Returns the first index of value in the array, or Error(Nil) if the value is not found.

index_of_from

</>

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

Like index_of, but starts searching from index.

index_reduce

</>

pub fn index_reduce(
  over array: Array(a),
  from initial: b,
  with callback: fn(b, a, Int) -> b,
) -> b

index_reduce_right

</>

pub fn index_reduce_right(
  over array: Array(a),
  from initial: b,
  with callback: fn(b, a, Int) -> b,
) -> b

index_some

</>

pub fn index_some(
  in array: Array(a),
  satisfying predicate: fn(a, Int) -> Bool,
) -> Bool

join

</>

pub fn join(array: Array(a), with separator: String) -> String

keys

</>

pub fn keys(
  of array: Array(a),
) -> iterator.Iterator(Int, Nil, Nil)

last_index_of

</>

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

Returns the last index of value in the array, or Error(Nil) if the value is not found.

last_index_of_from

</>

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

Like last_index_of, but searches backwards from index.

length

</>

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

map

</>

pub fn map(
  over array: Array(a),
  with callback: fn(a) -> b,
) -> Array(b)

new

</>

pub fn new() -> Array(a)

pop

</>

pub fn pop(from array: Array(a)) -> Result(a, Nil)

Returns the removed element, or an error if the array is empty.

push

</>

pub fn push(to array: Array(a), value value: a) -> Array(a)

reduce

</>

pub fn reduce(
  over array: Array(a),
  from initial: b,
  with callback: fn(b, a) -> b,
) -> b

reduce_right

</>

pub fn reduce_right(
  over array: Array(a),
  from initial: b,
  with callback: fn(b, a) -> b,
) -> b

reverse

</>

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

shift

</>

pub fn shift(from array: Array(a)) -> Result(a, Nil)

Returns the removed element, or an error if the array is empty.

slice

</>

pub fn slice(array: Array(a)) -> Array(a)

slice_from

</>

pub fn slice_from(array: Array(a), start: Int) -> Array(a)

slice_range

</>

pub fn slice_range(
  array: Array(a),
  from start: Int,
  to end: Int,
) -> Array(a)

some

</>

pub fn some(
  in array: Array(a),
  satisfying predicate: fn(a) -> Bool,
) -> Bool

sort

</>

pub fn sort(
  array: Array(a),
  by compare: fn(a, a) -> order.Order,
) -> Array(a)

splice

</>

pub fn splice(
  in array: Array(a),
  from start: Int,
  removing count: Int,
) -> Array(a)

Removes elements and returns them. Mutates the array.

splice_with

</>

pub fn splice_with(
  in array: Array(a),
  from start: Int,
  removing count: Int,
  inserting items: List(a),
) -> Array(a)

Removes elements, inserts new ones, and returns the removed elements. Mutates the array.

to_list

</>

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

to_reversed

</>

pub fn to_reversed(array: Array(a)) -> Array(a)

to_sorted

</>

pub fn to_sorted(
  array: Array(a),
  by compare: fn(a, a) -> order.Order,
) -> Array(a)

to_spliced

</>

pub fn to_spliced(
  array: Array(a),
  from start: Int,
  removing count: Int,
) -> Array(a)

to_spliced_with

</>

pub fn to_spliced_with(
  array: Array(a),
  from start: Int,
  removing count: Int,
  inserting items: List(a),
) -> Array(a)

to_string

</>

pub fn to_string(array: Array(a)) -> String

unshift

</>

pub fn unshift(to array: Array(a), value value: a) -> Array(a)

values

</>

pub fn values(
  of array: Array(a),
) -> iterator.Iterator(a, Nil, Nil)

with

</>

pub fn with(
  array: Array(a),
  at_index index: Int,
  value value: a,
) -> Result(Array(a), js_error.JsError)

Returns a copy of the array with the element at index replaced by value. Negative indices count from the end. Returns an error if index is out of range.