/ 
Bubblegum-0.44
River stage zero No dependents
/ Bubblegum::Object::Array

NAME

Bubblegum::Object::Array - Common Methods for Operating on Array References

VERSION

version 0.44

SYNOPSIS

use Bubblegum;

my $array = [1..5];
say $array->keyed('a'..'d'); # {a=>1,b=>2,c=>3,d=>4}

DESCRIPTION

Array methods work on array references. Users of these methods should be aware of the methods that modify the array reference itself as opposed to returning a new array reference. Unless stated, it may be safe to assume that the following methods copy, modify and return new array references based on their subjects. It is not necessary to use this module as it is loaded automatically by the Bubblegum class.

METHODS

all

my $array = [2..5];
$array->all('$a > 1'); # 1; true
$array->all('$a > 3'); # 0; false

The all method returns true if all of the elements in the subject meet the criteria set by the operand and rvalue.

any

my $array = [2..5];
$array->any('$a > 5'); # 0; false
$array->any('$a > 3'); # 1; true

The any method returns true if any of the elements in the subject meet the criteria set by the operand and rvalue.

clear

my $array = ['a'..'g'];
$array->clear; # []

The clear method is an alias to the empty method.

count

my $array = [1..5];
$array->count; # 5

The count method returns the number of elements within the subject.

defined

my $array = [1,2,undef,4,5];
$array->defined(2); # 0; false
$array->defined(1); # 1; true

The defined method returns true if the element within the subject at the index specified by the argument meets the criteria for being defined, otherwise it returns false.

delete

my $array = [1..5];
$array->delete(2); # 3

The delete method returns the value of the element within the subject at the index specified by the argument after removing it from the array.

each

my $array = ['a'..'g'];
$array->each(sub{
    my $index = shift; # 0
    my $value = shift; # a
    ...
});

The each method iterates over each element in the subject, executing the code reference supplied in the argument, passing the routine the index and value at the current position in the loop.

each_key

my $array = ['a'..'g'];
$array->each_key(sub{
    my $index = shift; # 0
    ...
});

The each_key method iterates over each element in the subject, executing the code reference supplied in the argument, passing the routine the index at the current position in the loop.

each_n_values

my $array = ['a'..'g'];
$array->each_n_values(4, sub{
    my $value_1 = shift; # a
    my $value_2 = shift; # b
    my $value_3 = shift; # c
    my $value_4 = shift; # d
    ...
});

The each_n_values method iterates over each element in the subject, executing the code reference supplied in the argument, passing the routine the next n values until all values have been seen.

each_value

my $array = ['a'..'g'];
$array->each_value(sub{
    my $value = shift; # a
    ...
});

The each_value method iterates over each element in the subject, executing the code reference supplied in the argument, passing the routine the value at the current position in the loop.

empty

my $array = ['a'..'g'];
$array->empty; # []

The empty method drops all elements from the subject. Note, this method modifies the subject.

exists

my $array = [1,2,3,4,5];
$array->exists(5); # 0; false
$array->exists(0); # 1; true

The exists method returns true if the element within the subject at the index specified by the argument exists, otherwise it returns false.

first

my $array = [1..5];
$array->first; # 1

The first method returns the value of the first element in the subject.

get

my $array = [1..5];
$array->get(0); # 1;

The get method returns the value of the element in the subject at the index specified by the argument.

grep

my $array = [1..5];
$array->grep(sub{
    shift >= 3
});

# [3,4,5]

The grep method iterates over each element in the subject, executing the code reference supplied in the argument, passing the routine the value at the current position in the loop and returning a new array reference containing the elements for which the argument evaluated true.

hashify

my $array = [1..5];
$array->hashify; # {1=>1,2=>1,3=>1,4=>1,5=>1}

The hashify method returns a hash reference where the elements of subject become the hash keys and the corresponding values are assigned a value of 1. Note, undefined elements will be dropped.

my $array = [1..5];
$array->head; # 1

The head method returns the value of the first element in the subject.

iterator

my $array = [1..5];
my $iterator = $array->iterator;
while (my $value = $iterator->next) {
    say $value; # 1
}

The iterator method returns a code reference which can be used to iterate over the subject. Each time the iterator is executed it will return the next element in the subject until all elements have been seen, at which point the iterator will return an undefined value.

join

