8.9.4 Протокол быстрой переборки ¶

Если вы хотите, чтобы ваш собственный объект коллекции можно было использовать с быстрой переборкой, вам нужно реализовать метод

- (unsigned long) countByEnumeratingWithState: (NSFastEnumerationState *)state
                                      objects: (id *)objects
                                        count: (unsigned long)len;

где NSFastEnumerationState должно быть определено в вашем коде следующим образом:

typedef struct
{
  unsigned long state;
  id            *itemsPtr;
  unsigned long *mutationsPtr;
  unsigned long extra[5];
} NSFastEnumerationState;

Если NSFastEnumerationState не определено в вашем коде, компилятор автоматически заменит NSFastEnumerationState * на struct __objcFastEnumerationState *, где этот тип неявно определяется компилятором аналогичным образом. Это может быть запутанно, и мы рекомендуем определить NSFastEnumerationState (как показано выше) вместо этого.

Метод вызывается многократно во время быстрой переборки для получения порций объектов. Каждый вызов метода должен возвращать следующую порцию объектов.

Значение возвращаемого методом является количеством объектов в текущей порции; это значение не должно превышать len, которое представляет собой максимальный размер порции, запрошенный вызывающей стороной. Сама порция возвращается в поле itemsPtr структуры NSFastEnumerationState.

Для помощи в возвращении объектов массив objects — это предварительно выделенный вызывающей стороной (в стеке) массив С с размером len. Во многих случаях вы можете поместить возвращаемые объекты в этот массив objects, а затем выполнить itemsPtr = objects. Но вам это не обязательно; если ваша коллекция уже содержит возвращаемые объекты в некотором виде массива С, она может возвращать их из него вместо этого.

Поля state и extra структуры NSFastEnumerationState позволяют вашему объекту коллекции отслеживать состояние переборки. В простой реализации массива state может отслеживать индекс последнего возвращенного объекта, а extra может оставаться неиспользованным.

Поле mutationsPtr структуры NSFastEnumerationState используется для отслеживания изменений. Оно должно указывать на число; перед обработкой каждого объекта цикл быстрой переборки проверит, не изменилось ли это число. Если изменилось, произошло изменение, и быстрая переборка прервётся. Таким образом, mutationsPtr может указывать на некоторую версию вашей коллекции, которая увеличивается на единицу каждый раз, когда происходит изменение (например, при добавлении или удалении объекта). Или, если вы удовлетворены менее строгими проверками изменений, оно может указывать на количество объектов в вашей коллекции или какое-то другое значение, которое можно проверить, чтобы приблизительно убедиться, что коллекция не была изменена.

Наконец, обратите внимание, как мы объявили аргумент len и значение возвращаемого метода как тип unsigned long. Их также можно объявить как тип unsigned int, и все равно всё будет работать.