Merge 765ce4e into 0539678

changelog.md

@@ -1,56 +1,64 @@
-**1.2.1**
+# 2.0.0
+
+* Parse currency as cents ([#166](https://github.com/scurker/currency.js/issues/166) thanks [@ryanwood](https://github.com/ryanwood))
+
+## Breaking Changes
+
+* Formatter now accepts a function or static option, allowing for fine tuned customization of output formats ([#213](https://github.com/scurker/currency.js/pull/213))
+
+# 1.2.1
 
 * Updated flow definition for breaking changes in flow `0.82.x`. ([#149](https://github.com/scurker/currency.js/issues/133)) thanks [@amccloud](https://github.com/amccloud)
 
-**1.2.0**
+# 1.2.0
 
 * Adjusted internal precision to better account for some edge case precision issues. ([#133](https://github.com/scurker/currency.js/issues/133)) thanks [@tvainika](https://github.com/tvainika)
 * Added new formatting options, `pattern` and `negativePattern` allowing for greater flexibility of currency formats. ([#95](https://github.com/scurker/currency.js/issues/95))
 
-**1.1.4**
+# 1.1.4
 
 * Fixed rounding for string values. ([#116](https://github.com/scurker/currency.js/issues/116)) thanks [@pdcmoreira](https://github.com/pdcmoreira)
 
-**1.1.3**
+# 1.1.3
 
 * Fixed grouping separator for numbers with 0 precision. ([#109](https://github.com/scurker/currency.js/issues/109)) thanks [@hameedraha](https://github.com/hameedraha)
 
-**1.1.2**
+# 1.1.2
 
 * Fixed rounding not always being consistent with half cent values and high precision. ([#102](https://github.com/scurker/currency.js/pull/102)) thanks [@philippetrepanier](https://github.com/philippetrepanier)
 * Fixed comma separator appearing in decimals when formatting. ([#104](https://github.com/scurker/currency.js/pull/104)) thanks [@lanceli](https://github.com/lanceli)
 
-**1.1.1**
+# 1.1.1
 
 * Fixed negative distribution values. ([#99](https://github.com/scurker/currency.js/pull/99)) thanks [@andrewkatz](https://github.com/andrewkatz)
 
-**1.1.0**
+# 1.1.0
 
 * `useVedic` option added for displaying groupings using the Indian Numbering System. ([#74](https://github.com/scurker/currency.js/issues/74))
 * `increment` option added for incremental rounding on display. ([#70](https://github.com/scurker/currency.js/issues/70))
 * Documentation updated to be built from source; should help keep documentation in sync.
 
-**1.0.8**
+# 1.0.8
 
 * Changed module `export default currency` to `export = currency` for Typescript definition. ([#88](https://github.com/scurker/currency.js/issues/88) thanks [@arturnt](https://github.com/arturnt))
 
-**1.0.6**
+# 1.0.6
 
 * Fixed travis deployments. ([#79](https://github.com/scurker/currency.js/issues/79))
 
-**1.0.5**
+# 1.0.5
 
 * Removed `static` properties from flow definition files.
 
-**1.0.2**
+# 1.0.2
 
 * Fixed multiplying with precisions other than 2. ([#76](https://github.com/scurker/currency.js/issues/76) thanks [@usb248](https://github.com/usb248))
 
-**1.0.1**
+# 1.0.1
 
 * Fixed default imports for Typescript. ([#73](https://github.com/scurker/currency.js/issues/73) thanks [@shepherdwind](https://github.com/shepherdwind))
 
-**1.0.0**
+# 1.0.0
 
 * Node < 4 support dropped.
 * Separate UMD, ES6, CommonJS modules now available.
@@ -59,67 +67,69 @@
 * Added Typescript definition. ([#36](https://github.com/scurker/currency.js/issues/36))
 * Added Flow definition. ([#37](https://github.com/scurker/currency.js/issues/37))
 
-**0.4.4**
+# 0.4.4
 
 * Fix for currency.min.js being compiled incorrectly.
 
-**0.4.3**
+# 0.4.3
 
 * Added AMD support.
 * Fixed issue resolving bundling with webpack/browserify. ([#24](https://github.com/scurker/currency.js/issues/24))
 * Updated to latest closure compiler for minification.
 
-**0.4.2**
+# 0.4.2
 
 * Whitelist currency.js files for smaller npm size.
 
-**0.4.1**
+# 0.4.1
 
 * Switched to mocha for testing and added test coverage.
 
-**0.4.0**
+# 0.4.0
 
 * Removed deprecated "seperator" option, is now "separator".
 * Currency can now throw an error with undefined inputs with the `errorOnInvalid` option set to true.
 
-**v0.3.4**
+# 0.3.4
 
 * Fix bower package management.
 
-**v0.3.2**
+# 0.3.2
 
 * Fix spelling of "seperator" to "separator".
 * Automatic publish to npm when tags are pushed to master.
 
-**v0.3.1**
+# 0.3.1
 
 * Added bower support.
 
-**v0.3.0**
+# 0.3.0
 
 * Added new format option to optionally include the set currency symbol.
 * Added travis ci integration.
 * Fixed issue where international values were not being formatted correctly. ([#6](https://github.com/scurker/currency.js/issues/6))
 
-**v0.2.0**
+# 0.2.0
 
 * Adding nodejs / commonjs support
 
-**v0.1.4**
+# 0.1.4
 
 * Fixes issue with serializing currency via JSON.stringify ([#1](https://github.com/scurker/currency.js/issues/1))
 * Added grunt tasks
 
-**v0.1.3**
+# 0.1.3
 
 * Switching value returned to be the real float value and not the int value.
 
-**v0.1.2**
+# 0.1.2
 
 * Fixed issue with rounding not being defaulted correctly.
 
-**v0.1.1**
+# 0.1.1
 
 * Fixed issue with multiplication/division not allowing precision beyond 2 decimal points.
 
-**v0.1** - Initial version
+# 0.1.0
+
+* Initial release

docs/02-options.md

@@ -4,10 +4,8 @@ You can customize the formatting and parsing of `currency.js` with an optional o
 
 ### symbol *default*: `"$"`
 
-When `formatWithSymbol` is set to `true`, this currency symbol will be used when calling `currency.format()`.
-
 ```js
-currency(1.23, { formatWithSymbol: true }).format(); // => "$1.23"
+currency(1.23).format(); // => "$1.23"
 ```
 
 ### separator *default*: `","`
@@ -22,8 +20,8 @@ currency(1234.56, { separator: ' ' }).format(); // => "1 234.56"
 ### decimal *default*: `"."`
 
 ```js
-currency(1.23, { decimal: '.' }).format(); // => "1.23"
-currency(1.23, { decimal: ',' }).format(); // => "1,23"
+currency(1.23, { decimal: '.' }).format(); // => "$1.23"
+currency(1.23, { decimal: ',' }).format(); // => "$1,23"
 ```
 
 ### precision *default*: `2`
@@ -35,23 +33,13 @@ currency(1.234, { precision: 2 }); // => "1.23"
 currency(1.234, { precision: 3 }); // => "1.234"
 ```
 
-### formatWithSymbol *default*: `false`
-
-Includes the `symbol` option when calling `currency.format()`.
-
-```js
-currency(1.23, { formatWithSymbol: true }).format(); // => "$1.23"
-currency(1.23, { formatWithSymbol: false }).format(); // => "1.23"
-```
-
 ### pattern *default*: `!#`
 
 Allows you to customize the format pattern using `!` as replacement for the currency symbol and `#` as replacement for the currency amount.
 
 ```js
 currency(1.23, {
-  pattern: `# !`,
-  formatWithSymbol: true
+  pattern: `# !`
 }).format(); // => "1.23 $"
 ```
 
@@ -61,11 +49,32 @@ Allows you to customize the negative format pattern using `!` as replacement for
 
 ```js
 currency(-1.23, {
-  negativePattern: `(!#)`,
-  formatWithSymbol: true
+  negativePattern: `(!#)`
 }).format(); // => "($1.23)"
 ```
 
+### format *default*: `null`
+
+Allows you to customize the format of the currency when calling `currency.format()`. `format` passes in the `currency` object as well as the `options` object to the function and expects a string to be returned. Use this when the provided formatting options do not meet your needs.
+
+```js
+function format(currency, options) {
+  return `${currency.dollars}.${currency.cents}`;
+}
+currency(1234.56, { format }).format(); // => "1234.56"
+```
+
+### fromCents *default*: `false`
+
+Currency accepts decimal values (i.e. `1.23`) with a default precision of 2, but can accept a minor currency unit (e.g. cents in a dollar). This will respect the precision option when parsing.
+
+```javascript
+currency(123456, { fromCents: true });               // => "1234.56"
+currency('123456', { fromCents: true });             // => "1234.56"
+currency(123456, { fromCents: true, precision: 0 }); // => "123456"
+currency(123456, { fromCents: true, precision: 3 }); // => "123.456"
+```
+
 ### errorOnInvalid *default*: `false`
 
 If an invalid value such as `null` or `undefined` is passed in, `currency` will throw an error.

docs/03-api.md

@@ -83,35 +83,26 @@ currency(12.00).distribute(3); // => [4.00, 4.00, 4.00]
 
 ### format
 
-`currency.format([ boolean ])`
+`currency.format([ function | options ])`
 
 A simple formatter that returns a human friendly currency format.
 
 ```js
-currency(1000.00).format(); // => "1,000.00"
-currency("1,234,567/90").add("200,000").format(); // => "1,434,567.89"
+currency(1000.00).format(); // => "$1,000.00"
+currency("1,234,567/90").add("200,000").format(); // => "$1,434,567.89"
 ```
 
 The default formatter can be overridden by passing in options as a second parameter.
 
 ```js
-var euro = value => currency(value, { separator: ' ', decimal: ',' });
+var euro = value => currency(value, { separator: ' ', decimal: ',', format: ... });
 
 // ...
 
 euro(1000.00).format(); // => "1 000,00"
 euro(1234567.89).add("200 000").format(); // => "1 434 567,89"
 ```
 
-You can also include the currently set `symbol` option in a couple of different ways. By default it's always turned off, but you can turn it on for all instances of the object via options, or by passing in a boolean operator to the `format()` function.
-
-```js
-var money = value => currency(value, { formatWithSymbol: true });
-
-money(1000.00).format(); // => "$1,000.00"
-money(1000.00).format(false); // => "1,000.00"
-```
-
 ### dollars
 
 `currency.dollars`