FOR/NEXT statements

Purpose

Define a loop of program statements whose execution is controlled by an automatically incrementing or decrementing counter.

Syntax

FOR Counter = start TO stop [STEP increment]

  .

  . {statements}

  .

NEXT [Counter [, [Counter]] ...]

Remarks

Counter is a numeric variable serving as the loop counter.

start is a numeric expression specifying the value initially assigned to Counter.

stop is a numeric expression giving the value that Counter must reach for the loop to be terminated.

increment is an optional numeric expression defining the amount by which Counter is incremented with each loop execution.  If not specified, increment defaults to 1.

Note that increment must be the same data type or in the same range as Counter.  For example:

FOR x?? = 50 TO 1 STEP -1

will fail because -1 is not within the range of an unsigned Word variable.

When a FOR statement is encountered, start is assigned to Counter, and Counter is tested to see if it is greater than (or, for negative increment, less than) stop.  If not, the statements within the FOR/NEXT loop are executed, increment is added to Counter, and Counter again tested against stop.  The statements in the loop are executed repeatedly until the test fails, at which time control passes to the statement immediately following the NEXT.

If increment is equal to the maximum value of a variable class (255 for a byte, 32767 for an Integer, 65535 for a Word, etc), the compiler will generate an error.  If step is zero, an infinite loop can be created.

When using floating-point values with FOR/NEXT, be sure to allow for round-off errors when mixing numbers of different precision.  Using constants or variables of the same type throughout will help solve this problem:

FOR n# = 1.0 TO 1.5 STEP 0.1

  x$ = STR$(n#)

NEXT n#

executes 5 times and returns:

1

1.10000000149012

1.20000000298023

1.30000000447035

1.40000000596046

while:

FOR n@ = 1.0@ TO 1.5@ STEP 0.1@

  x$ = STR$(n@)

NEXT n@

executes 6 times and returns:

1

1.1

1.2

1.3

1.4

1.5

FOR/NEXT loops run fastest when Counter is a Long-integer variable, and start and increment are Long-integer constants.  The value of Counter is available like any other variable within the loop.  It is wise to avoid explicitly modifying the value of Counter within the loop.  If you need to exit the loop prematurely, use an EXIT FOR statement.  Keep range considerations in mind.  For example, if Counter is an Integer variable, you may not use the maximum value for an Integer for stop, as Counter would be incremented outside the Integer range at the end of the loop.

The body of the loop is skipped altogether if the initial value of Counter is greater than stop (or, for a negative increment, if Counter is less than stop).

FOR/NEXT loops can be nested within other FOR/NEXT loops.  Be sure to use unique counter variables.  Note that PowerBASIC allows the Counter in the NEXT keyword simply as a comment, which is ignored. For example, the following will compile, even though the counter variables are "crossed":

FOR n = 1 TO 10

  FOR m = 1 TO 20

    .

    .

    .

  NEXT n

NEXT m

You can omit the counter variable in the NEXT statement altogether.  For example:

FOR n = 1 TO 10

  .

  .

  .

NEXT

A single NEXT statement can also be used with multiple nested FOR/NEXT loops.  The counter variables can be omitted but their use is recommended for clarity.  For example:

FOR n = 1 TO 10

  FOR m = 1 TO 20

    FOR q = 1 TO 100

      .

      .

      .

NEXT q,m,n ' Can also use: NEXT ,,

If a NEXT is encountered without a corresponding FOR (or vice versa), a compile-time error is generated.

In certain situations, previous versions of PowerBASIC optimized FOR/NEXT loops to count down instead of up for improved execution speed.  This optimization could cause the counter variable to contain a value which was not expected when execution of the loop was complete.  This optimization has been improved so that the counter variable value is always correct upon loop completion, even if EXIT FOR was used to force an early termination.

Although the compiler does not care about such things, it is considered good programming practice to indent the statements between FOR and NEXT by two or three spaces to set off the structure of the loop.

For additional performance, use a REGISTER variable for the loop counter variable.

Restrictions

A variable that has been passed by reference ( BYREF ) to a Sub, Function, Method, or Property may not be used as a Counter.  Use a local variable instead.

See also

#OPTIMIZE, #REGISTER, DO/LOOP, EXIT, ITERATE, WHILE/WEND, REGISTER