#-------------
    my $self = shift;
    local($^W) = 0;
    undef $self->{'_prev'};
    undef $self->{'_next'};
    undef $self->{'_rank'};
    undef $self->{'_master'};

#-------------
    my( $self, %param) = @_;

    $self->_set_master($self) unless $self->{'_master'}->{'_set'};

    my($rank, $rank_by) = $self->master->_rearrange([qw(RANK RANK_BY)], %param);

    $DEBUG==1 and do{ print STDERR "$ID:set_rank() = $rank; Criteria: $rank_by."; <STDIN>; };

    $self->{'_rank'} = ($rank || undef);
    $self->{'_master'}->{'_rankBy'} = ($rank_by || undef);
    if( defined $self->{'_rank'} and not defined $self->{'_master'}->{'_rankBy'} ) {
	return $self->master->warn('Rank defined without ranking criteria.');
    }	
    1;

    my( $self, $arg) = @_;
    $self->{'_master'}->{'_rankBy'} = $arg || 'unknown';

    ## A vector does not need a master object unless it needs to grow.
    my($self,$obj) = @_;

#    print "$ID: _set_master() new Master object for ${\$obj->name}."; <STDIN>;

    require Bio::Root::Object;
    my $master = {};
    bless $master, 'Bio::Root::Object';

    $master->{'_set'}  = 1;  ## Special member indicating that this method has been called.
                            ## Necessary since perl will generate an anonymous {Master}
                            ## hash ref on the fly. This ref will not be blessed however.
    $master->{'_first'} = $obj;
    $master->{'_last'}  = $obj;
    $master->{'_size'}  = 1;
    $master->{'_index'}->{$obj->name()} = $obj;
    $self->{'_master'} = $master;

    $self->{'_rank'} = 1;
    $self->{'_prev'} = undef;
    $self->{'_next'} = undef;
#    $self->{'_master'}->{'_rankBy'} = undef;  # Default rank is the order of addition to Vector.

# This is called when the last object in the vector is being remove()d
    my $self = shift;

    return if !$self->master or !$self->master->{'_set'};

    my $master = $self->master;

    ## Get rid of the Vector master object.
    ref $master->{'_first'} and (%{$master->{'_first'}} = (), undef $master->{'_first'});
    ref $master->{'_last'}  and (%{$master->{'_last'}} = (), undef $master->{'_last'});
    ref $master->{'_index'} and (%{$master->{'_index'}} = (), undef $master->{'_index'});
    %{$master} = ();
    undef $master;

#-----------------
    my($self, $obj) = @_;

    ref($obj) || throw($self, "Can't clone $ID object: Not an object ref ($obj)");

    $self->{'_prev'} = $obj->{'_prev'};
    $self->{'_next'} = $obj->{'_next'};
    $self->{'_rank'} = $obj->{'_rank'};
    $self->{'_master'} = $obj->{'_master'};

 my $self = shift; $self->{'_prev'};

 my $self = shift; $self->{'_next'};

#----------
    my $self = shift;
    defined $self->{'_master'} ? $self->{'_master'}->{'_first'} : $self;

#-------
    my $self = shift;
    defined $self->{'_master'} ? $self->{'_master'}->{'_last'} : $self;

 my $self = shift; $self->{'_rank'} || 1;

#-----------
    my $self = shift;
    defined $self->{'_master'} ? ($self->{'_master'}->{'_rankBy'}||'order of addition')
	: 'unranked';

#---------
    my $self = shift;
    defined $self->{'_master'} ? $self->{'_master'}->{'_size'} : 1;

 my $self = shift; $self->{'_master'};

 my($self,$obj) = @_; $self->{'_prev'} = $obj;

 my($self,$obj) = @_; $self->{'_next'} = $obj;

 my($self) = shift; return not defined $self->{'_prev'};

 my($self) = shift; return not defined $self->{'_next'};

#--------
    my($self,$name) = @_;

    my ($obj);
#    print "$ID get(): getting $name\n";

    if($self->{'_master'}->{'_set'}) {
#	my @names = keys %{$self->{'_master'}->{'_index'}};
#	print "$ID: names in hash:\n@names";<STDIN>;
#	print "  returning $self->{'_master'}->{'_index'}->{$name}\n";
	local($^W) = 0;
	$obj = $self->{'_master'}->{'_index'}->{$name};
    }

    elsif($self->name =~ /$name/i) {
#	print "  returning self\n";
	$obj = $self;
    }

    if(not ref $obj) {
	$self->throw("Can't get object named\" $name\": object not set or name undefined.");
    }
    $obj;

#--------
    my($self,$new,$index) = @_;

    $self->_set_master($self) unless $self->{'_master'}->{'_set'};

