NAME

Number::Format - Perl extension for formatting numbers

SYNOPSIS

  use Number::Format;
  
  $rounded = round($number, $precision);
  $formatted = format_number($number, $precision);
  $formatted = format_picture($number, $picture);
  $formatted = format_price($number, $precision);
  $number = unformat_number($formatted);

REQUIRES

Perl, version 5.003 or higher.

DESCRIPTION

These functions provide an easy means of formatting numbers 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 formatting 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())

They may be specified in upper or lower case, with or without a leading hyphen ( - ). The defaults come from the POSIX locale information (see perllocale). 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. If any of the thousands_sep, decimal_point, and/or int_curr_symbol are not set, then package global variables $THOUSANDS_SEP, $DECIMAL_POINT, and/or $INT_CURR_SYMBOL are used, which by default have the values comma (,), period (.), and US dollars ( USD ) respectively. You can change the default values by setting the global variables $DECIMAL_POINT, and $THOUSANDS_SEP, and $INT_CURR_SYMBOL to any characters you wish. 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 only restrictions on decimal_point and thousands_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 interface, 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 functions or the global variables defined herein, specify the function name(s) on the import list of the use Number::Format statement. To export all functions defined herein, use the special tag :subs. To export the variables, 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 DECIMAL_POINT, THOUSANDS_SEP, and INT_CURR_SYMBOL. 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 default value of 2 is used. Both input and output are numeric (the function uses math operators 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 oriented function, there will be no trailing zeroes to the right of the decimal point, and the DECIMAL_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)

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 not appear in the output (see format_price() for that). If $precision is omitted, the 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(1.23456789, 6)   yields   '1.234568'

Of course the output would have your values of THOUSANDS_SEP and DECIMAL_POINT instead of ',' and '.' respectively.

format_picture($number, $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. 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 operation. 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.

format_price($number, $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. 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.

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, including but not limited to INT_CURR_SYMBOL and THOUSANDS_SEP, are removed.

AUTHOR

William R. Ward, wrw@bayview.com

SEE ALSO

perl(1).