SamRecord Class Reference

Class providing an easy to use interface to get/set/operate on the fields in a SAM/BAM record. More...

#include <SamRecord.h>

Collaboration diagram for SamRecord:

[legend]

List of all members.

Public Types
enum	SequenceTranslation { NONE, EQUAL, BASES }
	Enum containing the settings on how to translate the sequence if a reference is available. More...
Public Member Functions
	SamRecord ()
	Default Constructor.
	SamRecord (ErrorHandler::HandlingType errorHandlingType)
	Constructor that sets the error handling type.
	~SamRecord ()
	Destructor.
void	resetRecord ()
	Reset the fields of the record to a default value.
void	resetTagIter ()
	Reset the tag iterator to the beginning of the tags.
bool	isValid (SamFileHeader &header)
	Returns whether or not the record is valid.
SamStatus::Status	setBufferFromFile (IFILE filePtr, SamFileHeader &header)
	Read the BAM record from a file.
void	setReference (GenomeSequence *reference)
	Set the reference to the specified genome sequence object.
void	setSequenceTranslation (SequenceTranslation translation)
	Set the type of sequence translation to use when getting the sequence.
bool	isIntegerType (char vtype) const
	Returns whether or not the specified vtype is an integer type.
bool	isDoubleType (char vtype) const
	Returns whether or not the specified vtype is a double type.
bool	isCharType (char vtype) const
	Returns whether or not the specified vtype is a char type.
bool	isStringType (char vtype) const
	Returns whether or not the specified vtype is a string type.
void	clearTags ()
	Clear the tags in this record.
bool	rmTag (const char *tag, char type)
const SamStatus &	getStatus ()
	Returns the status associated with the last method that sets the status.
String &	getString (const char *tag)
	Get the string value for the specified tag.
int &	getInteger (const char *tag)
	Get the integer value for the specified tag.
double &	getDouble (const char *tag)
	Get the double value for the specified tag.
bool	checkString (const char *tag)
	Check if the specified tag contains a string.
bool	checkInteger (const char *tag)
	Check if the specified tag contains a string.
bool	checkDouble (const char *tag)
	Check if the specified tag contains a string.
bool	checkTag (const char *tag, char type)
	Check if the specified tag contains a value of the specified vtype.
uint32_t	getNumOverlaps (int32_t start, int32_t end)
	Return the number of bases in this read that overlap the passed in region.
Set Alignment Data
Set methods for record fields. All of the "set" methods set the status to indicate success or the failure reason.
bool	setReadName (const char *readName)
	Set QNAME to the passed in name.
bool	setFlag (uint16_t flag)
	Set the bitwise flag to the specified value.
bool	setReferenceName (SamFileHeader &header, const char *referenceName)
	Set the reference name to the specified name, using the header to determine the reference id.
bool	set1BasedPosition (int32_t position)
	Set the leftmost position using the specified 1-based (SAM format) value.
bool	set0BasedPosition (int32_t position)
	Set the leftmost position using the specified 0-based (BAM format) value.
bool	setMapQuality (uint8_t mapQuality)
	Set the mapping quality.
bool	setCigar (const char *cigar)
	Set the CIGAR to the specified SAM formatted cigar string.
bool	setCigar (const Cigar &cigar)
	Set the CIGAR to the specified Cigar object.
bool	setMateReferenceName (SamFileHeader &header, const char *mateReferenceName)
	Set the mate reference sequence name to the specified name, using the header to determine the matee reference id.
bool	set1BasedMatePosition (int32_t matePosition)
	Set the leftmost mate position using the specified 1-based (SAM format) value.
bool	set0BasedMatePosition (int32_t matePosition)
	Set the leftmost mate position using the specified 0-based (BAM format) value.
bool	setInsertSize (int32_t insertSize)
	Sets the inferred insert size.
bool	setSequence (const char *seq)
	Sets the sequence to the specified sequence string.
bool	setQuality (const char *quality)
	Sets the quality to the specified quality string.
SamStatus::Status	setBuffer (const char *fromBuffer, uint32_t fromBufferSize, SamFileHeader &header)
	Sets the SamRecord to contain the information in BAM format found in fromBuffer.
bool	addTag (const char *tag, char vtype, const char *value)
	Add the specified tag to the record.
Get Alignment Data
Get methods for record fields. All of the "get" methods set the status to indicate success or the failure reason.
const void *	getRecordBuffer ()
	Get a const pointer to the buffer that contains the BAM representation of the record.
const void *	getRecordBuffer (SequenceTranslation translation)
	Get a const pointer to the buffer that contains the BAM representation of the record.
SamStatus::Status	writeRecordBuffer (IFILE filePtr)
	Write the record as a BAM into the specified file.
SamStatus::Status	writeRecordBuffer (IFILE filePtr, SequenceTranslation translation)
	Write the record as a BAM into the specified file.
int32_t	getBlockSize ()
	Get the block size of the record.
const char *	getReferenceName ()
	Get the reference sequence name of the record.
int32_t	getReferenceID ()
	Get the reference sequence id of the record.
int32_t	get1BasedPosition ()
	Get the 1-based(SAM) leftmost position of the record.
int32_t	get0BasedPosition ()
	Get the 0-based(BAM) leftmost position of the record.
uint8_t	getReadNameLength ()
	Get the length of the readname (QNAME) including the null.
uint8_t	getMapQuality ()
	Get the mapping quality of the record.
uint16_t	getBin ()
	Get the BAM bin for the record.
uint16_t	getCigarLength ()
	Get the length of the CIGAR in BAM format.
uint16_t	getFlag ()
	Get the flag.
int32_t	getReadLength ()
	Get the length of the read.
const char *	getMateReferenceName ()
	Get the mate reference sequence name of the record.
const char *	getMateReferenceNameOrEqual ()
	Get the mate reference sequence name of the record, returning "=" if it is the same as the reference name, unless they are both "*" in which case "*" is returned.
int32_t	getMateReferenceID ()
	Get the mate reference id of the record.
int32_t	get1BasedMatePosition ()
	Get the 1-based(SAM) leftmost mate position of the record.
int32_t	get0BasedMatePosition ()
	Get the 0-based(BAM) leftmost mate position of the record.
int32_t	getInsertSize ()
	Get the inferred insert size of the read pair.
int32_t	get0BasedAlignmentEnd ()
	Returns the 0-based inclusive rightmost position of the clipped sequence.
int32_t	get1BasedAlignmentEnd ()
	Returns the 1-based inclusive rightmost position of the clipped sequence.
int32_t	getAlignmentLength ()
	Returns the length of the clipped sequence, returning 0 if the cigar is '*'.
int32_t	get0BasedUnclippedStart ()
	Returns the 0-based inclusive left-most position adjusted for clipped bases.
int32_t	get1BasedUnclippedStart ()
	Returns the 1-based inclusive left-most position adjusted for clipped bases.
int32_t	get0BasedUnclippedEnd ()
	Returns the 0-based inclusive right-most position adjusted for clipped bases.
int32_t	get1BasedUnclippedEnd ()
	Returns the 1-based inclusive right-most position adjusted for clipped bases.
const char *	getReadName ()
	Returns the SAM formatted Read Name (QNAME).
const char *	getCigar ()
	Returns the SAM formatted CIGAR string.
const char *	getSequence ()
	Returns the SAM formatted sequence string, translating the base as specified by setSequenceTranslation.
const char *	getSequence (SequenceTranslation translation)
	Returns the SAM formatted sequence string performing the specified sequence translation.
const char *	getQuality ()
	Returns the SAM formatted quality string.
char	getSequence (int index)
	Get the sequence base at the specified index into this sequence 0 to readLength - 1, translating the base as specified by setSequenceTranslation.
char	getSequence (int index, SequenceTranslation translation)
	Get the sequence base at the specified index into this sequence 0 to readLength - performing the specified sequence translation1.
char	getQuality (int index)
	Get the quality character at the specified index into the quality 0 to readLength - 1.
Cigar *	getCigarInfo ()
	Returns a pointer to the Cigar object associated with this record.
uint32_t	getTagLength ()
	Returns the length of the tags in BAM format.
bool	getNextSamTag (char *tag, char &vtype, void **value)
	Get the next tag from the record.
bool	getFields (bamRecordStruct &recStruct, String &readName, String &cigar, String &sequence, String &quality)
	Returns the values of all fields except the tags.
