/////////////////////////////////////////////////////////////////////////////
// File:            gnSequence.h
// Purpose:         Sequence class
// Description:     Provides a high level sequence interface to all types of
//					sequence data.
// Changes:        
// Version:         libGenome 0.1.0 
// Author:          Aaron Darling 
// Last Edited:     April 15, 2001, 10:34:50pm 
// Modified by:     
// Copyright:       (c) Aaron Darling 
// Licenses:        Proprietary 
/////////////////////////////////////////////////////////////////////////////
#ifndef _gnSequence_h_
#define _gnSequence_h_

#include "gn/gnDefs.h"

#include <string>
#include <iostream>
#include <list>
#include "gn/gnBaseSource.h"
#include "gn/gnGenomeSpec.h"
#include "gn/gnSourceSpec.h"
#include "gn/gnStringSpec.h"
#include "gn/gnBaseFilter.h"
#include "gn/gnCompare.h"

/**
 * gnSequence is the most commonly used class in libGenome.  It provides a simple
 * and general way to manipulate genetic sequences, regardless of what kind of
 * database, web site, or file they are stored in.  Sequence data can be
 * manipulated like a c++ string by using subseq() and erase().  gnSequence
 * updates annotated sequences with each change, breaking features if necessary.
 */
class GNDLLEXPORT gnSequence : public gnClone
{
public:
	/**
	 * Empty Constructor, creates an empty gnSequence.
	 */
	gnSequence();
	/**
	 * Creates a gnSequence with a single fragment containing the bases in "seq".
	 * @param seq The null terminated character array of base pairs to use.
	 */
	gnSequence( const gnSeqC* seq );
	/**
	 * Creates a gnSequence with a single fragment containing the bases in "str".
	 * @param str The base pairs to use.
	 */
	gnSequence( const string& str );
	/**
	 * Creates a gnSequence with the genome stored in the gnGenomeSpec "gngs".
	 * @param gngs the gnGenomeSpec to get contigs from.
	 */
	gnSequence( const gnGenomeSpec& gngs );
	/**
	 * Creates a gnSequence with the sequence fragment stored in the gnFragmentSpec "gnfs".
	 * @param gnfs the gnFragmentSpec to get contigs from.
	 */
	gnSequence( const gnFragmentSpec& gnfs );
	/**
	 * Creates a gnSequence with the contig stored in the gnContigSpec "gncs".
	 * Usually gncs will be a gnStringSpec or a gnSourceSpec.
	 * @param gncs the gnContigSpec to get contigs from.
	 */
	gnSequence( const gnContigSpec& gncs );
	/**
	 * Creates a gnSequence with a single fragment containing the bases in "bases".
	 * @param bases The base pairs to use
	 * @param length The length of the base pair array.
	 */
	gnSequence( gnSeqC *bases, const gnSeqI length);
	/**
	 * Copies the gnSequence "seq".
	 * @param seq The gnSequence to copy.
	 */
	gnSequence( const gnSequence& seq);
	/**
	 * Destructor, frees the memory used by this sequence.
	 */
	~gnSequence();

	/**
	 * Copies the gnSequence.
	 */
	gnSequence& operator=( const gnSequence& seq);

	gnSequence* Clone() const;

