NAME Data::Money - Money/currency with formatting and overloading. SYNOPSIS use Data::Money; my $price = Data::Money->new(value => 1.2. code => 'USD'); print $price; # $1.20 print $price->code; # USD print $price->format; # FMT_COMMON print $price->as_string; # $1.20 # Overloading, returns new instance my $m2 = $price + 1; my $m3 = $price - 1; my $m4 = $price * 1; my $m5 = $price / 1; my $m6 = $price % 1; # Objects work too my $m7 = $m2 + $m3; my $m8 = $m2 - $m3; my $m9 = $m2 * $m3; my $m10 = $m2 / $m3; # Modifies in place $price += 1; $price -= 1; $price *= 1; $price /= 1; # Compares against numbers if($m2 > 2) if($m2 < 3) if($m2 == 2.2) # And strings if($m2 gt '$2.00') if($m2 lt '$3.00') if($m2 eq '$2.20') # and objects if($m2 > $m3) if($m3 lt $m2) print $price->as_string('FMT_SYMBOL'); # $1.20 DESCRIPTION The Data::Money module provides basic currency formatting and number handling via Math::BigFloat: my $currency = Data::Money->new(value => 1.23); Each Data::Money object will stringify to the original value except in string context, where it stringifies to the format specified in "format". MOTIVATION Data::Money was created to make it easy to use different currencies (leveraging existing work in "Locale::Currency" and Moose), to allow math operations with proper rounding (via Math::BigFloat) and formatting via Locale::Currency::Format. OPERATOR OVERLOADING Data::Money overrides some operators. It is important to note which operators change the object's value and which return new ones. All operators accept either a Data::Money argument or a normal number via scalar, and will die if the currency types mismatch. Data::Money overloads the following operators: + Handled by the "add" method. Returns a new Data::Money object. - Handled by the "subtract" method. Returns a new Data::Money object. * Handled by the "multiply" method. Returns a new Data::Money object. / Handled by the "divide" method. Returns a new Data::Money object. += Handled by the "add_in_place" method. Modifies the left-hand object's value. Works with either a Data::Money argument or a normal number. -= Handled by the "subtract_in_place" method. Modifies the left-hand object's value. Works with either a Data::Money argument or a normal number. *= Handled by the "multiply_in_place" method. Modifies the left-hand object's value. Works with either a Data::Money argument or a normal number. /= Handled by the "divide_in_place" method. Modifies the left-hand object's value. Works with either a Data::Money argument or a normal number. <=> Performs a three way comparsion. Works with either a Data::Money argument or a normal number. ATTRIBUTES code Gets/sets the three letter currency code for the current currency object. Defaults to USD format Gets/sets the format to be used when "as_string" is called. See Locale::Currency::Format for the available formatting options. Defaults to "FMT_COMMON". name Returns the currency name for the current objects currency code. If no currency code is set the method will die. value The amount of money/currency. Defaults to 0. METHODS add($amount) Adds the specified amount to this Data::Money object and returns a new Data::Money object. You can supply either a number of a Data::Money object. Note that this does not modify the existing object. add_in_place($amount) Adds the specified amount to this Data::Money object, modifying its value. You can supply either a number of a Data::Money object. Note that this does modify the existing object. as_int Returns the object's value "in pennies" (in the US at least). It strips the value of formatting using "as_float" and of any decimals. as_float Returns objects value without any formatting. subtract($amount) Subtracts the specified amount to this Data::Money object and returns a new Data::Money object. You can supply either a number of a Data::Money object. Note that this does not modify the existing object. subtract_in_place($amount) Subtracts the specified amount to this Data::Money object, modifying its value. You can supply either a number of a Data::Money object. Note that this does modify the existing object. multiply($amount) Multiplies the value of this Data::Money object and returns a new Data::Money object. You can supply either a number of a Data::Money object. Note that this does not modify the existing object. multiply_in_place($amount) Multiplies the value of this Data::Money object, modifying its value. You can supply either a number of a Data::Money object. Note that this does modify the existing object. divide($amount) Divides the value of this Data::Money object and returns a new Data::Money object. You can supply either a number of a Data::Money object. Note that this does not modify the existing object. divide_in_place($amount) Divides the value of this Data::Money object, modifying its value. You can supply either a number of a Data::Money object. Note that this does modify the existing object. modulo Performs the modulo operation on this Data::Money object, returning a new Data::Money object with the value of the remainder. three_way_compare Compares a Data::Money object to another Data::Money object, or anything it is capable of coercing - numbers, numerical strings, or Math::BigFloat objects. Both numerical and string comparators work. negate Performs the negation operation, returning a new Data::Money object with the opposite value (1 to -1, -2 to 2, etc). absolute Returns a new Data::Money object with the value set to the absolute value of the original. clone(%params) Returns a clone (new instance) of this Data::Money object. You may optionally specify some of the attributes to overwrite. $curr->clone({ value => 100 }); # Clones all fields but changes value to 100 See MooseX::Clone for more information. stringify Sames as "as_string". as_string Returns the current objects value as a formatted currency string. SEE ALSO Locale::Currency, Locale::Currency::Format, ACKNOWLEDGEMENTS This module was originally based on Data::Currency by Christopher H. Laco but I opted to fork and create a whole new module because my work was wildly different from the original. I decided it was better to make a new module than to break back compat and surprise users. Many thanks to him for the great module. Inspiration and ideas were also drawn from Math::Currency and Math::BigFloat. Major contributions (more overloaded operators, disallowing operations on mismatched currences, absolute value, negation and unit tests) from Andrew Nelson "". Major contributions (more overloaded operators, disallowing operations on mismatched currences, absolute value, negation and unit tests) from Andrew Nelson. AUTHOR Cory G Watson, "" Copyright 2010 Cory Watson This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License. See http://dev.perl.org/licenses/ for more information.