@grain/stdlib 0.4.2 → 0.4.6

package/queue.gr

@@ -1,46 +1,118 @@
+/**
+ * @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> }
+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.gr

@@ -38,7 +38,7 @@ export let inRange = (value, range) => {
     Inclusive(upper, lower) when value >= lower && value <= upper => true,
     Exclusive(lower, upper) when value >= lower && value < upper => true,
     Exclusive(upper, lower) when value >= lower && value < upper => true,
-    _ => false
+    _ => false,
   }
 }
 
@@ -52,34 +52,34 @@ export let inRange = (value, range) => {
  *
  * @since v0.3.0
  */
-export let forEach = (fn: (Number) -> Void, range) => {
+export let forEach = (fn: Number -> Void, range) => {
   match (range) {
     Inclusive(lower, upper) when lower <= upper => {
-      let mut idx = lower;
+      let mut idx = lower
       while (idx <= upper) {
-        fn(idx);
-        idx += 1;
+        fn(idx)
+        idx += 1
       }
     },
     Inclusive(upper, lower) => {
-      let mut idx = upper;
+      let mut idx = upper
       while (idx >= lower) {
-        fn(idx);
-        idx -= 1;
+        fn(idx)
+        idx -= 1
       }
     },
     Exclusive(lower, upper) when lower <= upper => {
-      let mut idx = lower;
+      let mut idx = lower
       while (idx < upper) {
-        fn(idx);
-        idx += 1;
+        fn(idx)
+        idx += 1
       }
     },
     Exclusive(upper, lower) => {
-      let mut idx = upper;
+      let mut idx = upper
       while (idx > lower) {
-        fn(idx);
-        idx -= 1;
+        fn(idx)
+        idx -= 1
       }
     },
   }
@@ -100,31 +100,31 @@ export let map = (fn, range) => {
   let mut result = []
   match (range) {
     Inclusive(lower, upper) when lower <= upper => {
-      let mut idx = upper;
+      let mut idx = upper
       while (idx >= lower) {
-        result = [fn(idx), ...result];
-        idx -= 1;
+        result = [fn(idx), ...result]
+        idx -= 1
       }
     },
     Inclusive(upper, lower) => {
-      let mut idx = lower;
+      let mut idx = lower
       while (idx <= upper) {
-        result = [fn(idx), ...result];
-        idx += 1;
+        result = [fn(idx), ...result]
+        idx += 1
       }
     },
     Exclusive(lower, upper) when lower <= upper => {
-      let mut idx = upper - 1;
+      let mut idx = upper - 1
       while (idx >= lower) {
-        result = [fn(idx), ...result];
-        idx -= 1;
+        result = [fn(idx), ...result]
+        idx -= 1
       }
     },
     Exclusive(upper, lower) => {
-      let mut idx = lower + 1;
+      let mut idx = lower + 1
       while (idx <= upper) {
-        result = [fn(idx), ...result];
-        idx += 1;
+        result = [fn(idx), ...result]
+        idx += 1
       }
     },
   }

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.

package/regex.md

@@ -5,7 +5,7 @@ title: Regex
 Regular Expressions.
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.4.3</code></summary>
 No other changes yet.
 </details>
 
@@ -20,7 +20,7 @@ Functions for working with regular expressions.
 ### Regex.**make**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.4.3</code></summary>
 No other changes yet.
 </details>
 
@@ -180,7 +180,7 @@ Returns the positions of all groups matched in this match object.
 ### Regex.**isMatch**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.4.3</code></summary>
 No other changes yet.
 </details>
 
@@ -212,7 +212,7 @@ assert Regex.isMatch(Result.unwrap(Regex.make("ca+[at]")), "caaat") == true
 ### Regex.**isMatchRange**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.4.3</code></summary>
 No other changes yet.
 </details>
 
@@ -250,7 +250,7 @@ assert Regex.isMatchRange(Result.unwrap(Regex.make("ca+[at]")), "caaat", 1, 5) =
 ### Regex.**find**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.4.3</code></summary>
 No other changes yet.
 </details>
 
@@ -282,7 +282,7 @@ Regex.find(Result.unwrap(Regex.make("ca+[at]")), "caaat")
 ### Regex.**findRange**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.4.3</code></summary>
 No other changes yet.
 </details>
 
@@ -339,7 +339,7 @@ Returns:
 ### Regex.**findAllRange**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.4.3</code></summary>
 No other changes yet.
 </details>
 
@@ -375,7 +375,7 @@ Regex.findAllRange(Result.unwrap(Regex.make("ca+[at]")), "caaat", 0, 5)
 ### Regex.**replace**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.4.3</code></summary>
 No other changes yet.
 </details>
 
@@ -416,7 +416,7 @@ assert Regex.replace(Result.unwrap(Regex.make("o")), "foo", "a") == "fao"
 ### Regex.**replaceAll**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.4.3</code></summary>
 No other changes yet.
 </details>