	/**
	 * Returns the number of sequence fragments in this sequence.
	 * @return the number of sequence fragments in this sequence.
	 */
	gnSeqI contigListSize() const;
	/**
	 * Returns the number of sequence fragments in this sequence.
	 * @return the number of sequence fragments in this sequence.
	 */
	gnSeqI contigListLength() const;
	/**
	 * Returns the index of the contig which contains the specified base.
	 * @param baseI A base pair in the contig.
	 * @throws SeqIndexOutOfBounds will be propagated if baseI is invalid
	 * @return The contig index which contains the base.
	 */
	uint32 contigIndexByBase( const gnSeqI baseI) const;
	/**
	 * Returns a gnSequence containing the specified fragment.
	 * @param contigI The index of the fragment to get.
	 * @throws FragmentIndexOutOfBounds will be propagated if contigI is invalid
	 * @return A gnSequence containing only the fragment.
	 */
	gnSequence contig( const uint32 contigI) const;
	/**
	 * Returns a gnSequence containing only the fragment which contains the specified base.
	 * @param baseI A base pair index in the contig
	 * @throws SeqIndexOutOfBounds will be propagated if baseI is invalid
	 * @return A gnSequence containing only the contig.
	 */
	gnSequence contigByBase( const gnSeqI baseI) const;
	/**
	 * Returns the index of the base pair where the specified contig starts in this sequence.
	 * @param contigI The index of the contig.
	 * @throws FragmentIndexOutOfBounds will be propagated if contigI is invalid
	 * @return The starting base pair index.
	 */
	virtual gnSeqI contigStart( const uint32 contigI) const;
	/**
	 * Returns the length in base pairs of the specified contig in this sequence.
	 * @param contigI The index of the contig.
	 * @throws FragmentIndexOutOfBounds will be propagated if contigI is invalid
	 * @return The length of the contig.
	 */
	virtual gnSeqI contigLength( const uint32 contigI) const;
	/**
	 * Returns the index of the contig with the given name.  
	 * If two contigs have the same name, contigIndexByName() will return the first.
	 * @param contigName The name of the contig.
	 * @throws FragmentIndexOutOfBounds will be propagated if contigName is not found
	 * @return The index of the contig.
	 */
	virtual uint32 contigIndexByName( string& contigName) const;
	/**
	 * Returns the name of the specified contig.  
	 * @param contigI The index of the contig.
	 * @throws FragmentIndexOutOfBounds will be propagated if contigI is invalid
	 * @return The name of the contig.
	 */
	virtual string contigName( const uint32 contigI) const;
	/**
	 * Returns a gnSequence containing only the named contig.
	 * If two contigs have the same name, contigByName() will return the first.
	 * @param contigName The name of the contig.
	 * @throws FragmentIndexOutOfBounds will be propagated if contigName is not found
	 * @return A gnSequence containing the contig.
	 */
	virtual gnSequence contigByName( string& contigName) const;
	/**
	 * Merges the bases starting at base index "startI" and ending at "endI" into one contig, splitting existing contigs.
	 * @param startI The starting base pair of the new contig.
	 * @param endI The ending base pair of the new contig.
	 * @throws SeqIndexOutOfBounds exception is propagated if startI or endI are invalid
	 */
	virtual void merge(const gnSeqI startI, const gnSeqI endI);
	/**
	 * Merges the contigs starting at the contig index "startC" and ending at "endC" into one contig.
	 * @param startC The starting contig of the new contig.
	 * @param endC The ending contig of the new contig.
	 * @throws FragmentIndexOutOfBounds exception is propagated if startC or endC are invalid
	 */
	virtual void mergeContigs(const uint32 startC, const uint32 endC);
	/**
	 * Splits the specified contig after splitI
	 * @param splitI The base pair to split after.
	 * @param contigI The index of the contig to split or ALL_CONTIGS by default.
	 */
	virtual void splitContig(const gnSeqI splitI, const uint32 contigI=ALL_CONTIGS);

	virtual void setContigName( const uint32 contigI, const string& contig_name);

