Previous Next

Class Finance

The Finance class is a BIRT-provided JavaScript class that provides a set of static financial functions that you can use to perform a variety of common business computations. Financial values can be represented as a float value. The application cannot create an instance of this class.

Finance.ddb

This function returns the depreciation of an asset for a given, single period using the double-declining balance method. Double-declining balance depreciation is an accelerated method of depreciation that results in higher depreciation charges and greater tax savings in the earlier years of the useful life of a fixed asset than are given by the straight-line depreciation method (SLN), where charges are uniform throughout.

The function uses the following formula for depreciation over a single period:

depreciation = (( initialCost - totalDepreciationFromPriorPeriods) * 2) / assetLifespan

The following rules apply:

*
*

Syntax

double ddb( double cost, double salvage, double life, integer period )

Parameters

initial

Double. Numeric expression that specifies the initial cost of the asset.

salvage

Double. Numeric expression that specifies the value of the asset at the end of its useful life.

life

Double. Numeric expression that specifies the length of the useful life of the asset. You must provide this value in the same units of measure as singlePeriod. For example, if singlePeriod represents a month, then assetLifespan must be expressed in months.

period

Integer. Numeric expression that specifies the period for which you want DDB to calculate the depreciation. You must provide this value in the same units of measure as assetLifespan. For example, if assetLifespan is expressed in months, then singlePeriod must represent a period of one month.

Returns

Double.

Example

The following example calculates the depreciation for the first year under the double-declining balance method for a new machine purchased at $1400, with a salvage value of $200, and a useful life estimated at 10 years. The result ($280) is assigned to the variable Year1Deprec:

Year1Deprec = Finance.ddb(1400, 200, 10, 1)

See also

Finance.sln function

Finance.syd function

Finance.fv

This function returns the future value of an annuity based on periodic constant payments, and on an unvarying interest rate. An annuity is a series of cash payments, constant in value, made over a period of time. An annuity can be an investment, such as a monthly savings plan, or a loan, such as a home mortgage. The future value of an annuity is the cash balance you want after you have made your final payment.

For example, if you set up a savings plan with a goal of having $75,000 in 18 years to pay for your child's education, the future value of the plan is $75,000.

Or if you take out a loan for $11,000, the future value of the loan is $0.00, as it is for any typical loan.

The following rules apply:

*
*

Syntax

double fv( double rate, integer nPer, double pmt, double pvalue, integer due )

Parameters

rate

Double numeric expression that specifies the interest rate that accrues per period. You must provide this value in the same units of measure as numberPayPeriods. For instance, if numberPayPeriods is expressed in months, then ratePerPeriod must be expressed as a monthly rate.

nPer

Integer that specifies the total number of payment periods in the annuity. You must provide this value in the same units of measure as ratePerPeriod. For instance, if ratePerPeriod is expressed as a monthly rate, then numberPayPeriods must be expressed in months.

pmt

Double numeric expression that specifies the amount of each payment. You must provide this value in the same units of measure as ratePerPeriod. For instance, if ratePerPeriod is expressed in months, then eachPmt must be expressed as a monthly payment.

pvalue

Double numeric expression that specifies the value today of a future payment, or stream of payments. For example, if you put $23.94 in the bank today and leave it there for 15 years at an interest rate of 10% compounded annually, you end up with about $100. The present value of that $100 is approximately $23.94.

due

Integer that specifies whether each payment is made at the beginning (1), or at the end (0) of each period. This value must be 0 or 1.

Returns

Double

Example

The following example assumes you deposit $10,000 in a savings account for your daughter when she is born. If the account pays 5.7% compounded daily, how much will she have for college in 18 years? The answer, $27,896.60, is assigned to the variable TotalValue:

TotalValue = Finance.fv(0.057/365, 18*365, 0, -10000, 1)

The following example is almost the same as the previous one. In this one, however, assume that the interest is compounded monthly instead of daily, and that you have decided to make an additional monthly deposit of $55 into the account. The future value assigned to TotalValue in this case is $48,575.82:

TotalValue = Finance.fv(0.057/12, 18*12, -55, -10000, 1)

See also

