@grain/stdlib 0.5.13 → 0.6.0

package/number.md

@@ -10,38 +10,77 @@ No other changes yet.
 </details>
 
 ```grain
-import Number from "number"
+from "number" include Number
 ```
 
-## Constants
+```grain
+1
+```
 
-Number constant values.
+```grain
+-1
+```
 
-### Number.**nan**
+```grain
+0.5
+```
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.5.4</code></summary>
-No other changes yet.
-</details>
+```grain
+1/2
+```
 
 ```grain
-nan : Number
+Infinity
 ```
 
-NaN represented as a Number value.
+```grain
+NaN
+```
+
+## Types
+
+Type declarations included in the Number module.
 
-### Number.**infinity**
+### Number.**ParseIntError**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
 No other changes yet.
 </details>
 
 ```grain
-infinity : Number
+enum ParseIntError {
+  ParseIntEmptyString,
+  ParseIntInvalidDigit,
+  ParseIntInvalidRadix,
+}
+```
+
+Represents an error that occurred trying to parse an integer.
+
+Variants:
+
+```grain
+ParseIntEmptyString
+```
+
+Represents an error caused by trying to parse an empty string.
+
+```grain
+ParseIntInvalidDigit
+```
+
+Represents an error caused by trying to parse a string with an invalid character.
+
+```grain
+ParseIntInvalidRadix
 ```
 
-Infinity represented as a Number value.
+Represents an error caused by trying to parse with an invalid radix.
+
+## Values
+
+Functions and constants included in the Number module.
 
 ### Number.**pi**
 
@@ -82,19 +121,22 @@ e : Number
 
 Euler's number represented as a Number value.
 
-## Operations
+### Number.**(+)**
 
-Functions for operating on values of the Number type.
-
-### Number.**add**
-
-<details disabled>
-<summary tabindex="-1">Added in <code>0.4.0</code></summary>
-No other changes yet.
+<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.4.0</code></td><td>Originally named `add`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-add : (Number, Number) -> Number
+(+) : (num1: Number, num2: Number) => Number
 ```
 
 Computes the sum of its operands.
@@ -103,8 +145,8 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`x`|`Number`|The first operand|
-|`y`|`Number`|The second operand|
+|`num1`|`Number`|The first operand|
+|`num2`|`Number`|The second operand|
 
 Returns:
 
@@ -112,15 +154,29 @@ Returns:
 |----|-----------|
 |`Number`|The sum of the two operands|
 
-### Number.**sub**
+Examples:
+
+```grain
+from Number use { (+) }
+assert 1 + 2 == 3
+```
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.4.0</code></summary>
-No other changes yet.
+### Number.**(-)**
+
+<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.4.0</code></td><td>Originally named `sub`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-sub : (Number, Number) -> Number
+(-) : (num1: Number, num2: Number) => Number
 ```
 
 Computes the difference of its operands.
@@ -129,8 +185,8 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`x`|`Number`|The first operand|
-|`y`|`Number`|The second operand|
+|`num1`|`Number`|The first operand|
+|`num2`|`Number`|The second operand|
 
 Returns:
 
@@ -138,15 +194,29 @@ Returns:
 |----|-----------|
 |`Number`|The difference of the two operands|
 
-### Number.**mul**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.4.0</code></summary>
-No other changes yet.
+```grain
+from Number use { (-) }
+assert 5 - 2 == 3
+```
+
+### Number.**(*)**
+
+<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.4.0</code></td><td>Originally named `mul`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-mul : (Number, Number) -> Number
+(*) : (num1: Number, num2: Number) => Number
 ```
 
 Computes the product of its operands.
@@ -155,8 +225,8 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`x`|`Number`|The first operand|
-|`y`|`Number`|The second operand|
+|`num1`|`Number`|The first operand|
+|`num2`|`Number`|The second operand|
 
 Returns:
 
@@ -164,15 +234,29 @@ Returns:
 |----|-----------|
 |`Number`|The product of the two operands|
 
-### Number.**div**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.4.0</code></summary>
-No other changes yet.
+```grain
+from Number use { (*) }
+assert 5 * 4 == 20
+```
+
+### Number.**(/)**
+
+<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.4.0</code></td><td>Originally named `div`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-div : (Number, Number) -> Number
+(/) : (num1: Number, num2: Number) => Number
 ```
 
 Computes the quotient of its operands.
