ClassesClasses | | Operators

Use the tabs on the upper right to switch to a different programming language.

Use the tabs on the upper right to switch to a different programming language.

Use the tabs on the upper right to switch to a different programming language.

forforForFor (Operator)

Name

forforForFor — Starts a loop block that is usually executed for a fixed number of iterations.

Signature

for( : : Start, End, Step : Index)

Herror for(const Hlong Start, const Hlong End, const Hlong Step, Hlong* Index)

Herror T_for(const Htuple Start, const Htuple End, const Htuple Step, Htuple* Index)

void For(const HTuple& Start, const HTuple& End, const HTuple& Step, HTuple* Index)

static void HOperatorSet.For(HTuple start, HTuple end, HTuple step, out HTuple index)

Description

Syntax in HDevelop: for Index := Start to End by Step

The forforForForFor statement starts a loop block that is usually executed for a fixed number of iterations. The forforForForFor block ends at the corresponding endforendforEndforEndforEndfor statement.

The number of iterations is defined by the StartStartStartStartstart value, the EndEndEndEndend value, and the increment value StepStepStepStepstep. All of these parameters can be initialized with expressions or variables instead of constant values. Please note that these loop parameters are evaluated only once, namely, immediately before the forforForForFor loop is entered. They are not re-evaluated after the loop cycles, i.e., any modifications of these variables within the loop body will have no influence on the number of iterations.

The passed loop parameters must be either of type integer or real. If all input parameters are of type integer, the IndexIndexIndexIndexindex variable will also be of type integer. In all other cases the IndexIndexIndexIndexindex variable will be of type real.

At the beginning of each iteration the loop variable IndexIndexIndexIndexindex is compared to the EndEndEndEndend parameter. If the increment value StepStepStepStepstep is positive, the forforForForFor loop is executed as long as the IndexIndexIndexIndexindex variable is less than or equal to the EndEndEndEndend parameter. If the increment value StepStepStepStepstep is negative, the forforForForFor loop is executed as long as the IndexIndexIndexIndexindex variable is greater than or equal to the EndEndEndEndend parameter.

Attention: If the increment value StepStepStepStepstep is set to a value of type real, it may happen that the last loop cycle is omitted owing to rounding errors in case the IndexIndexIndexIndexindex variable is expected to match the EndEndEndEndend value exactly in the last cycle. Hence, on some systems the following loop is not executed---as expected---for four times (with the IndexIndexIndexIndexindex variable set to 1.3, 1.4, 1.5, and 1.6), but only three times because after three additions the index variable is slightly greater than 1.6 due to rounding errors.

  I:=[]
  for Index := 1.3 to 1.6 by 0.1
    I := [I,Index]
  endfor

After the execution of the loop body, i.e., upon reaching the corresponding endforendforEndforEndforEndfor statement or a continuecontinueContinueContinueContinue statement, the increment value (as initialized at the beginning of the forforForForFor loop) is added to the current value of the loop counter IndexIndexIndexIndexindex. Then, the loop condition is re-evaluated as described above. Depending on the result the loop is either executed again or finished in which case execution continues with the first statement after the corresponding endforendforEndforEndforEndfor statement.

A breakbreakBreakBreakBreak statement within the loop---that is not covered by a more internal block---leaves the loop immediately and execution continues after the corresponding endforendforEndforEndforEndfor statement. In contrast, the continuecontinueContinueContinueContinue statement is used to ignore the rest of the loop body in the current cycle and continue execution with adapting the IndexIndexIndexIndexindex variable and re-evaluating the loop condition.

Attention: The behavior of the forforForForFor loop with respect to the IndexIndexIndexIndexindex variable has changed in HALCON 11: In previous versions changes to the IndexIndexIndexIndexindex variable within the loop body were ignored by the forforForForFor statement. Before evaluating the loop condition the IndexIndexIndexIndexindex variable would be reset to an internal counter that was calculated by:

  Index := Start + count * Step
where count was the number of already executed cycles.

Programs and procedures that were saved with a HALCON version prior to HALCON 11 are kept running unmodified by analyzing their forforForForFor loops while loading: If the IndexIndexIndexIndexindex variable of such a forforForForFor loop is modified within the loop body, the loop is set into a compatibility mode and marked accordingly. All forforForForFor loops that are marked in such a way are executed using the old semantics, i.e., the IndexIndexIndexIndexindex variable is reset to the internal counter before each loop cycle to keep the old behavior. In the listing the forforForForFor statement is marked by a warning triangle and the label __use_internal_index__ at the end of the line. In addition, in the operator window a warning is displayed. A check box allows to cancel the compatibility mode for the selected forforForForFor loop and perform it with the new semantics. Deleting the label __use_internal_index__ in the full text editor has the same effect. However, to keep the program behavior, the body of the forforForForFor loop must slightly be adapted by copying the IndexIndexIndexIndexindex variable at the begin of the loop body to a local variable. This local variable can be used and modified within the loop body at will.

In any case it is recommended to avoid modifying the IndexIndexIndexIndexindex variable of the forforForForFor loop within its body because the code becomes harder to debug and the code will not be compatible to HALCON versions prior to HALCON 11.

If the forforForForFor loop is stopped, e.g., by a stopstopStopStopStop statement or by pressing the Stop button, and if the PC is placed manually by the user, the forforForForFor loop is continued at the current iteration as long as the PC remains within the forforForForFor body or is set to the endforendforEndforEndforEndfor statement. If the PC is set on the forforForForFor statement (or before it) and executed again, the loop is reinitialized and restarts at the beginning.

Parameters

StartStartStartStartstart (input_control)  number HTupleHTupleHtuple (integer / real) (int / long / double) (Hlong / double) (Hlong / double)

Start value of the loop variable.

Default value: 1

EndEndEndEndend (input_control)  number HTupleHTupleHtuple (integer / real) (int / long / double) (Hlong / double) (Hlong / double)

End value of the loop variable.

Default value: 5

StepStepStepStepstep (input_control)  number HTupleHTupleHtuple (integer / real) (int / long / double) (Hlong / double) (Hlong / double)

Increment value of the loop variable.

Default value: 1

IndexIndexIndexIndexindex (output_control)  number HTupleHTupleHtuple (integer / real) (int / long / double) (Hlong / double) (Hlong / double)

Loop variable.

Example (HDevelop)

read_image (Image, 'fabrik')
threshold (Image, Region, 128, 255)
connection (Region, ConnectedRegions)
select_shape (ConnectedRegions, SelectedRegions, 'area', 'and', 150, 99999)
area_center (SelectedRegions, Area, Row, Column)
dev_close_window ()
dev_open_window (0, 0, 512, 512, 'black', WindowHandle)
dev_display (Image)
dev_display (SelectedRegions)
dev_set_color ('white')
for Index := 0 to |Area| - 1 by 1
  set_tposition (WindowHandle, Row[Index], Column[Index])
  write_string (WindowHandle, 'Area=' + Area[Index])
endfor

Result

If the values of the specified parameters are correct, forforForForFor (as an operator) returns 2 (H_MSG_TRUE). Otherwise, an exception is raised and an error code is returned.

Alternatives

whilewhileWhileWhileWhile, untiluntilUntilUntilUntil

See also

repeatrepeatRepeatRepeatRepeat, breakbreakBreakBreakBreak, continuecontinueContinueContinueContinue, endforendforEndforEndforEndfor

Module

Foundation


ClassesClasses | | Operators