@grain/stdlib 0.5.0 → 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,12 +13,43 @@ import {
   coerceNumberToWasmF64,
   reducedInteger,
   isFloat,
+  isInteger,
+  isRational,
   isBoxedNumber,
 } from "runtime/numbers"
 import { parseInt } from "runtime/stringUtils"
 import { newFloat64, newInt64 } from "runtime/dataStructures"
 import Tags from "runtime/unsafe/tags"
 
+/**
+ * @section Constants: Number constant values.
+ */
+
+/**
+ * Pi represented as a Number value.
+ * 
+ * @since v0.5.2
+ */
+export let pi = 3.141592653589793
+
+/**
+ * Tau represented as a Number value.
+ * 
+ * @since v0.5.2
+ */
+export let tau = 6.283185307179586
+
+/**
+ * Euler's number represented as a Number value.
+ * 
+ * @since v0.5.2
+ */
+export let e = 2.718281828459045
+
+/**
+ * @section Operations: Functions for operating on values of the Number type.
+ */
+
 /**
  * Computes the sum of its operands.
  *
@@ -203,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.
@@ -317,3 +387,55 @@ export let isInfinite = (x: Number) => {
  * @since v0.4.5
  */
 export parseInt
+
+/**
+ * Computes how many times pi has to be subtracted to achieve the required bounds for sin.
+ */
+let reduceToPiBound = (radians: Number) => {
+  floor(radians / pi)
+}
+
+/**
+ * Computes the sine of a number using Chebyshev polynomials. Requires the input to be bounded to (-pi, pi). More information on the algorithm can be found here: http://mooooo.ooo/chebyshev-sine-approximation/.
+ */
+let chebyshevSine = (radians: Number) => {
+  let pi_minor = -0.00000008742278
+  let x2 = radians * radians
+  let p11 = 0.00000000013291342
+  let p9 = p11 * x2 + -0.000000023317787
+  let p7 = p9 * x2 + 0.0000025222919
+  let p5 = p7 * x2 + -0.00017350505
+  let p3 = p5 * x2 + 0.0066208798
+  let p1 = p3 * x2 + -0.10132118
+  (radians - pi - pi_minor) * (radians + pi + pi_minor) * p1 * radians
+}
+
+/**
+ * Computes the sine of a number (in radians) using Chebyshev polynomials.
+ *
+ * @param radians: The input in radians
+ * @returns The computed sine
+ *
+ * @since v0.5.2
+ */
+export let sin = (radians: Number) => {
+  let quot = reduceToPiBound(radians)
+  let bounded = radians - pi * quot
+  if (quot % 2 == 0) {
+    chebyshevSine(bounded)
+  } else {
+    neg(chebyshevSine(bounded))
+  }
+}
+
+/**
+ * Computes the cosine of a number (in radians) using Chebyshev polynomials.
+ *
+ * @param radians: The input in radians
+ * @returns The computed cosine
+ *
+ * @since v0.5.2
+ */
+export let cos = (radians: Number) => {
+  sin(pi / 2 + radians)
+}

package/number.md

@@ -13,6 +13,53 @@ No other changes yet.
 import Number from "number"
 ```
 
+## Constants
+
+Number constant values.
+
+### Number.**pi**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.2</code></summary>
+No other changes yet.
+</details>
+
+```grain
+pi : Number
+```
+
+Pi represented as a Number value.
+
+### Number.**tau**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.2</code></summary>
+No other changes yet.
+</details>
+
+```grain
+tau : Number
+```
+
+Tau represented as a Number value.
+
+### Number.**e**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.2</code></summary>
+No other changes yet.
+</details>
+
+```grain
+e : Number
+```
+
+Euler's number represented as a Number value.
+
+## Operations
+
+Functions for operating on values of the Number type.
+
 ### Number.**add**
 
 <details disabled>
@@ -378,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>
@@ -488,3 +610,53 @@ Returns:
 |----|-----------|
 |`Result<Number, String>`|`Ok(value)` containing the parsed number on a successful parse or `Err(msg)` containing an error message string otherwise|
 
+### Number.**sin**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.2</code></summary>
+No other changes yet.
+</details>
+
+```grain
+sin : Number -> Number
+```
+
+Computes the sine of a number (in radians) using Chebyshev polynomials.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`radians`|`Number`|The input in radians|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Number`|The computed sine|
+
+### Number.**cos**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.2</code></summary>
+No other changes yet.
+</details>
+
+```grain
+cos : Number -> Number
+```
+
+Computes the cosine of a number (in radians) using Chebyshev polynomials.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`radians`|`Number`|The input in radians|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Number`|The computed cosine|
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grain/stdlib",
-  "version": "0.5.0",
+  "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.