bool	getFields (bamRecordStruct &recStruct, String &readName, String &cigar, String &sequence, String &quality, SequenceTranslation translation)
	Returns the values of all fields except the tags.

---

Detailed Description

Class providing an easy to use interface to get/set/operate on the fields in a SAM/BAM record.

Definition at line 51 of file SamRecord.h.

---

Member Enumeration Documentation

enum SamRecord::SequenceTranslation

Enum containing the settings on how to translate the sequence if a reference is available.

If no reference is available, no translation is done.

Enumerator:

NONE	Leave the sequence as is.
EQUAL	Translate bases that match the reference to '='.
BASES	Translate '=' to the actual base.

Definition at line 57 of file SamRecord.h.

                             { 
        NONE,   ///< Leave the sequence as is.
        EQUAL,  ///< Translate bases that match the reference to '='
        BASES,  ///< Translate '=' to the actual base.
    };

---

Constructor & Destructor Documentation

SamRecord::SamRecord

(

ErrorHandler::HandlingType

errorHandlingType

)

Constructor that sets the error handling type.

Parameters:

errorHandlingType

how to handle errors.

Definition at line 53 of file SamRecord.cpp.

References resetRecord().

    : myStatus(errorHandlingType),
      myRefPtr(NULL),
      mySequenceTranslation(NONE)
{
    int32_t defaultAllocSize = DEFAULT_BLOCK_SIZE + sizeof(int32_t);

    myRecordPtr = 
        (bamRecordStruct *) malloc(defaultAllocSize);

    myCigarTempBuffer = NULL;
    myCigarTempBufferAllocatedSize = 0;

    allocatedSize = defaultAllocSize;

    resetRecord();
}

---

Member Function Documentation

bool SamRecord::addTag	(	const char *	tag,
		char	vtype,
		const char *	value
	)

Add the specified tag to the record.

Internal processing handles switching between SAM/BAM formats when read/written.

Parameters:

	tag	two character tag to be added to the SAM/BAM record.
	vtype	vtype of the specified value - either SAM/BAM vtypes.
	value	value for the specified tag.

Returns:

true if the tag was successfully added, false otherwise.

Definition at line 469 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    bool status = true; // default to successful.
    int key = 0;
    int intVal = 0;
    int index = 0;
    char bamvtype;

    int tagBufferSize = 0;

    // First check to see if the tags need to be synced to the buffer.
    if(myNeedToSetTagsFromBuffer)
    {
        if(!setTagsFromBuffer())
        {
            // Failed to read tags from the buffer, so cannot add new ones.
            return(false);
        }
    }

    switch (vtype)
    {
        case 'A' :
            index = integers.Length();
            bamvtype = vtype;
            integers.Push((const int)*(valuePtr));
            tagBufferSize += 4;
            break;
        case 'i' :
            index = integers.Length();
            intVal = atoi((const char *)valuePtr);
            // Ints come in as int.  But it can be represented in fewer bits.
            // So determine a more specific type that is in line with the
            // types for BAM files.
            // First check to see if it is a negative.
            if(intVal < 0)
            {
                // The int is negative, so it will need to use a signed type.
                // See if it is greater than the min value for a char.
                if(intVal > std::numeric_limits<char>::min())
                {
                    // It can be stored in a signed char.
                    bamvtype = 'c';
                    tagBufferSize += 4;
                }
                else if(intVal > std::numeric_limits<short>::min())
                {
                    // It fits in a signed short.
                    bamvtype = 's';
                    tagBufferSize += 5;
                }
                else
                {
                    // Just store it as a signed int.
                    bamvtype = 'i';
                    tagBufferSize += 7;
                }
            }
            else
            {
                // It is positive, so an unsigned type can be used.
                if(intVal < std::numeric_limits<unsigned char>::max())
                {
                    // It is under the max of an unsigned char.
                    bamvtype = 'C';
                    tagBufferSize += 4;
                }
                else if(intVal < std::numeric_limits<unsigned short>::max())
                {
                    // It is under the max of an unsigned short.
                    bamvtype = 'S';
                    tagBufferSize += 5;
                }
                else
                {
                    // Just store it as an unsigned int.
                    bamvtype = 'I';
                    tagBufferSize += 7;
                }
            }
            integers.Push(intVal);
            break;
        case 'Z' :
            index = strings.Length();
            bamvtype = vtype;
            strings.Push((const char *)valuePtr);
            tagBufferSize += 4 + strings.Last().Length();
            break;
        case 'f' :
            index = doubles.Length();
            bamvtype = vtype;
            doubles.Push(atof((const char *)valuePtr));
            tagBufferSize += 7;
            break;
        default :
            fprintf(stderr,
                    "samFile::ReadSAM() - Unknown custom field of type %c\n",
                    vtype);
            myStatus.setStatus(SamStatus::FAIL_PARSE, 
                               "Unknown custom field in a tag");
            status = false;
    }

    // Only add the tag if it has so far been successfully processed.
    if(status)
    {
        // The buffer tags are now out of sync.
        myNeedToSetTagsInBuffer = true;
        myIsTagsBufferValid = false;
        myIsBufferSynced = false;

        key = MAKEKEY(tag[0], tag[1], bamvtype);
        extras.Add(key, index);
        myTagBufferSize += tagBufferSize;
    }
    return(status);
}

bool SamRecord::checkDouble

(

const char *

tag

)

[inline]

Check if the specified tag contains a string.

Does not set SamStatus.

Parameters:

tag

SAM tag to check contents of.

Returns:

true if the value associated with the tag is a string.

Definition at line 523 of file SamRecord.h.

References checkTag().

{ return checkTag(tag, 'f'); }

bool SamRecord::checkInteger

(

const char *

tag

)

[inline]

Check if the specified tag contains a string.

Does not set SamStatus.

Parameters:

tag

SAM tag to check contents of.

Returns:

true if the value associated with the tag is a string.

Definition at line 517 of file SamRecord.h.

References checkTag().

{ return checkTag(tag, 'i'); }

bool SamRecord::checkString

(

const char *

tag

)

[inline]

Check if the specified tag contains a string.

Does not set SamStatus.

Parameters:

tag

SAM tag to check contents of.

Returns:

true if the value associated with the tag is a string.

Definition at line 511 of file SamRecord.h.

References checkTag().

{ return checkTag(tag, 'Z'); }

bool SamRecord::checkTag	(	const char *	tag,
		char	type
	)

Check if the specified tag contains a value of the specified vtype.

Does not set SamStatus.

Parameters:

	tag	SAM tag to check contents of.
	type	value type to check if the SAM tag matches.

Returns:

true if the value associated with the tag is a string.

Definition at line 1625 of file SamRecord.cpp.

Referenced by checkDouble(), checkInteger(), and checkString().

{
    // Init to success.
    myStatus = SamStatus::SUCCESS;
    // Parse the buffer if necessary.
    if(myNeedToSetTagsFromBuffer)
    {
        if(!setTagsFromBuffer())
        {
            // Failed to read the tags from the buffer, so cannot
            // get tags.
            return("");
        }
    }
    
    int key = MAKEKEY(tag[0], tag[1], type);

    return (extras.Find(key) != LH_NOTFOUND);
}

void SamRecord::clearTags

(

)

Clear the tags in this record.

Does not set SamStatus.

Definition at line 1433 of file SamRecord.cpp.

References resetTagIter().

Referenced by resetRecord().

{
    if(extras.Entries() != 0)
    {
        extras.Clear();
    }
    strings.Clear();
    integers.Clear();
    doubles.Clear();
    myTagBufferSize = 0;
    resetTagIter();
}

int32_t SamRecord::get0BasedAlignmentEnd

(

)

Returns the 0-based inclusive rightmost position of the clipped sequence.

Returns:

0-based inclusive rightmost position

Definition at line 853 of file SamRecord.cpp.

Referenced by get0BasedUnclippedEnd(), get1BasedAlignmentEnd(), and SamFile::readIndexedRecord().

{
    myStatus = SamStatus::SUCCESS;
    if(myAlignmentLength == -1)
    {
        // Alignment end has not been set, so calculate it.
        parseCigar();
    }
    // If alignment length > 0, subtract 1 from it to get the end.
    if(myAlignmentLength == 0)
    {
        // Length is 0, just return the start position.
        return(myRecordPtr->myPosition);
    }
    return(myRecordPtr->myPosition + myAlignmentLength - 1);
}

