Basic array methods

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

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

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

  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

  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

  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.