money2 1.2.2

  • Readme
  • Changelog
  • Example
  • Installing
  • 78

Money2 #

This is a Dart implementation of Money and Currency classes

Overview #

Money2 is a fork of LitGroup's Money package.

The aim of this fork is to improve the documentation and introduce a number of convenience methods to make it easier to work with Money. This package also changes some of the naming convention to provide a (hopefully) more intuiative api.

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 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.

Lets start with some examples:

import 'money2.dart';

Currency usdCurrency = Currency.create('USD', 2);

// Create money from an int.
Money costPrice = Money.fromInt(1000, usdCurrency);
print(costPrice.toString());
  > $10.00

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

print(taxInclusive.format("SCC #.00"));
  > $US 11.00

// Create money from an String using the `Currency` instance.
Money parsed = usdCurrency.parse("\$10.00");
print(parsed.format("SCCC 0.0"));
  > $USD 10.00

// Create money from an int which contains the MajorUnit (e.g dollars)
Money buyPrice = Money.from(10);
print(buyPrice.toString());
  > $10.00

// Create money from a double which contains Major and Minor units (e.g. dollars and cents)
// We don't recommend transporting money as a double as you will get rounding errors.
Money sellPrice = Money.from(10.50);
print(sellPrice.toString());
  > $10.50

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
  • code - the currency code. 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 parsing and the display format.
  • minorDigits - the number of minor Units (e.g. cents) which should be used when storing the currency.
  • 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 ','
  • thousands separator - the character that is used to format thousands (e.g. 100,000). Defaults to ',' but can be changed to '.'

Creating a Currency #

Before you can start creating Money instances you first need a Currency.

The Money2 package does not contain any 'built-in' Currency types. Instead you must create your own Currency instances as required.

Creating a Currency is simple:

import 'money2.dart';
// US dollars which have 2 digits after the decimal place.
final usd = Currency.create('USD', 2);

You would normally create a single instance of a Currency and re-use that throughout your code base.

Registering a Currency #

To make your life easier we provide the Currencies class which is a singleton that allows you to register your currencies and quickly retrieve them from anywhere in your code.

Note: it is NOT a requirement to register a currency. You can just recreate and use currencies whenever and wherever you choose.

import 'money2.dart';
Currency usd = Currency.create('USD', 2);
Currencies.register(usd);
Currency aud = Currency.create('AUD', 2);
Currencies.register(aud);
Currency euro = Currency.create('EUR', 2, symbol: '€', invertSeparators: true, pattern: "S0.000,00");
Currencies.register(euro);
final Currency jpy = Currency.create('JPY', 0, symbol: '¥', pattern: 'S0');
Currencies.register(jpy);
// find a registred currency.
Currency nowUseIt = Currencies.find('USD');
Money cost = Money.fromInt(1000, nowUseIt);
cost.toString();
> $10.00

Common Currencies #

For your convenience here is a list of some of the more common currencies and their correct definitiona;

import 'money2.dart';
// USA 
Currency usd = Currency.create('USD', 2);
// Australia
Currency aud = Currency.create('AUD', 2);
// New Zealand
Currency aud = Currency.create('NZD', 2);
// Canada
Currency cad = Currency.create('CAD', 2);
// Swiss Franc
Currency chf = Currency.create('CHF', 2, symbol: 'fr');
// British Pound Sterling
Currency gbp = Currency.create('GBP', 2, symbol: '£');
// Chinese renminbi
Currency cny = Currency.create('CNY', 2, symbol: '¥');
// euro
Currency euro = Currency.create('EUR', 2, symbol: '€', invertSeparators: true, pattern: "S0.000,00");
// Japanese Yen
Currency jpy = Currency.create('JPY', 0, symbol: '¥', pattern: 'S0');
// Mexican Peso
Currency mxn = Currency.create('MXN', 2);
// Norwegian krone
Currency nok = Currency.create('NOK', 2, symbol: 'kr');
// South Korean Won
Currency krw = Currency.create('KRW', 0, symbol: '₩', pattern: "S0");
// Turkish Lira
Currency ltry = Currency.create('TRY', 2, symbol: '₺');
// Indian Rupee
Currency INR = Currency.create('INR', 2, symbol: '₹', invertSeparators: true, pattern: "S000.00,00");
// Russian Ruble
Currency rub = Currency.create('RUB', 2, symbol: '₽');
// Brazilian Real
Currency brl = Currency.create('BRL', 2, symbol: 'R$');
// South African Rand
Currency zar = Currency.create('ZAR', 2, symbol: 'R');

