Skip to content

Commit

Permalink
chore(stdlib): Add examples to Queue module (#2200)
Browse files Browse the repository at this point in the history 
Co-authored-by: Oscar Spencer <[email protected]>
  • Loading branch information
@spotandjake @ospencer
spotandjake and ospencer authored Jan 2, 2025
1 parent 551f5ad commit 1179c91
Show file tree
Hide file tree
Showing 2 changed files with 457 additions and 49 deletions.
206 changes: 179 additions & 27 deletions stdlib/queue.gr
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,13 @@
*
* @example from "queue" include Queue
*
* @example
* 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)
*
* @since v0.2.0
*/
module Queue
Expand All @@ -33,6 +40,9 @@ abstract record Queue<a> {
* @param size: The initial storage size of the queue
* @returns An empty queue
*
* @example Queue.make() // Creates a new queue
* @example Queue.make(size=16) // Creates a new queue with an initial size of 16
*
* @since v0.6.0
*/
provide let make = (size=16) => {
Expand All @@ -45,6 +55,9 @@ provide let make = (size=16) => {
* @param queue: The queue to check
* @returns `true` if the queue has no items or `false` otherwise
*
* @example Queue.isEmpty(Queue.make()) == true
* @example Queue.isEmpty(Queue.fromList([1, 2])) == false
*
* @since v0.6.0
*/
provide let isEmpty = queue => queue.size == 0
Expand All @@ -55,6 +68,9 @@ provide let isEmpty = queue => queue.size == 0
* @param queue: The queue to inspect
* @returns The count of the items in the queue
*
* @example Queue.size(Queue.make()) == 0
* @example Queue.size(Queue.fromList([1, 2])) == 2
*
* @since v0.6.0
*/
provide let size = queue => queue.size
Expand All @@ -65,6 +81,12 @@ provide let size = queue => queue.size
* @param queue: The queue to inspect
* @returns `Some(value)` containing the value at the beginning of the queue or `None` otherwise.
*
* @example Queue.peek(Queue.make()) == None
* @example
* let queue = Queue.make()
* Queue.push(1, queue)
* assert Queue.peek(queue) == Some(1)
*
* @since v0.6.0
*/
provide let peek = queue => {
Expand All @@ -77,6 +99,12 @@ provide let peek = queue => {
* @param value: The item to be added
* @param queue: The queue being updated
*
* @example
* let queue = Queue.make()
* assert Queue.peek(queue) == None
* Queue.push(1, queue)
* assert Queue.peek(queue) == Some(1)
*
* @since v0.6.0
*/
provide let push = (value, queue) => {
Expand Down Expand Up @@ -111,6 +139,12 @@ provide let push = (value, queue) => {
* @param queue: The queue being updated
* @returns The element removed from the queue
*
* @example
* let queue = Queue.make()
* Queue.push(1, queue)
* assert Queue.pop(queue) == Some(1)
* assert Queue.pop(queue) == None
*
* @since v0.6.0
*/
provide let pop = queue => {
Expand All @@ -125,12 +159,60 @@ provide let pop = queue => {
}
}

/**
* Clears the queue by removing all of its elements.
*
* @param queue: The queue to clear
*
* @example
* let queue = Queue.make()
* Queue.push(1, queue)
* assert Queue.size(queue) == 1
* Queue.clear(queue)
* assert Queue.size(queue) == 0
*
* @since v0.6.0
*/
provide let clear = queue => {
queue.size = 0
Array.fill(None, queue.array)
queue.headIndex = 0
queue.tailIndex = 0
}

/**
* Produces a shallow copy of the input queue.
*
* @param queue: The queue to copy
* @returns A new queue containing the elements from the input
*
* @example
* 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)
*
* @since v0.6.0
*/
provide let copy = queue => {
let { size, array, headIndex, tailIndex } = queue
{ size, array: Array.copy(array), headIndex, tailIndex }
}

/**
* Converts a queue into a list of its elements.
*
* @param queue: The queue to convert
* @returns A list containing all queue values
*
* @example
* let queue = Queue.make()
* Queue.push(0, queue)
* Queue.push(1, queue)
* Queue.push(2, queue)
* assert Queue.toList(queue) == [0, 1, 2]
*
* @since v0.6.0
*/
provide let toList = queue => {
Expand All @@ -152,6 +234,11 @@ provide let toList = queue => {
* @param list: The list to convert
* @returns A queue containing all list values
*
* @example
* let queue = Queue.fromList([0, 1])
* assert Queue.pop(queue) == Some(0)
* assert Queue.pop(queue) == Some(1)
*
* @since v0.6.0
*/
provide let fromList = list => {
Expand All @@ -160,39 +247,19 @@ provide let fromList = list => {
queue
}

/**
* Clears the queue by removing all of its elements
*
* @param queue: The queue to clear
*
* @since v0.6.0
*/
provide let clear = queue => {
queue.size = 0
Array.fill(None, queue.array)
queue.headIndex = 0
queue.tailIndex = 0
}

/**
* Produces a shallow copy of the input queue.
*
* @param queue: The queue to copy
* @returns A new queue containing the elements from the input
*
* @since v0.6.0
*/
provide let copy = queue => {
let { size, array, headIndex, tailIndex } = queue
{ size, array: Array.copy(array), headIndex, tailIndex }
}

/**
* Converts a queue into an array of its values.
*
* @param queue: The queue to convert
* @returns An array containing all values from the given queue
*
* @example
* let queue = Queue.make()
* Queue.push(0, queue)
* Queue.push(1, queue)
* Queue.push(2, queue)
* assert Queue.toArray(queue) == [> 0, 1, 2]
*
* @since v0.6.0
*/
provide let toArray = queue => {
Expand Down Expand Up @@ -230,6 +297,11 @@ provide let toArray = queue => {
* @param arr: The array to convert
* @returns A queue containing all values from the array
*
* @example
* let queue = Queue.fromArray([> 0, 1])
* assert Queue.pop(queue) == Some(0)
* assert Queue.pop(queue) == Some(1)
*
* @since v0.6.0
*/
provide let fromArray = arr => {
Expand All @@ -255,6 +327,18 @@ provide let fromArray = arr => {
* @param queue2: The second queue to compare
* @returns `true` if the queues are equivalent or `false` otherwise
*
* @example
* use Queue.{ (==) }
* let queue1 = Queue.fromList([0, 1, 2])
* let queue2 = Queue.fromList([0, 1, 2])
* assert queue1 == queue2
*
* @example
* use Queue.{ (==) }
* let queue1 = Queue.fromList([0, 1, 2])
* let queue2 = Queue.fromList([0, 1, 3])
* assert !(queue1 == queue2)
*
* @since v0.6.0
*/
provide let (==) = (queue1, queue2) => {
Expand All @@ -276,10 +360,24 @@ provide let (==) = (queue1, queue2) => {

/**
* An immutable queue implementation.
*
* @example
* 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)
*
* @since v0.6.0
*/
provide module Immutable {
/**
* An immutable FIFO (first-in-first-out) data structure.
*
* @since v0.6.0
* @history v0.5.4: Originally a module root API
*/
abstract record ImmutableQueue<a> {
forwards: List<a>,
Expand All @@ -289,6 +387,10 @@ provide module Immutable {
/**
* An empty queue.
*
* @example
* let queue = Queue.Immutable.empty
* assert Queue.Immutable.isEmpty(queue)
*
* @since v0.6.0
* @history v0.5.4: Originally a module root API
*/
Expand All @@ -303,6 +405,10 @@ provide module Immutable {
* @param queue: The queue to check
* @returns `true` if the given queue is empty or `false` otherwise
*
* @example Queue.Immutable.isEmpty(Queue.Immutable.empty) == true
*
* @example Queue.Immutable.isEmpty(Queue.Immutable.fromList([1, 2])) == false
*
* @since v0.6.0
* @history v0.2.0: Originally a module root API
*/
Expand All @@ -319,6 +425,14 @@ provide module Immutable {
* @param queue: The queue to inspect
* @returns `Some(value)` containing the value at the beginning of the queue, or `None` if the queue is empty
*
* @example
* let queue = Queue.Immutable.fromList([1, 2, 3])
* assert Queue.Immutable.peek(queue) == Some(1)
*
* @example
* let queue = Queue.Immutable.empty
* assert Queue.Immutable.peek(queue) == None
*
* @since v0.6.0
* @history v0.2.0: Originally named `head`
* @history v0.3.2: Deprecated `head` function
Expand All @@ -339,6 +453,12 @@ provide module Immutable {
* @param queue: The queue to update
* @returns An updated queue
*
* @example
* 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
*
* @since v0.6.0
* @history v0.2.0: Originally named `enqueue`
* @history v0.3.2: Deprecated `enqueue` function
Expand All @@ -358,6 +478,16 @@ provide module Immutable {
* @param queue: The queue to change
* @returns An updated queue
*
* @example
* let queue = Queue.Immutable.fromList([1, 2, 3])
* let queue = Queue.Immutable.pop(queue)
* assert Queue.Immutable.peek(queue) == Some(2)
*
* @example
* let queue = Queue.Immutable.empty
* let queue = Queue.Immutable.pop(queue)
* assert Queue.Immutable.isEmpty(queue)
*
* @since v0.6.0
* @history v0.2.0: Originally named `dequeue`
* @history v0.3.2: Deprecated `dequeue` function
Expand All @@ -381,6 +511,9 @@ provide module Immutable {
* @param queue: The queue to inspect
* @returns The number of values in the queue
*
* @example Queue.Immutable.size(Queue.Immutable.empty) == 0
* @example Queue.Immutable.size(Queue.Immutable.fromList([1, 2])) == 2
*
* @since v0.6.0
* @history v0.3.2: Originally a module root API
*/
Expand All @@ -399,6 +532,20 @@ provide module Immutable {
* @param queue: The queue to convert
* @returns A list containing all queue values
*
* @example
* 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]
*
* @example
* let queue = Queue.Immutable.fromList([1, 2, 3])
* assert Queue.Immutable.toList(queue) == [1, 2, 3]
*
* @example
* let queue = Queue.Immutable.empty
* assert Queue.Immutable.toList(queue) == []
*
* @since v0.6.0
*/
provide let toList = queue => {
Expand All @@ -411,6 +558,11 @@ provide module Immutable {
* @param list: The list to convert
* @returns A queue containing all list values
*
* @example
* let queue = Queue.Immutable.fromList([1, 2, 3])
* assert Queue.Immutable.peek(queue) == Some(1)
* assert Queue.Immutable.size(queue) == 3
*
* @since v0.6.0
*/
provide let fromList = list => {
Expand Down
Loading

0 comments on commit 1179c91

Please sign in to comment.