BigInt abstract final

abstract final class BigInt implements Comparable<BigInt>

An arbitrarily large integer value.

Big integers are signed and can have an arbitrary number of significant digits, only limited by memory.

To create a big integer from the provided number, use BigInt.from.

var bigInteger = BigInt.from(-1); // -1
bigInteger = BigInt.from(0.9999); // 0
bigInteger = BigInt.from(-10.99); // -10
bigInteger = BigInt.from(0x7FFFFFFFFFFFFFFF); // 9223372036854775807
bigInteger = BigInt.from(1e+30); // 1000000000000000019884624838656

To parse a large integer value from a string, use parse or tryParse.

var value = BigInt.parse('0x1ffffffffffffffff'); // 36893488147419103231
value = BigInt.parse('12345678901234567890'); // 12345678901234567890

To check whether a big integer can be represented as an int without losing precision, use isValidInt.

print(bigNumber.isValidInt); // false

To convert a big integer into an int, use toInt. To convert a big integer into an double, use toDouble.

var bigValue = BigInt.from(10).pow(3);
print(bigValue.isValidInt); // true
print(bigValue.toInt()); // 1000
print(bigValue.toDouble()); // 1000.0

See also:

• int: An integer number.
• double: A double-precision floating point number.
• num: The super class for int and double.
• Built-in number types
• Number representation

Implemented types

• Comparable<T>

Constructors

BigInt.from() factory

factory BigInt.from(num value)

Creates a big integer from the provided value number.

Examples:

var bigInteger = BigInt.from(1); // 1
bigInteger = BigInt.from(0.9999); // 0
bigInteger = BigInt.from(-10.99); // -10

Implementation

external factory BigInt.from(num value);

Properties

bitLength no setter

int get bitLength

Returns the minimum number of bits required to store this big integer.

The number of bits excludes the sign bit, which gives the natural length for non-negative (unsigned) values. Negative values are complemented to return the bit position of the first bit that differs from the sign bit.

To find the number of bits needed to store the value as a signed value, add one, i.e. use x.bitLength + 1.

x.bitLength == (-x-1).bitLength;

BigInt.from(3).bitLength == 2;   // 00000011
BigInt.from(2).bitLength == 2;   // 00000010
BigInt.from(1).bitLength == 1;   // 00000001
BigInt.from(0).bitLength == 0;   // 00000000
BigInt.from(-1).bitLength == 0;  // 11111111
BigInt.from(-2).bitLength == 1;  // 11111110
BigInt.from(-3).bitLength == 2;  // 11111101
BigInt.from(-4).bitLength == 2;  // 11111100

Implementation

int get bitLength;

hashCode no setter inherited

int get hashCode

The hash code for this object.

A hash code is a single integer which represents the state of the object that affects operator == comparisons.

All objects have hash codes. The default hash code implemented by Object represents only the identity of the object, the same way as the default operator == implementation only considers objects equal if they are identical (see identityHashCode).

If operator == is overridden to use the object state instead, the hash code must also be changed to represent that state, otherwise the object cannot be used in hash based data structures like the default Set and Map implementations.

Hash codes must be the same for objects that are equal to each other according to operator ==. The hash code of an object should only change if the object changes in a way that affects equality. There are no further requirements for the hash codes. They need not be consistent between executions of the same program and there are no distribution guarantees.

Objects that are not equal are allowed to have the same hash code. It is even technically allowed that all instances have the same hash code, but if clashes happen too often, it may reduce the efficiency of hash-based data structures like HashSet or HashMap.

If a subclass overrides hashCode, it should override the operator == operator as well to maintain consistency.

Inherited from Object.

Implementation

external int get hashCode;

isEven no setter

bool get isEven

Whether this big integer is even.

Implementation

bool get isEven;

isNegative no setter

bool get isNegative

Whether this number is negative.

Implementation

bool get isNegative;

isOdd no setter

bool get isOdd

Whether this big integer is odd.

Implementation

bool get isOdd;

isValidInt no setter

bool get isValidInt

Whether this big integer can be represented as an int without losing precision.

Warning: this function may give a different result on dart2js, dev compiler, and the VM, due to the differences in integer precision.

Example:

var bigNumber = BigInt.parse('100000000000000000000000');
print(bigNumber.isValidInt); // false

var value = BigInt.parse('0xFF'); // 255
print(value.isValidInt); // true

Implementation

bool get isValidInt;

runtimeType no setter inherited

Type get runtimeType

A representation of the runtime type of the object.

Inherited from Object.

Implementation

external Type get runtimeType;

sign no setter

int get sign

Returns the sign of this big integer.

