treelist · treelist

add

pub fn add(
  list: TreeList(a),
  value: a,
) -> Result(TreeList(a), Nil)

Adds an element to the end of the provided treelist i.e. insert at position size(list)

Returns a new TreeList containing the provided element

let list = new()
let assert Ok(new_list) = add(list, "Test")
get(new_list, 0)
// -> Ok("Test")

append

</>

pub fn append(
  tlist: TreeList(a),
  tlist2: TreeList(a),
) -> Result(TreeList(a), Nil)

Joins one treelist onto the end of another.

Examples

let assert Ok(l1) = treelist.from_list([1, 2])
let assert Ok(l2) = treelist.from_list([3])
let assert Ok(list) = append(l1, l2)
to_list(list)
// -> [1, 2, 3]

contains

</>

pub fn contains(tlist: TreeList(a), item: a) -> Bool

Returns true if this list contains the specified element.

let assert Ok(list) = from_list([1, 2, 3, 4])
contains(list, 3)
// -> True

let assert Ok(list) = from_list([1, 2, 3, 4])
contains(list, 999)
// -> False

do_reverse

</>

pub fn do_reverse(node: Node(a)) -> Node(a)

drop

</>

pub fn drop(tlist: TreeList(a), up_to_n: Int) -> TreeList(a)

Returns a treelist that is the given treelist with up to the given number of elements removed from the front of the treelist.

If the treelist has less than the number of elements an empty treelist is returned.

Examples

let assert Ok(list) = from_list([1, 2, 3, 4])
drop(list, 2)
|> to_list
// -> [3, 4]

let assert Ok(list) = from_list([1, 2, 3, 4])
drop(list, 9)
|> to_list
// -> []

filter

</>

pub fn filter(
  tlist: TreeList(a),
  filter_fn: fn(a) -> Bool,
) -> TreeList(a)

Returns a new treelist containing only the elements from the first treelist for which the given functions returns True.

Examples

let assert Ok(list) = from_list([2, 4, 6, 1])
filter(list), fn(x) { x > 2 })
|> to_list
// -> [4, 6]

let assert Ok(list) = from_list([2, 4, 6, 1])
filter(list), fn(x) { x > 6 })
|> to_list
// -> []

filter_map

</>

pub fn filter_map(
  tlist: TreeList(a),
  filter_fn: fn(a) -> Result(b, c),
) -> TreeList(b)

Returns a new treelist containing only the elements from the first treelist for which the given functions returns Ok(_).

Examples

let assert Ok(list) = from_list([2, 4, 6, 1])
filter_map(list, Error)
// -> []

let assert Ok(list) = from_list([2, 4, 6, 1])
filter_map(list, fn(x) { Ok(x + 1) })
|> to_list
// -> [3, 5, 7, 2]

first

</>

pub fn first(tlist: TreeList(a)) -> Result(a, Nil)

Gets the first element from the start of the treelist, if there is one.

Examples

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

let assert Ok(list) = from_list([0])
first(list)
// -> Ok(0)

let assert Ok(list) = from_list([1, 2])
first(list)
// -> Ok(1)

fold

</>

pub fn fold(
  over list: TreeList(a),
  from initial: b,
  with fun: fn(b, a) -> b,
) -> b

Reduces a treelist of elements into a single value by calling a given function on each element, going from left to right.

fold([1, 2, 3], 0, add) is the equivalent of add(add(add(0, 1), 2), 3).

fold_right

</>

pub fn fold_right(
  over list: TreeList(a),
  from initial: b,
  with fun: fn(b, a) -> b,
) -> b

Reduces a treelist of elements into a single value by calling a given function on each element, going from right to left.

fold_right([1, 2, 3], 0, add) is the equivalent of add(add(add(0, 3), 2), 1).

from_list

</>

pub fn from_list(list: List(a)) -> Result(TreeList(a), Nil)

Takes a list and returns a new TreeList containing all the elements from the list in the same order as that list

Returns an Error(Nil) in the case that the list is too large

