| 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
| |||||||||||||||||||||
| 106 | 4 | my ($v) = @_; | |||||||||||||||||||
| 107 | 4 | ▶ | my $r = blessed($v) // return; | ||||||||||||||||||
|
Condition50%1/2
builtin::blessed($v) // (return)
MC/DC0%0/1
builtin::blessed($v) // (return)
builtin::blessed($v)
Truth table50%1/2
A
A= builtin::blessed($v)
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 149 | 1097 | my ($class, $a) = @_; | |||||||||||||||||||
| 150 | 1097 | bless $a, $class; | |||||||||||||||||||
| 151 | 1097 | ▶ | if ($FP::PureArray::immutable) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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
MC/DC0%0/2
ref $proto || $proto
ref $proto
$proto
Truth table33%1/3
A || B
A= ref $protoB= $proto
| |||||||||||||||||||||
| 184 | 3 | ▶ | $null{$class} ||= $class->new_from_array([]) | ||||||||||||||||||
|
Condition66%2/3
$null{$class} ||= $class->new_from_array([])
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([])
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 195 | 0 | my $a = shift; | |||||||||||||||||||
| 196 | 0 | ▶ | carp "is already pure" unless $pure_warned++; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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 | |||||||||||||||||||