RankDictionary - SeqAn API Documentation

# Class RankDictionary
A rank dictionary is a data structure storing the rank of an element in a sequence at every position of the sequence. Only supports sequences containing SimpleType or bool.

All Subcl's | Levels, WaveletTree
Defined in | <seqan/index.h>
Signature | `template <typename TValue, typename TSpec> struct RankDictionary;`

## Template Parameters

`TSpec` | The rank dictionary specialisation. Default: WaveletTree, Levels.

## Interface Function Overview

- `void clear(dictionary);`
  Resets the rank dictionary.
- `void createRankDictionary(dictionary, text);`
  This functions creates the dictionary.
- `bool empty(dictionary);`
  Returns whether or not the rank dictionary is empty.
- `TFibre getFibre(dictionary, fibreTag);`
  Returns a specific fibre of a dictionary.
- `TSize countOccurrences(dictionary, pos[, character]);`
  Returns the rank of a specified character up to a specified position.
- `TValue getValue(dictionary, pos);`
  Returns the character of a specified position.
- `TSize length(dict)`
  Retruns the number of element in the rank dictionary.
- `bool open(dictionary, fileName[, openMode]);`
  This functions loads a rank dictionary from disk.
- `TSize reserve(dict, newCapacity, tag)`
  Reserves memory for a specified number of elements in the rank dictionary
- `TSize resize(dict, newLength, tag)`
  Increases the length of a rank dictionary to a specified value.
- `bool save(dictionary, fileName[, openMode]);`
  This functions saves a dictionary to disk.
- `void setValue(dictionary, pos, character);`
  Sets the character at a specified position.
- `void updateRanks(dict)`
  Updates the rank information.

## Interface Functions Detail

### `void clear(dictionary);`

Resets the rank dictionary.

#### Parameters

`dictionary` | The rank dictionary to be cleared.

#### Data Races

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

### `void createRankDictionary(dictionary, text);`

This functions creates the dictionary.

#### Parameters

`text` | A text to be transfered into a rank dictionary. Types: ContainerConcept
`dictionary` | The dictionary.

#### Data Races

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

### `bool empty(dictionary);`

Returns whether or not the rank dictionary is empty.

#### Parameters

`dictionary` | The rank dictionary to be checked.

#### Returns

`bool` | `true` if the dictionary is empty, `false` otherwise.

#### Data Races

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

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

Returns a specific fibre of a dictionary.

#### Parameters

`dictionary` | The dictionary holding the fibre.
`fibreTag` | A tag that identifies the Fibre. Types: RankDictionaryFibres.

#### Returns

`TFibre` | A reference to the Fibre object.

#### Data Races

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

### `TSize countOccurrences(dictionary, pos[, character]);`

Returns the rank of a specified character up to a specified position.

#### Parameters

`dictionary` | The dictionary.
`pos` | The position (which is also included in the rank computation).
`character` | The character of interest. Default: `true`

#### Returns

`TSize` | The rank of a specified character up to a specified position. The result of the metafunction Size<RankDictionary>::Type

#### Data Races

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

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

Returns the character of a specified position.

#### Parameters

`dictionary` | The dictionary.
`pos` | The position. Types: UnsignedIntegerConcept.

#### Returns

`TValue` | Returns the character of a specified position. The result is of type Value<RankDictionary>::Type;

#### Data Races

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

### `TSize length(dict)`

Retruns the number of element in the rank dictionary.

#### Parameters

`dict` | The RankDictionary.

#### Returns

`TSize` | The number of element in the rank dictionary. The result of the metafunction Size<RankDictionary>::Type

#### Data Races

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

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

This functions loads a rank dictionary from disk.

#### Parameters

`dictionary` | The dictionary.
`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 reserve(dict, newCapacity, tag)`

Reserves memory for a specified number of elements in the rank dictionary

#### Parameters

`dict` | The RankDictionary.
`newCapacity` | The number of elements one wants to reserve memory for.
`tag` | The tag that specifies the memory allocation strategy. Types: OverflowStrategyTags.

#### Returns

`TSize` | Retruns the number of element that could be reserved. The result of the metafunction Size<RankDictionary>::Type

#### Remarks

This operation does not changes the content of object.

This operation may invalidate iterators of object.

#### Data Races

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

### `TSize resize(dict, newLength, tag)`

Increases the length of a rank dictionary to a specified value.

#### Parameters

`dict` | The RankDictionary.
`newLength` | The number of elements the rank dictionaru contains after resizing.
`tag` | The tag that specifies the memory allocation strategy. Types: OverflowStrategyTags.

#### Returns

`TSize` | Retruns the number of element that could be reserved. The result of the metafunction Size<RankDictionary>::Type

#### Remarks

This operation may invalidate iterators of object.

#### Data Races

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

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

This functions saves a dictionary to disk.

#### Parameters

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

`TReturn` | A `bool` which is `true` on success.

#### Data Races

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

### `void setValue(dictionary, pos, character);`

Sets the character at a specified position.

#### Parameters

`dictionary` | The dictionary.
`pos` | The position. Types: UnsignedIntegerConcept.
`character` | The character to be set.

#### Data Races

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

### `void updateRanks(dict)`

Updates the rank information.

#### Parameters

`dict` | The RankDictionary.

#### Data Races

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

