//
//  BCSequence.h
//  BioCocoa
//
//  Created by Koen van der Drift on Sun Aug 15 2004.
//  Copyright (c) 2004 The BioCocoa Project. All rights reserved.
//

#import <Foundation/Foundation.h>
#import "BCSymbol.h"


/*!
    @enum       BCSequenceType
    @abstract   A list of sequence types, for readability
    @constant   BCOtherSequence     something we haven't thought of yet
    @constant   BCDNASequence       DNA
    @constant   BCRNASequence       RNA
    @constant   BCProteinSequence   Protein
*/
typedef enum BCSequenceType {
    BCOtherSequence = 0,
    BCDNASequence = 1,
    BCRNASequence = 2,
    BCProteinSequence = 3
} BCSequenceType;

/*!
@enum       BCMassType
 @abstract   A list of mass types, for calculating molecular masses
 @constant   BCMonoisotopic 
 @constant   BCAverage
 */
typedef enum BCMassType {
    BCMonoisotopic = 1,
    BCAverage = 2
} BCMassType;



/*!
    @class      BCSequence
    @abstract   Superclass of all individual sequences (DNA, protein, etc.)
    @discussion This class should not be instantiated, but acts to provide some common methods
    * and variables that are used by all subclasses.
*/

@interface BCSequence : NSObject <NSCopying>
{
	BCSequenceType  sequenceType;
    NSMutableArray  *sequenceArray;			// array of BCSymbol objects to represent the sequence
    NSCountedSet    *sequenceCountedSet;
    NSRange         range;			// 0-based location 
    int             startPosition, endPosition;	// 1-based location of subsequence in the whole sequence
}

////////////////////////////////////////////////////////////////////////////
//  OBJECT METHODS START HERE
//
#pragma mark â 
#pragma mark âINITIALIZATION METHODS
//
//  INITIALIZATION
////////////////////////////////////////////////////////////////////////////


/*!
    @method     - (id)initWithString:(NSString*)aString
    @abstract   initializes a BCSequence object by passing it an NSString.
    @discussion This method does nothing else, it only sets the sequence string. 
    * It's the subclass responsibility to setup all other variables
*/
- (id)initWithString:(NSString*)aString;


/*!
    @method     - (id)initWithString:(NSString*)aString withRange:(NSRange)aRange
    @abstract   initializes a BCSymbol object using a single character.
    @discussion This method does nothing else, it only sets the sequence string
    * and the range of this subsequence within a larger sequence. Note that the range is 0-based.
    * It's the subclass responsibility to setup all other variables
*/
- (id)initWithString:(NSString*)aString withRange:(NSRange)aRange;

/*!
    @method     - (id)initWithArray:(NSArray *)anArray
    @abstract   initializes a BCSequence object by passing it an NSArray.
    @discussion This method scans the passed array for all BCSymbol objects, and creates
    * a new BCSequence using them
*/
- (id)initWithArray:(NSArray *)anArray;


	////////////////////////////////////////////////////////////////////////////
#pragma mark â 
#pragma mark âGETTING/SETTING INTERNAL VARIABLES
	//
	//  OBTAINING AND MODIFYING INTERNAL INFORMATION
	////////////////////////////////////////////////////////////////////////////


	/*!
    @method   - (NSCountedSet *)sequenceCountedSet
	 @abstract   returns an NSCountedSet of BCSymbols
	 */
- (NSCountedSet *)sequenceCountedSet;
	/*!
	@method   - (void) setSequenceCountedSet: (NSCountedSet *)aSet
	 @abstract   sets an NSCountedSet of BCSymbols
	 */

- (void) setSequenceCountedSet: (NSCountedSet *)aSet;

	/*!
    @method   - (void)countSymbols
	 @abstract   calculates the occurence of each BCSymbol
	 @discussion using the unichar symbol, the creates an NSCountedSet containing the number of individual BCSymbols
	 */
- (void)countSymbols;


	/*!
    @method     - (int)startPosition
	 @abstract   returns the start position of this sequence within another sequence.
	 @discussion the startPosition is a 1-based location.
	 */
- (int)startPosition;


	/*!
    @method     - (void)setStartposition:(int)i
	 @abstract   sets the start position of this sequence within another sequence.
	 @discussion the startPosition is a 1-based location.
	 */
- (void)setStartPosition:(int)i;


	/*!
    @method     - (int)endPosition
	 @abstract   returns the end position of this sequence within another sequence.
	 @discussion the endPosition is a 1-based location.
	 */
- (int)endPosition;


	/*!
    @method     - (void)setEndposition:(int)i
	 @abstract   sets the end position of this sequence within another sequence.
	 @discussion the endPosition is a 1-based location.
	 */
- (void)setEndPosition:(int)i;


	/*!
    @method     - (NSRange)range
	 @abstract   returns the range (begin and end) of this sequence within another sequence.
	 @discussion the range is 0-based.
	 */
