From e08ca837dfa67237fb0eed924ce2b763d0afad09 Mon Sep 17 00:00:00 2001 From: unknown Date: Thu, 25 Jan 2024 19:20:25 +0100 Subject: [PATCH] Added informations in format_currency and format_number docs --- doc/filters/format_currency.rst | 108 ++++++++++++++++++----- doc/filters/format_number.rst | 148 ++++++++++++++++++++++++++------ 2 files changed, 210 insertions(+), 46 deletions(-) diff --git a/doc/filters/format_currency.rst b/doc/filters/format_currency.rst index 6f1036d33..b61823d04 100644 --- a/doc/filters/format_currency.rst +++ b/doc/filters/format_currency.rst @@ -20,25 +20,88 @@ You can pass attributes to tweak the output: The list of supported options: -* ``grouping_used``; -* ``decimal_always_shown``; -* ``max_integer_digit``; -* ``min_integer_digit``; -* ``integer_digit``; -* ``max_fraction_digit``; -* ``min_fraction_digit``; -* ``fraction_digit``; -* ``multiplier``; -* ``grouping_size``; -* ``rounding_mode``; -* ``rounding_increment``; -* ``format_width``; -* ``padding_position``; -* ``secondary_grouping_size``; -* ``significant_digits_used``; -* ``min_significant_digits_used``; -* ``max_significant_digits_used``; -* ``lenient_parse``. +* ``grouping_used``: Specifies whether to use grouping separator for thousands. + .. code-block:: twig + + {# €1,234,567.89 #} + {{ 1234567.89 | format_currency('EUR', {grouping_used:true}, 'en') }} + +* ``decimal_always_shown``: Specifies whether to always show the decimal part, even if it's zero. + .. code-block:: twig + + {# €123.00 #} + {{ 123 | format_currency('EUR', {decimal_always_shown:true}, 'en') }} + +* ``max_integer_digit``: +* ``min_integer_digit``: +* ``integer_digit``: Define constraints on the integer part. + .. code-block:: twig + + {# €345.68 #} + {{ 12345.6789 | format_currency('EUR', {max_integer_digit:3, min_integer_digit:2}, 'en') }} + +* ``max_fraction_digit``: +* ``min_fraction_digit``: +* ``fraction_digit``: Define constraints on the fraction part. + .. code-block:: twig + + {# €123.46 #} + {{ 123.456789 | format_currency('EUR', {max_fraction_digit:2, min_fraction_digit:1}, 'en') }} + +* ``multiplier``: Multiplies the value before formatting. + .. code-block:: twig + + {# €123,000.00 #} + {{ 123 | format_currency('EUR', {multiplier:1000}, 'en') }} + +* ``grouping_size``: +* ``secondary_grouping_size``: Set the size of the primary and secondary grouping separators. + .. code-block:: twig + + {# €1,23,45,678.00 #} + {{ 12345678 | format_currency('EUR', {grouping_size:3, secondary_grouping_size:2}, 'en') }} + +* ``rounding_mode``: +* ``rounding_increment``: Control rounding behavior, here is a list of all rounding_mode available: + * ``ceil``: Ceiling rounding. + * ``floor``: Floor rounding. + * ``down``: Rounding towards zero. + * ``up``: Rounding away from zero. + * ``half_even``: Round halves to the nearest even integer. + * ``half_up``: Round halves up. + * ``half_down``: Round halves down. + + .. code-block:: twig + + {# €123.50 #} + {{ 123.456 | format_currency('EUR', {rounding_mode:'ceiling', rounding_increment:0.05}, 'en') }} + +* ``format_width``: +* ``padding_position``: Set width and padding for the formatted number, here is a list of all padding_position available: + * ``before_prefix``: Pad before the currency symbol. + * ``after_prefix``: Pad after the currency symbol. + * ``before_suffix``: Pad before the suffix (currency symbol). + * ``after_suffix``: Pad after the suffix (currency symbol). + + .. code-block:: twig + + {# €123.00 #} + {{ 123 | format_currency('EUR', {format_width:10, padding_position:'before_suffix'}, 'en') }} + +* ``significant_digits_used``: +* ``min_significant_digits_used``: +* ``max_significant_digits_used``: Control significant digits in formatting. + .. code-block:: twig + + {# €123.4568 #} + {{ 123.456789 | format_currency('EUR', {significant_digits_used:true, min_significant_digits_used:4, max_significant_digits_used:7}, 'en') }} + + +* ``lenient_parse``: If true, allows lenient parsing of the input. + .. code-block:: twig + + {# €123.00 #} + {{ 123 | format_currency('EUR', {lenient_parse:true}, 'en') }} By default, the filter uses the current locale. You can pass it explicitly: @@ -72,8 +135,13 @@ By default, the filter uses the current locale. You can pass it explicitly: Arguments --------- -* ``currency``: The currency +* ``currency``: The currency (any 3 letter code of ISO 4217) * ``attrs``: A map of attributes * ``locale``: The locale code as defined in `RFC 5646`_ +.. note:: + + Internally, Twig uses the PHP `NumberFormatter::formatCurrency`_ function. + .. _RFC 5646: https://www.rfc-editor.org/info/rfc5646 +.. _`NumberFormatter::formatCurrency`: https://www.php.net/manual/en/numberformatter.formatcurrency.php diff --git a/doc/filters/format_number.rst b/doc/filters/format_number.rst index e1bedc2fc..e6060c675 100644 --- a/doc/filters/format_number.rst +++ b/doc/filters/format_number.rst @@ -19,25 +19,87 @@ You can pass attributes to tweak the output: The list of supported options: -* ``grouping_used``; -* ``decimal_always_shown``; -* ``max_integer_digit``; -* ``min_integer_digit``; -* ``integer_digit``; -* ``max_fraction_digit``; -* ``min_fraction_digit``; -* ``fraction_digit``; -* ``multiplier``; -* ``grouping_size``; -* ``rounding_mode``; -* ``rounding_increment``; -* ``format_width``; -* ``padding_position``; -* ``secondary_grouping_size``; -* ``significant_digits_used``; -* ``min_significant_digits_used``; -* ``max_significant_digits_used``; -* ``lenient_parse``. +* ``grouping_used``: Specifies whether to use grouping separator for thousands. + .. code-block:: twig + + {# 1,234,567.89 #} + {{ 1234567.89|format_number({grouping_used:true}, locale='en') }} + +* ``decimal_always_shown``: Specifies whether to always show the decimal part, even if it's zero. + .. code-block:: twig + + {# 123. #} + {{ 123|format_number({decimal_always_shown:true}, locale='en') }} + +* ``max_integer_digit``: +* ``min_integer_digit``: +* ``integer_digit``: Define constraints on the integer part. + .. code-block:: twig + + {# 345.679 #} + {{ 12345.6789|format_number({max_integer_digit:3, min_integer_digit:2}, locale='en') }} + +* ``max_fraction_digit``: +* ``min_fraction_digit``: +* ``fraction_digit``: Define constraints on the fraction part. + .. code-block:: twig + + {# 123.46 #} + {{ 123.456789|format_number({max_fraction_digit:2, min_fraction_digit:1}, locale='en') }} + +* ``multiplier``: Multiplies the value before formatting. + .. code-block:: twig + + {# 123,000 #} + {{ 123|format_number({multiplier:1000}, locale='en') }} + +* ``grouping_size``: +* ``secondary_grouping_size``: Set the size of the primary and secondary grouping separators. + .. code-block:: twig + + {# 1,23,45,678 #} + {{ 12345678|format_number({grouping_size:3, secondary_grouping_size:2}, locale='en') }} + +* ``rounding_mode``: +* ``rounding_increment``: Control rounding behavior, here is a list of all rounding_mode available: + * ``ceil``: Ceiling rounding. + * ``floor``: Floor rounding. + * ``down``: Rounding towards zero. + * ``up``: Rounding away from zero. + * ``half_even``: Round halves to the nearest even integer. + * ``half_up``: Round halves up. + * ``half_down``: Round halves down. + + .. code-block:: twig + + {# 123.5 #} + {{ 123.456|format_number({rounding_mode:'ceiling', rounding_increment:0.05}, locale='en') }} + +* ``format_width``: +* ``padding_position``: Set width and padding for the formatted number, here is a list of all padding_position available: + * ``before_prefix``: Pad before the currency symbol. + * ``after_prefix``: Pad after the currency symbol. + * ``before_suffix``: Pad before the suffix (currency symbol). + * ``after_suffix``: Pad after the suffix (currency symbol). + + .. code-block:: twig + + {# 123 #} + {{ 123|format_number({format_width:10, padding_position:'before_suffix'}, locale='en') }} + +* ``significant_digits_used``: +* ``min_significant_digits_used``: +* ``max_significant_digits_used``: Control significant digits in formatting. + .. code-block:: twig + + {# 123.4568 #} + {{ 123.456789|format_number({significant_digits_used:true, min_significant_digits_used:4, max_significant_digits_used:7}, locale='en') }} + +* ``lenient_parse``: If true, allows lenient parsing of the input. + .. code-block:: twig + + {# 123 #} + {{ 123|format_number({lenient_parse:true}, locale='en') }} Besides plain numbers, the filter can also format numbers in various styles: @@ -54,13 +116,47 @@ Besides plain numbers, the filter can also format numbers in various styles: The list of supported styles: -* ``decimal``; -* ``currency``; -* ``percent``; -* ``scientific``; -* ``spellout``; -* ``ordinal``; -* ``duration``. +* ``decimal``: + .. code-block:: twig + + {# 1,234.568 #} + {{ 1234.56789 | format_number(style='decimal', locale='en') }} + +* ``currency``: + .. code-block:: twig + + {# $1,234.56 #} + {{ 1234.56 | format_number(style='currency', locale='en') }} + +* ``percent``: + .. code-block:: twig + + {# 12% #} + {{ 0.1234 | format_number(style='percent', locale='en') }} + +* ``scientific``: + .. code-block:: twig + + {# 1.23456789e+3 #} + {{ 1234.56789 | format_number(style='scientific', locale='en') }} + +* ``spellout``: + .. code-block:: twig + + {# one thousand two hundred thirty-four point five six seven eight nine #} + {{ 1234.56789 | format_number(style='spellout', locale='en') }} + +* ``ordinal``: + .. code-block:: twig + + {# 1st #} + {{ 1 | format_number(style='ordinal', locale='en') }} + +* ``duration``: + .. code-block:: twig + + {# 2:30:00 #} + {{ 9000 | format_number(style='duration', locale='en') }} As a shortcut, you can use the ``format_*_number`` filters by replacing ``*`` with a style: