@grain/stdlib 0.5.13 → 0.6.1

package/queue.gr

@@ -1,137 +1,419 @@
 /**
- * @module Queue: An immutable queue implementation. 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.
- * @example import Queue from "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.
+ *
+ * @example from "queue" include Queue
+ *
  * @since v0.2.0
+ */
+module Queue
+
+from "list" include List
+from "array" include Array
+
+/**
+ * A mutable FIFO (first-in-first-out) data structure.
+ */
+abstract record Queue<a> {
+  mut size: Number,
+  mut array: Array<Option<a>>,
+  mut headIndex: Number,
+  mut tailIndex: Number, // tail points to where the next element should be inserted
+}
+
+/**
+ * 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
+ * default size.
+ *
+ * @param size: The initial storage size of the queue
+ * @returns An empty queue
+ *
+ * @since v0.6.0
+ */
+provide let make = (size=16) => {
+  { size: 0, array: Array.make(size, None), headIndex: 0, tailIndex: 0 }
+}
+
+/**
+ * Checks if the given queue contains no items.
  *
- * @deprecated This module will be renamed to ImmutableQueue in the v0.6.0 release of Grain.
+ * @param queue: The queue to check
+ * @returns `true` if the queue has no items or `false` otherwise
+ *
+ * @since v0.6.0
  */
-import List from "list"
+provide let isEmpty = queue => queue.size == 0
 
 /**
- * @section Types: Type declarations included in the Queue module.
+ * Computes the size of the input queue.
+ *
+ * @param queue: The queue to inspect
+ * @returns The count of the items in the queue
+ *
+ * @since v0.6.0
  */
+provide let size = queue => queue.size
 
