# do not use this module directly
    # See Bio::Map::Position for an example of
    # implementation.

    my $self = shift;
    unless (defined $self->{_eh}) {
        my $ph = Bio::Map::PositionHandler->new(-self => $self);
        $self->{_eh} = $ph;
        $ph->register;
    }
    return $self->{_eh};

    my ($self, $map) = @_;
    return $self->get_position_handler->map($map);

    my ($self, $element) = @_;
    return $self->get_position_handler->element($element);

    my $self = shift;
    $self->throw_not_implemented();

    my $self = shift;
    $self->throw_not_implemented();

    my $self = shift;
    $self->throw_not_implemented();

    my $self = shift;
    $self->throw_not_implemented();

    my $self = shift;
    $self->throw_not_implemented();

    return 1;

    my $self = shift;
    $self->throw_not_implemented();

    # overriding the RangeI implementation so we can handle Relative
    my ($self, $other, $so, $rel) = @_;
    
    my ($own_start, $own_end) = $self->_pre_rangei($self, $rel);
    my ($other_start, $other_end) = $self->_pre_rangei($other, $rel);
    
    return ($self->_testStrand($other, $so) and
            $own_start == $other_start and $own_end == $other_end);

    my ($self, $other, $rel) = @_;
    
    my ($own_start, $own_end) = $self->_pre_rangei($self, $rel);
    my ($other_start, $other_end) = $self->_pre_rangei($other, $rel);
    
    return $own_end < $other_start;

    my ($self, $other, $rel) = @_;
    
    my ($own_start, $own_end) = $self->_pre_rangei($self, $rel);
    my ($other_start, $other_end) = $self->_pre_rangei($other, $rel);
    
    return $own_start > $other_end;

    # overriding the RangeI implementation so we can handle Relative
    my ($self, $other, $so, $rel) = @_;
    
    my ($own_start, $own_end) = $self->_pre_rangei($self, $rel);
    my ($other_start, $other_end) = $self->_pre_rangei($other, $rel);
    
    return ($self->_testStrand($other, $so) and not
            (($own_start > $other_end or $own_end < $other_start)));

    # overriding the RangeI implementation so we can handle Relative
    my ($self, $other, $so, $rel) = @_;
    
    my ($own_start, $own_end) = $self->_pre_rangei($self, $rel);
    my ($other_start, $other_end) = $self->_pre_rangei($other, $rel);
    
    return ($self->_testStrand($other, $so) and
			$other_start >= $own_start and $other_end <= $own_end);

    # overriding the RangeI implementation so we can transfer map and handle
    # Relative
    my ($self, $given, $so, $rel) = @_;
	$self->throw("missing arg: you need to pass in another argument") unless $given;
    
    my @positions;
    if ($self eq "Bio::Map::PositionI") {
		$self = "Bio::Map::Position";
		$self->warn("calling static methods of an interface is deprecated; use $self instead");
	}
	if (ref $self) {
		push(@positions, $self);
	}
    ref($given) eq 'ARRAY' ? push(@positions, @{$given}) : push(@positions, $given);
    $self->throw("Need at least 2 Positions") unless @positions >= 2;
    
    my ($intersect, $i_start, $i_end, $c_start, $c_end, %known_maps);
    while (@positions > 0) {
        unless ($intersect) {
            $intersect = shift(@positions);
            ($i_start, $i_end) = $self->_pre_rangei($intersect, $rel);
            my $map = $intersect->map;
            $known_maps{$map->unique_id} = $map;
        }
        
        my $compare = shift(@positions);
        ($c_start, $c_end) = $self->_pre_rangei($compare, $rel);
        return unless $compare->_testStrand($intersect, $so);
        if ($compare->isa('Bio::Map::PositionI')) {
            my $this_map = $compare->map;
            if ($this_map) {
                $known_maps{$this_map->unique_id} = $this_map;
            }
        }
        else {
            $self->throw("Only Bio::Map::PositionI objects are supported, not [$compare]");
        }
        
        my @starts = sort {$a <=> $b} ($i_start, $c_start);
        my @ends   = sort {$a <=> $b} ($i_end, $c_end);
        
        my $start = pop @starts; # larger of the 2 starts
        my $end = shift @ends;   # smaller of the 2 ends
        
        my $intersect_strand;    # strand for the intersection
        if (defined($intersect->strand) && defined($compare->strand) && $intersect->strand == $compare->strand) {
            $intersect_strand = $compare->strand;
        }
        else {
            $intersect_strand = 0;
        }
        
        if ($start > $end) {
            return;
        }
        else {
            $intersect = $self->new(-start  => $start,
                                    -end    => $end,
                                    -strand => $intersect_strand);
        }
    }
    
    $intersect || return;
    my ($start, $end, $strand) = ($intersect->start, $intersect->end, $intersect->strand);
    
    my @intersects;
    foreach my $known_map (values %known_maps) {
        my $new_intersect = $intersect->new(-start => $start,
                                            -end => $end,
                                            -strand => $strand,
                                            -map => $known_map);
        $new_intersect->relative($rel) if $rel;
        push(@intersects, $new_intersect);
    }
    unless (@intersects) {
        $intersect->relative($rel) if $rel;
        @intersects = ($intersect);
    }
    
    my $result = Bio::Map::Mappable->new();
    $result->add_position(@intersects); # sneaky, add_position can take a list of positions
    return $result;

    # overriding the RangeI implementation so we can transfer map and handle
    # Relative
    my ($self, @args) = @_;
    $self->throw("Not enough arguments") unless @args >= 1;
    
    my @positions;
    my $rel;
    if ($self eq "Bio::Map::PositionI") {
		$self = "Bio::Map::Position";
		$self->warn("calling static methods of an interface is deprecated; use $self instead");
	}
	if (ref $self) {
		push(@positions, $self);
	}
    if (ref $args[0] eq 'ARRAY') {
        push(@positions, @{shift(@args)});
    }
    else {
        push(@positions, shift(@args));
    }
    if ($args[0] && $args[0]->isa('Bio::Map::RelativeI')) {
        $rel = shift(@args);
    }
    foreach my $arg (@args) {
        # avoid pushing undefined values into @positions
        push(@positions, $arg) if $arg;
    }
    $self->throw("Need at least 2 Positions") unless @positions >= 2;
    
    my (@starts, @ends, %known_maps, $union_strand);
    foreach my $compare (@positions) {
        # RangeI union allows start or end to be undefined; however _pre_rangei
        # will throw
        my ($start, $end) = $self->_pre_rangei($compare, $rel);
        
        if ($compare->isa('Bio::Map::PositionI')) {
            my $this_map = $compare->map;
            if ($this_map) {
                $known_maps{$this_map->unique_id} = $this_map;
            }
        }
        else {
            $self->throw("Only Bio::Map::PositionI objects are supported, not [$compare]");
        }
        
        if (! defined $union_strand) {
			$union_strand = $compare->strand;
		}
        else {
			if (! defined $compare->strand or $union_strand ne $compare->strand) {
				$union_strand = 0;
			}
		}
        
        push(@starts, $start);
        push(@ends, $end);
    }
    
	@starts = sort { $a <=> $b } @starts;
	@ends   = sort { $a <=> $b } @ends;
	my $start = shift @starts;
	my $end = pop @ends;
    
    my @unions;
    foreach my $known_map (values %known_maps) {
        my $new_union = $self->new(-start => $start,
                                   -end => $end,
                                   -strand => $union_strand,
                                   -map => $known_map);
        $new_union->relative($rel) if $rel;
        push(@unions, $new_union);
    }
    unless (@unions) {
        @unions = ($self->new(-start => $start,
                         -end => $end,
                         -strand => $union_strand));
        $unions[0]->relative($rel) if $rel;
    }
    
    my $result = Bio::Map::Mappable->new();
    $result->add_position(@unions); # sneaky, add_position can take a list of positions
    return $result;

    # overriding the RangeI implementation so we can transfer map and handle
    # Relative
    my ($self, @args) = @_;
    $self->throw("Not enough arguments") unless @args >= 1;
    
    my @positions;
    my $rel;
    if ($self eq "Bio::Map::PositionI") {
		$self = "Bio::Map::Position";
		$self->warn("calling static methods of an interface is deprecated; use $self instead");
	}
	if (ref $self) {
		push(@positions, $self);
	}
    if (ref $args[0] eq 'ARRAY') {
        push(@positions, @{shift(@args)});
    }
    else {
        push(@positions, shift(@args));
    }
    if ($args[0] && $args[0]->isa('Bio::Map::RelativeI')) {
        $rel = shift(@args);
    }
    foreach my $arg (@args) {
        push(@positions, $arg) if $arg;
    }
    $self->throw("Need at least 2 Positions") unless @positions >= 2;
    
    my %known_maps;
    foreach my $pos (@positions) {
        $pos->isa('Bio::Map::PositionI') || $self->throw("Must supply only Bio::Map::PositionI objects, not [$pos]");
        my $map = $pos->map || next;
        $known_maps{$map->unique_id} = $map;
    }
    my %prior_positions;
    foreach my $map (values %known_maps) {
        foreach my $pos ($map->get_positions) {
            $prior_positions{$pos} = 1;
        }
    }
    
    my @outranges = ();
    foreach my $inrange (@positions) {
        my @outranges_new = ();
        my %overlapping_ranges = ();
        
        for (my $i=0; $i<@outranges; $i++) {
            my $outrange = $outranges[$i];
            if ($inrange->overlaps($outrange, undef, $rel)) {
                my $union_able = $inrange->intersection($outrange, undef, $rel);
                foreach my $pos ($union_able->get_positions) {
                    $overlapping_ranges{$pos->toString} = $pos; # we flatten down to a result on a single map
                                                                # to avoid creating 10s of thousands of positions during this process;
                                                                # we then apply the final answer to all maps at the very end
                }
            }
            else {
                push(@outranges_new, $outrange);
            }
        }
        
        @outranges = @outranges_new;
        
        my @overlappers = values %overlapping_ranges;
        if (@overlappers) {
            if (@overlappers > 1) {
                my $merged_range_able = shift(@overlappers)->union(\@overlappers, $rel);
                push(@outranges, $merged_range_able->get_positions);
            }
            else {
                push(@outranges, @overlappers);
            }
        }
        else {
            push(@outranges, $self->new(-start => $inrange->start($rel), -end => $inrange->end($rel), -strand => $inrange->strand, -map => $inrange->map, -relative => $rel));
        }
    }
    
    # purge positions that were created whilst calculating the answer, but
    # aren't the final answer and weren't there previously
    my %answers = map { $_ => 1 } @outranges;
    foreach my $map (values %known_maps) {
        foreach my $pos ($map->get_positions) {
            if (! exists $prior_positions{$pos} && ! exists $answers{$pos}) {
                $map->purge_positions($pos);
            }
        }
    }
    
    my %post_positions;
    foreach my $map (values %known_maps) {
        foreach my $pos ($map->get_positions) {
            $post_positions{$pos} = 1;
        }
    }
    
    @outranges || return;
    
    # make an outrange on all known maps
    my @final_positions;
    foreach my $map (values %known_maps) {
        foreach my $pos (@outranges) {
            if ($pos->map eq $map) {
                push(@final_positions, $pos);
            }
            else {
                push(@final_positions, $pos->new(-start => $pos->start,
                                                 -end => $pos->end,
                                                 -relative => $pos->relative,
                                                 -map => $map));
            }
        }
    }
    
    # assign the positions to a result mappable
    my $result = Bio::Map::Mappable->new();
    $result->add_position(@final_positions); # sneaky, add_position can take a list of positions
    
    return $result;

    my ($self, $other, $rel) = @_;
    $self->throw("Must supply an object") unless $other;
    if ($rel) {
        $self->throw("Must supply an object for the Relative argument") unless ref($rel);
        $self->throw("This is [$rel], not a Bio::Map::RelativeI") unless $rel->isa('Bio::Map::RelativeI');
    }
    
    my ($other_start, $other_end);
    if (ref($other)) {
        if (ref($other) eq 'ARRAY') {
            $self->throw("_pre_rangei got an array");
        }
        $self->throw("This is [$other], not a Bio::RangeI object") unless defined $other && $other->isa('Bio::RangeI');
        
        if ($other->isa('Bio::Map::PositionI')) {
            # to get the desired start/end we need the position to be on a map;
            # if it isn't on one temporarily place it on self's map
            # - this lets us have 'generic' positions that aren't on any map
            # but have a relative defined and can thus be usefully compared to
            # positions that /are/ on maps
            my $other_map = $other->map;
            unless ($other_map) {
                my $self_map = $self->map || $self->throw("Trying to compare two positions but neither had been placed on a map");
                $other->map($self_map);
            }
            
            # want start and end positions relative to the supplied rel or map start
            $rel ||= $other->absolute_relative;
            $other_start = $other->start($rel);
            $other_end = $other->end($rel);
            
            unless ($other_map) {
                $self->map->purge_positions($other);
            }
        }
        else {
            $other_start = $other->start;
            $other_end = $other->end;
        }
    }
    else {
        $self->throw("not a number") unless looks_like_number($other);
        $other_start = $other_end = $other;
    }
    
	$other->throw("start is undefined") unless defined $other_start;
	$other->throw("end is undefined") unless defined $other_end;
    
    return ($other_start, $other_end);

  bioperl-l@bioperl.org                  - General discussion
  http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

  http://bugzilla.open-bio.org/

 These are fundamental to coordination of Positions and other entities, so are
 implemented at the interface level

 These are fundamental to coordination of Positions and other entities, so are
 implemented at the interface level

 Title   : marker
 Function: This is a synonym of the element() method
 Status  : deprecated, will be removed in the next version

  Title   : start
  Usage   : my $start = $position->start();
            $position->start($start);
  Function: Get/set the start co-ordinate of this position.
  Returns : the start of this position
  Args    : scalar numeric to set, OR
            none to get the co-ordinate normally (see absolute() method), OR
            Bio::Map::RelativeI to get the co-ordinate converted to be
            relative to what this Relative describes.

  Title   : end
  Usage   : my $end = $position->end();
            $position->end($end);
  Function: Get/set the end co-ordinate of this position.
  Returns : the end of this position
  Args    : scalar numeric to set, OR
            none to get the co-ordinate normally (see absolute() method), OR
            Bio::Map::RelativeI to get the co-ordinate converted to be
            relative to what this Relative describes.

  Title   : length
  Usage   : $length = $position->length();
  Function: Get the length of this position.
  Returns : the length of this position
  Args    : none

 Title   : overlap_extent
 Usage   : ($a_unique,$common,$b_unique) = $a->overlap_extent($b)
 Function: Provides actual amount of overlap between two different
           positions
 Example :
 Returns : array of values containing the length unique to the calling 
           position, the length common to both, and the length unique to 
           the argument position
 Args    : a position