@grain/stdlib 0.4.6 → 0.5.0

package/map.md

@@ -0,0 +1,525 @@
+---
+title: Map
+---
+
+A Map holds key-value pairs. Any value may be used as a key or value. Operations on a Map mutate the internal state, so it never needs to be re-assigned.
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+import Map from "map"
+```
+
+## Types
+
+Type declarations included in the Map module.
+
+### Map.**Map**
+
+```grain
+type Map<k, v>
+```
+
+## Values
+
+Functions for working with Maps.
+
+### Map.**makeSized**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+makeSized : Number -> Map<a, b>
+```
+
+Creates a new empty map 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 `Map.make()` instead.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`size`|`Number`|The initial storage size of the map|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Map<a, b>`|An empty map with the given initial storage size|
+
+### Map.**make**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+make : () -> Map<a, b>
+```
+
+Creates a new, empty map.
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Map<a, b>`|An empty map|
+
+### Map.**set**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+set : (a, b, Map<a, b>) -> Void
+```
+
+Adds a new key-value pair to the map. If the key already exists in the map, the value is replaced.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`key`|`a`|The unique key in the map|
+|`value`|`b`|The value to store|
+|`map`|`Map<a, b>`|The map to modify|
+
+### Map.**get**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+get : (a, Map<a, b>) -> Option<b>
+```
+
+Retrieves the value for the given key.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`key`|`a`|The key to access|
+|`map`|`Map<a, b>`|The map to access|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Option<b>`|`Some(value)` if the key exists in the map or `None` otherwise|
+
+### Map.**contains**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+contains : (a, Map<a, b>) -> Bool
+```
+
+Determines if the map contains the given key. In such a case, it will always contain a value for the given key.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`key`|`a`|The key to search for|
+|`map`|`Map<a, b>`|The map to search|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the map contains the given key or `false` otherwise|
+
+### Map.**remove**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+remove : (a, Map<a, b>) -> Void
+```
+
+Removes the given key from the map, which also removes the value. If the key pair doesn't exist, nothing happens.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`key`|`a`|The key to remove|
+|`map`|`Map<a, b>`|The map to update|
+
+### Map.**update**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+update : (a, (Option<b> -> Option<b>), Map<a, b>) -> Void
+```
+
+Updates a value in the map by calling an updater function that receives the previously stored value as an `Option` and returns the new value to be stored as an `Option`. If the key didn't exist previously, the value will be `None`. If `None` is returned from the updater function, the key-value pair is removed.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`key`|`a`|The unique key in the map|
+|`fn`|`Option<b> -> Option<b>`|The updater function|
+|`map`|`Map<a, b>`|The map to modify|
+
+### Map.**size**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+size : Map<a, b> -> Number
+```
+
+Provides the count of key-value pairs stored within the map.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`map`|`Map<a, b>`|The map to inspect|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Number`|The count of key-value pairs in the map|
+
+### Map.**isEmpty**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+isEmpty : Map<a, b> -> Bool
+```
+
+Determines if the map contains no key-value pairs.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`map`|`Map<a, b>`|The map to inspect|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the given map is empty or `false` otherwise|
+
+### Map.**clear**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+clear : Map<a, b> -> Void
+```
+
+Resets the map by removing all key-value pairs.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`map`|`Map<a, b>`|The map to reset|
+
+### Map.**forEach**
+
+<details>
+<summary>Added in <code>0.2.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>next</code></td><td>Ensured the iterator function return type is always `Void`</td></tr>
+</tbody>
+</table>
+</details>
+
+```grain
+forEach : (((a, b) -> Void), Map<a, b>) -> Void
+```
+
+Iterates the map, calling an iterator function with each key and value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`(a, b) -> Void`|The iterator function to call with each key and value|
+|`map`|`Map<a, b>`|The map to iterate|
+
+### Map.**reduce**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+reduce : (((a, b, c) -> a), a, Map<b, c>) -> a
+```
+
+Combines all key-value pairs of a map using a reducer function.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`(a, b, c) -> a`|The reducer function to call on each key and value, where the value returned will be the next accumulator value|
+|`init`|`a`|The initial value to use for the accumulator on the first iteration|
+|`map`|`Map<b, c>`|The map to iterate|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`a`|The final accumulator returned from `fn`|
+
+### Map.**keys**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+keys : Map<a, b> -> List<a>
+```
+
+Enumerates all keys in the given map.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`map`|`Map<a, b>`|The map to enumerate|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`List<a>`|A list containing all keys from the given map|
+
+### Map.**values**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+values : Map<a, b> -> List<b>
+```
+
+Enumerates all values in the given map.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`map`|`Map<a, b>`|The map to enumerate|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`List<b>`|A list containing all values from the given map|
+
+### Map.**toList**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+toList : Map<a, b> -> List<(a, b)>
+```
+
+Enumerates all key-value pairs in the given map.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`map`|`Map<a, b>`|The map to enumerate|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`List<(a, b)>`|A list containing all key-value pairs from the given map|
+
+### Map.**fromList**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+fromList : List<(a, b)> -> Map<a, b>
+```
+
+Creates a map from a list.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`list`|`List<(a, b)>`|The list to convert|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Map<a, b>`|A map containing all key-value pairs from the list|
+
+### Map.**toArray**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+toArray : Map<a, b> -> Array<(a, b)>
+```
+
+Converts a map into an array of its key-value pairs.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`map`|`Map<a, b>`|The map to convert|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Array<(a, b)>`|An array containing all key-value pairs from the given map|
+
+### Map.**fromArray**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+fromArray : Array<(a, b)> -> Map<a, b>
+```
+
+Creates a map from an array.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`array`|`Array<(a, b)>`|The array to convert|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Map<a, b>`|A map containing all key-value pairs from the array|
+
+### Map.**filter**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+filter : (((a, b) -> Bool), Map<a, b>) -> Void
+```
+
+Removes key-value pairs from a map where a predicate function returns `false`.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`(a, b) -> Bool`|The predicate function to indicate which key-value pairs to remove from the map, where returning `false` indicates the key-value pair should be removed|
+|`map`|`Map<a, b>`|The map to iterate|
+
+### Map.**reject**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+reject : (((a, b) -> Bool), Map<a, b>) -> Void
+```
+
+Removes key-value pairs from a map where a predicate function returns `true`.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`(a, b) -> Bool`|The predicate function to indicate which key-value pairs to remove from the map, where returning `true` indicates the key-value pair should be removed|
+|`map`|`Map<a, b>`|The map to iterate|
+
+### Map.**getInternalStats**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+getInternalStats : Map<a, b> -> (Number, Number)
+```
+
+Provides data representing the internal state state of the map.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`map`|`Map<a, b>`|The map to inspect|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`(Number, Number)`|The internal state of the map|
+

