--- 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.
```grain from "queue" include Queue ``` ```grain 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** ```grain type Queue ``` 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.
```grain make: (?size: Number) => Queue ``` 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` | An empty queue | Examples: ```grain Queue.make() // Creates a new queue ``` ```grain 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.
```grain isEmpty: (queue: Queue) => Bool ``` Checks if the given queue contains no items. Parameters: | param | type | description | | ------- | ---------- | ------------------ | | `queue` | `Queue` | The queue to check | Returns: | type | description | | ------ | ----------------------------------------------------- | | `Bool` | `true` if the queue has no items or `false` otherwise | Examples: ```grain Queue.isEmpty(Queue.make()) == true ``` ```grain Queue.isEmpty(Queue.fromList([1, 2])) == false ``` ### Queue.**size**
Added in 0.6.0 No other changes yet.
```grain size: (queue: Queue) => Number ``` Computes the size of the input queue. Parameters: | param | type | description | | ------- | ---------- | -------------------- | | `queue` | `Queue` | The queue to inspect | Returns: | type | description | | -------- | ----------------------------------- | | `Number` | The count of the items in the queue | Examples: ```grain Queue.size(Queue.make()) == 0 ``` ```grain Queue.size(Queue.fromList([1, 2])) == 2 ``` ### Queue.**peek**
Added in 0.6.0 No other changes yet.
```grain peek: (queue: Queue) => Option ``` Provides the value at the beginning of the queue, if it exists. Parameters: | param | type | description | | ------- | ---------- | -------------------- | | `queue` | `Queue` | The queue to inspect | Returns: | type | description | | ----------- | ------------------------------------------------------------------------------------- | | `Option` | `Some(value)` containing the value at the beginning of the queue or `None` otherwise. | Examples: ```grain Queue.peek(Queue.make()) == None ``` ```grain 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.
```grain push: (value: a, queue: Queue) => Void ``` Adds a new item to the end of the queue. Parameters: | param | type | description | | ------- | ---------- | ----------------------- | | `value` | `a` | The item to be added | | `queue` | `Queue` | The queue being updated | Examples: ```grain 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.
```grain pop: (queue: Queue) => Option ``` Removes the item at the beginning of the queue. Parameters: | param | type | description | | ------- | ---------- | ----------------------- | | `queue` | `Queue` | The queue being updated | Returns: | type | description | | ----------- | ---------------------------------- | | `Option` | The element removed from the queue | Examples: ```grain 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.
```grain clear: (queue: Queue) => Void ``` Clears the queue by removing all of its elements. Parameters: | param | type | description | | ------- | ---------- | ------------------ | | `queue` | `Queue` | The queue to clear | Examples: ```grain 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.
```grain copy: (queue: Queue) => Queue ``` Produces a shallow copy of the input queue. Parameters: | param | type | description | | ------- | ---------- | ----------------- | | `queue` | `Queue` | The queue to copy | Returns: | type | description | | ---------- | -------------------------------------------------- | | `Queue` | A new queue containing the elements from the input | Examples: ```grain 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.
```grain toList: (queue: Queue) => List ``` Converts a queue into a list of its elements. Parameters: | param | type | description | | ------- | ---------- | -------------------- | | `queue` | `Queue` | The queue to convert | Returns: | type | description | | --------- | ---------------------------------- | | `List` | A list containing all queue values | Examples: ```grain 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.
```grain fromList: (list: List) => Queue ``` Creates a queue from a list. Parameters: | param | type | description | | ------ | --------- | ------------------- | | `list` | `List` | The list to convert | Returns: | type | description | | ---------- | ---------------------------------- | | `Queue` | A queue containing all list values | Examples: ```grain 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.
```grain toArray: (queue: Queue) => Array ``` Converts a queue into an array of its values. Parameters: | param | type | description | | ------- | ---------- | -------------------- | | `queue` | `Queue` | The queue to convert | Returns: | type | description | | ---------- | --------------------------------------------------- | | `Array` | An array containing all values from the given queue | Examples: ```grain 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.
```grain fromArray: (arr: Array) => Queue ``` Creates a queue from an array. Parameters: | param | type | description | | ----- | ---------- | -------------------- | | `arr` | `Array` | The array to convert | Returns: | type | description | | ---------- | -------------------------------------------- | | `Queue` | A queue containing all values from the array | Examples: ```grain 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.
```grain (==): (queue1: Queue, queue2: Queue) => Bool ``` Checks if two queues are equivalent by value. Parameters: | param | type | description | | -------- | ---------- | --------------------------- | | `queue1` | `Queue` | The first queue to compare | | `queue2` | `Queue` | The second queue to compare | Returns: | type | description | | ------ | -------------------------------------------------------- | | `Bool` | `true` if the queues are equivalent or `false` otherwise | Examples: ```grain use Queue.{ (==) } let queue1 = Queue.fromList([0, 1, 2]) let queue2 = Queue.fromList([0, 1, 2]) assert queue1 == queue2 ``` ```grain 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.
```grain 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
versionchanges
0.5.4Originally a module root API
```grain type ImmutableQueue ``` 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
versionchanges
0.5.4Originally a module root API
```grain empty: ImmutableQueue ``` An empty queue. Examples: ```grain let queue = Queue.Immutable.empty assert Queue.Immutable.isEmpty(queue) ``` #### Queue.Immutable.**isEmpty**
Added in 0.6.0
versionchanges
0.2.0Originally a module root API
```grain isEmpty: (queue: ImmutableQueue) => Bool ``` Checks if the given queue contains any values. Parameters: | param | type | description | | ------- | ------------------- | ------------------ | | `queue` | `ImmutableQueue` | The queue to check | Returns: | type | description | | ------ | ------------------------------------------------------- | | `Bool` | `true` if the given queue is empty or `false` otherwise | Examples: ```grain Queue.Immutable.isEmpty(Queue.Immutable.empty) == true ``` ```grain Queue.Immutable.isEmpty(Queue.Immutable.fromList([1, 2])) == false ``` #### Queue.Immutable.**peek**
Added in 0.6.0
versionchanges
0.2.0Originally named `head`
0.3.2Deprecated `head` function
0.3.2Originally a module root API
0.4.0Removed `head` function
```grain peek: (queue: ImmutableQueue) => Option ``` Returns the value at the beginning of the queue. It is not removed from the queue. Parameters: | param | type | description | | ------- | ------------------- | -------------------- | | `queue` | `ImmutableQueue` | The queue to inspect | Returns: | type | description | | ----------- | ------------------------------------------------------------------------------------------------- | | `Option` | `Some(value)` containing the value at the beginning of the queue, or `None` if the queue is empty | Examples: ```grain let queue = Queue.Immutable.fromList([1, 2, 3]) assert Queue.Immutable.peek(queue) == Some(1) ``` ```grain let queue = Queue.Immutable.empty assert Queue.Immutable.peek(queue) == None ``` #### Queue.Immutable.**push**
Added in 0.6.0
versionchanges
0.2.0Originally named `enqueue`
0.3.2Deprecated `enqueue` function
0.3.2Originally a module root API
0.4.0Removed `enqueue` function
```grain push: (value: a, queue: ImmutableQueue) => ImmutableQueue ``` Adds a value to the end of the queue. Parameters: | param | type | description | | ------- | ------------------- | ------------------- | | `value` | `a` | The value to append | | `queue` | `ImmutableQueue` | The queue to update | Returns: | type | description | | ------------------- | ---------------- | | `ImmutableQueue` | An updated queue | Examples: ```grain 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
versionchanges
0.2.0Originally named `dequeue`
0.3.2Deprecated `dequeue` function
0.3.2Originally a module root API
0.4.0Removed `dequeue` function
```grain pop: (queue: ImmutableQueue) => ImmutableQueue ``` Dequeues the next value in the queue. Parameters: | param | type | description | | ------- | ------------------- | ------------------- | | `queue` | `ImmutableQueue` | The queue to change | Returns: | type | description | | ------------------- | ---------------- | | `ImmutableQueue` | An updated queue | Examples: ```grain let queue = Queue.Immutable.fromList([1, 2, 3]) let queue = Queue.Immutable.pop(queue) assert Queue.Immutable.peek(queue) == Some(2) ``` ```grain let queue = Queue.Immutable.empty let queue = Queue.Immutable.pop(queue) assert Queue.Immutable.isEmpty(queue) ``` #### Queue.Immutable.**size**
Added in 0.6.0
versionchanges
0.3.2Originally a module root API
```grain size: (queue: ImmutableQueue) => Number ``` Get the number of values in a queue. Parameters: | param | type | description | | ------- | ------------------- | -------------------- | | `queue` | `ImmutableQueue` | The queue to inspect | Returns: | type | description | | -------- | --------------------------------- | | `Number` | The number of values in the queue | Examples: ```grain Queue.Immutable.size(Queue.Immutable.empty) == 0 ``` ```grain Queue.Immutable.size(Queue.Immutable.fromList([1, 2])) == 2 ``` #### Queue.Immutable.**toList**
Added in 0.6.0 No other changes yet.
```grain toList: (queue: ImmutableQueue) => List ``` Converts a queue into a list of its elements. Parameters: | param | type | description | | ------- | ------------------- | -------------------- | | `queue` | `ImmutableQueue` | The queue to convert | Returns: | type | description | | --------- | ---------------------------------- | | `List` | A list containing all queue values | Examples: ```grain 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] ``` ```grain let queue = Queue.Immutable.fromList([1, 2, 3]) assert Queue.Immutable.toList(queue) == [1, 2, 3] ``` ```grain let queue = Queue.Immutable.empty assert Queue.Immutable.toList(queue) == [] ``` #### Queue.Immutable.**fromList**
Added in 0.6.0 No other changes yet.
```grain fromList: (list: List) => ImmutableQueue ``` Creates a queue from a list. Parameters: | param | type | description | | ------ | --------- | ------------------- | | `list` | `List` | The list to convert | Returns: | type | description | | ------------------- | ---------------------------------- | | `ImmutableQueue` | A queue containing all list values | Examples: ```grain let queue = Queue.Immutable.fromList([1, 2, 3]) assert Queue.Immutable.peek(queue) == Some(1) assert Queue.Immutable.size(queue) == 3 ```