@grain/stdlib 0.5.13 → 0.6.0

package/bigint.md

@@ -10,12 +10,24 @@ No other changes yet.
 </details>
 
 ```grain
-import BigInt from "bigint"
+from "bigint" include Bigint
 ```
 
-## Conversions
+```grain
+9223372036854775809t
+```
+
+```grain
+0t
+```
+
+```grain
+-9223372036854775809t
+```
+
+## Values
 
-Functions for converting between Numbers and the BigInt type.
+Functions and constants included in the BigInt module.
 
 ### BigInt.**fromNumber**
 
@@ -25,7 +37,7 @@ No other changes yet.
 </details>
 
 ```grain
-fromNumber : Number -> BigInt
+fromNumber : (number: Number) => BigInt
 ```
 
 Converts a Number to a BigInt.
@@ -50,7 +62,7 @@ No other changes yet.
 </details>
 
 ```grain
-toNumber : BigInt -> Number
+toNumber : (num: BigInt) => Number
 ```
 
 Converts a BigInt to a Number.
@@ -67,10 +79,6 @@ Returns:
 |----|-----------|
 |`Number`|The BigInt represented as a Number|
 
-## Operations
-
-Mathematical operations for BigInt values.
-
 ### BigInt.**incr**
 
 <details disabled>
@@ -79,7 +87,7 @@ No other changes yet.
 </details>
 
 ```grain
-incr : BigInt -> BigInt
+incr : (num: BigInt) => BigInt
 ```
 
 Increments the value by one.
@@ -96,6 +104,16 @@ Returns:
 |----|-----------|
 |`BigInt`|The incremented value|
 
+Examples:
+
+```grain
+BigInt.incr(1t) == 2t
+```
+
+```grain
+BigInt.incr(-2t) == -1t
+```
+
 ### BigInt.**decr**
 
 <details disabled>
@@ -104,7 +122,7 @@ No other changes yet.
 </details>
 
 ```grain
-decr : BigInt -> BigInt
+decr : (num: BigInt) => BigInt
 ```
 
 Decrements the value by one.
@@ -121,6 +139,16 @@ Returns:
 |----|-----------|
 |`BigInt`|The decremented value|
 
+Examples:
+
+```grain
+BigInt.decr(2t) == 1t
+```
+
+```grain
+BigInt.decr(-2t) == -3t
+```
+
 ### BigInt.**neg**
 
 <details disabled>
@@ -129,7 +157,7 @@ No other changes yet.
 </details>
 
 ```grain
-neg : BigInt -> BigInt
+neg : (num: BigInt) => BigInt
 ```
 
 Negates the given operand.
@@ -146,6 +174,16 @@ Returns:
 |----|-----------|
 |`BigInt`|The negated operand|
 
+Examples:
+
+```grain
+BigInt.neg(1t) == -1t
+```
+
+```grain
+BigInt.neg(-1t) == 1t
+```
+
 ### BigInt.**abs**
 
 <details disabled>
@@ -154,7 +192,7 @@ No other changes yet.
 </details>
 
 ```grain
-abs : BigInt -> BigInt
+abs : (num: BigInt) => BigInt
 ```
 
 Returns the absolute value of the given operand.
@@ -171,15 +209,32 @@ Returns:
 |----|-----------|
 |`BigInt`|The operand's absolute value|
 
-### BigInt.**add**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.5.0</code></summary>
-No other changes yet.
+```grain
+BigInt.abs(1t) == 1t
+```
+
+```grain
+BigInt.abs(-1t) == 1t
+```
+
+### BigInt.**(+)**
+
+<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.0</code></td><td>Originally named `add`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-add : (BigInt, BigInt) -> BigInt
+(+) : (num1: BigInt, num2: BigInt) => BigInt
 ```
 
 Computes the sum of its operands.
@@ -197,15 +252,29 @@ Returns:
 |----|-----------|
 |`BigInt`|The sum of the two operands|
 
-### BigInt.**sub**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.5.0</code></summary>
-No other changes yet.
+```grain
+use BigInt.{ (+) }
+assert 1t + 1t == 2t
+```
+
+### BigInt.**(-)**
+
+<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.0</code></td><td>Originally named `sub`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-sub : (BigInt, BigInt) -> BigInt
+(-) : (num1: BigInt, num2: BigInt) => BigInt
 ```
 
 Computes the difference of its operands.
@@ -223,15 +292,29 @@ Returns:
 |----|-----------|
 |`BigInt`|The difference of the two operands|
 
