File Coverage

blib/lib/Venus/Array.pm
Criterion Covered Total %
statement 276 290 95.1
branch 78 108 72.2
condition 9 14 64.2
subroutine 50 59 84.7
pod 44 46 95.6
total 457 517 88.3


line stmt bran cond sub pod time code
1             package Venus::Array;
2              
3 18     18   492 use 5.018;
  18         65  
4              
5 18     18   104 use strict;
  18         40  
  18         440  
6 18     18   99 use warnings;
  18         47  
  18         686  
7              
8 18     18   110 use Venus::Class 'base', 'with';
  18         52  
  18         208  
9              
10             base 'Venus::Kind::Value';
11              
12             with 'Venus::Role::Mappable';
13              
14             # METHODS
15              
16             sub all {
17 2     2 1 7 my ($self, $code) = @_;
18              
19 2         9 my $data = $self->get;
20              
21 2 50   0   20 $code = sub{} if !$code;
22              
23 2         7 my $failed = 0;
24              
25 2         10 for (my $i = 0; $i < @$data; $i++) {
26 18         30 my $index = $i;
27 18         27 my $value = $data->[$i];
28              
29 18         25 local $_ = $value;
30 18 50       327 $failed++ if !$code->($index, $value);
31              
32 18 50       60 CORE::last if $failed;
33             }
34              
35 2 50       15 return $failed ? false : true;
36             }
37              
38             sub any {
39 2     2 1 6 my ($self, $code) = @_;
40              
41 2         7 my $data = $self->get;
42              
43 2 50   0   6 $code = sub{} if !$code;
44              
45 2         5 my $found = 0;
46              
47 2         8 for (my $i = 0; $i < @$data; $i++) {
48 10         12 my $index = $i;
49 10         16 my $value = $data->[$i];
50              
51 10         13 local $_ = $value;
52 10 100       162 $found++ if $code->($index, $value);
53              
54 10 100       27 CORE::last if $found;
55             }
56              
57 2 50       13 return $found ? true : false;
58             }
59              
60             sub assertion {
61 0     0 1 0 my ($self) = @_;
62              
63 0         0 my $assert = $self->SUPER::assertion;
64              
65 0         0 $assert->clear->expression('arrayref');
66              
67 0         0 return $assert;
68             }
69              
70             sub call {
71 2     2 1 7 my ($self, $mapper, $method, @args) = @_;
72              
73 2         10 require Venus::Type;
74              
75             return $self->$mapper(sub{
76 18     18   30 my ($key, $val) = @_;
77              
78 18         65 my $type = Venus::Type->new($val)->deduce;
79              
80 18         58 local $_ = $type;
81              
82 18         73 $type->$method(@args)
83 2         28 });
84             }
85              
86             sub count {
87 3     3 1 9 my ($self) = @_;
88              
89 3         12 my $data = $self->get;
90              
91 3         20 return scalar(@$data);
92             }
93              
94             sub default {
95 182     182 1 756 return [];
96             }
97              
98             sub delete {
99 1     1 1 7 my ($self, $index) = @_;
100              
101 1         7 my $data = $self->get;
102              
103 1         6 return CORE::delete($data->[$index]);
104             }
105              
106             sub each {
107 7     7 1 22 my ($self, $code) = @_;
108              
109 7         20 my $data = $self->get;
110              
111 7 50   0   20 $code = sub{} if !$code;
112              
113 7         18 my $result = [];
114              
115 7         26 for (my $i = 0; $i < @$data; $i++) {
116 33         51 my $index = $i;
117 33         47 my $value = $data->[$i];
118              
119 33         45 local $_ = $value;
120 33         366 CORE::push(@$result, $code->($index, $value));
121             }
122              
123 7 100       45 return wantarray ? (@$result) : $result;
124             }
125              
126             sub empty {
127 1     1 1 3 my ($self) = @_;
128              
129 1         5 my $data = $self->get;
130              
131 1         5 $#$data = -1;
132              
133 1         13 return $self;
134             }
135              
136             sub exists {
137 1     1 1 5 my ($self, $index) = @_;
138              
139 1         6 my $data = $self->get;
140              
141 1 50       4 return $index <= $#{$data} ? true : false;
  1         14  
142             }
143              
144             sub find {
145 19     19 1 52 my ($self, @args) = @_;
146              
147 19         37 my $seen = 0;
148 19         58 my $item = my $data = $self->get;
149              
150 19         100 for (my $i = 0; $i < @args; $i++) {
151 34 100       98 if (ref($item) eq 'ARRAY') {
    100          
152 20 50       106 if ($args[$i] !~ /^\d+$/) {
153 0         0 $item = undef;
154 0         0 $seen = 0;
155 0         0 CORE::last;
156             }
157 20         36 $seen = $args[$i] <= $#{$item};
  20         55  
158 20         60 $item = $item->[$args[$i]];
159             }
160             elsif (ref($item) eq 'HASH') {
161 12         26 $seen = exists $item->{$args[$i]};
162 12         36 $item = $item->{$args[$i]};
163             }
164             else {
165 2         5 $item = undef;
166 2         7 $seen = 0;
167             }
168             }
169              
170 19 100       90 return wantarray ? ($item, int(!!$seen)) : $item;
171             }
172              
173             sub first {
174 1     1 1 4 my ($self) = @_;
175              
176 1         5 return $self->get->[0];
177             }
178              
179             sub get {
180 267     267 1 589 my ($self, @args) = @_;
181              
182 267 100       1174 return $self->value if !@args;
183              
184 4         10 my ($index) = @args;
185              
186 4         11 return $self->value->[$index];
187             }
188              
189             sub grep {
190 3     3 1 12 my ($self, $code) = @_;
191              
192 3         11 my $data = $self->get;
193              
194 3 50   0   27 $code = sub{} if !$code;
195              
196 3         9 my $result = [];
197              
198 3         15 for (my $i = 0; $i < @$data; $i++) {
199 27         52 my $index = $i;
200 27         36 my $value = $data->[$i];
201              
202 27         38 local $_ = $value;
203 27 100       306 CORE::push(@$result, $value) if $code->($index, $value);
204             }
205              
206 3 50       47 return wantarray ? (@$result) : $result;
207             }
208              
209             sub head {
210 5     5 0 17 my ($self, $size) = @_;
211              
212 5         20 my $data = $self->get;
213              
214 5 100       42 $size = !$size ? 1 : $size > @$data ? @$data : $size;
    100          
215              
216 5         17 my $index = $size - 1;
217              
218 5         15 return [@{$data}[0..$index]];
  5         34  
219             }
220              
221             sub iterator {
222 2     2 1 7 my ($self) = @_;
223              
224 2         11 my $data = $self->get;
225              
226 2         11 my $i = 0;
227 2         7 my $j = 0;
228              
229             return sub {
230 20 100   20   9847 return undef if $i > $#{$data};
  20         74  
231 18 100       84 return wantarray ? ($j++, $data->[$i++]) : $data->[$i++];
232             }
233 2         20 }
234              
235             sub join {
236 2     2 1 8 my ($self, $delimiter) = @_;
237              
238 2         9 my $data = $self->get;
239              
240 2   100     28 return CORE::join($delimiter // '', @$data);
241             }
242              
243             sub keyed {
244 1     1 1 5 my ($self, @keys) = @_;
245              
246 1         6 my $data = $self->get;
247              
248 1         5 my $i = 0;
249 1         4 return {map { $_ => $data->[$i++] } @keys};
  4         20  
250             }
251              
252             sub keys {
253 1     1 1 6 my ($self) = @_;
254              
255 1         5 my $data = $self->get;
256              
257 1         3 return [0..$#{$data}];
  1         8  
258             }
259              
260             sub last {
261 1     1 1 5 my ($self) = @_;
262              
263 1         5 return $self->value->[-1];
264             }
265              
266             sub length {
267 1     1 1 4 my ($self) = @_;
268              
269 1         6 return $self->count;
270             }
271              
272             sub list {
273 2     2 1 7 my ($self) = @_;
274              
275 2 100       9 return wantarray ? (@{$self->value}) : scalar(@{$self->value});
  1         6  
  1         4  
276             }
277              
278             sub map {
279 3     3 1 12 my ($self, $code) = @_;
280              
281 3         14 my $data = $self->get;
282              
283 3 50   0   16 $code = sub{} if !$code;
284              
285 3         8 my $result = [];
286              
287 3         17 for (my $i = 0; $i < @$data; $i++) {
288 27         42 my $index = $i;
289 27         42 my $value = $data->[$i];
290              
291 27         37 local $_ = $value;
292 27         318 CORE::push(@$result, $code->($index, $value));
293             }
294              
295 3 50       30 return wantarray ? (@$result) : $result;
296             }
297              
298             sub merge {
299 2     2 1 9 my ($self, @rvalues) = @_;
300              
301 2         14 require Venus;
302              
303 2         6 my $lvalue = [@{$self->get}];
  2         12  
304              
305 2         15 return Venus::merge($lvalue, @rvalues);
306             }
307              
308             sub none {
309 2     2 1 7 my ($self, $code) = @_;
310              
311 2         8 my $data = $self->get;
312              
313 2 50   0   14 $code = sub{} if !$code;
314              
315 2         8 my $found = 0;
316              
317 2         7 for (my $i = 0; $i < @$data; $i++) {
318 18         28 my $index = $i;
319 18         23 my $value = $data->[$i];
320              
321 18         24 local $_ = $value;
322 18 50       281 $found++ if $code->($index, $value);
323              
324 18 50       51 CORE::last if $found;
325             }
326              
327 2 50       18 return $found ? false : true;
328             }
329              
330             sub one {
331 2     2 1 10 my ($self, $code) = @_;
332              
333 2         13 my $data = $self->get;
334              
335 2 50   0   17 $code = sub{} if !$code;
336              
337 2         4 my $found = 0;
338              
339 2         11 for (my $i = 0; $i < @$data; $i++) {
340 18         23 my $index = $i;
341 18         29 my $value = $data->[$i];
342              
343 18         21 local $_ = $value;
344 18 100       283 $found++ if $code->($index, $value);
345              
346 18 50       56 CORE::last if $found > 1;
347             }
348              
349 2 50       18 return $found == 1 ? true : false;
350             }
351              
352             sub order {
353 3     3 1 13 my ($self, @args) = @_;
354              
355 3         13 my $data = $self->get;
356              
357 3         10 my %seen = ();
358              
359 3         7 @{$data} = (map $data->[$_], grep !$seen{$_}++, (@args), 0..$#{$data});
  3         12  
  3         54  
360              
361 3         39 return $self;
362             }
363              
364             sub pairs {
365 1     1 1 4 my ($self) = @_;
366              
367 1         6 my $data = $self->get;
368              
369 1         5 my $i = 0;
370 1         9 my $result = [map +[$i++, $_], @$data];
371              
372 1 50       12 return wantarray ? (@$result) : $result;
373             }
374              
375             sub path {
376 16     16 1 36 my ($self, $path) = @_;
377              
378 16         100 my @path = CORE::grep(/./, CORE::split(/\W/, $path));
379              
380 16 100       74 return wantarray ? ($self->find(@path)) : $self->find(@path);
381             }
382              
383             sub part {
384 2     2 1 6 my ($self, $code) = @_;
385              
386 2         7 my $data = $self->get;
387              
388 2         8 my $results = [[], []];
389              
390 2         13 for (my $i = 0; $i < @$data; $i++) {
391 18         28 my $index = $i;
392 18         26 my $value = $data->[$i];
393 18         24 local $_ = $value;
394 18         286 my $result = $code->($index, $value);
395 18 100       42 my $slot = $result ? $$results[0] : $$results[1];
396              
397 18         43 CORE::push(@$slot, $value);
398             }
399              
400 2 50       13 return wantarray ? (@$results) : $results;
401             }
402              
403             sub pop {
404 1     1 1 3 my ($self) = @_;
405              
406 1         7 my $data = $self->get;
407              
408 1         6 return CORE::pop(@$data);
409             }
410              
411             sub push {
412 1     1 1 4 my ($self, @args) = @_;
413              
414 1         4 my $data = $self->get;
415              
416 1         4 CORE::push(@$data, @args);
417              
418 1         6 return $data;
419             }
420              
421             sub puts {
422 4     4 1 15 my ($self, @args) = @_;
423              
424 4         12 my $result = [];
425              
426 4         15 for (my $i = 0; $i < @args; $i += 2) {
427 12         29 my ($into, $path) = @args[$i, $i+1];
428              
429 12 50       27 next if !defined $path;
430              
431 12         19 my $value;
432             my @range;
433              
434 12 100       30 ($path, @range) = @{$path} if ref $path eq 'ARRAY';
  1         4  
435              
436 12         33 $value = $self->path($path);
437 12 100       36 $value = Venus::Array->new($value)->range(@range) if ref $value eq 'ARRAY';
438              
439 12 100       28 if (ref $into eq 'SCALAR') {
440 10         21 $$into = $value;
441             }
442              
443 12         18 CORE::push @{$result}, $value;
  12         37  
444             }
445              
446 4 50       77 return wantarray ? (@{$result}) : $result;
  0         0  
447             }
448              
449             sub random {
450 1     1 1 4 my ($self) = @_;
451              
452 1         4 my $data = $self->get;
453              
454 1         3 return @$data[rand($#{$data}+1)];
  1         49  
455             }
456              
457             sub range {
458 37     37 1 119 my ($self, @args) = @_;
459              
460 37 100       124 return $self->slice(@args) if @args > 1;
461              
462 36         90 my ($note) = @args;
463              
464 36 100       104 return $self->slice if !defined $note;
465              
466 35         160 my ($f, $l) = split /:/, $note, 2;
467              
468 35         140 my $data = $self->get;
469              
470 35 100 66     204 $f = 0 if !defined $f || $f eq '';
471 35 100       106 $l = $f if !defined $l;
472 35 100 66     204 $l = $#$data if !defined $l || $l eq '';
473              
474 35         82 $f = 0+$f;
475 35         69 $l = 0+$l;
476              
477 35 100 100     157 $l = $#$data + $l if $f > -1 && $l < 0;
478              
479 35         148 return $self->slice($f..$l);
480             }
481              
482             sub reverse {
483 1     1 1 4 my ($self) = @_;
484              
485 1         4 my $data = $self->get;
486              
487 1         8 return [CORE::reverse(@$data)];
488             }
489              
490             sub rotate {
491 1     1 1 4 my ($self) = @_;
492              
493 1         5 my $data = $self->get;
494              
495 1         6 CORE::push(@$data, CORE::shift(@$data));
496              
497 1         5 return $data;
498             }
499              
500             sub rsort {
501 1     1 1 6 my ($self) = @_;
502              
503 1         8 my $data = $self->get;
504              
505 1         6 return [CORE::sort { $b cmp $a } @$data];
  12         25  
506             }
507              
508             sub set {
509 0     0 1 0 my ($self, @args) = @_;
510              
511 0 0       0 return $self->value if !@args;
512              
513 0 0 0     0 return $self->value(@args) if @args == 1 && ref $args[0] eq 'ARRAY';
514              
515 0         0 my ($index, $value) = @args;
516              
517 0 0       0 return if not defined $index;
518              
519 0         0 return $self->value->[$index] = $value;
520             }
521              
522             sub shift {
523 1     1 1 5 my ($self) = @_;
524              
525 1         6 my $data = $self->get;
526              
527 1         13 return CORE::shift(@$data);
528             }
529              
530             sub shuffle {
531 1     1 1 4 my ($self) = @_;
532              
533 1         5 my $data = $self->get;
534 1         6 my $result = [@$data];
535              
536 1         6 for my $index (0..$#$result) {
537 9         19 my $other = int(rand(@$result));
538 9         12 my $stash = $result->[$index];
539 9         10 $result->[$index] = $result->[$other];
540 9         15 $result->[$other] = $stash;
541             }
542              
543 1         5 return $result;
544             }
545              
546             sub slice {
547 38     38 1 114 my ($self, @args) = @_;
548              
549 38         81 my $data = $self->get;
550              
551 38         224 return [@$data[@args]];
552             }
553              
554             sub sort {
555 1     1 1 4 my ($self) = @_;
556              
557 1         6 my $data = $self->get;
558              
559 1         6 return [CORE::sort { $a cmp $b } @$data];
  4         11  
560             }
561              
562             sub tail {
563 5     5 0 17 my ($self, $size) = @_;
564              
565 5         24 my $data = $self->get;
566              
567 5 100       30 $size = !$size ? 1 : $size > @$data ? @$data : $size;
    100          
568              
569 5         21 my $index = $#$data - ($size - 1);
570              
571 5         13 return [@{$data}[$index..$#$data]];
  5         36  
572             }
573              
574             sub unique {
575 1     1 1 4 my ($self) = @_;
576              
577 1         6 my $data = $self->get;
578              
579 1         3 my %seen;
580 1         4 return [CORE::grep { not $seen{$_}++ } @$data];
  7         25  
581             }
582              
583             sub unshift {
584 1     1 1 4 my ($self, @args) = @_;
585              
586 1         7 my $data = $self->get;
587              
588 1         6 CORE::unshift(@$data, @args);
589              
590 1         12 return $data;
591             }
592              
593             1;
594              
595              
596              
597             =head1 NAME
598              
599             Venus::Array - Array Class
600              
601             =cut
602              
603             =head1 ABSTRACT
604              
605             Array Class for Perl 5
606              
607             =cut
608              
609             =head1 SYNOPSIS
610              
611             package main;
612              
613             use Venus::Array;
614              
615             my $array = Venus::Array->new([1..9]);
616              
617             # $array->random;
618              
619             =cut
620              
621             =head1 DESCRIPTION
622              
623             This package provides methods for manipulating array data.
624              
625             =cut
626              
627             =head1 INHERITS
628              
629             This package inherits behaviors from:
630              
631             L
632              
633             =cut
634              
635             =head1 INTEGRATES
636              
637             This package integrates behaviors from:
638              
639             L
640              
641             =cut
642              
643             =head1 METHODS
644              
645             This package provides the following methods:
646              
647             =cut
648              
649             =head2 all
650              
651             all(CodeRef $code) (Bool)
652              
653             The all method returns true if the callback returns true for all of the
654             elements.
655              
656             I>
657              
658             =over 4
659              
660             =item all example 1
661              
662             # given: synopsis;
663              
664             my $all = $array->all(sub {
665             $_ > 0;
666             });
667              
668             # 1
669              
670             =back
671              
672             =over 4
673              
674             =item all example 2
675              
676             # given: synopsis;
677              
678             my $all = $array->all(sub {
679             my ($key, $value) = @_;
680              
681             $value > 0;
682             });
683              
684             # 1
685              
686             =back
687              
688             =cut
689              
690             =head2 any
691              
692             any(CodeRef $code) (Bool)
693              
694             The any method returns true if the callback returns true for any of the
695             elements.
696              
697             I>
698              
699             =over 4
700              
701             =item any example 1
702              
703             # given: synopsis;
704              
705             my $any = $array->any(sub {
706             $_ > 4;
707             });
708              
709             =back
710              
711             =over 4
712              
713             =item any example 2
714              
715             # given: synopsis;
716              
717             my $any = $array->any(sub {
718             my ($key, $value) = @_;
719              
720             $value > 4;
721             });
722              
723             =back
724              
725             =cut
726              
727             =head2 call
728              
729             call(Str $iterable, Str $method) (Any)
730              
731             The call method executes the given method (named using the first argument)
732             which performs an iteration (i.e. takes a callback) and calls the method (named
733             using the second argument) on the object (or value) and returns the result of
734             the iterable method.
735              
736             I>
737              
738             =over 4
739              
740             =item call example 1
741              
742             # given: synopsis
743              
744             package main;
745              
746             my $call = $array->call('map', 'incr');
747              
748             # [2..10]
749              
750             =back
751              
752             =over 4
753              
754             =item call example 2
755              
756             # given: synopsis
757              
758             package main;
759              
760             my $call = $array->call('grep', 'gt', 4);
761              
762             # [4..9]
763              
764             =back
765              
766             =cut
767              
768             =head2 cast
769              
770             cast(Str $kind) (Object | Undef)
771              
772             The cast method converts L<"value"|Venus::Kind::Value> objects between
773             different I<"value"> object types, based on the name of the type provided. This
774             method will return C if the invocant is not a L.
775              
776             I>
777              
778             =over 4
779              
780             =item cast example 1
781              
782             package main;
783              
784             use Venus::Array;
785              
786             my $array = Venus::Array->new;
787              
788             my $cast = $array->cast('array');
789              
790             # bless({ value => [] }, "Venus::Array")
791              
792             =back
793              
794             =over 4
795              
796             =item cast example 2
797              
798             package main;
799              
800             use Venus::Array;
801              
802             my $array = Venus::Array->new;
803              
804             my $cast = $array->cast('boolean');
805              
806             # bless({ value => 1 }, "Venus::Boolean")
807              
808             =back
809              
810             =over 4
811              
812             =item cast example 3
813              
814             package main;
815              
816             use Venus::Array;
817              
818             my $array = Venus::Array->new;
819              
820             my $cast = $array->cast('code');
821              
822             # bless({ value => sub { ... } }, "Venus::Code")
823              
824             =back
825              
826             =over 4
827              
828             =item cast example 4
829              
830             package main;
831              
832             use Venus::Array;
833              
834             my $array = Venus::Array->new;
835              
836             my $cast = $array->cast('float');
837              
838             # bless({ value => "1.0" }, "Venus::Float")
839              
840             =back
841              
842             =over 4
843              
844             =item cast example 5
845              
846             package main;
847              
848             use Venus::Array;
849              
850             my $array = Venus::Array->new;
851              
852             my $cast = $array->cast('hash');
853              
854             # bless({ value => {} }, "Venus::Hash")
855              
856             =back
857              
858             =over 4
859              
860             =item cast example 6
861              
862             package main;
863              
864             use Venus::Array;
865              
866             my $array = Venus::Array->new;
867              
868             my $cast = $array->cast('number');
869              
870             # bless({ value => 2 }, "Venus::Number")
871              
872             =back
873              
874             =over 4
875              
876             =item cast example 7
877              
878             package main;
879              
880             use Venus::Array;
881              
882             my $array = Venus::Array->new;
883              
884             my $cast = $array->cast('regexp');
885              
886             # bless({ value => qr/(?^u:\[\])/ }, "Venus::Regexp")
887              
888             =back
889              
890             =over 4
891              
892             =item cast example 8
893              
894             package main;
895              
896             use Venus::Array;
897              
898             my $array = Venus::Array->new;
899              
900             my $cast = $array->cast('scalar');
901              
902             # bless({ value => \[] }, "Venus::Scalar")
903              
904             =back
905              
906             =over 4
907              
908             =item cast example 9
909              
910             package main;
911              
912             use Venus::Array;
913              
914             my $array = Venus::Array->new;
915              
916             my $cast = $array->cast('string');
917              
918             # bless({ value => "[]" }, "Venus::String")
919              
920             =back
921              
922             =over 4
923              
924             =item cast example 10
925              
926             package main;
927              
928             use Venus::Array;
929              
930             my $array = Venus::Array->new;
931              
932             my $cast = $array->cast('undef');
933              
934             # bless({ value => undef }, "Venus::Undef")
935              
936             =back
937              
938             =cut
939              
940             =head2 count
941              
942             count() (Int)
943              
944             The count method returns the number of elements within the array.
945              
946             I>
947              
948             =over 4
949              
950             =item count example 1
951              
952             # given: synopsis;
953              
954             my $count = $array->count;
955              
956             # 9
957              
958             =back
959              
960             =cut
961              
962             =head2 default
963              
964             default() (ArrayRef)
965              
966             The default method returns the default value, i.e. C<[]>.
967              
968             I>
969              
970             =over 4
971              
972             =item default example 1
973              
974             # given: synopsis;
975              
976             my $default = $array->default;
977              
978             # []
979              
980             =back
981              
982             =cut
983              
984             =head2 delete
985              
986             delete(Int $index) (Any)
987              
988             The delete method returns the value of the element at the index specified after
989             removing it from the array.
990              
991             I>
992              
993             =over 4
994              
995             =item delete example 1
996              
997             # given: synopsis;
998              
999             my $delete = $array->delete(2);
1000              
1001             # 3
1002              
1003             =back
1004              
1005             =cut
1006              
1007             =head2 each
1008              
1009             each(CodeRef $code) (ArrayRef)
1010              
1011             The each method executes a callback for each element in the array passing the
1012             index and value as arguments. This method can return a list of values in
1013             list-context.
1014              
1015             I>
1016              
1017             =over 4
1018              
1019             =item each example 1
1020              
1021             # given: synopsis;
1022              
1023             my $each = $array->each(sub {
1024             [$_]
1025             });
1026              
1027             # [[1], [2], [3], [4], [5], [6], [7], [8], [9]]
1028              
1029             =back
1030              
1031             =over 4
1032              
1033             =item each example 2
1034              
1035             # given: synopsis;
1036              
1037             my $each = $array->each(sub {
1038             my ($key, $value) = @_;
1039              
1040             [$key, $value]
1041             });
1042              
1043             # [
1044             # [0, 1],
1045             # [1, 2],
1046             # [2, 3],
1047             # [3, 4],
1048             # [4, 5],
1049             # [5, 6],
1050             # [6, 7],
1051             # [7, 8],
1052             # [8, 9],
1053             # ]
1054              
1055             =back
1056              
1057             =cut
1058              
1059             =head2 empty
1060              
1061             empty() (Array)
1062              
1063             The empty method drops all elements from the array.
1064              
1065             I>
1066              
1067             =over 4
1068              
1069             =item empty example 1
1070              
1071             # given: synopsis;
1072              
1073             my $empty = $array->empty;
1074              
1075             # bless({ value => [] }, "Venus::Array")
1076              
1077             =back
1078              
1079             =cut
1080              
1081             =head2 eq
1082              
1083             eq(Any $arg) (Bool)
1084              
1085             The eq method performs an I<"equals"> operation using the argument provided.
1086              
1087             I>
1088              
1089             =over 4
1090              
1091             =item eq example 1
1092              
1093             package main;
1094              
1095             use Venus::Array;
1096              
1097             my $lvalue = Venus::Array->new;
1098             my $rvalue = Venus::Array->new;
1099              
1100             my $result = $lvalue->eq($rvalue);
1101              
1102             # 1
1103              
1104             =back
1105              
1106             =over 4
1107              
1108             =item eq example 2
1109              
1110             package main;
1111              
1112             use Venus::Array;
1113             use Venus::Code;
1114              
1115             my $lvalue = Venus::Array->new;
1116             my $rvalue = Venus::Code->new;
1117              
1118             my $result = $lvalue->eq($rvalue);
1119              
1120             # 0
1121              
1122             =back
1123              
1124             =over 4
1125              
1126             =item eq example 3
1127              
1128             package main;
1129              
1130             use Venus::Array;
1131             use Venus::Float;
1132              
1133             my $lvalue = Venus::Array->new;
1134             my $rvalue = Venus::Float->new;
1135              
1136             my $result = $lvalue->eq($rvalue);
1137              
1138             # 0
1139              
1140             =back
1141              
1142             =over 4
1143              
1144             =item eq example 4
1145              
1146             package main;
1147              
1148             use Venus::Array;
1149             use Venus::Hash;
1150              
1151             my $lvalue = Venus::Array->new;
1152             my $rvalue = Venus::Hash->new;
1153              
1154             my $result = $lvalue->eq($rvalue);
1155              
1156             # 0
1157              
1158             =back
1159              
1160             =over 4
1161              
1162             =item eq example 5
1163              
1164             package main;
1165              
1166             use Venus::Array;
1167             use Venus::Number;
1168              
1169             my $lvalue = Venus::Array->new;
1170             my $rvalue = Venus::Number->new;
1171              
1172             my $result = $lvalue->eq($rvalue);
1173              
1174             # 0
1175              
1176             =back
1177              
1178             =over 4
1179              
1180             =item eq example 6
1181              
1182             package main;
1183              
1184             use Venus::Array;
1185             use Venus::Regexp;
1186              
1187             my $lvalue = Venus::Array->new;
1188             my $rvalue = Venus::Regexp->new;
1189              
1190             my $result = $lvalue->eq($rvalue);
1191              
1192             # 0
1193              
1194             =back
1195              
1196             =over 4
1197              
1198             =item eq example 7
1199              
1200             package main;
1201              
1202             use Venus::Array;
1203             use Venus::Scalar;
1204              
1205             my $lvalue = Venus::Array->new;
1206             my $rvalue = Venus::Scalar->new;
1207              
1208             my $result = $lvalue->eq($rvalue);
1209              
1210             # 0
1211              
1212             =back
1213              
1214             =over 4
1215              
1216             =item eq example 8
1217              
1218             package main;
1219              
1220             use Venus::Array;
1221             use Venus::String;
1222              
1223             my $lvalue = Venus::Array->new;
1224             my $rvalue = Venus::String->new;
1225              
1226             my $result = $lvalue->eq($rvalue);
1227              
1228             # 0
1229              
1230             =back
1231              
1232             =over 4
1233              
1234             =item eq example 9
1235              
1236             package main;
1237              
1238             use Venus::Array;
1239             use Venus::Undef;
1240              
1241             my $lvalue = Venus::Array->new;
1242             my $rvalue = Venus::Undef->new;
1243              
1244             my $result = $lvalue->eq($rvalue);
1245              
1246             # 0
1247              
1248             =back
1249              
1250             =cut
1251              
1252             =head2 exists
1253              
1254             exists(Int $index) (Bool)
1255              
1256             The exists method returns true if the element at the index specified exists,
1257             otherwise it returns false.
1258              
1259             I>
1260              
1261             =over 4
1262              
1263             =item exists example 1
1264              
1265             # given: synopsis;
1266              
1267             my $exists = $array->exists(0);
1268              
1269             # 1
1270              
1271             =back
1272              
1273             =cut
1274              
1275             =head2 find
1276              
1277             find(Str @keys) (Any)
1278              
1279             The find method traverses the data structure using the keys and indices
1280             provided, returning the value found or undef. In list-context, this method
1281             returns a tuple, i.e. the value found and boolean representing whether the
1282             match was successful.
1283              
1284             I>
1285              
1286             =over 4
1287              
1288             =item find example 1
1289              
1290             package main;
1291              
1292             use Venus::Array;
1293              
1294             my $array = Venus::Array->new([{'foo' => {'bar' => 'baz'}}, 'bar', ['baz']]);
1295              
1296             my $find = $array->find(0, 'foo');
1297              
1298             # { bar => "baz" }
1299              
1300             =back
1301              
1302             =over 4
1303              
1304             =item find example 2
1305              
1306             package main;
1307              
1308             use Venus::Array;
1309              
1310             my $array = Venus::Array->new([{'foo' => {'bar' => 'baz'}}, 'bar', ['baz']]);
1311              
1312             my $find = $array->find(0, 'foo', 'bar');
1313              
1314             # "baz"
1315              
1316             =back
1317              
1318             =over 4
1319              
1320             =item find example 3
1321              
1322             package main;
1323              
1324             use Venus::Array;
1325              
1326             my $array = Venus::Array->new([{'foo' => {'bar' => 'baz'}}, 'bar', ['baz']]);
1327              
1328             my $find = $array->find(2, 0);
1329              
1330             # "baz"
1331              
1332             =back
1333              
1334             =cut
1335              
1336             =head2 first
1337              
1338             first() (Any)
1339              
1340             The first method returns the value of the first element.
1341              
1342             I>
1343              
1344             =over 4
1345              
1346             =item first example 1
1347              
1348             # given: synopsis;
1349              
1350             my $first = $array->first;
1351              
1352             # 1
1353              
1354             =back
1355              
1356             =cut
1357              
1358             =head2 ge
1359              
1360             ge(Any $arg) (Bool)
1361              
1362             The ge method performs a I<"greater-than-or-equal-to"> operation using the
1363             argument provided.
1364              
1365             I>
1366              
1367             =over 4
1368              
1369             =item ge example 1
1370              
1371             package main;
1372              
1373             use Venus::Array;
1374              
1375             my $lvalue = Venus::Array->new;
1376             my $rvalue = Venus::Array->new;
1377              
1378             my $result = $lvalue->ge($rvalue);
1379              
1380             # 1
1381              
1382             =back
1383              
1384             =over 4
1385              
1386             =item ge example 2
1387              
1388             package main;
1389              
1390             use Venus::Array;
1391             use Venus::Code;
1392              
1393             my $lvalue = Venus::Array->new;
1394             my $rvalue = Venus::Code->new;
1395              
1396             my $result = $lvalue->ge($rvalue);
1397              
1398             # 0
1399              
1400             =back
1401              
1402             =over 4
1403              
1404             =item ge example 3
1405              
1406             package main;
1407              
1408             use Venus::Array;
1409             use Venus::Float;
1410              
1411             my $lvalue = Venus::Array->new;
1412             my $rvalue = Venus::Float->new;
1413              
1414             my $result = $lvalue->ge($rvalue);
1415              
1416             # 1
1417              
1418             =back
1419              
1420             =over 4
1421              
1422             =item ge example 4
1423              
1424             package main;
1425              
1426             use Venus::Array;
1427             use Venus::Hash;
1428              
1429             my $lvalue = Venus::Array->new;
1430             my $rvalue = Venus::Hash->new;
1431              
1432             my $result = $lvalue->ge($rvalue);
1433              
1434             # 0
1435              
1436             =back
1437              
1438             =over 4
1439              
1440             =item ge example 5
1441              
1442             package main;
1443              
1444             use Venus::Array;
1445             use Venus::Number;
1446              
1447             my $lvalue = Venus::Array->new;
1448             my $rvalue = Venus::Number->new;
1449              
1450             my $result = $lvalue->ge($rvalue);
1451              
1452             # 1
1453              
1454             =back
1455              
1456             =over 4
1457              
1458             =item ge example 6
1459              
1460             package main;
1461              
1462             use Venus::Array;
1463             use Venus::Regexp;
1464              
1465             my $lvalue = Venus::Array->new;
1466             my $rvalue = Venus::Regexp->new;
1467              
1468             my $result = $lvalue->ge($rvalue);
1469              
1470             # 0
1471              
1472             =back
1473              
1474             =over 4
1475              
1476             =item ge example 7
1477              
1478             package main;
1479              
1480             use Venus::Array;
1481             use Venus::Scalar;
1482              
1483             my $lvalue = Venus::Array->new;
1484             my $rvalue = Venus::Scalar->new;
1485              
1486             my $result = $lvalue->ge($rvalue);
1487              
1488             # 0
1489              
1490             =back
1491              
1492             =over 4
1493              
1494             =item ge example 8
1495              
1496             package main;
1497              
1498             use Venus::Array;
1499             use Venus::String;
1500              
1501             my $lvalue = Venus::Array->new;
1502             my $rvalue = Venus::String->new;
1503              
1504             my $result = $lvalue->ge($rvalue);
1505              
1506             # 1
1507              
1508             =back
1509              
1510             =over 4
1511              
1512             =item ge example 9
1513              
1514             package main;
1515              
1516             use Venus::Array;
1517             use Venus::Undef;
1518              
1519             my $lvalue = Venus::Array->new;
1520             my $rvalue = Venus::Undef->new;
1521              
1522             my $result = $lvalue->ge($rvalue);
1523              
1524             # 1
1525              
1526             =back
1527              
1528             =cut
1529              
1530             =head2 gele
1531              
1532             gele(Any $arg1, Any $arg2) (Bool)
1533              
1534             The gele method performs a I<"greater-than-or-equal-to"> operation on the 1st
1535             argument, and I<"lesser-than-or-equal-to"> operation on the 2nd argument.
1536              
1537             I>
1538              
1539             =over 4
1540              
1541             =item gele example 1
1542              
1543             package main;
1544              
1545             use Venus::Array;
1546              
1547             my $lvalue = Venus::Array->new;
1548             my $rvalue = Venus::Array->new;
1549              
1550             my $result = $lvalue->gele($rvalue);
1551              
1552             # 0
1553              
1554             =back
1555              
1556             =over 4
1557              
1558             =item gele example 2
1559              
1560             package main;
1561              
1562             use Venus::Array;
1563             use Venus::Code;
1564              
1565             my $lvalue = Venus::Array->new;
1566             my $rvalue = Venus::Code->new;
1567              
1568             my $result = $lvalue->gele($rvalue);
1569              
1570             # 0
1571              
1572             =back
1573              
1574             =over 4
1575              
1576             =item gele example 3
1577              
1578             package main;
1579              
1580             use Venus::Array;
1581             use Venus::Float;
1582              
1583             my $lvalue = Venus::Array->new;
1584             my $rvalue = Venus::Float->new;
1585              
1586             my $result = $lvalue->gele($rvalue);
1587              
1588             # 0
1589              
1590             =back
1591              
1592             =over 4
1593              
1594             =item gele example 4
1595              
1596             package main;
1597              
1598             use Venus::Array;
1599             use Venus::Hash;
1600              
1601             my $lvalue = Venus::Array->new;
1602             my $rvalue = Venus::Hash->new;
1603              
1604             my $result = $lvalue->gele($rvalue);
1605              
1606             # 0
1607              
1608             =back
1609              
1610             =over 4
1611              
1612             =item gele example 5
1613              
1614             package main;
1615              
1616             use Venus::Array;
1617             use Venus::Number;
1618              
1619             my $lvalue = Venus::Array->new;
1620             my $rvalue = Venus::Number->new;
1621              
1622             my $result = $lvalue->gele($rvalue);
1623              
1624             # 0
1625              
1626             =back
1627              
1628             =over 4
1629              
1630             =item gele example 6
1631              
1632             package main;
1633              
1634             use Venus::Array;
1635             use Venus::Regexp;
1636              
1637             my $lvalue = Venus::Array->new;
1638             my $rvalue = Venus::Regexp->new;
1639              
1640             my $result = $lvalue->gele($rvalue);
1641              
1642             # 0
1643              
1644             =back
1645              
1646             =over 4
1647              
1648             =item gele example 7
1649              
1650             package main;
1651              
1652             use Venus::Array;
1653             use Venus::Scalar;
1654              
1655             my $lvalue = Venus::Array->new;
1656             my $rvalue = Venus::Scalar->new;
1657              
1658             my $result = $lvalue->gele($rvalue);
1659              
1660             # 0
1661              
1662             =back
1663              
1664             =over 4
1665              
1666             =item gele example 8
1667              
1668             package main;
1669              
1670             use Venus::Array;
1671             use Venus::String;
1672              
1673             my $lvalue = Venus::Array->new;
1674             my $rvalue = Venus::String->new;
1675              
1676             my $result = $lvalue->gele($rvalue);
1677              
1678             # 0
1679              
1680             =back
1681              
1682             =over 4
1683              
1684             =item gele example 9
1685              
1686             package main;
1687              
1688             use Venus::Array;
1689             use Venus::Undef;
1690              
1691             my $lvalue = Venus::Array->new;
1692             my $rvalue = Venus::Undef->new;
1693              
1694             my $result = $lvalue->gele($rvalue);
1695              
1696             # 0
1697              
1698             =back
1699              
1700             =cut
1701              
1702             =head2 grep
1703              
1704             grep(CodeRef $code) (ArrayRef)
1705              
1706             The grep method executes a callback for each element in the array passing the
1707             value as an argument, returning a new array reference containing the elements
1708             for which the returned true. This method can return a list of values in
1709             list-context.
1710              
1711             I>
1712              
1713             =over 4
1714              
1715             =item grep example 1
1716              
1717             # given: synopsis;
1718              
1719             my $grep = $array->grep(sub {
1720             $_ > 3
1721             });
1722              
1723             # [4..9]
1724              
1725             =back
1726              
1727             =over 4
1728              
1729             =item grep example 2
1730              
1731             # given: synopsis;
1732              
1733             my $grep = $array->grep(sub {
1734             my ($key, $value) = @_;
1735              
1736             $value > 3
1737             });
1738              
1739             # [4..9]
1740              
1741             =back
1742              
1743             =cut
1744              
1745             =head2 gt
1746              
1747             gt(Any $arg) (Bool)
1748              
1749             The gt method performs a I<"greater-than"> operation using the argument provided.
1750              
1751             I>
1752              
1753             =over 4
1754              
1755             =item gt example 1
1756              
1757             package main;
1758              
1759             use Venus::Array;
1760              
1761             my $lvalue = Venus::Array->new;
1762             my $rvalue = Venus::Array->new;
1763              
1764             my $result = $lvalue->gt($rvalue);
1765              
1766             # 0
1767              
1768             =back
1769              
1770             =over 4
1771              
1772             =item gt example 2
1773              
1774             package main;
1775              
1776             use Venus::Array;
1777             use Venus::Code;
1778              
1779             my $lvalue = Venus::Array->new;
1780             my $rvalue = Venus::Code->new;
1781              
1782             my $result = $lvalue->gt($rvalue);
1783              
1784             # 0
1785              
1786             =back
1787              
1788             =over 4
1789              
1790             =item gt example 3
1791              
1792             package main;
1793              
1794             use Venus::Array;
1795             use Venus::Float;
1796              
1797             my $lvalue = Venus::Array->new;
1798             my $rvalue = Venus::Float->new;
1799              
1800             my $result = $lvalue->gt($rvalue);
1801              
1802             # 1
1803              
1804             =back
1805              
1806             =over 4
1807              
1808             =item gt example 4
1809              
1810             package main;
1811              
1812             use Venus::Array;
1813             use Venus::Hash;
1814              
1815             my $lvalue = Venus::Array->new;
1816             my $rvalue = Venus::Hash->new;
1817              
1818             my $result = $lvalue->gt($rvalue);
1819              
1820             # 0
1821              
1822             =back
1823              
1824             =over 4
1825              
1826             =item gt example 5
1827              
1828             package main;
1829              
1830             use Venus::Array;
1831             use Venus::Number;
1832              
1833             my $lvalue = Venus::Array->new;
1834             my $rvalue = Venus::Number->new;
1835              
1836             my $result = $lvalue->gt($rvalue);
1837              
1838             # 1
1839              
1840             =back
1841              
1842             =over 4
1843              
1844             =item gt example 6
1845              
1846             package main;
1847              
1848             use Venus::Array;
1849             use Venus::Regexp;
1850              
1851             my $lvalue = Venus::Array->new;
1852             my $rvalue = Venus::Regexp->new;
1853              
1854             my $result = $lvalue->gt($rvalue);
1855              
1856             # 0
1857              
1858             =back
1859              
1860             =over 4
1861              
1862             =item gt example 7
1863              
1864             package main;
1865              
1866             use Venus::Array;
1867             use Venus::Scalar;
1868              
1869             my $lvalue = Venus::Array->new;
1870             my $rvalue = Venus::Scalar->new;
1871              
1872             my $result = $lvalue->gt($rvalue);
1873              
1874             # 0
1875              
1876             =back
1877              
1878             =over 4
1879              
1880             =item gt example 8
1881              
1882             package main;
1883              
1884             use Venus::Array;
1885             use Venus::String;
1886              
1887             my $lvalue = Venus::Array->new;
1888             my $rvalue = Venus::String->new;
1889              
1890             my $result = $lvalue->gt($rvalue);
1891              
1892             # 1
1893              
1894             =back
1895              
1896             =over 4
1897              
1898             =item gt example 9
1899              
1900             package main;
1901              
1902             use Venus::Array;
1903             use Venus::Undef;
1904              
1905             my $lvalue = Venus::Array->new;
1906             my $rvalue = Venus::Undef->new;
1907              
1908             my $result = $lvalue->gt($rvalue);
1909              
1910             # 1
1911              
1912             =back
1913              
1914             =cut
1915              
1916             =head2 gtlt
1917              
1918             gtlt(Any $arg1, Any $arg2) (Bool)
1919              
1920             The gtlt method performs a I<"greater-than"> operation on the 1st argument, and
1921             I<"lesser-than"> operation on the 2nd argument.
1922              
1923             I>
1924              
1925             =over 4
1926              
1927             =item gtlt example 1
1928              
1929             package main;
1930              
1931             use Venus::Array;
1932              
1933             my $lvalue = Venus::Array->new;
1934             my $rvalue = Venus::Array->new;
1935              
1936             my $result = $lvalue->gtlt($rvalue);
1937              
1938             # 0
1939              
1940             =back
1941              
1942             =over 4
1943              
1944             =item gtlt example 2
1945              
1946             package main;
1947              
1948             use Venus::Array;
1949             use Venus::Code;
1950              
1951             my $lvalue = Venus::Array->new;
1952             my $rvalue = Venus::Code->new;
1953              
1954             my $result = $lvalue->gtlt($rvalue);
1955              
1956             # 0
1957              
1958             =back
1959              
1960             =over 4
1961              
1962             =item gtlt example 3
1963              
1964             package main;
1965              
1966             use Venus::Array;
1967             use Venus::Float;
1968              
1969             my $lvalue = Venus::Array->new;
1970             my $rvalue = Venus::Float->new;
1971              
1972             my $result = $lvalue->gtlt($rvalue);
1973              
1974             # 0
1975              
1976             =back
1977              
1978             =over 4
1979              
1980             =item gtlt example 4
1981              
1982             package main;
1983              
1984             use Venus::Array;
1985             use Venus::Hash;
1986              
1987             my $lvalue = Venus::Array->new;
1988             my $rvalue = Venus::Hash->new;
1989              
1990             my $result = $lvalue->gtlt($rvalue);
1991              
1992             # 0
1993              
1994             =back
1995              
1996             =over 4
1997              
1998             =item gtlt example 5
1999              
2000             package main;
2001              
2002             use Venus::Array;
2003             use Venus::Number;
2004              
2005             my $lvalue = Venus::Array->new;
2006             my $rvalue = Venus::Number->new;
2007              
2008             my $result = $lvalue->gtlt($rvalue);
2009              
2010             # 0
2011              
2012             =back
2013              
2014             =over 4
2015              
2016             =item gtlt example 6
2017              
2018             package main;
2019              
2020             use Venus::Array;
2021             use Venus::Regexp;
2022              
2023             my $lvalue = Venus::Array->new;
2024             my $rvalue = Venus::Regexp->new;
2025              
2026             my $result = $lvalue->gtlt($rvalue);
2027              
2028             # 0
2029              
2030             =back
2031              
2032             =over 4
2033              
2034             =item gtlt example 7
2035              
2036             package main;
2037              
2038             use Venus::Array;
2039             use Venus::Scalar;
2040              
2041             my $lvalue = Venus::Array->new;
2042             my $rvalue = Venus::Scalar->new;
2043              
2044             my $result = $lvalue->gtlt($rvalue);
2045              
2046             # 0
2047              
2048             =back
2049              
2050             =over 4
2051              
2052             =item gtlt example 8
2053              
2054             package main;
2055              
2056             use Venus::Array;
2057             use Venus::String;
2058              
2059             my $lvalue = Venus::Array->new;
2060             my $rvalue = Venus::String->new;
2061              
2062             my $result = $lvalue->gtlt($rvalue);
2063              
2064             # 0
2065              
2066             =back
2067              
2068             =over 4
2069              
2070             =item gtlt example 9
2071              
2072             package main;
2073              
2074             use Venus::Array;
2075             use Venus::Undef;
2076              
2077             my $lvalue = Venus::Array->new;
2078             my $rvalue = Venus::Undef->new;
2079              
2080             my $result = $lvalue->gtlt($rvalue);
2081              
2082             # 0
2083              
2084             =back
2085              
2086             =cut
2087              
2088             =head2 iterator
2089              
2090             iterator() (CodeRef)
2091              
2092             The iterator method returns a code reference which can be used to iterate over
2093             the array. Each time the iterator is executed it will return the next element
2094             in the array until all elements have been seen, at which point the iterator
2095             will return an undefined value. This method can return a tuple with the key and
2096             value in list-context.
2097              
2098             I>
2099              
2100             =over 4
2101              
2102             =item iterator example 1
2103              
2104             # given: synopsis;
2105              
2106             my $iterator = $array->iterator;
2107              
2108             # sub { ... }
2109              
2110             # while (my $value = $iterator->()) {
2111             # say $value; # 1
2112             # }
2113              
2114             =back
2115              
2116             =over 4
2117              
2118             =item iterator example 2
2119              
2120             # given: synopsis;
2121              
2122             my $iterator = $array->iterator;
2123              
2124             # sub { ... }
2125              
2126             # while (grep defined, my ($key, $value) = $iterator->()) {
2127             # say $value; # 1
2128             # }
2129              
2130             =back
2131              
2132             =cut
2133              
2134             =head2 join
2135              
2136             join(Str $seperator) (Str)
2137              
2138             The join method returns a string consisting of all the elements in the array
2139             joined by the join-string specified by the argument. Note: If the argument is
2140             omitted, an empty string will be used as the join-string.
2141              
2142             I>
2143              
2144             =over 4
2145              
2146             =item join example 1
2147              
2148             # given: synopsis;
2149              
2150             my $join = $array->join;
2151              
2152             # 123456789
2153              
2154             =back
2155              
2156             =over 4
2157              
2158             =item join example 2
2159              
2160             # given: synopsis;
2161              
2162             my $join = $array->join(', ');
2163              
2164             # "1, 2, 3, 4, 5, 6, 7, 8, 9"
2165              
2166             =back
2167              
2168             =cut
2169              
2170             =head2 keyed
2171              
2172             keyed(Str @keys) (HashRef)
2173              
2174             The keyed method returns a hash reference where the arguments become the keys,
2175             and the elements of the array become the values.
2176              
2177             I>
2178              
2179             =over 4
2180              
2181             =item keyed example 1
2182              
2183             package main;
2184              
2185             use Venus::Array;
2186              
2187             my $array = Venus::Array->new([1..4]);
2188              
2189             my $keyed = $array->keyed('a'..'d');
2190              
2191             # { a => 1, b => 2, c => 3, d => 4 }
2192              
2193             =back
2194              
2195             =cut
2196              
2197             =head2 keys
2198              
2199             keys() (ArrayRef)
2200              
2201             The keys method returns an array reference consisting of the indicies of the
2202             array.
2203              
2204             I>
2205              
2206             =over 4
2207              
2208             =item keys example 1
2209              
2210             # given: synopsis;
2211              
2212             my $keys = $array->keys;
2213              
2214             # [0..8]
2215              
2216             =back
2217              
2218             =cut
2219              
2220             =head2 last
2221              
2222             last() (Any)
2223              
2224             The last method returns the value of the last element in the array.
2225              
2226             I>
2227              
2228             =over 4
2229              
2230             =item last example 1
2231              
2232             # given: synopsis;
2233              
2234             my $last = $array->last;
2235              
2236             # 9
2237              
2238             =back
2239              
2240             =cut
2241              
2242             =head2 le
2243              
2244             le(Any $arg) (Bool)
2245              
2246             The le method performs a I<"lesser-than-or-equal-to"> operation using the
2247             argument provided.
2248              
2249             I>
2250              
2251             =over 4
2252              
2253             =item le example 1
2254              
2255             package main;
2256              
2257             use Venus::Array;
2258              
2259             my $lvalue = Venus::Array->new;
2260             my $rvalue = Venus::Array->new;
2261              
2262             my $result = $lvalue->le($rvalue);
2263              
2264             # 1
2265              
2266             =back
2267              
2268             =over 4
2269              
2270             =item le example 2
2271              
2272             package main;
2273              
2274             use Venus::Array;
2275             use Venus::Code;
2276              
2277             my $lvalue = Venus::Array->new;
2278             my $rvalue = Venus::Code->new;
2279              
2280             my $result = $lvalue->le($rvalue);
2281              
2282             # 1
2283              
2284             =back
2285              
2286             =over 4
2287              
2288             =item le example 3
2289              
2290             package main;
2291              
2292             use Venus::Array;
2293             use Venus::Float;
2294              
2295             my $lvalue = Venus::Array->new;
2296             my $rvalue = Venus::Float->new;
2297              
2298             my $result = $lvalue->le($rvalue);
2299              
2300             # 0
2301              
2302             =back
2303              
2304             =over 4
2305              
2306             =item le example 4
2307              
2308             package main;
2309              
2310             use Venus::Array;
2311             use Venus::Hash;
2312              
2313             my $lvalue = Venus::Array->new;
2314             my $rvalue = Venus::Hash->new;
2315              
2316             my $result = $lvalue->le($rvalue);
2317              
2318             # 0
2319              
2320             =back
2321              
2322             =over 4
2323              
2324             =item le example 5
2325              
2326             package main;
2327              
2328             use Venus::Array;
2329             use Venus::Number;
2330              
2331             my $lvalue = Venus::Array->new;
2332             my $rvalue = Venus::Number->new;
2333              
2334             my $result = $lvalue->le($rvalue);
2335              
2336             # 0
2337              
2338             =back
2339              
2340             =over 4
2341              
2342             =item le example 6
2343              
2344             package main;
2345              
2346             use Venus::Array;
2347             use Venus::Regexp;
2348              
2349             my $lvalue = Venus::Array->new;
2350             my $rvalue = Venus::Regexp->new;
2351              
2352             my $result = $lvalue->le($rvalue);
2353              
2354             # 1
2355              
2356             =back
2357              
2358             =over 4
2359              
2360             =item le example 7
2361              
2362             package main;
2363              
2364             use Venus::Array;
2365             use Venus::Scalar;
2366              
2367             my $lvalue = Venus::Array->new;
2368             my $rvalue = Venus::Scalar->new;
2369              
2370             my $result = $lvalue->le($rvalue);
2371              
2372             # 0
2373              
2374             =back
2375              
2376             =over 4
2377              
2378             =item le example 8
2379              
2380             package main;
2381              
2382             use Venus::Array;
2383             use Venus::String;
2384              
2385             my $lvalue = Venus::Array->new;
2386             my $rvalue = Venus::String->new;
2387              
2388             my $result = $lvalue->le($rvalue);
2389              
2390             # 0
2391              
2392             =back
2393              
2394             =over 4
2395              
2396             =item le example 9
2397              
2398             package main;
2399              
2400             use Venus::Array;
2401             use Venus::Undef;
2402              
2403             my $lvalue = Venus::Array->new;
2404             my $rvalue = Venus::Undef->new;
2405              
2406             my $result = $lvalue->le($rvalue);
2407              
2408             # 0
2409              
2410             =back
2411              
2412             =cut
2413              
2414             =head2 length
2415              
2416             length() (Int)
2417              
2418             The length method returns the number of elements within the array, and is an
2419             alias for the L method.
2420              
2421             I>
2422              
2423             =over 4
2424              
2425             =item length example 1
2426              
2427             # given: synopsis;
2428              
2429             my $length = $array->length;
2430              
2431             # 9
2432              
2433             =back
2434              
2435             =cut
2436              
2437             =head2 list
2438              
2439             list() (Any)
2440              
2441             The list method returns a shallow copy of the underlying array reference as an
2442             array reference.
2443              
2444             I>
2445              
2446             =over 4
2447              
2448             =item list example 1
2449              
2450             # given: synopsis;
2451              
2452             my $list = $array->list;
2453              
2454             # 9
2455              
2456             =back
2457              
2458             =over 4
2459              
2460             =item list example 2
2461              
2462             # given: synopsis;
2463              
2464             my @list = $array->list;
2465              
2466             # (1..9)
2467              
2468             =back
2469              
2470             =cut
2471              
2472             =head2 lt
2473              
2474             lt(Any $arg) (Bool)
2475              
2476             The lt method performs a I<"lesser-than"> operation using the argument provided.
2477              
2478             I>
2479              
2480             =over 4
2481              
2482             =item lt example 1
2483              
2484             package main;
2485              
2486             use Venus::Array;
2487              
2488             my $lvalue = Venus::Array->new;
2489             my $rvalue = Venus::Array->new;
2490              
2491             my $result = $lvalue->lt($rvalue);
2492              
2493             # 0
2494              
2495             =back
2496              
2497             =over 4
2498              
2499             =item lt example 2
2500              
2501             package main;
2502              
2503             use Venus::Array;
2504             use Venus::Code;
2505              
2506             my $lvalue = Venus::Array->new;
2507             my $rvalue = Venus::Code->new;
2508              
2509             my $result = $lvalue->lt($rvalue);
2510              
2511             # 1
2512              
2513             =back
2514              
2515             =over 4
2516              
2517             =item lt example 3
2518              
2519             package main;
2520              
2521             use Venus::Array;
2522             use Venus::Float;
2523              
2524             my $lvalue = Venus::Array->new;
2525             my $rvalue = Venus::Float->new;
2526              
2527             my $result = $lvalue->lt($rvalue);
2528              
2529             # 0
2530              
2531             =back
2532              
2533             =over 4
2534              
2535             =item lt example 4
2536              
2537             package main;
2538              
2539             use Venus::Array;
2540             use Venus::Hash;
2541              
2542             my $lvalue = Venus::Array->new;
2543             my $rvalue = Venus::Hash->new;
2544              
2545             my $result = $lvalue->lt($rvalue);
2546              
2547             # 0
2548              
2549             =back
2550              
2551             =over 4
2552              
2553             =item lt example 5
2554              
2555             package main;
2556              
2557             use Venus::Array;
2558             use Venus::Number;
2559              
2560             my $lvalue = Venus::Array->new;
2561             my $rvalue = Venus::Number->new;
2562              
2563             my $result = $lvalue->lt($rvalue);
2564              
2565             # 0
2566              
2567             =back
2568              
2569             =over 4
2570              
2571             =item lt example 6
2572              
2573             package main;
2574              
2575             use Venus::Array;
2576             use Venus::Regexp;
2577              
2578             my $lvalue = Venus::Array->new;
2579             my $rvalue = Venus::Regexp->new;
2580              
2581             my $result = $lvalue->lt($rvalue);
2582              
2583             # 1
2584              
2585             =back
2586              
2587             =over 4
2588              
2589             =item lt example 7
2590              
2591             package main;
2592              
2593             use Venus::Array;
2594             use Venus::Scalar;
2595              
2596             my $lvalue = Venus::Array->new;
2597             my $rvalue = Venus::Scalar->new;
2598              
2599             my $result = $lvalue->lt($rvalue);
2600              
2601             # 0
2602              
2603             =back
2604              
2605             =over 4
2606              
2607             =item lt example 8
2608              
2609             package main;
2610              
2611             use Venus::Array;
2612             use Venus::String;
2613              
2614             my $lvalue = Venus::Array->new;
2615             my $rvalue = Venus::String->new;
2616              
2617             my $result = $lvalue->lt($rvalue);
2618              
2619             # 0
2620              
2621             =back
2622              
2623             =over 4
2624              
2625             =item lt example 9
2626              
2627             package main;
2628              
2629             use Venus::Array;
2630             use Venus::Undef;
2631              
2632             my $lvalue = Venus::Array->new;
2633             my $rvalue = Venus::Undef->new;
2634              
2635             my $result = $lvalue->lt($rvalue);
2636              
2637             # 0
2638              
2639             =back
2640              
2641             =cut
2642              
2643             =head2 map
2644              
2645             map(CodeRef $code) (ArrayRef)
2646              
2647             The map method iterates over each element in the array, executing the code
2648             reference supplied in the argument, passing the routine the value at the
2649             current position in the loop and returning a new array reference containing the
2650             elements for which the argument returns a value or non-empty list. This method
2651             can return a list of values in list-context.
2652              
2653             I>
2654              
2655             =over 4
2656              
2657             =item map example 1
2658              
2659             # given: synopsis;
2660              
2661             my $map = $array->map(sub {
2662             $_ * 2
2663             });
2664              
2665             # [2, 4, 6, 8, 10, 12, 14, 16, 18]
2666              
2667             =back
2668              
2669             =over 4
2670              
2671             =item map example 2
2672              
2673             # given: synopsis;
2674              
2675             my $map = $array->map(sub {
2676             my ($key, $value) = @_;
2677              
2678             [$key, ($value * 2)]
2679             });
2680              
2681             # [
2682             # [0, 2],
2683             # [1, 4],
2684             # [2, 6],
2685             # [3, 8],
2686             # [4, 10],
2687             # [5, 12],
2688             # [6, 14],
2689             # [7, 16],
2690             # [8, 18],
2691             # ]
2692              
2693             =back
2694              
2695             =cut
2696              
2697             =head2 merge
2698              
2699             merge(ArrayRef @data) (ArrayRef)
2700              
2701             The merge method returns an array reference where the elements in the array and
2702             the elements in the argument(s) are merged. This operation performs a deep
2703             merge and clones the datasets to ensure no side-effects.
2704              
2705             I>
2706              
2707             =over 4
2708              
2709             =item merge example 1
2710              
2711             # given: synopsis;
2712              
2713             my $merge = $array->merge([10..15]);
2714              
2715             # [10..15,7,8,9]
2716              
2717             =back
2718              
2719             =over 4
2720              
2721             =item merge example 2
2722              
2723             # given: synopsis;
2724              
2725             my $merge = $array->merge([1,2,{1..4},4..9]);
2726              
2727             # [1,2,{1..4},4..9]
2728              
2729             =back
2730              
2731             =cut
2732              
2733             =head2 ne
2734              
2735             ne(Any $arg) (Bool)
2736              
2737             The ne method performs a I<"not-equal-to"> operation using the argument provided.
2738              
2739             I>
2740              
2741             =over 4
2742              
2743             =item ne example 1
2744              
2745             package main;
2746              
2747             use Venus::Array;
2748              
2749             my $lvalue = Venus::Array->new;
2750             my $rvalue = Venus::Array->new;
2751              
2752             my $result = $lvalue->ne($rvalue);
2753              
2754             # 0
2755              
2756             =back
2757              
2758             =over 4
2759              
2760             =item ne example 2
2761              
2762             package main;
2763              
2764             use Venus::Array;
2765             use Venus::Code;
2766              
2767             my $lvalue = Venus::Array->new;
2768             my $rvalue = Venus::Code->new;
2769              
2770             my $result = $lvalue->ne($rvalue);
2771              
2772             # 1
2773              
2774             =back
2775              
2776             =over 4
2777              
2778             =item ne example 3
2779              
2780             package main;
2781              
2782             use Venus::Array;
2783             use Venus::Float;
2784              
2785             my $lvalue = Venus::Array->new;
2786             my $rvalue = Venus::Float->new;
2787              
2788             my $result = $lvalue->ne($rvalue);
2789              
2790             # 1
2791              
2792             =back
2793              
2794             =over 4
2795              
2796             =item ne example 4
2797              
2798             package main;
2799              
2800             use Venus::Array;
2801             use Venus::Hash;
2802              
2803             my $lvalue = Venus::Array->new;
2804             my $rvalue = Venus::Hash->new;
2805              
2806             my $result = $lvalue->ne($rvalue);
2807              
2808             # 1
2809              
2810             =back
2811              
2812             =over 4
2813              
2814             =item ne example 5
2815              
2816             package main;
2817              
2818             use Venus::Array;
2819             use Venus::Number;
2820              
2821             my $lvalue = Venus::Array->new;
2822             my $rvalue = Venus::Number->new;
2823              
2824             my $result = $lvalue->ne($rvalue);
2825              
2826             # 1
2827              
2828             =back
2829              
2830             =over 4
2831              
2832             =item ne example 6
2833              
2834             package main;
2835              
2836             use Venus::Array;
2837             use Venus::Regexp;
2838              
2839             my $lvalue = Venus::Array->new;
2840             my $rvalue = Venus::Regexp->new;
2841              
2842             my $result = $lvalue->ne($rvalue);
2843              
2844             # 1
2845              
2846             =back
2847              
2848             =over 4
2849              
2850             =item ne example 7
2851              
2852             package main;
2853              
2854             use Venus::Array;
2855             use Venus::Scalar;
2856              
2857             my $lvalue = Venus::Array->new;
2858             my $rvalue = Venus::Scalar->new;
2859              
2860             my $result = $lvalue->ne($rvalue);
2861              
2862             # 1
2863              
2864             =back
2865              
2866             =over 4
2867              
2868             =item ne example 8
2869              
2870             package main;
2871              
2872             use Venus::Array;
2873             use Venus::String;
2874              
2875             my $lvalue = Venus::Array->new;
2876             my $rvalue = Venus::String->new;
2877              
2878             my $result = $lvalue->ne($rvalue);
2879              
2880             # 1
2881              
2882             =back
2883              
2884             =over 4
2885              
2886             =item ne example 9
2887              
2888             package main;
2889              
2890             use Venus::Array;
2891             use Venus::Undef;
2892              
2893             my $lvalue = Venus::Array->new;
2894             my $rvalue = Venus::Undef->new;
2895              
2896             my $result = $lvalue->ne($rvalue);
2897              
2898             # 1
2899              
2900             =back
2901              
2902             =cut
2903              
2904             =head2 none
2905              
2906             none(CodeRef $code) (Bool)
2907              
2908             The none method returns true if none of the elements in the array meet the
2909             criteria set by the operand and rvalue.
2910              
2911             I>
2912              
2913             =over 4
2914              
2915             =item none example 1
2916              
2917             # given: synopsis;
2918              
2919             my $none = $array->none(sub {
2920             $_ < 1
2921             });
2922              
2923             # 1
2924              
2925             =back
2926              
2927             =over 4
2928              
2929             =item none example 2
2930              
2931             # given: synopsis;
2932              
2933             my $none = $array->none(sub {
2934             my ($key, $value) = @_;
2935              
2936             $value < 1
2937             });
2938              
2939             # 1
2940              
2941             =back
2942              
2943             =cut
2944              
2945             =head2 one
2946              
2947             one(CodeRef $code) (Bool)
2948              
2949             The one method returns true if only one of the elements in the array meet the
2950             criteria set by the operand and rvalue.
2951              
2952             I>
2953              
2954             =over 4
2955              
2956             =item one example 1
2957              
2958             # given: synopsis;
2959              
2960             my $one = $array->one(sub {
2961             $_ == 1
2962             });
2963              
2964             # 1
2965              
2966             =back
2967              
2968             =over 4
2969              
2970             =item one example 2
2971              
2972             # given: synopsis;
2973              
2974             my $one = $array->one(sub {
2975             my ($key, $value) = @_;
2976              
2977             $value == 1
2978             });
2979              
2980             # 1
2981              
2982             =back
2983              
2984             =cut
2985              
2986             =head2 order
2987              
2988             order(Int @indices) (Array)
2989              
2990             The order method reorders the array items based on the indices provided and
2991             returns the invocant.
2992              
2993             I>
2994              
2995             =over 4
2996              
2997             =item order example 1
2998              
2999             # given: synopsis;
3000              
3001             my $order = $array->order;
3002              
3003             # bless({ value => [1..9] }, "Venus::Array")
3004              
3005             =back
3006              
3007             =over 4
3008              
3009             =item order example 2
3010              
3011             # given: synopsis;
3012              
3013             my $order = $array->order(8,7,6);
3014              
3015             # bless({ value => [9,8,7,1,2,3,4,5,6] }, "Venus::Array")
3016              
3017             =back
3018              
3019             =over 4
3020              
3021             =item order example 3
3022              
3023             # given: synopsis;
3024              
3025             my $order = $array->order(0,2,1);
3026              
3027             # bless({ value => [1,3,2,4,5,6,7,8,9] }, "Venus::Array")
3028              
3029             =back
3030              
3031             =cut
3032              
3033             =head2 pairs
3034              
3035             pairs() (ArrayRef)
3036              
3037             The pairs method is an alias to the pairs_array method. This method can return
3038             a list of values in list-context.
3039              
3040             I>
3041              
3042             =over 4
3043              
3044             =item pairs example 1
3045              
3046             # given: synopsis;
3047              
3048             my $pairs = $array->pairs;
3049              
3050             # [
3051             # [0, 1],
3052             # [1, 2],
3053             # [2, 3],
3054             # [3, 4],
3055             # [4, 5],
3056             # [5, 6],
3057             # [6, 7],
3058             # [7, 8],
3059             # [8, 9],
3060             # ]
3061              
3062             =back
3063              
3064             =cut
3065              
3066             =head2 part
3067              
3068             part(CodeRef $code) (Tuple[ArrayRef, ArrayRef])
3069              
3070             The part method iterates over each element in the array, executing the code
3071             reference supplied in the argument, using the result of the code reference to
3072             partition to array into two distinct array references. This method can return a
3073             list of values in list-context.
3074              
3075             I>
3076              
3077             =over 4
3078              
3079             =item part example 1
3080              
3081             # given: synopsis;
3082              
3083             my $part = $array->part(sub {
3084             $_ > 5
3085             });
3086              
3087             # [[6..9], [1..5]]
3088              
3089             =back
3090              
3091             =over 4
3092              
3093             =item part example 2
3094              
3095             # given: synopsis;
3096              
3097             my $part = $array->part(sub {
3098             my ($key, $value) = @_;
3099              
3100             $value < 5
3101             });
3102              
3103             # [[1..4], [5..9]]
3104              
3105             =back
3106              
3107             =cut
3108              
3109             =head2 path
3110              
3111             path(Str $expr) (Any)
3112              
3113             The path method traverses the data structure using the path expr provided,
3114             returning the value found or undef. In list-context, this method returns a
3115             tuple, i.e. the value found and boolean representing whether the match was
3116             successful.
3117              
3118             I>
3119              
3120             =over 4
3121              
3122             =item path example 1
3123              
3124             package main;
3125              
3126             use Venus::Array;
3127              
3128             my $array = Venus::Array->new([{'foo' => {'bar' => 'baz'}}, 'bar', ['baz']]);
3129              
3130             my $path = $array->path('/0/foo');
3131              
3132             # { bar => "baz" }
3133              
3134             =back
3135              
3136             =over 4
3137              
3138             =item path example 2
3139              
3140             package main;
3141              
3142             use Venus::Array;
3143              
3144             my $array = Venus::Array->new([{'foo' => {'bar' => 'baz'}}, 'bar', ['baz']]);
3145              
3146             my $path = $array->path('/0/foo/bar');
3147              
3148             # "baz"
3149              
3150             =back
3151              
3152             =over 4
3153              
3154             =item path example 3
3155              
3156             package main;
3157              
3158             use Venus::Array;
3159              
3160             my $array = Venus::Array->new([{'foo' => {'bar' => 'baz'}}, 'bar', ['baz']]);
3161              
3162             my $path = $array->path('/2/0');
3163              
3164             # "baz"
3165              
3166             =back
3167              
3168             =over 4
3169              
3170             =item path example 4
3171              
3172             package main;
3173              
3174             use Venus::Array;
3175              
3176             my $array = Venus::Array->new([{'foo' => {'bar' => 'baz'}}, 'bar', ['baz']]);
3177              
3178             my @path = $array->path('/3/0');
3179              
3180             # (undef, 0)
3181              
3182             =back
3183              
3184             =cut
3185              
3186             =head2 pop
3187              
3188             pop() (Any)
3189              
3190             The pop method returns the last element of the array shortening it by one.
3191             Note, this method modifies the array.
3192              
3193             I>
3194              
3195             =over 4
3196              
3197             =item pop example 1
3198              
3199             # given: synopsis;
3200              
3201             my $pop = $array->pop;
3202              
3203             # 9
3204              
3205             =back
3206              
3207             =cut
3208              
3209             =head2 push
3210              
3211             push(Any @data) (ArrayRef)
3212              
3213             The push method appends the array by pushing the agruments onto it and returns
3214             itself.
3215              
3216             I>
3217              
3218             =over 4
3219              
3220             =item push example 1
3221              
3222             # given: synopsis;
3223              
3224             my $push = $array->push(10);
3225              
3226             # [1..10]
3227              
3228             =back
3229              
3230             =cut
3231              
3232             =head2 puts
3233              
3234             puts(Any @args) (ArrayRef)
3235              
3236             The puts method select values from within the underlying data structure using
3237             L, optionally assigning the value to the preceeding scalar
3238             reference and returns all the values selected.
3239              
3240             I>
3241              
3242             =over 4
3243              
3244             =item puts example 1
3245              
3246             package main;
3247              
3248             use Venus::Array;
3249              
3250             my $array = Venus::Array->new([
3251             {
3252             fruit => "apple",
3253             size => "small",
3254             color => "red",
3255             },
3256             {
3257             fruit => "lemon",
3258             size => "large",
3259             color => "yellow",
3260             },
3261             ]);
3262              
3263             my $puts = $array->puts(undef, '0.fruit', undef, '1.fruit');
3264              
3265             # ["apple", "lemon"]
3266              
3267             =back
3268              
3269             =over 4
3270              
3271             =item puts example 2
3272              
3273             package main;
3274              
3275             use Venus::Array;
3276              
3277             my $array = Venus::Array->new([
3278             {
3279             fruit => "apple",
3280             size => "small",
3281             color => "red",
3282             },
3283             {
3284             fruit => "lemon",
3285             size => "large",
3286             color => "yellow",
3287             },
3288             ]);
3289              
3290             $array->puts(\my $fruit1, '0.fruit', \my $fruit2, '1.fruit');
3291              
3292             my $puts = [$fruit1, $fruit2];
3293              
3294             # ["apple", "lemon"]
3295              
3296             =back
3297              
3298             =over 4
3299              
3300             =item puts example 3
3301              
3302             package main;
3303              
3304             use Venus::Array;
3305              
3306             my $array = Venus::Array->new([
3307             {
3308             fruit => "apple",
3309             size => "small",
3310             color => "red",
3311             },
3312             {
3313             fruit => "lemon",
3314             size => "large",
3315             color => "yellow",
3316             },
3317             ]);
3318              
3319             $array->puts(
3320             \my $fruit1, '0.fruit',
3321             \my $fruit2, '1.fruit',
3322             \my $fruit3, '2.fruit',
3323             );
3324              
3325             my $puts = [$fruit1, $fruit2, $fruit3];
3326              
3327             # ["apple", "lemon", undef]
3328              
3329             =back
3330              
3331             =over 4
3332              
3333             =item puts example 4
3334              
3335             package main;
3336              
3337             use Venus::Array;
3338              
3339             my $array = Venus::Array->new([1..20]);
3340              
3341             $array->puts(
3342             \my $a, '0',
3343             \my $b, '1',
3344             \my $m, ['', '2:-2'],
3345             \my $x, '18',
3346             \my $y, '19',
3347             );
3348              
3349             my $puts = [$a, $b, $m, $x, $y];
3350              
3351             # [1, 2, [3..18], 19, 20]
3352              
3353             =back
3354              
3355             =cut
3356              
3357             =head2 random
3358              
3359             random() (Any)
3360              
3361             The random method returns a random element from the array.
3362              
3363             I>
3364              
3365             =over 4
3366              
3367             =item random example 1
3368              
3369             # given: synopsis;
3370              
3371             my $random = $array->random;
3372              
3373             # 2
3374              
3375             # my $random = $array->random;
3376              
3377             # 1
3378              
3379             =back
3380              
3381             =cut
3382              
3383             =head2 range
3384              
3385             range(Int | Str @args) (ArrayRef)
3386              
3387             The range method accepts a I<"range expression"> and returns the result of
3388             calling the L method with the computed range.
3389              
3390             I>
3391              
3392             =over 4
3393              
3394             =item range example 1
3395              
3396             # given: synopsis
3397              
3398             package main;
3399              
3400             my $range = $array->range;
3401              
3402             # []
3403              
3404             =back
3405              
3406             =over 4
3407              
3408             =item range example 2
3409              
3410             # given: synopsis
3411              
3412             package main;
3413              
3414             my $range = $array->range(0);
3415              
3416             # [1]
3417              
3418             =back
3419              
3420             =over 4
3421              
3422             =item range example 3
3423              
3424             # given: synopsis
3425              
3426             package main;
3427              
3428             my $range = $array->range('0:');
3429              
3430             # [1..9]
3431              
3432             =back
3433              
3434             =over 4
3435              
3436             =item range example 4
3437              
3438             # given: synopsis
3439              
3440             package main;
3441              
3442             my $range = $array->range(':4');
3443              
3444             # [1..5]
3445              
3446             =back
3447              
3448             =over 4
3449              
3450             =item range example 5
3451              
3452             # given: synopsis
3453              
3454             package main;
3455              
3456             my $range = $array->range('8:');
3457              
3458             # [9]
3459              
3460             =back
3461              
3462             =over 4
3463              
3464             =item range example 6
3465              
3466             # given: synopsis
3467              
3468             package main;
3469              
3470             my $range = $array->range('4:');
3471              
3472             # [5..9]
3473              
3474             =back
3475              
3476             =over 4
3477              
3478             =item range example 7
3479              
3480             # given: synopsis
3481              
3482             package main;
3483              
3484             my $range = $array->range('0:2');
3485              
3486             # [1..3]
3487              
3488             =back
3489              
3490             =over 4
3491              
3492             =item range example 8
3493              
3494             # given: synopsis
3495              
3496             package main;
3497              
3498             my $range = $array->range('2:4');
3499              
3500             # [3..5]
3501              
3502             =back
3503              
3504             =over 4
3505              
3506             =item range example 9
3507              
3508             # given: synopsis
3509              
3510             package main;
3511              
3512             my $range = $array->range(0..3);
3513              
3514             # [1..4]
3515              
3516             =back
3517              
3518             =over 4
3519              
3520             =item range example 10
3521              
3522             # given: synopsis
3523              
3524             package main;
3525              
3526             my $range = $array->range('-1:8');
3527              
3528             # [9,1..9]
3529              
3530             =back
3531              
3532             =over 4
3533              
3534             =item range example 11
3535              
3536             # given: synopsis
3537              
3538             package main;
3539              
3540             my $range = $array->range('0:8');
3541              
3542             # [1..9]
3543              
3544             =back
3545              
3546             =over 4
3547              
3548             =item range example 12
3549              
3550             # given: synopsis
3551              
3552             package main;
3553              
3554             my $range = $array->range('0:-2');
3555              
3556             # [1..7]
3557              
3558             =back
3559              
3560             =over 4
3561              
3562             =item range example 13
3563              
3564             # given: synopsis
3565              
3566             package main;
3567              
3568             my $range = $array->range('-2:-2');
3569              
3570             # [8]
3571              
3572             =back
3573              
3574             =over 4
3575              
3576             =item range example 14
3577              
3578             # given: synopsis
3579              
3580             package main;
3581              
3582             my $range = $array->range('0:-20');
3583              
3584             # []
3585              
3586             =back
3587              
3588             =over 4
3589              
3590             =item range example 15
3591              
3592             # given: synopsis
3593              
3594             package main;
3595              
3596             my $range = $array->range('-2:-20');
3597              
3598             # []
3599              
3600             =back
3601              
3602             =over 4
3603              
3604             =item range example 16
3605              
3606             # given: synopsis
3607              
3608             package main;
3609              
3610             my $range = $array->range('-2:-6');
3611              
3612             # []
3613              
3614             =back
3615              
3616             =over 4
3617              
3618             =item range example 17
3619              
3620             # given: synopsis
3621              
3622             package main;
3623              
3624             my $range = $array->range('-2:-8');
3625              
3626             # []
3627              
3628             =back
3629              
3630             =over 4
3631              
3632             =item range example 18
3633              
3634             # given: synopsis
3635              
3636             package main;
3637              
3638             my $range = $array->range('-2:-9');
3639              
3640             # []
3641              
3642             =back
3643              
3644             =over 4
3645              
3646             =item range example 19
3647              
3648             # given: synopsis
3649              
3650             package main;
3651              
3652             my $range = $array->range('-5:-1');
3653              
3654             # [5..9]
3655              
3656             =back
3657              
3658             =cut
3659              
3660             =head2 reverse
3661              
3662             reverse() (ArrayRef)
3663              
3664             The reverse method returns an array reference containing the elements in the
3665             array in reverse order.
3666              
3667             I>
3668              
3669             =over 4
3670              
3671             =item reverse example 1
3672              
3673             # given: synopsis;
3674              
3675             my $reverse = $array->reverse;
3676              
3677             # [9, 8, 7, 6, 5, 4, 3, 2, 1]
3678              
3679             =back
3680              
3681             =cut
3682              
3683             =head2 rotate
3684              
3685             rotate() (ArrayRef)
3686              
3687             The rotate method rotates the elements in the array such that first elements
3688             becomes the last element and the second element becomes the first element each
3689             time this method is called.
3690              
3691             I>
3692              
3693             =over 4
3694              
3695             =item rotate example 1
3696              
3697             # given: synopsis;
3698              
3699             my $rotate = $array->rotate;
3700              
3701             # [2..9, 1]
3702              
3703             =back
3704              
3705             =cut
3706              
3707             =head2 rsort
3708              
3709             rsort() (ArrayRef)
3710              
3711             The rsort method returns an array reference containing the values in the array
3712             sorted alphanumerically in reverse.
3713              
3714             I>
3715              
3716             =over 4
3717              
3718             =item rsort example 1
3719              
3720             # given: synopsis;
3721              
3722             my $rsort = $array->rsort;
3723              
3724             # [9, 8, 7, 6, 5, 4, 3, 2, 1]
3725              
3726             =back
3727              
3728             =cut
3729              
3730             =head2 shift
3731              
3732             shift() (Any)
3733              
3734             The shift method returns the first element of the array shortening it by one.
3735              
3736             I>
3737              
3738             =over 4
3739              
3740             =item shift example 1
3741              
3742             # given: synopsis;
3743              
3744             my $shift = $array->shift;
3745              
3746             # 1
3747              
3748             =back
3749              
3750             =cut
3751              
3752             =head2 shuffle
3753              
3754             shuffle() (ArrayRef)
3755              
3756             The shuffle method returns an array with the items in a randomized order.
3757              
3758             I>
3759              
3760             =over 4
3761              
3762             =item shuffle example 1
3763              
3764             # given: synopsis
3765              
3766             package main;
3767              
3768             my $shuffle = $array->shuffle;
3769              
3770             # [4, 5, 8, 7, 2, 9, 6, 3, 1]
3771              
3772             =back
3773              
3774             =cut
3775              
3776             =head2 slice
3777              
3778             slice(Str @keys) (ArrayRef)
3779              
3780             The slice method returns a hash reference containing the elements in the array
3781             at the index(es) specified in the arguments.
3782              
3783             I>
3784              
3785             =over 4
3786              
3787             =item slice example 1
3788              
3789             # given: synopsis;
3790              
3791             my $slice = $array->slice(2, 4);
3792              
3793             # [3, 5]
3794              
3795             =back
3796              
3797             =cut
3798              
3799             =head2 sort
3800              
3801             sort() (ArrayRef)
3802              
3803             The sort method returns an array reference containing the values in the array
3804             sorted alphanumerically.
3805              
3806             I>
3807              
3808             =over 4
3809              
3810             =item sort example 1
3811              
3812             package main;
3813              
3814             use Venus::Array;
3815              
3816             my $array = Venus::Array->new(['d','c','b','a']);
3817              
3818             my $sort = $array->sort;
3819              
3820             # ["a".."d"]
3821              
3822             =back
3823              
3824             =cut
3825              
3826             =head2 tv
3827              
3828             tv(Any $arg) (Bool)
3829              
3830             The tv method performs a I<"type-and-value-equal-to"> operation using argument
3831             provided.
3832              
3833             I>
3834              
3835             =over 4
3836              
3837             =item tv example 1
3838              
3839             package main;
3840              
3841             use Venus::Array;
3842              
3843             my $lvalue = Venus::Array->new;
3844             my $rvalue = Venus::Array->new;
3845              
3846             my $result = $lvalue->tv($rvalue);
3847              
3848             # 1
3849              
3850             =back
3851              
3852             =over 4
3853              
3854             =item tv example 2
3855              
3856             package main;
3857              
3858             use Venus::Array;
3859             use Venus::Code;
3860              
3861             my $lvalue = Venus::Array->new;
3862             my $rvalue = Venus::Code->new;
3863              
3864             my $result = $lvalue->tv($rvalue);
3865              
3866             # 0
3867              
3868             =back
3869              
3870             =over 4
3871              
3872             =item tv example 3
3873              
3874             package main;
3875              
3876             use Venus::Array;
3877             use Venus::Float;
3878              
3879             my $lvalue = Venus::Array->new;
3880             my $rvalue = Venus::Float->new;
3881              
3882             my $result = $lvalue->tv($rvalue);
3883              
3884             # 0
3885              
3886             =back
3887              
3888             =over 4
3889              
3890             =item tv example 4
3891              
3892             package main;
3893              
3894             use Venus::Array;
3895             use Venus::Hash;
3896              
3897             my $lvalue = Venus::Array->new;
3898             my $rvalue = Venus::Hash->new;
3899              
3900             my $result = $lvalue->tv($rvalue);
3901              
3902             # 0
3903              
3904             =back
3905              
3906             =over 4
3907              
3908             =item tv example 5
3909              
3910             package main;
3911              
3912             use Venus::Array;
3913             use Venus::Number;
3914              
3915             my $lvalue = Venus::Array->new;
3916             my $rvalue = Venus::Number->new;
3917              
3918             my $result = $lvalue->tv($rvalue);
3919              
3920             # 0
3921              
3922             =back
3923              
3924             =over 4
3925              
3926             =item tv example 6
3927              
3928             package main;
3929              
3930             use Venus::Array;
3931             use Venus::Regexp;
3932              
3933             my $lvalue = Venus::Array->new;
3934             my $rvalue = Venus::Regexp->new;
3935              
3936             my $result = $lvalue->tv($rvalue);
3937              
3938             # 0
3939              
3940             =back
3941              
3942             =over 4
3943              
3944             =item tv example 7
3945              
3946             package main;
3947              
3948             use Venus::Array;
3949             use Venus::Scalar;
3950              
3951             my $lvalue = Venus::Array->new;
3952             my $rvalue = Venus::Scalar->new;
3953              
3954             my $result = $lvalue->tv($rvalue);
3955              
3956             # 0
3957              
3958             =back
3959              
3960             =over 4
3961              
3962             =item tv example 8
3963              
3964             package main;
3965              
3966             use Venus::Array;
3967             use Venus::String;
3968              
3969             my $lvalue = Venus::Array->new;
3970             my $rvalue = Venus::String->new;
3971              
3972             my $result = $lvalue->tv($rvalue);
3973              
3974             # 0
3975              
3976             =back
3977              
3978             =over 4
3979              
3980             =item tv example 9
3981              
3982             package main;
3983              
3984             use Venus::Array;
3985             use Venus::Undef;
3986              
3987             my $lvalue = Venus::Array->new;
3988             my $rvalue = Venus::Undef->new;
3989              
3990             my $result = $lvalue->tv($rvalue);
3991              
3992             # 0
3993              
3994             =back
3995              
3996             =cut
3997              
3998             =head2 unique
3999              
4000             unique() (ArrayRef)
4001              
4002             The unique method returns an array reference consisting of the unique elements
4003             in the array.
4004              
4005             I>
4006              
4007             =over 4
4008              
4009             =item unique example 1
4010              
4011             package main;
4012              
4013             use Venus::Array;
4014              
4015             my $array = Venus::Array->new([1,1,1,1,2,3,1]);
4016              
4017             my $unique = $array->unique;
4018              
4019             # [1, 2, 3]
4020              
4021             =back
4022              
4023             =cut
4024              
4025             =head2 unshift
4026              
4027             unshift(Any @data) (ArrayRef)
4028              
4029             The unshift method prepends the array by pushing the agruments onto it and
4030             returns itself.
4031              
4032             I>
4033              
4034             =over 4
4035              
4036             =item unshift example 1
4037              
4038             # given: synopsis;
4039              
4040             my $unshift = $array->unshift(-2,-1,0);
4041              
4042             # [-2..9]
4043              
4044             =back
4045              
4046             =cut
4047              
4048             =head1 AUTHORS
4049              
4050             Awncorp, C
4051              
4052             =cut
4053              
4054             =head1 LICENSE
4055              
4056             Copyright (C) 2000, Al Newkirk.
4057              
4058             This program is free software, you can redistribute it and/or modify it under
4059             the terms of the Apache license version 2.0.
4060              
4061             =cut