BigInteger

An arbitrarily-large integer.

BigInteger objects should be considered immutable.  None of the “built-in” methods modify this or their arguments.  All properties should be considered private.

All the methods of BigInteger instances can be called “statically”.  The static versions are convenient if you don’t already have a BigInteger object.

As an example, these calls are equivalent.

BigInteger(4).multiply(5); // returns BigIngeger(20);
BigInteger.multiply(4, 5); // returns BigInteger(20);
var a = 42;
var a = BigInteger.toJSValue("0b101010"); // Not completely useless...
Summary
BigIntegerAn arbitrarily-large integer.
Functions
BigInteger()Convert a value to a BigInteger.
Constants
ZEROBigInteger 0.
ONEBigInteger 1.
M_ONEBigInteger -1.
_0Shortcut for ZERO.
_1Shortcut for ONE.
smallArray of BigIntegers from 0 to 36.
Functions
toStringConvert a BigInteger to a string.
parseParse a string into a BigInteger.
addAdd two BigIntegers.
negateGet the additive inverse of a BigInteger.
absGet the absolute value of a BigInteger.
subtractSubtract two BigIntegers.
nextGet the next BigInteger (add one).
prevGet the previous BigInteger (subtract one).
compareAbsCompare the absolute value of two BigIntegers.
compareCompare two BigIntegers.
isUnitReturn true iff this is either 1 or -1.
multiplyMultiply two BigIntegers.
squareMultiply a BigInteger by itself.
divideDivide two BigIntegers.
remainderCalculate the remainder of two BigIntegers.
divRemCalculate the integer quotient and remainder of two BigIntegers.
isEvenReturn true iff this is divisible by two.
isOddReturn true iff this is not divisible by two.
signGet the sign of a BigInteger.
isPositiveReturn true iff this > 0.
isNegativeReturn true iff this < 0.
isZeroReturn true iff this == 0.
exp10Multiply a BigInteger by a power of 10.
powRaise a BigInteger to a power.
modPowRaise a BigInteger to a power (mod m).
valueOfConvert a BigInteger to a native JavaScript integer.
toJSValueConvert a BigInteger to a native JavaScript integer.
Constants
MAX_EXPThe largest exponent allowed in pow and exp10 (0x7FFFFFFF or 2147483647).

Functions

BigInteger()

function BigInteger(n,
s)

Convert a value to a BigInteger.

Although BigInteger() is the constructor for BigInteger objects, it is best not to call it as a constructor.  If n is a BigInteger object, it is simply returned as-is.  Otherwise, BigInteger() is equivalent to parse without a radix argument.

var n0 = BigInteger();      // Same as <BigInteger.ZERO>
var n1 = BigInteger("123"); // Create a new <BigInteger> with value 123
var n2 = BigInteger(123);   // Create a new <BigInteger> with value 123
var n3 = BigInteger(n2);    // Return n2, unchanged

The constructor form only takes an array and a sign.  n must be an array of numbers in little-endian order, where each digit is between 0 and 9 inclusive.  A second parameter sets the sign: -1 for negative, +1 for positive, or 0 for zero.  The array is not copied and may be modified.  If the array contains only zeros, the sign parameter is ignored and is forced to zero.

new BigInteger([3,2,1], -1): create a new BigInteger with value -123

Parameters

nValue to convert to a BigInteger.

Returns

A BigInteger value.

See Also

parse, BigInteger

Constants

ZERO

M_ONE

_0

Shortcut for ZERO.

_1

Shortcut for ONE.

small

Array of BigIntegers from 0 to 36.

These are used internally for parsing, but useful when you need a “small” BigInteger.

See Also

ZERO, ONE, _0, _1

Functions

toString

BigInteger.prototype.toString = function(base)

Convert a BigInteger to a string.

When base is greater than 10, letters are upper case.

Parameters

baseOptional base to represent the number in (default is base 10).  Must be between 2 and 36 inclusive, or an Error will be thrown.

Returns

The string representation of the BigInteger.

parse

BigInteger.parse = function(s,
base)

Parse a string into a BigInteger.

base is optional but, if provided, must be from 2 to 36 inclusive.  If base is not provided, it will be guessed based on the leading characters of s as follows:

  • ”0x” or “0X”: base = 16
  • ”0b” or “0B”: base = 2
  • ”0”: base = 8
  • else: base = 10

If no base is provided, or base is 10, the number can be in exponential form.  For example, these are all valid:

BigInteger.parse("1e9");              // Same as "1000000000"
BigInteger.parse("1.234*10^3");       // Same as 1234
BigInteger.parse("56789 * 10 ** -2"); // Same as 567

If any characters fall outside the range defined by the radix, an exception will be thrown.

Parameters

