non_empty_list - v2.1.0

non_empty_list

Types

NonEmptyList

</>

A list that is guaranteed to contain at least one item.

pub type NonEmptyList(a) {
  NonEmptyList(first: a, rest: List(a))
}

Constructors 

  • NonEmptyList(first: a, rest: List(a))

Functions

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

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

> single("a")
> |> append(new("b", ["c"])
NonEmptyList("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

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

> new("a", ["b", "c"])
> |> append_list([])
NonEmptyList("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

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

> 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

> new(1, [2, 3, 4])
> |> first
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

> new(1, [3, 5])
> |> flat_map(fn(x) { new(x, [x + 1]) })
NonEmptyList(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

> new(new(1, [2, 3]), [new(3, [4, 5])])
> |> flatten
NonEmptyList(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

> from_list([1, 2, 3, 4])
Ok(NonEmptyList(1, [2, 3, 4]))

> from_list(["a"])
Ok(NonEmptyList("a", []))

> from_list([])
Error(Nil)

group

</> 
pub fn group(
  list: NonEmptyList(a),
  by key: fn(a) -> b,
) -> Dict(b, NonEmptyList(a))

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

new(Ok(3), [Error("Wrong"), Ok(200), Ok(73)])
|> group(by: fn(i) {
  case i {
    Ok(_) -> "Successful"
    Error(_) -> "Failed"
  }
})
|> dict.to_list
// -> [
//   #("Failed", NonEmptyList(Error("Wrong"), [])),
//   #("Successful", NonEmptyList(Ok(73), [Ok(200), Ok(3)])),
// ]

import gleam/dict

new(1, [2,3,4,5])
|> group(by: fn(i) { i - i / 3 * 3 })
|> dict.to_list
// -> [#(0, NonEmptyList(3, [])), #(1, NonEmptyList(4, [1])), #(2, NonEmptyList(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

> new("a", ["b", "c"])
> |> index_map(fn(index, letter) { #(index, letter) })
NonEmptyList(#(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

> new(1, [2, 3, 4])
> |> intersperse(with: 0)
NonEmptyList(1, [0, 2, 0, 3, 0, 4])

> single("a")
> |> intersperse(with: "z")
NonEmptyList("a", ["z"])

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

> single(1)
> |> last
1

> new(1, [2, 3, 4])
> |> last
4

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

> new(1, [2, 3])
> |> map(fn(x) { x + 1 })
NonEmptyList(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

> map2(new(1, [2, 3]), new(4, [5, 6]), fn(x, y) { x + y }) |> to_list
[5, 7, 9]

> map2(new(1, [2]), new("a", ["b", "c"]), fn(i, x) { #(i, x) }) |> to_list
[#(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

> new(1, [2, 3])
> |> map_fold(from: 100, with: fn(memo, n) { #(memo + i, i * 2) })
#(106, NonEmptyList(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.

Examples

> new(1, [2, 3, 4])
NonEmptyList(1, [2, 3, 4])

> new("a", [])
NonEmptyList("a", [])

prepend

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

Prefixes an item to a non-empty list.

Examples

> new(2, [3, 4])
> |> prepend(1)
NonEmptyList(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

> 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

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

> 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

> new(1, [2, 3, 4])
> |> reverse
NonEmptyList(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

> new(1, [2, 3, 4])
> |> scan(from: 100, with: fn(acc, i) { acc + i })
NonEmptyList(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

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

single

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

Creates a non-empty list with a single element.

Examples

> single(1)
NonEmptyList(1, [])

sort

</> 
pub fn sort(
  list: NonEmptyList(a),
  by compare: fn(a, a) -> 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
> new(4, [1, 3, 4, 2, 6, 5])
> sort(by: int.compare)
NonEmptyList(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

> strict_zip(single(1), new("a", ["b", "c"]))
Error(Nil)

> strict_zip(new(1, [2, 3]), single("a"))
Error(Nil)

> strict_zip(new(1, [2, 3]), new("a", ["b", "c"]))
Ok(NonEmptyList(#(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

> new(1, [2, 3, 4])
> take(2)
[1, 2]

> 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

> new(1, [2, 3, 4])
> |> to_list
[1, 2, 3, 4]

> 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

> new(1, [1, 2, 3, 1, 4, 4, 3])
> |> unique
NonEmptyList(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

> new(#(1, "a"), [#(2, "b"), #(3, "c")])
> |> unzip
#(NonEmptyList(1, [2, 3]), NonEmptyList("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

> zip(new(1, [2, 3]), single("a"))
NonEmptyList(#(1, "a"), [])

> zip(single(1), new("a", ["b", "c"]))
NonEmptyList(#(1, "a"), [])

> zip(new(1, [2, 3]), new("a", ["b", "c"]))
NonEmptyList(#(1, "a"), [#(2, "b"), #(3, "c")])
✨ Search Document