NAME

Tie::Comma - A simple and easy way to format numbers with commas, using a tied hash.

VERSION

This documentation describes version 0.04 of Tie::Comma, January 07, 2005

SYNOPSIS

 # The usual case; formatting with commas.
 $comma{$number};

 # Format with commas, and to a given number of places.
 $comma{$number, $decimal_places};

 # Format as above, with a minimum field width (right-justified).
 $comma{$number, $decimal_places, $minimum_field_width};

DESCRIPTION

This module provides a global read-only hash, %comma, for formatting numbers with commas. The tied-hash idiom is quite useful, since you can use it within a string as easily as outside a string.

The %comma hash may be "passed" one to three "arguments".

One-argument form

$string = $comma{$number};

Formats $number with commas.

Two-argument form

$string = $comma{$number, $decimals};

Formats $number with commas and $decimals decimal places.

Three-argument form

$string = $comma{$number, $decimals, $min_width};

Formats $number with commas and $decimals decimal places, and pads it with spaces on the left (right-justifying the number) so it takes up at least $min_width characters. If $decimals is undef, the $number is formatted with commas but not to any particular number of decimal places.

EXAMPLES

 # Simple formatting with commas:
 $a = 1234567.89;
 print "With commas: $comma{$a}";      => "With commas: 1,234,567.89"

 # Specify number of decimal places:
 print "1 decimal:   $comma{$a,1}";    => "1 decimal:   1,234,567.9"
 print "3 decimals:  $comma{$a,3}";    => "3 decimals:  1,234,567.890"

 # Specify field width:
 print "Min width:  '$comma{$a,0,12}'" => "Min width:  '   1,234,568'

 # In-string computations:
 print "Seconds in a year: $comma{365 * 24 * 60 * 60}";
    => "Seconds in a year: 31,536,000";

EXPORTS

Exports %comma.

REQUIREMENTS

Uses Carp and Exporter, which of course come with Perl.

SEE ALSO

Mark Dominus's excellent Interpolation module, which provides a much more general solution than this special-purpose module.

AUTHOR / COPYRIGHT

Eric J. Roode, roode@cpan.org

Copyright (c) 2005 by Eric J. Roode. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.