/*!
* @class CompressedSA
*
* @implements ContainerConcept
*
* @headerfile <seqan/index.h>
*
* @brief A suffix array storing only a few suffix array entries and computing
* the remaining on demand.
*
* @signature template <typename TText, typename TSpec, typename TConfig> class
* CompressedSA;
*
* @tparam TSpec Possibility to specialize a compressed suffix array. Default:
* void.
* @tparam TText The type of the text the compressed suffix array is created
* from. Types: @link String @endlink, @link StringSet @endlink
* @tparam TConfig A configuration object that can be used to change the types
* of the fibres easily. This possibility is provided for
* convenience.
*
* @section Remarks
*
* The compressed suffix array can only be used together with a @link LF
* @endlink.
*
* @fn CompressedSA#clear
*
* @headerfile <seqan/index.h>
*
* @brief Resets the compressed suffix array.
*
* @signature void clear(compressedSA);
*
* @param[in,out] compressesSA The compressed suffix array to be cleared.
*
* @fn CompressedSA#empty
*
* @headerfile <seqan/index.h>
*
* @brief Checks whether or not a compressed suffix array contains any elements.
*
* @signature bool empty(compressedSA);
*
* @param[in] compressesSA The compressed suffix array to be cleared.
*
* @return bool Returns true if the compressed suffix array is empty and false
* otherwise.
*
* @fn CompressedSA#createCompressedSa
*
* @headerfile <seqan/index.h>
*
* @brief This function creates a compressed suffix array with a specified
* compression factor.
*
* @signature void createCompressedSa(compressedSA, completeSA,
* compressionFactor[, offset]);
*
* @param[out] compressedSA The compressed suffix array.
* @param[in] completeSA A complete suffix array containing all values. Types:
* @link String @endlink
* @param[in] compressionFactor The compression factor. A compression factor of
* x means that the compressed suffix array
* specifically stores a value for every x values
* in the complete suffix array. Types: @link
* UnsignedIntegerConcept @endlink
* @param[in] offset The offset determines how many empty values should be
* inserted into the compressed suffix array at the beginning.
* This possibility accounts for the sentinel positions of the
* @link FMIndex @endlink.
*
* @fn CompressedSA#getFibre
*
* @headerfile <seqan/index.h>
*
* @brief Returns a specific fibre of a compressed suffix array.
*
* @signature TFibre getFibre(compressedSA, fibreTag);
*
* @param[in] fibreTag A tag that identifies the @link Fibre @endlink. Types:
* @link CompressedSAFibres @endlink.
* @param[out] compressedSA The container holding the fibre.
*
* @return TFibre A reference to the specified fibre of type @link Fibre
* @endlink<CompressedSA<TText, TSpec, TConfig>,
* FibreSparseString>::Type.
*
* @fn CompressedSA#setFibre
*
* @headerfile <seqan/index.h>
*
* @brief Set the LF of the compressed suffix array. *
*
* @signature void setFibre(compressedSa, lf, fibreLF);
*
* @param[in] compressesSa The compressed suffix array.
* @param[in] lf The LF table to be used by the compressed suffix array.
* @param[in] fibreLF A tag to specify the LF table Fibre
*
* @fn CompressedSA#length
*
* @headerfile <seqan/index.h>
*
* @brief Returns the number of elements in the compressed suffix array.
*
* @signature TSize length(compressedSA);
*
* @param[in] compressesSA The compressed suffix array.
*
* @return TSize The number of elements in the compressed suffix array. Types:
* The result of @link Size @endlink of the compressed suffix
* array.
*
* @fn CompressedSA#resize
*
* @headerfile <seqan/index.h>
*
* @brief Resets the number of elements in the compressed suffix array.
*
* @signature TSize resize(compressedSA, newLength);
*
* @param[in,out] compressesSA The compressed suffix array.
* @param[in] newLength The number of elements which should be stored in the
* compressed suffix array. Types: @link
* UnsignedIntegerConcept @endlink.
*
* @return TSize The number of elements in the compressed suffix array. Types:
* The result of @link Size @endlink of the compressed suffix
* array.
*
* If the new length is smaller than the actual one then the last <tt>x<tt>
* items of the compressed suffix array are deleted with <tt>x = oldLength -
* newLength</tt>.
*
* @fn CompressedSA#value
*
* @brief Returns the value stored at a specified position in the compressed
* suffix-array.
*
* @signature TValue value(compressedSA, pos);
*
* @param[in] compressedSA The compressed suffix array to access.
* @param[in] pos Position at which to access the suffix array. Types: @link
* UnsignedIntegerConcept @endlink.
*
* Note that the compressed suffix array is read only. Therefore a const
* reference is return by this function.
*
* @fn CompressedSA#open
*
* @headerfile <seqan/index.h>
*
* @brief This functions opens a compressed suffix array from disk.
*
* @signature bool open(compressedSA, fileName[, mode]);
*
* @param[in,out] compressedSA The compressed suffix array to be opened.
* @param[in] fileName <tt>char const *</tt> containing the file name.
* @param[in] mode The combination of flags defining how the file should be
* opened. To open a file read-only, write-only or to read and
* write use <tt>OPEN_RDONLY</tt>, <tt>OPEN_WRONLY</tt>, or
* <tt>OPEN_RDWR</tt>.To create or overwrite a file add
* <tt>OPEN_CREATE</tt>. To append a file if existing add
* <tt>OPEN_APPEND</tt>. To circumvent problems, files are
* always opened in binary mode. Default: <tt>OPEN_RDWR |
* OPEN_CREATE | OPEN_APPEND</tt>
*
* @return bool <tt>true</tt> on success.
*
* @fn CompressedSA#save
*
* @headerfile <seqan/index.h>
*
* @brief This functions saves a compressed suffix array to disk.
*
* @signature bool save(compressedSA, fileName[, mode]);
*
* @param[in,out] compressedSA The compressed suffix array to be opened.
* @param[in] fileName <tt>char const *</tt> containing the file name.
* @param[in] mode The combination of flags defining how the file should be
* opened. To open a file read-only, write-only or to read and
* write use <tt>OPEN_RDONLY</tt>, <tt>OPEN_WRONLY</tt>, or
* <tt>OPEN_RDWR</tt>.To create or overwrite a file add
* <tt>OPEN_CREATE</tt>. To append a file if existing add
* <tt>OPEN_APPEND</tt>. To circumvent problems, files are
* always opened in binary mode. Default: <tt>OPEN_RDWR |
* OPEN_CREATE | OPEN_APPEND</tt>
*
* @return bool <tt>true</tt> on success.
*
* @fn CompressedSA#begin
*
* @headerfile <seqan/index.h>
*
* @brief Returns an iterator pointing to the first position of a compresses
* suffix array.
*
* @signature TIterator begin(compressedSA, tag);
*
* @param[in] compressedSA The compresses suffix array to be traversed.
* @param[in] tag The specialisation of the iterator to be returned by the
* function. Types: @link ContainerIteratorTags#Standard
* @endlink, @link ContainerIteratorTags#Rooted @endlink
*
* @return TIterator Returns an iterator pointing to the first position of a
* compresses suffix array. Types: <tt>The result of
* Iterator<Index<TText, TIndexSpec>,
* TSpec>::Type</tt>
*
* @fn CompressedSA#end
*
* @headerfile <seqan/index.h>
*
* @brief Returns an iterator pointing to the position behind the last element
* of a compresses suffix array.
*
* @signature TIterator end(compressedSA, tag);
*
* @param[in] compressedSA The compresses suffix array to be traversed.
* @param[in] tag The specialisation of the iterator to be returned by the
* function. Types: @link ContainerIteratorTags#Standard
* @endlink, @link ContainerIteratorTags#Rooted @endlink
*
* @return TIterator Returns an iterator pointing to the position behind the
* last element of a compresses suffix array. Types: <tt>The
* result of Iterator<Index<TText, TIndexSpec>,
* TSpec>::Type</tt>
*/