grain/stdlib/queue.md at main · grain-lang/grain

title	Queue

A queue is a FIFO (first-in-first-out) data structure where new values are added to the end and retrieved or removed from the beginning.

The default implementation is mutable, but an immutable queue implementation is available in the Immutable submodule.

Added in 0.2.0

No other changes yet.

from "queue" include Queue

let queue = Queue.fromList([0, 1])
Queue.push(2, queue)
assert Queue.pop(queue) == Some(0)
assert Queue.pop(queue) == Some(1)
assert Queue.pop(queue) == Some(2)

Types

Type declarations included in the Queue module.

Queue.Queue

type Queue<a>

A mutable FIFO (first-in-first-out) data structure.

Values

Functions and constants included in the Queue module.

Queue.make

Added in 0.6.0

No other changes yet.

make: (?size: Number) => Queue<a>

Creates a new queue with an initial storage of the given size. As values are added or removed, the internal storage may grow or shrink. Generally, you won’t need to care about the storage size of your queue and can use the default size.

Parameters:

param	type	description
`?size`	`Number`	The initial storage size of the queue

Returns:

type	description
`Queue<a>`	An empty queue

Examples:

Queue.make() // Creates a new queue

Queue.make(size=16) // Creates a new queue with an initial size of 16

Queue.isEmpty

Added in 0.6.0

No other changes yet.

isEmpty: (queue: Queue<a>) => Bool

Checks if the given queue contains no items.

Parameters:

param	type	description
`queue`	`Queue<a>`	The queue to check

Returns:

type	description
`Bool`	`true` if the queue has no items or `false` otherwise

Examples:

Queue.isEmpty(Queue.make()) == true

Queue.isEmpty(Queue.fromList([1, 2])) == false

Queue.size

Added in 0.6.0

No other changes yet.

size: (queue: Queue<a>) => Number

Computes the size of the input queue.

Parameters:

param	type	description
`queue`	`Queue<a>`	The queue to inspect

Returns:

type	description
`Number`	The count of the items in the queue

Examples:

Queue.size(Queue.make()) == 0

Queue.size(Queue.fromList([1, 2])) == 2

Queue.peek

Added in 0.6.0

No other changes yet.

peek: (queue: Queue<a>) => Option<a>

Provides the value at the beginning of the queue, if it exists.

Parameters:

param	type	description
`queue`	`Queue<a>`	The queue to inspect

Returns:

type	description
`Option<a>`	`Some(value)` containing the value at the beginning of the queue or `None` otherwise.

Examples:

Queue.peek(Queue.make()) == None

let queue = Queue.make()
Queue.push(1, queue)
assert Queue.peek(queue) == Some(1)

Queue.push

Added in 0.6.0

No other changes yet.

push: (value: a, queue: Queue<a>) => Void

Adds a new item to the end of the queue.

Parameters:

param	type	description
`value`	`a`	The item to be added
`queue`	`Queue<a>`	The queue being updated

Examples:

let queue = Queue.make()
assert Queue.peek(queue) == None
Queue.push(1, queue)
assert Queue.peek(queue) == Some(1)

Queue.pop

Added in 0.6.0

No other changes yet.

pop: (queue: Queue<a>) => Option<a>

Removes the item at the beginning of the queue.

Parameters:

param	type	description
`queue`	`Queue<a>`	The queue being updated

Returns:

type	description
`Option<a>`	The element removed from the queue

Examples:

let queue = Queue.make()
Queue.push(1, queue)
assert Queue.pop(queue) == Some(1)
assert Queue.pop(queue) == None

Queue.clear

Added in 0.6.0

No other changes yet.

clear: (queue: Queue<a>) => Void

Clears the queue by removing all of its elements.

Parameters:

param	type	description
`queue`	`Queue<a>`	The queue to clear

Examples:

let queue = Queue.make()
Queue.push(1, queue)
assert Queue.size(queue) == 1
Queue.clear(queue)
assert Queue.size(queue) == 0

Queue.copy

Added in 0.6.0

No other changes yet.

copy: (queue: Queue<a>) => Queue<a>

Produces a shallow copy of the input queue.

Parameters:

param	type	description
`queue`	`Queue<a>`	The queue to copy

Returns:

type	description
`Queue<a>`	A new queue containing the elements from the input

Examples:

let queue = Queue.make()
Queue.push(1, queue)
let copiedQueue = Queue.copy(queue)
Queue.push(2, queue) // Does not affect copiedQueue
assert Queue.pop(copiedQueue) == Some(1)

Queue.toList

Added in 0.6.0

No other changes yet.

toList: (queue: Queue<a>) => List<a>

Converts a queue into a list of its elements.

Parameters:

param	type	description
`queue`	`Queue<a>`	The queue to convert

Returns:

type	description
`List<a>`	A list containing all queue values

Examples:

