Data::Money - Money/currency with formatting and overloading.
Version 0.17
The Data::Money module provides basic currency formatting and number handling via Math::BigFloat:
Data::Money
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.
format
Data::Money was created to make it easy to use different currencies (leveraging existing work in Locale::Currency and Moo), to allow math operations with proper rounding (via Math::BigFloat) and formatting via Locale::Currency::Format.
Locale::Currency
use strict; use warnings; 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 print "Currency > 2 \n" if ($m2 > 2); print "Currency < 3 \n" if ($m2 < 3); print "Currency == 2.2 \n" if ($m2 == 2.2); # And strings print "Currency gt \$2.00 \n" if ($m2 gt '$2.00'); print "Currency lt \$3.00 \n" if ($m2 lt '$3.00'); print "Currency eq \$2.20 \n" if ($m2 eq '$2.20'); # and objects print "Currency m2 > m3 \n" if ($m2 > $m3); print "Currency m3 lt m2 \n" if ($m3 lt $m2); print $price->as_string('FMT_SYMBOL'); # $1.20
Returns Data::Money object currency name.
Gets/sets the three letter currency code for the current currency object.Defaults to USD.
Returns the amount. Defaults to 0.
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.
as_string()
FMT_COMMON
Returns a clone (new instance) of this Data::Money object. You may optionally specify some of the attributes to overwrite.
$currency->clone({ value => 100 }); # Clones all fields but changes value to 100
Returns Data::Money object value without any formatting.
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 a new Data::Money object with the value set to the absolute value of the original.
Performs the negation operation, returning a new Data::Money object with the opposite value (1 to -1, -2 to 2, etc).
Adds the specified amount to this Data::Money object and returns a new Data::Money object. You can supply either a number or a Data::Money object. Note that this does not modify the existing object.
Adds the specified amount to this Data::Money object, modifying its value. You can supply either a number or a Data::Money object. Note that this does modify the existing object.
Returns Data::Money object as string.There is an alias stringify() as well.
stringify()
Subtracts the specified amount to this Data::Money object and returns a new Data::Money object. You can supply either a number or a Data::Money object. Note that this does not modify the existing object.
Subtracts the specified amount to this Data::Money object,modifying its value. You can supply either a number or a Data::Money object. Note that this does modify the existing object.
Multiplies the value of this Data::Money object and returns a new Data::Money object. You dcan dsupply either a number or a Data::Money object. Note that this does not modify the existing object.
Multiplies the value of this Data::Money object, modifying its value. You can supply either a number or a Data::Money object. Note that this does modify the existing object.
Divides the value of this Data::Money object and returns a new Data::Money object. You can supply either a number or a Data::Money object. Note that this does not modify the existing object.
Divides the value of this Data::Money object, modifying its value. You can supply either a number or a Data::Money object. Note that this does modify the existing object.
Performs the modulo operation on this Data::Money object, returning a new Data::Money object with the value of the remainder.
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.
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 / 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.
add
Handled by the subtract method. Returns a new Data::Money object.
subtract
Handled by the multiply method. Returns a new Data::Money object.
multiply
Handled by the divide method. Returns a new Data::Money object.
divide
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.
add_in_place()
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.
subtract_in_place()
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.
multiply_in_place()
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.
divide_in_place()
Performs a three way comparsion. Works with either a Data::Money argument or a normal number.
This module was originally based on Data::Currency by Christopher H. Laco but I 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 <anelson@cpan.org>.
<anelson@cpan.org>
Cory G Watson, <gphat at cpan.org>
<gphat at cpan.org>
Currently maintained by Mohammad S Anwar (MANWAR) <mohammad.anwar at yahoo.com>
<mohammad.anwar at yahoo.com>
https://github.com/manwar/Data-Money
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 here for more information.
To install Data::Money, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Data::Money
CPAN shell
perl -MCPAN -e shell install Data::Money
For more information on module installation, please visit the detailed CPAN module installation guide.