## org.biojava.bio.symbol
Interface Alphabet

All Superinterfaces:
  Annotatable, Changeable

All Known Subinterfaces:
  FiniteAlphabet

All Known Implementing Classes:
  AbstractAlphabet, DoubleAlphabet, DoubleAlphabet.SubDoubleAlphabet, IntegerAlphabet, IntegerAlphabet.SubIntegerAlphabet, SimpleAlphabet, SingletonAlphabet, SoftMaskedAlphabet

    public interface Alphabet

extends Annotatable

The set of AtomicSymbols which can be concatenated together to make a SymbolList.

A non-atomic symbol is considered to be contained within this alphabet if all of the atomic symbols that it could match are members of this alphabet.

Author:
  Matthew Pocock, Thomas Down

Nested Class Summary

Nested classes/interfaces inherited from interface org.biojava.bio.Annotatable
`Annotatable.AnnotationForwarder`

Field Summary
`static FiniteAlphabet` `EMPTY_ALPHABET` A really useful static alphabet that is always empty.
`static ChangeType` `PARSERS` This signals that the available parsers have changed.
`static ChangeType` `SYMBOLS` This ChangeType indicates that some symbols have been added or removed from the alphabet.

Fields inherited from interface org.biojava.bio.Annotatable
`ANNOTATION`

Method Summary
`boolean` `contains(Symbol s)` Returns whether or not this Alphabet contains the symbol.
`List` `getAlphabets()` Return an ordered List of the alphabets which make up a compound alphabet.
`Symbol` `getAmbiguity(Set syms)` Get a symbol that represents the set of symbols in syms.
`Symbol` `getGapSymbol()` Get the 'gap' ambiguity symbol that is most appropriate for this alphabet.
`String` `getName()` Get the name of the alphabet.
`Symbol` `getSymbol(List rl)` Get a symbol from the Alphabet which corresponds to the specified ordered list of symbols.
`SymbolTokenization` `getTokenization(String name)` Get a SymbolTokenization by name.
`void` `validate(Symbol s)` Throws a precanned IllegalSymbolException if the symbol is not contained within this Alphabet.

Methods inherited from interface org.biojava.bio.Annotatable
`getAnnotation`

Methods inherited from interface org.biojava.utils.Changeable
`addChangeListener, addChangeListener, isUnchanging, removeChangeListener, removeChangeListener`

Field Detail

### SYMBOLS

    static final ChangeType SYMBOLS

  This ChangeType indicates that some symbols have been added or removed from the alphabet. The current and previous fields should indicate what symbols were there originally, and what they have been replaced with.

  If the alphabet wishes to propagate that the symbol has changed state, then previous and current should be null, but the chainedEvent property should rever to the ChangeEvent on the unerlying Symbol.

### PARSERS

    static final ChangeType PARSERS

  This signals that the available parsers have changed. If a parser is added, it will appear in getChanged(). If it is removed, it will appear in getPrevious().

### EMPTY_ALPHABET

    static final FiniteAlphabet EMPTY_ALPHABET

  A really useful static alphabet that is always empty.

Method Detail

### getName

    String getName()

  Get the name of the alphabet.

  Returns:
    the name as a string.

### getAlphabets

    List getAlphabets()

  Return an ordered List of the alphabets which make up a compound alphabet. For simple alphabets, this will return a singleton list of itself. The returned list should be immutable.

  Returns:
    a List of alphabets

### getSymbol

    Symbol getSymbol(List rl)
                     throws IllegalSymbolException

  Get a symbol from the Alphabet which corresponds to the specified ordered list of symbols.

  The symbol at i in the list must be a member of the i'th alphabet in getAlphabets. If all of the symbols in rl are atomic, then the resulting symbol will also be atomic. If any one of them is an ambiguity symbol then the resulting symbol will be the appropriate ambiguity symbol.

  Parameters:
    `rl` - A list of Symbol instances
  Throws:
    `IllegalSymbolException` - if the members of rl are not Symbols over the alphabets returned from `getAlphabets`

### getAmbiguity

    Symbol getAmbiguity(Set syms)
                        throws IllegalSymbolException

  Get a symbol that represents the set of symbols in syms.

  Syms must be a set of Symbol instances each of which is contained within this alphabet. This method is used to retrieve ambiguity symbols.

  Parameters:
    `syms` - the Set of Symbols that will be found in getMatches of the returned symbol
  Returns:
    a Symbol (possibly fly-weighted) for the Set of symbols in syms
  Throws:
    `IllegalSymbolException`

### getGapSymbol

    Symbol getGapSymbol()

  Get the 'gap' ambiguity symbol that is most appropriate for this alphabet.

  In general, this will be a BasisSymbol that represents a list of AlphabetManager.getGapSymbol() the same length as the getAlphabets list.

  Returns:
    the appropriate gap Symbol instance

### contains

    boolean contains(Symbol s)

  Returns whether or not this Alphabet contains the symbol.

  An alphabet contains an ambiguity symbol iff the ambiguity symbol's getMatches() returns an alphabet that is a proper sub-set of this alphabet. That means that every one of the symbols that could match the ambiguity symbol is also a member of this alphabet.

  Parameters:
    `s` - the Symbol to check
  Returns:
    boolean true if the Alphabet contains the symbol and false otherwise

### validate

    void validate(Symbol s)
                  throws IllegalSymbolException

  Throws a precanned IllegalSymbolException if the symbol is not contained within this Alphabet.

  This function is used all over the code to validate symbols as they enter a method. Also, the code is littered with catches for IllegalSymbolException. There is a preferred style of handling this, which should be covererd in the package documentation.

  Parameters:
    `s` - the Symbol to validate
  Throws:
    `IllegalSymbolException` - if r is not contained in this alphabet

### getTokenization

    SymbolTokenization getTokenization(String name)
                                       throws BioException

  Get a SymbolTokenization by name.

  The parser returned is guaranteed to return Symbols and SymbolLists that conform to this alphabet.

  Every alphabet should have a SymbolTokenzation under the name 'token' that uses the symbol token characters to translate a string into a SymbolList. Likewise, there should be a SymbolTokenization under the name 'name' that uses symbol names to identify symbols. Any other names may also be defined, but the behaviour of the returned SymbolTokenization is not defined here.

  A SymbolTokenization under the name 'default' should be defined for all sequences, that determines the behavior when printing out a sequence. Standard behavior is to define the 'token' SymbolTokenization as default if it exists, else to define the 'name' SymbolTokenization as the default, but others are possible.

  Parameters:
    `name` - the name of the parser
  Returns:
    a parser for that name
  Throws:
    `NoSuchElementException` - if the name is unknown
    `BioException` - if for any reason the tokenization could not be built
  Since:
    1.2