@isdk/bigint
Version:
The BigInteger class wrapped bn.js and native BitInt
402 lines (399 loc) • 10.8 kB
TypeScript
/**
* The unified interface for Big Integer
*
* @remarks
*
* The operator method prefix
*
* * `i`: perform operation in-place, storing the result in the host object (on which the method was invoked). Might be used to avoid number allocation costs
*
* @example
*
* ```typescript
* import BigInteger from '@isdk/bigint'
* const a = new BigInteger(9)
* const b = new BigInteger(6)
* // perform addition on `a` and `b`, storing the result in `a`
* a.iadd(b)
* console.log(a.toString()) // prints "15"
* ```
*/
interface IBigInt {
/**
* return a new IBigInteger object with the same value
*/
clone(): IBigInt;
/**
* IBigInteger increment number n in place
* @param n - (optional) Value to increment, defaults to 1
*/
iinc(n?: number): this;
/**
* IBigInteger decrement number n in place
* @param n - (optional) Value to decrement, defaults to 1
*/
idec(n?: number): this;
/**
* IBigInteger addition in place
* @param x - Value to add
*/
iadd(x: IBigInt): this;
/**
* IBigInteger subtraction in place
* @param x - Value to subtract
*/
isub(x: IBigInt): this;
/**
* IBigInteger multiplication in place
* @param x - Value to multiply
*/
imul(x: IBigInt): this;
/**
* Compute value modulo m, in place
* @param m - Modulo
*/
imod(m: IBigInt): this;
/**
* Shift this to the left by x, in place
* @param x - Shift value
*/
ileftShift(x: IBigInt): this;
/**
* Shift this to the right by x, in place
* @param x - Shift value
*/
irightShift(x: this): this;
/**
* IBigInteger increment
* @param n - (optional) Value to increment, defaults to 1
* @returns this + 1.
*/
inc(n?: number): IBigInt;
/**
* IBigInteger decrement
* @param n - (optional) Value to decrement, defaults to 1
* @returns this - 1.
*/
dec(n?: number): IBigInt;
/**
* IBigInteger addition
* @param x - Value to add
* @returns this + x.
*/
add(x: IBigInt): IBigInt;
/**
* IBigInteger subtraction
* @param x - Value to subtract
* @returns this - x.
*/
sub(x: IBigInt): IBigInt;
/**
* IBigInteger multiplication
* @param x - Value to multiply
* @returns this * x.
*/
mul(x: IBigInt): IBigInt;
/**
* Compute value modulo m
* @param m - Modulo
* @returns this mod m.
*/
mod(m: IBigInt): IBigInt;
/**
* Compute modular exponentiation
* Much faster than this.exp(e).mod(n)
* @param e - Exponent
* @param n - Modulo
* @returns this ** e mod n.
*/
modExp(e: IBigInt, n: IBigInt): IBigInt;
/**
* Compute the inverse of this value modulo n
* Note: this and and n must be relatively prime
* @param n - Modulo
* @returns x such that this*x = 1 mod n
* @throws {Error} if the inverse does not exist
*/
modInv(n: IBigInt): IBigInt;
/**
* Compute greatest common divisor between this and n
* @param n - Operand
* @returns gcd
*/
gcd(n: IBigInt): IBigInt;
/**
* Shift this to the left by x
* @param x - Shift value
* @returns this << x.
*/
leftShift(x: IBigInt): IBigInt;
/**
* Shift this to the right by x
* @param x - Shift value
* @returns this >> x.
*/
rightShift(x: IBigInt): IBigInt;
/**
* Whether this value is equal to x
* @param x
* @returns {Boolean}
*/
equal(x: IBigInt): boolean;
/**
* Whether this value is less than x
* @param x
* @returns {Boolean}
*/
lt(x: IBigInt): boolean;
/**
* Whether this value is less than or equal to x
* @param x
* @returns {Boolean}
*/
lte(x: IBigInt): boolean;
/**
* Whether this value is greater than x
* @param x
* @returns {Boolean}
*/
gt(x: IBigInt): boolean;
/**
* Whether this value is greater than or equal to x
* @param x
* @returns {Boolean}
*/
gte(x: IBigInt): boolean;
isZero(): boolean;
isOne(): boolean;
isNegative(): boolean;
isEven(): boolean;
abs(): IBigInt;
/**
* Get this value as a string
* @returns {String} this value.
*/
toString(): string;
/**
* Get this value as an exact Number (max 53 bits)
* Fails if this value is too large
* @returns the number value
*/
toNumber(): number;
/**
* Get value of i-th bit
* @param i - Bit index
* @returns Bit value.
*/
getBit(i: number): number;
/**
* Compute bit length
* @returns Bit length.
*/
bitLength(): number;
/**
* Compute byte length
* @returns Byte length.
*/
byteLength(): number;
/**
* Get Uint8Array representation of this number
* @param {"le"|"be"} endian - Endianess of output array (defaults to 'be')
* @param length - Of output array
* @returns {Uint8Array}
*/
toUint8Array(endian?: string, length?: number): Uint8Array;
}
/**
* The Big Integer implementation of basic operations
* that wraps the native BigInt library.
* Operations are not constant time,
* but we try and limit timing leakage where we can
*/
declare class BigIntNative implements IBigInt {
value: bigint;
/**
* Get a BigInteger (input must be big endian for strings and arrays)
* @param {Number|String|Uint8Array} n - Value to convert
* @throws {Error} on null or undefined input
*/
constructor(n: number | string | Uint8Array | bigint | boolean);
clone(): BigIntNative;
iinc(n?: number): this;
inc(n?: number): BigIntNative;
idec(n?: number): this;
dec(n?: number): BigIntNative;
/**
* BigInteger addition in place
* @param {BigIntNative} x - Value to add
*/
iadd(x: BigIntNative): this;
/**
* BigInteger addition
* @param {BigIntNative} x - Value to add
* @returns {BigIntNative} this + x.
*/
add(x: BigIntNative): BigIntNative;
/**
* BigInteger subtraction in place
* @param {BigIntNative} x - Value to subtract
*/
isub(x: BigIntNative): this;
/**
* BigInteger subtraction
* @param {BigIntNative} x - Value to subtract
* @returns {BigIntNative} this - x.
*/
sub(x: BigIntNative): BigIntNative;
/**
* BigInteger multiplication in place
* @param {BigIntNative} x - Value to multiply
*/
imul(x: BigIntNative): this;
/**
* BigInteger multiplication
* @param {BigIntNative} x - Value to multiply
* @returns {BigIntNative} this * x.
*/
mul(x: BigIntNative): BigIntNative;
imod(m: BigIntNative): this;
/**
* Compute value modulo m, in place
* @param {BigIntNative} m - Modulo
*/
iumod(m: BigIntNative): this;
/**
* Compute value modulo m
* @param {BigIntNative} m - Modulo
* @returns {BigIntNative} this mod m.
*/
umod(m: BigIntNative): BigIntNative;
/**
* Compute value modulo m
* @param {BigIntNative} m - Modulo
* @returns {BigIntNative} this mod m.
*/
mod(m: BigIntNative): BigIntNative;
modExp(e: BigIntNative, n: BigIntNative): BigIntNative;
/**
* Compute the inverse of this value modulo n
* Note: this and and n must be relatively prime
* @param {BigIntNative} n - Modulo
* @returns {BigIntNative} x such that this*x = 1 mod n
* @throws {Error} if the inverse does not exist
*/
modInv(n: BigIntNative): BigIntNative;
__egcd(b: bigint): {
x: bigint;
y: bigint;
gcd: bigint;
};
/**
* Extended Eucleadian algorithm (http://anh.cs.luc.edu/331/notes/xgcd.pdf)
* Given a = this and b, compute (x, y) such that ax + by = gdc(a, b)
* @param {BigIntNative} b - Second operand
* @returns {{ gcd, x, y: BigIntNative }}
*/
_egcd(b: any): {
x: BigIntNative;
y: BigIntNative;
gcd: BigIntNative;
};
/**
* Compute greatest common divisor between this and n
* @param {BigIntNative} b - Operand
* @returns {BigIntNative} gcd
*/
gcd(b: any): BigIntNative;
/**
* Shift this to the left by x, in place
* @param {BigIntNative} x - Shift value
*/
ileftShift(x: BigIntNative): this;
/**
* Shift this to the left by x
* @param {BigIntNative} x - Shift value
* @returns {BigIntNative} this << x.
*/
leftShift(x: BigIntNative): BigIntNative;
/**
* Shift this to the right by x, in place
* @param {BigIntNative} x - Shift value
*/
irightShift(x: BigIntNative): this;
/**
* Shift this to the right by x
* @param {BigIntNative} x - Shift value
* @returns {BigIntNative} this >> x.
*/
rightShift(x: BigIntNative): BigIntNative;
/**
* Whether this value is equal to x
* @param {BigIntNative} x
* @returns {Boolean}
*/
equal(x: BigIntNative): boolean;
/**
* Whether this value is less than x
* @param {BigIntNative} x
* @returns {Boolean}
*/
lt(x: BigIntNative): boolean;
/**
* Whether this value is less than or equal to x
* @param {BigIntNative} x
* @returns {Boolean}
*/
lte(x: BigIntNative): boolean;
/**
* Whether this value is greater than x
* @param {BigIntNative} x
* @returns {Boolean}
*/
gt(x: BigIntNative): boolean;
/**
* Whether this value is greater than or equal to x
* @param {BigIntNative} x
* @returns {Boolean}
*/
gte(x: BigIntNative): boolean;
isZero(): boolean;
isOne(): boolean;
isNegative(): boolean;
isEven(): boolean;
abs(): BigIntNative;
/**
* Get this value as a string
* @returns {String} this value.
*/
toString(): string;
/**
* Get this value as an exact Number (max 53 bits)
* Fails if this value is too large
* @returns {Number}
*/
toNumber(): number;
/**
* Get value of i-th bit
* @param {Number} i - Bit index
* @returns {Number} Bit value.
*/
getBit(i: number): 1 | 0;
/**
* Compute bit length
* @returns {Number} Bit length.
*/
bitLength(): number;
/**
* Compute byte length
* @returns {Number} Byte length.
*/
byteLength(): number;
/**
* Get Uint8Array representation of this number
* @param {String} endian - Endianess of output array (defaults to 'be')
* @param {Number} length - Of output array
* @returns {Uint8Array}
*/
toUint8Array(endian?: string, length?: number): Uint8Array;
}
export { BigIntNative as B, IBigInt as I };