NAME

Text::Number - Overloaded class for printing numbers

SYNOPSIS

Provides a facility for transparently configuring numbers to print the way you want them to. Calculations are always executed using the full precision of the number, but printing is rounded to the number of places of your choosing.

Extended printing operations are configurable via the format method.

DESCRIPTION

use Text::Number;

$allowance = number(value => 5, places => 2);

print STDOUT "My allowance is $allowance dollars."

> My allowance is 5.00 dollars.

require Text::Number;

$allowance = Text::Number-new(value => 5, places => 2)>;

$allowance += 5000; print "$allowance";

> 5005.00

$allowance->format(type => 'number'); print "$allowance";

> 5,005.00

EXPORTS

If you import Text::Number with the <use> statement, the number constructor will be imported into your namespace. If you'd rather not import this symbol, require Text::Number instead and use either new Text::Number or Text::Number->number as your constructor.

OPERATORS

Objects created by this module should function transparently with these operators:

+ - / * "" x ** ++ += -- -= *= /= < > <= >= <=>

abs atan2 cos exp log sin sqrt

METHODS

new (synonymous with number)

$number = number(6); (only if you used)

$number = new Text::Number(value => 6, places => 0)

$number = Text::Number->number(6)

places

Returns the display precision of the number.

$precision = $number->places

value

Returns the real value of the number.

$value = $number->value

format

Use this method to configure the number for more sophisticated printing option, i.e., anything other than plain old decimal point control. If you invoke this method, you need to have Number::Format installed on your system, as this module is used to generate the formats. The module is only loaded at runtime so Text::Number will work without it, except you won't have access to these formatting options.

Number::Format is a very useful and feature-rich module. Please see the pod for that module for a better description of it capabilities.

$success = $number->format(type => number) inserts commas, or the local equivalent, into numbers > 1000. It can also insert the localized decimal point character.

$success = $number->format(type => picture, template => template )

Please see the Number::Format docs for more information.

$success = $number->format(type => negative,template => template )

Please see the Number::Format docs for more information.

$success = $number->format(type => price)

Prepends the printed output with the local currency symbol. Please see the Number::Format docs for more information.

$success = $number->format(type => bytes)

Prints the number as K or M. Please see the Number::Format docs for more information.

$success = $number->format()

Will remove the advanced formatting option.

CAVEATS and NOTES

Performance Issues

I wrote this to help me transparently configure number printing formats for figures that get passed around between objects that print. In this capacity it works pretty decently for me. However, using these objects in place of numeric scalars adds a fair bit of memory and processor consumption, so I'd recommend only using them when you need to print numbers, and for the occasional calculation.

If you have many calculations to do, you can do the calculations first, and then stuff the value into a Text::Number object.

Exception Handling

All calculations that can throw exceptions are wrapped in evals. If your calculation threw an exception (say, divided bt zero), the return value will be an empty string. I was considering returning an instance of the object with the value set to zero, but this seemed confusing, since you wouldn't necessarily know if the value was the result of math or of the exception. I also considered undef.

I'm open to suggestion on this -- if anyone is using this object and has suggestions, please send them to me <fix@fixler.com>

REQUIRES

Perl 5.005

POSIX

Number::Format (optional)

AUTHOR

Eric Fixler <fix@fixler.com>

Copyright 1999. You are free to use, modify, and redistribute this module as long as the source remains freely available, and credit is given to the the original author (i.e., me).

TODO

Fuller and better implementation of Number::Format methods.

Elimination of POSIX call (there's only one).

Implement mod arithmetic.

Is Text::Number really the right name for this package?

ACKNOWLEDGEMENTS

Tom Christansen and Nathan Torkington; their StrNum/overload example in the [excellent] Perl Cookbook was the beginning of this module.

William R. Ward <wrw@bayview.com> author of Number::Format.

SEE ALSO

Number::Format

cpanm Text::Number

perl -MCPAN -e shell
install Text::Number