gleam/deque

Types

Deque

opaque </>

A deque (double-ended-queue) is an ordered collection of elements. It is similar to a list. Unlike a list elements can be added to or removed from either the front or the back in a performant fashion.

The internal representation may be different for two deques with the same elements in the same order if the deques were constructed in different ways. This is the price paid for a deque’s fast access at both the front and the back.

Because of unpredictable internal representation the equality operator == may return surprising results, and the is_equal and is_logically_equal functions are the recommended way to test deques for equality.

pub opaque type Deque(a)

Functions

from_list

</>

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

Converts a list of elements into a deque of the same elements in the same order. The first element in the list becomes the front element in the deque.

This function runs in constant time.

Examples

[1, 2, 3] |> from_list |> length
// -> 3

is_empty

</>

pub fn is_empty(deque: Deque(a)) -> Bool

Determines whether or not the deque is empty.

This function runs in constant time.

Examples

[] |> from_list |> is_empty
// -> True

[1] |> from_list |> is_empty
// -> False

[1, 2] |> from_list |> is_empty
// -> False

is_equal

</>

pub fn is_equal(a: Deque(a), to b: Deque(a)) -> Bool

Checks whether two deques have the same elements in the same order.

This function is useful as the internal representation may be different for two deques with the same elements in the same order depending on how they were constructed, so the equality operator == may return surprising results.

This function runs in linear time.

is_logically_equal

</>

pub fn is_logically_equal(
  a: Deque(a),
  to b: Deque(a),
  checking element_is_equal: fn(a, a) -> Bool,
) -> Bool

Checks whether two deques have equal elements in the same order, where the equality of elements is determined by a given equality checking function.

This function runs in linear time multiplied by the time taken by the element equality checking function.

length

</>

pub fn length(deque: Deque(a)) -> Int

Counts the number of elements in a given deque.

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

Examples

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

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

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

new

</>

pub fn new() -> Deque(a)

Creates a fresh deque that contains no values.

pop_back

</>

pub fn pop_back(
  from deque: Deque(a),
) -> Result(#(a, Deque(a)), Nil)

Gets the last element from the deque, returning the element and a new deque without that element.

This function typically runs in constant time, but will occasionally run in linear time.

Examples

new()
|> push_back(0)
|> push_back(1)
|> pop_back
// -> Ok(#(1, push_front(new(), 0)))

new()
|> push_front(0)
|> pop_back
// -> Ok(#(0, new()))

new() |> pop_back
// -> Error(Nil)

pop_front

</>

pub fn pop_front(
  from deque: Deque(a),
) -> Result(#(a, Deque(a)), Nil)

Gets the first element from the deque, returning the element and a new deque without that element.

This function typically runs in constant time, but will occasionally run in linear time.

Examples

new()
|> push_front(1)
|> push_front(0)
|> pop_front
// -> Ok(#(0, push_back(new(), 1)))

new()
|> push_back(0)
|> pop_front
// -> Ok(#(0, new()))

new() |> pop_back
// -> Error(Nil)

push_back

</>

pub fn push_back(onto deque: Deque(a), this item: a) -> Deque(a)

Pushes an element onto the back of the deque.

Examples

[1, 2] |> from_list |> push_back(3) |> to_list
// -> [1, 2, 3]

push_front

</>

pub fn push_front(onto deque: Deque(a), this item: a) -> Deque(a)

Pushes an element onto the front of the deque.

Examples

[0, 0] |> from_list |> push_front(1) |> to_list
// -> [1, 0, 0]

reverse

</>

pub fn reverse(deque: Deque(a)) -> Deque(a)

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

This function runs in constant time.

Examples

[] |> from_list |> reverse |> to_list
// -> []

[1] |> from_list |> reverse |> to_list
// -> [1]

[1, 2] |> from_list |> reverse |> to_list
// -> [2, 1]

to_list

</>

pub fn to_list(deque: Deque(a)) -> List(a)

Converts a deque of elements into a list of the same elements in the same order. The front element in the deque becomes the first element in the list.

This function runs in linear time.

Examples

new() |> push_back(1) |> push_back(2) |> to_list
// -> [1, 2]