package/number.gr

@@ -71,19 +71,16 @@ export let div = (/)
  *
  * @since v0.4.0
  */
-@disableGC
-export let rec sqrt = (x: Number) => {
+@unsafe
+export let sqrt = (x: Number) => {
   let xval = coerceNumberToWasmF64(x)
   let x = WasmI32.fromGrain(x)
   let sqrtd = WasmF64.sqrt(xval)
-  let ret = if (!isFloat(x) && WasmF64.eq(sqrtd, WasmF64.trunc(sqrtd))) {
+  if (!isFloat(x) && WasmF64.eq(sqrtd, WasmF64.trunc(sqrtd))) {
     WasmI32.toGrain(reducedInteger(WasmI64.truncF64S(sqrtd))): Number
   } else {
     WasmI32.toGrain(newFloat64(sqrtd)): Number
   }
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(sqrt))
-  ret
 }
 
 /**
@@ -134,14 +131,11 @@ export let max = (x: Number, y: Number) => if (x > y) x else y
  *
  * @since v0.4.0
  */
-@disableGC
-export let rec ceil = (x: Number) => {
+@unsafe
+export let ceil = (x: Number) => {
   let xval = coerceNumberToWasmF64(x)
   let ceiling = WasmI64.truncF64S(WasmF64.ceil(xval))
-  let ret = WasmI32.toGrain(reducedInteger(ceiling)): Number
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(ceil))
-  ret
+  WasmI32.toGrain(reducedInteger(ceiling)): Number
 }
 
 /**
@@ -152,14 +146,11 @@ export let rec ceil = (x: Number) => {
  *
  * @since v0.4.0
  */
-@disableGC
-export let rec floor = (x: Number) => {
+@unsafe
+export let floor = (x: Number) => {
   let xval = coerceNumberToWasmF64(x)
   let floored = WasmI64.truncF64S(WasmF64.floor(xval))
-  let ret = WasmI32.toGrain(reducedInteger(floored)): Number
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(floor))
-  ret
+  WasmI32.toGrain(reducedInteger(floored)): Number
 }
 
 /**
@@ -170,14 +161,11 @@ export let rec floor = (x: Number) => {
  *
  * @since v0.4.0
  */
-@disableGC
-export let rec trunc = (x: Number) => {
+@unsafe
+export let trunc = (x: Number) => {
   let xval = coerceNumberToWasmF64(x)
   let trunced = WasmI64.truncF64S(xval)
-  let ret = WasmI32.toGrain(reducedInteger(trunced)): Number
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(trunc))
-  ret
+  WasmI32.toGrain(reducedInteger(trunced)): Number
 }
 
 /**
@@ -188,14 +176,11 @@ export let rec trunc = (x: Number) => {
  *
  * @since v0.4.0
  */
-@disableGC
-export let rec round = (x: Number) => {
+@unsafe
+export let round = (x: Number) => {
   let xval = coerceNumberToWasmF64(x)
   let rounded = WasmI64.truncF64S(WasmF64.nearest(xval))
-  let ret = WasmI32.toGrain(reducedInteger(rounded)): Number
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(round))
-  ret
+  WasmI32.toGrain(reducedInteger(rounded)): Number
 }
 
 /**
@@ -216,21 +201,21 @@ export let abs = (x: Number) => if (0 > x) x * -1 else x
  *
  * @since v0.4.0
  */
-export let neg = (x: Number) => if (x > 0) x * -1 else x
+export let neg = (x: Number) => x * -1
 
 /**
  * Checks if a number is finite.
  * All values are finite exept for floating point NaN, infinity or negative infinity.
  *
  * @param x: The number to check
- * @returns `true` if the value is finite, otherwise `false`
+ * @returns `true` if the value is finite or `false` otherwise
  *
  * @since v0.4.0
  */
-@disableGC
-export let rec isFinite = (x: Number) => {
+@unsafe
+export let isFinite = (x: Number) => {
   let asPtr = WasmI32.fromGrain(x)
-  let ret = if (isBoxedNumber(asPtr)) {
+  if (isBoxedNumber(asPtr)) {
     // Boxed numbers can have multiple subtypes, of which float32 and float64 can be infinite.
     let tag = WasmI32.load(asPtr, 4n)
     if (WasmI32.eq(tag, Tags._GRAIN_FLOAT64_BOXED_NUM_TAG)) {
@@ -251,9 +236,6 @@ export let rec isFinite = (x: Number) => {
     // Simple numbers are integers and cannot be infinite.
     true
   }
-  Memory.decRef(asPtr)
-  Memory.decRef(WasmI32.fromGrain(isFinite))
-  ret
 }
 
 /**
@@ -265,10 +247,10 @@ export let rec isFinite = (x: Number) => {
  *
  * @since v0.4.0
  */
-@disableGC
-export let rec isNaN = (x: Number) => {
+@unsafe
+export let isNaN = (x: Number) => {
   let asPtr = WasmI32.fromGrain(x)
-  let ret = if (isBoxedNumber(asPtr)) {
+  if (isBoxedNumber(asPtr)) {
     // Boxed numbers can have multiple subtypes, of which float32 and float64 can be NaN.
     let tag = WasmI32.load(asPtr, 4n)
     if (WasmI32.eq(tag, Tags._GRAIN_FLOAT64_BOXED_NUM_TAG)) {
@@ -287,9 +269,6 @@ export let rec isNaN = (x: Number) => {
     // Simple numbers are integers and cannot be NaN.
     false
   }
-  Memory.decRef(asPtr)
-  Memory.decRef(WasmI32.fromGrain(isNaN))
-  ret
 }
 
 /**
@@ -297,16 +276,16 @@ export let rec isNaN = (x: Number) => {
  * Note that this function is not the exact opposite of isFinite(Number) in that it doesn't return true for NaN.
  *
  * @param x: The number to check
- * @returns `true` if the value is infinite, otherwise `false`
+ * @returns `true` if the value is infinite or `false` otherwise
  *
  * @since v0.4.0
  */
-@disableGC
-export let rec isInfinite = (x: Number) => {
+@unsafe
+export let isInfinite = (x: Number) => {
   // The following code is equivalent to (!isFinite(x) && !isNaN(x)),
   // so see those functions to understand what's going on here.
   let asPtr = WasmI32.fromGrain(x)
-  let ret = if (isBoxedNumber(asPtr)) {
+  if (isBoxedNumber(asPtr)) {
     let tag = WasmI32.load(asPtr, 4n)
     if (WasmI32.eq(tag, Tags._GRAIN_FLOAT64_BOXED_NUM_TAG)) {
       let wf64 = WasmF64.load(asPtr, 8n)
@@ -320,24 +299,21 @@ export let rec isInfinite = (x: Number) => {
   } else {
     false
   }
-  Memory.decRef(asPtr)
-  Memory.decRef(WasmI32.fromGrain(isInfinite))
-  ret
 }
 
 /**
  * Parses a string representation of an integer into a `Number` using the
  * specified radix (also known as a number system "base").
- * 
+ *
  * If the string has a radix prefix (i.e. "0x"/"0X", "0o"/"0O", or "0b"/"0B"
  * for radixes 16, 8, or 2 respectively), the supplied radix is ignored in
  * favor of the prefix. Underscores that appear in the numeric portion of the
  * input are ignored.
- * 
+ *
  * @param input: The string to parse
  * @param radix: The number system base to use when parsing the input string
  * @returns `Ok(value)` containing the parsed number on a successful parse or `Err(msg)` containing an error message string otherwise
- * 
+ *
  * @since v0.4.5
  */
 export parseInt