int32_t SamRecord::get0BasedMatePosition

(

)

Get the 0-based(BAM) leftmost mate position of the record.

Returns:

0-based leftmost position.

Definition at line 838 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    return myRecordPtr->myMatePosition;
}

int32_t SamRecord::get0BasedPosition

(

)

Get the 0-based(BAM) leftmost position of the record.

Returns:

0-based leftmost position.

Definition at line 705 of file SamRecord.cpp.

Referenced by getNumOverlaps(), SamFile::readIndexedRecord(), SamQuerySeqWithRefIter::reset(), SamFilter::softClip(), and SamFile::validateSortOrder().

{
    myStatus = SamStatus::SUCCESS;
    return myRecordPtr->myPosition;
}

int32_t SamRecord::get0BasedUnclippedEnd

(

)

Returns the 0-based inclusive right-most position adjusted for clipped bases.

Returns:

0-based inclusive rightmost position including clips.

Definition at line 912 of file SamRecord.cpp.

References get0BasedAlignmentEnd().

Referenced by get1BasedUnclippedEnd().

{
    // myUnclippedEndOffset will be set by get0BasedAlignmentEnd if the 
    // cigar has not yet been parsed, so no need to check it here.
    return(get0BasedAlignmentEnd() + myUnclippedEndOffset);
}

int32_t SamRecord::get0BasedUnclippedStart

(

)

Returns the 0-based inclusive left-most position adjusted for clipped bases.

Returns:

0-based inclusive leftmost position including clips.

Definition at line 892 of file SamRecord.cpp.

Referenced by get1BasedUnclippedStart().

{
    myStatus = SamStatus::SUCCESS;
    if(myUnclippedStartOffset == -1)
    {
        // Unclipped has not yet been calculated, so parse the cigar to get it
        parseCigar();
    }
    return(myRecordPtr->myPosition - myUnclippedStartOffset);
}

int32_t SamRecord::get1BasedAlignmentEnd

(

)

Returns the 1-based inclusive rightmost position of the clipped sequence.

Returns:

1-based inclusive rightmost position

Definition at line 872 of file SamRecord.cpp.

References get0BasedAlignmentEnd().

Referenced by getBin().

{
    return(get0BasedAlignmentEnd() + 1);
}

int32_t SamRecord::get1BasedMatePosition

(

)

Get the 1-based(SAM) leftmost mate position of the record.

Returns:

1-based leftmost position.

Definition at line 831 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    return (myRecordPtr->myMatePosition + 1);
}

int32_t SamRecord::get1BasedPosition

(

)

Get the 1-based(SAM) leftmost position of the record.

Returns:

1-based leftmost position.

Definition at line 698 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    return (myRecordPtr->myPosition + 1);
}

int32_t SamRecord::get1BasedUnclippedEnd

(

)

Returns the 1-based inclusive right-most position adjusted for clipped bases.

Returns:

1-based inclusive rightmost position including clips.

Definition at line 921 of file SamRecord.cpp.

References get0BasedUnclippedEnd().

{
    return(get0BasedUnclippedEnd() + 1);
}

int32_t SamRecord::get1BasedUnclippedStart

(

)

Returns the 1-based inclusive left-most position adjusted for clipped bases.

Returns:

1-based inclusive leftmost position including clips.

Definition at line 905 of file SamRecord.cpp.

References get0BasedUnclippedStart().

{
    return(get0BasedUnclippedStart() + 1);
}

int32_t SamRecord::getAlignmentLength

(

)

Returns the length of the clipped sequence, returning 0 if the cigar is '*'.

Returns:

length of the clipped sequence.

Definition at line 879 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    if(myAlignmentLength == -1)
    {
        // Alignment end has not been set, so calculate it.
        parseCigar();
    }
    // Return the alignment length.
    return(myAlignmentLength);
}

uint16_t SamRecord::getBin

(

)

Get the BAM bin for the record.

Returns:

BAM bin

Definition at line 733 of file SamRecord.cpp.

References get1BasedAlignmentEnd().

{
    myStatus = SamStatus::SUCCESS;
    if(!myIsBinValid)
    {
        // The bin that is set in the record is not valid, so
        // reset it.
        myRecordPtr->myBin = 
            bam_reg2bin(myRecordPtr->myPosition, get1BasedAlignmentEnd());      
        myIsBinValid = true;
    }
    return(myRecordPtr->myBin);
}

int32_t SamRecord::getBlockSize

(

)

Get the block size of the record.

Returns:

BAM block size of the record.

Definition at line 667 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    // If the buffer isn't synced, sync the buffer to determine the
    // block size.
    if(myIsBufferSynced == false)
    {
        // Since this just returns the block size, the translation of
        // the sequence does not matter, so just use the currently set
        // value.
        fixBuffer(myBufferSequenceTranslation);
    }
    return myRecordPtr->myBlockSize;
}

const char * SamRecord::getCigar

(

)

Returns the SAM formatted CIGAR string.

Returns:

cigar string.

Definition at line 941 of file SamRecord.cpp.

Referenced by getFields(), and SamValidator::isValidCigar().

{
    myStatus = SamStatus::SUCCESS;
    if(myCigar.Length() == 0)
    {
        // 0 Length, means that it is in the buffer, but has not yet
        // been synced to the string, so do the sync.
        parseCigarBinary();
    }
    return myCigar.c_str();
}

Cigar * SamRecord::getCigarInfo

(

)

Returns a pointer to the Cigar object associated with this record.

The object is essentially read-only, only allowing modifications due to lazy evaluations.

Returns:

pointer to the Cigar object.

Definition at line 1212 of file SamRecord.cpp.

Referenced by getSequence(), SamQuerySeqWithRefIter::reset(), and SamFilter::softClip().

{
    // Check to see whether or not the Cigar has already been
    // set - this is determined by checking if alignment length
    // is set since alignment length and the cigar are set
    // at the same time.
    if(myAlignmentLength == -1)
    {
        // Not been set, so calculate it.
        parseCigar();
    }
    return(&myCigarRoller);
}

uint16_t SamRecord::getCigarLength

(

)

Get the length of the CIGAR in BAM format.

Returns:

length of BAM formatted cigar.

Definition at line 748 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    // If the cigar buffer is valid
    // then get the length from there.
    if(myIsCigarBufferValid)
    {
        return myRecordPtr->myCigarLength;      
    }

    if(myCigarTempBufferLength == -1)
    {
        // The cigar buffer is not valid and the cigar temp buffer is not set,
        // so parse the string.
        parseCigarString();
    }
   
    // The temp buffer is now set, so return the size.
    return(myCigarTempBufferLength);
}

double & SamRecord::getDouble

(

const char *

tag

)

Get the double value for the specified tag.

Does not set SamStatus.

Definition at line 1594 of file SamRecord.cpp.

{
    // Init to success.
    myStatus = SamStatus::SUCCESS;
    // Parse the buffer if necessary.
    if(myNeedToSetTagsFromBuffer)
    {
        if(!setTagsFromBuffer())
        {
            // Failed to read the tags from the buffer, so cannot
            // get tags.
            // TODO - what do we want to do on failure?
        }
    }
    
    int key = MAKEKEY(tag[0], tag[1], 'f');
    int offset = extras.Find(key);

    int value;
    if (offset < 0)
    {
        // TODO - what do we want to do on failure?
        return NOT_FOUND_TAG_DOUBLE;
    }
    else
        value = extras[offset];

    return doubles[value];
}

bool SamRecord::getFields	(	bamRecordStruct &	recStruct,
		String &	readName,
		String &	cigar,
		String &	sequence,
		String &	quality,
		SequenceTranslation	translation
	)

Returns the values of all fields except the tags.

Parameters:

	recStruct	structure containing the contents of all non-variable length fields.
	readName	read name from the record (return param)
	cigar	cigar string from the record (return param)
	sequence	sequence string from the record (return param)
	quality	quality string from the record (return param)
	translation	type of sequence translation to use.

Returns:

true if all fields were successfully set, false otherwise.

Definition at line 1344 of file SamRecord.cpp.

References getCigar(), getQuality(), getReadName(), and getSequence().

