Sub::Ha...::Array(3)
Sub::HandlesVia::HandlerLibrary::Array(3) ๐
okay bestie, this is the manual forSub::HandlesVia::HandlerLibrary::Arrayโ a whole library of array-related methods. It's givingSub::HandlesViaenergy. No cap. ๐ฆ
โจ NAME โจ
Sub::HandlesVia::HandlerLibrary::Array โ library of array-related methods
๐ธ SYNOPSIS ๐ธ
package My::Class {
use Moo;
use Sub::HandlesVia;
use Types::Standard 'ArrayRef';
has attr => (
is => 'rwp',
isa => ArrayRef,
handles_via => 'Array',
handles => {
'my_accessor' => 'accessor',
'my_all' => 'all',
'my_all_true' => 'all_true',
'my_any' => 'any',
'my_apply' => 'apply',
'my_clear' => 'clear',
'my_count' => 'count',
'my_delete' => 'delete',
'my_elements' => 'elements',
'my_first' => 'first',
'my_first_index' => 'first_index',
'my_flatten' => 'flatten',
'my_flatten_deep' => 'flatten_deep',
'my_for_each' => 'for_each',
'my_for_each2' => 'for_each2',
'my_for_each_pair' => 'for_each_pair',
'my_get' => 'get',
'my_grep' => 'grep',
'my_head' => 'head',
'my_indexed' => 'indexed',
'my_insert' => 'insert',
'my_is_empty' => 'is_empty',
'my_join' => 'join',
'my_map' => 'map',
'my_max' => 'max',
'my_maxstr' => 'maxstr',
'my_min' => 'min',
'my_minstr' => 'minstr',
'my_natatime' => 'natatime',
'my_not_all_true' => 'not_all_true',
'my_pairfirst' => 'pairfirst',
'my_pairgrep' => 'pairgrep',
'my_pairkeys' => 'pairkeys',
'my_pairmap' => 'pairmap',
'my_pairs' => 'pairs',
'my_pairvalues' => 'pairvalues',
'my_peek' => 'peek',
'my_peekend' => 'peekend',
'my_pick_random' => 'pick_random',
'my_pop' => 'pop',
'my_print' => 'print',
'my_product' => 'product',
'my_push' => 'push',
'my_reduce' => 'reduce',
'my_reductions' => 'reductions',
'my_reset' => 'reset',
'my_reverse' => 'reverse',
'my_sample' => 'sample',
'my_set' => 'set',
'my_shallow_clone' => 'shallow_clone',
'my_shift' => 'shift',
'my_shuffle' => 'shuffle',
'my_shuffle_in_place' => 'shuffle_in_place',
'my_sort' => 'sort',
'my_sort_in_place' => 'sort_in_place',
'my_splice' => 'splice',
'my_sum' => 'sum',
'my_tail' => 'tail',
'my_uniq' => 'uniq',
'my_uniq_in_place' => 'uniq_in_place',
'my_uniqnum' => 'uniqnum',
'my_uniqnum_in_place' => 'uniqnum_in_place',
'my_uniqstr' => 'uniqstr',
'my_uniqstr_in_place' => 'uniqstr_in_place',
'my_unshift' => 'unshift',
},
);
}
๐ DESCRIPTION ๐
This is a library of methods for Sub::HandlesVia. That's the whole vibe. Periodt. โจ
๐ DELEGATABLE METHODS ๐
Okay bestie, here's the whole menu of methods you can delegate. Let's go. ๐ซถ
accessor( $index, $value? ) ๐
Arguments: Int, Optional[Any].
If you give it just an index, it's giving get. If you give it an index and a value, it's giving set. Iconic.
my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
$object->my_accessor( 1, 'quux' );
say Dumper( $object->attr ); ## ==> [ 'foo', 'quux', 'baz' ]
say $object->my_accessor( 2 ); ## ==> 'baz'
โจ Lowkey: a faster XS implementation may be used if Sub::HandlesVia::XS is installed.
all() ๐ธ
All the elements in the array, in list context. The whole squad.
my $object = My::Class->new( attr => [ 'foo', 'bar' ] );
my @list = $object->my_all;
say Dumper( \@list ); ## ==> [ 'foo', 'bar' ]
โจ Lowkey: a faster XS implementation may be used if Sub::HandlesVia::XS is installed.
all_true( $coderef ) ๐
Arguments: CodeRef.
Like List::Util::all(). It's giving "are all of these true?" energy.
โจ Lowkey: a faster XS implementation may be used if Sub::HandlesVia::XS is installed.
any( $coderef ) ๐ฅ
Arguments: CodeRef.
Like List::Util::any(). It's giving "is at least one of these true?" energy.
my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
my $truth = $object->my_any( sub { /a/ } );
say $truth; ## ==> true
โจ Lowkey: a faster XS implementation may be used if Sub::HandlesVia::XS is installed.
apply( $coderef ) ๐ฆ
Arguments: CodeRef.
Executes the coderef (which should modify $_) against each element of the array; returns the resulting array in list context. It's giving "glow up every item" energy.
clear() ๐งน
Empties the array. Poof, gone.
my $object = My::Class->new( attr => [ 'foo' ] );
$object->my_clear;
say Dumper( $object->attr ); ## ==> []
โจ Lowkey: a faster XS implementation may be used if Sub::HandlesVia::XS is installed.
count() ๐ข
The number of elements in the referenced array. Math is mathing.
my $object = My::Class->new( attr => [ 'foo', 'bar' ] );
say $object->my_count; ## ==> 2
โจ Lowkey: a faster XS implementation may be used if Sub::HandlesVia::XS is installed.
delete( $index ) ๐๏ธ
Arguments: Int.
Removes the indexed element from the array and returns it. Elements after it will be "moved up". It's giving "bye bye, and everyone shifts forward" energy.
elements() โจ
All elements in the array, in list context. (Essentially the same as all.)
my $object = My::Class->new( attr => [ 'foo', 'bar' ] );
my @list = $object->my_elements;
say Dumper( \@list ); ## ==> [ 'foo', 'bar' ]
โจ Lowkey: a faster XS implementation may be used if Sub::HandlesVia::XS is installed.
first( $coderef ) ๐ฅ
Arguments: CodeRef.
Like List::Util::first(). It's giving "find the first match" energy.
my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
my $found = $object->my_first( sub { /a/ } );
say $found; ## ==> 'bar'
โจ Lowkey: a faster XS implementation may be used if Sub::HandlesVia::XS is installed.
first_index( $coderef ) ๐
Arguments: CodeRef.
Like List::MoreUtils::first_index(). It's giving "where is the first match?" energy.
my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
my $found = $object->my_first_index( sub { /z$/ } );
say $found; ## ==> 2
flatten() ๐ซง
All elements in the array, in list context. (Essentially the same as all.)
my $object = My::Class->new( attr => [ 'foo', 'bar' ] );
my @list = $object->my_flatten;
say Dumper( \@list ); ## ==> [ 'foo', 'bar' ]
flatten_deep( $depth? ) ๐
Arguments: Optional[Int].
Flattens the arrayref into a list, including any nested arrayrefs. (Has the potential to loop infinitely.) So like, be careful bestie, it can go forever.
my $object = My::Class->new( attr => [ 'foo', [ 'bar', [ 'baz' ] ] ] );
say Dumper( [ $object->my_flatten_deep ] ); ## ==> [ 'foo', 'bar', 'baz' ]
my $object2 = My::Class->new( attr => [ 'foo', [ 'bar', [ 'baz' ] ] ] );
say Dumper( [ $object->my_flatten_deep(1) ] ); ## ==> [ 'foo', 'bar', [ 'baz' ] ]
for_each( $coderef ) ๐
Arguments: CodeRef.
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 $_. It's giving "do the thing for every item" energy.
my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
$object->my_for_each( sub { say "Item $_[1] is $_[0]." } );
โจ Lowkey: a faster XS implementation may be used if Sub::HandlesVia::XS is installed.
for_each2( $coderef ) ๐
Arguments: CodeRef.
The same as foreach, but the element will only be available as $_: no parameters are passed to the coderef. It may be faster than for_each. So if you want speed, this is the vibe.
my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
my $i = 0;
$object->my_for_each2( sub { say "Item $i is $_."; ++$i } );
โจ Lowkey: a faster XS implementation may be used if Sub::HandlesVia::XS is installed.
for_each_pair( $coderef ) ๐ฏ
Arguments: CodeRef.
Chainable method which executes the coderef on each pair of elements in the array. The coderef will be passed the two elements. It's giving "two at a time" energy.
get( $index ) ๐ฏ
Arguments: Int.
Returns a single element from the array by index. Negative indexes? Slay, they work too.
my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
say $object->my_get( 0 ); ## ==> 'foo'
say $object->my_get( 1 ); ## ==> 'bar'
say $object->my_get( -1 ); ## ==> 'baz'
โจ Lowkey: a faster XS implementation may be used if Sub::HandlesVia::XS is installed.
grep( $coderef ) ๐
Arguments: CodeRef.
Like grep from perlfunc. It's giving filtering energy.
โจ Lowkey: a faster XS implementation may be used if Sub::HandlesVia::XS is installed.
head( $count ) ๐
Arguments: Int.
Returns the first $count elements of the array in list context. It's giving "just the front" energy.
indexed() ๐ท๏ธ
Like indexed from builtin. It's giving "pair each element with its index" energy.
insert( $index, $value ) ๐ฅ
Arguments: Int, Any.
Inserts a value into the array with the given index. Elements after it will be "moved down". It's giving "scooch over, new item coming through" energy.
my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
$object->my_insert( 1, 'quux' );
say Dumper( $object->attr ); ## ==> [ 'foo', 'quux', 'bar', 'baz' ]
is_empty() ๐ซ
Boolean indicating if the referenced array is empty. It's giving "is this thing empty or not?" energy.
my $object = My::Class->new( attr => [ 'foo', 'bar' ] );
say $object->my_is_empty; ## ==> false
$object->_set_attr( [] );
say $object->my_is_empty; ## ==> true
โจ Lowkey: a faster XS implementation may be used if Sub::HandlesVia::XS is installed.
join( $with? ) ๐งต
Arguments: Optional[Str].
Returns a string joining all the elements in the array; if $with is omitted, defaults to a comma. It's giving "glue it all together" energy.
my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
say $object->my_join; ## ==> 'foo,bar,baz'
say $object->my_join( '|' ); ## ==> 'foo|bar|baz'
โจ Lowkey: a faster XS implementation may be used if Sub::HandlesVia::XS is installed.
map( $coderef ) ๐บ๏ธ
Arguments: CodeRef.
Like map from perlfunc. It's giving transformation energy.
โจ Lowkey: a faster XS implementation may be used if Sub::HandlesVia::XS is installed.
max() ๐
Like List::Util::max(). It's giving "the biggest one" energy.
maxstr() ๐ค
Like List::Util::maxstr(). It's giving "the biggest string" energy.
min() ๐
Like List::Util::min(). It's giving "the smallest one" energy.
minstr() ๐ก
Like List::Util::minstr(). It's giving "the smallest string" energy.
natatime( $n, $callback? ) โณ
Arguments: Int, Optional[CodeRef].
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. It's giving "batch processing" energy.
my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
my $iter = $object->my_natatime( 2 );
say Dumper( [ $iter->() ] ); ## ==> [ 'foo', 'bar' ]
say Dumper( [ $iter->() ] ); ## ==> [ 'baz' ]
not_all_true( $coderef ) ๐
Arguments: CodeRef.
Like List::Util::notall(). It's giving "not all of these are true" energy.
โจ Lowkey: a faster XS implementation may be used if Sub::HandlesVia::XS is installed.
pairfirst( $coderef ) ๐ซ
Arguments: CodeRef.
Like List::Util::pairfirst(). It's giving "first pair match" energy.
pairgrep( $coderef ) ๐งฒ
Arguments: CodeRef.
Like List::Util::pairgrep(). It's giving "filter pairs" energy.
pairkeys() ๐
Like List::Util::pairkeys(). It's giving "keys from pairs" energy.
pairmap( $coderef ) ๐บ๏ธ
Arguments: CodeRef.
Like List::Util::pairmap(). It's giving "map over pairs" energy.
pairs() ๐ฏ
Like List::Util::pairs(). It's giving "pair them up" energy.
pairvalues() ๐
Like List::Util::pairvalues(). It's giving "values from pairs" energy.
peek() ๐
Returns the first item on the array. It's giving "sneak peek" energy.
my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
say $object->my_peek; ## ==> 'foo'
peekend()
Gives you the last element of the array โ like a lil sneak peek, it does not remove anything. ๐ซฃ
my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
say $object->my_peekend; ## ==> 'baz'
A faster XS implementation may be used if Sub::HandlesVia::XS is installed. โจ
pick_random( $count )
Arguments: Optional[Int].
If you don't hand it a $count, it just returns one random element of the array, like a little chaos goblin. ๐ฒ If you do pass a $count, it makes a whole new array with that many random elements pulled from the original (or fewer, if the original array isn't long enough to keep up), and returns that as an arrayref or a list depending on context. bestie it just knows what you want.
pop()
Takes the last element off the array and gives it to you. gone. removed. no take-backs. ๐
my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
say $object->my_pop; ## ==> 'baz'
say $object->my_pop; ## ==> 'bar'
say Dumper( $object->attr ); ## ==> [ 'foo' ]
A faster XS implementation may be used if Sub::HandlesVia::XS is installed. โจ
print( $fh?, $with? )
Arguments: Optional[FileHandle], Optional[Str].
Prints a string that joins all the elements in the array together. If $fh is left out, it defaults to STDOUT; if $with is left out, it defaults to a comma. simple as. ๐ธ
product()
Like List::Util::product(). multiply girlies rise up. โ๏ธ
push( @values )
Adds elements to the end of the array. queue behaviour, we love to see it.
my $object = My::Class->new( attr => [ 'foo' ] );
$object->my_push( 'bar', 'baz' );
say Dumper( $object->attr ); ## ==> [ 'foo', 'bar', 'baz' ]
A faster XS implementation may be used if Sub::HandlesVia::XS is installed. โจ
reduce( $coderef )
Arguments: CodeRef.
Like List::Util::reduce(), except $a and $b get passed as parameters. ikyk. ๐
reductions( $coderef )
Arguments: CodeRef.
Like List::Util::reductions(), except $a and $b get passed as parameters. ๐
reset()
Resets the attribute back to its default value โ or to an empty arrayref if it doesn't have a default. factory reset but cute. ๐งผ
my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
$object->my_reset;
say Dumper( $object->attr ); ## ==> []
reverse()
Returns the reversed array in list context. it's giving backwards. ๐
A faster XS implementation may be used if Sub::HandlesVia::XS is installed. โจ
sample( $count )
Arguments: Int.
Like List::Util::sample(). ๐
set( $index, $value )
Arguments: Int, Any.
Sets the element at the given index to the value you supplied. very demure, very precise. ๐
my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
$object->my_set( 1, 'quux' );
say Dumper( $object->attr ); ## ==> [ 'foo', 'quux', 'baz' ]
A faster XS implementation may be used if Sub::HandlesVia::XS is installed. โจ
shallow_clone()
Creates a new arrayref with the same elements as the original. copy/paste energy, but make it legal. ๐
shift()
Removes an element from the start of the array and returns it.
my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
say $object->my_shift; ## ==> 'foo'
say $object->my_shift; ## ==> 'bar'
say Dumper( $object->attr ); ## ==> [ 'baz' ]
A faster XS implementation may be used if Sub::HandlesVia::XS is installed. โจ
shuffle()
Returns the array in a random order; call it in list context or scalar context and it'll return an arrayref in the latter case. ๐
shuffle_in_place()
Rearranges the array in a random order, and changes the attribute to point to the new order. it rearranges, it stays. main character behaviour. ๐
sort( $coderef? )
Arguments: Optional[CodeRef].
Like sort from perlfunc, except $a and $b are passed as parameters. โญ
A faster XS implementation may be used if Sub::HandlesVia::XS is installed. โจ
sort_in_place( $coderef? )
Arguments: Optional[CodeRef].
Like sort from perlfunc, but it changes the attribute to point to the newly sorted array. $a and $b are passed as parameters. ๐ซถ
splice( $index, $length, @values )
Like splice from perlfunc. the ultimate glow-up and glow-down tool. โ๏ธ
sum()
Like List::Util::sum0(). ๐งฎ
tail( $count )
Arguments: Int.
Returns the last $count elements of the array in list context. ๐ฆ
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. no dupes, no drama. โจ
uniq_in_place()
Filters the array to remove duplicates, and changes the attribute to point to the filtered array. ๐ง
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. ๐ข
uniqnum_in_place()
Filters the array to remove duplicates numerically, and changes the attribute to point to the filtered array. ๐ข
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. ๐ค
uniqstr_in_place()
Filters the array to remove duplicates stringwise, and changes the attribute to point to the filtered array. ๐ค
unshift( @values )
Adds an element to the start of the array.
my $object = My::Class->new( attr => [ 'foo' ] );
$object->my_unshift( 'bar', 'baz' );
say Dumper( $object->attr ); ## ==> [ 'bar', 'baz', 'foo' ]
A faster XS implementation may be used if Sub::HandlesVia::XS is installed. โจ
๐ SHORTCUT CONSTANTS ๐
This module serves up some shortcut constants for when you wanna indicate a whole list of delegations without typing them all out like a peasant. ๐
package My::Class {
use Moo;
use Sub::HandlesVia;
use Sub::HandlesVia::HandlerLibrary::Array qw( HandleQueue );
has things => (
is => 'ro',
handles_via => 'Array',
handles => HandleQueue,
default => sub { [] },
);
}
And you can combine these shortcuts with the | operator. mix and match, bestie. โจ
has things => (
is => 'ro',
handles_via => 'Array',
handles => HandleQueue | HandleStack,
default => sub { [] },
);
HandleQueue
Creates delegations named like things_is_empty, things_size, things_enqueue, things_dequeue, and things_peek. ๐๏ธ
HandleStack
Creates delegations named like things_is_empty, things_size, things_push, things_pop, and things_peek. ๐ฅ
๐ EXTENDED EXAMPLES ๐
Using for_each
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 => 'ro',
isa => ArrayRef[ ConsumerOf['My::Plugin'] ],
handles_via => 'Array',
handles => {
add_plugin => 'push',
plugin_do => 'for_each',
},
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 'My::Plugin';
sub initialize {
my ( $self, $processor, @args ) = @_;
say "initialize @args"; ## ==> 'initialize 1 2 3'
}
sub finalize {
my ( $self, $processor, @args ) = @_;
say "finalize @args"; ## ==> 'finalize 1 2 3'
}
}
$p->add_plugin( My::Plugin::Noisy->new );
$p->run_process( 1, 2, 3 );
Job queue using push and shift
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 => 'ro',
isa => Bool,
default => 0,
);
has jobs => (
is => 'ro',
isa => ArrayRef[ CodeRef | HasMethods['run'] ],
handles_via => 'Array',
handles => {
add_job => 'push',
_get_job => 'shift',
is_empty => 'is_empty',
},
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 = '';
$q->add_job( sub { $str .= 'A' } );
$q->add_job( sub { $str .= 'B' } );
$q->add_job( sub { $str .= 'C' } );
$q->run_jobs;
say $str; ## ==> 'ABC'
# Attempt to push invalid value on the queue
#
try {
$q->add_job( "jobs cannot be strings" );
}
catch {
say $q->is_empty; ## ==> true
};
๐ BUGS ๐
Please report any bugs to <https://github.com/tobyink/p5-sub-handlesvia/issues>. don't be shy, they wanna hear from you. ๐ซถ
๐ SEE ALSO ๐
Sub::HandlesVia.
๐ AUTHOR ๐
Toby Inkster <tobyink@cpan.org>. legend behaviour. ๐
๐ COPYRIGHT AND LICENCE ๐
This software is copyright (c) 2020, 2022 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
โ ๏ธ 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.
and that's the whole page, bestie!! ๐ธ this was perl v5.42.0 on 2026-02-11, from the Sub::Ha...::Array(3) manpage โ go forth and delegate, you've got this fr fr ๐
โจ๐
๐ฆ where this page comes from
- fedora 44: perl-Sub-HandlesVia 0.053005-1.fc44 ยท GPL-1.0-or-later OR Artistic-1.0-Perl
- ๐ girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms