File Coverage

blib/lib/Venus/Hash.pm
Criterion Covered Total %
statement 190 201 94.5
branch 56 86 65.1
condition 3 6 50.0
subroutine 35 43 81.4
pod 29 30 96.6
total 313 366 85.5


line stmt bran cond sub pod time code
1             package Venus::Hash;
2              
3 16     16   381 use 5.018;
  16         59  
4              
5 16     16   116 use strict;
  16         35  
  16         412  
6 16     16   80 use warnings;
  16         36  
  16         485  
7              
8 16     16   88 use Venus::Class 'base', 'with';
  16         37  
  16         120  
9              
10             base 'Venus::Kind::Value';
11              
12             with 'Venus::Role::Mappable';
13              
14             # BUILDERS
15              
16             sub build_args {
17 367     367 0 930 my ($self, $data) = @_;
18              
19 367 50 66     1412 if (keys %$data == 1 && exists $data->{value}) {
20 0         0 return $data;
21             }
22             return {
23 367         1384 value => $data
24             };
25             }
26              
27             # METHODS
28              
29             sub all {
30 2     2 1 7 my ($self, $code) = @_;
31              
32 2         9 my $data = $self->get;
33              
34 2 50   0   9 $code = sub{} if !$code;
35              
36 2         6 my $failed = 0;
37              
38 2         7 for my $index (CORE::keys %$data) {
39 8         17 my $value = $data->{$index};
40              
41 8         10 local $_ = $value;
42 8 50       130 $failed++ if !$code->($index, $value);
43              
44 8 50       23 CORE::last if $failed;
45             }
46              
47 2 50       33 return $failed ? false : true;
48             }
49              
50             sub any {
51 2     2 1 9 my ($self, $code) = @_;
52              
53 2         8 my $data = $self->get;
54              
55 2 50   0   14 $code = sub{} if !$code;
56              
57 2         5 my $found = 0;
58              
59 2         7 for my $index (CORE::keys %$data) {
60 8         15 my $value = $data->{$index};
61              
62 8         12 local $_ = $value;
63 8 50       127 $found++ if $code->($index, $value);
64              
65 8 50       22 CORE::last if $found;
66             }
67              
68 2 50       27 return $found ? true : false;
69             }
70              
71             sub assertion {
72 0     0 1 0 my ($self) = @_;
73              
74 0         0 my $assert = $self->SUPER::assertion;
75              
76 0         0 $assert->clear->expression('hashref');
77              
78 0         0 return $assert;
79             }
80              
81             sub call {
82 2     2 1 10 my ($self, $mapper, $method, @args) = @_;
83              
84 2         9 require Venus::Type;
85              
86             return $self->$mapper(sub{
87 8     8   15 my ($key, $val) = @_;
88              
89 8         44 my $type = Venus::Type->new($val)->deduce;
90              
91 8         29 local $_ = $type;
92              
93 8         44 $key, $type->$method(@args)
94 2         35 });
95             }
96              
97             sub count {
98 3     3 1 11 my ($self) = @_;
99              
100 3         13 my $data = $self->get;
101              
102 3         18 return scalar(CORE::keys(%$data));
103             }
104              
105             sub default {
106 1     1 1 6 return {};
107             }
108              
109             sub delete {
110 1     1 1 3 my ($self, $key) = @_;
111              
112 1         6 my $data = $self->get;
113              
114 1         7 return CORE::delete($data->{$key});
115             }
116              
117             sub each {
118 2     2 1 9 my ($self, $code) = @_;
119              
120 2         7 my $data = $self->get;
121              
122 2 50   0   8 $code = sub{} if !$code;
123              
124 2         5 my $results = [];
125              
126 2         12 for my $index (CORE::sort(CORE::keys(%$data))) {
127 8         13 my $value = $data->{$index};
128              
129 8         12 local $_ = $value;
130 8         130 CORE::push(@$results, $code->($index, $value));
131             }
132              
133 2 50       13 return wantarray ? (@$results) : $results;
134             }
135              
136             sub empty {
137 1     1 1 3 my ($self) = @_;
138              
139 1         5 my $data = $self->get;
140              
141 1         8 CORE::delete(@$data{CORE::keys(%$data)});
142              
143 1         7 return $data;
144             }
145              
146             sub exists {
147 2     2 1 7 my ($self, $key) = @_;
148              
149 2         6 my $data = $self->get;
150              
151 2 100       13 return CORE::exists($data->{$key}) ? true : false;
152             }
153              
154             sub find {
155 83     83 1 179 my ($self, @args) = @_;
156              
157 83         118 my $seen = 0;
158 83         153 my $item = my $data = $self->get;
159              
160 83         257 for (my $i = 0; $i < @args; $i++) {
161 126 100       322 if (ref($item) eq 'ARRAY') {
    50          
162 6 50       43 if ($args[$i] !~ /^\d+$/) {
163 0         0 $item = undef;
164 0         0 $seen = 0;
165 0         0 CORE::last;
166             }
167 6         12 $seen = $args[$i] <= $#{$item};
  6         17  
168 6         22 $item = $item->[$args[$i]];
169             }
170             elsif (ref($item) eq 'HASH') {
171 120         215 $seen = exists $item->{$args[$i]};
172 120         278 $item = $item->{$args[$i]};
173             }
174             else {
175 0         0 $item = undef;
176 0         0 $seen = 0;
177             }
178             }
179              
180 83 100       497 return wantarray ? ($item, int(!!$seen)) : $item;
181             }
182              
183             sub get {
184 300     300 1 510 my ($self, @args) = @_;
185              
186 300 100       958 return $self->value if !@args;
187              
188 4         5 my ($index) = @args;
189              
190 4         14 return $self->value->{$index};
191             }
192              
193             sub grep {
194 3     3 1 10 my ($self, $code) = @_;
195              
196 3         10 my $data = $self->get;
197              
198 3 50   0   22 $code = sub{} if !$code;
199              
200 3         8 my $result = [];
201              
202 3         25 for my $index (CORE::sort(CORE::keys(%$data))) {
203 12         23 my $value = $data->{$index};
204              
205 12         19 local $_ = $value;
206 12 100       140 CORE::push(@$result, $index, $value) if $code->($index, $value);
207             }
208              
209 3 50       35 return wantarray ? (@$result) : $result;
210             }
211              
212             sub iterator {
213 2     2 1 9 my ($self) = @_;
214              
215 2         9 my $data = $self->get;
216 2         7 my @keys = CORE::sort(CORE::keys(%{$data}));
  2         12  
217              
218 2         5 my $i = 0;
219 2         3 my $j = 0;
220              
221             return sub {
222 10 100   10   4157 return undef if $i > $#keys;
223 8 100       43 return wantarray ? ($keys[$j++], $data->{$keys[$i++]}) : $data->{$keys[$i++]};
224             }
225 2         18 }
226              
227             sub keys {
228 1     1 1 4 my ($self) = @_;
229              
230 1         4 my $data = $self->get;
231              
232 1         11 return [CORE::sort(CORE::keys(%$data))];
233             }
234              
235             sub length {
236 1     1 1 4 my ($self) = @_;
237              
238 1         5 return $self->count;
239             }
240              
241             sub list {
242 2     2 1 6 my ($self) = @_;
243              
244 2 100       7 return wantarray ? (%{$self->value}) : scalar(CORE::keys(%{$self->value}));
  1         5  
  1         5  
245             }
246              
247             sub map {
248 3     3 1 12 my ($self, $code) = @_;
249              
250 3         14 my $data = $self->get;
251              
252 3 50   0   18 $code = sub{} if !$code;
253              
254 3         7 my $result = [];
255              
256 3         18 for my $index (CORE::sort(CORE::keys(%$data))) {
257 12         24 my $value = $data->{$index};
258              
259 12         20 local $_ = $value;
260 12         139 CORE::push(@$result, ($code->($index, $value)));
261             }
262              
263 3 50       33 return wantarray ? (@$result) : $result;
264             }
265              
266             sub merge {
267 24     24 1 60 my ($self, @rvalues) = @_;
268              
269 24         87 require Venus;
270              
271 24         36 my $lvalue = {%{$self->get}};
  24         46  
272              
273 24         96 return Venus::merge($lvalue, @rvalues);
274             }
275              
276             sub none {
277 2     2 1 6 my ($self, $code) = @_;
278              
279 2         10 my $data = $self->get;
280              
281 2 50   0   8 $code = sub{} if !$code;
282              
283 2         6 my $found = 0;
284              
285 2         20 for my $index (CORE::sort(CORE::keys(%$data))) {
286 8         13 my $value = $data->{$index};
287              
288 8         10 local $_ = $value;
289 8 50       132 $found++ if $code->($index, $value);
290              
291 8 50       21 CORE::last if $found;
292             }
293              
294 2 50       15 return $found ? false : true;
295             }
296              
297             sub one {
298 2     2 1 9 my ($self, $code) = @_;
299              
300 2         8 my $data = $self->get;
301              
302 2 50   0   9 $code = sub{} if !$code;
303              
304 2         8 my $found = 0;
305              
306 2         12 for my $index (CORE::sort(CORE::keys(%$data))) {
307 8         13 my $value = $data->{$index};
308              
309 8         13 local $_ = $value;
310 8 100       134 $found++ if $code->($index, $value);
311              
312 8 50       25 CORE::last if $found > 1;
313             }
314              
315 2 50       13 return $found == 1 ? true : false;
316             }
317              
318             sub pairs {
319 1     1 1 3 my ($self) = @_;
320              
321 1         5 my $data = $self->get;
322              
323 1         8 my $result = [CORE::map { [$_, $data->{$_}] } CORE::sort(CORE::keys(%$data))];
  4         12  
324              
325 1 50       8 return wantarray ? (@$result) : $result;
326             }
327              
328             sub path {
329 79     79 1 228 my ($self, $path) = @_;
330              
331 79         436 my @path = CORE::grep(/./, CORE::split(/\W/, $path));
332              
333 79 100       264 return wantarray ? ($self->find(@path)) : $self->find(@path);
334             }
335              
336             sub puts {
337 4     4 1 15 my ($self, @args) = @_;
338              
339 4         8 my $result = [];
340              
341 4         16 require Venus::Array;
342              
343 4         16 for (my $i = 0; $i < @args; $i += 2) {
344 13         32 my ($into, $path) = @args[$i, $i+1];
345              
346 13 50       27 next if !defined $path;
347              
348 13         21 my $value;
349             my @range;
350              
351 13 100       27 ($path, @range) = @{$path} if ref $path eq 'ARRAY';
  1         4  
352              
353 13         25 $value = $self->path($path);
354 13 100       34 $value = Venus::Array->new($value)->range(@range) if ref $value eq 'ARRAY';
355              
356 13 100       45 if (ref $into eq 'SCALAR') {
357 11         21 $$into = $value;
358             }
359              
360 13         16 CORE::push @{$result}, $value;
  13         40  
361             }
362              
363 4 50       79 return wantarray ? (@{$result}) : $result;
  0         0  
364             }
365              
366             sub random {
367 1     1 1 4 my ($self) = @_;
368              
369 1         5 my $data = $self->get;
370 1         4 my $keys = [CORE::keys(%$data)];
371              
372 1         3 return $data->{@$keys[rand($#{$keys}+1)]};
  1         49  
373             }
374              
375             sub reset {
376 1     1 1 4 my ($self) = @_;
377              
378 1         4 my $data = $self->get;
379              
380 1         6 @$data{CORE::keys(%$data)} = ();
381              
382 1         5 return $data;
383             }
384              
385             sub reverse {
386 1     1 1 4 my ($self) = @_;
387              
388 1         4 my $data = $self->get;
389              
390 1         3 my $result = {};
391              
392 1         9 for (CORE::grep(CORE::defined($data->{$_}), CORE::sort(CORE::keys(%$data)))) {
393 4         9 $result->{$_} = $data->{$_};
394             }
395              
396 1         12 return {CORE::reverse(%$result)};
397             }
398              
399             sub set {
400 15     15 1 28 my ($self, @args) = @_;
401              
402 15 50       31 return $self->value if !@args;
403              
404 15 50 33     36 return $self->value(@args) if @args == 1 && ref $args[0] eq 'HASH';
405              
406 15         32 my ($index, $value) = @args;
407              
408 15 50       28 return if not defined $index;
409              
410 15         37 return $self->value->{$index} = $value;
411             }
412              
413             sub slice {
414 1     1 1 7 my ($self, @args) = @_;
415              
416 1         6 my $data = $self->get;
417              
418 1         4 return [@{$data}{@args}];
  1         6  
419             }
420              
421             1;
422              
423              
424              
425             =head1 NAME
426              
427             Venus::Hash - Hash Class
428              
429             =cut
430              
431             =head1 ABSTRACT
432              
433             Hash Class for Perl 5
434              
435             =cut
436              
437             =head1 SYNOPSIS
438              
439             package main;
440              
441             use Venus::Hash;
442              
443             my $hash = Venus::Hash->new({1..8});
444              
445             # $hash->random;
446              
447             =cut
448              
449             =head1 DESCRIPTION
450              
451             This package provides methods for manipulating hash data.
452              
453             =cut
454              
455             =head1 INHERITS
456              
457             This package inherits behaviors from:
458              
459             L
460              
461             =cut
462              
463             =head1 INTEGRATES
464              
465             This package integrates behaviors from:
466              
467             L
468              
469             =cut
470              
471             =head1 METHODS
472              
473             This package provides the following methods:
474              
475             =cut
476              
477             =head2 all
478              
479             all(CodeRef $code) (Bool)
480              
481             The all method returns true if the callback returns true for all of the
482             elements.
483              
484             I>
485              
486             =over 4
487              
488             =item all example 1
489              
490             # given: synopsis;
491              
492             my $all = $hash->all(sub {
493             $_ > 1
494             });
495              
496             # 1
497              
498             =back
499              
500             =over 4
501              
502             =item all example 2
503              
504             # given: synopsis;
505              
506             my $all = $hash->all(sub {
507             my ($key, $value) = @_;
508              
509             $value > 1
510             });
511              
512             # 1
513              
514             =back
515              
516             =cut
517              
518             =head2 any
519              
520             any(CodeRef $code) (Bool)
521              
522             The any method returns true if the callback returns true for any of the
523             elements.
524              
525             I>
526              
527             =over 4
528              
529             =item any example 1
530              
531             # given: synopsis;
532              
533             my $any = $hash->any(sub {
534             $_ < 1
535             });
536              
537             # 0
538              
539             =back
540              
541             =over 4
542              
543             =item any example 2
544              
545             # given: synopsis;
546              
547             my $any = $hash->any(sub {
548             my ($key, $value) = @_;
549              
550             $value < 1
551             });
552              
553             # 0
554              
555             =back
556              
557             =cut
558              
559             =head2 call
560              
561             call(Str $iterable, Str $method) (Any)
562              
563             The call method executes the given method (named using the first argument)
564             which performs an iteration (i.e. takes a callback) and calls the method (named
565             using the second argument) on the object (or value) and returns the result of
566             the iterable method.
567              
568             I>
569              
570             =over 4
571              
572             =item call example 1
573              
574             # given: synopsis
575              
576             package main;
577              
578             my $call = $hash->call('map', 'incr');
579              
580             # ['1', 3, '3', 5, '5', 7, '7', 9]
581              
582             =back
583              
584             =over 4
585              
586             =item call example 2
587              
588             # given: synopsis
589              
590             package main;
591              
592             my $call = $hash->call('grep', 'gt', 4);
593              
594             # [5..8]
595              
596             =back
597              
598             =cut
599              
600             =head2 cast
601              
602             cast(Str $kind) (Object | Undef)
603              
604             The cast method converts L<"value"|Venus::Kind::Value> objects between
605             different I<"value"> object types, based on the name of the type provided. This
606             method will return C if the invocant is not a L.
607              
608             I>
609              
610             =over 4
611              
612             =item cast example 1
613              
614             package main;
615              
616             use Venus::Hash;
617              
618             my $hash = Venus::Hash->new;
619              
620             my $cast = $hash->cast('array');
621              
622             # bless({ value => [{}] }, "Venus::Array")
623              
624             =back
625              
626             =over 4
627              
628             =item cast example 2
629              
630             package main;
631              
632             use Venus::Hash;
633              
634             my $hash = Venus::Hash->new;
635              
636             my $cast = $hash->cast('boolean');
637              
638             # bless({ value => 1 }, "Venus::Boolean")
639              
640             =back
641              
642             =over 4
643              
644             =item cast example 3
645              
646             package main;
647              
648             use Venus::Hash;
649              
650             my $hash = Venus::Hash->new;
651              
652             my $cast = $hash->cast('code');
653              
654             # bless({ value => sub { ... } }, "Venus::Code")
655              
656             =back
657              
658             =over 4
659              
660             =item cast example 4
661              
662             package main;
663              
664             use Venus::Hash;
665              
666             my $hash = Venus::Hash->new;
667              
668             my $cast = $hash->cast('float');
669              
670             # bless({ value => "1.0" }, "Venus::Float")
671              
672             =back
673              
674             =over 4
675              
676             =item cast example 5
677              
678             package main;
679              
680             use Venus::Hash;
681              
682             my $hash = Venus::Hash->new;
683              
684             my $cast = $hash->cast('hash');
685              
686             # bless({ value => {} }, "Venus::Hash")
687              
688             =back
689              
690             =over 4
691              
692             =item cast example 6
693              
694             package main;
695              
696             use Venus::Hash;
697              
698             my $hash = Venus::Hash->new;
699              
700             my $cast = $hash->cast('number');
701              
702             # bless({ value => 2 }, "Venus::Number")
703              
704             =back
705              
706             =over 4
707              
708             =item cast example 7
709              
710             package main;
711              
712             use Venus::Hash;
713              
714             my $hash = Venus::Hash->new;
715              
716             my $cast = $hash->cast('regexp');
717              
718             # bless({ value => qr/(?^u:\{\})/ }, "Venus::Regexp")
719              
720             =back
721              
722             =over 4
723              
724             =item cast example 8
725              
726             package main;
727              
728             use Venus::Hash;
729              
730             my $hash = Venus::Hash->new;
731              
732             my $cast = $hash->cast('scalar');
733              
734             # bless({ value => \{} }, "Venus::Scalar")
735              
736             =back
737              
738             =over 4
739              
740             =item cast example 9
741              
742             package main;
743              
744             use Venus::Hash;
745              
746             my $hash = Venus::Hash->new;
747              
748             my $cast = $hash->cast('string');
749              
750             # bless({ value => "{}" }, "Venus::String")
751              
752             =back
753              
754             =over 4
755              
756             =item cast example 10
757              
758             package main;
759              
760             use Venus::Hash;
761              
762             my $hash = Venus::Hash->new;
763              
764             my $cast = $hash->cast('undef');
765              
766             # bless({ value => undef }, "Venus::Undef")
767              
768             =back
769              
770             =cut
771              
772             =head2 count
773              
774             count() (Int)
775              
776             The count method returns the total number of keys defined.
777              
778             I>
779              
780             =over 4
781              
782             =item count example 1
783              
784             # given: synopsis;
785              
786             my $count = $hash->count;
787              
788             # 4
789              
790             =back
791              
792             =cut
793              
794             =head2 default
795              
796             default() (HashRef)
797              
798             The default method returns the default value, i.e. C<{}>.
799              
800             I>
801              
802             =over 4
803              
804             =item default example 1
805              
806             # given: synopsis;
807              
808             my $default = $hash->default;
809              
810             # {}
811              
812             =back
813              
814             =cut
815              
816             =head2 delete
817              
818             delete(Str $key) (Any)
819              
820             The delete method returns the value matching the key specified in the argument
821             and returns the value.
822              
823             I>
824              
825             =over 4
826              
827             =item delete example 1
828              
829             # given: synopsis;
830              
831             my $delete = $hash->delete(1);
832              
833             # 2
834              
835             =back
836              
837             =cut
838              
839             =head2 each
840              
841             each(CodeRef $code) (ArrayRef)
842              
843             The each method executes callback for each element in the hash passing the
844             routine the key and value at the current position in the loop. This method can
845             return a list of values in list-context.
846              
847             I>
848              
849             =over 4
850              
851             =item each example 1
852              
853             # given: synopsis;
854              
855             my $each = $hash->each(sub {
856             [$_]
857             });
858              
859             # [[2], [4], [6], [8]]
860              
861             =back
862              
863             =over 4
864              
865             =item each example 2
866              
867             # given: synopsis;
868              
869             my $each = $hash->each(sub {
870             my ($key, $value) = @_;
871              
872             [$key, $value]
873             });
874              
875             # [[1, 2], [3, 4], [5, 6], [7, 8]]
876              
877             =back
878              
879             =cut
880              
881             =head2 empty
882              
883             empty() (HashRef)
884              
885             The empty method drops all elements from the hash.
886              
887             I>
888              
889             =over 4
890              
891             =item empty example 1
892              
893             # given: synopsis;
894              
895             my $empty = $hash->empty;
896              
897             # {}
898              
899             =back
900              
901             =cut
902              
903             =head2 eq
904              
905             eq(Any $arg) (Bool)
906              
907             The eq method performs an I<"equals"> operation using the argument provided.
908              
909             I>
910              
911             =over 4
912              
913             =item eq example 1
914              
915             package main;
916              
917             use Venus::Array;
918             use Venus::Hash;
919              
920             my $lvalue = Venus::Hash->new;
921             my $rvalue = Venus::Array->new;
922              
923             my $result = $lvalue->eq($rvalue);
924              
925             # 0
926              
927             =back
928              
929             =over 4
930              
931             =item eq example 2
932              
933             package main;
934              
935             use Venus::Code;
936             use Venus::Hash;
937              
938             my $lvalue = Venus::Hash->new;
939             my $rvalue = Venus::Code->new;
940              
941             my $result = $lvalue->eq($rvalue);
942              
943             # 0
944              
945             =back
946              
947             =over 4
948              
949             =item eq example 3
950              
951             package main;
952              
953             use Venus::Float;
954             use Venus::Hash;
955              
956             my $lvalue = Venus::Hash->new;
957             my $rvalue = Venus::Float->new;
958              
959             my $result = $lvalue->eq($rvalue);
960              
961             # 0
962              
963             =back
964              
965             =over 4
966              
967             =item eq example 4
968              
969             package main;
970              
971             use Venus::Hash;
972              
973             my $lvalue = Venus::Hash->new;
974             my $rvalue = Venus::Hash->new;
975              
976             my $result = $lvalue->eq($rvalue);
977              
978             # 1
979              
980             =back
981              
982             =over 4
983              
984             =item eq example 5
985              
986             package main;
987              
988             use Venus::Hash;
989             use Venus::Number;
990              
991             my $lvalue = Venus::Hash->new;
992             my $rvalue = Venus::Number->new;
993              
994             my $result = $lvalue->eq($rvalue);
995              
996             # 0
997              
998             =back
999              
1000             =over 4
1001              
1002             =item eq example 6
1003              
1004             package main;
1005              
1006             use Venus::Hash;
1007             use Venus::Regexp;
1008              
1009             my $lvalue = Venus::Hash->new;
1010             my $rvalue = Venus::Regexp->new;
1011              
1012             my $result = $lvalue->eq($rvalue);
1013              
1014             # 0
1015              
1016             =back
1017              
1018             =over 4
1019              
1020             =item eq example 7
1021              
1022             package main;
1023              
1024             use Venus::Hash;
1025             use Venus::Scalar;
1026              
1027             my $lvalue = Venus::Hash->new;
1028             my $rvalue = Venus::Scalar->new;
1029              
1030             my $result = $lvalue->eq($rvalue);
1031              
1032             # 0
1033              
1034             =back
1035              
1036             =over 4
1037              
1038             =item eq example 8
1039              
1040             package main;
1041              
1042             use Venus::Hash;
1043             use Venus::String;
1044              
1045             my $lvalue = Venus::Hash->new;
1046             my $rvalue = Venus::String->new;
1047              
1048             my $result = $lvalue->eq($rvalue);
1049              
1050             # 0
1051              
1052             =back
1053              
1054             =over 4
1055              
1056             =item eq example 9
1057              
1058             package main;
1059              
1060             use Venus::Hash;
1061             use Venus::Undef;
1062              
1063             my $lvalue = Venus::Hash->new;
1064             my $rvalue = Venus::Undef->new;
1065              
1066             my $result = $lvalue->eq($rvalue);
1067              
1068             # 0
1069              
1070             =back
1071              
1072             =cut
1073              
1074             =head2 exists
1075              
1076             exists(Str $key) (Bool)
1077              
1078             The exists method returns true if the value matching the key specified in the
1079             argument exists, otherwise returns false.
1080              
1081             I>
1082              
1083             =over 4
1084              
1085             =item exists example 1
1086              
1087             # given: synopsis;
1088              
1089             my $exists = $hash->exists(1);
1090              
1091             # 1
1092              
1093             =back
1094              
1095             =over 4
1096              
1097             =item exists example 2
1098              
1099             # given: synopsis;
1100              
1101             my $exists = $hash->exists(0);
1102              
1103             # 0
1104              
1105             =back
1106              
1107             =cut
1108              
1109             =head2 find
1110              
1111             find(Str @data) (Any)
1112              
1113             The find method traverses the data structure using the keys and indices
1114             provided, returning the value found or undef. In list-context, this method
1115             returns a tuple, i.e. the value found and boolean representing whether the
1116             match was successful.
1117              
1118             I>
1119              
1120             =over 4
1121              
1122             =item find example 1
1123              
1124             package main;
1125              
1126             use Venus::Hash;
1127              
1128             my $hash = Venus::Hash->new({'foo' => {'bar' => 'baz'},'bar' => ['baz']});
1129              
1130             my $find = $hash->find('foo', 'bar');
1131              
1132             # "baz"
1133              
1134             =back
1135              
1136             =over 4
1137              
1138             =item find example 2
1139              
1140             package main;
1141              
1142             use Venus::Hash;
1143              
1144             my $hash = Venus::Hash->new({'foo' => {'bar' => 'baz'},'bar' => ['baz']});
1145              
1146             my $find = $hash->find('bar', 0);
1147              
1148             # "baz"
1149              
1150             =back
1151              
1152             =over 4
1153              
1154             =item find example 3
1155              
1156             package main;
1157              
1158             use Venus::Hash;
1159              
1160             my $hash = Venus::Hash->new({'foo' => {'bar' => 'baz'},'bar' => ['baz']});
1161              
1162             my $find = $hash->find('bar');
1163              
1164             # ["baz"]
1165              
1166             =back
1167              
1168             =over 4
1169              
1170             =item find example 4
1171              
1172             package main;
1173              
1174             use Venus::Hash;
1175              
1176             my $hash = Venus::Hash->new({'foo' => {'bar' => 'baz'},'bar' => ['baz']});
1177              
1178             my ($find, $exists) = $hash->find('baz');
1179              
1180             # (undef, 0)
1181              
1182             =back
1183              
1184             =cut
1185              
1186             =head2 ge
1187              
1188             ge(Any $arg) (Bool)
1189              
1190             The ge method performs a I<"greater-than-or-equal-to"> operation using the
1191             argument provided.
1192              
1193             I>
1194              
1195             =over 4
1196              
1197             =item ge example 1
1198              
1199             package main;
1200              
1201             use Venus::Array;
1202             use Venus::Hash;
1203              
1204             my $lvalue = Venus::Hash->new;
1205             my $rvalue = Venus::Array->new;
1206              
1207             my $result = $lvalue->ge($rvalue);
1208              
1209             # 0
1210              
1211             =back
1212              
1213             =over 4
1214              
1215             =item ge example 2
1216              
1217             package main;
1218              
1219             use Venus::Code;
1220             use Venus::Hash;
1221              
1222             my $lvalue = Venus::Hash->new;
1223             my $rvalue = Venus::Code->new;
1224              
1225             my $result = $lvalue->ge($rvalue);
1226              
1227             # 0
1228              
1229             =back
1230              
1231             =over 4
1232              
1233             =item ge example 3
1234              
1235             package main;
1236              
1237             use Venus::Float;
1238             use Venus::Hash;
1239              
1240             my $lvalue = Venus::Hash->new;
1241             my $rvalue = Venus::Float->new;
1242              
1243             my $result = $lvalue->ge($rvalue);
1244              
1245             # 1
1246              
1247             =back
1248              
1249             =over 4
1250              
1251             =item ge example 4
1252              
1253             package main;
1254              
1255             use Venus::Hash;
1256              
1257             my $lvalue = Venus::Hash->new;
1258             my $rvalue = Venus::Hash->new;
1259              
1260             my $result = $lvalue->ge($rvalue);
1261              
1262             # 1
1263              
1264             =back
1265              
1266             =over 4
1267              
1268             =item ge example 5
1269              
1270             package main;
1271              
1272             use Venus::Hash;
1273             use Venus::Number;
1274              
1275             my $lvalue = Venus::Hash->new;
1276             my $rvalue = Venus::Number->new;
1277              
1278             my $result = $lvalue->ge($rvalue);
1279              
1280             # 1
1281              
1282             =back
1283              
1284             =over 4
1285              
1286             =item ge example 6
1287              
1288             package main;
1289              
1290             use Venus::Hash;
1291             use Venus::Regexp;
1292              
1293             my $lvalue = Venus::Hash->new;
1294             my $rvalue = Venus::Regexp->new;
1295              
1296             my $result = $lvalue->ge($rvalue);
1297              
1298             # 0
1299              
1300             =back
1301              
1302             =over 4
1303              
1304             =item ge example 7
1305              
1306             package main;
1307              
1308             use Venus::Hash;
1309             use Venus::Scalar;
1310              
1311             my $lvalue = Venus::Hash->new;
1312             my $rvalue = Venus::Scalar->new;
1313              
1314             my $result = $lvalue->ge($rvalue);
1315              
1316             # 0
1317              
1318             =back
1319              
1320             =over 4
1321              
1322             =item ge example 8
1323              
1324             package main;
1325              
1326             use Venus::Hash;
1327             use Venus::String;
1328              
1329             my $lvalue = Venus::Hash->new;
1330             my $rvalue = Venus::String->new;
1331              
1332             my $result = $lvalue->ge($rvalue);
1333              
1334             # 1
1335              
1336             =back
1337              
1338             =over 4
1339              
1340             =item ge example 9
1341              
1342             package main;
1343              
1344             use Venus::Hash;
1345             use Venus::Undef;
1346              
1347             my $lvalue = Venus::Hash->new;
1348             my $rvalue = Venus::Undef->new;
1349              
1350             my $result = $lvalue->ge($rvalue);
1351              
1352             # 1
1353              
1354             =back
1355              
1356             =cut
1357              
1358             =head2 gele
1359              
1360             gele(Any $arg1, Any $arg2) (Bool)
1361              
1362             The gele method performs a I<"greater-than-or-equal-to"> operation on the 1st
1363             argument, and I<"lesser-than-or-equal-to"> operation on the 2nd argument.
1364              
1365             I>
1366              
1367             =over 4
1368              
1369             =item gele example 1
1370              
1371             package main;
1372              
1373             use Venus::Array;
1374             use Venus::Hash;
1375              
1376             my $lvalue = Venus::Hash->new;
1377             my $rvalue = Venus::Array->new;
1378              
1379             my $result = $lvalue->gele($rvalue);
1380              
1381             # 0
1382              
1383             =back
1384              
1385             =over 4
1386              
1387             =item gele example 2
1388              
1389             package main;
1390              
1391             use Venus::Code;
1392             use Venus::Hash;
1393              
1394             my $lvalue = Venus::Hash->new;
1395             my $rvalue = Venus::Code->new;
1396              
1397             my $result = $lvalue->gele($rvalue);
1398              
1399             # 0
1400              
1401             =back
1402              
1403             =over 4
1404              
1405             =item gele example 3
1406              
1407             package main;
1408              
1409             use Venus::Float;
1410             use Venus::Hash;
1411              
1412             my $lvalue = Venus::Hash->new;
1413             my $rvalue = Venus::Float->new;
1414              
1415             my $result = $lvalue->gele($rvalue);
1416              
1417             # 0
1418              
1419             =back
1420              
1421             =over 4
1422              
1423             =item gele example 4
1424              
1425             package main;
1426              
1427             use Venus::Hash;
1428              
1429             my $lvalue = Venus::Hash->new;
1430             my $rvalue = Venus::Hash->new;
1431              
1432             my $result = $lvalue->gele($rvalue);
1433              
1434             # 0
1435              
1436             =back
1437              
1438             =over 4
1439              
1440             =item gele example 5
1441              
1442             package main;
1443              
1444             use Venus::Hash;
1445             use Venus::Number;
1446              
1447             my $lvalue = Venus::Hash->new;
1448             my $rvalue = Venus::Number->new;
1449              
1450             my $result = $lvalue->gele($rvalue);
1451              
1452             # 0
1453              
1454             =back
1455              
1456             =over 4
1457              
1458             =item gele example 6
1459              
1460             package main;
1461              
1462             use Venus::Hash;
1463             use Venus::Regexp;
1464              
1465             my $lvalue = Venus::Hash->new;
1466             my $rvalue = Venus::Regexp->new;
1467              
1468             my $result = $lvalue->gele($rvalue);
1469              
1470             # 0
1471              
1472             =back
1473              
1474             =over 4
1475              
1476             =item gele example 7
1477              
1478             package main;
1479              
1480             use Venus::Hash;
1481             use Venus::Scalar;
1482              
1483             my $lvalue = Venus::Hash->new;
1484             my $rvalue = Venus::Scalar->new;
1485              
1486             my $result = $lvalue->gele($rvalue);
1487              
1488             # 0
1489              
1490             =back
1491              
1492             =over 4
1493              
1494             =item gele example 8
1495              
1496             package main;
1497              
1498             use Venus::Hash;
1499             use Venus::String;
1500              
1501             my $lvalue = Venus::Hash->new;
1502             my $rvalue = Venus::String->new;
1503              
1504             my $result = $lvalue->gele($rvalue);
1505              
1506             # 0
1507              
1508             =back
1509              
1510             =over 4
1511              
1512             =item gele example 9
1513              
1514             package main;
1515              
1516             use Venus::Hash;
1517             use Venus::Undef;
1518              
1519             my $lvalue = Venus::Hash->new;
1520             my $rvalue = Venus::Undef->new;
1521              
1522             my $result = $lvalue->gele($rvalue);
1523              
1524             # 0
1525              
1526             =back
1527              
1528             =cut
1529              
1530             =head2 grep
1531              
1532             grep(CodeRef $code) (ArrayRef)
1533              
1534             The grep method executes callback for each key/value pair in the hash passing
1535             the routine the key and value at the current position in the loop and returning
1536             a new hash reference containing the elements for which the argument evaluated
1537             true. This method can return a list of values in list-context.
1538              
1539             I>
1540              
1541             =over 4
1542              
1543             =item grep example 1
1544              
1545             # given: synopsis;
1546              
1547             my $grep = $hash->grep(sub {
1548             $_ >= 3
1549             });
1550              
1551             # [3..8]
1552              
1553             =back
1554              
1555             =over 4
1556              
1557             =item grep example 2
1558              
1559             # given: synopsis;
1560              
1561             my $grep = $hash->grep(sub {
1562             my ($key, $value) = @_;
1563              
1564             $value >= 3
1565             });
1566              
1567             # [3..8]
1568              
1569             =back
1570              
1571             =cut
1572              
1573             =head2 gt
1574              
1575             gt(Any $arg) (Bool)
1576              
1577             The gt method performs a I<"greater-than"> operation using the argument provided.
1578              
1579             I>
1580              
1581             =over 4
1582              
1583             =item gt example 1
1584              
1585             package main;
1586              
1587             use Venus::Array;
1588             use Venus::Hash;
1589              
1590             my $lvalue = Venus::Hash->new;
1591             my $rvalue = Venus::Array->new;
1592              
1593             my $result = $lvalue->gt($rvalue);
1594              
1595             # 0
1596              
1597             =back
1598              
1599             =over 4
1600              
1601             =item gt example 2
1602              
1603             package main;
1604              
1605             use Venus::Code;
1606             use Venus::Hash;
1607              
1608             my $lvalue = Venus::Hash->new;
1609             my $rvalue = Venus::Code->new;
1610              
1611             my $result = $lvalue->gt($rvalue);
1612              
1613             # 0
1614              
1615             =back
1616              
1617             =over 4
1618              
1619             =item gt example 3
1620              
1621             package main;
1622              
1623             use Venus::Float;
1624             use Venus::Hash;
1625              
1626             my $lvalue = Venus::Hash->new;
1627             my $rvalue = Venus::Float->new;
1628              
1629             my $result = $lvalue->gt($rvalue);
1630              
1631             # 1
1632              
1633             =back
1634              
1635             =over 4
1636              
1637             =item gt example 4
1638              
1639             package main;
1640              
1641             use Venus::Hash;
1642              
1643             my $lvalue = Venus::Hash->new;
1644             my $rvalue = Venus::Hash->new;
1645              
1646             my $result = $lvalue->gt($rvalue);
1647              
1648             # 0
1649              
1650             =back
1651              
1652             =over 4
1653              
1654             =item gt example 5
1655              
1656             package main;
1657              
1658             use Venus::Hash;
1659             use Venus::Number;
1660              
1661             my $lvalue = Venus::Hash->new;
1662             my $rvalue = Venus::Number->new;
1663              
1664             my $result = $lvalue->gt($rvalue);
1665              
1666             # 1
1667              
1668             =back
1669              
1670             =over 4
1671              
1672             =item gt example 6
1673              
1674             package main;
1675              
1676             use Venus::Hash;
1677             use Venus::Regexp;
1678              
1679             my $lvalue = Venus::Hash->new;
1680             my $rvalue = Venus::Regexp->new;
1681              
1682             my $result = $lvalue->gt($rvalue);
1683              
1684             # 0
1685              
1686             =back
1687              
1688             =over 4
1689              
1690             =item gt example 7
1691              
1692             package main;
1693              
1694             use Venus::Hash;
1695             use Venus::Scalar;
1696              
1697             my $lvalue = Venus::Hash->new;
1698             my $rvalue = Venus::Scalar->new;
1699              
1700             my $result = $lvalue->gt($rvalue);
1701              
1702             # 0
1703              
1704             =back
1705              
1706             =over 4
1707              
1708             =item gt example 8
1709              
1710             package main;
1711              
1712             use Venus::Hash;
1713             use Venus::String;
1714              
1715             my $lvalue = Venus::Hash->new;
1716             my $rvalue = Venus::String->new;
1717              
1718             my $result = $lvalue->gt($rvalue);
1719              
1720             # 1
1721              
1722             =back
1723              
1724             =over 4
1725              
1726             =item gt example 9
1727              
1728             package main;
1729              
1730             use Venus::Hash;
1731             use Venus::Undef;
1732              
1733             my $lvalue = Venus::Hash->new;
1734             my $rvalue = Venus::Undef->new;
1735              
1736             my $result = $lvalue->gt($rvalue);
1737              
1738             # 1
1739              
1740             =back
1741              
1742             =cut
1743              
1744             =head2 gtlt
1745              
1746             gtlt(Any $arg1, Any $arg2) (Bool)
1747              
1748             The gtlt method performs a I<"greater-than"> operation on the 1st argument, and
1749             I<"lesser-than"> operation on the 2nd argument.
1750              
1751             I>
1752              
1753             =over 4
1754              
1755             =item gtlt example 1
1756              
1757             package main;
1758              
1759             use Venus::Array;
1760             use Venus::Hash;
1761              
1762             my $lvalue = Venus::Hash->new;
1763             my $rvalue = Venus::Array->new;
1764              
1765             my $result = $lvalue->gtlt($rvalue);
1766              
1767             # 0
1768              
1769             =back
1770              
1771             =over 4
1772              
1773             =item gtlt example 2
1774              
1775             package main;
1776              
1777             use Venus::Code;
1778             use Venus::Hash;
1779              
1780             my $lvalue = Venus::Hash->new;
1781             my $rvalue = Venus::Code->new;
1782              
1783             my $result = $lvalue->gtlt($rvalue);
1784              
1785             # 0
1786              
1787             =back
1788              
1789             =over 4
1790              
1791             =item gtlt example 3
1792              
1793             package main;
1794              
1795             use Venus::Float;
1796             use Venus::Hash;
1797              
1798             my $lvalue = Venus::Hash->new;
1799             my $rvalue = Venus::Float->new;
1800              
1801             my $result = $lvalue->gtlt($rvalue);
1802              
1803             # 0
1804              
1805             =back
1806              
1807             =over 4
1808              
1809             =item gtlt example 4
1810              
1811             package main;
1812              
1813             use Venus::Hash;
1814              
1815             my $lvalue = Venus::Hash->new;
1816             my $rvalue = Venus::Hash->new;
1817              
1818             my $result = $lvalue->gtlt($rvalue);
1819              
1820             # 0
1821              
1822             =back
1823              
1824             =over 4
1825              
1826             =item gtlt example 5
1827              
1828             package main;
1829              
1830             use Venus::Hash;
1831             use Venus::Number;
1832              
1833             my $lvalue = Venus::Hash->new;
1834             my $rvalue = Venus::Number->new;
1835              
1836             my $result = $lvalue->gtlt($rvalue);
1837              
1838             # 0
1839              
1840             =back
1841              
1842             =over 4
1843              
1844             =item gtlt example 6
1845              
1846             package main;
1847              
1848             use Venus::Hash;
1849             use Venus::Regexp;
1850              
1851             my $lvalue = Venus::Hash->new;
1852             my $rvalue = Venus::Regexp->new;
1853              
1854             my $result = $lvalue->gtlt($rvalue);
1855              
1856             # 0
1857              
1858             =back
1859              
1860             =over 4
1861              
1862             =item gtlt example 7
1863              
1864             package main;
1865              
1866             use Venus::Hash;
1867             use Venus::Scalar;
1868              
1869             my $lvalue = Venus::Hash->new;
1870             my $rvalue = Venus::Scalar->new;
1871              
1872             my $result = $lvalue->gtlt($rvalue);
1873              
1874             # 0
1875              
1876             =back
1877              
1878             =over 4
1879              
1880             =item gtlt example 8
1881              
1882             package main;
1883              
1884             use Venus::Hash;
1885             use Venus::String;
1886              
1887             my $lvalue = Venus::Hash->new;
1888             my $rvalue = Venus::String->new;
1889              
1890             my $result = $lvalue->gtlt($rvalue);
1891              
1892             # 0
1893              
1894             =back
1895              
1896             =over 4
1897              
1898             =item gtlt example 9
1899              
1900             package main;
1901              
1902             use Venus::Hash;
1903             use Venus::Undef;
1904              
1905             my $lvalue = Venus::Hash->new;
1906             my $rvalue = Venus::Undef->new;
1907              
1908             my $result = $lvalue->gtlt($rvalue);
1909              
1910             # 0
1911              
1912             =back
1913              
1914             =cut
1915              
1916             =head2 iterator
1917              
1918             iterator() (CodeRef)
1919              
1920             The iterator method returns a code reference which can be used to iterate over
1921             the hash. Each time the iterator is executed it will return the values of the
1922             next element in the hash until all elements have been seen, at which point the
1923             iterator will return an undefined value. This method can return a tuple with
1924             the key and value in list-context.
1925              
1926             I>
1927              
1928             =over 4
1929              
1930             =item iterator example 1
1931              
1932             # given: synopsis;
1933              
1934             my $iterator = $hash->iterator;
1935              
1936             # sub { ... }
1937              
1938             # while (my $value = $iterator->()) {
1939             # say $value; # 1
1940             # }
1941              
1942             =back
1943              
1944             =over 4
1945              
1946             =item iterator example 2
1947              
1948             # given: synopsis;
1949              
1950             my $iterator = $hash->iterator;
1951              
1952             # sub { ... }
1953              
1954             # while (grep defined, my ($key, $value) = $iterator->()) {
1955             # say $value; # 1
1956             # }
1957              
1958             =back
1959              
1960             =cut
1961              
1962             =head2 keys
1963              
1964             keys() (ArrayRef)
1965              
1966             The keys method returns an array reference consisting of all the keys in the
1967             hash.
1968              
1969             I>
1970              
1971             =over 4
1972              
1973             =item keys example 1
1974              
1975             # given: synopsis;
1976              
1977             my $keys = $hash->keys;
1978              
1979             # [1, 3, 5, 7]
1980              
1981             =back
1982              
1983             =cut
1984              
1985             =head2 le
1986              
1987             le(Any $arg) (Bool)
1988              
1989             The le method performs a I<"lesser-than-or-equal-to"> operation using the
1990             argument provided.
1991              
1992             I>
1993              
1994             =over 4
1995              
1996             =item le example 1
1997              
1998             package main;
1999              
2000             use Venus::Array;
2001             use Venus::Hash;
2002              
2003             my $lvalue = Venus::Hash->new;
2004             my $rvalue = Venus::Array->new;
2005              
2006             my $result = $lvalue->le($rvalue);
2007              
2008             # 0
2009              
2010             =back
2011              
2012             =over 4
2013              
2014             =item le example 2
2015              
2016             package main;
2017              
2018             use Venus::Code;
2019             use Venus::Hash;
2020              
2021             my $lvalue = Venus::Hash->new;
2022             my $rvalue = Venus::Code->new;
2023              
2024             my $result = $lvalue->le($rvalue);
2025              
2026             # 1
2027              
2028             =back
2029              
2030             =over 4
2031              
2032             =item le example 3
2033              
2034             package main;
2035              
2036             use Venus::Float;
2037             use Venus::Hash;
2038              
2039             my $lvalue = Venus::Hash->new;
2040             my $rvalue = Venus::Float->new;
2041              
2042             my $result = $lvalue->le($rvalue);
2043              
2044             # 0
2045              
2046             =back
2047              
2048             =over 4
2049              
2050             =item le example 4
2051              
2052             package main;
2053              
2054             use Venus::Hash;
2055              
2056             my $lvalue = Venus::Hash->new;
2057             my $rvalue = Venus::Hash->new;
2058              
2059             my $result = $lvalue->le($rvalue);
2060              
2061             # 1
2062              
2063             =back
2064              
2065             =over 4
2066              
2067             =item le example 5
2068              
2069             package main;
2070              
2071             use Venus::Hash;
2072             use Venus::Number;
2073              
2074             my $lvalue = Venus::Hash->new;
2075             my $rvalue = Venus::Number->new;
2076              
2077             my $result = $lvalue->le($rvalue);
2078              
2079             # 0
2080              
2081             =back
2082              
2083             =over 4
2084              
2085             =item le example 6
2086              
2087             package main;
2088              
2089             use Venus::Hash;
2090             use Venus::Regexp;
2091              
2092             my $lvalue = Venus::Hash->new;
2093             my $rvalue = Venus::Regexp->new;
2094              
2095             my $result = $lvalue->le($rvalue);
2096              
2097             # 1
2098              
2099             =back
2100              
2101             =over 4
2102              
2103             =item le example 7
2104              
2105             package main;
2106              
2107             use Venus::Hash;
2108             use Venus::Scalar;
2109              
2110             my $lvalue = Venus::Hash->new;
2111             my $rvalue = Venus::Scalar->new;
2112              
2113             my $result = $lvalue->le($rvalue);
2114              
2115             # 0
2116              
2117             =back
2118              
2119             =over 4
2120              
2121             =item le example 8
2122              
2123             package main;
2124              
2125             use Venus::Hash;
2126             use Venus::String;
2127              
2128             my $lvalue = Venus::Hash->new;
2129             my $rvalue = Venus::String->new;
2130              
2131             my $result = $lvalue->le($rvalue);
2132              
2133             # 0
2134              
2135             =back
2136              
2137             =over 4
2138              
2139             =item le example 9
2140              
2141             package main;
2142              
2143             use Venus::Hash;
2144             use Venus::Undef;
2145              
2146             my $lvalue = Venus::Hash->new;
2147             my $rvalue = Venus::Undef->new;
2148              
2149             my $result = $lvalue->le($rvalue);
2150              
2151             # 0
2152              
2153             =back
2154              
2155             =cut
2156              
2157             =head2 length
2158              
2159             length() (Int)
2160              
2161             The length method returns the total number of keys defined, and is an alias for
2162             the L method.
2163              
2164             I>
2165              
2166             =over 4
2167              
2168             =item length example 1
2169              
2170             # given: synopsis;
2171              
2172             my $length = $hash->length;
2173              
2174             # 4
2175              
2176             =back
2177              
2178             =cut
2179              
2180             =head2 list
2181              
2182             list() (Any)
2183              
2184             The list method returns a shallow copy of the underlying hash reference as an
2185             array reference.
2186              
2187             I>
2188              
2189             =over 4
2190              
2191             =item list example 1
2192              
2193             # given: synopsis;
2194              
2195             my $list = $hash->list;
2196              
2197             # 4
2198              
2199             =back
2200              
2201             =over 4
2202              
2203             =item list example 2
2204              
2205             # given: synopsis;
2206              
2207             my @list = $hash->list;
2208              
2209             # (1..8)
2210              
2211             =back
2212              
2213             =cut
2214              
2215             =head2 lt
2216              
2217             lt(Any $arg) (Bool)
2218              
2219             The lt method performs a I<"lesser-than"> operation using the argument provided.
2220              
2221             I>
2222              
2223             =over 4
2224              
2225             =item lt example 1
2226              
2227             package main;
2228              
2229             use Venus::Array;
2230             use Venus::Hash;
2231              
2232             my $lvalue = Venus::Hash->new;
2233             my $rvalue = Venus::Array->new;
2234              
2235             my $result = $lvalue->lt($rvalue);
2236              
2237             # 0
2238              
2239             =back
2240              
2241             =over 4
2242              
2243             =item lt example 2
2244              
2245             package main;
2246              
2247             use Venus::Code;
2248             use Venus::Hash;
2249              
2250             my $lvalue = Venus::Hash->new;
2251             my $rvalue = Venus::Code->new;
2252              
2253             my $result = $lvalue->lt($rvalue);
2254              
2255             # 1
2256              
2257             =back
2258              
2259             =over 4
2260              
2261             =item lt example 3
2262              
2263             package main;
2264              
2265             use Venus::Float;
2266             use Venus::Hash;
2267              
2268             my $lvalue = Venus::Hash->new;
2269             my $rvalue = Venus::Float->new;
2270              
2271             my $result = $lvalue->lt($rvalue);
2272              
2273             # 0
2274              
2275             =back
2276              
2277             =over 4
2278              
2279             =item lt example 4
2280              
2281             package main;
2282              
2283             use Venus::Hash;
2284              
2285             my $lvalue = Venus::Hash->new;
2286             my $rvalue = Venus::Hash->new;
2287              
2288             my $result = $lvalue->lt($rvalue);
2289              
2290             # 0
2291              
2292             =back
2293              
2294             =over 4
2295              
2296             =item lt example 5
2297              
2298             package main;
2299              
2300             use Venus::Hash;
2301             use Venus::Number;
2302              
2303             my $lvalue = Venus::Hash->new;
2304             my $rvalue = Venus::Number->new;
2305              
2306             my $result = $lvalue->lt($rvalue);
2307              
2308             # 0
2309              
2310             =back
2311              
2312             =over 4
2313              
2314             =item lt example 6
2315              
2316             package main;
2317              
2318             use Venus::Hash;
2319             use Venus::Regexp;
2320              
2321             my $lvalue = Venus::Hash->new;
2322             my $rvalue = Venus::Regexp->new;
2323              
2324             my $result = $lvalue->lt($rvalue);
2325              
2326             # 1
2327              
2328             =back
2329              
2330             =over 4
2331              
2332             =item lt example 7
2333              
2334             package main;
2335              
2336             use Venus::Hash;
2337             use Venus::Scalar;
2338              
2339             my $lvalue = Venus::Hash->new;
2340             my $rvalue = Venus::Scalar->new;
2341              
2342             my $result = $lvalue->lt($rvalue);
2343              
2344             # 0
2345              
2346             =back
2347              
2348             =over 4
2349              
2350             =item lt example 8
2351              
2352             package main;
2353              
2354             use Venus::Hash;
2355             use Venus::String;
2356              
2357             my $lvalue = Venus::Hash->new;
2358             my $rvalue = Venus::String->new;
2359              
2360             my $result = $lvalue->lt($rvalue);
2361              
2362             # 0
2363              
2364             =back
2365              
2366             =over 4
2367              
2368             =item lt example 9
2369              
2370             package main;
2371              
2372             use Venus::Hash;
2373             use Venus::Undef;
2374              
2375             my $lvalue = Venus::Hash->new;
2376             my $rvalue = Venus::Undef->new;
2377              
2378             my $result = $lvalue->lt($rvalue);
2379              
2380             # 0
2381              
2382             =back
2383              
2384             =cut
2385              
2386             =head2 map
2387              
2388             map(CodeRef $code) (ArrayRef)
2389              
2390             The map method executes callback for each key/value in the hash passing the
2391             routine the value at the current position in the loop and returning a new hash
2392             reference containing the elements for which the argument returns a value or
2393             non-empty list. This method can return a list of values in list-context.
2394              
2395             I>
2396              
2397             =over 4
2398              
2399             =item map example 1
2400              
2401             # given: synopsis;
2402              
2403             my $map = $hash->map(sub {
2404             $_ * 2
2405             });
2406              
2407             # [4, 8, 12, 16]
2408              
2409             =back
2410              
2411             =over 4
2412              
2413             =item map example 2
2414              
2415             # given: synopsis;
2416              
2417             my $map = $hash->map(sub {
2418             my ($key, $value) = @_;
2419              
2420             [$key, ($value * 2)]
2421             });
2422              
2423             # [[1, 4], [3, 8], [5, 12], [7, 16]]
2424              
2425             =back
2426              
2427             =cut
2428              
2429             =head2 merge
2430              
2431             merge(HashRef @data) (HashRef)
2432              
2433             The merge method returns a hash reference where the elements in the hash and
2434             the elements in the argument(s) are merged. This operation performs a deep
2435             merge and clones the datasets to ensure no side-effects.
2436              
2437             I>
2438              
2439             =over 4
2440              
2441             =item merge example 1
2442              
2443             # given: synopsis;
2444              
2445             my $merge = $hash->merge({1 => 'a'});
2446              
2447             # { 1 => "a", 3 => 4, 5 => 6, 7 => 8 }
2448              
2449             =back
2450              
2451             =over 4
2452              
2453             =item merge example 2
2454              
2455             # given: synopsis;
2456              
2457             my $merge = $hash->merge({1 => 'a'}, {5 => 'b'});
2458              
2459             # { 1 => "a", 3 => 4, 5 => "b", 7 => 8 }
2460              
2461             =back
2462              
2463             =cut
2464              
2465             =head2 ne
2466              
2467             ne(Any $arg) (Bool)
2468              
2469             The ne method performs a I<"not-equal-to"> operation using the argument provided.
2470              
2471             I>
2472              
2473             =over 4
2474              
2475             =item ne example 1
2476              
2477             package main;
2478              
2479             use Venus::Array;
2480             use Venus::Hash;
2481              
2482             my $lvalue = Venus::Hash->new;
2483             my $rvalue = Venus::Array->new;
2484              
2485             my $result = $lvalue->ne($rvalue);
2486              
2487             # 1
2488              
2489             =back
2490              
2491             =over 4
2492              
2493             =item ne example 2
2494              
2495             package main;
2496              
2497             use Venus::Code;
2498             use Venus::Hash;
2499              
2500             my $lvalue = Venus::Hash->new;
2501             my $rvalue = Venus::Code->new;
2502              
2503             my $result = $lvalue->ne($rvalue);
2504              
2505             # 1
2506              
2507             =back
2508              
2509             =over 4
2510              
2511             =item ne example 3
2512              
2513             package main;
2514              
2515             use Venus::Float;
2516             use Venus::Hash;
2517              
2518             my $lvalue = Venus::Hash->new;
2519             my $rvalue = Venus::Float->new;
2520              
2521             my $result = $lvalue->ne($rvalue);
2522              
2523             # 1
2524              
2525             =back
2526              
2527             =over 4
2528              
2529             =item ne example 4
2530              
2531             package main;
2532              
2533             use Venus::Hash;
2534              
2535             my $lvalue = Venus::Hash->new;
2536             my $rvalue = Venus::Hash->new;
2537              
2538             my $result = $lvalue->ne($rvalue);
2539              
2540             # 0
2541              
2542             =back
2543              
2544             =over 4
2545              
2546             =item ne example 5
2547              
2548             package main;
2549              
2550             use Venus::Hash;
2551             use Venus::Number;
2552              
2553             my $lvalue = Venus::Hash->new;
2554             my $rvalue = Venus::Number->new;
2555              
2556             my $result = $lvalue->ne($rvalue);
2557              
2558             # 1
2559              
2560             =back
2561              
2562             =over 4
2563              
2564             =item ne example 6
2565              
2566             package main;
2567              
2568             use Venus::Hash;
2569             use Venus::Regexp;
2570              
2571             my $lvalue = Venus::Hash->new;
2572             my $rvalue = Venus::Regexp->new;
2573              
2574             my $result = $lvalue->ne($rvalue);
2575              
2576             # 1
2577              
2578             =back
2579              
2580             =over 4
2581              
2582             =item ne example 7
2583              
2584             package main;
2585              
2586             use Venus::Hash;
2587             use Venus::Scalar;
2588              
2589             my $lvalue = Venus::Hash->new;
2590             my $rvalue = Venus::Scalar->new;
2591              
2592             my $result = $lvalue->ne($rvalue);
2593              
2594             # 1
2595              
2596             =back
2597              
2598             =over 4
2599              
2600             =item ne example 8
2601              
2602             package main;
2603              
2604             use Venus::Hash;
2605             use Venus::String;
2606              
2607             my $lvalue = Venus::Hash->new;
2608             my $rvalue = Venus::String->new;
2609              
2610             my $result = $lvalue->ne($rvalue);
2611              
2612             # 1
2613              
2614             =back
2615              
2616             =over 4
2617              
2618             =item ne example 9
2619              
2620             package main;
2621              
2622             use Venus::Hash;
2623             use Venus::Undef;
2624              
2625             my $lvalue = Venus::Hash->new;
2626             my $rvalue = Venus::Undef->new;
2627              
2628             my $result = $lvalue->ne($rvalue);
2629              
2630             # 1
2631              
2632             =back
2633              
2634             =cut
2635              
2636             =head2 none
2637              
2638             none(CodeRef $code) (Bool)
2639              
2640             The none method returns true if none of the elements in the array meet the
2641             criteria set by the operand and rvalue.
2642              
2643             I>
2644              
2645             =over 4
2646              
2647             =item none example 1
2648              
2649             # given: synopsis;
2650              
2651             my $none = $hash->none(sub {
2652             $_ < 1
2653             });
2654              
2655             # 1
2656              
2657             =back
2658              
2659             =over 4
2660              
2661             =item none example 2
2662              
2663             # given: synopsis;
2664              
2665             my $none = $hash->none(sub {
2666             my ($key, $value) = @_;
2667              
2668             $value < 1
2669             });
2670              
2671             # 1
2672              
2673             =back
2674              
2675             =cut
2676              
2677             =head2 one
2678              
2679             one(CodeRef $code) (Bool)
2680              
2681             The one method returns true if only one of the elements in the array meet the
2682             criteria set by the operand and rvalue.
2683              
2684             I>
2685              
2686             =over 4
2687              
2688             =item one example 1
2689              
2690             # given: synopsis;
2691              
2692             my $one = $hash->one(sub {
2693             $_ == 2
2694             });
2695              
2696             # 1
2697              
2698             =back
2699              
2700             =over 4
2701              
2702             =item one example 2
2703              
2704             # given: synopsis;
2705              
2706             my $one = $hash->one(sub {
2707             my ($key, $value) = @_;
2708              
2709             $value == 2
2710             });
2711              
2712             # 1
2713              
2714             =back
2715              
2716             =cut
2717              
2718             =head2 pairs
2719              
2720             pairs() (ArrayRef)
2721              
2722             The pairs method is an alias to the pairs_array method. This method can return
2723             a list of values in list-context.
2724              
2725             I>
2726              
2727             =over 4
2728              
2729             =item pairs example 1
2730              
2731             # given: synopsis;
2732              
2733             my $pairs = $hash->pairs;
2734              
2735             # [[1, 2], [3, 4], [5, 6], [7, 8]]
2736              
2737             =back
2738              
2739             =cut
2740              
2741             =head2 path
2742              
2743             path(Str $expr) (Any)
2744              
2745             The path method traverses the data structure using the path expr provided,
2746             returning the value found or undef. In list-context, this method returns a
2747             tuple, i.e. the value found and boolean representing whether the match was
2748             successful.
2749              
2750             I>
2751              
2752             =over 4
2753              
2754             =item path example 1
2755              
2756             package main;
2757              
2758             use Venus::Hash;
2759              
2760             my $hash = Venus::Hash->new({'foo' => {'bar' => 'baz'},'bar' => ['baz']});
2761              
2762             my $path = $hash->path('/foo/bar');
2763              
2764             # "baz"
2765              
2766             =back
2767              
2768             =over 4
2769              
2770             =item path example 2
2771              
2772             package main;
2773              
2774             use Venus::Hash;
2775              
2776             my $hash = Venus::Hash->new({'foo' => {'bar' => 'baz'},'bar' => ['baz']});
2777              
2778             my $path = $hash->path('/bar/0');
2779              
2780             # "baz"
2781              
2782             =back
2783              
2784             =over 4
2785              
2786             =item path example 3
2787              
2788             package main;
2789              
2790             use Venus::Hash;
2791              
2792             my $hash = Venus::Hash->new({'foo' => {'bar' => 'baz'},'bar' => ['baz']});
2793              
2794             my $path = $hash->path('/bar');
2795              
2796             # ["baz"]
2797              
2798             =back
2799              
2800             =over 4
2801              
2802             =item path example 4
2803              
2804             package main;
2805              
2806             use Venus::Hash;
2807              
2808             my $hash = Venus::Hash->new({'foo' => {'bar' => 'baz'},'bar' => ['baz']});
2809              
2810             my ($path, $exists) = $hash->path('/baz');
2811              
2812             # (undef, 0)
2813              
2814             =back
2815              
2816             =cut
2817              
2818             =head2 puts
2819              
2820             puts(Any @args) (ArrayRef)
2821              
2822             The puts method select values from within the underlying data structure using
2823             L, optionally assigning the value to the preceeding scalar
2824             reference and returns all the values selected.
2825              
2826             I>
2827              
2828             =over 4
2829              
2830             =item puts example 1
2831              
2832             package main;
2833              
2834             use Venus::Hash;
2835              
2836             my $hash = Venus::Hash->new({
2837             size => "small",
2838             fruit => "apple",
2839             meta => {
2840             expiry => '5d',
2841             },
2842             color => "red",
2843             });
2844              
2845             my $puts = $hash->puts(undef, 'fruit', undef, 'color');
2846              
2847             # ["apple", "red"]
2848              
2849             =back
2850              
2851             =over 4
2852              
2853             =item puts example 2
2854              
2855             package main;
2856              
2857             use Venus::Hash;
2858              
2859             my $hash = Venus::Hash->new({
2860             size => "small",
2861             fruit => "apple",
2862             meta => {
2863             expiry => '5d',
2864             },
2865             color => "red",
2866             });
2867              
2868             $hash->puts(\my $fruit, 'fruit', \my $expiry, 'meta.expiry');
2869              
2870             my $puts = [$fruit, $expiry];
2871              
2872             # ["apple", "5d"]
2873              
2874             =back
2875              
2876             =over 4
2877              
2878             =item puts example 3
2879              
2880             package main;
2881              
2882             use Venus::Hash;
2883              
2884             my $hash = Venus::Hash->new({
2885             size => "small",
2886             fruit => "apple",
2887             meta => {
2888             expiry => '5d',
2889             },
2890             color => "red",
2891             });
2892              
2893             $hash->puts(
2894             \my $fruit, 'fruit',
2895             \my $color, 'color',
2896             \my $expiry, 'meta.expiry',
2897             \my $ripe, 'meta.ripe',
2898             );
2899              
2900             my $puts = [$fruit, $color, $expiry, $ripe];
2901              
2902             # ["apple", "red", "5d", undef]
2903              
2904             =back
2905              
2906             =over 4
2907              
2908             =item puts example 4
2909              
2910             package main;
2911              
2912             use Venus::Hash;
2913              
2914             my $hash = Venus::Hash->new({set => [1..20]});
2915              
2916             $hash->puts(
2917             \my $a, 'set.0',
2918             \my $b, 'set.1',
2919             \my $m, ['set', '2:-2'],
2920             \my $x, 'set.18',
2921             \my $y, 'set.19',
2922             );
2923              
2924             my $puts = [$a, $b, $m, $x, $y];
2925              
2926             # [1, 2, [3..18], 19, 20]
2927              
2928             =back
2929              
2930             =cut
2931              
2932             =head2 random
2933              
2934             random() (Any)
2935              
2936             The random method returns a random element from the array.
2937              
2938             I>
2939              
2940             =over 4
2941              
2942             =item random example 1
2943              
2944             # given: synopsis;
2945              
2946             my $random = $hash->random;
2947              
2948             # 6
2949              
2950             # my $random = $hash->random;
2951              
2952             # 4
2953              
2954             =back
2955              
2956             =cut
2957              
2958             =head2 reset
2959              
2960             reset() (ArrayRef)
2961              
2962             The reset method returns nullifies the value of each element in the hash.
2963              
2964             I>
2965              
2966             =over 4
2967              
2968             =item reset example 1
2969              
2970             # given: synopsis;
2971              
2972             my $reset = $hash->reset;
2973              
2974             # { 1 => undef, 3 => undef, 5 => undef, 7 => undef }
2975              
2976             =back
2977              
2978             =cut
2979              
2980             =head2 reverse
2981              
2982             reverse() (HashRef)
2983              
2984             The reverse method returns a hash reference consisting of the hash's keys and
2985             values inverted. Note, keys with undefined values will be dropped.
2986              
2987             I>
2988              
2989             =over 4
2990              
2991             =item reverse example 1
2992              
2993             # given: synopsis;
2994              
2995             my $reverse = $hash->reverse;
2996              
2997             # { 2 => 1, 4 => 3, 6 => 5, 8 => 7 }
2998              
2999             =back
3000              
3001             =cut
3002              
3003             =head2 slice
3004              
3005             slice(Str @keys) (ArrayRef)
3006              
3007             The slice method returns an array reference of the values that correspond to
3008             the key(s) specified in the arguments.
3009              
3010             I>
3011              
3012             =over 4
3013              
3014             =item slice example 1
3015              
3016             # given: synopsis;
3017              
3018             my $slice = $hash->slice(1, 3);
3019              
3020             # [2, 4]
3021              
3022             =back
3023              
3024             =cut
3025              
3026             =head2 tv
3027              
3028             tv(Any $arg) (Bool)
3029              
3030             The tv method performs a I<"type-and-value-equal-to"> operation using argument
3031             provided.
3032              
3033             I>
3034              
3035             =over 4
3036              
3037             =item tv example 1
3038              
3039             package main;
3040              
3041             use Venus::Array;
3042             use Venus::Hash;
3043              
3044             my $lvalue = Venus::Hash->new;
3045             my $rvalue = Venus::Array->new;
3046              
3047             my $result = $lvalue->tv($rvalue);
3048              
3049             # 0
3050              
3051             =back
3052              
3053             =over 4
3054              
3055             =item tv example 2
3056              
3057             package main;
3058              
3059             use Venus::Code;
3060             use Venus::Hash;
3061              
3062             my $lvalue = Venus::Hash->new;
3063             my $rvalue = Venus::Code->new;
3064              
3065             my $result = $lvalue->tv($rvalue);
3066              
3067             # 0
3068              
3069             =back
3070              
3071             =over 4
3072              
3073             =item tv example 3
3074              
3075             package main;
3076              
3077             use Venus::Float;
3078             use Venus::Hash;
3079              
3080             my $lvalue = Venus::Hash->new;
3081             my $rvalue = Venus::Float->new;
3082              
3083             my $result = $lvalue->tv($rvalue);
3084              
3085             # 0
3086              
3087             =back
3088              
3089             =over 4
3090              
3091             =item tv example 4
3092              
3093             package main;
3094              
3095             use Venus::Hash;
3096              
3097             my $lvalue = Venus::Hash->new;
3098             my $rvalue = Venus::Hash->new;
3099              
3100             my $result = $lvalue->tv($rvalue);
3101              
3102             # 1
3103              
3104             =back
3105              
3106             =over 4
3107              
3108             =item tv example 5
3109              
3110             package main;
3111              
3112             use Venus::Hash;
3113             use Venus::Number;
3114              
3115             my $lvalue = Venus::Hash->new;
3116             my $rvalue = Venus::Number->new;
3117              
3118             my $result = $lvalue->tv($rvalue);
3119              
3120             # 0
3121              
3122             =back
3123              
3124             =over 4
3125              
3126             =item tv example 6
3127              
3128             package main;
3129              
3130             use Venus::Hash;
3131             use Venus::Regexp;
3132              
3133             my $lvalue = Venus::Hash->new;
3134             my $rvalue = Venus::Regexp->new;
3135              
3136             my $result = $lvalue->tv($rvalue);
3137              
3138             # 0
3139              
3140             =back
3141              
3142             =over 4
3143              
3144             =item tv example 7
3145              
3146             package main;
3147              
3148             use Venus::Hash;
3149             use Venus::Scalar;
3150              
3151             my $lvalue = Venus::Hash->new;
3152             my $rvalue = Venus::Scalar->new;
3153              
3154             my $result = $lvalue->tv($rvalue);
3155              
3156             # 0
3157              
3158             =back
3159              
3160             =over 4
3161              
3162             =item tv example 8
3163              
3164             package main;
3165              
3166             use Venus::Hash;
3167             use Venus::String;
3168              
3169             my $lvalue = Venus::Hash->new;
3170             my $rvalue = Venus::String->new;
3171              
3172             my $result = $lvalue->tv($rvalue);
3173              
3174             # 0
3175              
3176             =back
3177              
3178             =over 4
3179              
3180             =item tv example 9
3181              
3182             package main;
3183              
3184             use Venus::Hash;
3185             use Venus::Undef;
3186              
3187             my $lvalue = Venus::Hash->new;
3188             my $rvalue = Venus::Undef->new;
3189              
3190             my $result = $lvalue->tv($rvalue);
3191              
3192             # 0
3193              
3194             =back
3195              
3196             =cut
3197              
3198             =head1 AUTHORS
3199              
3200             Awncorp, C
3201              
3202             =cut
3203              
3204             =head1 LICENSE
3205              
3206             Copyright (C) 2000, Al Newkirk.
3207              
3208             This program is free software, you can redistribute it and/or modify it under
3209             the terms of the Apache license version 2.0.
3210              
3211             =cut