ethers.js/docs/source/api-utils.rst

Utilities
*********

The utility functions exposed in both the *ethers* umbrella package and the *ethers-utils*::

    var utils = ethers.utils;


-----

.. _bignumber:

Big Numbers
===========

A BigNumber is an immutable object which allow math operations to be carried
out on numbers far larger than :ref:`JavaScript can accurately handle <ieee754>`.
Many functions return these, so it is important to understand how to work with these.

:sup:`prototype` . add ( otherValue )
    Return a new BigNumber of this plus *otherValue*

:sup:`prototype` . sub ( otherValue )
    Return a new BigNumber of this minus *otherValue*

:sup:`prototype` . mul ( otherValue )
    Return a new BigNumber of this times *otherValue*

:sup:`prototype` . div ( otherValue )
    Return a new BigNumber of this divided by *otherValue*

:sup:`prototype` . mod ( otherValue )
    Return a new BigNumber of this modulo *otherValue*

:sup:`prototype` . eq ( otherValue )
    Return true if this is equal to *otherValue*

:sup:`prototype` . lt ( otherValue )
    Return true if this is less than *otherValue*

:sup:`prototype` . lte ( otherValue )
    Return true if this is less or equal to *otherValue*

:sup:`prototype` . gt ( otherValue )
    Return true if this is greater than *otherValue*

:sup:`prototype` . gte ( otherValue )
    Return true if this is greater than or equal to *otherValue*

:sup:`prototype` . isZero ( )
    Return true if this is equal to zero

:sup:`prototype` . toNumber ( )
    Return a JavaScript number representation; an error is thrown if the value is
    outside the safe range for JavaScript IEEE 754 64-bit floating point numbers

:sup:`prototype` . toString ()
    Return a decimal string representation

:sup:`prototype` . toHexString ( )
    Return a **0x prefixed** hexidecimal representation


Creating Instances
------------------

:sup:`utils` **. bigNumberify** ( value )
    Returns a BigNumber instance of *value*. The *value* may be anything which can be
    reliably converted into a BigNumber:

    *Decimal String*
      A string consisting of the decimal digits 0 through 9, optionally with a leading
      negative sign.

      **examples:** utils.bigNumberify("42")

    *Hex String*
        A :ref:`hex string <hexstring>`, witch has aa **prefix of 0x** and consisting
        of the hexidecimal digits 0 through 9 and a through f, case-insensitive. Must
        be non-negative.

        **examples:** utils.bigNumberify("0x2a")

    *JavaScript Numbers*
        Numbers must be within the `safe range`_ for JavaScript.

        **examples:** utils.bigNumberify(42)

    *Arrayish*
        Treats the :ref:`arrayish <api-arrayish>` as a big-endian encoded bytes representation.

        **examples:** utils.bigNumberify([ 42 ])

    *BigNumber*
        Returns *value*, since a BigNumber is immutable.

.. _safe range: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger

*Examples*
----------

::

    var gasPriceWei = utils.bigNumberify("20902747399");
    var gasLimit = utils.bigNumberify(3000000);

    var maxCostWei = gasPriceWei.mul(gasLimit)
    console.log("Max Cost: " + maxCostWei.toString());
    // "Max Cost: 62708242197000000"

    console.log("Number: " + maxCostWei.toNumber());
    // throws an Error, the value is too large for JavaScript to handle safely

-----


Ether Strings and Wei
=====================

:sup:`utils` . etherSymbol
    The ethereum symbol (the Greek letter *Xi* )

.. _parseEther:

:sup:`utils` . parseEther ( etherString )
    Parse the *etherString* representation of ether into a BigNumber instance
    of the amount of wei.

.. _formatEther:

:sup:`utils` . formatEther ( wei [ , options ] )
    Format an amount of *wei* into a decimal string representing the amount of ether. The
    *options* object supports the keys ``commify`` and ``pad``. The output will always
    include at least one whole number and at least one decimal place.


*Examples*
----------

::

    var wei = utils.parseEther('1000.0');
    console.log(wei.toString(10));
    // "1000000000000000000000"

    console.log(utils.formatEther(0));
    // "0.0"

    var wei = utils.bigNumberify("1000000000000000000000");

    console.log(utils.formatEther(wei));
    // "1000.0"

    console.log(utils.formatEther(wei, {commify: true}));
    // "1,000.0"

    console.log(utils.formatEther(wei, {pad: true}));
    // "1000.000000000000000000"       (18 decimal places)

    console.log(utils.formatEther(wei, {commify: true, pad: true}));
    // "1,000.000000000000000000"      (18 decimal places)


-----

Addresses
=========

There are :ref:`several formats <checksum-address>` available on the Ethereum network for
addresses, and it is often useful to be able to convert between them.


.. _api-getAddress:

:sup:`utils` . getAddress ( address [ , generateIcap ] )
    Normalize an address to a :ref:`checksum address <checksum-address>`, or as an
    :ref:`ICAP <icap-address>` address if *generateIcap* is true.

*Examples*
----------

