MG Mud User | 88f1247 | 2016-06-24 23:31:02 +0200 | [diff] [blame^] | 1 | NAME |
| 2 | foreach |
| 3 | |
| 4 | SYNTAX |
| 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 | |
| 15 | DESCRIPTION |
| 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 | |
| 96 | WARNING |
| 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 | |
| 102 | EXAMPLES |
| 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 | |
| 125 | HISTORY |
| 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 | |
| 131 | SEE ALSO |
| 132 | for(LPC) |