#    print "\n\nADDING TO VECTOR ${\ref $self} ${\$self->name}\nFOR PARENT: ${\ref $self->parent} ${\$self->parent->name}\n\n";

    $self->{'_next'} = $new;
    $new->{'_prev'} = $self;
    $self->{'_master'}->{'_last'} = $new;
    $self->{'_master'}->{'_size'}++;
    $new->{'_master'} = $self->{'_master'};
    $new->_incrementRank();
    $new->Bio::Root::Vector::_index();

#    printf "NEW CONTENTS: (n=%s)\n", $self->size;
#    my $obj = $self->first;
#    my $count=0;
#    do { print "\n","Object #",++$count,"\n";
#	       $obj->display;
#     } while($obj=$obj->next);
#    <STDIN>;

    my($self) = @_;
    my $name = $self->name;

    # Generate unique name, if necessary, for indexing purposes.
    if( not $name or $name =~ /anonymous/) {
	$name ||= '';
	$name .= $self->size();
    }
#    print "$ID: _index() called for $name\n";

    $self->{'_master'}->{'_index'}->{$name} = $self;

    my $self = shift;
    return if not defined $self->{'_prev'};
    $self->{'_rank'} = $self->{'_prev'}->rank() + 1;

#-----------
    my($self,%param) = @_;
    my $updateRank = $param{-UPDATE} || $param{'-update'}  || 0;
    my $ret = $param{-RET} || $param{'-ret'} || 'next';

    $DEBUG==2 && do{ print STDERR "$ID: removing ${\$self->name}; ret = $ret";<STDIN>; };

    ## This set of conditionals involves primarily pointer shuffling.
    ## The special case of destroying a vector of size 1 is handled.

    if($self->is_first()) {
	$DEBUG==2 && print STDERR "---> removing first object: ${\$self->name()}.\n";
	if($self->is_last) {
#	    print "Removing only object in vector: ${\$self->name}.\n";
	    $self->_destroy_master();
	    return $self->destroy;
	} else {
	    undef ($self->{'_next'}->{'_prev'});
	    $self->_update_first($self->{'_next'});
	}

    } elsif($self->is_last()) {
	$DEBUG==2 && print STDERR "---> removing last object: ${\$self->name()}.\n";
	undef ($self->{'_prev'}->{'_next'});
	$self->_update_last($self->{'_prev'});

    } else {
	$DEBUG==2 && print STDERR "---> removing internal object.\n";
	$self->{'_prev'}->{'_next'} = $self->{'_next'};
	$self->{'_next'}->{'_prev'} = $self->{'_prev'};
    }

    $updateRank && $self->_update_rank();
    $self->{'_master'}->{'_size'}--;

#    print "new vector size = ",$self->size,"\n"; <STDIN>;

    my($retObj);

    if( $self->size) {
	if($ret eq 'first') { $retObj = $self->first(); }
	elsif($ret eq 'last') { $retObj = $self->last(); }
	elsif($ret eq 'next') { $retObj = $self->next(); }
	elsif($ret eq 'prev') { $retObj = $self->prev(); }
    }

    ## Destroy the object.
#    $self->destroy;

    $DEBUG && do{ print STDERR "$ID: returning ${\$retObj->name}";<STDIN>; };

    $retObj;

    my($self,$first) = @_;
    $DEBUG && print STDERR "Updating first.\n";
    undef ($first->{'_prev'});
    $self->{'_master'}->{'_first'} = $first;

    my($self,$last) = @_;
    $DEBUG && print STDERR "Updating last.\n";
    undef ($last->{'_next'});
    $self->{'_master'}->{'_last'} = $last;

#---------------
    my($self,%param) = @_;

    $DEBUG==2 && print STDERR "DESTROYING VECTOR $self ${\$self->name}";

#    print "$ID Removing all.";

    $self = $self->first();

    while(ref $self) {
#	print "$ID: removing ${\$self->name}\n";
	$self = $self->remove(-RET=>'next');
    }

#---------
    my($self,%param) = @_;
    $self = $self->first();
    $self = $self->remove(%param);

#----------
    my($self,%param) = @_;
    $self = $self->last();
    $self = $self->remove(%param);