let assert Ok(list) = from_list([1,2,3])
get(list, 1)
// -> Ok(2)

get

</>

pub fn get(list: TreeList(a), index: Int) -> Result(a, Nil)

Returns the element at the specified position in the provided treelist

Returns an Error(Nil) if the index is outside the allowed range

Index is zero based

Examples

let list = new()
let assert Ok(new_list) = add(list, "Test")
get(new_list, 0)
// -> Ok("Test")

new() |> get(0)
// -> Error(Nil)

index_of

</>

pub fn index_of(tlist: TreeList(a), item: a) -> Int

Returns the index of the first occurrence of the specified element in this list, or -1 if this list does not contain the element.

let assert Ok(list) = from_list([1, 2, 3, 4])
index_of(list, 3)
// -> 2

let assert Ok(list) = from_list([1, 2, 3, 4, 2, 2])
index_of(list, 2)
// -> 1

let assert Ok(list) = from_list([1, 2, 3, 4])
index_of(list, 999)
// -> -1

insert

</>

pub fn insert(
  list: TreeList(a),
  index: Int,
  value: a,
) -> Result(TreeList(a), Nil)

Inserts an element at the specified index in the provided treelist

Returns an Error(Nil) if the index is outside the allowed range

Index is zero based

Returns a new TreeList containing the provided element

let list = new()
let assert Ok(new_list) = insert(list, 0, "Test")
get(new_list, 0)
// -> Ok("Test")

let list = new()
insert(list, 1, "Test")
// -> Error(Nil)

last

</>

pub fn last(tlist: TreeList(a)) -> Result(a, Nil)

Gets the last element from the start of the treelist, if there is one.

Examples

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

let assert Ok(list) = from_list([0])
last(list)
// -> Ok(0)

let assert Ok(list) = from_list([1, 2])
last(list)
// -> Ok(2)

last_index_of

</>

pub fn last_index_of(tlist: TreeList(a), item: a) -> Int

Returns the index of the last occurrence of the specified element in this list, or -1 if this list does not contain the element.

let assert Ok(list) = from_list([1, 2, 3, 4])
last_index_of(list, 3)
// -> 2

let assert Ok(list) = from_list([1, 2, 3, 4, 2, 2])
last_index_of(list, 2)
// -> 5

let assert Ok(list) = from_list([1, 2, 3, 4])
last_index_of(list, 999)
// -> -1

map

</>

pub fn map(
  tlist: TreeList(a),
  filter_fn: fn(a) -> b,
) -> TreeList(b)

Returns a new treelist containing only the elements of the first list after the function has been applied to each one.

Examples

let assert Ok(list) = from_list([2, 4, 6])
map(list, fn(x) { x * 2 })
|> to_list
// -> [4, 8, 12]

new

</>

pub fn new() -> TreeList(a)

Creates an empty treelist

remove

</>

