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

Co-authored-by: Oscar Spencer <oscar.spen@gmail.com>

Author: spotandjake

stdlib/queue.gr

@@ -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
@@ -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) => {
@@ -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
@@ -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
@@ -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 => {
@@ -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) => {
@@ -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 => {
@@ -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 => {
@@ -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 => {
@@ -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 => {
@@ -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 => {
@@ -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) => {
@@ -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>,
@@ -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
    */
@@ -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
    */
@@ -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
@@ -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
@@ -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
@@ -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
    */
@@ -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 => {
@@ -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 => {