NAME
Template::Plugin::Number::Format - Plugin/filter interface to
Number::Format
SYNOPSIS
[% USE Number.Format %]
[% num | format_number %]
ABSTRACT
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.
DESCRIPTION
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:
THOUSANDS_SEP
character inserted between groups of 3 digits
DECIMAL_POINT
character separating integer and fractional parts
MON_THOUSANDS_SEP
like THOUSANDS_SEP, but used for format_price
MON_DECIMAL_POINT
like DECIMAL_POINT, but used for format_price
INT_CURR_SYMBOL
character(s) denoting currency (see format_price())
DECIMAL_DIGITS
number of digits to the right of dec point (def 2)
DECIMAL_FILL
boolean; whether to add zeroes to fill out decimal
NEG_FORMAT
format to display negative numbers (def -x)
KILO_SUFFIX
suffix to add when format_bytes formats kilobytes
MEGA_SUFFIX
suffix to add when format_bytes formats megabytes
GIGA_SUFFIX
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:
round($precision)
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.
format_negative($picture)
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.
format_picture($picture)
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.
format_price($precision)
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.
format_bytes($precision)
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.
unformat_number
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.
SEE ALSO
Template, Number::Format
AUTHOR
darren chamberlain