pub fn remove(
  list: TreeList(a),
  index: Int,
) -> Result(#(a, TreeList(a)), Nil)

Removes an element at the specified index in the provided treelist

Returns an Error(Nil) if the index is outside the allowed range

Index is zero based

Returns a tuple containing the value at the specified index and the new TreeList

let list = new()
let assert Ok(new_list) = insert(list, 0, "Test")
get(new_list, 0)
// -> Ok("Test")
remove(new_list, 0)
// -> #("Test", TreeList(..))

let list = new()
remove(list, 1)
// -> Error(Nil)

repeat

</>

pub fn repeat(
  item a: a,
  times times: Int,
) -> Result(TreeList(a), Nil)

Builds a list of a given value a given number of times.

Examples

repeat("a", times: 0)
// -> new()

repeat("a", times: 5)
|> to_list
// -> ["a", "a", "a", "a", "a"]

rest

</>

pub fn rest(tlist: TreeList(a)) -> Result(TreeList(a), Nil)

Returns a new treelist minus the first element. If the treelist is empty, Error(Nil) is returned.

Examples

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

let assert Ok(list) = from_list([0])
rest(list)
// -> Ok([])

let assert Ok(list) = from_list([1, 2])
rest(list)
// -> Ok([2])

reverse

</>

pub fn reverse(tlist: TreeList(a)) -> TreeList(a)

Creates a new treelist from a given treelist containing the same elements but in the opposite order.

Examples

reverse(new())
|> to_list
// -> []

let assert Ok(list) = from_list([1])
reverse(list)
|> to_list
// -> [1]

let assert Ok(list) = from_list([1, 2])
reverse(list)
|> to_list
// -> [2, 1]

set

</>

pub fn set(
  list: TreeList(a),
  index: Int,
  value: a,
) -> Result(TreeList(a), Nil)

Updates the element at index specified in the provided treelist

Returns an Error(Nil) if the index is outside the allowed range

Index is zero based

Returns a new TreeList containing the updated node

let list = new()
let assert Ok(new_list) = add(list, "Test")
get(new_list, 0)
// -> Ok("Test")
let assert Ok(new_list) = set(list, 0, "Updated")
get(new_list, 0)
// -> Ok("Updated")

size

</>

pub fn size(list: TreeList(a)) -> Int

Returns the number of elements in the provided treelist

take

</>

pub fn take(tlist: TreeList(a), up_to_n: Int) -> TreeList(a)

Returns a treelist containing the first given number of elements from the given treelist.

If the treelist has less than the number of elements then the full treelist is returned.

Examples

let assert Ok(list) = from_list([1, 2, 3, 4])
take(list, 2)
|> to_list
// -> [1, 2]

let assert Ok(list) = from_list([1, 2, 3, 4])
take(list, 9)
|> to_list
// -> [1, 2, 3, 4]

to_iterator

</>

pub fn to_iterator(tlist: TreeList(a)) -> Iterator(a)

Creates an iterator that yields each element from the given treelist.

let assert Ok(list) = from_list([1, 2, 3, 4])
to_iterator(list)
|> to_list
// -> [1, 2, 3, 4]

to_iterator_reverse

</>

pub fn to_iterator_reverse(tlist: TreeList(a)) -> Iterator(a)

Creates an iterator that yields each element from the given treelist.

let assert Ok(list) = from_list([1, 2, 3, 4])
to_iterator_reverse(list)
|> to_list
// -> [4, 3, 2, 1]

to_list

</>

pub fn to_list(l: TreeList(a)) -> List(a)

Converts a TreeList into a standard Gleam list

let list = new()
let assert Ok(new_list) = insert(list, 0, "Test")
let assert Ok(new_list2) = insert(new_list, 1, "Second")
to_list(new_list2)
// -> ["Test", "Second"]

try_map

</>

pub fn try_map(
  tlist: TreeList(a),
  filter_fn: fn(a) -> Result(b, c),
) -> Result(TreeList(b), c)

Takes a function that returns a Result and applies it to each element in a given treelist in turn.

If the function returns Ok(new_value) for all elements in the treelist then a treelist of the new values is returned.

If the function returns Error(reason) for any of the elements then it is returned immediately. None of the elements in the treelist are processed after one returns an Error.

Examples

let assert Ok(list) = from_list([1, 2, 3])
let assert Ok(tl) = try_map(list, fn(x) { Ok(x + 2) })
treelist.to_list(tl)
// -> [3, 4, 5]

let assert Ok(list) = from_list([1, 2, 3])
try_map(list, fn(_) { Error(0) })
// -> Error(0)

let assert Ok(list) = from_list([[1], [2, 3]])
let assert Ok(tl) = try_map(list, first)
treelist.to_list(tl)
// -> Ok([1, 2])

let assert Ok(list) = from_list([[1], [], [2]])
try_map(list, first)
// -> Error(Nil)

wrap

</>

pub fn wrap(val: a) -> TreeList(a)

Returns the given item wrapped in a list.

Examples

wrap(1)
|> to_list
// -> [1]

wrap(["a", "b", "c"])
|> to_list
// -> [["a", "b", "c"]]

wrap([[]])
|> to_list
// -> [[[]]]