/ 
Module-Generic-v0.12.16
River stage two • 17 direct dependents • 20 total dependents
/ Module::Generic::Array

NAME

Module::Generic::Array - An Array Manipulation Object Class

SYNOPSIS

my $ar = Module::Generic::Array->new( [qw( Joe John Mary )] );
printf( "There are %d people\n", $ar->length );
# Adding one more
$ar->push( "Jack" );

VERSION

v0.1.1

DESCRIPTION

The purpose of this class/package is to provide an object-oriented approach at array manipulation

METHODS

new

Provided with an optional array reference or an array object such as Module::Generic::Array, this will create a new object and return it.

as_hash

Returns an hash reference with the keys being the array elements and the hash values their offset value.

clone

Creates a clone of the current array object and returns it.

delete

Provided with an offset value and an optional length, and this will remove data from the array at the given offset and for the given length.

If no given length is provided, it removes all entries from the offset until the end.

It returns a list of elements removed in list context or an array reference of it in scalar context.

each

Provided with a code reference such as a reference to a subroutine, and this will execute the code passing it the array offset and the current value as the 2 arguements. The current value is also accessible with $_

$a->each(sub
{
    print( "I got $_\n" );
    # could also write:
    # print( "I got $_[1] at offset $_[0]\n" );
});

To exit the loop, return undef(), for example:

$a->each(sub
{
    return if( $_ eq $not_this_one );
    print( "ok, this one\n" );
});

exists

Provided with a value and this returns the number of match, as an Module::Generic::Number object, if it is found in the array, or false otherwise.

first

Returns the first element of the array, if any. If there are none, to ensure chaining will work, it will return a Module::Generic::Null object.

for

Provided with a subroutine reference and this will call the subroutine reference, passing it the offset number and the corresponding array value.

$ar->for(sub
{
    my( $i, $val ) = @_;
    # do something
})

$_ is made available and contains the value of $val

It returns the object itself so this can be chained.

To exit the loop, return undef(), for example:

$a->for(sub
{
    return if( $_ eq $not_this_one );
    print( "ok, this one\n" );
});

foreach

Provided with a subroutine reference and this will call the subroutine reference, passing it the value for each entry in the array.

$ar->foreach(sub
{
    my $val = shift( @_ );
    # do something
})

It returns the object itself so this can be chained.

$_ is made available and contains the value of $val

To exit the loop, return undef(), for example:

$a->foreach(sub
{
    return if( $_ eq $not_this_one );
    print( "ok, this one\n" );
});

get

Provided an integer representing an offset and this returns the corresponding value in the array. Offsets start from 0. A blank value will be treated as 0.

my $a = Module::Generic::Array->new( [qw( abc def ghi )] );
$a->get( 1 ); # def
$a->get( '' ); # abc
$a->get( undef() ); # abc
$a->get( -1 ); # ghi

grep

Provided with some data, and this will do a grep on the array.

If the data provided is a code reference or a reference to a subroutine, the code reference will be called for each array entry, and $_ will also be available for each entry.

If the data is a regular expression, each array entry is tested against it.

It returns a list of matches found in ilst context and a new Module::Generic::Array in scalar context.

join

Provided with a string, or expression just as documented in "join" in perlfunc and this will return a string as an <Module::Generic::Scalar object.

keys

This works as documented in "keys" in perlfunc and returns a list of offset values for each entry in the array.

last

Returns the last element of the array. If there are none, instead it will return a Module::Generic::Null to ensure chaining will still work.

length

Returns the size of the array, starting from 1, as a Module::Generic::Number object.

list

Reeturns the array as a list

my $a = Module::Generic::Array->new( [qw( Joe John Mary )] );
print( "@$a" ); # Joe John Mary
my @people = $a->list; # @people now is ( "Joe", "John", "Mary" )

map

Provided with a reference to a subroutine and this will call the subroutine for each element of the array and return a list in list context or a new Module::Generic::Array otherwise.

For each iteration of the array, $_ is made available.

print( $a->map(sub{ $_->value })->join( "\n" ), "\n" );

pop

Returns the last entry in the array.

push

Provided with some data and this adds it at the end of the array.

push_arrayref

Provided with an array reference, and this add all its entry at the end of the array.

my $ar = Module::Generic::Array->new( [qw( John Joe Mary )]);
$ar->push_arrayref( [qw( Jack Peter )] );
print( $ar->join( "," ), "\n" );
# Now prints: John, Joe, Mary, Jack, Peter

reset

This empty the array, just like "undef"

reverse

Returns a the array in reverse order in list context or a new Module::Generic::Array object of it in scalar context.

scalar

Returns the size of the array. It basically calls "length"

set

Provided with an array or an array-based object and this replace all the data in the current object by the ones provided.

shift

Remove the first entry and returns it.

size

Returns the size of the array starting from 1, and 0 if the array is empty, as a Module::Generic::Number object.

sort

Sort the array and return the new array as a list in list context or a new Module::Generic::Array object in scalar context.

splice

Takes the same arguments as the "splice" in perlfunc function and returns the result.

split

Just like the normal "split" in perlfunct function, it takes a string or expression and split the data provided into a list of elements.

It returns the list in list context, and returns a new Module::Generic::Array object in scalar context.

undef

Just like "reset", this empty the array.

unshift

This add the given values at the beginning of the array.

values

Get a list of all the array values and return a list in list context or a ne Module::Generic::Array object in scalar context.

SEE ALSO

Module::Generic::Scalar, Module::Generic::Number, Module::Generic::Boolean, Module::Generic::Hash, Module::Generic::Dynamic

AUTHOR

Jacques Deguest <jack@deguest.jp>

COPYRIGHT & LICENSE

Copyright (c) 2000-2020 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.