@@ -181,8 +265,8 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`x`|`Number`|The dividend|
-|`y`|`Number`|The divisor|
+|`num1`|`Number`|The dividend|
+|`num2`|`Number`|The divisor|
 
 Returns:
 
@@ -190,15 +274,29 @@ Returns:
 |----|-----------|
 |`Number`|The quotient of the two operands|
 
-### Number.**pow**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.5.4</code></summary>
-No other changes yet.
+```grain
+from Number use { (/) }
+assert 10 / 2.5 == 4
+```
+
+### Number.**(\*\*)**
+
+<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.5.4</code></td><td>Originally named `pow`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-pow : (Number, Number) -> Number
+(**) : (base: Number, power: Number) => Number
 ```
 
 Computes the exponentiation of the given base and power.
@@ -216,6 +314,13 @@ Returns:
 |----|-----------|
 |`Number`|The base raised to the given power|
 
+Examples:
+
+```grain
+from Number use { (**) }
+assert 10 ** 2 == 100
+```
+
 ### Number.**exp**
 
 <details disabled>
@@ -224,7 +329,7 @@ No other changes yet.
 </details>
 
 ```grain
-exp : Number -> Number
+exp : (power: Number) => Number
 ```
 
 Computes the exponentiation of Euler's number to the given power.
@@ -241,6 +346,16 @@ Returns:
 |----|-----------|
 |`Number`|The `Number.e` value raised to the given power|
 
+Examples:
+
+```grain
+Number.exp(1) == Number.e
+```
+
+```grain
+Number.exp(10) == 22026.465794806703
+```
+
 ### Number.**sqrt**
 
 <details disabled>
@@ -249,7 +364,7 @@ No other changes yet.
 </details>
 
 ```grain
-sqrt : Number -> Number
+sqrt : (x: Number) => Number
 ```
 
 Computes the square root of its operand.
@@ -266,10 +381,21 @@ Returns:
 |----|-----------|
 |`Number`|The square root of the operand|
 
+Examples:
+
+```grain
+Number.sqrt(25) == 5
+```
+
 ### Number.**sign**
 
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.0</code></summary>
+No other changes yet.
+</details>
+
 ```grain
-sign : Number -> Number
+sign : (x: Number) => Number
 ```
 
 Determine the positivity or negativity of a Number.
@@ -315,7 +441,7 @@ Number.sign(0) == 0
 </details>
 
 ```grain
-min : (Number, Number) -> Number
+min : (x: Number, y: Number) => Number
 ```
 
 Returns the smaller of its operands.
@@ -333,6 +459,12 @@ Returns:
 |----|-----------|
 |`Number`|The smaller of the two operands|
 
+Examples:
+
+```grain
+Number.min(5, 2) == 2
+```
+
 ### Number.**max**
 
 <details>
@@ -348,7 +480,7 @@ Returns:
 </details>
 
 ```grain
-max : (Number, Number) -> Number
+max : (x: Number, y: Number) => Number
 ```
 
 Returns the larger of its operands.
@@ -366,6 +498,12 @@ Returns:
 |----|-----------|
 |`Number`|The larger of the two operands|
 
+Examples:
+
+```grain
+Number.max(5, 2) == 5
+```
+
 ### Number.**ceil**
 
 <details>
@@ -381,7 +519,7 @@ Returns:
 </details>
 
 ```grain
-ceil : Number -> Number
+ceil : (x: Number) => Number
 ```
 
 Rounds its operand up to the next largest integer.
@@ -398,6 +536,16 @@ Returns:
 |----|-----------|
 |`Number`|The next largest integer of the operand|
 
+Examples:
+
+```grain
+Number.ceil(5.5) == 6
+```
+
+```grain
+Number.ceil(-5.5) == -5
+```
+
 ### Number.**floor**
 
 <details>
@@ -413,7 +561,7 @@ Returns:
 </details>
 
 ```grain