Finance.ipmt function

Finance.nper function

Finance.pmt function

Finance.ppmt function

Finance.pv function

Finance.rate function

Finance.ipmt

Returns the interest payment for a given period of an annuity, based on periodic, constant payments, and on an unvarying interest rate. An annuity is a series of cash payments, constant in value, made over a period of time. An annuity can be an investment, such as a monthly savings plan, or a loan, such as a home mortgage. Each payment consists of two components, principal and interest. iPmt returns the interest component of the payment.

The following rules apply:

*
*

Syntax

double ipmt( double rate, integer per, integer nPer, double pmt, double pvalue, double fvalue, integer due )

Parameters

rate

Double numeric expression that specifies the interest rate that accrues per period. You must provide this value in the same units of measure as numberPayPeriods. For example, if numberPayPeriods is expressed in months, then ratePerPeriod must be expressed as a monthly rate.

per

Integer that specifies the particular period for which you want to determine how much of the payment for that period represents interest. You must provide this value in the range 1 through numberPayPeriods.

nPer

Integer that specifies the total number of payment periods in the annuity. You must provide this value in the same units of measure ratePerPeriod For example, if ratePerPeriod is expressed as a monthly rate, then numberPayPeriods must be expressed in months.

pvalue

Double numeric expression that specifies the value today of a future payment or stream of payments. For example, if you put $23.94 in the bank today and leave it there for 15 years at an interest rate of 10% compounded annually, you end up with about $100. In this case, the present value of that $100 is approximately $23.94.

fvalue

Double numeric expression that specifies the cash balance you want after you have made your final payment. For example:

*
*

due

Integer that specifies whether each payment is made at the beginning (1) or at the end (0) of each period. This value must be 0 or 1.

Returns

Double.

Example

The following example assumes you are making monthly payments the first of each month on a loan of $20,000, over 36 months, at an APR of 11.5%. How much of your 5th payment represents interest? The answer, $171.83, is assigned to Interest5:

Interest5 = Finance.ipmt(.115/12, 5, 36, -20000, 0, 1)

See also

Finance.fv function

Finance.nper function

Finance.pmt function

Finance.ppmt function

Finance.pv function

Finance.rate function

Finance.irr

This function returns the internal rate of return for a series of periodic cash flows, payments, and receipts in an existing array. The internal rate of return is the interest rate for an investment consisting of payments and receipts that occur at regular intervals. The cash flow for each period does not need to be constant, as it does for an annuity.

IRR is closely related to the net present value function, NPV, because the rate of return calculated by IRR is the interest rate corresponding to a net present value of zero. IRR calculates by iteration. Starting with the value of <starting guess>, it repeats the calculation until the result is accurate to within 0.00001 percent. If it cannot determine a result after 20 iterations, the function fails.

The following rules apply:

*
*
*
*

The following tips can be useful:

*
*

Syntax

double irr( double[ ] cash, double intrate)

Parameters

cash

Array of double values that specify the name of an existing array of Doubles representing cash flow values. cashArray must contain at least one positive value, or receipt, and one negative value, or payment.

s

Double numeric expression that specifies the value you estimate internal rate of return will be. In most cases, this is 0.1, or 10 percent.

Returns

Double

Example

The following example assumes you have filled the array myArray with a series of cash flow values. The internal rate of return is assigned to the variable IRRValue:

IRRValue = Finance.irr( myArray, .1 )

See also

Finance.mirr function

Finance.npv function

Finance.rate function

Finance.mirr

This function returns the modified internal rate of return for a series of periodic cash flows, or payments and receipts, in an existing array. The modified internal rate of return is the internal rate of return (IRR) when payments and receipts are financed at different rates. MIRR takes into account both the cost of the investment, or the financeRate, and the interest rate received on the reinvestment of cash, or the reinvestmentRate.

The following rules apply:

*
*
*
*

Because MIRR uses the order of values within the array to interpret the order of payments and receipts, be sure to type payment and receipt values in the correct sequence.

Syntax

double mirr( double[ ] arptr, double frate, double rrate)

Parameters

arptr

