line |
stmt |
bran |
cond |
sub |
pod |
time |
code |
1
|
|
|
|
|
|
|
=for gpg |
2
|
|
|
|
|
|
|
-----BEGIN PGP SIGNED MESSAGE----- |
3
|
|
|
|
|
|
|
Hash: SHA1 |
4
|
|
|
|
|
|
|
|
5
|
|
|
|
|
|
|
=head1 NAME |
6
|
|
|
|
|
|
|
|
7
|
|
|
|
|
|
|
Iterator::Util - Essential utilities for the Iterator class. |
8
|
|
|
|
|
|
|
|
9
|
|
|
|
|
|
|
=head1 VERSION |
10
|
|
|
|
|
|
|
|
11
|
|
|
|
|
|
|
This documentation describes version 0.02 of Iterator::Util, August 23, 2005. |
12
|
|
|
|
|
|
|
|
13
|
|
|
|
|
|
|
=cut |
14
|
|
|
|
|
|
|
|
15
|
9
|
|
|
9
|
|
231067
|
use strict; |
|
9
|
|
|
|
|
23
|
|
|
9
|
|
|
|
|
349
|
|
16
|
9
|
|
|
9
|
|
52
|
use warnings; |
|
9
|
|
|
|
|
17
|
|
|
9
|
|
|
|
|
549
|
|
17
|
|
|
|
|
|
|
package Iterator::Util; |
18
|
|
|
|
|
|
|
our $VERSION = '0.02'; |
19
|
|
|
|
|
|
|
|
20
|
9
|
|
|
9
|
|
59
|
use base 'Exporter'; |
|
9
|
|
|
|
|
91
|
|
|
9
|
|
|
|
|
1197
|
|
21
|
9
|
|
|
9
|
|
47
|
use vars qw/@EXPORT @EXPORT_OK %EXPORT_TAGS/; |
|
9
|
|
|
|
|
17
|
|
|
9
|
|
|
|
|
883
|
|
22
|
|
|
|
|
|
|
|
23
|
|
|
|
|
|
|
@EXPORT = qw(imap igrep irange ilist iarray ihead iappend |
24
|
|
|
|
|
|
|
ipairwise iskip iskip_until imesh izip iuniq); |
25
|
|
|
|
|
|
|
|
26
|
|
|
|
|
|
|
@EXPORT_OK = (@EXPORT); |
27
|
|
|
|
|
|
|
|
28
|
9
|
|
|
9
|
|
9944
|
use Iterator; |
|
9
|
|
|
|
|
219077
|
|
|
9
|
|
|
|
|
11911
|
|
29
|
|
|
|
|
|
|
|
30
|
|
|
|
|
|
|
# Function name: imap |
31
|
|
|
|
|
|
|
# Synopsis: $iter = imap {code} $another_iterator; |
32
|
|
|
|
|
|
|
# Description: Transforms an iterator. |
33
|
|
|
|
|
|
|
# Created: 07/27/2005 by EJR |
34
|
|
|
|
|
|
|
# Parameters: code - Transformation code |
35
|
|
|
|
|
|
|
# $another_iterator - any other iterator. |
36
|
|
|
|
|
|
|
# Returns: Transformed iterator. |
37
|
|
|
|
|
|
|
# Exceptions: Iterator::X::Parameter_Error |
38
|
|
|
|
|
|
|
# Iterator::X::Am_Now_Exhausted |
39
|
|
|
|
|
|
|
sub imap (&$) |
40
|
|
|
|
|
|
|
{ |
41
|
12
|
|
|
12
|
1
|
198
|
my ($transformation, $iter) = @_; |
42
|
|
|
|
|
|
|
|
43
|
12
|
100
|
|
|
|
69
|
Iterator::X::Parameter_Error->throw(q{Argument to imap must be an Iterator object}) |
44
|
|
|
|
|
|
|
unless UNIVERSAL::isa($iter, 'Iterator'); |
45
|
|
|
|
|
|
|
|
46
|
|
|
|
|
|
|
return Iterator->new( sub |
47
|
|
|
|
|
|
|
{ |
48
|
42
|
100
|
|
42
|
|
2493
|
Iterator::is_done if ($iter->is_exhausted); |
49
|
|
|
|
|
|
|
|
50
|
40
|
|
|
|
|
248
|
local $_ = $iter->value (); |
51
|
40
|
|
|
|
|
2256
|
return $transformation-> (); |
52
|
11
|
|
|
|
|
61
|
}); |
53
|
|
|
|
|
|
|
} |
54
|
|
|
|
|
|
|
|
55
|
|
|
|
|
|
|
|
56
|
|
|
|
|
|
|
# Function name: igrep |
57
|
|
|
|
|
|
|
# Synopsis: $iter = igrep {code} $another_iterator; |
58
|
|
|
|
|
|
|
# Description: Filters an iterator. |
59
|
|
|
|
|
|
|
# Created: 07/27/2005 by EJR |
60
|
|
|
|
|
|
|
# Parameters: code - Filter condition. |
61
|
|
|
|
|
|
|
# $another_iterator - any other iterator. |
62
|
|
|
|
|
|
|
# Returns: Filtered iterator. |
63
|
|
|
|
|
|
|
# Exceptions: Iterator::X::Parameter_Error |
64
|
|
|
|
|
|
|
# Iterator::X::Am_Now_Exhausted |
65
|
|
|
|
|
|
|
sub igrep (&$) |
66
|
|
|
|
|
|
|
{ |
67
|
2
|
|
|
2
|
1
|
29
|
my ($test, $iter) = @_; |
68
|
|
|
|
|
|
|
|
69
|
2
|
50
|
|
|
|
11
|
Iterator::X::Parameter_Error->throw(q{Argument to imap must be an Iterator object}) |
70
|
|
|
|
|
|
|
unless UNIVERSAL::isa($iter, 'Iterator'); |
71
|
|
|
|
|
|
|
|
72
|
|
|
|
|
|
|
return Iterator->new(sub |
73
|
|
|
|
|
|
|
{ |
74
|
7
|
|
|
7
|
|
1250
|
while ($iter->isnt_exhausted ()) |
75
|
|
|
|
|
|
|
{ |
76
|
16
|
|
|
|
|
159
|
local $_ = $iter->value (); |
77
|
16
|
100
|
|
|
|
1557
|
return $_ if $test-> (); |
78
|
|
|
|
|
|
|
} |
79
|
|
|
|
|
|
|
|
80
|
2
|
|
|
|
|
26
|
Iterator::is_done(); |
81
|
2
|
|
|
|
|
12
|
}); |
82
|
|
|
|
|
|
|
} |
83
|
|
|
|
|
|
|
|
84
|
|
|
|
|
|
|
|
85
|
|
|
|
|
|
|
# Function name: irange |
86
|
|
|
|
|
|
|
# Synopsis: $iter = irange ($start, $end, $step); |
87
|
|
|
|
|
|
|
# Description: Generates an arithmetic sequence of numbers. |
88
|
|
|
|
|
|
|
# Created: 07/27/2005 by EJR |
89
|
|
|
|
|
|
|
# Parameters: $start - First value. |
90
|
|
|
|
|
|
|
# $end - Final value. (may be omitted) |
91
|
|
|
|
|
|
|
# $step - Increment value. (may be omitted) |
92
|
|
|
|
|
|
|
# Returns: Sequence iterator |
93
|
|
|
|
|
|
|
# Exceptions: Iterator::X::Am_Now_Exhausted |
94
|
|
|
|
|
|
|
# Notes: If the $end value is omitted, iterator is unbounded. |
95
|
|
|
|
|
|
|
# If $step is omitted, it defaults to 1. |
96
|
|
|
|
|
|
|
# $step may be negative (or even zero). |
97
|
|
|
|
|
|
|
sub irange |
98
|
|
|
|
|
|
|
{ |
99
|
38
|
|
|
38
|
1
|
42617
|
my ($from, $to, $step) = @_; |
100
|
38
|
100
|
|
|
|
114
|
$step = 1 unless defined $step; |
101
|
|
|
|
|
|
|
|
102
|
|
|
|
|
|
|
return Iterator->new (sub |
103
|
|
|
|
|
|
|
{ |
104
|
|
|
|
|
|
|
# Reached limit? |
105
|
285
|
100
|
66
|
285
|
|
15840
|
Iterator::is_done |
|
|
|
66
|
|
|
|
|
106
|
|
|
|
|
|
|
if (defined($to) |
107
|
|
|
|
|
|
|
&& ($step>0 && $from>$to || $step<0 && $from<$to) ); |
108
|
|
|
|
|
|
|
|
109
|
|
|
|
|
|
|
# This iteration's return value |
110
|
266
|
|
|
|
|
275
|
my $retval = $from; |
111
|
|
|
|
|
|
|
|
112
|
266
|
|
|
|
|
287
|
$from += $step; |
113
|
266
|
|
|
|
|
766
|
return $retval; |
114
|
38
|
|
|
|
|
297
|
}); |
115
|
|
|
|
|
|
|
} |
116
|
|
|
|
|
|
|
|
117
|
|
|
|
|
|
|
# Function name: ilist |
118
|
|
|
|
|
|
|
# Synopsis: $iter = ilist (@list); |
119
|
|
|
|
|
|
|
# Description: Creates an iterator from a list |
120
|
|
|
|
|
|
|
# Created: 07/28/2005 by EJR |
121
|
|
|
|
|
|
|
# Parameters: @list - list of values to iterate over |
122
|
|
|
|
|
|
|
# Returns: Array (list) iterator |
123
|
|
|
|
|
|
|
# Exceptions: Iterator::X::Am_Now_Exhausted |
124
|
|
|
|
|
|
|
# Notes: Makes an internal copy of the list. |
125
|
|
|
|
|
|
|
sub ilist |
126
|
|
|
|
|
|
|
{ |
127
|
11
|
|
|
11
|
1
|
5381
|
my @items = @_; |
128
|
11
|
|
|
|
|
20
|
my $index=0; |
129
|
|
|
|
|
|
|
return Iterator->new( sub |
130
|
|
|
|
|
|
|
{ |
131
|
43
|
100
|
|
43
|
|
1545
|
Iterator::is_done if ($index >= @items); |
132
|
34
|
|
|
|
|
154
|
return $items[$index++]; |
133
|
11
|
|
|
|
|
71
|
}); |
134
|
|
|
|
|
|
|
} |
135
|
|
|
|
|
|
|
|
136
|
|
|
|
|
|
|
# Function name: iarray |
137
|
|
|
|
|
|
|
# Synopsis: $iter = iarray ($a_ref); |
138
|
|
|
|
|
|
|
# Description: Creates an iterator from an array reference |
139
|
|
|
|
|
|
|
# Created: 07/28/2005 by EJR |
140
|
|
|
|
|
|
|
# Parameters: $a_ref - Reference to array to iterate over |
141
|
|
|
|
|
|
|
# Returns: Array iterator |
142
|
|
|
|
|
|
|
# Exceptions: Iterator::X::Parameter_Error |
143
|
|
|
|
|
|
|
# Iterator::X::Am_Now_Exhausted |
144
|
|
|
|
|
|
|
# Notes: Does not make an internal copy of the list. |
145
|
|
|
|
|
|
|
sub iarray ($) |
146
|
|
|
|
|
|
|
{ |
147
|
2
|
|
|
2
|
1
|
1890
|
my $items = shift; |
148
|
2
|
|
|
|
|
4
|
my $index=0; |
149
|
|
|
|
|
|
|
|
150
|
2
|
50
|
|
|
|
8
|
Iterator::X::Parameter_Error->throw-> |
151
|
|
|
|
|
|
|
(q{Argument to iarray must be an array reference}) |
152
|
|
|
|
|
|
|
if ref $items ne 'ARRAY'; |
153
|
|
|
|
|
|
|
|
154
|
|
|
|
|
|
|
return Iterator->new( sub |
155
|
|
|
|
|
|
|
{ |
156
|
11
|
100
|
|
11
|
|
1119
|
Iterator::is_done if $index >= @$items; |
157
|
9
|
|
|
|
|
34
|
return $items->[$index++]; |
158
|
2
|
|
|
|
|
21
|
}); |
159
|
|
|
|
|
|
|
} |
160
|
|
|
|
|
|
|
|
161
|
|
|
|
|
|
|
# Function name: ihead |
162
|
|
|
|
|
|
|
# Synopsis: $iter = ihead ($num, $some_other_iterator); |
163
|
|
|
|
|
|
|
# Synopsis: @valuse = ihead ($num, $iterator); |
164
|
|
|
|
|
|
|
# Description: Returns at most $num items from other iterator. |
165
|
|
|
|
|
|
|
# Created: 07/28/2005 by EJR |
166
|
|
|
|
|
|
|
# 08/02/2005 EJR: combined with ahead, per Will Coleda |
167
|
|
|
|
|
|
|
# Parameters: $num - Max number of items to return |
168
|
|
|
|
|
|
|
# $some_other_iterator - another iterator |
169
|
|
|
|
|
|
|
# Returns: limited iterator |
170
|
|
|
|
|
|
|
# Exceptions: Iterator::X::Parameter_Error |
171
|
|
|
|
|
|
|
# Iterator::X::Am_Now_Exhausted |
172
|
|
|
|
|
|
|
sub ihead |
173
|
|
|
|
|
|
|
{ |
174
|
10
|
|
|
10
|
1
|
2908
|
my $num = shift; |
175
|
10
|
|
|
|
|
12
|
my $iter = shift; |
176
|
|
|
|
|
|
|
|
177
|
10
|
100
|
|
|
|
83
|
Iterator::X::Parameter_Error->throw |
178
|
|
|
|
|
|
|
(q{Second parameter for ihead must be an Iterator}) |
179
|
|
|
|
|
|
|
unless UNIVERSAL::isa($iter, 'Iterator'); |
180
|
|
|
|
|
|
|
|
181
|
|
|
|
|
|
|
# List context? Return the first $num elements. |
182
|
8
|
100
|
|
|
|
19
|
if (wantarray) |
183
|
|
|
|
|
|
|
{ |
184
|
4
|
|
|
|
|
4
|
my @a; |
185
|
4
|
|
100
|
|
|
11
|
while ($iter->isnt_exhausted && (!defined($num) || $num-- > 0)) |
|
|
|
66
|
|
|
|
|
186
|
|
|
|
|
|
|
{ |
187
|
8
|
|
|
|
|
132
|
push @a, $iter->value; |
188
|
|
|
|
|
|
|
} |
189
|
4
|
|
|
|
|
440
|
return @a; |
190
|
|
|
|
|
|
|
} |
191
|
|
|
|
|
|
|
|
192
|
|
|
|
|
|
|
# Scalar context: return an iterator to return at most $num elements. |
193
|
|
|
|
|
|
|
return Iterator->new(sub |
194
|
|
|
|
|
|
|
{ |
195
|
14
|
100
|
|
14
|
|
1513
|
Iterator::is_done if $num <= 0; |
196
|
|
|
|
|
|
|
|
197
|
10
|
|
|
|
|
16
|
$num--; |
198
|
10
|
|
|
|
|
27
|
return $iter->value; |
199
|
4
|
|
|
|
|
24
|
}); |
200
|
|
|
|
|
|
|
} |
201
|
|
|
|
|
|
|
|
202
|
|
|
|
|
|
|
# Function name: iappend |
203
|
|
|
|
|
|
|
# Synopsis: $iter = iappend (@iterators); |
204
|
|
|
|
|
|
|
# Description: Joins a bunch of iterators together. |
205
|
|
|
|
|
|
|
# Created: 07/28/2005 by EJR |
206
|
|
|
|
|
|
|
# Parameters: @iterators - any number of other iterators |
207
|
|
|
|
|
|
|
# Returns: A "merged" iterator. |
208
|
|
|
|
|
|
|
# Exceptions: Iterator::X::Parameter_Error |
209
|
|
|
|
|
|
|
# Iterator::X::Am_Now_Exhausted |
210
|
|
|
|
|
|
|
sub iappend |
211
|
|
|
|
|
|
|
{ |
212
|
3
|
|
|
3
|
1
|
80
|
my @its = @_; |
213
|
|
|
|
|
|
|
|
214
|
|
|
|
|
|
|
# Check types |
215
|
3
|
|
|
|
|
9
|
foreach (@its) |
216
|
|
|
|
|
|
|
{ |
217
|
7
|
50
|
|
|
|
38
|
Iterator::X::Parameter_Error->throw |
218
|
|
|
|
|
|
|
(q{All parameters for iarray must be Iterators}) |
219
|
|
|
|
|
|
|
unless UNIVERSAL::isa($_, 'Iterator'); |
220
|
|
|
|
|
|
|
} |
221
|
|
|
|
|
|
|
|
222
|
|
|
|
|
|
|
# Passthru, if there's only one. |
223
|
3
|
50
|
|
|
|
15
|
return $its[0] if @its == 1; |
224
|
|
|
|
|
|
|
|
225
|
|
|
|
|
|
|
return Iterator->new (sub |
226
|
|
|
|
|
|
|
{ |
227
|
19
|
|
|
19
|
|
4223
|
my $val; |
228
|
|
|
|
|
|
|
|
229
|
|
|
|
|
|
|
# Any empty iterators at front of list? Remove'em. |
230
|
19
|
|
100
|
|
|
87
|
while (@its && $its[0]->is_exhausted) |
231
|
|
|
|
|
|
|
{ |
232
|
5
|
|
|
|
|
48
|
shift @its; |
233
|
|
|
|
|
|
|
} |
234
|
|
|
|
|
|
|
|
235
|
|
|
|
|
|
|
# No more iterators? Then we're done. |
236
|
|
|
|
|
|
|
Iterator::is_done |
237
|
19
|
100
|
|
|
|
166
|
if @its == 0; |
238
|
|
|
|
|
|
|
|
239
|
|
|
|
|
|
|
# Return the next value of the iterator at the head of the list. |
240
|
18
|
|
|
|
|
57
|
return $its[0]->value; |
241
|
3
|
|
|
|
|
27
|
}); |
242
|
|
|
|
|
|
|
} |
243
|
|
|
|
|
|
|
|
244
|
|
|
|
|
|
|
# Function name: ipairwise |
245
|
|
|
|
|
|
|
# Synopsis: $iter = ipairwise {code} ($iter1, $iter2); |
246
|
|
|
|
|
|
|
# Description: Applies an operation to pairs of values from iterators. |
247
|
|
|
|
|
|
|
# Created: 07/28/2005 by EJR |
248
|
|
|
|
|
|
|
# Parameters: code - transformation, may use $a and $b |
249
|
|
|
|
|
|
|
# $iter1 - First iterator; "$a" value. |
250
|
|
|
|
|
|
|
# $iter2 - First iterator; "$b" value. |
251
|
|
|
|
|
|
|
# Returns: Iterator |
252
|
|
|
|
|
|
|
# Exceptions: Iterator::X::Parameter_Error |
253
|
|
|
|
|
|
|
# Iterator::X::Am_Now_Exhausted |
254
|
|
|
|
|
|
|
sub ipairwise (&$$) |
255
|
|
|
|
|
|
|
{ |
256
|
2
|
|
|
2
|
1
|
39
|
my $op = shift; |
257
|
2
|
|
|
|
|
4
|
my $iterA = shift; |
258
|
2
|
|
|
|
|
4
|
my $iterB = shift; |
259
|
|
|
|
|
|
|
|
260
|
|
|
|
|
|
|
# Check types |
261
|
2
|
|
|
|
|
6
|
for ($iterA, $iterB) |
262
|
|
|
|
|
|
|
{ |
263
|
4
|
50
|
|
|
|
23
|
Iterator::X::Parameter_Error->throw |
264
|
|
|
|
|
|
|
(q{Second and third parameters for ipairwise must be Iterators}) |
265
|
|
|
|
|
|
|
unless UNIVERSAL::isa($_, 'Iterator'); |
266
|
|
|
|
|
|
|
} |
267
|
|
|
|
|
|
|
|
268
|
|
|
|
|
|
|
return Iterator->new(sub |
269
|
|
|
|
|
|
|
{ |
270
|
10
|
50
|
33
|
10
|
|
831
|
Iterator::is_done |
271
|
|
|
|
|
|
|
if $iterA->is_exhausted || $iterB->is_exhausted; |
272
|
|
|
|
|
|
|
|
273
|
|
|
|
|
|
|
# Localize $a and $b |
274
|
|
|
|
|
|
|
# My thanks to Benjamin Goldberg for this little bit of evil. |
275
|
|
|
|
|
|
|
my ($caller_a, $caller_b) = do |
276
|
10
|
|
|
|
|
110
|
{ |
277
|
10
|
|
|
|
|
12
|
my $pkg; |
278
|
10
|
|
|
|
|
12
|
my $i = 1; |
279
|
10
|
|
|
|
|
12
|
while (1) |
280
|
|
|
|
|
|
|
{ |
281
|
24
|
|
|
|
|
41
|
$pkg = caller($i++); |
282
|
24
|
100
|
100
|
|
|
89
|
last if $pkg ne 'Iterator' && $pkg ne 'Iterator::Util'; |
283
|
|
|
|
|
|
|
} |
284
|
9
|
|
|
9
|
|
167
|
no strict 'refs'; |
|
9
|
|
|
|
|
21
|
|
|
9
|
|
|
|
|
4497
|
|
285
|
10
|
|
|
|
|
32
|
\*{$pkg.'::a'}, \*{$pkg.'::b'}; |
|
10
|
|
|
|
|
27
|
|
|
10
|
|
|
|
|
57
|
|
286
|
|
|
|
|
|
|
}; |
287
|
|
|
|
|
|
|
|
288
|
|
|
|
|
|
|
# Set caller's $a and $b |
289
|
10
|
|
|
|
|
34
|
local (*$caller_a, *$caller_b) = \($iterA->value, $iterB->value); |
290
|
|
|
|
|
|
|
|
291
|
|
|
|
|
|
|
# Invoke caller's operation |
292
|
10
|
|
|
|
|
119
|
return $op->(); |
293
|
2
|
|
|
|
|
20
|
}); |
294
|
|
|
|
|
|
|
} |
295
|
|
|
|
|
|
|
|
296
|
|
|
|
|
|
|
# Function name: iskip |
297
|
|
|
|
|
|
|
# Synopsis: $iter = iskip $num, $another_iterator |
298
|
|
|
|
|
|
|
# Description: Skips the first $num values of another iterator |
299
|
|
|
|
|
|
|
# Created: 07/28/2005 by EJR |
300
|
|
|
|
|
|
|
# Parameters: $num - how many values to skip |
301
|
|
|
|
|
|
|
# $another_iterator - another iterator |
302
|
|
|
|
|
|
|
# Returns: Sequence iterator |
303
|
|
|
|
|
|
|
# Exceptions: None |
304
|
|
|
|
|
|
|
sub iskip |
305
|
|
|
|
|
|
|
{ |
306
|
2
|
|
|
2
|
1
|
44
|
my $num = shift; |
307
|
2
|
|
|
|
|
4
|
my $it = shift; |
308
|
|
|
|
|
|
|
|
309
|
2
|
50
|
|
|
|
13
|
Iterator::X::Parameter_Error->throw |
310
|
|
|
|
|
|
|
(q{Second parameter for iskip must be an Iterator}) |
311
|
|
|
|
|
|
|
unless UNIVERSAL::isa($it, 'Iterator'); |
312
|
|
|
|
|
|
|
|
313
|
|
|
|
|
|
|
# Discard first $num values |
314
|
2
|
|
66
|
|
|
12
|
$it->value while $it->isnt_exhausted && $num-->0; |
315
|
|
|
|
|
|
|
|
316
|
2
|
|
|
|
|
36
|
return $it; |
317
|
|
|
|
|
|
|
} |
318
|
|
|
|
|
|
|
|
319
|
|
|
|
|
|
|
|
320
|
|
|
|
|
|
|
# Function name: iskip_until |
321
|
|
|
|
|
|
|
# Synopsis: $iter = iskip_until {code}, $another_iterator |
322
|
|
|
|
|
|
|
# Description: Skips values of another iterator until {code} is true. |
323
|
|
|
|
|
|
|
# Created: 07/28/2005 by EJR |
324
|
|
|
|
|
|
|
# Parameters: {code} - Determines when to start returning values |
325
|
|
|
|
|
|
|
# $another_iterator - another iterator |
326
|
|
|
|
|
|
|
# Returns: Sequence iterator |
327
|
|
|
|
|
|
|
# Exceptions: Iterator::X::Am_Now_Exhausted |
328
|
|
|
|
|
|
|
sub iskip_until (&$) |
329
|
|
|
|
|
|
|
{ |
330
|
2
|
|
|
2
|
1
|
76
|
my $code = shift; |
331
|
2
|
|
|
|
|
5
|
my $iter = shift; |
332
|
2
|
|
|
|
|
5
|
my $value; |
333
|
2
|
|
|
|
|
5
|
my $found_it = 0; |
334
|
|
|
|
|
|
|
|
335
|
2
|
50
|
|
|
|
17
|
Iterator::X::Parameter_Error->throw |
336
|
|
|
|
|
|
|
(q{Second parameter for iskip_until must be an Iterator}) |
337
|
|
|
|
|
|
|
unless UNIVERSAL::isa($iter, 'Iterator'); |
338
|
|
|
|
|
|
|
|
339
|
|
|
|
|
|
|
# Discard first $num values |
340
|
2
|
|
|
|
|
10
|
while ($iter->isnt_exhausted) |
341
|
|
|
|
|
|
|
{ |
342
|
9
|
|
|
|
|
167
|
local $_ = $iter->value; |
343
|
9
|
100
|
|
|
|
114
|
if ($code->()) |
344
|
|
|
|
|
|
|
{ |
345
|
2
|
|
|
|
|
11
|
$found_it = 1; |
346
|
2
|
|
|
|
|
5
|
$value = $_; |
347
|
2
|
|
|
|
|
4
|
last; |
348
|
|
|
|
|
|
|
} |
349
|
|
|
|
|
|
|
} |
350
|
|
|
|
|
|
|
|
351
|
|
|
|
|
|
|
# Didn't find it? Pity. |
352
|
|
|
|
|
|
|
Iterator::is_done |
353
|
2
|
50
|
|
|
|
10
|
unless $found_it; |
354
|
|
|
|
|
|
|
|
355
|
|
|
|
|
|
|
# Return an iterator with this value, and all remaining values. |
356
|
2
|
|
|
|
|
8
|
return iappend ilist($value), $iter; |
357
|
|
|
|
|
|
|
} |
358
|
|
|
|
|
|
|
|
359
|
|
|
|
|
|
|
|
360
|
|
|
|
|
|
|
# Function name: imesh / izip |
361
|
|
|
|
|
|
|
# Synopsis: $iter = imesh ($iter1, $iter2, ...) |
362
|
|
|
|
|
|
|
# Description: Merges other iterators together. |
363
|
|
|
|
|
|
|
# Created: 07/30/2005 by EJR |
364
|
|
|
|
|
|
|
# Parameters: Any number of other iterators. |
365
|
|
|
|
|
|
|
# Returns: Sequence iterator |
366
|
|
|
|
|
|
|
# Exceptions: Iterator::X::Parameter_Error |
367
|
|
|
|
|
|
|
# Iterator::X::Am_Now_Exhausted |
368
|
|
|
|
|
|
|
foreach my $sub (qw/imesh izip/) |
369
|
|
|
|
|
|
|
{ |
370
|
9
|
|
|
9
|
|
57
|
no strict 'refs'; |
|
9
|
|
|
|
|
16
|
|
|
9
|
|
|
|
|
379
|
|
371
|
|
|
|
|
|
|
*$sub = sub |
372
|
|
|
|
|
|
|
{ |
373
|
9
|
|
|
9
|
|
61
|
use strict 'refs'; |
|
9
|
|
|
|
|
31
|
|
|
9
|
|
|
|
|
4545
|
|
374
|
|
|
|
|
|
|
|
375
|
2
|
|
|
2
|
|
31
|
my @iterators = @_; |
376
|
2
|
|
|
|
|
4
|
my $it_index = 0; |
377
|
|
|
|
|
|
|
|
378
|
2
|
|
|
|
|
6
|
foreach my $iter (@iterators) |
379
|
|
|
|
|
|
|
{ |
380
|
6
|
50
|
|
|
|
26
|
Iterator::X::Parameter_Error->throw( |
381
|
|
|
|
|
|
|
"Argument to $sub is not an iterator") |
382
|
|
|
|
|
|
|
unless UNIVERSAL::isa($iter, 'Iterator'); |
383
|
|
|
|
|
|
|
} |
384
|
|
|
|
|
|
|
|
385
|
|
|
|
|
|
|
return Iterator->new (sub |
386
|
|
|
|
|
|
|
{ |
387
|
16
|
50
|
|
16
|
|
1405
|
Iterator::is_done |
388
|
|
|
|
|
|
|
if $iterators[$it_index]->is_exhausted(); |
389
|
|
|
|
|
|
|
|
390
|
16
|
|
|
|
|
110
|
my $retval = $iterators[$it_index]->value(); |
391
|
|
|
|
|
|
|
|
392
|
16
|
100
|
|
|
|
2086
|
if (++$it_index >= @iterators) |
393
|
|
|
|
|
|
|
{ |
394
|
4
|
|
|
|
|
8
|
$it_index = 0; |
395
|
|
|
|
|
|
|
} |
396
|
|
|
|
|
|
|
|
397
|
16
|
|
|
|
|
61
|
return $retval; |
398
|
2
|
|
|
|
|
13
|
}); |
399
|
|
|
|
|
|
|
}; |
400
|
|
|
|
|
|
|
} |
401
|
|
|
|
|
|
|
|
402
|
|
|
|
|
|
|
# Function name: iuniq |
403
|
|
|
|
|
|
|
# Synopsis: $iter = iuniq ($another_iterator); |
404
|
|
|
|
|
|
|
# Description: Removes duplicate entries from an iterator. |
405
|
|
|
|
|
|
|
# Created: 07/30/2005 by EJR |
406
|
|
|
|
|
|
|
# Parameters: Another iterator. |
407
|
|
|
|
|
|
|
# Returns: Sequence iterator |
408
|
|
|
|
|
|
|
# Exceptions: Iterator::X::Parameter_Error |
409
|
|
|
|
|
|
|
# Iterator::X::Am_Now_Exhausted |
410
|
|
|
|
|
|
|
sub iuniq |
411
|
|
|
|
|
|
|
{ |
412
|
1
|
50
|
|
1
|
1
|
20
|
Iterator::X::Parameter_Error->throw ("Too few parameters to iuniq") |
413
|
|
|
|
|
|
|
if @_ < 1; |
414
|
1
|
50
|
|
|
|
5
|
Iterator::X::Parameter_Error->throw ("Too many parameters to iuniq") |
415
|
|
|
|
|
|
|
if @_ > 1; |
416
|
|
|
|
|
|
|
|
417
|
1
|
|
|
|
|
2
|
my $iter = shift; |
418
|
1
|
50
|
|
|
|
7
|
Iterator::X::Parameter_Error->throw("Argument to iuniq is not an iterator") |
419
|
|
|
|
|
|
|
unless UNIVERSAL::isa($iter, 'Iterator'); |
420
|
|
|
|
|
|
|
|
421
|
1
|
|
|
|
|
3
|
my %did_see; |
422
|
|
|
|
|
|
|
return Iterator->new (sub |
423
|
|
|
|
|
|
|
{ |
424
|
5
|
|
|
5
|
|
691
|
my $value; |
425
|
5
|
|
|
|
|
8
|
while (1) |
426
|
|
|
|
|
|
|
{ |
427
|
7
|
100
|
|
|
|
18
|
Iterator::is_done |
428
|
|
|
|
|
|
|
if $iter->is_exhausted; |
429
|
|
|
|
|
|
|
|
430
|
6
|
|
|
|
|
45
|
$value = $iter->value; |
431
|
6
|
100
|
|
|
|
492
|
last if !$did_see{$value}++; |
432
|
|
|
|
|
|
|
} |
433
|
4
|
|
|
|
|
15
|
return $value; |
434
|
1
|
|
|
|
|
7
|
}); |
435
|
|
|
|
|
|
|
} |
436
|
|
|
|
|
|
|
|
437
|
|
|
|
|
|
|
1; |
438
|
|
|
|
|
|
|
__END__ |
439
|
|
|
|
|
|
|
|
440
|
|
|
|
|
|
|
=head1 SYNOPSIS |
441
|
|
|
|
|
|
|
|
442
|
|
|
|
|
|
|
use Iterator::Util; |
443
|
|
|
|
|
|
|
|
444
|
|
|
|
|
|
|
# Transform sequences |
445
|
|
|
|
|
|
|
$iterator = imap { transformation code } $some_other_iterator; |
446
|
|
|
|
|
|
|
|
447
|
|
|
|
|
|
|
# Filter sequences |
448
|
|
|
|
|
|
|
$iterator = igrep { condition code } $some_other_iterator; |
449
|
|
|
|
|
|
|
|
450
|
|
|
|
|
|
|
# Range of values (arithmetic sequence) |
451
|
|
|
|
|
|
|
$iter = irange ($start, $end, $increment); |
452
|
|
|
|
|
|
|
$iter = irange ($start, $end); |
453
|
|
|
|
|
|
|
$iter = irange ($start); |
454
|
|
|
|
|
|
|
|
455
|
|
|
|
|
|
|
# Iterate over an arbitrary list |
456
|
|
|
|
|
|
|
$iter = ilist (item, item, ...); |
457
|
|
|
|
|
|
|
$iter = ilist (@items); |
458
|
|
|
|
|
|
|
|
459
|
|
|
|
|
|
|
# Iterate over an array, by reference |
460
|
|
|
|
|
|
|
$iter = iarray (\@array); |
461
|
|
|
|
|
|
|
|
462
|
|
|
|
|
|
|
# Return at most $num items from an iterator |
463
|
|
|
|
|
|
|
$iter = ihead ($num, $some_other_iterator); |
464
|
|
|
|
|
|
|
@values = ihead ($num, $some_other_iterator); |
465
|
|
|
|
|
|
|
|
466
|
|
|
|
|
|
|
# Append multiple iterators into one |
467
|
|
|
|
|
|
|
$iter = iappend ($it1, $it2, $it3, ...); |
468
|
|
|
|
|
|
|
|
469
|
|
|
|
|
|
|
# Apply a function to pairs of iterator values |
470
|
|
|
|
|
|
|
$iter = ipairwise {code} $iter_A, $iter_B; |
471
|
|
|
|
|
|
|
|
472
|
|
|
|
|
|
|
# Skip the first $num values of an iterator |
473
|
|
|
|
|
|
|
$iter = iskip ($num, $some_other_iterator); |
474
|
|
|
|
|
|
|
|
475
|
|
|
|
|
|
|
# Skip values from an iterator until a condition is met |
476
|
|
|
|
|
|
|
$iter = iskip_until {code} $some_other_iterator; |
477
|
|
|
|
|
|
|
|
478
|
|
|
|
|
|
|
# Mesh iterators together |
479
|
|
|
|
|
|
|
$iter = imesh ($iter, $iter, ...); |
480
|
|
|
|
|
|
|
$iter = izip ($iter, $iter, ...); |
481
|
|
|
|
|
|
|
|
482
|
|
|
|
|
|
|
# Return each value of an iterator once |
483
|
|
|
|
|
|
|
$iter = iuniq ($another_iterator); |
484
|
|
|
|
|
|
|
|
485
|
|
|
|
|
|
|
=head1 DESCRIPTION |
486
|
|
|
|
|
|
|
|
487
|
|
|
|
|
|
|
This module implements many useful functions for creating and |
488
|
|
|
|
|
|
|
manipulating iterator objects. |
489
|
|
|
|
|
|
|
|
490
|
|
|
|
|
|
|
An "iterator" is an object, represented as a code block that generates |
491
|
|
|
|
|
|
|
the "next value" of a sequence, and generally implemented as a |
492
|
|
|
|
|
|
|
closure. For further information, including a tutorial on using |
493
|
|
|
|
|
|
|
iterator objects, see the L<Iterator> documentation. |
494
|
|
|
|
|
|
|
|
495
|
|
|
|
|
|
|
=head1 FUNCTIONS |
496
|
|
|
|
|
|
|
|
497
|
|
|
|
|
|
|
=over 4 |
498
|
|
|
|
|
|
|
|
499
|
|
|
|
|
|
|
=item imap |
500
|
|
|
|
|
|
|
|
501
|
|
|
|
|
|
|
$iter = imap { transformation code } $some_other_iterator; |
502
|
|
|
|
|
|
|
|
503
|
|
|
|
|
|
|
Returns an iterator that is a transformation of some other iterator. |
504
|
|
|
|
|
|
|
Within the transformation code, C<$_> is set to each value of the |
505
|
|
|
|
|
|
|
other iterator, in turn. |
506
|
|
|
|
|
|
|
|
507
|
|
|
|
|
|
|
I<Examples:> |
508
|
|
|
|
|
|
|
|
509
|
|
|
|
|
|
|
$evens = imap { $_ * 2 } irange (0); # returns 0, 2, 4, ... |
510
|
|
|
|
|
|
|
$squares = imap { $_ * $_ } irange (7); # 49, 64, 81, 100, ... |
511
|
|
|
|
|
|
|
|
512
|
|
|
|
|
|
|
=item igrep |
513
|
|
|
|
|
|
|
|
514
|
|
|
|
|
|
|
$iter = igrep { condition } $some_other_iterator; |
515
|
|
|
|
|
|
|
|
516
|
|
|
|
|
|
|
Returns an iterator that selectively returns values from some other |
517
|
|
|
|
|
|
|
iterator. Within the C<condition> code, C<$_> is set to each value of |
518
|
|
|
|
|
|
|
the other iterator, in turn. |
519
|
|
|
|
|
|
|
|
520
|
|
|
|
|
|
|
I<Examples:> |
521
|
|
|
|
|
|
|
|
522
|
|
|
|
|
|
|
$fives = igrep { $_ % 5 == 0 } irange (0,10); # returns 0, 5, 10 |
523
|
|
|
|
|
|
|
$small = igrep { $_ < 10 } irange (8,12); # returns 8, 9 |
524
|
|
|
|
|
|
|
|
525
|
|
|
|
|
|
|
=item irange |
526
|
|
|
|
|
|
|
|
527
|
|
|
|
|
|
|
$iter = irange ($start, $end, $increment); |
528
|
|
|
|
|
|
|
$iter = irange ($start, $end); |
529
|
|
|
|
|
|
|
$iter = irange ($start); |
530
|
|
|
|
|
|
|
|
531
|
|
|
|
|
|
|
C<irange> returns a sequence of numbers. The sequence begins with |
532
|
|
|
|
|
|
|
C<$start>, ends at C<$end>, and steps by C<$increment>. This is sort |
533
|
|
|
|
|
|
|
of the Iterator version of a C<for> loop. |
534
|
|
|
|
|
|
|
|
535
|
|
|
|
|
|
|
If C<$increment> is not specified, 1 is used. C<$increment> may be |
536
|
|
|
|
|
|
|
negative -- or even zero, in which case iterator returns an infinite |
537
|
|
|
|
|
|
|
sequence of C<$start>. |
538
|
|
|
|
|
|
|
|
539
|
|
|
|
|
|
|
If C<$end> is not specified (is C<undef>), the sequence is infinite. |
540
|
|
|
|
|
|
|
|
541
|
|
|
|
|
|
|
I<Examples:> |
542
|
|
|
|
|
|
|
|
543
|
|
|
|
|
|
|
$iter = irange (1, 2); # Iterate from 1 to 2 |
544
|
|
|
|
|
|
|
$val = $iter->value(); # $val is now 1. |
545
|
|
|
|
|
|
|
$val = $iter->value(); # $val is now 2. |
546
|
|
|
|
|
|
|
$bool = $iter->is_exhausted(); # $bool is now true. |
547
|
|
|
|
|
|
|
|
548
|
|
|
|
|
|
|
$iter = irange (10, 8, -1); # Iterate from 10 down to 8 |
549
|
|
|
|
|
|
|
$iter = irange (1); # Iterate from 1, endlessly. |
550
|
|
|
|
|
|
|
|
551
|
|
|
|
|
|
|
=item ilist |
552
|
|
|
|
|
|
|
|
553
|
|
|
|
|
|
|
$iter = ilist (@items); |
554
|
|
|
|
|
|
|
|
555
|
|
|
|
|
|
|
Returns an iterator that iterates over an arbitrary sequence of |
556
|
|
|
|
|
|
|
values. It's sort of an Iterator version of C<foreach>. |
557
|
|
|
|
|
|
|
|
558
|
|
|
|
|
|
|
This function makes an internal copy of the list, so it may not be |
559
|
|
|
|
|
|
|
appropriate for an extremely large list. |
560
|
|
|
|
|
|
|
|
561
|
|
|
|
|
|
|
I<Example:> |
562
|
|
|
|
|
|
|
|
563
|
|
|
|
|
|
|
$iter = ilist (4, 'minus five', @foo, 7); |
564
|
|
|
|
|
|
|
$val = $iter->value(); # $val is now 4 |
565
|
|
|
|
|
|
|
$val = $iter->value(); # $val is now 'minus five' |
566
|
|
|
|
|
|
|
... |
567
|
|
|
|
|
|
|
|
568
|
|
|
|
|
|
|
=item iarray |
569
|
|
|
|
|
|
|
|
570
|
|
|
|
|
|
|
$iter = iarray (\@array); |
571
|
|
|
|
|
|
|
|
572
|
|
|
|
|
|
|
Returns an iterator that iterates over an array. Note that since it |
573
|
|
|
|
|
|
|
uses a reference to that array, if you modify the array, that will be |
574
|
|
|
|
|
|
|
reflected in the values returned by the iterator. This may be What |
575
|
|
|
|
|
|
|
You Want. Or it may cause Hard-To-Find Bugs. |
576
|
|
|
|
|
|
|
|
577
|
|
|
|
|
|
|
=item ihead |
578
|
|
|
|
|
|
|
|
579
|
|
|
|
|
|
|
$iter = ihead ($num, $some_other_iterator); |
580
|
|
|
|
|
|
|
@values = ihead ($num, $some_iterator); |
581
|
|
|
|
|
|
|
|
582
|
|
|
|
|
|
|
In scalar context, creates an iterator that returns at most C<$num> |
583
|
|
|
|
|
|
|
items from another iterator, then stops. |
584
|
|
|
|
|
|
|
|
585
|
|
|
|
|
|
|
In list context, returns the first C<$num> items from the iterator. |
586
|
|
|
|
|
|
|
If C<$num> is C<undef>, all remaining values are pulled |
587
|
|
|
|
|
|
|
from the iterator until it is exhausted. Use C<undef> with caution; |
588
|
|
|
|
|
|
|
iterators can be huge -- or infinite. |
589
|
|
|
|
|
|
|
|
590
|
|
|
|
|
|
|
I<Examples:> |
591
|
|
|
|
|
|
|
|
592
|
|
|
|
|
|
|
$iota5 = ihead 5, irange 1; # returns 1, 2, 3, 4, 5. |
593
|
|
|
|
|
|
|
|
594
|
|
|
|
|
|
|
$iter = irange 1; # infinite sequence, starting with 1 |
595
|
|
|
|
|
|
|
@vals = ihead (5, $iter); # @vals is (1, 2, 3, 4, 5) |
596
|
|
|
|
|
|
|
$nextval = $iter->value; # $nextval is 6. |
597
|
|
|
|
|
|
|
|
598
|
|
|
|
|
|
|
=item iappend |
599
|
|
|
|
|
|
|
|
600
|
|
|
|
|
|
|
$iter = iappend (@list_of_iterators); |
601
|
|
|
|
|
|
|
|
602
|
|
|
|
|
|
|
Creates an iterator that consists of any number of other iterators |
603
|
|
|
|
|
|
|
glued together. The resulting iterator pulls values from the first |
604
|
|
|
|
|
|
|
iterator until it's exhausted, then from the second, and so on. |
605
|
|
|
|
|
|
|
|
606
|
|
|
|
|
|
|
=item ipairwise |
607
|
|
|
|
|
|
|
|
608
|
|
|
|
|
|
|
$iter = ipairwise {code} $it_A, $it_B; |
609
|
|
|
|
|
|
|
|
610
|
|
|
|
|
|
|
Creates a new iterator which applies C<{code}> to pairs of elements of |
611
|
|
|
|
|
|
|
two other iterators, C<$it_A> and C<$it_B> in turn. The pairs are |
612
|
|
|
|
|
|
|
assigned to C<$a> and C<$b> before invoking the code. |
613
|
|
|
|
|
|
|
|
614
|
|
|
|
|
|
|
The new iterator is exhausted when either C<$it_A> or C<$it_B> are |
615
|
|
|
|
|
|
|
exhausted. |
616
|
|
|
|
|
|
|
|
617
|
|
|
|
|
|
|
This function is analogous to the L<pairwise|List::MoreUtils/pairwise> |
618
|
|
|
|
|
|
|
function from L<List::MoreUtils>. |
619
|
|
|
|
|
|
|
|
620
|
|
|
|
|
|
|
I<Example:> |
621
|
|
|
|
|
|
|
|
622
|
|
|
|
|
|
|
$first = irange 1; # 1, 2, 3, 4, ... |
623
|
|
|
|
|
|
|
$second = irange 4, undef, 2; # 4, 6, 8, 10, ... |
624
|
|
|
|
|
|
|
$third = ipairwise {$a * $b} $first, $second; # 4, 12, 24, 40, ... |
625
|
|
|
|
|
|
|
|
626
|
|
|
|
|
|
|
=item iskip |
627
|
|
|
|
|
|
|
|
628
|
|
|
|
|
|
|
$iter = iskip ($num, $another_iterator); |
629
|
|
|
|
|
|
|
|
630
|
|
|
|
|
|
|
Returns an iterator that contains the values of C<$another_iterator>, |
631
|
|
|
|
|
|
|
minus the first C<$num> values. In other words, skips the first |
632
|
|
|
|
|
|
|
C<$num> values of C<$another_iterator>. |
633
|
|
|
|
|
|
|
|
634
|
|
|
|
|
|
|
I<Example:> |
635
|
|
|
|
|
|
|
|
636
|
|
|
|
|
|
|
$iter = ilist (24, -1, 7, 8); # Bunch of random values |
637
|
|
|
|
|
|
|
$cdr = iskip 1, $iter; # "pop" the first value |
638
|
|
|
|
|
|
|
$val = $cdr->value(); # $val is -1. |
639
|
|
|
|
|
|
|
|
640
|
|
|
|
|
|
|
=item iskip_until |
641
|
|
|
|
|
|
|
|
642
|
|
|
|
|
|
|
$iter = iskip_until {code} $another_iterator; |
643
|
|
|
|
|
|
|
|
644
|
|
|
|
|
|
|
Returns an iterator that skips the leading values of C<$another_iterator> |
645
|
|
|
|
|
|
|
until C<{code}> evaluates to true for one of its values. C<{code}> |
646
|
|
|
|
|
|
|
can refer to the current value as C<$_>. |
647
|
|
|
|
|
|
|
|
648
|
|
|
|
|
|
|
I<Example:> |
649
|
|
|
|
|
|
|
|
650
|
|
|
|
|
|
|
$iter = iskip_until {$_ > 5} irange 1; # returns 6, 7, 8, 9, ... |
651
|
|
|
|
|
|
|
|
652
|
|
|
|
|
|
|
=item imesh |
653
|
|
|
|
|
|
|
|
654
|
|
|
|
|
|
|
=item izip |
655
|
|
|
|
|
|
|
|
656
|
|
|
|
|
|
|
$iter = imesh ($iter1, $iter2, ...); |
657
|
|
|
|
|
|
|
|
658
|
|
|
|
|
|
|
This iterator accepts any number of other iterators, and "meshes" |
659
|
|
|
|
|
|
|
their values together. First it returns the first value of the first |
660
|
|
|
|
|
|
|
iterator, then the first value of the second iterator, and so on, |
661
|
|
|
|
|
|
|
until it has returned the first value of all of its iterator |
662
|
|
|
|
|
|
|
arguments. Then it goes back and returns the second value of the |
663
|
|
|
|
|
|
|
first iterator, and so on. It stops when any of its iterator |
664
|
|
|
|
|
|
|
arguments is exhausted. |
665
|
|
|
|
|
|
|
|
666
|
|
|
|
|
|
|
I<Example:> |
667
|
|
|
|
|
|
|
|
668
|
|
|
|
|
|
|
$i1 = ilist ('a', 'b', 'c'); |
669
|
|
|
|
|
|
|
$i2 = ilist (1, 2, 3); |
670
|
|
|
|
|
|
|
$i3 = ilist ('rock', 'paper', 'scissors'); |
671
|
|
|
|
|
|
|
$iter = imesh ($i1, $i2, $i3); |
672
|
|
|
|
|
|
|
# $iter will return, in turn, 'a', 1, 'rock', 'b', 2, 'paper', 'c',... |
673
|
|
|
|
|
|
|
|
674
|
|
|
|
|
|
|
C<izip> is a synonym for C<imesh>. |
675
|
|
|
|
|
|
|
|
676
|
|
|
|
|
|
|
=item iuniq |
677
|
|
|
|
|
|
|
|
678
|
|
|
|
|
|
|
$iter = iuniq ($another_iterator); |
679
|
|
|
|
|
|
|
|
680
|
|
|
|
|
|
|
Creates an iterator to return unique values from another iterator; |
681
|
|
|
|
|
|
|
weeds out duplicates. |
682
|
|
|
|
|
|
|
|
683
|
|
|
|
|
|
|
I<Example:> |
684
|
|
|
|
|
|
|
|
685
|
|
|
|
|
|
|
$iter = ilist (1, 2, 2, 3, 1, 4); |
686
|
|
|
|
|
|
|
$uniq = iuniq ($iter); # returns 1, 2, 3, 4. |
687
|
|
|
|
|
|
|
|
688
|
|
|
|
|
|
|
=back |
689
|
|
|
|
|
|
|
|
690
|
|
|
|
|
|
|
=head1 EXPORTS |
691
|
|
|
|
|
|
|
|
692
|
|
|
|
|
|
|
All function names are exported to the caller's namespace by default. |
693
|
|
|
|
|
|
|
|
694
|
|
|
|
|
|
|
=head1 DIAGNOSTICS |
695
|
|
|
|
|
|
|
|
696
|
|
|
|
|
|
|
Iterator::Util uses L<Exception::Class> objects for throwing |
697
|
|
|
|
|
|
|
exceptions. If you're not familiar with Exception::Class, don't |
698
|
|
|
|
|
|
|
worry; these exception objects work just like C<$@> does with C<die> |
699
|
|
|
|
|
|
|
and C<croak>, but they are easier to work with if you are trapping |
700
|
|
|
|
|
|
|
errors. |
701
|
|
|
|
|
|
|
|
702
|
|
|
|
|
|
|
See the L<Iterator|Iterator/DIAGNOSTICS> module documentation for more |
703
|
|
|
|
|
|
|
information on trapping and handling these exceptions. |
704
|
|
|
|
|
|
|
|
705
|
|
|
|
|
|
|
=over 4 |
706
|
|
|
|
|
|
|
|
707
|
|
|
|
|
|
|
=item * Parameter Errors |
708
|
|
|
|
|
|
|
|
709
|
|
|
|
|
|
|
Class: C<Iterator::X::Parameter_Error> |
710
|
|
|
|
|
|
|
|
711
|
|
|
|
|
|
|
You called an Iterator method with one or more bad parameters. Since |
712
|
|
|
|
|
|
|
this is almost certainly a coding error, there is probably not much |
713
|
|
|
|
|
|
|
use in handling this sort of exception. |
714
|
|
|
|
|
|
|
|
715
|
|
|
|
|
|
|
As a string, this exception provides a human-readable message about |
716
|
|
|
|
|
|
|
what the problem was. |
717
|
|
|
|
|
|
|
|
718
|
|
|
|
|
|
|
=item * Exhausted Iterators |
719
|
|
|
|
|
|
|
|
720
|
|
|
|
|
|
|
Class: C<Iterator::X::Exhausted> |
721
|
|
|
|
|
|
|
|
722
|
|
|
|
|
|
|
You called C<value|Iterator/value> on an iterator that is exhausted; |
723
|
|
|
|
|
|
|
that is, there are no more values in the sequence to return. |
724
|
|
|
|
|
|
|
|
725
|
|
|
|
|
|
|
As a string, this exception is "Iterator is exhausted." |
726
|
|
|
|
|
|
|
|
727
|
|
|
|
|
|
|
=item * User Code Exceptions |
728
|
|
|
|
|
|
|
|
729
|
|
|
|
|
|
|
Class: C<Iterator::X::User_Code_Error> |
730
|
|
|
|
|
|
|
|
731
|
|
|
|
|
|
|
This exception is thrown when the sequence generation code throws any |
732
|
|
|
|
|
|
|
sort of error besides C<Am_Now_Exhausted>. This could be because your |
733
|
|
|
|
|
|
|
code explicitly threw an error (that is, C<die>d), or because it |
734
|
|
|
|
|
|
|
otherwise encountered an exception (any runtime error). |
735
|
|
|
|
|
|
|
|
736
|
|
|
|
|
|
|
This exception has one method, C<eval_error>, which returns the |
737
|
|
|
|
|
|
|
original C<$@> that was trapped by the Iterator object. This may be a |
738
|
|
|
|
|
|
|
string or an object, depending on how C<die> was invoked. |
739
|
|
|
|
|
|
|
|
740
|
|
|
|
|
|
|
As a string, this exception evaluates to the stringified C<$@>. |
741
|
|
|
|
|
|
|
|
742
|
|
|
|
|
|
|
=item * I/O Errors |
743
|
|
|
|
|
|
|
|
744
|
|
|
|
|
|
|
Class: C<Iterator::X::IO_Error> |
745
|
|
|
|
|
|
|
|
746
|
|
|
|
|
|
|
This exception is thrown when any sort of I/O error occurs; this |
747
|
|
|
|
|
|
|
only happens with the filesystem iterators. |
748
|
|
|
|
|
|
|
|
749
|
|
|
|
|
|
|
This exception has one method, C<os_error>, which returns the original |
750
|
|
|
|
|
|
|
C<$!> that was trapped by the Iterator object. |
751
|
|
|
|
|
|
|
|
752
|
|
|
|
|
|
|
As a string, this exception provides some human-readable information |
753
|
|
|
|
|
|
|
along with C<$!>. |
754
|
|
|
|
|
|
|
|
755
|
|
|
|
|
|
|
=item * Internal Errors |
756
|
|
|
|
|
|
|
|
757
|
|
|
|
|
|
|
Class: C<Iterator::X::Internal_Error> |
758
|
|
|
|
|
|
|
|
759
|
|
|
|
|
|
|
Something happened that I thought couldn't possibly happen. I would |
760
|
|
|
|
|
|
|
appreciate it if you could send me an email message detailing the |
761
|
|
|
|
|
|
|
circumstances of the error. |
762
|
|
|
|
|
|
|
|
763
|
|
|
|
|
|
|
=back |
764
|
|
|
|
|
|
|
|
765
|
|
|
|
|
|
|
=head1 REQUIREMENTS |
766
|
|
|
|
|
|
|
|
767
|
|
|
|
|
|
|
Requires the following additional modules: |
768
|
|
|
|
|
|
|
|
769
|
|
|
|
|
|
|
L<Iterator> |
770
|
|
|
|
|
|
|
|
771
|
|
|
|
|
|
|
=head1 SEE ALSO |
772
|
|
|
|
|
|
|
|
773
|
|
|
|
|
|
|
I<Higher Order Perl>, Mark Jason Dominus, Morgan Kauffman 2005. |
774
|
|
|
|
|
|
|
|
775
|
|
|
|
|
|
|
L<http://perl.plover.com/hop/> |
776
|
|
|
|
|
|
|
|
777
|
|
|
|
|
|
|
=head1 THANKS |
778
|
|
|
|
|
|
|
|
779
|
|
|
|
|
|
|
Much thanks to Will Coleda and Paul Lalli (and the RPI lily crowd in |
780
|
|
|
|
|
|
|
general) for suggestions for the pre-release version. |
781
|
|
|
|
|
|
|
|
782
|
|
|
|
|
|
|
=head1 AUTHOR / COPYRIGHT |
783
|
|
|
|
|
|
|
|
784
|
|
|
|
|
|
|
Eric J. Roode, roode@cpan.org |
785
|
|
|
|
|
|
|
|
786
|
|
|
|
|
|
|
Copyright (c) 2005 by Eric J. Roode. All Rights Reserved. |
787
|
|
|
|
|
|
|
This module is free software; you can redistribute it and/or modify it |
788
|
|
|
|
|
|
|
under the same terms as Perl itself. |
789
|
|
|
|
|
|
|
|
790
|
|
|
|
|
|
|
To avoid my spam filter, please include "Perl", "module", or this |
791
|
|
|
|
|
|
|
module's name in the message's subject line, and/or GPG-sign your |
792
|
|
|
|
|
|
|
message. |
793
|
|
|
|
|
|
|
|
794
|
|
|
|
|
|
|
=cut |
795
|
|
|
|
|
|
|
|
796
|
|
|
|
|
|
|
=begin gpg |
797
|
|
|
|
|
|
|
|
798
|
|
|
|
|
|
|
-----BEGIN PGP SIGNATURE----- |
799
|
|
|
|
|
|
|
Version: GnuPG v1.4.1 (Cygwin) |
800
|
|
|
|
|
|
|
|
801
|
|
|
|
|
|
|
iD8DBQFDC5UFY96i4h5M0egRApNiAJ9WwoZql+2DE+RsSA6koGLZPcbQZACfY248 |
802
|
|
|
|
|
|
|
VoKah+WAFOvk46vOcn+hL9Y= |
803
|
|
|
|
|
|
|
=aOws |
804
|
|
|
|
|
|
|
-----END PGP SIGNATURE----- |
805
|
|
|
|
|
|
|
|
806
|
|
|
|
|
|
|
=end gpg |