tornado-packages/ethers.js
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
fetchData
ethers.js/docs/v5/api/utils/bignumber/README.md

238 lines
5.9 KiB
Markdown
Raw Permalink Normal View History

Check-in old v5 docs changes.
2020-06-09 23:56:58 -04:00
-----
Updated docs build.
2020-07-03 01:54:56 -04:00
Documentation: [html](https://docs.ethers.io/)
Check-in old v5 docs changes.
2020-06-09 23:56:58 -04:00
-----
BigNumber
=========
Types
-----
### BigNumberish
#### ***string***
A [HexString](/v5/api/utils/bytes/#HexString) or a decimal string, either of which may be negative.
#### ***BytesLike***
A [BytesLike](/v5/api/utils/bytes/#BytesLike) Object, such as an Array or Uint8Array.
#### ***BigNumber***
An existing [BigNumber](/v5/api/utils/bignumber/) instance.
#### ***number***
A number that is within the [safe range](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER#Description) for JavaScript numbers.
#### ***BigInt***
A JavaScript [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) object, on environments that support BigInt.
Creating Instances
------------------
#### *ethers* . *BigNumber* . **from**( aBigNumberish ) => *[BigNumber](/v5/api/utils/bignumber/)*
Returns an instance of a **BigNumber** for *aBigNumberish*.
### Examples:
```javascript
// From a decimal string...
BigNumber.from("42")
Updated docs.
2020-06-12 19:21:37 -04:00
// { BigNumber: "42" }
Check-in old v5 docs changes.
2020-06-09 23:56:58 -04:00
// From a HexString...
BigNumber.from("0x2a")
Updated docs.
2020-06-12 19:21:37 -04:00
// { BigNumber: "42" }
Check-in old v5 docs changes.
2020-06-09 23:56:58 -04:00
// From a negative HexString...
BigNumber.from("-0x2a")
Updated docs.
2020-06-12 19:21:37 -04:00
// { BigNumber: "-42" }
Check-in old v5 docs changes.
2020-06-09 23:56:58 -04:00
// From an Array (or Uint8Array)...
BigNumber.from([ 42 ])
Updated docs.
2020-06-12 19:21:37 -04:00
// { BigNumber: "42" }
Check-in old v5 docs changes.
2020-06-09 23:56:58 -04:00
// From an existing BigNumber...
let one1 = constants.One;
let one2 = BigNumber.from(one1)
one2
Updated docs.
2020-06-12 19:21:37 -04:00
// { BigNumber: "1" }
Check-in old v5 docs changes.
2020-06-09 23:56:58 -04:00
// ...which returns the same instance
one1 === one2
Updated docs.
2020-06-12 19:21:37 -04:00
// true
Check-in old v5 docs changes.
2020-06-09 23:56:58 -04:00
// From a (safe) number...
BigNumber.from(42)
Updated docs.
2020-06-12 19:21:37 -04:00
// { BigNumber: "42" }
Check-in old v5 docs changes.
2020-06-09 23:56:58 -04:00
// From a ES2015 BigInt... (only on platforms with BigInt support)
BigNumber.from(42n)
Updated docs.
2020-06-12 19:21:37 -04:00
// { BigNumber: "42" }
Check-in old v5 docs changes.
2020-06-09 23:56:58 -04:00
// Numbers outside the safe range fail:
BigNumber.from(Number.MAX_SAFE_INTEGER);
Updated docs build.
2020-07-05 00:02:47 -04:00
// Error: overflow (fault="overflow", operation="BigNumber.from", value=9007199254740991, code=NUMERIC_FAULT, version=bignumber/5.0.3)
Check-in old v5 docs changes.
2020-06-09 23:56:58 -04:00
```
Methods
-------
### Math Operations
#### *BigNumber* . **add**( otherValue ) => *[BigNumber](/v5/api/utils/bignumber/)*
Returns a BigNumber with the value of *BigNumber* **+** *otherValue*.
#### *BigNumber* . **sub**( otherValue ) => *[BigNumber](/v5/api/utils/bignumber/)*
Returns a BigNumber with the value of *BigNumber* **-** *otherValue*.
#### *BigNumber* . **mul**( otherValue ) => *[BigNumber](/v5/api/utils/bignumber/)*
Returns a BigNumber with the value of *BigNumber* **\*** *otherValue*.
#### *BigNumber* . **div**( divisor ) => *[BigNumber](/v5/api/utils/bignumber/)*
Returns a BigNumber with the value of *BigNumber* **/** *divisor*.
#### *BigNumber* . **mod**( divisor ) => *[BigNumber](/v5/api/utils/bignumber/)*
Returns a BigNumber with the value of the **remainder** of *BigNumber* / *divisor*.
#### *BigNumber* . **pow**( exponent ) => *[BigNumber](/v5/api/utils/bignumber/)*
Returns a BigNumber with the value of *BigNumber* to the power of *exponent*.
#### *BigNumber* . **abs**( ) => *[BigNumber](/v5/api/utils/bignumber/)*
Returns a BigNumber with the absolute value of *BigNumber*.
#### *BigNumber* . **mask**( bitcount ) => *[BigNumber](/v5/api/utils/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](/v5/api/utils/bignumber/)*
Returns a BigNumber with the value of *BigNumber* converted from twos-compliment with *bitwidth*.
#### *BigNumber* . **toTwos**( bitwidth ) => *[BigNumber](/v5/api/utils/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](/v5/api/utils/bytes/#DataHexString) >*
Returns the value of *BigNumber* as a base-16, `0x`-prefixed [DataHexString](/v5/api/utils/bytes/#DataHexString).
### Inspection
#### *ethers* . *BigNumnber* . **isBigNumber**( object ) => *boolean*
Returns true if and only if the *object* is a BigNumber object.
### Examples
```javascript
let a = BigNumber.from(42);
let b = BigNumber.from("91");
a.mul(b);
Updated docs.
2020-06-12 19:21:37 -04:00
// { BigNumber: "3822" }
Check-in old v5 docs changes.
2020-06-09 23:56:58 -04:00
```
Notes
-----
### Why can't I just use numbers?
```javascript
(Number.MAX_SAFE_INTEGER + 2 - 2) == (Number.MAX_SAFE_INTEGER)
Updated docs.
2020-06-12 19:21:37 -04:00
// false
Check-in old v5 docs changes.
2020-06-09 23:56:58 -04:00
```
To remedy this, all numbers (which can be large) are stored and manipulated as [Big Numbers](/v5/api/utils/bignumber/).
The functions [parseEther( etherString )](/v5/api/utils/display-logic/#utils-parseEther) and [formatEther( wei )](/v5/api/utils/display-logic/#utils-formatEther) 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.
### Why not BigNumber.js, BN.js, BigDecimal, etc?
### Why BN.js??
### Allow us to set a global Big Number library?
Reference in New Issue Copy Permalink