## 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) / assetLifespanDouble. Numeric expression that specifies the initial cost of the asset.

Double. Numeric expression that specifies the value of the asset at the end of its useful 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.

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.

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:

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.

ratePerPeriod, numberPayPeriods, and eachPmt must all be expressed in terms of the same units, such as weekly, monthly, or yearly.

You must express cash paid out, such as deposits to savings, using negative numbers, and cash received, such as dividend checks, using positive numbers.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.

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.

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.

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.

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.

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:

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:

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.

ratePerPeriod and numberPayPeriods must be expressed in terms of the same units, such as weekly, monthly, or yearly.

You must express cash paid out, such as deposits to savings, using negative numbers, and cash received, such as dividend checks, using positive numbers.double ipmt( double rate, integer per, integer nPer, double pmt, double pvalue, double fvalue, integer due )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.

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.

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.

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.

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

You set up a savings plan with a goal of having $75,000 in 18 years to pay for your child's education. For this plan, the future value is $75,000.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.

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:

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.

You must express cash paid out, such as deposits to savings, using negative numbers, and cash received, such as dividend checks, using positive numbers.

In cases where you have both a positive cash flow, or income, and a negative one, or payment, for the same period, use the net flow for that period.

If no cash flow or net cash flow occurs for a particular period, you must type 0 (zero) as the value for that period.The following tips can be useful:

Because IRR uses the order of values within the array to interpret the order of payments and receipts, be sure to type your payment and receipt values in the correct sequence.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.

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.

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:

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.

In cases where you have both a positive cash flow, or income, and a negative one, or payment, for the same period, use the net flow for that period.

If no cash flow or net cash flow occurs for a particular period, you must type 0 (zero) as the value for that period.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.

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.

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

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

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:

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.

ratePerPeriod and eachPmt must be expressed in terms of the same units, such as weekly, monthly, or yearly.

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.

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.

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.

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

You set up a savings plan with a goal of having $75,000 in 18 years to pay for your child's education. For this plan, the future value is $75,000.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.

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.

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 NPV investment begins one period before the date of the first cash flow value and ends with the last cash flow value in the array.

If your first cash flow occurs at the beginning of the first period, its value must be added to the value returned by NPV and must not be included in the cash flow values of cashArray.

In cases where you have both a positive cash flow, or income, and a negative one, or payment, for the same period, use the net flow for that period.

If no cash flow or net cash flow occurs for a particular period, you must supply 0 (zero) as the value for that period.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.

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

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.

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:

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

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

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

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

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.

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

ratePerPeriod and numberPayPeriods must be expressed in terms of the same units, such as weekly, monthly, or yearly.

You must express cash paid out, such as deposits to savings, using negative numbers, and cash received (such as dividend checks) using positive numbers.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.

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.

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.

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

You set up a savings plan with a goal of having $75,000 in 18 years to pay for your child's education. For this plan, the future value is $75,000.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.

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.

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.

ratePerPeriod and numberPayPeriods must be expressed in terms of the same units such as weeks, months or years.

double ppmt( double rate, integer per, integer nPer, double pmt, double pvalue, double fvalue, integer due )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.

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.

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.

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.

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.

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:

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.

ratePerPeriod and numberPayPeriods must be expressed in terms of the same units, weekly, monthly, or yearly.

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.

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.

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.

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

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.

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:

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:

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:

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.

numberPayPeriods, and eachPmt must be expressed in terms of the same units, such as weekly, monthly, or yearly.

You must express cash paid out, such as deposits to savings, using negative numbers and cash received, such as dividend checks, using positive numbers.The following tips can be helpful:

Because Rate uses the order of values within the array to interpret the order of payments and receipts, be sure to provide your payment and receipt values in the correct sequence.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.

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.

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.

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.

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

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:

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.

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

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.

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.

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:

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.

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

Double numeric expression that specifies the value of the asset at the end of its useful 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.

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.

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.

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.

Finance.ddb function

Finance.sln function

(c) Copyright Actuate Corporation 2012 |