-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
175 lines (128 loc) · 6.7 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
NAME
Iterator::Simple::Util - Port of List::Util and List::MoreUtils to
Iterator::Simple
VERSION
version 0.002
SYNOPSIS
use Iterator::Simple::Util qw( igroup ireduce isum
imax imin imaxstr iminstr imax_by imin_by imaxstr_by iminstr_by
iany inone inotall
ifirstval ilastval
ibefore ibefore_incl iafter iafter_incl
inatatime );
DESCRIPTION
Iterator::Simple::Util implements many of the functions from List::Util
and List::MoreUtils for iterators generated by Iterator::Simple.
EXPORTS
All of these functions call "Iterator::Simple::iter()" on the
**ITERABLE** argument; this detects what **ITERABLE** is and turns it
into an iterator. See iterator::Simple for details.
Functions taking a *BLOCK* expect a code block that operates on $_ or,
in the case of igroup and ireduce, on $a and $b.
igroup *BLOCK* *ITERABLE*
ireduce *BLOCK* [*INIT_VAL*] *ITERABLE*
Reduces *ITERABLE* by calling *BLOCK*, in a scalar context, multiple
times, setting $a and $b each time. The first call will be with $a
and $b set to the first two elements of the list, subsequent calls
will be done by setting $a to the result of the previous call and $b
to the next element in the list.
Returns the result of the last call to *BLOCK*. If the iterator is
empty then "undef" is returned. If the iterator only contains one
element then that element is returned and *BLOCK* is not executed.
$foo = ireduce { $a < $b ? $a : $b } $iterator # min
$foo = ireduce { $a lt $b ? $a : $b } $iterator # minstr
$foo = ireduce { $a + $b } $iterator # sum
$foo = ireduce { $a . $b } $iterator # concat
If your algorithm requires that "reduce" produce an identity value,
then make sure that you always pass that identity value as the first
argument to prevent "undef" being returned. For example:
$foo = ireduce { $a + $b } 0, $iterator
will return 0 (rather than "undef") when $iterator is empty.
isum [*INIT_VAL*] *ITERABLE*
Returns the sum of the elements of *ITERABLE*, which should return
numeric values. Returns 0 if the iterator is empty.
imax *ITERABLE*
Returns the maximum value of *ITERABLE*, which should produce
numeric values. Retruns "undef" if the iterator is empty.
imin *ITERABLE*
Returns the minimum value of *ITERABLE*, which should produce
numeric values. Returns "undef" if the iterator is empty.
imax_by *BLOCK* *ITERABLE*
Return the value of *ITERABLE* for which *BLOCK* produces the
maximum value. For example:
imax_by { $_ * $_ } iter( [ -5 -2 -1 0 1 2 ] )
will return -5.
imin_by *BLOCK* *ITERABLE*
Similar to imax_by, but returns the value of *ITERABLE* for which
*BLOCK* produces the minimum value.
imaxstr *ITERABLE*
Similar to imax, but expects *ITERABLE* to return string values.
iminstr *ITERABLE*
Similar to imin, but expects *ITERABLE* to return string values.
imaxstr_by *BLOCK* *ITERABLE*
Similar to imax_by, but expects *ITERABLE* to return string values.
iminstr_by *BLOCK* *ITERABLE*
Similar to imin_by, but expects *ITERABLE* to return string values.
iany *BLOCK* *ITERABLE*
Returns a true value if any item produced by *ITERABLE* meets the
criterion given through *BLOCK*. Sets $_ for each item in turn:
print "At least one value greater than 10"
if iany { $_ > 10 } $iterator;
Returns false otherwise, or if the iterator is empty.
inone *BLOCK* *ITERABLE*
Returns a true value if no item produced by *ITERABLE* meets the
criterion given through *BLOCK*, or if the iterator is empty. Sets
$_ for each item in turn:
print "No values greater than 10"
if inone { $_ > 10 } $iterator;
Returns false otherwise.
inotall *BLOCK* *ITERABLE*
Logically the negation of *all*. Returns true if *BLOCK* returns
false for some value of *ITERABLE*:
print "Not all even"
if inotall { $_ % 2 == 0 } $iterator;
Returns false if the iterator is empty, or all values of *BLOCK*
produces a true value for every item produced by *ITERABLE*.
ifirstval *BLOCK* *ITERABLE*
Returns the first element produced by *ITERABLE* for which *BLOCK*
evaluates to true. Each element produced by *ITERABLE* is set to $_
in turn. Returns "undef" if no such element has been found.
ilastval *BLOCK* *ITERABLE*
Returns the last element produced by *ITERABLE* for which *BLOCK*
evaluates to true. Each element of *ITERABLE* is set to $_ in turn.
Returns "undef" if no such element has been found.
ibefore *BLOCK* *ITERABLE*
Returns an iterator that will produce all values of *ITERABLE* upto
(and not including) the point where *BLOCK* returns a true value.
Sets $_ for each element in turn.
ibefore_incl *BLOCK* *ITERABLE*
Returns an iterator that will produce all values of *ITERABLE* upto
(and including) the point where *BLOCK* returns a true value. Sets
$_ for each element in turn.
iafter *BLOCK* *ITERABLE*
Returns an iterator that will produce all values of *ITERABLE* after
(and not including) the point where *BLOCK* returns a true value.
Sets $_ for each element in turn.
$it = iafter { $_ % 5 == 0 } [1..9]; # $it returns 6, 7, 8, 9
iafter_incl *BLOCK* *ITERABLE*
Returns an iterator that will produce all values of *ITERABLE* after
(and including) the point where *BLOCK* returns a true value. Sets
$_ for each element in turn.
$it = iafter_incl { $_ % 5 == 0 } [1..9]; # $it returns 5, 6, 7, 8, 9
inatatime *KICKS* *ITERABLE*
Creates an array iterator that returns array refs of elements from
*ITERABLE*, *KICKS* items at a time. For example:
my $it = inatatime 3, iter( [ 'a' .. 'g' ] );
while( my $vals = $it->next ) {
print join( ' ', @{$vals} ) . "\n";
}
This prints:
a b c
d e f
g
AUTHOR
Ray Miller <raym@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2012 by Ray Miller.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.