NAME

Data::Object::Array

ABSTRACT

Array Class for Perl 5

SYNOPSIS

  package main;

  use Data::Object::Array;

  my $array = Data::Object::Array->new([1..9]);

DESCRIPTION

This package provides methods for manipulating array data.

INHERITS

This package inherits behaviors from:

Data::Object::Kind

INTEGRATES

This package integrates behaviors from:

Data::Object::Role::Dumpable

Data::Object::Role::Pluggable

Data::Object::Role::Throwable

LIBRARIES

This package uses type constraints from:

Data::Object::Types

METHODS

This package implements the following methods:

all

  all(CodeRef $arg1, Any @args) : Num

The all method returns true if the callback returns true for all of the elements.

all example #1

  my $array = Data::Object::Array->new([2..5]);

  $array->all(sub {
    my ($value, @args) = @_;

    $value > 1;
  });

any

  any(CodeRef $arg1, Any @args) : Num

The any method returns true if the callback returns true for any of the elements.

any example #1

  my $array = Data::Object::Array->new([2..5]);

  $array->any(sub {
    my ($value) = @_;

    $value > 5;
  });

clear

  clear() : ArrayLike

The clear method is an alias to the empty method.

clear example #1

  my $array = Data::Object::Array->new(['a'..'g']);

  $array->clear;

count

  count() : Num

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

count example #1

  my $array = Data::Object::Array->new([1..5]);

  $array->count;

defined

  defined() : Num

The defined method returns true if the element at the array index is defined.

defined example #1

  my $array = Data::Object::Array->new;

  $array->defined;

delete

  delete(Int $arg1) : Any

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

delete example #1

  my $array = Data::Object::Array->new([1..5]);

  $array->delete(2);

each

  each(CodeRef $arg1, Any @args) : ArrayLike

The each method executes a callback for each element in the array passing the index and value as arguments.

each example #1

  my $array = Data::Object::Array->new(['a'..'g']);

  $array->each(sub {
    my ($index, $value) = @_;

    [$index, $value]
  });

each_key

  each_key(CodeRef $arg1, Any @args) : ArrayRef

The each_key method executes a callback for each element in the array passing the index as an argument.

each_key example #1

  my $array = Data::Object::Array->new(['a'..'g']);

  $array->each_key(sub {
    my ($index)  = @_;

    [$index]
  });

each_n_values

  each_n_values(Num $arg1, CodeRef $arg2, Any @args) : ArrayRef

The each_n_values method executes a callback for each element in the array passing the routine the next n values until all values have been handled.

each_n_values example #1

  my $array = Data::Object::Array->new(['a'..'g']);

  $array->each_n_values(4, sub {
    my (@values) = @_;

    # $values[1] # a
    # $values[2] # b
    # $values[3] # c
    # $values[4] # d

    [@values]
  });

each_value

  each_value(CodeRef $arg1, Any @args) : ArrayRef

The each_value method executes a callback for each element in the array passing the routine the value as an argument.

each_value example #1

  my $array = Data::Object::Array->new(['a'..'g']);

  $array->each_value(sub {
    my ($value, @args) = @_;

    [$value, @args]
  });

empty

  empty() : ArrayLike

The empty method drops all elements from the array.

empty example #1

  my $array = Data::Object::Array->new(['a'..'g']);

  $array->empty;

eq

  eq(Any $arg1) : Num

The eq method will throw an exception if called.

eq example #1

  my $array = Data::Object::Array->new;

  $array->eq([]);

exists

  exists(Int $arg1) : Num

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

exists example #1

  my $array = Data::Object::Array->new([1,2,3,4,5]);

  $array->exists(0);

first

  first() : Any

The first method returns the value of the first element.

first example #1

  my $array = Data::Object::Array->new([1..5]);

  $array->first;

ge

  ge(Any $arg1) : Num

The ge method will throw an exception if called.

ge example #1

  my $array = Data::Object::Array->new;

  $array->ge([]);

get

  get(Int $arg1) : Any

The get method returns the value of the element at the index specified.

get example #1

  my $array = Data::Object::Array->new([1..5]);

  $array->get(0);

grep

  grep(CodeRef $arg1, Any @args) : ArrayRef

The grep method executes a callback for each element in the array passing the value as an argument, returning a new array reference containing the elements for which the returned true.

