001    /*
002     *                    BioJava development code
003     *
004     * This code may be freely distributed and modified under the
005     * terms of the GNU Lesser General Public Licence.  This should
006     * be distributed with the code.  If you do not have a copy,
007     * see:
008     *
009     *      http://www.gnu.org/copyleft/lesser.html
010     *
011     * Copyright for this code is held jointly by the individual
012     * authors.  These should be listed in @author doc comments.
013     *
014     * For more information on the BioJava project and its aims,
015     * or to join the biojava-l mailing list, visit the home page
016     * at:
017     *
018     *      http://www.biojava.org/
019     *
020     * Created on 01-21-2010
021     *
022     * @author Richard Holland
023     *
024     *
025     */
026    package org.biojava3.core.sequence.template;
027    
028    import java.util.List;
029    
030    /**
031     * Main interface for defining a collection of Compounds and accessing them
032     * using biological indexes
033     *
034     * @author Richard Holland
035     * @author Andy Yates
036     * @author Scooter Willis
037     * @param <C> Compound a Sequence holds
038     */
039    public interface Sequence<C extends Compound> extends Iterable<C>, Accessioned {
040    
041        /**
042         * Returns the length of the Sequence
043         */
044        public int getLength();
045    
046        /**
047         * Returns the Compound at the given biological index
048         *
049         * @param position Biological index (1 to n)
050         * @return Compound at the specified position
051         */
052        public C getCompoundAt(int position);
053    
054        /**
055         * Scans through the Sequence looking for the first occurrence of the given
056         * compound
057         *
058         * @param compound Compounds to look for
059         * @return Index of the first position of the compound in the sequence
060         */
061        public int getIndexOf(C compound);
062    
063    /**
064         * Scans through the Sequence looking for the last occurrence of the given
065         * compound
066         *
067         * @param compound Compounds to look for
068         * @return Index of the last position of the compound in the sequence
069         */
070        public int getLastIndexOf(C compound);
071    
072        /**
073         * Returns the String representation of the Sequence
074         */
075        public String getSequenceAsString();
076    
077        /**
078         * Returns the Sequence as a List of compounds
079         */
080        public List<C> getAsList();
081    
082        /**
083         * Returns a portion of the sequence from the different positions. This is
084         * indexed from 1
085         *
086         * @param start Biological index start; must be greater than 0
087         * @param end Biological end; must be less than length + 1
088         * @return A SequenceView of the offset
089         */
090        public SequenceView<C> getSubSequence(Integer start, Integer end);
091    
092        /**
093         * Gets the compound set used to back this Sequence
094         */
095        public CompoundSet<C> getCompoundSet();
096    
097        /**
098         * Returns the number of times we found a compound in the Sequence
099         *
100         * @param compounds Vargs of the compounds to count
101         * @return Number of times a compound was found
102         */
103        public int countCompounds(C... compounds);
104    
105        /**
106         * Does the <em>right thing</em> to get the inverse of the current
107         * Sequence. This means either reversing the Sequence and optionally
108         * complementing the Sequence.
109         */
110        public SequenceView<C> getInverse();
111    }