import 'money2.dart';
Currency usd = Currency.create('USD', 2, symbol: '¥', invertSeparators: true, pattern: "S0.000");

Currency jpy = Currency.create('JPY', 0, symbol: '¥', invertSeparators: true, pattern: "S0.000");
Currency euro = Currency.create('EUR', 2, symbol: '€', invertSeparators: true, pattern: "S0.000,00");

Default format #

The Currency class also allows you to specify a default format which is used when parsing or formating a Money instance.

Note: if you don't specify a pattern it defaults to "S0.00"

import 'money2.dart';
Currency aud = Currency.create('AUD', 2, pattern:"S0.00");
Money costPrice = Money.fromInt(1099, aud);
print(costPrice.toString());
  > $10.99

final Currency jpy = Currency.create('JPY', 0, symbol: '¥', pattern: 'S0');
Money yenCostPrice = Money.fromInt(1099, jpy);
print(yenCostPrice.toString());
  > ¥1099

Currency euro = Currency.create('EUR', 2, symbol: '€', invertSeparators: true, pattern: "S0.000,00");
Money euroCostPrice = Money.fromInt(899, euro);
print(euroCostPrice.toString());
  > €8,99

Money usdValue = usd.parse("€7,10");
print(euroCostPrice.toString());
  > €7,10

Money euroValue = euro.parse("\$2.99");
print(euroValue.toString());
  > $2.99

You can also use the Money.format method to define a specific format where required. See details below

Symbols #

A number of currency have different symbols, you can specify the symbol when creating the currency.

import 'money2.dart';
// Create a currency for Japan's yen with the correct symbol
Currency jpy = Currency.create('JPY', 0, symbol: '¥');
Currency euro = Currency.create('EUR', 2, symbol: '€');

Separators #

Decimal Separator #

Numbers use a decimal separator to separate the integer and factional component of a number.

In the english speaking world the period (.) is used as the decimal separator, however in large parts of the world the comma (,) is used as the decimal separator.

e.g.

  • $USD1,000.99 (one thousand dollars and 99 cents)

  • €EUR1.000,99 (one thousand euro and 99 cents)

Money2 use the English convention. To switch to the Euro style convention set the invertSeparators argument to true when creating a currency.

You will also need to provide an appropriate pattern.

import 'money2.dart';
Currency euro = Currency.create('EUR', 2, symbol: '€', invertSeparators: true, pattern: "S0.000,00");

Thousand Separator #

Numbers also use a thousands separator to help format large numbers by placing a separator every few digits. e.g. $100,000.00

In the english speaking world the comma (,) is used as the thousands separator however in large parts of the world the period (.) is used as the thousands separator.

Money2 use the English convention. To switch to the Euro style convention set the invertSeparators argument to true when creating a currency.

You will also need to provide an appropriate pattern.

import 'money2.dart';
Currency euro = Currency.create('EUR', 2, symbol: '€', invertSeparators: true, pattern: "S0.000,00");

Creating Money #

For you convience we provide a number of methods to create a Money instance.

  • Money.parse - parse a monetary string containing an amount.
  • Money.fromInt - from a minorUnit (e.g. cents)
  • Money.fromBigInt - from a minorUnit
  • Money.from - from a num (int or double)
  • Currency.parse - parse a monetary string assuming the currency
  • Currencies.parse - parse a monetary amount and determine the currency from the embedded currency code.

The Money variants all require you to pass in the Currency. The Currency variant requires only the monetary value. The Currencies variant is able to determine the Currency if the passed string amount contains a currency code.

The two most common methods are:

  • Money.fromInt
  • Currency.parse

Money.parse #

Parses a string containing a monetary value.

Money.fromInt is faster if you already have the value represented as an integer in minor units.

The simplest variant of Money.parse relies on the default pattern of the passed currency.

import 'money2.dart';
final Currency usd = Currency.create('USD', 2);
final Money amount = Money.parse("\$10.25", usd);

You can also pass an explict pattern.

import 'money2.dart';
final Currency usd = Currency.create('USD', 2);
final Money amount = Money.parse("\$10.25", usd, 'S0.0');

