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

FreeBSD Manual Pages

  
 
  

home | help
Data::Perl::Role::CollUseroContributed PData::Perl::Role::Collection::Array(3)

NAME
       Data::Perl::Role::Collection::Array - Wrapping class for	Perl's built
       in array	structure.

VERSION
       version 0.002011

SYNOPSIS
	 use Data::Perl	qw/array/;

	 my $array = array(1, 2, 3);

	 $array->push(5);

	 $array->grep(sub { $_ > 2 })->map(sub { $_ ** 2 })->elements; # (3, 5);

DESCRIPTION
       This class provides a wrapper and methods for interacting with an
       array.  All methods that	return a list do so via	a
       Data::Perl::Collection::Array object.

PROVIDED METHODS
       new($value, $value, ....)
	   Constructs a	new Data::Perl::Collection::Array object initialized
	   with	passed in values, and returns it.

       count
	   Returns the number of elements in the array.

	     $stuff = Data::Perl::Collection::Array->new(qw/foo	bar baz	boo/);

	     print $stuff->count; # prints 4

	   This	method does not	accept any arguments.

       is_empty
	   Returns a boolean value that	is true	when the array has no
	   elements.

	     $stuff->is_empty ?	die "No	options!\n" : print "Good boy.\n";

	   This	method does not	accept any arguments.

       elements/all
	   Returns all of the elements of the array as an array	(not an	array
	   reference).

	     my	@options = $stuff->elements;
	     print "@options\n";    # prints "foo bar baz boo"

	   This	method does not	accept any arguments.

       get($index)
	   Returns an element of the array by its index. You can also use
	   negative index numbers, just	as with	Perl's core array handling.

	     my	$option	= $stuff->get(1);
	     print "$option\n";	   # prints "bar"

	   If the specified element does not exist, this will return "undef".

	   This	method accepts just one	argument.

       pop Just	like Perl's builtin "pop".

	   This	method does not	accept any arguments.

       push($value1, $value2, value3 ...)
	   Just	like Perl's builtin "push". Returns the	number of elements in
	   the new array.

	   This	method accepts any number of arguments.

       shift
	   Just	like Perl's builtin "shift".

	   This	method does not	accept any arguments.

       unshift($value1,	$value2, value3	...)
	   Just	like Perl's builtin "unshift". Returns the number of elements
	   in the new array.

	   This	method accepts any number of arguments.

       splice($offset, $length,	@values)
	   Just	like Perl's builtin "splice". In scalar	context, this returns
	   the last element removed, or	"undef"	if no elements were removed.
	   In list context, this returns all the elements removed from the
	   array, wrapped in a Collection::Array object.

	   This	method requires	at least one argument.

       first( sub { ...	} )
	   This	method returns the first matching item in the array, just like
	   List::Util's	"first"	function. The matching is done with a
	   subroutine reference	you pass to this method. The subroutine	will
	   be called against each element in the array until one matches or
	   all elements	have been checked.

	     my	$found = $stuff->find_option( sub {/^b/} );
	     print "$found\n";	  # prints "bar"

	   This	method requires	a single argument.

       first_index( sub	{ ... }	)
	   This	method returns the index of the	first matching item in the
	   array, just like List::MoreUtils's "first_index" function. The
	   matching is done with a subroutine reference	you pass to this
	   method. The subroutine will be called against each element in the
	   array until one matches or all elements have	been checked.

	   This	method requires	a single argument.

       grep( sub { ... } )
	   This	method returns every element matching a	given criteria,	just
	   like	Perl's core "grep" function. This method requires a subroutine
	   which implements the	matching logic.	The returned list is provided
	   as a	Collection::Array object.

	     my	@found = $stuff->grep( sub {/^b/} );
	     print "@found\n";	  # prints "bar	baz boo"

	   This	method requires	a single argument.

       map( sub	{ ... }	)
	   This	method transforms every	element	in the array and returns a new
	   array, just like Perl's core	"map" function.	This method requires a
	   subroutine which implements the transformation. The returned	list
	   is provided as a Collection::Array object.

	     my	@mod_options = $stuff->map( sub	{ $_ . "-tag" }	);
	     print "@mod_options\n";	# prints "foo-tag bar-tag baz-tag boo-tag"

	   This	method requires	a single argument.

       reduce( sub { ... } )
	   This	method turns an	array into a single value, by passing a
	   function the	value so far and the next value	in the array, just
	   like	List::Util's "reduce" function.	The reducing is	done with a
	   subroutine reference	you pass to this method.

	     my	$found = $stuff->reduce( sub { $_[0] . $_[1] } );
	     print "$found\n";	  # prints "foobarbazboo"

	   This	method requires	a single argument.

       sort
       sort( sub { ... } )
	   Returns the elements	of the array in	sorted order.

	   You can provide an optional subroutine reference to sort with (as
	   you can with	Perl's core "sort" function). However, instead of
	   using $a and	$b in this subroutine, you will	need to	use $_[0] and
	   $_[1]. The returned list is provided	as a Collection::Array object.

	     # ascending ASCIIbetical
	     my	@sorted	= $stuff->sort();

	     # Descending alphabetical order
	     my	@sorted_options	= $stuff->sort(	sub { lc $_[1] cmp lc $_[0] } );
	     print "@sorted_options\n";	   # prints "foo boo baz bar"

	   This	method accepts a single	argument.

       sort_in_place
       sort_in_place( sub { ...	} )
	   Sorts the array in place, modifying the value of the	attribute.

	   You can provide an optional subroutine reference to sort with (as
	   you can with	Perl's core "sort" function). However, instead of
	   using $a and	$b, you	will need to use $_[0] and $_[1] instead. The
	   returned list is provided as	a Collection::Array object.

	   This	method accepts a single	argument.

       reverse
	   Returns the elements	of the array in	reversed order.	The returned
	   list	is provided as a Collection::Array object.

	   This	method does not	accept any arguments.

       shuffle
	   Returns the elements	of the array in	random order, like "shuffle"
	   from	List::Util. The	returned list is provided as a
	   Collection::Array object.

	   This	method does not	accept any arguments.

       uniq
	   Returns the array with all duplicate	elements removed, like "uniq"
	   from	List::MoreUtils. The returned list is provided as a
	   Collection::Array object.

	   This	method does not	accept any arguments.

       head($count)
	   Returns the first $count elements of	the array. If $count is
	   greater than	the number of elements in the array, the array
	   (without spurious "undef"s) is returned. Negative $count means "all
	   but the last	$count elements". The returned list is provided	as a
	   Collection::Array object.

       tail($count)
	   Returns the last $count elements of the array. If $count is greater
	   than	the number of elements in the array, the array (without
	   spurious "undef"s) is returned. Negative $count means "all but the
	   first $count	elements". The returned	list is	provided as a
	   Collection::Array object.

       join($str)
	   Joins every element of the array using the separator	given as
	   argument, just like Perl's core "join" function.

	     my	$joined	= $stuff->join(':');
	     print "$joined\n";	   # prints "foo:bar:baz:boo"

	   This	method requires	a single argument.

       print($handle, $str)
	   Prints the output of	join($str) to $handle. $handle defaults	to
	   STDOUT, and join $str defaults to join()'s default of ','.

	     $joined = $stuff->print(*STDERR, ';'); # prints foo;bar;baz to STDERR

       set($index, $value)
	   Given an index and a	value, sets the	specified array	element's
	   value.

	   This	method returns the value at $index after the set.

	   This	method requires	two arguments.

       delete($index)
	   Removes the element at the given index from the array.

	   This	method returns the deleted value, either as an array or	scalar
	   as dependent	on splice context semantics. Note that if no value
	   exists, it will

	   return "undef".

	   This	method requires	one argument.

       insert($index, $value)
	   Inserts a new element into the array	at the given index.

	   This	method returns the new value at	$index,	either as an array or
	   scalar as dependent on splice context semantics.

	   This	method requires	two arguments.

       clear
	   Empties the entire array, like "@array = ()".

	   This	method does not	define a return	value.

	   This	method does not	accept any arguments.

       accessor($index)
       accessor($index,	$value)
	   This	method provides	a get/set accessor for the array, based	on
	   array indexes.  If passed one argument, it returns the value	at the
	   specified index.  If	passed two arguments, it sets the value	of the
	   specified index.

	   When	called as a setter, this method	returns	the new	value at
	   $index.

	   This	method accepts one or two arguments.

       natatime($n)
       natatime($n, $code)
	   This	method returns an iterator which, on each call,	returns	$n
	   more	items from the array, in order,	like "natatime"	from
	   List::MoreUtils. A coderef can optionally be	provided; it will be
	   called on each group	of $n elements in the array.

	   This	method accepts one or two arguments.

       shallow_clone
	   This	method returns a shallow clone of the array reference.	The
	   return value	is a reference to a new	array with the same elements.
	   It is shallow because any elements that were	references in the
	   original will be the	same references	in the clone.

       flatten
	   This	method returns a list of elements in the array.	 This method
	   is an alias to the elements method.

       flatten_deep($level)
	   This	method returns a flattened list	of elements in the array. Will
	   flatten arrays contained within the root array recursively -	depth
	   is controlled by the	optional $level	parameter.

SEE ALSO
       o   Data::Perl

       o   MooX::HandlesVia

AUTHOR
       Matthew Phillips	<mattp@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2020 by Matthew Phillips
       <mattp@cpan.org>.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.32.0			  2020-0Data::Perl::Role::Collection::Array(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | PROVIDED METHODS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

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

home | help