Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(stdlib): Add examples to Queue module #2200

Merged
merged 4 commits into from
Jan 2, 2025
Merged

chore(stdlib): Add examples to Queue module #2200

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2e73539
chore(stdlib): Add examples to `Queue` module
spotandjake Nov 18, 2024
42b6a49
chore: Correct wording in `make`
spotandjake Nov 18, 2024
f489b03
Apply suggestions from oscar code review
spotandjake Dec 29, 2024
b9d2560
chore: Update grain doc
spotandjake Dec 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
208 changes: 180 additions & 28 deletions stdlib/queue.gr
View file
Open in desktop
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 @@ -27,12 +34,15 @@ abstract record 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 map and can use the
* won’t need to care about the storage size of your queue and can use the
* default size.
*
* @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
spotandjake marked this conversation as resolved.
Show resolved Hide resolved
*
* @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
Loading