v4.0.0 toFormat amended

doc/API.html

@@ -92,6 +92,7 @@ li span{float:right;margin-right:10px;color:#c0c0c0}
       <li><a href="#errors"   >errors</a></li>
       <li><a href="#modulo"   >modulo</a></li>
       <li><a href="#crypto"   >crypto</a></li>
+      <li><a href="#format"   >format</a></li>
       <li class='spacer'>&nbsp;</li>
       <li><a href="#modes">ROUND_UP</a></li>
       <li><a href="#modes">ROUND_DOWN</a></li>
@@ -348,7 +349,15 @@ Decimal.config({
     maxE: 9e15,
     errors: true,
     crypto: false,
-    modulo: 1
+    modulo: 1,
+    format: {
+        decimalSeparator : '.',
+        groupSeparator : ',',
+        groupSize : 3,
+        secondaryGroupSize : 0,
+        fractionGroupSeparator : '\xA0',    // non-breaking space
+        fractionGroupSize : 0
+    }
 })</pre>
     <p>
       The properties of a Decimal constructor can also be set by direct assignment, but that will
@@ -553,13 +562,16 @@ x.equals(y)                         // true</pre>
       <a href='#rounding'><code>rounding</code></a>, <a href='#minE'><code>minE</code></a>,
       <a href='#maxE'><code>maxE</code></a>, <a href='#toExpNeg'><code>toExpNeg</code></a>,
       <a href='#toExpPos'><code>toExpPos</code></a>, <a href='#errors'><code>errors</code></a>,
-      <a href='#modulo'><code>modulo</code></a> and <a href='#crypto'><code>crypto</code></a> are
-      set using the <a href='#Dconfig'><code>config</code></a> method.
+      <a href='#modulo'><code>modulo</code></a>, <a href='#crypto'><code>crypto</code></a> and
+      <a href='#format'><code>format</code></a> are set using the
+      <a href='#Dconfig'><code>config</code></a> method.
     </p>
     <p>
       As simple object properties they can be set directly without using
       <a href='#Dconfig'><code>config</code></a>, 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
+      <a href='#Dconfig'><code>format</code></a> object are not checked by
+      <code>config</code>). For example:
     </p>
     <pre>Decimal.config({ precision: 0 })
 // 'Decimal Error: config() precision out of range: 0'
@@ -851,6 +863,47 @@ Decimal.config({ crypto: true })</pre>
 
 
 
+    <h5 id="format">format</h5>
+    <p><i>object</i>
+    <p>
+      The <code>format</code> object configures the format of the string returned by the
+      <a href='#toFo'><code>toFormat</code></a> method.
+    </p>
+    <p>
+      The example below shows the properties of the <code>format</code> object
+      that are recognised, and their default values.
+    </p>
+    <p>
+      Unlike setting other properties using <code>config</code>, the values of the
+      properties of the <code>format</code> object will not be checked for validity. The existing
+      <code>format</code> object will simply be replaced by the object that is passed in. Only the
+      <a href='#toFo'><code>toFormat</code></a> method ever references a Decimal constructor's
+      <code>format</code> object property.
+    </p>
+    <p>
+      See <a href='#toFo'><code>toFormat</code></a> for examples of usage, and of setting
+      <code>format</code> properties individually and directly without using <code>config</code>.
+    </p>
+    <pre>
+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
+    }
+});</pre>
+
+
+
     <h6 id="modes">Rounding modes</h6>
     <p>
       The library's enumerated rounding modes are stored as properties of a Decimal constructor.
@@ -1617,47 +1670,61 @@ y.toFixed(5)             // '3.45600'</pre>
 
 
     <h5 id="toFo">
-       toFormat<code class='inset'>.toFormat([sep1 [, dp [, sep2]]]) <i>&rArr; string</i></code>
+       toFormat<code class='inset'>.toFormat([dp [, rm]]) <i>&rArr; string</i></code>
     </h5>
     <p>
-      <code>sep1</code>: <i>string</i>: the grouping separator of the integer part of the number
-      <br />
-      <code>sep2</code>: <i>string</i>: the grouping separator of the fraction part of the number
-      <br />
-      <code>dp</code>: <i>number</i>: integer, 0 to 8 inclusive
+      <code>dp</code>: <i>number</i>: integer, 0 to 1e+9 inclusive<br />
+      <code>rm</code>: <i>number</i>: integer, 0 to 8 inclusive
     </p>
     <p>
-      <i>
-        This method is a placeholder and is likely to be subject to change / further development.
-      </i>
+      Returns a string representing the value of this Decimal in fixed-point notation rounded to
+      <code>dp</code> decimal places using rounding mode <code>rm</code> (as
+      <a href='#toFi'><code>toFixed</code></a>), and formatted according to the properties of this
+      Decimal's constructor's <a href='#format'><code>format</code></a> object property.
     </p>
     <p>
-      Returns a string representing the value of this Decimal to <code>dp</code> decimal places,
-      (see <a href='#toFi'><code>toFixed</code></a>), but with the integer part of the number
-      separated by <code>sep1</code> into groups of three digits, and the fraction part of the
-      number separated into groups of five digits by <code>sep2</code>.
-    </p>
-    <p>
-      If <code>sep1</code> is <code>null</code> or undefined, the integer part groupings will be
-      separated by a comma.
-    </p>
-    <p>
-      If <code>sep2</code> is <code>null</code> or undefined, the fraction part groupings will not
-      be separated.
+      See the examples below for the properties of the <a href='#format'><code>format</code></a>
+      object, their types and their usage.
     </p>
     <p>
       If <code>dp</code> is omitted or is <code>null</code> or undefined, then the return value is
       not rounded to a fixed number of decimal places.
     </p>
-    <p>A useful separator character is the non-breaking thin-space: <code>\u202f</code>.<p>
+     <p>
+      if <code>rm</code> is omitted or is <code>null</code> or undefined, rounding mode
+      <a href='#rounding'><code>rounding</code></a> is used.
+    </p>
     <pre>
-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'</pre>
+// 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'</pre>