Since iOS 2.0, NSEnumerator has been available for enumerating elements in NSArray, NSDictionary, and NSSet objects. The NSEnumerator itself is an abstract class. It relies on some factory methods, (see the Factory Method pattern, Chapter 4) like objectEnumerator or keyEnumerator, to create and return a corresponding concrete enumerator object. Clients use a returned enumerator object to traverse elements in a collection, as illustrated in the following code snippet.

NSArray *anArray = ... ;
NSEnumerator *itemEnumerator = [anArray objectEnumerator];

NSString *item;
while (item = [itemEnumerator nextObject])
{
  // do something with the item
}

We assume the anArray is storing a collection of NSString objects. We process each item in the while loop with operations in NSString.

When the array's content is exhausted, the message call [itemEnumerator nextObject] will return nil and the enumeration process is complete.

With the introduction of iOS 4.0, there is another method to enumerate collection objects of the Cocoa Touch framework. It's called Block-Based Enumeration.

The Block-Based Enumeration was introduced in the iOS 4 for collection objects in the Cocoa Touch framework. Block is part is the language features of Objective-C (as of this writing, Apple is still trying to standardize block as an extension to the C language). A block is a typed function, which means a block is a function yet it's also a type. A defined block is a variable that can be passed around between method calls just like other variables in an object. At the same time, a block variable can be used as a function within a method. When a method is passed with a block as a parameter, the block can be used as a callback function just like a function pointer in a C program. So the idea of block is perfect for implementing internal iterators (enumerators). Clients do not need to create iterators manually anymore but just provide a defined block that fits the required signature of the target collection object. Then the block will be called upon in each traversal step. An algorithm defining the block can process a returned element each time when the block is called by the target collection object.

Block is a really cool feature in the Objective-C language. It allows us to define callback algorithms in line within the same message call. Without using Block, the traditional way to do "callback" in the Cocoa Touch framework is to use delegation (see the Adapter pattern, Chapter 8). You need to define a separate protocol (a target) for any object (an adapter) that will respond to a callback from a client. If that part of an application is complex enough to justify another adapter mechanism, then that's fine. Sometimes a block can provide a more elegant solution than enumerators.

Apple has introduced new methods for the Block-Based Enumeration in NSArray, NSDictionary, and NSSet objects in iOS 4. One of them is called enumerateObjectsUsingBlock:(void (^)(id obj, NSUInteger idx, BOOL *stop))block. You can define your own algorithm for the block in line with the message call, or predefine a block elsewhere, then pass it as a parameter in the message call. The following code snippet illustrates how it can be accomplished in code with an NSArray object.

NSArray *anArray=[NSArray arrayWithObjects:@"This", @"is", @"a", @"test", nil];
NSString *string=@"test";

[anArray enumerateObjectsUsingBlock:^(id obj, NSUInteger index, BOOL *stop)
{
  if([obj localizedCaseInsensitiveCompare:string] == NSOrderedSame)
  {
    // do something else with the returned obj
    *stop=YES;
  }
}
];

When one of the words in the anArray object is @"test", then set the pointer *stop=YES to tell the anArray object to stop the enumeration early. Except id obj and BOOL *stop parameters for the block, there is also the NSUInteger index parameter. The index parameter lets an algorithm in the block know the position of the current element, and it's very useful for concurrent enumeration like this. Without the parameter, the only way to access the index would be to use the indexOfObject: method, which is inefficient.

The Block-Based Enumeration in an NSSet object is very similar to the one in an NSArray object, except the block signature doesn't have the index parameter as part of the callback process. An NSSet object is a data structure that simulates a set data structure; each element in a set doesn't have an index to refer the element's position in the structure.

A big benefit of using an internal iterator of NSArray, NSDictionary, and NSSet is that an algorithm that processes their contents can be defined elsewhere by different developers. Unlike algorithms defined in a traditional for loop, well-defined blocks can be reusable. When blocks are getting very large, we can put them in separate implementation files without crowding other code. Even though block is a convenient way to put inline algorithms without defining separate delegation protocols to complicate things, you should consider using the Strategy pattern (Chapter 19) for blocks that are too big to maintain.

Objective-C 2.0 offers a type of enumeration called Fast Enumeration. It's the preferred method to do enumeration by Apple. It allows an enumeration of a collection object to be used as part of a for loop directly without using other enumerator objects, and it's more efficient than traditional index-based for loops. The syntax of Fast Enumeration is as follows.

NSArray * anArray = ... ;

for (NSString * item in anArray)
{
  // do something with the item
}

The enumeration loop now uses pointer arithmetic, which makes it more efficient than the standard methods of using NSEnumerator to achieve the same thing.