grep example #1

  my $array = Data::Object::Array->new([1..5]);

  $array->grep(sub {
    my ($value) = @_;

    $value >= 3
  });

gt

  gt(Any $arg1) : Num

The gt method will throw an exception if called.

gt example #1

  my $array = Data::Object::Array->new;

  $array->gt([]);

hash

  hash() : HashRef

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

hash example #1

  my $array = Data::Object::Array->new([1..5]);

  $array->hash; # {0=>1,1=>2,2=>3,3=>4,4=>5}

hashify

  hashify(CodeRef $arg1, Any $arg2) : HashRef

The hashify method returns a hash reference where the elements of array become the hash keys and the corresponding values are assigned a value of 1.

hashify example #1

  my $array = Data::Object::Array->new([1..5]);

  $array->hashify;

hashify example #2

  my $array = Data::Object::Array->new([1..5]);

  $array->hashify(sub { my ($value) = @_; $value % 2 });

head

  head() : Any

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

head example #1

  my $array = Data::Object::Array->new([9,8,7,6,5]);

  $array->head; # 9

invert

  invert() : Any

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

invert example #1

  my $array = Data::Object::Array->new([1..5]);

  $array->invert; # [5,4,3,2,1]

iterator

  iterator() : CodeRef

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

iterator example #1

  my $array = Data::Object::Array->new([1..5]);

  my $iterator = $array->iterator;

  # while (my $value = $iterator->next) {
  #   say $value; # 1
  # }

join

  join(Str $arg1) : Str

The join method returns a string consisting of all the elements in the array 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.

join example #1

  my $array = Data::Object::Array->new([1..5]);

  $array->join; # 12345

join example #2

  my $array = Data::Object::Array->new([1..5]);

  $array->join(', '); # 1, 2, 3, 4, 5

keyed

  keyed(Str $arg1) : HashRef

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

keyed example #1

  my $array = Data::Object::Array->new([1..5]);

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

keys

  keys() : ArrayRef

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

keys example #1

  my $array = Data::Object::Array->new(['a'..'d']);

  $array->keys; # [0,1,2,3]

last

  last() : Any

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

last example #1

  my $array = Data::Object::Array->new([1..5]);

  $array->last; # 5

le

  le(Any $arg1) : Num

The le method will throw an exception if called.

le example #1

  my $array = Data::Object::Array->new;

  $array->le([]);

length

  length() : Num

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

length example #1

  my $array = Data::Object::Array->new([1..5]);

  $array->length; # 5

list

  list() : (Any)

The list method returns a shallow copy of the underlying array reference as an array reference.

list example #1

  my $array = Data::Object::Array->new([1..5]);

  my @list = $array->list;

  [@list]

lt

  lt(Any $arg1) : Num

The lt method will throw an exception if called.

lt example #1

  my $array = Data::Object::Array->new;

  $array->lt([]);

map

  map(CodeRef $arg1, Any $arg2) : ArrayRef

The map method iterates over each element in the array, 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.

map example #1

  my $array = Data::Object::Array->new([1..5]);

  $array->map(sub {
    $_[0] + 1
  });

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

max

  max() : Any

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

max example #1

  my $array = Data::Object::Array->new([8,9,1,2,3,4,5]);

  $array->max; # 9

min

  min() : Any

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

min example #1

  my $array = Data::Object::Array->new([8,9,1,2,3,4,5]);

  $array->min; # 1

ne

  ne(Any $arg1) : Num

The ne method will throw an exception if called.

ne example #1

  my $array = Data::Object::Array->new;

  $array->ne([]);

none

  none(CodeRef $arg1, Any $arg2) : Num

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

none example #1

  my $array = Data::Object::Array->new([2..5]);

  $array->none(sub {
    my ($value) = @_;

    $value <= 1; # 1; true
  });

none example #2

  my $array = Data::Object::Array->new([2..5]);

  $array->none(sub {
    my ($value) = @_;

    $value <= 1; # 1; true
  });

nsort

  nsort() : ArrayRef

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

nsort example #1

  my $array = Data::Object::Array->new([5,4,3,2,1]);

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

one

  one(CodeRef $arg1, Any $arg2) : Num

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

one example #1

  my $array = Data::Object::Array->new([2..5]);

  $array->one(sub {
    my ($value) = @_;

    $value == 5; # 1; true
  });

