1``format_number``
2=================
3
4.. versionadded:: 2.12
5
6    The ``format_number`` filter was added in Twig 2.12.
7
8The ``format_number`` filter formats a number:
9
10.. code-block:: twig
11
12    {{ '12.345'|format_number }}
13
14You can pass attributes to tweak the output:
15
16.. code-block:: twig
17
18    {# 12.34 #}
19    {{ '12.345'|format_number({rounding_mode: 'floor'}) }}
20
21    {# 1000000.0000 #}
22    {{ '1000000'|format_number({fraction_digit: 4}) }}
23
24The list of supported options:
25
26* ``grouping_used``;
27* ``decimal_always_shown``;
28* ``max_integer_digit``;
29* ``min_integer_digit``;
30* ``integer_digit``;
31* ``max_fraction_digit``;
32* ``min_fraction_digit``;
33* ``fraction_digit``;
34* ``multiplier``;
35* ``grouping_size``;
36* ``rounding_mode``;
37* ``rounding_increment``;
38* ``format_width``;
39* ``padding_position``;
40* ``secondary_grouping_size``;
41* ``significant_digits_used``;
42* ``min_significant_digits_used``;
43* ``max_significant_digits_used``;
44* ``lenient_parse``.
45
46Besides plain numbers, the filter can also format numbers in various styles:
47
48.. code-block:: twig
49
50    {# 1,234% #}
51    {{ '12.345'|format_number(style='percent') }}
52
53    {# twelve point three four five #}
54    {{ '12.345'|format_number(style='spellout') }}
55
56    {# 12 sec. #}
57    {{ '12'|format_duration_number }}
58
59The list of supported styles:
60
61* ``decimal``;
62* ``currency``;
63* ``percent``;
64* ``scientific``;
65* ``spellout``;
66* ``ordinal``;
67* ``duration``.
68
69As a shortcut, you can use the ``format_*_number`` filters by replacing `*` with
70a style:
71
72.. code-block:: twig
73
74    {# 1,234% #}
75    {{ '12.345'|format_percent_number }}
76
77    {# twelve point three four five #}
78    {{ '12.345'|format_spellout_number }}
79
80You can pass attributes to tweak the output:
81
82.. code-block:: twig
83
84    {# 12.3% #}
85    {{ '0.12345'|format_percent_number({rounding_mode: 'floor', fraction_digit: 1}) }}
86
87By default, the filter uses the current locale. You can pass it explicitly:
88
89.. code-block:: twig
90
91    {# 12,345 #}
92    {{ '12.345'|format_number(locale='fr') }}
93
94.. note::
95
96    The ``format_number`` filter is part of the ``IntlExtension`` which is not
97    installed by default. Install it first:
98
99    .. code-block:: bash
100
101        $ composer require twig/intl-extra
102
103    Then, on Symfony projects, install the ``twig/extra-bundle``:
104
105    .. code-block:: bash
106
107        $ composer require twig/extra-bundle
108
109    Otherwise, add the extension explicitly on the Twig environment::
110
111        use Twig\Extra\Intl\IntlExtension;
112
113        $twig = new \Twig\Environment(...);
114        $twig->addExtension(new IntlExtension());
115
116Arguments
117---------
118
119* ``locale``: The locale
120* ``attrs``: A map of attributes
121* ``style``: The style of the number output
122