blib/lib/List/NSect.pm

filter: Statementstmt 100% 40 / 40 Branchbran 100% 16 / 16 Conditioncond 100% 9 / 9 MC/DCmcdc 100% 5 / 5 Subroutinesub 100% 10 / 10 Podpod 100% 3 / 3 totaltotal 100% 83 / 83 CC 13 SCAR 12.7
CC
13
Cov
100%
nsect
6.0
spart
4.0
deal
4.0
CRAP 3.5
↑ Summary
1 package List::NSect;
2 6 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 6 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 6 ▶use base qw{Exporter};
Subroutine BEGIN: called CC=1 SCAR=0.0
5 6 ▶use List::MoreUtils qw{part};
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 6 our $VERSION = '0.07';
8 6 our @EXPORT = qw(nsect);
9 6 our @EXPORT_OK = qw(spart deal);
10  
11 =head1 NAME
12  
13 List::NSect - Cuts or divides a list into N equal parts.
14  
15 =head1 SYNOPSIS
16  
17 use List::NSect;
18 my @sections=nsect(5 => "a" .. "z");
19 foreach my $section (@sections) {
20 print join(",", @$section), "\n";
21 }
22  
23 Output
24  
25 a,b,c,d,e,f
26 g,h,i,j,k
27 l,m,n,o,p
28 q,r,s,t,u
29 v,w,x,y,z
30  
31 =head1 DESCRIPTION
32  
33 List::NSect is an L<Exporter> that exports the function "nsect".
34  
35 =head2 nsect like bisect not mosquito
36  
37 I had a hard time deciding on a function name that was distinct and succinct. When I searched the Internet for "divide into equal parts", "bisect - to divide into two equal parts" was one of the top hits. I then tried to find a synonym for "divide into N equal parts". I soon realized that there is no single English word for the concept: thus "nsect".
38  
39 Other function names that I was contemplating are "chunk" (to cut, break, or form into chunks), "allot" (to divide or distribute by share or portion) and "apportion" (to distribute or allocate proportionally; divide and assign according to some rule of proportional distribution). None of these names implies the need for exactly N sections instead of some other distribution.
40  
41 I use this capability all of the time which is a specific implementation of List::MoreUtils::part. You may ask `why not just use "part" directly from L<List::MoreUtils>?` Well, there are many edge cases. Please, take a look at the code; This is Perl!
42  
43 =head1 USAGE
44  
45 use List::NSect;
46 my @sections=nsect($n => @list); #returns ([...], [...], [...], ...); #$n count of arrray references
47  
48 use List::NSect qw{spart};
49 my @batches=spart($n => @list); #returns ([...], [...], [...], ...); #array reference of $n size
50  
51 =head1 FUNCTION
52  
53 =head2 nsect
54  
55 Cuts or divides a list into N equal or nearly equal parts.
56  
57 Returns an array of array references given a scalar number of sections and a list.
58  
59 my @sections=nsect(4, 1 .. 17); #returns ([1,2,3,4,5],[6,7,8,9],[10,11,12,13],[14,15,16,17]);
60 my $sections=nsect(4, 1 .. 17); #returns [[1,2,3,4,5],[6,7,8,9],[10,11,12,13],[14,15,16,17]];
61  
62 =cut
63  
64 28 ▶sub nsect {
Subroutine nsect: called CC=6 SCAR=17.9
Pod documented
65 28 ▶ my $n = shift || 0;
Condition100%2/2
shift() || 0
l!l
1612
MC/DC100%1/1
shift() || 0
shift()
Truth table100%2/2
A
A= shift()
Aresult
11
00
66 28 my $count = scalar(@_);
67 28 my @sections = ();
68 #undef, 0 or empty array returns nothing as requested
69 28 ▶ if ($n > 0 and $count > 0) {
Branch: 1 branch
BranchTrueFalseTotal
if ($n > 0 and $count > 0) 8 20 28
Condition100%3/3
$n > 0 and $count > 0
!ll&&!rl&&r
1288
MC/DC100%2/2
$n > 0 and $count > 0
$n > 0 $count > 0
Truth table100%3/3
A and B
A= $n > 0B= $count > 0
ABresult
0X0
100
111
70 8 ▶ $n=$count if $n > $count;
Branch: 1 branch
BranchTrueFalseTotal
if $n > $count 2 6 8
71 8 my $i=0;
72 8 ▶ @sections=part {int($i++ * $n / $count)} @_; #Each partition created is a reference to an array.
Subroutine __ANON__: called CC=1 SCAR=0.0
73 }
74 28 ▶ return wantarray ? @sections : \@sections;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 14 14 28
75 }
76  
77 =head2 spart (not exported by default)
78  
79 Cut or divides a list into parts each of size N.
80  
81 Returns an array of array references given a scalar size and a list.
82  
83 my @parts=spart(4, 1 .. 17); #returns ([1,2,3,4],[5,6,7,8],[9,10,11,12],[13,14,15,16],[17]);
84 my $parts=spart(4, 1 .. 17); #returns [[1,2,3,4],[5,6,7,8],[9,10,11,12],[13,14,15,16],[17]];
85  
86 Note: The last array reference may be short.
87  
88 =cut
89  
90 28 ▶sub spart {
Subroutine spart: called CC=4 SCAR=13.9
Pod documented
91 28 ▶ my $parts = shift || 0;
Condition100%2/2
shift() || 0
l!l
1612
MC/DC100%1/1
shift() || 0
shift()
Truth table100%2/2
A
A= shift()
Aresult
11
00
92 28 my @deck = ();
93 #undef, 0 or empty array returns nothing as requested
94 28 ▶ if ($parts > 0) {
Branch: 1 branch
BranchTrueFalseTotal
if ($parts > 0) 16 12 28
95 16 my $i = 0;
96 16 ▶ @deck = part {int($i++ / $parts)} @_; #/#Each partition created is a reference to an array.
Subroutine __ANON__: called CC=1 SCAR=0.0
97 }
98 28 ▶ return wantarray ? @deck : \@deck;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 14 14 28
99 }
100  
101 =head2 deal (not exported by default)
102  
103 Deals a list into hands
104  
105 Returns an array of array references given a scalar size and a list.
106  
107 my @hands=deal(4, 1 .. 17); #returns ([1,5,9,13,17],[2,6,10,14],[3,7,11,15],[4,8,12,16]);
108  
109 =cut
110  
111 28 ▶sub deal {
Subroutine deal: called CC=4 SCAR=13.9
Pod documented
112 28 ▶ my $hands = shift || 0;
Condition100%2/2
shift() || 0
l!l
1612
MC/DC100%1/1
shift() || 0
shift()
Truth table100%2/2
A
A= shift()
Aresult
11
00
113 28 my @deck = ();
114 #undef, 0 or empty array returns nothing as requested
115 28 ▶ if ($hands > 0) {
Branch: 1 branch
BranchTrueFalseTotal
if ($hands > 0) 16 12 28
116 16 my $hand = 0;
117 16 ▶ @deck=part {$hand=0 if $hand>=$hands; $hand++;} @_;
Subroutine __ANON__: called CC=2 SCAR=6.9
Branch: 1 branch
BranchTrueFalseTotal
if $hand >= $hands 12 40 52
118 }
119 28 ▶ return wantarray ? @deck : \@deck;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 14 14 28
120 }
121  
122 =head1 LIMITATIONS
123  
124 my @sections=nsect($n => @list);
125  
126 The nsect function will ALWAYS return an array (array reference in scalar context). So, that you can always pass the return directly into a foreach loop without the need to test for edge cases. However, I made the executive decision that if $n > scalar(@list) the returned array, @sections, is not $n in size but rather scalar(@list) in size.
127  
128 my @sections=nsect(100, "a", "b", "c"); #scalar(@sections) == 3 != 100;
129  
130 =head1 BUGS
131  
132 Please open an issue on GitHub
133  
134 =head1 AUTHOR
135  
136 Michael R. Davis
137  
138 =head1 COPYRIGHT
139  
140 MIT License
141  
142 Copyright (c) 2022 Michael R. Davis
143  
144 =head1 SEE ALSO
145  
146 L<List::MoreUtils> part and natatime, L<Array::Group>, L<List::UtilsBy> bundle_by, L<http://www.perlmonks.org/?no^de_id=516499>, L<http://www.perlmonks.org/?node_id=861938>, L<Parallel::ForkManager>
147  
148 =cut
149  
150 6 1;
↑ Summary