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. 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.