#### Dox Sources

    /*!
     * @class RankDictionary
     *
     * @headerfile <seqan/index.h>
     *
     * @brief A rank dictionary is a data structure storing the rank of an element
     *        in a sequence at every position of the sequence. Only supports
     *        sequences containing @link SimpleType @endlink or bool.
     *
     * @signature template <typename TValue, typename TSpec> struct RankDictionary;
     *
     * @tparam TSpec The rank dictionary specialisation. Default: @link WaveletTree
     *               @endlink, @link Levels @endlink.
     *
     * @fn RankDictionary#getFibre
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns a specific fibre of a dictionary.
     *
     * @signature TFibre getFibre(dictionary, fibreTag);
     *
     * @param[in] dictionary The dictionary holding the fibre.
     * @param[in] fibreTag A tag that identifies the @link Fibre @endlink. Types:
     *                     @link RankDictionaryFibres @endlink.
     *
     * @return TFibre A reference to the @link Fibre @endlink object.
     *
     * @fn RankDictionary#clear
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Resets the rank dictionary.
     *
     * @signature void clear(dictionary);
     *
     * @param[in,out] dictionary The rank dictionary to be cleared.
     *
     * @fn RankDictionary#empty
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns whether or not the rank dictionary is empty.
     *
     * @signature bool empty(dictionary);
     *
     * @param[in] dictionary The rank dictionary to be checked.
     *
     * @return bool <tt>true</tt> if the dictionary is empty, <tt>false</tt>
     *              otherwise.
     *
     * @fn RankDictionary#createRankDictionary
     *
     * @headerfile <seqan/index.h>
     *
     * @brief This functions creates the dictionary.
     *
     * @signature void createRankDictionary(dictionary, text);
     *
     * @param[in] text A text to be transfered into a rank dictionary. Types: @link
     *                 ContainerConcept @endlink
     * @param[out] dictionary The dictionary.
     *
     * @fn RankDictionary#getRank
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns the rank of a specified character up to a specified position.
     *
     * @signature TSize countOccurrences(dictionary, pos[, character]);
     *
     * @param[in] dictionary The dictionary.
     * @param[in] pos The position (which is also included in the rank computation).
     * @param[in] character The character of interest. Default: <tt>true</tt>
     *
     * @return TSize The rank of a specified character up to a specified position.
     *               The result of the metafunction Size&lt;RankDictionary&gt;::Type
     *
     * @fn RankDictionary#getValue
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns the character of a specified position.
     *
     * @signature TValue getValue(dictionary, pos);
     *
     * @param[in] dictionary The dictionary.
     * @param[in] pos The position. Types: @link UnsignedIntegerConcept @endlink.
     *
     * @return TValue Returns the character of a specified position. The result is
     *                of type Value&lt;RankDictionary&gt;::Type;
     *
     * @fn RankDictionary#setValue
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Sets the character at a specified position.
     *
     * @signature void setValue(dictionary, pos, character);
     *
     * @param[in] dictionary The dictionary.
     * @param[in] pos The position. Types: @link UnsignedIntegerConcept @endlink.
     * @param[in] character The character to be set.
     *
     * @fn RankDictionary#updateRanks
     *
     * @brief Updates the rank information.
     *
     * @signature void updateRanks(dict)
     *
     * @param dict The @link RankDictionary @endlink.
     *
     * @fn RankDictionary#length
     *
     * @brief Retruns the number of element in the rank dictionary.
     *
     * @signature TSize length(dict)
     *
     * @param dict The @link RankDictionary @endlink.
     *
     * @return TSize The number of element in the rank dictionary. The result of the
     *               metafunction Size&lt;RankDictionary&gt;::Type
     *
     * @fn RankDictionary#reserve
     *
     * @brief Reserves memory for a specified number of elements in the rank
     *        dictionary
     *
     * @signature TSize reserve(dict, newCapacity, tag)
     *
     * @param dict The @link RankDictionary @endlink.
     * @param newCapacity The number of elements one wants to reserve memory for.
     * @param tag The tag that specifies the memory allocation strategy. Types:
     *            @link OverflowStrategyTags @endlink.
     *
     * @return TSize Retruns the number of element that could be reserved. The
     *               result of the metafunction Size&lt;RankDictionary&gt;::Type
     *
     * @section Remarks
     *
     * This operation does not changes the content of object.
     *
     * This operation may invalidate iterators of object.
     *
     * @fn RankDictionary#resize
     *
     * @brief Increases the length of a rank dictionary to a specified value.
     *
     * @signature TSize resize(dict, newLength, tag)
     *
     * @param dict The @link RankDictionary @endlink.
     * @param newLength The number of elements the rank dictionaru contains after
     *                  resizing.
     * @param tag The tag that specifies the memory allocation strategy. Types:
     *            @link OverflowStrategyTags @endlink.
     *
     * @return TSize Retruns the number of element that could be reserved. The
     *               result of the metafunction Size&lt;RankDictionary&gt;::Type
     *
     * @section Remarks
     *
     * This operation may invalidate iterators of object.
     *
     * @fn RankDictionary#open
     *
     * @headerfile <seqan/index.h>
     *
     * @brief This functions loads a rank dictionary from disk.
     *
     * @signature bool open(dictionary, fileName[, openMode]);
     *
     * @param[in,out] dictionary The dictionary.
     * @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 RankDictionary#save
     *
     * @headerfile <seqan/index.h>
     *
     * @brief This functions saves a dictionary to disk.
     *
     * @signature bool save(dictionary, fileName[, openMode]);
     *
     * @param[in] dictionary The dictionary.
     * @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 TReturn A <tt>bool</tt> which is <tt>true</tt> on success.
     */