lib/FP/PureArray.pm

filter: Statementstmt 87.5% 91 / 104 Branchbran 33.3% 8 / 24 Conditioncond 50.0% 4 / 8 MC/DCmcdc 0.0% 0 / 5 Subroutinesub 85.7% 24 / 28 Podpod 0.0% 0 / 4 totaltotal 73.4% 127 / 173 CC 18 SCAR 11.3
CC
18
Cov
76%
pure
12.0
purearray
6.0
as_sorted_by
6.0
CRAP 3.1
« lib/Chj/NamespaceClean.pm ↑ Summary lib/FP/Path.pm »
1 #
2 # Copyright (c) 2015-2021 Christian Jaeger, copying@christianjaeger.ch
3 #
4 # This is free software, offered under either the same terms as perl 5
5 # or the terms of the Artistic License version 2 or the terms of the
6 # MIT License (Expat version). See the file COPYING.md that came
7 # bundled with this file.
8 #
9  
10 =head1 NAME
11  
12 FP::PureArray
13  
14 =head1 SYNOPSIS
15  
16 1 ▶ use FP::PureArray;
Subroutine BEGIN: called CC=1 SCAR=0.0
17 1 ▶ use FP::Div 'inc';
Subroutine BEGIN: called CC=1 SCAR=0.0
18  
19 my $a = purearray(1,4,5)->map(\&inc);
20 is $a->sum, 13;
21  
22 # can't mutate it:
23 like( (eval { $a->[0]++; 1 } || $@),
24 qr/^Modification of a read-only value attempted/);
25 like( (eval { push @$a, 123; 1 } || $@),
26 qr/^Modification of a read-only value attempted/);
27  
28 is $a->sum, 13;
29  
30 my $b = $a->unsafe_mutable; # efficient but dangerous!
31 $$b[0]++;
32 is $a->sum, 14; # said it was dangerous!
33 is ref($a), 'FP::_::MutableArray';
34 # see FP::MutableArray
35  
36 is( FP::_::PureArray->null == FP::_::PureArray->null, 1);
37  
38 =head1 DESCRIPTION
39  
40 Perl arrays blessed into the `FP::PureArray` package, inheriting from
41 `FP::Abstract::Pure`, and coming with the functions from `FP::Array` as methods.
42  
43 If you hand someone an FP::PureArray you guarantee that you won't
44 mutate it. This might be enforced in the future by making them
45 immutable (todo).
46  
47 =head1 PURITY
48  
49 `PureArray`s are created to be immutable by default, which enforces
50 the functional purity of the API. This can be disabled by setting
51 `$FP::PureArray::immutable` to false when creating them. Only ever use
52 this during development, if at all. If you need to have efficient
53 updates, use another data structure (L<FP::List> suits many cases, or
54 the to-be written L<FP::Vec>, although at that point updates directly
55 on PureArray may be implemented efficiently, too). Or if you're sure
56 making a PureArray mutable again is safe, you can call the
57 `unsafe_mutable` method. Should lexical analysis get implemented in
58 Perl at some point, a method `mutable` could be offered that safely
59 (by way of checking via the reference count that there are no other
60 users) turns a PureArray back into a mutable array.
61  
62 PureArray implements `FP::Abstract::Pure` (`is_pure` from
63 `FP::Predicates` returns true even if instances were made mutable via
64 setting `$FP::PureArray::immutable`). Values returned from
65 `unsafe_mutable` are in a different class which does *not* implement
66 `FP::Abstract::Pure`.
67  
68 =head1 TODO
69  
70 Create alternative implementation that is efficient for updates on big
71 arrays (perhaps to be called FP::Vec, but to be interoperable).
72  
73 =head1 SEE ALSO
74  
75 Implements: L<FP::Abstract::Pure>, L<FP::Abstract::Sequence>,
76 L<FP::Abstract::Equal>, L<FP::Abstract::Show>
77  
78 L<FP::MutableArray>
79  
80 =head1 NOTE
81  
82 This is alpha software! Read the status section in the package README
83 or on the L<website|http://functional-perl.org/>.
84  
85 =cut
86  
87 package FP::PureArray;
88 35 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
89 35 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
90 35 ▶use warnings FATAL => 'uninitialized';
Subroutine BEGIN: called CC=1 SCAR=0.0
91 35 ▶use Exporter "import";
Subroutine BEGIN: called CC=1 SCAR=0.0
92  
93 35 our @EXPORT = qw(is_purearray purearray);
94 35 our @EXPORT_OK = qw(array_clone_to_purearray array_to_purearray);
95 35 our %EXPORT_TAGS = (all => [@EXPORT, @EXPORT_OK]);
96  
97 35 ▶use FP::Interfaces;
Subroutine BEGIN: called CC=1 SCAR=0.0
98 35 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
99 35 ▶use Scalar::Util qw(blessed);
Subroutine BEGIN: called CC=1 SCAR=0.0
100 35 ▶use FP::Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
101  
102 35 our $immutable = 1; # whether new instances are to be immutable
103  
104 4 ▶sub is_purearray {
Subroutine is_purearray: called CC=3 SCAR=11.4
Pod undocumented
105 4 ▶ @_ == 1 or fp_croak_arity 1;
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 or fp_croak_arity(1) 4 0 4
106 4 my ($v) = @_;
107 4 ▶ my $r = blessed($v) // return;
Condition50%1/2
builtin::blessed($v) // (return)
l!l
40
MC/DC0%0/1
builtin::blessed($v) // (return)
builtin::blessed($v)
Truth table50%1/2
A
A= builtin::blessed($v)
Aresult
11
00
108 4 $v->isa("FP::_::PureArray")
109 }
110  
111 333 ▶sub purearray {
Subroutine purearray: called CC=1 SCAR=0.0
Pod undocumented
112 333 FP::_::PureArray->new_from_array([@_])
113 }
114  
115 1 ▶sub array_clone_to_purearray {
Subroutine array_clone_to_purearray: called CC=2 SCAR=7.1
Pod undocumented
116 1 ▶ @_ == 1 or fp_croak_arity 1;
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 or fp_croak_arity(1) 1 0 1
117 1 FP::_::PureArray->new_from_array([@{ $_[0] }])
118 }
119  
120 48 ▶sub array_to_purearray {
Subroutine array_to_purearray: called CC=2 SCAR=7.2
Pod undocumented
121 48 ▶ @_ == 1 or fp_croak_arity 1;
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 or fp_croak_arity(1) 48 0 48
122 48 FP::_::PureArray->new_from_array($_[0])
123 }
124  
125 35 package FP::PureArray::autobox {
126 35 our $AUTOLOAD;
127  
128 13 ▶ sub AUTOLOAD {
Subroutine AUTOLOAD: called CC=2 SCAR=7.2
129 13 my $methodname = $AUTOLOAD;
130 13 $methodname =~ s/.*:://;
131 13 my $v = FP::_::PureArray->new_from_array($_[0]);
132 13 ▶ if (my $m = $v->can($methodname)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $m = $v->can($methodname)) { } 13 0 13
133 13 goto $m
134 } else {
135 0 die "no method '$methodname' found for object: $v";
136 }
137 }
138 }
139  
140 35 package FP::_::PureArray {
141 35 ▶ use base qw(FP::Array::Mixin);
Subroutine BEGIN: called CC=1 SCAR=0.0
142 35 ▶ use FP::Interfaces;
Subroutine BEGIN: called CC=1 SCAR=0.0
143 35 ▶ use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
144 35 ▶ use FP::Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
145 35 ▶ use Chj::NamespaceCleanAbove;
Subroutine BEGIN: called CC=1 SCAR=0.0
146  
147 1097 ▶ sub new_from_array {
Subroutine new_from_array: called CC=4 SCAR=14.1
148 1097 ▶ @_ == 2 or fp_croak_arity 2;
Branch: 1 branch
BranchTrueFalseTotal
@_ == 2 or fp_croak_arity(2) 1097 0 1097
149 1097 my ($class, $a) = @_;
150 1097 bless $a, $class;
151 1097 ▶ if ($FP::PureArray::immutable) {
Branch: 1 branch
BranchTrueFalseTotal
if ($FP::PureArray::immutable) 1097 0 1097
152 1097 Internals::SvREADONLY $_, 1 for @$a;
153 1097 Internals::SvREADONLY @$a, 1;
154 }
155 $a
156 1097 }
157  
158 0 ▶ sub purearray {
Subroutine purearray: not called CC=2 SCAR=17.9
159 0 ▶ @_ == 1 or fp_croak_arity 1;
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 or fp_croak_arity(1) 0 0 0
160 0 my $s = shift;
161 0 $s
162 }
163  
164 0 ▶ sub as_sorted_by {
Subroutine as_sorted_by: not called CC=2 SCAR=17.9
165 0 ▶ @_ == 2 or fp_croak_arity 2;
Branch: 1 branch
BranchTrueFalseTotal
@_ == 2 or fp_croak_arity(2) 0 0 0
166 0 my ($s, $cmp) = @_;
167 0 require FP::SortedPureArray;
168 0 FP::_::SortedPureArray->new_from_purearray($s, $cmp)
169 }
170  
171 1 ▶ sub mutablearray {
Subroutine mutablearray: called CC=2 SCAR=7.1
172 1 ▶ @_ == 1 or fp_croak_arity 1;
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 or fp_croak_arity(1) 1 0 1
173 1 my $s = shift;
174 1 FP::_::MutableArray->new_from_array([@$s])
175 }
176  
177 # emptyness constructor that works for subclassing (using singletons
178 # for performance (perhaps))
179 35 my %null;
180  
181 3 ▶ sub null {
Subroutine null: called CC=3 SCAR=12.0
182 3 my $proto = shift;
183 3 ▶ my $class = ref($proto) || $proto;
Condition33%1/3
ref $proto || $proto
l!l&&r!l&&!r
030
MC/DC0%0/2
ref $proto || $proto
ref $proto $proto
Truth table33%1/3
A || B
A= ref $protoB= $proto
ABresult
1X1
011
000
184 3 ▶ $null{$class} ||= $class->new_from_array([])
Condition66%2/3
$null{$class} ||= $class->new_from_array([])
l!l&&r!l&&!r
120
MC/DC0%0/2
$null{$class} ||= $class->new_from_array([])
$null{$class} $class->new_from_array([])
Truth table66%2/3
A ||= B
A= $null{$class}B= $class->new_from_array([])
ABresult
1X1
011
000
185 }
186  
187 0 ▶ sub constructor_name {
Subroutine constructor_name: not called CC=1 SCAR=6.9
188 0 "purearray"
189 }
190  
191 35 our $pure_warned = 0;
192  
193 0 ▶ sub pure {
Subroutine pure: not called CC=3 SCAR=24.8
194 0 ▶ @_ == 1 or fp_croak_arity 1;
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 or fp_croak_arity(1) 0 0 0
195 0 my $a = shift;
196 0 ▶ carp "is already pure" unless $pure_warned++;
Branch: 1 branch
BranchTrueFalseTotal
unless $FP::_::PureArray::pure_warned++ 0 0 0
197 0 $a
198 }
199  
200 1 ▶ sub unsafe_mutable {
Subroutine unsafe_mutable: called CC=3 SCAR=11.0
201 1 ▶ @_ == 1 or fp_croak_arity 1;
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 or fp_croak_arity(1) 1 0 1
202 1 my $a = shift;
203 1 Internals::SvREADONLY $_, 0 for @$a;
204 1 Internals::SvREADONLY @$a, 0;
205 1 require FP::MutableArray; # cost?
206 1 bless $a, "FP::_::MutableArray"
207 }
208  
209 35 _END_; # Chj::NamespaceCleanAbove
210  
211 35 FP::Interfaces::implemented qw(
212 FP::Abstract::Pure
213 FP::Abstract::Sequence
214 FP::Abstract::Equal
215 FP::Abstract::Show);
216 }
217  
218 35 1
« lib/Chj/NamespaceClean.pm ↑ Summary lib/FP/Path.pm »