NAME

Comma - Yet Another way to format numbers with commas, this time via tied hash.

VERSION

This documentation describes version 0.01 of Comma.pm, January 03, 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.