{
    myStatus = SamStatus::SUCCESS;
    if(myIsBufferSynced == false)
    {
        if(!fixBuffer(translation))
        {
            // failed to set the buffer, return false.
            return(false);
        }
    }
    memcpy(&recStruct, myRecordPtr, sizeof(bamRecordStruct));

    readName = getReadName();
    // Check the status.
    if(myStatus != SamStatus::SUCCESS)
    {
        // Failed to set the fields, return false.
        return(false);
    }
    cigar = getCigar();
    // Check the status.
    if(myStatus != SamStatus::SUCCESS)
    {
        // Failed to set the fields, return false.
        return(false);
    }
    sequence = getSequence(translation);
    // Check the status.
    if(myStatus != SamStatus::SUCCESS)
    {
        // Failed to set the fields, return false.
        return(false);
    }
    quality = getQuality();
    // Check the status.
    if(myStatus != SamStatus::SUCCESS)
    {
        // Failed to set the fields, return false.
        return(false);
    }
    return(true);
}

bool SamRecord::getFields	(	bamRecordStruct &	recStruct,
		String &	readName,
		String &	cigar,
		String &	sequence,
		String &	quality
	)

Returns the values of all fields except the tags.

Parameters:

	recStruct	structure containing the contents of all non-variable length fields.
	readName	read name from the record (return param)
	cigar	cigar string from the record (return param)
	sequence	sequence string from the record (return param)
	quality	quality string from the record (return param)

Returns:

true if all fields were successfully set, false otherwise.

Definition at line 1335 of file SamRecord.cpp.

{
    return(getFields(recStruct, readName, cigar, sequence, quality,
                     mySequenceTranslation));
}

uint16_t SamRecord::getFlag

(

)

Get the flag.

Returns:

flag.

Definition at line 770 of file SamRecord.cpp.

Referenced by SamQuerySeqWithRefIter::getNextMatchMismatch().

{
    myStatus = SamStatus::SUCCESS;
    return myRecordPtr->myFlag;
}

int32_t SamRecord::getInsertSize

(

)

Get the inferred insert size of the read pair.

Returns:

inferred insert size.

Definition at line 845 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    return myRecordPtr->myInsertSize;
}

int & SamRecord::getInteger

(

const char *

tag

)

Get the integer value for the specified tag.

Does not set SamStatus.

Definition at line 1564 of file SamRecord.cpp.

{
    // Init to success.
    myStatus = SamStatus::SUCCESS;
    // Parse the buffer if necessary.
    if(myNeedToSetTagsFromBuffer)
    {
        if(!setTagsFromBuffer())
        {
            // Failed to read the tags from the buffer, so cannot
            // get tags.
            // TODO - what do we want to do on failure?
        }
    }
    
    int key = MAKEKEY(tag[0], tag[1], 'i');
    int offset = extras.Find(key);

    int value;
    if (offset < 0)
    {
        // TODO - what do we want to do on failure?
        return NOT_FOUND_TAG_INT;
    }
    else
        value = extras[offset];

    return integers[value];
}

uint8_t SamRecord::getMapQuality

(

)

Get the mapping quality of the record.

Returns:

map quality.

Definition at line 726 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    return myRecordPtr->myMapQuality;
}

int32_t SamRecord::getMateReferenceID

(

)

Get the mate reference id of the record.

Returns:

reference id

Definition at line 824 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    return myRecordPtr->myMateReferenceID;
}

const char * SamRecord::getMateReferenceName

(

)

Get the mate reference sequence name of the record.

If it is equal to the reference name, it still returns the reference name.

Returns:

reference sequence name

Definition at line 796 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    return myMateReferenceName.c_str();
}

const char * SamRecord::getMateReferenceNameOrEqual

(

)

Get the mate reference sequence name of the record, returning "=" if it is the same as the reference name, unless they are both "*" in which case "*" is returned.

Returns:

reference sequence name

Definition at line 806 of file SamRecord.cpp.

References getReferenceName().

{
    myStatus = SamStatus::SUCCESS;
    if(myMateReferenceName == "*")
    {
        return(myMateReferenceName);
    }
    if(myMateReferenceName == getReferenceName())
    {
        return(FIELD_ABSENT_STRING);
    }
    else
    {
        return(myMateReferenceName);
    }
}

bool SamRecord::getNextSamTag	(	char *	tag,
		char &	vtype,
		void **	value
	)

Get the next tag from the record.

Sets the Status to SUCCESS when a tag is successfully returned or when there are no more tags. Otherwise the status is set to describe why it failed (parsing, etc).

Parameters:

	tag	set to the tag when a tag is read.
	vtype	set to the vtype when a tag is read.
	value	pointer to the value of the tag (will need to cast to int, double, char, or string based on vtype).

Returns:

true if a tag was read, false if there are no more tags.

Definition at line 1260 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    if(myNeedToSetTagsFromBuffer)
    {
        if(!setTagsFromBuffer())
        {
            // Failed to read the tags from the buffer, so cannot
            // get tags.
            return(false);
        }
    }

    // Increment the tag index to start looking at the next tag.
    // At the beginning, it is set to -1.
    myLastTagIndex++;
    int maxTagIndex = extras.Capacity();
    if(myLastTagIndex >= maxTagIndex)
    {
        // Hit the end of the tags, return false, no more tags.
        // Status is still success since this is not an error, 
        // it is just the end of the list.
        return(false);
    }

    bool tagFound = false;
    // Loop until a tag is found or the end of extras is hit.
    while((tagFound == false) && (myLastTagIndex < maxTagIndex))
    {
        if(extras.SlotInUse(myLastTagIndex))
        {
            // Found a slot to use.
            int key = extras.GetKey(myLastTagIndex);
            getTag(key, tag);
            getVtype(key, vtype);
            tagFound = true;
            // Get the value associated with the key based on the vtype.
            switch (vtype)
            {
                case 'A' :
                    *value = getIntegerPtr(myLastTagIndex);
                    break;
                case 'f' :
                    *value = getDoublePtr(myLastTagIndex);
                    break;
                case 'c' :
                case 'C' :
                case 's' :
                case 'S' :
                case 'i' :
                case 'I' :
                    vtype = 'i';
                    *value = getIntegerPtr(myLastTagIndex);
                    break;
                case 'Z' :
                    *value = getStringPtr(myLastTagIndex);
                    break;
                default:
                    myStatus.setStatus(SamStatus::FAIL_PARSE,
                                       "Unknown tag type");
                    tagFound = false;
                    break;
            }
        }
        if(!tagFound)
        {
            // Increment the index since a tag was not found.
            myLastTagIndex++;
        }
    }
    return(tagFound);
}

uint32_t SamRecord::getNumOverlaps	(	int32_t	start,
		int32_t	end
	)

Return the number of bases in this read that overlap the passed in region.

Parameters:

	start	inclusive 0-based start position (reference position) of the region to check for overlaps in. (-1 indicates to start at the beginning of the reference.)
	end	exclusive 0-based end position (reference position) of the region to check for overlaps in. (-1 indicates to go to the end of the reference.)

Returns:

number of overlapping bases (matches in the cigar - not skips/deletions)

Definition at line 1648 of file SamRecord.cpp.

References get0BasedPosition().

Referenced by SamFile::GetNumOverlaps().

{
    // Determine whether or not the cigar has been parsed, which sets up
    // the cigar roller.  This is determined by checking the alignment length.
    if(myAlignmentLength == -1)
    {
        parseCigar();
    }
    return(myCigarRoller.getNumOverlaps(start, end, get0BasedPosition()));
}

char SamRecord::getQuality

(

int

index

)

Get the quality character at the specified index into the quality 0 to readLength - 1.

Parameters:

index

index into the quality string (0 to readLength-1).

Returns:

the quality character at the specified index into the quality.

Definition at line 1165 of file SamRecord.cpp.

References getReadLength().