sThe string to parse.
baseOptional radix (default is to guess based on s).

Returns

a BigInteger instance.

add

BigInteger.prototype.add = function(n)

Add two BigIntegers.

Parameters

nThe number to add to this.  Will be converted to a BigInteger.

Returns

The numbers added together.

See Also

subtract, multiply, divide, next

negate

BigInteger.prototype.negate = function()

Get the additive inverse of a BigInteger.

Returns

A BigInteger with the same magnatude, but with the opposite sign.

See Also

abs

abs

BigInteger.prototype.abs = function()

Get the absolute value of a BigInteger.

Returns

A BigInteger with the same magnatude, but always positive (or zero).

See Also

negate

subtract

BigInteger.prototype.subtract = function(n)

Subtract two BigIntegers.

Parameters

nThe number to subtract from this.  Will be converted to a BigInteger.

Returns

The n subtracted from this.

See Also

add, multiply, divide, prev

next

BigInteger.prototype.next = function()

Get the next BigInteger (add one).

Returns

this + 1.

See Also

add, prev

prev

BigInteger.prototype.prev = function()

Get the previous BigInteger (subtract one).

Returns

*this*1.

See Also

next, subtract

compareAbs

BigInteger.prototype.compareAbs = function(n)

Compare the absolute value of two BigIntegers.

Calling compareAbs is faster than calling abs twice, then compare.

Parameters

nThe number to compare to this.  Will be converted to a BigInteger.

Returns

-1, 0, or +1 if |this| is less than, equal to, or greater than |n|.

See Also

compare, abs

compare

BigInteger.prototype.compare = function(n)

Compare two BigIntegers.

Parameters

nThe number to compare to this.  Will be converted to a BigInteger.

Returns

-1, 0, or +1 if this is less than, equal to, or greater than n.

See Also

compareAbs, isPositive, isNegative, isUnit

isUnit

BigInteger.prototype.isUnit = function()

Return true iff this is either 1 or -1.

Returns

true if this compares equal to BigInteger.ONE or BigInteger.M_ONE.

See Also

isZero, isNegative, isPositive, compareAbs, compare, BigInteger.ONE, BigInteger.M_ONE

multiply

BigInteger.prototype.multiply = function(n)

Multiply two BigIntegers.

Parameters

nThe number to multiply this by.  Will be converted to a BigInteger.

Returns

The numbers multiplied together.

See Also

add, subtract, divide, square

square

BigInteger.prototype.square = function()

Multiply a BigInteger by itself.

This is slightly faster than regular multiplication, since it removes the duplicated multiplcations.

Returns

this.multiply(this)

See Also

multiply

divide

BigInteger.prototype.divide = function(n)

Divide two BigIntegers.

divide throws an exception if n is zero.

Parameters

nThe number to divide this by.  Will be converted to a BigInteger.

Returns

The this / n, truncated to an integer.

See Also

add, subtract, multiply, divRem, remainder

remainder

BigInteger.prototype.remainder = function(n)

Calculate the remainder of two BigIntegers.

remainder throws an exception if n is zero.

Parameters

nThe remainder after this is divided this by n.  Will be converted to a BigInteger.

Returns

this % n.

See Also

divRem, divide

divRem

BigInteger.prototype.divRem = function(n)

Calculate the integer quotient and remainder of two BigIntegers.

divRem throws an exception if n is zero.

Parameters

nThe number to divide this by.  Will be converted to a BigInteger.

Returns

A two-element array containing the quotient and the remainder.

a.divRem(b)

is exactly equivalent to

[a.divide(b), a.remainder(b)]

except it is faster, because they are calculated at the same time.

See Also

divide, remainder

isEven

BigInteger.prototype.isEven = function()

Return true iff this is divisible by two.

Note that BigInteger.ZERO is even.

Returns

true if this is even, false otherwise.

See Also

isOdd

isOdd

BigInteger.prototype.isOdd = function()

Return true iff this is not divisible by two.

Returns

true if this is odd, false otherwise.

See Also

isEven

sign

BigInteger.prototype.sign = function()

Get the sign of a BigInteger.

Returns

  • -1 if this < 0
  • 0 if this == 0
  • +1 if this > 0

See Also

isZero, isPositive, isNegative, compare, BigInteger.ZERO

isPositive

BigInteger.prototype.isPositive = function()

Return true iff this > 0.

Returns

true if this.compare(BigInteger.ZERO) == 1.

See Also

sign, isZero, isNegative, isUnit, compare, BigInteger.ZERO

isNegative

BigInteger.prototype.isNegative = function()

Return true iff this < 0.

Returns

true if this.compare(BigInteger.ZERO) == -1.

See Also

sign, isPositive, isZero, isUnit, compare, BigInteger.ZERO

