@grain/stdlib 0.5.13 → 0.6.1

package/range.md

@@ -2,45 +2,178 @@
 title: Range
 ---
 
-Utilities for working with ranges. A range represents an interval—a set of values with a beginning and an end.
+Utilities for working with ranges.
+
+A range represents an interval—a set of values with a beginning and an end.
+
+All functions in this module treat ranges as exclusive, but inclusive versions
+of all APIs are available in the `Inclusive` submodule.
+
+<details>
+<summary>Added in <code>0.3.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.6.0</code></td><td>Treats all ranges as exclusive</td></tr>
+</tbody>
+</table>
+</details>
+
+```grain
+from "range" include Range
+```
+
+## Values
+
+Functions and constants included in the Range module.
+
+### Range.**inRange**
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.3.0</code></summary>
-No other changes yet.
+<details>
+<summary>Added in <code>0.3.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.6.0</code></td><td>Treats all ranges as exclusive</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-import Range from "range"
+inRange : (value: Number, range: Range<Number>) => Bool
+```
+
+Checks if the given number is within the range.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`value`|`Number`|The number being checked|
+|`range`|`Range<Number>`|The range to check within|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|Whether or not the value is within range|
+
+Examples:
+
+```grain
+Range.inRange(1, { rangeStart: 0, rangeEnd: 2 }) == true
 ```
 
-## Types
+```grain
+Range.inRange(10, { rangeStart: 0, rangeEnd: 2 }) == false
+```
 
-Type declarations included in the Range module.
+### Range.**forEach**
 
-### Range.**Range**
+<details>
+<summary>Added in <code>0.3.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.6.0</code></td><td>Treats all ranges as exclusive</td></tr>
+</tbody>
+</table>
+</details>
 
 ```grain
-enum Range {
-  Inclusive(Number, Number),
-  Exclusive(Number, Number),
-}
+forEach : (fn: (Number => Void), range: Range<Number>) => Void
 ```
 
-Ranges can be inclusive or exclusive. When `Inclusive`, the end value will be included in operations. When `Exclusive`, the end value will be excluded from operations.
+Calls the given function with each number in the range.
 
-## Values
+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.
 
-Functions and constants included in the Range module.
+Parameters:
 
-### Range.**inRange**
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`Number => Void`|The function to be executed on each number in the range|
+|`range`|`Range<Number>`|The range to iterate|
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.3.0</code></summary>
-No other changes yet.
+Examples:
+
+```grain
+Range.forEach(val => print(val), { rangeStart: 0, rangeEnd: 2 })
+```
+
+### Range.**map**
+
+<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.6.0</code></td><td>Treats all ranges as exclusive</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-inRange : (Number, Range) -> Bool
+map : (fn: (Number => a), range: Range<Number>) => 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.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`Number => a`|The function called on each number in the range that returns the value for the output list|
+|`range`|`Range<Number>`|The range to iterate|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`List<a>`|A list containing all values returned from the `fn`|
+
+Examples:
+
+```grain
+Range.map(val => val * 2, { rangeStart: 0, rangeEnd: 3 }) == [0, 2, 4]
+```
+
+## Range.Inclusive
+
+### Values
+
+Functions and constants included in the Range.Inclusive module.
+
+#### Range.Inclusive.**inRange**
+
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.3.0</code></td><td>Root APIs originally handled Inclusive & Exclusive variants</td></tr>
+</tbody>
+</table>
+</details>
+
+```grain
+inRange : (value: Number, range: Range<Number>) => Bool
 ```
 
 Checks if the given number is within the range.
@@ -50,7 +183,7 @@ Parameters:
 |param|type|description|
 |-----|----|-----------|
 |`value`|`Number`|The number being checked|
-|`range`|`Range`|The range to check within|
+|`range`|`Range<Number>`|The range to check within|
 
 Returns:
 
@@ -61,58 +194,80 @@ Returns:
 Examples:
 
 ```grain
-Range.inRange(1, Range.Inclusive(0, 2)) == true
+Range.Inclusive.inRange(1, { rangeStart: 0, rangeEnd: 1 }) == true
 ```
 
 ```grain
-Range.inRange(10, Range.Inclusive(0, 2)) == false
+Range.Inclusive.inRange(10, { rangeStart: 0, rangeEnd: 2 }) == false
 ```
 
-### Range.**forEach**
-
-<details disabled>
-<summary tabindex="-1">Added in <code>0.3.0</code></summary>
-No other changes yet.
+#### Range.Inclusive.**forEach**
+
+<details>
+<summary>Added in <code>0.3.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.3.0</code></td><td>Root APIs originally handled Inclusive & Exclusive variants</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-forEach : ((Number -> Void), Range) -> Void
+forEach : (fn: (Number => Void), range: Range<Number>) => Void
 ```
 
