_section: Display Logic and Input @<display-logic>

When creating an Application, it is useful to convert between
user-friendly strings (usually displaying **ether**) and the
machine-readable values that contracts and maths depend on
(usually in **wei**).

For example, a Wallet may specify the balance in ether, and
gas prices in gwei for the User Interface, but when sending
a transaction, both must be specified in wei.

The [parseUnits](unit-conversion) will parse a string representing
ether, such as ``1.1`` into a [BigNumber](BigNumber) in wei, and is
useful when a user types in a value, such as sending 1.1 ether.

The [formatUnits](unit-conversion) will format a [BigNumberish](BigNumberish)
into a string, which is useful when displaying a balance.


_subsection: Units @<display-logic--units>

_heading: Decimal Count

A **Unit** can be specified as a number, which indicates the
number of decimal places that should be used.

**Examples:**

- 1 ether in wei, has **18** decimal places (i.e. 1 ether represents 10^^18^^ wei)
- 1 bitcoin in Satoshi, has **8** decimal places (i.e. 1 bitcoin represents 10^^8^^ satoshi)

_heading: Named Units @<display-logic--named-units>

There are also several common **Named Units**, in which case their name (as
a string) may be used.

_table: @STYLE<compact>

|  **Name**    |  **Decimals**  |
|  //wei//     |      0         |
|  //kwei//    |      3         |
|  //mwei//    |      6         |
|  //gwei//    |      9         |
|  //szabo//   |     12         |
|  //finney//  |     15         |
|  //ether//   |     18         |


_subsection: Functions @<display-logic--functions>

_heading: Formatting @<display-logic--formatting>

_property: ethers.utils.commify(value) => string  @<utils-commify> @SRC<units>
Returns a string with value grouped by 3 digits, separated by ``,``.

_code: @lang<javascript>

//_hide: const commify = ethers.utils.commify;

//_result:
commify("-1000.3000");
//_log:

_heading: Conversion @<unit-conversion>

_property: ethers.utils.formatUnits(value [ , unit = "ether" ] ) => string  @<utils-formatUnits> @SRC<units>
Returns a string representation of //value// formatted with //unit//
digits (if it is a number) or to the unit specified (if a string).

_code: @lang<javascript>

//_hide: const formatUnits = ethers.utils.formatUnits;
//_hide: const BigNumber = ethers.BigNumber;

const oneGwei = BigNumber.from("1000000000");
const oneEther = BigNumber.from("1000000000000000000");

//_result:
formatUnits(oneGwei, 0);
//_log:

//_result:
formatUnits(oneGwei, "gwei");
//_log:

//_result:
formatUnits(oneGwei, 9);
//_log:

//_result:
formatUnits(oneEther);
//_log:

//_result:
formatUnits(oneEther, 18);
//_log:

_property: ethers.utils.formatEther(value) => string  @<utils-formatEther> @SRC<units>
The equivalent to calling ``formatUnits(value, "ether")``.

_code: @lang<javascript>

//_hide: const formatEther = ethers.utils.formatEther;
//_hide: const BigNumber = ethers.BigNumber;

const value = BigNumber.from("1000000000000000000");

//_result:
formatEther(value);
//_log:

_property: ethers.utils.parseUnits(value [ , unit = "ether" ] ) => [BigNumber](BigNumber)  @<utils-parseUnits> @SRC<units>
Returns a [BigNumber](BigNumber) representation of //value//, parsed with
//unit// digits (if it is a number) or from the unit specified (if
a string).

_code: @lang<javascript>

//_hide: const parseUnits = ethers.utils.parseUnits;

//_result:
parseUnits("1.0");
//_log:

//_result:
parseUnits("1.0", "ether");
//_log:

//_result:
parseUnits("1.0", 18);
//_log:

//_result:
parseUnits("121.0", "gwei");
//_log:

//_result:
parseUnits("121.0", 9);
//_log:

_property: ethers.utils.parseEther(value) => [BigNumber](BigNumber)  @<utils-parseEther> @SRC<units>
The equivalent to calling ``parseUnits(value, "ether")``.

_code: @lang<javascript>

//_hide: const parseEther = ethers.utils.parseEther;

//_result:
parseEther("1.0");
//_log:

//_result:
parseEther("-0.5");
//_log: