github/cordova-android
4
0
Fork 1
mirror of https://github.com/apache/cordova-android.git synced 2026-02-21 00:02:46 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
a68f9fd752a25bb680da96414a3b956357c2dfcb
cordova-android/node_modules/big-integer/README.md
Christopher J. Brody 84cb08b23e Revert "Other minor dependencies updates in 7.1.x patch" 
This reverts commit 5a5f544a48.

Rationale: base64-js update in 5a5f544 causes extra
base64-js version to be installed under plist
(node_modules/plist/node_modules/base64-js),
which would need to be committed to satisfy the needs
of the deprecated Node.js 4 version.

The extra base64-js version in
node_modules/plist/node_modules/base64-js
was missed at the time 5a5f544 was committed.

The base64-js update in 5a5f544 is now deemed as
not wanted due to the extra base64-js version that
would need to be committed.

The other dependencies updates in 5a5f544
may be nice to have but not considered necessary
for the patch release.

Reverting now to unblock the upcoming 7.1.4 patch release.

Note that neither 5a5f544 nor this revert will
show up in the master branch.
2018-11-22 22:18:32 -05:00

571 lines
17 KiB
Markdown
Raw Blame History

# BigInteger.js [![Build Status][travis-img]][travis-url] [![Coverage Status][coveralls-img]][coveralls-url] [![Monthly Downloads][downloads-img]][downloads-url]
[travis-url]: https://travis-ci.org/peterolson/BigInteger.js
[travis-img]: https://travis-ci.org/peterolson/BigInteger.js.svg?branch=master
[coveralls-url]: https://coveralls.io/github/peterolson/BigInteger.js?branch=master
[coveralls-img]: https://coveralls.io/repos/peterolson/BigInteger.js/badge.svg?branch=master&service=github
[downloads-url]: https://www.npmjs.com/package/big-integer
[downloads-img]: https://img.shields.io/npm/dm/big-integer.svg
**BigInteger.js** is an arbitrary-length integer library for Javascript, allowing arithmetic operations on integers of unlimited size, notwithstanding memory and time limitations.
## Installation
If you are using a browser, you can download [BigInteger.js from GitHub](http://peterolson.github.com/BigInteger.js/BigInteger.min.js) or just hotlink to it:
<script src="http://peterolson.github.com/BigInteger.js/BigInteger.min.js"></script>
If you are using node, you can install BigInteger with [npm](https://npmjs.org/).
npm install big-integer
Then you can include it in your code:
var bigInt = require("big-integer");
## Usage
### `bigInt(number, [base])`
You can create a bigInt by calling the `bigInt` function. You can pass in
- a string, which it will parse as an bigInt and throw an `"Invalid integer"` error if the parsing fails.
- a Javascript number, which it will parse as an bigInt and throw an `"Invalid integer"` error if the parsing fails.
- another bigInt.
- nothing, and it will return `bigInt.zero`.
If you provide a second parameter, then it will parse `number` as a number in base `base`. Note that `base` can be any bigInt (even negative or zero). The letters "a-z" and "A-Z" will be interpreted as the numbers 10 to 35. Higher digits can be specified in angle brackets (`<` and `>`).
Examples:
var zero = bigInt();
var ninetyThree = bigInt(93);
var largeNumber = bigInt("75643564363473453456342378564387956906736546456235345");
var googol = bigInt("1e100");
var bigNumber = bigInt(largeNumber);
var maximumByte = bigInt("FF", 16);
var fiftyFiveGoogol = bigInt("<55>0", googol);
Note that Javascript numbers larger than `9007199254740992` and smaller than `-9007199254740992` are not precisely represented numbers and will not produce exact results. If you are dealing with numbers outside that range, it is better to pass in strings.
### Method Chaining
Note that bigInt operations return bigInts, which allows you to chain methods, for example:
var salary = bigInt(dollarsPerHour).times(hoursWorked).plus(randomBonuses)
### Constants
There are three named constants already stored that you do not have to construct with the `bigInt` function yourself:
- `bigInt.one`, equivalent to `bigInt(1)`
- `bigInt.zero`, equivalent to `bigInt(0)`
- `bigInt.minusOne`, equivalent to `bigInt(-1)`
The numbers from -999 to 999 are also already prestored and can be accessed using `bigInt[index]`, for example:
- `bigInt[-999]`, equivalent to `bigInt(-999)`
- `bigInt[256]`, equivalent to `bigInt(256)`
### Methods
#### `abs()`
Returns the absolute value of a bigInt.
- `bigInt(-45).abs()` => `45`
- `bigInt(45).abs()` => `45`
#### `add(number)`
Performs addition.
- `bigInt(5).add(7)` => `12`
[View benchmarks for this method](http://peterolson.github.io/BigInteger.js/benchmark/#Addition)
#### `and(number)`
Performs the bitwise AND operation. The operands are treated as if they were represented using [two's complement representation](http://en.wikipedia.org/wiki/Two%27s_complement).
- `bigInt(6).and(3)` => `2`
- `bigInt(6).and(-3)` => `4`
#### `bitLength()`
Returns the number of digits required to represent a bigInt in binary.
- `bigInt(5)` => `3` (since 5 is `101` in binary, which is three digits long)
#### `compare(number)`
Performs a comparison between two numbers. If the numbers are equal, it returns `0`. If the first number is greater, it returns `1`. If the first number is lesser, it returns `-1`.
- `bigInt(5).compare(5)` => `0`
- `bigInt(5).compare(4)` => `1`
- `bigInt(4).compare(5)` => `-1`
#### `compareAbs(number)`
Performs a comparison between the absolute value of two numbers.
- `bigInt(5).compareAbs(-5)` => `0`
- `bigInt(5).compareAbs(4)` => `1`
- `bigInt(4).compareAbs(-5)` => `-1`
#### `compareTo(number)`
Alias for the `compare` method.
#### `divide(number)`
Performs integer division, disregarding the remainder.
- `bigInt(59).divide(5)` => `11`
[View benchmarks for this method](http://peterolson.github.io/BigInteger.js/benchmark/#Division)
#### `divmod(number)`
Performs division and returns an object with two properties: `quotient` and `remainder`. The sign of the remainder will match the sign of the dividend.
- `bigInt(59).divmod(5)` => `{quotient: bigInt(11), remainder: bigInt(4) }`
- `bigInt(-5).divmod(2)` => `{quotient: bigInt(-2), remainder: bigInt(-1) }`
[View benchmarks for this method](http://peterolson.github.io/BigInteger.js/benchmark/#Division)
#### `eq(number)`
Alias for the `equals` method.
#### `equals(number)`
Checks if two numbers are equal.
- `bigInt(5).equals(5)` => `true`
- `bigInt(4).equals(7)` => `false`
#### `geq(number)`
Alias for the `greaterOrEquals` method.
#### `greater(number)`
Checks if the first number is greater than the second.
- `bigInt(5).greater(6)` => `false`
- `bigInt(5).greater(5)` => `false`
- `bigInt(5).greater(4)` => `true`
#### `greaterOrEquals(number)`
Checks if the first number is greater than or equal to the second.
- `bigInt(5).greaterOrEquals(6)` => `false`
- `bigInt(5).greaterOrEquals(5)` => `true`
- `bigInt(5).greaterOrEquals(4)` => `true`
#### `gt(number)`
Alias for the `greater` method.
#### `isDivisibleBy(number)`
Returns `true` if the first number is divisible by the second number, `false` otherwise.
- `bigInt(999).isDivisibleBy(333)` => `true`
- `bigInt(99).isDivisibleBy(5)` => `false`
#### `isEven()`
Returns `true` if the number is even, `false` otherwise.
- `bigInt(6).isEven()` => `true`
- `bigInt(3).isEven()` => `false`
#### `isNegative()`
Returns `true` if the number is negative, `false` otherwise.
Returns `false` for `0` and `-0`.
- `bigInt(-23).isNegative()` => `true`
- `bigInt(50).isNegative()` => `false`
#### `isOdd()`
Returns `true` if the number is odd, `false` otherwise.
- `bigInt(13).isOdd()` => `true`
- `bigInt(40).isOdd()` => `false`
#### `isPositive()`
Return `true` if the number is positive, `false` otherwise.
Returns `false` for `0` and `-0`.
- `bigInt(54).isPositive()` => `true`
- `bigInt(-1).isPositive()` => `false`
#### `isPrime()`
Returns `true` if the number is prime, `false` otherwise.
- `bigInt(5).isPrime()` => `true`
- `bigInt(6).isPrime()` => `false`
#### `isProbablePrime([iterations])`
Returns `true` if the number is very likely to be prime, `false` otherwise.
Argument is optional and determines the amount of iterations of the test (default: `5`). The more iterations, the lower chance of getting a false positive.
This uses the [Fermat primality test](https://en.wikipedia.org/wiki/Fermat_primality_test).
- `bigInt(5).isProbablePrime()` => `true`
- `bigInt(49).isProbablePrime()` => `false`
- `bigInt(1729).isProbablePrime(50)` => `false`
Note that this function is not deterministic, since it relies on random sampling of factors, so the result for some numbers is not always the same. [Carmichael numbers](https://en.wikipedia.org/wiki/Carmichael_number) are particularly prone to give unreliable results.
For example, `bigInt(1729).isProbablePrime()` returns `false` about 76% of the time and `true` about 24% of the time. The correct result is `false`.
#### `isUnit()`
Returns `true` if the number is `1` or `-1`, `false` otherwise.
- `bigInt.one.isUnit()` => `true`
- `bigInt.minusOne.isUnit()` => `true`
- `bigInt(5).isUnit()` => `false`
#### `isZero()`
Return `true` if the number is `0` or `-0`, `false` otherwise.
- `bigInt.zero.isZero()` => `true`
- `bigInt("-0").isZero()` => `true`
- `bigInt(50).isZero()` => `false`
#### `leq(number)`
Alias for the `lesserOrEquals` method.
#### `lesser(number)`
Checks if the first number is lesser than the second.
- `bigInt(5).lesser(6)` => `true`
- `bigInt(5).lesser(5)` => `false`
- `bigInt(5).lesser(4)` => `false`
#### `lesserOrEquals(number)`
Checks if the first number is less than or equal to the second.
- `bigInt(5).lesserOrEquals(6)` => `true`
- `bigInt(5).lesserOrEquals(5)` => `true`
- `bigInt(5).lesserOrEquals(4)` => `false`
#### `lt(number)`
Alias for the `lesser` method.
#### `minus(number)`
Alias for the `subtract` method.
- `bigInt(3).minus(5)` => `-2`
[View benchmarks for this method](http://peterolson.github.io/BigInteger.js/benchmark/#Subtraction)
#### `mod(number)`
Performs division and returns the remainder, disregarding the quotient. The sign of the remainder will match the sign of the dividend.
- `bigInt(59).mod(5)` => `4`
- `bigInt(-5).mod(2)` => `-1`
[View benchmarks for this method](http://peterolson.github.io/BigInteger.js/benchmark/#Division)
#### `modInv(mod)`
Finds the [multiplicative inverse](https://en.wikipedia.org/wiki/Modular_multiplicative_inverse) of the number modulo `mod`.
- `bigInt(3).modInv(11)` => `4`
- `bigInt(42).modInv(2017)` => `1969`
#### `modPow(exp, mod)`
Takes the number to the power `exp` modulo `mod`.
- `bigInt(10).modPow(3, 30)` => `10`
#### `multiply(number)`
Performs multiplication.
- `bigInt(111).multiply(111)` => `12321`
[View benchmarks for this method](http://peterolson.github.io/BigInteger.js/benchmark/#Multiplication)
#### `neq(number)`
Alias for the `notEquals` method.
#### `next()`
Adds one to the number.
- `bigInt(6).next()` => `7`
#### `not()`
Performs the bitwise NOT operation. The operands are treated as if they were represented using [two's complement representation](http://en.wikipedia.org/wiki/Two%27s_complement).
- `bigInt(10).not()` => `-11`
- `bigInt(0).not()` => `-1`
#### `notEquals(number)`
Checks if two numbers are not equal.
- `bigInt(5).notEquals(5)` => `false`
- `bigInt(4).notEquals(7)` => `true`
#### `or(number)`
Performs the bitwise OR operation. The operands are treated as if they were represented using [two's complement representation](http://en.wikipedia.org/wiki/Two%27s_complement).
- `bigInt(13).or(10)` => `15`
- `bigInt(13).or(-8)` => `-3`
#### `over(number)`
Alias for the `divide` method.
- `bigInt(59).over(5)` => `11`
[View benchmarks for this method](http://peterolson.github.io/BigInteger.js/benchmark/#Division)
#### `plus(number)`
Alias for the `add` method.
- `bigInt(5).plus(7)` => `12`
[View benchmarks for this method](http://peterolson.github.io/BigInteger.js/benchmark/#Addition)
#### `pow(number)`
Performs exponentiation. If the exponent is less than `0`, `pow` returns `0`. `bigInt.zero.pow(0)` returns `1`.
- `bigInt(16).pow(16)` => `18446744073709551616`
[View benchmarks for this method](http://peterolson.github.io/BigInteger.js/benchmark/#Exponentiation)
#### `prev(number)`
Subtracts one from the number.
- `bigInt(6).prev()` => `5`
#### `remainder(number)`
Alias for the `mod` method.
[View benchmarks for this method](http://peterolson.github.io/BigInteger.js/benchmark/#Division)
#### `shiftLeft(n)`
Shifts the number left by `n` places in its binary representation. If a negative number is provided, it will shift right. Throws an error if `n` is outside of the range `[-9007199254740992, 9007199254740992]`.
- `bigInt(8).shiftLeft(2)` => `32`
- `bigInt(8).shiftLeft(-2)` => `2`
#### `shiftRight(n)`
Shifts the number right by `n` places in its binary representation. If a negative number is provided, it will shift left. Throws an error if `n` is outside of the range `[-9007199254740992, 9007199254740992]`.
- `bigInt(8).shiftRight(2)` => `2`
- `bigInt(8).shiftRight(-2)` => `32`
#### `square()`
Squares the number
- `bigInt(3).square()` => `9`
[View benchmarks for this method](http://peterolson.github.io/BigInteger.js/benchmark/#Squaring)
#### `subtract(number)`
Performs subtraction.
- `bigInt(3).subtract(5)` => `-2`
[View benchmarks for this method](http://peterolson.github.io/BigInteger.js/benchmark/#Subtraction)
#### `times(number)`
Alias for the `multiply` method.
- `bigInt(111).times(111)` => `12321`
[View benchmarks for this method](http://peterolson.github.io/BigInteger.js/benchmark/#Multiplication)
#### `toArray(radix)`
Converts a bigInt into an object with the properties "value" and "isNegative." "Value" is an array of integers modulo the given radix. "isNegative" is a boolean that represents the sign of the result.
- `bigInt("1e9").toArray(10)` => {
value: [1, 0, 0, 0, 0, 0, 0, 0, 0, 0],
isNegative: false
}
- `bigInt("1e9").toArray(16)` => {
value: [3, 11, 9, 10, 12, 10, 0, 0],
isNegative: false
}
- `bigInt(567890).toArray(100)` => {
value: [56, 78, 90],
isNegative: false
}
Negative bases are supported.
- `bigInt(12345).toArray(-10)` => {
value: [2, 8, 4, 6, 5],
isNegative: false
}
Base 1 and base -1 are also supported.
- `bigInt(-15).toArray(1)` => {
value: [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
isNegative: true
}
- `bigInt(-15).toArray(-1)` => {
value: [1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1,
0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0],
isNegative: false
}
Base 0 is only allowed for the number zero.
- `bigInt(0).toArray(0)` => {
value: [0],
isNegative: false
}
- `bigInt(1).toArray(0)` => `Error: Cannot convert nonzero numbers to base 0.`
#### `toJSNumber()`
Converts a bigInt into a native Javascript number. Loses precision for numbers outside the range `[-9007199254740992, 9007199254740992]`.
- `bigInt("18446744073709551616").toJSNumber()` => `18446744073709552000`
#### `xor(number)`
Performs the bitwise XOR operation. The operands are treated as if they were represented using [two's complement representation](http://en.wikipedia.org/wiki/Two%27s_complement).
- `bigInt(12).xor(5)` => `9`
- `bigInt(12).xor(-5)` => `-9`
### Static Methods
#### `fromArray(digits, base = 10, isNegative?)`
Constructs a bigInt from an array of digits in base `base`. The optional `isNegative` flag will make the number negative.
- `bigInt.fromArray([1, 2, 3, 4, 5], 10)` => `12345`
- `bigInt.fromArray([1, 0, 0], 2, true)` => `-4`
#### `gcd(a, b)`
Finds the greatest common denominator of `a` and `b`.
- `bigInt.gcd(42,56)` => `14`
#### `isInstance(x)`
Returns `true` if `x` is a BigInteger, `false` otherwise.
- `bigInt.isInstance(bigInt(14))` => `true`
- `bigInt.isInstance(14)` => `false`
#### `lcm(a,b)`
Finds the least common multiple of `a` and `b`.
- `bigInt.lcm(21, 6)` => `42`
#### `max(a,b)`
Returns the largest of `a` and `b`.
- `bigInt.max(77, 432)` => `432`
#### `min(a,b)`
Returns the smallest of `a` and `b`.
- `bigInt.min(77, 432)` => `77`
#### `randBetween(min, max)`
Returns a random number between `min` and `max`.
- `bigInt.randBetween("-1e100", "1e100")` => (for example) `8494907165436643479673097939554427056789510374838494147955756275846226209006506706784609314471378745`
### Override Methods
#### `toString(radix = 10)`
Converts a bigInt to a string. There is an optional radix parameter (which defaults to 10) that converts the number to the given radix. Digits in the range `10-35` will use the letters `a-z`.
- `bigInt("1e9").toString()` => `"1000000000"`
- `bigInt("1e9").toString(16)` => `"3b9aca00"`
**Note that arithmetical operators will trigger the `valueOf` function rather than the `toString` function.** When converting a bigInteger to a string, you should use the `toString` method or the `String` function instead of adding the empty string.
- `bigInt("999999999999999999").toString()` => `"999999999999999999"`
- `String(bigInt("999999999999999999"))` => `"999999999999999999"`
- `bigInt("999999999999999999") + ""` => `1000000000000000000`
Bases larger than 36 are supported. If a digit is greater than or equal to 36, it will be enclosed in angle brackets.
- `bigInt(567890).toString(100)` => `"<56><78><90>"`
Negative bases are also supported.
- `bigInt(12345).toString(-10)` => `"28465"`
Base 1 and base -1 are also supported.
- `bigInt(-15).toString(1)` => `"-111111111111111"`
- `bigInt(-15).toString(-1)` => `"101010101010101010101010101010"`
Base 0 is only allowed for the number zero.
- `bigInt(0).toString(0)` => `0`
- `bigInt(1).toString(0)` => `Error: Cannot convert nonzero numbers to base 0.`
[View benchmarks for this method](http://peterolson.github.io/BigInteger.js/benchmark/#toString)
#### `valueOf()`
Converts a bigInt to a native Javascript number. This override allows you to use native arithmetic operators without explicit conversion:
- `bigInt("100") + bigInt("200") === 300; //true`
## Contributors
To contribute, just fork the project, make some changes, and submit a pull request. Please verify that the unit tests pass before submitting.
The unit tests are contained in the `spec/spec.js` file. You can run them locally by opening the `spec/SpecRunner.html` or file or running `npm test`. You can also [run the tests online from GitHub](http://peterolson.github.io/BigInteger.js/spec/SpecRunner.html).
There are performance benchmarks that can be viewed from the `benchmarks/index.html` page. You can [run them online from GitHub](http://peterolson.github.io/BigInteger.js/benchmark/).
## License
This project is public domain. For more details, read about the [Unlicense](http://unlicense.org/).
Reference in New Issue View Git Blame Copy Permalink