Released 5.0.0-alpha.1.

Author: bsutton

CHANGELOG.md

@@ -1,3 +1,42 @@
+# 5.0.0-alpha.1
+The driver for this release and the breaking changes comes from:
+https://github.com/onepub-dev/money.dart/issues/79
+
+The aim is to allow users to fully customise the group and decimal separators.
+We have also renamed 'scale' to 'decimalDigits' as this term is likely to be
+more familiar to users.
+
+## breaking changes
+- The 'invertSeparator' argument to the Currency class has been broken out 
+into two separate arguments 'groupSeparator' and 'decimalSeparator'. 
+If you are using 'invertSeparator: true' then you need to replace this with
+```dart
+  groupSeparator: '.',
+  decimalSeparator: ',',
+```
+- patterns used for parsing and formatting must always use ',' for group separators
+and '.' for decimal separators regardless of what has been used for the
+groupSeparator and decimalSeparator.
+This allows a single pattern to be used across currencies rather than having
+to create a unique pattern for each currency when looking to use custom formats.
+
+This means that if you have been using 'invertSeparator: true' then you will 
+need to modifiy any custom patterns from '#.###,##' to '#,###.##'.
+Note the change in the separators!
+
+
+- For methods that take a 'code' it has been renamed 'isoCode' to make the
+correct use of the code more apparent.
+
+- renamed PatterDecoder.isCode to isIsoCode
+- renamed CurrencyCode to CurrencyIsoCode
+- renamed all occurances of 'scale' to 'decimalDigits' as many people
+  are not familiar with the concept of scale.
+- changed toScale on ExchangeRate members to be 'toDecimalDigits'.
+
+## non-breaking changes
+- Fixed doco for Currencies class as it is a singleton and it's needs methods need to be called  via Currencies()...
+
 # 4.1.0
 - upgraded to intl 0.19
 

example/example.dart

@@ -11,11 +11,11 @@ void main() {
   /// Create money from Fixed amount
 
   final fixed = Fixed.fromInt(100);
-  Money.parse('1.23', code: 'AUD');
+  Money.parse('1.23', isoCode: 'AUD');
 
-  Money.fromFixed(fixed, code: 'AUD');
+  Money.fromFixed(fixed, isoCode: 'AUD');
 
-  Money.fromDecimal(Decimal.parse('1.23'), code: 'EUR');
+  Money.fromDecimal(Decimal.parse('1.23'), isoCode: 'EUR');
 
   ///
   /// Create a money which stores $USD 10.00
@@ -24,7 +24,7 @@ void main() {
   ///   monetary value.
   /// So $10.00 is 1000 cents.
   ///
-  final costPrice = Money.fromInt(1000, code: 'USD');
+  final costPrice = Money.fromInt(1000, isoCode: 'USD');
 
   print(costPrice);
   // > $10.00
@@ -42,13 +42,13 @@ void main() {
   /// Create a [Money] instance from a String
   /// using [Money.parse]
   ///
-  final taxPrice = Money.parse(r'$1.50', code: 'USD');
+  final taxPrice = Money.parse(r'$1.50', isoCode: 'USD');
   print(taxPrice.format('CC 0.0 S'));
   // > US 1.50 $
 
   ///
   /// Create a [Money] instance from a String
-  /// with an embedded Currency Code
+  /// with an embedded Currency isoCode
   /// using [Currencies.parse]
   ///
   /// Create a custom currency
@@ -68,7 +68,7 @@ void main() {
   Currencies().register(Currency.create('DODGE', 5, symbol: 'Ð'));
   final dodge = Currencies().find('DODGE');
   Money.fromNumWithCurrency(0.1123, dodge!);
-  Money.fromNum(0.1123, code: 'DODGE');
+  Money.fromNum(0.1123, isoCode: 'DODGE');
 
   ///
   /// Do some maths
@@ -84,7 +84,7 @@ void main() {
   ///
   /// Do some custom formatting of the ouput
   /// S - the symbol e.g. $
-  /// CC - first two digits of the currency code provided when creating
+  /// CC - first two digits of the currency isoCode provided when creating
   ///     the currency.
   /// # - a digit if required
   /// 0 - a digit or the zero character as padding.
@@ -95,7 +95,7 @@ void main() {
   /// Explicitly define the symbol and the default pattern to be used
   ///    when calling [Money.toString()]
   ///
-  /// JPY - code for japenese yen.
+  /// JPY - isoCode 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
@@ -118,7 +118,10 @@ void main() {
   ///      -> 1.000,00
   ///
   final euro = Currency.create('EUR', 2,
-      symbol: '€', invertSeparators: true, pattern: '#.##0,00 S');
+      symbol: '€',
+      groupSeparator: '.',
+      decimalSeparator: ',',
+      pattern: '#,##0.00 S');
 
   final bmwPrice = Money.fromIntWithCurrency(10025090, euro);
   print(bmwPrice);
@@ -130,7 +133,7 @@ void main() {
   ///
 
   // 100,345.30 usd
-  final teslaPrice = Money.fromInt(10034530, code: 'USD');
+  final teslaPrice = Money.fromInt(10034530, isoCode: 'USD');
 
   print(teslaPrice.format('###,###'));
   // > 100,345
@@ -142,14 +145,14 @@ void main() {
   // > US100,345.30
 
   // 100,345.30 EUR
-  final euroCostPrice = Money.fromInt(10034530, code: 'EUR');
-  print(euroCostPrice.format('###.###'));
+  final euroCostPrice = Money.fromInt(10034530, isoCode: 'EUR');
+  print(euroCostPrice.format('###,###'));
   // > 100.345
 
-  print(euroCostPrice.format('###.###,## S'));
+  print(euroCostPrice.format('###,###.## S'));
   // > 100.345,3 €
 
-  print(euroCostPrice.format('###.###,#0 CC'));
+  print(euroCostPrice.format('###,###.#0 CC'));
   // > 100.345,30 EU
 
   ///
@@ -161,7 +164,7 @@ void main() {
   Currencies().register(jpy);
 
   // use a registered currency by finding it in the registry using
-  // the currency code that the currency was created with.
+  // the currency isoCode that the currency was created with.
   final usDollar = Currencies().find('USD');
 
   final invoicePrice = Money.fromIntWithCurrency(1000, usDollar!);
@@ -180,7 +183,7 @@ void main() {
 
   // retrieve all registered currencies
   final registeredCurrencies = Currencies().getRegistered();
-  final codes = registeredCurrencies.map((c) => c.code);
+  final codes = registeredCurrencies.map((c) => c.isoCode);
   print(codes);
   // (USD, AUD, EUR, JPY)
 }

lib/money2.dart

@@ -9,7 +9,7 @@
 ///
 ///
 /// The [Currency] class allows you to define the key attributes of a currency
-/// such as Symbol, Code, precision and a default format.
+/// 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).
@@ -33,7 +33,7 @@
 /// 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
+/// * 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.

lib/src/common_currencies.dart

@@ -38,8 +38,8 @@ class CommonCurrencies {
   /// Brazilian Real
   final Currency brl = Currency.create('BRL', 2,
       symbol: r'R$',
-      invertSeparators: true,
-      pattern: 'S0,00',
+      groupSeparator: '.',
+      decimalSeparator: ',',
       country: 'Brazil',
       unit: 'Real',
       name: 'Brazilian Real');
@@ -65,17 +65,19 @@ class CommonCurrencies {
   /// Czech Koruna
   final Currency czk = Currency.create('CZK', 2,
       symbol: 'Kč',
-      invertSeparators: true,
-      pattern: '0,00S',
+      groupSeparator: '.',
+      decimalSeparator: ',',
+      pattern: '0.00S',
       country: 'Czech',
       unit: 'Koruna',
       name: 'Czech Koruna');
 
   /// European Union Euro
   final Currency euro = Currency.create('EUR', 2,
       symbol: '€',
-      invertSeparators: true,
-      pattern: '0,00S',
+      groupSeparator: '.',
+      decimalSeparator: ',',
+      pattern: '0.00S',
       country: 'European Union',
       unit: 'Euro',
       name: 'European Union Euro');
@@ -118,8 +120,9 @@ class CommonCurrencies {
   /// Polish Zloty
   final Currency pln = Currency.create('PLN', 2,
       symbol: 'zł',
-      invertSeparators: true,
-      pattern: '0,00S',
+      groupSeparator: '.',
+      decimalSeparator: ',',
+      pattern: '0.00S',
       country: 'Polish',
       unit: 'Zloty',
       name: 'Polish Zloty');