blob: 7e6060bd998f7cddff5c108ba76dd65ff14ff6a5 [file] [log] [blame]
MG Mud User88f12472016-06-24 23:31:02 +02001NAME
2 foreach
3
4SYNTAX
5 foreach (<var> : <expr>) <statement>;
6 foreach (<var>, <var2>, ... ,<varN> : <expr>) <statement>;
7
8 foreach (<var> : <expr1> .. <expr2>) <statement>;
9 foreach (<var>, <var2>, ... ,<varN> : <expr1>..<expr2> ) <statement>;
10
11 /* MudOS compatibility only - not for new code: */
12 foreach (<var> in <expr>) <statement>;
13 foreach (<var>, <var2>, ... ,<varN> in <expr>) <statement>;
14
15DESCRIPTION
16 The instruction evaluates its range specification - either a
17 simple <expr> which can yield an array, a struct, a string, a
18 mapping or an integer, or an integer range <expr1> through
19 <expr2> - and executes <statement> once for each value in the
20 range. The respective value is assigned to <var> right before
21 <statement> is executed.
22
23 A 'break' in the <statement> will terminate the loop. A
24 'continue' will continue the execution from the beginning of
25 the loop.
26
27 Every <var> specification can declare a new local variable, whose
28 scope is the whole foreach() statement.
29
30
31 The normal form (one <expr>):
32
33 <expr> is evaluated and has to yield an array, a struct, a
34 string or a mapping (or reference to the former), or an
35 integer.
36
37 If <expr> is a array, struct, or string, the values of
38 <expr> (in case of the string, the integer values of the
39 characters) are then assigned one by one in order of
40 occurence to <var>, and <statement> is executed for every
41 assignment.
42
43 If <expr> is a mapping, the keys are assigned one by one
44 to <var>, and the values for each key are assigned in
45 order to <var2>..<varN>. If there are more values than
46 variable, the extraneous values are ignored. Due to the
47 nature of mappings, a specific order of the keys can not
48 be guaranteed.
49
50 If <expr> evaluates to a reference to an array, mapping, or
51 string, the loop will assign references to the values into
52 the variables. This allows the loop body to change the contents
53 of the original data.
54
55 If <expr> evalutes to an integer, the loop will count up <var>
56 from 0 to <expr>-1, basically implementing a count loop.
57
58 If there are more variables than necessary, the unneeded ones
59 are not changed.
60
61
62 The ranged form (<expr1> .. <expr2>):
63
64 <expr1> and <expr2> are evaluated and must yield integers.
65 The loop will count up <var> from <expr1> to <expr2>, basically
66 implementing a counted loop.
67
68 If <expr1> is less than <expr2>, the loop will terminate at once.
69
70 If there are more than variable, the unneeded ones are not
71 changed.
72
73
74
75 WHAT HAPPENS IF <expr> IS CHANGED IN THE LOOP?
76
77 If <expr> yields an array or struct:
78 - assignments to single elements or to array ranges effect
79 the values assigned to the variable:
80 a = ({1, 2, 3})
81 foreach(x : a) { a[1..2] = ({4, 5}); write(x+" "); }
82 will write ("1 4 5 ").
83 - operations which implicitely copy the array or struct (this
84 includes range assignments which change the size) don't
85 have an effect on the loop.
86
87 If <expr> yields a mapping, the loop will run over the indices
88 the mapping had at the begin of the loop. Deleted indices are silently
89 skipped, new indices ignored, but changes of the data of existing
90 indices are acknowledged.
91
92 If <expr> yields a string, the value used at the start of the loop
93 remains.
94
95
96WARNING
97 The additional syntax forms using "in" as keyword are meant
98 to make re-engineering of MudOS objects easier. Do not use them
99 for newly written code, as they may not be available in future.
100
101
102EXAMPLES
103 // Call quit() in all interactive users
104 foreach(o : users()) o->quit();
105 foreach(object o : users()) o->quit();
106
107 // Print the contents of a mapping <m>
108 foreach(key, value : m) printf("%O:%O\n", key, value);
109 foreach(mixed key, mixed value : m) printf("%O:%O\n", key, value);
110
111 // Don't change the content of a string: s remains "FOOBAR".
112 s = "FOOBAR";
113 foreach(i : s) i += 32;
114
115 // Do change the content of a string: s will become "foobar".
116 s = "FOOBAR";
117 foreach(i : &s) i += 32;
118
119 // Count from 0 to 5
120 foreach(i : 6) printf("%d\n", i);
121
122 // Count from 1 to 6
123 foreach(i : 1 .. 6) printf("%d\n", i);
124
125HISTORY
126 LDMud 3.3.44 introduced the use of references, the loop over
127 an integer expression, and the loop over an integer range.
128 LDMud 3.3.266 added support for structs.
129
130
131SEE ALSO
132 for(LPC)