-Calls the given function with each number 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.
+Calls the given function with each number 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.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`Number -> Void`|The function to be executed on each number in the range|
-|`range`|`Range`|The range to iterate|
+|`fn`|`Number => Void`|The function to be executed on each number in the range|
+|`range`|`Range<Number>`|The range to iterate|
 
 Examples:
 
 ```grain
-Range.forEach(val => print(val), Range.Exclusive(0, 2))
+Range.Inclusive.forEach(val => print(val), { rangeStart: 0, rangeEnd: 2 })
 ```
 
-### Range.**map**
-
-<details disabled>
-<summary tabindex="-1">Added in <code>0.3.2</code></summary>
-No other changes yet.
+#### Range.Inclusive.**map**
+
+<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.3.0</code></td><td>Root APIs originally handled Inclusive & Exclusive variants</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-map : ((Number -> a), Range) -> List<a>
+map : (fn: (Number => a), range: Range<Number>) => 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.
+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.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`Number -> a`|The function called on each number in the range that returns the value for the output list|
-|`range`|`Range`|The range to iterate|
+|`fn`|`Number => a`|The function called on each number in the range that returns the value for the output list|
+|`range`|`Range<Number>`|The range to iterate|
 
 Returns:
 
@@ -123,6 +278,6 @@ Returns:
 Examples:
 
 ```grain
-Range.map(val => val * 2, Range.Inclusive(0, 2)) == [0, 2, 4]
+Range.Inclusive.map(val => val * 2, { rangeStart: 0, rangeEnd: 2 }) == [0, 2, 4]
 ```
 

package/rational.gr