::

    var address = "0xd115bffabbdd893a6f7cea402e7338643ced44a6";
    var icapAddress = "XE93OF8SR0OWI6F4FO88KWO4UNNGG1FEBHI";

    console.log('Checksum address: ' + utils.getAddress(address));
    // "0xD115BFFAbbdd893A6f7ceA402e7338643Ced44a6"

    console.log('Checksum address: ' + utils.getAddress(icapAddress));
    // "0xD115BFFAbbdd893A6f7ceA402e7338643Ced44a6"

    console.log('ICAP address:' + utils.getAddress(address, true));
    // "XE93OF8SR0OWI6F4FO88KWO4UNNGG1FEBHI"

    console.log('ICAP address:' + utils.getAddress(icapAddress, true));
    // "XE93OF8SR0OWI6F4FO88KWO4UNNGG1FEBHI"


-----


UTF-8 Strings
=============

:sup:`utils` . toUtf8Bytes ( string )
    Converts a UTF-8 string to a Uint8Array.

:sup:`utils` . toUtf8String ( hexStringOrArrayish )
    Converts a hex-encoded string or array to its UTF-8 representation.

*Examples*
----------

::

    var text = "Hello World";

    var bytes = utils.toUtf8Bytes(text);
    console.log(bytes);
    // Uint8Array [72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100]

    console.log(utils.toUtf8String(bytes));
    // "Hello World"

    var hexString = "0x48656c6c6f20576f726c64";
    console.log(utils.toUtf8String(hexString));
    // "Hello World"


-----

Cryptographic Functions
=======================

:sup:`utils` . keccak256 ( hexStringOrArrayish )
    Compute the keccak256 cryptographic hash of a value, returned as a hex string. (Note:
    often Ethereum refers to this, **incorrectly**, as SHA3)

:sup:`utils` . sha256 ( hexStringOrArrayish )
    Compute the SHA2-256 cryptographic hash of a value, returned as a hex string.

:sup:`utils` . randomBytes ( length )
    Return a Uint8Array of cryptographically secure random bytes


*Examples*
----------

**Hashing Binary Data** ::

    console.log(utils.keccak256([ 0x42 ]));
    // '0x1f675bff07515f5df96737194ea945c36c41e7b4fcef307b7cd4d0e602a69111'

    console.log(utils.keccak256("0x42"));
    // '0x1f675bff07515f5df96737194ea945c36c41e7b4fcef307b7cd4d0e602a69111'


    console.log(utils.sha256([ 0x42 ]));
    // '0xdf7e70e5021544f4834bbee64a9e3789febc4be81470df629cad6ddb03320a5c'

    console.log(utils.sha256("0x42"));
    // '0xdf7e70e5021544f4834bbee64a9e3789febc4be81470df629cad6ddb03320a5c'


**Hashing UTF-8 Strings** ::

    // Convert the string to binary data
    var utf8Bytes = utils.toUtf8Bytes('Hello World');

    console.log(utils.keccak256(utf8Bytes));
    // '0x592fa743889fc7f92ac2a37bb1f5ba1daf2a5c84741ca0e0061d243a2e6707ba'

    console.log(utils.sha256(utf8Bytes));
    // '0xa591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e'


**Random Bytes** ::

    console.log(utils.randomBytes(3));
    // Uint8Array [ 194, 22, 140 ]


-----

.. _api-arrayish:

Arrayish
========

An arrayish object is any such that it:

* has a *length* property
* has a value for each index from 0 up to (but excluding) *length*
* has a valid byte for each value; a byte is an integer in the range [0, 255]

:sup:`utils` . isArrayish ( object )
    Returns true if *object* can be treated as an arrayish object.

:sup:`utils` . arrayify ( hexStringOrArrayish )
    Returns a Uint8Array of a hex string, BigNumber or of an `Arrayish`_ object.

:sup:`utils` . concat ( arrayOfHexStringsAndArrayish )
    Return a Uint8Array of all *arrayOfHexStringsAndArrayish* concatenated.

:sup:`utils` . padZeros ( typedUint8Array, length )
    Return a Uint8Array of *typedUint8Array* with zeros prepended to *length* bytes.

:sup:`utils` . stripZeros ( hexStringOrArrayish )
    Returns a Uint8Array with all leading zero **bytes** striped.

-----

.. _hexstring:

Hex Strings
===========

A hex string is **always** prefixed with "0x" and consists of the characters
0 -- 9 and a -- f. It is always returned lower case with even-length, but any hex
string passed into a function may be any case and may be odd-length.


:sup:`utils` . hexlify ( numberOrBigNumberOrHexStringOrArrayish )
    Converts any number, :ref:`BigNumber <bignumber>`, hex string or
    `Arrayish`_ to a hex string. (otherwise, throws an error)

-----

Contract Addresses
==================

Every contract deployed on the Ethereum network requires an address (you can think
of this as the memory address which the running application lives at). The address
is generated from a cryptographic has of the address of the creator and the nonce
of the transaction.

:sup:`utils` . getContractAddress ( transaction )
    Computes the contract address a contract would have if this transaction
    created a contract. (transaction requires only ``from`` and ``nonce`` be
    defined)

*Examples*
----------

::

    // Ropsten: 0x5bdfd14fcc917abc2f02a30721d152a6f147f09e8cbaad4e0d5405d646c5c3e1
    var transaction = {
        from: '0xc6af6e1a78a6752c7f8cd63877eb789a2adb776c',
        nonce: 0
    };

    console.log(utils.getContractAddress(transaction));
    // "0x0CcCC7507aEDf9FEaF8C8D731421746e16b4d39D"

-----

.. EOF