.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "Sub::HandlesVia::HandlerLibrary::Array 3"
.TH Sub::HandlesVia::HandlerLibrary::Array 3 2026-08-30 "perl v5.42.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Sub::HandlesVia::HandlerLibrary::Array \- library of array\-related methods
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 10
\&  package My::Class {
\&    use Moo;
\&    use Sub::HandlesVia;
\&    use Types::Standard \*(AqArrayRef\*(Aq;
\&    has attr => (
\&      is => \*(Aqrwp\*(Aq,
\&      isa => ArrayRef,
\&      handles_via => \*(AqArray\*(Aq,
\&      handles => {
\&        \*(Aqmy_accessor\*(Aq => \*(Aqaccessor\*(Aq,
\&        \*(Aqmy_all\*(Aq => \*(Aqall\*(Aq,
\&        \*(Aqmy_all_true\*(Aq => \*(Aqall_true\*(Aq,
\&        \*(Aqmy_any\*(Aq => \*(Aqany\*(Aq,
\&        \*(Aqmy_apply\*(Aq => \*(Aqapply\*(Aq,
\&        \*(Aqmy_clear\*(Aq => \*(Aqclear\*(Aq,
\&        \*(Aqmy_count\*(Aq => \*(Aqcount\*(Aq,
\&        \*(Aqmy_delete\*(Aq => \*(Aqdelete\*(Aq,
\&        \*(Aqmy_elements\*(Aq => \*(Aqelements\*(Aq,
\&        \*(Aqmy_first\*(Aq => \*(Aqfirst\*(Aq,
\&        \*(Aqmy_first_index\*(Aq => \*(Aqfirst_index\*(Aq,
\&        \*(Aqmy_flatten\*(Aq => \*(Aqflatten\*(Aq,
\&        \*(Aqmy_flatten_deep\*(Aq => \*(Aqflatten_deep\*(Aq,
\&        \*(Aqmy_for_each\*(Aq => \*(Aqfor_each\*(Aq,
\&        \*(Aqmy_for_each2\*(Aq => \*(Aqfor_each2\*(Aq,
\&        \*(Aqmy_for_each_pair\*(Aq => \*(Aqfor_each_pair\*(Aq,
\&        \*(Aqmy_get\*(Aq => \*(Aqget\*(Aq,
\&        \*(Aqmy_grep\*(Aq => \*(Aqgrep\*(Aq,
\&        \*(Aqmy_head\*(Aq => \*(Aqhead\*(Aq,
\&        \*(Aqmy_indexed\*(Aq => \*(Aqindexed\*(Aq,
\&        \*(Aqmy_insert\*(Aq => \*(Aqinsert\*(Aq,
\&        \*(Aqmy_is_empty\*(Aq => \*(Aqis_empty\*(Aq,
\&        \*(Aqmy_join\*(Aq => \*(Aqjoin\*(Aq,
\&        \*(Aqmy_map\*(Aq => \*(Aqmap\*(Aq,
\&        \*(Aqmy_max\*(Aq => \*(Aqmax\*(Aq,
\&        \*(Aqmy_maxstr\*(Aq => \*(Aqmaxstr\*(Aq,
\&        \*(Aqmy_min\*(Aq => \*(Aqmin\*(Aq,
\&        \*(Aqmy_minstr\*(Aq => \*(Aqminstr\*(Aq,
\&        \*(Aqmy_natatime\*(Aq => \*(Aqnatatime\*(Aq,
\&        \*(Aqmy_not_all_true\*(Aq => \*(Aqnot_all_true\*(Aq,
\&        \*(Aqmy_pairfirst\*(Aq => \*(Aqpairfirst\*(Aq,
\&        \*(Aqmy_pairgrep\*(Aq => \*(Aqpairgrep\*(Aq,
\&        \*(Aqmy_pairkeys\*(Aq => \*(Aqpairkeys\*(Aq,
\&        \*(Aqmy_pairmap\*(Aq => \*(Aqpairmap\*(Aq,
\&        \*(Aqmy_pairs\*(Aq => \*(Aqpairs\*(Aq,
\&        \*(Aqmy_pairvalues\*(Aq => \*(Aqpairvalues\*(Aq,
\&        \*(Aqmy_peek\*(Aq => \*(Aqpeek\*(Aq,
\&        \*(Aqmy_peekend\*(Aq => \*(Aqpeekend\*(Aq,
\&        \*(Aqmy_pick_random\*(Aq => \*(Aqpick_random\*(Aq,
\&        \*(Aqmy_pop\*(Aq => \*(Aqpop\*(Aq,
\&        \*(Aqmy_print\*(Aq => \*(Aqprint\*(Aq,
\&        \*(Aqmy_product\*(Aq => \*(Aqproduct\*(Aq,
\&        \*(Aqmy_push\*(Aq => \*(Aqpush\*(Aq,
\&        \*(Aqmy_reduce\*(Aq => \*(Aqreduce\*(Aq,
\&        \*(Aqmy_reductions\*(Aq => \*(Aqreductions\*(Aq,
\&        \*(Aqmy_reset\*(Aq => \*(Aqreset\*(Aq,
\&        \*(Aqmy_reverse\*(Aq => \*(Aqreverse\*(Aq,
\&        \*(Aqmy_sample\*(Aq => \*(Aqsample\*(Aq,
\&        \*(Aqmy_set\*(Aq => \*(Aqset\*(Aq,
\&        \*(Aqmy_shallow_clone\*(Aq => \*(Aqshallow_clone\*(Aq,
\&        \*(Aqmy_shift\*(Aq => \*(Aqshift\*(Aq,
\&        \*(Aqmy_shuffle\*(Aq => \*(Aqshuffle\*(Aq,
\&        \*(Aqmy_shuffle_in_place\*(Aq => \*(Aqshuffle_in_place\*(Aq,
\&        \*(Aqmy_sort\*(Aq => \*(Aqsort\*(Aq,
\&        \*(Aqmy_sort_in_place\*(Aq => \*(Aqsort_in_place\*(Aq,
\&        \*(Aqmy_splice\*(Aq => \*(Aqsplice\*(Aq,
\&        \*(Aqmy_sum\*(Aq => \*(Aqsum\*(Aq,
\&        \*(Aqmy_tail\*(Aq => \*(Aqtail\*(Aq,
\&        \*(Aqmy_uniq\*(Aq => \*(Aquniq\*(Aq,
\&        \*(Aqmy_uniq_in_place\*(Aq => \*(Aquniq_in_place\*(Aq,
\&        \*(Aqmy_uniqnum\*(Aq => \*(Aquniqnum\*(Aq,
\&        \*(Aqmy_uniqnum_in_place\*(Aq => \*(Aquniqnum_in_place\*(Aq,
\&        \*(Aqmy_uniqstr\*(Aq => \*(Aquniqstr\*(Aq,
\&        \*(Aqmy_uniqstr_in_place\*(Aq => \*(Aquniqstr_in_place\*(Aq,
\&        \*(Aqmy_unshift\*(Aq => \*(Aqunshift\*(Aq,
\&      },
\&    );
\&  }
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This is a library of methods for Sub::HandlesVia.
.SH "DELEGATABLE METHODS"
.IX Header "DELEGATABLE METHODS"
.ie n .SS """accessor( $index, $value? )"""
.el .SS "\f(CWaccessor( $index, $value? )\fP"
.IX Subsection "accessor( $index, $value? )"
Arguments: \fBInt\fR, \fBOptional[Any]\fR.
.PP
Acts like \f(CW\*(C`get\*(C'\fR if given just an index, or \f(CW\*(C`set\*(C'\fR if given an index and value.
.PP
.Vb 4
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ] );
\&  $object\->my_accessor( 1, \*(Aqquux\*(Aq );
\&  say Dumper( $object\->attr ); ## ==> [ \*(Aqfoo\*(Aq, \*(Aqquux\*(Aq, \*(Aqbaz\*(Aq ]
\&  say $object\->my_accessor( 2 ); ## ==> \*(Aqbaz\*(Aq
.Ve
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS all()
.el .SS \f(CWall()\fP
.IX Subsection "all()"
All elements in the array, in list context.
.PP
.Vb 3
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq ] );
\&  my @list = $object\->my_all;
\&  say Dumper( \e@list ); ## ==> [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq ]
.Ve
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS "all_true( $coderef )"
.el .SS "\f(CWall_true( $coderef )\fP"
.IX Subsection "all_true( $coderef )"
Arguments: \fBCodeRef\fR.
.PP
Like \f(CWList::Util::all()\fR.
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS "any( $coderef )"
.el .SS "\f(CWany( $coderef )\fP"
.IX Subsection "any( $coderef )"
Arguments: \fBCodeRef\fR.
.PP
Like \f(CWList::Util::any()\fR.
.PP
.Vb 3
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ] );
\&  my $truth  = $object\->my_any( sub { /a/ } );
\&  say $truth; ## ==> true
.Ve
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS "apply( $coderef )"
.el .SS "\f(CWapply( $coderef )\fP"
.IX Subsection "apply( $coderef )"
Arguments: \fBCodeRef\fR.
.PP
Executes the coderef (which should modify \f(CW$_\fR) against each element of the array; returns the resulting array in list context.
.ie n .SS clear()
.el .SS \f(CWclear()\fP
.IX Subsection "clear()"
Empties the array.
.PP
.Vb 3
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq ] );
\&  $object\->my_clear;
\&  say Dumper( $object\->attr ); ## ==> []
.Ve
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS count()
.el .SS \f(CWcount()\fP
.IX Subsection "count()"
The number of elements in the referenced array.
.PP
.Vb 2
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq ] );
\&  say $object\->my_count; ## ==> 2
.Ve
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS "delete( $index )"
.el .SS "\f(CWdelete( $index )\fP"
.IX Subsection "delete( $index )"
Arguments: \fBInt\fR.
.PP
Removes the indexed element from the array and returns it. Elements after it will be "moved up".
.ie n .SS elements()
.el .SS \f(CWelements()\fP
.IX Subsection "elements()"
All elements in the array, in list context. (Essentially the same as \f(CW\*(C`all\*(C'\fR.)
.PP
.Vb 3
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq ] );
\&  my @list = $object\->my_elements;
\&  say Dumper( \e@list ); ## ==> [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq ]
.Ve
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS "first( $coderef )"
.el .SS "\f(CWfirst( $coderef )\fP"
.IX Subsection "first( $coderef )"
Arguments: \fBCodeRef\fR.
.PP
Like \f(CWList::Util::first()\fR.
.PP
.Vb 3
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ] );
\&  my $found  = $object\->my_first( sub { /a/ } );
\&  say $found; ## ==> \*(Aqbar\*(Aq
.Ve
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS "first_index( $coderef )"
.el .SS "\f(CWfirst_index( $coderef )\fP"
.IX Subsection "first_index( $coderef )"
Arguments: \fBCodeRef\fR.
.PP
Like \f(CWList::MoreUtils::first_index()\fR.
.PP
.Vb 3
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ] );
\&  my $found  = $object\->my_first_index( sub { /z$/ } );
\&  say $found; ## ==> 2
.Ve
.ie n .SS flatten()
.el .SS \f(CWflatten()\fP
.IX Subsection "flatten()"
All elements in the array, in list context. (Essentially the same as \f(CW\*(C`all\*(C'\fR.)
.PP
.Vb 3
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq ] );
\&  my @list = $object\->my_flatten;
\&  say Dumper( \e@list ); ## ==> [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq ]
.Ve
.ie n .SS "flatten_deep( $depth? )"
.el .SS "\f(CWflatten_deep( $depth? )\fP"
.IX Subsection "flatten_deep( $depth? )"
Arguments: \fBOptional[Int]\fR.
.PP
Flattens the arrayref into a list, including any nested arrayrefs. (Has the potential to loop infinitely.)
.PP
.Vb 2
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, [ \*(Aqbar\*(Aq, [ \*(Aqbaz\*(Aq ] ] ] );
\&  say Dumper( [ $object\->my_flatten_deep ] ); ## ==> [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ]
\&
\&  my $object2 = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, [ \*(Aqbar\*(Aq, [ \*(Aqbaz\*(Aq ] ] ] );
\&  say Dumper( [ $object\->my_flatten_deep(1) ] ); ## ==> [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, [ \*(Aqbaz\*(Aq ] ]
.Ve
.ie n .SS "for_each( $coderef )"
.el .SS "\f(CWfor_each( $coderef )\fP"
.IX Subsection "for_each( $coderef )"
Arguments: \fBCodeRef\fR.
.PP
Chainable method which executes the coderef on each element of the array. The coderef will be passed two values: the element and its index. The element will also be available as \f(CW$_\fR.
.PP
.Vb 2
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ] );
\&  $object\->my_for_each( sub { say "Item $_[1] is $_[0]." } );
.Ve
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS "for_each2( $coderef )"
.el .SS "\f(CWfor_each2( $coderef )\fP"
.IX Subsection "for_each2( $coderef )"
Arguments: \fBCodeRef\fR.
.PP
The same as foreach, but the element will only be available as \f(CW$_\fR: no parameters are passed to the coderef. It may be faster than for_each.
.PP
.Vb 3
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ] );
\&  my $i = 0;
\&  $object\->my_for_each2( sub { say "Item $i is $_."; ++$i } );
.Ve
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS "for_each_pair( $coderef )"
.el .SS "\f(CWfor_each_pair( $coderef )\fP"
.IX Subsection "for_each_pair( $coderef )"
Arguments: \fBCodeRef\fR.
.PP
Chainable method which executes the coderef on each pair of elements in the array. The coderef will be passed the two elements.
.ie n .SS "get( $index )"
.el .SS "\f(CWget( $index )\fP"
.IX Subsection "get( $index )"
Arguments: \fBInt\fR.
.PP
Returns a single element from the array by index.
.PP
.Vb 4
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ] );
\&  say $object\->my_get(  0 ); ## ==> \*(Aqfoo\*(Aq
\&  say $object\->my_get(  1 ); ## ==> \*(Aqbar\*(Aq
\&  say $object\->my_get( \-1 ); ## ==> \*(Aqbaz\*(Aq
.Ve
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS "grep( $coderef )"
.el .SS "\f(CWgrep( $coderef )\fP"
.IX Subsection "grep( $coderef )"
Arguments: \fBCodeRef\fR.
.PP
Like \f(CW\*(C`grep\*(C'\fR from perlfunc.
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS "head( $count )"
.el .SS "\f(CWhead( $count )\fP"
.IX Subsection "head( $count )"
Arguments: \fBInt\fR.
.PP
Returns the first \f(CW$count\fR elements of the array in list context.
.ie n .SS indexed()
.el .SS \f(CWindexed()\fP
.IX Subsection "indexed()"
Like \f(CW\*(C`indexed\*(C'\fR from builtin.
.ie n .SS """insert( $index, $value )"""
.el .SS "\f(CWinsert( $index, $value )\fP"
.IX Subsection "insert( $index, $value )"
Arguments: \fBInt\fR, \fBAny\fR.
.PP
Inserts a value into the array with the given index. Elements after it will be "moved down".
.PP
.Vb 3
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ] );
\&  $object\->my_insert( 1, \*(Aqquux\*(Aq );
\&  say Dumper( $object\->attr ); ## ==> [ \*(Aqfoo\*(Aq, \*(Aqquux\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ]
.Ve
.ie n .SS is_empty()
.el .SS \f(CWis_empty()\fP
.IX Subsection "is_empty()"
Boolean indicating if the referenced array is empty.
.PP
.Vb 4
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq ] );
\&  say $object\->my_is_empty; ## ==> false
\&  $object\->_set_attr( [] );
\&  say $object\->my_is_empty; ## ==> true
.Ve
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS "join( $with? )"
.el .SS "\f(CWjoin( $with? )\fP"
.IX Subsection "join( $with? )"
Arguments: \fBOptional[Str]\fR.
.PP
Returns a string joining all the elements in the array; if \f(CW$with\fR is omitted, defaults to a comma.
.PP
.Vb 3
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ] );
\&  say $object\->my_join;        ## ==> \*(Aqfoo,bar,baz\*(Aq
\&  say $object\->my_join( \*(Aq|\*(Aq ); ## ==> \*(Aqfoo|bar|baz\*(Aq
.Ve
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS "map( $coderef )"
.el .SS "\f(CWmap( $coderef )\fP"
.IX Subsection "map( $coderef )"
Arguments: \fBCodeRef\fR.
.PP
Like \f(CW\*(C`map\*(C'\fR from perlfunc.
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS max()
.el .SS \f(CWmax()\fP
.IX Subsection "max()"
Like \f(CWList::Util::max()\fR.
.ie n .SS maxstr()
.el .SS \f(CWmaxstr()\fP
.IX Subsection "maxstr()"
Like \f(CWList::Util::maxstr()\fR.
.ie n .SS min()
.el .SS \f(CWmin()\fP
.IX Subsection "min()"
Like \f(CWList::Util::min()\fR.
.ie n .SS minstr()
.el .SS \f(CWminstr()\fP
.IX Subsection "minstr()"
Like \f(CWList::Util::minstr()\fR.
.ie n .SS """natatime( $n, $callback? )"""
.el .SS "\f(CWnatatime( $n, $callback? )\fP"
.IX Subsection "natatime( $n, $callback? )"
Arguments: \fBInt\fR, \fBOptional[CodeRef]\fR.
.PP
Given just a number, returns an iterator which reads that many elements from the array at a time. If also given a callback, calls the callback repeatedly with those values.
.PP
.Vb 4
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ] );
\&  my $iter   = $object\->my_natatime( 2 );
\&  say Dumper( [ $iter\->() ] ); ## ==> [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq ]
\&  say Dumper( [ $iter\->() ] ); ## ==> [ \*(Aqbaz\*(Aq ]
.Ve
.ie n .SS "not_all_true( $coderef )"
.el .SS "\f(CWnot_all_true( $coderef )\fP"
.IX Subsection "not_all_true( $coderef )"
Arguments: \fBCodeRef\fR.
.PP
Like \f(CWList::Util::notall()\fR.
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS "pairfirst( $coderef )"
.el .SS "\f(CWpairfirst( $coderef )\fP"
.IX Subsection "pairfirst( $coderef )"
Arguments: \fBCodeRef\fR.
.PP
Like \f(CWList::Util::pairfirst()\fR.
.ie n .SS "pairgrep( $coderef )"
.el .SS "\f(CWpairgrep( $coderef )\fP"
.IX Subsection "pairgrep( $coderef )"
Arguments: \fBCodeRef\fR.
.PP
Like \f(CWList::Util::pairgrep()\fR.
.ie n .SS pairkeys()
.el .SS \f(CWpairkeys()\fP
.IX Subsection "pairkeys()"
Like \f(CWList::Util::pairkeys()\fR.
.ie n .SS "pairmap( $coderef )"
.el .SS "\f(CWpairmap( $coderef )\fP"
.IX Subsection "pairmap( $coderef )"
Arguments: \fBCodeRef\fR.
.PP
Like \f(CWList::Util::pairmap()\fR.
.ie n .SS pairs()
.el .SS \f(CWpairs()\fP
.IX Subsection "pairs()"
Like \f(CWList::Util::pairs()\fR.
.ie n .SS pairvalues()
.el .SS \f(CWpairvalues()\fP
.IX Subsection "pairvalues()"
Like \f(CWList::Util::pairvalues()\fR.
.ie n .SS peek()
.el .SS \f(CWpeek()\fP
.IX Subsection "peek()"
Returns the first item on the array.
.PP
.Vb 2
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ] );
\&  say $object\->my_peek; ## ==> \*(Aqfoo\*(Aq
.Ve
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS peekend()
.el .SS \f(CWpeekend()\fP
.IX Subsection "peekend()"
Returns the last item on the array.
.PP
.Vb 2
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ] );
\&  say $object\->my_peekend; ## ==> \*(Aqbaz\*(Aq
.Ve
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS "pick_random( $count )"
.el .SS "\f(CWpick_random( $count )\fP"
.IX Subsection "pick_random( $count )"
Arguments: \fBOptional[Int]\fR.
.PP
If no \f(CW$count\fR is given, returns one element of the array at random. If \f(CW$count\fR is given, creates a new array with that many random elements from the original array (or fewer if the original array is not long enough) and returns that as an arrayref or list depending on context
.ie n .SS pop()
.el .SS \f(CWpop()\fP
.IX Subsection "pop()"
Removes the last element from the array and returns it.
.PP
.Vb 4
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ] );
\&  say $object\->my_pop; ## ==> \*(Aqbaz\*(Aq
\&  say $object\->my_pop; ## ==> \*(Aqbar\*(Aq
\&  say Dumper( $object\->attr ); ## ==> [ \*(Aqfoo\*(Aq ]
.Ve
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS """print( $fh?, $with? )"""
.el .SS "\f(CWprint( $fh?, $with? )\fP"
.IX Subsection "print( $fh?, $with? )"
Arguments: \fBOptional[FileHandle]\fR, \fBOptional[Str]\fR.
.PP
Prints a string joining all the elements in the array; if \f(CW$fh\fR is omitted, defaults to STDOUT; if \f(CW$with\fR is omitted, defaults to a comma.
.ie n .SS product()
.el .SS \f(CWproduct()\fP
.IX Subsection "product()"
Like \f(CWList::Util::product()\fR.
.ie n .SS "push( @values )"
.el .SS "\f(CWpush( @values )\fP"
.IX Subsection "push( @values )"
Adds elements to the end of the array.
.PP
.Vb 3
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq ] );
\&  $object\->my_push( \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq );
\&  say Dumper( $object\->attr ); ## ==> [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ]
.Ve
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS "reduce( $coderef )"
.el .SS "\f(CWreduce( $coderef )\fP"
.IX Subsection "reduce( $coderef )"
Arguments: \fBCodeRef\fR.
.PP
Like \f(CWList::Util::reduce()\fR, except \f(CW$a\fR and \f(CW$b\fR are passed as parameters.
.ie n .SS "reductions( $coderef )"
.el .SS "\f(CWreductions( $coderef )\fP"
.IX Subsection "reductions( $coderef )"
Arguments: \fBCodeRef\fR.
.PP
Like \f(CWList::Util::reductions()\fR, except \f(CW$a\fR and \f(CW$b\fR are passed as parameters.
.ie n .SS reset()
.el .SS \f(CWreset()\fP
.IX Subsection "reset()"
Resets the attribute to its default value, or an empty arrayref if it has no default.
.PP
.Vb 3
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ] );
\&  $object\->my_reset;
\&  say Dumper( $object\->attr ); ## ==> []
.Ve
.ie n .SS reverse()
.el .SS \f(CWreverse()\fP
.IX Subsection "reverse()"
Returns the reversed array in list context.
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS "sample( $count )"
.el .SS "\f(CWsample( $count )\fP"
.IX Subsection "sample( $count )"
Arguments: \fBInt\fR.
.PP
Like \f(CWList::Util::sample()\fR.
.ie n .SS """set( $index, $value )"""
.el .SS "\f(CWset( $index, $value )\fP"
.IX Subsection "set( $index, $value )"
Arguments: \fBInt\fR, \fBAny\fR.
.PP
Sets the element with the given index to the supplied value.
.PP
.Vb 3
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ] );
\&  $object\->my_set( 1, \*(Aqquux\*(Aq );
\&  say Dumper( $object\->attr ); ## ==> [ \*(Aqfoo\*(Aq, \*(Aqquux\*(Aq, \*(Aqbaz\*(Aq ]
.Ve
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS shallow_clone()
.el .SS \f(CWshallow_clone()\fP
.IX Subsection "shallow_clone()"
Creates a new arrayref with the same elements as the original.
.ie n .SS shift()
.el .SS \f(CWshift()\fP
.IX Subsection "shift()"
Removes an element from the start of the array and returns it.
.PP
.Vb 4
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ] );
\&  say $object\->my_shift; ## ==> \*(Aqfoo\*(Aq
\&  say $object\->my_shift; ## ==> \*(Aqbar\*(Aq
\&  say Dumper( $object\->attr ); ## ==> [ \*(Aqbaz\*(Aq ]
.Ve
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS shuffle()
.el .SS \f(CWshuffle()\fP
.IX Subsection "shuffle()"
Returns the array in a random order; can be called in list context or scalar context and will return an arrayref in the latter case.
.ie n .SS shuffle_in_place()
.el .SS \f(CWshuffle_in_place()\fP
.IX Subsection "shuffle_in_place()"
Rearranges the array in a random order, and changes the attribute to point to the new order.
.ie n .SS "sort( $coderef? )"
.el .SS "\f(CWsort( $coderef? )\fP"
.IX Subsection "sort( $coderef? )"
Arguments: \fBOptional[CodeRef]\fR.
.PP
Like \f(CW\*(C`sort\*(C'\fR from perlfunc, except \f(CW$a\fR and \f(CW$b\fR are passed as parameters.
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.ie n .SS "sort_in_place( $coderef? )"
.el .SS "\f(CWsort_in_place( $coderef? )\fP"
.IX Subsection "sort_in_place( $coderef? )"
Arguments: \fBOptional[CodeRef]\fR.
.PP
Like \f(CW\*(C`sort\*(C'\fR from perlfunc, but changes the attribute to point to the newly sorted array. \f(CW$a\fR and \f(CW$b\fR are passed as parameters.
.ie n .SS """splice( $index, $length, @values )"""
.el .SS "\f(CWsplice( $index, $length, @values )\fP"
.IX Subsection "splice( $index, $length, @values )"
Like \f(CW\*(C`splice\*(C'\fR from perlfunc.
.ie n .SS sum()
.el .SS \f(CWsum()\fP
.IX Subsection "sum()"
Like \f(CWList::Util::sum0()\fR.
.ie n .SS "tail( $count )"
.el .SS "\f(CWtail( $count )\fP"
.IX Subsection "tail( $count )"
Arguments: \fBInt\fR.
.PP
Returns the last \f(CW$count\fR elements of the array in list context.
.ie n .SS uniq()
.el .SS \f(CWuniq()\fP
.IX Subsection "uniq()"
Returns the array filtered to remove duplicates; can be called in list context or scalar context and will return an arrayref in the latter case.
.ie n .SS uniq_in_place()
.el .SS \f(CWuniq_in_place()\fP
.IX Subsection "uniq_in_place()"
Filters the array to remove duplicates, and changes the attribute to point to the filtered array.
.ie n .SS uniqnum()
.el .SS \f(CWuniqnum()\fP
.IX Subsection "uniqnum()"
Returns the array filtered to remove duplicates numerically; can be called in list context or scalar context and will return an arrayref in the latter case.
.ie n .SS uniqnum_in_place()
.el .SS \f(CWuniqnum_in_place()\fP
.IX Subsection "uniqnum_in_place()"
Filters the array to remove duplicates numerically, and changes the attribute to point to the filtered array.
.ie n .SS uniqstr()
.el .SS \f(CWuniqstr()\fP
.IX Subsection "uniqstr()"
Returns the array filtered to remove duplicates stringwise; can be called in list context or scalar context and will return an arrayref in the latter case.
.ie n .SS uniqstr_in_place()
.el .SS \f(CWuniqstr_in_place()\fP
.IX Subsection "uniqstr_in_place()"
Filters the array to remove duplicates stringwise, and changes the attribute to point to the filtered array.
.ie n .SS "unshift( @values )"
.el .SS "\f(CWunshift( @values )\fP"
.IX Subsection "unshift( @values )"
Adds an element to the start of the array.
.PP
.Vb 3
\&  my $object = My::Class\->new( attr => [ \*(Aqfoo\*(Aq ] );
\&  $object\->my_unshift( \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq );
\&  say Dumper( $object\->attr ); ## ==> [ \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq, \*(Aqfoo\*(Aq ]
.Ve
.PP
A faster XS implementation may be used if Sub::HandlesVia::XS is installed.
.SH "SHORTCUT CONSTANTS"
.IX Header "SHORTCUT CONSTANTS"
This module provides some shortcut constants for indicating a list of
delegations.
.PP
.Vb 4
\&  package My::Class {
\&    use Moo;
\&    use Sub::HandlesVia;
\&    use Sub::HandlesVia::HandlerLibrary::Array qw( HandleQueue );
\&    
\&    has things => (
\&      is          => \*(Aqro\*(Aq,
\&      handles_via => \*(AqArray\*(Aq,
\&      handles     => HandleQueue,
\&      default     => sub { [] },
\&    );
\&  }
.Ve
.PP
These shortcuts can be combined using the \f(CW\*(C` | \*(C'\fR operator.
.PP
.Vb 6
\&    has things => (
\&      is          => \*(Aqro\*(Aq,
\&      handles_via => \*(AqArray\*(Aq,
\&      handles     => HandleQueue | HandleStack,
\&      default     => sub { [] },
\&    );
.Ve
.ie n .SS """HandleQueue"""
.el .SS \f(CWHandleQueue\fP
.IX Subsection "HandleQueue"
Creates delegations named like \f(CW\*(C`things_is_empty\*(C'\fR, \f(CW\*(C`things_size\*(C'\fR,
\&\f(CW\*(C`things_enqueue\*(C'\fR, \f(CW\*(C`things_dequeue\*(C'\fR, and \f(CW\*(C`things_peek\*(C'\fR.
.ie n .SS """HandleStack"""
.el .SS \f(CWHandleStack\fP
.IX Subsection "HandleStack"
Creates delegations named like \f(CW\*(C`things_is_empty\*(C'\fR, \f(CW\*(C`things_size\*(C'\fR,
\&\f(CW\*(C`things_push\*(C'\fR, \f(CW\*(C`things_pop\*(C'\fR, and \f(CW\*(C`things_peek\*(C'\fR.
.SH "EXTENDED EXAMPLES"
.IX Header "EXTENDED EXAMPLES"
.SS "Using for_each"
.IX Subsection "Using for_each"
.Vb 2
\&  use strict;
\&  use warnings;
\&  
\&  package My::Plugin {
\&    use Moo::Role;
\&    sub initialize {}
\&    sub finalize {}
\&  }
\&  
\&  package My::Processor {
\&    use Moo;
\&    use Sub::HandlesVia;
\&    use Types::Standard qw( ArrayRef ConsumerOf );
\&    
\&    has plugins => (
\&      is => \*(Aqro\*(Aq,
\&      isa => ArrayRef[ ConsumerOf[\*(AqMy::Plugin\*(Aq] ],
\&      handles_via => \*(AqArray\*(Aq,
\&      handles => {
\&        add_plugin => \*(Aqpush\*(Aq,
\&        plugin_do => \*(Aqfor_each\*(Aq,
\&      },
\&      default => sub { [] },
\&    );
\&    
\&    sub _do_stuff {
\&      return;
\&    }
\&    
\&    sub run_process {
\&      my ( $self, @args ) = @_;
\&      $self\->plugin_do( sub {
\&        my $plugin = shift;
\&        $plugin\->initialize( $self, @args );
\&      } );
\&      $self\->_do_stuff( @args );
\&      $self\->plugin_do( sub {
\&        my $plugin = shift;
\&        $plugin\->finalize( $self, @args );
\&      } );
\&    }
\&  }
\&  
\&  my $p = My::Processor\->new();
\&  
\&  package My::Plugin::Noisy {
\&    use Moo; with \*(AqMy::Plugin\*(Aq;
\&    sub initialize {
\&      my ( $self, $processor, @args ) = @_;
\&      say "initialize @args"; ## ==> \*(Aqinitialize 1 2 3\*(Aq
\&    }
\&    sub finalize {
\&      my ( $self, $processor, @args ) = @_;
\&      say "finalize @args"; ## ==> \*(Aqfinalize 1 2 3\*(Aq
\&    }
\&  }
\&  
\&  $p\->add_plugin( My::Plugin::Noisy\->new );
\&  
\&  $p\->run_process( 1, 2, 3 );
.Ve
.SS "Job queue using push and shift"
.IX Subsection "Job queue using push and shift"
.Vb 3
\&  use strict;
\&  use warnings;
\&  use Try::Tiny;
\&  
\&  package My::JobQueue {
\&    use Moo;
\&    use Sub::HandlesVia;
\&    use Types::Standard qw( Bool ArrayRef CodeRef HasMethods is_Object );
\&    use Try::Tiny;
\&    
\&    has auto_requeue => (
\&      is => \*(Aqro\*(Aq,
\&      isa => Bool,
\&      default => 0,
\&    );
\&    
\&    has jobs => (
\&      is => \*(Aqro\*(Aq,
\&      isa => ArrayRef[ CodeRef | HasMethods[\*(Aqrun\*(Aq] ],
\&      handles_via => \*(AqArray\*(Aq,
\&      handles => {
\&        add_job => \*(Aqpush\*(Aq,
\&        _get_job => \*(Aqshift\*(Aq,
\&        is_empty => \*(Aqis_empty\*(Aq,
\&      },
\&      default => sub { [] },
\&    );
\&    
\&    sub _handle_failed_job {
\&      my ( $self, $job ) = @_;
\&      $self\->add_job( $job ) if $self\->auto_requeue;
\&    }
\&    
\&    sub run_jobs {
\&      my $self = shift;
\&      while ( not $self\->is_empty ) {
\&        my $job = $self\->_get_job;
\&        try {
\&          is_Object($job) ? $job\->run() : $job\->();
\&        }
\&        catch {
\&          $self\->_handle_failed_job( $job );
\&        };
\&      }
\&    }
\&  }
\&  
\&  my $q = My::JobQueue\->new();
\&  
\&  my $str = \*(Aq\*(Aq;
\&  $q\->add_job( sub { $str .= \*(AqA\*(Aq } );
\&  $q\->add_job( sub { $str .= \*(AqB\*(Aq } );
\&  $q\->add_job( sub { $str .= \*(AqC\*(Aq } );
\&  
\&  $q\->run_jobs;
\&  
\&  say $str; ## ==> \*(AqABC\*(Aq
\&  
\&  # Attempt to push invalid value on the queue
\&  #
\&  try {
\&    $q\->add_job( "jobs cannot be strings" );
\&  }
\&  catch {
\&    say $q\->is_empty;  ## ==> true
\&  };
.Ve
.SH BUGS
.IX Header "BUGS"
Please report any bugs to
<https://github.com/tobyink/p5\-sub\-handlesvia/issues>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Sub::HandlesVia.
.SH AUTHOR
.IX Header "AUTHOR"
Toby Inkster <tobyink@cpan.org>.
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
This software is copyright (c) 2020, 2022 by Toby Inkster.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
.SH "DISCLAIMER OF WARRANTIES"
.IX Header "DISCLAIMER OF WARRANTIES"
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.