BIGNUM support

Author: braindigitalis

docpages/basic-language-reference/functions/integer/02_INDEX.md

@@ -4,6 +4,7 @@ The following functions operate on or return **integer values** in Retro Rocket
 
 * \subpage ABS
 * \subpage ASC
+* \subpage BIGCMP
 * \subpage BITAND
 * \subpage BITEOR
 * \subpage BITNAND

docpages/basic-language-reference/functions/integer/BIGCMP.md

@@ -0,0 +1,47 @@
+\page BIGCMP BIGCMP Function
+
+```basic
+BIGCMP(string-expression, string-expression)
+```
+
+Compares two **arbitrary precision integers** provided as **decimal strings**.
+
+---
+
+### Examples
+
+```basic
+PRINT BIGCMP("100", "50")
+```
+
+Produces `1`.
+
+```basic
+PRINT BIGCMP("42", "42")
+```
+
+Produces `0`.
+
+```basic
+PRINT BIGCMP("-10", "5")
+```
+
+Produces `-1`.
+
+---
+
+### Notes
+
+* Inputs must be valid base-10 integer strings.
+* Returns:
+
+  * `1` if first value is greater than second
+  * `0` if both values are equal
+  * `-1` if first value is less than second
+* Supports values far beyond 64-bit limits.
+* Negative numbers are supported.
+
+---
+
+**See also:**
+\ref BIGADDS "BIGADD$" · \ref BIGSUBS "BIGSUB$" · \ref BIGMULS "BIGMUL$" · \ref BIGDIVS "BIGDIV$" · \ref BIGMODS "BIGMOD$"

docpages/basic-language-reference/functions/string/04_INDEX.md

@@ -3,6 +3,18 @@
 The following functions return or manipulate **string values** in Retro Rocket BASIC.
 
 * \subpage ADFSIMAGE
+* \subpage BIGABSS
+* \subpage BIGADDS
+* \subpage BIGDIVS
+* \subpage BIGGCDS
+* \subpage BIGMODINVS
+* \subpage BIGMODPOWS
+* \subpage BIGMODS
+* \subpage BIGMULS
+* \subpage BIGNEGS
+* \subpage BIGSHLS
+* \subpage BIGSHRS
+* \subpage BIGSUBS
 * \subpage BOOL
 * \subpage BUFFERTOSTRINGS
 * \subpage CHR

docpages/basic-language-reference/functions/string/BIGABSS.md

@@ -0,0 +1,43 @@
+\page BIGABSS BIGABS$ Function
+
+```basic
+BIGABS$(string-expression)
+```
+
+Returns the **absolute value** of an **arbitrary precision integer** provided as a decimal string.
+
+---
+
+### Examples
+
+```basic
+PRINT BIGABS$("-12345678901234567890")
+```
+
+Produces `"12345678901234567890"`.
+
+```basic
+PRINT BIGABS$("42")
+```
+
+Produces `"42"`.
+
+```basic
+PRINT BIGABS$("0")
+```
+
+Produces `"0"`.
+
+---
+
+### Notes
+
+* Input must be a valid base-10 integer string.
+* Negative values are converted to positive.
+* Zero and positive values are returned unchanged.
+* Result is returned as a decimal string.
+
+---
+
+**See also:**
+\ref BIGNEGS "BIGNEG$" · \ref BIGADDS "BIGADD$" · \ref BIGSUBS "BIGSUB$" · \ref BIGCMP "BIGCMP"

docpages/basic-language-reference/functions/string/BIGADDS.md

@@ -0,0 +1,44 @@
+\page BIGADDS BIGADD$ Function
+
+```basic
+BIGADD$(string-expression, string-expression)
+```
+
+Adds two **arbitrary precision integers** provided as **decimal strings**, returning the result as a string.
+
+---
+
+### Examples
+
+```basic
+PRINT BIGADD$("12345678901234567890", "1")
+```
+
+Produces `"12345678901234567891"`.
+
+```basic
+PRINT BIGADD$("99999999999999999999", "1")
+```
+
+Produces `"100000000000000000000"`.
+
+```basic
+PRINT BIGADD$("-50", "25")
+```
+
+Produces `"-25"`.
+
+---
+
+### Notes
+
+* Inputs must be valid base-10 integer strings.
+* Supports values far beyond 64-bit limits.
+* Negative numbers are supported.
+* Result is returned as a decimal string.
+* Leading zeros in input are ignored.
+
+---
+
+**See also:**
+\ref BIGSUBS "BIGSUB$" · \ref BIGMULS "BIGMUL$" · \ref BIGDIVS "BIGDIV$" · \ref BIGMODS "BIGMOD$" · \ref BIGCMP "BIGCMP"

docpages/basic-language-reference/functions/string/BIGDIVS.md

@@ -0,0 +1,44 @@
+\page BIGDIVS BIGDIV$ Function
+
+```basic
+BIGDIV$(string-expression, string-expression)
+```
+
+Divides one **arbitrary precision integer** (as a decimal string) by another, returning the **quotient** as a string.
+
+---
+
+### Examples
+
+```basic
+PRINT BIGDIV$("100000000000000000000", "10")
+```
+
+Produces `"10000000000000000000"`.
+
+```basic
+PRINT BIGDIV$("7", "2")
+```
+
+Produces `"3"`.
+
+```basic
+PRINT BIGDIV$("-100", "4")
+```
+
+Produces `"-25"`.
+
+---
+
+### Notes
+
+* Inputs must be valid base-10 integer strings.
+* Division is integer division (fractional part is discarded).
+* Division by zero produces an error.
+* Negative numbers are supported.
+* Result is returned as a decimal string.
+
+---
+
+**See also:**
+\ref BIGMODS "BIGMOD$" · \ref BIGADDS "BIGADD$" · \ref BIGSUBS "BIGSUB$" · \ref BIGMULS "BIGMUL$" · \ref BIGCMP "BIGCMP"

