===========================================================================

Foreach is a loop, similar to "for" or "while". It's used like this:

foreach (string s in strs) {
  write(s+"\n");
}

In this example, strs is an array of strings. Starting at strs[0] and
going up, s is set to each element, then the body (write, in this case)
is run. This is useful because most of the time, with an array,
you just want to do something to each element. "For" loops are often used
for this, but they are harder to read and not quite as fast.

Note that foreach can work on any data type that you can make into
an array, and it can even work on mappings, like so:

foreach (string k, int v in somemapping) {
  write("key: "+k+", value: "+v+"\n");
}

The variables you define in the foreach (s, k, and v in the examples)
only exist inside the loop.

Now for a real life example:

string *all_stats = this_player()->query_all_stats();
foreach (string stat in all_stats) {
  message("info", stat + ": " + this_player()->query_stats(stat), this_player() );
}

This prints out each of your stats and their current values.

The foreach loop works on a copy of the data you send, so keep this in mind
if you need to add or delete from this data. Anything you add to the list will
NOT be looped over, and anything you delete WILL still be looped over.

Using a combination of foreach and filter, we can do almost everything
for which the "for" or "while" loops are often used, but faster
and easier to read.

The only time you really need to use the for loop is when you need to go X elements
into an array and then stop, or when you need to loop over two corresponding arrays
at the same time (which can be avoided by setting up your data better).
