# Class BamAlignmentRecord
Represent a record from a BAM or SAM file.

Implements | FormattedFileRecordConcept
All Impl'd | AssignableConcept, CopyConstructibleConcept, DefaultConstructibleConcept, FormattedFileRecordConcept
Defined in | <seqan/bam_io.h>
Signature | `class BamAlignmentRecord;`

## Member Function Overview

### Member Functions Inherited From AssignableConcept

- `operator=`

## Interface Function Overview

- `void bamRecordToAlignment(align, reference, record);`
  Construct an Align object from a BamAlignmentRecord object.
- `void clear(record);`
  Clear BamAlignmentRecord.
- `unsigned getAlignmentLengthInRef(record);`
  Return the alignment length in the record's projection in the reference.
- `TLength getContigLength(record, file);`
  Return the length of the reference contig of a BamAlignmentRecord.
- `TNameString getContigName(record, file);`
  Return the name of the reference contig of a BamAlignmentRecord.
- `bool hasFlagAllProper(record);`
  Return true if a BamAlignmentRecord has the "all properly aligned" flag set.
- `bool hasFlagDuplicate(record);`
  Return true if a BamAlignmentRecord has the "duplicate" flag set.
- `bool hasFlagFirst(record);`
  Return true if a BamAlignmentRecord has the "first in template" flag set.
- `bool hasFlagLast(record);`
  Return true if a BamAlignmentRecord has the "last in template" flag set.
- `bool hasFlagMultiple(record);`
  Return true if a BamAlignmentRecord has the "multiple" flag set.
- `bool hasFlagNextRC(record);`
  Return true if a BamAlignmentRecord has the "next reverse-complemented" flag set.
- `bool hasFlagNextUnmapped(record);`
  Return true if a BamAlignmentRecord has the "next unmapped" flag set.
- `bool hasFlagQCNoPass(record);`
  Return true if a BamAlignmentRecord has the "did not pass QC" flag set.
- `bool hasFlagRC(record);`
  Return true if a BamAlignmentRecord has the "reverse-complemented" flag set.
- `bool hasFlagSecondary(record);`
  Return true if a BamAlignmentRecord has the "secondary" flag set.
- `bool hasFlagSupplementary(record);`
  Return true if a BamAlignmentRecord has the "supplementary" flag set.
- `bool hasFlagUnmapped(record);`
  Return true if a BamAlignmentRecord has the "unmapped" flag set.

### Interface Functions Inherited From AssignableConcept

- `assign`
- `set`
- `move`

## Member Variable Overview

- `__int32 BamAlignmentRecord::beginPos`
  Begin position of the alignment (0-based, `INVALID_POS` for '0' in SAM).
- `__uint16 BamAlignmentRecord::bin`
  The bin of the alignment, automatically computed when writing BAM.
- `TCigarString BamAlignmentRecord::cigar`
  The CIGAR string for the BAM alignment (of type String<CigarElement<> >).
- `__uint16 BamAlignmentRecord::flag`
  The flag of this mapping.
- `__uint32 BamAlignmentRecord::INVALID_LEN`
  Static member with invalid/sentinel reference ids (0 as in BAM/SAM).
- `__uint32 BamAlignmentRecord::INVALID_POS`
  Static member with invalid sentinel/position value (-1).
- `__uint32 BamAlignmentRecord::INVALID_REFID`
  Static member with invalid sentinel/position value (-1).
- `__uint8 BamAlignmentRecord::mapQ`
  Mapping quality (255 for '*').
- `__int32 BamAlignmentRecord::pNext`
  Position on the reference where the next fragment in this template aligns.
- `CharString BamAlignmentRecord::qName`
  The query/read name.
- `CharString BamAlignmentRecord::qual`
  The PHRED quality values of the sequence (as in SAM), empty for '*'.
- `__int32 BamAlignmentRecord::rID`
  ID of reference for this fragment mapping (0-based, `INVALID_REFID` for '*' in SAM).
- `__int32 BamAlignmentRecord::rNextId`
  The ID of the reference where the next fragment in this template aligns.
- `CharString BamAlignmentRecord::seq`
  The fragment sequence.
- `CharString BamAlignmentRecord::tags`
  Raw BAM tag string, use BamTagsDict for comfortable access.
- `__int32 BamAlignmentRecord::tLen`
  The inferred template size.

## Detailed Description

### Remarks

