186 lines
32 KiB
HTML
186 lines
32 KiB
HTML
<!DOCTYPE html>
|
|
<html class="paged">
|
|
<head>
|
|
<title>BigNumber</title>
|
|
<link rel="stylesheet" type="text/css" href="/v5/static/style.css">
|
|
</head>
|
|
<body>
|
|
<div class="sidebar">
|
|
<div class="header">
|
|
<div class="logo"><a href="/v5/"><div class="image"></div><div class="name">ethers</div><div class="version">v5.0</div></a></div>
|
|
</div>
|
|
<div class="toc"><div>
|
|
<div class="link title"><a href="/v5/">Documentation</a></div><div class="base show link depth-1"><a href="/v5/getting-started/">Getting Started</a></div><div class="base show link depth-1"><a href="/v5/concepts/">Ethereum Basics</a></div><div class="hide link depth-2"><a href="/v5/concepts/events/">Events</a></div><div class="hide link depth-2"><a href="/v5/concepts/gas/">Gas</a></div><div class="hide link depth-2"><a href="/v5/concepts/security/">Security</a></div><div class="base show link depth-1"><a href="/v5/api-keys/">Provider API Keys</a></div><div class="base ancestor show link depth-1"><a href="/v5/api/">Application Programming Interface</a></div><div class="show link depth-2"><a href="/v5/api/providers/">Providers</a></div><div class="hide link depth-3"><a href="/v5/api/providers/provider/">Provider</a></div><div class="hide link depth-3"><a href="/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a></div><div class="hide link depth-3"><a href="/v5/api/providers/api-providers/">API Providers</a></div><div class="hide link depth-3"><a href="/v5/api/providers/other/">Other Providers</a></div><div class="hide link depth-3"><a href="/v5/api/providers/types/">Types</a></div><div class="show link depth-2"><a href="/v5/api/signer/">Signers</a></div><div class="show link depth-2"><a href="/v5/api/contract/">Contract Interaction</a></div><div class="hide link depth-3"><a href="/v5/api/contract/contract/">Contract</a></div><div class="hide link depth-3"><a href="/v5/api/contract/contract-factory/">ContractFactory</a></div><div class="hide link depth-3"><a href="/v5/api/contract/example/">Example: ERC-20 Contract</a></div><div class="ancestor show link depth-2"><a href="/v5/api/utils/">Utilities</a></div><div class="show link depth-3"><a href="/v5/api/utils/abi/">Application Binary Interface</a></div><div class="hide link depth-4"><a href="/v5/api/utils/abi/coder/">AbiCoder</a></div><div class="hide link depth-4"><a href="/v5/api/utils/abi/formats/">ABI Formats</a></div><div class="hide link depth-4"><a href="/v5/api/utils/abi/fragments/">Fragments</a></div><div class="hide link depth-4"><a href="/v5/api/utils/abi/interface/">Interface</a></div><div class="show link depth-3"><a href="/v5/api/utils/address/">Addresses</a></div><div class="myself ancestor ancestor show link depth-3"><a href="/v5/api/utils/bignumber/">BigNumber</a></div><div class="show link depth-3"><a href="/v5/api/utils/bytes/">Byte Manipulation</a></div><div class="show link depth-3"><a href="/v5/api/utils/constants/">Constants</a></div><div class="show link depth-3"><a href="/v5/api/utils/display-logic/">Display Logic and Input</a></div><div class="show link depth-3"><a href="/v5/api/utils/encoding/">Encoding Utilities</a></div><div class="show link depth-3"><a href="/v5/api/utils/fixednumber/">FixedNumber</a></div><div class="show link depth-3"><a href="/v5/api/utils/hashing/">Hashing Algorithms</a></div><div class="show link depth-3"><a href="/v5/api/utils/hdnode/">HD Wallet</a></div><div class="show link depth-3"><a href="/v5/api/utils/logger/">Logging</a></div><div class="show link depth-3"><a href="/v5/api/utils/properties/">Property Utilities</a></div><div class="show link depth-3"><a href="/v5/api/utils/signing-key/">Signing Key</a></div><div class="show link depth-3"><a href="/v5/api/utils/strings/">Strings</a></div><div class="show link depth-3"><a href="/v5/api/utils/transactions/">Transactions</a></div><div class="show link depth-3"><a href="/v5/api/utils/web/">Web Utilities</a></div><div class="show link depth-3"><a href="/v5/api/utils/wordlists/">Wordlists</a></div><div class="show link depth-2"><a href="/v5/api/other/">Other Libraries</a></div><div class="hide link depth-3"><a href="/v5/api/other/assembly/">Assembly</a></div><div class="hide link depth-4"><a href="/v5/api/other/assembly/dialect/">Ethers ASM Dialect</a></div><div class="hide link depth-4"><a href="/v5/api/other/assembly/api/">Utilities</a></div><div class="hide link depth-4"><a href="/v5/api/other/assembly/ast/">Abstract Syntax Tree</a></div><div class="hide link depth-3"><a href="/v5/api/other/hardware/">Hardware Wallets</a></div><div class="show link depth-2"><a href="/v5/api/experimental/">Experimental</a></div><div class="base show link depth-1"><a href="/v5/cli/">Command Line Interfaces</a></div><div class="hide link depth-2"><a href="/v5/cli/ethers/">Sandbox Utility</a></div><div class="hide link depth-2"><a href="/v5/cli/asm/">Assembler</a></div><div class="hide link depth-2"><a href="/v5/cli/ens/">Ethereum Naming Service</a></div><div class="hide link depth-2"><a href="/v5/cli/typescript/">TypeScript</a></div><div class="hide link depth-2"><a href="/v5/cli/plugin/">Making Your Own</a></div><div class="base show link depth-1"><a href="/v5/cookbook/">Cookbook</a></div><div class="hide link depth-2"><a href="/v5/cookbook/react-native/">React Native (and ilk)</a></div><div class="base show link depth-1"><a href="/v5/migration/">Migration Guide</a></div><div class="hide link depth-2"><a href="/v5/migration/web3/">Migration: From Web3.js</a></div><div class="hide link depth-2"><a href="/v5/migration/ethers-v4/">Migration: From Ethers v4</a></div><div class="base show link depth-1"><a href="/v5/testing/">Testing</a></div><div class="base show link depth-1"><a href="/v5/contributing/">Contributing and Hacking</a></div><div class="base show link depth-1"><a href="/v5/documentation/">Flatworm Docs</a></div><div class="base show link depth-1"><a href="/v5/license/">License and Copyright</a></div>
|
|
</div></div>
|
|
</div>
|
|
<div class="content">
|
|
<div class="breadcrumbs"><a href="/v5/">Documentation</a> » <a href="/v5/api/">API</a> » <a href="/v5/api/utils/">Utilities</a> » <span class="current">BigNumber</span></div>
|
|
|
|
<a name="BigNumber"></a><a name="BigNumber"></a><h1 class="show-anchors"><div>BigNumber<div class="anchors"><a class="self" href="/v5/api/utils/bignumber/#BigNumber"></a></div></div></h1><p>Many operations in Ethereum operation on numbers which are <a href="/v5/api/utils/bignumber/#BigNumber--notes-safenumbers">outside the range of safe values</a> to use in JavaScript.</p>
|
|
|
|
<p>A <b>BigNumber</b> is an object which safely allows mathematic operations on numbers of any magnitude.</p>
|
|
|
|
<p>Most operations which need to return a value will return a <b>BigNumber</b> and parameters which accept values will generally accept them.</p>
|
|
|
|
<a name="BigNumber--types"></a><a name="BigNumber--BigNumber--types"></a><h2 class="show-anchors"><div>Types<div class="anchors"><a class="self" href="/v5/api/utils/bignumber/#BigNumber--types"></a></div></div></h2>
|
|
<a name="BigNumberish"></a><a name="BigNumber--BigNumber--types--BigNumberish"></a><h3 class="show-anchors"><div>BigNumberish<div class="anchors"><a class="self" href="/v5/api/utils/bignumber/#BigNumberish"></a></div></div></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="/v5/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="/v5/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 <a href="/v5/api/utils/bignumber/">BigNumber</a> 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 <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER#Description">safe range</a> 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="BigNumber--creating"></a><a name="BigNumber--BigNumber--creating"></a><h2 class="show-anchors"><div>Creating Instances<div class="anchors"><a class="self" href="/v5/api/utils/bignumber/#BigNumber--creating"></a></div></div></h2><p>The constructor of BigNumber cannot be called directly. Instead, Use the static <code class="inline">BigNumber.from</code>.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">from</span><span class="symbol">(</span> <span class="param">aBigNumberish</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"></div></div><div class="body"><p>Returns an instance of a <b>BigNumber</b> for <i>aBigNumberish</i>.</p>
|
|
|
|
</div></div><a name="BigNumber--BigNumber--creating--examples"></a><h3 class="show-anchors"><div>Examples:<div class="anchors"></div></div></h3>
|
|
<div class="code"><span class="comment">// From a decimal string...
|
|
</span>BigNumber.from("42")
|
|
<span class="result ok">// { BigNumber: "42" }
|
|
</span>
|
|
<span class="comment">// From a HexString...
|
|
</span>BigNumber.from("0x2a")
|
|
<span class="result ok">// { BigNumber: "42" }
|
|
</span>
|
|
<span class="comment">// From a negative HexString...
|
|
</span>BigNumber.from("-0x2a")
|
|
<span class="result ok">// { BigNumber: "-42" }
|
|
</span>
|
|
<span class="comment">// From an Array (or Uint8Array)...
|
|
</span>BigNumber.from([ 42 ])
|
|
<span class="result ok">// { BigNumber: "42" }
|
|
</span>
|
|
<span class="comment">// From an existing BigNumber...
|
|
</span>let one1 = constants.One;
|
|
let one2 = BigNumber.from(one1)
|
|
|
|
one2
|
|
<span class="result ok">// { BigNumber: "1" }
|
|
</span>
|
|
<span class="comment">// ...which returns the same instance
|
|
</span>one1 === one2
|
|
<span class="result ok">// true
|
|
</span>
|
|
<span class="comment">// From a (safe) number...
|
|
</span>BigNumber.from(42)
|
|
<span class="result ok">// { BigNumber: "42" }
|
|
</span>
|
|
<span class="comment">// From a ES2015 BigInt... (only on platforms with BigInt support)
|
|
</span>BigNumber.from(42n)
|
|
<span class="result ok">// { BigNumber: "42" }
|
|
</span>
|
|
<span class="comment">// Numbers outside the safe range fail:
|
|
</span>BigNumber.from(Number.MAX_SAFE_INTEGER);
|
|
<span class="result error">// Error: overflow (fault="overflow", operation="BigNumber.from", value=9007199254740991, code=NUMERIC_FAULT, version=bignumber/5.0.6)
|
|
</span></div><a name="BigNumber--methods"></a><a name="BigNumber--BigNumber--methods"></a><h2 class="show-anchors"><div>Methods<div class="anchors"><a class="self" href="/v5/api/utils/bignumber/#BigNumber--methods"></a></div></div></h2><p>The BigNumber class is immutable, so no operations can change the value it represents.</p>
|
|
|
|
<a name="BigNumber--BigNumber--methods--math-operations"></a><h3 class="show-anchors"><div>Math Operations<div class="anchors"><a class="self" href="/v5/api/utils/bignumber/#BigNumber--BigNumber--methods--math-operations"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">add</span><span class="symbol">(</span> <span class="param">otherValue</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L71">source</a></div></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 show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">sub</span><span class="symbol">(</span> <span class="param">otherValue</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L75">source</a></div></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 show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">mul</span><span class="symbol">(</span> <span class="param">otherValue</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L87">source</a></div></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 show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">div</span><span class="symbol">(</span> <span class="param">divisor</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L79">source</a></div></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 show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">mod</span><span class="symbol">(</span> <span class="param">divisor</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L91">source</a></div></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 show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">pow</span><span class="symbol">(</span> <span class="param">exponent</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L99">source</a></div></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 show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">abs</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L64">source</a></div></div><div class="body"><p>Returns a BigNumber with the absolute value of <i>BigNumber</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">mask</span><span class="symbol">(</span> <span class="param">bitcount</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L131">source</a></div></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="BigNumber--BigNumber--methods--two-s-compliment"></a><h3 class="show-anchors"><div>Two's Compliment<div class="anchors"><a class="self" href="/v5/api/utils/bignumber/#BigNumber--BigNumber--methods--two-s-compliment"></a></div></div></h3><p><a href="https://en.wikipedia.org/wiki/Two%27s_complement">Two's Complicment</a> is an elegant method used to encode and decode fixed-width signed values while efficiently preserving mathematic operations. Most users will not need to interact with these.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">fromTwos</span><span class="symbol">(</span> <span class="param">bitwidth</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L56">source</a></div></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 show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">toTwos</span><span class="symbol">(</span> <span class="param">bitwidth</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L60">source</a></div></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="BigNumber--BigNumber--methods--comparison-and-equivalence"></a><h3 class="show-anchors"><div>Comparison and Equivalence<div class="anchors"><a class="self" href="/v5/api/utils/bignumber/#BigNumber--BigNumber--methods--comparison-and-equivalence"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">eq</span><span class="symbol">(</span> <span class="param">otherValue</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L152">source</a></div></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 show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">lt</span><span class="symbol">(</span> <span class="param">otherValue</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L156">source</a></div></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 show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">lte</span><span class="symbol">(</span> <span class="param">otherValue</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L160">source</a></div></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 show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">gt</span><span class="symbol">(</span> <span class="param">otherValue</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L164">source</a></div></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 show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">gte</span><span class="symbol">(</span> <span class="param">otherValue</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L168">source</a></div></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 show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">isZero</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L176">source</a></div></div><div class="body"><p>Returns true if and only if the value of <i>BigNumber</i> is zero.</p>
|
|
|
|
</div></div><a name="BigNumber--BigNumber--methods--conversion"></a><h3 class="show-anchors"><div>Conversion<div class="anchors"><a class="self" href="/v5/api/utils/bignumber/#BigNumber--BigNumber--methods--conversion"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">toNumber</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L180">source</a></div></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 show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">toString</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L189">source</a></div></div><div class="body"><p>Returns the value of <i>BigNumber</i> as a base-10 string.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">toHexString</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="/v5/api/utils/bytes/#DataHexString">DataHexString</a> ></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L197">source</a></div></div><div class="body"><p>Returns the value of <i>BigNumber</i> as a base-16, <code class="inline">0x</code>-prefixed <a href="/v5/api/utils/bytes/#DataHexString">DataHexString</a>.</p>
|
|
|
|
</div></div><a name="BigNumber--BigNumber--methods--inspection"></a><h3 class="show-anchors"><div>Inspection<div class="anchors"><a class="self" href="/v5/api/utils/bignumber/#BigNumber--BigNumber--methods--inspection"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">BigNumnber</span><span class="symbol">.</span><span class="method">isBigNumber</span><span class="symbol">(</span> <span class="param">object</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L271">source</a></div></div><div class="body"><p>Returns true if and only if the <i>object</i> is a BigNumber object.</p>
|
|
|
|
</div></div><a name="BigNumber--BigNumber--methods--examples"></a><h3 class="show-anchors"><div>Examples<div class="anchors"><a class="self" href="/v5/api/utils/bignumber/#BigNumber--BigNumber--methods--examples"></a></div></div></h3>
|
|
<div class="code">let a = BigNumber.from(42);
|
|
let b = BigNumber.from("91");
|
|
|
|
a.mul(b);
|
|
<span class="result ok">// { BigNumber: "3822" }
|
|
</span></div><a name="BigNumber--notes"></a><a name="BigNumber--BigNumber--notes"></a><h2 class="show-anchors"><div>Notes<div class="anchors"><a class="self" href="/v5/api/utils/bignumber/#BigNumber--notes"></a></div></div></h2><p>This section is a for a couple of questions that come up frequently.</p>
|
|
|
|
<a name="BigNumber--notes-safenumbers"></a><a name="BigNumber--BigNumber--notes--BigNumber--notes-safenumbers"></a><h3 class="show-anchors"><div>Why can't I just use numbers?<div class="anchors"><a class="self" href="/v5/api/utils/bignumber/#BigNumber--notes-safenumbers"></a></div></div></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)
|
|
<span class="result ok">// false
|
|
</span></div><p>To remedy this, all numbers (which can be large) are stored and manipulated as <a href="/v5/api/utils/bignumber/">Big Numbers</a>.</p>
|
|
|
|
<p>The functions <a href="/v5/api/utils/display-logic/#utils-parseEther">parseEther( etherString )</a> and <a href="/v5/api/utils/display-logic/#utils-formatEther">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>
|
|
|
|
<a name="BigNumber--BigNumber--notes--why-not-bignumber-js-bn-js-bigdecimal-etc"></a><h3 class="show-anchors"><div>Why not BigNumber.js, BN.js, BigDecimal, etc?<div class="anchors"><a class="self" href="/v5/api/utils/bignumber/#BigNumber--BigNumber--notes--why-not-bignumber-js-bn-js-bigdecimal-etc"></a></div></div></h3><p>Everyone has their own favourite Big Number library, and once someone has choosen one, it becomes part of their identity, like their editor, vi vs emacs. There are over 100 Big Number libraries on <a href="https://www.npmjs.com/search?q=bignumber">npm</a>.</p>
|
|
|
|
<p>One of the biggest differences between the Ethers <a href="/v5/api/utils/bignumber/">BigNumber</a> object and other libraries is that it is immutable, which is very important when dealing with the asynchronous nature of the blockchain.</p>
|
|
|
|
<p>Capturing the value is not safe in async functions, so immutability protects us from easy to make mistakes, which is not possible on the low-level library's objects which supports myriad in-place operations.</p>
|
|
|
|
<p>Second, the Ethers <a href="/v5/api/utils/bignumber/">BigNumber</a> provides all the functionality required internally and should generally be sufficient for most developers while not exposing some of the more advanced and rare functionality. So it will be eaiser to swap out the underlying library without impacting consumers.</p>
|
|
|
|
<p>For example, if <a href="https://www.npmjs.com/package/bn.js">BN.js</a> was exposed, someone may use the greatest-common-denominator functions, which would then be functionality the replacing library should also provide to ensure anyone depending on that functionality is not broken.</p>
|
|
|
|
<a name="BigNumber--BigNumber--notes--why-bn-js"></a><h3 class="show-anchors"><div>Why BN.js??<div class="anchors"><a class="self" href="/v5/api/utils/bignumber/#BigNumber--BigNumber--notes--why-bn-js"></a></div></div></h3><p>The reason why <a href="https://www.npmjs.com/package/bn.js">BN.js</a> is used internally as the big number is because that is the library used by <a href="https://www.npmjs.com/package/elliptic">elliptic</a>.</p>
|
|
|
|
<p>Therefore it <b>must</b> be included regardless, so we leverage that library rather than adding another Big Number library, which would mean two different libraries offering the same functionality.</p>
|
|
|
|
<p>This has saved about 85kb (80% of this library size) of library size over other libraries which include separate Big Number libraries for various purposes.</p>
|
|
|
|
<a name="BigNumber--BigNumber--notes--allow-us-to-set-a-global-big-number-library"></a><h3 class="show-anchors"><div>Allow us to set a global Big Number library?<div class="anchors"><a class="self" href="/v5/api/utils/bignumber/#BigNumber--BigNumber--notes--allow-us-to-set-a-global-big-number-library"></a></div></div></h3><p>Another comment that comes up frequently is tha desire to specify a global user-defined Big Number library, which all functions would return.</p>
|
|
|
|
<p>This becomes problematic since your code may live along side other libraries or code that use Ethers. In fact, even Ethers uses a lot of the public functions internally.</p>
|
|
|
|
<p>If you, for example, used a library that used <code class="inline">a.plus(b)</code> instead of <code class="inline">a.add(b)</code>, this would break Ethers when it tries to compute fees internally, and other libraries likely have similar logic.</p>
|
|
|
|
<p>But, the <a href="/v5/api/utils/bignumber/">BigNumber</a> prototype is exposed, so you can always add a <code class="inline">toMyCustomBigNumber()</code> method to all <a href="/v5/api/utils/bignumber/">BigNumber</a>'s globally which is safe.</p>
|
|
|
|
|
|
|
|
<div class="footer">
|
|
<div class="nav previous"><a href="/v5/api/utils/address/"><span class="arrow">←</span>Addresses</a></div>
|
|
<div class="nav next"><a href="/v5/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 License</a>. Generated on September 8, 2020, 1:8am.</div>
|
|
</div>
|
|
<script src="/v5/static/script.js" type="text/javascript"></script>
|
|
</body>
|
|
</html>
|