-floor : Number -> Number
+floor : (x: Number) => Number
 ```
 
 Rounds its operand down to the largest integer less than the operand.
@@ -430,6 +578,16 @@ Returns:
 |----|-----------|
 |`Number`|The previous integer of the operand|
 
+Examples:
+
+```grain
+Number.floor(5.5) == 5
+```
+
+```grain
+Number.floor(-5.5) == -6
+```
+
 ### Number.**trunc**
 
 <details>
@@ -445,7 +603,7 @@ Returns:
 </details>
 
 ```grain
-trunc : Number -> Number
+trunc : (x: Number) => Number
 ```
 
 Returns the integer part of its operand, removing any fractional value.
@@ -462,6 +620,12 @@ Returns:
 |----|-----------|
 |`Number`|The integer part of the operand|
 
+Examples:
+
+```grain
+Number.trunc(5.5) == 5
+```
+
 ### Number.**round**
 
 <details>
@@ -477,7 +641,7 @@ Returns:
 </details>
 
 ```grain
-round : Number -> Number
+round : (x: Number) => Number
 ```
 
 Returns its operand rounded to its nearest integer.
@@ -494,6 +658,24 @@ Returns:
 |----|-----------|
 |`Number`|The nearest integer to the operand|
 
+Examples:
+
+```grain
+Number.round(5.5) == 6
+```
+
+```grain
+Number.round(5.4) == 5
+```
+
+```grain
+Number.round(-5.5) == -6
+```
+
+```grain
+Number.round(-5.4) == -5
+```
+
 ### Number.**abs**
 
 <details disabled>
@@ -502,7 +684,7 @@ No other changes yet.
 </details>
 
 ```grain
-abs : Number -> Number
+abs : (x: Number) => Number
 ```
 
 Returns the absolute value of a number. That is, it returns `x` if `x` is positive or zero and the negation of `x` if `x` is negative.
@@ -519,6 +701,16 @@ Returns:
 |----|-----------|
 |`Number`|The absolute value of the operand|
 
+Examples:
+
+```grain
+Number.abs(-1) == 1
+```
+
+```grain
+Number.abs(5) == 5
+```
+
 ### Number.**neg**
 
 <details disabled>
@@ -527,7 +719,7 @@ No other changes yet.
 </details>
 
 ```grain
-neg : Number -> Number
+neg : (x: Number) => Number
 ```
 
 Returns the negation of its operand.
@@ -544,6 +736,16 @@ Returns:
 |----|-----------|
 |`Number`|The negated operand|
 
+Examples:
+
+```grain
+Number.neg(-1) == 1
+```
+
+```grain
+Number.neg(1) == -1
+```
+
 ### Number.**isFloat**
 
 <details disabled>
@@ -552,7 +754,7 @@ No other changes yet.
 </details>
 
 ```grain
-isFloat : Number -> Bool
+isFloat : (x: Number) => Bool
 ```
 
 Checks if a number is a floating point value.
@@ -569,6 +771,32 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the value is a floating point number or `false` otherwise|
 
+Examples:
+
+```grain
+Number.isFloat(0.5)
+```
+
+```grain
+Number.isFloat(1.0)
+```
+
+```grain
+Number.isFloat(Infinity)
+```
+
+```grain
+Number.isFloat(NaN)
+```
+
+```grain
+Number.isFloat(1/2) == false
+```
+
+```grain
+Number.isFloat(1) == false
+```
+
 ### Number.**isInteger**
 
 <details disabled>
@@ -577,7 +805,7 @@ No other changes yet.
 </details>
 
 ```grain
