Iterator::Simple(3pm)

1Iterator::Simple(3)   User Contributed Perl Documentation  Iterator::Simple(3)
2
3
4

NAME

6       Iterator::Simple - Simple iterator and utilities
7

SYNOPSIS

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

DESCRIPTION

53       Iterator::Simple is yet another general-purpose iterator utilities.
54
55       Rather simple, but powerful and fast iterator.
56

FUNCTIONS

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

OO INTERFACE

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

TIPS

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

Why Not Iterator.pm

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

AUTHOR

370       Rintaro Ishizaki <rintaro@cpan.org>
371

LICENSE

373       This library is free software; you can redistribute it and/or modify it
374       under the same terms as Perl itself.
375