#-----------
    my($self,$object,$where) = @_;
    my($first);
    $where ||= 'after';

    $self->_set_master($self) unless $self->{'_master'}->{'_set'};

    ref($object) || return $self->master->throw("Can't insert. Not an object: $object");

    if($where eq 'before') {
	$object->{'_next'} = $self;
	$object->{'_prev'} = $self->{'_prev'};
	$object->{'_master'} = $self->{'_master'};
	$self->{'_prev'}->{'_next'} = $object;
	$self->{'_prev'} = $object;
    } else {
	$object->{'_prev'} = $self;
	$object->{'_next'} = $self->{'_next'};
	$object->{'_master'} = $self->{'_master'};
	$self->{'_next'}->{'_prev'} = $object;
	$self->{'_next'} = $object;
    }
    $self->{'_master'}->{'_size'}++;
    $object->Bio::Root::Vector::_index();  ##Fully qualified to disambiguate a potentially common method name.
    $self->_update_rank();

    my($self) = @_;
    my $current = $self->first();
    my $count = 0;
    $DEBUG && print STDERR "$ID: Updating rank.\n";
    do{
	$count++;
	$current->{'_rank'} = $count;

    } while($current = $current->next());

#----------
    my($self,$start,$stop) = @_;
    my(@list);

    $start ||= 1;
    $stop  ||= 'last';

    if( $start =~ /first|beg|start/i or $start <= 1 ) {
	$start = $self->first();
    }

    if( $stop =~ /last|end|stop/i ) {
	$stop = $self->last();
    }

    ref($start) || ($start = $self->first());
    ref($stop)  || ($stop = $self->last());

    my $obj = $start;
    my $fini = 0;
    do{
	push @list, $obj;
	if($obj eq $stop) { $fini = 1; }
    } while( $obj = $obj->next() and !$fini);

    @list;

#---------
    my ($self,$sortBy,$reverse) = @_;
    my (@unsortedList,@sortedList);

    $sortBy ||= 'rank';
    my $rankBy = $self->rank_by;

    ### Build the initial unsorted list.
    my $obj = $self->first();
    do{
	push @unsortedList, $obj;
    } while( $obj = $obj->next());

#    print "UNSORTED LIST:\n";
#    foreach(@unsortedList) {print $_->name().' '};<STDIN>;

    ### Sort it.
    if( $sortBy =~ /rank/i) {
#	print "sorting by rank";
	if($reverse) {
#	    print " (reverse).\n";
	    @sortedList = reverse sort _sort_by_rank @unsortedList;
	} else {
	    @sortedList = sort _sort_by_rank @unsortedList;
	}
    } elsif( $sortBy =~ /name/i) {
#	print "sorting by name";
	if($reverse) {
#	    print "(reverse).\n";
	    @sortedList = reverse sort _sort_by_name @unsortedList;
	} else {
	    @sortedList = sort _sort_by_name @unsortedList;
	}
    } else {
#	print "unknown sort criteria: $sortBy\n";
	$self->warn("Invalid sorting criteria: $sortBy.",
		    "Sorting by rank.");
	@sortedList = sort _sort_by_rank @unsortedList;
    }


#    if($reverse) { @sortedList = reverse sort @sortedList;  }

#    print "SORTED LIST:\n";
#    foreach(@sortedList) {print $_->name().' '};<STDIN>;

    ### Re-load the Vector with the sorted list.
    my $count=0;

    $self = $sortedList[0];
    $self->_set_master($self);
    $self->_set_rank_by($rankBy);

    my($i);
    my $current = $self;
    for($i=1; $i<@sortedList; $current=$sortedList[$i], $i++) {
	$current->add($sortedList[$i]);
	if($i==$#sortedList) { $sortedList[$i]->{'_next'} = undef;}
    }

    $self->last();

 my $aRank = $a->rank(); my $bRank = $b->rank(); $aRank <=> $bRank;

 my $aName = $a->name(); my $bName = $b->name(); $aName cmp $bName;

#-------------
    my $self = &shift(@_);

    my $obj = $self->first();
    do{
	return 1 if $obj->valid();
    } while( $obj = $obj->next());

   return undef;

#--------------
    my $self = &shift(@_);

    my $obj = $self->first();
    do{
	return  unless $obj->valid();
    } while( $obj = $obj->next());

   return 1;

# This could be fleshed out a bit...

    my( $self, $OUT ) = @_;

    printf ( $OUT "%-11s %s\n","RANK:", $self->rank());
    printf ( $OUT "%-11s %s\n","RANK BY:", $self->rank_by());

   http://bio.perl.org/Core/Latest
   ftp://bio.perl.org/pub/DIST

  bioperl-l@bioperl.org             - General discussion
  http://bioperl.org/MailList.shtml - About the mailing lists

    bioperl-bugs@bio.perl.org
    http://bugzilla.bioperl.org/

  Bio::Root::Object.pm    - Core object
  Bio::Root::Err.pm       - Error/Exception object
  Bio::Root::Global.pm    - Manages global variables/constants

  http://bio.perl.org/Projects/modules.html  - Online module documentation
  http://bio.perl.org/                       - Bioperl Project Homepage

 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.