-### BigInt.**mul**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.5.0</code></summary>
-No other changes yet.
+```grain
+use BigInt.{ (-) }
+assert 3t - 1t == 2t
+```
+
+### BigInt.**(*)**
+
+<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.0</code></td><td>Originally named `mul`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-mul : (BigInt, BigInt) -> BigInt
+(*) : (num1: BigInt, num2: BigInt) => BigInt
 ```
 
 Computes the product of its operands.
@@ -249,15 +332,29 @@ Returns:
 |----|-----------|
 |`BigInt`|The product of the two operands|
 
-### BigInt.**div**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.5.0</code></summary>
-No other changes yet.
+```grain
+use BigInt.{ (*) }
+assert 3t * 3t == 9t
+```
+
+### BigInt.**(/)**
+
+<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.0</code></td><td>Originally named `div`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-div : (BigInt, BigInt) -> BigInt
+(/) : (num1: BigInt, num2: BigInt) => BigInt
 ```
 
 Computes the quotient of its operands using signed (truncated) division
@@ -276,6 +373,13 @@ Returns:
 |----|-----------|
 |`BigInt`|The quotient of its operands|
 
+Examples:
+
+```grain
+use BigInt.{ (/) }
+assert 9t / 3t == 3t
+```
+
 ### BigInt.**rem**
 
 <details disabled>
@@ -284,7 +388,7 @@ No other changes yet.
 </details>
 
 ```grain
-rem : (BigInt, BigInt) -> BigInt
+rem : (num1: BigInt, num2: BigInt) => BigInt
 ```
 
 Computes the remainder of the division of its operands using signed (truncated) division
@@ -303,6 +407,12 @@ Returns:
 |----|-----------|
 |`BigInt`|The remainder of its operands|
 
+Examples:
+
+```grain
+BigInt.rem(3t, 2t) == 1t
+```
+
 ### BigInt.**quotRem**
 
 <details disabled>
@@ -311,7 +421,7 @@ No other changes yet.
 </details>
 
 ```grain
-quotRem : (BigInt, BigInt) -> (BigInt, BigInt)
+quotRem : (num1: BigInt, num2: BigInt) => (BigInt, BigInt)
 ```
 
 Computes the quotient and remainder of its operands using signed (truncated) division.
@@ -329,6 +439,12 @@ Returns:
 |----|-----------|
 |`(BigInt, BigInt)`|The quotient and remainder of its operands|
 
+Examples:
+
+```grain
+BigInt.quotRem(7t, 2t) == (3t, 1t))
+```
+
 ### BigInt.**gcd**
 
 <details disabled>
@@ -337,7 +453,7 @@ No other changes yet.
 </details>
 
 ```grain
-gcd : (BigInt, BigInt) -> BigInt
+gcd : (num1: BigInt, num2: BigInt) => BigInt
 ```
 
 Computes the greatest common divisior of the two operands.
@@ -355,19 +471,28 @@ Returns:
 |----|-----------|
 |`BigInt`|The greatest common divisor of its operands|
 
-## Bitwise operations
-
-Functions for operating on bits of BigInt values.
+Examples:
 
-### BigInt.**shl**
+```grain
+BigInt.gcd(36t, 24t) == 12t
+```
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.5.0</code></summary>
-No other changes yet.
+### BigInt.**(<<)**
+
+<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.0</code></td><td>Originally named `shl`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-shl : (BigInt, Int32) -> BigInt
+(<<) : (num: BigInt, places: Int32) => BigInt
 ```
 
 Shifts the bits of the value left by the given number of bits.
@@ -385,15 +510,29 @@ Returns:
 |----|-----------|
 |`BigInt`|The shifted value|
 
-### BigInt.**shr**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.5.0</code></summary>
-No other changes yet.
+```grain
+use BigInt.{ (<<) }
+assert (10t << 2l) == 40t
+```
+
+### BigInt.**(>>)**
+
+<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.0</code></td><td>Originally named `shr`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-shr : (BigInt, Int32) -> BigInt
+(>>) : (num: BigInt, places: Int32) => BigInt
 ```
 
 Shifts the bits of the value right by the given number of bits, preserving the sign bit.
@@ -411,9 +550,12 @@ Returns:
 |----|-----------|
 |`BigInt`|The shifted value|
 
-## Comparisons
+Examples:
 
-Functions for comparing BigInt values.
+```grain
+use BigInt.{ (>>) }
+assert (9999t >> 2l) == 2499t
+```
 
 ### BigInt.**eqz**
 
