65 lines
23 KiB
HTML
65 lines
23 KiB
HTML
<html><head><title>Big Number</title><link rel="stylesheet" type="text/css" href="/static/style.css"></head><body><div class="sidebar"><div class="header"><div class="logo"><a href="/"><div class="image"></div><div class="name">ethers</div><div class="version">v5.0-beta</div></a></div></div><div class="toc"><div><div class="link title"><a href="/">Documentation</a></div><div class="base show link depth-1"><a href="/getting-started/">Getting Started</a></div><div class="hide link depth-2"><a href="/getting-started/#installing">Installing</a></div><div class="hide link depth-2"><a href="/getting-started/#importing">Importing</a></div><div class="base show link depth-1"><a href="/concepts/">Concepts</a></div><div class="hide link depth-2"><a href="/concepts/events/">Events</a></div><div class="hide link depth-2"><a href="/concepts/gas/">Gas</a></div><div class="hide link depth-3"><a href="/concepts/gas/#gas-price">Gas Price</a></div><div class="hide link depth-3"><a href="/concepts/gas/#gas-limit">Gas Limit</a></div><div class="base ancestor show link depth-1"><a href="/api/">Application Programming Interface</a></div><div class="show link depth-2"><a href="/api/contract/">Contracts</a></div><div class="hide link depth-3"><a href="/api/contract/#buckets">Buckets</a></div><div class="show link depth-2"><a href="/api/signer/">Signers</a></div><div class="hide link depth-3"><a href="/api/signer/#signer">Signer</a></div><div class="hide link depth-3"><a href="/api/signer/#wallet-inherits-signer">Wallet inherits Signer</a></div><div class="show link depth-2"><a href="/api/providers/">Providers</a></div><div class="hide link depth-3"><a href="/api/providers/provider/">Provider</a></div><div class="hide link depth-4"><a href="/api/providers/provider/#accounts-methods">Accounts Methods</a></div><div class="hide link depth-4"><a href="/api/providers/provider/#blocks-methods">Blocks Methods</a></div><div class="hide link depth-4"><a href="/api/providers/provider/#ethereum-naming-service-(ens)-methods">Ethereum Naming Service (ENS) Methods</a></div><div class="hide link depth-4"><a href="/api/providers/provider/#logs-methods">Logs Methods</a></div><div class="hide link depth-4"><a href="/api/providers/provider/#network-status-methods">Network Status Methods</a></div><div class="hide link depth-4"><a href="/api/providers/provider/#transactions-methods">Transactions Methods</a></div><div class="hide link depth-4"><a href="/api/providers/provider/#event-emitter-methods">Event Emitter Methods</a></div><div class="hide link depth-4"><a href="/api/providers/provider/#inspection-methods">Inspection Methods</a></div><div class="hide link depth-3"><a href="/api/providers/jsonrpc-provider/">JSON-RPC Provider</a></div><div class="hide link depth-4"><a href="/api/providers/jsonrpc-provider/#jsonrpcprovider">JsonRpcProvider</a></div><div class="hide link depth-4"><a href="/api/providers/jsonrpc-provider/#jsonrpcsigner">JsonRpcSigner</a></div><div class="hide link depth-4"><a href="/api/providers/jsonrpc-provider/#jsonrpcuncheckedsigner">JsonRpcUncheckedSigner</a></div><div class="hide link depth-3"><a href="/api/providers/api-providers/">API Providers</a></div><div class="hide link depth-4"><a href="/api/providers/api-providers/#etherscanprovider">EtherscanProvider</a></div><div class="hide link depth-4"><a href="/api/providers/api-providers/#infuraprovider">InfuraProvider</a></div><div class="hide link depth-4"><a href="/api/providers/api-providers/#nodesmithprovider">NodesmithProvider</a></div><div class="hide link depth-4"><a href="/api/providers/api-providers/#alchemyprovider">AlchemyProvider</a></div><div class="hide link depth-3"><a href="/api/providers/other/">Other Providers</a></div><div class="hide link depth-4"><a href="/api/providers/other/#fallbackprovider">FallbackProvider</a></div><div class="hide link depth-4"><a href="/api/providers/other/#ipcprovider">IpcProvider</a></div><div class="hide link depth-3"><a href="/api/providers/types/">Types</a></div><div class="hide link depth-4"><a href="/api/providers/types/#blocks">Blocks</a></div><div class="hide link depth-4"><a href="/api/providers/types/#events-and-logs">Events and Logs</a></div><div class="hide link depth-4"><a href="/api/providers/types/#transactions">Transactions</a></div><div class="ancestor show link depth-2"><a href="/api/utils/">Utilities</a></div><div class="show link depth-3"><a href="/api/utils/address/">Addresses</a></div><div class="myself ancestor ancestor show link depth-3"><a href="/api/utils/bignumber/">BigNumber</a></div><div class="child link depth-4"><a href="/api/utils/bignumber/#types">Types</a></div><div class="child link depth-4"><a href="/api/utils/bignumber/#creating-instances">Creating Instances</a></div><div class="child link depth-4"><a href="/api/utils/bignumber/#methods">Methods</a></div><div class="child link depth-4"><a href="/api/utils/bignumber/#notes">Notes</a></div><div class="show link depth-3"><a href="/api/utils/bytes/">Byte Manipulation</a></div><div class="hide link depth-4"><a href="/api/utils/bytes/#types">Types</a></div><div class="hide link depth-4"><a href="/api/utils/bytes/#inspection">Inspection</a></div><div class="hide link depth-4"><a href="/api/utils/bytes/#converting-between-arrays-and-hexstrings">Converting between Arrays and Hexstrings</a></div><div class="hide link depth-4"><a href="/api/utils/bytes/#array-manipulation">Array Manipulation</a></div><div class="hide link depth-4"><a href="/api/utils/bytes/#hexstring-manipulation">Hexstring Manipulation</a></div><div class="hide link depth-4"><a href="/api/utils/bytes/#signature-conversion">Signature Conversion</a></div><div class="show link depth-3"><a href="/api/utils/constants/">Constants</a></div><div class="hide link depth-4"><a href="/api/utils/constants/#bytes">Bytes</a></div><div class="hide link depth-4"><a href="/api/utils/constants/#strings">Strings</a></div><div class="hide link depth-4"><a href="/api/utils/constants/#bignumber">BigNumber</a></div><div class="show link depth-3"><a href="/api/utils/display-logic/">Display Logic and Input</a></div><div class="hide link depth-4"><a href="/api/utils/display-logic/#units">Units</a></div><div class="hide link depth-4"><a href="/api/utils/display-logic/#functions">Functions</a></div><div class="show link depth-3"><a href="/api/utils/fixednumber/">FixedNumber</a></div><div class="hide link depth-4"><a href="/api/utils/fixednumber/#types">Types</a></div><div class="hide link depth-4"><a href="/api/utils/fixednumber/#creating-instances">Creating Instances</a></div><div class="hide link depth-4"><a href="/api/utils/fixednumber/#properties">Properties</a></div><div class="hide link depth-4"><a href="/api/utils/fixednumber/#methods">Methods</a></div><div class="show link depth-3"><a href="/api/utils/hashing/">Hashing Algorithms</a></div><div class="hide link depth-4"><a href="/api/utils/hashing/#cryptographic-hashing">Cryptographic Hashing</a></div><div class="hide link depth-4"><a href="/api/utils/hashing/#common-hashing-helpers">Common Hashing Helpers</a></div><div class="hide link depth-4"><a href="/api/utils/hashing/#solidity-hashing-algorithms">Solidity Hashing Algorithms</a></div><div class="show link depth-3"><a href="/api/utils/strings/">Strings</a></div><div class="hide link depth-4"><a href="/api/utils/strings/#bytes32string">Bytes32String</a></div><div class="hide link depth-4"><a href="/api/utils/strings/#utf-8-strings">UTF-8 Strings</a></div><div class="base show link depth-1"><a href="/cookbook/">Cookbook</a></div><div class="base show link depth-1"><a href="/migration/">Migration Guide</a></div><div class="hide link depth-2"><a href="/migration/#from-web3">From Web3</a></div><div class="hide link depth-2"><a href="/migration/#from-ethers-v4">From ethers v4</a></div><div class="base show link depth-1"><a href="/testing/">Testing</a></div><div class="base show link depth-1"><a href="/contributing/">Contributing and Hacking</a></div><div class="hide link depth-2"><a href="/contributing/#building">Building</a></div><div class="base show link depth-1"><a href="/documentation/">Flatworm Docs</a></div><div class="hide link depth-2"><a href="/documentation/#fragments">Fragments</a></div><div class="hide link depth-2"><a href="/documentation/#markdown">Markdown</a></div><div class="base show link depth-1"><a href="/license/">License and Copyright</a></div></div></div></div><div class="content"><div class="breadcrumbs"><a href="/">Documentation</a> » <a href="/api/">Application Programming Interface</a> » <a href="/api/utils/">Utilities</a> » <span class="current">Big Number</span></div>
|
|
<a name="bignumber"></a><a name="bignumber"></a><h1>BigNumber</h1>
|
|
<p>Explain about BigNumber here...</p>
|
|
<a name="importing"></a><h3>Importing</h3>
|
|
|
|
<div class="code"><span class="comment">/////</span><br><span class="comment">// CommonJS:</span><br><br><span class="comment">// From the Umbrella ethers package...</span><br>const { BigNumber } = require("ethers");<br><br><span class="comment">// From the bignumber pacakge...</span><br>const { BigNumber } = require("@ethersproject/bignumber");<br><br><br><span class="comment">/////</span><br><span class="comment">// ES6 and TypeScript:</span><br><br><span class="comment">// From the Umbrella ethers package...</span><br>import { BigNumber } from "ethers";<br><br><span class="comment">// From the bignumber pacakge...</span><br>import { BigNumber } from "@ethersproject/bignumber";<br></div>
|
|
|
|
<a name="types"></a><h2>Types</h2>
|
|
|
|
<a name="bignumberish"></a><a name="bignumberish"></a><h3>BigNumberish</h3>
|
|
<p>Many functions and methods in this library take in values which can be non-ambiguously and safely converted to a BigNumber. These values can be sepcified as:</p>
|
|
<div class="definition"><div class="term"><b><i>string</i></b></div><div class="body"><p>A <a href="/api/utils/bytes/#hexstring">hexstring</a> or a decimal string, either of which may be negative.</p></div></div>
|
|
<div class="definition"><div class="term"><b><i>BytesLike</i></b></div><div class="body"><p>A <a href="/api/utils/bytes/#byteslike">BytesLike</a> Object, such as an Array or Uint8Array.</p></div></div>
|
|
<div class="definition"><div class="term"><b><i>BigNumber</i></b></div><div class="body"><p>An existing BigNumber instance.</p></div></div>
|
|
<div class="definition"><div class="term"><b><i>number</i></b></div><div class="body"><p>A number that is within the safe range for JavaScript numbers.</p></div></div>
|
|
<div class="definition"><div class="term"><b><i>BigInt</i></b></div><div class="body"><p>A JavaScript <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt">BigInt</a> object, on environments that support BigInt.</p></div></div>
|
|
<a name="creating-instances"></a><h2>Creating Instances</h2>
|
|
<p>The constructor of BigNumber cannot be called directly. Instead, Use the static <code class="inline">BigNumber.from</code>.</p>
|
|
<div class="property"><div class="signature"><span class="path">BigNumber</span> . <span class="method">from</span> ( <span class="param">aBigNumberish</span> ) <span class="arrow">⇒</span> <span class="returns"><a href="/api/utils/bignumber/">BigNumber</a></span></div><div class="body"><p>Returns an instance of a <b>BigNumber</b> for <i>aBigNumberish</i>.</p></div></div>
|
|
<a name="examples:"></a><h3>Examples:</h3>
|
|
|
|
<div class="code"><br><span class="comment">// From a decimal string...</span><br>BigNumber.from("42")<br><span class="result ok">// { BigNumber: "42" }</span><br><br><span class="comment">// From a hexstring...</span><br>BigNumber.from("0x2a")<br><span class="result ok">// { BigNumber: "42" }</span><br><br><span class="comment">// From a negative hexstring...</span><br>BigNumber.from("-0x2a")<br><span class="result ok">// { BigNumber: "-42" }</span><br><br><span class="comment">// From an Array (or Uint8Array)...</span><br>BigNumber.from([ 42 ])<br><span class="result ok">// { BigNumber: "42" }</span><br><br><span class="comment">// From an existing BigNumber...</span><br>let one1 = constants.One;<br>let one2 = BigNumber.from(one1)<br><br>one2<br><span class="result ok">// { BigNumber: "1" }</span><br><br><span class="comment">// ...which returns the same instance</span><br>one1 === one2<br><span class="result ok">// true</span><br><br><span class="comment">// From a (safe) number...</span><br>BigNumber.from(42)<br><span class="result ok">// { BigNumber: "42" }</span><br><br><span class="comment">// From a ES2015 BigInt... (only on platforms with BigInt support)</span><br>BigNumber.from(42n)<br><span class="result ok">// { BigNumber: "42" }</span><br><br><span class="comment">// Numbers outside the safe range fail:</span><br>BigNumber.from(Number.MAX_SAFE_INTEGER);<br><span class="result error">// Error: overflow (fault="overflow", operation="BigNumber.from", value=9007199254740991, version=bignumber/5.0.0-beta.129)</span><br></div>
|
|
|
|
<a name="methods"></a><h2>Methods</h2>
|
|
<p>The BigNumber class is immutable, so no operations can change the value it represents.</p>
|
|
<a name="math-operations"></a><h3>Math Operations</h3>
|
|
|
|
<div class="property"><div class="signature"><span class="path">bignumber</span> . <span class="method">add</span> ( <span class="param">otherValue</span> ) <span class="arrow">⇒</span> <span class="returns"><a href="/api/utils/bignumber/">BigNumber</a></span></div><div class="body"><p>Returns a BigNumber with the value of <i>bignumber</i> <b>+</b> <i>otherValue</i>.</p></div></div>
|
|
<div class="property"><div class="signature"><span class="path">bignumber</span> . <span class="method">sub</span> ( <span class="param">otherValue</span> ) <span class="arrow">⇒</span> <span class="returns"><a href="/api/utils/bignumber/">BigNumber</a></span></div><div class="body"><p>Returns a BigNumber with the value of <i>bignumber</i> <b>–</b> <i>otherValue</i>.</p></div></div>
|
|
<div class="property"><div class="signature"><span class="path">bignumber</span> . <span class="method">mul</span> ( <span class="param">otherValue</span> ) <span class="arrow">⇒</span> <span class="returns"><a href="/api/utils/bignumber/">BigNumber</a></span></div><div class="body"><p>Returns a BigNumber with the value of <i>bignumber</i> <b>×</b> <i>otherValue</i>.</p></div></div>
|
|
<div class="property"><div class="signature"><span class="path">bignumber</span> . <span class="method">div</span> ( <span class="param">divisor</span> ) <span class="arrow">⇒</span> <span class="returns"><a href="/api/utils/bignumber/">BigNumber</a></span></div><div class="body"><p>Returns a BigNumber with the value of <i>bignumber</i> <b>÷</b> <i>divisor</i>.</p></div></div>
|
|
<div class="property"><div class="signature"><span class="path">bignumber</span> . <span class="method">mod</span> ( <span class="param">divisor</span> ) <span class="arrow">⇒</span> <span class="returns"><a href="/api/utils/bignumber/">BigNumber</a></span></div><div class="body"><p>Returns a BigNumber with the value of the <b>remainder</b> of <i>bignumber</i> ÷ <i>divisor</i>.</p></div></div>
|
|
<div class="property"><div class="signature"><span class="path">bignumber</span> . <span class="method">pow</span> ( <span class="param">exponent</span> ) <span class="arrow">⇒</span> <span class="returns"><a href="/api/utils/bignumber/">BigNumber</a></span></div><div class="body"><p>Returns a BigNumber with the value of <i>bignumber</i> to the power of <i>exponent</i>.</p></div></div>
|
|
<div class="property"><div class="signature"><span class="path">bignumber</span> . <span class="method">abs</span> ( ) <span class="arrow">⇒</span> <span class="returns"><a href="/api/utils/bignumber/">BigNumber</a></span></div><div class="body"><p>Returns a BigNumber with the absolute value of <i>bignumber</i>.</p></div></div>
|
|
<div class="property"><div class="signature"><span class="path">bignumber</span> . <span class="method">maskn</span> ( <span class="param">bitcount</span> ) <span class="arrow">⇒</span> <span class="returns"><a href="/api/utils/bignumber/">BigNumber</a></span></div><div class="body"><p>Returns a BigNumber with the value of <i>bignumber</i> with bits beyond the <i>bitcount</i> least significant bits set to zero.</p></div></div>
|
|
<a name="two's-compliment"></a><h3>Two's Compliment</h3>
|
|
<p><a href="https://en.wikipedia.org/wiki/Two%27s_complement">Two's Complicment</a> is a method used to encode and decode fixed-width values which can be positive or negative, without requiring a separate sign bit. Most users will not need to interact with these.</p>
|
|
<div class="property"><div class="signature"><span class="path">bignumber</span> . <span class="method">fromTwos</span> ( <span class="param">bitwidth</span> ) <span class="arrow">⇒</span> <span class="returns"><a href="/api/utils/bignumber/">BigNumber</a></span></div><div class="body"><p>Returns a BigNumber with the value of <i>bignumber</i> converted from twos-compliment with <i>bitwidth</i>.</p></div></div>
|
|
<div class="property"><div class="signature"><span class="path">bignumber</span> . <span class="method">toTwos</span> ( <span class="param">bitwidth</span> ) <span class="arrow">⇒</span> <span class="returns"><a href="/api/utils/bignumber/">BigNumber</a></span></div><div class="body"><p>Returns a BigNumber with the value of <i>bignumber</i> converted to twos-compliment with <i>bitwidth</i>.</p></div></div>
|
|
<a name="comparison-and-equivalence"></a><h3>Comparison and Equivalence</h3>
|
|
|
|
<div class="property"><div class="signature"><span class="path">bignumber</span> . <span class="method">eq</span> ( <span class="param">otherValue</span> ) <span class="arrow">⇒</span> <span class="returns">boolean</span></div><div class="body"><p>Returns true if and only if the value of <i>bignumber</i> is equal to <i>otherValue</i>.</p></div></div>
|
|
<div class="property"><div class="signature"><span class="path">bignumber</span> . <span class="method">lt</span> ( <span class="param">otherValue</span> ) <span class="arrow">⇒</span> <span class="returns">boolean</span></div><div class="body"><p>Returns true if and only if the value of <i>bignumber</i> <b><</b> <i>otherValue</i>.</p></div></div>
|
|
<div class="property"><div class="signature"><span class="path">bignumber</span> . <span class="method">lte</span> ( <span class="param">otherValue</span> ) <span class="arrow">⇒</span> <span class="returns">boolean</span></div><div class="body"><p>Returns true if and only if the value of <i>bignumber</i> <b>≤</b> <i>otherValue</i>.</p></div></div>
|
|
<div class="property"><div class="signature"><span class="path">bignumber</span> . <span class="method">gt</span> ( <span class="param">otherValue</span> ) <span class="arrow">⇒</span> <span class="returns">boolean</span></div><div class="body"><p>Returns true if and only if the value of <i>bignumber</i> <b>></b> <i>otherValue</i>.</p></div></div>
|
|
<div class="property"><div class="signature"><span class="path">bignumber</span> . <span class="method">gte</span> ( <span class="param">otherValue</span> ) <span class="arrow">⇒</span> <span class="returns">boolean</span></div><div class="body"><p>Returns true if and only if the value of <i>bignumber</i> <b>≥</b> <i>otherValue</i>.</p></div></div>
|
|
<div class="property"><div class="signature"><span class="path">bignumber</span> . <span class="method">isZero</span> ( ) <span class="arrow">⇒</span> <span class="returns">boolean</span></div><div class="body"><p>Returns true if and only if the value of <i>bignumber</i> is zero.</p></div></div>
|
|
<a name="conversion"></a><h3>Conversion</h3>
|
|
|
|
<div class="property"><div class="signature"><span class="path">bignumber</span> . <span class="method">toNumber</span> ( ) <span class="arrow">⇒</span> <span class="returns">number</span></div><div class="body"><p>Returns the value of <i>bignumber</i> as a JavaScript value.</p><p>This will <b>throw an error</b> if the value is greater than or equal to <i>Number.MAX_SAFE_INTEGER</i> or less than or equal to <i>Number.MIN_SAFE_INTEGER</i>.</p></div></div>
|
|
<div class="property"><div class="signature"><span class="path">bignumber</span> . <span class="method">toString</span> ( ) <span class="arrow">⇒</span> <span class="returns">string</span></div><div class="body"><p>Returns the value of <i>bignumber</i> as a base-10 string.</p></div></div>
|
|
<div class="property"><div class="signature"><span class="path">bignumber</span> . <span class="method">toHexString</span> ( ) <span class="arrow">⇒</span> <span class="returns">string</span></div><div class="body"><p>Returns the value of <i>bignumber</i> as a base-16, `0x`-prefixed <a href="/api/utils/bytes/#hexstring">hexstring</a>.</p></div></div>
|
|
<a name="inspection"></a><h3>Inspection</h3>
|
|
|
|
<div class="property"><div class="signature"><span class="path">BigNumnber</span> . <span class="method">isBigNumber</span> ( <span class="param">object</span> ) <span class="arrow">⇒</span> <span class="returns">boolean</span></div><div class="body"><p>Returns true if and only if the <i>object</i> is a BigNumber object.</p></div></div>
|
|
<a name="examples"></a><h3>Examples</h3>
|
|
|
|
<div class="code"><br>let a = BigNumber.from(42);<br>let b = BigNumber.from("91");<br><br> a.mul(b);<br><span class="result ok"> // { BigNumber: "3822" }</span><br></div>
|
|
|
|
<a name="notes"></a><h2>Notes</h2>
|
|
<p>A few short notes on numbers...</p>
|
|
<a name="why-can't-i-just-use-numbers?"></a><h3>Why can't I just use numbers?</h3>
|
|
<p>The first problem many encounter when dealing with Ethereum is the concept of numbers. Most common currencies are broken down with very little granularity. For example, there are only 100 cents in a single dollar. However, there are 10<sup>18</sup> <b>wei</b> in a single <b>ether</b>.</p><p>JavaScript uses <a href="https://en.wikipedia.org/wiki/Double-precision_floating-point_format">IEEE 754 double-precision binary floating point</a> numbers to represent numeric values. As a result, there are <i>holes</i> in the integer set after 9,007,199,254,740,991; which is problematic for <i>Ethereum</i> because that is only around 0.009 ether (in wei), which means any value over that will begin to experience rounding errors.</p><p>To demonstrate how this may be an issue in your code, consider:</p>
|
|
<div class="code">(Number.MAX_SAFE_INTEGER + 2 - 2) == (Number.MAX_SAFE_INTEGER)<br><span class="result ok">// false</span><br></div>
|
|
<p>To remedy this, all numbers (which can be large) are stored and manipulated as <a href="/api/utils/bignumber/">Big Numbers</a>.</p><p>The functions <a href="http://linkto">parseEther( etherString )</a> and <a href="http://linkto">formatEther( wei )</a> 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.</p><div class="footer"><div class="nav previous"><a href="/api/utils/address/"><span class="arrow">←</span>Addresses</a></div> <div class="nav next"><a href="/api/utils/bytes/">Byte Manipulation<span class="arrow">→</span></a></div></div><div class="copyright">The content of this site is licensed under the <a href="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons Attribution 4.0 International License</a>.</div></div><script src="/script.js" type="text/javascript"></script></body></html><!-- ContentHash:afcc27a12ae5a43b7ee621b007c1f1ad7c6c0714b1fbb7b6d119a773de8f938d --> |