Currency.parse #

The simplest variant of Currency.parse relies on the default pattern of the currency.

import 'money2.dart';
final Currency usd = Currency.create('USD', 2);
Money value = usd.parse("\$10.25");

You can also pass an explict pattern.

import 'money2.dart';
final Currency usd = Currency.create('USD', 2);
Money value = usd.parse("\$10.25", 'S0.0');

Money.fromInt #

Money can be instantiated by providing the amount in the minor units of the currency (e.g. cents):

// Create a currency that normally displays 2 decimal places:
final Currency usd = Currency.create('USD', 2);

// Create a currency for Japan's yen with the correct symbol (we default to $)
final Currency jpy = Currency.create('JPY', 0, symbol: '¥');


// Create a money value of $5.10 usd from an int
Money fiveDollars = Money.fromInt(510, usd);

// Create a money value of ¥25010 from a big int.
Money bigDollars = Money.fromBigInt(BigInt.from(25010), jpy);

Currencies.parse #

This method is extremely useful if you have a database/list of monetary amounts that contain their currency code. 'Currencies.parse' will create a Money instance of the correct currency based on the currency code embedded in the monetary amount.

An exception will be thrown if the monetary amount does not include a currency code.

Before you can use Currencies.parse you must first register the list of Currency's that you need to support.

If you try to create a Money instance for an unregistered Currency an UknownCurrencyException will be thrown.

import 'money2.dart';
final Currency usd = Currency.create('USD', 2);
final Currency jpy = Currency.create('JPY', 0, symbol: '¥');

Currencies.register(usd);
Currencies.register(jpy);

Money usdAmount = Currencies.parse("\$USD10.25", "SCCC0.0");
Money jpyAmount = Currencies.parse("JPY100", "CCC0");

Formatting #

The money class provides a simple way of formatting currency using a pattern.

When you create a Currency instance you can provide a default format pattern which is used to format a Money instance when you call Money.toString().

In some cases you may however want to format a Money instances in a specific manner. In this case you can use:

Money.format(String pattern)

import 'money2.dart';
final Currency usd = Currency.create('USD', 2);
Money one = Money.fromInt(100, usd);
print(one.format("S0"));
  > $1

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 denotes a digit and and forces padding with leading and trailing zeros.
 * , (comma) a placeholder for the grouping separtor
 * . (period) a place holder for the decimal separator 
 

Examples:

import 'money2.dart';
final Currency usd = Currency.create('USD', 2);
Money lowPrice = Money.fromInt(1099, usd);
print(lowPrice.format("S000.000"));
  > $010.990

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

print(costPrice.format("###,###.##"));
  > 100,345.30

print(costPrice.format("S###,###.##"));
  > $100,345.3

print(costPrice.format("CC###,###.#0"));
  > US100,345.30

print(costPrice.format("CCC###,###.##"));
  > USD100,345.3

print(costPrice.format("SCC###,###.#0"));
  > $US100,345.30

final usd = Currency.create('USD', 2);
Money costPrice = Money.fromInt(10034530, usd);  // 100,345.30 usd
print(costPrice.format("SCC###,###.##"));
  > $US100,345.3

final jpy = Currency.create('JPY', 0, symbol: '¥');
Money costPrice = Money.fromInt(345, jpy);  // 345 yen
print(costPrice.format("SCCC#"));
  > ¥JPY345

// Bahraini dinar
final bhd = Currency.create('BHD', 3, symbol: 'BD', invertSeparators: true);
Money costPrice = Money.withInt(100345, bhd);  // 100.345 bhd
print(costPrice.format("SCCC0000,###")); 
  > BDBHD0100,345

Exchange Rates #

When manipulating monetary amounts you often need to convert between currencies.

Money2 provide a simple method to convert a Money instance to another currency using an exchange rate.

To converts a Money instance into a target Currency use the Money.exchangeTo method.

To do this you need to define an exchange rate which is simply another Money instance. That 'exchange rate' Money instance is created with the target Currency and having a monetary value which represents the exchange rate.

Example #

Lets say you have an invoice in Australian Dollars (AUD) which you need to convert to US Dollars (USD).

Start by google the exchange rate for AUD to USD. You are likely to find something similar to:

1 AUD = 0.68c USD

