public abstract class SequenceCharSequence extends Object implements CharSequence, XMLSerializable, Comparable<SequenceCharSequence>, XMLSerializable.OldVersionCompatible
A CharSequence that knows the length of its terminal gaps (sequences of '-') and
allows for efficient insertions and
deletions of subsequences.
This class is a wrapper around another CharSequence which must be immutable. As long as the wrapped CharSequence honors this contract, instances of this class are also immutable and therefore thread safe.
Traditionally we have used Strings to represent biological sequences in Geneious, however it is preferrable for methods to not require Strings but just CharSequences to be passed in, mostly because some aspects of CharSequences can be calculated on the fly or (e.g. when a CharSequence contains a long repetition of the same character) be stored much more memory efficient than a String. Also, other than repetitive characters, a CharSequence implementation can also store any additional metainformation about a sequence.
This class (SequenceCharSequence) makes use of this advantage. It is an immutable wrapper around another CharSequence (which must also be immutable, i.e. not change its length or sequence of characters, particularly it may not acquire or lose any terminal gaps). Failure of the wrapped CharSequence to comply with this contract may result in arbitrary nondeterministic behaviour or RuntimeExceptions, but it is not guaranteed that such exceptions will be thrown.
You can obtain a SequenceCharSequence wrapper around any immutable CharSequence via:
valueOf(CharSequence); to prepend terminal gaps to an existing sequence
in constant time, use withTerminalGaps(int, CharSequence, int).
Of note among the methods in this class that run in constant time are:
getLeadingGapsLength()getTrailingGapsLength()isAllGaps()subSequence(int, int) (not always in constant time)getInternalCharSequence() (returns the sequence without terminal gaps)
When working with SequenceCharSequences, it is advisable to use the methods in
SequenceUtilities
and CharSequenceUtilities
wherever possible, rather than writing your own code. All of those methods
treat SequenceCharSequences special to run more efficiently.
XMLSerializable.OldVersionCompatible, XMLSerializable.VersionSupportType| Modifier and Type | Field and Description |
|---|---|
static SequenceCharSequence |
EMPTY
An empty (0 length) immutable SequenceCharSequence
|
ROOT_ELEMENT_NAME| Modifier and Type | Method and Description |
|---|---|
abstract char |
charAt(int index)
Returns the
char value at the specified index. |
char |
charAtIgnoringEndGaps(int index)
Gets the character at the given index, ignoring end gaps.
|
int |
compareTo(SequenceCharSequence that)
Lexicographically compares this SequenceCharSequence to another, taking into account case.
|
abstract boolean |
contains(char c)
Checks whether this CharSequence contains the specified character.
|
MaybeBoolean |
containsInvalidResidues(SequenceType sequenceType,
boolean allowGaps)
performs a quick test to see if this sequence contains possilby contains invalid residues for its sequence type.
|
abstract int |
count(char c)
Counts the number of occurences of c in this CharSequence
|
int |
countGaps(int startIndex,
int endIndexExclusive)
Counts the number of gaps in this sequence between the 2 given positions.
|
SequenceCharSequence |
delete(int deletionBegin,
int deletionEnd)
Returns a copy of this SequenceCharSequence where the characters at positions deletionBegin inclusive
to deletionEnd exclusive have been removed.
|
boolean |
equals(Object obj)
Checks whether obj is a SequenceCharSequence representing the same sequence of characters
as this one.
|
boolean |
equalsIgnoreCase(SequenceCharSequence that)
Checks whether this SequenceCharSequence contains the same sequence of
characters as the specified SequenceCharSequence, ignoring case.
|
static SequenceCharSequence |
fromXml(org.jdom.Element element)
Constructs a SequenceCharSequence from the specified element to which it
was serialized via
toXML(). |
void |
fromXML(org.jdom.Element element)
Unsupported operation.
|
abstract CharSequence |
getInternalCharSequence()
Returns the CharSequence wrapped by this SequenceCharSequence, representing the
sequence without the terminal gaps.
|
int |
getInternalSequenceLength() |
abstract int |
getLeadingGapsLength()
The number of leading gaps in this SequenceCharSequence, i.e.
|
abstract int |
getTrailingGapsLength()
The number of trailing gaps in this SequenceCharSequence.
|
abstract int |
getTrailingGapsStartIndex()
Get the index in the sequence at which the trailing gaps (if any) start.
|
int |
getUngappedLength()
returns the length of this sequence, excluding any gaps (both internal and end gaps)
|
Geneious.MajorVersion |
getVersionSupport(XMLSerializable.VersionSupportType versionType)
Implements
XMLSerializable.OldVersionCompatible#getVersionSupport(com.biomatters.geneious.publicapi.documents.XMLSerializable.VersionSupportType)
but note that SequenceCharSequence is guaranteed to be able to always serialize to Geneious.MajorVersion#Version6_0 |
int |
hashCode()
Calculates a hashCode that is based on this CharSequence's sequence of characters.
|
int |
indexOf(CharSequence subSequence)
Get the index of the first character of the first occurrence of the specified sub sequence in this sequence
|
int |
indexOf(CharSequence subSequence,
int fromIndex)
Get the index of the first character of the first occurrence of the specified sub sequence in this sequence, starting at the specified index
|
SequenceCharSequence |
insert(int index,
CharSequence charSequence)
Creates a copy of this SequenceCharSequence with the specified CharSequence inserted
at the specified index.
|
boolean |
isAllGaps()
Returns true if this seqeuence consists entirely of gap ('-') characters.
|
boolean |
isEndGap(int index)
Returns true if the given endex is an end gap (i.e.
|
boolean |
isGap(int index)
Returns true if the given endex is a gap.
|
static SequenceCharSequence |
readObject(DataInput dataInput)
Reconstructs this sequence from data previously created using
writeObject(java.io.DataOutput, jebl.util.ProgressListener) |
static SequenceCharSequence |
readObject(GeneiousObjectInputStream inputStream)
Reconstructs this sequence from data previously created using
writeObject(GeneiousObjectOutputStream , jebl.util.ProgressListener) |
SequenceCharSequence |
subSequence(int start,
int end)
Constructs a subsequence of this sequence.
|
String |
toString() |
org.jdom.Element |
toXML()
Serializes this SequenceCharSequence to XML into an element named
XMLSerializable.ROOT_ELEMENT_NAME. |
org.jdom.Element |
toXML(boolean allowFileData)
Serializes this SequenceCharSequence to XML into an element named
XMLSerializable.ROOT_ELEMENT_NAME. |
org.jdom.Element |
toXML(Geneious.MajorVersion majorVersion,
ProgressListener progressListener)
Serializes this class to XML format, potentially to a format readable by an earlier version of Geneious.
|
org.jdom.Element |
toXML(Geneious.MajorVersion version,
ProgressListener progressListener,
boolean allowFileData)
Serializes this SequenceCharSequence to XML into an element named
XMLSerializable.ROOT_ELEMENT_NAME. |
static SequenceCharSequence |
valueOf(CharSequence charSequence)
A SequenceCharSequence representing the same sequence of characters as charSequence;
It is guaranteed that if charSequence instanceof SequenceCharSequence, charSequence
is returned.
|
static SequenceCharSequence |
withOnlyGaps(int numberOfGaps)
Gets a char sequence that consists of only gaps.
|
static SequenceCharSequence |
withTerminalGaps(int gapPrefixLength,
CharSequence charSequence,
int gapSuffixLength)
Create a new SequenceCharSequence from a CharSequence with the specified terminal gap lengths.
|
void |
writeObject(DataOutput dataOutput,
ProgressListener progressListener)
Writes this sequence to a DataOutput.
|
void |
writeObject(Geneious.MajorVersion version,
DataOutput dataOutput,
ProgressListener progressListener)
Writes this sequence to a DataOutput.
|
void |
writeObject(GeneiousObjectOutputStream outputStream,
ProgressListener progressListener)
Writes this sequence to an ObjectOutputStream as specified by
Serializable. |
clone, finalize, getClass, notify, notifyAll, wait, wait, waitlengthpublic static final SequenceCharSequence EMPTY
public static SequenceCharSequence withTerminalGaps(int gapPrefixLength, CharSequence charSequence, int gapSuffixLength)
charSequence and the characters retured from charSequence must not change after calling this method.
It is guaranteed that the returned SequenceCharSequence's internal charSequence is either charSequence,
or a subSequence() of charSequence, or (if charSequence is already a SequenceCharSequence) its internal char sequence.gapPrefixLength - the length of the leading gaps in addition to any leading gaps already present in charSequencecharSequence - CharSequence to wrap in a SequenceCharSequence. The length of charSequence and the characters retured from charSequence must not change after calling this method.gapSuffixLength - the length of the trailing gaps in addition to any trailing gaps already present in charSequencepublic static SequenceCharSequence withOnlyGaps(int numberOfGaps)
numberOfGaps - the number of gapspublic static SequenceCharSequence valueOf(CharSequence charSequence)
charSequence and the characters retured from charSequence must not change after calling this method.charSequence - CharSequence to wrap in a SequenceCharSequence. The length of charSequence and the characters retured from charSequence must not change after calling this method.public abstract boolean contains(char c)
c - the character to look forpublic abstract int count(char c)
c - The character to search forpublic static SequenceCharSequence fromXml(org.jdom.Element element) throws XMLSerializationException
toXML().element - An element constructed by toXML().XMLSerializationExceptionpublic org.jdom.Element toXML(Geneious.MajorVersion majorVersion, ProgressListener progressListener)
XMLSerializable.OldVersionCompatibleXMLSerializable.toXML() for a more
detailed description of what it means to serialize to XML.
All classes that implement this method must also implement XMLSerializable.toXML() and should delegate back to
this method using Geneious.getMajorVersion() and ProgressListener.EMPTY as parameters.toXML in interface XMLSerializable.OldVersionCompatiblemajorVersion - the major version of Geneious to serialize to XML for. For example "6.0" but not "6.0.0". This must be a version
returned greater or equal to a version returned from
getVersionSupport(VersionSupportType.OldestVersionSerializableTo)
and must never be greater than the current version (Geneious.getMajorVersion())progressListener - for reporting progress and cancellingpublic org.jdom.Element toXML(boolean allowFileData)
throws XMLSerializationException
XMLSerializable.ROOT_ELEMENT_NAME.
Deserialization can be done via the fromXml(org.jdom.Element).allowFileData - true to allow the sequence to potentially serialize to a file if it is large enough, using PluginDocument.FILE_DATA_ATTRIBUTE_NAME.XMLSerializationExceptionpublic Geneious.MajorVersion getVersionSupport(XMLSerializable.VersionSupportType versionType)
XMLSerializable.OldVersionCompatible#getVersionSupport(com.biomatters.geneious.publicapi.documents.XMLSerializable.VersionSupportType)
but note that SequenceCharSequence is guaranteed to be able to always serialize to Geneious.MajorVersion#Version6_0getVersionSupport in interface XMLSerializable.OldVersionCompatibleversionType - specifies which version property to returnpublic org.jdom.Element toXML(Geneious.MajorVersion version, ProgressListener progressListener, boolean allowFileData) throws XMLSerializationException
XMLSerializable.ROOT_ELEMENT_NAME.
Deserialization can be done via the fromXml(org.jdom.Element).version - the version number of Geneious that must be able to deserialize thisprogressListener - for reporting progress and cancellingallowFileData - true to allow the sequence to potentially serialize to a file if it is large enough, using PluginDocument.FILE_DATA_ATTRIBUTE_NAME.XMLSerializationExceptionpublic org.jdom.Element toXML()
XMLSerializable.ROOT_ELEMENT_NAME.
Deserialization can be done via fromXml(org.jdom.Element)toXML in interface XMLSerializablepublic void fromXML(org.jdom.Element element)
throws XMLSerializationException
fromXml(org.jdom.Element)
should be used.fromXML in interface XMLSerializableelement - representation from a previous call to XMLSerializable.toXML()XMLSerializationException - always.public abstract int getLeadingGapsLength()
public abstract int getTrailingGapsLength()
charAt(i) won't return '-' is
length() - getTrailingGapsLength(). If this sequence consists only
of gaps, then this method will return 0 (i.e. in a gap-only sequnce, all gaps
are considered leading rather than trailing gaps).public abstract int getTrailingGapsStartIndex()
CharSequence.length().public final boolean isAllGaps()
public abstract char charAt(int index)
char value at the specified index. If index < getLeadingGapsLength()
or index >= CharSequence.length() - getTrailingGapsLength(), returns '-'.charAt in interface CharSequenceindex - Index of character to look upchar value at the specified indexIndexOutOfBoundsException - if index < 0 or index >= CharSequence.length()public char charAtIgnoringEndGaps(int index)
charAt(int).
charAtIgnoringEndGaps(index) is equivalent to charAt(index+getLeadingGapsLength())index - the index of the character to get relative to the leading gaps lengthpublic SequenceCharSequence subSequence(int start, int end)
insert(int, CharSequence) or delete(int, int)) and supports logarithmic
time modifications, then it is guaranteed that the returned subsequence supports logarithmic
time modifications as well.subSequence in interface CharSequencestart - the start index, inclusiveend - the end index, exclusivepublic abstract CharSequence getInternalCharSequence()
public int getInternalSequenceLength()
public final String toString()
toString in interface CharSequencetoString in class Objectpublic final int hashCode()
Object.hashCode(),
it is guaranteed that if a.toString().equals(b.toString()) for two SequenceCharSequences
a, b, then a.hashCode() == b.hashCode(). However, a.hashCode() will generally be different
from a.toString().hashCode().
Note - since this method is generally unused, it is not that efficient or that good at hashing.public boolean equals(Object obj)
public SequenceCharSequence insert(int index, CharSequence charSequence)
insertions
and deletions, and its length will be longer than this sequence's by
charSequence.length().
In order to obey the contract of SequenceCharSequence that it is immutable,
the length of charSequence and the characters retured from charSequence must not change after calling this method.index - The position where to insert csq. All existing characters at or to the right of this position will be moved to the right by charSequence.length().charSequence - A CharSequence to insert at the specified index. The length of charSequence and the characters retured from charSequence must not change after calling this method.public SequenceCharSequence delete(int deletionBegin, int deletionEnd)
insertions
and deletions, and its length will be shorter than this sequence's by
deletionEnd - deletionBegin.deletionBegin - Deletion start index, inclusivedeletionEnd - Deletion end index, exclusivepublic final int compareTo(SequenceCharSequence that)
compareTo in interface Comparable<SequenceCharSequence>that - public final boolean equalsIgnoreCase(SequenceCharSequence that)
that - SequenceCharSequence to be compared for equality (ignoring case) with thispublic int indexOf(CharSequence subSequence)
subSequence - the subsequence to findpublic int indexOf(CharSequence subSequence, int fromIndex)
subSequence - the subsequence to findfromIndex - the index from which to start the search.public boolean isEndGap(int index)
index<getLeadingGapsLength or index>=getTrailingGapsStartIndex())index - Index of character to look uppublic boolean isGap(int index)
index - Index of character to look uppublic void writeObject(GeneiousObjectOutputStream outputStream, ProgressListener progressListener) throws IOException
Serializable.
The object can be reconstructed using readObject(GeneiousObjectInputStream)outputStream - the stream to write to.progressListener - for reporting progress and allowing the write to be canceled.IOException - if the write cannot be completed for any reason (including if the progress listener requests the operation be canceled)public void writeObject(DataOutput dataOutput, ProgressListener progressListener) throws IOException
readObject(java.io.DataInput)dataOutput - the DataOutput to write to.progressListener - for reporting progress and allowing the write to be canceled.IOException - if the write cannot be completed for any reason (including if the progress listener requests the operation be canceled)public void writeObject(Geneious.MajorVersion version, DataOutput dataOutput, ProgressListener progressListener) throws IOException
readObject(java.io.DataInput)version - the version number of Geneious that must be able to deserialize this.dataOutput - the DataOutput to write to.progressListener - for reporting progress and allowing the write to be canceled.IOException - if the write cannot be completed for any reason (including if the progress listener requests the operation be canceled)public static SequenceCharSequence readObject(GeneiousObjectInputStream inputStream) throws XMLSerializationException
writeObject(GeneiousObjectOutputStream , jebl.util.ProgressListener)inputStream - the input stream to read this sequence fromXMLSerializationException - if there is any sort of problem reading from or reconstructing this instance.public static SequenceCharSequence readObject(DataInput dataInput) throws XMLSerializationException
writeObject(java.io.DataOutput, jebl.util.ProgressListener)dataInput - the DataInput to read this sequence fromXMLSerializationException - if there is any sort of problem reading from or reconstructing this instance.public int countGaps(int startIndex,
int endIndexExclusive)
startIndex - the 0-based start index to count from (inclusive)endIndexExclusive - the 0-based end index to stop counting at (exclusive)public int getUngappedLength()
public MaybeBoolean containsInvalidResidues(SequenceType sequenceType, boolean allowGaps)
SequenceUtilities.containsInvalidResidues(CharSequence, com.biomatters.geneious.publicapi.documents.sequence.SequenceDocument.Alphabet, boolean, boolean)sequenceType - the type of sequence it must beallowGaps - true if gaps are allowed in the sequence