CakeNumber::formatDelta

en/appendices/2-3-migration-guide.rst

@@ -178,6 +178,7 @@ CakeNumber
 ----------
 
 - :php:meth:`CakeNumber::fromReadableSize()` was added.
+- :php:meth:`CakeNumber::formatDelta()` was added.
 
 Folder
 ------

en/core-utility-libraries/number.rst

@@ -115,7 +115,7 @@ automatically echo the output into the view.
         echo CakeNumber::currency('1234.56', 'FOO');
 
 .. php:method:: addFormat(string $formatName, array $options)
-    
+
     :param string $formatName: The format name to be used in the future
     :param array $options: The array of options for this format. Uses the
         same ``$options`` keys as :php:meth:`CakeNumber::currency()`.
@@ -211,7 +211,7 @@ automatically echo the output into the view.
 
 .. php:method:: toReadableSize(string $dataSize)
 
-    :param string $data_size: The number of bytes to make readable. 
+    :param string $data_size: The number of bytes to make readable.
 
     This method formats data sizes in human readable forms. It provides
     a shortcut way to convert bytes to KB, MB, GB, and TB. The size is
@@ -292,6 +292,52 @@ automatically echo the output into the view.
         ));
         // output '¥ 123,456.79'
 
+.. php:method:: formatDelta(mixed $number, mixed $options=array())
+
+    This method displays differences in value as a signed number::
+
+        <?php
+        // called as NumberHelper
+        $this->Number->format($number, $options);
+
+        // called as CakeNumber
+        CakeNumber::format($number, $options);
+
+    The $number parameter is the number that you are planning on
+    formatting for output. With no $options supplied, the number
+    1236.334 would output as 1,236. Note that the default precision is
+    zero decimal places.
+
+    The $options parameter takes the same keys as :php:meth:`CakeNumber::format()` itself:
+
+       -  places (integer): the amount of desired precision
+       -  before (string): to be put before the outputted number
+       -  after (string): to be put after the outputted number
+       -  decimals (string): used to delimit the decimal places in a
+          number
+       -  thousands (string): used to mark off thousand, millions, …
+          places
+
+    Example::
+
+        <?php
+        // called as NumberHelper
+        echo $this->Number->formatDelta('123456.7890', array(
+            'places' => 2,
+            'decimals' => '.',
+            'thousands' => ','
+        ));
+        // output '+123,456.79'
+
+        // called as CakeNumber
+        App::uses('CakeNumber', 'Utility');
+        echo CakeNumber::formatDelta('123456.7890', array(
+            'places' => 2,
+            'decimals' => '.',
+            'thousands' => ','
+        ));
+        // output '+123,456.79'
+
 .. end-cakenumber
 
 .. meta::