added map and grep methods

modules/Bio/EnsEMBL/Utils/Iterator.pm

@@ -34,12 +34,17 @@
 
 
 =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.
+  
+  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. You can tell if an iterator is exhausted with the has_next()
+  method.
+
+  You can map and grep an iterator in an analogous way to using map and grep on arrays using
+  the provided map and grep methods. These methods return another iterator, and only perform
+  the filtering and transformation on each element as it is requested, so again these can be 
+  used without loading the entire set into memory.
 
 =head1 METHODS
 
@@ -132,4 +137,63 @@ sub has_next {
     return defined $self->{next}; 
 }
 
+=head2 grep
+
+  Example    : my $filtered_iterator = $original_iterator->grep(sub {$_->name =~ /^rs/});
+  Description: filter this iterator, returning another iterator
+  Argument   : a coderef which returns true if the element should be included in the
+               filtered set, or false if the element should be filtered out. $_ will be 
+               set locally to each element in turn so you should be able to write a block 
+               in a similar way as for the perl grep function (although it will need to be 
+               preceded with the sub keyword). Otherwise you can pass in a reference to an 
+               existing subroutine with the same behaviour.
+  Returntype : Bio::EnsEMBL::Utils::Iterator
+  Exceptions : dies if the argument is not a coderef
+  Caller     : general
+  Status     : Experimental
+
+=cut
+
+sub grep {
+    my ($self, $coderef) = @_;
+
+    die "Argument should be a coderef" unless ref $coderef eq 'CODE';
+
+    return Bio::EnsEMBL::Utils::Iterator->new(sub {
+        while ($self->has_next) {
+            local $_ = $self->next;
+            return $_ if $coderef->();
+        }
+        return undef;
+    });
+}
+
+=head2 map
+
+  Example    : my $transformed_iterator = $original_iterator->map(sub {$_->name});
+  Description: transform the elements of this iterator, returning another iterator
+  Argument   : a coderef which returns the desired transformation of each element.
+               $_ will be set locally set to each original element in turn so you 
+               should be able to write a block in a similar way as for the perl map 
+               function (although it will need to be preceded with the sub keyword). 
+               Otherwise you can pass in a reference to an existing subroutine with 
+               the same behaviour.
+  Returntype : Bio::EnsEMBL::Utils::Iterator
+  Exceptions : dies if the argument is not a coderef
+  Caller     : general
+  Status     : Experimental
+
+=cut
+
+sub map {
+    my ($self, $coderef) = @_;
+    
+    die "Argument should be a coderef" unless ref $coderef eq 'CODE';
+
+    return Bio::EnsEMBL::Utils::Iterator->new(sub {
+        local $_ = $self->next;
+        return defined $_ ? $coderef->() : undef;
+    });
+}
+
 1;