1<html lang="en"> 2<head> 3<title>Fast enumeration protocol - Using the GNU Compiler Collection (GCC)</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Using the GNU Compiler Collection (GCC)"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Fast-enumeration.html#Fast-enumeration" title="Fast enumeration"> 9<link rel="prev" href="Fast-enumeration-details.html#Fast-enumeration-details" title="Fast enumeration details"> 10<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 11<!-- 12Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 131998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 142010 Free Software Foundation, Inc. 15 16Permission is granted to copy, distribute and/or modify this document 17under the terms of the GNU Free Documentation License, Version 1.3 or 18any later version published by the Free Software Foundation; with the 19Invariant Sections being ``Funding Free Software'', the Front-Cover 20Texts being (a) (see below), and with the Back-Cover Texts being (b) 21(see below). A copy of the license is included in the section entitled 22``GNU Free Documentation License''. 23 24(a) The FSF's Front-Cover Text is: 25 26 A GNU Manual 27 28(b) The FSF's Back-Cover Text is: 29 30 You have freedom to copy and modify this GNU Manual, like GNU 31 software. Copies published by the Free Software Foundation raise 32 funds for GNU development.--> 33<meta http-equiv="Content-Style-Type" content="text/css"> 34<style type="text/css"><!-- 35 pre.display { font-family:inherit } 36 pre.format { font-family:inherit } 37 pre.smalldisplay { font-family:inherit; font-size:smaller } 38 pre.smallformat { font-family:inherit; font-size:smaller } 39 pre.smallexample { font-size:smaller } 40 pre.smalllisp { font-size:smaller } 41 span.sc { font-variant:small-caps } 42 span.roman { font-family:serif; font-weight:normal; } 43 span.sansserif { font-family:sans-serif; font-weight:normal; } 44--></style> 45<link rel="stylesheet" type="text/css" href="../cs.css"> 46</head> 47<body> 48<div class="node"> 49<a name="Fast-enumeration-protocol"></a> 50<p> 51Previous: <a rel="previous" accesskey="p" href="Fast-enumeration-details.html#Fast-enumeration-details">Fast enumeration details</a>, 52Up: <a rel="up" accesskey="u" href="Fast-enumeration.html#Fast-enumeration">Fast enumeration</a> 53<hr> 54</div> 55 56<h4 class="subsection">8.9.4 Fast enumeration protocol</h4> 57 58<p>If you want your own collection object to be usable with fast 59enumeration, you need to have it implement the method 60 61<pre class="smallexample"> - (unsigned long) countByEnumeratingWithState: (NSFastEnumerationState *)state 62 objects: (id *)objects 63 count: (unsigned long)len; 64</pre> 65 <p>where <code>NSFastEnumerationState</code> must be defined in your code as follows: 66 67<pre class="smallexample"> typedef struct 68 { 69 unsigned long state; 70 id *itemsPtr; 71 unsigned long *mutationsPtr; 72 unsigned long extra[5]; 73 } NSFastEnumerationState; 74</pre> 75 <p>If no <code>NSFastEnumerationState</code> is defined in your code, the 76compiler will automatically replace <code>NSFastEnumerationState *</code> 77with <code>struct __objcFastEnumerationState *</code>, where that type is 78silently defined by the compiler in an identical way. This can be 79confusing and we recommend that you define 80<code>NSFastEnumerationState</code> (as shown above) instead. 81 82 <p>The method is called repeatedly during a fast enumeration to retrieve 83batches of objects. Each invocation of the method should retrieve the 84next batch of objects. 85 86 <p>The return value of the method is the number of objects in the current 87batch; this should not exceed <code>len</code>, which is the maximum size of 88a batch as requested by the caller. The batch itself is returned in 89the <code>itemsPtr</code> field of the <code>NSFastEnumerationState</code> struct. 90 91 <p>To help with returning the objects, the <code>objects</code> array is a C 92array preallocated by the caller (on the stack) of size <code>len</code>. 93In many cases you can put the objects you want to return in that 94<code>objects</code> array, then do <code>itemsPtr = objects</code>. But you 95don't have to; if your collection already has the objects to return in 96some form of C array, it could return them from there instead. 97 98 <p>The <code>state</code> and <code>extra</code> fields of the 99<code>NSFastEnumerationState</code> structure allows your collection object 100to keep track of the state of the enumeration. In a simple array 101implementation, <code>state</code> may keep track of the index of the last 102object that was returned, and <code>extra</code> may be unused. 103 104 <p>The <code>mutationsPtr</code> field of the <code>NSFastEnumerationState</code> is 105used to keep track of mutations. It should point to a number; before 106working on each object, the fast enumeration loop will check that this 107number has not changed. If it has, a mutation has happened and the 108fast enumeration will abort. So, <code>mutationsPtr</code> could be set to 109point to some sort of version number of your collection, which is 110increased by one every time there is a change (for example when an 111object is added or removed). Or, if you are content with less strict 112mutation checks, it could point to the number of objects in your 113collection or some other value that can be checked to perform an 114approximate check that the collection has not been mutated. 115 116 <p>Finally, note how we declared the <code>len</code> argument and the return 117value to be of type <code>unsigned long</code>. They could also be declared 118to be of type <code>unsigned int</code> and everything would still work. 119 120<!-- ========================================================================= --> 121 </body></html> 122 123