	/**
	 * Returns the size of the feature list for the specified contig.
	 * @param contigI The index of the contig to use, or ALL_CONTIGS to add a general header.
	 * @return The feature list size.
	 */
	virtual uint32 getFeatureListLength() const;
	/**
	 * Returns the feature specified by featureI.
	 * @param featureI The index of the feature to return.
	 * @throws FeatureIndexOutOfBounds exception is thrown if featureI does not reference a valid feature
	 * @return A copy of the feature allocated on the heap.  You must delete the feature when finished with it.
	 */
	virtual gnBaseFeature* getFeature(const uint32 featureI) const;
	/**
	 * Creates a list of all features which are contained by coordinates specified.
	 * @param lt The coordinates containing the features to return.
	 * @param feature_vector The vector to store features in.  Each feature pointer points to a copy of the feature on the heap which must be deleted.
	 * @param index_vector A vector of indices which correspond to the features.
	 */
	virtual void getContainedFeatures(const gnLocation& lt, vector<gnBaseFeature*>& feature_vector, vector<uint32>& index_vector) const;
	/**
	 * Creates a list of all features which intersect the coordinates specified.
	 * @param lt The coordinates intersecting the features to return.
	 * @param feature_vector The vector to store features in.  Each feature pointer points to a copy of the feature on the heap which must be deleted.
	 * @param index_vector A vector of indices which correspond to the features.
	 */
	virtual void getIntersectingFeatures(const gnLocation& lt, vector<gnBaseFeature*>& feature_vector, vector<uint32>& index_vector) const;
	/**
	 * Adds the specified feature to the feature list.
	 * @param feature The feature to add.
	 * @return The feature index.
	 */
	virtual uint32 addFeature(gnBaseFeature* feature);
	/**
	 * Removes the specified feature.
	 * @param featureI The index in the feature list of the feature to remove.
	 * @throws FeatureIndexOutOfBounds exception is thrown if featureI does not reference a valid feature
	 */
	virtual void removeFeature(const uint32 featureI);
	/**
	 * Creates a list of features which may have been broken by an edit.
	 * @param lt The coordinates containing the features to return.
	 * @param feature_vector The vector to store features in.  Each feature pointer points to a copy of the feature on the heap which must be deleted.
	 */
	virtual void getBrokenFeatures(const gnLocation& lt, vector<gnBaseFeature*>& feature_vector) const;
	/**
	 * Returns the size of the header list for the specified contig.
	 * @param contigI The index of the contig to use, or ALL_CONTIGS to add a general header.
	 * @throws FragmentIndexOutOfBounds will be propagated if contigI is invalid
	 * @return The header list size.
	 */
	virtual uint32 getHeaderListLength(const uint32 contigI) const;
	/**
	 * Returns the feature specified by featureI.
	 * @param contigI The index of the contig to use, or ALL_CONTIGS to get a general header.
	 * @param headerI The index of the header to return.
	 * @throws FragmentIndexOutOfBounds will be propagated if contigI is invalid
	 * @throws HeaderIndexOutOfBounds will be propagated if headerI is invalid
	 * @return The header, or NULL if headerI is out of range.
	 */
	virtual gnBaseHeader* getHeader(const uint32 contigI, const uint32 headerI) const;
	/**
	 * Adds header information to a specified contig.
	 * @param contigI The index of the contig to use, or ALL_CONTIGS to add a general header.
	 * @param header The header to add.
	 * @param headerI The index in the header list where this header should be inserted.
	 * @throws FragmentIndexOutOfBounds will be propagated if contigI is invalid
	 */
	virtual void addHeader(const uint32 contigI, gnBaseHeader* header, const uint32 headerI);
	/**
	 * Removes header information from a specified contig.
	 * @param contigI The index of the contig to use, or ALL_CONTIGS to remove a general header.
	 * @param headerI The index in the header list of the header to remove.
	 * @throws FragmentIndexOutOfBounds will be propagated if contigI is invalid
	 */
	virtual void removeHeader(const uint32 contigI, const uint32 headerI);
	/**
	 * Reverse complements a specified contig, or the entire sequence if ALL_CONTIGS is specified.
	 * @param revComp True if the area should be reverse complement, false otherwise.
	 * @param contigI The index of the contig to use, or ALL_CONTIGS.
	 * @throws FragmentIndexOutOfBounds will be propagated if contigI is invalid
	 */
	virtual void setReverseComplement( const boolean revComp, const uint32 contigI=ALL_CONTIGS);
	/**
	 * Returns true if a specified contig, or the entire sequence is reverse complement.
	 * @param contigI The index of the contig to use, or ALL_CONTIGS for the whole sequence.
	 * @throws FragmentIndexOutOfBounds will be propagated if contigI is invalid
	 * @return True if the sequence is reverse complement, false otherwise.
	 */
	virtual boolean isReverseComplement( const uint32 contigI=ALL_CONTIGS );
	/**
	 * Returns true if this sequence is circular.
	 * @return True if this sequence is circular.
	 */
	virtual boolean isCircular() const;
	/**
	 * Sets whether this sequence should be read circular.
	 * If circular is set, reads beyond the end of the sequence will pick up
	 * at the beginning.
	 * @param value True for circular, false otherwise.
	 */
	virtual void setCircular( const boolean value );
	
