# decimalDigits

When defining a Currency you must define the number of digits after the decimal place that will be stored. This is referred to as the decimalDigits (or more technically scale) of the currency.

```dart
 test('parse with Currency', () {
        final aud = Currency.create('AUD', 2);
        expect(aud.decimalDigits, equals(2));
});
```

In the above example we create a Currency for the Australian Dollar with 2 decimal digits.

The defined number of decimal digits will affect all calculations performed on Money objects created for the Currency in that all calculations will be rounded to the defined number of decimal digits.

### Parsing

When we parse a monetary amount the Currencies number of decimal digits affects how the amount is parsed.

If we parse an AUD amount it will always be stored with 2 decimals regardless of the value we passed:

```
   test('parsing', () {
        final aud = Currency.create('AUD', 2);
        final one = aud.parse(r'$1.12345');
        expect(one.minorUnits.toInt(), equals(112));
      });
```

As you can see, even though we parsed 5 decimal places we only stored 2 decimal places as the currency is defined as storing 2 decimal digits.

### Formatting

The number of decimal digits also affects formatting.   As the monetary amount is always rounded to the number of decimal digits you can't print more decimal places than the amount retrains.

```dart
final aud = Currency.create('AUD', 2);
final one = aud.parse(r'$1.12345');
expect(one.format('#.###'), equals('1.12'));
```

You can however force trailing zeros to be appended by using '0' in your format pattern.

```dart
final aud = Currency.create('AUD', 2);
final one = aud.parse(r'$1.12345');
expect(one.format('0.000'), equals('1.120'));
```

In practice it is recommended that you only use the '0' pattern character for decimal places so you always output a consistent no. of decimals.

## Customising the number of Decimal Digits

Note: Money2 is tested with up to 100 decimal digits but should work with a higher precisions as we store the amount as a BigInt which is only limited by memory.

Money ships with a collection of CommonCurrencies.  Each of the common currencies has a precision that conforms to the currencies standard number of decimal digits. e.g.  The USD has 2 decimal digits.

If you need to use a non-standard number of decimals for a Currency then you will need to create your own currency object rather than relying on one of the CommonCurrencies or copy one of the common currencies.

```dart
CommonCurrencies().aud.copyWith(decimalDigits: 4);
Currency.create('AUD', 4, pattern: '0.0000');

```

If you entire application needs to use the high precision version of the AUD you can overwrite the standard CommonCurrency:

```dart
  test('formatting - trailing zeros', () {
        Currencies()
            .register(CommonCurrencies().aud.copyWith(decimalDigits: 5));
        expect(Currencies().find('AUD')!.decimalDigits, equals(5));
      });
```

Once you have registered the updated currency any code that references  the 'AUD' currency by its code will return your custom currency.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://money2.onepub.dev/creating-money/decimaldigits.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.