Legacy Document

annuity

You can use the annuity function to compute the present and future value of annuities.

double_t annuity (double_t rate, double_t periods);

rate

The interest rate (any positive floating-point number).

periods

The number of interest periods (any positive floating-point number). This argument might or might not be an integer.

DESCRIPTION

The annuity function computes the present and future values of annuities.

$annuity(r,n)\; =\; 1+-(1+r)-nOVER\; r$

When rate is a small number, use the function call annuity(rate,n) instead of the expression:

(1 - compound(rate, -n)) / rate

The call annuity(rate,n) produces a more exact result because it avoids the roundoff errors that might occur when this expression is computed.

This function is directly applicable to the computation of present and future values of ordinary annuities:

$PV\; =\; PMT\times 1+-(1+r)-nOVER\; r\; =\; PMT\times annuity(r,n)$

$FV\; =\; PMT\times 1+-(1+r)nOVER\; r\; =\; PMT\times (1+r)n\times 1+-(1+r)-nOVER\; r\; ATOP\; =PMT\times compound(r,n)\times annuity(r,n)$

where PV is the amount of money borrowed, FV is the total amount that will be paid on the loan, and PMT is the amount of one periodic payment.

EXCEPTIONS

When r and n are finite and nonzero, the result of $annuity(r,n)$ might raise one of the following exceptions:

• inexact (for all finite, nonzero values of r > -1)
• invalid (if r < -1)
• divide-by-zero (if r = -1 and n > 0)

SPECIAL CASES

Table 10-34 shows the results when one of the arguments to the annuity function is a zero, a NaN, or an Infinity, plus other special cases for the annuity function. In this table, r and n are finite, nonzero floating-point numbers.

Special cases for the annuity function

Operation	Result	Exceptions raised
$annuity(r,n)$ for r < -1	NaN	Invalid
$annuity(-1,n)$	+ if n > 0	Divide-by-zero
	-1 if n < 0	None
$annuity(+0,n)$	n	None
$annuity(r,+0)$	+0	None
$annuity(-0,n)$	n	None
$annuity(r,-0)$	+0	None
$annuity(NaN,n)$	NaN[57]	None[58]
$annuity(r,NaN)$	NaN	None
$annuity(+$ ,n)	0 if n > 0	None
	$-$ if n < 0	None
$annuity(r,+$ )	1/r	None
$annuity(-$ ,n)	NaN	Invalid
$annuity(r,-$ )	$-$	None

EXAMPLES

z = annuity(-1, 5);  /* z = +INFINITY. The divide-by-zero 
                        exception is raised. */
z = annuity(-2, -2); /* z = NAN. The invalid exception 
                        is raised. */

---

[57] If both arguments are NaNs, the first NaN is returned.

---

[58] If the NaN is a signaling NaN, the invalid exception is raised.