Formatting Patterns

Note: the same patterns are used for both formatting and parsing monetary amounts.

The supported pattern characters are:

• S outputs the currencies symbol e.g. $.

• C outputs part of the currency code e.g. USD. You can specify 1,2 or 3 C's. Specifying CCC will output the full code regardless of its length.

  • C - U

  • CC - US

  • CCC - USD - outputs the full currency code regardless of length.

• denotes a digit.

• '0' (zero) denotes a digit and and forces padding with leading and trailing zeros.

• '#' denotes a digit is output if required.

• , (comma) a placeholder for the grouping separator

• . (period) a place holder for the decimal separator

• '-' a place holder for a '-' character if the amount is -ve.

• '+' a place holder for a '-' or a '+' character dependant on whether the amount is -ve or +ve respectively.

The following rules apply:

• Currency placeholders (S or C) may appear only as a contiguous prefix or suffix (not both) and only one occurrence is allowed.

• A negative symbol '-' or '+' may appear at most once in the numeric portion and must be either the first or last character there.

Examples:

import 'money2.dart';
test('formatting', () {
        var usd = Currency.create('USD', 2);
        final lowPrice = Money.fromIntWithCurrency(1099, usd);
        expect(lowPrice.format('S000.000'), equals(r'$010.990'));

        var costPrice =
            Money.fromIntWithCurrency(10034530, usd); // 100,345.30 usd

        expect(costPrice.format('###,###.00'), equals('100,345.30'));

        expect(costPrice.format('S###,###.##'), equals(r'$100,345.3'));

        expect(costPrice.format('CC###,###.00'), equals('US100,345.30'));

        expect(costPrice.format('CCC###,###.##'), equals('USD100,345.3'));

        expect(costPrice.format('SCC###,###.00'), equals(r'$US100,345.30'));

        usd = Currency.create('USD', 2);
        costPrice = Money.fromIntWithCurrency(10034530, usd); // 100,345.30 usd
        expect(costPrice.format('SCC###,###.##'), equals(r'$US100,345.3'));

        final jpy = Currency.create('JPY', 0, symbol: '¥');
        costPrice = Money.fromIntWithCurrency(345, jpy); // 345 yen
        expect(costPrice.format('SCCC#'), equals('¥JPY345'));

// Bahraini dinar
        final bhd = Currency.create('BHD', 3,
            symbol: 'BD', decimalSeparator: ',', groupSeparator: '.');
        costPrice = Money.fromIntWithCurrency(100345, bhd); // 100.345 bhd
        expect(costPrice.format('SCCC0000.000'), equals('BDBHD0100,345'));
      });

Group Separators

Group Separators have a number of rules on how repeating patterns are treated. For most currencies the thousand separator repeats every three characters:

10,000,000

For india, the pattern is:

1,00,00,000 To support this in a generic manor the group separator has the following rules. Parsing of the group separator pattern is done 'right to left'. Digits are output according to the pattern until all of the pattern has been consumed.

Additional digits then look at the last two groups of the pattern:

#,##,####

In the above case # and ## are the last two groups, with # as the last group. If the last group contains more than 1 character we use that group as the pattern to repeat.

If the last group contains only a single character then we use the 2nd last group as the pattern to repeat.

So:

#,### == ###,###,###

##,### == ##,##,###

###,### - ###,###,###

#,#,### - #,#,#,###

Where in each pattern the last group (read right to left) is repeated indefinitely.