Xbasic

*FOR_EACH Function

Syntax

Result as C = *FOR_EACH(A tag, A each, C list [, L filter_expression ])

Arguments

tagAny Type

An arbitrary named placeholder used in the expression/command specified by Each to refer to each entry in List. Any type

eachAny Type

An expression or command that you want to execute on each entry in List. Any type

listCharacter

A CR-LF delimited list of entries on which you want to operate, or an array. Character

filter_expressionLogical

A filter expression that returns a .t. or .f. value.

Description

Executes the command specified by "each" on every entry in a CR-LF delimited "list". "Tag" refers to each entry in the "list".

Discussion

*FOR_EACH() is a very quick and efficient way of performing a command on every entry in a CR-LF delimited list of values, or in an array. It is an alternative to writing an Xbasic loop.

Result is a CR-LF delimited list of return values generated when the command/expression specified by Each is executed.

The *COUNTER() function can be used inside the *FOR_EACH() function to return the current count of the number of entries processed. See example below.

It is easiest to explain how this function works by example. Assume you have a CR-LF list of names:

Names = <<%str%
Smith,John
Jones,Jenny
Kelly,Kim
%str%

You would like to get a list of first names only by selecting the word after the comma:

First_names = *for_each(fullname, word(fullname, 2, ","),names)

? First_names
= John
Jenny
Kim

In this example, " fullname" is an arbitrary tag that is defined. The Each argument is: word(fullname, 2, ","). This function is performed on each entry in the input list of names. The tag fullname is used in the expression to refer to each entry in the input list.

If the tag had been specified as "foo" for example, then the expression would be:

First_names = *for_each(foo, word(foo, 2, ","),names)

? First_names
= John
Jenny
Kim

In this case, this same result can be achieved using the word_change() function:

First_names = word_change("$(,)+1", names, crlf() )

? First_names
= John
Jenny
Kim

However, the syntax for *FOR_EACH() is easier to understand since it uses standard Alpha Anywhere functions.

In other situations, such as the example below, where the *FOR_EACH() function is executing a command, WORD_CHANGE() cannot be used as an alternative.

Examples 

To delete all of the files with a .tmp extension in a folder.

file_list = filefind.get("c:\temp_FILEs\*.tmp", 0, "PN")
*for_each(filename, file.remove(filename), file_list)

Using counter() to create a numbered list.

dim list as c = <<%str%
apples
oranges
pears
%str%

? *for_each(item, *counter() + ") "+item, list)
= 1) apples
2) oranges
3) pears

Using an array as in the input to the function.

dim a[3] as P
a[1].fname = "fred"
a[1].lname = "smith"
a[1].city = "new york"
a[2].fname = "kelly"
a[2].lname = "jones"
a[2].city = "chicago"
a[3].fname = "aaron"
a[3].lname = "brown"
a[3].city = "london"

? *for_each(x,x.fname + " " + x.lname,a)
= fred smith
kelly jones
aaron brown

This example demonstrates using a filter expression. Only the entries where the filter expression returns true are returned:

dim txt as c=<<%str%
Smith,Jenny
Jones,Michelle
Amira,Stone
Krayzelberg,Lawson
%str%

?  *for_each(x,word(x,1,","),txt,x>"K")
= Smith
Krayzelberg

In the following example, we read data from the customer table into a property array, and then use *FOR_EACH() to dump out values from the array into a CR-LF string.

dim PropArray 100 as P  
PropArray.initialize_from_table("customer")

? *for_each(x,x.firstname +" " + x.lastname + " lives in " + x.bill_city + ", " + x.bill_state_region,PropArray) 
= Michael Graham lives in Natick, MA 
Aaron Peabody lives in Brockton, MA 
Janet Rebo lives in Keene, NH 
David Mesner lives in York Beach, ME 
Evan Feld lives in Acra, NY

See Also