{
    // Determine the read length.
    int32_t readLen = getReadLength();

    // If the read length is 0, return ' ' whose ascii code is below
    // the minimum ascii code for qualities.
    if(readLen == 0)
    {
        return(BaseUtilities::UNKNOWN_QUALITY_CHAR);
    }
    else if((index < 0) || (index >= readLen))
    {
        // Only get here if the index was out of range, so thow an exception.
        String exceptionString = "SamRecord::getQuality(";
        exceptionString += index;
        exceptionString += ") is out of range. Index must be between 0 and ";
        exceptionString += (readLen - 1);
        throw std::runtime_error(exceptionString.c_str());
    }

    if(myQuality.Length() == 0)
    {
        // Parse BAM Quality.
        unsigned char * packedQuality = 
            (unsigned char *)myRecordPtr->myData +
            myRecordPtr->myReadNameLength + 
            myRecordPtr->myCigarLength * sizeof(int) + 
            (myRecordPtr->myReadLength + 1) / 2;
        return(packedQuality[index] + 33);
    }
    else
    {
        // Already have string.
        if((myQuality.Length() == 1) && (myQuality[0] == '*'))
        {
            // Return 0xFF like it does for BAM.
            return(0xFF);
        }
        else
        {
            return(myQuality[index]);
        }
    }
}

const char * SamRecord::getQuality

(

)

Returns the SAM formatted quality string.

Returns:

quality string.

Definition at line 1024 of file SamRecord.cpp.

Referenced by getFields().

{
    myStatus = SamStatus::SUCCESS;
    if(myQuality.Length() == 0)
    {
        // 0 Length, means that it is in the buffer, but has not yet
        // been synced to the string, so do the sync.
        setSequenceAndQualityFromBuffer();      
    }
    return myQuality.c_str();
}

int32_t SamRecord::getReadLength

(

)

Get the length of the read.

Returns:

read length.

Definition at line 777 of file SamRecord.cpp.

Referenced by SamQuerySeqWithRefIter::getNextMatchMismatch(), getQuality(), getSequence(), SamValidator::isValidCigar(), and SamQuerySeqWithRefIter::reset().

{
    myStatus = SamStatus::SUCCESS;
    if(myIsSequenceBufferValid == false)
    {
        // If the sequence is "*", then return 0.
        if((mySequence.Length() == 1) && (mySequence[0] == '*'))
        {
            return(0);
        }
        // Do not add 1 since it is not null terminated.
        return(mySequence.Length());
    }
    return(myRecordPtr->myReadLength);
}

const char * SamRecord::getReadName

(

)

Returns the SAM formatted Read Name (QNAME).

Returns:

read name.

Definition at line 928 of file SamRecord.cpp.

Referenced by getFields(), and SamFile::validateSortOrder().

{
    myStatus = SamStatus::SUCCESS;
    if(myReadName.Length() == 0)
    {
        // 0 Length, means that it is in the buffer, but has not yet
        // been synced to the string, so do the sync.
        myReadName = (char*)&(myRecordPtr->myData);
    }
    return myReadName.c_str();
}

uint8_t SamRecord::getReadNameLength

(

)

Get the length of the readname (QNAME) including the null.

Returns:

length of the read name (including null).

Definition at line 712 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    // If the buffer is valid, return the size from there, otherwise get the 
    // size from the string length + 1 (ending null).
    if(myIsReadNameBufferValid)
    {
        return(myRecordPtr->myReadNameLength);
    }
   
    return(myReadName.Length() + 1);
}

const void * SamRecord::getRecordBuffer

(

SequenceTranslation

translation

)

Get a const pointer to the buffer that contains the BAM representation of the record.

Parameters:

translation

type of sequence translation to use.

Returns:

const pointer to the buffer that contains the BAM representation of the record.

Definition at line 597 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    bool status = true;
    // If the buffer is not synced or the sequence in the buffer is not
    // properly translated, fix the buffer.
    if((myIsBufferSynced == false) ||
       (myBufferSequenceTranslation != translation))
    {
        status &= fixBuffer(translation);
    }
    // If the buffer is synced, check to see if the tags need to be synced.
    if(myNeedToSetTagsInBuffer)
    {
        status &= setTagsInBuffer();
    }
    if(!status)
    {
        return(NULL);
    }
    return (const void *)myRecordPtr;
}

const void * SamRecord::getRecordBuffer

(

)

Get a const pointer to the buffer that contains the BAM representation of the record.

Returns:

const pointer to the buffer that contains the BAM representation of the record.

Definition at line 590 of file SamRecord.cpp.

{
    return(getRecordBuffer(mySequenceTranslation));
}

int32_t SamRecord::getReferenceID

(

)

Get the reference sequence id of the record.

Returns:

reference sequence id

Definition at line 691 of file SamRecord.cpp.

Referenced by SamFile::readIndexedRecord(), and SamFile::validateSortOrder().

{
    myStatus = SamStatus::SUCCESS;
    return myRecordPtr->myReferenceID;
}

const char * SamRecord::getReferenceName

(

)

Get the reference sequence name of the record.

Returns:

reference sequence name

Definition at line 684 of file SamRecord.cpp.

Referenced by getMateReferenceNameOrEqual(), getSequence(), and SamQuerySeqWithRefIter::reset().

{
    myStatus = SamStatus::SUCCESS;
    return myReferenceName.c_str();
}

char SamRecord::getSequence	(	int	index,
		SequenceTranslation	translation
	)

Get the sequence base at the specified index into this sequence 0 to readLength - performing the specified sequence translation1.

Parameters:

	index	index into the sequence string (0 to readLength-1).
	translation	type of sequence translation to use.

Returns:

the sequence base at the specified index into the sequence.

Definition at line 1043 of file SamRecord.cpp.

References EQUAL, getCigarInfo(), getReadLength(), getReferenceName(), NONE, SamQuerySeqWithRef::seqWithEquals(), and SamQuerySeqWithRef::seqWithoutEquals().

{
    static const char * asciiBases = "=AC.G...T......N";

    // Determine the read length.
    int32_t readLen = getReadLength();

    // If the read length is 0, this method should not be called.
    if(readLen == 0)
    {
        String exceptionString = "SamRecord::getSequence(";
        exceptionString += index;
        exceptionString += ") is not allowed since sequence = '*'";
        throw std::runtime_error(exceptionString.c_str());
    }
    else if((index < 0) || (index >= readLen))
    {
        // Only get here if the index was out of range, so thow an exception.
        String exceptionString = "SamRecord::getSequence(";
        exceptionString += index;
        exceptionString += ") is out of range. Index must be between 0 and ";
        exceptionString += (readLen - 1);
        throw std::runtime_error(exceptionString.c_str());
    }

    // Determine if translation needs to be done.
    if((translation == NONE) || (myRefPtr == NULL))
    {
        // No translation needs to be done.
        if(mySequence.Length() == 0)
        {
            // Parse BAM sequence.
            // TODO - maybe store this pointer - and use that to track when
            // valid?
            unsigned char * packedSequence = 
                (unsigned char *)myRecordPtr->myData + 
                myRecordPtr->myReadNameLength +
                myRecordPtr->myCigarLength * sizeof(int);
            
            return(index & 1 ?
                   asciiBases[packedSequence[index / 2] & 0xF] :
                   asciiBases[packedSequence[index / 2] >> 4]);
        }
        // Already have string.
        return(mySequence[index]);
    }
    else
    {
        // Need to translate the sequence either to have '=' or to not
        // have it.
        // First check to see if the sequence has been set.
        if(mySequence.Length() == 0)
        {
            // 0 Length, means that it is in the buffer, but has not yet
            // been synced to the string, so do the sync.
            setSequenceAndQualityFromBuffer();
        }

        // Check the type of translation.
        if(translation == EQUAL)
        {
            // Check whether or not the string has already been 
            // retrieved that has the '=' in it.
            if(mySeqWithEq.length() == 0)
            {
                // The string with '=' has not yet been determined,
                // so get the string.
                // Check to see if the sequence is defined.
                if(mySequence == "*")
                {
                    // Sequence is undefined, so no translation necessary.
                    mySeqWithEq = '*';
                }
                else
                {
                    // Sequence defined, so translate it.
                    SamQuerySeqWithRef::seqWithEquals(mySequence.c_str(), 
                                                      myRecordPtr->myPosition, 
                                                      *(getCigarInfo()),
                                                      getReferenceName(),
                                                      *myRefPtr,
                                                      mySeqWithEq);
                }
            }
            // Sequence is set, so return it.
            return(mySeqWithEq[index]);
        }
        else
        {
            // translation == BASES
            // Check whether or not the string has already been 
            // retrieved that does not have the '=' in it.
            if(mySeqWithoutEq.length() == 0)
            {
                // The string with '=' has not yet been determined,
                // so get the string.
                // Check to see if the sequence is defined.
                if(mySequence == "*")
                {
                    // Sequence is undefined, so no translation necessary.
                    mySeqWithoutEq = '*';
                }
                else
                {
                    // Sequence defined, so translate it.
                    // The string without '=' has not yet been determined,
                    // so get the string.
                    SamQuerySeqWithRef::seqWithoutEquals(mySequence.c_str(), 
                                                         myRecordPtr->myPosition, 
                                                         *(getCigarInfo()),
                                                         getReferenceName(),
                                                         *myRefPtr,
                                                         mySeqWithoutEq);
                }
            }
            // Sequence is set, so return it.
            return(mySeqWithoutEq[index]);
        }
    }
}

