Commit 7c3aa370 authored by Graham Ritchie's avatar Graham Ritchie
Browse files

adding new Iterator object to core API

parent 4bd8da64
=head1 NAME
Bio::EnsEMBL::Utils::Iterator
=head1 SYNOPSIS
my $variation_iterator = $variation_adaptor->fetch_iterator_by_VariationSet($1kg_set);
while (my $variation = $variation_iterator->next) {
# operate on variation object
print $variation->name, "\n";
}
=head1 DESCRIPTION
Some adaptor methods may return more objects than can fit in memory at once, in these cases
you can fetch an iterator object instead of the usual list reference. The iterator object
allows you to iterate over the set of objects (using the next() method) without loading the
entire set into memory at once.
=head1 LICENSE
Copyright (c) 1999-2010 The European Bioinformatics Institute and
Genome Research Limited. All rights reserved.
This software is distributed under a modified Apache license.
For license details, please see
http://www.ensembl.org/info/about/code_licence.html
=head1 CONTACT
Please email comments or questions to the public Ensembl
developers list at <dev@ensembl.org>.
Questions may also be sent to the Ensembl help desk at
<helpdesk@ensembl.org>.
=cut
package Bio::EnsEMBL::Utils::Iterator;
use strict;
use warnings;
=head2 new
Arg 1 : a coderef representing the iterator, this anonymous subroutine
is assumed to return the next object in the set when called,
and to return undef when the set is exhausted
Example :
my $iterator = Bio::EnsEMBL::Utils::Iterator->new(
sub { return $self->fetch_by_dbID(shift @dbIDs) }
);
NB: this is a very simple example showing how to call the constructor
that would be rather inefficient in practice, real examples should
probably be smarter about batching up queries to minimise trips to
the database. See examples in the Variation API.
Description: Constructor, creates a new iterator object
Returntype : Bio::EnsEMBL::Utils::Iterator instance
Exceptions : dies if the supplied argument is not a coderef
Caller : general
Status : Experimental
=cut
sub new {
my $class = shift;
my $coderef = shift;
die "The supplied argument does not look like an coderef"
unless ref $coderef eq 'CODE';
my $self = {sub => $coderef};
return bless $self, $class;
}
=head2 next
Example : $obj = $iterator->next()
Description: returns the next object from this iterator, or undef if the iterator is exhausted
Returntype : object reference (the type will depend on what this iterator is iterating over)
Exceptions : none
Caller : general
Status : Experimental
=cut
sub next {
my $self = shift;
# if someone has called has_next, there might be a cached value we can return
if ($self->{next}) {
return delete $self->{next};
}
else {
return $self->{sub}->();
}
}
=head2 has_next
Example : if ($iterator->has_next) { my $obj = $iterator->next }
Description: returns true if this iterator has more objects to fetch, false when it is exhausted
Returntype : boolean
Exceptions : none
Caller : general
Status : Experimental
=cut
sub has_next {
my $self = shift;
$self->{next} = $self->{sub}->();
return defined $self->{next};
}
1;
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment