diff --git a/docs/dinero.js.html b/docs/dinero.js.html
index 0f3816a01..4edc1eadb 100644
--- a/docs/dinero.js.html
+++ b/docs/dinero.js.html
@@ -278,7 +278,14 @@
/**
* Returns a new Dinero object with a new precision and a converted amount.
*
+ * By default, fractional minor currency units are rounded using the **half to even** rule ([banker's rounding](http://wiki.c2.com/?BankersRounding)).
+ * This can be necessary when you need to convert objects to a smaller precision.
+ *
+ * Rounding *can* lead to accuracy issues as you chain many times. Consider a minimal amount of subsequent conversions for safer results.
+ * You can also specify a different `roundingMode` to better fit your needs.
+ *
* @param {Number} newPrecision - The new precision.
+ * @param {String} [roundingMode='HALF_EVEN'] - The rounding mode to use: `'HALF_ODD'`, `'HALF_EVEN'`, `'HALF_UP'`, `'HALF_DOWN'`, `'HALF_TOWARDS_ZERO'` or `'HALF_AWAY_FROM_ZERO'`.
*
* @example
* // Returns a Dinero object with precision 3 and amount 1000
@@ -288,12 +295,15 @@
*
* @return {Dinero}
*/
- convertPrecision(newPrecision) {
+ convertPrecision(newPrecision, roundingMode = globalFormatRoundingMode) {
assertInteger(newPrecision)
return create.call(this, {
- amount: calculator.multiply(
- this.getAmount(),
- Math.pow(10, calculator.subtract(newPrecision, this.getPrecision()))
+ amount: calculator.round(
+ calculator.multiply(
+ this.getAmount(),
+ Math.pow(10, calculator.subtract(newPrecision, this.getPrecision()))
+ ),
+ roundingMode
),
precision: newPrecision
})
diff --git a/docs/index.html b/docs/index.html
index ee71af89d..82ba3e051 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -203,7 +203,7 @@ Quick start
Dinero.js makes it easy to create, calculate and format m
Dinero({ amount: 500 })
.setLocale('fr-FR')
.add(Dinero({ amount: 500 }))
- .toFormat('$0,0')
By default, new Dinero objects represent monetary values with two decimal places. If you want to represent more, or if you're using a currency with a different exponent), you can specify a precision.
+ .toFormat('$0,0')By default, new Dinero objects represent monetary values with two decimal places. If you want to represent more, or if you're using a currency with a different exponent>), you can specify a precision.
// represents $10.545
Dinero({ amount: 10545, precision: 3 })
@@ -218,6 +218,14 @@ Quick start
Dinero.js makes it easy to create, calculate and format m
Dinero({ amount: 1000 })
This is only a preview of what you can do. Dinero.js has extensive documentation with examples for all of its methods.
Read full documentation
Contributing
Pull requests are welcome! Please check the contributing guidelines for install instructions and general conventions.
+Community
Selected content about Dinero.js:
+
Support
Show some love by upvoting on Product Hunt if you like, support and/or use the library πΌπ
Acknowledgements
Dinero.js is inspired from Martin Fowler's monetary representation. Design-wise, it draws inspiration from Money PHP, Luxon, Moment.js and Numeral.js (even though it doesn't rely on any of them).
Logo by David DeSandro.
diff --git a/docs/module-Dinero.html b/docs/module-Dinero.html
index ab77dd36e..df36b3c08 100644
--- a/docs/module-Dinero.html
+++ b/docs/module-Dinero.html
@@ -1020,7 +1020,7 @@ Example
- (inner) convertPrecision(newPrecision) → {Dinero}
+ (inner) convertPrecision(newPrecision, roundingModeopt) → {Dinero}
@@ -1030,6 +1030,10 @@
Returns a new Dinero object with a new precision and a converted amount.
+
By default, fractional minor currency units are rounded using the half to even rule (banker's rounding).
+This can be necessary when you need to convert objects to a smaller precision.
+
Rounding can lead to accuracy issues as you chain many times. Consider a minimal amount of subsequent conversions for safer results.
+You can also specify a different roundingMode to better fit your needs.
@@ -1051,8 +1055,12 @@ Parameters:
Type |
+ Attributes |
+
+ Default |
+
Description |
@@ -1079,7 +1087,19 @@ Parameters:
+
+
+
+
+
+ |
+
+
+
+
+
+ |
@@ -1089,6 +1109,51 @@ Parameters:
+ |
+
+ roundingMode |
+
+
+
+
+
+
+ String
+
+
+
+
+
+
+ |
+
+
+
+
+ <optional>
+
+
+
+
+
+ |
+
+
+
+
+
+ 'HALF_EVEN'
+
+ |
+
+
+
+ The rounding mode to use: 'HALF_ODD', 'HALF_EVEN', 'HALF_UP', 'HALF_DOWN', 'HALF_TOWARDS_ZERO' or 'HALF_AWAY_FROM_ZERO'.
+
+ |
+
+
+
@@ -1127,7 +1192,7 @@ Parameters:
@@ -1320,7 +1385,7 @@ Parameters:
@@ -1517,7 +1582,7 @@ Parameters:
@@ -1777,7 +1842,7 @@ Parameters:
@@ -2011,7 +2076,7 @@ Parameters:
@@ -2181,7 +2246,7 @@ Parameters:
@@ -2379,7 +2444,7 @@ Parameters:
@@ -2791,7 +2856,7 @@ Parameters:
@@ -2987,7 +3052,7 @@ Parameters:
@@ -3168,7 +3233,7 @@ Parameters:
@@ -3372,7 +3437,7 @@ Parameters:
@@ -3584,7 +3649,7 @@ Parameters:
@@ -3788,7 +3853,7 @@ Parameters:
@@ -3945,7 +4010,7 @@