let queue = Queue.make()
Queue.push(0, queue)
Queue.push(1, queue)
Queue.push(2, queue)
assert Queue.toList(queue) == [0, 1, 2]

Queue.fromList

Added in 0.6.0

No other changes yet.

fromList: (list: List<a>) => Queue<a>

Creates a queue from a list.

Parameters:

param	type	description
`list`	`List<a>`	The list to convert

Returns:

type	description
`Queue<a>`	A queue containing all list values

Examples:

let queue = Queue.fromList([0, 1])
assert Queue.pop(queue) == Some(0)
assert Queue.pop(queue) == Some(1)

Queue.toArray

Added in 0.6.0

No other changes yet.

toArray: (queue: Queue<a>) => Array<a>

Converts a queue into an array of its values.

Parameters:

param	type	description
`queue`	`Queue<a>`	The queue to convert

Returns:

type	description
`Array<a>`	An array containing all values from the given queue

Examples:

let queue = Queue.make()
Queue.push(0, queue)
Queue.push(1, queue)
Queue.push(2, queue)
assert Queue.toArray(queue) == [> 0, 1, 2]

Queue.fromArray

Added in 0.6.0

No other changes yet.

fromArray: (arr: Array<a>) => Queue<a>

Creates a queue from an array.

Parameters:

param	type	description
`arr`	`Array<a>`	The array to convert

Returns:

type	description
`Queue<a>`	A queue containing all values from the array

Examples:

let queue = Queue.fromArray([> 0, 1])
assert Queue.pop(queue) == Some(0)
assert Queue.pop(queue) == Some(1)

Queue.(==)

Added in 0.6.0

No other changes yet.

(==): (queue1: Queue<a>, queue2: Queue<a>) => Bool

Checks if two queues are equivalent by value.

Parameters:

param	type	description
`queue1`	`Queue<a>`	The first queue to compare
`queue2`	`Queue<a>`	The second queue to compare

Returns:

type	description
`Bool`	`true` if the queues are equivalent or `false` otherwise

Examples:

use Queue.{ (==) }
let queue1 = Queue.fromList([0, 1, 2])
let queue2 = Queue.fromList([0, 1, 2])
assert queue1 == queue2

use Queue.{ (==) }
let queue1 = Queue.fromList([0, 1, 2])
let queue2 = Queue.fromList([0, 1, 3])
assert !(queue1 == queue2)

Queue.Immutable

An immutable queue implementation.

Added in 0.6.0

No other changes yet.

let queue = Immutable.Queue.fromList([0, 1])
let queue = Immutable.Queue.push(2, queue)
assert Immutable.Queue.peek(queue) == Some(0)
let queue = Immutable.Queue.pop(queue)
assert Immutable.Queue.peek(queue) == Some(1)
ignore(Queue.Immutable.pop(queue)) // Does not affect the original queue
assert Immutable.Queue.peek(queue) == Some(1)

Types

Type declarations included in the Queue.Immutable module.

Queue.Immutable.ImmutableQueue

Added in 0.6.0

version	changes
`0.5.4`	Originally a module root API

type ImmutableQueue<a>

An immutable FIFO (first-in-first-out) data structure.

Values

Functions and constants included in the Queue.Immutable module.

Queue.Immutable.empty

Added in 0.6.0

version	changes
`0.5.4`	Originally a module root API

empty: ImmutableQueue<a>

An empty queue.

Examples:

let queue = Queue.Immutable.empty
assert Queue.Immutable.isEmpty(queue)

Queue.Immutable.isEmpty

Added in 0.6.0

version	changes
`0.2.0`	Originally a module root API

isEmpty: (queue: ImmutableQueue<a>) => Bool

Checks if the given queue contains any values.

Parameters:

param	type	description
`queue`	`ImmutableQueue<a>`	The queue to check

Returns:

type	description
`Bool`	`true` if the given queue is empty or `false` otherwise

Examples:

Queue.Immutable.isEmpty(Queue.Immutable.empty) == true

Queue.Immutable.isEmpty(Queue.Immutable.fromList([1, 2])) == false

Queue.Immutable.peek

Added in 0.6.0

version	changes
`0.2.0`	Originally named `head`
`0.3.2`	Deprecated `head` function
`0.3.2`	Originally a module root API
`0.4.0`	Removed `head` function

peek: (queue: ImmutableQueue<a>) => Option<a>

Returns the value at the beginning of the queue. It is not removed from the queue.

Parameters:

param	type	description
`queue`	`ImmutableQueue<a>`	The queue to inspect

Returns:

type	description
`Option<a>`	`Some(value)` containing the value at the beginning of the queue, or `None` if the queue is empty

Examples:

let queue = Queue.Immutable.fromList([1, 2, 3])
assert Queue.Immutable.peek(queue) == Some(1)

let queue = Queue.Immutable.empty
assert Queue.Immutable.peek(queue) == None

