money2 library

Money2 stores, parses, formats and allows precision mathematical operations on monetary amounts and their associated currency.

The Currency class allows you to define the key attributes of a currency such as Symbol, isoCode, precision and a default format.

The Money class stores the underlying values using a BigInt. The value is stored using the currencies 'minor' units (e.g. cents).

This allows for precise calculations as required when handling money.

The ExchangePlatform allows you to set up a table of exchange rates for converting between currencies.

Key features of Money2:

simple and expressive formating.
simple parsing of monetary amounts.
multi-currency support.
intuitive maths operations.
fixed precision storage to ensure precise calcuation.
detailed documentation and extensive examples to get you up and running.
pure dart implementation.
Open Source MIT license.
Using Money2 will make you taller.

The package use the following terms:

Minor Units - the smallest unit of a currency e.g. cents.
Major Units - the integer component of a currency - e.g. dollars
isoCode - the currency isoCode. e.g. USD
symbol - the currency symbol. e.g. '$'. It should be noted that not every currency has a symbol.
pattern - a pattern used to control the display format.
precision - the number of decimal places assumed when a minor unit value (e.g. cents) is passed.
decimal separator - the character that separates the fraction part from the integer of a number e.g. '10.99'. This defaults to '.' but can be changed to ','
group separator - the character that is used to format groups (e.g. 100,000). This can be changed to '.'

Using the Money and Currency classes is easy.

import 'money2.dart';
Currency aud = Currency.create('AUD', 2, pattern:r'$0.00');
Money costPrice = Money.fromInt(1000, aud);
print(costPrice.toString());
  > $10.00

Money spareChange = Money.parse('$10.50', aud);

Money lunchMoney = aud.parse('$11.50');

Money taxInclusive = costPrice * 1.1;
print(taxInclusive.toString());
  > $11.00

print(taxInclusive.format('SCCC0.00'));
  > $AUD11.00

print(taxInclusive.format('SCCC0'));
  > $AUD11

Classes

CommonCurrencies: Provides a list of the most common currencies.
Currencies: A factory for registering, parsing and finding Currency instances.
Currency: Allows you to create a Currency which is then used to construct Money instances.
ExchangePlatform: The ExchangePlatform allows you to register a set of ExchangeRate which you can then use to do currency conversions.
ExchangeRate: When defining an exchange rate we need to specify the conditions under which the exchange is calculated.
Fixed: Represents a fixed scale decimal no.
Money: Allows you to store, print and perform mathematically operations on money whilst maintaining precision.
MoneyData: DTO for exchange of data between an instance of Money and PatternEncoder or PatternDecoder.
MoneyDecoder<T>: Bases class for implementing a decoder for money.
MoneyEncoder<T>: Bases class for implementing a encoder for money.
Percentage: Helper class to allow us to do percentage calculations on Money amounts. Percentage is described as a decimal Fixed so 20% is expressed as 20.0

Typedefs

CurrencyIsoCode = String

Exceptions / Errors

AmountTooLargeException: Thrown if a number larger than the supported ranges is passed in. This will only occur if you call Fixed.fromNum with scale > 20 or a absolute value of > 10^21 If you need larger numbers then use one of the alternate constructors.
FixedException: Base exception of all exceptions thrown from the Fixed package.
FixedParseException: Exception thrown when a parse fails.
IllegalFixedPatternException: Thrown when you pass an invalid pattern to Fixed.format.
IllegalPatternException: Thrown when you pass an invalid pattern to Money.format.
MismatchedCurrencyException: Thrown if an exchange is attempted with a Money has a Currency which doesn't match the exchange rate.
MoneyException: Base class of all exceptions thrown from Money2.
MoneyParseException: Exception thrown when a parse fails.
UnknownCurrencyException: Thrown if the currency is not registered.
UnknownExchangeRateException: Thrown if an attempt is made to calcuate the value of a Money amount in another currency for which there isn't a registered exchange rate.

money2 library

Classes

Typedefs

Exceptions / Errors

money2 package

money2 library