SparseString - SeqAn API Documentation

# Class SparseString
A string storing only a fraction of the values of the original string.

Defined in | <seqan/index.h>
Signature | `template <typename TValueString, typename TSpec> class SparseString;`

## Template Parameters

`TSpec` | The specialisation tag. Default: void.
`TValueString` | The type of the string containing the values.

## Interface Function Overview

- `void clear(sparseString);`
  Resets the SparseString.
- `bool empty(sparseString);`
  Returns whether or not the SparseString is empty.
- `TFibre getFibre(sparseString, fibreTag);`
  Returns a specific fibre of a SparseString.
- `TValue getValue(sparseString, pos);`
  Returns the value of a SparseString.
- `TSize length(sparseString);`
  Returns the number of elements in the SparseString.
- `bool open(string, fileName[, openMode]);`
  This functions open a sparse string from disk.
- `TSize resize(sparseString, newLength);`
  Resets the number of elements in the compressed suffix array.
- `bool save(string, fileName[, openMode]);`
  This functions saves a sparse string to disk.
- `TReference value(sparseString, pos);`
  Returns the value of a SparseString.

## Interface Functions Detail

### `void clear(sparseString);`

Resets the SparseString.

#### Parameters

`sparseString` | The SparseString to be cleared.

#### Data Races

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

### `bool empty(sparseString);`

Returns whether or not the SparseString is empty.

#### Parameters

`sparseString` | The SparseString to be checked.

#### Returns

`bool` | `true` if there are no elements in the sparse string and `false` otherwise.

#### Data Races

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

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

Returns a specific fibre of a SparseString.

#### Parameters

`sparseString` | The sparseString holding the fibre.
`fibreTag` | A tag that identifies the Fibre. Types: SparseString Fibres

#### Returns

`TFibre` | A reference to the Fibre object.

#### Data Races

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

### `TValue getValue(sparseString, pos);`

Returns the value of a SparseString.

#### Parameters

`sparseString` | The SparseString.
`pos` | The position at which a value should be assign to the sparse string. Types: UnsignedIntegerConcept

#### Returns

`TValue` | The type GetValue of SparseString is returned.

#### Data Races

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

### `TSize length(sparseString);`

Returns the number of elements in the SparseString.

#### Parameters

`sparseString` | The sparse string suffix array.

#### Returns

`TSize` | The number of elements in the sparse string array. Types: The result of Size of the sparse string.

#### Data Races

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

### `bool open(string, fileName[, openMode]);`

This functions open a sparse string from disk.

#### Parameters

`string` | The string to be opened. Types: SparseString
`fileName` | C-style character string containing the file name.
`openMode` | 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(sparseString, newLength);`

Note.

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`.``

Resets the number of elements in the compressed suffix array.

#### Parameters

`sparseString` | The sparse string.
`newLength` | The number of elements which should be stored in the sparse string. Types: UnsignedIntegerConcept.

#### Returns

`TSize` | The number of elements in the sparse string. Types: The result of Size of the sparse string.

#### Data Races

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

### `bool save(string, fileName[, openMode]);`

This functions saves a sparse string to disk.

#### Parameters

`string` | The string to be saved. Types: SparseString
`fileName` | C-style character string containing the file name.
`openMode` | 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.

### `TReference value(sparseString, pos);`

Returns the value of a SparseString.

#### Parameters

`sparseString` | The SparseString.
`pos` | The position at which a value should be assign to the sparse string. Types: UnsignedIntegerConcept

#### Returns

`TReference` | The type Reference of SparseString is returned.

#### Data Races

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

#### Dox Sources

    /*!
     * @class SparseString
     *
     * @headerfile <seqan/index.h>
     *
     * @brief A string storing only a fraction of the values of the original string.
     *
     * @signature template <typename TValueString, typename TSpec> class
     *            SparseString;
     *
     * @tparam TSpec The specialisation tag. Default: void.
     * @tparam TValueString The type of the @link String string @endlink containing
     *                      the values.
     *
     * @fn SparseString#clear
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Resets the @link SparseString @endlink.
     *
     * @signature void clear(sparseString);
     *
     * @param[in,out] sparseString The @link SparseString @endlink to be cleared.
     *
     * @fn SparseString#empty
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns whether or not the @link SparseString @endlink is empty.
     *
     * @signature bool empty(sparseString);
     *
     * @param[in] sparseString The SparseString to be checked.
     *
     * @return bool <tt>true</tt> if there are no elements in the sparse string and
     *              <tt>false</tt> otherwise.
     *
     * @fn SparseString#getValue
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns the value of a SparseString.
     *
     * @signature TValue getValue(sparseString, pos);
     *
     * @param[in] sparseString The @link SparseString @endlink.
     * @param[in] pos The position at which a value should be assign to the sparse
     *                string. Types: @link UnsignedIntegerConcept @endlink
     *
     * @return TValue The type @link GetValue @endlink of @link SparseString
     *                @endlink is returned.
     *
     * @fn SparseString#value
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns the value of a @link SparseString @endlink.
     *
     * @signature TReference value(sparseString, pos);
     *
     * @param[in] sparseString The @link SparseString @endlink.
     * @param[in] pos The position at which a value should be assign to the sparse
     *                string. Types: @link UnsignedIntegerConcept @endlink
     *
     * @return TReference The type @link Reference @endlink of @link SparseString
     *                    @endlink is returned.
     *
     * @fn SparseString#getFibre
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns a specific fibre of a @link SparseString @endlink.
     *
     * @signature TFibre getFibre(sparseString, fibreTag);
     *
     * @param[in] sparseString The sparseString holding the fibre.
     * @param[in] fibreTag A tag that identifies the @link Fibre @endlink. Types:
     *                     @link SparseStringFibres SparseString Fibres @endlink
     *
     * @return TFibre A reference to the @link Fibre @endlink object.
     *
     * @fn SparseString#length
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns the number of elements in the @link SparseString @endlink.
     *
     * @signature TSize length(sparseString);
     *
     * @param[in] sparseString The sparse string suffix array.
     *
     * @return TSize The number of elements in the sparse string array. Types: The
     *               result of @link Size @endlink of the sparse string.
     *
     * @fn SparseString#resize
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Resets the number of elements in the compressed suffix array.
     *
     * @note 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>.
     *
     * @signature TSize resize(sparseString, newLength);
     *
     * @param[in,out] sparseString The sparse string.
     * @param[in] newLength The number of elements which should be stored in the
     *                      sparse string. Types: @link UnsignedIntegerConcept
     *                      @endlink.
     *
     * @return TSize The number of elements in the sparse string. Types: The result
     *               of @link Size @endlink of the sparse string.
     *
     * @fn SparseString#open
     *
     * @headerfile <seqan/index.h>
     *
     * @brief This functions open a sparse string from disk.
     *
     * @signature bool open(string, fileName[, openMode]);
     *
     * @param[in] string The string to be opened. Types: SparseString
     * @param[in] fileName C-style character string containing the file name.
     * @param[in] openMode 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 SparseString#save
     *
     * @headerfile <seqan/index.h>
     *
     * @brief This functions saves a sparse string to disk.
     *
     * @signature bool save(string, fileName[, openMode]);
     *
     * @param[in] string The string to be saved. Types: SparseString
     * @param[in] fileName C-style character string containing the file name.
     * @param[in] openMode 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.
     */