char SamRecord::getSequence

(

int

index

)

Get the sequence base at the specified index into this sequence 0 to readLength - 1, translating the base as specified by setSequenceTranslation.

Parameters:

index

index into the sequence string (0 to readLength-1).

Returns:

the sequence base at the specified index into the sequence.

Definition at line 1037 of file SamRecord.cpp.

References getSequence().

{
    return(getSequence(index, mySequenceTranslation));
}

const char * SamRecord::getSequence

(

SequenceTranslation

translation

)

Returns the SAM formatted sequence string performing the specified sequence translation.

Parameters:

translation

type of sequence translation to use.

Returns:

sequence string.

Definition at line 960 of file SamRecord.cpp.

References EQUAL, getCigarInfo(), getReferenceName(), NONE, SamQuerySeqWithRef::seqWithEquals(), and SamQuerySeqWithRef::seqWithoutEquals().

{
    myStatus = SamStatus::SUCCESS;
    if(mySequence.Length() == 0)
    {
        // 0 Length, means that it is in the buffer, but has not yet
        // been synced to the string, so do the sync.
        setSequenceAndQualityFromBuffer();
    }

    // Determine if translation needs to be done.
    if((translation == NONE) || (myRefPtr == NULL))
    {
        return mySequence.c_str();
    }
    else if(translation == EQUAL)
    {
        if(mySeqWithEq.length() == 0)
        {
            // Check to see if the sequence is defined.
            if(mySequence == "*")
            {
                // Sequence is undefined, so no translation necessary.
                mySeqWithEq = '*';
            }
            else
            {
                // Sequence defined, so translate it.
                SamQuerySeqWithRef::seqWithEquals(mySequence.c_str(), 
                                                  myRecordPtr->myPosition,
                                                  *(getCigarInfo()),
                                                  getReferenceName(),
                                                  *myRefPtr,
                                                  mySeqWithEq);
            }
        }
        return(mySeqWithEq.c_str());
    }
    else
    {
        // translation == BASES
        if(mySeqWithoutEq.length() == 0)
        {
            if(mySequence == "*")
            {
                // Sequence is undefined, so no translation necessary.
                mySeqWithoutEq = '*';
            }
            else
            {
                // Sequence defined, so translate it.
                SamQuerySeqWithRef::seqWithoutEquals(mySequence.c_str(), 
                                                     myRecordPtr->myPosition,
                                                     *(getCigarInfo()),
                                                     getReferenceName(),
                                                     *myRefPtr,
                                                     mySeqWithoutEq);
            }
        }
        return(mySeqWithoutEq.c_str());
    }
}

const char * SamRecord::getSequence

(

)

Returns the SAM formatted sequence string, translating the base as specified by setSequenceTranslation.

Returns:

sequence string.

Definition at line 954 of file SamRecord.cpp.

Referenced by getFields(), SamQuerySeqWithRefIter::getNextMatchMismatch(), and getSequence().

{
    return(getSequence(mySequenceTranslation));
}

const SamStatus & SamRecord::getStatus

(

)

Returns the status associated with the last method that sets the status.

Returns:

SamStatus of the last command that sets status.

Definition at line 1528 of file SamRecord.cpp.

{
    return(myStatus);
}

String & SamRecord::getString

(

const char *

tag

)

Get the string value for the specified tag.

Does not set SamStatus.

Definition at line 1534 of file SamRecord.cpp.

{
    // Init to success.
    myStatus = SamStatus::SUCCESS;
    // Parse the buffer if necessary.
    if(myNeedToSetTagsFromBuffer)
    {
        if(!setTagsFromBuffer())
        {
            // Failed to read the tags from the buffer, so cannot
            // get tags.
            // TODO - what do we want to do on failure?
        }
    }
    
    int key = MAKEKEY(tag[0], tag[1], 'Z');
    int offset = extras.Find(key);

    int value;
    if (offset < 0)
    {
        // TODO - what do we want to do on failure?
        return(NOT_FOUND_TAG_STRING);
    }
    else
        value = extras[offset];

    return strings[value];
}

uint32_t SamRecord::getTagLength

(

)

Returns the length of the tags in BAM format.

Returns:

length of tags in BAM format.

Definition at line 1227 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    if(myNeedToSetTagsFromBuffer)
    {
        // Tags are only set in the buffer, so the size of the tags is 
        // the length of the record minus the starting location of the tags.
        unsigned char * tagStart = 
            (unsigned char *)myRecordPtr->myData 
            + myRecordPtr->myReadNameLength 
            + myRecordPtr->myCigarLength * sizeof(int)
            + (myRecordPtr->myReadLength + 1) / 2 + myRecordPtr->myReadLength;
      
        // The non-tags take up from the start of the record to the tag start.
        // Do not include the block size part of the record since it is not
        // included in the size.
        uint32_t nonTagSize = 
            tagStart - (unsigned char*)&(myRecordPtr->myReferenceID);
        // Tags take up the size of the block minus the non-tag section.
        uint32_t tagSize = myRecordPtr->myBlockSize - nonTagSize;
        return(tagSize);
    }

    // Tags are stored outside the buffer, so myTagBufferSize is set.
    return(myTagBufferSize);
}

bool SamRecord::isCharType

(

char

vtype

)

const

Returns whether or not the specified vtype is a char type.

Does not set SamStatus.

Parameters:

vtype

value type to check.

Returns:

true if the passed in vtype is a char ('A'), false otherwise.

Definition at line 1413 of file SamRecord.cpp.

{
    if(vtype == 'A')
    {
        return(true);
    }
    return(false);
}

bool SamRecord::isDoubleType

(

char

vtype

)

const

Returns whether or not the specified vtype is a double type.

Does not set SamStatus.

Parameters:

vtype

value type to check.

Returns:

true if the passed in vtype is a double ('f'), false otherwise.

Definition at line 1403 of file SamRecord.cpp.

{
    if(vtype == 'f')
    {
        return(true);
    }
    return(false);
}

bool SamRecord::isIntegerType

(

char

vtype

)

const

Returns whether or not the specified vtype is an integer type.

Does not set SamStatus.

Parameters:

vtype

value type to check.

Returns:

true if the passed in vtype is an integer ('c', 'C', 's', 'S', 'i', 'I'), false otherwise.

Definition at line 1391 of file SamRecord.cpp.

{
    if((vtype == 'c') || (vtype == 'C') ||
       (vtype == 's') || (vtype == 'S') ||
       (vtype == 'i') || (vtype == 'I'))
    {
        return(true);
    }
    return(false);
}

bool SamRecord::isStringType

(

char

vtype

)

const

Returns whether or not the specified vtype is a string type.

Does not set SamStatus.

Parameters:

vtype

value type to check.

Returns:

true if the passed in vtype is a string ('Z'), false othwerise.

Definition at line 1423 of file SamRecord.cpp.

{
    if(vtype == 'Z')
    {
        return(true);
    }
    return(false);
}

bool SamRecord::isValid

(

SamFileHeader &

header

)

Returns whether or not the record is valid.

Sets the status to indicate success or failure.

Parameters:

header

SAM Header associated with the record. Used to perform some validation against the header.

Returns:

true if the record is valid, false if not.

Definition at line 164 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    SamValidationErrors invalidSamErrors;
    if(!SamValidator::isValid(header, *this, invalidSamErrors))
    {
        // The record is not valid.
        std::string errorMessage = "";
        invalidSamErrors.getErrorString(errorMessage);
        myStatus.setStatus(SamStatus::INVALID, errorMessage.c_str());
        return(false);
    }
    // The record is valid.
    return(true);
}

void SamRecord::resetRecord

(

)

Reset the fields of the record to a default value.

