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 */
026package org.biojava.nbio.core.sequence.template;
027
028import 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 */
039public 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 (1 to n)
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 (1 to n)
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}