## org.biojava.bio.symbol
Class GappedSymbolList

    java.lang.Object
      |
      +--org.biojava.bio.symbol.AbstractSymbolList
            |
            +--org.biojava.bio.symbol.GappedSymbolList

public class GappedSymbolList
extends AbstractSymbolList
implements java.io.Serializable

This implementation of SymbolList wraps another one, allowing you to insert gaps.

You could make a SymbolList that contains gaps directly. However, this leaves you with a nasty problem if you wish to support gap-edit operations. Also, the original SymbolList must either be coppied or lost.

GappedSymbolList solves these problems. It wraps up a source sequence, and views it through a data-structure that places gaps. You can add and remove the gaps by using the public API.

For gap-insert operations, the insert index is the position that will become a gap. The symbol currently there will move to a higher index. To insert leading gaps, add gaps at index 1. To insert trailing gaps, add gaps at index length+1.

Author:
  Matthew Pocock
See Also:
  Serialized Form

Constructor Summary
`GappedSymbolList(SymbolList source)` Create a new GappedSymbolList that will view source.

Method Summary
`void` `addGapInSource(int pos)` Add a gap at pos within the source coordinates.
`void` `addGapInView(int pos)` Add a single gap at pos within the view coordintates.
`void` `addGapsInSource(int pos, int length)` Add length gaps at pos within the source coordinates.
`void` `addGapsInView(int pos, int length)` Add length gaps at pos within the view coordinates.
`void` `dumpBlocks()` Debugging method
`protected int` `findSourceBlock(int indx)` Finds the index of the block containing the source coordinate indx.
`protected int` `findSourceGap(int indx)` Finds the index of the Block before the gap at indx within the following gap.
`protected int` `findViewBlock(int indx)` Finds the index of the Block containing indx within the view ranges.
`protected int` `findViewGap(int indx)` Finds the index of the Block before the gap at indx within the view range.
`int` `firstNonGap()` Return the index of the first Symbol that is not a Gap character.
`Alphabet` `getAlphabet()` The alphabet that this SymbolList is over.
`int` `lastNonGap()` Return the index of the last Symbol that is not a Gap character.
`int` `length()` The number of symbols in this SymbolList.
`void` `removeGap(int pos)` Remove a single gap at position pos in this GappedSymbolList.
`void` `removeGaps(int pos, int length)` Remove some gaps at position pos in this GappedSymbolList.
`protected void` `renumber(int i, int delta)` Renumber the view indexes from block, adding delta to each offset.
`protected int` `sourceToView(org.biojava.bio.symbol.GappedSymbolList.Block b, int indx)` Coordinate conversion from source to view.
`int` `sourceToView(int indx)` Coordinate conversion from source to view.
`Symbol` `symbolAt(int indx)` Return the symbol at index, counting from 1.
`protected int` `viewToSource(org.biojava.bio.symbol.GappedSymbolList.Block b, int indx)` Coordinate conversion from view to source.
`int` `viewToSource(int indx)` Coordinate conversion from view to source.

Methods inherited from class org.biojava.bio.symbol.AbstractSymbolList
`iterator, seqString, subList, subStr, toList`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### GappedSymbolList

    public GappedSymbolList(SymbolList source)

  Create a new GappedSymbolList that will view source.
  Parameters:
    `source` - the underlying sequence

Method Detail

### findSourceBlock

    protected final int findSourceBlock(int indx)

  Finds the index of the block containing the source coordinate indx.
  Parameters:
    `indx` - the index to find
  Returns:
    the index of the Block containing indx

### findViewBlock

    protected final int findViewBlock(int indx)

  Finds the index of the Block containing indx within the view ranges.

  If indx is not within a view block, then it is the index of a gap. The method will return -1.

  Parameters:
    `indx` - the index to find within a view range.
  Returns:
    the index of the block containing index, or -1 if no block contains it

### findSourceGap

    protected final int findSourceGap(int indx)

  Finds the index of the Block before the gap at indx within the following gap.
  Parameters:
    `indx` - the index to find within a gap
  Returns:
    the index of the block with indx in the gap

### findViewGap

    protected final int findViewGap(int indx)

  Finds the index of the Block before the gap at indx within the view range.

  If indx is in-fact a real symbol, then there will be no Block before it. In this case, the method returns -2. It returns -1 if indx is within the leading gaps and blocks.size()-1 if it is within the trailing gaps.

  Parameters:
    `indx` - the index to find within a view range
  Returns:
    the index of the block with indx in the following gap

### viewToSource

    protected final int viewToSource(org.biojava.bio.symbol.GappedSymbolList.Block b,
                                     int indx)

  Coordinate conversion from view to source.
  Parameters:
    `b` - the block containing indx
    `indx` - the index to project
  Returns:
    the position of indx projected from view to source

### viewToSource

    public final int viewToSource(int indx)
                           throws java.lang.IndexOutOfBoundsException

  Coordinate conversion from view to source.
  Parameters:
    `indx` - the index to project
  Returns:
    the position of indx projected from view to source
  Throws:
    java.lang.IndexOutOfBoundsException - if indx is not a valid view index