-record Queue<a> {
-  forwards: List<a>,
-  backwards: List<a>,
+/**
+ * Provides the value at the beginning of the queue, if it exists.
+ *
+ * @param queue: The queue to inspect
+ * @returns `Some(value)` containing the value at the beginning of the queue or `None` otherwise.
+ *
+ * @since v0.6.0
+ */
+provide let peek = queue => {
+  if (queue.size == 0) None else queue.array[queue.headIndex]
 }
 
 /**
- * @section Values: Functions and constants for working with queues.
+ * Adds a new item to the end of the queue.
+ *
+ * @param value: The item to be added
+ * @param queue: The queue being updated
+ *
+ * @since v0.6.0
  */
+provide let push = (value, queue) => {
+  let arrLen = Array.length(queue.array)
+  // expand the array if needed
+  if (arrLen == 0) {
+    queue.array = Array.make(1, None)
+  } else if (queue.size == arrLen) {
+    let newArray = Array.make(arrLen * 2, None)
+
+    newArray[0] = queue.array[queue.headIndex]
+    let mut insertI = 1
+    let mut currI = (queue.headIndex + 1) % arrLen
+    while (currI != queue.tailIndex) {
+      newArray[insertI] = queue.array[currI]
+      insertI += 1
+      currI = (currI + 1) % arrLen
+    }
+
+    queue.headIndex = 0
+    queue.tailIndex = arrLen
+    queue.array = newArray
+  }
+  queue.array[queue.tailIndex] = Some(value)
+  queue.tailIndex = (queue.tailIndex + 1) % Array.length(queue.array)
+  queue.size += 1
+}
 
 /**
- * An empty queue.
+ * Removes the item at the beginning of the queue.
  *
- * @since v0.5.4
+ * @param queue: The queue being updated
+ * @returns The element removed from the queue
+ *
+ * @since v0.6.0
  */
-export let empty = {
-  let empty = { forwards: [], backwards: [] }
-  empty
+provide let pop = queue => {
+  if (queue.size == 0) {
+    None
+  } else {
+    let elem = queue.array[queue.headIndex]
+    queue.array[queue.headIndex] = None
+    queue.headIndex = (queue.headIndex + 1) % Array.length(queue.array)
+    queue.size -= 1
+    elem
+  }
 }
 
 /**
- * Creates an empty queue.
+ * Converts a queue into a list of its elements.
  *
- * @returns An empty queue
+ * @param queue: The queue to convert
+ * @returns A list containing all queue values
  *
- * @deprecated This will be removed in the v0.6.0 release of Grain.
+ * @since v0.6.0
+ */
+provide let toList = queue => {
+  let lst = List.init(
+    queue.size,
+    i =>
+      match (queue.array[(queue.headIndex + i) % Array.length(queue.array)]) {
+        Some(n) => n,
+        None =>
+          fail "Impossible: Attempted to access non-existent bucket in Queue.toList",
+      }
+  )
+  lst
+}
+
+/**
+ * Creates a queue from a list.
  *
- * @since v0.2.0
+ * @param list: The list to convert
+ * @returns A queue containing all list values
+ *
+ * @since v0.6.0
  */
-export let make = () => {
-  { forwards: [], backwards: [] }
+provide let fromList = list => {
+  let queue = make(size=List.length(list))
+  List.forEach(e => push(e, queue), list)
+  queue
 }
 
 /**
- * Checks if the given queue contains any values.
+ * Clears the queue by removing all of its elements
  *
- * @param queue: The queue to check
- * @returns `true` if the given queue is empty or `false` otherwise
+ * @param queue: The queue to clear
  *
- * @since v0.2.0
+ * @since v0.6.0
  */
-export let isEmpty = queue => {
-  match (queue) {
-    { forwards: [], backwards: [] } => true,
-    _ => false,
-  }
+provide let clear = queue => {
+  queue.size = 0
+  Array.fill(None, queue.array)
+  queue.headIndex = 0
+  queue.tailIndex = 0
 }
 
 /**
- * Returns the value at the beginning of the queue. It is not removed from the queue.
+ * Produces a shallow copy of the input queue.
  *
- * @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
+ * @param queue: The queue to copy
+ * @returns A new queue containing the elements from the input
  *
- * @since v0.3.2
- * @history v0.2.0: Originally named `head`
- * @history v0.3.2: Deprecated `head` function
- * @history v0.4.0: Removed `head` function
+ * @since v0.6.0
  */
-export let peek = queue => {
-  match (queue) {
-    { forwards: [], backwards: [] } => None,
-    { forwards, backwards } => List.head(forwards),
-  }
+provide let copy = queue => {
+  let { size, array, headIndex, tailIndex } = queue
+  { size, array: Array.copy(array), headIndex, tailIndex }
 }
 
 /**
- * Adds a value to the end of the queue.
+ * Converts a queue into an array of its values.
  *
- * @param value: The value to append
- * @param queue: The queue to update
- * @returns An updated queue
+ * @param queue: The queue to convert
+ * @returns An array containing all values from the given queue
  *
- * @since v0.3.2
- * @history v0.2.0: Originally named `enqueue`
- * @history v0.3.2: Deprecated `enqueue` function
- * @history v0.4.0: Removed `enqueue` function
+ * @since v0.6.0
  */
-export let push = (value, queue) => {
-  match (queue) {
-    { forwards: [], backwards: [] } => { forwards: [value], backwards: [] },
-    { forwards, backwards } => { forwards, backwards: [value, ...backwards] },
+provide let toArray = queue => {
+  let arr = Array.make(queue.size, None)
+  let mut outIndex = 0
+  if (queue.tailIndex < queue.headIndex) {
+    // Get the first half
+    for (let mut i = queue.headIndex; i < Array.length(queue.array); i += 1) {
+      arr[outIndex] = queue.array[i]
+      outIndex += 1
+    }
+    // Get the second half
+    let endOffset = Array.length(queue.array) - queue.headIndex
+    for (let mut i = 0; i < queue.tailIndex; i += 1) {
+      arr[outIndex] = queue.array[i]
+      outIndex += 1
+    }
+  } else {
+    for (let mut i = queue.headIndex; i < queue.tailIndex; i += 1) {
+      arr[outIndex] = queue.array[i]
+      outIndex += 1
+    }
   }
+  Array.map(e => {
+    match (e) {
+      Some(v) => v,
+      None => fail "Impossible: empty bucket in Queue.toArray",
+    }
+  }, arr)
 }
 
 /**
- * Dequeues the next value in the queue.
+ * Creates a queue from an array.
  *
- * @param queue: The queue to change
- * @returns An updated queue
+ * @param arr: The array to convert
+ * @returns A queue containing all values from the array
  *
- * @since v0.3.2
- * @history v0.2.0: Originally named `dequeue`
- * @history v0.3.2: Deprecated `dequeue` function
- * @history v0.4.0: Removed `dequeue` function
+ * @since v0.6.0
  */
-export let pop = queue => {
-  match (queue) {
-    { forwards: [], backwards: [] } => queue,
-    { forwards: [head], backwards: [] } => { forwards: [], backwards: [] },
-    { forwards: [head], backwards } =>
-      {
-        forwards: List.reverse(backwards),
-        backwards: [],
-      },
-    { forwards: [head, ...ftail], backwards } => { forwards: ftail, backwards },
+provide let fromArray = arr => {
+  let size = Array.length(arr)
+  let contents = if (size == 0) {
+    Array.make(16, None)
+  } else {
+    Array.init(size * 2, i => {
+      if (i < size) {
+        Some(arr[i])
+      } else {
+        None
+      }
+    })
   }
+  { size, array: contents, headIndex: 0, tailIndex: size }
 }
 
 /**
- * Get the number of values in a queue.
+ * Checks if two queues are equivalent by value.
  *
- * @param queue: The queue to inspect
- * @returns The number of values in the queue
+ * @param queue1: The first queue to compare
+ * @param queue2: The second queue to compare
+ * @returns `true` if the queues are equivalent or `false` otherwise
  *
- * @since v0.3.2
+ * @since v0.6.0
  */
-export let size = queue => {
-  match (queue) {
-    { forwards: [], backwards: [] } => 0,
-    { forwards, backwards: [] } => List.length(forwards),
-    { forwards: [], backwards } => List.length(backwards),
-    { forwards, backwards } => List.length(forwards) + List.length(backwards),
+provide let (==) = (queue1, queue2) => {
+  if (queue1.size != queue2.size) return false
+  let len1 = Array.length(queue1.array)
+  let len2 = Array.length(queue2.array)
+  for (let mut i = 0; i < queue1.size; i += 1) {
+    // Get the index of element from queue1
+    let mut index1 = queue1.headIndex + i
+    if (index1 >= len1) index1 -= len1
+    // Get the index of element from queue2
+    let mut index2 = queue2.headIndex + i
+    if (index2 >= len2) index2 -= len2
+
+    if (queue1.array[index1] != queue2.array[index2]) return false
+  }
+  return true
+}
+
+/**
+ * An immutable queue implementation.
+ */
+provide module Immutable {
+  /**
+   * An immutable FIFO (first-in-first-out) data structure.
+   */
+  abstract record ImmutableQueue<a> {
+    forwards: List<a>,
+    backwards: List<a>,
+  }
+
+  /**
+   * An empty queue.
+   *
+   * @since v0.6.0
+   * @history v0.5.4: Originally a module root API
+   */
+  provide let empty = {
+    let empty = { forwards: [], backwards: [] }
+    empty
+  }
+
+  /**
+   * Checks if the given queue contains any values.
+   *
+   * @param queue: The queue to check
+   * @returns `true` if the given queue is empty or `false` otherwise
+   *
+   * @since v0.6.0
+   * @history v0.2.0: Originally a module root API
+   */
+  provide let isEmpty = queue => {
+    match (queue) {
+      { forwards: [], backwards: [] } => true,
+      _ => false,
+    }
+  }
+
+  /**
+   * Returns the value at the beginning of the queue. It is not removed from the queue.
+   *
+   * @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
+   *
+   * @since v0.6.0
+   * @history v0.2.0: Originally named `head`
+   * @history v0.3.2: Deprecated `head` function
+   * @history v0.3.2: Originally a module root API
+   * @history v0.4.0: Removed `head` function
+   */
+  provide let peek = queue => {
+    match (queue) {
+      { forwards: [], backwards: [] } => None,
+      { forwards, backwards } => List.head(forwards),
+    }
+  }
+
+  /**
+   * Adds a value to the end of the queue.
+   *
+   * @param value: The value to append
+   * @param queue: The queue to update
+   * @returns An updated queue
+   *
+   * @since v0.6.0
+   * @history v0.2.0: Originally named `enqueue`
+   * @history v0.3.2: Deprecated `enqueue` function
+   * @history v0.3.2: Originally a module root API
+   * @history v0.4.0: Removed `enqueue` function
+   */
+  provide let push = (value, queue) => {
+    match (queue) {
+      { forwards: [], backwards: [] } => { forwards: [value], backwards: [] },
+      { forwards, backwards } => { forwards, backwards: [value, ...backwards] },
+    }
+  }
+
+  /**
+   * Dequeues the next value in the queue.
+   *
+   * @param queue: The queue to change
+   * @returns An updated queue
+   *
+   * @since v0.6.0
+   * @history v0.2.0: Originally named `dequeue`
+   * @history v0.3.2: Deprecated `dequeue` function
+   * @history v0.3.2: Originally a module root API
+   * @history v0.4.0: Removed `dequeue` function
+   */
+  provide let pop = queue => {
+    match (queue) {
+      { forwards: [], backwards: [] } => queue,
+      { forwards: [head], backwards: [] } => { forwards: [], backwards: [] },
+      { forwards: [head], backwards } =>
+        { forwards: List.reverse(backwards), backwards: [] },
+      { forwards: [head, ...ftail], backwards } =>
+        { forwards: ftail, backwards },
+    }
+  }
+
+  /**
+   * Get the number of values in a queue.
+   *
+   * @param queue: The queue to inspect
+   * @returns The number of values in the queue
+   *
+   * @since v0.6.0
+   * @history v0.3.2: Originally a module root API
+   */
+  provide let size = queue => {
+    match (queue) {
+      { forwards: [], backwards: [] } => 0,
+      { forwards, backwards: [] } => List.length(forwards),
+      { forwards: [], backwards } => List.length(backwards),
+      { forwards, backwards } => List.length(forwards) + List.length(backwards),
+    }
+  }
+
+  /**
+   * Converts a queue into a list of its elements.
+   *
+   * @param queue: The queue to convert
+   * @returns A list containing all queue values
+   *
+   * @since v0.6.0
+   */
+  provide let toList = queue => {
+    List.append(queue.forwards, List.reverse(queue.backwards))
+  }
+
+  /**
+   * Creates a queue from a list.
+   *
+   * @param list: The list to convert
+   * @returns A queue containing all list values
+   *
+   * @since v0.6.0
+   */
+  provide let fromList = list => {
+    { forwards: list, backwards: [] }
   }
 }