@@ -0,0 +1,284 @@
+/**
+ * Utilities for working with the Rational type.
+ * @example from "rational" include Rational
+ *
+ * @example 1/2r
+ * @example 3/4r
+ *
+ * @since v0.6.0
+ */
+module Rational
+
+from "runtime/unsafe/wasmi32" include WasmI32
+from "runtime/exception" include Exception
+from "runtime/numbers" include Numbers
+use Numbers.{
+  coerceNumberToRational as fromNumber,
+  coerceRationalToNumber as toNumber,
+  rationalNumerator as numerator,
+  rationalDenominator as denominator,
+  addSubRational,
+  timesDivideRational,
+  rationalsEqual,
+  cmpRationals,
+  isInteger,
+}
+
+provide { fromNumber, toNumber, numerator, denominator }
+
+/**
+ * Gets the numerator and denominator of the rational.
+ *
+ * @param x: The rational to split
+ * @returns The numerator and denominator of the rational
+ *
+ * @example Rational.toIntegerRatio(1/2r) == (1, 2)
+ * @example Rational.toIntegerRatio(2/8r) == (1, 4)
+ *
+ * @since v0.6.0
+ */
+provide let toIntegerRatio = x => {
+  (numerator(x), denominator(x))
+}
+
+/**
+ * Creates a rational from a numerator and denominator.
+ *
+ * @param numerator: The numerator
+ * @param denominator: The denominator
+ * @returns The reduced rational
+ *
+ * @throws InvalidArgument(String): If the numerator is not an integer
+ * @throws InvalidArgument(String): If the denominator is not an integer
+ *
+ * @example Rational.fromIntegerRatio(1, 2) == 1/2r
+ * @example Rational.fromIntegerRatio(2, 8) == 1/4r
+ *
+ * @since v0.6.0
+ */
+@unsafe
+provide let fromIntegerRatio = (numerator: Number, denominator: Number) => {
+  let numeratorptr = WasmI32.fromGrain(numerator)
+  let denominatorptr = WasmI32.fromGrain(denominator)
+  if (!isInteger(numeratorptr)) {
+    throw Exception.InvalidArgument("Numerator must be an integer")
+  }
+  if (!isInteger(denominatorptr)) {
+    throw Exception.InvalidArgument("Denominator must be an integer")
+  }
+  fromNumber(numerator / denominator)
+}
+
+/**
+ * Computes the sum of its operands.
+ *
+ * @param x: The first operand
+ * @param y: The second operand
+ * @returns The sum of the two operands
+ *
+ * @example
+ * use Rational.{ (+) }
+ * assert 1/2r + 1/4r == 3/4r
+ *
+ * @since v0.6.0
+ */
+@unsafe
+provide let (+) = (x: Rational, y: Rational) => {
+  let xptr = WasmI32.fromGrain(x)
+  let yptr = WasmI32.fromGrain(y)
+  let ptr = addSubRational(xptr, yptr, false, true)
+  WasmI32.toGrain(ptr): Rational
+}
+
+/**
+ * Computes the difference of its operands.
+ *
+ * @param x: The first operand
+ * @param y: The second operand
+ * @returns The difference of the two operands
+ *
+ * @example
+ * use Rational.{ (-) }
+ * assert 1/2r - 1/4r == 1/4r
+ *
+ * @since v0.6.0
+ */
+@unsafe
+provide let (-) = (x: Rational, y: Rational) => {
+  let xptr = WasmI32.fromGrain(x)
+  let yptr = WasmI32.fromGrain(y)
+  let ptr = addSubRational(xptr, yptr, true, true)
+  WasmI32.toGrain(ptr): Rational
+}
+
+/**
+ * Computes the product of its operands.
+ *
+ * @param x: The first operand
+ * @param y: The second operand
+ * @returns The product of the two operands
+ *
+ * @example
+ * use Rational.{ (*) }
+ * assert 1/2r * 1/4r == 1/8r
+ *
+ * @since v0.6.0
+ */
+@unsafe
+provide let (*) = (x: Rational, y: Rational) => {
+  let xptr = WasmI32.fromGrain(x)
+  let yptr = WasmI32.fromGrain(y)
+  let ptr = timesDivideRational(xptr, yptr, false, true)
+  WasmI32.toGrain(ptr): Rational
+}
+
+/**
+ * Computes the quotient of its operands.
+ *
+ * @param x: The first operand
+ * @param y: The second operand
+ * @returns The quotient of the two operands
+ *
+ * @example
+ * use Rational.{ (/) }
+ * assert 1/2r / 1/4r == 2/1r
+ *
+ * @since v0.6.0
+ */
+@unsafe
+provide let (/) = (x: Rational, y: Rational) => {
+  let xptr = WasmI32.fromGrain(x)
+  let yptr = WasmI32.fromGrain(y)
+  let ptr = timesDivideRational(xptr, yptr, true, true)
+  WasmI32.toGrain(ptr): Rational
+}
+
+/**
+ * Checks if the first value is equal to the second value.
+ *
+ * @param x: The first value
+ * @param y: The second value
+ * @returns `true` if the first value is equal to the second value or `false` otherwise
+ *
+ * @example
+ * use Rational.{ (==) }
+ * assert 1/2r == 1/2r
+ *
+ * @since v0.6.0
+ */
+@unsafe
+provide let (==) = (x: Rational, y: Rational) => {
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  rationalsEqual(x, y)
+}
+
+/**
+ * Checks if the first value is not equal to the second value.
+ *
+ * @param x: The first value
+ * @param y: The second value
+ * @returns `true` if the first value is not equal to the second value or `false` otherwise
+ *
+ * @example
+ * use Rational.{ (!=) }
+ * assert 1/2r != 1/4r
+ *
+ * @since v0.6.0
+ */
+@unsafe
+provide let (!=) = (x: Rational, y: Rational) => {
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  !rationalsEqual(x, y)
+}
+
+/**
+ * Checks if the first value is less than the second value.
+ *
+ * @param x: The first value
+ * @param y: The second value
+ * @returns `true` if the first value is less than the second value or `false` otherwise
+ *
+ * @example
+ * use Rational.{ (<) }
+ * assert 1/4r < 1/2r
+ *
+ * @since v0.6.0
+ */
+@unsafe
+provide let (<) = (x: Rational, y: Rational) => {
+  use WasmI32.{ (<) }
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  cmpRationals(x, y) < 0n
+}
+
+/**
+ * Checks if the first value is greater than the second value.
+ *
+ * @param x: The first value
+ * @param y: The second value
+ * @returns `true` if the first value is greater than the second value or `false` otherwise
+ *
+ * @example
+ * use Rational.{ (>) }
+ * assert 1/2r > 1/4r
+ *
+ * @since v0.6.0
+ */
+@unsafe
+provide let (>) = (x: Rational, y: Rational) => {
+  use WasmI32.{ (>) }
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  cmpRationals(x, y) > 0n
+}
+
+/**
+ * Checks if the first value is less than or equal to the second value.
+ *
+ * @param x: The first value
+ * @param y: The second value
+ * @returns `true` if the first value is less than or equal to the second value or `false` otherwise
+ *
+ * @example
+ * use Rational.{ (<=) }
+ * assert 1/4r <= 1/2r
+ * @example
+ * use Rational.{ (<=) }
+ * assert 1/2r <= 1/2r
+ *
+ * @since v0.6.0
+ */
+@unsafe
+provide let (<=) = (x: Rational, y: Rational) => {
+  use WasmI32.{ (<=) }
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  cmpRationals(x, y) <= 0n
+}
+
+/**
+ * Checks if the first value is greater than or equal to the second value.
+ *
+ * @param x: The first value
+ * @param y: The second value
+ * @returns `true` if the first value is greater than or equal to the second value or `false` otherwise
+ *
+ * @example
+ * use Rational.{ (>=) }
+ * assert 1/2r >= 1/4r
+ * @example
+ * use Rational.{ (>=) }
+ * assert 1/2r >= 1/2r
+ *
+ * @since v0.6.0
+ */
+@unsafe
+provide let (>=) = (x: Rational, y: Rational) => {
+  use WasmI32.{ (>=) }
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  cmpRationals(x, y) >= 0n
+}