List/Objects/WithUtils/Role/Hash.pm

filter: Statementstmt 98.2% 170 / 173 Branchbran 90.6% 29 / 32 Conditioncond 80.0% 8 / 10 MC/DCmcdc 50.0% 3 / 6 Subroutinesub 96.1% 50 / 52 Podpod 94.4% 34 / 36 totaltotal 95.1% 294 / 309 SCAR 30.9
CC
22
Cov
96%
get_or_else
4.0
get_path
4.0
new
3.0
CRAP 22.0
« List/Objects/WithUtils/Array/Junction.pm ↑ Summary List/Objects/WithUtils.pm »
1 package List::Objects::WithUtils::Role::Hash;
2 136 $List::Objects::WithUtils::Role::Hash::VERSION = '2.028002';
3 136 ▶use strictures 2;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 136 ▶use Module::Runtime ();
Subroutine BEGIN: called CC=1 SCAR=0.0
6 136 ▶use Scalar::Util ();
Subroutine BEGIN: called CC=1 SCAR=0.0
7 136 ▶use List::Util ();
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 =for Pod::Coverage HASH_TYPE blessed_or_pkg
10  
11 =cut
12  
13 sub HASH_TYPE () { 'List::Objects::WithUtils::Hash' }
14 sub blessed_or_pkg {
15 54 ▶ Scalar::Util::blessed($_[0]) ?
Subroutine blessed_or_pkg: called CC=2 SCAR=6.9
Pod undocumented
Branch: 1 branch
BranchTrueFalseTotal
builtin::blessed($_[0]) ? : 39 15 54
16 $_[0] : Module::Runtime::use_module(HASH_TYPE)
17 }
18  
19 136 ▶use Role::Tiny;
Subroutine BEGIN: called CC=1 SCAR=0.0
20  
21 116 ▶sub array_type { 'List::Objects::WithUtils::Array' }
Subroutine array_type: called CC=1 SCAR=0.0
Pod documented
22 4 ▶sub inflated_type { 'List::Objects::WithUtils::Hash::Inflated' }
Subroutine inflated_type: called CC=1 SCAR=0.0
Pod documented
23 2 ▶sub inflated_rw_type { 'List::Objects::WithUtils::Hash::Inflated::RW' }
Subroutine inflated_rw_type: called CC=1 SCAR=0.0
Pod documented
24  
25 =for Pod::Coverage TO_JSON TO_ZPL damn type
26  
27 =cut
28  
29 0 ▶sub is_mutable { 1 }
Subroutine is_mutable: not called CC=1 SCAR=6.9
Pod documented
30 0 ▶sub is_immutable { ! $_[0]->is_mutable }
Subroutine is_immutable: not called CC=1 SCAR=6.9
Pod documented
31  
32 ▶sub type { }
Subroutine type: called CC=1 SCAR=0.0
Pod undocumented
33  
34 136 our %Required;
35 sub new {
36 67 ▶ my $arraytype = $_[0]->array_type;
Subroutine new: called CC=3 SCAR=11.0
Pod documented
37 $Required{$arraytype} = Module::Runtime::require_module($arraytype)
38 67 ▶ unless exists $Required{$arraytype};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $List::Objects::WithUtils::Role::Hash::Required{$arraytype} 43 24 67
39 67 ▶ bless +{ @_[1 .. $#_] }, Scalar::Util::blessed($_[0]) || $_[0]
Condition66%2/3
builtin::blessed($_[0]) || $_[0]
l!l&&r!l&&!r
9580
MC/DC0%0/2
builtin::blessed($_[0]) || $_[0]
builtin::blessed($_[0]) $_[0]
Truth table66%2/3
A || B
A= builtin::blessed($_[0])B= $_[0]
ABresult
1X1
011
000
40 }
41  
42 13 ▶sub export { %{ $_[0] } }
Subroutine export: called CC=1 SCAR=0.0
Pod documented
43 13 ▶sub unbless { +{ %{ $_[0] } } }
Subroutine unbless: called CC=1 SCAR=0.0
Pod documented
44  
45 136 ▶{ no warnings 'once';
Subroutine BEGIN: called CC=1 SCAR=0.0
46 136 *TO_JSON = *unbless;
47 136 *TO_ZPL = *unbless;
48 136 *damn = *unbless;
49 }
50  
51 1 ▶sub clear { %{ $_[0] } = (); $_[0] }
Subroutine clear: called CC=1 SCAR=0.0
Pod documented
52  
53 =for Pod::Coverage untyped
54  
55 =cut
56  
57 4 ▶sub copy { blessed_or_pkg($_[0])->new(%{ $_[0] }) }
Subroutine copy: called CC=1 SCAR=0.0
Pod documented
58 136 ▶{ no warnings 'once'; *untyped = *copy; }
Subroutine BEGIN: called CC=1 SCAR=0.0
59  
60 sub inflate {
61 3 ▶ my ($self, %params) = @_;
Subroutine inflate: called CC=2 SCAR=6.9
Pod documented
62 3 ▶ my $type = $params{rw} ? 'inflated_rw_type' : 'inflated_type';
Branch: 1 branch
BranchTrueFalseTotal
$params{'rw'} ? : 1 2 3
63 3 my $cls = blessed_or_pkg($self);
64 3 Module::Runtime::require_module( $cls->$type );
65 3 $cls->$type->new( %$self )
66 }
67  
68 6 ▶sub defined { CORE::defined $_[0]->{ $_[1] } }
Subroutine defined: called CC=1 SCAR=0.0
Pod documented
69 10 ▶sub exists { CORE::exists $_[0]->{ $_[1] } }
Subroutine exists: called CC=1 SCAR=0.0
Pod documented
70  
71 4 ▶sub is_empty { ! keys %{ $_[0] } }
Subroutine is_empty: called CC=1 SCAR=0.0
Pod documented
72  
73 sub get {
74 44 ▶ if (@_ > 2) {
Subroutine get: called CC=2 SCAR=6.9
Pod documented
Branch: 1 branch
BranchTrueFalseTotal
if (@_ > 2) 2 42 44
75 return blessed_or_pkg($_[0])->array_type->new(
76 2 @{ $_[0] }{ @_[1 .. $#_] }
77 )
78 }
79 42 $_[0]->{ $_[1] }
80 }
81  
82 sub get_or_else {
83 10 ▶ exists $_[0]->{ $_[1] } ? $_[0]->{ $_[1] }
Subroutine get_or_else: called CC=4 SCAR=13.9
Pod documented
Branch: 2 branches
BranchTrueFalseTotal
exists $_[0]{$_[1]} ? : 4 6 10
(builtin::reftype($_[2]) || '') eq 'CODE' ? : 2 4 6
Condition100%2/2
builtin::reftype($_[2]) || ''
l!l
24
MC/DC100%1/1
builtin::reftype($_[2]) || ''
builtin::reftype($_[2])
Truth table100%2/2
A
A= builtin::reftype($_[2])
Aresult
11
00
84 : (Scalar::Util::reftype $_[2] || '') eq 'CODE' ? $_[2]->(@_[0,1])
85 : $_[2]
86 }
87  
88 sub get_path {
89 11 ▶ my $ref = $_[0];
Subroutine get_path: called CC=4 SCAR=13.9
Pod documented
90 11 for my $part (@_[1 .. $#_]) {
91 25 ▶ $ref = ref $part eq 'ARRAY' ? $ref->[ $part->[0] ] : $ref->{$part};
Branch: 1 branch
BranchTrueFalseTotal
ref $part eq 'ARRAY' ? : 2 23 25
92 23 ▶ return undef unless defined $ref;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $ref 3 20 23
93 }
94 $ref
95 6 }
96  
97 =for Pod::Coverage slice
98  
99 =cut
100  
101 136 ▶{ no warnings 'once'; *slice = *sliced; }
Subroutine BEGIN: called CC=1 SCAR=0.0
102 136 { local $@;
103 136 ▶ if ($] >= 5.020) {
Branch: 1 branch
BranchTrueFalseTotal
if ($] >= 5.02) { } 136 0 136
104 4 ▶ eval q[
Subroutine sliced: called CC=1 SCAR=0.0
Pod documented
105 sub sliced {
106 blessed_or_pkg($_[0])->new(
107 %{ $_[0] }{ grep {; exists $_[0]->{$_} } @_[1 .. $#_] }
108 )
109 }
110 ];
111 } else {
112 0 eval q[
113 sub sliced {
114 blessed_or_pkg($_[0])->new(
115 map {; exists $_[0]->{$_} ? ($_ => $_[0]->{$_}) : () }
116 @_[1 .. $#_]
117 )
118 }
119 ];
120 }
121 136 ▶ die "installing sub 'sliced' died: $@" if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 136 136
122 }
123  
124 sub set {
125 9 ▶ my $self = shift;
Subroutine set: called CC=3 SCAR=11.0
Pod documented
126 9 my (@keysidx, @valsidx);
127 9 ▶ $_ % 2 ? push @valsidx, $_ : push @keysidx, $_ for 0 .. $#_;
Branch: 1 branch
BranchTrueFalseTotal
$_ % 2 ? : 13 13 26
128 9 @{$self}{ @_[@keysidx] } = @_[@valsidx];
129 8 $self
130 }
131  
132 sub maybe_set {
133 2 ▶ my $self = shift;
Subroutine maybe_set: called CC=3 SCAR=11.0
Pod documented
134 2 for (grep {; not $_ % 2 } 0 .. $#_) {
135 6 ▶ $self->{ $_[$_] } = $_[$_ + 1] unless exists $self->{ $_[$_] }
Branch: 1 branch
BranchTrueFalseTotal
unless exists $$self{$_[$_]} 2 4 6
136 }
137 $self
138 2 }
139  
140 sub delete {
141 blessed_or_pkg($_[0])->array_type->new(
142 4 ▶ CORE::delete @{ $_[0] }{ @_[1 .. $#_] }
Subroutine delete: called CC=1 SCAR=0.0
Pod documented
143 )
144 }
145  
146 sub keys {
147 blessed_or_pkg($_[0])->array_type->new(
148 10 ▶ CORE::keys %{ $_[0] }
Subroutine keys: called CC=1 SCAR=0.0
Pod documented
149 )
150 }
151  
152 sub values {
153 blessed_or_pkg($_[0])->array_type->new(
154 2 ▶ CORE::values %{ $_[0] }
Subroutine values: called CC=1 SCAR=0.0
Pod documented
155 )
156 }
157  
158 sub intersection {
159 3 ▶ my %seen; my %inner;
Subroutine intersection: called CC=1 SCAR=0.0
Pod documented
160 blessed_or_pkg($_[0])->array_type->new(
161 8 grep {; not $seen{$_}++ }
162 3 grep {; ++$inner{$_} > $#_ } map {; CORE::keys %$_ } @_
163 )
164 }
165  
166 sub diff {
167 3 ▶ my %seen; my %inner;
Subroutine diff: called CC=2 SCAR=6.9
Pod documented
168 3 my @vals = map {; CORE::keys %$_ } @_;
169 3 $seen{$_}++ for @vals;
170 blessed_or_pkg($_[0])->array_type->new(
171 19 grep {; $seen{$_} != @_ }
172 3 grep {; not $inner{$_}++ } @vals
173 )
174 }
175  
176 sub iter {
177 3 ▶ my @list = %{ $_[0] };
Subroutine iter: called CC=1 SCAR=0.0
Pod documented
178 9 ▶ sub { splice @list, 0, 2 }
Subroutine __ANON__: called CC=1 SCAR=0.0
179 3 }
180  
181 sub kv {
182 blessed_or_pkg($_[0])->array_type->new(
183 2 ▶ map {; [ $_, $_[0]->{ $_ } ] } CORE::keys %{ $_[0] }
Subroutine kv: called CC=1 SCAR=0.0
Pod documented
184 )
185 }
186  
187 sub kv_sort {
188 8 ▶ if (defined $_[1] && (my $cb = $_[1])) {
Subroutine kv_sort: called CC=3 SCAR=11.0
Pod documented
Branch: 1 branch
BranchTrueFalseTotal
if (defined $_[1] and my $cb = $_[1]) 4 4 8
Condition66%2/3
defined $_[1] and my $cb = $_[1]
!ll&&!rl&&r
404
MC/DC50%1/2
defined $_[1] and my $cb = $_[1]
defined $_[1] my $cb = $_[1]
Truth table66%2/3
A and B
A= defined $_[1]B= my $cb = $_[1]
ABresult
0X0
100
111
189 4 my $pkg = caller;
190 136 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
191 return blessed_or_pkg($_[0])->array_type->new(
192 11 map {; [ $_, $_[0]->{ $_ } ] } sort {;
193 13 local (*{"${pkg}::a"}, *{"${pkg}::b"}) = (\$a, \$b);
194 13 $a->$cb($b)
195 4 } CORE::keys %{ $_[0] }
196 )
197 }
198 blessed_or_pkg($_[0])->array_type->new(
199 4 map {; [ $_, $_[0]->{ $_ } ] } sort( CORE::keys %{ $_[0] } )
200 )
201 }
202  
203 sub kv_map {
204 3 ▶ my ($self, $cb) = @_;
Subroutine kv_map: called CC=1 SCAR=0.0
Pod documented
205 3 my $pkg = caller;
206 136 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
207 blessed_or_pkg($self)->array_type->new(
208 List::Util::pairmap {;
209 9 ▶ local (*{"${pkg}::a"}, *{"${pkg}::b"}) = (\$a, \$b);
Subroutine __ANON__: called CC=1 SCAR=0.0
210 9 $a->$cb($b)
211 3 } %$self
212 )
213 }
214  
215 sub kv_grep {
216 3 ▶ my ($self, $cb) = @_;
Subroutine kv_grep: called CC=1 SCAR=0.0
Pod documented
217 3 my $pkg = caller;
218 136 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
219 blessed_or_pkg($self)->new(
220 List::Util::pairgrep {;
221 9 ▶ local (*{"${pkg}::a"}, *{"${pkg}::b"}) = (\$a, \$b);
Subroutine __ANON__: called CC=1 SCAR=0.0
222 9 $a->$cb($b)
223 3 } %$self
224 )
225 }
226  
227 =for Pod::Coverage invert
228  
229 =cut
230  
231 sub inverted {
232 3 ▶ my ($self) = @_;
Subroutine inverted: called CC=1 SCAR=0.0
Pod documented
233 3 my $cls = blessed_or_pkg($self);
234 3 my %new;
235 List::Util::pairmap {;
236 exists $new{$b} ?
237 12 ▶ $new{$b}->push($a) : ( $new{$b} = $cls->array_type->new($a) )
Subroutine __ANON__: called CC=2 SCAR=6.9
Branch: 1 branch
BranchTrueFalseTotal
exists $new{$b} ? : 2 10 12
238 3 } %$self;
239 3 $cls->new(%new)
240 }
241 136 ▶{ no warnings 'once'; *invert = *inverted; }
Subroutine BEGIN: called CC=1 SCAR=0.0
242  
243  
244 sub random_kv {
245 2 ▶ my $key = (CORE::keys %{ $_[0] })[rand CORE::keys %{ $_[0] }];
Subroutine random_kv: called CC=2 SCAR=6.9
Pod documented
246 2 ▶ $key ? [ $key => $_[0]->{$key} ] : undef
Branch: 1 branch
BranchTrueFalseTotal
$key ? : 1 1 2
247 }
248  
249 sub random_key {
250 2 ▶ (CORE::keys %{ $_[0] })[rand (CORE::keys %{ $_[0] } || return undef)]
Subroutine random_key: called CC=2 SCAR=6.9
Pod documented
Condition100%2/2
CORE::keys %{$_[0];} || (return undef)
l!l
11
MC/DC100%1/1
CORE::keys %{$_[0];} || (return undef)
CORE::keys %{$_[0];}
Truth table100%2/2
A
A= CORE::keys %{$_[0];}
Aresult
11
00
251 }
252  
253 sub random_value {
254 2 ▶ [@_ = %{ $_[0] }]->[1|rand @_]
Subroutine random_value: called CC=1 SCAR=0.0
Pod documented
255 }
256  
257  
258 136 ▶print
Branch: 1 branch
BranchTrueFalseTotal
unless caller 0 136 136
259 qq[<Su-Shee> huf: I learned that from toyota via agile blahblah,],
260 qq[ it's asking the five "why" questions.\n],
261 qq[<mauke> WHY WHY WHY WHY GOD WHY\n]
262 unless caller;
263 136 1;
264  
265  
266 =pod
267  
268 =head1 NAME
269  
270 List::Objects::WithUtils::Role::Hash - Hash manipulation methods
271  
272 =head1 SYNOPSIS
273  
274 ## Via List::Objects::WithUtils::Hash ->
275 use List::Objects::WithUtils 'hash';
276  
277 my $hash = hash(foo => 'bar');
278  
279 $hash->set(
280 foo => 'baz',
281 pie => 'tasty',
282 );
283  
284 my @matches = $hash->keys->grep(sub { $_[0] =~ /foo/ })->all;
285  
286 my $pie = $hash->get('pie')
287 if $hash->exists('pie');
288  
289 for my $pair ( $hash->kv->all ) {
290 my ($key, $val) = @$pair;
291 ...
292 }
293  
294 my $obj = $hash->inflate;
295 my $foo = $obj->foo;
296  
297 ## As a Role ->
298 use Role::Tiny::With;
299 with 'List::Objects::WithUtils::Role::Hash';
300  
301 =head1 DESCRIPTION
302  
303 A L<Role::Tiny> role defining methods for creating and manipulating HASH-type
304 objects.
305  
306 In addition to the methods documented below, these objects provide a
307 C<TO_JSON> method exporting a plain HASH-type reference for convenience when
308 feeding L<JSON::Tiny> or similar, as well as a C<TO_ZPL> method for
309 compatibility with L<Text::ZPL>.
310  
311 =head2 Basic hash methods
312  
313 =head3 new
314  
315 Constructs a new HASH-type object.
316  
317 =head3 copy
318  
319 Creates a shallow clone of the current object.
320  
321 =head3 defined
322  
323 if ( $hash->defined($key) ) { ... }
324  
325 Returns boolean true if the key has a defined value.
326  
327 =head3 exists
328  
329 if ( $hash->exists($key) ) { ... }
330  
331 Returns boolean true if the key exists.
332  
333 =head3 export
334  
335 my %hash = $hash->export;
336  
337 Returns a raw key => value list.
338  
339 For a plain HASH-type reference, see: L</unbless>
340  
341 =head3 array_type
342  
343 The class name of array-type objects that will be used to contain the results
344 of methods returning a list.
345  
346 Defaults to L<List::Objects::WithUtils::Array>.
347  
348 Subclasses can override C<array_type> to produce different types of array
349 objects.
350  
351 =head3 inflate
352  
353 my $obj = hash(foo => 'bar', baz => 'quux')->inflate;
354 my $baz = $obj->baz;
355  
356 Inflates the hash-type object into a simple struct-like object with accessor
357 methods matching the keys of the hash.
358  
359 By default, accessors are read-only; specifying C<rw => 1> allows setting new
360 values:
361  
362 my $obj = hash(foo => 'bar', baz => 'quux')->inflate(rw => 1);
363 $obj->foo('frobulate');
364  
365 Returns an L</inflated_type> (or L</inflated_rw_type>) object.
366  
367 The default objects provide a C<DEFLATE> method returning a
368 plain hash; this makes it easy to turn inflated objects back into a C<hash()>
369 for modification:
370  
371 my $first = hash( foo => 'bar', baz => 'quux' )->inflate;
372 my $second = hash( $first->DEFLATE, frobulate => 1 )->inflate;
373  
374 =head3 inflated_type
375  
376 The class that objects are blessed into when calling L</inflate>.
377  
378 Defaults to L<List::Objects::WithUtils::Hash::Inflated>.
379  
380 =head3 inflated_rw_type
381  
382 The class that objects are blessed into when calling L</inflate> with
383 C<rw => 1> specified.
384  
385 Defaults to L<List::Objects::WithUtils::Hash::Inflated::RW>, a subclass of
386 L<List::Objects::WithUtils::Hash::Inflated>.
387  
388 =head3 is_empty
389  
390 Returns boolean true if the hash has no keys.
391  
392 =head3 is_mutable
393  
394 Returns boolean true if the hash is mutable; immutable subclasses can override
395 to provide a negative value.
396  
397 =head3 is_immutable
398  
399 The opposite of L</is_mutable>.
400  
401 =head3 unbless
402  
403 Returns a plain C<HASH> reference (shallow clone).
404  
405 =head2 Methods that manipulate the hash
406  
407 =head3 clear
408  
409 Clears the current hash entirely.
410  
411 Returns the (same, but now empty) hash object.
412  
413 =head3 delete
414  
415 $hash->delete(@keys);
416  
417 Deletes the given key(s) from the hash.
418  
419 Returns an L</array_type> object containing the deleted values.
420  
421 =head3 set
422  
423 $hash->set(
424 key1 => $val,
425 key2 => $other,
426 )
427  
428 Sets keys in the hash.
429  
430 Returns the current hash object.
431  
432 =head3 maybe_set
433  
434 my $hash = hash(foo => 1, bar => 2, baz => 3);
435 $hash->maybe_set(foo => 2, bar => 3, quux => 4);
436 # $hash = +{ foo => 1, bar => 2, baz => 3, quux => 4 }
437  
438 Like L</set>, but only sets values that do not already exist in the hash.
439  
440 Returns the current hash object.
441  
442 =head2 Methods that retrieve items
443  
444 =head3 get
445  
446 my $val = $hash->get($key);
447 my @vals = $hash->get(@keys)->all;
448  
449 Retrieves a key or list of keys from the hash.
450  
451 If taking a slice (multiple keys were specified), values are returned
452 as an L</array_type> object. (See L</sliced> if you'd rather generate a new
453 hash.)
454  
455 =head3 get_path
456  
457 my $hash = hash(
458 foo => +{ bar => +{ baz => 'bork' } },
459 quux => [ +{ weeble => 'snork' } ],
460 );
461 my $item = $hash->get_path(qw/foo bar baz/); # 'bork'
462  
463 Attempt to retrieve a value from a 'deep' hash (without risking
464 autovivification).
465  
466 If an element of the given path is a (plain) array reference, as in this
467 example:
468  
469 my $item = $hash->get_path('quux', [1], 'weeble'); # "snork"
470  
471 ... then it is taken as the index of an array or array-type object in the
472 path.
473  
474 Returns undef if any of the path elements are nonexistant.
475
476 An exception is thrown if an invalid access is attempted, such as trying to
477 use a hash-type object as if it were an array.
478  
479 (Available from v2.15.1)
480  
481 =head3 get_or_else
482  
483 # Expect to find an array() obj at $key in $hash,
484 # or create an empty one if $key doesn't exist:
485 my @all = $hash->get_or_else($key => array)->all;
486  
487 # Or pass a coderef
488 # First arg is the object being operated on
489 # Second arg is the requested key
490 my $item = $hash->get_or_else($key => sub { shift->get($defaultkey) });
491  
492 Retrieves a key from the hash; optionally takes a second argument that is used
493 as a default value if the given key does not exist in the hash.
494  
495 If the second argument is a coderef, it is invoked on the object (with the
496 requested key as an argument) and its return value is taken as the default
497 value.
498  
499 =head3 keys
500  
501 my @keys = $hash->keys->all;
502  
503 Returns the list of keys in the hash as an L</array_type> object.
504  
505 =head3 values
506  
507 my @vals = $hash->values->all;
508  
509 Returns the list of values in the hash as an L</array_type> object.
510  
511 =head3 inverted
512  
513 my $hash = hash(
514 a => 1,
515 b => 2,
516 c => 2,
517 d => 3
518 );
519 my $newhash = $hash->inverted;
520 # $newhash = +{
521 # 1 => array('a'),
522 # 2 => array('b', 'c'),
523 # 3 => array('d'),
524 # }
525  
526 Inverts the hash; the values of the original hash become keys in the new
527 object. Their corresponding values are L</array_type> objects containing the
528 key(s) that mapped to the original value.
529  
530 This is a bit like reversing the hash, but lossless with regards to non-unique
531 values.
532  
533 (Available from v2.14.1)
534  
535 =head3 iter
536  
537 my $iter = $hash->iter;
538 while (my ($key, $val) = $iter->()) {
539 # ...
540 }
541  
542 Returns an iterator that, when called, returns ($key, $value) pairs.
543 When the list is exhausted, an empty list is returned.
544  
545 The iterator operates on a shallow clone of the hash, making it safe to
546 operate on the original hash while using the iterator.
547  
548 (Available from v2.9.1)
549  
550 =head3 kv
551  
552 for my $pair ($hash->kv->all) {
553 my ($key, $val) = @$pair;
554 }
555  
556 Returns an L</array_type> object containing the key/value pairs in the hash,
557 each of which is a two-element (unblessed) ARRAY.
558  
559 =head3 kv_grep
560  
561 my $positive_vals = $hash->kv_grep(sub { $b > 0 });
562  
563 Like C<grep>, but operates on pairs. See L<List::Util/"pairgrep">.
564  
565 Returns a hash-type object consisting of the key/value pairs for which the
566 given block returned true.
567  
568 (Available from v2.21.1)
569  
570 =head3 kv_map
571  
572 # Add 1 to each value, get back an array-type object:
573 my $kvs = hash(a => 2, b => 2, c => 3)
574 ->kv_map(sub { ($a, $b + 1) });
575  
576 Like C<map>, but operates on pairs. See L<List::Util/"pairmap">.
577  
578 Returns an L</array_type> object containing the results of the map.
579  
580 (Available from v2.8.1; in versions prior to v2.20.1, C<$_[0]> and C<$_[1]>
581 must be used in place of C<$a> and C<$b>, respectively.)
582  
583 =head3 kv_sort
584  
585 my $kvs = hash(a => 1, b => 2, c => 3)->kv_sort;
586 # $kvs = array(
587 # [ a => 1 ],
588 # [ b => 2 ],
589 # [ c => 3 ]
590 # )
591  
592 my $reversed = hash(a => 1, b => 2, c => 3)
593 ->kv_sort(sub { $b cmp $a });
594 # Reverse result as above
595  
596 Like L</kv>, but sorted by key. A sort routine can be provided.
597  
598 In versions prior to v2.19.1, C<$_[0]> and C<$_[1]> must be used in place of
599 C<$a> and C<$b>, respectively.
600  
601 =head3 random_kv
602  
603 Returns a random key/value pair from the hash as an C<ARRAY>-type reference.
604  
605 Returns undef if the hash is empty.
606  
607 (Available from v2.28.1)
608  
609 =head3 random_key
610  
611 Returns a random key from the hash.
612  
613 Returns undef if the hash is empty.
614  
615 (Available from v2.28.1)
616  
617 =head3 random_value
618  
619 Returns a random value from the hash.
620  
621 Returns undef if the hash is empty.
622  
623 (Available from v2.28.1)
624  
625 =head3 sliced
626  
627 my $newhash = $hash->sliced(@keys);
628  
629 Returns a new hash object built from the specified set of keys and their
630 respective values.
631  
632 If a given key is not found in the hash, it is omitted from the result (this
633 is different than C<perl-5.20+> hash slice syntax, which sets unknown keys to
634 C<undef> in the slice).
635  
636 If you only need the values, see L</get>.
637  
638 =head2 Methods that compare hashes
639  
640 =head3 intersection
641  
642 my $first = hash(a => 1, b => 2, c => 3);
643 my $second = hash(b => 2, c => 3, d => 4);
644 my $intersection = $first->intersection($second);
645 my @common = $intersection->sort->all;
646  
647 Returns the list of keys common between all given hash-type objects (including
648 the invocant) as an L</array_type> object.
649  
650 =head3 diff
651  
652 The opposite of L</intersection>; returns the list of keys that are not common
653 to all given hash-type objects (including the invocant) as an L</array_type>
654 object.
655  
656 =head1 NOTES FOR CONSUMERS
657  
658 If creating your own consumer of this role, some extra effort is required to
659 make C<$a> and C<$b> work in sort statements without warnings; an example with
660 a custom exported constructor might look something like:
661  
662 package My::Custom::Hash;
663 use strictures 2;
664 require Role::Tiny;
665 Role::Tiny->apply_roles_to_package( __PACKAGE__,
666 qw/
667 List::Objects::WithUtils::Role::Hash
668 My::Custom::Hash::Role
669 /
670 );
671  
672 use Exporter ();
673 our @EXPORT = 'myhash';
674 sub import {
675 my $pkg = caller;
676 { no strict 'refs';
677 ${"${pkg}::a"} = ${"${pkg}::a"};
678 ${"${pkg}::b"} = ${"${pkg}::b"};
679 }
680 goto &Exporter::import
681 }
682  
683 sub myhash { __PACKAGE__->new(@_) }
684  
685 =head1 SEE ALSO
686  
687 L<List::Objects::WithUtils>
688  
689 L<List::Objects::WithUtils::Hash>
690  
691 L<List::Objects::WithUtils::Hash::Immutable>
692  
693 L<List::Objects::WithUtils::Hash::Typed>
694  
695 L<Data::Perl>
696  
697 =head1 AUTHOR
698  
699 Jon Portnoy <avenj@cobaltirc.org>
700  
701 Portions of this code are derived from L<Data::Perl> by Matthew Phillips
702 (CPAN: MATTP), haarg et al
703  
704 Licensed under the same terms as Perl.
705  
706 =cut
« List/Objects/WithUtils/Array/Junction.pm ↑ Summary List/Objects/WithUtils.pm »