From f54a5b52e5d62c2394a1aa16e1176b829e54f152 Mon Sep 17 00:00:00 2001 From: Daniel Thayer Date: Tue, 12 Apr 2016 15:40:18 -0500 Subject: [PATCH] Improve documentation of the "for" statement --- doc/script-reference/statements.rst | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/doc/script-reference/statements.rst b/doc/script-reference/statements.rst index 47e82eb074..14e0cc3c32 100644 --- a/doc/script-reference/statements.rst +++ b/doc/script-reference/statements.rst @@ -315,30 +315,33 @@ Here are the statements that the Bro scripting language supports. .. bro:keyword:: for A "for" loop iterates over each element in a string, set, vector, or - table and executes a statement for each iteration. Currently, - modifying a container's membership while iterating over it may - result in undefined behavior, so avoid adding or removing elements - inside the loop. + table and executes a statement for each iteration (note that the order + in which the loop iterates over the elements in a set or a table is + nondeterministic). However, no loop iterations occur if the string, + set, vector, or table is empty. For each iteration of the loop, a loop variable will be assigned to an element if the expression evaluates to a string or set, or an index if the expression evaluates to a vector or table. Then the statement - is executed. However, the statement will not be executed if the expression - evaluates to an object with no elements. + is executed. If the expression is a table or a set with more than one index, then the loop variable must be specified as a comma-separated list of different loop variables (one for each index), enclosed in brackets. - A :bro:keyword:`break` statement can be used at any time to immediately - terminate the "for" loop, and a :bro:keyword:`next` statement can be - used to skip to the next loop iteration. - Note that the loop variable in a "for" statement is not allowed to be a global variable, and it does not need to be declared prior to the "for" statement. The type will be inferred from the elements of the expression. + Currently, modifying a container's membership while iterating over it may + result in undefined behavior, so do not add or remove elements + inside the loop. + + A :bro:keyword:`break` statement will immediately terminate the "for" + loop, and a :bro:keyword:`next` statement will skip to the next loop + iteration. + Example:: local myset = set(80/tcp, 81/tcp);