looparray statement

looparray

ARRAY

SEP

ELEMENT

INDEX

The looparray statement is used at the beginning of a loop that loops over the elements of an array.

Parameters

This statement has four parameters:

array – is a formula that calculates the array to be scanned. This could be a field or variable, or a complex formula.

sep – is the array’s separator character.

element – is the name of a field or variable where each array element will be stored. If this field or variable does not already exist it will be created as a local variable.

index – is the name of a field or variable where the loop count will be stored. If this field or variable does not already exist it will be created as a local variable. (Note: This parameter is optional – if you don’t need to know the loop count, you can leave this parameter off.

Description

The looparray statement is used at the beginning of a loop that iterates over a text array (see Text Arrays and Loop more information on these topics). LoopArray loops are always terminated with an endloop statement.

When the loop starts, Panorama calculates the text array (based on the formula in the first parameter) and makes a copy of it. Each time through the loop Panorama extracts the next element from the array for processing. In other words, the first time through the loop the first element is processed, then the next time through the second element is processed, etc. The loop repeats until all of the array elements have been processed.

Here is how it works:

looparray myarray,myseparator,item
    ... do something with item 
endloop

Here is a simple example that loops once for each word in the Notes field.

looparray Notes," ",word
    message word
endloop

If the Notes field contains Now is the time, the message alert will appear four times, once for each word.

Adding a fourth parameter to the looparray statement allows you to access the number of times the loop has repeated so far.

looparray Notes," ",word,wordnumber
    message wordnumber+": "+word
endloop

Again, if the Notes field contains Now is the time, the message alert will appear four times, but this time each word will be numbered like this:

☞ 1: Now
☞ 2: is
☞ 3: the
☞ 4: time

It’s possible to create a loop that iterates over an array without using the looparray statement. For example, the previous example could be written like this:

local word,wordnumber
for wordnumber,1,arraysize(Notes," ")
    word=array(Notes,wordcount," ")
    message wordnumber+": "+word
    wordnumber=wordnumber+1
endloop

As you can see, writing the loop this way takes six lines instead of three. Using looparray is also significantly faster, especially with large arrays, because looparray uses special optimizations to reduce the amount of processing that needs to be done on the array each time through the loop. In some cases, it may even be worthwhile to rewrite old code to use looparray instead of other types of loop statements. However, unlike other Panorama structures, looparray is not compatible with recursion. If looparray is used inside a procedure and a recursive call to the same procedure is made within that loop, no more iterations of the loop will take place.

Note: If the text array is empty, the statements in the loop are skipped without even executing them once.

Error Messages

LOOP without ENDLOOP – Each FOR statement must be paired with a corresponding ENDLOOP, UNTIL or WHILE statement. If this error message appears, the necessary statement terminating the loop has not been included.

LOOPARRAY element parameter must be a field or variable – The ELEMENT parameter must be a field or variable, it cannot be a more complex calculation.

LOOPARRAY index parameter must be a field or variable – The INDEX parameter must be a field or variable, it cannot be a more complex calculation.

See Also

endloop -- is used at the end of a loop.
for -- is used at the beginning of a loop that loops a fixed number of times.
info("timelimitremaining") -- returns the amount of time available (in seconds) before a loop will time out.
loop -- is used at the beginning of a loop.
loopdataarray -- is used at the beginning of a loop that loops over the elements of a data array.
loopindex -- allows a procedure to determine how many times a loop has been repeated.
loopwhile -- is used at the beginning of a loop.
Preventing Endless Loops -- setting up a timeout limit to prevent endless loops.
repeatloopif -- decides whether to continue with a loop or to start over again from the top.
stoploopif -- decides whether to continue with a loop or to exit the loop immediately.
timelimit -- specifies the maximum time a procedure can continue to run after this statement.
until -- is used at the end of a loop, and can control how many times the loop is executed.
while -- is used at the end of a loop, and can control how many times the loop is executed.

History

Version	Status	Notes
10.0	New	New in this version