NAME

Math::Financial - Calculates figures relating to loans and annuities.

SYNOPSIS

$calc = new Math::Financial(fv => 100000, pv => 1000); $calc->set->(pmt => 500, ir => 8);

$calc->compound_interest(find => 'fv');

DESCRIPTION

This package contains solves mathematical problems relating to loans and annuities.

The attributes that are used in the equations may be set on a per-object basis, allowing you to run a set of different calculations using the same numbers, or they may be fed directly to the methods.

The attribute types, accessed through the get and set methods are

pv => Present Value

fv => Future Value

ir => Yearly Interest Rate (in percent)

pmt => Payment Amount

np => Number of Payments/Loan Term

tpy => Terms Per Year (defaults to 12)

pd => Payments made so far (used only for loan/annuity balances)

Attributes are case-insensitive. The documentation for the individual methods indicates which attributes must be set for those methods.

Calculations are based either on the attributes set with the new or set methods, or with arguments fed directly to the methods. This seemed like the least confusing way to make the interface flexible for people who are using the module in different ways.

Also, performing a calculation does not update the attribute of the solution. In other words, if you solve an equation that returns fv, the solution is returned but the internal fv field is unaffected.

Any attempted calculation which cannot be completed -- due to either missing or invalid attributes -- will return undef.

I am interested to hear from people using this module -- let me know what you think about the interface and how it can be improved.

METHODS

new

$calc = new Math::Financial();

$calc = new Math::Financial(pv => 10000, ir => 5, np = 12)>

Object constructor. See above for a description of the available attributes. You do not have to set attributes here, you can also do so using set, or feed attributes directly to the methods.

There are no default values for any of the attributes except TPY (Terms Per Year), which is 12 by default, and PD which defaults to zero.

If you don't want to use the object-oriented interface, see the EXPORTS section below.

set

$calc->set(fv => 100000, pmt => 500)

You can set any of the stored attributes using this method, which is is also called by <new>. Returns the number of attributes set.

get

$calc->get(field = 'ir')>

$calc->get('ir','pmt','pv')

$calc->get([qw(ir pmt pv)])

You can get one or several attributes using this method. In the multiple attribute formats, it accepts either a list or a list reference as input.

In single attribute context, returns a scalar. In multiple attribute context, it returns a list or a reference to a list, depending on the calling context.

compound_interest

$calc->compound_interest

$calc->compound_interest->('fv')

$calc->compound_interest->(find => 'fv')

Calculates compund interest for an annuity. With any 3 of pv, fv, np, and ir, you can always solve the fourth.

Without arguments, the method will attempt to figure out what you'd like to solve based on what attributes of the object are defined. Usually, you'll probably want to explicitly request what attribute you'd like returned, which you can do using the second or third method.

funding_annuity

$calc->funding_annuity

$calc->funding_annuity->(pmt => 2000, ir => 6.50, np => 40, tpy = 4)>

funding_annuity calculates how much money ( fv ) you will have at the end of np periods if you deposit pmt into the account each period and the account earns ir interest per year.

You may want to set the tpy attribute here to something other than 12, since, while loans usually compound monthly, annuities rarely do.

loan_balance

$calc->loan_balance

$calc->loan_balance->(pmt => 2000, ir => 6.50, np => 360, pd => 12)

loan_balance calculates the balance on a loan that is being made in np equal payments, given that pd payments have already been made. You can also use this method to determine the amount of money left in an annuity that you are drawing down.

loan_payment

$calc->loan_payment

Return the payment amount, per period, of a loan. This is also known as amortizing. The ir, np, and pv fields must be set.

loan_size

$calc->loan_term

$calc->loan_size->(pmt => 2000, ir => 6.50, np => 360)

loan_size calculates the size of loan you can get based on the monthly payment you can afford.

loan_term

$calc->loan_term

Return the number of payments (term) of a loan given the interest rate ir, payment amount pmt and loan amount pv. The ir, pmt, and pv fields must be set.

simple_interest

$calc->simple_interest

$calc->simple_interest->('ir')

$calc->simple_interest->(find => 'ir')

This works just like compound interest, but there is no consideration of np. With any 2 of pv, fv, and ir, you can always solve for the third.

Without arguments, the method will attempt to figure out what you'd like to solve based on what attributes of the object have been defined. Usually, you'll probably want to explicitly request what attribute you'd like returned, which you can do using the second or third method.

REQUIRES

POSIX -- c_type functions

(c_types might work under Windows. I really don't know. I'd appreciate it if someome would let me know. If they don't, in a future release, I'll provide a runtime replacement for the POSIX functions so it'll work on Win releases. )

EXPORTS

By default, nothing.

If you'd like to use a procedural interface, you can use Math::Financial qw(:standard).

Then you can call the methods as function, without an object reference, like

$term = loan_term(ir => 6.5, pmt => 1000, pv => 200000);

All of the methods are exported in this fashion, except for set and get; this just seemed too confusing.

You can still use the facility of set and get with the procedural interface (i.e., you can set the attributes and them use them for many different calculations), but you must call them as Math::Financial::set and Math::Financial::get.

AUTHOR

Eric Fixler <fix@fixler.com>, 1999

TODO

Add more equations! Send me equations and I'll put them in.

ACKNOWLEDGEMENTS

Larry Freeman, whose Financial Formulas Page http://ourworld.compuserve.com/homepages/Larry_Freeman/finance.htm was essential for this project.

cpanm Math::Financial

perl -MCPAN -e shell
install Math::Financial