BigInteger
Represents an arbitrary-precision signed integer.
A BigInteger object can represent any integer value that fits in available memory. It supports arithmetic, comparison, conversion, and bitwise operations while preserving exact integer precision.
Constructor
BigInteger(value: ( BigInteger | string | integer | nil ), base: ( integer | nil )): BigInteger
Fields
| Name | Type | Description |
|---|
limbs | integer[] | The magnitude as little-endian 16-bit limbs, limbs[ 0 ] is the limb count. |
sign | boolean | |
Operators
Static functions
function BigInteger.fromBytes(signed: boolean, ...: integer): BigInteger
Creates a new BigInteger from the given bytes.
The bytes are interpreted in big-endian order (most significant byte first). If signed is true, the resulting value is interpreted as a signed two's-complement integer.
Parameters
| Name | Type | Description |
|---|
signed | boolean | Whether the byte sequence represents a signed integer. |
... | integer | The bytes of the integer, each in the range 0–255. |
Returns
Methods
abs | Makes a big integer object absolute (simply removes the sign). |
add | Summarizes the current BigInteger with the specified value. |
band | Performs a bitwise AND operation between two big integer objects. |
bnot | Performs a bitwise NOT operation on a big integer object. |
bor | Performs a bitwise OR operation between two big integer objects. |
bxor | Performs a bitwise XOR operation between two big integer objects. |
compare | Compares the BigInteger with the given value. |
copy | Makes a copy of the BigInteger object. |
div | Divides the current BigInteger with the specified value. |
fromBytes | Replaces the contents of this BigInteger with the given bytes. |
fromInteger | Sets a BigInteger object from Lua integer. |
fromString | Sets a BigInteger object from a decimal string. |
isEven | Checks if a big integer object is even. |
isOdd | Checks if a big integer object is odd. |
isPowerOfTwo | Checks if BigInteger is a power of two. |
isZero | Checks if a big integer object is zero/empty. |
log2 | Returns the log2 of a big integer object. |
lshift | Shifts a big integer object to the left by a given number of bits (positive or negative). |
mod | Calculates modulus (remainder after division); |
mul | Multiplies the current BigInteger by the specified value. |
negate | Negates a big integer object. |
pow | Raises a big integer object to a power. |
rshift | Shifts a big integer object to the right by a given number of bits (positive or negative). |
sub | Subtract the current BigInteger by the specified value. |
toBinaryString | Converts the big integer to a binary [01] string. |
toHexString | Converts the big integer into a hex string. |
toInteger | Converts a big integer object to a lua_number (always an integer). |
toSigned | Converts unsigned BigInteger to signed one. |
toString | Converts the big integer to a string in the specified (or not) base. |
toUnsigned | Converts signed BigInteger to unsigned one. |
function BigInteger:abs(): BigInteger
Makes a big integer object absolute (simply removes the sign).
Returns
| Type | Name | Description |
|---|
BigInteger | self | The absolute big integer object. |
function BigInteger:add(value: any): BigInteger
Summarizes the current BigInteger with the specified value.
Parameters
| Name | Type | Description |
|---|
value | any | The second value to be converted into BigInteger. |
Returns
| Type | Name | Description |
|---|
BigInteger | object | The result of the operation. |
function BigInteger:band(value: any): BigInteger
Performs a bitwise AND operation between two big integer objects.
Parameters
| Name | Type | Description |
|---|
value | any | The value to perform the operation on. |
Returns
| Type | Name | Description |
|---|
BigInteger | new_object | The result of the operation. |
function BigInteger:bnot(): BigInteger
Performs a bitwise NOT operation on a big integer object.
Returns
| Type | Name | Description |
|---|
BigInteger | object | The result of the operation. |
function BigInteger:bor(value: any): BigInteger
Performs a bitwise OR operation between two big integer objects.
Parameters
| Name | Type | Description |
|---|
value | any | The value to perform the operation on. |
Returns
| Type | Name | Description |
|---|
BigInteger | object | The result of the operation. |
function BigInteger:bxor(value: any): BigInteger
Performs a bitwise XOR operation between two big integer objects.
Parameters
| Name | Type | Description |
|---|
value | any | The value to perform the operation on. |
Returns
| Type | Name | Description |
|---|
BigInteger | object | The result of the operation. |
function BigInteger:compare(value: any): `-1` | `0` | `1`
Compares the BigInteger with the given value.
Unlike the ==, < and <= operators, this also works with plain Lua numbers and strings.
Parameters
| Name | Type | Description |
|---|
value | any | The value to compare with (will be converted into BigInteger). |
Returns
| Type | Name | Description |
|---|
`-1` | `0` | `1` | result | -1 if self < value, 0 if equal, 1 if self > value. |
function BigInteger:div(value: any): BigInteger, BigInteger
Divides the current BigInteger with the specified value.
Parameters
| Name | Type | Description |
|---|
value | any | The second value to divide by (will be converted into BigInteger). |
Returns
function BigInteger:fromBytes(signed: boolean, ...: integer): BigInteger
Replaces the contents of this BigInteger with the given bytes.
The bytes are interpreted in big-endian order (most significant byte first). If signed is true, the resulting value is interpreted as a signed two's-complement integer.
Parameters
| Name | Type | Description |
|---|
signed | boolean | Whether the byte sequence represents a signed integer. |
... | integer | The bytes to store, each in the range 0–255. |
Returns
function BigInteger:fromInteger(value: integer): BigInteger
Parameters
| Name | Type | Description |
|---|
value | integer | The number to convert. |
Returns
function BigInteger:fromString(str: string, base?: integer, start_position?: integer, end_position?: integer): BigInteger
Parameters
| Name | Type | Description |
|---|
str | string | The string representation of the big integer. |
baseoptional | integer | The numerical base of the digits in the input value. Can be any integer between 2 and 36, inclusive. By default: 10 |
start_positionoptional | integer | The start position to read from. |
end_positionoptional | integer | The end position to read to. |
Returns
function BigInteger:isEven(): boolean
Checks if a big integer object is even.
Returns
| Type | Name | Description |
|---|
boolean | result | true if the big integer object is even, false otherwise. |
function BigInteger:isOdd(): boolean
Checks if a big integer object is odd.
Returns
| Type | Name | Description |
|---|
boolean | | true if the big integer object is odd, false otherwise. |
function BigInteger:isPowerOfTwo(): boolean
Returns
| Type | Name | Description |
|---|
boolean | is_pot | true if a number is a valid power-of-two, otherwise false. |
function BigInteger:isZero(): boolean
Checks if a big integer object is zero/empty.
Returns
| Type | Name | Description |
|---|
boolean | is_zero | true if the big integer object is zero/empty, false otherwise. |
function BigInteger:log2(): number
Returns the log2 of a big integer object.
Returns
| Type | Name | Description |
|---|
number | result | The base-2 logarithm of the big integer object. NaN for negative values, -inf for zero. |
function BigInteger:lshift(shift: integer): BigInteger
Shifts a big integer object to the left by a given number of bits (positive or negative).
Parameters
| Name | Type | Description |
|---|
shift | integer | The number of bits to shift by. |
Returns
| Type | Name | Description |
|---|
BigInteger | object | The shifted big integer object. |
function BigInteger:mod(value: any): BigInteger
Calculates modulus (remainder after division);
Handles Lua-to-BigInteger conversions and non-positive cases correctly.
Parameters
| Name | Type | Description |
|---|
value | any | The value to divide by. |
Returns
| Type | Name | Description |
|---|
BigInteger | remainder | The remainder (same sign as self, or zero). |
function BigInteger:mul(value: any): BigInteger
Multiplies the current BigInteger by the specified value.
Parameters
| Name | Type | Description |
|---|
value | any | The second value to be converted into BigInteger. |
Returns
| Type | Name | Description |
|---|
BigInteger | object | The result of the operation. |
function BigInteger:negate(): BigInteger
Negates a big integer object.
Returns
| Type | Name | Description |
|---|
BigInteger | self | The negated big integer object. |
function BigInteger:pow(value: integer): BigInteger
Raises a big integer object to a power.
Parameters
| Name | Type | Description |
|---|
value | integer | The value to raise to. |
Returns
| Type | Name | Description |
|---|
BigInteger | self | The result of the operation. |
function BigInteger:rshift(shift: integer): BigInteger
Shifts a big integer object to the right by a given number of bits (positive or negative).
Parameters
| Name | Type | Description |
|---|
shift | integer | The number of bits to shift by. |
Returns
| Type | Name | Description |
|---|
BigInteger | object | The shifted big integer object. |
function BigInteger:sub(value: any): BigInteger
Subtract the current BigInteger by the specified value.
Parameters
| Name | Type | Description |
|---|
value | any | The second value to be converted into BigInteger. |
Returns
| Type | Name | Description |
|---|
BigInteger | object | The result of the operation. |
#BigInteger:toBinaryString
function BigInteger:toBinaryString(): string
Converts the big integer to a binary [01] string.
The output is zero-padded to a whole number of bytes.
Returns
| Type | Name | Description |
|---|
string | str | The binary string representation of the big integer. |
function BigInteger:toHexString(): string
Converts the big integer into a hex string.
Returns
| Type | Name | Description |
|---|
string | hex_str | The hex string representation of the big integer. |
function BigInteger:toInteger(): integer
Converts a big integer object to a lua_number (always an integer).
Returns
| Type | Name | Description |
|---|
integer | value | The number that the big integer object represents. |
function BigInteger:toSigned(byte_width: integer): BigInteger
Parameters
| Name | Type | Description |
|---|
byte_width | integer | The byte width to interpret the raw magnitude at (e.g. 1 for int8, 4 for int32). |
Returns
| Type | Name | Description |
|---|
BigInteger | object | Self, reinterpreted as a signed integer of the given byte width. |
function BigInteger:toString(base?: integer): string
Converts the big integer to a string in the specified (or not) base.
Parameters
| Name | Type | Description |
|---|
baseoptional | integer | The numerical base of the digits in the input value. Can be any integer between 2 and 36, inclusive. By default: 10 |
Returns
| Type | Name | Description |
|---|
string | str | The string representation of the big integer. |
function BigInteger:toUnsigned(byte_width: integer): BigInteger
Parameters
| Name | Type | Description |
|---|
byte_width | integer | The byte width to encode as (e.g. 1 for uint8, 4 for uint32). |
Returns