non_empty_list · non_empty_list

all

pub fn all(
  results: NonEmptyList(Result(a, e)),
) -> Result(NonEmptyList(a), e)

Combines a NonEmptyList of Results into a single Result. If all elements in the list are Ok then returns an Ok holding the list of values. If any element is Error then returns the first error.

This function runs in linear time, and it traverses and copies the Ok values or the Error value.

Examples

assert all(new(Ok(1), [Ok(2)])) == Ok(new(1, [2]))
assert all(new(Ok(1), [Error("e")])) == Error("e")

append

</>

pub fn append(
  first: NonEmptyList(a),
  second: NonEmptyList(a),
) -> NonEmptyList(a)

Joins a non-empty list onto the end of a non-empty list.

This function runs in linear time, and it traverses and copies the first non-empty list.

Examples

assert new(1, [2, 3, 4])
  |> append(new(5, [6, 7]))
  == new(1, [2, 3, 4, 5, 6, 7])

assert single("a")
  |> append(new("b", ["c"])
  == new("a", ["b", "c"])

append_list

</>

pub fn append_list(
  first: NonEmptyList(a),
  second: List(a),
) -> NonEmptyList(a)

Joins a list onto the end of a non-empty list.

This function runs in linear time, and it traverses and copies the first non-empty list.

Examples

assert new(1, [2, 3, 4])
  |> append_list([5, 6, 7])
  == new(1, [2, 3, 4, 5, 6, 7])

assert new("a", ["b", "c"])
  |> append_list([])
  == new("a", ["b", "c"])

drop

</>

pub fn drop(from list: NonEmptyList(a), up_to n: Int) -> List(a)

Returns a list that is the given non-empty list with up to the given number of elements removed from the front of the list.

Examples

assert new("a", ["b", "c"]) |> drop(up_to: 2) == ["c"]
assert new("a", ["b", "c"]) |> drop(up_to: 3) == []

first

</>

pub fn first(list: NonEmptyList(a)) -> a

Gets the first element from the start of the non-empty list.

Examples

assert first(new(1, [2, 3, 4])) == 1

flat_map

</>

pub fn flat_map(
  over list: NonEmptyList(a),
  with fun: fn(a) -> NonEmptyList(b),
) -> NonEmptyList(b)

Maps the non-empty list with the given function and then flattens it.

Examples

assert new(1, [3, 5])
  |> flat_map(fn(x) { new(x, [x + 1]) })
  == new(1, [2, 3, 4, 5, 6])

flatten

</>

pub fn flatten(
  lists: NonEmptyList(NonEmptyList(a)),
) -> NonEmptyList(a)

Flattens a non-empty list of non-empty lists into a single non-empty list.

This function traverses all elements twice.

Examples

assert new(new(1, [2, 3]), [new(3, [4, 5])])
  |> flatten
  == new(1, [2, 3, 4, 5])

from_list

</>

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

Attempts to turn a list into a non-empty list, fails if the starting list is empty.

Examples

assert from_list([1, 2, 3, 4]) == Ok(new(1, [2, 3, 4]))
assert from_list(["a"]) == Ok(single("a"))
assert from_list([]) == Error(Nil)

group

</>

pub fn group(
  list: NonEmptyList(v),
  by key: fn(v) -> k,
) -> dict.Dict(k, NonEmptyList(v))

Takes a list and groups the values by a key which is built from a key function.

Does not preserve the initial value order.

Examples

import gleam/dict

assert new(1, [2, 3, 4, 5])
  |> group(by: fn(i) { i - i / 3 * 3 })
  == dict.from_list([
    #(0, new(3, [])),
    #(1, new(4, [1])),
    #(2, new(5, [2]))
  ]

index_map

</>

pub fn index_map(
  list: NonEmptyList(a),
  with fun: fn(Int, a) -> b,
) -> NonEmptyList(b)

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

The index starts at 0, so the first element is 0, the second is 1, and so on.

Examples

assert new("a", ["b", "c"])
  |> index_map(fn(index, letter) { #(index, letter) })
  == new(#(0, "a"), [#(1, "b"), #(2, "c")])

intersperse

</>

pub fn intersperse(
  list: NonEmptyList(a),
  with elem: a,
) -> NonEmptyList(a)

Inserts a given value between each existing element in a given list.

This function runs in linear time and copies the list.

Examples

assert new(1, [2, 3]) |> intersperse(with: 0) == new(1, [0, 2, 0, 3])
assert single("a") |> intersperse(with: "z") == single("a")

last

</>

pub fn last(list: NonEmptyList(a)) -> a

Returns the last element in the given list.

This function runs in linear time. For a collection oriented around performant access at either end, see gleam/queue.Queue.

Examples

assert last(single(1)) == 1
assert last(new(1, [2, 3, 4])) == 4

length

</>

pub fn length(of list: NonEmptyList(a)) -> Int

Counts the number of elements in a given list.

This function has to traverse the list to determine the number of elements, so it runs in linear time.

Examples

assert length(single(0)) == 1
assert length(new(0, [1])) == 2

map

</>

pub fn map(
  over list: NonEmptyList(a),
  with fun: fn(a) -> b,
) -> NonEmptyList(b)

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

Examples

assert new(1, [2, 3]) |> map(fn(x) { x + 1 }) == new(2, [3, 4])

map2

</>

pub fn map2(
  list1: NonEmptyList(a),
  list2: NonEmptyList(b),
  with fun: fn(a, b) -> c,
) -> NonEmptyList(c)

Combines two non-empty lists into a single non-empty list using the given function.

If a list is longer than the other the extra elements are dropped.

Examples

assert map2(new(1, [2, 3]), new(4, [5, 6]), fn(x, y) { x + y })
  == new(5, [7, 9])
assert map2(new(1, [2]), new("a", ["b", "c"]), fn(i, x) { #(i, x) })
  == new(#(1, "a"), [#(2, "b")])

map_fold

</>

pub fn map_fold(
  over list: NonEmptyList(a),
  from acc: b,
  with fun: fn(b, a) -> #(b, c),
) -> #(b, NonEmptyList(c))

Similar to map but also lets you pass around an accumulated value.

Examples

assert new(1, [2, 3])
  |> map_fold(from: 100, with: fn(memo, n) { #(memo + i, i * 2) })
  == #(106, new(2, [4, 6]))

new

</>

pub fn new(first: a, rest: List(a)) -> NonEmptyList(a)

Creates a new non-empty list given its first element and a list for the rest of the elements.

prepend

</>

pub fn prepend(
  to list: NonEmptyList(a),
  this item: a,
) -> NonEmptyList(a)

Prefixes an item to a non-empty list.

Examples

assert new(2, [3, 4]) |> prepend(1) == new(1, [2, 3, 4])

reduce

</>

pub fn reduce(
  over list: NonEmptyList(a),
  with fun: fn(a, a) -> a,
) -> a

This function acts similar to fold, but does not take an initial state. Instead, it starts from the first element in the non-empty list and combines it with each subsequent element in turn using the given function. The function is called as fun(accumulator, current_element).

Examples

assert new(1, [2, 3, 4]) |> reduce(fn(acc, x) { acc + x }) == 10

rest

</>

pub fn rest(list: NonEmptyList(a)) -> List(a)

Returns the list minus the first element. Since the remaining list could be empty this functions returns a normal list.

Examples

assert new(1, [2, 3, 4]) |> rest == [2, 3, 4]
assert single(1) |> rest == []

reverse

</>

pub fn reverse(list: NonEmptyList(a)) -> NonEmptyList(a)

Creates a new non-empty list from a given non-empty list containing the same elements but in the opposite order.

This function has to traverse the non-empty list to create the new reversed non-empty list, so it runs in linear time.

Examples

assert new(1, [2, 3, 4]) |> reverse == new(4, [3, 2, 1])

scan

</>

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

Similar to fold, but yields the state of the accumulator at each stage.

Examples

assert new(1, [2, 3, 4])
  |> scan(from: 100, with: fn(acc, i) { acc + i })
  == new(101 [103, 106, 110])

shuffle

</>

pub fn shuffle(list: NonEmptyList(a)) -> NonEmptyList(a)

Takes a non-empty list, randomly sorts all items and returns the shuffled non-empty list.

This function uses Erlang’s :rand module or Javascript’s Math.random() to calcuate the index shuffling.

Examples

assert new("a", ["b", "c", "d"]) |> shuffle == new("c", ["a", "d", "b"])

single

</>

pub fn single(first: a) -> NonEmptyList(a)

Creates a non-empty list with a single element.

Examples

assert single(1) == new(1, [])

sort

</>

pub fn sort(
  list: NonEmptyList(a),
  by compare: fn(a, a) -> order.Order,
) -> NonEmptyList(a)

Sorts a given non-empty list from smallest to largest based upon the ordering specified by a given function.

Examples

import gleam/int
assert new(4, [1, 3, 4, 2, 6, 5]) |> sort(by: int.compare)
  == new(1, [2, 3, 4, 4, 5, 6])

strict_zip

</>

pub fn strict_zip(
  list: NonEmptyList(a),
  with other: NonEmptyList(b),
) -> Result(NonEmptyList(#(a, b)), Nil)

Takes two non-empty lists and returns a single non-empty list of 2-element tuples.

If one of the non-empty lists is longer than the other, an Error is returned.

Examples

assert strict_zip(single(1), new("a", ["b", "c"])) == Error(Nil)
assert strict_zip(new(1, [2, 3]), single("a")) == Error(Nil)
assert strict_zip(new(1, [2, 3]), new("a", ["b", "c"]))
  == Ok(new(#(1, "a"), [#(2, "b"), #(3, "c")]))

take

</>

pub fn take(from list: NonEmptyList(a), up_to n: Int) -> List(a)

Returns a list containing the first given number of elements from the given non-empty list.

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

This function runs in linear time but does not copy the list.

Examples

assert new(1, [2, 3, 4]) |> take(2) == [1, 2]
assert new(1, [2, 3, 4]) |> take(9) == [1, 2, 3, 4]

to_list

</>

pub fn to_list(non_empty: NonEmptyList(a)) -> List(a)

Turns a non-empty list back into a normal list with the same elements.

Examples

assert new(1, [2, 3, 4]) |> to_list == [1, 2, 3, 4]
assert single("a") |> to_list == ["a"]

unique

</>

pub fn unique(list: NonEmptyList(a)) -> NonEmptyList(a)

Removes any duplicate elements from a given list.

This function returns in loglinear time.

Examples

assert new(1, [1, 2, 3, 1, 4, 4, 3]) |> unique == new(1, [2, 3, 4])

unzip

</>

pub fn unzip(
  list: NonEmptyList(#(a, b)),
) -> #(NonEmptyList(a), NonEmptyList(b))

Takes a single non-empty list of 2-element tuples and returns two non-empty lists.

Examples

assert new(#(1, "a"), [#(2, "b"), #(3, "c")]) |> unzip
 == #(new(1, [2, 3]), new("a", ["b", "c"]))

zip

</>

pub fn zip(
  list: NonEmptyList(a),
  with other: NonEmptyList(b),
) -> NonEmptyList(#(a, b))

Takes two non-empty lists and returns a single non-empty list of 2-element tuples.

If one of the non-empty lists is longer than the other, the remaining elements from the longer non-empty list are not used.

Examples

assert zip(new(1, [2, 3]), single("a")) == new(#(1, "a"), [])
assert zip(single(1), new("a", ["b", "c"])) == new(#(1, "a"), [])
assert zip(new(1, [2, 3]), new("a", ["b", "c"])) ==
  new(#(1, "a"), [#(2, "b"), #(3, "c")])

Constructors

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples