/ 
Collections-0.01
/ Collections::Ordered

NAME

Collections::Ordered - Easy to use iterator

VERSION

Version 0.01

SYNOPSIS

use Collections::Ordered;
use Collections::Sorted;

# Ordered collection
my $colection = Collections::Ordered->new;

$colection->add($item);
$colection->do(sub { print $_[0] });
$colection->remove($item);

# Access first element
print $sorted_collection->first;

HIERARCHY

Collections::Ordered
 +Collections::Sorted
 +Collections::Set

CLASS METHODS

new()

Returns a new instace of a Collection

my $collection = Collections::Ordered->new;

from_array(\@array)

Returns a new instace of a Collection filled with \@array

my $collection = Collections::Ordered->new(34,23,12,443);

INSTANCE METHODS

add($element)

Add $element as part of receiver's elements

$colection->add(1);

add_all($elements)

Add all $collection's element as part of receiver's elements

$colection->add_all($another_collection);
... or ...
$collection->add_all(1,2,3);
... or ...
$colection->add_all([1,2,3]);

at($index)

Returns element at the $index location, if location doesn't exists it throws Collection::Error::InvalidSize error, first element index is 1

my $third_element = $collection->at(3);

collect($sub)

Returns a new object like the receiver whose elements are the result of evaluating $sub over each element of the receiver

my $names = $employees->collect(sub { $_[0]->name});

# First name in the name list
$names->first

detect($sub)

Returns the first element that evaluated agains $sub is true, if no element is detect throws an error

my $employee = $employees->detect(sub { $_[0]->name eq 'John' });

detect_and_if_none($sub,$another_sub)

Returns the first element of the receiver that evaluated agains $sub is true, if no element is true evaluates $another_sub and returns the results

my $employee = $employees->detect (
    sub { $_[0]->name eq 'John' },
    sub { $employees->add(Employee->new('John') }
);

do($sub)

Iterate over each of the receiver elements evaluating $sub for each element

# print all elements
$collection->do(sub { print $_[0] });

exists($element)

Returns a true value if an element $element exists

if($collection->exists($element) {
  print 'Hey $element exists!';
}

first()

Returns the first element of the receiver's elements if it can't be retrieve throws an Error::InvalidSize exception

my $first_element = $collection->first;

index_of($element)

Returns the index of an $element, if the element is not part of the receiver's elements throws an Error::ElementNotFound exception, first element's index is 1

$collection->add('hello');
$collection->add('bye');
...
$collection->index_of('bye');
# This will return 2 (as it is the second element)

index_of_and_if_none($element,$sub)

Returns the index of $element element, if the element is not part of the receiver's elements evaluates $sub

$collection->index_of_and_if_none('hello', sub { print 'Not found!' });

inject_into($value,$sub)

Inject $value and iterate over each of receiver's elements using $sub, finally answer the result, this method is usefull for accumulator tasks

# elements are 1, 5, 8, 9
my $sum = $collection->inject_into(3, sub { $_[0] + $_[1] });

# $sum is 26

is_empty()

Returns true value if the receiver's has no elements

if($collection->is_empty) {
  $collection->add($some_element);
}

join($separator,$sub)

Iterate over each of receiver's element, evaluating $sub over each element, finally concatenate results using $separator

my $all_names = $employees->join(',', sub { $_[0]->name });

last()

Returns the last element of the receiver's elements if it can't be retrieve throws an Collections::Error::InvalidSize exception

my $last_element = $collection->last;

remove($element)

Removes $element from receiver's elements if the element doesn't exists throws Collections::Error::ElementNotFound exception

$employees->remove($employees->first);

remove_all($elements)

Removes all $elements from receiver's elements if any of the elements to be removed doesn't exists throws Collections::Error::ElementNotFound exception

my $elements = [1 2 3];
$collection->remove_all($elements);
...
$collection->remove_all($another_collection);

reverse()

Returns a collection like this one but with elements in reverse order

second()

Returns the second element of the receiver's elements if it doesn't exists throws an Error::InvalidSize exception

my $second_element = $collection->second;

size()

Returns the number of collection's elements

print $collection->size;

to_array()

Returns an array or array_ref (depending on the context) with all the elements

print $collection->size;

to_ordered()

Returns the same object

my $col = $collection->to_ordered;

to_set()

Returns a new Collections::Set with the elements of this collection

my $set = $collection->to_set;

to_sorted($block)

Returns a new Collections::Sorted with the elements of this collection, first argument is the sort block if none specified it will use the default sorting block

my $sorted = $collection->to_sorted;

AUTHOR

Mariano Wahlmann, <dichoso at gmail.com>

BUGS

Please report any bugs or feature requests to dichoso at gmail.com. I will be notified, and then you'll be notified of progress on your bug as I make changes.

COPYRIGHT & LICENSE

Copyright 2009 Mariano Wahlmann, all rights reserved.

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