8.2.1 Iterating Through Group Elements

The elements in a group with nested sub-structure can be accessed as though this structure were "flattened out". This can be done more efficiently using an iterator scheme as opposed to repeatedly calling the Leaf() function. The iterator for going through leaves is an object that remembers information about where it is in the group structure. This iterator is of type taLeafItr, and a variable should be declared of this type before beginning a for loop to iterate. The FirstEl and NextEl functions use this iterator to traverse through the elements of the group.

There is a macro which makes group traversal relatively painless. The following example illustrates its use:

  Unit* u;                      // a pointer to a unit object
  taLeafItr i;                  // the iterator object
  FOR_ITR_EL(Unit, u, layer->units., i) {
    u->DoSomething();
  }

The FOR_ITR_EL macro iterates though the leaves of a group. It accepts four arguments. The first is the type of object expected at the leaf level of the group. The second is a pointer to an object of that type. The third is group followed by its access method. In the example, the group is "layer->units", and the access method is the "." . If the group was instead a pointer to group called "mygroup" then the third argument would be "mygroup->". The fourth argument is the iterator object.

To iterate through all the leaf groups (groups which contain leaf elements) the FOR_ITR_GP macro may be used. Its first argument is the group type (not the leaf type). The second is a pointer to group of that type. The third is pointer group and its access method. And again, the fourth argument is the iterator object.