@@ -423,7 +565,7 @@ No other changes yet.
 </details>
 
 ```grain
-eqz : BigInt -> Bool
+eqz : (num: BigInt) => Bool
 ```
 
 Checks if the given value is equal to zero.
@@ -440,15 +582,32 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is equal to zero or `false` otherwise|
 
-### BigInt.**eq**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.5.0</code></summary>
-No other changes yet.
+```grain
+assert BigInt.eqz(0t) == true
+```
+
+```grain
+assert BigInt.eqz(1t) == false
+```
+
+### BigInt.**(==)**
+
+<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.0</code></td><td>Originally named `eq`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-eq : (BigInt, BigInt) -> Bool
+(==) : (num1: BigInt, num2: BigInt) => Bool
 ```
 
 Checks if the first value is equal to the second value.
@@ -466,15 +625,34 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is equal to the second value or `false` otherwise|
 
-### BigInt.**ne**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.5.0</code></summary>
-No other changes yet.
+```grain
+use BigInt.{ (==) }
+assert 1t == 1t
+```
+
+```grain
+use BigInt.{ (==) }
+assert -10t == -10t
+```
+
+### BigInt.**(!=)**
+
+<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.0</code></td><td>Originally named `ne`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-ne : (BigInt, BigInt) -> Bool
+(!=) : (num1: BigInt, num2: BigInt) => Bool
 ```
 
 Checks if the first value is not equal to the second value.
@@ -492,15 +670,34 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is not equal to the second value or `false` otherwise|
 
-### BigInt.**lt**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.5.0</code></summary>
-No other changes yet.
+```grain
+use BigInt.{ (!=) }
+assert 1t != 2t
+```
+
+```grain
+use BigInt.{ (!=) }
+assert -10t != -20t
+```
+
+### BigInt.**(<)**
+
+<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.0</code></td><td>Originally named `lt`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-lt : (BigInt, BigInt) -> Bool
+(<) : (num1: BigInt, num2: BigInt) => Bool
 ```
 
 Checks if the first value is less than the second value.
@@ -518,15 +715,34 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is less than the second value or `false` otherwise|
 
-### BigInt.**lte**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.5.0</code></summary>
-No other changes yet.
+```grain
+use BigInt.{ (<) }
+assert 1t < 2t
+```
+
+```grain
+use BigInt.{ (<) }
+assert -10t < 0t
+```
+
+### BigInt.**(<=)**
+
+<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.0</code></td><td>Originally named `lte`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-lte : (BigInt, BigInt) -> Bool
+(<=) : (num1: BigInt, num2: BigInt) => Bool
 ```
 
 Checks if the first value is less than or equal to the second value.
@@ -544,15 +760,39 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is less than or equal to the second value or `false` otherwise|
 
-### BigInt.**gt**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.5.0</code></summary>
-No other changes yet.
+```grain
+use BigInt.{ (<=) }
+assert 1t <= 1t
+```
+
+```grain
+use BigInt.{ (<=) }
+assert -10t <= 0t
+```
+
+```grain
+use BigInt.{ (<=) }
+assert 2t <= 3t
+```
+
+### BigInt.**(>)**
+
+<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.0</code></td><td>Originally named `gt`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-gt : (BigInt, BigInt) -> Bool
+(>) : (num1: BigInt, num2: BigInt) => Bool
 ```
 
 Checks if the first value is greater than the second value.
@@ -570,15 +810,34 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is greater than the second value or `false` otherwise|
 
-### BigInt.**gte**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.5.0</code></summary>
-No other changes yet.
+```grain
+use BigInt.{ (>) }
+assert 2t > 1t
+```
+
+```grain
+use BigInt.{ (>) }
+assert 0t > -10t
+```
+
+### BigInt.**(>=)**
+
+<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.0</code></td><td>Originally named `gte`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-gte : (BigInt, BigInt) -> Bool
+(>=) : (num1: BigInt, num2: BigInt) => Bool
 ```
 
 Checks if the first value is greater than or equal to the second value.
@@ -596,9 +855,22 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is greater than or equal to the second value or `false` otherwise|
 
-## Bitwise logic
+Examples:
 
-Boolean operations on the bits of BigInt values.
+```grain
+use BigInt.{ (>=) }
+assert 1t >= 1t
+```
+
+```grain
+use BigInt.{ (>=) }
+assert 0t >= -10t
+```
+
+```grain
+use BigInt.{ (>=) }
+assert 3t >= 2t
+```
 
 ### BigInt.**lnot**
 
@@ -608,7 +880,7 @@ No other changes yet.
 </details>
 
 ```grain
-lnot : BigInt -> BigInt
+lnot : (num: BigInt) => BigInt
 ```
 
 Computes the bitwise NOT of the given value.
