Skip to content

Latest commit

 

History

History
1042 lines (608 loc) · 17.3 KB

api.md

File metadata and controls

1042 lines (608 loc) · 17.3 KB

API

BigInteger Class

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 BigInteger(20);
BigInteger.multiply(4, 5); // returns BigInteger(20);

var a = 42;
var a = BigInteger.toJSValue("0b101010");

BigInteger(n)

Convert a value to a BigInteger.

Although BigInteger() is the constructor for BigInteger objects, it should be called as a function. If n is a BigInteger object, it is simply returned as-is. Otherwise, BigInteger() is equivalent to BigInteger.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

Parameters:

  • n - Value to convert to a BigInteger.

Returns:

A BigInteger value.

See Also:

BigInteger.parse(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
  • "0c" or "0C": base = 8
  • "0b" or "0B": base = 2
  • 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:

  • s - The string to parse.
  • base - Optional radix (default is to guess based on s).

Returns:

a BigInteger instance.

BigInteger.ZERO

BigInteger 0.

BigInteger.ONE

BigInteger 1.

BigInteger.M_ONE

BigInteger -1.

BigInteger._0

Shortcut for ZERO.

BigInteger._1

Shortcut for ONE.

BigInteger.small

Array of BigIntegers from 0 to 36.

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

See Also:

BigInteger.MAX_EXP

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

toString([base])

Convert a BigInteger to a string.

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

Parameters:

  • base - Optional 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.

toJSValue()

Convert a BigInteger to a native JavaScript integer.

Returns:

parseInt(this.toString(), 10)

See Also:

add(n)

Add two BigIntegers

Parameters:

  • n - The number to add to this. Will be converted to a BigInteger.

Returns:

The numbers added together.

See Also:

subtract(n)

Subtract two BigIntegers.

Parameters:

  • n - The number to subtract from this. Will be converted to a BigInteger.

Returns:

The n subtracted from this.

See Also:

multiply(n)

Multiply two BigIntegers.

Parameters:

  • n - The number to multiply this by. Will be converted to a BigInteger.

Returns:

The numbers multiplied together.

See Also:

quotient(n)

Divide two BigIntegers and truncate towards zero.

quotient() throws an exception if n is zero.

Parameters:

  • n - The number to divide this by. Will be converted to a BigInteger.

Returns:

this / n, truncated to an integer.

See Also:

remainder(n)

Calculate the remainder of two BigIntegers.

remainder throws an exception if n is zero.

Parameters:

  • n - The remainder after this is divided this by n. Will be converted to a BigInteger.

Returns:

this % n.

See Also:

divRem(n)

Calculate the integer quotient and remainder of two BigIntegers.

divRem throws an exception if n is zero.

Parameters:

  • n - The 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.quotient(b), a.remainder(b)]

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

See Also:

divide(n)

Deprecated synonym for quotient().

negate()

Get the additive inverse of a BigInteger.

Returns:

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

See Also:

abs()

Get the absolute value of a BigInteger.

Returns:

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

See Also:

pow(n)

Raise a BigInteger to a power.

In this implementation, 0**0 is 1.

Parameters:

  • n - The 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(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:

  • exponent - The exponent to raise this by. Must be positive.
  • modulus - The modulus.

Returns:

this ** exponent (mod modulus).

See Also:

square()

Multiply a BigInteger by itself.

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

Returns:

this.multiply(this)

See Also:

exp10(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.quotient(BigInteger("1e" + -n));
}

Parameters:

  • n - The 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:

log()

Get the natural logarithm of a BigInteger as a native JavaScript number.

This is equivalent to

Math.log(this.toJSValue())

but handles values outside of the native number range.

Returns:

log(this)

See Also:

next()

Get the next BigInteger (add one).

Returns:

this + 1.

See Also:

prev()

Get the previous BigInteger (subtract one).

Returns:

this - 1.

See Also:

compare(n)

Compare two BigIntegers.

Parameters:

  • n - The 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(n)

Compare the absolute value of two BigIntegers.

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

Parameters:

  • n - The 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:

isUnit()

Return true iff this is either 1 or -1.

Returns:

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

See Also:

isEven()

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()

Return true iff this is not divisible by two.

Returns:

true if this is odd, false otherwise.

See Also:

sign()

Get the sign of a BigInteger.

Returns:

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

See Also:

isPositive()

Return true iff this > 0.

Returns:

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

See Also:

isNegative()

Return true iff this < 0.

Returns:

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

See Also:

isZero()

Return true iff this == 0.

Returns:

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

See Also:

valueOf()

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:

BigInteger.toString(n)

Static equivalent to BigInteger(n).toString().

BigInteger.toJSValue(n)

Static equivalent to BigInteger(n).toJSValue().

BigInteger.add(a, b)

Static equivalent to BigInteger(a).add(b).

BigInteger.subtract(a, b)

Static equivalent to BigInteger(a).subtract(b).

BigInteger.multiply(a, b)

Static equivalent to BigInteger(a).multiply(b).

BigInteger.quotient(a, b)

Static equivalent to BigInteger(a).quotient(b).

BigInteger.remainder(a, b)

Static equivalent to BigInteger(a).remainder(b).

BigInteger.divRem(a, b)

Static equivalent to BigInteger(a).divRem(b).

BigInteger.divide(a, b)

Static equivalent to BigInteger(a).divide(b).

BigInteger.negate(n)

Static equivalent to BigInteger(n).negate().

BigInteger.abs(n)

Static equivalent to BigInteger(n).abs().

BigInteger.pow(a, b)

Static equivalent to BigInteger(a).pow(b).

BigInteger.modPow(base, exponent, modulus)

Static equivalent to BigInteger(base).modPow(exponent, modulus).

BigInteger.square(n)

Static equivalent to BigInteger(n).square().

BigInteger.exp10(b)

Static equivalent to BigInteger(a).exp10(b).

BigInteger.log(n)

Static equivalent to BigInteger(n).log().

BigInteger.next(n)

Static equivalent to BigInteger(n).next().

BigInteger.prev(n)

Static equivalent to BigInteger(n).prev().

BigInteger.compare(a, b)

Static equivalent to BigInteger(a).compare(b).

BigInteger.compareAbs(a, b)

Static equivalent to BigInteger(a).compareAbs(b).

BigInteger.isUnit(n)

Static equivalent to BigInteger(n).isUnit().

BigInteger.isEven(n)

Static equivalent to BigInteger(n).isEven().

BigInteger.isOdd(n)

Static equivalent to BigInteger(n).isOdd().

BigInteger.sign(n)

Static equivalent to BigInteger(n).sign().

BigInteger.isPositive(n)

Static equivalent to BigInteger(n).isPositive().

BigInteger.isNegative(n)

Static equivalent to BigInteger(n).isNegative().

BigInteger.isZero(n)

Static equivalent to BigInteger(n).isZero().