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.