As you remember from the foreach Loop chapter, both how foreach works and the types and numbers of loop variables that it supports depend on the kind of collection: For slices, foreach provides access to elements with or without a counter; for associative arrays, to values with or without keys; for number ranges, to the individual values. For library types, foreach behaves in a way that is specific to that type; e.g. for File, it provides the lines of a file.

It is possible to define the behavior of foreach for user-defined types as well. There are two methods of providing this support:

• Defining range member functions, which allows using the user-defined type with other range algorithms as well
• Defining one or more opApply member functions

Of the two methods, opApply has priority: If it is defined, the compiler uses opApply, otherwise it considers the range member functions. However, in most cases range member functions are sufficient, easier, and more useful.

在这两个方法中，opApply具有优先级：如果它被定义了，编译器将使用opApply，否则它将考虑range成员函数。然而，在大多数情况下，范围成员函数是足够的，更简单，更有用。

foreach need not be supported for every type. Iterating over an object makes sense only if that object defines the concept of a collection.

For example, it may not be clear what elements should foreach provide when iterating over a class that represents a student, so the class better not support foreach at all. On the other hand, a design may require that Student is a collection of grades and foreach may provide individual grades of the student.

It depends on the design of the program what types should provide this support and how.

73.1 foreach support by range member functions

We know that foreach is very similar to for, except that it is more useful and safer than for. Consider the following loop:

foreach (element; myObject) {
    // ... expressions ...
}

Behind the scenes, the compiler rewrites that foreach loop as a for loop, roughly an equivalent of the following one:

for ( ; /* while not done */; /* skip the front element */) {

    auto element = /* the front element */;

    // ... expressions ...
}

User-defined types that need to support foreach can provide three member functions that correspond to the three sections of the previous code: determining whether the loop is over, skipping the front element, and providing access to the front element.

Those three member functions must be named as empty, popFront, and front, respectively. The code that is generated by the compiler calls those functions:

这三个成员函数必须分别命名为empty、popFront和front。编译器生成的代码调用这些函数。

for ( ; !myObject.empty(); myObject.popFront()) {

    auto element = myObject.front();

    // ... expressions ...
}

These three functions must work according to the following expectations:

• .empty() must return true if the loop is over, false otherwise
• .popFront() must move to the next element (in other words, skip the front element)
• .front() must return the front element

• .empty()必须在循环结束时返回true，否则返回false
• .popFront()必须移动到下一个元素
• .front()必须返回下一个元素

Any type that defines those member functions can be used with foreach.

Example

Let's define a struct that produces numbers within a certain range. In order to be consistent with D's number ranges and slice indexes, let's have the last number be outside of the valid numbers. Under these requirements, the following struct would work exactly like D's number ranges:

struct NumberRange {
    int begin;
    int end;

    invariant() {
        // There is a bug if begin is greater than end
        assert(begin <= end);
    }

    bool empty() const {
        // The range is consumed when begin equals end
        return begin == end;
    }

    void popFront() {
        // Skipping the first element is achieved by
        // incrementing the beginning of the range
        ++begin;
    }

    int front() const {
        // The front element is the one at the beginning
        return begin;
    }
}

Note: The safety of that implementation depends solely on a single invariant block. Additional checks could be added to front and popFront to ensure that those functions are never called when the range is empty.

这个实现的安全性仅仅依赖于一个invariant块。额外的检查可以添加到front和popFront，以确保当范围为空时，这些函数永远不会被调用。

Objects of that struct can be used with foreach:

foreach (element; NumberRange(3, 7)) {
    write(element, ' ');
}

foreach uses those three functions behind the scenes and iterates until empty() returns true:

3 4 5 6 

std.range.retro to iterate in reverse

The std.range module contains many range algorithms. retro is one of those algorithms, which iterates a range in reverse order. It requires two additional range member functions:

• .popBack() must move to the element that is one before the end (skips the last element)
• .back() must return the last element

• .popBack()必须移动到末尾前1的元素（跳过最后一个元素）
• .back()必须返回最后一个元素

However, although not directly related to reverse iteration, for retro to consider those functions at all, there must be one more function defined:

然而，尽管与反向迭代没有直接关系，但retro要考虑这些功能，必须定义一个以上的功能。

• .save() must return a copy of this object

• .save()必须返回该对象的副本

We will learn more about these member functions later in the Ranges chapter.

These three additional member functions can trivially be defined for NumberRange:

struct NumberRange {
// ...

    void popBack() {
        // Skipping the last element is achieved by decrementing the end of the range.
        --end;
    }

    int back() const {
        // As the 'end' value is outside of the range, the last element is one less than that
        return end - 1;
    }

    NumberRange save() const {
        // Returning a copy of this struct object
        return this;
    }
}

Objects of this type can now be used with retro:

import std.range;

// ...

    foreach (element; NumberRange(3, 7).retro) {
        write(element, ' ');
    }

The output of the program is now in reverse:

6 5 4 3 

73.2 foreach support by opApply and opApplyReverse member functions

