SYNOPSIS

         # create Bio::Coordinate::Pairs or other Bio::Coordinate::MapperIs somehow
         $pair1; $pair2;

         # add them into a Collection
         $collection = Bio::Coordinate::Collection->new;
         $collection->add_mapper($pair1);
         $collection->add_mapper($pair2);

         # create a position and map it
         $pos = Bio::Location::Simple->new (-start => 5, -end => 9 );
         $res = $collection->map($pos);
         $res->match->start == 1;
         $res->match->end == 5;

         # if mapping is many to one (*>1) or many-to-many (*>*)
         # you have to give seq_id not get unrelevant entries
         $pos = Bio::Location::Simple->new
             (-start => 5, -end => 9 -seq_id=>'clone1');

DESCRIPTION

       Generic, context neutral mapper to provide coordinate transforms between two disjoint
       coordinate systems. It brings into Bioperl the functionality from Ewan Birney's
       Bio::EnsEMBL::Mapper ported into current bioperl.

       This class is aimed for representing mapping between whole chromosomes and contigs, or
       between contigs and clones, or between sequencing reads and assembly. The submaps are
       automatically sorted, so they can be added in any order.

       To map coordinates to the other direction, you have to swap() the collection. Keeping
       track of the direction and ID restrictions are left to the calling code.

   new
   add_mapper
        Title   : add_mapper
        Usage   : $obj->add_mapper($mapper)
        Function: Pushes one Bio::Coordinate::MapperI into the list of mappers.
                  Sets _is_sorted() to false.
        Example :
        Returns : 1 when succeeds, 0 for failure.
        Args    : mapper object

   mappers
        Title   : mappers
        Usage   : $obj->mappers();
        Function: Returns or sets a list of mappers.
        Example :
        Returns : array of mappers
        Args    : array of mappers

   each_mapper
        Title   : each_mapper
        Usage   : $obj->each_mapper();
        Function: Returns a list of mappers.
        Example :
        Returns : list of mappers
        Args    : none

   mapper_count
        Title   : mapper_count
        Usage   : my $count = $collection->mapper_count;
        Function: Get the count of the number of mappers stored
                  in this collection
        Example :
        Returns : integer
        Args    : none

   swap
        Title   : swap
        Usage   : $obj->swap;
        Function: Swap the direction of mapping;input <-> output
        Example :
        Returns : 1
        Args    :

   test
        Title   : test
        Usage   : $obj->test;
        Function: test that both components of all pairs are of the same length.
                  Ran automatically.
        Example :
        Returns : boolean
        Args    :

   map
        Title   : map
        Usage   : $newpos = $obj->map($pos);
        Function: Map the location from the input coordinate system
                  to a new value in the output coordinate system.
        Example :
        Returns : new value in the output coordinate system
        Args    : integer

   _map
        Title   : _map
        Usage   : $newpos = $obj->_map($simpleloc);
        Function: Internal method that does the actual mapping. Called multiple times
                  by map() if the location  to be mapped is a split location

        Example :
        Returns : new location in the output coordinate system or undef
        Args    : Bio::Location::Simple

   sort
        Title   : sort
        Usage   : $obj->sort;
        Function: Sort function so that all mappings are sorted by
                  input coordinate start
        Example :
        Returns : 1
        Args    :

   _is_sorted
        Title   : _is_sorted
        Usage   : $newpos = $obj->_is_sorted;
        Function: toggle for whether the (internal) coodinate mapper data are sorted
        Example :
        Returns : boolean
        Args    : boolean