- (NSRange)range;


	/*!
    @method     - (void)setRange:(NSRange)aRange
	 @abstract   sets the range (begin and end) of this sequence within another sequence.
	 @discussion the range is 0-based.
	 */
- (void)setRange:(NSRange)aRange;

	
////////////////////////////////////////////////////////////////////////////
#pragma mark â 
#pragma mark âOBTAINING SEQUENCE INFORMATION
//
//  INFORMATIONAL METHODS
////////////////////////////////////////////////////////////////////////////


/*!
    @method     - (BCSequenceType) sequenceType
    @abstract   returns the type of sequence
*/
- (BCSequenceType) sequenceType;

/*!
@method     - (void) setSequenceType(BCSequenceType):aType
@abstract   sets the type of sequence
*/
- (void) setSequenceType:(BCSequenceType)aType;

/*!
@method     - (unsigned int) length
@abstract   returns the length of the sequence
*/
- (unsigned int) length;


/*!
    @method     - (id)symbolAtIndex: (int)theIndex
    @abstract   returns the BCSymbol object at index.  Returns nil if index is out of bounds.
*/
- (id)symbolAtIndex: (int)theIndex;


/*!
    @method     - (NSString *)sequenceString
    @abstract   returns the sequence string of the object.
    @discussion returns an NSString containing a one letter-code string of the sequence.
*/
- (NSString*)sequenceString;


/*!
    @method    - (NSArray *)sequenceArray
    @abstract   returns the sequence as an array of BCSymbol objects.
*/
- (NSArray *)sequenceArray;

/*!
@method    - (NSArray *)sequenceArray
@abstract   sets an array of BCSymbol objects as the sequence.
@discussion	private method, do not use.
*/
- (void) setSequenceArray: (NSArray *) anArray;

/*!
    @method    - (NSString *)subSequenceStringInRange:(NSRange)aRange
    @abstract   returns a subsequence in string form
    @discussion returns an NSString conatining a subsequence specified by aRange (0-based).
 *   Returns nil if any part of aRange is out of bounds.
*/
- (NSString *)subSequenceStringInRange:(NSRange)aRange;

/*!
    @method    - (NSArray *)subSequenceArrayInRange:(NSRange)aRange
    @abstract   returns a subsequence in array form
 @discussion returns an Array conatining a subsequence specified by aRange (0-based).
 *   Returns nil if any part of aRange is out of bounds.
*/
- (NSArray *)subSequenceArrayInRange:(NSRange)aRange;

/*!
    @method    - (BCSequence *)subSequenceInRange:(NSRange)aRange
    @abstract   returns a subsequence
    @discussion returns an NSString conatining a subsequence specified by aRange (0-based).
    *   Returns nil if any part of aRange is out of bounds.
*/
- (BCSequence *)subSequenceInRange:(NSRange)aRange ;

/*!
    @method    - (float) molecularWeight
    @abstract   returns the molecular weight of the sequence
    @discussion Using a BCMassCalculator object this returns the molecular mass of the sequence, 
	* using mono isotopic or average masses.
*/
- (float) molecularWeight:(BCMassType)type;


/*!
     @method     - (NSString *) savableRepresentation
     @abstract   Returns the sequenceString for saving.
     @discussion All BCSymbol classes implement this method to provide a standard way of
     *  accessing their data in a format that can be stored in Apple .plist files within
     *  arrays or dictionaries.  Subclasses should provide a method of converting this information
     *  back into the appropriate Symbol object.
*/
- (NSString *) savableRepresentation;


/*!
     @method     - (NSString *) description
     @abstract   Overrides NSObject's description - describes the object in string form
     @discussion In the default implementation, returns the sequence string.  Useful primarily
     *  for debugging.
*/
- (NSString *) description;


////////////////////////////////////////////////////////////////////////////
#pragma mark â 
#pragma mark âMANIPULATING THE SEQUENCE
//
//  SEQUENCE MANIPULATION METHODS
////////////////////////////////////////////////////////////////////////////


/*!
    @method    - (void)setSequence:(NSMutableArray *)anArray
    @abstract   sets the sequence as an array of BCSymbol objects.
*/
- (void)setSequence:(NSMutableArray *)anArray;


/*!
    @method   - (void)removeSymbolsInRange:(NSRange)aRange
    @abstract   deletes a subsequence.
    @discussion deletes the BCSymbols in the subsequence specified by aRange (0-based).
*/
- (void)removeSymbolsInRange:(NSRange)aRange;


/*!
    @method   - (void)removeSymbolAtIndex:(int)index
    @abstract   deletes one symbol.
    @discussion deletes a BCSymbol located at index (0-based).
*/
- (void)removeSymbolAtIndex:(int)index;


/*!
    @method   - (void)insertSymbolsFromSequence:(BCSequence *)seq atIndex:(int)index
    @abstract   inserts a BCSequence into the current sequence, starting at index (0-based)
    @discussion inserts the BCSequence that is in the first argument in the current BCSequence.
*/
- (void)insertSymbolsFromSequence:(BCSequence *)seq atIndex:(int)index;


@end