help foreach
-------------------------------------------------------------------------------
Title
[P] foreach -- Loop over items
Syntax
foreach lname {in|of listtype} list {
commands referring to `lname'
}
Allowed are
foreach lname in any_list {
foreach lname of local lmacname {
foreach lname of global gmacname {
foreach lname of varlist varlist {
foreach lname of newlist newvarlist {
foreach lname of numlist numlist {
Braces must be specified with foreach, and
1. the open brace must appear on the same line as the foreach;
2. nothing may follow the open brace except, of course, comments;
the first command to be executed must appear on a new line;
3. the close brace must appear on a line by itself.
Description
foreach repeatedly sets local macro lname to each element of the list and
executes the commands enclosed in braces. The loop is executed zero or
more times; it is executed zero times if the list is null or empty. Also
see [P] forvalues, which is the fastest way to loop over consecutive
values, such as looping over numbers from 1 to k.
foreach lname in list { ... } allows a general list. Elements are
separated from each other by one or more blanks.
foreach lname of local list { ... } and foreach lname of global list {
... } obtain the list from the indicated place. This method of using
foreach produces the fastest executing code.
foreach lname of varlist list { ... }, foreach lname of newlist list {
... }, and foreach lname of numlist list { ... } are much like foreach
lname in list { ... }, except that the list is given the appropriate
interpretation. For instance,
foreach x in mpg weight-turn {
...
}
has two elements, mpg and weight-turn, so the loop will be executed
twice.
foreach x of varlist mpg weight-turn {
...
}
has four elements, mpg, weight, length, and turn, because list was given
the interpretation of a varlist.
foreach lname of varlist list { ... } gives list the interpretation of a
varlist. The list is expanded according to standard variable
abbreviation rules, and the existence of the variables is confirmed.
foreach lname of newlist list { ... } indicates that the list is to be
interpreted as new variable names; see varlist. A check is performed to
see that the named variables could be created, but they are not
automatically created.
foreach lname of numlist list { ... } indicates a number list and allows
standard number-list notation; see numlist.
The macro `ferest()' may be used in the body of the foreach loop to
obtain the unprocessed list elements. `ferest()' is only available
within the body of the loop; outside of that, `ferest()' evaluates to "".
The continue command provides a method of prematurely terminating a loop.
Examples
Loop over an arbitrary list. In this case, append a list of files to the
current dataset.
foreach file in this.dta that.dta theother.dta {
append using "`file'"
}
Quotes may be used to allow elements with blanks.
foreach name in "Annette Fett" "Ashley Poole" "Marsha Martinez" {
display length("`name'") " characters long -- `name'"
}
Loop over the elements of a local macro.
local grains "rice wheat corn rye barley oats"
foreach x of local grains {
display "`x'"
}
Loop over the elements of a global macro.
global money "Franc Dollar Lira Pound"
foreach y of global money {
display "`y'"
}
Loop over existing variables.
foreach var of varlist pri-rep t* {
quietly summarize `var'
summarize `var' if `var' > r(mean)
}
foreach lname of varlist varlist { ... } can be useful interactively but
is rarely used in programming contexts. Instead of coding,
syntax [varlist] ...
foreach var of varlist `varlist' {
...
}
it is more efficient to code
syntax [varlist] ...
foreach var of local varlist {
...
}
because `varlist' has already been expanded by the syntax command.
Loop over new variables.
foreach var of newlist z1-z20 {
gen `var' = runiform()
}
Loop over a numlist.
foreach num of numlist 1 4/8 13(2)21 103 {
display `num'
}
If you wish to loop over many equally spaced values, do not code, for
instance,
foreach x in 1/1000 {
...
}
Instead code
forvalues x = 1/1000 {
...
}
foreach must store the list of elements, whereas forvalues obtains the
elements one at a time by calculation; see [P] forvalues.
The macro `ferest()' allows access to the unprocessed elements of the
list.
foreach x in alpha "one two" three four {
display
display `" x is |`x'|"'
display `"ferest() is |`ferest()'|"'
}
Also see
Manual: [P] foreach
Help: [P] continue, [P] forvalues, [P] while; [P] if; [P] levelsof
