Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
List::Objects::WithUtiUserRContributedLPst::Objects::WithUtils::Role::Array(3)

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.

perl v5.24.1			  2016List::Objects::WithUtils::Role::Array(3)

NAME | SYNOPSIS | DESCRIPTION | NOTES FOR CONSUMERS | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=List::Objects::WithUtils::Role::Array&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help