merged branch markstory/number-format (PR #573)

Commits
-------

e3b81ad Add documentation page for number_format.
0edcfdd Add number_format filter.

Discussion
----------

Implement number_format filter

Implement a `number_format` filter that wraps the native PHP `number_format`.

Fixes #417

doc/filters/index.rst

@@ -7,6 +7,7 @@ Filters
     date
     format
     replace
+    number_format
     url_encode
     json_encode
     convert_encoding

doc/filters/number_format.rst

@@ -0,0 +1,39 @@
+``number_format``
+=================
+
+.. versionadded:: 1.6
+    The number_format filter was added in Twig 1.6
+
+The ``number_format`` filter formats numbers.  It is a wrapper around PHP's
+`number_format`_ function:
+
+.. code-block:: jinja
+
+    {{ 200.35|number_format }}
+
+You can control the number of decimal places, decimal point, and thousands
+separator using the additional arguments:
+
+.. code-block:: jinja
+
+    {{ 9800.333|number_format(2, ',', '.') }}
+
+If no formatting options are provided then Twig will use the default formatting
+options of:
+
+- 0 decimal places.
+- ``.`` as the decimal point.
+- ``,`` as the thousands separator.
+
+These defaults can be easily changed through the core extension:
+
+.. code-block:: php
+
+    $twig = new Twig_Environment($loader);
+    $twig->getExtension('core')->setNumberFormat(3, ',', '.');
+
+The defaults set for ``number_format`` can be over-ridden upon each call using the
+additional parameters.
+
+.. _`number_format`: http://php.net/number_format
+

lib/Twig/Extension/Core.php

@@ -15,6 +15,7 @@ if (!defined('ENT_SUBSTITUTE')) {
 class Twig_Extension_Core extends Twig_Extension
 {
     protected $dateFormat = 'F j, Y H:i';
+    protected $numberFormat = array(0, '.', ',');
 
     /**
      * Sets the default format to be used by the date filter.
@@ -36,6 +37,28 @@ class Twig_Extension_Core extends Twig_Extension
         return $this->dateFormat;
     }
 
+    /**
+     * Sets the default format to be used by the number_format filter.
+     *
+     * @param integer $decimal The number of decimal places to use.
+     * @param string $decimalPoint The character(s) to use for the decimal point.
+     * @param string $thousandSep The character(s) to use for the thousands separator.
+     */
+    public function setNumberFormat($decimal, $decimalPoint, $thousandSep)
+    {
+        $this->numberFormat = array($decimal, $decimalPoint, $thousandSep);
+    }
+
+    /**
+     * Get the default format used by the number_format filter.
+     *
+     * @return array The arguments for number_format()
+     */
+    public function getNumberFormat()
+    {
+        return $this->numberFormat;
+    }
+
     /**
      * Returns the token parser instance to add to the existing list.
      *
@@ -73,6 +96,7 @@ class Twig_Extension_Core extends Twig_Extension
             'date'    => new Twig_Filter_Function('twig_date_format_filter', array('needs_environment' => true)),
             'format'  => new Twig_Filter_Function('sprintf'),
             'replace' => new Twig_Filter_Function('strtr'),
+            'number_format'  => new Twig_Filter_Function('twig_number_format_filter', array('needs_environment' => true)),
 
             // encoding
             'url_encode'       => new Twig_Filter_Function('twig_urlencode_filter'),
@@ -310,6 +334,36 @@ function twig_date_format_filter(Twig_Environment $env, $date, $format = null, $
     return $date->format($format);
 }
 
+/**
+ * Number format filter.
+ *
+ * All of the formatting options can be left null, in that case the defaults will
+ * be used.  Supplying any of the parameters will override the defaults set in the
+ * environment object.
+ *
+ * @param Twig_Environment    $env          A Twig_Environment instance
+ * @param mixed               $number       A float/int/string of the number to format
+ * @param int                 $decimal      The number of decimal points to display.
+ * @param string              $decimalPoint The character(s) to use for the decimal point.
+ * @param string              $thousandSep  The character(s) to use for the thousands separator.
+ *
+ * @return string The formatted number
+ */
+function twig_number_format_filter(Twig_Environment $env, $number, $decimal = null, $decimalPoint = null, $thousandSep = null)
+{
+    $defaults = $env->getExtension('core')->getNumberFormat();
+    if ($decimal === null) {
+        $decimal = $defaults[0];
+    }
+    if ($decimalPoint === null) {
+        $decimalPoint = $defaults[1];
+    }
+    if ($thousandSep === null) {
+        $thousandSep = $defaults[2];
+    }
+    return number_format((float) $number, $decimal, $decimalPoint, $thousandSep);
+}
+
 /**
  * URL encodes a string.
  *

test/Twig/Tests/Fixtures/filters/number_format.test

@@ -0,0 +1,18 @@
+--TEST--
+"number_format" filter
+--TEMPLATE--
+{{ 20|number_format }}
+{{ 20.25|number_format }}
+{{ 20.25|number_format(2) }}
+{{ 20.25|number_format(2, ',') }}
+{{ 1020.25|number_format(2, ',') }}
+{{ 1020.25|number_format(2, ',', '.') }}
+--DATA--
+return array();
+--EXPECT--
+20
+20
+20.25
+20,25
+1,020,25
+1.020,25

test/Twig/Tests/Fixtures/filters/number_format_default.test

@@ -0,0 +1,21 @@
+--TEST--
+"number_format" filter with defaults.
+--TEMPLATE--
+{{ 20|number_format }}
+{{ 20.25|number_format }}
+{{ 20.25|number_format(1) }}
+{{ 20.25|number_format(2, ',') }}
+{{ 1020.25|number_format }}
+{{ 1020.25|number_format(2, ',') }}
+{{ 1020.25|number_format(2, ',', '.') }}
+--DATA--
+$twig->getExtension('core')->setNumberFormat(2, '!', '=');
+return array();
+--EXPECT--
+20!00
+20!25
+20!3
+20,25
+1=020!25
+1=020,25
+1.020,25