new($data)
Constructor method. A reference to a list of values is passed as the
first parameter. Subsequent calls to get_first() and get_next() calls
will return each element from the list.
my $iter = Template::Iterator->new([ 'foo', 'bar', 'baz' ]);
The constructor will also accept a reference to a hash array and will
expand it into a list in which each entry is a hash array containing
a 'key' and 'value' item, sorted according to the hash keys.
my $iter = Template::Iterator->new({
foo => 'Foo Item',
bar => 'Bar Item',
});
This is equivalent to:
my $iter = Template::Iterator->new([
{ key => 'bar', value => 'Bar Item' },
{ key => 'foo', value => 'Foo Item' },
]);
When passed a single item which is not an array reference, the constructor
will automatically create a list containing that single item.
my $iter = Template::Iterator->new('foo');
This is equivalent to:
my $iter = Template::Iterator->new([ 'foo' ]);
Note that a single item which is an object based on a blessed ARRAY
references will NOT be treated as an array and will be folded into
a list containing that one object reference.
my $list = bless [ 'foo', 'bar' ], 'MyListClass';
my $iter = Template::Iterator->new($list);
equivalent to:
my $iter = Template::Iterator->new([ $list ]);
If the object provides an as_list() method then the Template::Iterator
constructor will call that method to return the list of data. For example:
package MyListObject;
sub new {
my $class = shift;
bless [ @_ ], $class;
}
package main;
my $list = MyListObject->new('foo', 'bar');
my $iter = Template::Iterator->new($list);
This is then functionally equivalent to:
my $iter = Template::Iterator->new([ $list ]);
The iterator will return only one item, a reference to the MyListObject
object, $list.
By adding an as_list() method to the MyListObject class, we can force
the Template::Iterator constructor to treat the object as a list and
use the data contained within.
package MyListObject;
...
sub as_list {
my $self = shift;
return $self;
}
package main;
my $list = MyListObject->new('foo', 'bar');
my $iter = Template::Iterator->new($list);
The iterator will now return the two item, 'foo' and 'bar', which the
MyObjectList encapsulates.
get_first()
Returns a ($value, $error) pair for the first item in the iterator set.
The $error returned may be zero or undefined to indicate a valid datum
was successfully returned. Returns an error of STATUS_DONE if the list
is empty.
get_next()
Returns a ($value, $error) pair for the next item in the iterator set.
Returns an error of STATUS_DONE if all items in the list have been
visited.
get_all()
Returns a (\@values, $error) pair for all remaining items in the iterator
set. Returns an error of STATUS_DONE if all items in the list have been
visited.
size()
Returns the size of the data set or undef if unknown.
max()
Returns the maximum index number (i.e. the index of the last element)
which is equivalent to size() - 1.
index()
Returns the current index number which is in the range 0 to max().
count()
Returns the current iteration count in the range 1 to size(). This is
equivalent to index() + 1. Note that number() is supported as an alias
for count() for backwards compatability.
first()
Returns a boolean value to indicate if the iterator is currently on
the first iteration of the set.
last()
Returns a boolean value to indicate if the iterator is currently on
the last iteration of the set.
prev()
Returns the previous item in the data set, or undef if the iterator is
on the first item.
next()
Returns the next item in the data set or undef if the iterator is on the
last item.
|