Array of Doubles that specifies the name of an existing array of cash flow values. Array must contain at least one positive value, or receipt, and one negative value, or payment.

frate

Double numeric expression that specifies the interest rate paid as the cost of financing. Must be a decimal value that represents a percentage.

rrate

Double numeric expression that specifies the interest rate received on gains from cash reinvestment. Must be a decimal value that represents a percentage.

Returns

Double.

Example

The following example assumes you have filled the array myArray with a series of cash flow values. If the interest rate you pay for financing is 12%, and the rate your earn on income is 11.5%, what is the modified internal rate of return? The answer is assigned to the variable MIRRValue:

MIRRValue = Finance.mirr( myArray, 0.12, 0.115 )

See also

Finance.irr function

Finance.rate function

Finance.nper

Returns the number of periods for an annuity based on periodic, constant payments, and on an unvarying interest rate. An annuity is a series of cash payments, constant in value, made over a period of time. An annuity can be an investment, such as a monthly savings plan, or a loan, such as a home mortgage.

The following rules apply:

*
*

Syntax

double nper( double rate, double pmt, double pvalue, double fvalue, integer due )

Parameters

rate

Double numeric expression that specifies the interest rate that accrues per period. You must provide this value in the same units of measure as eachPmt. For instance, if eachPmt is expressed as a monthly payment, then ratePerPeriod must be expressed as the monthly interest rate.

pmt

Double numeric expression that specifies the amount of each payment. You must provide this value in the same units of measure as ratePerPeriod. For instance, if ratePerPeriod is expressed in months, then eachPmt must be expressed as a monthly payment.

pvalue

Double numeric expression that specifies the value today of a future payment or of a stream of payments. For example, if you put $23.94 in the bank today and leave it there for 15 years at an interest rate of 10% compounded annually, you will end up with about $100. In this case, the present value of that $100 is approximately $23.94.

fvalue

Double numeric expression that specifies the cash balance you want after you have made your final payment. For example:

*
*

due

Integerthat specifies whether each payment is made at the beginning (1), or at the end (0) of each period. This value must be 0 or 1.

Returns

Double.

Example

The following example assumes you are making monthly payments at the first of each month on a loan of $20,000, at an APR of 11.5%. If each payment is $653.26, how many payments will you have to make to finish paying off the loan? The answer, 36, is assigned to the variable NumPeriods.

NumPeriods = Finance.nper(.115/12, -653.26, 20000, 0, 1)

See also

Finance.fv function

Finance.ipmt function

Finance.pmt function

Finance.ppmt function

Finance.pv function

Finance.rate function

Finance.npv

This function returns the net present value of a varying series of periodic cash flows, both positive and negative, at a given interest rate. While PV determines the present value of a series of constant payments, NPV does the same for a series of varying payments. Net present value is the value in today's dollars of all future cash flows associated with an investment minus any initial cost. In other words, it is that lump sum of money that would return the same profit or loss as the series of cash flows in question, if the lump sum were deposited in a bank today and left untouched to accrue interest at the rate given by <rate> for the same period of time contemplated by the cash flow stream.

The following rules apply:

*
*
*
*
*
*

Because NPV uses the order of values within the array to interpret the order of payments and receipts, be sure to supply your payment and receipt values in the correct sequence.

Syntax

double npv( double rate, double[ ] arptr )

Parameters

rate

Double numeric expression that specifies the discount rate over the length of the period. You must express this value as a decimal.

arptr

Array of doubles that specifies the name of an existing array of cash flow values. Array must contain at least one positive value, receipt, and one negative value, payment.

Returns

Double.

Example

The following example assumes you have filled the array myArray with a series of cash flow values, and that the interest rate is 11%. What is the net present value? The answer is assigned to the variable NetPValue:

NetPValue = Finance.npv( .11, MyArray )

Finance.percent

This function computes the percentage of two numbers. This function handles the two key housekeeping tasks associated with computing percents: handling zero in the numerator and handling null values.

Syntax

double percent( double denom, double num, double valueIfZero )

Parameters

denom

Double. The denominator. The argument must contain a numeric value.

num

Double. The numerator. The argument must contain a numeric value. The value can be zero.