-isInteger : Number -> Bool
+isInteger : (x: Number) => Bool
 ```
 
 Checks if a number is an integer.
@@ -594,6 +822,32 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the value is an integer or `false` otherwise|
 
+Examples:
+
+```grain
+Number.isInteger(1)
+```
+
+```grain
+Number.isInteger(0.5) == false
+```
+
+```grain
+Number.isInteger(1.0) == false
+```
+
+```grain
+Number.isInteger(1/2) == false
+```
+
+```grain
+Number.isInteger(Infinity) == false
+```
+
+```grain
+Number.isInteger(NaN) == false
+```
+
 ### Number.**isRational**
 
 <details disabled>
@@ -602,7 +856,7 @@ No other changes yet.
 </details>
 
 ```grain
-isRational : Number -> Bool
+isRational : (x: Number) => Bool
 ```
 
 Checks if a number is a non-integer rational value.
@@ -619,25 +873,51 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the value is a non-integer rational number or `false` otherwise|
 
-### Number.**isFinite**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.4.0</code></summary>
-No other changes yet.
-</details>
+```grain
+Number.isRational(1/2)
+```
 
 ```grain
-isFinite : Number -> Bool
+Number.isRational(0.5) == false
 ```
 
-Checks if a number is finite.
-All values are finite exept for floating point NaN, infinity or negative infinity.
+```grain
+Number.isRational(1.0) == false
+```
 
-Parameters:
+```grain
+Number.isRational(1) == false
+```
 
-|param|type|description|
-|-----|----|-----------|
-|`x`|`Number`|The number to check|
+```grain
+Number.isRational(Infinity) == false
+```
+
+```grain
+Number.isRational(NaN) == false
+```
+
+### Number.**isFinite**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.4.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+isFinite : (x: Number) => Bool
+```
+
+Checks if a number is finite.
+All values are finite exept for floating point NaN, infinity or negative infinity.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`x`|`Number`|The number to check|
 
 Returns:
 
@@ -645,6 +925,36 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the value is finite or `false` otherwise|
 
+Examples:
+
+```grain
+Number.isFinite(1/2)
+```
+
+```grain
+Number.isFinite(0.5)
+```
+
+```grain
+Number.isFinite(1.0)
+```
+
+```grain
+Number.isFinite(1)
+```
+
+```grain
+Number.isFinite(Infinity) == false
+```
+
+```grain
+Number.isFinite(-Infinity) == false
+```
+
+```grain
+Number.isFinite(NaN) == false
+```
+
 ### Number.**isNaN**
 
 <details disabled>
@@ -653,7 +963,7 @@ No other changes yet.
 </details>
 
 ```grain
-isNaN : Number -> Bool
+isNaN : (x: Number) => Bool
 ```
 
 Checks if a number is the float NaN value (Not A Number).
@@ -670,6 +980,36 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the value is NaN, otherwise `false`|
 
+Examples:
+
+```grain
+Number.isNaN(NaN)
+```
+
+```grain
+Number.isNaN(Infinity) == false
+```
+
+```grain
+Number.isNaN(-Infinity) == false
+```
+
+```grain
+Number.isNaN(1/2) == false
+```
+
+```grain
+Number.isNaN(0.5) == false
+```
+
+```grain
+Number.isNaN(1.0) == false
+```
+
+```grain
+Number.isNaN(1) == false
+```
+
 ### Number.**isInfinite**
 
 <details disabled>
@@ -678,7 +1018,7 @@ No other changes yet.
 </details>
 
 ```grain
-isInfinite : Number -> Bool
+isInfinite : (x: Number) => Bool
 ```
 
 Checks if a number is infinite, that is either of floating point positive or negative infinity.
@@ -696,15 +1036,117 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the value is infinite or `false` otherwise|
 
