Provided by: liblist-objects-withutils-perl_2.028003-3_all 
NAME
List::Objects::WithUtils::Role::Array - Array manipulation methods
SYNOPSIS
## Via List::Objects::WithUtils::Array ->
use List::Objects::WithUtils 'array';
my $array = array(qw/ a b c /);
$array->push(qw/ d e f /);
my @upper = $array->map(sub { uc })->all;
if ( $array->has_any(sub { $_ eq 'a' }) ) {
...
}
my $sum = array(1 .. 10)->reduce(sub { $a + $b });
# See below for full list of methods
## As a Role ->
use Role::Tiny::With;
with 'List::Objects::WithUtils::Role::Array';
DESCRIPTION
A Role::Tiny role defining methods for creating and manipulating ARRAY-type objects.
List::Objects::WithUtils::Array consumes this role (along with
List::Objects::WithUtils::Role::Array::WithJunctions) to provide array() object methods.
In addition to the methods documented below, these objects provide a "TO_JSON" method
exporting a plain ARRAY-type reference for convenience when feeding JSON::Tiny or similar,
as well as a "TO_ZPL" method for compatibility with Text::ZPL.
Basic array methods
new
Constructs a new ARRAY-type object.
copy
Returns a shallow clone of the current object.
count
Returns the number of elements in the array.
defined
Returns true if the element at the specified position is defined.
(Available from v2.13.1)
end
Returns the last index of the array (or -1 if the array is empty).
exists
Returns true if the specified index exists in the array.
Negative indices work as you might expect:
my $arr = array(1, 2, 3);
$arr->set(-2 => 'foo') if $arr->exists(-2);
# [ 1, 'foo', 3 ]
(Available from v2.13.1)
is_empty
Returns boolean true if the array is empty.
is_mutable
Returns boolean true if the hash is mutable; immutable subclasses can override to provide
a negative value.
is_immutable
The opposite of "is_mutable". (Subclasses do not need to override so long as "is_mutable"
returns a correct value.)
inflate
my $hash = $array->inflate;
# Same as:
# my $hash = hash( $array->all )
Inflates an array-type object to a hash-type object.
Returns an object of type "inflated_type"; by default this is a
List::Objects::WithUtils::Hash.
Throws an exception if the array contains an odd number of elements.
inflated_type
The class name that objects are blessed into when calling "inflate"; subclasses can
override to provide their own hash-type objects.
Defaults to List::Objects::WithUtils::Hash.
A consumer returning an "inflated_type" that is not a hash-type object will result in
undefined behavior.
scalar
See "count".
unbless
Returns a plain "/ARRAY" reference (shallow clone).
Methods that manipulate the list
clear
Delete all elements from the array.
Returns the newly-emptied array object.
delete
Splices a given index out of the array.
Returns the removed value.
delete_when
$array->delete_when( sub { $_ eq 'foo' } );
Splices all items out of the array for which the given subroutine evaluates to true.
Returns a new array object containing the deleted values (possibly none).
insert
$array->insert( $position, $value );
$array->insert( $position, @values );
Inserts values at a given position, moving the rest of the array rightwards.
The array will be "backfilled" (with undefs) if $position is past the end of the array.
Returns the array object.
(Available from v2.12.1)
pop
Pops the last element off the array and returns it.
push
Pushes elements to the end of the array.
Returns the array object.
rotate_in_place
array(1 .. 3)->rotate_in_place; # 2, 3, 1
array(1 .. 3)->rotate_in_place(right => 1); # 3, 1, 2
Rotates the array in-place. A direction can be given.
Also see "rotate", "rotator".
set
$array->set( $index, $value );
Takes an array element and a new value to set.
Returns the array object.
shift
Shifts the first element off the beginning of the array and returns it.
unshift
Adds elements to the beginning of the array.
Returns the array object.
splice
# 1- or 2-arg splice (remove elements):
my $spliced = $array->splice(0, 2)
# 3-arg splice (replace):
$array->splice(0, 1, 'abc');
Performs a "splice()" on the current list and returns a new array object consisting of the
items returned from the splice.
The existing array is modified in-place.
validated
use Types::Standard -all;
my $valid = array(qw/foo bar baz/)->validated(Str);
Accepts a Type::Tiny type, against which each element of the current array will be checked
before being added to a new array. Returns the new array.
If the element fails the type check but can be coerced, the coerced value will be added to
the new array.
Dies with a stack trace if the value fails type checks and can't be coerced.
(You probably want an array_of object from List::Objects::WithUtils::Array::Typed
instead.)
See: Types::Standard, List::Objects::Types
Methods that retrieve items
all
Returns all elements in the array as a plain list.
bisect
my ($true, $false) = array( 1 .. 10 )
->bisect(sub { $_ >= 5 })
->all;
my @bigger = $true->all; # ( 5 .. 10 )
my @smaller = $false->all; # ( 1 .. 4 )
Like "part", but creates an array-type object containing two partitions; the first
contains all items for which the subroutine evaluates to true, the second contains items
for which the subroutine evaluates to false.
nsect
my ($first, $second) = array( 1 .. 10 )->nsect(2)->all;
# array( 1 .. 5 ), array( 6 .. 10 )
Like "part" and "bisect", but takes an (integer) number of sets to create.
If there are no items in the list (or no sections are requested), an empty array-type
object is returned.
If the list divides unevenly, the first set will be the largest.
Inspired by List::NSect.
(Available from v2.11.1)
ssect
my ($first, $second) = array( 1 .. 10 )->ssect(5)->all;
# array( 1 .. 5 ), array( 6 .. 10 );
Like "nsect" and "bisect", but takes an (integer) target number of items per set.
If the list divides unevenly, the last set will be smaller than the specified target.
Inspired by List::NSect.
(Available from v2.11.1)
elements
Same as "all"; included for consistency with similar array-type object classes.
export
Same as "all"; included for consistency with hash-type objects.
flatten
Flatten array objects to plain lists, possibly recursively.
"flatten" without arguments is the same as "all":
my @flat = array( 1, 2, [ 3, 4 ] )->flatten;
# @flat = ( 1, 2, [ 3, 4 ] );
If a depth is specified, sub-arrays are recursively flattened until the specified depth is
reached:
my @flat = array( 1, 2, [ 3, 4 ] )->flatten(1);
# @flat = ( 1, 2, 3, 4 );
my @flat = array( 1, 2, [ 3, 4, [ 5, 6 ] ] )->flatten(1);
# @flat = ( 1, 2, 3, 4, [ 5, 6 ] );
This works with both ARRAY-type references and array objects:
my @flat = array( 1, 2, [ 3, 4, array( 5, 6 ) ] )->flatten(2);
# @flat = ( 1, 2, 3, 4, 5, 6 );
(Specifically, consumers of this role and plain ARRAYs are flattened; other ARRAY-type
objects are left alone.)
See "flatten_all" for flattening to an unlimited depth.
flatten_all
Returns a plain list consisting of all sub-arrays recursively flattened. Also see
"flatten".
get
Returns the array element corresponding to a specified index.
get_or_else
# Expect to find an object at $pos in $array,
# or return an empty one if $pos is undef:
my @keys = $array->get_or_else($pos => hash)->keys->all;
# Or pass a coderef that provides a default return value;
# First arg is the object being operated on:
my $item_or_first = $array->get_or_else($pos => sub { shift->get(0) });
# Second arg is the requested index:
my $item = $array->get_or_else(3 => sub {
my (undef, $pos) = @_;
my $created = make_value_for( $pos );
$array->set($pos => $created);
$created
});
Returns the element corresponding to a specified index; optionally takes a second argument
that is used as a default return value if the given index is undef (the array remains
unmodified).
If the second argument is a coderef, it is invoked on the object (with the requested index
as an argument) and its return value is taken as the default.
head
my ($first, $rest) = $array->head;
In list context, returns the first element of the list, and a new array-type object
containing the remaining list. The original object's list is untouched.
In scalar context, returns just the first element of the array:
my $first = $array->head;
tail
Similar to "head", but returns either the last element and a new array-type object
containing the remaining list (in list context), or just the last element of the list (in
scalar context).
join
my $str = $array->join(' ');
Joins the array's elements and returns the joined string.
Defaults to ',' if no delimiter is specified.
kv
Returns an array-type object containing index/value pairs as (unblessed) ARRAYs; this is
much like "kv" in List::Objects::WithUtils::Role::Hash, except the array index is the
"key."
zip
mesh
my $meshed = array(qw/ a b c /)->mesh(
array( 1 .. 3 )
);
$meshed->all; # 'a', 1, 'b', 2, 'c', 3
Takes array references or objects and returns a new array object consisting of one element
from each array, in turn, until all arrays have been traversed fully.
You can mix and match references and objects freely:
my $meshed = array(qw/ a b c /)->mesh(
array( 1 .. 3 ),
[ qw/ foo bar baz / ],
);
("zip" is an alias for "mesh".)
part
my $parts = array( 1 .. 8 )->part(sub { $i++ % 2 });
# Returns array objects:
$parts->get(0)->all; # 1, 3, 5, 7
$parts->get(1)->all; # 2, 4, 6, 8
Takes a subroutine that indicates into which partition each value should be placed.
Returns an array-type object containing partitions represented as array-type objects, as
seen above.
Skipped partitions are empty array objects:
my $parts = array(qw/ foo bar /)->part(sub { 1 });
$parts->get(0)->is_empty; # true
$parts->get(1)->is_empty; # false
The subroutine is passed the value we are operating on, or you can use the topicalizer $_:
array(qw/foo bar baz 1 2 3/)
->part(sub { m/^[0-9]+$/ ? 0 : 1 })
->get(1)
->all; # 'foo', 'bar', 'baz'
part_to_hash
my $people = array(qw/ann andy bob fred frankie/);
my $parts = $people->part_to_hash(sub { ucfirst substr $_, 0, 1 });
$parts->get('A')->all; # 'ann', 'andy'
Like "part", but partitions values into a hash-type object using the result of the given
subroutine as the hash key; the values are array-type objects.
The returned object is of type "inflated_type"; by default this is a
List::Objects::WithUtils::Hash.
(Available from v2.23.1)
pick
my $picked = array('a' .. 'f')->pick(3);
Returns a new array object containing the specified number of elements chosen randomly and
without repetition.
If the given number is equal to or greater than the number of elements in the list, "pick"
will return a shuffled list (same as calling "shuffle").
(Available from v2.26.1)
random
Returns a random element from the array.
reverse
Returns a new array object consisting of the reversed list of elements.
roll
Much like "pick", but repeated entries in the resultant list are allowed, and the number
of entries to return may be larger than the size of the array.
If the number of elements to return is not specified, the size of the original array is
used.
(Available from v2.26.1)
rotate
my $leftwards = $array->rotate;
my $rightwards = $array->rotate(right => 1);
Returns a new array object containing the rotated list.
Also see "rotate_in_place", "rotator".
shuffle
my $shuffled = $array->shuffle;
Returns a new array object containing the shuffled list.
sliced
my $slice = $array->sliced(1, 3, 5);
Returns a new array object consisting of the elements retrived from the specified indexes.
tuples
my $tuples = array(1 .. 7)->tuples(2);
# Returns:
# array(
# [ 1, 2 ],
# [ 3, 4 ],
# [ 5, 6 ],
# [ 7 ],
# )
Returns a new array object consisting of tuples (unblessed ARRAY references) of the
specified size (defaults to 2).
"tuples" accepts Type::Tiny types as an optional second parameter; if specified, items in
tuples are checked against the type and a coercion is attempted (if available for the
given type) if the initial type-check fails:
use Types::Standard -all;
my $tuples = array(1 .. 7)->tuples(2 => Int);
A stack-trace is thrown if a value in a tuple cannot be made to validate.
As of v2.24.1, it's possible to make the returned tuples blessed array-type objects (of
the type of the original class) by passing a boolean true third parameter:
# bless()'d tuples, no type validation or coercion:
my $tuples = array(1 .. 7)->tuples(2, undef, 'bless');
See: Types::Standard, List::Objects::Types
Methods that find items
grep
my $matched = $array->grep(sub { /foo/ });
Returns a new array object consisting of the list of elements for which the given
subroutine evaluates to true. $_[0] is the element being operated on; you can also use the
topicalizer $_.
indexes
my $matched = $array->indexes(sub { /foo/ });
If passed a reference to a subroutine, "indexes" behaves like "grep", but returns a new
array object consisting of the list of array indexes for which the given subroutine
evaluates to true.
If no subroutine is provided, returns a new array object consisting of the full list of
indexes (like "keys" on an array in perl-5.12+). This feature was added in "v2.022".
first_where
my $arr = array( qw/ ab bc bd de / );
my $first = $arr->first_where(sub { /^b/ }); ## 'bc'
Returns the first element of the list for which the given sub evaluates to true. $_ is set
to each element, in turn, until a match is found (or we run out of possibles).
first_index
Like "first_where", but return the index of the first successful match.
Returns -1 if no match is found.
firstidx
An alias for "first_index".
last_where
Like "first_where", but returns the last successful match.
last_index
Like "first_index", but returns the index of the last successful match.
lastidx
An alias for "last_index".
has_any
if ( $array->has_any(sub { $_ eq 'foo' }) ) {
...
}
If passed no arguments, returns boolean true if the array has any elements.
If passed a sub, returns boolean true if the sub is true for any element of the array.
$_ is set to the element being operated upon.
intersection
my $first = array(qw/ a b c /);
my $second = array(qw/ b c d /);
my $intersection = $first->intersection($second);
Returns a new array object containing the list of values common between all given array-
type objects (including the invocant).
The new array object is not sorted in any predictable order.
(It may be worth noting that an intermediate hash is used; objects that stringify to the
same value will be taken to be the same.)
diff
my $first = array(qw/ a b c d /);
my $second = array(qw/ b c x /);
my @diff = $first->diff($second)->sort->all; # (a, d, x)
The opposite of "intersection"; returns a new array object containing the list of values
that are not common between all given array-type objects (including the invocant).
The same constraints as "intersection" apply.
items_after
my $after = array( 1 .. 10 )->items_after(sub { $_ == 5 });
## $after contains [ 6, 7, 8, 9, 10 ]
Returns a new array object consisting of the elements of the original list that occur
after the first position for which the given sub evaluates to true.
items_after_incl
Like "items_after", but include the item that evaluated to true.
items_before
The opposite of "items_after".
items_before_incl
The opposite of "items_after_incl".
Methods that iterate the list
map
my $lowercased = $array->map(sub { lc });
# Same as:
my $lowercased = $array->map(sub { lc $_[0] });
Evaluates a given subroutine for each element of the array, and returns a new array
object. $_[0] is the element being operated on; you can also use the topicalizer $_.
Also see "mapval".
mapval
my $orig = array(1, 2, 3);
my $incr = $orig->mapval(sub { ++$_ });
$incr->all; # (2, 3, 4)
$orig->all; # Still untouched
An alternative to "map". $_ is a copy, rather than an alias to the current element, and
the result is retrieved from the altered $_ rather than the return value of the block.
This feature is borrowed from Data::Munge by Lukas Mai (CPAN: MAUKE).
natatime
my $iter = array( 1 .. 7 )->natatime(3);
$iter->(); ## ( 1, 2, 3 )
$iter->(); ## ( 4, 5, 6 )
$iter->(); ## ( 7 )
array( 1 .. 7 )->natatime(3, sub { my @vals = @_; ... });
Returns an iterator that, when called, produces a list containing the next 'n' items.
If given a coderef as a second argument, it will be called against each bundled group.
rotator
my $rot = array(qw/cat sheep mouse/);
$rot->(); ## 'cat'
$rot->(); ## 'sheep'
$rot->(); ## 'mouse'
$rot->(); ## 'cat'
Returns an iterator that, when called, produces the next element in the array; when there
are no elements left, the iterator returns to the start of the array.
See also "rotate", "rotate_in_place".
(Available from v2.7.1)
reduce
my $sum = array(1,2,3)->reduce(sub { $a + $b });
Reduces the array by calling the given subroutine for each element of the list. $a is the
accumulated value; $b is the current element. See "reduce" in List::Util.
Prior to "v2.18.1", $_[0] and $_[1] must be used in place of $a and $b, respectively.
Using positional arguments may make for cleaner syntax in some cases:
my $divide = sub {
my ($acc, $next) = @_;
$acc / $next
};
my $q = $array->reduce($divide);
An empty list reduces to "undef".
This is a "left fold" -- foldl is an alias for "reduce" (as of v2.17.1).
See also: "foldr"
foldr
my $result = array(2,3,6)->foldr(sub { $_[1] / $_[0] }); # 1
Reduces the array by calling the given subroutine for each element of the list starting at
the end (the opposite of "reduce").
Unlike "reduce" (foldl), the first argument passed to the subroutine is the current
element; the second argument is the accumulated value.
An empty list reduces to "undef".
(Available from v2.17.1)
visit
$arr->visit(sub { warn "array contains: $_" });
Executes the given subroutine against each element sequentially; in practice this is much
like "map", except the return value is thrown away.
Returns the original array object.
(Available from v2.7.1)
Methods that sort the list
sort
my $sorted = $array->sort(sub { $a cmp $b });
Returns a new array object consisting of the list sorted by the given subroutine.
Prior to version 2.18.1, positional arguments ($_[0] and $_[1]) must be used in place of
$a and $b, respectively.
sort_by
my $array = array(
{ id => 'a' },
{ id => 'c' },
{ id => 'b' },
);
my $sorted = $array->sort_by(sub { $_->{id} });
Returns a new array object consisting of the list of elements sorted via a stringy
comparison using the given sub. See List::UtilsBy.
Uses List::UtilsBy::XS if available.
nsort_by
Like "sort_by", but using numerical comparison.
repeated
my $repeats = $array->repeated;
The opposite of "uniq"; returns a new array object containing only repeated elements.
(The same constraints apply with regards to stringification; see "uniq")
(Available from v2.26.1)
squished
my $squished = array(qw/a a b a b b/)->squished;
# $squished = array( 'a', 'b', 'a', 'b' );
Similar to "uniq", but only consecutively repeated values are removed from the returned
(new) array object.
The same constraints as "uniq" apply with regards to stringification, but multiple
"undef"s in a row will also be squished.
(Available from v2.27.1)
uniq
my $unique = $array->uniq;
Returns a new array object containing only unique elements from the original array.
(It may be worth noting that this takes place via an intermediate hash; objects that
stringify to the same value are not unique, even if they are different objects. "uniq_by"
plus "refaddr" in Scalar::Util may help you there.)
uniq_by
my $array = array(
{ id => 'a' },
{ id => 'a' },
{ id => 'b' },
);
my $unique = $array->uniq_by(sub { $_->{id} });
Returns a new array object consisting of the list of elements for which the given sub
returns unique values.
Uses List::UtilsBy::XS if available; falls back to List::UtilsBy if not.
NOTES FOR CONSUMERS
If creating your own consumer of this role, some extra effort is required to make $a and
$b work in sort statements without warnings; an example with a custom exported constructor
(and junction support) might look something like:
package My::Custom::Array;
use strictures 2;
require Role::Tiny;
Role::Tiny->apply_roles_to_package( __PACKAGE__,
qw/
List::Objects::WithUtils::Role::Array
List::Objects::WithUtils::Role::Array::WithJunctions
My::Custom::Array::Role
/
);
use Exporter ();
our @EXPORT = 'myarray';
sub import {
# touch $a/$b in caller to avoid 'used only once' warnings:
my $pkg = caller;
{ no strict 'refs';
${"${pkg}::a"} = ${"${pkg}::a"};
${"${pkg}::b"} = ${"${pkg}::b"};
}
goto &Exporter::import
}
sub myarray { __PACKAGE__->new(@_) }
SEE ALSO
List::Objects::WithUtils
List::Objects::WithUtils::Array
List::Objects::WithUtils::Array::Immutable
List::Objects::WithUtils::Array::Typed
List::Objects::WithUtils::Role::Array::WithJunctions
Data::Perl
List::Util
List::UtilsBy
AUTHOR
Jon Portnoy <avenj@cobaltirc.org>
Portions of this code were contributed by Toby Inkster (CPAN: TOBYINK).
Portions of this code are derived from Data::Perl by Matthew Phillips (MATTP), Graham Knop
(HAARG) et al.
Portions of this code are inspired by List::MoreUtils-0.33 by Adam Kennedy (ADAMK),
Tassilo von Parseval, and Aaron Crane.
"part_to_hash" was inspired by Yanick Champoux in
<https://github.com/perl5-utils/List-MoreUtils/pull/15>
Licensed under the same terms as Perl.