Iterating over a Range of Numeric Values

For numeric values (that is, Integer, Real, Decimal, Date, Time, and TimeStamp primitive types), you can specify the collection-expression of the foreach instruction in the following form when iterating over a range of numeric values.

foreach variable in initial-expression to final-expression
    [step increment-expression] [options]
    [where condition] do [:label]
    [foreach-instructions]
endforeach [label];

A sequence of instructions is executed once for each value of the loop control variable in a discrete range of numbers.

The variable, increment-expression, initial-expression, and final-expression values must all be numeric.

These parts of the foreach instruction syntax are listed in the following table.

Value Description
variable Contains the value in the range for each iteration of the loop. The variable must be one of the following single lowercase identifiers: the name of a local variable, the name of a parameter in the current method, or an unqualified property name (that is, a property defined in the same class as the method containing the foreach instruction).
initial‑expression Defines the initial value of the variable.
final-expression Defines the final value of the variable.
increment‑expression Defines the value to be added to variable at the end of each iteration of the loop.

The increment-expression value defaults to 1 but can be specified as a positive or negative numeric expression. The loop continues executing while the value of variable is one of the following.

variable <= final-expression (if increment-expression >= 0)

variable >= final-expression (if increment-expression < 0)

The variable can be of type Byte, but if the value of the final-expression plus the value of the increment-expression exceeds 255, an exception is raised, as shown in the following example.

vars
    byte: Byte;
begin
    foreach b in 1.Byte to 255.Byte step 1 do
    endforeach;
end;

For performance reasons, the initial, final, and increment expressions are evaluated once only, before entering the loop.

This form of the foreach instruction has the same meaning as the following code sequence, in which incrementExpression >= 0.

variable       := initialExpression;
finalValue     := finalExpression;
incrementValue := incrementExpression;
while variable <= finalValue do
    ...                                   // foreach statements
    variable := variable + incrementValue;
endwhile;

In this code sequence, finalValue and incrementValue are expressions of the same type as variable. If the value of incrementExpression is less than 0, the while instruction would be as follows.

while variable >= finalValue do

The following code sequence uses the reversed option.

foreach variable in expr1 to expr2 step expr3 reversed do

This code sequence using the reversed option is equivalent to the following code sequence.

foreach variable in expr2 to expr1 step -expr3 do

For examples of iterating over a range of numeric values, see "Examples of Numeric Value Iteration", in the following subsection.