blib/lib/Array/Windowed.pm

filter: Statementstmt 100% 26 / 26 Branchbran 100% 4 / 4 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 5 / 5 Podpod 100% 1 / 1 totaltotal 100% 36 / 36 CC 3 SCAR 6.2
CC
3
Cov
100%
array_windowed
3.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.9
↑ Summary
1 package Array::Windowed;
2 1 ▶use base qw(Exporter);
Subroutine BEGIN: called CC=1 SCAR=0.0
3  
4 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 #use Smart::Comments;
8 1 ▶use List::Util qw(min max);
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 1 our @EXPORT_OK;
11  
12 1 our $VERSION = "1.00";
13  
14 =head1 NAME
15  
16 Array::Windowed - return a windowed slice of the array
17  
18 =head1 SYNOPSIS
19  
20 use Array::Windowed qw(windowed_array);
21  
22 # from an array
23 my $new_array = array_window @old_array, $start_index, $count);
24  
25 # from an arrayref
26 my $new_array2 = &array_window($array_ref, $start_index, $count);
27  
28 =head1 DESCRIPTION
29  
30 Simple module to return a slice of the passed array as specified by a start
31 position and a number of elements. Unlike the built in slicing functions this
32 does not populate the returned array with C<undef>s for out of bounds
33 operations, but simply returns a smaller array.
34  
35 =head1 FUNCTION
36  
37 Exported on demand (or you can call it fully qualified)
38  
39 =over
40  
41 =item array_windowed @old_array, $start_index, $count
42  
43 Returns an array reference containing up to C<$count> elements from the
44 C<@old_array> starting at C<$start_index>.
45  
46 Unlike a traditional array slice elements outside the bounds of the array
47 are simply dropped. Negative indexes are treated as normal indexes that
48 occur before the 0th index (rather than indexes counting backwards from
49 the start of the array.)
50  
51 This is probably best shown with a series of examples:
52  
53  
54 my @array = ['a'..'z'];
55  
56 # ["a".."z"]
57 array_windowed(@array, 0, 26);
58  
59 # ["a","b","c","d","e"]
60 array_windowed(@array, 0, 5);
61  
62 # ["b","c","d","e","f"]
63 array_windowed(@array, 1, 5);
64  
65 # []
66 array_windowed(@array, 26, 5);
67  
68 # []
69 array_windowed(@array, -50, 5);
70  
71 # ["x","y","z"]
72 array_windowed(@array, 23, 5);
73  
74 # ["a","b","c"]
75 array_windowed(@array, -2, 5);
76  
77 # ["a".."z"]
78 &array_windowed(\@array, 0, 26);
79  
80  
81 =cut
82  
83 8 ▶sub array_windowed(\@$$) {
Subroutine array_windowed: called CC=3 SCAR=11.0
Pod documented
84 8 my $array_ref = shift;
85 8 my $start = shift;
86 8 my $count = shift;
87  
88 8 my $first_index = max(0, $start);
89 8 my $last_index = min(@{ $array_ref } - 1, $start + $count - 1);
90  
91 # smart comment for debugging, uncomment use Smart::Comments above
92 ### $start
93 ### $count
94 ### $first_index
95 ### $last_index
96  
97 8 ▶ return [] if $last_index < 0;
Branch: 1 branch
BranchTrueFalseTotal
if $last_index < 0 1 7 8
98 7 ▶ return [] if $first_index > $last_index;
Branch: 1 branch
BranchTrueFalseTotal
if $first_index > $last_index 1 6 7
99 6 return [@{$array_ref}[$first_index..$last_index]];
100 }
101 1 push @EXPORT_OK, "array_windowed";
102  
103 =back
104  
105 =head1 RATIONALLE
106  
107 Why this module?
108  
109 =over
110  
111 =item Why not simple array slices with @foo[ ... ]
112  
113 Because the edge cases of indexes outside the bounds of the array don't do the
114 same thing (they return lots of C<undef>s mainly)
115  
116 =item Why not splice?
117  
118 It's destructive on the original array.
119  
120 =item Why not Array::Window
121  
122 Because it tries too hard to DTRT, which isn't the RT for us. For example,
123 if you have a count bigger than the entire array then it always returns the
124 entire array irregardless of the start position.
125  
126 This doesn't mean it's not the module for you, however.
127  
128 =item Why not Data::Page
129  
130 This concept of windowing we're using doesn't use pages, but rather
131 a start position and a count.
132  
133 This doesn't mean it's not the module for you, however.
134  
135 =back
136  
137 =head1 AUTHOR
138  
139 Written by Mark Fowler <mark@twoshortplanks.com>
140  
141 =head1 COPYRIGHT
142  
143 Copyright Mark Fowler 2012. All Rights Reserved.
144  
145 This program is free software; you can redistribute it
146 and/or modify it under the same terms as Perl itself.
147  
148 =head1 BUGS
149  
150 This module does no sanity checking on the values that are passed into
151 it (i.e. it does not check that C<$start> or C<$count> are integer numbers,
152 nor does it check that the first argument is an array reference if you disable
153 prototyping.)
154  
155 Bugs should be reported via this distribution's
156 CPAN RT queue. This can be found at
157 L<https://rt.cpan.org/Dist/Display.html?Array-Windowed>
158  
159 You can also address issues by forking this distribution
160 on github and sending pull requests. It can be found at
161 L<http://github.com/2shortplanks/Array-Windowed>
162  
163 =head1 SEE ALSO
164  
165 L<Array::Window>, L<Data::Page>
166  
167 =cut
168  
169 1 1;
170  
↑ Summary