This is not necessary when you are reading a Sam/Bam file, but if you are setting fields, it is a good idea to clean out a record before reusing it. Clearing it allows you to not have to set any empty fields.

Definition at line 91 of file SamRecord.cpp.

References clearTags(), and NONE.

Referenced by SamRecord(), setBuffer(), setBufferFromFile(), and ~SamRecord().

{
    myIsBufferSynced = true;

    myRecordPtr->myBlockSize = DEFAULT_BLOCK_SIZE;
    myRecordPtr->myReferenceID = -1;
    myRecordPtr->myPosition = -1;
    myRecordPtr->myReadNameLength = DEFAULT_READ_NAME_LENGTH;
    myRecordPtr->myMapQuality = 0;
    myRecordPtr->myBin = DEFAULT_BIN;
    myRecordPtr->myCigarLength = 0;
    myRecordPtr->myFlag = 0;
    myRecordPtr->myReadLength = 0;
    myRecordPtr->myMateReferenceID = -1;
    myRecordPtr->myMatePosition = -1;
    myRecordPtr->myInsertSize = 0;
   
    // Set the sam values for the variable length fields.
    // TODO - one way to speed this up might be to not set to "*" and just
    // clear them, and write out a '*' for SAM if it is empty.
    myReadName = DEFAULT_READ_NAME;
    myReferenceName = "*";
    myMateReferenceName = "*";
    myCigar = "*";
    mySequence = "*";
    mySeqWithEq.clear();
    mySeqWithoutEq.clear();
    myQuality = "*";
    myNeedToSetTagsFromBuffer = false;
    myNeedToSetTagsInBuffer = false;

    // Initialize the calculated alignment info to the uncalculated value.
    myAlignmentLength = -1;
    myUnclippedStartOffset = -1;
    myUnclippedEndOffset = -1;

    clearTags();

    // Set the bam values for the variable length fields.
    // Only the read name needs to be set, the others are a length of 0.
    // Set the read name.  The min size of myRecordPtr includes the size for
    // the default read name.
    memcpy(&(myRecordPtr->myData), myReadName.c_str(), 
           myRecordPtr->myReadNameLength);

    // Set that the variable length buffer fields are valid.
    myIsReadNameBufferValid = true;
    myIsCigarBufferValid = true;
    myIsSequenceBufferValid = true;
    myBufferSequenceTranslation = NONE;
    myIsQualityBufferValid = true;
    myIsTagsBufferValid = true;
    myIsBinValid = true;

    myCigarTempBufferLength = -1;

    myStatus = SamStatus::SUCCESS;

    NOT_FOUND_TAG_STRING = "";
    NOT_FOUND_TAG_INT = -1;
    NOT_FOUND_TAG_DOUBLE = -1;
}

bool SamRecord::set0BasedMatePosition

(

int32_t

matePosition

)

Set the leftmost mate position using the specified 0-based (BAM format) value.

Internal processing handles the switching between SAM/BAM formats when read/written.

Parameters:

position

0-based start position

Returns:

true if successfully set, false if not.

Definition at line 394 of file SamRecord.cpp.

Referenced by set1BasedMatePosition().

{
    myStatus = SamStatus::SUCCESS;
    myRecordPtr->myMatePosition = matePosition;
    return true;
}

bool SamRecord::set0BasedPosition

(

int32_t

position

)

Set the leftmost position using the specified 0-based (BAM format) value.

Internal processing handles the switching between SAM/BAM formats when read/written.

Parameters:

position

0-based start position

Returns:

true if successfully set, false if not.

Definition at line 309 of file SamRecord.cpp.

Referenced by set1BasedPosition(), and SamFilter::softClip().

{
    myStatus = SamStatus::SUCCESS;
    myRecordPtr->myPosition = position;
    myIsBinValid = false;
    return true;
}

bool SamRecord::set1BasedMatePosition

(

int32_t

matePosition

)

Set the leftmost mate position using the specified 1-based (SAM format) value.

Internal processing handles the switching between SAM/BAM formats when read/written.

Parameters:

position

1-based start position

Returns:

true if successfully set, false if not.

Definition at line 388 of file SamRecord.cpp.

References set0BasedMatePosition().

{
    return(set0BasedMatePosition(matePosition - 1));
}

bool SamRecord::set1BasedPosition

(

int32_t

position

)

Set the leftmost position using the specified 1-based (SAM format) value.

Internal processing handles the switching between SAM/BAM formats when read/written.

Parameters:

position

1-based start position

Returns:

true if successfully set, false if not.

Definition at line 303 of file SamRecord.cpp.

References set0BasedPosition().

{
    return(set0BasedPosition(position - 1));
}

SamStatus::Status SamRecord::setBuffer	(	const char *	fromBuffer,
		uint32_t	fromBufferSize,
		SamFileHeader &	header
	)

Sets the SamRecord to contain the information in BAM format found in fromBuffer.

Parameters:

	fromBuffer	buffer to read the BAM record from.
	fromBufferSize	size of the buffer containing the BAM record.
	header	BAM header for the record.

Returns:

status of reading the BAM record from the buffer.

Definition at line 435 of file SamRecord.cpp.

References resetRecord().

{
    myStatus = SamStatus::SUCCESS;
    if((fromBuffer == NULL) || (fromBufferSize == 0))
    {
        // Buffer is empty.
        myStatus.setStatus(SamStatus::FAIL_PARSE,
                           "Cannot parse an empty file.");
        return(SamStatus::FAIL_PARSE);
    }

    // Clear the record.   
    resetRecord();

    // allocate space for the record size.
    if(!allocateRecordStructure(fromBufferSize))
    {
        // Failed to allocate space.
        return(SamStatus::FAIL_MEM);
    }
   
    memcpy(myRecordPtr, fromBuffer, fromBufferSize);

    setVariablesForNewBuffer(header);

    // Return the status of the record.
    return(SamStatus::SUCCESS);
}

SamStatus::Status SamRecord::setBufferFromFile	(	IFILE	filePtr,
		SamFileHeader &	header
	)

Read the BAM record from a file.

Parameters:

	filePtr	file to read the buffer from.
	header	BAM header for the record.

Returns:

status of the reading the BAM record from the file.

Definition at line 182 of file SamRecord.cpp.

References ifeof(), ifread(), InputFile::isOpen(), and resetRecord().

{
    myStatus = SamStatus::SUCCESS;
    if((filePtr == NULL) || (filePtr->isOpen() == false))
    {
        // File is not open, return failure.
        myStatus.setStatus(SamStatus::FAIL_ORDER, 
                           "Can't read from an unopened file.");
        return(SamStatus::FAIL_ORDER);
    }

    // Clear the record.
    resetRecord();

    // read the record size.
    int numBytes = 
        ifread(filePtr, &(myRecordPtr->myBlockSize), sizeof(int32_t));

    if(ifeof(filePtr))
    {
        if(numBytes == 0)
        {
            // End of file, nothing was read, no more records.
            myStatus.setStatus(SamStatus::NO_MORE_RECS,
                               "No more records left to read.");
            return(SamStatus::NO_MORE_RECS);
        }
        else
        {
            // Error: end of the file reached prior to reading the rest of the
            // record.
            myStatus.setStatus(SamStatus::FAIL_PARSE, 
                               "EOF reached in the middle of a record.");
            return(SamStatus::FAIL_PARSE);
        }
    }

    // allocate space for the record size.
    if(!allocateRecordStructure(myRecordPtr->myBlockSize + sizeof(int32_t)))
    {
        // Failed to allocate space.
        // Status is set by allocateRecordStructure.
        return(SamStatus::FAIL_MEM);
    }

    // Read the rest of the alignment block, starting at the reference id.
    if(ifread(filePtr, &(myRecordPtr->myReferenceID), myRecordPtr->myBlockSize)
       != (unsigned int)myRecordPtr->myBlockSize)
    {
        // Error reading the record.  Reset it and return failure.
        resetRecord();
        myStatus.setStatus(SamStatus::FAIL_IO,
                           "Failed to read the record");
        return(SamStatus::FAIL_IO);
    }

    setVariablesForNewBuffer(header);

    // Return the status of the record.
    return(SamStatus::SUCCESS);
}

bool SamRecord::setCigar

(

const Cigar &

cigar

)

Set the CIGAR to the specified Cigar object.

Internal processing handles the switching between SAM/BAM formats when read/written.

Parameters:

cigar

object to set this record's cigar to have.