Returns 0 for zero, -1 for values less than zero and +1 for values greater than zero.

Implementation

int get sign;

Methods

abs()

BigInt abs()

Returns the absolute value of this integer.

For any integer x, the result is the same as x < 0 ? -x : x.

Implementation

BigInt abs();

compareTo() override

int compareTo(BigInt other)

Compares this to other.

Returns a negative number if this is less than other, zero if they are equal, and a positive number if this is greater than other.

Example:

print(BigInt.from(1).compareTo(BigInt.from(2))); // => -1
print(BigInt.from(2).compareTo(BigInt.from(1))); // => 1
print(BigInt.from(1).compareTo(BigInt.from(1))); // => 0

Implementation

int compareTo(BigInt other);

gcd()

BigInt gcd(BigInt other)

Returns the greatest common divisor of this big integer and other.

If either number is non-zero, the result is the numerically greatest integer dividing both this and other.

The greatest common divisor is independent of the order, so x.gcd(y) is always the same as y.gcd(x).

For any integer x, x.gcd(x) is x.abs().

If both this and other is zero, the result is also zero.

Example:

print(BigInt.from(4).gcd(BigInt.from(2))); // 2
print(BigInt.from(8).gcd(BigInt.from(4))); // 4
print(BigInt.from(10).gcd(BigInt.from(12))); // 2
print(BigInt.from(10).gcd(BigInt.from(10))); // 10
print(BigInt.from(-2).gcd(BigInt.from(-3))); // 1

Implementation

BigInt gcd(BigInt other);

modInverse()

BigInt modInverse(BigInt modulus)

Returns the modular multiplicative inverse of this big integer modulo modulus.

The modulus must be positive.

It is an error if no modular inverse exists.

Implementation

// Returns 1/this % modulus, with modulus > 0.
BigInt modInverse(BigInt modulus);

modPow()

BigInt modPow(BigInt exponent, BigInt modulus)

Returns this integer to the power of exponent modulo modulus.

The exponent must be non-negative and modulus must be positive.

Implementation

BigInt modPow(BigInt exponent, BigInt modulus);

noSuchMethod() inherited

dynamic noSuchMethod(Invocation invocation)

Invoked when a nonexistent method or property is accessed.

A dynamic member invocation can attempt to call a member which doesn't exist on the receiving object. Example:

dynamic object = 1;
object.add(42); // Statically allowed, run-time error

This invalid code will invoke the noSuchMethod method of the integer 1 with an Invocation representing the .add(42) call and arguments (which then throws).

Classes can override noSuchMethod to provide custom behavior for such invalid dynamic invocations.

A class with a non-default noSuchMethod invocation can also omit implementations for members of its interface. Example:

class MockList<T> implements List<T> {
  noSuchMethod(Invocation invocation) {
    log(invocation);
    super.noSuchMethod(invocation); // Will throw.
  }
}
void main() {
  MockList().add(42);
}

