/*!
* @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://trac.seqan.de/wiki/Tutorial/IndexedFastaIO">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 id (numeric index in the file) of a sequence in a FAI file.
*
* @signature bool getIdByName(faiIndex, name, id);
*
* @param[in] faiIndex The FaiIndex to query.
* @param[in] name The name of the sequence to look the id up for. Type: @link
* SequenceConcept @endlink.
* @param[out] id The id of the sequence is written here.
*
* @return bool true if a reference with the given name is known in the index.
*
* @fn FaiIndex#sequenceLength
*
* @brief Return length of the sequence with the given id in the FaiIndex.
*
* @signature __uint64 sequenceLength(faiIndex, refId);
*
* @param[in] faiIndex The FaiIndex to query.
* @param[in] refId The id of the sequence to get the length of.
*
* @return __uint64 The length of the sequence with index refId in faiIndex.
*
* @fn FaiIndex#sequenceName
*
* @brief Return the name of the sequence with th egiven id in the FaiIndex.
*
* @signature CharString sequenceName(faiIndex, refId);
*
* @param[in] faiIndex The FaiIndex to query.
* @param[in] refId 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 int readRegion(str, faiIndex, refId, beginPos, endPos);
* @signature int 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] refId The id of the reference 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.
*
* @return int 0 on success, non-0 on errors.
*
* @fn FaiIndex#readSequence
*
* @brief Load a whole sequence from a FaiIndex.
*
* @signature int readSequence(str, faiIndex, refId);
*
* @param[out] str The @link String @endlink to read into.
* @param[in] faiIndex The FaiIndex to read from.
* @param[in] refID The index of the sequence in the file.
*
* @return int 0 on success, non-0 on errors.
*
* @fn FaiIndex#read
*
* @brief Read a FAI index from file.
*
* @signature int read(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>.
*
* @return int 0 on success, non-0 on errors.
*
* @fn FaiIndex#write
*
* @brief Write out an FaiIndex object.
*
* @signature int write(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 int 0 on success, 1 on errors.
*
* @fn FaiIndex#build
*
* @brief Create a FaiIndex from FASTA file.
*
* @signature int 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 int 0 on success, non-0 on errors.
*/