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

3 POD Errors

The following errors were encountered while parsing the POD:

- Around line 33:
Unknown directive: =over4

- Around line 35:
'=item' outside of any '=over'

- Around line 104:
Unterminated C<...> sequence