@grain/stdlib 0.5.2 → 0.5.3

package/marshal.md

@@ -0,0 +1,76 @@
+---
+title: Marshal
+---
+
+Utilities for serializing and deserializing Grain data.
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+import Marshal from "marshal"
+```
+
+## Values
+
+Functions for marshaling and unmarshaling data.
+
+### Marshal.**marshal**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+marshal : a -> Bytes
+```
+
+Serialize a value into a byte-based representation suitable for transmission
+across a network or disk storage. The byte-based representation can be
+deserialized at a later time to restore the value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`value`|`a`|The value to serialize|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bytes`|A byte-based representation of the value|
+
+### Marshal.**unmarshal**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+unmarshal : Bytes -> Result<a, String>
+```
+
+Deserialize the byte-based representation of a value back into an in-memory
+value. This operation is not type-safe, and it is recommended that a type
+annotation is used to declare the type of the unmarshaled value. While
+attempts to unmarshal bad data will fail, this operation is still generally
+unsafe and great care should be taken to ensure that the data being
+unmarshaled corresponds to the expected type.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`bytes`|`Bytes`|The data to deserialize|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Result<a, String>`|An in-memory value|
+

package/number.gr

@@ -13,6 +13,8 @@ import {
   coerceNumberToWasmF64,
   reducedInteger,
   isFloat,
+  isInteger,
+  isRational,
   isBoxedNumber,
 } from "runtime/numbers"
 import { parseInt } from "runtime/stringUtils"
@@ -232,6 +234,45 @@ export let abs = (x: Number) => if (0 > x) x * -1 else x
  */
 export let neg = (x: Number) => x * -1
 
+/**
+ * Checks if a number is a floating point value.
+ *
+ * @param x: The number to check
+ * @returns `true` if the value is a floating point number or `false` otherwise
+ *
+ * @since v0.5.3
+ */
+@unsafe
+export let isFloat = (x: Number) => {
+  isFloat(WasmI32.fromGrain(x))
+}
+
+/**
+ * Checks if a number is an integer.
+ *
+ * @param x: The number to check
+ * @returns `true` if the value is an integer or `false` otherwise
+ *
+ * @since v0.5.3
+ */
+@unsafe
+export let isInteger = (x: Number) => {
+  isInteger(WasmI32.fromGrain(x))
+}
+
+/**
+ * Checks if a number is a non-integer rational value.
+ *
+ * @param x: The number to check
+ * @returns `true` if the value is a non-integer rational number or `false` otherwise
+ *
+ * @since v0.5.3
+ */
+@unsafe
+export let isRational = (x: Number) => {
+  isRational(WasmI32.fromGrain(x))
+}
+
 /**
  * Checks if a number is finite.
  * All values are finite exept for floating point NaN, infinity or negative infinity.

package/number.md

@@ -20,7 +20,7 @@ Number constant values.
 ### Number.**pi**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.5.2</code></summary>
 No other changes yet.
 </details>
 
@@ -33,7 +33,7 @@ Pi represented as a Number value.
 ### Number.**tau**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.5.2</code></summary>
 No other changes yet.
 </details>
 
@@ -46,7 +46,7 @@ Tau represented as a Number value.
 ### Number.**e**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.5.2</code></summary>
 No other changes yet.
 </details>
 
@@ -425,6 +425,81 @@ Returns:
 |----|-----------|
 |`Number`|The negated operand|
 
+### Number.**isFloat**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+isFloat : Number -> Bool
+```
+
+Checks if a number is a floating point value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`x`|`Number`|The number to check|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the value is a floating point number or `false` otherwise|
+
+### Number.**isInteger**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+isInteger : Number -> Bool
+```
+
+Checks if a number is an integer.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`x`|`Number`|The number to check|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the value is an integer or `false` otherwise|
+
+### Number.**isRational**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+isRational : Number -> Bool
+```
+
+Checks if a number is a non-integer rational value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`x`|`Number`|The number to check|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the value is a non-integer rational number or `false` otherwise|
+
 ### Number.**isFinite**
 
 <details disabled>
@@ -538,7 +613,7 @@ Returns:
 ### Number.**sin**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.5.2</code></summary>
 No other changes yet.
 </details>
 
@@ -563,7 +638,7 @@ Returns:
 ### Number.**cos**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.5.2</code></summary>
 No other changes yet.
 </details>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grain/stdlib",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "The standard library for the Grain language.",
   "license": "MIT",
   "homepage": "https://grain-lang.org",

package/pervasives.gr

@@ -11,6 +11,7 @@ import Memory from "runtime/unsafe/memory"
 import WasmI32 from "runtime/unsafe/wasmi32"
 
 import { equal as (==) } from "runtime/equal"