docpages/basic-language-reference/functions/string/BIGGCDS.md

@@ -0,0 +1,43 @@
+\page BIGGCDS BIGGCD$ Function
+
+```basic
+BIGGCD$(string-expression, string-expression)
+```
+
+Calculates the **greatest common divisor (GCD)** of two **arbitrary precision integers** provided as decimal strings, returning the result as a string.
+
+---
+
+### Examples
+
+```basic
+PRINT BIGGCD$("48", "18")
+```
+
+Produces `"6"`.
+
+```basic
+PRINT BIGGCD$("12345678901234567890", "9876543210")
+```
+
+Produces `"90"`.
+
+```basic
+PRINT BIGGCD$("-42", "56")
+```
+
+Produces `"14"`.
+
+---
+
+### Notes
+
+* Inputs must be valid base-10 integer strings.
+* Negative values are treated by magnitude (the result is always non-negative).
+* If both inputs are zero, the result is `"0"`.
+* Result is returned as a decimal string.
+
+---
+
+**See also:**
+\ref BIGADDS "BIGADD$" · \ref BIGSUBS "BIGSUB$" · \ref BIGMULS "BIGMUL$" · \ref BIGDIVS "BIGDIV$" · \ref BIGMODS "BIGMOD$" · \ref BIGCMP "BIGCMP"

docpages/basic-language-reference/functions/string/BIGMODINVS.md

@@ -0,0 +1,47 @@
+\page BIGMODINVS BIGMODINV$ Function
+
+```basic
+BIGMODINV$(string-expression, string-expression)
+```
+
+Computes the **modular multiplicative inverse** of an **arbitrary precision integer**.
+Returns a value (X) such that:
+
+```
+(A * X) MOD M = 1
+```
+
+---
+
+### Examples
+
+```basic
+PRINT BIGMODINV$("3", "11")
+```
+
+Produces `"4"`.
+
+```basic
+PRINT BIGMODINV$("10", "17")
+```
+
+Produces `"12"`.
+
+```
+(10 * 12) MOD 17 = 1
+```
+
+---
+
+### Notes
+
+* Inputs must be valid base-10 integer strings.
+* The inverse exists only if `A` and `M` are coprime.
+* If no inverse exists, an error is produced.
+* Modulus must be non-zero.
+* Result is returned as a decimal string.
+
+---
+
+**See also:**
+\ref BIGMODPOWS "BIGMODPOW$" · \ref BIGMODS "BIGMOD$" · \ref BIGGCDS "BIGGCD$" · \ref BIGMULS "BIGMUL$"

docpages/basic-language-reference/functions/string/BIGMODPOWS.md

@@ -0,0 +1,46 @@
+\page BIGMODPOWS BIGMODPOW$ Function
+
+```basic
+BIGMODPOW$(string-expression, string-expression, string-expression)
+```
+
+Computes **modular exponentiation** on **arbitrary precision integers**, returning
+((A^E) \bmod M) as a string.
+
+---
+
+### Examples
+
+```basic
+PRINT BIGMODPOW$("2", "10", "1000")
+```
+
+Produces `"24"`.
+
+```basic
+PRINT BIGMODPOW$("5", "3", "13")
+```
+
+Produces `"8"`.
+
+```basic
+PRINT BIGMODPOW$("123456789", "2", "100000")
+```
+
+Produces `"521"`.
+
+---
+
+### Notes
+
+* All inputs must be valid base-10 integer strings.
+* Efficient for large values (uses modular exponentiation, not naive power).
+* Modulus must be non-zero.
+* Negative bases are supported; exponent must be non-negative.
+* Result is always in the range `0` to `M-1`.
+* Result is returned as a decimal string.
+
+---
+
+**See also:**
+\ref BIGMODINVS "BIGMODINV$" · \ref BIGMODS "BIGMOD$" · \ref BIGMULS "BIGMUL$" · \ref BIGADDS "BIGADD$"

docpages/basic-language-reference/functions/string/BIGMODS.md

@@ -0,0 +1,43 @@
+\page BIGMODS BIGMOD$ Function
+
+```basic
+BIGMOD$(string-expression, string-expression)
+```
+
+Calculates the **remainder** of dividing one **arbitrary precision integer** (as a decimal string) by another, returning the result as a string.
+
+---
+
+### Examples
+
+```basic
+PRINT BIGMOD$("10", "3")
+```
+
+Produces `"1"`.
+
+```basic
+PRINT BIGMOD$("100000000000000000000", "7")
+```
+
+Produces `"2"`.
+
+```basic
+PRINT BIGMOD$("-10", "3")
+```
+
+Produces `"-1"`.
+
+---
+
+### Notes
+
+* Inputs must be valid base-10 integer strings.
+* Division by zero produces an error.
+* The result follows the sign of the dividend.
+* Result is returned as a decimal string.
+
+---
+
+**See also:**
+\ref BIGDIVS "BIGDIV$" · \ref BIGADDS "BIGADD$" · \ref BIGSUBS "BIGSUB$" · \ref BIGMULS "BIGMUL$" · \ref BIGCMP "BIGCMP"