projects / OpenSPARC-T2-SAM / blame
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Initial commit of OpenSPARC T2 architecture model.
[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / lib / itertools-functions.html
CommitLineData
920dae64
AT		 1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3<head>
4<link rel="STYLESHEET" href="lib.css" type='text/css' />
5<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
6<link rel='start' href='../index.html' title='Python Documentation Index' />
7<link rel="first" href="lib.html" title='Python Library Reference' />
8<link rel='contents' href='contents.html' title="Contents" />
9<link rel='index' href='genindex.html' title='Index' />
10<link rel='last' href='about.html' title='About this document...' />
11<link rel='help' href='about.html' title='About this document...' />
12<link rel="next" href="itertools-example.html" />
13<link rel="prev" href="module-itertools.html" />
14<link rel="parent" href="module-itertools.html" />
15<link rel="next" href="itertools-example.html" />
16<meta name='aesop' content='information' />
17<title>5.16.1 Itertool functions </title>
18</head>
19<body>
20<DIV CLASS="navigation">
21<div id='top-navigation-panel' xml:id='top-navigation-panel'>
22<table align="center" width="100%" cellpadding="0" cellspacing="2">
23<tr>
24<td class='online-navigation'><a rel="prev" title="5.16 itertools "
25 href="module-itertools.html"><img src='../icons/previous.png'
26 border='0' height='32' alt='Previous Page' width='32' /></A></td>
27<td class='online-navigation'><a rel="parent" title="5.16 itertools "
28 href="module-itertools.html"><img src='../icons/up.png'
29 border='0' height='32' alt='Up One Level' width='32' /></A></td>
30<td class='online-navigation'><a rel="next" title="5.16.2 Examples"
31 href="itertools-example.html"><img src='../icons/next.png'
32 border='0' height='32' alt='Next Page' width='32' /></A></td>
33<td align="center" width="100%">Python Library Reference</td>
34<td class='online-navigation'><a rel="contents" title="Table of Contents"
35 href="contents.html"><img src='../icons/contents.png'
36 border='0' height='32' alt='Contents' width='32' /></A></td>
37<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
38 border='0' height='32' alt='Module Index' width='32' /></a></td>
39<td class='online-navigation'><a rel="index" title="Index"
40 href="genindex.html"><img src='../icons/index.png'
41 border='0' height='32' alt='Index' width='32' /></A></td>
42</tr></table>
43<div class='online-navigation'>
44<b class="navlabel">Previous:</b>
45<a class="sectref" rel="prev" href="module-itertools.html">5.16 itertools </A>
46<b class="navlabel">Up:</b>
47<a class="sectref" rel="parent" href="module-itertools.html">5.16 itertools </A>
48<b class="navlabel">Next:</b>
49<a class="sectref" rel="next" href="itertools-example.html">5.16.2 Examples</A>
50</div>
51<hr /></div>
52</DIV>
53<!--End of Navigation Panel-->
54
55<H2><A NAME="SECTION0071610000000000000000"></A><A NAME="itertools-functions"></A>
56<BR>
575.16.1 Itertool functions
58</H2>
59
60<P>
61The following module functions all construct and return iterators.
62Some provide streams of infinite length, so they should only be accessed
63by functions or loops that truncate the stream.
64
65<P>
66<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
67 <td><nobr><b><tt id='l2h-1383' xml:id='l2h-1383' class="function">chain</tt></b>(</nobr></td>
68 <td><var>*iterables</var>)</td></tr></table></dt>
69<dd>
70 Make an iterator that returns elements from the first iterable until
71 it is exhausted, then proceeds to the next iterable, until all of the
72 iterables are exhausted. Used for treating consecutive sequences as
73 a single sequence. Equivalent to:
74
75<P>
76<div class="verbatim"><pre>
77 def chain(*iterables):
78 for it in iterables:
79 for element in it:
80 yield element
81</pre></div>
82</dl>
83
84<P>
85<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
86 <td><nobr><b><tt id='l2h-1384' xml:id='l2h-1384' class="function">count</tt></b>(</nobr></td>
87 <td><var></var><big>[</big><var>n</var><big>]</big><var></var>)</td></tr></table></dt>
88<dd>
89 Make an iterator that returns consecutive integers starting with <var>n</var>.
90 If not specified <var>n</var> defaults to zero.
91 Does not currently support python long integers. Often used as an
92 argument to <tt class="function">imap()</tt> to generate consecutive data points.
93 Also, used with <tt class="function">izip()</tt> to add sequence numbers. Equivalent to:
94
95<P>
96<div class="verbatim"><pre>
97 def count(n=0):
98 while True:
99 yield n
100 n += 1
101</pre></div>
102
103<P>
104Note, <tt class="function">count()</tt> does not check for overflow and will return
105 negative numbers after exceeding <code>sys.maxint</code>. This behavior
106 may change in the future.
107</dl>
108
109<P>
110<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
111 <td><nobr><b><tt id='l2h-1385' xml:id='l2h-1385' class="function">cycle</tt></b>(</nobr></td>
112 <td><var>iterable</var>)</td></tr></table></dt>
113<dd>
114 Make an iterator returning elements from the iterable and saving a
115 copy of each. When the iterable is exhausted, return elements from
116 the saved copy. Repeats indefinitely. Equivalent to:
117
118<P>
119<div class="verbatim"><pre>
120 def cycle(iterable):
121 saved = []
122 for element in iterable:
123 yield element
124 saved.append(element)
125 while saved:
126 for element in saved:
127 yield element
128</pre></div>
129
130<P>
131Note, this member of the toolkit may require significant
132 auxiliary storage (depending on the length of the iterable).
133</dl>
134
135<P>
136<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
137 <td><nobr><b><tt id='l2h-1386' xml:id='l2h-1386' class="function">dropwhile</tt></b>(</nobr></td>
138 <td><var>predicate, iterable</var>)</td></tr></table></dt>
139<dd>
140 Make an iterator that drops elements from the iterable as long as
141 the predicate is true; afterwards, returns every element. Note,
142 the iterator does not produce <em>any</em> output until the predicate
143 is true, so it may have a lengthy start-up time. Equivalent to:
144
145<P>
146<div class="verbatim"><pre>
147 def dropwhile(predicate, iterable):
148 iterable = iter(iterable)
149 for x in iterable:
150 if not predicate(x):
151 yield x
152 break
153 for x in iterable:
154 yield x
155</pre></div>
156</dl>
157
158<P>
159<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
160 <td><nobr><b><tt id='l2h-1387' xml:id='l2h-1387' class="function">groupby</tt></b>(</nobr></td>
161 <td><var>iterable</var><big>[</big><var>, key</var><big>]</big><var></var>)</td></tr></table></dt>
162<dd>
163 Make an iterator that returns consecutive keys and groups from the
164 <var>iterable</var>. The <var>key</var> is a function computing a key value for each
165 element. If not specified or is <code>None</code>, <var>key</var> defaults to an
166 identity function and returns the element unchanged. Generally, the
167 iterable needs to already be sorted on the same key function.
168
169<P>
170The returned group is itself an iterator that shares the underlying
171 iterable with <tt class="function">groupby()</tt>. Because the source is shared, when
172 the <tt class="function">groupby</tt> object is advanced, the previous group is no
173 longer visible. So, if that data is needed later, it should be stored
174 as a list:
175
176<P>
177<div class="verbatim"><pre>
178 groups = []
179 uniquekeys = []
180 for k, g in groupby(data, keyfunc):
181 groups.append(list(g)) # Store group iterator as a list
182 uniquekeys.append(k)
183</pre></div>
184
185<P>
186<tt class="function">groupby()</tt> is equivalent to:
187
188<P>
189<div class="verbatim"><pre>
190 class groupby(object):
191 def __init__(self, iterable, key=None):
192 if key is None:
193 key = lambda x: x
194 self.keyfunc = key
195 self.it = iter(iterable)
196 self.tgtkey = self.currkey = self.currvalue = xrange(0)
197 def __iter__(self):
198 return self
199 def next(self):
200 while self.currkey == self.tgtkey:
201 self.currvalue = self.it.next() # Exit on StopIteration
202 self.currkey = self.keyfunc(self.currvalue)
203 self.tgtkey = self.currkey
204 return (self.currkey, self._grouper(self.tgtkey))
205 def _grouper(self, tgtkey):
206 while self.currkey == tgtkey:
207 yield self.currvalue
208 self.currvalue = self.it.next() # Exit on StopIteration
209 self.currkey = self.keyfunc(self.currvalue)
210</pre></div>
211
212<span class="versionnote">New in version 2.4.</span>
213
214</dl>
215
216<P>
217<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
218 <td><nobr><b><tt id='l2h-1388' xml:id='l2h-1388' class="function">ifilter</tt></b>(</nobr></td>
219 <td><var>predicate, iterable</var>)</td></tr></table></dt>
220<dd>
221 Make an iterator that filters elements from iterable returning only
222 those for which the predicate is <code>True</code>.
223 If <var>predicate</var> is <code>None</code>, return the items that are true.
224 Equivalent to:
225
226<P>
227<div class="verbatim"><pre>
228 def ifilter(predicate, iterable):
229 if predicate is None:
230 predicate = bool
231 for x in iterable:
232 if predicate(x):
233 yield x
234</pre></div>
235</dl>
236
237<P>
238<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
239 <td><nobr><b><tt id='l2h-1389' xml:id='l2h-1389' class="function">ifilterfalse</tt></b>(</nobr></td>
240 <td><var>predicate, iterable</var>)</td></tr></table></dt>
241<dd>
242 Make an iterator that filters elements from iterable returning only
243 those for which the predicate is <code>False</code>.
244 If <var>predicate</var> is <code>None</code>, return the items that are false.
245 Equivalent to:
246
247<P>
248<div class="verbatim"><pre>
249 def ifilterfalse(predicate, iterable):
250 if predicate is None:
251 predicate = bool
252 for x in iterable:
253 if not predicate(x):
254 yield x
255</pre></div>
256</dl>
257
258<P>
259<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
260 <td><nobr><b><tt id='l2h-1390' xml:id='l2h-1390' class="function">imap</tt></b>(</nobr></td>
261 <td><var>function, *iterables</var>)</td></tr></table></dt>
262<dd>
263 Make an iterator that computes the function using arguments from
264 each of the iterables. If <var>function</var> is set to <code>None</code>, then
265 <tt class="function">imap()</tt> returns the arguments as a tuple. Like
266 <tt class="function">map()</tt> but stops when the shortest iterable is exhausted
267 instead of filling in <code>None</code> for shorter iterables. The reason
268 for the difference is that infinite iterator arguments are typically
269 an error for <tt class="function">map()</tt> (because the output is fully evaluated)
270 but represent a common and useful way of supplying arguments to
271 <tt class="function">imap()</tt>.
272 Equivalent to:
273
274<P>
275<div class="verbatim"><pre>
276 def imap(function, *iterables):
277 iterables = map(iter, iterables)
278 while True:
279 args = [i.next() for i in iterables]
280 if function is None:
281 yield tuple(args)
282 else:
283 yield function(*args)
284</pre></div>
285</dl>
286
287<P>
288<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
289 <td><nobr><b><tt id='l2h-1391' xml:id='l2h-1391' class="function">islice</tt></b>(</nobr></td>
290 <td><var>iterable, </var><big>[</big><var>start,</var><big>]</big><var> stop </var><big>[</big><var>, step</var><big>]</big><var></var>)</td></tr></table></dt>
291<dd>
292 Make an iterator that returns selected elements from the iterable.
293 If <var>start</var> is non-zero, then elements from the iterable are skipped
294 until start is reached. Afterward, elements are returned consecutively
295 unless <var>step</var> is set higher than one which results in items being
296 skipped. If <var>stop</var> is <code>None</code>, then iteration continues until
297 the iterator is exhausted, if at all; otherwise, it stops at the specified
298 position. Unlike regular slicing,
299 <tt class="function">islice()</tt> does not support negative values for <var>start</var>,
300 <var>stop</var>, or <var>step</var>. Can be used to extract related fields
301 from data where the internal structure has been flattened (for
302 example, a multi-line report may list a name field on every
303 third line). Equivalent to:
304
305<P>
306<div class="verbatim"><pre>
307 def islice(iterable, *args):
308 s = slice(*args)
309 it = iter(xrange(s.start or 0, s.stop or sys.maxint, s.step or 1))
310 nexti = it.next()
311 for i, element in enumerate(iterable):
312 if i == nexti:
313 yield element
314 nexti = it.next()
315</pre></div>
316</dl>
317
318<P>
319<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
320 <td><nobr><b><tt id='l2h-1392' xml:id='l2h-1392' class="function">izip</tt></b>(</nobr></td>
321 <td><var>*iterables</var>)</td></tr></table></dt>
322<dd>
323 Make an iterator that aggregates elements from each of the iterables.
324 Like <tt class="function">zip()</tt> except that it returns an iterator instead of
325 a list. Used for lock-step iteration over several iterables at a
326 time. Equivalent to:
327
328<P>
329<div class="verbatim"><pre>
330 def izip(*iterables):
331 iterables = map(iter, iterables)
332 while iterables:
333 result = [i.next() for i in iterables]
334 yield tuple(result)
335</pre></div>
336
337<P>
338
339<span class="versionnote">Changed in version 2.4:
340When no iterables are specified, returns a zero length
341 iterator instead of raising a TypeError exception.</span>
342
343</dl>
344
345<P>
346<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
347 <td><nobr><b><tt id='l2h-1393' xml:id='l2h-1393' class="function">repeat</tt></b>(</nobr></td>
348 <td><var>object</var><big>[</big><var>, times</var><big>]</big><var></var>)</td></tr></table></dt>
349<dd>
350 Make an iterator that returns <var>object</var> over and over again.
351 Runs indefinitely unless the <var>times</var> argument is specified.
352 Used as argument to <tt class="function">imap()</tt> for invariant parameters
353 to the called function. Also used with <tt class="function">izip()</tt> to create
354 an invariant part of a tuple record. Equivalent to:
355
356<P>
357<div class="verbatim"><pre>
358 def repeat(object, times=None):
359 if times is None:
360 while True:
361 yield object
362 else:
363 for i in xrange(times):
364 yield object
365</pre></div>
366</dl>
367
368<P>
369<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
370 <td><nobr><b><tt id='l2h-1394' xml:id='l2h-1394' class="function">starmap</tt></b>(</nobr></td>
371 <td><var>function, iterable</var>)</td></tr></table></dt>
372<dd>
373 Make an iterator that computes the function using arguments tuples
374 obtained from the iterable. Used instead of <tt class="function">imap()</tt> when
375 argument parameters are already grouped in tuples from a single iterable
376 (the data has been ``pre-zipped''). The difference between
377 <tt class="function">imap()</tt> and <tt class="function">starmap()</tt> parallels the distinction
378 between <code>function(a,b)</code> and <code>function(*c)</code>.
379 Equivalent to:
380
381<P>
382<div class="verbatim"><pre>
383 def starmap(function, iterable):
384 iterable = iter(iterable)
385 while True:
386 yield function(*iterable.next())
387</pre></div>
388</dl>
389
390<P>
391<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
392 <td><nobr><b><tt id='l2h-1395' xml:id='l2h-1395' class="function">takewhile</tt></b>(</nobr></td>
393 <td><var>predicate, iterable</var>)</td></tr></table></dt>
394<dd>
395 Make an iterator that returns elements from the iterable as long as
396 the predicate is true. Equivalent to:
397
398<P>
399<div class="verbatim"><pre>
400 def takewhile(predicate, iterable):
401 for x in iterable:
402 if predicate(x):
403 yield x
404 else:
405 break
406</pre></div>
407</dl>
408
409<P>
410<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
411 <td><nobr><b><tt id='l2h-1396' xml:id='l2h-1396' class="function">tee</tt></b>(</nobr></td>
412 <td><var>iterable</var><big>[</big><var>, n=2</var><big>]</big><var></var>)</td></tr></table></dt>
413<dd>
414 Return <var>n</var> independent iterators from a single iterable.
415 The case where <code>n==2</code> is equivalent to:
416
417<P>
418<div class="verbatim"><pre>
419 def tee(iterable):
420 def gen(next, data={}, cnt=[0]):
421 for i in count():
422 if i == cnt[0]:
423 item = data[i] = next()
424 cnt[0] += 1
425 else:
426 item = data.pop(i)
427 yield item
428 it = iter(iterable)
429 return (gen(it.next), gen(it.next))
430</pre></div>
431
432<P>
433Note, once <tt class="function">tee()</tt> has made a split, the original <var>iterable</var>
434 should not be used anywhere else; otherwise, the <var>iterable</var> could get
435 advanced without the tee objects being informed.
436
437<P>
438Note, this member of the toolkit may require significant auxiliary
439 storage (depending on how much temporary data needs to be stored).
440 In general, if one iterator is going to use most or all of the data before
441 the other iterator, it is faster to use <tt class="function">list()</tt> instead of
442 <tt class="function">tee()</tt>.
443
444<span class="versionnote">New in version 2.4.</span>
445
446</dl>
447
448<P>
449
450<DIV CLASS="navigation">
451<div class='online-navigation'>
452<p></p><hr />
453<table align="center" width="100%" cellpadding="0" cellspacing="2">
454<tr>
455<td class='online-navigation'><a rel="prev" title="5.16 itertools "
456 href="module-itertools.html"><img src='../icons/previous.png'
457 border='0' height='32' alt='Previous Page' width='32' /></A></td>
458<td class='online-navigation'><a rel="parent" title="5.16 itertools "
459 href="module-itertools.html"><img src='../icons/up.png'
460 border='0' height='32' alt='Up One Level' width='32' /></A></td>
461<td class='online-navigation'><a rel="next" title="5.16.2 Examples"
462 href="itertools-example.html"><img src='../icons/next.png'
463 border='0' height='32' alt='Next Page' width='32' /></A></td>
464<td align="center" width="100%">Python Library Reference</td>
465<td class='online-navigation'><a rel="contents" title="Table of Contents"
466 href="contents.html"><img src='../icons/contents.png'
467 border='0' height='32' alt='Contents' width='32' /></A></td>
468<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
469 border='0' height='32' alt='Module Index' width='32' /></a></td>
470<td class='online-navigation'><a rel="index" title="Index"
471 href="genindex.html"><img src='../icons/index.png'
472 border='0' height='32' alt='Index' width='32' /></A></td>
473</tr></table>
474<div class='online-navigation'>
475<b class="navlabel">Previous:</b>
476<a class="sectref" rel="prev" href="module-itertools.html">5.16 itertools </A>
477<b class="navlabel">Up:</b>
478<a class="sectref" rel="parent" href="module-itertools.html">5.16 itertools </A>
479<b class="navlabel">Next:</b>
480<a class="sectref" rel="next" href="itertools-example.html">5.16.2 Examples</A>
481</div>
482</div>
483<hr />
484<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
485</DIV>
486<!--End of Navigation Panel-->
487<ADDRESS>
488See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
489</ADDRESS>
490</BODY>
491</HTML>
Full OpenSPARC architecture tarball including simulator, hypervisor, and OBP.