/*!
* @class FaiIndex
*
* @headerfile <seqan/seq_io.h>
*
* @brief Data structure for access to FAI indices.
*
* @signature class FaiIndex;
*
* FAI indices allow the rast random access to sequences or parts of sequences
* in a FASTA file. Originally, they were introduced in the <a
* href="http://samtools.sourceforge.net/samtools.shtml">samtools</a> program.
*
* Also see the <a href="http://seqan.readthedocs.org/en/develop/Tutorial/Indexe
* dFastaIO.html">Indexed FASTA I/O Tutorial</a>.
*
* @section Example
*
* The following example demonstrates the usage of the FaiIndex class.
*
* @include demos/seq_io/fai_index_example.cpp
*
* The output is as follows:
*
* @include demos/seq_io/fai_index_example.cpp.stdout
*
* @fn FaiIndex::FaiIndex
*
* @brief Constructor.
*
* @signature FaiIndex::FaiIndex();
*
* @fn FaiIndex#clear
*
* @brief Reset a FaiIndex object to the state after default construction.
*
* @signature void clear(faiIndex);
*
* @param[in,out] faiIndex The FaiIndex to clear.
*
* @fn FaiIndex#getIdByName
*
* @brief Return reference ID (numeric index in the file) of a sequence in a FAI
* file.
*
* @signature bool getIdByName(rID, faiIndex, name);
*
* @param[in] faiIndex The FaiIndex to query.
* @param[in] name The name of the sequence to look the id up for. Type: @link
* ContainerConcept @endlink.
* @param[out] rID The id of the sequence is written here.
*
* @return bool <tt>true</tt> if a sequence with the given name is known in the
* index, <tt>false</tt> otherwise.
*
* @fn FaiIndex#sequenceLength
*
* @brief Return length of the sequence with the given id in the FaiIndex.
*
* @signature __uint64 sequenceLength(faiIndex, rID);
*
* @param[in] faiIndex The FaiIndex to query.
* @param[in] rID The id of the sequence to get the length of.
*
* @return __uint64 The length of the sequence with index rID in faiIndex.
*
* @fn FaiIndex#sequenceName
*
* @brief Return the name of the sequence with the given id in the FaiIndex.
*
* @signature CharString sequenceName(faiIndex, rID);
*
* @param[in] faiIndex The FaiIndex to query.
* @param[in] rID The index of the sequence.
*
* @return CharString The name of the sequence with the given id.
*
* @fn FaiIndex#numSeqs
*
* @brief Return the number of sequences known to a FaiIndex.
*
* @signature __uint64 numSeqs(faiIndex);
*
* @param[in] faiIndex The FaiIndex to query.
*
* @return __uint64 The number of sequences in the index.
*
* @fn FaiIndex#readRegion
*
* @brief Read a region through an FaiIndex.
*
* @signature void readRegion(str, faiIndex, rID, beginPos, endPos);
* @signature void readRegion(str, faiIndex, region);
*
* @param[out] str The @link String @endlink to read the sequence into.
* @param[in] faiIndex The FaiIndex to read from.
* @param[in] rID The id of the sequence to read (Type: <tt>unsigned).
* @param[in] beginPos The begin position of the region to read (Type:
* <tt>unsigned).
* @param[in] endPos The end position of the region to read (Type:
* <tt>unsigned).
* @param[in] region The @link GenomicRegion @endlink to read.
*
* @fn FaiIndex#readSequence
*
* @brief Load a whole sequence from a FaiIndex.
*
* @signature void readSequence(str, faiIndex, rID);
*
* @param[out] str The @link String @endlink to read into.
* @param[in] faiIndex The FaiIndex to read from.
* @param[in] seqID The index of the sequence in the file.
*
* @fn FaiIndex#readRecord
*
* @brief Read a FAI index from file.
*
* @signature void readRecord(faiIndex, fastaFileName[, faiFileName]);
*
* @param[out] faiIndex The FaiIndex to read into.
* @param[in] fastaFileName Path to the FASTA file to read. Type: <tt>char const
* *</tt>.
* @param[in] faiFileName Path to the FAI file to read. Type: <tt>char const
* *</tt>. Defaults to <tt>"${fastaFileName}.fai"</tt>.
*
* @fn FaiIndex#open
*
* @brief Open a FaiIndex object.
*
* @signature bool open(faiIndex, fastaFilename [, faiFileName]);
*
* @param[in] faiIndex The FaiIndex to write out.
* @param[in] fastaFilename Path to the FASTA file to build an index for. Type:
* <tt>char const *</tt>.
* @param[in] faiFileName The name of the FAI file to open. This parameter is
* optional. By default, the FAI file name is derived
* from the FASTA file name. Type: <tt>char const *</tt>.
*
* @return bool <tt>true</tt> on success, <tt>false</tt> otherwise.
*
* @fn FaiIndex#save
*
* @brief Save a FaiIndex object.
*
* @signature bool save(faiIndex[, faiFileName]);
*
* @param[in] faiIndex The FaiIndex to write out.
* @param[in] faiFileName The name of the FAI file to write to. This parameter
* is optional only if the FAI index knows the FAI file
* name from a previous @link FaiIndex#build @endlink
* call. By default, the FAI file name from the previous
* call to @link FaiIndex#build @endlink is used. Type:
* <tt>char const *</tt>.
*
* @return bool <tt>true</tt> on success, <tt>false</tt> otherwise.
*
* @fn FaiIndex#build
*
* @brief Create a FaiIndex from FASTA file.
*
* @signature bool build(faiIndex, seqFileName[, faiFileName]);
*
* @param[out] faiIndex The FaiIndex to build into.
* @param[in] seqFileName Path to the FASTA file to build an index for. Type:
* <tt>char const *</tt>.
* @param[in] faiFileName Path to the FAI file to use as the index file. Type:
* <tt>char const *</tt>. Default:
* <tt>"${seqFileName}.fai"</tt>.
*
* @return bool <tt>true</tt> on success, <tt>false</tt> otherwise.
*/