valueIfZero

Double. The percent value to return if the numerator is zero. The default is null.

Returns

The ratio of the two numbers expressed as a percentage. Returns 0 if the numerator is zero. Returns null if either of the two arguments are null.

Example

pct = Finance.percent( 20, 50 ) // returns 40
pct = Finance.percent( 20, 0 ) // returns 0

Finance.pmt

Returns the payment for an annuity, based on periodic, constant payments, and on an unvarying interest rate. An annuity is a series of cash payments, constant in value, made over a period of time. An annuity can be an investment, such as a monthly savings plan, or a loan, such as a home mortgage.

The following rules apply:

*
*

Syntax

double pmt( double rate, integer nPer, double pvalue, double fvalue, integer due )

Parameters

rate

Double numeric expression that specifies the interest rate that accrues per period. You must provide this value in the same units of measure as ratePerPeriod. For instance, if numberPayPeriods is expressed in months, then ratePerPeriod must be expressed as a monthly rate.

nPer

Integer that specifies the total number of payment periods in the annuity. You must provide this value in the same units of measure as ratePerPeriod. For instance, if ratePerPeriod is expressed as a monthly rate, then numberPayPeriods must be expressed in months.

pvalue

Double numeric expression that specifies the value in today's dollars of a future payment, or stream of payments. For example, if you put $23.94 in the bank today and leave it there for 15 years at an interest rate of 10% compounded annually, you end up with about $100. In this case, the present value of that $100 is approximately $23.94.

fvalue

Double numeric expression that specifies the cash balance you want after you have made your final payment. For example:

*
*

due

Integer that specifies whether each payment is made at the beginning (1), or at the end (0) of each period. This value must be a 0 or 1.

Returns

Double.

Example

The following example assumes you are making monthly payments the first of each month on a loan of $20,000, over 36 months, at an APR of 11.5%. How much will each of your payments be? The answer, $653.26, is assigned to PaymentAmt.

PaymentAmt = Finance.pmt(.115/12, 36, -20000, 0, 1)

See also

Finance.fv function

Finance.ipmt function

Finance.nper function

Finance.ppmt function

Finance.pv function

Finance.rate function

Finance.ppmt

Returns the principal payment for a given period of an annuity, based on periodic, constant payments, and on an unvarying interest rate. An annuity is a series of cash payments, constant in value, made over a period of time. An annuity can be an investment, such as a monthly savings plan, or a loan, such as a home mortgage. Each payment in an annuity consists of two components: principal and interest. ppmt returns the principal component of the payment.

The following rules apply:

*
*

Syntax

double ppmt( double rate, integer per, integer nPer, double pmt, double pvalue, double fvalue, integer due )

Parameters

rate

Double numeric expression that specifies the interest rate that accrues per period. You must provide this value in the same units of measure as nPer. For instance, if nPer is expressed in months, then rate must be expressed as a monthly rate.

per

Integerthat specifies the particular period for which you want to determine how much of the payment for that period represents interest. This value must be in the range 1 through nPer.

nPer

Integer that specifies the total number of payment periods in the annuity. You must provide this value in the same units of measure as rate. For instance, if rate is expressed as a monthly rate, then nPer must be expressed in months.

pvalue

Double numeric expression that specifies the value today of a future payment, or stream of payments. For example, if you put $23.94 in the bank today and leave it there for 15 years at an interest rate of 10% compounded annually, you end up with about $100. In this case, the present value of that $100 is approximately $23.94.

fvalue

Double numeric expression that specifies the cash balance you want after you have made your final payment. For example:

*
*

due

Integer that specifies whether each payment is made at the beginning (1), or at the end (0) of each period. This value must be a 0 or 1.

Returns

Double.

Example

The following example assumes you are making monthly payments at the first of each month on a loan of $20,000, over 36 months, at an APR of 11.5%. How much of your 5th payment represents principal? The answer, $481.43, is assigned to Principal5:

Principal5 = Finance.ppmt(.115/12, 5, 36, -20000, 0, 1)

See also

Finance.fv function

Finance.ipmt function

Finance.nper function

Finance.pmt function