Queue.Immutable.push

Added in 0.6.0

version	changes
`0.2.0`	Originally named `enqueue`
`0.3.2`	Deprecated `enqueue` function
`0.3.2`	Originally a module root API
`0.4.0`	Removed `enqueue` function

push: (value: a, queue: ImmutableQueue<a>) => ImmutableQueue<a>

Adds a value to the end of the queue.

Parameters:

param	type	description
`value`	`a`	The value to append
`queue`	`ImmutableQueue<a>`	The queue to update

Returns:

type	description
`ImmutableQueue<a>`	An updated queue

Examples:

let queue = Queue.Immutable.fromList([1])
assert Queue.Immutable.size(queue) == 1
let queue = Queue.Immutable.push(2, queue)
assert Queue.Immutable.size(queue) == 2

Queue.Immutable.pop

Added in 0.6.0

version	changes
`0.2.0`	Originally named `dequeue`
`0.3.2`	Deprecated `dequeue` function
`0.3.2`	Originally a module root API
`0.4.0`	Removed `dequeue` function

pop: (queue: ImmutableQueue<a>) => ImmutableQueue<a>

Dequeues the next value in the queue.

Parameters:

param	type	description
`queue`	`ImmutableQueue<a>`	The queue to change

Returns:

type	description
`ImmutableQueue<a>`	An updated queue

Examples:

let queue = Queue.Immutable.fromList([1, 2, 3])
let queue = Queue.Immutable.pop(queue)
assert Queue.Immutable.peek(queue) == Some(2)

let queue = Queue.Immutable.empty
let queue = Queue.Immutable.pop(queue)
assert Queue.Immutable.isEmpty(queue)

Queue.Immutable.size

Added in 0.6.0

version	changes
`0.3.2`	Originally a module root API

size: (queue: ImmutableQueue<a>) => Number

Get the number of values in a queue.

Parameters:

param	type	description
`queue`	`ImmutableQueue<a>`	The queue to inspect

Returns:

type	description
`Number`	The number of values in the queue

Examples:

Queue.Immutable.size(Queue.Immutable.empty) == 0

Queue.Immutable.size(Queue.Immutable.fromList([1, 2])) == 2

Queue.Immutable.toList

Added in 0.6.0

No other changes yet.

toList: (queue: ImmutableQueue<a>) => List<a>

Converts a queue into a list of its elements.

Parameters:

param	type	description
`queue`	`ImmutableQueue<a>`	The queue to convert

Returns:

type	description
`List<a>`	A list containing all queue values

Examples:

let queue = Queue.Immutable.empty
let queue = Queue.Immutable.push(1, queue)
let queue = Queue.Immutable.push(2, queue)
assert Queue.Immutable.toList(queue) == [1, 2]

let queue = Queue.Immutable.fromList([1, 2, 3])
assert Queue.Immutable.toList(queue) == [1, 2, 3]

let queue = Queue.Immutable.empty
assert Queue.Immutable.toList(queue) == []

Queue.Immutable.fromList

Added in 0.6.0

No other changes yet.

fromList: (list: List<a>) => ImmutableQueue<a>

Creates a queue from a list.

Parameters:

param	type	description
`list`	`List<a>`	The list to convert

Returns:

type	description
`ImmutableQueue<a>`	A queue containing all list values

Examples:

let queue = Queue.Immutable.fromList([1, 2, 3])
assert Queue.Immutable.peek(queue) == Some(1)
assert Queue.Immutable.size(queue) == 3

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Types

Queue.Queue

Values

Queue.make

Queue.isEmpty

Queue.size

Queue.peek

Queue.push

Queue.pop

Queue.clear

Queue.copy

Queue.toList

Queue.fromList

Queue.toArray

Queue.fromArray

Queue.(==)

Queue.Immutable

Types

Queue.Immutable.ImmutableQueue

Values

Queue.Immutable.empty

Queue.Immutable.isEmpty

Queue.Immutable.peek

Queue.Immutable.push

Queue.Immutable.pop

Queue.Immutable.size

Queue.Immutable.toList

Queue.Immutable.fromList

Uh oh!

Uh oh!

FilesExpand file tree

queue.md

Latest commit

History

queue.md

File metadata and controls

Types

Queue.Queue

Values

Queue.make

Queue.isEmpty

Queue.size

Queue.peek

Queue.push

Queue.pop

Queue.clear

Queue.copy

Queue.toList

Queue.fromList

Queue.toArray

Queue.fromArray

Queue.(==)

Queue.Immutable

Types

Queue.Immutable.ImmutableQueue

Values

Queue.Immutable.empty

Queue.Immutable.isEmpty

Queue.Immutable.peek

Queue.Immutable.push

Queue.Immutable.pop

Queue.Immutable.size

Queue.Immutable.toList

Queue.Immutable.fromList