-### Number.**parseInt**
+Examples:
+
+```grain
+Number.isInfinite(Infinity)
+```
+
+```grain
+Number.isInfinite(-Infinity)
+```
+
+```grain
+Number.isInfinite(NaN) == false
+```
+
+```grain
+Number.isInfinite(1/2) == false
+```
+
+```grain
+Number.isInfinite(0.5) == false
+```
+
+```grain
+Number.isInfinite(1.0) == false
+```
+
+```grain
+Number.isInfinite(1) == false
+```
+
+### Number.**isClose**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>0.4.5</code></summary>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
 No other changes yet.
 </details>
 
 ```grain
-parseInt : (String, Number) -> Result<Number, String>
+isClose :
+  (a: Number, b: Number, ?relativeTolerance: Number,
+   ?absoluteTolerance: Number) => Bool
+```
+
+Determines whether two values are considered close to each other using a relative and absolute tolerance.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`a`|`Number`|The first value|
+|`b`|`Number`|The second value|
+|`?relativeTolerance`|`Number`|The maximum tolerance to use relative to the larger absolute value `a` or `b`|
+|`?absoluteTolerance`|`Number`|The absolute tolerance to use, regardless of the values of `a` or `b`|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the values are considered close to each other or `false` otherwise|
+
+Examples:
+
+```grain
+Number.isClose(1.233, 1.233)
+```
+
+```grain
+Number.isClose(1.233, 1.233000001)
+```
+
+```grain
+Number.isClose(8.005, 8.450, absoluteTolerance=0.5)
+```
+
+```grain
+Number.isClose(4, 4.1, relativeTolerance=0.025)
+```
+
+```grain
+Number.isClose(1.233, 1.24) == false
+```
+
+```grain
+Number.isClose(1.233, 1.4566) == false
+```
+
+```grain
+Number.isClose(8.005, 8.450, absoluteTolerance=0.4) == false
+```
+
+```grain
+Number.isClose(4, 4.1, relativeTolerance=0.024) == false
+```
+
+### Number.**parseInt**
+
+<details>
+<summary>Added in <code>0.4.5</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.6.0</code></td><td>Switched from a string-based error message to a structured error enum</td></tr>
+</tbody>
+</table>
+</details>
+
+```grain
+parseInt :
+  (string: String, radix: Number) => Result<Number, Atoi.ParseIntError>
 ```
 
 Parses a string representation of an integer into a `Number` using the
@@ -719,14 +1161,28 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`input`|`String`|The string to parse|
+|`string`|`String`|The string to parse|
 |`radix`|`Number`|The number system base to use when parsing the input string|
 
 Returns:
 
 |type|description|
 |----|-----------|
-|`Result<Number, String>`|`Ok(value)` containing the parsed number on a successful parse or `Err(msg)` containing an error message string otherwise|
+|`Result<Number, Atoi.ParseIntError>`|`Ok(value)` containing the parsed number on a successful parse or `Err(err)` containing a variant of `ParseIntError`|
+
+Examples:
+
+```grain
+Number.parseInt("1", radix=10) == Ok(1)
+```
+
+```grain
+Number.parseInt("-1", radix=10) == Ok(-1)
+```
+
+```grain
+Number.parseInt("0xf0", radix=16) == Ok(0x0f0)
+```
 
 ### Number.**parseFloat**
 
@@ -736,7 +1192,7 @@ No other changes yet.
 </details>
 
 ```grain
-parseFloat : String -> Result<Number, String>
+parseFloat : (string: String) => Result<Number, String>
 ```
 
 Parses a string representation of a float into a `Number`. Underscores that appear
@@ -746,7 +1202,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`input`|`String`|The string to parse|
+|`string`|`String`|The string to parse|
 
 Returns:
 
@@ -754,6 +1210,20 @@ Returns:
 |----|-----------|
 |`Result<Number, String>`|`Ok(value)` containing the parsed number on a successful parse or `Err(msg)` containing an error message string otherwise|
 
+Examples:
+
+```grain
+Number.parseFloat("1") == Ok(1.0)
+```
+
+```grain
+Number.parseFloat("-1") == Ok(-1.0)
+```
+
+```grain
+Number.parseFloat("-1.5") == Ok(-1.5)
+```
+
 ### Number.**parse**
 
 <details disabled>
@@ -762,7 +1232,7 @@ No other changes yet.
 </details>
 
 ```grain
-parse : String -> Result<Number, String>
+parse : (input: String) => Result<Number, Atoi.ParseIntError>
 ```
 
 Parses a string representation of an integer, float, or rational into a `Number`.
