format(3)

NAME

Number::Format - Perl extension for formatting numbers

SYNOPSIS

use Number::Format;
my $x = new Number::Format %args;
$formatted = $x->round($number, $precision);
$formatted  =   $x->format_number($number,   $precision,
$trailing_zeroes);
$formatted = $x->format_negative($number, $picture);
$formatted = $x->format_picture($number, $picture);
$formatted = $x->format_price($number, $precision);
$formatted = $x->format_bytes($number, $precision);
$number    = $x->unformat_number($formatted);
use Number::Format qw(:subs);
$formatted = round($number, $precision);
$formatted  = format_number($number, $precision, $trailing_zeroes);
$formatted = format_negative($number, $picture);
$formatted = format_picture($number, $picture);
$formatted = format_price($number, $precision);
$formatted = format_bytes($number, $precision);
$number    = unformat_number($formatted);

REQUIRES

Perl, version 5.003 or higher.

POSIX.pm will be used if present to determine locale set
tings.

Carp.pm is used for some error reporting.

DESCRIPTION

These functions provide an easy means of formatting num
bers in a manner suitable for displaying to the user.

There are two ways to use this package. One is to declare an object of type Number::Format, which you can think of as a formatting engine. The various functions defined here are provided as object methods. The constructor "new()" can be used to set the parameters of the format ting engine. Valid parameters are:: 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 for; mats kilobytes
MEGA_SUFFIX - " " " " " "; megabytes
GIGA_SUFFIX - " " " " " "; gigabytes
They may be specified in upper or lower case, with or without a leading hyphen ( - ).
The defaults for "THOUSANDS_SEP", "DECIMAL_POINT", "MON_THOUSANDS_SEP", "MON_DECIMAL_POINT", and "INT_CURR_SYMBOL" come from the POSIX locale information (see perllocale), if available. If your POSIX locale does not provide "MON_THOUSANDS_SEP" and/or "MON_DECIMAL_POINT" fields, then the "THOUSANDS_SEP" and/or "DECIMAL_POINT" values are used for those parameters. Some systems (e.g. Win32 ports of Perl) do not include POSIX support. In those systems, the POSIX system is bypassed.
If any of the above parameters are not specified when you invoke "new()", then the values are taken from package global variables of the same name (e.g. $DECIMAL_POINT is the default for the "DECIMAL_POINT" parameter). If you use the ":vars" keyword on your "use Number::Format" line (see non-object-oriented example below) you will import those variables into your namesapce and can assign values as if they were your own local variables. The default values for all the parameters are:: THOUSANDS_SEP = ','
DECIMAL_POINT = '.'
MON_THOUSANDS_SEP = ','
MON_DECIMAL_POINT = '.'
INT_CURR_SYMBOL = 'USD'
DECIMAL_DIGITS = 2
DECIMAL_FILL = 0
NEG_FORMAT = '-x'
KILO_SUFFIX = 'K'
MEGA_SUFFIX = 'M'
GIGA_SUFFIX = 'G'
Note however that when you first call one of the functions in this module without using the object-oriented inter face, further setting of those global variables will have no effect on non-OO calls. It is recommended that you use the object-oriented interface instead for fewer headaches and a cleaner design.
The "DECIMAL_FILL" and "DECIMAL_DIGITS" values are not set by the Locale system, but are definable by the user. They affect the output of "format_number()". Setting "DECI MAL_DIGITS" is like giving that value as the $precision argument to that function. Setting "DECIMAL_FILL" to a true value causes "format_number()" to append zeroes to the right of the decimal digits until the length is the specified number of digits.
"NEG_FORMAT" is only used by "format_negative()" and is a string containing the letter 'x', where that letter will be replaced by a positive representation of the number being passed to that function. "format_number()" and "format_price()" utilize this feature by calling "for mat_negative()" if the number was less than 0.
"KILO_SUFFIX", "MEGA_SUFFIX", and "GIGA_SUFFIX" are used by "format_bytes()" when the value is over 1024, 1024*1024, or 1024*1024*1024, respectively. The default values are "K", "M", and "G". Note: we can't do TERA because of integer overflows on 32-bit systems.
The only restrictions on "DECIMAL_POINT" and "THOU SANDS_SEP" are that they must not be digits, must not be identical, and must each be one character. There are no restrictions on "INT_CURR_SYMBOL".
For example, a German user might include this in their code:: use Number::Format;
my $de = new Number::Format(-thousands_sep => '.',
-decimal_point => ',',
-int_curr_symbol => 'DEM');; my $formatted = $de->format_number($number);
Or, if you prefer not to use the object oriented inter face, you can do this instead:: use Number::Format qw(:subs :vars);
$THOUSANDS_SEP = '.';
$DECIMAL_POINT = ',';
$INT_CURR_SYMBOL = 'DEM';
my $formatted = format_number($number);

EXPORTS

Nothing is exported by default. To export the func
tions or the global variables defined herein, specify the
function name(s) on the import list of the "use Num
ber::Format" statement. To export all functions defined
herein, use the special tag ":subs". To export the vari
ables, use the special tag ":vars"; to export both subs
and vars you can use the tag ":all".

