The properties of a Decimal constructor can also be set by direct assignment, but that will
@@ -558,13 +567,16 @@ x.equals(y) // true
rounding, minE,
maxE, toExpNeg,
toExpPos, errors,
- modulo and crypto are
- set using the config method.
+ modulo, crypto and
+ format are set using the
+ config method.
As simple object properties they can be set directly without using
config, and it is fine to do so, but the values assigned
- will not then be checked for validity. For example:
+ will not then be checked for validity (the properties of the
+ format object are not checked by
+ config). For example:
Decimal.config({ precision: 0 })
// 'Decimal Error: config() precision out of range: 0'
@@ -856,6 +868,47 @@ Decimal.config({ crypto: true })
+ object +
+ The format object configures the format of the string returned by the
+ toFormat method.
+
+ The example below shows the properties of the format object
+ that are recognised, and their default values.
+
+ Unlike setting other properties using config, the values of the
+ properties of the format object will not be checked for validity. The existing
+ format object will simply be replaced by the object that is passed in. Only the
+ toFormat method ever references a Decimal constructor's
+ format object property.
+
+ See toFormat for examples of usage, and of setting
+ format properties individually and directly without using config.
+
+Decimal.config({
+ format : {
+ // the decimal separator
+ decimalSeparator : '.',
+ // the grouping separator of the integer part of the number
+ groupSeparator : ',',
+ // the primary grouping size of the integer part of the number
+ groupSize : 3,
+ // the secondary grouping size of the integer part of the number
+ secondaryGroupSize : 0,
+ // the grouping separator of the fraction part of the number
+ fractionGroupSeparator : ' ',
+ // the grouping size of the fraction part of the number
+ fractionGroupSize : 0
+ }
+});
+
+
+
The library's enumerated rounding modes are stored as properties of a Decimal constructor. @@ -1622,47 +1675,61 @@ y.toFixed(5) // '3.45600'
.toFormat([sep1 [, dp [, sep2]]]) ⇒ string
+ toFormat.toFormat([dp [, rm]]) ⇒ string
- sep1: string: the grouping separator of the integer part of the number
-
- sep2: string: the grouping separator of the fraction part of the number
-
- dp: number: integer, 0 to 8 inclusive
+ dp: number: integer, 0 to 1e+9 inclusive
+ rm: number: integer, 0 to 8 inclusive
-
- This method is a placeholder and is likely to be subject to change / further development.
-
+ Returns a string representing the value of this Decimal in fixed-point notation rounded to
+ dp decimal places using rounding mode rm (as
+ toFixed), and formatted according to the properties of this
+ Decimal's constructor's format object property.
- Returns a string representing the value of this Decimal to dp decimal places,
- (see toFixed), but with the integer part of the number
- separated by sep1 into groups of three digits, and the fraction part of the
- number separated into groups of five digits by sep2.
-
- If sep1 is null or undefined, the integer part groupings will be
- separated by a comma.
-
- If sep2 is null or undefined, the fraction part groupings will not
- be separated.
+ See the examples below for the properties of the format
+ object, their types and their usage.
If dp is omitted or is null or undefined, then the return value is
not rounded to a fixed number of decimal places.
A useful separator character is the non-breaking thin-space: \u202f.
+
+ if rm is omitted or is null or undefined, rounding mode
+ rounding is used.
+
-x = new Decimal('1.23456000000000000000789e+9')
-x.toFormat() // '1,234,560,000.00000000000789'
-x.toFormat(' ') // '1 234 560 000.00000000000789'
-x.toFormat(',', 2) // '1,234,560,000.00'
-x.toFormat(' ', 2) // '1 234 560 000.00'
-x.toFormat(',', 12, ' ') // '1 ,234,560,000.00000 00000 08'
-x.toFormat('-', 14, '-') // '1-234-560-000.00000-00000-0789'
+// Using config to assign values to the format object
+Decimal.config({
+ format : {
+ decimalSeparator : '.',
+ groupSeparator : ',',
+ groupSize : 3,
+ secondaryGroupSize : 0,
+ fractionGroupSeparator : ' ',
+ fractionGroupSize : 0
+ }
+});
+
+x = new Decimal('123456789.123456789')
+x.toFormat() // '123,456,789.123456789'
+x.toFormat(1) // '123,456,789.1'
+
+// Assigning the format properties directly
+Decimal.format.groupSeparator = ' ';
+Decimal.format.fractionGroupSize = 5;
+x.toFormat() // '123 456 789.12345 6789'
+
+// Assigning the format object directly
+Decimal.format = {
+ decimalSeparator = ',',
+ groupSeparator = '.',
+ groupSize = 3,
+ secondaryGroupSize = 2
+}
+
+x.toFormat() // '12.34.56.789,123456789'
@@ -2359,8 +2426,8 @@ z = x.multiply(y) // 4.1400000