@@ -625,15 +897,28 @@ Returns:
 |----|-----------|
 |`BigInt`|Containing the inverted bits of the given value|
 
-### BigInt.**land**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.5.0</code></summary>
-No other changes yet.
+```grain
+BigInt.lnot(91234t) == -91235t
+```
+
+### BigInt.**(&)**
+
+<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.0</code></td><td>Originally named `land`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-land : (BigInt, BigInt) -> BigInt
+(&) : (num1: BigInt, num2: BigInt) => BigInt
 ```
 
 Computes the bitwise AND (`&`) on the given operands.
@@ -651,15 +936,29 @@ Returns:
 |----|-----------|
 |`BigInt`|Containing a `1` in each bit position for which the corresponding bits of both operands are `1`|
 
-### BigInt.**lor**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.5.0</code></summary>
-No other changes yet.
+```grain
+use BigInt.{ (&) }
+assert (4t & 3t) == 0t
+```
+
+### BigInt.**(|)**
+
+<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.0</code></td><td>Originally named `lor`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-lor : (BigInt, BigInt) -> BigInt
+(|) : (num1: BigInt, num2: BigInt) => BigInt
 ```
 
 Computes the bitwise OR (`|`) on the given operands.
@@ -677,15 +976,29 @@ Returns:
 |----|-----------|
 |`BigInt`|Containing a `1` in each bit position for which the corresponding bits of either or both operands are `1`|
 
-### BigInt.**lxor**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.5.0</code></summary>
-No other changes yet.
+```grain
+use BigInt.{ (|) }
+assert (5t | 3t) == 7t
+```
+
+### BigInt.**(^)**
+
+<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.0</code></td><td>Originally named `lxor`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-lxor : (BigInt, BigInt) -> BigInt
+(^) : (num1: BigInt, num2: BigInt) => BigInt
 ```
 
 Computes the bitwise XOR (`^`) on the given operands.
@@ -703,6 +1016,13 @@ Returns:
 |----|-----------|
 |`BigInt`|Containing a `1` in each bit position for which the corresponding bits of either but not both operands are `1`|
 
+Examples:
+
+```grain
+use BigInt.{ (^) }
+assert (5t ^ 3t) == 6t
+```
+
 ### BigInt.**clz**
 
 <details disabled>
@@ -711,7 +1031,7 @@ No other changes yet.
 </details>
 
 ```grain
-clz : BigInt -> Int32
+clz : (num: BigInt) => Int32
 ```
 
 Counts the number of leading zero bits in the value.
@@ -729,6 +1049,12 @@ Returns:
 |----|-----------|
 |`Int32`|The amount of leading zeros|
 
+Examples:
+
+```grain
+BigInt.clz(5t) == 2147483647t
+```
+
 ### BigInt.**ctz**
 
 <details disabled>
@@ -737,7 +1063,7 @@ No other changes yet.
 </details>
 
 ```grain
-ctz : BigInt -> Int64
+ctz : (num: BigInt) => Int64
 ```
 
 Counts the number of trailing zero bits in the value.
@@ -754,6 +1080,12 @@ Returns:
 |----|-----------|
 |`Int64`|The amount of trailing zeros|
 
+Examples:
+
+```grain
+BigInt.ctz(14t) == 1t
+```
+
 ### BigInt.**popcnt**
 
 <details disabled>
@@ -762,7 +1094,7 @@ No other changes yet.
 </details>
 
 ```grain
-popcnt : BigInt -> Option<Int64>
+popcnt : (num: BigInt) => Option<Int64>
 ```
 
 Counts the number of bits set to `1` in the value, also known as a population count.
@@ -780,9 +1112,11 @@ Returns:
 |----|-----------|
 |`Option<Int64>`|The amount of 1-bits in its operand|
 
-## Other
+Examples:
 
-Other functions on BigInts.
+```grain
+BigInt.popcnt(14t) == 1t
+```
 
 ### BigInt.**toString**
 
@@ -792,7 +1126,7 @@ No other changes yet.
 </details>
 
 ```grain
-toString : BigInt -> String
+toString : (num: BigInt) => String
 ```
 
 Converts the given operand to a string.
@@ -809,3 +1143,13 @@ Returns:
 |----|-----------|
 |`String`|The operand, as a string|
 
+Examples:
+
+```grain
+BigInt.toString(1t) == "1"
+```
+
+```grain
+BigInt.toString(-1t) == "-1"
+```
+