LumeWeb
/
bigint-mod-arith
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

better documentation

This commit is contained in:
juanelas 2020-04-08 11:53:15 +02:00
parent a98bcbf7a9
commit 6511d95cb6
10 changed files with 126 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
README.md
View File

@ -17,7 +17,7 @@ npm install bigint-mod-arith
``` ```
NPM installation defaults to the ES6 module for browsers and the CJS one for Node.js. NPM installation defaults to the ES6 module for browsers and the CJS one for Node.js.
For web browsers, you can also directly download the [IIFE bundle](https://raw.githubusercontent.com/juanelas/bigint-mod-arith/master/lib/index.browser.bundle.js) or the [ES6 bundle module](https://raw.githubusercontent.com/juanelas/bigint-mod-arith/master/lib/index.browser.bundle.mod.js) from GitHub. For web browsers, you can also directly download the [IIFE bundle](https://raw.githubusercontent.com/juanelas/bigint-mod-arith/master/lib/index.browser.bundle.iife.js) or the [ES6 bundle module](https://raw.githubusercontent.com/juanelas/bigint-mod-arith/master/lib/index.browser.bundle.mod.js) from GitHub.
## Usage example ## Usage example
@ -28,15 +28,16 @@ Import your module as :
const bigintModArith = require('bigint-mod-arith') const bigintModArith = require('bigint-mod-arith')
... // your code here ... // your code here
``` ```
- JavaScript native project - JavaScript native or TypeScript project
```javascript ```javascript
import * as bigintModArith from 'bigint-mod-arith' import * as bigintModArith from 'bigint-mod-arith'
... // your code here ... // your code here
``` ```
> BigInt is [ES-2020](https://tc39.es/ecma262/#sec-bigint-objects). In order to use it with TypeScript you should set `lib` (and probably also `target` and `module`) to `esnext` in `tsconfig.json`.
- JavaScript native browser ES6 mod - JavaScript native browser ES6 mod
```html ```html
<script type="module"> <script type="module">
import * as bigintModArith from 'lib/index.browser.bundle.mod.js' // Use you actual path to the browser mod bundle import * as bigintModArith from 'lib/index.browser.bundle.mod.js' // Use you actual path to the broser mod bundle
... // your code here ... // your code here
</script> </script>
``` ```
@ -46,12 +47,9 @@ Import your module as :
<script> <script>
... // your code here ... // your code here
</script> </script>
- TypeScript
```typescript
import * as bigintModArith from 'bigint-mod-arith'
... // your code here
``` ```
> BigInt is [ES-2020](https://tc39.es/ecma262/#sec-bigint-objects). In order to use it with TypeScript you should set `lib` (and probably also `target` and `module`) to `esnext` in `tsconfig.json`.
And you could use it like in the following:
```javascript ```javascript
/* Stage 3 BigInts with value 666 can be declared as BigInt('666') /* Stage 3 BigInts with value 666 can be declared as BigInt('666')
@ -74,50 +72,69 @@ console.log(bigintModArith.modInv(BigInt('3'), BigInt('5'))) // prints 2
## API reference documentation ## API reference documentation
<a name="abs"></a> <a name="module_bigint-mod-arith"></a>
### abs(a) ⇒ <code>bigint</code> ### bigint-mod-arith
Some common functions for modular arithmetic using native JS implementation of BigInt
* [bigint-mod-arith](#module_bigint-mod-arith)
* [~abs(a)](#module_bigint-mod-arith..abs) ⇒ <code>bigint</code>
* [~bitLength(a)](#module_bigint-mod-arith..bitLength) ⇒ <code>number</code>
* [~eGcd(a, b)](#module_bigint-mod-arith..eGcd) ⇒ <code>egcdReturn</code>
* [~gcd(a, b)](#module_bigint-mod-arith..gcd) ⇒ <code>bigint</code>
* [~lcm(a, b)](#module_bigint-mod-arith..lcm) ⇒ <code>bigint</code>
* [~max(a, b)](#module_bigint-mod-arith..max) ⇒ <code>bigint</code>
* [~min(a, b)](#module_bigint-mod-arith..min) ⇒ <code>bigint</code>
* [~modInv(a, n)](#module_bigint-mod-arith..modInv) ⇒ <code>bigint</code>
* [~modPow(b, e, n)](#module_bigint-mod-arith..modPow) ⇒ <code>bigint</code>
* [~toZn(a, n)](#module_bigint-mod-arith..toZn) ⇒ <code>bigint</code>
* [~egcdReturn](#module_bigint-mod-arith..egcdReturn) : <code>Object</code>
<a name="module_bigint-mod-arith..abs"></a>
#### bigint-mod-arith~abs(a) ⇒ <code>bigint</code>
Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0 Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0
**Kind**: global function **Kind**: inner method of [<code>bigint-mod-arith</code>](#module_bigint-mod-arith)
**Returns**: <code>bigint</code> - the absolute value of a **Returns**: <code>bigint</code> - the absolute value of a
| Param | Type | | Param | Type |
| --- | --- | | --- | --- |
| a | <code>number</code> \| <code>bigint</code> | | a | <code>number</code> \| <code>bigint</code> |
<a name="bitLength"></a> <a name="module_bigint-mod-arith..bitLength"></a>
### bitLength(a) ⇒ <code>number</code> #### bigint-mod-arith~bitLength(a) ⇒ <code>number</code>
Returns the bitlength of a number Returns the bitlength of a number
**Kind**: global function **Kind**: inner method of [<code>bigint-mod-arith</code>](#module_bigint-mod-arith)
**Returns**: <code>number</code> - - the bit length **Returns**: <code>number</code> - - the bit length
| Param | Type | | Param | Type |
| --- | --- | | --- | --- |
| a | <code>number</code> \| <code>bigint</code> | | a | <code>number</code> \| <code>bigint</code> |
<a name="eGcd"></a> <a name="module_bigint-mod-arith..eGcd"></a>
### eGcd(a, b) ⇒ [<code>egcdReturn</code>](#egcdReturn) #### bigint-mod-arith~eGcd(a, b) ⇒ <code>egcdReturn</code>
An iterative implementation of the extended euclidean algorithm or extended greatest common divisor algorithm. 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). Take positive integers a, b as input, and return a triple (g, x, y), such that ax + by = g = gcd(a, b).
**Kind**: global function **Kind**: inner method of [<code>bigint-mod-arith</code>](#module_bigint-mod-arith)
**Returns**: [<code>egcdReturn</code>](#egcdReturn) - A triple (g, x, y), such that ax + by = g = gcd(a, b). **Returns**: <code>egcdReturn</code> - A triple (g, x, y), such that ax + by = g = gcd(a, b).
| Param | Type | | Param | Type |
| --- | --- | | --- | --- |
| a | <code>number</code> \| <code>bigint</code> | | a | <code>number</code> \| <code>bigint</code> |
| b | <code>number</code> \| <code>bigint</code> | | b | <code>number</code> \| <code>bigint</code> |
<a name="gcd"></a> <a name="module_bigint-mod-arith..gcd"></a>
### gcd(a, b) ⇒ <code>bigint</code> #### bigint-mod-arith~gcd(a, b) ⇒ <code>bigint</code>
Greatest-common divisor of two integers based on the iterative binary algorithm. Greatest-common divisor of two integers based on the iterative binary algorithm.
**Kind**: global function **Kind**: inner method of [<code>bigint-mod-arith</code>](#module_bigint-mod-arith)
**Returns**: <code>bigint</code> - The greatest common divisor of a and b **Returns**: <code>bigint</code> - The greatest common divisor of a and b
| Param | Type | | Param | Type |
@ -125,12 +142,12 @@ Greatest-common divisor of two integers based on the iterative binary algorithm.
| a | <code>number</code> \| <code>bigint</code> | | a | <code>number</code> \| <code>bigint</code> |
| b | <code>number</code> \| <code>bigint</code> | | b | <code>number</code> \| <code>bigint</code> |
<a name="lcm"></a> <a name="module_bigint-mod-arith..lcm"></a>
### lcm(a, b) ⇒ <code>bigint</code> #### bigint-mod-arith~lcm(a, b) ⇒ <code>bigint</code>
The least common multiple computed as abs(a*b)/gcd(a,b) The least common multiple computed as abs(a*b)/gcd(a,b)
**Kind**: global function **Kind**: inner method of [<code>bigint-mod-arith</code>](#module_bigint-mod-arith)
**Returns**: <code>bigint</code> - The least common multiple of a and b **Returns**: <code>bigint</code> - The least common multiple of a and b
| Param | Type | | Param | Type |
@ -138,12 +155,12 @@ The least common multiple computed as abs(a*b)/gcd(a,b)
| a | <code>number</code> \| <code>bigint</code> | | a | <code>number</code> \| <code>bigint</code> |
| b | <code>number</code> \| <code>bigint</code> | | b | <code>number</code> \| <code>bigint</code> |
<a name="max"></a> <a name="module_bigint-mod-arith..max"></a>
### max(a, b) ⇒ <code>bigint</code> #### bigint-mod-arith~max(a, b) ⇒ <code>bigint</code>
Maximum. max(a,b)==a if a>=b. max(a,b)==b if a<=b Maximum. max(a,b)==a if a>=b. max(a,b)==b if a<=b
**Kind**: global function **Kind**: inner method of [<code>bigint-mod-arith</code>](#module_bigint-mod-arith)
**Returns**: <code>bigint</code> - maximum of numbers a and b **Returns**: <code>bigint</code> - maximum of numbers a and b
| Param | Type | | Param | Type |
@ -151,12 +168,12 @@ Maximum. max(a,b)==a if a>=b. max(a,b)==b if a<=b
| a | <code>number</code> \| <code>bigint</code> | | a | <code>number</code> \| <code>bigint</code> |
| b | <code>number</code> \| <code>bigint</code> | | b | <code>number</code> \| <code>bigint</code> |
<a name="min"></a> <a name="module_bigint-mod-arith..min"></a>
### min(a, b) ⇒ <code>bigint</code> #### bigint-mod-arith~min(a, b) ⇒ <code>bigint</code>
Minimum. min(a,b)==b if a>=b. min(a,b)==a if a<=b Minimum. min(a,b)==b if a>=b. min(a,b)==a if a<=b
**Kind**: global function **Kind**: inner method of [<code>bigint-mod-arith</code>](#module_bigint-mod-arith)
**Returns**: <code>bigint</code> - minimum of numbers a and b **Returns**: <code>bigint</code> - minimum of numbers a and b
| Param | Type | | Param | Type |
@ -164,12 +181,12 @@ Minimum. min(a,b)==b if a>=b. min(a,b)==a if a<=b
| a | <code>number</code> \| <code>bigint</code> | | a | <code>number</code> \| <code>bigint</code> |
| b | <code>number</code> \| <code>bigint</code> | | b | <code>number</code> \| <code>bigint</code> |
<a name="modInv"></a> <a name="module_bigint-mod-arith..modInv"></a>
### modInv(a, n) ⇒ <code>bigint</code> #### bigint-mod-arith~modInv(a, n) ⇒ <code>bigint</code>
Modular inverse. Modular inverse.
**Kind**: global function **Kind**: inner method of [<code>bigint-mod-arith</code>](#module_bigint-mod-arith)
**Returns**: <code>bigint</code> - the inverse modulo n or NaN if it does not exist **Returns**: <code>bigint</code> - the inverse modulo n or NaN if it does not exist
| Param | Type | Description | | Param | Type | Description |
@ -177,12 +194,12 @@ Modular inverse.
| a | <code>number</code> \| <code>bigint</code> | The number to find an inverse for | | a | <code>number</code> \| <code>bigint</code> | The number to find an inverse for |
| n | <code>number</code> \| <code>bigint</code> | The modulo | | n | <code>number</code> \| <code>bigint</code> | The modulo |
<a name="modPow"></a> <a name="module_bigint-mod-arith..modPow"></a>
### modPow(b, e, n) ⇒ <code>bigint</code> #### bigint-mod-arith~modPow(b, e, n) ⇒ <code>bigint</code>
Modular exponentiation b**e mod n. Currently using the right-to-left binary method Modular exponentiation b**e mod n. Currently using the right-to-left binary method
**Kind**: global function **Kind**: inner method of [<code>bigint-mod-arith</code>](#module_bigint-mod-arith)
**Returns**: <code>bigint</code> - b**e mod n **Returns**: <code>bigint</code> - b**e mod n
| Param | Type | Description | | Param | Type | Description |
@ -191,12 +208,12 @@ Modular exponentiation b**e mod n. Currently using the right-to-left binary meth
| e | <code>number</code> \| <code>bigint</code> | exponent | | e | <code>number</code> \| <code>bigint</code> | exponent |
| n | <code>number</code> \| <code>bigint</code> | modulo | | n | <code>number</code> \| <code>bigint</code> | modulo |
<a name="toZn"></a> <a name="module_bigint-mod-arith..toZn"></a>
### toZn(a, n) ⇒ <code>bigint</code> #### bigint-mod-arith~toZn(a, n) ⇒ <code>bigint</code>
Finds the smallest positive element that is congruent to a in modulo n Finds the smallest positive element that is congruent to a in modulo n
**Kind**: global function **Kind**: inner method of [<code>bigint-mod-arith</code>](#module_bigint-mod-arith)
**Returns**: <code>bigint</code> - The smallest positive representation of a in modulo n **Returns**: <code>bigint</code> - The smallest positive representation of a in modulo n
| Param | Type | Description | | Param | Type | Description |
@ -204,12 +221,12 @@ Finds the smallest positive element that is congruent to a in modulo n
| a | <code>number</code> \| <code>bigint</code> | An integer | | a | <code>number</code> \| <code>bigint</code> | An integer |
| n | <code>number</code> \| <code>bigint</code> | The modulo | | n | <code>number</code> \| <code>bigint</code> | The modulo |
<a name="egcdReturn"></a> <a name="module_bigint-mod-arith..egcdReturn"></a>
### egcdReturn : <code>Object</code> #### bigint-mod-arith~egcdReturn : <code>Object</code>
A triple (g, x, y), such that ax + by = g = gcd(a, b). A triple (g, x, y), such that ax + by = g = gcd(a, b).
**Kind**: global typedef **Kind**: inner typedef of [<code>bigint-mod-arith</code>](#module_bigint-mod-arith)
**Properties** **Properties**
| Name | Type | | Name | Type |

26
build/build.docs.js
View File

@ -7,18 +7,34 @@ const pkgJson = require('../package.json')
const rootDir = path.join(__dirname, '..') const rootDir = path.join(__dirname, '..')
const template = path.join(rootDir, pkgJson.directories.src, 'doc', 'readme-template.md') function camelise (str) {
const input = path.join(rootDir, pkgJson.directories.lib, 'index.node.js') return str.replace(/-([a-z])/g,
function (m, w) {
return w.toUpperCase()
})
}
const templateFile = path.join(rootDir, pkgJson.directories.src, 'doc', 'readme-template.md')
const template = fs.readFileSync(templateFile, { encoding: 'UTF-8' })
.replace(/\{\{PKG_NAME\}\}/g, pkgJson.name)
.replace(/\{\{PKG_CAMELCASE\}\}/g, camelise(pkgJson.name))
.replace(/\{\{IIFE_BUNDLE\}\}/g, 'IIFE bundle')
.replace(/\{\{ESM_BUNDLE\}\}/g, 'ES6 bundle module')
const input = path.join(rootDir, pkgJson.browser)
// Let us replace bigint literals by standard numbers to avoid issues with bigint
const source = fs.readFileSync(input, { encoding: 'UTF-8' }).replace(/([0-9]+)n([,\s\n)])/g, '$1$2')
const options = { const options = {
source: fs.readFileSync(input, { encoding: 'UTF-8' }), // we need to use this instead of files in order to avoid issues with esnext features source,
template: fs.readFileSync(template, { encoding: 'UTF-8' }), template,
'heading-depth': 3, // The initial heading depth. For example, with a value of 2 the top-level markdown headings look like "## The heading" 'heading-depth': 3, // The initial heading depth. For example, with a value of 2 the top-level markdown headings look like "## The heading"
'global-index-format': 'none' // none, grouped, table, dl. 'global-index-format': 'none' // none, grouped, table, dl.
} }
jsdoc2md.clear().then(() => {
const readmeContents = jsdoc2md.renderSync(options) const readmeContents = jsdoc2md.renderSync(options)
const readmeFile = path.join(rootDir, 'README.md') const readmeFile = path.join(rootDir, 'README.md')
fs.writeFileSync(readmeFile, readmeContents) fs.writeFileSync(readmeFile, readmeContents)
})

24
build/rollup.config.js
View File

@ -12,7 +12,6 @@ const srcDir = path.join(rootDir, pkgJson.directories.src)
const dstDir = path.join(rootDir, pkgJson.directories.lib) const dstDir = path.join(rootDir, pkgJson.directories.lib)
function camelise (str) { function camelise (str) {
console.log('camelise', str)
return str.replace(/-([a-z])/g, return str.replace(/-([a-z])/g,
function (m, w) { function (m, w) {
return w.toUpperCase() return w.toUpperCase()
@ -25,12 +24,12 @@ const pkgCamelisedName = camelise(pkgName)
const input = path.join(srcDir, 'js', 'index.js') const input = path.join(srcDir, 'js', 'index.js')
module.exports = [ module.exports = [
{ // ESM native module { // Native JS
input: input, input: input,
output: [ output: [
{ {
file: path.join(dstDir, 'index.browser.mod.js'), file: path.join(rootDir, pkgJson.browser),
format: 'esm' format: 'es'
} }
], ],
plugins: [ plugins: [
@ -44,7 +43,7 @@ module.exports = [
input: input, input: input,
output: [ output: [
{ {
file: path.join(dstDir, 'index.browser.bundle.js'), file: path.join(dstDir, 'index.browser.bundle.iife.js'),
format: 'iife', format: 'iife',
name: pkgCamelisedName name: pkgCamelisedName
}, },
@ -60,23 +59,20 @@ module.exports = [
resolve({ resolve({
browser: true browser: true
}), }),
terser({ terser()
// mangle: false,
// compress: false
})
] ]
}, },
{ // Node { // Node
input: input, input: input,
output: {
file: path.join(rootDir, pkgJson.main),
format: 'cjs'
},
plugins: [ plugins: [
replace({ replace({
'process.browser': false 'process.browser': false
}) })
], ]
output: {
file: path.join(dstDir, 'index.node.js'),
format: 'cjs'
}
// external: ['bigint-crypto-utils'] // external: ['bigint-crypto-utils']
} }
] ]

0
lib/index.browser.bundle.js → lib/index.browser.bundle.iife.js
View File

5
lib/index.browser.mod.js
View File

@ -1,3 +1,8 @@
/**
* Some common functions for modular arithmetic using native JS implementation of BigInt
* @module bigint-mod-arith
*/
/** /**
* Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0 * Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0
* *

5
lib/index.node.js
View File

@ -2,6 +2,11 @@
Object.defineProperty(exports, '__esModule', { value: true }) Object.defineProperty(exports, '__esModule', { value: true })
/**
* Some common functions for modular arithmetic using native JS implementation of BigInt
* @module bigint-mod-arith
*/
/** /**
* Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0 * Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0
* *

4
package.json
View File

@ -1,7 +1,7 @@
{ {
"name": "bigint-mod-arith", "name": "bigint-mod-arith",
"version": "2.0.4", "version": "2.0.4",
"description": "Some additional common functions for modular arithmetics using native JS (stage 3) implementation of BigInt", "description": "Some common functions for modular arithmetic using native JS implementation of BigInt",
"keywords": [ "keywords": [
"modular arithmetics", "modular arithmetics",
"BigInt", "BigInt",
@ -49,7 +49,7 @@
], ],
"ignore": [ "ignore": [
"/test/browser/", "/test/browser/",
"/lib/index.browser.bundle.js", "/lib/index.browser.bundle.iife.js",
"/lib/index.browser.bundle.mod.js" "/lib/index.browser.bundle.mod.js"
] ]
}, },

19
src/doc/readme-template.md
View File

@ -17,7 +17,7 @@ npm install bigint-mod-arith
``` ```
NPM installation defaults to the ES6 module for browsers and the CJS one for Node.js. NPM installation defaults to the ES6 module for browsers and the CJS one for Node.js.
For web browsers, you can also directly download the [IIFE bundle](https://raw.githubusercontent.com/juanelas/bigint-mod-arith/master/lib/index.browser.bundle.js) or the [ES6 bundle module](https://raw.githubusercontent.com/juanelas/bigint-mod-arith/master/lib/index.browser.bundle.mod.js) from GitHub. For web browsers, you can also directly download the [IIFE bundle](https://raw.githubusercontent.com/juanelas/bigint-mod-arith/master/lib/index.browser.bundle.iife.js) or the [ES6 bundle module](https://raw.githubusercontent.com/juanelas/bigint-mod-arith/master/lib/index.browser.bundle.mod.js) from GitHub.
## Usage example ## Usage example
@ -25,18 +25,19 @@ Import your module as :
- Node.js - Node.js
```javascript ```javascript
const bigintModArith = require('bigint-mod-arith') const {{PKG_CAMELCASE}} = require('{{PKG_NAME}}')
... // your code here ... // your code here
``` ```
- JavaScript native project - JavaScript native or TypeScript project
```javascript ```javascript
import * as bigintModArith from 'bigint-mod-arith' import * as {{PKG_CAMELCASE}} from '{{PKG_NAME}}'
... // your code here ... // your code here
``` ```
> BigInt is [ES-2020](https://tc39.es/ecma262/#sec-bigint-objects). In order to use it with TypeScript you should set `lib` (and probably also `target` and `module`) to `esnext` in `tsconfig.json`.
- JavaScript native browser ES6 mod - JavaScript native browser ES6 mod
```html ```html
<script type="module"> <script type="module">
import * as bigintModArith from 'lib/index.browser.bundle.mod.js' // Use you actual path to the browser mod bundle import * as {{PKG_CAMELCASE}} from 'lib/index.browser.bundle.mod.js' // Use you actual path to the broser mod bundle
... // your code here ... // your code here
</script> </script>
``` ```
@ -47,12 +48,8 @@ Import your module as :
... // your code here ... // your code here
</script> </script>
``` ```
- TypeScript
```typescript And you could use it like in the following:
import * as bigintModArith from 'bigint-mod-arith'
... // your code here
```
> BigInt is [ES-2020](https://tc39.es/ecma262/#sec-bigint-objects). In order to use it with TypeScript you should set `lib` (and probably also `target` and `module`) to `esnext` in `tsconfig.json`.
```javascript ```javascript
/* Stage 3 BigInts with value 666 can be declared as BigInt('666') /* Stage 3 BigInts with value 666 can be declared as BigInt('666')

5
src/js/index.js
View File

@ -1,3 +1,8 @@
/**
* Some common functions for modular arithmetic using native JS implementation of BigInt
* @module bigint-mod-arith
*/
/** /**
* Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0 * Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0
* *

4
types/index.d.ts vendored
View File

@ -6,6 +6,10 @@ export type egcdReturn = {
x: bigint; x: bigint;
y: bigint; y: bigint;
}; };
/**
* Some common functions for modular arithmetic using native JS implementation of BigInt
* @module bigint-mod-arith
*/
/** /**
* Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0 * Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0
* *