ensembl-hive
2.6
|
Public Member Functions | |
public Bio::EnsEMBL::Utils::Iterator | new () |
protected void | _fetch_next_value_if_needed () |
public Object | next () |
public Boolean | has_next () |
public Object | peek () |
public Bio::EnsEMBL::Utils::Iterator | grep () |
public Bio::EnsEMBL::Utils::Iterator | map () |
public void | each () |
public Arrayref | to_arrayref () |
public Bio::EnsEMBL::Utils::Iterator | append () |
public Bio::EnsEMBL::Utils::Iterator | take () |
public Bio::EnsEMBL::Utils::Iterator | skip () |
public Returntype | reduce () |
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 array 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. The peek() method allows you to fetch the next object from the iterator without advancing the iterator - this is useful if you want to check some property of en element in the set while leaving the iterator unchanged. You can filter and transform 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. Iterators can be combined together with the append() method which merges together the iterator it is called on with the list of iterators passed in as arguments. This is somewhat analogous to concatenating arrays with the push function. append() returns a new iterator which iterates over each component iterator until it is exhausted before moving on to the next iterator, in the order in which they are supplied to the method. An iterator can be converted to an array (reference) containing all the elements in the set with the to_arrayref() method, but note that this array may consume a lot of memory if the set the iterator is iterating over is large and it is recommended that you do not call this method unless there is no way of working with each element at a time.
Definition at line 44 of file Iterator.pm.
protected void Bio::EnsEMBL::Utils::Iterator::_fetch_next_value_if_needed | ( | ) |
Example :
Description: Helper method used to fill the internal buffer with the next value of the iterator Returntype : none Exceptions : none Caller : general Status : Experimental
public Bio::EnsEMBL::Utils::Iterator Bio::EnsEMBL::Utils::Iterator::append | ( | ) |
Example :
Description: return a new iterator that combines this iterator with the others passed as arguments, this new iterator will iterate over each component iterator (in the order supplied here) until it is exhausted and then move on to the next iterator until all are exhausted Argument : an array of Bio::EnsEMBL::Utils::Iterator objects Returntype : Bio::EnsEMBL::Utils::Iterator Exceptions : thrown if any of the arguments are not iterators Caller : general Status : Experimental
public void Bio::EnsEMBL::Utils::Iterator::each | ( | ) |
Example :
Description: Performs a full iteration of the current iterator instance. Argument : a coderef which returns the desired transformation of each element. $_ will be set locally set to each element. Returntype : None Exceptions : thrown if the argument is not a coderef Caller : general Status : Experimental
public Bio::EnsEMBL::Utils::Iterator Bio::EnsEMBL::Utils::Iterator::grep | ( | ) |
Example :
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 a subroutine which expects a single argument with the same behaviour. Returntype : Bio::EnsEMBL::Utils::Iterator Exceptions : thrown if the argument is not a coderef Caller : general Status : Experimental
public Boolean Bio::EnsEMBL::Utils::Iterator::has_next | ( | ) |
Example :
Description: Boolean - true if this iterator has more elements to fetch, false when it is exhausted Returntype : boolean Exceptions : none Caller : general Status : Experimental
public Bio::EnsEMBL::Utils::Iterator Bio::EnsEMBL::Utils::Iterator::map | ( | ) |
Example :
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 a subroutine which expects a single argument with the same behaviour. Returntype : Bio::EnsEMBL::Utils::Iterator Exceptions : thrown if the argument is not a coderef Caller : general Status : Experimental
public Bio::EnsEMBL::Utils::Iterator Bio::EnsEMBL::Utils::Iterator::new | ( | ) |
Argument : either a coderef representing the iterator, in which case this anonymous subroutine is assumed to return the next object in the set when called and to return undef when the set is exhausted, or an arrayref, in which case we return an iterator over this array. If the argument is not defined then we return an 'empty' iterator that immediately returns undef
Example :
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 : thrown if the supplied argument is not the expected Caller : general Status : Experimental
public Object Bio::EnsEMBL::Utils::Iterator::next | ( | ) |
Example :
Description: returns the next object from this iterator, or undef if the iterator is exhausted Returntype : Object type will depend on what this iterator is iterating over Exceptions : none Caller : general Status : Experimental
public Object Bio::EnsEMBL::Utils::Iterator::peek | ( | ) |
Example :
Description: returns the next object from this iterator, or undef if the iterator is exhausted, much like next but does not advance the iterator (so the same object will be returned on the following call to next or peek) Returntype : Object type will depend on what this iterator is iterating over Exceptions : none Caller : general Status : Experimental
public Returntype Bio::EnsEMBL::Utils::Iterator::reduce | ( | ) |
Example :
Description: reduce this iterator with the provided coderef, using the (optional) second argument as the initial value of the accumulator Argument[1]: a coderef that expects 2 arguments, the current accumulator value and the next element in the set, and returns the next accumulator value. Unless the optional second argument is provided the first accumulator value passed in will be the first element in the set Argument[2]: (optional) an initial value to use for the accumulator instead of the first value of the set Returntype : returntype of the coderef Exceptions : thrown if the argument is not a coderef Caller : general Status : Experimental
public Bio::EnsEMBL::Utils::Iterator Bio::EnsEMBL::Utils::Iterator::skip | ( | ) |
Example :
Description: skip over the first n elements of this iterator (and then return the same iterator for your method chaining convenience) Argument : a positive integer Returntype : Bio::EnsEMBL::Utils::Iterator Exceptions : thrown if the argument is negative Caller : general Status : Experimental
public Bio::EnsEMBL::Utils::Iterator Bio::EnsEMBL::Utils::Iterator::take | ( | ) |
Example :
Description: return a new iterator that only iterates over the first n elements of this iterator Argument : a positive integer Returntype : Bio::EnsEMBL::Utils::Iterator Exceptions : thrown if the argument is negative Caller : general Status : Experimental
public Arrayref Bio::EnsEMBL::Utils::Iterator::to_arrayref | ( | ) |
Example :
Description: return a reference to an array containing all elements from the iterator. This is created by simply iterating over the iterator until it is exhausted and adding each element in turn to an array. Note that this may consume a lot of memory for iterators over large collections Returntype : arrayref Exceptions : none Caller : general Status : Experimental