one example #2

  my $array = Data::Object::Array->new([2..5]);

  $array->one(sub {
    my ($value) = @_;

    $value == 6; # 0; false
  });

pairs

  pairs() : ArrayRef

The pairs method is an alias to the pairs_array method.

pairs example #1

  my $array = Data::Object::Array->new([1..5]);

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

pairs_array

  pairs_array() : ArrayRef

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 array.

pairs_array example #1

  my $array = Data::Object::Array->new([1..5]);

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

pairs_hash

  pairs_hash() : HashRef

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 array.

pairs_hash example #1

  my $array = Data::Object::Array->new([1..5]);

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

part

  part(CodeRef $arg1, Any $arg2) : Tuple[ArrayRef, ArrayRef]

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

part example #1

  my $array = Data::Object::Array->new([1..10]);

  $array->part(sub { my ($value) = @_; $value > 5 });

  # [[6, 7, 8, 9, 10], [1, 2, 3, 4, 5]]

pop

  pop() : Any

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

pop example #1

  my $array = Data::Object::Array->new([1..5]);

  $array->pop; # 5

push

  push(Any $arg1) : Any

The push method appends the array by pushing the agruments onto it and returns itself.

push example #1

  my $array = Data::Object::Array->new([1..5]);

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

random

  random() : Any

The random method returns a random element from the array.

random example #1

  my $array = Data::Object::Array->new([1..5]);

  $array->random; # 4

reverse

  reverse() : ArrayRef

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

reverse example #1

  my $array = Data::Object::Array->new([1..5]);

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

rnsort

  rnsort() : ArrayRef

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

rnsort example #1

  my $array = Data::Object::Array->new([5,4,3,2,1]);

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

rotate

  rotate() : ArrayLike

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

rotate example #1

  my $array = Data::Object::Array->new([1..5]);

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

rotate example #2

  my $array = Data::Object::Array->new([2,3,4,5,1]);

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

rsort

  rsort() : ArrayRef

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

rsort example #1

  my $array = Data::Object::Array->new(['a'..'d']);

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

set

  set(Str $arg1, Any $arg2) : Any

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

set example #1

  my $array = Data::Object::Array->new([1..5]);

  $array->set(4,6); # 6

shift

  shift() : Any

The shift method returns the first element of the array shortening it by one.

shift example #1

  my $array = Data::Object::Array->new([1..5]);

  $array->shift; # 1

size

  size() : Num

The size method is an alias to the length method.

size example #1

  my $array = Data::Object::Array->new([1..5]);

  $array->size; # 5

slice

  slice(Any @args) : HashRef

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

slice example #1

  my $array = Data::Object::Array->new([1..5]);

  $array->kvslice(2,4); # {2=>3, 4=>5}

sort

  sort() : ArrayRef

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

sort example #1

  my $array = Data::Object::Array->new(['d','c','b','a']);

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

sum

  sum() : Num

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

sum example #1

  my $array = Data::Object::Array->new([1..5]);

  $array->sum; # 15

tail

  tail() : Any

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

tail example #1

  my $array = Data::Object::Array->new([1..5]);

  $array->tail; # [2,3,4,5]

unique

  unique() : ArrayRef

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

unique example #1

  my $array = Data::Object::Array->new([1,1,1,1,2,3,1]);

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

unshift

  unshift() : Any

The unshift method prepends the array by pushing the agruments onto it and returns itself.

unshift example #1

  my $array = Data::Object::Array->new([1..5]);

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

values

  values() : ArrayRef

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

values example #1

  my $array = Data::Object::Array->new([1..5]);

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

AUTHOR

Al Newkirk, "awncorp@cpan.org"

LICENSE

This is free software; you can redistribute it and/or modify it under the terms of the The Apache License, Version 2.0, as elucidated in the "license file" <https://github.com/iamalnewkirk/data-object/blob/master/LICENSE>.

PROJECT

Wiki <https://github.com/iamalnewkirk/data-object/wiki>

Project <https://github.com/iamalnewkirk/data-object>

Initiatives <https://github.com/iamalnewkirk/data-object/projects>

Milestones <https://github.com/iamalnewkirk/data-object/milestones>

Contributing <https://github.com/iamalnewkirk/data-object/blob/master/CONTRIBUTE.md>

Issues <https://github.com/iamalnewkirk/data-object/issues>