@grain/stdlib 0.4.0 → 0.4.4

package/queue.gr

@@ -1,46 +1,115 @@
+/**
+ * @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"
+ * @since v0.2.0
+ */
 import List from "list"
 
 record Queue<a> { forwards: List<a>, backwards: List<a> }
 
+/**
+ * @section Values: Functions for working with queues.
+ */
+
+/**
+ * Creates an empty queue.
+ * 
+ * @returns An empty queue
+ * @since v0.2.0
+ */
 export let make = () => {
-    { forwards: [], backwards: [] }
+  { forwards: [], backwards: [] }
 }
 
-export let isEmpty = (queue) => {
-    match (queue) {
-        { forwards: [], backwards: [] } => true,
-        _ => false
-    }
+/**
+ * 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.2.0
+ */
+export let isEmpty = queue => {
+  match (queue) {
+    { forwards: [], backwards: [] } => true,
+    _ => false,
+  }
 }
 
-export let peek = (queue) => {
-    match (queue) {
-        { forwards: [], backwards: [] } => None,
-        { forwards, backwards } => List.head(forwards)
-    }
+/**
+ * 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.3.2
+ * @history v0.2.0: Originally named `head`
+ * @history v0.3.2: Deprecated `head` function
+ * @history v0.4.0: Removed `head` function
+ */
+export 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.3.2
+ * @history v0.2.0: Originally named `enqueue`
+ * @history v0.3.2: Deprecated `enqueue` function
+ * @history v0.4.0: Removed `enqueue` function
+ */
 export let push = (value, queue) => {
-    match (queue) {
-        { forwards: [], backwards: [] } => { forwards: [value], backwards: [] },
-        { forwards, backwards } => { forwards, backwards: [value, ...backwards] }
-    }
+  match (queue) {
+    { forwards: [], backwards: [] } => { forwards: [value], backwards: [] },
+    { forwards, backwards } => { forwards, backwards: [value, ...backwards] },
+  }
 }
 
-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 }
-    }
+/**
+ * Dequeues the next value in the queue.
+ * 
+ * @param queue: The queue to change
+ * @returns An updated queue
+ *
+ * @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
+ */
+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 },
+  }
 }
 
-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),
-    }
+/**
+ * Get the number of values in a queue.
+ * 
+ * @param queue: The queue to inspect
+ * @returns The number of values in the queue
+ *
+ * @since v0.3.2
+ */
+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),
+  }
 }

package/queue.md

@@ -0,0 +1,191 @@
+---
+title: 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.
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+import Queue from "queue"
+```
+
+## Values
+
+Functions for working with queues.
+
+### Queue.**make**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+make : () -> Queue<a>
+```
+
+Creates an empty queue.
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Queue<a>`|An empty queue|
+
+### Queue.**isEmpty**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+isEmpty : Queue<a> -> Bool
+```
+
+Checks if the given queue contains any values.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`queue`|`Queue<a>`|The queue to check|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the given queue is empty or `false` otherwise|
+
+### Queue.**peek**
+
+<details>
+<summary>Added in <code>0.3.2</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.2.0</code></td><td>Originally named `head`</td></tr>
+<tr><td><code>0.3.2</code></td><td>Deprecated `head` function</td></tr>
+<tr><td><code>0.4.0</code></td><td>Removed `head` function</td></tr>
+</tbody>
+</table>
+</details>
+
+```grain
+peek : Queue<a> -> Option<a>
+```
+
+Returns the value at the beginning of the queue. It is not removed from the queue.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`queue`|`Queue<a>`|The queue to inspect|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Option<a>`|`Some(value)` containing the value at the beginning of the queue, or `None` if the queue is empty|
+
+### Queue.**push**
+
+<details>
+<summary>Added in <code>0.3.2</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.2.0</code></td><td>Originally named `enqueue`</td></tr>
+<tr><td><code>0.3.2</code></td><td>Deprecated `enqueue` function</td></tr>
+<tr><td><code>0.4.0</code></td><td>Removed `enqueue` function</td></tr>
+</tbody>
+</table>
+</details>
+
+```grain
+push : (a, Queue<a>) -> Queue<a>
+```
+
+Adds a value to the end of the queue.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`value`|`a`|The value to append|
+|`queue`|`Queue<a>`|The queue to update|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Queue<a>`|An updated queue|
+
+### Queue.**pop**
+
+<details>
+<summary>Added in <code>0.3.2</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.2.0</code></td><td>Originally named `dequeue`</td></tr>
+<tr><td><code>0.3.2</code></td><td>Deprecated `dequeue` function</td></tr>
+<tr><td><code>0.4.0</code></td><td>Removed `dequeue` function</td></tr>
+</tbody>
+</table>
+</details>
+
+```grain
+pop : Queue<a> -> Queue<a>
+```
+
+Dequeues the next value in the queue.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`queue`|`Queue<a>`|The queue to change|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Queue<a>`|An updated queue|
+
+### Queue.**size**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.2</code></summary>
+No other changes yet.
+</details>
+
+```grain
+size : Queue<a> -> Number
+```
+
+Get the number of values in a queue.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`queue`|`Queue<a>`|The queue to inspect|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Number`|The number of values in the queue|
+

package/range.md

@@ -102,7 +102,7 @@ No other changes yet.
 </details>
 
 ```grain
-map : ((Number -> a), Range) -> List<b>
+map : ((Number -> a), Range) -> List<a>
 ```
 
 Produces a list by calling the given function on each number included in the range. For increasing ranges, the value is increased by `1` in each iteration, and for decreasing ranges, the value is decreased by `1`. The value is always changed by `1`, even if non-integer values were provided in the range.