diff --git a/bigint/bigint-tests.ts b/bigint/bigint-tests.ts index 8ccf2ba4b9..14cdd5b12c 100644 --- a/bigint/bigint-tests.ts +++ b/bigint/bigint-tests.ts @@ -49,7 +49,7 @@ bi = BigInt.trim(bi, num); BigInt.addInt_(bi, num); BigInt.add_(bi, bi); BigInt.copy_(bi, bi); -num = BigInt.copyInt_(bi, num); +BigInt.copyInt_(bi, num); BigInt.GCD_(bi, bi); b = BigInt.inverseMod_(bi, bi); BigInt.mod_(bi, bi); diff --git a/bigint/bigint.d.ts b/bigint/bigint.d.ts index b70f20fa4c..a2a8ed4176 100644 --- a/bigint/bigint.d.ts +++ b/bigint/bigint.d.ts @@ -1,8 +1,11 @@ -// Type definitions for BigInt v5.5.1 +// Type definitions for BigInt v5.5.3 // Project: https://github.com/Evgenus/BigInt // Definitions by: Eugene Chernyshov // Definitions: https://github.com/borisyankov/DefinitelyTyped +// Development repository: https://github.com/Evgenus/bigint-typescript-definitions +// For answers, fixes and cutting edge version please see development repository. + declare module BigInt { export interface BigInt extends Array { } @@ -11,361 +14,632 @@ declare module BigInt { (): number; } + /** + * Sets a random number generator. + * + * @param {IRandom} random function that returns random number. + */ export function setRandom(random: IRandom): void; /** - * bigInt add(x,y) * return (x+y) for bigInts x and y. + * + * @param {BigInt} x The BigInt augend. + * @param {BigInt} y The BigInt addend. + * + * @return {BigInt} A sum as BigInt. */ export function add(x: BigInt, y: BigInt): BigInt; /** - * bigInt addInt(x,n) * return (x+n) where x is a bigInt and n is an integer. + * + * @param {BigInt} x The BigInt augend. + * @param {number} n The number addend. + * + * @return {BigInt} A sum as BigInt. */ export function addInt(x: BigInt, n: number): BigInt; - interface bigInt2str_T { - /** - * string bigInt2str(x,base) - * return a string form of bigInt x in a given base, with 2 <= base <= 95 - */ - (x: BigInt, base: T): string; - } - - interface bigInt2strSignature extends bigInt2str_T, bigInt2str_T{ - } - - export var bigInt2str: bigInt2strSignature; + /** + * return a string form of bigInt x in a given base, with 2 <= base <= 95. + * + * @param {BigInt} x The BigInt to stringify. + * @param {number} base The base as radix number. + * + * @return {string} A string representation of given BigInt. + */ + export function bigInt2str(x: BigInt, base: number): string; /** - * int bitSize(x) - * return how many bits long the bigInt x is, not counting leading zeros + * return a string form of bigInt x in a given base, with 2 <= base <= 95. + * + * @param {BigInt} x The BigInt to stringify. + * @param {string} base The base as vocabulary of characters. + * + * @return {string} A string representation of given BigInt. + */ + export function bigInt2str(x: BigInt, base: string): string; + + /** + * return how many bits long the bigInt x is, not counting leading zeros. + * + * @param {BigInt} x The BigInt to process. + * + * @return {number} A size in BigInt as number. */ export function bitSize(x: BigInt): number; /** - * bigInt dup(x) - * return a copy of bigInt x + * return a copy of bigInt x. + * + * @param {BigInt} x Source BigInt to be copied. + * + * @return {BigInt} A copy of this object. */ export function dup(x: BigInt): BigInt; /** - * boolean equals(x,y) * is the bigInt x equal to the bigint y? + * + * @param {BigInt} x BigInt to be compared. + * @param {BigInt} y BigInt to be compared. + * + * @return {boolean} true if the objects are considered equal, false if they are not. */ export function equals(x: BigInt, y: BigInt): boolean; /** - * boolean equalsInt(x,y) * is bigint x equal to integer y? + * + * @param {BigInt} x BigInt to be compared. + * @param {BigInt} y BigInt to be compared. + * + * @return {boolean} true if the objects are considered equal, false if not. */ export function equalsInt(x: BigInt, y: number): boolean; /** - * bigInt expand(x,n) - * return a copy of x with at least n elements, adding leading zeros if needed + * return a copy of x with at least n elements, adding leading zeros if needed. + * + * @param {BigInt} value The source object to copy. + * @param {number} n The minimal number of elements. + * + * @return {BigInt} A copy of given BigInt. */ export function expand(value: BigInt, n: number): BigInt; /** - * Array findPrimes(n) - * return array of all primes less than integer n + * return array of all primes less than integer n. + * + * @param {number} n Upper limit of search. + * + * @return {Array} The found primes as Array. */ export function findPrimes(n: number): number[]; /** - * bigInt GCD(x,y) * return greatest common divisor of bigInts x and y (each with same number of elements). + * + * @param {BigInt} x The BigInt to process. + * @param {BigInt} y The BigInt to process. + * + * @return {BigInt} A greatest common divisor as BigInt. */ export function GCD(x: BigInt, y: BigInt): BigInt; /** - * boolean greater(x,y) * is x>y? (x and y are nonnegative bigInts) + * + * @param {BigInt} x BigInt to be compared. + * @param {BigInt} y BigInt to be compared. + * + * @return {boolean} true if x is greater, false if it's not. */ export function greater(x: BigInt, y: BigInt): boolean; /** - * boolean greaterShift(x,y,shift) * is (x <<(shift*bpe)) > y? + * + * @param {BigInt} x BigInt to be compared. + * @param {BigInt} y BigInt to be compared. + * @param {number} shift The shift amount in bits. + * + * @return {boolean} true if x is greater, false if it's not. */ export function greaterShift(x: BigInt, y: BigInt, shift: number): boolean; /** - * bigInt int2bigInt(t,n,m) - * return a bigInt equal to integer t, with at least n bits and m array elements + * return a bigInt equal to integer t, with at least n bits and m array elements. + * + * @param {number} t The number to process. + * @param {number=} n (Optional) the number to process. + * @param {number=} m (Optional) the number to process. + * + * @return {BigInt} A BigInt equivalent of given number. */ export function int2bigInt(t: number, n?: number, m?: number): BigInt; /** - * bigInt inverseMod(x,n) - * return (x**(-1) mod n) for bigInts x and n. If no inverse exists, it returns null + * return (x**(-1) mod n) for bigInts x and n. If no inverse exists, it returns null. + * + * @param {BigInt} x The BigInt base. + * @param {BigInt} n The BigInt divisor. + * + * @return {BigInt} A BigInt remainder. */ export function inverseMod(x: BigInt, n: BigInt): BigInt; /** - * int inverseModInt(x,n) - * return x**(-1) mod n, for integers x and n. Return 0 if there is no inverse + * return x**(-1) mod n, for integers x and n. + * Return 0 if there is no inverse. + * + * @param {number} x The BigInt base. + * @param {number} n The BigInt divisor. + * + * @return {BigInt} A BigInt remainder. */ export function inverseModInt(x: number, n: number): BigInt; /** - * boolean isZero(x) * is the bigInt x equal to zero? + * + * @param {BigInt} x BigInt to be compared. + * + * @return {boolean} true if zero, false if not. */ export function isZero(x: BigInt): boolean; /** - * boolean millerRabin(x,b) - * does one round of Miller-Rabin base integer b say that bigInt x is possibly prime? (b is bigInt, 1=1). If s=1, then the most significant of those n bits is set to 1. + * return an n-bit random BigInt (n>=1). + * If s=1, then the most significant of those n bits is set to 1. + * + * @param {number} n The number of bits (n>=1). + * @param {number} s The sign bit. + * + * @return {BigInt} A new random BigInt. */ export function randBigInt(n: number, s: number): BigInt; /** - * bigInt randTruePrime(k) * return a new, random, k-bit, true prime bigInt using Maurer's algorithm. + * + * @param {number} k The number of bits. + * + * @return {BigInt} A new random BigInt. */ export function randTruePrime(k: number): BigInt; /** - * bigInt randProbPrime(k) - * return a new, random, k-bit, probable prime bigInt (probability it's composite less than 2^-80). + * return a new, random, k-bit, probable prime bigInt. + * Probability it's composite less than 2^- 80. + * + * @param {number} k The number of bits. + * + * @return {BigInt} A new probably random BigInt. */ export function randProbPrime(k: number): BigInt; - interface str2bigInt_T { - /** - * bigInt str2bigInt(s,b,n,m) - * return a bigInt for number represented in string s in base b with at least n bits and m array elements - */ - (s: string, b: T, n?: number, m?: number): BigInt; - } - - interface str2bigIntSignature extends str2bigInt_T, str2bigInt_T { - } - - export var str2bigInt: str2bigIntSignature; + /** + * return a bigInt for number represented in string s in base b with at least n bits and m array + * elements. + * + * @param {string} s The string representation of number. + * @param {number} b The base as radix number. + * @param {number=} n (Optional) minimal bit length as number. + * @param {number=} m (Optional) the number of array elements as number. + * + * @return {BigInt} A parsed BigInt. + */ + export function str2bigInt(s: string, b: number, n?: number, m?: number): BigInt; /** - * bigInt sub(x,y) - * return (x-y) for bigInts x and y. Negative answers will be 2s complement + * return a bigInt for number represented in string s in base b with at least n bits and m array + * elements. + * + * @param {string} s The string representation of number. + * @param {string} b The base as string vocabulary of characters. + * @param {number=} n (Optional) minimal bit length as number. + * @param {number=} m (Optional) the number of array elements as number. + * + * @return {BigInt} A parsed BigInt. + */ + export function str2bigInt(s: string, b: string, n?: number, m?: number): BigInt; + + /** + * return (x-y) for bigInts x and y. + * Negative answers will be 2s complement. + * + * @param {BigInt} x The minuend as BigInt. + * @param {BigInt} y The subtrahend as BigInt. + * + * @return {BigInt} A difference BigInt. */ export function sub(x: BigInt, y: BigInt): BigInt; /** - * bigInt trim(x,k) - * return a copy of x with exactly k leading zero elements + * return a copy of x with exactly k leading zero elements. + * + * @param {BigInt} x The BigInt to be copied. + * @param {number} k The number of zeroes. + * + * @return {BigInt} A copy BigInt. */ export function trim(x: BigInt, k: number): BigInt; /** - * void addInt_(x,n) - * do x=x+n where x is a bigInt and n is an integer + * do x=x+n where x is a bigInt and n is an integer. + * + * @private Intend to be internal function. + * + * @param {BigInt} x The BigInt accumulator. + * @param {number} n The number addend. */ export function addInt_(x: BigInt, n: number): void; /** - * void add_(x,y) - * do x=x+y for bigInts x and y + * do x=x+y for bigInts x and y. + * + * @private Intend to be internal function. + * + * @param {BigInt} x The BigInt accumulator. + * @param {BigInt} y The BigInt addend. */ export function add_(x: BigInt, y: BigInt): void; /** - * void copy_(x,y) - * do x=y on bigInts x and y + * do x=y on bigInts x and y. + * + * @private Intend to be internal function. + * + * @param {BigInt} x The BigInt destination. + * @param {BigInt} y The BigInt source. */ export function copy_(x: BigInt, y: BigInt): void; /** - * void copyInt_(x,n) - * do x=n on bigInt x and integer n + * do x=n on bigInt x and integer n. + * + * @private Intend to be internal function. + * + * @param {BigInt} x The BigInt destination. + * @param {number} n The number source. */ - export function copyInt_(x: BigInt, n: number): number; + export function copyInt_(x: BigInt, n: number): void; /** - * void GCD_(x,y) - * set x to the greatest common divisor of bigInts x and y, (y is destroyed). (This never overflows its array). + * set x to the greatest common divisor of bigInts x and y, (y is destroyed). + * This never overflows its array. + * + * @private Intend to be internal function. + * + * @param {BigInt} x The BigInt first dividend. + * @param {BigInt} y The BigInt second dividend. */ export function GCD_(x: BigInt, y: BigInt): void; /** - * boolean inverseMod_(x,n) - * do x=x**(-1) mod n, for bigInts x and n. Returns 1 (0) if inverse does (doesn't) exist + * do x=x**(-1) mod n, for bigInts x and n. Returns 1 (0) if inverse does (doesn't) exist. + * + * @private Intend to be internal function. + * + * @param {BigInt} x The BigInt base and the remainder result. + * @param {BigInt} n The BigInt divisor. + * + * @return {boolean} true if inverse does exist, false if doesn't. */ export function inverseMod_(x: BigInt, n: BigInt): boolean; /** - * void mod_(x,n) * do x=x mod n for bigInts x and n. (This never overflows its array). + * + * @private Intend to be internal function. + * + * @param {BigInt} x The BigInt dividend and the remainder result. + * @param {BigInt} n The BigInt divisor. */ export function mod_(x: BigInt, n: BigInt): void; /** - * void mult_(x,y) * do x=x*y for bigInts x and y. + * + * @private Intend to be internal function. + * + * @param {BigInt} x The BigInt multiplicand and the product result. + * @param {BigInt} y The BigInt multiplier. */ export function mult_(x: BigInt, y: BigInt): void; /** - * void multMod_(x,y,n) - * do x=x*y mod n for bigInts x,y,n. + * do x=x*y mod n for bigInts x,y,n. + * + * @private Intend to be internal function. + * + * @param {BigInt} x The BigInt multiplicand and the remainder result. + * @param {BigInt} y The BigInt multiplier. + * @param {BigInt} n The BigInt divisor. */ export function multMod_(x: BigInt, y: BigInt, n: BigInt): void; /** - * void powMod_(x,y,n) - * do x=x**y mod n, where x,y,n are bigInts (n is odd) and ** is exponentiation. 0**0=1. + * do x=x**y mod n, where x,y,n are bigInts (n is odd) and ** is exponentiation. + * 0**0=1. + * + * @private Intend to be internal function. + * + * @param {BigInt} x The BigInt base and the remainder result. + * @param {BigInt} y The BigInt exponent. + * @param {BigInt} n The BigInt divisor. */ export function powMod_(x: BigInt, y: BigInt, n: BigInt): void; /** - * void randBigInt_(b,n,s) - * do b = an n-bit random BigInt. if s=1, then nth bit (most significant bit) is set to 1. n>=1. + * do b = an n-bit random BigInt. + * if s=1, then nth bit (most significant bit) is set to 1. n>=1. + * + * @private Intend to be internal function. + * + * @param {BigInt} b The BigInt destination. + * @param {number} n The number of bits. + * @param {number} s The sign bit number. */ export function randBigInt_(b: BigInt, n: number, s: number): void; /** - * void randTruePrime_(ans,k) * do ans = a random k-bit true random prime (not just probable prime) with 1 in the msb. + * + * @private Intend to be internal function. + * + * @param {BigInt} ans The destination. + * @param {number} k The number of bits. */ export function randTruePrime_(ans: BigInt, k: number): void; /** - * void sub_(x,y) * do x=x-y for bigInts x and y. Negative answers will be 2s complement. + * + * @private Intend to be internal function. + * + * @param {BigInt} x The BigInt minuend and the result difference. + * @param {BigInt} y The BigInt subtrahend . */ export function sub_(x: BigInt, y: BigInt): void; /** - * void addShift_(x,y,ys) * do x=x+(y<<(ys*bpe)) + * + * @private Intend to be internal function. + * + * @param {BigInt} x The BigInt accumulator. + * @param {BigInt} y The BigInt addend to be shifted. + * @param {number} ys The number of shift amount. */ export function addShift_(x: BigInt, y: BigInt, ys: number): void; /** - * void carry_(x) * do carries and borrows so each element of the bigInt x fits in bpe bits. + * + * @private Intend to be internal function. + * + * @param {BigInt} x The BigInt to process. */ export function carry_(x: BigInt): void; /** - * void divide_(x,y,q,r) - * divide x by y giving quotient q and remainder r + * divide x by y giving quotient q and remainder r. + * + * @private Intend to be internal function. + * + * @param {BigInt} x The BigInt dividend. + * @param {BigInt} y The BigInt divisor. + * @param {BigInt} q The BigInt quotient. + * @param {BigInt} r The BigInt remainder. */ export function divide_(x: BigInt, y: BigInt, q: BigInt, r: BigInt): void; /** - * int divInt_(x,n) - * do x=floor(x/n) for bigInt x and integer n, and return the remainder. (This never overflows its array). + * do x=floor(x/n) for bigInt x and integer n, and return the remainder. + * This never overflows its array. + * + * @private Intend to be internal function. + * + * @param {BigInt} x The BigInt dividend and the quotient result. + * @param {number} n The number divisor. + * + * @return {number} A number remainder. */ export function divInt_(x: BigInt, n: number): number; /** - * void eGCD_(x,y,d,a,b) - * sets a,b,d to positive bigInts such that d = GCD_(x,y) = a*x-b*y + * sets a,b,d to positive bigInts such that d = GCD_(x,y) = a*x-b*y. + * + * @private Intend to be internal function. + * + * @param {BigInt} x The BigInt to process. + * @param {BigInt} y The BigInt to process. + * @param {BigInt} d The BigInt to process. + * @param {BigInt} a The BigInt to process. + * @param {BigInt} b The BigInt to process. */ export function eGCD_(x: BigInt, y: BigInt, d: BigInt, a: BigInt, b: BigInt): void; /** - * void halve_(x) - * do x=floor(|x|/2)*sgn(x) for bigInt x in 2's complement. (This never overflows its array). + * do x=floor(|x|/2)*sgn(x) for bigInt x in 2's complement. + * This never overflows its array. + * + * @private Intend to be internal function. + * + * @param {BigInt} x The BigInt to process. */ export function halve_(x: BigInt): void; /** - * void leftShift_(x,n) * left shift bigInt x by n bits. n