NAME
List::Objects::WithUtils::Role::Array - Array manipulation methods
SYNOPSIS
use List::Objects::WithUtils 'array';
my $array = array(qw/ a b c /);
$array->push(qw/ d e f /);
my @upper = $array->map(sub { uc $_[0] })->all;
## ...etc...DESCRIPTION
A Role::Tiny role defining methods for creating and manipulating ARRAY-type objects.
Basic Array Methods
new
Constructs a new ARRAY-type object.
copy
Creates a shallow clone of the current object.
clear
Clears the array entirely.
count
Returns the number of elements in the array.
scalar
The same as calling "count".
is_empty
Returns boolean true if the array is empty.
all
Returns all elements in the array as a plain list.
get
Returns the array element corresponding to a specified index.
set
$array->set( $index, $value );Takes an array element and a new value to set.
Returns the array object.
pop
Pops the last element off the array and returns it.
push
Pushes elements to the end of the array.
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.
delete
Splices a given index out of the array.
insert
$array->insert( $position, $value );Inserts a value at a given position.
join
my $str = $array->join(' ');Joins the array's elements and returns the joined string.
Defaults to ',' if no delimiter is specified.
sliced
my $slice = $array->sliced(1, 3, 5);Returns a new array object consisting of the elements retrived from the specified indexes.
splice
## 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.
natatime
my $iter = array( 1 .. 7 )->natatime(3);
$iter->(); ## [ 1, 2, 3 ]
$iter->(); ## [ 4, 5, 6 ]
$iter->(); ## [ 7 ]Returns an iterator that, when called, produces an ARRAY containing the next 'n' items.
reverse
Returns a new array object consisting of the reversed list of elements.
shuffle
my $shuffled = $array->shuffle;Shuffles the original list and returns a new array object.
uniq
my $unique = $array->uniq;Returns a new array object containing only unique elements from the original array.
Methods that take subs with params
map
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 upon.
grep
my $matched = $array->grep(sub { $_[0] =~ /foo/ });Returns a new array object consisting of the list of elements for which the given subroutine evaluated to true. $_[0] is the element being operated upon.
sort
my $sorted = $array->sort(sub { $_[0] cmp $_[1] });Returns a new array object consisting of the list sorted by the given subroutine. $_[0] and $_[1] are equivalent to $a and $b in a normal sort() call.
The existing array is not modified.)
reduce
my $sum = array(1,2,3)->reduce(sub { $_[0] + $_[1] });Reduces the array by calling the given subroutine for each element of the list. See "reduce" in List::Util.
Methods that take subs with topicalizer
first
my $arr = array( qw/ ab bc bd de / );
my $first = $arr->first(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).
firstidx
Like "first", but return the index of the first successful match.
has_any
if ( $array->has_any(sub { $_ eq 'foo' }) ) {
...
}If passed no arguments, returns the same thing as "count".
If passed a sub, returns boolean true if the sub is true for any element of the array; see "any" in List::MoreUtils.
$_ is set to the element being operated upon.
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".
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.
nsort_by
Like "sort_by", but using numerical comparison.
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.
SEE ALSO
List::Objects::WithUtils::Array
List::Objects::WithUtils::Role::WithJunctions
AUTHOR
Jon Portnoy <avenj@cobaltirc.org>
Portions of this code are derived from Data::Perl by Matthew Phillips (CPAN: MATTP), haarg et al
Licensed under the same terms as Perl.