	/**
	 * Converts the global sequence coordinate baseI to a contig local coordinate.
	 * @param contigI This is set to the index of the contig containing baseI
	 * @param baseI This is the global coordinate to be converted to contig local.
	 * @throws SeqIndexOutOfBounds will be thrown if baseI is out of range
	 */
	virtual void globalToLocal(uint32& contigI, gnSeqI& baseI) const;

	/**
	 * Converts the local contig coordinate baseI to a global sequence coordinate.
	 * @param contigI The index of the contig containing baseI.
	 * @param baseI The local contig coordinate to be converted to global.
	 * @throws SeqIndexOutOfBounds will be thrown if baseI is out of range
	 * @throws FragmentIndexOutOfBounds will be propagated if contigI is invalid
	 */
	virtual void localToGlobal(const uint32 contigI, gnSeqI& baseI) const;
	/**
	 * Converts the global sequence coordinate baseI to a local coordinate in the original
	 * data source.  globalToSource() will overwrite any values passed to it!
	 * @param contigI This will be set to contig index in the original source.
	 * @param baseI This will be set to the contig local base index in the original source.
	 * @throws SeqIndexOutOfBounds will be thrown if baseI is out of range
	 */
	virtual void globalToSource(uint32& contigI, gnSeqI& baseI) const;
	/**
	 * Converts the contig local sequence coordinate baseI in contig contigI to a
	 * local coordinate in the original data source.  localToSource() will overwrite any values
	 * passed to it!
	 * @param contigI This will be set to contig index in the original source.
	 * @param baseI This will be set to the contig local base index in the original source.
	 * @throws SeqIndexOutOfBounds will be thrown if baseI is out of range
	 * @throws FragmentIndexOutOfBounds will be propagated if contigI is invalid
	 */
	virtual void localToSource(uint32& contigI, gnSeqI& baseI) const;
	/**
	 * Loads the sequence located at the URL in "sourcename".
	 * Possible URLs currently include only "file:///" URLs.
	 * If no URL prefix is found then LoadSource assumes that "sourcename"
	 * contains the name of a local file.
	 * @param sourcename The location of the data to load.
	 * @return True if successful.  False otherwise.
	 */
	virtual bool LoadSource(const string sourcename);

	/** Assigns a filter which all sequence data must pass through when
	 *  read from the object.
	 *  @param filt The filter to use.
	 */
	virtual void setFilter(const gnBaseFilter* filt);

	/** Assigns a list of filters which all sequence data passes through
	 *  in order when read from the object.  There may not be any NULL
	 *  pointers in the list.
	 *  @param filt_list The ordered list of filters to use.
	 */
	virtual void setFilterList(list<const gnBaseFilter*>& filt_list);

	/** Returns the list of filters currently being used
	 *  @return The list of filters in use.
	 */
	virtual list<const gnBaseFilter*> getFilterList() const;