METHODS

new( %args ): Creates a new Number::Format object. Valid keys for
%args are any of the parameters described above.
Keys may be in all uppercase or all lowercase, and may
optionally be preceded by a hyphen (-) character.
Example:

my $de = new Number::Format(-thousands_sep => '.',
-decimal_point => ',',
-int_curr_symbol =>

'DEM');
round($number, $precision): Rounds the number to the specified precision. If
$precision is omitted, the value of the "DECIMAL_DIG
ITS" parameter is used (default value 2). Both input
and output are numeric (the function uses math opera
tors rather than string manipulation to do its job),
The value of $precision may be any integer, positive
or negative. Examples:

round(3.14159) yields 3.14
round(3.14159, 4) yields 3.1416
round(42.00, 4) yields 42
round(1234, -2) yields 1200; Since this is a mathematical rather than string ori
ented function, there will be no trailing zeroes to
the right of the decimal point, and the "DECI
MAL_POINT" and "THOUSANDS_SEP" variables are ignored.
To format your number using the "DECIMAL_POINT" and
"THOUSANDS_SEP" variables, use "format_number()"
instead.
format_number($number, $precision, $trailing_zeroes): 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 preci
sion 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 $pre
cision is omitted, the value of the "DECIMAL_DIGITS"
parameter (default value of 2) is used. Examples:

format_number(12345.6789) yields '12,345.68'
format_number(123456.789, 2) yields '123,456.79'
format_number(1234567.89, 2) yields

'1,234,567.89'
format_number(1234567.8, 2) yields

'1,234,567.8'
format_number(1234567.8, 2, 1) yields

'1,234,567.80'
format_number(1.23456789, 6) yields '1.234568'; Of course the output would have your values of "THOU
SANDS_SEP" and "DECIMAL_POINT" instead of ',' and '.'
respectively.
format_negative($number, $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 num
bers you might use ``"-x"'', while for accounting pur
poses you might use ``"(x)"''. If the specified num
ber begins with a ``-'' character, that will be
removed before formatting, but formatting will occur
whether or not the number is negative.
format_picture($number, $picture): Returns a string based on $picture with the "#" char
acters 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. Examples:

format_picture(100.023, 'USD ##,###.##') yields

'USD 100.02'
format_picture(1000.23, 'USD ##,###.##') yields

'USD 1,000.23'
format_picture(10002.3, 'USD ##,###.##') yields

'USD 10,002.30'
format_picture(100023, 'USD ##,###.##') yields

'USD **,***.**'
format_picture(1.00023, 'USD #.###,###') yields

'USD 1.002,300'; The comma (,) and period (.) you see in the picture
examples should match the values of "THOUSANDS_SEP"
and "DECIMAL_POINT", respectively, for proper opera
tion. However, the "THOUSANDS_SEP" characters in
$picture need not occur every three digits; the only
use of that variable by this function is to remove
leading commas (see the first example above). There
may not be more than one instance of "DECIMAL_POINT"
in $picture.; The value of "NEG_FORMAT" is used to determine how
negative numbers are displayed. The result of this is
that the output of this function my have unexpected
spaces before and/or after the number. This is neces
sary so that positive and negative numbers are format
ted into a space the same size. If you are only using
positive numbers and want to avoid this problem, set
NEG_FORMAT to "x".
format_price($number, $precision): Returns a string containing $number formatted simi
larly 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. Examples:

format_price(12.95) yields 'USD 12.95'
format_price(12) yields 'USD 12.00'
format_price(12, 3) yields '12.000'; The third example assumes that "INT_CURR_SYMBOL" is
the empty string.
format_bytes($number, $precision): Returns a string containing $number formatted simi
larly to "format_number()", except that if the number
is over 1024, it will be divided by 1024 and "K"
appended to the end; or if it is over 1048576
(1024*1024), it will be divided by 1048576 and "M"
appended to the end. Negative values will result in
an error.; If $precision is not provided, the default of 2 will
be used. Examples:

format_bytes(12.95) yields '12.95'
format_bytes(2048) yields '2K'
format_bytes(1048576) yields '1M'; unformat_number($formatted)
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.
Examples:

unformat_number('USD 12.95') yields 12.95
unformat_number('USD 12.00') yields 12
unformat_number('foobar') yields undef
unformat_number('1234-567@.8') yields 1234567.8

The value of "DECIMAL_POINT" is used to determine
where to separate the integer and decimal portions of
the input. All other non-digit characters, includ
ing but not limited to "INT_CURR_SYMBOL" and "THOU
SANDS_SEP", are removed.

If the number matches the pattern of "NEG_FORMAT" or
there is a ``-'' character before any of the digits,
then a negative number is returned.

If the number ends with the "KILO_SUFFIX" or
"MEGA_SUFFIX" characters, then the number returned
will be multiplied by 1024 or 1024*1024 as appropri
ate.

BUGS

No known bugs at this time. Please report any problems to
the author.

AUTHOR

William R. Ward, wrw@bayview.com

docs.sk

comprehensive documentation repository

See also