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 <anelson@cpan.org>.

AUTHOR

Cory G Watson, <gphat at cpan.org>

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.

cpanm Data::Money

perl -MCPAN -e shell
install Data::Money