5.9 KiB
BigNumber
Types
BigNumberish
string
A HexString or a decimal string, either of which may be negative.
BytesLike
A BytesLike Object, such as an Array or Uint8Array.
BigNumber
An existing BigNumber instance.
number
A number that is within the safe range for JavaScript numbers.
BigInt
A JavaScript BigInt object, on environments that support BigInt.
Creating Instances
ethers . BigNumber . from( aBigNumberish ) => BigNumber
Returns an instance of a BigNumber for aBigNumberish.
Examples:
// From a decimal string...
BigNumber.from("42")
// { BigNumber: "42" }
// From a HexString...
BigNumber.from("0x2a")
// { BigNumber: "42" }
// From a negative HexString...
BigNumber.from("-0x2a")
// { BigNumber: "-42" }
// From an Array (or Uint8Array)...
BigNumber.from([ 42 ])
// { BigNumber: "42" }
// From an existing BigNumber...
let one1 = constants.One;
let one2 = BigNumber.from(one1)
one2
// { BigNumber: "1" }
// ...which returns the same instance
one1 === one2
// true
// From a (safe) number...
BigNumber.from(42)
// { BigNumber: "42" }
// From a ES2015 BigInt... (only on platforms with BigInt support)
BigNumber.from(42n)
// { BigNumber: "42" }
// Numbers outside the safe range fail:
BigNumber.from(Number.MAX_SAFE_INTEGER);
// Error: overflow (fault="overflow", operation="BigNumber.from", value=9007199254740991, code=NUMERIC_FAULT, version=bignumber/5.0.3)
Methods
Math Operations
BigNumber . add( otherValue ) => BigNumber
Returns a BigNumber with the value of BigNumber + otherValue.
BigNumber . sub( otherValue ) => BigNumber
Returns a BigNumber with the value of BigNumber - otherValue.
BigNumber . mul( otherValue ) => BigNumber
Returns a BigNumber with the value of BigNumber * otherValue.
BigNumber . div( divisor ) => BigNumber
Returns a BigNumber with the value of BigNumber / divisor.
BigNumber . mod( divisor ) => BigNumber
Returns a BigNumber with the value of the remainder of BigNumber / divisor.
BigNumber . pow( exponent ) => BigNumber
Returns a BigNumber with the value of BigNumber to the power of exponent.
BigNumber . abs( ) => BigNumber
Returns a BigNumber with the absolute value of BigNumber.
BigNumber . mask( bitcount ) => BigNumber
Returns a BigNumber with the value of BigNumber with bits beyond the bitcount least significant bits set to zero.
Two's Compliment
BigNumber . fromTwos( bitwidth ) => BigNumber
Returns a BigNumber with the value of BigNumber converted from twos-compliment with bitwidth.
BigNumber . toTwos( bitwidth ) => BigNumber
Returns a BigNumber with the value of BigNumber converted to twos-compliment with bitwidth.
Comparison and Equivalence
BigNumber . eq( otherValue ) => boolean
Returns true if and only if the value of BigNumber is equal to otherValue.
BigNumber . lt( otherValue ) => boolean
Returns true if and only if the value of BigNumber < otherValue.
BigNumber . lte( otherValue ) => boolean
Returns true if and only if the value of BigNumber <= otherValue.
BigNumber . gt( otherValue ) => boolean
Returns true if and only if the value of BigNumber > otherValue.
BigNumber . gte( otherValue ) => boolean
Returns true if and only if the value of BigNumber >= otherValue.
BigNumber . isZero( ) => boolean
Returns true if and only if the value of BigNumber is zero.
Conversion
BigNumber . toNumber( ) => number
Returns the value of BigNumber as a JavaScript value.
This will throw an error if the value is greater than or equal to Number.MAX_SAFE_INTEGER or less than or equal to Number.MIN_SAFE_INTEGER.
BigNumber . toString( ) => string
Returns the value of BigNumber as a base-10 string.
BigNumber . toHexString( ) => string< DataHexString >
Returns the value of BigNumber as a base-16, 0x-prefixed DataHexString.
Inspection
ethers . BigNumnber . isBigNumber( object ) => boolean
Returns true if and only if the object is a BigNumber object.
Examples
let a = BigNumber.from(42);
let b = BigNumber.from("91");
a.mul(b);
// { BigNumber: "3822" }
Notes
Why can't I just use numbers?
(Number.MAX_SAFE_INTEGER + 2 - 2) == (Number.MAX_SAFE_INTEGER)
// false
To remedy this, all numbers (which can be large) are stored and manipulated as Big Numbers.
The functions parseEther( etherString ) and formatEther( wei ) can be used to convert between string representations, which are displayed to or entered by the user and Big Number representations which can have mathematical operations handled safely.