Which means that for each Australian Dollar you will recieve 0.68 US cents. (AKA I'm not traveling to the USA this year).

To do the above conversion:

import 'money2.dart';
// Create the source and the target Currencies
Currency aud = Currency.create("AUD", 2, pattern="SCCC 0.00");
Currency usd = Currency.create("USD", 2, pattern="SCCC 0.00");

// Create the AUD invoice amount ($10.00)
Money invoiceAmount = Money.fromInt(1000, aud);
print(invoiceAmount);
  > $AUD 10.00

// Define the exchange rate in USD (0.68c)
Money auToUsExchangeRate = Money.fromInt(68, usd);
print(auToUsExchangeRate);
  > $USD 0.68

// Now do the conversion.
Money usdAmount = invoiceAmount.exchangeTo(auToUsExchangeRate);
print(usdAmount);
  > $USD 6.80

Comparison #

Equality operator (==) returns true when both operands are in the same currency and have equal amount.

import 'money2.dart';
fiveDollars == fiveDollars;  // => true
fiveDollars == sevenDollars; // => false
fiveDollars == fiveEuros;    // => false (different currencies)

Money values can be compared with operators <, <=, >, >=, or method compareTo() from the interface Comparable<Money>.

This operators and method compareTo() can be used only between money values in the same currency. Runtime error will be thrown on attempt to compare values in different currencies.

import 'money2.dart';
fiveDollars < sevenDollars; // => true
fiveDollars > sevenDollars; // => false
fiveEuros < fiveDollars;    // throws ArgumentError!

Currency Predicates #

To check that money value has an expected currency use methods isInCurrency(Currency) and isInSameCurrencyAs(Money):

import 'money2.dart';
fiveDollars.isInCurrency(usd); // => true
fiveDollars.isInCurrency(eur); // => false
import 'money2.dart';
fiveDollars.isInSameCurrencyAs(sevenDollars); // => true
fiveDollars.isInSameCurrencyAs(fiveEuros);    // => false

Value Sign Predicates #

To check if some money amount is a credit, a debit or zero, use predicates:

  • Money.isNegative — returns true only if amount is less than 0.
  • Money.isPositive — returns true only if amount is greater than 0.
  • Money.isZero — returns true only if amount is 0.

Arithmetic Operations #

The Money class is immutable, so each operation returns a new Money instance.

Money provides next arithmetic operators:

  • unary -()
  • +(Money)
  • -(Money)
  • *(num)
  • /(num)

Operators + and - must be used with operands in same currency, ArgumentError will be thrown otherwise.

import 'money2.dart';
final tenDollars = fiveDollars + fiveDollars;
final zeroDollars = fiveDollars - fiveDollars;

Operators *, / receive a num as the second operand. Both operators use schoolbook rounding to round result up to a minorUnits of a currency.

import 'money2.dart';
final fifteenCents = Money.fromBigInt(BigInt.from(15), usd);

final thirtyCents = fifteenCents * 2;  // $0.30
final eightCents = fifteenCents * 0.5; // $0.08 (rounded from 0.075)

Allocation #

Allocation According to Ratios #

Let our company have made a profit of 5 cents, which has ro be divided amongst a company (70%) and an investor (30%). Cents cant' be divided, so We can't give 3.5 and 1.5 cents. If we round up, the company gets 4 cents, the investor gets 2, which means we need to conjure up an additional cent.

The best solution to avoid this pitfall is to use allocation according to ratios.

import 'money2.dart';
final profit = Money.fromBigInt(BigInt.from(5), usd); // 5¢

var allocation = profit.allocationAccordingTo([70, 30]);
assert(allocation[0] == Money.fromBigInt(BigInt.from(4), usd)); // 4¢
assert(allocation[1] == Money.fromBigInt(BigInt.from(1), usd)); // 1¢

// The order of ratios is important:
allocation = profit.allocationAccordingTo([30, 70]);
assert(allocation[0] == Money.fromBigInt(BigInt.from(2), usd)); // 2¢
assert(allocation[1] == Money.fromBigInt(BigInt.from(3), usd)); // 3¢

Allocation to N Targets #

An amount of money can be allocated to N targets using allocateTo().

import 'money2.dart';
final value = Money.fromBigInt(BigInt.from(800), usd); // $8.00

final allocation = value.allocationTo(3);
assert(allocation[0] == Money.fromBigInt(BigInt.from(267), usd)); // $2.67
assert(allocation[1] == Money.fromBigInt(BigInt.from(267), usd)); // $2.67
assert(allocation[2] == Money.fromBigInt(BigInt.from(266), usd)); // $2.66

Money encoding/decoding #

API for encoding/decoding a money value enables an application to store value in a database or send over the network.

A money value can be encoded to any type. For example it can be coded as a string in the format like "USD 5.00".

Note: this is a trivial example and you would simply use the parse/format methods to encode/decode from/to a string.

Encoding #

import 'money2.dart';
class MoneyToStringEncoder implements MoneyEncoder<String> {
  String encode(MoneyData data) {
    // Receives MoneyData DTO and produce
    // a string representation of money value...
    String major = data.getMajorUnits().toString();
    String mainor = data.getMinorUnits().toString();

    return data.currency.code + " " + major + "." + minor;
  }
}


final encoded = fiveDollars.encodedBy(MoneyToStringEncoder());
// Now we can save `encoded` to database...

Decoding #

import 'money2.dart';
class StringToMoneyDecoder implements MoneyDecoder<String> {

  Currencies _currencies;

  StringToMoneyDecoder(this._currencies) {
    if (_currencies == null) {
      throw ArgumentError.notNull('currencies');
    }
  }

  /// Returns decoded `MoneyData` or throws a `FormatException`.
  MoneyData decode(String encoded) {
    // If `encoded` has an invalid format throws FormatException;
    
    // Extracts currency code from `encoded`:
    final currencyCode = ...;

    // Tries to find information about a currency:
    final currency = _currencies.find(currencyCode);
    if (currency == null) {
      throw FormatException('Unknown currency: $currencyCode.');
    }
    
    // Using `currency.precision`, extracts minorUnits from `encoded`:
    final minorUnits = ...;
    
    return MoneyData.from(minorUnits, currency);
  }
}
import 'money2.dart';
try {
  final value = Money.decoding('USD 5.00', MyMoneyDecoder(myCurrencies));

  // ...
} on FormatException {
  // ...
}

Change Log #

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

version: 1.2.2 #

Documented creation of top 20 currencies.

version: 1.2.1 #

Corrections and improvements to the documentation.

version: 1.2.0 #

Deprecated 'fromString' methods in favour of 'parse' method name. This was done to bring the library in line with the likes of BigInt.parse.

Added #

New 'Money.from(num)' method to support creating money from int's and doubles. New Unit tests for Money.from and the new parse methods.

Deprecated #

Money.fromString - use Money.parse Currency.fromString - use Currency.parse Currencies.fromString - use Currencies.parse

version: 1.1.1 #

Minor documenation cleanups.

version: 1.1.0 #

Change the API of Currencies. Its now a singleton so usage changes from: Currencies().register() to Currencies.register().

Added #

New methods to parse a monetary value from a String including: Money.frommString Currency.fromString Currencies.fromString

New method to convert a [Money] of one currency to another currency via the [Money.exchangeTo] method.

New examples and unit tests for the above methods.

version: 1.0.7 #

2nd Attempt to improve the description displayed on pub.dev.

version: 1.0.6 #

Attempt to improve the description displayed on pub.dev.

version: 1.0.5 #

Formatting of examples as the pub.dev site clips wide lines.

version: 1.0.4 #

Improved the examples.

version: 1.0.3 #

Changed readme sample to the more familar usd.

Added #

Examples of registry usage.
Additional unit tests.

version: 1.0.2 #

tweaks to the doco, some additional unit tests. Improved the trailing zero logic.

version: 1.0.1 #

Improvemenst to the dartdoc.

version: 1.0.0 #

First release version

Updated #

Readme to document invertedSeparators and general improvments corrections.

Added #

Added a couple additional examples. InvertedSeparator argument to Currency.create Additional unit test for the InvertedSeparator option.

version: 1.0.0-beta.6 #

Minor cleanups of the readme.md

version: 1.0.0-beta.5 #

Updated the name of example.dart to please google package gods.

version: 1.0.0-beta.4 #

Update to please the google package gods.

Added #

  • longer description
  • fixed to broken annotations.

version: 1.0.0-beta.3 #

Updated the description.

Removed #

  • Dependency on meta ^1.1.7.

Updated #

  • Dependancy on intl: ^0.16.0.

1.0.0-beta.1 - 2019-9-26 #

Added #

  • Dependency on meta ^1.1.7.
  • Dependancy on intl: ^0.15.8.
  • Annotations @immutable and @sealed to Money, Currency, MoneyData.
  • Added new format method on Money class to allow simply formating of amounts.
  • Modified the API to make it easier to follow.
  • Change the Currencies class to a factory and renamed methods to 'register' and 'registerList'.
  • Chaneged ctor for Money from withBigInt to fromBigInt
  • Added ctor for Money 'fromInt'
  • Added strong mode to the analyzer.
  • Renamed a number of classes for clarity.
  • Added unit tests for the new formatter.
  • Updated the readme.md for clarity and the details on the new formatter.
  • Removed the aggregated currency interface as couldn't see that it added significant value.

1.0.0-alpha.1 - 2019-04-09 #

This release was made from scratch and provides API incompatible with 0.2.1.

Added #

  • Currency value-type.
  • The interface Currencies for representation of currency directories.
  • Implementation of currencies which can be initialized by any Iterable<Currency> (see the factory Currencies.from(Iterable<Currency>)).
  • Aggregating Currencies implementation (see the factory Currencies.aggregating(Iterable<Currencies>)).
  • Adds Money value-type:
    • amount predicates: .isZero, .isPositive, .isNegative;
    • currency predicates .isInCurrency(Currency), .isInSameCurrencyAs(Money);
    • comparison operators: ==, <, <=, >, >=;
    • conformance to Comparable<Money>;
    • arithmetic operators (+(Money), -(Money), *(num), /(num));
    • allocation according to ratios with .allocationAccordingTo(List<int>);
    • allocation to N targets with .allocationTo(int);
    • .encodedBy(MoneyDecoder);
    • Money.decoding(MoneyEncoder).
  • Interface MoneyEncoder.
  • Interface MoneyDecoder.
  • MoneyData — DTO for encoding/decoding.

0.2.1 - 2018-08-21 #

Fixed #

  • Fixes comparison of 0 and -0 amount in a browser.

0.2.0 - 2018-08-17 #

Changed #

  • Code was migrated to Dart 2.0. No API changes.

0.1.6 - 2017-02-24 #

Fixed #

  • Fixed wrong parsing from string when integer part of amount is 0.

0.1.5 - 2016-07-06 #

Changed #

  • Class Currency is not abstract from now on.

Fixed #

  • Money.hashCode now relates on amount and currency (Issue #1).

0.1.4 - 2016-06-03 #

Changed #

  • [BC] Money.==() now receives Object instead of Money and checks runtime type of the argument, closes #4.

0.1.3+2 - 2016-05-10 #

Fixed #

  • Fixed invalid rounding of amount in Money.toString(), closes #3.

0.1.3 - 2015-05-05 #

Added #

  • Added Money.fromDouble() constructor.

0.1.2 - 2015-05-05 #

Added #

  • Added getter Money.amountAsString.

0.1.1 - 2015-05-04 #

Added #

  • Added Money.fromString() constructor.
  • Added relational operators (<, <=, >, >=).

0.1.0+1 - 2015-05-01 #

Fixed #

  • Fixes README.md.

[0.1.0] - 2015-05-01

Initial version.

example/example.dart

import 'package:money2/money2.dart';

void main() {
  ///
  /// Create a currency
  /// USD currency uses 2 decimal places.
  ///
  final usd = Currency.create('USD', 2);
  final aud = Currency.create('AUD', 2);

  ///
  /// Create a money which stores $USD 10.00
  ///
  /// Note: we use the minor unit (e.g. cents) when passing in the
  ///   monetary value.
  /// So $10.00 is 1000 cents.
  ///
  Money costPrice = Money.fromInt(1000, usd);
  print(costPrice.toString());
  // > $10.00

  ///
  /// Create a [Money] instance from a String
  /// using [Currency.parse]
  /// The [Currency] of salePrice is USD.
  ///
  Money salePrice = usd.parse("\$10.50");
  print(salePrice.format("SCC 0.0"));
  // > $US 10.50

  ///
  /// Create a [Money] instance from a String
  /// using [Money.parse]
  ///
  Money taxPrice = Money.parse("\$1.50", usd);
  print(taxPrice.format("CC 0.0 S"));
  // > US 1.50 $

  ///
  /// Create a [Money] instance from a String
  /// with an embedded Currency Code
  /// using [Currencies.parse]
  ///
  Currencies.register(usd);
  Currencies.register(aud);
  Money cheapIPhone = Currencies.parse("\$USD1500.0", "SCCC0.0");
  print(cheapIPhone.format("SCC0.0"));
  // > $US1500.00

  Money expensiveIPhone = Currencies.parse("\$AUD2000.0", "SCCC0.0");
  print(expensiveIPhone.format("SCC0.0"));
  // > $AUD2000.00

  ///
  /// Do some maths
  ///
  final taxInclusive = costPrice * 1.1;

  ///
  /// Output the result using the default format.
  ///
  print(taxInclusive.toString());
  // > $11.00

  ///
  /// Do some custom formatting of the ouput
  /// S - the symbol e.g. $
  /// CC - first two digits of the currency code provided when creating
  ///     the currency.
  /// # - a digit if required
  /// 0 - a digit or the zero character as padding.
  print(taxInclusive.format("SCC #.00"));
  // > $US 11.00

  ///
  /// Explicitly define the symbol and the default pattern to be used
  ///    when calling [Money.toString()]
  ///
  /// JPY - code for japenese yen.
  /// 0 - the number of minor units (e.g cents) used by the currency.
  ///     The yen has no minor units.
  /// ¥ - currency symbol for the yen
  /// S0 - the default pattern for [Money.toString()].
  ///      S output the symbol.
  ///      0 - force at least a single digit in the output.
  ///
  final Currency jpy = Currency.create('JPY', 0, symbol: '¥', pattern: 'S0');
  Money jpyMoney = Money.fromInt(500, jpy);
  print(jpyMoney.toString());
  // > ¥500

  ///
  /// Define a currency that has inverted separators.
  /// i.e. The USD uses '.' for the integer/fractional separator
  ///      and ',' for the thousands separator.
  ///      -> 1,000.00
  /// The EURO use ',' for the integer/fractional separator
  ///      and '.' for the thousands separator.
  ///      -> 1.000,00
  ///
  final Currency euro = Currency.create('EUR', 2,
      symbol: '€', invertSeparators: true, pattern: "#.##0,00 S");

  Money bmwPrice = Money.fromInt(10025090, euro);
  print(bmwPrice.toString());
  // > 100.250,90 €

  ///
  /// Formatting examples
  ///
  ///

  // 100,345.30 usd
  Money teslaPrice = Money.fromInt(10034530, usd);

  print(teslaPrice.format("###,###"));
  // > 100,345

  print(teslaPrice.format("S###,###.##"));
  // > $100,345.3

  print(teslaPrice.format("CC###,###.#0"));
  // > US100,345.30

  // 100,345.30 EUR
  Money euroCostPrice = Money.fromInt(10034530, euro);
  print(euroCostPrice.format("###.###"));
  // > 100.345

  print(euroCostPrice.format("###.###,## S"));
  // > 100.345,3 €

  print(euroCostPrice.format("###.###,#0 CC"));
  // > 100.345,30 EU

  ///
  /// Make the currencies available globally by registering them
  ///     with the [Currencies] singleton factory.
  ///
  Currencies.register(usd);
  Currencies.register(euro);
  Currencies.register(jpy);

  // use a registered currency by finding it in the registry using
  // the currency code that the currency was created with.
  Currency usDollar = Currencies.find("USD");

  Money invoicePrice = Money.fromInt(1000, usDollar);

  ///
  print(invoicePrice.format("SCCC 0.00"));
  // $USD 10.00

  // Do some maths
  Money taxInclusivePrice = invoicePrice * 1.1;
  print(taxInclusivePrice.toString());
  // $11.00

  print(taxInclusivePrice.format("SCC 0.00"));
  // $US 11.00
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  money2: ^1.2.2

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:money2/money2.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
57
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
78
Learn more about scoring.

We analyzed this package on Nov 7, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.6.0
  • pana: 0.12.21

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:money2/money2.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.1.0 <3.0.0
intl ^0.16.0 0.16.0
Transitive dependencies
path 1.6.4
Dev dependencies
pedantic ^1.0.0
test ^1.6.1