@@ -778,129 +1248,195 @@ Returns:
 
 |type|description|
 |----|-----------|
-|`Result<Number, String>`|`Ok(value)` containing the parsed number on a successful parse or `Err(msg)` containing an error message string otherwise|
+|`Result<Number, Atoi.ParseIntError>`|`Ok(value)` containing the parsed number on a successful parse or `Err(msg)` containing an error message string otherwise|
 
-### Number.**sin**
+Examples:
 
-<details>
-<summary>Added in <code>0.5.2</code></summary>
-<table>
-<thead>
-<tr><th>version</th><th>changes</th></tr>
-</thead>
-<tbody>
-<tr><td><code>0.5.4</code></td><td>Handle NaN and Infinity</td></tr>
-</tbody>
-</table>
+```grain
+Number.parse("1") == Ok(1)
+```
+
+```grain
+Number.parse("-1") == Ok(-1)
+```
+
+```grain
+Number.parse("0xf0") == Ok(0x0f0)
+```
+
+```grain
+Number.parse("-1.5") == Ok(-1.5)
+```
+
+### Number.**asin**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
 </details>
 
 ```grain
-sin : Number -> Number
+asin : (angle: Number) => Number
 ```
 
-Computes the sine of a number (in radians) using Chebyshev polynomials.
+Computes the inverse sine of the given angle.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`radians`|`Number`|The input in radians|
+|`angle`|`Number`|A number between -1 and 1, representing the angle's sine value|
 
 Returns:
 
 |type|description|
 |----|-----------|
-|`Number`|The computed sine|
+|`Number`|The inverse sine (angle in radians between `-pi/2` and `pi/2`) of the given `angle` or `NaN` if the given `angle` is not between`-1` and `1`|
 
-### Number.**cos**
+Examples:
 
-<details>
-<summary>Added in <code>0.5.2</code></summary>
-<table>
-<thead>
-<tr><th>version</th><th>changes</th></tr>
-</thead>
-<tbody>
-<tr><td><code>0.5.4</code></td><td>Handle NaN and Infinity</td></tr>
-</tbody>
-</table>
+```grain
+Number.asin(0) == 0
+```
+
+```grain
+Number.asin(1) == 1.5707963267948966
+```
+
+### Number.**acos**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
 </details>
 
 ```grain
-cos : Number -> Number
+acos : (angle: Number) => Number
 ```
 
-Computes the cosine of a number (in radians) using Chebyshev polynomials.
+Computes the inverse cosine of the given angle.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`radians`|`Number`|The input in radians|
+|`angle`|`Number`|A number between -1 and 1, representing the angle's cosine value|
 
 Returns:
 
 |type|description|
 |----|-----------|
-|`Number`|The computed cosine|
+|`Number`|The inverse cosine (angle in radians between `-pi/2` and `pi/2`) of the given `angle` or `NaN` if the given `angle` is not between`-1` and `1`|
 
-### Number.**tan**
+Examples:
+
+```grain
+Number.acos(1) == 0
+```
+
+```grain
+Number.acos(0) == 1.5707963267948966
+```
+
+### Number.**atan**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
 No other changes yet.
 </details>
 
 ```grain
-tan : Number -> Number
+atan : (angle: Number) => Number
 ```
 
-Computes the tangent of a number (in radians) using Chebyshev polynomials.
+Computes the inverse tangent of the given angle.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`radians`|`Number`|The input in radians|
+|`angle`|`Number`|A number between -1 and 1, representing the angle's tangent value|
 
 Returns:
 
 |type|description|
 |----|-----------|
-|`Number`|The computed tangent|
+|`Number`|The inverse tangent (angle in radians between `-pi/2` and `pi/2`) of the given `angle` or `NaN` if the given `angle` is not between`-1` and `1`|
 
-### Number.**gamma**
+Examples:
+
+```grain
+Number.atan(0) == 0
+```
+
+```grain
+Number.atan(1) == 0.7853981633974483
+```
+
+### Number.**atan2**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
 No other changes yet.
 </details>
 
 ```grain
-gamma : Number -> Number
+atan2 : (y: Number, x: Number) => Number
 ```
 