Everything that is said about opApply in this section is valid for opApplyReverse as well. opApplyReverse is for defining the behaviors of objects in the foreach_reverse loops.

这一节中关于opApply的所有内容也适用于opApplyReverse。opApplyReverse用于定义foreach_reverse循环中对象的行为。

The member functions above allow using objects as ranges. That method is more suitable when there is only one sensible way of iterating over a range. For example, it would be easy to provide access to individual students of a Students type.

On the other hand, sometimes it makes more sense to iterate over the same object in different ways. We know this from associative arrays where it is possible to access either only to the values or to both the keys and the values:

string[string] dictionary;    // from English to Turkish

// ...

foreach (inTurkish; dictionary) {
    // ... only values ...
}

foreach (inEnglish, inTurkish; dictionary) {
    // ... keys and values ...
}

opApply allows using user-defined types with foreach in various and sometimes more complex ways. Before learning how to define opApply, we must first understand how it is called automatically by foreach.

The program execution alternates between the expressions inside the foreach block and the expressions inside the opApply() function. First the opApply() member function gets called, and then opApply makes an explicit call to the foreach block. They alternate in that way until the loop eventually terminates. This process is based on a convention, which I will explain soon.

程序在foreach块中的表达式和opApply()函数中的表达式之间交替执行。首先调用opApply()成员函数，然后opApply显式调用foreach块。它们以这种方式交替，直到循环最终终止。

Let's first observe the structure of the foreach loop one more time:

// The loop that is written by the programmer:

foreach (/* loop variables */; myObject) {
    // ... expressions inside the foreach block ...
}

If there is an opApply() member function that matches the loop variables, then the foreach block becomes a delegate, which is then passed to opApply().

Accordingly, the loop above is converted to the following code behind the scenes. The curly brackets that define the body of the delegate are highlighted:

// The code that the compiler generates behind the scenes:

myObject.opApply(delegate int(/* loop variables */) {
    // ... expressions inside the foreach block ...
    return hasBeenTerminated;
});

In other words, the foreach loop is replaced by a delegate that is passed to opApply(). Before showing an example, here are the requirements and expectations of this convention that opApply() must observe:

1. The body of the foreach loop becomes the body of the delegate. opApply must call this delegate for each iteration.
2. The loop variables become the parameters of the delegate. opApply() must define these parameters as ref. (The variables may be defined without the ref keyword as well but doing that would prevent iterating over the elements by reference.)
3. The return type of the delegate is int. Accordingly, the compiler injects a return statement at the end of the delegate, which determines whether the loop has been terminated (by a break or a return statement): If the return value is zero, the iteration must continue, otherwise it must terminate.
4. The actual iteration happens inside opApply().
5. opApply() must return the same value that is returned by the delegate.

1. foreach循环的主体成为委托的主体。opApply必须在每次迭代中调用这个委托。
2. 循环变量成为委托的参数。opApply()必须将这些参数定义为ref。（变量也可以在没有ref关键字的情况下定义，但这样做会防止通过引用遍历元素）
3. 委托的返回类型为int。因此，编译器在委托的末尾注入一个return语句，该语句确定循环是否已经终止（通过break或return语句）：如果返回值为0，迭代必须继续，否则必须终止。
4. 实际的迭代发生在opApply()中。
5. opApply()必须返回与委托返回的相同的值。

The following is a definition of NumberRange that is implemented according to that convention:

struct NumberRange {
    int begin;
    int end;
                         //    (2)       (1)
    int opApply(int delegate(ref int) operations) const {
        int result = 0;

        for (int number = begin; number != end; ++number) { // (4)
            result = operations(number);  // (1)

            if (result) {
                break;                    // (3)
            }
        }

        return result;                    // (5)
    }
}

This definition of NumberRange can be used with foreach in exactly the same way as before:

foreach (element; NumberRange(3, 7)) {
    write(element, ' ');
}

The output is the same as the one produced by range member functions:

3 4 5 6 

Overloading opApply to iterate in different ways

It is possible to iterate over the same object in different ways by defining overloads of opApply() that take different types of delegates. The compiler calls the overload that matches the particular set of loop variables.

通过定义接受不同类型委托的opApply()重载，可以以不同的方式遍历同一对象。编译器调用匹配特定循环变量集的重载。

As an example, let's make it possible to iterate over NumberRange by two loop variables as well:

foreach (first, second; NumberRange(0, 15)) {
    writef("%s,%s ", first, second);
}

Note how it is similar to the way associative arrays are iterated over by both keys and values.

For this example, let's require that when a NumberRange object is iterated by two variables, it should provide two consecutive values and that it arbitrarily increases the values by 5. So, the loop above should produce the following output:

0,1 5,6 10,11 

This is achieved by an additional definition of opApply() that takes a delegate that takes two parameters. opApply() must call that delegate with two values:

int opApply(int delegate(ref int, ref int) dg) const {
    int result = 0;

    for (int i = begin; (i + 1) < end; i += 5) {
        int first = i;
        int second = i + 1;

        result = dg(first, second);

        if (result) {
            break;
        }
    }

    return result;
}

