---
name: "Template::Plugin::Number::Format"
section: "3pm"
platform: "linux"
package: "libtemplate-plugin-number-format-perl"
version: "1.06-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Template::Plugin::Number::Format"
---

# Template::Plugin::Number::Format(3pm)

Plugin/filter interface to Number::Format

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