1Iterator::Simple(3) User Contributed Perl Documentation Iterator::Simple(3)
2
3
4
6 Iterator::Simple - Simple iterator and utilities
7
9 use Iterator::Simple;
10
11 sub foo {
12 my $max = shift;
13 my $i = 0;
14 iterator {
15 return if $i > $max;
16 $i++;
17 }
18 }
19
20 my $iterator = foo(20); # yields 0,1,2, ..., 19, 20;
21 $iterator = imap { $_ + 2 } $iterator; # yields 2,3,4,5, ... ,20,21,22
22 $iterator = igrep { $_ % 2 } $iterator; # yields 3,5,7,9, ... ,17,19,21
23
24 # iterable object
25 $iterator = iter([qw(foo bar baz)]); # iterator from array ref
26 $iterator = iter(IO::File->new($filename)); # iterator from GLOB
27
28 # filters
29 $iterator = ichain($itr1, $itr2); # chain iterators;
30 $iterator = izip($itr1, $itr2); # zip iterators;
31 $iterator = ienumerate $iterator; # add index;
32
33 # general filter
34 $iterator = ifilter $iterator, sub {
35 return $_ if /^A/;
36 return;
37 }
38
39 # how to iterate
40 while(defined($_ = $iterator->())) {
41 print;
42 }
43
44 while(defined($_ = $iterator->next)) {
45 print;
46 }
47
48 while(<iterator>) {
49 print;
50 }
51
53 Iterator::Simple is yet another general-purpose iterator utilities.
54
55 Rather simple, but powerful and fast iterator.
56
58 Iterator::Simple doesn't export any functions by default. please import
59 them like:
60
61 use Iterator::Simple qw(iter list imap);
62
63 For all functions:
64
65 use Iterator::Simple qw(:all);
66
67 iterator { CODE }
68 Iterator constructor. CODE returns a value on each call, and if it
69 is exhausted, returns undef. Therefore, you cannot yields undefined
70 value as a meaning value. If you want, you could use Iterator
71 module which can do that.
72
73 Generally, you can implement iterator as a closure like:
74
75 use Iterator::Simple qw(iterator);
76
77 sub fibonacci {
78 my($s1, $s2, $max) = @_;
79
80 iterator {
81 my $rv;
82 ($rv, $s1, $s2) = ($s1, $s2, $s1 + $s2);
83 return if $rv > $max;
84 return $rv;
85 }
86 }
87
88 my $iterator = fiboacci(1, 1, 1000);
89
90 You can iterate it in several ways:
91
92 · just call it
93
94 while(defined($_ = $iterator->())) {
95 print "$_\n";
96 }
97
98 · "next" method
99
100 while(defined($_ = $iterator->next)) {
101 print "$_\n";
102 }
103
104 · <> operator
105
106 while(<$iterator>) {
107 print "$_\n";
108 }
109
110 is_iterator($object)
111 If $object is an iterator created by Iterator::Simple, returns
112 true. False otherwise.
113
114 iter($object)
115 This function auto detects what $object is, and automatically turns
116 it into an iterator. Supported objects are:
117
118 · Iterator made with Iterator::Simple.
119
120 · Object that implements "__iter__" method.
121
122 · Object that overloads '<>' or has "next" method.
123
124 · Object that overloads '&{}'.(as iterator function.)
125
126 · Object that overloads '@{}'.(with "iarray()")
127
128 · ARRAY reference. ("iarray()")
129
130 · CODE reference. (as iterator function.)
131
132 · GLOB reference.
133
134 · nothing ("iter()".) (empty iterator.)
135
136 If it fails to convert, runtime error.
137
138 is_iterable($object)
139 return true if $object can be converted with "iter($object)"
140
141 list($object)
142 This function converts $object into single array referece.
143
144 · ARRAY reference.
145
146 · GLOB reference.
147
148 · Iterator made with Iterator::Simple.
149
150 · Object that overloads '@{}' operator.
151
152 · Object that implements '__iter__' method.
153
154 · Object that overloads '<>' operator or has "next" method.
155
156 · nothing (i.e. list() returns []);
157
158 If it fails to convert, runtime error.
159
160 Note that after "list($iterator)", that iterator is not usable any
161 more.
162
163 imap { CODE } $iterable
164 This is the iterator version of "map". Returns an iterator which
165 yields the value from source iterator modified by CODE.
166
167 igrep { CODE } $iterable
168 This is the iterator version of "grep". Returns an iterator which
169 yields the value from source iterator only when CODE returns true
170 value.
171
172 iflatten $iterable
173 When $iterable yields another iterator, iterate it first.
174
175 $subitr = iter([10, 11,12]);
176 $source = iter([ 1, 2, $subitr, 4]);
177
178 $flattened = iflatten $source;
179
180 # yields 1, 2, 10, 11, 12, 4.
181
182 ifilter $iterable, sub{ CODE }
183 This is the combination of imap, igrep, iflatten. it supports
184 modify (imap) , skip (igrep), and inflate (iflatten). but it should
185 be faster than combination of them.
186
187 For example:
188
189 $combination = iflatten
190 imap { $_ eq 'baz' ? iter(['whoa', 'who']) : ":$_:" }
191 igrep { $_ ne 'bar' }
192 iter [ 'foo', 'bar', 'baz', 'fiz' ];
193
194 $itr = iter [ 'foo', 'bar', 'baz', 'fiz' ];
195 $filterd = ifilter $itr, sub {
196 return if $_ eq 'bar'; #skip
197 return iter(['whoa', 'who']) if $_ eq 'baz'; #inflate
198 return ":$_:"; # modify
199 };
200
201 Both of them will yields ':foo:', 'whoa', 'who', ':fiz:'.
202
203 ichain($iterable, $iterable2, ...)
204 This function returns an iterator which chains one or more
205 iterators. Iterates each iterables in order as is, until each
206 iterables are exhausted.
207
208 Example:
209
210 $itr1 = iter(['foo', 'bar', 'baz']);
211 $itr2 = iter(['hoge', 'hage']);
212
213 $chained = ichain($itr1, $itr2);
214
215 # yields 'foo', 'bar', 'baz', 'hoge', 'hage'.
216
217 ienumerate($iterable)
218 This function returns an iterator yields like:
219
220 $ary = iter(['foo', 'bar', 'baz', ... ]);
221
222 $iter = ienumerate $ary;
223
224 # yields [0, 'foo'], [1, 'bar'], [2, 'baz'], ...
225
226 izip($iterable, $iterable2, ...);
227 Accepts one or more iterables, returns an iterator like:
228
229 $animals = iter(['dogs', 'cats', 'pigs']);
230 $says = iter(['bowwow', 'mew', 'oink']);
231
232 $zipped = izip($animals, $says);
233
234 # yields ['dogs','bowwow'], ['cats','mew'], ['pigs', 'oink'].
235
236 Note that when one of source iterables is exhausted, zipped
237 iterator will be exhausted also.
238
239 islice($iterable, $start, $end, $step)
240 Same as islice of itertools in Python. If $end is undef or negative
241 value, it iterates source until it is exhausted. $step defaults to
242 1. 0 or negative step value is prohibited.
243
244 $iter = iter([0,1,2,3,4,5,6,7,8,9,10,11,12]);
245
246 $sliced = islice($iter, 3, 13, 2);
247
248 # yields 3, 5, 7, 9, 11.
249
250 ihead($count, $iterable)
251 islice($iterable, 0, $count, 1);
252
253 iskip($count, $iterable)
254 islice($iterable, $count, undef, 1);
255
256 iarray($arrayref);
257 Turns array reference into an iterator. Used in "iter($arrayref)".
258 You do not have to use this function directly, because
259 "iter($arrayref)" is sufficient.
260
262 Iterator used in Iterator::Simple is just a code reference blessed in
263 Iterator::Simple::Iterator. This class implements several method and
264 overloads some operators.
265
266 Itrator::Simple::Iterator->new($coderef)
267 Just bless $coderef in Iterator::Simple::Iterator and returns it.
268
269 $iterator->next
270 Call underlying code.
271
272 $iterator->__iter__
273 Returns self. You don't need to use this.
274
275 Overloaded operators.
276 · Read filehandle operator '<>'
277
278 Overloading '<>' makes this possible like:
279
280 print while <$iterator>;
281
282 · Pipe.. bit_OR? .. No, pipe!
283
284 $iterator | $coderef1 | $coderef2;
285
286 is equivalent to:
287
288 $iterator->filter($coderef1)->filter($coderef2);
289
290 is equivalent to:
291
292 ifilter(ifilter($iterator, $coderef1), $coderef2);
293
294 $iterator->filter($coderef)
295 $iterator->flatten()
296 $iterator->chain($another, ..)
297 $iterator->zip($another, ..)
298 $iterator->enumerate()
299 $iterator->slice($start, $end, $step)
300 $iterator->head($count)
301 $iterator->skip($count)
302 For example, $iterator->flatten() is equivalent to "iflatten
303 $iterator".
304
306 All iterator transformation function calls "iter" function on all
307 source iterables. So you can pass just array reference, GLOB ref, etc.
308
309 These examples completely do the right thing:
310
311 imap { $_ + 2 } [1, 2, 3, ... ];
312 ienumerate(\*STDIN);
313
314 # DBIx::Class::ResultSet has 'next' method.
315 ifilter $dbic_resultset, sub {CODE};
316
317 You can implement "__iter__" method on your objects in your
318 application. By doing that, your object will be Iterator::Simple
319 friendly :).
320
321 Note that "__iter__" method must return an iterator.
322
324 There is another iterator module in CPAN, named Iterator and
325 Iterator::Util made by Eric J. Roode that is great solution. Why yet
326 another iterator module? The answer is *Speed*. You use iterator
327 because you have too many data to manipulate in memory, therefore
328 iterator could be called thousands of times, speed is important.
329
330 For this simple example:
331
332 use Iterator::Util qw(iarray imap igrep);
333
334 for(1 .. 100) {
335 my $itr = igrep { $_ % 2 } imap { $_ + 2 } iarray([1 .. 1000]);
336 my @result;
337 while($itr->isnt_exhausted) {
338 push @result, $itr->value;
339 }
340 }
341
342 meanwhile:
343
344 use Iterator::Simple qw(iarray imap igrep);
345
346 for(1 .. 100) {
347 my $itr = igrep { $_ % 2 } imap { $_ + 2 } iarray([1 .. 1000]);
348 my @result;
349 while(defined($_ = $itr->())) {
350 push @result, $_;
351 }
352 }
353
354 Iterator::Simple is about ten times faster!
355
356 That is natural because Iterator::Simple iterator is just a code
357 reference, while Iterator.pm iterator is full featured class instance.
358 But Iterator::Simple is sufficient for usual demands.
359
360 One of most downside of Iterator::Simple is, you cannot yields undef
361 value as a meaning value, because Iterator::Simple thinks it as a
362 exhausted sign. If you need to do that, you have to yield something
363 which represents undef value.
364
365 Also, Iterator::Simple cannot determine iterator is exhausted until
366 next iteration, while Iterator.pm has 'is(nt)_exhausted' method which
367 is useful in some situation.
368
370 Rintaro Ishizaki <rintaro@cpan.org>
371
373 This library is free software; you can redistribute it and/or modify it
374 under the same terms as Perl itself.
375
377 · Iterator - Feature rich another iterator class.
378
379 · Iterator::Util - Utilities which uses Iterator. Many of filter
380 functions are from this module.
381
382
383
384perl v5.30.1 2020-01-30 Iterator::Simple(3)