	/**
	 * Assigns the sequence "seq" to this sequence.
	 * @param seq The seqence to assign to this sequence.
	 */
	virtual void assign(gnSequence& seq);

// Comparison Operators
	/**
	 * Assigns the sequence "seq" to this sequence.
	 */
	void operator=(gnSequence& seq);
	boolean operator==(const gnSequence& seq) const;
	boolean operator!=(const gnSequence& seq) const;
	boolean operator<(const gnSequence& seq) const;
	boolean operator<=(const gnSequence& seq) const;
	boolean operator>(const gnSequence& seq) const;
	boolean operator>=(const gnSequence& seq) const;
	/**
	 * Appends the bases in "seq" to this sequence.
	 */
	gnSequence& operator+=(const gnSequence& seq);
    /**
	 * Compares the bases in "seq" to this sequence.
	 * @param seq The sequence to compare this sequence to.
	 * @return Negative if this sequence is lesser, 0 if the two sequences are
	 * equal, and positive if this sequence is greater.
	 */
	virtual int compare(const gnSequence& seq) const;
	virtual int compare(const string& str) const;
// Append and Insert Operators
	/**
	 * Appends the bases in "seq" to this sequence.
	 * @param seq The sequence to append to this sequence.
	 */
	virtual void append( const gnSequence& seq);
	/**
	 * Inserts the first "len" bases in "bases" into this sequence.at "offset".
	 * insert() will update the locations of all affected features.
	 * @param offset The base pair to insert before.
	 * @param str The character array of bases to insert.
	 * @param length The length of the character array.
	 */
	virtual void insert( const gnSeqI offset, const gnSeqC *bases, const gnSeqI length);
	/**
	 * Inserts the annotated sequence in "seq" into this sequence.at "offset".
	 * insert() will update the locations of all affected features.
	 * @param offset The base pair to insert before.
	 * @param seq The sequence to insert.
	 */
	virtual void insert( const gnSeqI offset, const gnSequence& seq);
	/**
	 * Inserts the annotated sequence in "gnbs" into this sequence.at "offset".
	 * insert() will update the locations of all affected features.
	 * @param offset The base pair to insert before.
	 * @param gnbs The spec to insert.
	 */
	virtual void insert( const gnSeqI offset, const gnGenomeSpec& gnbs);
// Concatenation Operators
	/**
	 * Concatenates this sequence with the annotated sequence in "seq".
	 */
	gnSequence const operator+(const gnSequence& seq) const;
// Substrings and base deletion
	/**
	 * Creates a sequence containing the "length" bases starting at "offset".
	 * @param The base pair index to start the subsequence.
	 * @param The length of the subsequence.
	 * @return The subsequence.
	 */
	gnSequence subseq(const gnSeqI offset, const gnSeqI length) const;
	/**
	 * Deletes the "len" bases starting at "offset".
	 * @param offset The base pair index to start erasing.
	 * @param length The length of the sequence to erase
	 */
	virtual void erase( const gnSeqI offset=0, const gnSeqI length=GNSEQI_END );
// IO operators
	/**
	 * Reads bases from the specified input stream (e.g. cin).
	 */
	friend std::istream& operator>>(std::istream& is, gnSequence& gns);	//read from source.
	/**
	 * Writes the bases in this sequence to the specified output stream (e.g. cout).
	 */
	friend std::ostream& operator<<(std::ostream& os, const gnSequence& gns); //write to source.
// Size functions
	/**
	 * Returns the length of this sequence.
	 * @return the length of this sequence.
	 */
	virtual gnSeqI length() const;
	/**
	 * Returns the length of this sequence.
	 * @return the length of this sequence.
	 */
	virtual gnSeqI size() const;
// Raw Sequence Access
	/**
	 * Returns the "length" bases starting at "offset" as a string.
	 * @param length The length of the sequence to convert
	 * @param offset The base pair index of the sequence to convert
	 * @return The string of base pairs.
	 */
	virtual string ToString( const gnSeqI length=GNSEQI_END, const gnSeqI offset=1 ) const;
	/**
	 * Converts the "length" bases starting at "offset" into the string "str".
	 * @param str The string to store bases in.
	 * @param length The length, in base pairs, to convert.
	 * @param offset The base pair index to start converting.
	 * @return True if successful, false otherwise.
	 */
	virtual boolean ToString( string& str, const gnSeqI length=GNSEQI_END, const gnSeqI offset=1 ) const;
	/**
	 * Converts the "length" bases starting at "offset" into the character array "pSeqC"..
	 * After converting, "length" will be set to the actual length of the sequence.
	 * Be sure to null terminate the character array if you are going to print it!
	 * @param pSeqC The character array of bases to store bases in.
	 * @param length The length, in base pairs, to convert.
	 * @param offset The base pair index to start converting.
	 * @return True if successful, false otherwise.
	 */
	virtual boolean ToArray( gnSeqC* pSeqC, gnSeqI length, const gnSeqI offset=1 ) const;
	/**
	 * Returns the base at "offset".
	 * @param offset The index of the base to get.
	 * @return The base.
	 */
	virtual gnSeqC GetSeqC( const gnSeqI offset ) const; // return gnSeqC illegal char.
	/**
	 * Returns the base at the specified index.
	 * @return The base at the specified index.
	 */
	gnSeqC operator[]( const gnSeqI offset ) const;

	/**
	 * Get the spec (annotated sequence) which this sequence represents.
	 * @return The spec represented by this gnSequence.
	 */
	virtual gnGenomeSpec* GetSpec() const;
	/**
	 * Set the spec (annotated sequence) which this sequence represents.
	 * @param s The new spec.
	 */
	virtual void SetSpec(gnGenomeSpec* s);
	
