Bio::Root::Vector - Interface for managing linked lists of Perl5 objects.


Object Creation

At present, Vector objects cannot be instantiated. This package is currently designed to be inherited along with another class that provides a constructor (e.g., The Vector provides a set of methods that can then be used for managing sets of objects.



This module is included with the central Bioperl distribution:

Follow the installation instructions included in the README file.

DESCRIPTION provides an interface for creating and manipulating dynamic sets (linked lists) of Perl5 objects. This is an abstract class (ie., there is no constructor) and as such is expected to be inherited along with some other class (see note above).

Vectors are handy when, for example, an object may contain one or more other objects of a certain class. The container object knows only that is has at least one such object; the multiplex nature of the contained object is managed by the contained object via its Vector interface. The methods for adding, removing, counting, listing, and sorting all objects are bundled together in

Thus, the current Bio::Root::Vector class is somewhat of a cross between an interator and a composite design pattern. At present, a number of classes utilize Bio::Root::Vector's composite-like behavior to implement a composite pattern (, for example). This is not necessarily ideal and is expected to change.


For a usage demo of, see:

DEPENDENCIES does not directly inherit from but creates an manager object which does.


By default, all Vectors are doubly-linked lists. This relieves one from the burden of worrying about whether a given Vector is single- or doubly-linked. However, when generating lots of Vectors or extremely large vectors, memory becomes an issue. In particular, signaling the GC to free the memory for an object when you want to remove it. Until this memory issue is resolved, the use of is not recommended for large projects.

Although it is not required, all objects within a vector are expected to derive from the same class (package). Support for heterogeneous Vectors has not been explicitly added (but they should work fine, as long as you know what you're doing).


Mailing Lists

User feedback is an integral part of the evolution of this and other Bioperl modules. Send your comments and suggestions preferably to one of the Bioperl mailing lists. Your participation is much appreciated.          - General discussion     - Technically-oriented discussion             - About the mailing lists

Reporting Bugs

Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their resolution. Bug reports can be submitted via email or the web:                         


Steve A. Chervitz,

See the FEEDBACK section for where to send bug reports and comments.



  • (Maybe) create an container class version of this module

    to permit Vectors to be instantiated. Thus, instead of inherited from both and, you could create a object.

  • Improve documentation.

SEE ALSO    - Core object       - Error/Exception object    - Manages global variables/constants  - Online module documentation                       - Bioperl Project Homepage 


This module was developed under the auspices of the Saccharomyces Genome Database:


Copyright (c) 1996-98 Steve A. Chervitz. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Methods beginning with a leading underscore are considered private and are intended for internal use by this module. They are not considered part of the public interface and are described here for documentation purposes only.


 Purpose  : To set an object's rank to an arbitrary numeric
          : value to be used for sorting the objects of the Vector.
 Usage    : $self->set_rank(-RANK    =>numeric_ranking_data, 
          :                 -RANK_BY =>ranking_criterion_string);
          : or without the named parameters as (rank, rank_by).
 Throws   : warning (if rank is set without also setting RANK_BY)
 Comments : It is redundant for every object to store RANK_BY data.
          : For this reason, the RANK_BY data is stored with the master
          : object associated with the vector.

See Also : rank(), rank_by()


 Purpose  : Call this method to clone the whole vector. 
          : NOT calling this method will extract the vector element.
 Usage    : $self->clone_vector();
 Throws   : Exception if argument is not an object reference. 
 Comments : This method is usually called from within a module's
          : _set_clone() method for modules that inherit from 


 Purpose  : Returns the previous object in the Vector or undef 
          : if on first object.
 Usage    : $self->prev


 Purpose  : Returns the next object in the Vector or undef 
          : if on last object.
 Usage    : $self->next


 Purpose  : Returns the first object in the Vector or $self 
          : if Vector size = 1.
 Usage    : $self->first


 Purpose  : Returns the last object in the Vector or 
          : $self if Vector size = 1.
 Usage    : $self->last


 Purpose  : Returns the rank of the current object or 1
          : if rank is not defined.
 Usage    : $self->rank

See Also : set_rank()


 Purpose  : Returns the ranking criterion or the string 'order of addition'
          : if rankBy has not been explicitly set.
 Usage    : $self->rank_by

See Also : set_rank()


 Purpose  : Returns the number of objects currently in the Vector.
 Usage    : $self->size


 Purpose  : Returns the master object associated with the Vector.
          : (should probably be a private method).
 Usage    : $self->master


 Purpose  : Test whether the current object is the first in the Vector.
 Usage    : $self->is_first


 Purpose  : Test whether the current object is the last in the Vector.
 Usage    : $self->is_last


 Purpose  : Retrives an object from the Vector given its name.
          : Returns undef if the object cannot be found.
 Usage    : $self->get(object_name)
 Examples : $self->get($obj->name)

See Also : list()


 Purpose  : Add an object to the end of a Vector.
 Usage    : $self->add(object_reference)

See also : insert(), remove()


 Purpose  : Remove the current object from the Vector.
 Usage    : $self->remove([-RET=>'first'|'last'|'next'|'prev'], [-UPDATE => 0|1])
 Returns  : The first, last, next, or previous object in the Vector
          : depending on the value of the -RET parameter.
          : Default = next.
 Argument : Named parameters: (TAGS CAN BE ALL UPPER OR ALL LOWER CASE)
          :    -RET    => string: 'first', 'last', 'prev' 'next'
          :               THis indicates the object to be returned.
          :    -UPDATE => boolean, if non-zero all objects in the vector
          :               will be re-ranked.
 Comments : The -UPDATE parameter should be set to true to force a re-updating
          : of the rank data for each object. (default = 0, no update).

See Also : add(), insert(), shift(), chop()


 Purpose  : Remove all objects currently in the Vector. 
 Usage    : $self->remove_all

See Also : remove(), shift(), chop()


 Purpose  : Remove the first object from the Vector. 
          : This is a wrapper for remove().
 Usage    : $self->shift([-RET=>'first'|'last'|'next'|'prev'])
 Returns  : The object returned by remove().

See Also : remove(), chop()


 Purpose  : Remove the last object from the Vector. 
          : This is a wrapper for remove().
 Usage    : $self->chop([-RET=>'first'|'last'|'next'|'prev'])
 Returns  : The object returned by remove().

See Also : remove(), shift()


 Purpose  : Insert a new object into the vector relative to the current object.
 Usage    : $self->insert(object_ref, ['before'|'after'])
 Examples : $self->insert($obj)  # Default insert after $self
          : $self->insert($obj,'before')  
 Returns  : The new number of objects in the vector (int).
 Throws   : exception if the first argument is not a reference.

See Also : add(), remove()


 Purpose  : Returns objects in the Vector as an array or array slice.
 Usage    : $self->list([starting_object|'first'] [,ending_object|'last'])
 Examples : $self->list
          : $self->list('first',$self->prev)

See Also : get()


 Purpose  : Sort the objects in the Vector.
 Usage    : $self->sort(['rank'|'name'], [reverse])
 Returns  : The last object of the sorted Vector.
 Argument : First argument can be 'name' or 'rank' to sort on
          : the object's name or rank data member, respectively.
          : If reverse is non-zero, sort will be in reverse order.
 Example  : $self->sort()   #  Default sort by rank, not reverse.
          : $self->sort('name','reverse')   


 Purpose  : Determine if at least one object in the Vector is valid.
 Usage    : $self->valid_any
 Status   : Deprecated.
 Comments : A non-valid object should throw an exception that must be
          : be caught an dealt with on the spot.

See Also : Bio::Root::Object::valid()


 Purpose  : Determine if all objects in the Vector are valid.
 Usage    : $self->valid_all
 Comments : A non-valid object should throw an exception that must be
          : be caught an dealt with on the spot.

See Also : Bio::Root::Object::valid()


Data Members

Information about the various data members of this module is provided for those wishing to modify or understand the code. Two things to bear in mind:

1 Do NOT rely on these in any code outside of this module.

All data members are prefixed with an underscore to signify that they are private. Always use accessor methods. If the accessor doesn't exist or is inadequate, create or modify an accessor (and let me know, too!).

2 This documentation may be incomplete and out of date.

It is easy for this documentation to become obsolete as this module is still evolving. Always double check this info and search for members not described here. objects currently cannot be instantiated. must be inherited along with (or an object that provides a constructor). defines the following fields:

 FIELD          VALUE
  _prev         Reference to the previous object in the Vector.
  _next         Reference to the next object in the Vector.

  _rank         Rank relative to other objects in the Vector.
                Default rank = chronological order of addition to the Vector.
  _master       A reference to an Bio::Root::Object that acts as a manager for 
                the given Vector. There is only one master per Vector.
                A master object is only needed when the Vector size is >1. 
                The master object manages the following Vector data:
                _first  - Reference to the first object in the Vector.
                _last   - Reference to the last object in the Vector.
                _size   - Total number of objects in the Vector.
                _rankBy - Criteria used to rank the object. 
                         Default: chronological order of addition.
                _index  - Hash reference for quick access to any object 
                         based on its name.
                Bio::Root::Object{'_err'} - Holds any errors affecting the 
                                     Vector as a whole.