While also used to represent SAM records, the type is called `BamAlignmentRecord` since the data directly reflects a BAM records (0-based positions, identify references by id, and tags are stored in BAM format.

## See Also

- BamFileIn
- BamFileOut

## Interface Functions Detail

### `void bamRecordToAlignment(align, reference, record);`

Construct an Align object from a BamAlignmentRecord object.

#### Parameters

`align` | The Align object to create the alignment object in.
`reference` | The string with the reference that `record` lies on.
`record` | The BamAlignmentRecord to construct alignment from.

The function will resize `align` to have two rows. The part of the reference that the read from `record` 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 `record` will be copied to `align`.

#### Example

Here is an example:

    StringSet<Dna5String> references;
    BamAlignment record;
    // Read references and record.
    Align<Dna5String> align;
    if (record.rID != BamAlignmentRecord::INVALID_REFID)
        bamRecordToAlignment(align, references[record.refId], record);

#### Data Races

Thread safety unknown!

### `void clear(record);`

Clear BamAlignmentRecord.

#### Parameters

`record` | The BamAlignmentRecord to clear.

Clears all strings and resets it to default initialization state.

#### Data Races

Thread safety unknown!

### `unsigned getAlignmentLengthInRef(record);`

Return the alignment length in the record's projection in the reference.

#### Parameters

`record` | The BamAlignmentRecord to compute length for.

#### Returns

`unsigned` | The alignment length.

#### Data Races

Thread safety unknown!

#### See Also

- BamFlags

### `TLength getContigLength(record, file);`

Return the length of the reference contig of a BamAlignmentRecord.

#### Parameters

`record` | The BamAlignmentRecord to query.
`file` | The BamFileIn or BamFileOut where the record belongs to.

#### Returns

`TLength` | The length of the reference contig. `TLength` is the Value type of the LengthStore. The LengthStore type can be determined using the Member metafunction for the BamIOContext in conjunction with the LengthStoreMember tag.

#### Data Races

Thread safety unknown!

### `TNameString getContigName(record, file);`

Return the name of the reference contig of a BamAlignmentRecord.

#### Parameters

`record` | The BamAlignmentRecord to query.
`file` | The BamFileIn or BamFileOut where the record belongs to.

#### Returns

`TNameString` | The name of the reference contig. `TNameString` is the Value type of the NameStore. The NameStore type can be determined using the Member metafunction for the BamIOContext in conjunction with the NameStoreMember tag.

#### Data Races

Thread safety unknown!

### `bool hasFlagAllProper(record);`

Return true if a BamAlignmentRecord has the "all properly aligned" flag set.

#### Parameters

`record` | The BamAlignmentRecord to query.

#### Returns

`bool` | `true` if the flag is set, `false` otherwise.

#### Data Races

Thread safety unknown!

#### See Also

- BamFlags

### `bool hasFlagDuplicate(record);`

Return true if a BamAlignmentRecord has the "duplicate" flag set.

#### Parameters

`record` | The BamAlignmentRecord to query.

#### Returns

`bool` | `true` if the flag is set, `false` otherwise.

#### Data Races

Thread safety unknown!

#### See Also

- BamFlags

### `bool hasFlagFirst(record);`

Return true if a BamAlignmentRecord has the "first in template" flag set.

#### Parameters

`record` | The BamAlignmentRecord to query.

#### Returns

`bool` | `true` if the flag is set, `false` otherwise.

#### Data Races

Thread safety unknown!

#### See Also

- BamFlags

### `bool hasFlagLast(record);`

Return true if a BamAlignmentRecord has the "last in template" flag set.

#### Parameters

`record` | The BamAlignmentRecord to query.

#### Returns

`bool` | `true` if the flag is set, `false` otherwise.

#### Data Races

Thread safety unknown!

#### See Also

- BamFlags

### `bool hasFlagMultiple(record);`

Return true if a BamAlignmentRecord has the "multiple" flag set.

#### Parameters

`record` | The BamAlignmentRecord to query.

#### Returns

`bool` | `true` if the flag is set, `false` otherwise.

#### Data Races

Thread safety unknown!

#### See Also

- BamFlags

### `bool hasFlagNextRC(record);`

Return true if a BamAlignmentRecord has the "next reverse-complemented" flag set.

#### Parameters

`record` | The BamAlignmentRecord to query.

#### Returns

`bool` | `true` if the flag is set, `false` otherwise.

#### Data Races

Thread safety unknown!

#### See Also

- BamFlags

### `bool hasFlagNextUnmapped(record);`

Return true if a BamAlignmentRecord has the "next unmapped" flag set.

#### Parameters

`record` | The BamAlignmentRecord to query.

#### Returns

`bool` | `true` if the flag is set, `false` otherwise.

#### Data Races

Thread safety unknown!

#### See Also

- BamFlags

### `bool hasFlagQCNoPass(record);`

Return true if a BamAlignmentRecord has the "did not pass QC" flag set.

#### Parameters

`record` | The BamAlignmentRecord to query.

#### Returns

`bool` | `true` if the flag is set, `false` otherwise.

#### Data Races

Thread safety unknown!

#### See Also

- BamFlags

### `bool hasFlagRC(record);`

Return true if a BamAlignmentRecord has the "reverse-complemented" flag set.

#### Parameters

`record` | The BamAlignmentRecord to query.

#### Returns

`bool` | `true` if the flag is set, `false` otherwise.

#### Data Races

Thread safety unknown!

#### See Also

- BamFlags

### `bool hasFlagSecondary(record);`

Return true if a BamAlignmentRecord has the "secondary" flag set.

#### Parameters

`record` | The BamAlignmentRecord to query.

#### Returns

`bool` | `true` if the flag is set, `false` otherwise.

#### Data Races

Thread safety unknown!

#### See Also

- BamFlags

### `bool hasFlagSupplementary(record);`

Return true if a BamAlignmentRecord has the "supplementary" flag set.

#### Parameters

`record` | The BamAlignmentRecord to query.

#### Returns

`bool` | `true` if the flag is set, `false` otherwise.

#### Data Races

Thread safety unknown!

### `bool hasFlagUnmapped(record);`

Return true if a BamAlignmentRecord has the "unmapped" flag set.

#### Parameters

`record` | The BamAlignmentRecord to query.

#### Returns

`bool` | `true` if the flag is set, `false` otherwise.

#### Data Races

Thread safety unknown!

#### See Also

- BamFlags

## Member Variables Detail

### `__int32 BamAlignmentRecord::beginPos`

Begin position of the alignment (0-based, `INVALID_POS` for '0' in SAM).

### `__uint16 BamAlignmentRecord::bin`

The bin of the alignment, automatically computed when writing BAM.

### `TCigarString BamAlignmentRecord::cigar`

The CIGAR string for the BAM alignment (of type String<CigarElement<> >).

### `__uint16 BamAlignmentRecord::flag`

The flag of this mapping.

See BamFlags for flag constants and also see the `hasFlag*()` functions.

### `__uint32 BamAlignmentRecord::INVALID_LEN`

Static member with invalid/sentinel reference ids (0 as in BAM/SAM).

### `__uint32 BamAlignmentRecord::INVALID_POS`

Static member with invalid sentinel/position value (-1).

### `__uint32 BamAlignmentRecord::INVALID_REFID`

Static member with invalid sentinel/position value (-1).

### `__uint8 BamAlignmentRecord::mapQ`

Mapping quality (255 for '*').

### `__int32 BamAlignmentRecord::pNext`

Position on the reference where the next fragment in this template aligns.

`INVALID_POS` for '*'.

### `CharString BamAlignmentRecord::qName`

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 `BAM_FLAG_FIRST`/`BAM_FLAG_LAST` flag values.

### `CharString BamAlignmentRecord::qual`

The PHRED quality values of the sequence (as in SAM), empty for '*'.

### `__int32 BamAlignmentRecord::rID`

ID of reference for this fragment mapping (0-based, `INVALID_REFID` for '*' in SAM).

### `__int32 BamAlignmentRecord::rNextId`

The ID of the reference where the next fragment in this template aligns.

`INVALID_REFID` for '*'.

### `CharString BamAlignmentRecord::seq`

The fragment sequence.

### `CharString BamAlignmentRecord::tags`

Raw BAM tag string, use BamTagsDict for comfortable access.

### `__int32 BamAlignmentRecord::tLen`

The inferred template size.

`INVALID_LEN` for '*'.

#### Dox Sources

    /*!
     * @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 BamAlignmentRecord::INVALID_POS;
     *
     * @brief Static member with invalid sentinel/position value (-1).
     *
     * @var __uint32 BamAlignmentRecord::INVALID_REFID;
     *
     * @brief Static member with invalid sentinel/position value (-1).
     *
     * @var __uint32 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 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 BamAlignmentRecord::rID;
     *
     * @brief ID of reference for this fragment mapping (0-based,
     *        <tt>INVALID_REFID</tt> for '*' in SAM).
     *
     * @var __int32 BamAlignmentRecord::beginPos;
     *
     * @brief Begin position of the alignment (0-based, <tt>INVALID_POS</tt> for '0'
     *        in SAM).
     *
     * @var __uint8 BamAlignmentRecord::mapQ;
     *
     * @brief Mapping quality (255 for '*').
     *
     * @var __uint16 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 BamAlignmentRecord::rNextId;
     *
     * @brief The ID of the reference where the next fragment in this template
     *        aligns.
     *
     * <tt>INVALID_REFID</tt> for '*'.
     *
     * @var __int32 BamAlignmentRecord::pNext;
     *
     * @brief Position on the reference where the next fragment in this template
     *        aligns.
     *
     * <tt>INVALID_POS</tt> for '*'.
     *
     * @var __int32 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#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
     *
     * @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
     */