Returns:

true if successfully set, false if not.

Definition at line 345 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    cigar.getCigarString(myCigar);
 
    myIsBufferSynced = false;
    myIsCigarBufferValid = false;
    myCigarTempBufferLength = -1;
    myIsBinValid = false;

    // Initialize the calculated alignment info to the uncalculated value.
    myAlignmentLength = -1;
    myUnclippedStartOffset = -1;
    myUnclippedEndOffset = -1;

    return true;
}

bool SamRecord::setCigar

(

const char *

cigar

)

Set the CIGAR to the specified SAM formatted cigar string.

Internal processing handles the switching between SAM/BAM formats when read/written.

Parameters:

cigar

string containing the SAM formatted cigar.

Returns:

true if successfully set, false if not.

Definition at line 326 of file SamRecord.cpp.

Referenced by SamFilter::softClip().

{
    myStatus = SamStatus::SUCCESS;
    myCigar = cigar;
 
    myIsBufferSynced = false;
    myIsCigarBufferValid = false;
    myCigarTempBufferLength = -1;
    myIsBinValid = false;

    // Initialize the calculated alignment info to the uncalculated value.
    myAlignmentLength = -1;
    myUnclippedStartOffset = -1;
    myUnclippedEndOffset = -1;

    return true;
}

bool SamRecord::setFlag

(

uint16_t

flag

)

Set the bitwise flag to the specified value.

Parameters:

flag

integer flag to use.

Returns:

true if successfully set, false if not.

Definition at line 283 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    myRecordPtr->myFlag = flag;
    return true;
}

bool SamRecord::setInsertSize

(

int32_t

insertSize

)

Sets the inferred insert size.

Parameters:

insertSize

inferred insert size.

Returns:

true if successfully set, false if not.

Definition at line 402 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    myRecordPtr->myInsertSize = insertSize;
    return true;
}

bool SamRecord::setMapQuality

(

uint8_t

mapQuality

)

Set the mapping quality.

Parameters:

mapQuality

map quality to set in the record.

Returns:

true if successfully set, false if not.

Definition at line 318 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    myRecordPtr->myMapQuality = mapQuality;
    return true;
}

bool SamRecord::setMateReferenceName	(	SamFileHeader &	header,
		const char *	mateReferenceName
	)

Set the mate reference sequence name to the specified name, using the header to determine the matee reference id.

Parameters:

	header	SAM/BAM header to use to determine the mate reference id.
	referenceName	mate reference name to use.

Returns:

true if successfully set, false if not

Definition at line 364 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    // Set the mate reference, if it is "=", set it to be equal
    // to myReferenceName.  This assumes that myReferenceName has already
    // been called.
    if(strcmp(mateReferenceName, FIELD_ABSENT_STRING) == 0)
    {
        myMateReferenceName = myReferenceName;
    }
    else
    {
        myMateReferenceName = mateReferenceName;
    }

    // Set the Mate Reference ID.
    myRecordPtr->myMateReferenceID = 
        header.getReferenceID(myMateReferenceName);

    return true;
}

bool SamRecord::setQuality

(

const char *

quality

)

Sets the quality to the specified quality string.

This is a SAM formatted quality string. Internal processing handles switching between SAM/BAM formats when read/written.

Parameters:

quality

SAM quality string.

Returns:

true if successfully set, false if not.

Definition at line 423 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    myQuality = quality;
    myIsBufferSynced = false;
    myIsQualityBufferValid = false;
    return true;
}

bool SamRecord::setReadName

(

const char *

readName

)

Set QNAME to the passed in name.

Parameters:

readName

the readname to set the QNAME to.

Returns:

true if successfully set, false if not.

Definition at line 261 of file SamRecord.cpp.

{
    myReadName = readName;
    myIsBufferSynced = false;
    myIsReadNameBufferValid = false;
    myStatus = SamStatus::SUCCESS;

    // The read name must at least have some length, otherwise this is a parsing
    // error.
    if(myReadName.Length() == 0)
    {
        // Invalid - reset ReadName return false.
        myReadName = DEFAULT_READ_NAME;
        myRecordPtr->myReadNameLength = DEFAULT_READ_NAME_LENGTH;
        myStatus.setStatus(SamStatus::INVALID, "0 length Query Name.");
        return(false);
    }

    return true;
}

void SamRecord::setReference

(

GenomeSequence *

reference

)

Set the reference to the specified genome sequence object.

Parameters:

reference

pointer to the GenomeSequence object.

Definition at line 246 of file SamRecord.cpp.

Referenced by SamFile::GetNumOverlaps(), SamFile::readIndexedRecord(), SamFile::ReadRecord(), SamFile::validateSortOrder(), and SamFile::WriteRecord().

{
    myRefPtr = reference;
}

bool SamRecord::setReferenceName	(	SamFileHeader &	header,
		const char *	referenceName
	)

Set the reference name to the specified name, using the header to determine the reference id.

Parameters:

	header	SAM/BAM header to use to determine the reference id.
	referenceName	reference name to use.

Returns:

true if successfully set, false if not

Definition at line 291 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;

    myReferenceName = referenceName;
    myRecordPtr->myReferenceID = header.getReferenceID(referenceName);

    return true;
}

bool SamRecord::setSequence

(

const char *

seq

)

Sets the sequence to the specified sequence string.

This is a SAM formatted sequence string. Internal processing handles switching between SAM/BAM formats when read/written.

Parameters:

seq

SAM sequence string. May contain '='.

Returns:

true if successfully set, false if not.

Definition at line 410 of file SamRecord.cpp.

{
    myStatus = SamStatus::SUCCESS;
    mySequence = seq;
    mySeqWithEq.clear();
    mySeqWithoutEq.clear();
   
    myIsBufferSynced = false;
    myIsSequenceBufferValid = false;
    return true;
}

void SamRecord::setSequenceTranslation

(

SequenceTranslation

translation

)

Set the type of sequence translation to use when getting the sequence.

The default type (if this method is never called) is NONE (the sequence is left as-is). Can be over-ridden by using the accessors that take a SequenceTranslation parameter.

Parameters:

translation

type of sequence translation to use.

Definition at line 255 of file SamRecord.cpp.

Referenced by SamFile::GetNumOverlaps(), SamFile::readIndexedRecord(), SamFile::ReadRecord(), and SamFile::validateSortOrder().

{
    mySequenceTranslation = translation;
}

SamStatus::Status SamRecord::writeRecordBuffer	(	IFILE	filePtr,
		SequenceTranslation	translation
	)

Write the record as a BAM into the specified file.

Parameters:

	filePtr	file to write the BAM record into.
	translation	type of sequence translation to use.

Returns:

status of the write.

Definition at line 630 of file SamRecord.cpp.

References ifwrite(), and InputFile::isOpen().

{
    myStatus = SamStatus::SUCCESS;
    if((filePtr == NULL) || (filePtr->isOpen() == false))
    {
        // File is not open, return failure.
        myStatus.setStatus(SamStatus::FAIL_ORDER,
                           "Can't write to an unopened file.");
        return(SamStatus::FAIL_ORDER);
    }

    if((myIsBufferSynced == false) ||
       (myBufferSequenceTranslation != translation))
    {
        if(!fixBuffer(translation))
        {
            return(myStatus.getStatus());
        }
    }

    // Write the record.
    unsigned int numBytesToWrite = myRecordPtr->myBlockSize + sizeof(int32_t);
    unsigned int numBytesWritten = 
        ifwrite(filePtr, myRecordPtr, numBytesToWrite);

    // Return status based on if the correct number of bytes were written.
    if(numBytesToWrite == numBytesWritten)
    {
        return(SamStatus::SUCCESS);
    }
    // The correct number of bytes were not written.
    myStatus.setStatus(SamStatus::FAIL_IO, "Failed to write the entire record.");
    return(SamStatus::FAIL_IO);
}

SamStatus::Status SamRecord::writeRecordBuffer

(

IFILE

filePtr

)

Write the record as a BAM into the specified file.

Parameters:

filePtr

file to write the BAM record into.

Returns:

status of the write.

Definition at line 623 of file SamRecord.cpp.

{
    return(writeRecordBuffer(filePtr, mySequenceTranslation));
}

---

The documentation for this class was generated from the following files:

• lib/bam/SamRecord.h
• lib/bam/SamRecord.cpp