NAME

Pangloss::Collection - base class for collections in Pangloss.

SYNOPSIS

  # abstract - cannot be used directly
  use base qw( Pangloss::Collection );

  # read on...

DESCRIPTION

This class is a simple OO wrapper around a perl Hash. Perhaps a better name for it would be Collection::Map. It should help make storing collections of objects in Pixie easier.

Items stored in these collections should inherit from Pangloss::Collection::Item.

METHODS

@keys = $obj->keys

as in keys(). uses wantarray for Petal compliancy.

@values = $obj->values

as in values(). uses wantarray for Petal compliancy.

@values = $obj->list

synonym for $obj->values().

@values = $obj->sorted_list

returns $obj->values() sorted alphabetically by key.

$iterator = $obj->iterator

get an iterator code ref for this collection, can be used as such:

  while (my $next_val = $iterator->()) {
      ...
  }

useful for large collections.

$boolean = $obj->exists( $key )

as in exists().

$value = $obj->get( $key )

get the value associated with $key. throws an error if $key does not exist.

$obj->add( $value1, $value2, ... )

add values to this collection. looks up keys for these values with $obj->get_values_key(). throws an error if values already exists. returns this object.

$obj->remove( $key1, $value2, ... )

remove keys and/or values from this collection. throws an error if a key does not exist. returns this object.

$key = $obj->get_values_key( $value )

gets $value->key() if $value is blessed, or returns $value.

$obj2 = $obj->clone

returns a new object containing a shallow copy of this collection. (ie: objects in the clone's collection are the same)

$obj2 = $obj->deep_clone

returns a new object containing a deep copy of this collection. (ie: objects in the clone's collection are cloned)

SUB-CLASSING

Override the following methods:

$key = $obj->error_key_exists( $key ): abstract. indicates a Pangloss::Error should be thrown.
$key = $obj->error_key_nonexistent( $key ): abstract. indicates a Pangloss::Error should be thrown.

AUTHOR

Steve Purkis <spurkis@quiup.com>

CPAN RT