CompressedSA - SeqAn API Documentation

# Class CompressedSA
A suffix array storing only a few suffix array entries and computing the remaining on demand.

Implements | ContainerConcept
All Impl'd | AssignableConcept, ContainerConcept, DestructibleConcept
Defined in | <seqan/index.h>
Signature | `template <typename TText, typename TSpec, typename TConfig> class CompressedSA;`

## Template Parameters

`TSpec` | Possibility to specialize a compressed suffix array. Default: void.
`TText` | The type of the text the compressed suffix array is created from. Types: String, StringSet
`TConfig` | A configuration object that can be used to change the types of the fibres easily. This possibility is provided for convenience.

## Member Function Overview

### Member Functions Inherited From AssignableConcept

- `operator=`

## Interface Function Overview

- `TIterator begin(compressedSA, tag);`
  Returns an iterator pointing to the first position of a compresses suffix array.
- `void clear(compressedSA);`
  Resets the compressed suffix array.
- `void createCompressedSa(compressedSA, completeSA, compressionFactor[, offset]);`
  This function creates a compressed suffix array with a specified compression factor.
- `bool empty(compressedSA);`
  Checks whether or not a compressed suffix array contains any elements.
- `TIterator end(compressedSA, tag);`
  Returns an iterator pointing to the position behind the last element of a compresses suffix array.
- `TFibre getFibre(compressedSA, fibreTag);`
  Returns a specific fibre of a compressed suffix array.
- `TSize length(compressedSA);`
  Returns the number of elements in the compressed suffix array.
- `bool open(compressedSA, fileName[, mode]);`
  This functions opens a compressed suffix array from disk.
- `TSize resize(compressedSA, newLength);`
  Resets the number of elements in the compressed suffix array.
- `bool save(compressedSA, fileName[, mode]);`
  This functions saves a compressed suffix array to disk.
- `void setFibre(compressedSa, lf, fibreLF);`
  Set the LF of the compressed suffix array. *
- `TValue value(compressedSA, pos);`
  Returns the value stored at a specified position in the compressed suffix-array.

### Interface Functions Inherited From AssignableConcept

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

### Interface Functions Inherited From ContainerConcept

- `writeValue`
- `write`
- `begin`
- `end`
- `length`
- `empty`
- `swap`
- `getObjectId`
- `moveValue`
- `append`
- `appendValue`
- `shrinkToFit`
- `directionIterator`

## Interface Metafunction Overview

### Interface Metafunctions Inherited From ContainerConcept

- `DefaultGetIteratorSpec`
- `DefaultIteratorSpec`
- `Difference`
- `DirectionIterator`
- `GetValue`
- `Iterator`
- `Position`
- `Reference`
- `Size`
- `Value`

## Detailed Description

### Remarks

The compressed suffix array can only be used together with a LF.

## Interface Functions Detail

### `TIterator begin(compressedSA, tag);`

Returns an iterator pointing to the first position of a compresses suffix array.

#### Parameters

`compressedSA` | The compresses suffix array to be traversed.
`tag` | The specialisation of the iterator to be returned by the function. Types: Standard, Rooted

#### Returns

`TIterator` | Returns an iterator pointing to the first position of a compresses suffix array. Types: `The result of Iterator<Index<TText, TIndexSpec>, TSpec>::Type`

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `void clear(compressedSA);`

Resets the compressed suffix array.

#### Parameters

`compressesSA` | The compressed suffix array to be cleared.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `void createCompressedSa(compressedSA, completeSA, compressionFactor[, offset]);`

This function creates a compressed suffix array with a specified compression factor.

#### Parameters

`compressedSA` | The compressed suffix array.
`completeSA` | A complete suffix array containing all values. Types: String
`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: UnsignedIntegerConcept
`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 FMIndex.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `bool empty(compressedSA);`

Checks whether or not a compressed suffix array contains any elements.

#### Parameters

`compressesSA` | The compressed suffix array to be cleared.

#### Returns

