comments added to declaration file
This commit is contained in:
Juanelas
parent
75b3dcf61b
commit
b365f49816
|
|
@ -21,6 +21,7 @@ const tsConfig = parseJsonSourceFileConfigFileContent(configFile, sys, dirname(t
|
|||
export const compile = (outDir) => {
|
||||
const compilerOptions = {
|
||||
...tsConfig.options,
|
||||
removeComments: false,
|
||||
declaration: true,
|
||||
declarationMap: true,
|
||||
emitDeclarationOnly: true,
|
||||
|
|
|
|||
|
|
@ -1,7 +1,32 @@
|
|||
/**
|
||||
* Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0
|
||||
*
|
||||
* @param a
|
||||
*
|
||||
* @returns The absolute value of a
|
||||
*/
|
||||
declare function abs(a: number | bigint): number | bigint;
|
||||
|
||||
/**
|
||||
* Returns the (minimum) length of a number expressed in bits.
|
||||
*
|
||||
* @param a
|
||||
* @returns The bit length
|
||||
*/
|
||||
declare function bitLength(a: number | bigint): number;
|
||||
|
||||
/**
|
||||
* Chinese remainder theorem states that if one knows the remainders of the Euclidean division of an integer n by several integers, then one can determine uniquely the remainder of the division of n by the product of these integers, under the condition that the divisors are pairwise coprime (no two divisors share a common factor other than 1). Provided that n_i are pairwise coprime, and a_i any integers, this function returns a solution for the following system of equations:
|
||||
x ≡ a_1 mod n_1
|
||||
x ≡ a_2 mod n_2
|
||||
⋮
|
||||
x ≡ a_k mod n_k
|
||||
*
|
||||
* @param remainders the array of remainders a_i. For example [17n, 243n, 344n]
|
||||
* @param modulos the array of modulos n_i. For example [769n, 2017n, 47701n]
|
||||
* @param modulo the product of all modulos. Provided here just to save some operations if it is already known
|
||||
* @returns x
|
||||
*/
|
||||
declare function crt(remainders: bigint[], modulos: bigint[], modulo?: bigint): bigint;
|
||||
|
||||
interface Egcd {
|
||||
|
|
@ -9,29 +34,124 @@ interface Egcd {
|
|||
x: bigint;
|
||||
y: bigint;
|
||||
}
|
||||
/**
|
||||
* An iterative implementation of the extended euclidean algorithm or extended greatest common divisor algorithm.
|
||||
* Take positive integers a, b as input, and return a triple (g, x, y), such that ax + by = g = gcd(a, b).
|
||||
*
|
||||
* @param a
|
||||
* @param b
|
||||
*
|
||||
* @throws {@link RangeError} if a or b are <= 0
|
||||
*
|
||||
* @returns A triple (g, x, y), such that ax + by = g = gcd(a, b).
|
||||
*/
|
||||
declare function eGcd(a: number | bigint, b: number | bigint): Egcd;
|
||||
|
||||
/**
|
||||
* Greatest common divisor of two integers based on the iterative binary algorithm.
|
||||
*
|
||||
* @param a
|
||||
* @param b
|
||||
*
|
||||
* @returns The greatest common divisor of a and b
|
||||
*/
|
||||
declare function gcd(a: number | bigint, b: number | bigint): bigint;
|
||||
|
||||
/**
|
||||
* The least common multiple computed as abs(a*b)/gcd(a,b)
|
||||
* @param a
|
||||
* @param b
|
||||
*
|
||||
* @returns The least common multiple of a and b
|
||||
*/
|
||||
declare function lcm(a: number | bigint, b: number | bigint): bigint;
|
||||
|
||||
/**
|
||||
* Maximum. max(a,b)==a if a>=b. max(a,b)==b if a<b
|
||||
*
|
||||
* @param a
|
||||
* @param b
|
||||
*
|
||||
* @returns Maximum of numbers a and b
|
||||
*/
|
||||
declare function max(a: number | bigint, b: number | bigint): number | bigint;
|
||||
|
||||
/**
|
||||
* Minimum. min(a,b)==b if a>=b. min(a,b)==a if a<b
|
||||
*
|
||||
* @param a
|
||||
* @param b
|
||||
*
|
||||
* @returns Minimum of numbers a and b
|
||||
*/
|
||||
declare function min(a: number | bigint, b: number | bigint): number | bigint;
|
||||
|
||||
/**
|
||||
* Modular addition of (a_1 + ... + a_r) mod n
|
||||
* @param addends an array of the numbers a_i to add. For example [3, 12353251235n, 1243, -12341232545990n]
|
||||
* @param n the modulo
|
||||
* @returns The smallest positive integer that is congruent with (a_1 + ... + a_r) mod n
|
||||
*/
|
||||
declare function modAdd(addends: Array<number | bigint>, n: number | bigint): bigint;
|
||||
|
||||
/**
|
||||
* Modular inverse.
|
||||
*
|
||||
* @param a The number to find an inverse for
|
||||
* @param n The modulo
|
||||
*
|
||||
* @throws {@link RangeError} if a does not have inverse modulo n
|
||||
*
|
||||
* @returns The inverse modulo n
|
||||
*/
|
||||
declare function modInv(a: number | bigint, n: number | bigint): bigint;
|
||||
|
||||
/**
|
||||
* Modular addition of (a_1 * ... * a_r) mod n
|
||||
* @param factors an array of the numbers a_i to multiply. For example [3, 12353251235n, 1243, -12341232545990n]
|
||||
* @param n the modulo
|
||||
* @returns The smallest positive integer that is congruent with (a_1 * ... * a_r) mod n
|
||||
*/
|
||||
declare function modMultiply(factors: Array<number | bigint>, n: number | bigint): bigint;
|
||||
|
||||
type PrimePower = [number | bigint, number | bigint];
|
||||
type PrimeFactor = number | bigint | PrimePower;
|
||||
/**
|
||||
* Modular exponentiation b**e mod n. Currently using the right-to-left binary method if the prime factorization is not provided, or the chinese remainder theorem otherwise.
|
||||
*
|
||||
* @param b base
|
||||
* @param e exponent
|
||||
* @param n modulo
|
||||
* @param primeFactorization an array of the prime factors, for example [5n, 5n, 13n, 27n], or prime powers as [p, k], for instance [[5, 2], [13, 1], [27, 1]]. If the prime factorization is provided the chinese remainder theorem is used to greatly speed up the exponentiation.
|
||||
*
|
||||
* @throws {@link RangeError} if n <= 0
|
||||
*
|
||||
* @returns b**e mod n
|
||||
*/
|
||||
declare function modPow(b: number | bigint, e: number | bigint, n: number | bigint, primeFactorization?: PrimeFactor[]): bigint;
|
||||
|
||||
type PrimeFactorization = Array<[bigint, bigint]>;
|
||||
/**
|
||||
* A function that computes the Euler's totien function of a number n, whose prime power factorization is known
|
||||
*
|
||||
* @param primeFactorization an array of arrays containing the prime power factorization of a number n. For example, for n = (p1**k1)*(p2**k2)*...*(pr**kr), one should provide [[p1, k1], [p2, k2], ... , [pr, kr]]
|
||||
* @returns phi((p1**k1)*(p2**k2)*...*(pr**kr))
|
||||
*/
|
||||
declare function phi(primeFactorization: PrimeFactorization): bigint;
|
||||
|
||||
/**
|
||||
* Finds the smallest positive element that is congruent to a in modulo n
|
||||
*
|
||||
* @remarks
|
||||
* a and b must be the same type, either number or bigint
|
||||
*
|
||||
* @param a - An integer
|
||||
* @param n - The modulo
|
||||
*
|
||||
* @throws {@link RangeError} if n <= 0
|
||||
*
|
||||
* @returns A bigint with the smallest positive representation of a modulo n
|
||||
*/
|
||||
declare function toZn(a: number | bigint, n: number | bigint): bigint;
|
||||
|
||||
export { Egcd, PrimeFactor, PrimeFactorization, PrimePower, abs, bitLength, crt, eGcd, gcd, lcm, max, min, modAdd, modInv, modMultiply, modPow, phi, toZn };
|
||||
|
|
|
|||
34
docs/API.md
34
docs/API.md
|
|
@ -39,7 +39,7 @@ Some common functions for modular arithmetic using native JS implementation of B
|
|||
|
||||
#### Defined in
|
||||
|
||||
[modPow.ts:8](https://github.com/juanelas/bigint-mod-arith/blob/06b32a3/src/ts/modPow.ts#L8)
|
||||
[modPow.ts:8](https://github.com/juanelas/bigint-mod-arith/blob/75b3dcf/src/ts/modPow.ts#L8)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -49,7 +49,7 @@ ___
|
|||
|
||||
#### Defined in
|
||||
|
||||
[phi.ts:1](https://github.com/juanelas/bigint-mod-arith/blob/06b32a3/src/ts/phi.ts#L1)
|
||||
[phi.ts:1](https://github.com/juanelas/bigint-mod-arith/blob/75b3dcf/src/ts/phi.ts#L1)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -59,7 +59,7 @@ ___
|
|||
|
||||
#### Defined in
|
||||
|
||||
[modPow.ts:7](https://github.com/juanelas/bigint-mod-arith/blob/06b32a3/src/ts/modPow.ts#L7)
|
||||
[modPow.ts:7](https://github.com/juanelas/bigint-mod-arith/blob/75b3dcf/src/ts/modPow.ts#L7)
|
||||
|
||||
## Functions
|
||||
|
||||
|
|
@ -83,7 +83,7 @@ The absolute value of a
|
|||
|
||||
#### Defined in
|
||||
|
||||
[abs.ts:8](https://github.com/juanelas/bigint-mod-arith/blob/06b32a3/src/ts/abs.ts#L8)
|
||||
[abs.ts:8](https://github.com/juanelas/bigint-mod-arith/blob/75b3dcf/src/ts/abs.ts#L8)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -107,7 +107,7 @@ The bit length
|
|||
|
||||
#### Defined in
|
||||
|
||||
[bitLength.ts:7](https://github.com/juanelas/bigint-mod-arith/blob/06b32a3/src/ts/bitLength.ts#L7)
|
||||
[bitLength.ts:7](https://github.com/juanelas/bigint-mod-arith/blob/75b3dcf/src/ts/bitLength.ts#L7)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -137,7 +137,7 @@ x
|
|||
|
||||
#### Defined in
|
||||
|
||||
[crt.ts:16](https://github.com/juanelas/bigint-mod-arith/blob/06b32a3/src/ts/crt.ts#L16)
|
||||
[crt.ts:16](https://github.com/juanelas/bigint-mod-arith/blob/75b3dcf/src/ts/crt.ts#L16)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -167,7 +167,7 @@ A triple (g, x, y), such that ax + by = g = gcd(a, b).
|
|||
|
||||
#### Defined in
|
||||
|
||||
[egcd.ts:17](https://github.com/juanelas/bigint-mod-arith/blob/06b32a3/src/ts/egcd.ts#L17)
|
||||
[egcd.ts:17](https://github.com/juanelas/bigint-mod-arith/blob/75b3dcf/src/ts/egcd.ts#L17)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -192,7 +192,7 @@ The greatest common divisor of a and b
|
|||
|
||||
#### Defined in
|
||||
|
||||
[gcd.ts:11](https://github.com/juanelas/bigint-mod-arith/blob/06b32a3/src/ts/gcd.ts#L11)
|
||||
[gcd.ts:11](https://github.com/juanelas/bigint-mod-arith/blob/75b3dcf/src/ts/gcd.ts#L11)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -217,7 +217,7 @@ The least common multiple of a and b
|
|||
|
||||
#### Defined in
|
||||
|
||||
[lcm.ts:11](https://github.com/juanelas/bigint-mod-arith/blob/06b32a3/src/ts/lcm.ts#L11)
|
||||
[lcm.ts:11](https://github.com/juanelas/bigint-mod-arith/blob/75b3dcf/src/ts/lcm.ts#L11)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -242,7 +242,7 @@ Maximum of numbers a and b
|
|||
|
||||
#### Defined in
|
||||
|
||||
[max.ts:9](https://github.com/juanelas/bigint-mod-arith/blob/06b32a3/src/ts/max.ts#L9)
|
||||
[max.ts:9](https://github.com/juanelas/bigint-mod-arith/blob/75b3dcf/src/ts/max.ts#L9)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -267,7 +267,7 @@ Minimum of numbers a and b
|
|||
|
||||
#### Defined in
|
||||
|
||||
[min.ts:9](https://github.com/juanelas/bigint-mod-arith/blob/06b32a3/src/ts/min.ts#L9)
|
||||
[min.ts:9](https://github.com/juanelas/bigint-mod-arith/blob/75b3dcf/src/ts/min.ts#L9)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -292,7 +292,7 @@ The smallest positive integer that is congruent with (a_1 + ... + a_r) mod n
|
|||
|
||||
#### Defined in
|
||||
|
||||
[modAdd.ts:9](https://github.com/juanelas/bigint-mod-arith/blob/06b32a3/src/ts/modAdd.ts#L9)
|
||||
[modAdd.ts:9](https://github.com/juanelas/bigint-mod-arith/blob/75b3dcf/src/ts/modAdd.ts#L9)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -321,7 +321,7 @@ The inverse modulo n
|
|||
|
||||
#### Defined in
|
||||
|
||||
[modInv.ts:14](https://github.com/juanelas/bigint-mod-arith/blob/06b32a3/src/ts/modInv.ts#L14)
|
||||
[modInv.ts:14](https://github.com/juanelas/bigint-mod-arith/blob/75b3dcf/src/ts/modInv.ts#L14)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -347,7 +347,7 @@ The smallest positive integer that is congruent with (a_1 * ... * a_r) mod n
|
|||
|
||||
#### Defined in
|
||||
|
||||
[modMultiply.ts:9](https://github.com/juanelas/bigint-mod-arith/blob/06b32a3/src/ts/modMultiply.ts#L9)
|
||||
[modMultiply.ts:9](https://github.com/juanelas/bigint-mod-arith/blob/75b3dcf/src/ts/modMultiply.ts#L9)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -378,7 +378,7 @@ b**e mod n
|
|||
|
||||
#### Defined in
|
||||
|
||||
[modPow.ts:22](https://github.com/juanelas/bigint-mod-arith/blob/06b32a3/src/ts/modPow.ts#L22)
|
||||
[modPow.ts:22](https://github.com/juanelas/bigint-mod-arith/blob/75b3dcf/src/ts/modPow.ts#L22)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -402,7 +402,7 @@ phi((p1**k1)*(p2**k2)*...*(pr**kr))
|
|||
|
||||
#### Defined in
|
||||
|
||||
[phi.ts:9](https://github.com/juanelas/bigint-mod-arith/blob/06b32a3/src/ts/phi.ts#L9)
|
||||
[phi.ts:9](https://github.com/juanelas/bigint-mod-arith/blob/75b3dcf/src/ts/phi.ts#L9)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -435,4 +435,4 @@ A bigint with the smallest positive representation of a modulo n
|
|||
|
||||
#### Defined in
|
||||
|
||||
[toZn.ts:14](https://github.com/juanelas/bigint-mod-arith/blob/06b32a3/src/ts/toZn.ts#L14)
|
||||
[toZn.ts:14](https://github.com/juanelas/bigint-mod-arith/blob/75b3dcf/src/ts/toZn.ts#L14)
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@
|
|||
|
||||
#### Defined in
|
||||
|
||||
[egcd.ts:2](https://github.com/juanelas/bigint-mod-arith/blob/06b32a3/src/ts/egcd.ts#L2)
|
||||
[egcd.ts:2](https://github.com/juanelas/bigint-mod-arith/blob/75b3dcf/src/ts/egcd.ts#L2)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -26,7 +26,7 @@ ___
|
|||
|
||||
#### Defined in
|
||||
|
||||
[egcd.ts:3](https://github.com/juanelas/bigint-mod-arith/blob/06b32a3/src/ts/egcd.ts#L3)
|
||||
[egcd.ts:3](https://github.com/juanelas/bigint-mod-arith/blob/75b3dcf/src/ts/egcd.ts#L3)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -36,4 +36,4 @@ ___
|
|||
|
||||
#### Defined in
|
||||
|
||||
[egcd.ts:4](https://github.com/juanelas/bigint-mod-arith/blob/06b32a3/src/ts/egcd.ts#L4)
|
||||
[egcd.ts:4](https://github.com/juanelas/bigint-mod-arith/blob/75b3dcf/src/ts/egcd.ts#L4)
|
||||
|
|
|
|||
Loading…
Reference in New Issue