### sourceToView

    protected final int sourceToView(org.biojava.bio.symbol.GappedSymbolList.Block b,
                                     int indx)

  Coordinate conversion from source to view.
  Parameters:
    `b` - the block containing indx
    `indx` - the index to project
  Returns:
    the position of indx projected from source to view

### sourceToView

    public final int sourceToView(int indx)
                           throws java.lang.IndexOutOfBoundsException

  Coordinate conversion from source to view.
  Parameters:
    `indx` - the index to project
  Returns:
    the position of indx projected from source to view
  Throws:
    java.lang.IndexOutOfBoundsException - if indx is not a valid source index

### renumber

    protected final void renumber(int i,
                                  int delta)

  Renumber the view indexes from block, adding delta to each offset.

  This adjusts viewStart and viewEnd to be += delta for each block i->blocks.size(), and sets the total length to += delta.

  Parameters:
    `i` - the first

### addGapInView

    public void addGapInView(int pos)
                      throws java.lang.IndexOutOfBoundsException

  Add a single gap at pos within the view coordintates.

  this.symbolAt(pos) will then return gap. Adding a gap at 1 will prepend gaps. Adding a gap at (length+1) will append a gap.

  Parameters:
    `pos` - the position to add a gap before
  Throws:
    java.lang.IndexOutOfBoundsException - if pos is not within 1->length+1

### addGapsInView

    public void addGapsInView(int pos,
                              int length)
                       throws java.lang.IndexOutOfBoundsException

  Add length gaps at pos within the view coordinates.

  this.symbolAt(i) will then return gap for i = (pos .. pos+count-1). Adding gaps at 1 will prepend gaps. Adding gaps at (length+1) will append gaps.

  Parameters:
    `pos` - the position to add a gap before
    `length` - the number of gaps to insert
  Throws:
    java.lang.IndexOutOfBoundsException - if pos is not within 1->length+1

### addGapInSource

    public void addGapInSource(int pos)
                        throws java.lang.IndexOutOfBoundsException

  Add a gap at pos within the source coordinates.
  Parameters:
    `pos` - where to add the gap
  Throws:
    java.lang.IndexOutOfBoundsException - if pos is not within 1->source.length()

### addGapsInSource

    public void addGapsInSource(int pos,
                                int length)

  Add length gaps at pos within the source coordinates.
  Parameters:
    `pos` - where to add the gap
    `length` - how many gaps to add
  Throws:
    java.lang.IndexOutOfBoundsException - if pos is not within 1->source.length()

### removeGap

    public void removeGap(int pos)
                   throws java.lang.IndexOutOfBoundsException,
                          IllegalSymbolException

  Remove a single gap at position pos in this GappedSymbolList.
  Parameters:
    `pos` - where to remove the gap
  Throws:
    java.lang.IndexOutOfBoundsException - if pos is not within 1..length
    IllegalSymbolException - if the symbol at pos is not a gap

### removeGaps

    public void removeGaps(int pos,
                           int length)
                    throws java.lang.IndexOutOfBoundsException,
                           IllegalSymbolException

  Remove some gaps at position pos in this GappedSymbolList.
  Parameters:
    `pos` - where to remove the gaps
    `length` - how many to remove
  Throws:
    java.lang.IndexOutOfBoundsException - if pos is not within 1..length() or if some of the Symbols within pos->(pos+length-1) are not gap Symbols
    IllegalSymbolException - if the symbol at pos is not a gap

### getAlphabet

    public Alphabet getAlphabet()

  Description copied from interface: SymbolList
  The alphabet that this SymbolList is over.

  Every symbol within this SymbolList is a member of this alphabet. `alphabet.contains(symbol) == true` for each symbol that is within this sequence.

  Overrides:
    getAlphabet in class AbstractSymbolList
  Tags copied from interface: SymbolList
  Returns:
    the alphabet

### length

    public int length()

  Description copied from interface: SymbolList
  The number of symbols in this SymbolList.
  Overrides:
    length in class AbstractSymbolList
  Tags copied from interface: SymbolList
  Returns:
    the length

### symbolAt

    public Symbol symbolAt(int indx)
                    throws java.lang.IndexOutOfBoundsException

  Description copied from interface: SymbolList
  Return the symbol at index, counting from 1.
  Overrides:
    symbolAt in class AbstractSymbolList
  Tags copied from interface: SymbolList
  Parameters:
    `index` - the ofset into this SymbolList
  Returns:
    the Symbol at that index
  Throws:
    java.lang.IndexOutOfBoundsException - if index is less than 1, or greater than the length of the symbol list

### firstNonGap

    public int firstNonGap()

  Return the index of the first Symbol that is not a Gap character.

  All symbols before firstNonGap are leading gaps. firstNonGap is effectively the index in the view of symbol 1 in the original sequence.

  Returns:
    the index of the first character not to be a gap

### lastNonGap

    public int lastNonGap()

  Return the index of the last Symbol that is not a Gap character.

  All symbols after lastNonGap untill length are trailing gaps. lastNonGap is effectively the index in the view of symbol length in the original sequence.

  Returns:
    the index of the last character not to be a gap

### dumpBlocks

    public void dumpBlocks()

  Debugging method