`bool` | Returns true if the compressed suffix array is empty and false otherwise.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TIterator end(compressedSA, tag);`

Returns an iterator pointing to the position behind the last element of a compresses suffix array.

#### Parameters

`compressedSA` | The compresses suffix array to be traversed.
`tag` | The specialisation of the iterator to be returned by the function. Types: Standard, Rooted

#### Returns

`TIterator` | Returns an iterator pointing to the position behind the last element of a compresses suffix array. Types: `The result of Iterator<Index<TText, TIndexSpec>, TSpec>::Type`

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TFibre getFibre(compressedSA, fibreTag);`

Returns a specific fibre of a compressed suffix array.

#### Parameters

`fibreTag` | A tag that identifies the Fibre. Types: CompressedSAFibres.
`compressedSA` | The container holding the fibre.

#### Returns

`TFibre` | A reference to the specified fibre of type Fibre<CompressedSA<TText, TSpec, TConfig>, FibreSparseString>::Type.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TSize length(compressedSA);`

Returns the number of elements in the compressed suffix array.

#### Parameters

`compressesSA` | The compressed suffix array.

#### Returns

`TSize` | The number of elements in the compressed suffix array. Types: The result of Size of the compressed suffix array.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `bool open(compressedSA, fileName[, mode]);`

This functions opens a compressed suffix array from disk.

#### Parameters

`compressedSA` | The compressed suffix array to be opened.
`fileName` | `char const *` containing the file name.
`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 `OPEN_RDONLY`, `OPEN_WRONLY`, or `OPEN_RDWR`.To create or overwrite a file add `OPEN_CREATE`. To append a file if existing add `OPEN_APPEND`. To circumvent problems, files are always opened in binary mode. Default: `OPEN_RDWR | OPEN_CREATE | OPEN_APPEND`

#### Returns

`bool` | `true` on success.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TSize resize(compressedSA, newLength);`

Resets the number of elements in the compressed suffix array.

#### Parameters

`compressesSA` | The compressed suffix array.
`newLength` | The number of elements which should be stored in the compressed suffix array. Types: UnsignedIntegerConcept.

#### Returns

`TSize` | The number of elements in the compressed suffix array. Types: The result of Size of the compressed suffix array.

If the new length is smaller than the actual one then the last `x`items of the compressed suffix array are deleted with `x = oldLength - newLength`.``

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `bool save(compressedSA, fileName[, mode]);`

This functions saves a compressed suffix array to disk.

#### Parameters

`compressedSA` | The compressed suffix array to be opened.
`fileName` | `char const *` containing the file name.
`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 `OPEN_RDONLY`, `OPEN_WRONLY`, or `OPEN_RDWR`.To create or overwrite a file add `OPEN_CREATE`. To append a file if existing add `OPEN_APPEND`. To circumvent problems, files are always opened in binary mode. Default: `OPEN_RDWR | OPEN_CREATE | OPEN_APPEND`

#### Returns

`bool` | `true` on success.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `void setFibre(compressedSa, lf, fibreLF);`

Set the LF of the compressed suffix array. *

#### Parameters

`compressesSa` | The compressed suffix array.
`lf` | The LF table to be used by the compressed suffix array.
`fibreLF` | A tag to specify the LF table Fibre

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TValue value(compressedSA, pos);`

Returns the value stored at a specified position in the compressed suffix-array.

#### Parameters

`compressedSA` | The compressed suffix array to access.
`pos` | Position at which to access the suffix array. Types: UnsignedIntegerConcept.

Note that the compressed suffix array is read only. Therefore a const reference is return by this function.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

#### Dox Sources

    /*!
     * @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&lt;CompressedSA&lt;TText, TSpec, TConfig&gt;,
     *                FibreSparseString&gt;::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&lt;Index&lt;TText, TIndexSpec&gt;,
     *                   TSpec&gt;::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&lt;Index&lt;TText, TIndexSpec&gt;,
     *                   TSpec&gt;::Type</tt>
     */