	/**
	 * Find looks for the search sequence within this gnSequence and returns
	 * the position of the first match if any exists.
	 * @param search The gnSequence to be found
	 * @param offset The position where searching will begin (default is 0)
	 * @return The first position where the search string is found or
	 * GNSEQI_ERROR if the search sequence is not found.
	 */
	virtual gnSeqI find(const gnSequence& search, const gnSeqI offset=0) const;
	
private:
	gnGenomeSpec *spec;
	list<const gnBaseFilter*> filter_list;
	const gnCompare* comparator;
}; // class gnSequence


GNDLLEXPORT
std::istream& operator>>(std::istream& is, gnSequence& gns);	//read from source.
GNDLLEXPORT
std::ostream& operator<<(std::ostream& os, const gnSequence& gns); //write to source.

// Assignment Operators
inline
void gnSequence::operator=(gnSequence& seq){
	spec = seq.spec->Clone();
}
inline
void gnSequence::assign(gnSequence& seq){
	spec = seq.spec->Clone();
}
inline
boolean gnSequence::operator==(const gnSequence& seq) const{
	return (compare(seq)==0);
}
inline
boolean gnSequence::operator!=(const gnSequence& seq) const{
	return (compare(seq)!=0);
}
inline
boolean gnSequence::operator<(const gnSequence& seq) const{
	return (compare(seq)<0);
}
inline
boolean gnSequence::operator<=(const gnSequence& seq) const{
	return (compare(seq)<=0);
}
inline
boolean gnSequence::operator>(const gnSequence& seq) const{
	return (compare(seq)>0);
}
inline
boolean gnSequence::operator>=(const gnSequence& seq) const{
	return (compare(seq)>=0);
}
// Append and Insert Operators
inline
gnSequence& gnSequence::operator+=(const gnSequence& seq){
	insert(GNSEQI_END, *seq.spec);
	return *this;
}
inline
void gnSequence::append( const gnSequence& seq){
	insert(GNSEQI_END, *seq.spec);
}
//Feature functions
inline
uint32 gnSequence::getFeatureListLength() const{
	return spec->GetFeatureListLength();
}
inline
gnBaseFeature* gnSequence::getFeature(const uint32 featureI) const{
	return spec->GetFeature(featureI);
}
inline
uint32 gnSequence::addFeature(gnBaseFeature* feature){
	return spec->AddFeature(feature);
}
inline
void gnSequence::removeFeature(const uint32 featureI){
	spec->RemoveFeature(featureI);
}
inline
void gnSequence::getContainedFeatures(const gnLocation& lt, vector<gnBaseFeature*>& feature_vector, vector<uint32>& index_vector) const{
	spec->GetContainedFeatures(lt, feature_vector, index_vector);
}
inline
void gnSequence::getIntersectingFeatures(const gnLocation& lt, vector<gnBaseFeature*>& feature_vector, vector<uint32>& index_vector) const{
	spec->GetIntersectingFeatures(lt, feature_vector, index_vector);
}
inline
void gnSequence::getBrokenFeatures(const gnLocation& lt, vector<gnBaseFeature*>& feature_vector) const{
	spec->GetBrokenFeatures(lt, feature_vector);
}

inline
boolean gnSequence::isCircular() const{
	return spec->IsCircular();
}

inline
void gnSequence::setCircular( const boolean value ){
	spec->SetCircular(value);
}
inline
void gnSequence::insert( const gnSeqI offset, const gnSequence& seq){
	insert(offset, *seq.spec);
}

// Size functions
inline
gnSeqI gnSequence::length() const{
	return spec->GetLength();
}
inline
gnSeqI gnSequence::size() const{
	return spec->GetLength();
}
inline
gnGenomeSpec* gnSequence::GetSpec() const{
	return spec;
}
inline
void gnSequence::SetSpec(gnGenomeSpec* s){
	if(spec != NULL)
		delete spec;
	spec = s;
}

inline
void gnSequence::setFilter(const gnBaseFilter* filt){
	filter_list.clear();
	if(filt != NULL)
		filter_list.push_back(filt);
}
inline
void gnSequence::setFilterList(list<const gnBaseFilter*>& filt_list){
	filter_list = filt_list;
}
inline
list<const gnBaseFilter*> gnSequence::getFilterList() const{
	return filter_list;
}


#endif
	// _gnSequence_h_