Finance.pv function

Finance.rate function

Finance.pv

This function returns the present value of an annuity based on periodic, constant payments to be paid in the future, and on an unvarying interest rate. An annuity is a series of cash payments, constant in value, made over a period of time. An annuity can be an investment, such as a monthly savings plan, or a loan, such as a home mortgage. The present value is the value today of a future payment, or of a stream of payments structured as an annuity.

For example, if you put $23.94 in the bank today and leave it there for 15 years at an interest rate of 10% compounded annually, you end up with about $100. So, the present value of that $100 is approximately $23.94.

The following rules apply:

*
*

Syntax

double pv( double rate, integer nPer, double pmt, double fvalue, integer due)

Parameters

rate

Double numeric expression that specifies the interest rate that accrues per period. You must provide this value in the same units of measure as nPer. For instance, if nPer is expressed in months, then rate must be expressed as a monthly rate.

nPer

Integer that specifies the total number of payment periods in the annuity. You must provide this value in the same units of measure as rate. For instance, if rate is expressed as a monthly rate, then nPer must be expressed in months.

pmt

Double numeric expression that specifies the amount of each payment. You must provide this value in the same units of measure as rate. For instance, if rate is expressed in months, then pmt must be expressed as a monthly payment.

fvalue

Double. Specifies the cash balance you want after you have made your final payment. For example:

*
*

due

Integer that specifies whether each payment is made at the beginning or at the end of each period. This value must be a 1 for beginning of period, or 0 (zero) for end of period.

Returns

Double

Example

The following example assumes you are considering the purchase of a corporate bond with a $1000 face value. The bond pays an annual coupon of $100, matures in 15 years, and the next coupon is paid at the end of one year. The yield to maturity on similar bonds is 12.5%. What is a fair price for this bond, or in other words, what is its present value? The answer, $834.18, is assigned to the variable PresentValue:

PresentValue = Finance.pv(.125, 15, 100, 1000, 0)

The following examples assumes you have won the lottery. The jackpot is $10 million, which you receive in yearly installments of $500,000 per year for 20 years, beginning one year from today. If the interest rate is 9.5% compounded annually, how much is the lottery worth today? The answer, $4,406,191.06, is assigned to PresentValue:

PresentValue = Finance.pv(.095, 20, 50000,10000000, 0)

The following example assumes you want to save $11,000 over the course of 3 years. If the APR is 10.5% and you plan to save $325 monthly, and if you make your payments at the beginning of each month, how much would you need to start off with in your account to achieve your goal? The answer, $2,048.06, is assigned to StartValue. Note that eachPmt is expressed as a negative number because it represents cash paid out:

StartValue = Finance.pv(.105/12, 3*12, -325, 11000, 1)

See also

Finance.fv function

Finance.ipmt function

Finance.nper function

Finance.pmt function

Finance.ppmt function

Finance.rate function

Finance.rate

This function returns the interest rate per period for an annuity. An annuity is a series of cash payments, constant in value, made over a period of time. An annuity can be an investment, such as a monthly savings plan, or a loan, such as a home mortgage.

Rate calculates the interest rate on an annuity iteratively. Starting with the value of startingGuess, it repeats the calculation until the result is accurate to within 0.00001 percent. If it cannot determine a result after 20 iterations, the function fails.

The following rules apply:

*
*

The following tips can be helpful:

*
*

Syntax

double rate( integer nper, double pmt, double pvalue, double fvalue, integer due, double guess)

Parameters

nper

Integer that specifies the total number of payment periods in the annuity. You must provide this value in the same units of measure as pmt. For instance, if pmt is expressed as a monthly payment, then nper must be expressed in months.

pmt

Double numeric expression that specifies the amount of each payment. You must provide this value in the same units of measure as nper. For instance, if nper is expressed in months, then pmt must be expressed as a monthly payment.

pvalue

Double numeric expression that specifies the value today of a future payment, or of a stream of payments. For example, if you put $23.94 in the bank today and leave it there for 15 years at an interest rate of 10% compounded annually, you will end up with about $100. So in this case, the present value of that $100 is approximately $23.94.

fvalue

