# Spec BamFileIn
Class for reading SAM and BAM files.

Extends | FormattedFileIn
All Extended | FormattedFile, FormattedFileIn
Defined in | <seqan/bam_io.h>
Signature | `typedef FormattedFile<Bam, Input> BamFileIn;`

## Member Function Overview

### Member Functions Inherited From FormattedFile

- `getFileExtensions`
- `operatorTDependentContext`

## Interface Function Overview

- `bool jumpToOrphans(bamFileIn, hasAlignments, index);`
  Seek to orphans block in BamFileIn using an index.
- `bool jumpToRegion(bamFileIn, hasAlignments, refID, pos, posEnd, index);`
  Seek in BamFileIn using an index.

### Interface Functions Inherited From FormattedFile

- `atEnd`
- `close`
- `context`
- `format`
- `FormattedFile`
- `getFileExtensions`
- `guessFormat`
- `open`
- `setFormat`

### Interface Functions Inherited From FormattedFileIn

- `readHeader`
- `readRecord`

## Interface Metafunction Overview

### Interface Metafunctions Inherited From FormattedFile

- `FileFormat`
- `FormattedFileContext`

## Detailed Description

### Example

Access SAM or BAM files.

    #include <seqan/bam_io.h>

    using namespace seqan;

    int main()
    {
        CharString bamFileName = getAbsolutePath("demos/tutorial/sam_and_bam_io/example.sam");

        // Open input file, BamFileIn can read SAM and BAM files.
        BamFileIn bamFileIn;
        if (!open(bamFileIn, toCString(bamFileName)))
        {
            std::cerr << "ERROR: Could not open " << bamFileName << std::endl;
            return 1;
        }
        // Open output file, BamFileOut accepts also an ostream and a format tag.
        BamFileOut bamFileOut(context(bamFileIn), std::cout, Sam());

        try
        {
            // Copy header.
            BamHeader header;
            readHeader(header, bamFileIn);
            writeHeader(bamFileOut, header);

            // Copy records.
            BamAlignmentRecord record;
            while (!atEnd(bamFileIn))
            {
                readRecord(record, bamFileIn);
                writeRecord(bamFileOut, record);
            }
        }
        catch (Exception const & e)
        {
            std::cout << "ERROR: " << e.what() << std::endl;
            return 1;
        }

        return 0;
    }

Demo: demos/tutorial/sam_and_bam_io/solution1.cpp

The output is as follows:

    @HD	VN:1.3	SO:coordinate
    @SQ	SN:ref	LN:45
    @SQ	SN:ref2	LN:40
    r001	163	ref	7	30	8M4I4M1D3M	=	37	39	TTAGATAAAGAGGATACTG	*	XX:B:S,12561,2,20,112
    r002	0	ref	9	30	1S2I6M1P1I1P1I4M2I	*	0	0	AAAAGATAAGGGATAAA	*
    r003	0	ref	9	30	5H6M	*	0	0	AGCTAA	*
    r004	0	ref	16	30	6M14N1I5M	*	0	0	ATAGCTCTCAGC	*
    r003	16	ref	29	30	6H5M	*	0	0	TAGGC	*
    r001	83	ref	37	30	9M	=	7	-39	CAGCGCCAT	*

## See Also

- BamAlignmentRecord
- BamHeader

## Interface Functions Detail

### `bool jumpToOrphans(bamFileIn, hasAlignments, index);`

Seek to orphans block in BamFileIn using an index.

#### Parameters

`bamFileIn` | The BamFileIn object to jump with.
`hasAlignments` | A `bool` that is set to true if there are any orphans.
`index` | The BamIndex to use for jumping.

#### Data Races

Thread safety unknown!

### `bool jumpToRegion(bamFileIn, hasAlignments, refID, pos, posEnd, index);`

Seek in BamFileIn using an index.

#### Parameters

`bamFileIn` | The BamFileIn to jump with.
`hasAlignments` | A `bool` that is set true if the region `[pos, posEnd)` has any alignments.
`refID` | The reference id to jump to (`int32_t`).
`pos` | The begin of the region to jump to (`int32_t`).
`posEnd` | The end of the region to jump to (`int32_t`).
`index` | The BamIndex to use for the jumping.

#### Returns

`bool` | true if seeking was successful, false if not.

You provide a region `[pos, posEnd)` on the reference `refID` that you want to jump to and the function jumps to the first alignment in this region, if any.

#### Remarks

This function fails if `refID`/`pos` are invalid.

#### Data Races

Thread safety unknown!

#### Dox Sources

    /*!
     * @class BamFileIn
     *
     * @extends FormattedFileIn
     *
     * @headerfile <seqan/bam_io.h>
     *
     * @brief Class for reading SAM and BAM files.
     *
     * @signature typedef FormattedFile<Bam, Input> BamFileIn;
     *
     * @section Example
     *
     * Access SAM or BAM files.
     *
     * @include demos/tutorial/sam_and_bam_io/solution1.cpp
     *
     * The output is as follows:
     *
     * @include demos/tutorial/sam_and_bam_io/example.sam
     *
     *
     *
     * @see BamHeader
     * @see BamAlignmentRecord
     *
     * @fn BamFileIn#jumpToRegion
     *
     * @brief Seek in BamFileIn using an index.
     *
     * @signature bool jumpToRegion(bamFileIn, hasAlignments, refID, pos, posEnd,
     *            index);
     *
     * @param[in,out] bamFileIn The @link BamFileIn @endlink to jump with.
     * @param[out] hasAlignments A <tt>bool</tt> that is set true if the region
     *                           <tt>[pos, posEnd)</tt> has any alignments.
     * @param[in] refID The reference id to jump to (<tt>int32_t</tt>).
     * @param[in] pos The begin of the region to jump to (<tt>int32_t</tt>).
     * @param[in] posEnd The end of the region to jump to (<tt>int32_t</tt>).
     * @param[in] index The @link BamIndex @endlink to use for the jumping.
     *
     * @return bool true if seeking was successful, false if not.
     *
     * You provide a region <tt>[pos, posEnd)</tt> on the reference <tt>refID</tt>
     * that you want to jump to and the function jumps to the first alignment in
     * this region, if any.
     *
     * @section Remarks
     *
     * This function fails if <tt>refID</tt>/<tt>pos</tt> are invalid.
     *
     * @fn BamFileIn#jumpToOrphans
     *
     * @brief Seek to orphans block in BamFileIn using an index.
     *
     * @signature bool jumpToOrphans(bamFileIn, hasAlignments, index);
     *
     * @param[in,out] bamFileIn The @link BamFileIn @endlink object to jump with.
     * @param[out] hasAlignments A <tt>bool</tt> that is set to true if there are
     *                           any orphans.
     * @param[in] index The @link BamIndex @endlink to use for jumping.
     */