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 — это предварительно выделенный вызывающей стороной (в стеке) массив C размером len. Во многих случаях вы можете поместить возвращаемые объекты в этот массив objects, а затем выполнить itemsPtr = objects. Но вы не обязаны; если ваша коллекция уже содержит объекты для возврата в виде массива C, она может вернуть их оттуда вместо этого.

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

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

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