my $array = [1..5];
$array->join; # 12345
$array->join(', '); # 1, 2, 3, 4, 5

The join method returns a string consisting of all the elements in the subject joined by the join-string specified by the argument. Note, if the argument is omitted, an empty string will be used as the join-string.

keyed

my $array = [1..5];
$array->keyed('a'..'d'); # {a=>1,b=>2,c=>3,d=>4}

The keyed method returns a hash reference where the arguments become the keys, and the elements of the subject become the values.

keys

my $array = ['a'..'d'];
$array->keys; # [0,1,2,3]

The keys method returns an array reference consisting of the indicies of the subject.

last

my $array = [1..5];
$array->last; # 5

The last method returns the value of the last element in the subject.

length

my $array = [1..5];
$array->length; # 5

The length method returns the number of elements in the subject.

list

my $array = [1..5];
$array->list; # (1,2,3,4,5)

The list method returns the elements in the subject as a list.

map

my $array = [1..5];
$array->map(sub{
    shift + 1
});

# [2,3,4,5,6]

The map method iterates over each element in the subject, executing the code reference supplied in the argument, passing the routine the value at the current position in the loop and returning a new array reference containing the elements for which the argument returns a value or non-empty list.

max

my $array = [8,9,1,2,3,4,5];
$array->max; # 9

The max method returns the element in the subject with the highest numerical value. All non-numerical element are skipped during the evaluation process.

min

my $array = [8,9,1,2,3,4,5];
$array->min; # 1

The min method returns the element in the subject with the lowest numerical value. All non-numerical element are skipped during the evaluation process.

none

my $array = [2..5];
$array->none('$a <= 1'); # 1; true
$array->none('$a <= 2'); # 0; false

The none method returns true if none of the elements in the subject meet the criteria set by the operand and rvalue.

nsort

my $array = [5,4,3,2,1];
$array->nsort; # [1,2,3,4,5]

The nsort method returns an array reference containing the values in the subject sorted numerically.

one

my $array = [2..5];
$array->one('$a == 5'); # 1; true
$array->one('$a == 6'); # 0; false

The one method returns true if only one of the elements in the subject meet the criteria set by the operand and rvalue.

pairs

my $array = [1..5];
$array->pairs; # [[0,1],[1,2],[2,3],[3,4],[4,5]]

The pairs method is an alias to the pairs_array method.

pairs_array

my $array = [1..5];
$array->pairs_array; # [[0,1],[1,2],[2,3],[3,4],[4,5]]

The pairs_array method returns an array reference consisting of array references where each sub array reference has two elements corresponding to the index and value of each element in the subject.

pairs_hash

my $array = [1..5];
$array->pairs_hash; # {0=>1,1=>2,2=>3,3=>4,4=>5}

The pairs_hash method returns a hash reference where each key and value pairs corresponds to the index and value of each element in the subject.

part

my $array = [1..10];
$array->part(sub { shift > 5 }); # [[6, 7, 8, 9, 10], [1, 2, 3, 4, 5]]

The part method iterates over each element in the subject, executing the code reference supplied in the argument, using the result of the code reference to partition to subject into two distinct array references. This method returns an array reference containing exactly two array references.

pop

my $array = [1..5];
$array->pop; # 5

The pop method returns the last element of the subject shortening it by one. Note, this method modifies the subject.

print

my $array = [1..5];
$array->print; # 12345
$array->print(6789); # 123456789

The print method prints the array values to STDOUT, and returns true if successful.

push

my $array = [1..5];
$array->push(6,7,8); # [1,2,3,4,5,6,7,8]

The push method appends the subject by pushing the agruments onto it and returns itself. Note, this method modifies the subject.

random

my $array = [1..5];
$array->random; # 4

The random method returns a random element from the subject.

reverse

my $array = [1..5];
$array->reverse; # [5,4,3,2,1]

The reverse method returns an array reference containing the elements in the subject in reverse order.

rotate

my $array = [1..5];
$array->rotate; # [2,3,4,5,1]
$array->rotate; # [3,4,5,1,2]
$array->rotate; # [4,5,1,2,3]

The rotate method rotates the elements in the subject such that first elements becomes the last element and the second element becomes the first element each time this method is called. Note, this method modifies the subject.

rnsort

my $array = [5,4,3,2,1];
$array->rnsort; # [5,4,3,2,1]

