1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
|
<div class="subsection-level-extent" id="Fast-enumeration-protocol"> <div class="nav-panel"> <p> Previous: <a href="fast-enumeration-details" accesskey="p" rel="prev">Fast Enumeration Details</a>, Up: <a href="fast-enumeration" accesskey="u" rel="up">Fast Enumeration</a> [<a href="index#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="indices" title="Index" rel="index">Index</a>]</p> </div> <h1 class="subsection" id="Fast-Enumeration-Protocol"><span>8.9.4 Fast Enumeration Protocol<a class="copiable-link" href="#Fast-Enumeration-Protocol"> ¶</a></span></h1> <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="example smallexample"> <pre class="example-preformatted" data-language="cpp">- (unsigned long) countByEnumeratingWithState: (NSFastEnumerationState *)state
objects: (id *)objects
count: (unsigned long)len;</pre>
</div> <p>where <code class="code">NSFastEnumerationState</code> must be defined in your code as follows: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">typedef struct
{
unsigned long state;
id *itemsPtr;
unsigned long *mutationsPtr;
unsigned long extra[5];
} NSFastEnumerationState;</pre>
</div> <p>If no <code class="code">NSFastEnumerationState</code> is defined in your code, the compiler will automatically replace <code class="code">NSFastEnumerationState *</code> with <code class="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 class="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 class="code">len</code>, which is the maximum size of a batch as requested by the caller. The batch itself is returned in the <code class="code">itemsPtr</code> field of the <code class="code">NSFastEnumerationState</code> struct. </p> <p>To help with returning the objects, the <code class="code">objects</code> array is a C array preallocated by the caller (on the stack) of size <code class="code">len</code>. In many cases you can put the objects you want to return in that <code class="code">objects</code> array, then do <code class="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 class="code">state</code> and <code class="code">extra</code> fields of the <code class="code">NSFastEnumerationState</code> structure allows your collection object to keep track of the state of the enumeration. In a simple array implementation, <code class="code">state</code> may keep track of the index of the last object that was returned, and <code class="code">extra</code> may be unused. </p> <p>The <code class="code">mutationsPtr</code> field of the <code class="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 class="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 class="code">len</code> argument and the return value to be of type <code class="code">unsigned long</code>. They could also be declared to be of type <code class="code">unsigned int</code> and everything would still work. </p> </div> <div class="nav-panel"> <p> Previous: <a href="fast-enumeration-details">Fast Enumeration Details</a>, Up: <a href="fast-enumeration">Fast Enumeration</a> [<a href="index#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="indices" title="Index" rel="index">Index</a>]</p> </div><div class="_attribution">
<p class="_attribution-p">
© Free Software Foundation<br>Licensed under the GNU Free Documentation License, Version 1.3.<br>
<a href="https://gcc.gnu.org/onlinedocs/gcc-13.1.0/gcc/Fast-enumeration-protocol.html" class="_attribution-link">https://gcc.gnu.org/onlinedocs/gcc-13.1.0/gcc/Fast-enumeration-protocol.html</a>
</p>
</div>
|
