From 8666e44137e4024a30768960c827a219c0ebb139 Mon Sep 17 00:00:00 2001
From: Spotandjake <spotandjake@hotmail.com>
Date: Sat, 30 Dec 2023 04:56:46 -0500
Subject: [PATCH] chore(stdlib): Add examples to `BigInt` lib

---
 stdlib/bigint.gr | 120 ++++++++++++++++++++++
 stdlib/bigint.md | 259 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 379 insertions(+)

diff --git a/stdlib/bigint.gr b/stdlib/bigint.gr
index 3c717bc4c2..4ac1fcdbcd 100644
--- a/stdlib/bigint.gr
+++ b/stdlib/bigint.gr
@@ -3,6 +3,10 @@
  *
  * @example include "bigint"
  *
+ * @example 9223372036854775809t
+ * @example 0t
+ * @example -9223372036854775809t
+ *
  * @since v0.5.0
  */
 
@@ -27,6 +31,9 @@ provide { fromNumber, toNumber }
  * @param num: The value to increment
  * @returns The incremented value
  *
+ * @example BigInt.incr(1t) == 2t
+ * @example BigInt.incr(-2t) == -1t
+ *
  * @since v0.5.0
  */
 @unsafe
@@ -40,6 +47,9 @@ provide let incr = (num: BigInt) => {
  * @param num: The value to decrement
  * @returns The decremented value
  *
+ * @example BigInt.decr(2t) == 1t
+ * @example BigInt.decr(-2t) == -3t
+ *
  * @since v0.5.0
  */
 @unsafe
@@ -53,6 +63,9 @@ provide let decr = (num: BigInt) => {
  * @param num: The operand
  * @returns The negated operand
  *
+ * @example BigInt.neg(1t) == -1t
+ * @example BigInt.neg(-1t) == 1t
+ *
  * @since v0.5.0
  */
 @unsafe
@@ -66,6 +79,9 @@ provide let neg = (num: BigInt) => {
  * @param num: The operand
  * @returns The operand's absolute value
  *
+ * @example BigInt.abs(1t) == 1t
+ * @example BigInt.abs(-1t) == 1t
+ *
  * @since v0.5.0
  */
 @unsafe
@@ -80,6 +96,10 @@ provide let abs = (num: BigInt) => {
  * @param num2: The second operand
  * @returns The sum of the two operands
  *
+ * @example
+ * from BigInt use { (+) }
+ * assert 1t + 1t == 2t
+ *
  * @since v0.6.0
  * @history v0.5.0: Originally named `add`
  */
@@ -97,6 +117,10 @@ provide let (+) = (num1: BigInt, num2: BigInt) => {
  * @param num2: The second operand
  * @returns The difference of the two operands
  *
+ * @example
+ * from BigInt use { (-) }
+ * assert 3t - 1t == 2t
+ *
  * @since v0.6.0
  * @history v0.5.0: Originally named `sub`
  */
@@ -114,6 +138,10 @@ provide let (-) = (num1: BigInt, num2: BigInt) => {
  * @param num2: The second operand
  * @returns The product of the two operands
  *
+ * @example
+ * from BigInt use { (*) }
+ * assert 3t * 3t == 9t
+ *
  * @since v0.6.0
  * @history v0.5.0: Originally named `mul`
  */
@@ -134,6 +162,10 @@ provide let (*) = (num1: BigInt, num2: BigInt) => {
  * @param num2: The second operand
  * @returns The quotient of its operands
  *
+ * @example
+ * from BigInt use { (/) }
+ * assert 9t / 3t == 3t
+ *
  * @since v0.6.0
  * @history v0.5.0: Originally named `div`
  */
@@ -152,6 +184,8 @@ provide let (/) = (num1: BigInt, num2: BigInt) => {
  * @param num2: The second operand
  * @returns The remainder of its operands
  *
+ * @example BigInt.rem(3t, 2t) == 1t
+ *
  * @since v0.5.0
  */
 @unsafe
@@ -168,6 +202,8 @@ provide let rem = (num1: BigInt, num2: BigInt) => {
  * @param num2: The second operand
  * @returns The quotient and remainder of its operands
  *
+ * @example BigInt.quotRem(7t, 2t) == (3t, 1t))
+ *
  * @since v0.5.0
  */
 @unsafe
@@ -187,6 +223,8 @@ provide let quotRem = (num1: BigInt, num2: BigInt) => {
  * @param num2: The second operand
  * @returns The greatest common divisor of its operands
  *
+ * @example BigInt.gcd(36t, 24t) == 12t
+ *
  * @since v0.5.0
  */
 @unsafe
@@ -203,6 +241,10 @@ provide let gcd = (num1: BigInt, num2: BigInt) => {
  * @param places: The number of bits to shift by
  * @returns The shifted value
  *
+ * @example
+ * from BigInt use { (<<) }
+ * assert (10t << 2l) == 40t
+ *
  * @since v0.6.0
  * @history v0.5.0: Originally named `shl`
  */
@@ -220,6 +262,10 @@ provide let (<<) = (num: BigInt, places: Int32) => {
  * @param places: The amount to shift by
  * @returns The shifted value
  *
+ * @example
+ * from BigInt use { (>>) }
+ * assert (9999t >> 2l) == 2499t
+ *
  * @since v0.6.0
  * @history v0.5.0: Originally named `shr`
  */
@@ -236,6 +282,9 @@ provide let (>>) = (num: BigInt, places: Int32) => {
  * @param num: The value to inspect
  * @returns `true` if the first value is equal to zero or `false` otherwise
  *
+ * @example assert BigInt.eqz(0t) == true
+ * @example assert BigInt.eqz(1t) == false
+ *
  * @since v0.5.0
  */
 @unsafe
@@ -252,6 +301,13 @@ provide let eqz = (num: BigInt) => {
  * @param num2: The second value
  * @returns `true` if the first value is equal to the second value or `false` otherwise
  *
+ * @example
+ * from BigInt use { (==) }
+ * assert 1t == 1t
+ * @example
+ * from BigInt use { (==) }
+ * assert -10t == -10t
+ *
  * @since v0.6.0
  * @history v0.5.0: Originally named `eq`
  */
@@ -270,6 +326,13 @@ provide let (==) = (num1: BigInt, num2: BigInt) => {
  * @param num2: The second value
  * @returns `true` if the first value is not equal to the second value or `false` otherwise
  *
+ * @example
+ * from BigInt use { (!=) }
+ * assert 1t != 2t
+ * @example
+ * from BigInt use { (!=) }
+ * assert -10t != -20t
+ *
  * @since v0.6.0
  * @history v0.5.0: Originally named `ne`
  */
@@ -288,6 +351,13 @@ provide let (!=) = (num1: BigInt, num2: BigInt) => {
  * @param num2: The second value
  * @returns `true` if the first value is less than the second value or `false` otherwise
  *
+ * @example
+ * from BigInt use { (<) }
+ * assert 1t < 2t
+ * @example
+ * from BigInt use { (<) }
+ * assert -10t < 0t
+ *
  * @since v0.6.0
  * @history v0.5.0: Originally named `lt`
  */
@@ -306,6 +376,16 @@ provide let (<) = (num1: BigInt, num2: BigInt) => {
  * @param num2: The second value
  * @returns `true` if the first value is less than or equal to the second value or `false` otherwise
  *
+ * @example
+ * from BigInt use { (<=) }
+ * assert 1t <= 1t
+ * @example
+ * from BigInt use { (<=) }
+ * assert -10t <= 0t
+ * @example
+ * from BigInt use { (<=) }
+ * assert 2t <= 3t
+ *
  * @since v0.6.0
  * @history v0.5.0: Originally named `lte`
  */
@@ -324,6 +404,13 @@ provide let (<=) = (num1: BigInt, num2: BigInt) => {
  * @param num2: The second value
  * @returns `true` if the first value is greater than the second value or `false` otherwise
  *
+ * @example
+ * from BigInt use { (>) }
+ * assert 2t > 1t
+ * @example
+ * from BigInt use { (>) }
+ * assert 0t > -10t
+ *
  * @since v0.6.0
  * @history v0.5.0: Originally named `gt`
  */
@@ -342,6 +429,16 @@ provide let (>) = (num1: BigInt, num2: BigInt) => {
  * @param num2: The second value
  * @returns `true` if the first value is greater than or equal to the second value or `false` otherwise
  *
+ * @example
+ * from BigInt use { (>=) }
+ * assert 1t >= 1t
+ * @example
+ * from BigInt use { (>=) }
+ * assert 0t >= -10t
+ * @example
+ * from BigInt use { (>=) }
+ * assert 3t >= 2t
+ *
  * @since v0.6.0
  * @history v0.5.0: Originally named `gte`
  */
@@ -359,6 +456,8 @@ provide let (>=) = (num1: BigInt, num2: BigInt) => {
  * @param num: The given value
  * @returns Containing the inverted bits of the given value
  *
+ * @example BigInt.lnot(91234t) == -91235t
+ *
  * @since v0.5.0
  */
 @unsafe
@@ -373,6 +472,10 @@ provide let lnot = (num: BigInt) => {
  * @param num2: The second operand
  * @returns Containing a `1` in each bit position for which the corresponding bits of both operands are `1`
  *
+ * @example
+ * from BigInt use { (&) }
+ * assert (4t & 3t) == 0t
+ *
  * @since v0.6.0
  * @history v0.5.0: Originally named `land`
  */
@@ -390,6 +493,10 @@ provide let (&) = (num1: BigInt, num2: BigInt) => {
  * @param num2: The second operand
  * @returns Containing a `1` in each bit position for which the corresponding bits of either or both operands are `1`
  *
+ * @example
+ * from BigInt use { (|) }
+ * assert (5t | 3t) == 7t
+ *
  * @since v0.6.0
  * @history v0.5.0: Originally named `lor`
  */
@@ -407,6 +514,10 @@ provide let (|) = (num1: BigInt, num2: BigInt) => {
  * @param num2: The second operand
  * @returns Containing a `1` in each bit position for which the corresponding bits of either but not both operands are `1`
  *
+ * @example
+ * from BigInt use { (^) }
+ * assert (5t ^ 3t) == 6t
+ *
  * @since v0.6.0
  * @history v0.5.0: Originally named `lxor`
  */
@@ -424,6 +535,8 @@ provide let (^) = (num1: BigInt, num2: BigInt) => {
  * @param num: The value to inspect
  * @returns The amount of leading zeros
  *
+ * @example BigInt.clz(5t) == 2147483647t
+ *
  * @since v0.5.0
  */
 @unsafe
@@ -439,6 +552,8 @@ provide let clz = (num: BigInt) => {
  * @param num: The value to inspect
  * @returns The amount of trailing zeros
  *
+ * @example BigInt.ctz(14t) == 1t
+ *
  * @since v0.5.0
  */
 @unsafe
@@ -455,6 +570,8 @@ provide let ctz = (num: BigInt) => {
  * @param num: The value to inspect
  * @returns The amount of 1-bits in its operand
  *
+ * @example BigInt.popcnt(14t) == 1t
+ *
  * @since v0.5.0
  */
 @unsafe
@@ -475,6 +592,9 @@ provide let popcnt = (num: BigInt) => {
  * @param num: The operand
  * @returns The operand, as a string
  *
+ * @example BigInt.toString(1t) == "1"
+ * @example BigInt.toString(-1t) == "-1"
+ *
  * @since v0.5.0
  */
 @unsafe
diff --git a/stdlib/bigint.md b/stdlib/bigint.md
index 381ace81c5..b76fe39b0b 100644
--- a/stdlib/bigint.md
+++ b/stdlib/bigint.md
@@ -13,6 +13,18 @@ No other changes yet.
 include "bigint"
 ```
 
+```grain
+9223372036854775809t
+```
+
+```grain
+0t
+```
+
+```grain
+-9223372036854775809t
+```
+
 ## Values
 
 Functions and constants included in the BigInt module.
@@ -92,6 +104,16 @@ Returns:
 |----|-----------|
 |`BigInt`|The incremented value|
 
+Examples:
+
+```grain
+BigInt.incr(1t) == 2t
+```
+
+```grain
+BigInt.incr(-2t) == -1t
+```
+
 ### BigInt.**decr**
 
 <details disabled>
@@ -117,6 +139,16 @@ Returns:
 |----|-----------|
 |`BigInt`|The decremented value|
 
+Examples:
+
+```grain
+BigInt.decr(2t) == 1t
+```
+
+```grain
+BigInt.decr(-2t) == -3t
+```
+
 ### BigInt.**neg**
 
 <details disabled>
@@ -142,6 +174,16 @@ Returns:
 |----|-----------|
 |`BigInt`|The negated operand|
 
+Examples:
+
+```grain
+BigInt.neg(1t) == -1t
+```
+
+```grain
+BigInt.neg(-1t) == 1t
+```
+
 ### BigInt.**abs**
 
 <details disabled>
@@ -167,6 +209,16 @@ Returns:
 |----|-----------|
 |`BigInt`|The operand's absolute value|
 
+Examples:
+
+```grain
+BigInt.abs(1t) == 1t
+```
+
+```grain
+BigInt.abs(-1t) == 1t
+```
+
 ### BigInt.**(+)**
 
 <details>
@@ -200,6 +252,13 @@ Returns:
 |----|-----------|
 |`BigInt`|The sum of the two operands|
 
+Examples:
+
+```grain
+from BigInt use { (+) }
+assert 1t + 1t == 2t
+```
+
 ### BigInt.**(-)**
 
 <details>
@@ -233,6 +292,13 @@ Returns:
 |----|-----------|
 |`BigInt`|The difference of the two operands|
 
+Examples:
+
+```grain
+from BigInt use { (-) }
+assert 3t - 1t == 2t
+```
+
 ### BigInt.**(*)**
 
 <details>
@@ -266,6 +332,13 @@ Returns:
 |----|-----------|
 |`BigInt`|The product of the two operands|
 
+Examples:
+
+```grain
+from BigInt use { (*) }
+assert 3t * 3t == 9t
+```
+
 ### BigInt.**(/)**
 
 <details>
@@ -300,6 +373,13 @@ Returns:
 |----|-----------|
 |`BigInt`|The quotient of its operands|
 
+Examples:
+
+```grain
+from BigInt use { (/) }
+assert 9t / 3t == 3t
+```
+
 ### BigInt.**rem**
 
 <details disabled>
@@ -327,6 +407,12 @@ Returns:
 |----|-----------|
 |`BigInt`|The remainder of its operands|
 
+Examples:
+
+```grain
+BigInt.rem(3t, 2t) == 1t
+```
+
 ### BigInt.**quotRem**
 
 <details disabled>
@@ -353,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>
@@ -379,6 +471,12 @@ Returns:
 |----|-----------|
 |`BigInt`|The greatest common divisor of its operands|
 
+Examples:
+
+```grain
+BigInt.gcd(36t, 24t) == 12t
+```
+
 ### BigInt.**(<<)**
 
 <details>
@@ -412,6 +510,13 @@ Returns:
 |----|-----------|
 |`BigInt`|The shifted value|
 
+Examples:
+
+```grain
+from BigInt use { (<<) }
+assert (10t << 2l) == 40t
+```
+
 ### BigInt.**(>>)**
 
 <details>
@@ -445,6 +550,13 @@ Returns:
 |----|-----------|
 |`BigInt`|The shifted value|
 
+Examples:
+
+```grain
+from BigInt use { (>>) }
+assert (9999t >> 2l) == 2499t
+```
+
 ### BigInt.**eqz**
 
 <details disabled>
@@ -470,6 +582,16 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is equal to zero or `false` otherwise|
 
+Examples:
+
+```grain
+assert BigInt.eqz(0t) == true
+```
+
+```grain
+assert BigInt.eqz(1t) == false
+```
+
 ### BigInt.**(==)**
 
 <details>
@@ -503,6 +625,18 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is equal to the second value or `false` otherwise|
 
+Examples:
+
+```grain
+from BigInt use { (==) }
+assert 1t == 1t
+```
+
+```grain
+from BigInt use { (==) }
+assert -10t == -10t
+```
+
 ### BigInt.**(!=)**
 
 <details>
@@ -536,6 +670,18 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is not equal to the second value or `false` otherwise|
 
+Examples:
+
+```grain
+from BigInt use { (!=) }
+assert 1t != 2t
+```
+
+```grain
+from BigInt use { (!=) }
+assert -10t != -20t
+```
+
 ### BigInt.**(<)**
 
 <details>
@@ -569,6 +715,18 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is less than the second value or `false` otherwise|
 
+Examples:
+
+```grain
+from BigInt use { (<) }
+assert 1t < 2t
+```
+
+```grain
+from BigInt use { (<) }
+assert -10t < 0t
+```
+
 ### BigInt.**(<=)**
 
 <details>
@@ -602,6 +760,23 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is less than or equal to the second value or `false` otherwise|
 
+Examples:
+
+```grain
+from BigInt use { (<=) }
+assert 1t <= 1t
+```
+
+```grain
+from BigInt use { (<=) }
+assert -10t <= 0t
+```
+
+```grain
+from BigInt use { (<=) }
+assert 2t <= 3t
+```
+
 ### BigInt.**(>)**
 
 <details>
@@ -635,6 +810,18 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is greater than the second value or `false` otherwise|
 
+Examples:
+
+```grain
+from BigInt use { (>) }
+assert 2t > 1t
+```
+
+```grain
+from BigInt use { (>) }
+assert 0t > -10t
+```
+
 ### BigInt.**(>=)**
 
 <details>
@@ -668,6 +855,23 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is greater than or equal to the second value or `false` otherwise|
 
+Examples:
+
+```grain
+from BigInt use { (>=) }
+assert 1t >= 1t
+```
+
+```grain
+from BigInt use { (>=) }
+assert 0t >= -10t
+```
+
+```grain
+from BigInt use { (>=) }
+assert 3t >= 2t
+```
+
 ### BigInt.**lnot**
 
 <details disabled>
@@ -693,6 +897,12 @@ Returns:
 |----|-----------|
 |`BigInt`|Containing the inverted bits of the given value|
 
+Examples:
+
+```grain
+BigInt.lnot(91234t) == -91235t
+```
+
 ### BigInt.**(&)**
 
 <details>
@@ -726,6 +936,13 @@ Returns:
 |----|-----------|
 |`BigInt`|Containing a `1` in each bit position for which the corresponding bits of both operands are `1`|
 
+Examples:
+
+```grain
+from BigInt use { (&) }
+assert (4t & 3t) == 0t
+```
+
 ### BigInt.**(|)**
 
 <details>
@@ -759,6 +976,13 @@ Returns:
 |----|-----------|
 |`BigInt`|Containing a `1` in each bit position for which the corresponding bits of either or both operands are `1`|
 
+Examples:
+
+```grain
+from BigInt use { (|) }
+assert (5t | 3t) == 7t
+```
+
 ### BigInt.**(^)**
 
 <details>
@@ -792,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
+from BigInt use { (^) }
+assert (5t ^ 3t) == 6t
+```
+
 ### BigInt.**clz**
 
 <details disabled>
@@ -818,6 +1049,12 @@ Returns:
 |----|-----------|
 |`Int32`|The amount of leading zeros|
 
+Examples:
+
+```grain
+BigInt.clz(5t) == 2147483647t
+```
+
 ### BigInt.**ctz**
 
 <details disabled>
@@ -843,6 +1080,12 @@ Returns:
 |----|-----------|
 |`Int64`|The amount of trailing zeros|
 
+Examples:
+
+```grain
+BigInt.ctz(14t) == 1t
+```
+
 ### BigInt.**popcnt**
 
 <details disabled>
@@ -869,6 +1112,12 @@ Returns:
 |----|-----------|
 |`Option<Int64>`|The amount of 1-bits in its operand|
 
+Examples:
+
+```grain
+BigInt.popcnt(14t) == 1t
+```
+
 ### BigInt.**toString**
 
 <details disabled>
@@ -894,3 +1143,13 @@ Returns:
 |----|-----------|
 |`String`|The operand, as a string|
 
+Examples:
+
+```grain
+BigInt.toString(1t) == "1"
+```
+
+```grain
+BigInt.toString(-1t) == "-1"
+```
+