The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Module-Generic-v0.13.0
River stage two • 16 direct dependents • 20 total dependents
2 ++
/ 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_string

Returns the array as string, which is essentially the same as "@array"

It takes an optional boolean value that, if true, will sort the array before.

as_hash

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

It takes an optional hash of options:

start_from

If true, the offset values will start from the number provided and not 0, as it is the case by default.

Example:

    my $a = Module::Generic::Array->new( [qw( Jack John Peter )] );
    my $h = $a->as_hash({ start_from => 1 });
    # $h now is:
    {
        Jack => 1,
        John => 2,
        Peter => 3,
    }

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 a new array object of it in scalar context.

See also "splice"

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

See also "index"

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.

has

This is an alias for "exists"

index

Provided with an index of an element in the array and this returns its corresponding value.

It takes an integer and this ensures the value used is an integer by applying "int" in perlfunc

    my $a = Module::Generic::Array->new( [qw( John Jack Peter )] );
    $a->index( 1 ); # returns Jack

If there is nothing at the given offset, possibly because the array is smaller, then this would return undef.

iterator

This returns a new iterator to cycle through all the array items using iterator's method, such as "next" in Module::Generic::Iterator and "prev" in Module::Generic::Iterator. Each iterator element is an Module::Generic::Iterator::Element object

    my $i = $a->iterator;
    while( $i->has_next )
    {
        my $elem = $i->next;
        my $value = $elem->value;
        # Get the next element relative to our element
        printf( "Next value is: %s at offset %d\n", $elem->next, $elem->next->pos  );
    }

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.

This is different from "size" that returns value from 0 and -1 if the array is empty.

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.

pos

Provided with some value (references are ok too), and this will return the position of it in the array, or undef if nothing was found.

    my $a = Module::Generic::Array->new( [qw( John Jack Peter )] );
    my $offset = $a->pos( 'Jack' ); # returns 1
    $a->pos( 'Bob' ); # Returns undef
    my $hash = { first_name => 'John', last_name => 'Doe' };
    $a->push( $hash );
    $a->pos( $hash ); # Returns 3

Note that it returns the position in the array of the first occurrence found. Maybe I should consider returning a list of all occurrences in list context?

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, an array reference or an array-based object and this replaces all the data in the current object by the ones provided.

Note that if an array object is provided, it will copy the content of that object and not set the array object itself.

    $a->set( qw( John Jack Peter ) ); # Using an array of elements
    $a->set( [qw( John Jack Peter )] ); # Using an array reference of elements
    $a->set( $a2 ); # Using another array object, whatever its class may be

shift

Remove the first entry and returns it.

size

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

This is equivalent to the perl variable $# as documented in perldata. It returns the last index in the array.

This is different from "length" that returns value from 1 and 0 if the array is empty.

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, but its return value is different.

If "splice" is called to add new element, the array object is returned to allow chaining.

If no argument is provided, it just empties the array and return the array object is returned to allow chaining.

When offset and/or length are provided, it returns the list of elements found.

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.