-Computes the gamma function of a value using Lanczos approximation.
+Computes the angle between the positive x-axis and the ray from the origin to the point (x, y).
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`z`|`Number`|The value to interpolate|
+|`y`|`Number`|The given y coordinate|
+|`x`|`Number`|The given x coordinate|
 
 Returns:
 
 |type|description|
 |----|-----------|
-|`Number`|The gamma of the given value|
+|`Number`|The angle in radians between the positive x-axis and the point (x, y)|
 
-Throws:
+Examples:
 
-`InvalidArgument(String)`
+```grain
+Number.atan2(0, 1) == Number.pi
+```
+
+### Number.**toRadians**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
 
-* When `z` is zero
+```grain
+toRadians : (degrees: Number) => Number
+```
+
+Converts degrees to radians.
+
+Parameters:
 
-### Number.**factorial**
+|param|type|description|
+|-----|----|-----------|
+|`degrees`|`Number`|The value to convert|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Number`|The value in radians|
+
+Examples:
+
+```grain
+Number.toRadians(180) == Number.pi
+```
+
+### Number.**toDegrees**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.4</code></summary>
@@ -908,76 +1444,125 @@ No other changes yet.
 </details>
 
 ```grain
-factorial : Number -> Number
+toDegrees : (radians: Number) => Number
 ```
 
-Computes the product of consecutive integers for an integer input and computes the gamma function for non-integer inputs.
+Converts radians to degrees.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`n`|`Number`|The value to factorialize|
+|`radians`|`Number`|The value to convert|
 
 Returns:
 
 |type|description|
 |----|-----------|
-|`Number`|The factorial of the given value|
+|`Number`|The value in degrees|
 
-Throws:
+Examples:
 
-`InvalidArgument(String)`
+```grain
+Number.toRadians(Number.pi) == 180
+```
 
-* When `n` is negative
+### Number.**clamp**
 
-### Number.**toRadians**
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+clamp : (range: Range<Number>, input: Number) => Number
+```
+
+Constrains a number within the given inclusive range.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`range`|`Range<Number>`|The inclusive range to clamp within|
+|`input`|`Number`|The number to clamp|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Number`|The constrained number|
+
+### Number.**linearInterpolate**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
 No other changes yet.
 </details>
 
 ```grain
-toRadians : Number -> Number
+linearInterpolate : (range: Range<Number>, weight: Number) => Number
 ```
 
-Converts degrees to radians.
+Maps a weight between 0 and 1 within the given inclusive range.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`degrees`|`Number`|The value to convert|
+|`range`|`Range<Number>`|The inclusive range to interpolate within|
+|`weight`|`Number`|The weight to interpolate|
 
 Returns:
 
 |type|description|
 |----|-----------|
-|`Number`|The value in radians|
+|`Number`|The blended value|
 
-### Number.**toDegrees**
+Throws:
+
+`InvalidArgument(String)`
+
+* When `weight` is not between 0 and 1
+* When `range` is not finite
+* When `range` includes NaN
+
+### Number.**linearMap**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
 No other changes yet.
 </details>
 
 ```grain
-toDegrees : Number -> Number
+linearMap :
+  (inputRange: Range<Number>, outputRange: Range<Number>, current: Number) =>
+   Number
 ```
 
-Converts radians to degrees.
+Scales a number from one inclusive range to another inclusive range.
+If the number is outside the input range, it will be clamped.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`radians`|`Number`|The value to convert|
+|`inputRange`|`Range<Number>`|The inclusive range you are mapping from|
+|`outputRange`|`Range<Number>`|The inclusive range you are mapping to|
+|`current`|`Number`|The number to map|
 
 Returns:
 
 |type|description|
 |----|-----------|
-|`Number`|The value in degrees|
+|`Number`|The mapped number|
+
+Throws:
+
+`InvalidArgument(String)`
+
+* When `inputRange` is not finite
+* When `inputRange` includes NaN
+* When `outputRange` is not finite
+* When `outputRange` includes NaN