<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1988-2018 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Funding Free Software", the Front-Cover
Texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below). A copy of the license is included in the section entitled
"GNU Free Documentation License".
(a) The FSF's Front-Cover Text is:
A GNU Manual
(b) The FSF's Back-Cover Text is:
You have freedom to copy and modify this GNU Manual, like GNU
software. Copies published by the Free Software Foundation raise
funds for GNU development. -->
<!-- Created by GNU Texinfo 6.4, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Fast enumeration protocol (Using the GNU Compiler Collection (GCC))</title>
<meta name="description" content="Fast enumeration protocol (Using the GNU Compiler Collection (GCC))">
<meta name="keywords" content="Fast enumeration protocol (Using the GNU Compiler Collection (GCC))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Option-Index.html#Option-Index" rel="index" title="Option Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Fast-enumeration.html#Fast-enumeration" rel="up" title="Fast enumeration">
<link href="Messaging-with-the-GNU-Objective_002dC-runtime.html#Messaging-with-the-GNU-Objective_002dC-runtime" rel="next" title="Messaging with the GNU Objective-C runtime">
<link href="Fast-enumeration-details.html#Fast-enumeration-details" rel="prev" title="Fast enumeration details">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body lang="en">
<a name="Fast-enumeration-protocol"></a>
<div class="header">
<p>
Previous: <a href="Fast-enumeration-details.html#Fast-enumeration-details" accesskey="p" rel="prev">Fast enumeration details</a>, Up: <a href="Fast-enumeration.html#Fast-enumeration" accesskey="u" rel="up">Fast enumeration</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Fast-Enumeration-Protocol"></a>
<h4 class="subsection">8.9.4 Fast Enumeration Protocol</h4>
<p>If you want your own collection object to be usable with fast
enumeration, you need to have it implement the method
</p>
<div class="smallexample">
<pre class="smallexample">- (unsigned long) countByEnumeratingWithState: (NSFastEnumerationState *)state
objects: (id *)objects
count: (unsigned long)len;
</pre></div>
<p>where <code>NSFastEnumerationState</code> must be defined in your code as follows:
</p>
<div class="smallexample">
<pre class="smallexample">typedef struct
{
unsigned long state;
id *itemsPtr;
unsigned long *mutationsPtr;
unsigned long extra[5];
} NSFastEnumerationState;
</pre></div>
<p>If no <code>NSFastEnumerationState</code> is defined in your code, the
compiler will automatically replace <code>NSFastEnumerationState *</code>
with <code>struct __objcFastEnumerationState *</code>, where that type is
silently defined by the compiler in an identical way. This can be
confusing and we recommend that you define
<code>NSFastEnumerationState</code> (as shown above) instead.
</p>
<p>The method is called repeatedly during a fast enumeration to retrieve
batches of objects. Each invocation of the method should retrieve the
next batch of objects.
</p>
<p>The return value of the method is the number of objects in the current
batch; this should not exceed <code>len</code>, which is the maximum size of
a batch as requested by the caller. The batch itself is returned in
the <code>itemsPtr</code> field of the <code>NSFastEnumerationState</code> struct.
</p>
<p>To help with returning the objects, the <code>objects</code> array is a C
array preallocated by the caller (on the stack) of size <code>len</code>.
In many cases you can put the objects you want to return in that
<code>objects</code> array, then do <code>itemsPtr = objects</code>. But you
don’t have to; if your collection already has the objects to return in
some form of C array, it could return them from there instead.
</p>
<p>The <code>state</code> and <code>extra</code> fields of the
<code>NSFastEnumerationState</code> structure allows your collection object
to keep track of the state of the enumeration. In a simple array
implementation, <code>state</code> may keep track of the index of the last
object that was returned, and <code>extra</code> may be unused.
</p>
<p>The <code>mutationsPtr</code> field of the <code>NSFastEnumerationState</code> is
used to keep track of mutations. It should point to a number; before
working on each object, the fast enumeration loop will check that this
number has not changed. If it has, a mutation has happened and the
fast enumeration will abort. So, <code>mutationsPtr</code> could be set to
point to some sort of version number of your collection, which is
increased by one every time there is a change (for example when an
object is added or removed). Or, if you are content with less strict
mutation checks, it could point to the number of objects in your
collection or some other value that can be checked to perform an
approximate check that the collection has not been mutated.
</p>
<p>Finally, note how we declared the <code>len</code> argument and the return
value to be of type <code>unsigned long</code>. They could also be declared
to be of type <code>unsigned int</code> and everything would still work.
</p>
<hr>
<div class="header">
<p>
Previous: <a href="Fast-enumeration-details.html#Fast-enumeration-details" accesskey="p" rel="prev">Fast enumeration details</a>, Up: <a href="Fast-enumeration.html#Fast-enumeration" accesskey="u" rel="up">Fast enumeration</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>