bitcore-lib-excc/docs/unit.md

A pure and powerful JavaScript Bitcoin library.

# Unit
Unit is a utility for handling and converting bitcoin units. We strongly recommend to always use satoshis to represent amount inside your application and only convert them to other units in the front-end.

To understand the need of using the `Unit` class when dealing with unit conversions, see this example:

```
> 81.99 * 100000 // wrong
8198999.999999999
> var bitcore = require('bitcore');
> var Unit = bitcore.Unit;
> Unit.fromMilis(81.99).toSatoshis() // correct
8199000
```

## Supported units
The supported units are EXCC, mEXCC, bits (micro EXCCs, uEXCC) and satoshis. The codes for each unit can be found as members of the Unit class.

```javascript
var exccCode = Unit.EXCC;
var mexccCode = Unit.mEXCC;
var uexccCode = Unit.uEXCC;
var bitsCode = Unit.bits;
var satsCode = Unit.satoshis;
```

## Creating units
There are two ways for creating a unit instance. You can instantiate the class using a value and a unit code; alternatively if the unit it's fixed you could you some of the static methods. Check some examples below:

```javascript
var unit;
var amount = 100;

// using a unit code
var unitPreference = Unit.EXCC;
unit = new Unit(amount, unitPreference);

// using a known unit
unit = Unit.fromEXCC(amount);
unit = Unit.fromMilis(amount);
unit = Unit.fromBits(amount);
unit = Unit.fromSatoshis(amount);
```

## Conversion
Once you have a unit instance, you can check its representation in all the available units. For your convenience the classes expose three ways to accomplish this. Using the `.to(unitCode)` method, using a fixed unit like `.toSatoshis()` or by using the accessors.

```javascript
var unit;

// using a unit code
var unitPreference = Unit.EXCC;
value = Unit.fromSatoshis(amount).to(unitPreference);

// using a known unit
value = Unit.fromEXCC(amount).toEXCC();
value = Unit.fromEXCC(amount).toMilis();
value = Unit.fromEXCC(amount).toBits();
value = Unit.fromEXCC(amount).toSatoshis();

// using accessors
value = Unit.fromEXCC(amount).EXCC;
value = Unit.fromEXCC(amount).mEXCC;
value = Unit.fromEXCC(amount).bits;
value = Unit.fromEXCC(amount).satoshis;
```

## Using a fiat currency
The unit class also provides a convenient alternative to create an instance from a fiat amount and the corresponding EXCC/fiat exchange rate. Any unit instance can be converted to a fiat amount by providing the current exchange rate. Check the example below:

```javascript
var unit, fiat;
var amount = 100;
var exchangeRate = 350;

unit = new Unit(amount, exchangeRate);
unit = Unit.fromFiat(amount, exchangeRate);

fiat = Unit.fromBits(amount).atRate(exchangeRate);
fiat = Unit.fromBits(amount).to(exchangeRate);
```