isZero

BigInteger.prototype.isZero = function()

Return true iff this == 0.

Returns

true if this.compare(BigInteger.ZERO) == 0.

See Also

sign, isPositive, isNegative, isUnit, BigInteger.ZERO

exp10

BigInteger.prototype.exp10 = function(n)

Multiply a BigInteger by a power of 10.

This is equivalent to, but faster than

if (n >= 0) {
    return this.multiply(BigInteger("1e" + n));
}
else { // n <= 0
    return this.divide(BigInteger("1e" + -n));
}

Parameters

nThe power of 10 to multiply this by.  n is converted to a javascipt number and must be no greater than BigInteger.MAX_EXP (0x7FFFFFFF), or an exception will be thrown.

Returns

this * (10 ** n), truncated to an integer if necessary.

See Also

pow, multiply

pow

BigInteger.prototype.pow = function(n)

Raise a BigInteger to a power.

In this implementation, 0**0 is 1.

Parameters

nThe exponent to raise this by.  n must be no greater than BigInteger.MAX_EXP (0x7FFFFFFF), or an exception will be thrown.

Returns

this raised to the nth power.

See Also

modPow

modPow

BigInteger.prototype.modPow = function(exponent,
modulus)

Raise a BigInteger to a power (mod m).

Because it is reduced by a modulus, modPow is not limited by BigInteger.MAX_EXP like pow.

Parameters

exponentThe exponent to raise this by.  Must be positive.
modulusThe modulus.

Returns

this ^ exponent (mod modulus).

See Also

pow, <mod>

valueOf

BigInteger.prototype.valueOf = function()

Convert a BigInteger to a native JavaScript integer.

This is called automatically by JavaScipt to convert a BigInteger to a native value.

Returns

parseInt(this.toString(), 10)

See Also

toString, toJSValue

toJSValue

BigInteger.prototype.toJSValue = function()

Convert a BigInteger to a native JavaScript integer.

This is the same as valueOf, but more explicitly named.

Returns

parseInt(this.toString(), 10)

See Also

toString, valueOf

Constants

MAX_EXP

The largest exponent allowed in pow and exp10 (0x7FFFFFFF or 2147483647).

function BigInteger(n,
s)
Convert a value to a BigInteger.
BigInteger 0.
BigInteger 1.
BigInteger.prototype.toString = function(base)
Convert a BigInteger to a string.
BigInteger.parse = function(s,
base)
Parse a string into a BigInteger.
BigInteger.prototype.add = function(n)
Add two BigIntegers.
BigInteger.prototype.negate = function()
Get the additive inverse of a BigInteger.
BigInteger.prototype.abs = function()
Get the absolute value of a BigInteger.
BigInteger.prototype.subtract = function(n)
Subtract two BigIntegers.
BigInteger.prototype.next = function()
Get the next BigInteger (add one).
BigInteger.prototype.prev = function()
Get the previous BigInteger (subtract one).
BigInteger.prototype.compareAbs = function(n)
Compare the absolute value of two BigIntegers.
BigInteger.prototype.compare = function(n)
Compare two BigIntegers.
BigInteger.prototype.isUnit = function()
Return true iff this is either 1 or -1.
BigInteger.prototype.multiply = function(n)
Multiply two BigIntegers.
BigInteger.prototype.square = function()
Multiply a BigInteger by itself.
BigInteger.prototype.divide = function(n)
Divide two BigIntegers.
BigInteger.prototype.remainder = function(n)
Calculate the remainder of two BigIntegers.
BigInteger.prototype.divRem = function(n)
Calculate the integer quotient and remainder of two BigIntegers.
BigInteger.prototype.isEven = function()
Return true iff this is divisible by two.
BigInteger.prototype.isOdd = function()
Return true iff this is not divisible by two.
BigInteger.prototype.sign = function()
Get the sign of a BigInteger.
BigInteger.prototype.isPositive = function()
Return true iff this > 0.
BigInteger.prototype.isNegative = function()
Return true iff this < 0.
BigInteger.prototype.isZero = function()
Return true iff this == 0.
BigInteger.prototype.exp10 = function(n)
Multiply a BigInteger by a power of 10.
BigInteger.prototype.pow = function(n)
Raise a BigInteger to a power.
BigInteger.prototype.modPow = function(exponent,
modulus)
Raise a BigInteger to a power (mod m).
BigInteger.prototype.valueOf = function()
Convert a BigInteger to a native JavaScript integer.
BigInteger.prototype.toJSValue = function()
Convert a BigInteger to a native JavaScript integer.
Shortcut for ZERO.
Shortcut for ONE.
BigInteger -1.
The largest exponent allowed in pow and exp10 (0x7FFFFFFF or 2147483647).
Close