Template::Plugin::Number::Format(3) Plugin/filter interface to Number::Format


[% USE Number.Format %]
[% num | format_number %]


Template::Plugin::Number::Format makes the number-munging grooviness of Number::Format available to your templates. It is used like a plugin, but installs filters into the current context.


All filters created by Template::Plugin::Number::Format can be configured by constructor options and options that can be passed to individual filters. See ``METHODS'' in Number::Format for all the details.

Constructor Parameters

The USE line accepts the following parameters, all optional, which define the default behavior for filters within the current Context:
character inserted between groups of 3 digits
character separating integer and fractional parts
like THOUSANDS_SEP, but used for format_price
like DECIMAL_POINT, but used for format_price
character(s) denoting currency (see format_price())
number of digits to the right of dec point (def 2)
boolean; whether to add zeroes to fill out decimal
format to display negative numbers (def -x)
suffix to add when format_bytes formats kilobytes
suffix to add when format_bytes formats megabytes
suffix to add when format_bytes formats gigabytes

Using Template::Plugin::Number::Format

When you invoke:

    [% USE Number.Format(option = value) %]

the following filters are installed into the current Context:

Rounds the number to the specified precision. If ``$precision'' is omitted, the value of the ``DECIMAL_DIGITS'' parameter is used (default value 2).
format_number($precision, $trailing_zeros)
Formats a number by adding ``THOUSANDS_SEP'' between each set of 3 digits to the left of the decimal point, substituting ``DECIMAL_POINT'' for the decimal point, and rounding to the specified precision using ``round()''. Note that ``$precision'' is a maximum precision specifier; trailing zeroes will only appear in the output if ``$trailing_zeroes'' is provided, or the parameter ``DECIMAL_FILL'' is set, with a value that is true (not zero, undef, or the empty string). If ``$precision'' is omitted, the value of the ``DECIMAL_DIGITS'' parameter (default value of 2) is used.
Formats a negative number. Picture should be a string that contains the letter ``x'' where the number should be inserted. For example, for standard negative numbers you might use ``-x'', while for accounting purposes you might use ``(x)''. If the specified number begins with a - character, that will be removed before formatting, but formatting will occur whether or not the number is negative.
Returns a string based on ``$picture'' with the ``#'' characters replaced by digits from ``$number''. If the length of the integer part of $number is too large to fit, the ``#'' characters are replaced with asterisks (``*'') instead.
Returns a string containing ``$number'' formatted similarly to ``format_number()'', except that the decimal portion may have trailing zeroes added to make it be exactly ``$precision'' characters long, and the currency string will be prefixed.

If the ``INT_CURR_SYMBOL'' attribute of the object is the empty string, no currency will be added.

If ``$precision'' is not provided, the default of 2 will be used.

Returns a string containing ``$number'' formatted similarly to ``format_number()'', except that if the number is over 1024, it will be divided by 1024 and the value of KILO_SUFFIX appended to the end; or if it is over 1048576 (1024*1024), it will be divided by 1048576 and MEGA_SUFFIX appended to the end. Negative values will result in an error.

If ``$precision'' is not provided, the default of 2 will be used.

Converts a string as returned by ``format_number()'', ``format_price()'', or ``format_picture()'', and returns the corresponding value as a numeric scalar. Returns ``undef'' if the number does not contain any digits.


darren chamberlain <[email protected]>