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
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 <darren@cpan.org>