( Latest Revision: Sunday March 23, 2014 )

FOURTH CS 1500 SOLO PROGRAM
Payout Term of an Annuity

Figuring Out How Long It Will Take For An Annuity To Run Out

NOTE:

No use of global variables is allowed in this program. In other words, all variables must be declared inside main or another function. (See pages 219-220 of Savitch.)

OBJECTIVE:

Practice top down design, the use of the data type double in mathematical functions, and appropriate formatting of the output of double values.

THE ASSIGNMENT:

Write a program that computes the payout term of an annuity.

The idea is that you start with a sum of money S in a special account that is managed by a big company. Every month the company credits a month's worth of interest to the account and then sends you a check for a monthly payment P that you use for your living expenses. The annual interest rate R and the monthly payment P are fixed constants. Unless P is so small that it is no more than the monthly interest, the money will eventually run out and there will be no more payments for you to collect.

Naturally, your questions are:
  1. Will the money run out? And if so,
  2. How much time do I have before the money is gone?
For example, if you start out with S = $257,823 in the account, your monthly payment is $1554.55, and the interest rate is 4.125 percent per annum, how many monthly payments can you expect to receive? This program will answer such questions.

PROGRAM INPUT AND OUTPUT:

The program must begin by writing information to explain the purpose of the program, and a general description of how to use the program.

The program must then prompt for and input the following three items (in the following order): the amout S of the initial principal, the amount P of the monthly payment, and the annual interest rate R. It must print individual prompts for each of the three quantities.

The principal S and payment P amounts must be entered as fixed-point decimals, denoting dollars and cents, without a dollar sign or commas, using the decimal point in the standard manner. For example: the user enters 1554.55 to mean 1554 dollars and 55 cents. The prompts you create for S and P must make these rules clear to the user of the program.

The interest rate must be entered as a fixed-point decimal number of percentage points. For example: the user enters 4.125 to mean an annual interest rate of 4.125%. The prompt you create for the interest rate must make this rule clear to the user of the program.

Make sure to write the program so that it inputs only
  1. the amount of the initial principal,
  2. the amount of the payment, and
  3. the interest rate.
in that order. When I test all the programs that class members turn in, I will want to automate the process, using scripts and files of input prepared in advance. It will be as if another program checks the class programs. That won't work unless you and I have this precise agreement on the form (and order) of the inputs to your program.

After the user enters S, P, and R, your program must check to see whether the money will run out. If so, the program must compute how many monthly payments there will be before the money runs out, and report that information to the user. If the money will never run out, the program should tell that to the user.

It is important that the user be sure that the program correctly understood his or her input, and it also helps the user to understand the results of the calculations when the program includes the inputs along with the results.

Therefore you must design the program to write the inputs in the same section of the output where it tells the user the results of its calculations. This is called "echoing" the input.

See the sample script to get the details of how an interaction with the program should appear in cases where the money runs out, and in cases where it does not run out.

The number of months (the term of the payout) can be calculated with a formula comparable to this one: 

              log(P) - log(P-rS) 
Months  =  ------------------------
                 log(1+r)
where r = R/1200, the decimal equivalent of the monthly interest rate, and where it is assumed that rS, which is the amount of the first interest payment, is less than the monthly payment P. (rS < P)

If rS >= P then the money will never run out. In that case P-rS is negative (or zero), and so log(P-rS) is undefined. The formula does not apply to that case, of course.

Also, of course the formula given above for Months has a format 'to be understood by humans,' but it is not expressed in correct C++ syntax. Part of your job as programmer is to create appropriate C++ statements to perform the necessary calculations.

This should be pretty easy, because the cmath library includes the log function (the natural logarithm), and the only other problems are to represent the multiplication, the division, and the other arithmetic operations with the appropriate C++ syntax.

After computing the number of months, the program must write a message to the screen like this: 
Here is your answer:
$257823.21
will run out after approximately
245
months, assuming that an annual interest of
4.125%
is earned, compounded monthly, and a monthly payment of
$1555.54
is withdrawn immediately after each interest payment.
Your program is required to format the numbers for output as shown above. The money must always appear in fixed-point notation, preceded by a dollar sign, and with exactly two digits displayed after the decimal point. The interest rate must be displayed in fixed-point notation, as a percentage, with exactly three digits displayed after the decimal point. The "magic formula" on page 56 of Savitch describes the formatting commands you will need. Keep in mind that it is the parameter to cout.precision() that controls the number of digits after the decimal point. Your program will need statements that change the precision from 2 to 3 and back to 2 again, in order to format all the numbers correctly.

Please study examples in the text book that show how to use the "magic formula" commands. They condition the output stream cout. Once cout has been conditioned by the commands, cout responds by imposing certain controls on how numbers are formatted after insertion into cout. If the end of cout is connected to your screen, then you always see the double or float numbers displayed with a certain format. The commands affect only the cout stream. They do not affect any aspect of how numbers are stored in memory. Therefore, you should place them in your program just before the cout statements that are supposed to write the formatted numbers. When someone wants to modify the way a program formats output, that's the logical place for him or her to look for the formatting directives that need changing.

There's an example program on page 75 that illustrates how the "magic formulas" should be placed just before the cout statements that rely on them. You can find other examples on page 221 and page 232.

DESIGN:

I suggest you design the program according to this structure chart. You can write the program by starting with a copy of this program shell. To finish the program using my design suggestion, fill in the definitions of all the functions in the program shell (starting with "main"). Pay close attention to the header comments for each sub-function. They explain what each sub-function is supposed to do. This assignment document should give you all the information you need to figure out what function main needs to do, which is mostly just to make calls to the sub-functions.

You do not have to use my design suggestion or program shell. However, I expect you to employ good principles of top-down design. I will withhold substantial credit if you do not create a program that uses functions appropriately. As my design suggestion illustrates, there are plenty of jobs for individual functions in this program. Your program must have at least four functions, including the main function.

DETAILS:

Put the following lines at the top of your program:: 

#include <cmath>
#include <iostream>

using namespace std ;
WHAT TO TURN IN:

You will be sending me two e-mail messages. Please follow these rules: Here is the list of things you have to turn in: Note that there are no spaces in the subject lines given. It is important that you do not insert any spaces. My e-mail address is:

john@ishi.csustan.edu

WHEN IS THIS ASSIGNMENT DUE?

Look for the due date in the class schedule. (It's at the top level of the class directory.)