/*!
* @class BamAlignmentRecord
*
* @implements FormattedFileRecordConcept
*
* @headerfile <seqan/bam_io.h>
*
* @brief Represent a record from a BAM or SAM file.
*
* @signature class BamAlignmentRecord;
*
* @section Remarks
*
* While also used to represent SAM records, the type is called
* <tt>BamAlignmentRecord</tt> since the data directly reflects a BAM records
* (0-based positions, identify references by id, and tags are stored in BAM
* format.
*
* @see BamFileIn
* @see BamFileOut
*
* @var uint32_t BamAlignmentRecord::INVALID_POS;
*
* @brief Static member with invalid sentinel/position value (-1).
*
* @var uint32_t BamAlignmentRecord::INVALID_REFID;
*
* @brief Static member with invalid sentinel/position value (-1).
*
* @var uint32_t BamAlignmentRecord::INVALID_LEN;
*
* @brief Static member with invalid/sentinel reference ids (0 as in BAM/SAM).
*
* @var CharString BamAlignmentRecord::qName;
*
* @brief The query/read name.
*
* Note that the reads of a template all of the same query name and are
* differentiated by their position and the
* <tt>BAM_FLAG_FIRST</tt>/<tt>BAM_FLAG_LAST</tt> flag values.
*
* @var uint16_t BamAlignmentRecord::flag;
*
* @brief The flag of this mapping.
*
* See @link BamFlags @endlink for flag constants and also see the
* <tt>hasFlag*()</tt> functions.
*
* @var int32_t BamAlignmentRecord::rID;
*
* @brief ID of reference for this fragment mapping (0-based,
* <tt>INVALID_REFID</tt> for '*' in SAM).
*
* @var int32_t BamAlignmentRecord::beginPos;
*
* @brief Begin position of the alignment (0-based, <tt>INVALID_POS</tt> for '0'
* in SAM).
*
* @var uint8_t BamAlignmentRecord::mapQ;
*
* @brief Mapping quality (255 for '*').
*
* @var uint16_t BamAlignmentRecord::bin;
*
* @brief The bin of the alignment, automatically computed when writing BAM.
*
* @var TCigarString BamAlignmentRecord::cigar;
*
* @brief The CIGAR string for the BAM alignment (of type String<CigarElement<>
* >).
*
* @var int32_t BamAlignmentRecord::rNextId;
*
* @brief The ID of the reference where the next fragment in this template
* aligns.
*
* <tt>INVALID_REFID</tt> for '*'.
*
* @var int32_t BamAlignmentRecord::pNext;
*
* @brief Position on the reference where the next fragment in this template
* aligns.
*
* <tt>INVALID_POS</tt> for '*'.
*
* @var int32_t BamAlignmentRecord::tLen;
*
* @brief The inferred template size.
*
* <tt>INVALID_LEN</tt> for '*'.
*
* @var CharString BamAlignmentRecord::seq;
*
* @brief The fragment sequence.
*
* @var CharString BamAlignmentRecord::qual;
*
* @brief The PHRED quality values of the sequence (as in SAM), empty for '*'.
*
* @var CharString BamAlignmentRecord::tags;
*
* @brief Raw BAM tag string, use @link BamTagsDict @endlink for comfortable
* access.
*
* @fn BamAlignmentRecord#getContigName
*
* @brief Return the name of the reference contig of a @link BamAlignmentRecord
* @endlink.
*
* @signature TNameString getContigName(record, file);
*
* @param[in] record The @link BamAlignmentRecord @endlink to query.
* @param[in] file The @link BamFileIn @endlink or @link BamFileOut @endlink
* where the record belongs to.
*
* @return TNameString The name of the reference contig. <tt>TNameString</tt> is
* the @link Value @endlink type of the NameStore. The
* NameStore type can be determined using the @link Member
* @endlink metafunction for the @link BamIOContext @endlink
* in conjunction with the @link
* BamIOContextMemberTag#NameStoreMember @endlink tag.
*
* @fn BamAlignmentRecord#getContigLength
*
* @brief Return the length of the reference contig of a @link
* BamAlignmentRecord @endlink.
*
* @signature TLength getContigLength(record, file);
*
* @param[in] record The @link BamAlignmentRecord @endlink to query.
* @param[in] file The @link BamFileIn @endlink or @link BamFileOut @endlink
* where the record belongs to.
*
* @return TLength The length of the reference contig. <tt>TLength</tt> is the
* @link Value @endlink type of the LengthStore. The LengthStore
* type can be determined using the @link Member @endlink
* metafunction for the @link BamIOContext @endlink in
* conjunction with the @link
* BamIOContextMemberTag#LengthStoreMember @endlink tag.
*
* @fn BamAlignmentRecord#bamRecordToAlignment
*
* @headerfile <seqan/bam_io.h>
*
* @brief Construct an @link Align @endlink object from a BamAlignmentRecord
* object.
*
* @signature void bamRecordToAlignment(align, reference, record);
*
* @param[out] align The @link Align @endlink object to create the alignment
* object in.
* @param[in] reference The string with the reference that <tt>record</tt> lies
* on.
* @param[in] record The @link BamAlignmentRecord @endlink to construct
* alignment from.
*
* The function will resize <tt>align</tt> to have two rows. The part of the
* reference that the read from <tt>record</tt> aligns to will be copied to the
* first row and the sequence from record will be copied to the second row (and
* reverse-complemented if appropriate). Then, the gaps from the CIGAR string in
* <tt>record</tt> will be copied to <tt>align</tt>.
*
* @section Example
*
* Here is an example:
*
* @code{.cpp}
* StringSet<Dna5String> references;
* BamAlignment record;
* // Read references and record.
* Align<Dna5String> align;
* if (record.rID != BamAlignmentRecord::INVALID_REFID)
* bamRecordToAlignment(align, references[record.refId], record);
* @endcode
*
*
* @fn BamAlignmentRecord#clear
*
* @brief Clear BamAlignmentRecord.
*
* @signature void clear(record);
*
* @param[in,out] record The BamAlignmentRecord to clear.
*
* Clears all strings and resets it to default initialization state.
*
* @fn BamAlignmentRecord#hasFlagMultiple
*
* @headerfile <seqan/bam_io.h>
*
* @brief Return true if a @link BamAlignmentRecord @endlink has the "multiple"
* flag set.
*
* @signature bool hasFlagMultiple(record);
*
* @param[in] record The BamAlignmentRecord to query.
*
* @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
*
* @see BamFlags
*
* @fn BamAlignmentRecord#hasFlagAllProper
*
* @headerfile <seqan/bam_io.h>
*
* @brief Return true if a @link BamAlignmentRecord @endlink has the "all
* properly aligned" flag set.
*
* @signature bool hasFlagAllProper(record);
*
* @param[in] record The BamAlignmentRecord to query.
*
* @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
*
* @see BamFlags
*
* @fn BamAlignmentRecord#hasFlagUnmapped
*
* @headerfile <seqan/bam_io.h>
*
* @brief Return true if a @link BamAlignmentRecord @endlink has the "unmapped"
* flag set.
*
* @signature bool hasFlagUnmapped(record);
*
* @param[in] record The BamAlignmentRecord to query.
*
* @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
*
* @see BamFlags
*
* @fn BamAlignmentRecord#hasFlagNextUnmapped
*
* @headerfile <seqan/bam_io.h>
*
* @brief Return true if a @link BamAlignmentRecord @endlink has the "next
* unmapped" flag set.
*
* @signature bool hasFlagNextUnmapped(record);
*
* @param[in] record The BamAlignmentRecord to query.
*
* @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
*
* @see BamFlags
*
* @fn BamAlignmentRecord#hasFlagRC
*
* @headerfile <seqan/bam_io.h>
*
* @brief Return true if a @link BamAlignmentRecord @endlink has the "reverse-
* complemented" flag set.
*
* @signature bool hasFlagRC(record);
*
* @param[in] record The BamAlignmentRecord to query.
*
* @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
*
* @see BamFlags
*
* @fn BamAlignmentRecord#hasFlagNextRC
*
* @headerfile <seqan/bam_io.h>
*
* @brief Return true if a @link BamAlignmentRecord @endlink has the "next
* reverse-complemented" flag set.
*
* @signature bool hasFlagNextRC(record);
*
* @param[in] record The BamAlignmentRecord to query.
*
* @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
*
* @see BamFlags
*
* @fn BamAlignmentRecord#hasFlagFirst
*
* @headerfile <seqan/bam_io.h>
*
* @brief Return true if a @link BamAlignmentRecord @endlink has the "first in
* template" flag set.
*
* @signature bool hasFlagFirst(record);
*
* @param[in] record The BamAlignmentRecord to query.
*
* @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
*
* @see BamFlags
*
* @fn BamAlignmentRecord#hasFlagLast
*
* @headerfile <seqan/bam_io.h>
*
* @brief Return true if a @link BamAlignmentRecord @endlink has the "last in
* template" flag set.
*
* @signature bool hasFlagLast(record);
*
* @param[in] record The BamAlignmentRecord to query.
*
* @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
*
* @see BamFlags
*
* @fn BamAlignmentRecord#hasFlagSecondary
*
* @headerfile <seqan/bam_io.h>
*
* @brief Return true if a @link BamAlignmentRecord @endlink has the "secondary"
* flag set.
*
* @signature bool hasFlagSecondary(record);
*
* @param[in] record The BamAlignmentRecord to query.
*
* @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
*
* @see BamFlags
*
* @fn BamAlignmentRecord#hasFlagQCNoPass
*
* @headerfile <seqan/bam_io.h>
*
* @brief Return true if a @link BamAlignmentRecord @endlink has the "did not
* pass QC" flag set.
*
* @signature bool hasFlagQCNoPass(record);
*
* @param[in] record The BamAlignmentRecord to query.
*
* @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
*
* @see BamFlags
*
* @fn BamAlignmentRecord#hasFlagDuplicate
*
* @headerfile <seqan/bam_io.h>
*
* @brief Return true if a @link BamAlignmentRecord @endlink has the "duplicate"
* flag set.
*
* @signature bool hasFlagDuplicate(record);
*
* @param[in] record The BamAlignmentRecord to query.
*
* @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
*
* @see BamFlags
*
* @fn BamAlignmentRecord#hasFlagSupplementary
*
* @headerfile <seqan/bam_io.h>
*
* @brief Return true if a @link BamAlignmentRecord @endlink has the
* "supplementary" flag set.
*
* @signature bool hasFlagSupplementary(record);
*
* @param record The BamAlignmentRecord to query.
*
* @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
*
* @fn BamAlignmentRecord#getAlignmentLengthInRef
*
* @headerfile <seqan/bam_io.h>
*
* @brief Return the alignment length in the record's projection in the
* reference.
*
* @signature unsigned getAlignmentLengthInRef(record);
*
* @param[in] record The BamAlignmentRecord to compute length for.
*
* @return unsigned The alignment length.
*
* @see BamFlags
*/