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, и всё равно работало бы.

Предыдущий: Подробности быстрого перечисления, Вверх: Быстрое перечисление [Содержание][Индекс]