@grain/stdlib 0.4.1 → 0.4.5

package/pervasives.gr

@@ -24,7 +24,7 @@ import {
   (^),
   (<<),
   (>>>),
-  (>>)
+  (>>),
 } from "runtime/numbers"
 
 // Math operations
@@ -53,7 +53,6 @@ export (<<)
 export (>>>)
 export (>>)
 
-
 // Number coercions & conversions
 
 // [TODO] (#311) Commented until we nail down semantics
@@ -61,23 +60,23 @@ export (>>)
 // import foreign wasm convertInexactToExact : Number -> Number as exact from "stdlib-external/runtime"
 
 // Boolean operations
-primitive (!) : Bool -> Bool = "@not"
-primitive (&&) : (Bool, Bool) -> Bool = "@and"
-primitive (||) : (Bool, Bool) -> Bool = "@or"
+primitive (!): Bool -> Bool = "@not"
+primitive (&&): (Bool, Bool) -> Bool = "@and"
+primitive (||): (Bool, Bool) -> Bool = "@or"
 
 // Box operations
-primitive box : a -> Box<a> = "@box"
-primitive unbox : Box<a> -> a = "@unbox"
+primitive box: a -> Box<a> = "@box"
+primitive unbox: Box<a> -> a = "@unbox"
 
 // Exceptions
 exception Failure(String)
 exception InvalidArgument(String)
 
 // Other operations
-primitive ignore : a -> Void = "@ignore"
-primitive assert : Bool -> Void = "@assert"
-primitive throw : Exception -> a = "@throw"
-let fail : String -> a = msg => throw Failure(msg)
+primitive ignore: a -> Void = "@ignore"
+primitive assert: Bool -> Void = "@assert"
+primitive throw: Exception -> a = "@throw"
+let fail: String -> a = msg => throw Failure(msg)
 
 import { toString, print, concat as (++) } from "runtime/string"
 
@@ -91,28 +90,41 @@ export (++)
 
 // Checks the given items for structural equality.
 export (==)
-let (!=) : (a, a) -> Bool = (x, y) => !(x == y)
+let (!=): (a, a) -> Bool = (x, y) => !(x == y)
 // Checks the given items for physical equality.
-primitive (is) : (a, a) -> Bool = "@is"
+primitive (is): (a, a) -> Bool = "@is"
 // The opposite of is operator
-let (isnt) : (a, a) -> Bool = (x, y) => !(x is y)
+let (isnt): (a, a) -> Bool = (x, y) => !(x is y)
 
-export enum List<a> { [], [...](a, List<a>) }
+export enum List<a> {
+  [],
+  [...](a, List<a>),
+}
 
 /**
  * @deprecated This will be removed in a future release of Grain.
  */
-let cons = (a, b) => [a, ...b] // <- workaround for (grain-lang/grain#802) [TODO] fix #802 and delete
+let cons = (a, b) =>
+  [
+    a,
+    ...b
+  ] // <- workaround for (grain-lang/grain#802) [TODO] fix #802 and delete
 let empty = [] // <- for parity with `cons`, but should be deleted as well
 
 // Maybe some data, maybe not!
-enum Option<a> { Some(a), None }
+enum Option<a> {
+  Some(a),
+  None,
+}
 
 // Maybe some data, maybe an error!
-enum Result<t, e> { Ok(t), Err(e) }
+enum Result<t, e> {
+  Ok(t),
+  Err(e),
+}
 
 // Identity function
-let identity = (x) => x
+let identity = x => x
 
 // Setup exception printing
 @disableGC
@@ -121,7 +133,7 @@ let rec setupExceptions = () => {
     match (e) {
       Failure(msg) => Some("Failure: " ++ msg),
       InvalidArgument(msg) => Some("Invalid argument: " ++ msg),
-      _ => None
+      _ => None,
     }
   })
 

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.