Q(uick)BASIC Function: IRR#

Quick View

IRR#

A function that returns the internal rate of return for a series of periodic cash flows (payments and receipts)

Worth knowing

Useful and cross-version information about the programming environments of QBasic and QuickBasic.

Syntax

IRR# (valuearray#(), valuecount%, guess#, status%)

Description/Parameter(s)

valuearray#()	An array of cash flow values.
valuecount%	The total number of items in the cash flow array.
guess#	A value you guess is close to the result of IRR#.
status%	A variable that returns a value indicating calculation failure or success: 0 = success; 1 = failure.

The argument valuearray#() must contain at least one negative value (a payment) and one positive value (a receipt).
The argument guess# is your guess for what IRR# will be.
IRR# is calculated by iteration. Starting with the value of guess#, IRR# cycles through the calculation until the result is accurate within .00001%. If after 20 tries it can't find a result that works, IRR# returns a status of 1 (failure).
In most cases you can assume guess# to be 0.1 (10%). However, if IRR# returns a status of 1 (failure), or if the result is not close to what you expected, try different values of guess#.
The argument status% can be any variable that returns information about the success or failure of the calculation. The value of status% will be 0 if the calculation was successful, and 1 if it was not.

Usage Notes

The internal rate of return is the interest rate received for an investment consisting of payments (negative values) and receipts (positive values) that occur at regular intervals.
IRR# uses the order of values within the array to interpret the order of payments and receipts. Be sure to enter your payment and receipt values in the correct sequence.
The cash flow for each period does not have to be even as it would be for an annuity.

Important

To use IRR# in the QBX environment, use the FINANCER.QLB Quick library. To use IRR# outside the QBX environment, link your program with the appropriate FINANCxx.LIB file. Depending on the compiler options you chose when you installed BASIC, one or more of the following files will be available:

Filename	Compiler options
FINANCER.LIB	80x87 or emulator math; DOS or OS/2 real mode
FINANCAR.LIB	Alternate math; DOS or OS/2 real mode
FINANCEP.LIB	80x87 or emulator math; OS/2 protected mode
FINANCAP.LIB	Alternate math; OS/2 protected mode

The FINANC.BI header file contains the necessary function declarations for IRR#.
For more information on using libraries, see "Creating and Using Quick Libraries" and "Using LINK and LIB" in the BASIC Programmer's Guide.

Example

This example uses the IRR# function to determine the internal rate of return for a series of periodic cash flows represented in an array of values. It then uses the NPV# function to determine the net present value for the same periodic cash flows used to determine the internal rate of return.
Note: To run this example you must use a Quick library that includes the procedures contained in one of the financial function library files. The following include file must also be present.

'$INCLUDE: 'FINANC.BI'
 
OPTION BASE 1
CONST DOLLARFORMAT$ = "$#,###.##"
CONST PERCENTFORMAT$ = "##.##"
DEFDBL A-Z
DIM Status  AS INTEGER, NumFlows  AS INTEGER
NumFlows% = 6
DIM Values(NumFlows%) AS DOUBLE
Guess = .1
 
'Read cash flows into Values# array.
FOR I = 1 TO NumFlows%
    READ Values#(I)
NEXT I
 
'Calculate the internal rate of return.
ReturnRate = IRR#(Values#(), NumFlows%, Guess, Status%)
 
'Examine Status% to determine success or failure of IRR.
IF Status% THEN
 
    'If unsuccessful, announce a problem.
    PRINT "There was an error in calculating the internal rate of return."
 
ELSE
 
    'Display the internal rate of return.
    PRINT "You're starting a printing business. You estimate that it will"
    PRINT "cost you $70,000.00 in start-up costs. Your net annual income "
    PRINT "for the next five years is expected to be $12,000, $15,000, "
    PRINT "$18,000, $21,000, and $26000, respectively."
    PRINT
    PRINT "The internal rate of return for these cash flow figures is";
    PRINT USING PERCENTFORMAT$; ReturnRate * 100;
    PRINT "%."
    PRINT
 
    'Calculate the net present value.
    NetPresentValue = NPV#(ReturnRate, Values#(), NumFlows%, Status%)
 
    IF Status% THEN
  PRINT "There was an error in calculating the net present value."
    ELSE
  PRINT "The net present value of the cash flows used to calculate"
  PRINT "the internal rate of return is effectively ";
  PRINT USING DOLLARFORMAT$; NetPresentValue;
  PRINT "."
    END IF
END IF
 
'Estimated cost of starting up a printing business (Negative cash flow).
DATA -70000
 
'Net income each year for 5 successive years (Positive cash flow).
DATA 12000,15000,18000,21000,26000