/ 
Object-Relation-v0.1.0
/ Object::Relation::Collection

Name

Object::Relation::Collection - Object::Relation collection class

Synopsis

use Object::Relation::Collection;

my $coll = Object::Relation::Collection->new(
   {
       iter => $iterator,
       key  => $key        # optional
   }
);
while (my $thing = $coll->next) {
    # Do something with $thing.
}

Description

This class provides an interface for accessing a collection of Object::Relation objects. Users generally won't create collection objects directly, but will get them back from accessor methods for collections of objects related to an object.

Note that the collection is essentially an ordered set. Duplicate items are not allowed and order is important.

Also, a collection can be for objects other than Object::Relation objects, but the objects must provide a uuid method.

If the key is not supplied, the collection is untyped. If the key is supplied, the collection is typed. All objects in the collection must either be Object::Relation classes or subclasses for the key $key. =cut

############################################################################## # Constructors. ##############################################################################

Class Interface

Constructors

new

my $coll = Object::Relation::Collection->new({
    iter => $iterator,
    key  => $key,    # optional
});

Constructs and returns a new collection object. Takes a hash reference argument containing the following parameters:

iter

A Object::Relation::Iterator object. Required.

key

An optional key identifying a data type to force a typed collection.

Throws:

Fatal::Invalid

empty

my $collection = Object::Relation::Collection->empty;
my $collection = Object::Relation::Collection->empty( $key );

Syntactic sugar for creating a new, empty collection. Takes an optional data type key to force a typed collection.

from_list

my $coll = Object::Relation::Collection->from_list({
    list => \@list,
    key  => $key,    # optional
});

Constructs a new collection object based on an array reference. If the key is present, all objects in @list must be objects whose classes correspond to said key. Duplicate items in the list will be removed.

For convenience, this method may also be called from a collection instance and, in which case it returns a new collection. The new collection will be of the same type unless an explicit key is used.

# will be the same type as $old_coll
my $coll = $old_coll->from_list({ list => \@list });

# will ignore the type of $old_coll
my $coll = $old_coll->from_list({ list => \@list, key => 'customer' });

Instance Interface

Instance Methods

next

while (my $thing = $coll->next) {
    print "It's a thing!\n";
}

Returns the next item in the collection and sets the collection's current position to that item. Calling next() multiple times will return each item in sequence. If you attempt to fetch an item beyond the end of the current collection size, the collection returns false and the position of the collection will not be changed. Call curr() to get the value at the current index position.

package

my $package = $collection->package;

If the collection is typed (see new()), this method will return the package that objects in the collection are allowed to be.

curr

my $current = $coll->curr;

Returns the value at the current position of the collection.

current

my $current = $coll->current;

Alias for curr.

prev

my $previous = $coll->prev;

Returns the value at the previous position of the collection. Also sets the current collection value to that position. If we're already at the start of the collection, this method returns undef and does not change the position.

iter

iterator

my $iterator = $coll->iter;

This method returns the iterator the collection has.

iterator

my $iterator = $coll->iterator;

Alias for iter().

get

my $item = $coll->get($index);

Returns the item in the collection slot for the numeric $index. Sets the current position of the collection to $index. As a side effect, it loads the collection from the iterator up to $index.

set

$coll->set($index, $value);

Sets the value of the collection at $index to $value. As a side effect, it loads the collection from the iterator up to $index. As a side effect, added(), removed() will no longer return values, is_cleared() will return false, and is_assigned() will return true, because it is assumed that the whole collection has been reordered.

assign

$coll->assign(@values);

Assigns a list of values to the collection in the order in which they're passed. All previously-existing values will be discarded and the index will be reset. As a result, added() and removed() will return now values, is_cleared() will return false, and the collection will be reset, as it has been assigned to.

is_assigned

if ($coll->is_assigned) {
    print "Values have been set or assigned\n";
}

Returns true if values have been set or assigned by one or more calls to set() or assigned() and no subsequent call to clear().

add

$coll->add(@values);

Adds a list of values to the end of the collection. This method does not load the collection from the iterator. Returns the collection object.

added

my @added = $coll->added;
my $added = $coll->added;

Returns a list or array reference of items that have been added to the collection by one or more calls to add(). Returns an empty list or undef if no items have been added or if the collection has been modified by a call to set() or assign() or clear().

remove

$coll->remove(@values);

Removes a list of values to the end of the collection. This method does not load the collection from the iterator. Returns the collection object.

removed

my @removed = $coll->removed;
my $removed = $coll->removed;

Returns a list or array reference of items that have been removed from the collection by one or more calls to remove(). Returns an empty list or undef if no items have been removed or if the collection has been modified by a call to set() or assign() or clear().

index

my $index = $coll->index;

Returns the current numeric value of the index. Returns undef if the collection is not yet pointing at anything.

reset

$coll->reset;

reset resets the collection. The collection will now behave like a new collection has been created with the same iterator.

size

my $size = $coll->size;

Returns the number of items in the collection. As a side effect, it loads the entire collection from the iterator.

clear

$coll->clear;

Empties the collection. All existing values in the collection will be discarded, removed() and added() will return no values, and assigned() will return false.

is_cleared

if ($coll->is_cleared) {
    print "The collection has been cleared\n";
}

Returns true if the collection has been cleared by a call to clear() and there have been no subsequent calls to set() or assigned().

peek

my $item = $coll->peek;

Peek at the next item of the list without advancing the collection.

all

my @all = $coll->all;
my $all = $coll->all;

Returns a list or array reference of all items in the collection. Returns an array reference in scalar context. The entire collection will be loaded from the iterator.

do

$coll->do( sub { print "$_[0]\n"; return $_[0]; } );
$coll->do( sub { print "$_\n"; return $_; } );

Pass a code reference to this method to execute it for each item in the collection. Each item will be set to $_ before executing the code reference, and will also be passed as the sole argument to the code reference. If next() has been called prior to the call to do(), then only the remaining items in the iterator will passed to the code reference. Call reset() first to ensure that all items will be processed. Iteration terminates when the code reference returns a false value, so be sure to have it return a true value if you want it to iterate over every item.

Copyright and License

Copyright (c) 2004-2006 Kineticode, Inc. <info@obj_relode.com>

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