Double numeric expression that specifies the cash balance you want after you have made your final payment. For example:

*
*

due

Integer that specifies whether each payment is made at the beginning or at the end of each period. This value must be a 1 for beginning of period or 0 (zero) for end of period.

guess

Double numeric expression that specifies the value you estimate Rate will return. In most cases, this is 0.1, or 10 percent.

Returns

Double

Example

The following example assumes you have taken out a loan for $20,000, that you are paying off over the course of 3 years. If your payments are $653.26 per month, and you make them at the beginning of each month, what interest rate (APR) are you paying? The answer, .115 or 11.5%, is assigned to the variable InterestRate. Note that the return value of Rate must be multiplied by 12 to yield an annual rate:

InterestRate = Finance.rate(3*12, -653.26, 20000, 0, 1, .1) * 12

See also

Finance.fv function

Finance.ipmt function

Finance.nper function

Finance.pmt function

Finance.ppmt function

Finance.pv function

Finance.sln

This function returns the straight-line depreciation of an asset for a single period. Straight-line depreciation is the oldest and simplest method of depreciating a fixed asset. It uses the book value of the asset less its estimated residual value, and allocates the difference equally to each period of the asset's life. Such procedures are used to arrive at a uniform annual depreciation expense that is charged against income before calculating income taxes. All arguments must be positive numbers.

Syntax

double sln( double cost, double salvage, double life )

Parameters

cost

Double numeric expression that specifies the initial cost of the asset.

salvage

Double numeric expression that specifies the value of the asset at the end of its useful life. You can type a salvage value to view the straight line depreciation offset by the salvage value, or return straight line depreciation without salvage value by supplying 0 (zero) in salvage value.

life

Double numeric expression that specifies the length of the useful life of the asset. You must provide this value in the same units of measure you want the function to return. For example, if you want SLN to determine the annual depreciation of the asset, assetLifespan must be given in years.

Returns

Double.

Example

The following example calculates the depreciation under the straight-line method for a new machine purchased at $1400, with a salvage value of $200, and a useful life estimated at 10 years. The result, $120 annually, is assigned to AnnualDeprec:

AnnualDeprec = Finance.sln(1400, 200, 10)

See also

Finance.ddb function

Finance.syd function

Finance.syd

This function returns sum-of-years'-digits depreciation of an asset for a specified period. Sum-of-years'-digits is an accelerated method of depreciation that results in higher depreciation charges and greater tax savings in the earlier years of the useful life of a fixed asset than are given by the straight-line depreciation method (SLN), where charges are uniform throughout.

The function bases depreciation on an inverted scale of the total of digits for the years of useful life. For instance, if the asset's useful life is 4 years, the digits 4, 3, 2, and 1 are added together to produce 10. SYD for the first year then becomes four tenths of the depreciable cost of the asset, or the cost less salvage value. The rate for the second year becomes three tenths, and so forth.

The following rules apply:

*
*

Syntax

double syd( double cost, double salvage, double life, integer period )

Parameters

cost

Double numeric expression that specifies the initial cost of the asset.

salvage

Double numeric expression that specifies the value of the asset at the end of its useful life.

life

Double numeric expression that specifies the length of the useful life of the asset. You must give this value in the same units of measure as period. For example, if period represents a month, then life must be expressed in months.

period

Integerthat specifies the period for which you want syd to calculate the depreciation. You must give this value in the same units of measure as life. For example, if life is expressed in months, then period must represent a period of one month.

Returns

Double

Example

The following example calculates the depreciation for the first year under the sum-of-years'-digits method for a new machine purchased at $1400, with a salvage value of $200, and a useful life estimated at 10 years. The result, $218.18, is assigned to Year1Deprec.

Year1Deprec = Finance.syd(1400, 200, 10, 1)

Note that:

*
*
*

The following example calculates the depreciation of the same asset for the second year of its useful life. The result, $196.36, is assigned to Year2Deprec.

Year2Deprec = Finance.syd(1400, 200, 10, 2)

Note that:

*
*
*

See also

Finance.ddb function

Finance.sln function


(c) Copyright Actuate Corporation 2013