+import { compare } from "runtime/compare"
 
 import {
   incr,
@@ -218,6 +219,19 @@ export (<=)
  */
 export (>=)
 
+/**
+ * Compares the first argument to the second argument and produces an integer result.
+ * Provides a consistent ordering over all types and is suitable for sorting and other kinds of ordering.
+ * `compare` treats `NaN` differently than the other comparison operators in that it considers `NaN` equal to itself and smaller than any other number.
+ *
+ * @param num1: The first operand
+ * @param num2: The second operand
+ * @returns A negative integer if the first operand is less than the second operand, `0` if they are equal, or a positive integer otherwise
+ *
+ * @since v0.5.3
+ */
+export compare
+
 /**
  * @section Math operations: Infix functions for working with Number values.
  */
@@ -410,7 +424,7 @@ export (>>)
 
 // Number coercions & conversions
 
-// [TODO] (#311) Commented until we nail down semantics
+// TODO(#311): Commented until we nail down semantics
 // import foreign wasm convertExactToInexact : Number -> Number as inexact from "stdlib-external/runtime"
 // import foreign wasm convertInexactToExact : Number -> Number as exact from "stdlib-external/runtime"
 
@@ -553,10 +567,7 @@ export primitive unbox: Box<a> -> a = "@unbox"
  * @since v0.4.0
  */
 export let cons = (a, b) =>
-  [
-    a,
-    ...b
-  ] // <- workaround for (grain-lang/grain#802) [TODO] fix #802 and delete
+  [a, ...b] // TODO(#802): Remove workaround after 802 is completed
 /**
  * The empty list syntax (`[]`) provided as a value.
  *

package/pervasives.md

@@ -369,6 +369,34 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first operand is greater than or equal to the second operand or `false` otherwise|
 
+### Pervasives.**compare**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+compare : (a, a) -> Number
+```
+
+Compares the first argument to the second argument and produces an integer result.
+Provides a consistent ordering over all types and is suitable for sorting and other kinds of ordering.
+`compare` treats `NaN` differently than the other comparison operators in that it considers `NaN` equal to itself and smaller than any other number.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`num1`|`a`|The first operand|
+|`num2`|`a`|The second operand|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Number`|A negative integer if the first operand is less than the second operand, `0` if they are equal, or a positive integer otherwise|
+
 ## Math operations
 
 Infix functions for working with Number values.

package/priorityqueue.gr

@@ -0,0 +1,241 @@
+/**
+ * @module PriorityQueue: A mutable priority queue implementation. A priority queue is a data structure that maintains elements in a priority order. Elements with higher priority are served before elements with lower priority when extracting from the priority queue.
+ *
+ * @example import PriorityQueue from "priorityqueue"
+ *
+ * @since v0.5.3
+ */
+
+import Array from "array"
+import List from "list"
+import Number from "number"
+import Option from "option"
+
+/**
+ * @section Types: Type declarations included in the PriorityQueue module.
+ */
+
+/**
+ * Mutable data structure which maintains a priority order for its elements.
+ */
+record PriorityQueue<a> {
+  mut size: Number,
+  mut array: Array<Option<a>>,
+  comp: (a, a) -> Number,
+}
+
+/**
+ * @section Values: Functions for working with PriorityQueues.
+ */
+
+let swap = (i1, i2, array) => {
+  let t = array[i2]
+  array[i2] = array[i1]
+  array[i1] = t
+}
+
+let get = (array, i) =>
+  Option.expect(
+    "Impossible: " ++
+    toString(i) ++
+    " in PriorityQueue's inner storage array is None",
+    array[i]
+  )
+
+let rec siftDown = (i, pq) => {
+  let leftI = 2 * i + 1
+  let rightI = 2 * i + 2
+
+  // we want to find the smaller child from the current tree node to sift down to
+  let mut swapWithI = i
+  if (leftI < pq.size && pq.comp(get(pq.array, leftI), get(pq.array, i)) < 0) {
+    swapWithI = leftI
+  }
+  if (
+    rightI < pq.size &&
+    pq.comp(get(pq.array, rightI), get(pq.array, swapWithI)) < 0
+  ) {
+    swapWithI = rightI
+  }
+  if (swapWithI != i) {
+    swap(i, swapWithI, pq.array)
+    siftDown(swapWithI, pq)
+  }
+}
+
+let rec siftUp = (i, pq) => {
+  let parentI = Number.trunc((i - 1) / 2)
+  // we should only sift up if the element is smaller than its parent
+  if (i > 0 && pq.comp(get(pq.array, i), get(pq.array, parentI)) < 0) {
+    swap(i, parentI, pq.array)
+    siftUp(parentI, pq)
+  }
+}
+
+/**
+ * Creates a new priority queue with a given internal storage size and a
+ * comparator function, which is used to determine priority of elements. The
+ * comparator function takes two elements and must return 0 if both share
+ * priority, a positive number if the first has greater priority, and a
+ * negative number if the first has less priority.
+ * 
+ * Generally, you won't need to care about the storage size of your priority
+ * queue and can use `PriorityQueue.make()` instead.
+ * 
+ * @param size: The initial storage size of the priority queue
+ * @param comp: The comparator function used to indicate priority order
+ * @returns An empty priority queue
+ *
+ * @since v0.5.3
+ */
+export let makeSized = (size, comp) => {
+  { size: 0, array: Array.make(size, None), comp }
+}
+
+/**
+ * Creates a new priority queue with a comparator function, which is used to
+ * determine priority of elements. The comparator function takes two elements
+ * and must return 0 if both share priority, a positive number if the first
+ * has greater priority, and a negative number if the first has less priority.
+ * 
+ * @param comp: The comparator function used to indicate priority order
+ * @returns An empty priority queue
+ * 
+ * @example PriorityQueue.make(compare) // creates a min priority queue of numbers using the compare pervasive
+ * @example PriorityQueue.make((a, b) => String.length(b) - String.length(a)) // creates a priority queue by string length (longest to shortest)
+ *
+ * @since v0.5.3
+ */
+export let make = comp => {
+  makeSized(16, comp)
+}
+
+/**
+ * Gets the number of elements in a priority queue.
+ * 
+ * @param pq: The priority queue to inspect
+ * @returns The number of elements in the priority queue
+ *
+ * @since v0.5.3
+ */
+export let size = pq => {
+  pq.size
+}
+
+/**
+ * Determines if the priority queue contains no elements.
+ * 
+ * @param pq: The priority queue to check
+ * @returns `true` if the priority queue is empty and `false` otherwise
+ *
+ * @since v0.5.3
+ */
+export let isEmpty = pq => {
+  pq.size == 0
+}
+
+/**
+ * Adds a new element to the priority queue.
+ * 
+ * @param val: The value to add into the priority queue
+ * @param pq: The priority queue to update
+ *
+ * @since v0.5.3
+ */
+export let push = (val, pq) => {
+  let arrLen = Array.length(pq.array)
+  // double size of internal array if out of space
+  if (pq.size == arrLen) {
+    let oldArr = pq.array
+    pq.array = Array.make(arrLen * 2, None)
+    Array.forEachi((val, i) => {
+      pq.array[i] = val
+    }, oldArr)
+  }
+  pq.array[pq.size] = Some(val)
+  pq.size += 1
+  // reorder heap to ensure that binary heap property of parent nodes having
+  // larger values than their children is upheld
+  siftUp(pq.size - 1, pq)
+}
+
+/**
+ * Retrieves the highest priority element in the priority queue. It is not
+ * removed from the queue.
+ * 
+ * @param pq: The priority queue to inspect
+ * @returns `Some(value)` containing the highest priority element or `None` if the priority queue is empty
+ *
+ * @since v0.5.3
+ */
+export let peek = pq => {
+  if (pq.size == 0) {
+    None
+  } else {
+    pq.array[0]
+  }
+}
+
+/**
+ * Removes and retrieves the highest priority element in the priority queue.
+ * 
+ * @param pq: The priority queue to inspect
+ * @returns `Some(value)` containing the highest priority element or `None` if the priority queue is empty
+ *
+ * @since v0.5.3
+ */
+export let pop = pq => {
+  if (pq.size == 0) {
+    None
+  } else {
+    let root = pq.array[0]
+
+    pq.array[0] = pq.array[pq.size - 1]
+    pq.array[pq.size - 1] = None
+    pq.size -= 1
+    // reorder heap to ensure that binary heap property of parent nodes having
+    // larger values than their children is upheld
+    siftDown(0, pq)
+    root
+  }
+}
+
+/**
+ * Clears the priority queue and produces a list of all of the elements in the priority
+ * queue in priority order.
+ * 
+ * @param pq: The priority queue to drain
+ * @returns A list of all elements in the priority in priority order
+ *
+ * @since v0.5.3
+ */
+export let drain = pq => {
+  let rec drainRec = acc => {
+    match (pop(pq)) {
+      Some(val) => drainRec([val, ...acc]),
+      None => acc,
+    }
+  }
+  List.reverse(drainRec([]))
+}
+
+/**
+ * Constructs a new priority queue initialized with the elements in the list
+ * using a custom comparator function, which is used to determine priority of
+ * elements. The comparator function takes two elements and must return 0 if
+ * both share priority, a positive number if the first has greater priority,
+ * and a negative number if the first has less priority.
+ * 
+ * @param list: A list of values used to initialize the priority queue
+ * @param comp: A comparator function used to assign priority to elements
+ * @returns A priority queue containing the elements from the list
+ *
+ * @since v0.5.3
+ */
+export let fromList = (list, comp) => {
+  let heap = makeSized(List.length(list), comp)
+  List.forEach(val => {
+    push(val, heap)
+  }, list)
+  heap
+}