This code has no compile-time warnings or errors even though the MockList class has no concrete implementation of any of the List interface methods. Calls to List methods are forwarded to noSuchMethod, so this code will log an invocation similar to Invocation.method(#add, [42]) and then throw.

If a value is returned from noSuchMethod, it becomes the result of the original invocation. If the value is not of a type that can be returned by the original invocation, a type error occurs at the invocation.

The default behavior is to throw a NoSuchMethodError.

Inherited from Object.

Implementation

@pragma("vm:entry-point")
@pragma("wasm:entry-point")
external dynamic noSuchMethod(Invocation invocation);

pow()

BigInt pow(int exponent)

Returns this to the power of exponent.

Returns one if the exponent equals 0.

The exponent must otherwise be positive.

The result is always equal to the mathematical result of this to the power exponent, only limited by the available memory.

Example:

var value = BigInt.from(1000);
print(value.pow(0)); // 1
print(value.pow(1)); // 1000
print(value.pow(2)); // 1000000
print(value.pow(3)); // 1000000000
print(value.pow(4)); // 1000000000000
print(value.pow(5)); // 1000000000000000
print(value.pow(6)); // 1000000000000000000
print(value.pow(7)); // 1000000000000000000000
print(value.pow(8)); // 1000000000000000000000000

Implementation

BigInt pow(int exponent);

remainder()

BigInt remainder(BigInt other)

Returns the remainder of the truncating division of this by other.

The result r of this operation satisfies: this == (this ~/ other) * other + r. As a consequence the remainder r has the same sign as the divider this.

Example:

print(BigInt.from(5).remainder(BigInt.from(3))); // 2
print(BigInt.from(-5).remainder(BigInt.from(3))); // -2
print(BigInt.from(5).remainder(BigInt.from(-3))); // 2
print(BigInt.from(-5).remainder(BigInt.from(-3))); // -2

Implementation

BigInt remainder(BigInt other);

toDouble()

double toDouble()

Returns this BigInt as a double.

If the number is not representable as a double, an approximation is returned. For numerically large integers, the approximation may be infinite.

Example:

var bigNumber = BigInt.parse('100000000000000000000000');
print(bigNumber.toDouble()); // 1e+23

Implementation

double toDouble();

toInt()

int toInt()

Returns this BigInt as an int.

If the number does not fit, clamps to the max (or min) integer.

Warning: the clamping behaves differently between the web and native platforms due to the differences in integer precision.

Example:

var bigNumber = BigInt.parse('100000000000000000000000');
print(bigNumber.isValidInt); // false
print(bigNumber.toInt()); // 9223372036854775807

Implementation

int toInt();

toRadixString()

String toRadixString(int radix)

Converts this BigInt to a string representation in the given radix.

In the string representation, lower-case letters are used for digits above '9', with 'a' being 10 an 'z' being 35.

The radix argument must be an integer in the range 2 to 36.

Example:

// Binary (base 2).
print(BigInt.from(12).toRadixString(2)); // 1100
print(BigInt.from(31).toRadixString(2)); // 11111
print(BigInt.from(2021).toRadixString(2)); // 11111100101
print(BigInt.from(-12).toRadixString(2)); // -1100
// Octal (base 8).
print(BigInt.from(12).toRadixString(8)); // 14
print(BigInt.from(31).toRadixString(8)); // 37
print(BigInt.from(2021).toRadixString(8)); // 3745
// Hexadecimal (base 16).
print(BigInt.from(12).toRadixString(16)); // c
print(BigInt.from(31).toRadixString(16)); // 1f
print(BigInt.from(2021).toRadixString(16)); // 7e5
// Base 36.
print(BigInt.from(35 * 36 + 1).toRadixString(36)); // z1

Implementation

String toRadixString(int radix);

toSigned()

BigInt toSigned(int width)

Returns the least significant width bits of this integer, extending the highest retained bit to the sign. This is the same as truncating the value to fit in width bits using an signed 2-s complement representation. The returned value has the same bit value in all positions higher than width.

var big15 = BigInt.from(15);
var big16 = BigInt.from(16);
var big239 = BigInt.from(239);
                               //     V--sign bit-V
big16.toSigned(5) == -big16;   //  00010000 -> 11110000
big239.toSigned(5) == big15;   //  11101111 -> 00001111
                               //     ^           ^

This operation can be used to simulate arithmetic from low level languages. For example, to increment an 8 bit signed quantity:

q = (q + 1).toSigned(8);

q will count from 0 up to 127, wrap to -128 and count back up to 127.

If the input value fits in width bits without truncation, the result is the same as the input. The minimum width needed to avoid truncation of x is x.bitLength + 1, i.e.

x == x.toSigned(x.bitLength + 1);

Implementation

BigInt toSigned(int width);

toString() override

String toString()

Returns a String-representation of this integer.

The returned string is parsable by parse. For any BigInt i, it is guaranteed that i == BigInt.parse(i.toString()).

Example:

var bigNumber = BigInt.parse('100000000000000000000000');
print(bigNumber.toString()); // "100000000000000000000000"

Implementation

String toString();

toUnsigned()

BigInt toUnsigned(int width)

Returns the least significant width bits of this big integer as a non-negative number (i.e. unsigned representation). The returned value has zeros in all bit positions higher than width.

BigInt.from(-1).toUnsigned(5) == 31   // 11111111  ->  00011111

This operation can be used to simulate arithmetic from low level languages. For example, to increment an 8 bit quantity:

q = (q + 1).toUnsigned(8);

q will count from 0 up to 255 and then wrap around to 0.

If the input fits in width bits without truncation, the result is the same as the input. The minimum width needed to avoid truncation of x is given by x.bitLength, i.e.

x == x.toUnsigned(x.bitLength);

Implementation

BigInt toUnsigned(int width);

Operators

operator %()

BigInt operator %(BigInt other)

Euclidean modulo operator.

Returns the remainder of the Euclidean division. The Euclidean division of two integers a and b yields two integers q and r such that a == b * q + r and 0 <= r < b.abs().

The sign of the returned value r is always positive.

See remainder for the remainder of the truncating division.

Example:

print(BigInt.from(5) % BigInt.from(3)); // 2
print(BigInt.from(-5) % BigInt.from(3)); // 1
print(BigInt.from(5) % BigInt.from(-3)); // 2
print(BigInt.from(-5) % BigInt.from(-3)); // 1

Implementation

BigInt operator %(BigInt other);

operator &()

BigInt operator &(BigInt other)

Bit-wise and operator.

Treating both this and other as sufficiently large two's component integers, the result is a number with only the bits set that are set in both this and other

Of both operands are negative, the result is negative, otherwise the result is non-negative.

Implementation

BigInt operator &(BigInt other);

operator *()

BigInt operator *(BigInt other)

Multiplies other by this big integer.

The result is again a big integer.

Implementation

BigInt operator *(BigInt other);

operator +()

BigInt operator +(BigInt other)

Adds other to this big integer.

The result is again a big integer.

Implementation

BigInt operator +(BigInt other);

operator -()

BigInt operator -(BigInt other)

Subtracts other from this big integer.

The result is again a big integer.

Implementation

BigInt operator -(BigInt other);

operator /()

double operator /(BigInt other)

Double division operator.

Matching the similar operator on int, this operation first performs toDouble on both this big integer and other, then does double.operator/ on those values and returns the result.

Note: The initial toDouble conversion may lose precision.

Example:

print(BigInt.from(1) / BigInt.from(2)); // 0.5
print(BigInt.from(1.99999) / BigInt.from(2)); // 0.5

Implementation

double operator /(BigInt other);

operator <()

bool operator <(BigInt other)

Whether this big integer is numerically smaller than other.

Implementation

bool operator <(BigInt other);

operator <<()

BigInt operator <<(int shiftAmount)

Shift the bits of this integer to the left by shiftAmount.

Shifting to the left makes the number larger, effectively multiplying the number by pow(2, shiftIndex).

There is no limit on the size of the result. It may be relevant to limit intermediate values by using the "and" operator with a suitable mask.

It is an error if shiftAmount is negative.

Implementation

BigInt operator <<(int shiftAmount);

operator <=()

bool operator <=(BigInt other)

Whether other is numerically greater than this big integer.

Implementation

bool operator <=(BigInt other);

operator ==() inherited

bool operator ==(Object other)

The equality operator.

The default behavior for all Objects is to return true if and only if this object and other are the same object.

Override this method to specify a different equality relation on a class. The overriding method must still be an equivalence relation. That is, it must be:

• Total: It must return a boolean for all arguments. It should never throw.

• Reflexive: For all objects o, o == o must be true.

• Symmetric: For all objects o1 and o2, o1 == o2 and o2 == o1 must either both be true, or both be false.

• Transitive: For all objects o1, o2, and o3, if o1 == o2 and o2 == o3 are true, then o1 == o3 must be true.

The method should also be consistent over time, so whether two objects are equal should only change if at least one of the objects was modified.

If a subclass overrides the equality operator, it should override the hashCode method as well to maintain consistency.

Inherited from Object.

Implementation

external bool operator ==(Object other);

operator >()

bool operator >(BigInt other)

Whether this big integer is numerically greater than other.

Implementation

bool operator >(BigInt other);

operator >=()

bool operator >=(BigInt other)

Whether other is numerically smaller than this big integer.

Implementation

bool operator >=(BigInt other);

operator >>()

BigInt operator >>(int shiftAmount)

Shift the bits of this integer to the right by shiftAmount.

Shifting to the right makes the number smaller and drops the least significant bits, effectively doing an integer division by pow(2, shiftIndex).

It is an error if shiftAmount is negative.

Implementation

BigInt operator >>(int shiftAmount);

operator ^()

BigInt operator ^(BigInt other)

Bit-wise exclusive-or operator.

Treating both this and other as sufficiently large two's component integers, the result is a number with the bits set that are set in one, but not both, of this and other

If the operands have the same sign, the result is non-negative, otherwise the result is negative.

Implementation

BigInt operator ^(BigInt other);

operator unary-()

BigInt operator unary-()

Return the negative value of this integer.

The result of negating an integer always has the opposite sign, except for zero, which is its own negation.

Implementation

BigInt operator -();

operator |()

BigInt operator |(BigInt other)

Bit-wise or operator.

Treating both this and other as sufficiently large two's component integers, the result is a number with the bits set that are set in either of this and other

If both operands are non-negative, the result is non-negative, otherwise the result is negative.

Implementation

BigInt operator |(BigInt other);

operator ~()

BigInt operator ~()

The bit-wise negate operator.

Treating this as a sufficiently large two's component integer, the result is a number with the opposite bits set.

This maps any integer x to -x - 1.

Implementation

BigInt operator ~();

operator ~/()

BigInt operator ~/(BigInt other)

Truncating integer division operator.

Performs a truncating integer division, where the remainder is discarded.

The remainder can be computed using the remainder method.

Examples:

var seven = BigInt.from(7);
var three = BigInt.from(3);
seven ~/ three;    // => 2
(-seven) ~/ three; // => -2
seven ~/ -three;   // => -2
seven.remainder(three);    // => 1
(-seven).remainder(three); // => -1
seven.remainder(-three);   // => 1

Implementation

BigInt operator ~/(BigInt other);

Static Properties

one no setter

BigInt get one

A big integer with the numerical value 1.

Implementation

external static BigInt get one;

two no setter

BigInt get two

A big integer with the numerical value 2.

Implementation

external static BigInt get two;

zero no setter

BigInt get zero

A big integer with the numerical value 0.

Implementation

external static BigInt get zero;

Static Methods

parse()

BigInt parse(String source, {int? radix})

Parses source as a, possibly signed, integer literal and returns its value.

The source must be a non-empty sequence of base-radix digits, optionally prefixed with a minus or plus sign ('-' or '+').

The radix must be in the range 2..36. The digits used are first the decimal digits 0..9, and then the letters 'a'..'z' with values 10 through 35. Also accepts upper-case letters with the same values as the lower-case ones.

If no radix is given then it defaults to 10. In this case, the source digits may also start with 0x, in which case the number is interpreted as a hexadecimal literal, which effectively means that the 0x is ignored and the radix is instead set to 16.

For any int n and radix r, it is guaranteed that n == int.parse(n.toRadixString(r), radix: r).

Throws a FormatException if the source is not a valid integer literal, optionally prefixed by a sign. Examples:

print(BigInt.parse('-12345678901234567890')); // -12345678901234567890
print(BigInt.parse('0xFF')); // 255
print(BigInt.parse('0xffffffffffffffff')); // 18446744073709551615

// From binary (base 2) value.
print(BigInt.parse('1100', radix: 2)); // 12
print(BigInt.parse('00011111', radix: 2)); // 31
print(BigInt.parse('011111100101', radix: 2)); // 2021
// From octal (base 8) value.
print(BigInt.parse('14', radix: 8)); // 12
print(BigInt.parse('37', radix: 8)); // 31
print(BigInt.parse('3745', radix: 8)); // 2021
// From hexadecimal (base 16) value.
print(BigInt.parse('c', radix: 16)); // 12
print(BigInt.parse('1f', radix: 16)); // 31
print(BigInt.parse('7e5', radix: 16)); // 2021
// From base 35 value.
print(BigInt.parse('y1', radix: 35)); // 1191 == 34 * 35 + 1
print(BigInt.parse('z1', radix: 35)); // Throws.
// From base 36 value.
print(BigInt.parse('y1', radix: 36)); // 1225 == 34 * 36 + 1
print(BigInt.parse('z1', radix: 36)); // 1261 == 35 * 36 + 1

Implementation

external static BigInt parse(String source, {int? radix});

tryParse()

BigInt? tryParse(String source, {int? radix})

Parses source as a, possibly signed, integer literal and returns its value.

As parse except that this method returns null if the input is not valid

Examples:

print(BigInt.tryParse('-12345678901234567890')); // -12345678901234567890
print(BigInt.tryParse('0xFF')); // 255
print(BigInt.tryParse('0xffffffffffffffff')); // 18446744073709551615

// From binary (base 2) value.
print(BigInt.tryParse('1100', radix: 2)); // 12
print(BigInt.tryParse('00011111', radix: 2)); // 31
print(BigInt.tryParse('011111100101', radix: 2)); // 2021
// From octal (base 8) value.
print(BigInt.tryParse('14', radix: 8)); // 12
print(BigInt.tryParse('37', radix: 8)); // 31
print(BigInt.tryParse('3745', radix: 8)); // 2021
// From hexadecimal (base 16) value.
print(BigInt.tryParse('c', radix: 16)); // 12
print(BigInt.tryParse('1f', radix: 16)); // 31
print(BigInt.tryParse('7e5', radix: 16)); // 2021
// From base 35 value.
print(BigInt.tryParse('y1', radix: 35)); // 1191 == 34 * 35 + 1
print(BigInt.tryParse('z1', radix: 35)); // null
// From base 36 value.
print(BigInt.tryParse('y1', radix: 36)); // 1225 == 34 * 36 + 1
print(BigInt.tryParse('z1', radix: 36)); // 1261 == 35 * 36 + 1

Implementation

external static BigInt? tryParse(String source, {int? radix});