When there are two loop variables, this overload of opApply() gets called.

There may be as many overloads of opApply() as needed.

It is possible and sometimes necessary to give hints to the compiler on what overload to choose. This is done by specifying types of the loop variables explicitly.

For example, let's assume that there is a School type that supports iterating over the teachers and the students separately:

class School {
    int opApply(int delegate(ref Student) dg) const {
        // ...
    }

    int opApply(int delegate(ref Teacher) dg) const {
        // ...
    }
}

To indicate the desired overload, the loop variable must be specified:

foreach (Student student; school) {
    // ...
}

foreach (Teacher teacher; school) {
    // ...
}

73.3 Loop counter

The convenient loop counter of slices is not automatic for other types. Loop counter can be achieved for user-defined types in different ways depending on whether the foreach support is provided by range member functions or by opApply overloads.

对于其他类型的切片，方便的循环计数器不是自动的。对于用户定义的类型，循环计数器可以通过不同的方式实现，这取决于foreach支持是由range成员函数提供还是由opApply重载提供。

Loop counter with range functions

If foreach support is provided by range member functions, then a loop counter can be achieved simply by enumerate from the std.range module:

如果range成员函数提供foreach支持，那么可以简单地通过来自std.range模块的enumerate来实现循环计数器。

import std.range;

// ...

    foreach (i, element; NumberRange(42, 47).enumerate) {
        writefln("%s: %s", i, element);
    }

enumerate is a range that produces consecutive numbers starting by default from 0. enumerate pairs each number with the elements of the range that it is applied on. As a result, the numbers that enumerate generates and the elements of the actual range (NumberRange in this case) appear in lockstep as loop variables:

0: 42
1: 43
2: 44
3: 45
4: 46

Loop counter with opApply

On the other hand, if foreach support is provided by opApply(), then the loop counter must be defined as a separate parameter of the delegate, suitably as type size_t. Let's see this on a struct that represents a colored polygon.

另一方面，如果opApply()提供foreach支持，那么循环计数器必须定义为委托的单独参数，与类型size_t相匹配。

As we have already seen above, an opApply() that provides access to the points of this polygon can be implemented without a counter as in the following code:

import std.stdio;

enum Color { blue, green, red }

struct Point {
    int x;
    int y;
}

struct Polygon {
    Color color;
    Point[] points;

    int opApply(int delegate(ref const(Point)) dg) const {
        int result = 0;

        foreach (point; points) {
            result = dg(point);

            if (result) {
                break;
            }
        }

        return result;
    }
}

void main() {
    auto polygon = Polygon(Color.blue,
                           [ Point(0, 0), Point(1, 1) ] );

    foreach (point; polygon) {
        writeln(point);
    }
}

Note that opApply() itself is implemented by a foreach loop. As a result, the foreach inside main() ends up making indirect use of a foreach over the points member.

Also note that the type of the delegate parameter is ref const(Point). This means that this definition of opApply() does not allow modifying the Point elements of the polygon. In order to allow user code to modify the elements, both the opApply() function itself and the delegate parameter must be defined without the const specifier.

The output:

const(Point)(0, 0)
const(Point)(1, 1)

Naturally, trying to use this definition of Polygon with a loop counter would cause a compilation error:

foreach (i, point; polygon) {    // ← compilation ERROR
    writefln("%s: %s", i, point);
}

The compilation error:

Error: cannot uniquely infer foreach argument types

For that to work, another opApply() overload that supports a counter must be defined:

int opApply(int delegate(ref size_t, ref const(Point)) dg) const {
    int result = 0;

    foreach (i, point; points) {
        result = dg(i, point);

        if (result) {
            break;
        }
    }

    return result;
}

This time the foreach variables are matched to the new opApply() overload and the program prints the desired output:

0: const(Point)(0, 0)
1: const(Point)(1, 1)

Note that this implementation of opApply() takes advantage of the automatic counter over the points member. (Although the delegate variable is defined as ref size_t, the foreach loop inside main() cannot modify the counter variable over points).

When needed, the loop counter can be defined and incremented explicitly as well. For example, because the following opApply() is implemented by a while statement it must define a separate variable for the counter:

int opApply(int delegate(ref size_t, ref const(Point)) dg) const {
    int result = 0;
    bool isDone = false;

    size_t counter = 0;
    while (!isDone) {
        // ...

        result = dg(counter, nextElement);

        if (result) {
            break;
        }

        ++counter;
    }

    return result;
}

73.4 Warning: The collection must not mutate during the iteration

Regardless of whether the iteration support is provided by the range member functions or by opApply() functions, the collection itself must not mutate. New elements must not be added to the container and the existing elements must not be removed. (Mutating the existing elements is allowed.)

无论迭代支持是由range成员函数提供还是由opApply()函数提供，集合本身都不能发生变化。不能向容器添加新元素，也不能删除现有元素。

Doing otherwise is undefined behavior.