**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:
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`
#### `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.
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)
[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)
#### `toJSNumber()`
Converts a bigInt into a native Javascript number. Loses precision for numbers outside the range `[-9007199254740992, 9007199254740992]`.
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).
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(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/).