The rnsort method returns an array reference containing the values in the subject sorted numerically in reverse.

rsort

my $array = ['a'..'d'];
$array->rsort; # ['d','c','b','a']

The rsort method returns an array reference containing the values in the subject sorted alphanumerically in reverse.

say

my $array = [1..5];
$array->say; # 12345\n
$array->say(6789); # 123456789\n

The say method prints the array values with a newline appended to STDOUT, and returns true if successful.

set

my $array = [1..5];
$array->set(4,6); # [1,2,3,4,6]

The set method returns the value of the element in the subject at the index specified by the argument after updating it to the value of the second argument.

shift

my $array = [1..5];
$array->shift; # 1

The shift method returns the first element of the subject shortening it by one. Note, this method modifies the subject.

size

my $array = [1..5];
$array->size; # 5

The size method is an alias to the length method.

slice

my $array = [1..5];
$array->slice(2,4); # [3,5]

The slice method returns an array reference containing the elements in the subject at the index(es) specified in the arguments.

sort

my $array = ['d','c','b','a'];
$array->sort; # ['a','b','c','d']

The sort method returns an array reference containing the values in the subject sorted alphanumerically.

sum

my $array = [1..5];
$array->sum; # 15

The sum method returns the sum of all values for all numerical elements in the subject. All non-numerical element are skipped during the evaluation process.

tail

my $array = [1..5];
$array->tail; # [2,3,4,5]

The tail method returns an array reference containing the second through the last elements in the subject omitting the first.

unique

my $array = [1,1,1,1,2,3,1];
$array->unique; # [1,2,3]

The unique method returns an array reference consisting of the unique elements in the subject.

unshift

my $array = [1..5];
$array->unshift(-2,-1,0); # [-2,-1,0,1,2,3,4,5]

The unshift method prepends the subject by pushing the agruments onto it and returns itself. Note, this method modifies the subject.

values

my $array = [1..5];
$array->values; # [1,2,3,4,5]

The values method returns an array reference consisting of the elements in the subject. This method essentially copies the content of the subject into a new container.

COERCIONS

to_array

my $array  = [1..5];
my $result = $array->to_array; # [1,2,3,4,5]

The to_array method coerces an array to a array value. This method merely returns the subject.

to_a

my $array  = [1..5];
my $result = $array->to_a; # [1,2,3,4,5]

The to_a method coerces an array to an array value. This method merely returns the subject.

to_code

my $array  = [1..5];
my $result = $array->to_code; # sub { $array }

The to_code method coerces an array to a code value. The code reference, when executed, will return the subject.

to_c

my $array  = [1..5];
my $result = $array->to_c; # sub { $array }

The to_c method coerces an array to a code value. The code reference, when executed, will return the subject.

to_hash

my $array  = [1..5];
my $result = $array->to_hash; # {1=>2,3=>4,5=>undef}

The to_hash method coerces an array to a hash value. If the subject has an odd number of elements, an undefined value is appended to balance the set.

to_h

my $array  = [1..5];
my $result = $array->to_h; # {1=>2,3=>4,5=>undef}

The to_h method coerces an array to a hash value. If the subject has an odd number of elements, an undefined value is appended to balance the set.

to_number

my $array  = [1..5];
my $result = $array->to_number; # 5

The to_number method coerces an array to a number value. This method merely returns the numbers of elements in the subject.

to_n

my $array  = [1..5];
my $result = $array->to_n; # 5

The to_n method coerces an array to a number value. This method merely returns the numbers of elements in the subject.

to_string

my $array  = [1..5];
my $result = $array->to_string; # '[1,2,3,4,5]'

The to_string method coerces an array to a string value. This method returns a string representation of the subject.

to_s

my $array  = [1..5];
my $result = $array->to_s; # '[1,2,3,4,5]'

The to_s method coerces an array to a string value. This method returns a string representation of the subject.

to_undef

my $array  = [1..5];
my $result = $array->to_undef; # undef

The to_undef method coerces an array to a undef value. This method merely returns an undef value.

to_u

my $array  = [1..5];
my $result = $array->to_u; # undef

The to_u method coerces an array to an undefined value. This method merely returns an undef value.

SEE ALSO

AUTHOR

Al Newkirk <anewkirk@ana.io>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Al Newkirk.

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