In order to utilize Fast Enumeration, a collection class needs to implement NSFastEnumeration protocol to provide necessary information regarding the underlying collection to the runtime. All collection classes as well as NSEnumerator in the Foundation framework support Fast Enumeration. So instead of enumerating each item from an NSEnumerator in a while loop until nextObject returns nil, you can use its Fast Enumeration version, like the following code snippet.

NSArray * anArray = ... ;
NSEnumerator * itemEnumerator = [anArray objectEnumerator];

for (NSString * item in itemEnumerator)
{
  // do something with the item
}

Even though you can use Fast Enumeration with a collection object as well as its enumerators, it would make more sense to fast enumerate a collection object directly if you need only a default traversal (mostly just by ascending order). NSEnumerator uses its nextObject method to implement the NSFastEnumeration protocol. Performance-wise, it might not be a whole lot better than just calling that method manually in a while loop. The for loop in Fast Enumeration seems cleaner than the traditional while loop with nextObject, though.

Implementing NSFastEnumeration is outside the scope of this book, so we will not discuss it here.

NSArray has an instance method called (void)makeObjectsPerformSelector:(SEL)aSelector, which allows clients to send a message to each item in the array so each of them executes a provided aSelector (given an item supports it). You can achieve the same thing with one of those enumeration methods mentioned previously to let each of them execute the same selector. The method enumerates the underlying collection internally and sends a performSelector: message to each item. The downside of this approach is if any one of the items in the collection doesn't respond to the selector, an exception will be thrown. So it's mostly good for some simple operations without much runtime checking.

The iterator (enumerator) that we have discussed so far is an external iterator that we have seen in the original description of the Iterator pattern. It needs a client to ask the collection object to return its iterator, and then loop through the iterator to visit each of its elements. The client each time sends a nextObject message to the iterator to retrieve an element in a loop until the collection is exhausted.

Without letting the client use any iterator (enumerator) directly, we can implement an internal iterator as another approach. The internal or passive iterator (usually the collection object itself) controls the iteration. You can implement an internal iterator by letting clients provide some sort of callback mechanism to the internal iterator so it can return the next element in a collection when it's ready.

Since the introduction of iOS SDK 4.0, we can use Objective-C blocks for application development. A block is a form of function type. Once it is defined, it can be reused anywhere in the application. Blocks are much more powerful than C function pointers in many ways. They are a natural choice for implementing internal iterators in Objective-C.

The class diagram in Figure 14-4 illustrates a possible way to implement an internal iterator for the Mark family.

Figure 14-4. A class diagram of a modified version of the MarkEnumerator and Stroke that implements an internal iterator with an introduction of MarkEnumerationBlock

We have added a new method to the Mark, enumerateMarksUsingBlock:markEnumerationBlock. A client will provide a defined block with a signature of ^(id <Mark> item, BOOL *stop) as a parameter. The block defines an algorithm that processes each Mark element returned from the internal iterator. If the algorithm wants to stop the enumeration at the current position, it can set the *stop variable to YES to do so. As discussed in the sidebar table, a composite object itself, instead of clients, maintains an internal iterator. The enumerateMarksUsingBlock: method monitors the enumeration process with a loop that runs through an instance of MarkEnumerator. Every element obtained from the enumerator will be passed to a provided block, so the algorithm in it will be able to process the element.

If you want to let clients use the internal iterator exclusively, then you can put the enumerator factory method that returns an instance of MarkEnumerator in an anonymous category, just like we did for the MarkEnumerator class in Listing 14-3. It totally depends on the design.

Code snippets in Listings 14-8 and 14-9 show changes in both the Mark protocol and the Stroke class.

@protocol Mark <NSObject>

@property (nonatomic, retain) UIColor *color;
@property (nonatomic, assign) CGFloat size;
@property (nonatomic, assign) CGPoint location;
@property (nonatomic, readonly) NSUInteger count;
@property (nonatomic, readonly) id <Mark> lastChild;

- (void) addMark:(id <Mark>) mark;
- (void) removeMark:(id <Mark>) mark;
- (id <Mark>) childMarkAtIndex:(NSUInteger) index;

- (NSEnumerator*) enumerator;

// for internal iterator implementation
- (void) enumerateMarksUsingBlock:(void (^)(id <Mark> item, BOOL *stop)) block;

@end

The implementation of the enumerateMarksUsingBlock:(void (^)(id <Mark> item, BOOL * stop)) block in Stroke is as follows.

- (void) enumerateMarksUsingBlock:(void (^)(id <Mark> item, BOOL *stop)) block
{
  BOOL stop = NO;

  NSEnumerator *enumerator = [self enumerator];

  for (id <Mark> mark in enumerator)
  {
    block (mark, &stop);
    if (stop)
      break;
  }
}