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, и всё равно всё будет работать.

Предыдущий: Детали быстрой переборки, Следующий: Быстрая переборка [Содержание][Индекс]