RankSupportBitString - SeqAn API Documentation

# Class RankSupportBitString
A bit string supporting rank queries in constant time.

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

## Template Parameters

`TSpec` | Specialisation tag. Default: void

## Interface Function Overview

- `appendValue(bitString, bit)`
  Appends a bit to a RankSupportBitString.
- `clear(bitString)`
  Resets an rank-support-bit string.
- `bool empty(bitString)`
  Checks whether or not a rank-support-bit string contains any elements.
- `getFibre(bitString, fibreTag)`
  Returns a specific fibre of a rank-support-bit string.
- `getRank(bitString, pos)`
  Returns the rank (the number of bits set from the start of the bit string) of a specified position.
- `isSetBit(bitString, pos)`
  Returns whether the bit with the given index is set to 1.
- `length(bitString)`
  Returns the number of bits in the rank-support-bit string.
- `open(bitString, fileName [, openMode])`
  This functions opens a RankSupportBitString from disk.
- `TSize resize(bitString, newLenght)`
  Resets the number of bits in the rank-support-bit string.
- `save(bitString, fileName [, openMode])`
  This functions saves a RankSupportBitString to disk.
- `setBitTo(bitString, pos, value)`
  Set the bit with the given position to the given value.

## Detailed Description

The constant rank query time is achieved by evaluating precomputed subsolutions. In order to do so, the bit string is divided into blocks of length l. A super block string stores for each block of l blocks the number of bits set from the beginning. In addition a block string stores the number of bits set in each block from the start of the last super block block. Therefore it is possible to compute the result of a rank query in constant time by adding information from the bit, block and super block string.

## Interface Functions Detail

### `appendValue(bitString, bit)`

Appends a bit to a RankSupportBitString.

#### Parameters

`target` | A container. Types: RankSupportBitString
`bit` | Value that is appended to `target`.If the value is different from 0 it is interpreted as 1. Types: UnsignedIntegerConcept, bool

#### Data Races

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

### `clear(bitString)`

Resets an rank-support-bit string.

#### Parameters

`bitString` | The bit string to be cleared.

#### Data Races

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

### `bool empty(bitString)`

Checks whether or not a rank-support-bit string contains any elements.

#### Parameters

`bitString` | The rank-support-bit string to be checked.

#### Returns

`bool` | Returns true if the rank-support-bit string is empty and false otherwise.

#### Data Races

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

### `getFibre(bitString, fibreTag)`

Returns a specific fibre of a rank-support-bit string.

#### Parameters

`fibreTag` | A tag that identifies the Fibre. Types: RankSupportBitString Fibres.
`bitString` | The rank-support-bit string holding the fibre.

#### Returns

`TReturn` | A reference to the Fibre object.

#### Data Races

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

### `getRank(bitString, pos)`

Returns the rank (the number of bits set from the start of the bit string) of a specified position.

#### Parameters

`bitString` | The bit string. Types: RankSupportBitString
`pos` | Position of a bit.

#### Returns

`TReturn` | Value of Fibre of the rank-support-bit string.

#### Data Races

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

### `isSetBit(bitString, pos)`

Returns whether the bit with the given index is set to 1.

#### Parameters

`bitString` | The bit string.
`pos` | Position of the bit. Types: UnsignedIntegerConcept

#### Returns

`TReturn` | Returns whether a specified bit is set or not.

#### Data Races

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

### `length(bitString)`

Returns the number of bits in the rank-support-bit string.

#### Parameters

`bitString` | The rank-support-bit string.

#### Returns

`TReturn` | Types: Value of Fibre of the rank-support-bit string.

#### Data Races

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

### `open(bitString, fileName [, openMode])`

This functions opens a RankSupportBitString from disk.

#### Parameters

`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`
`bitString` | The bit string to be opened.
`fileName` | C-style character string containing the file name.

#### Returns

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

#### Data Races

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

### `TSize resize(bitString, newLenght)`

Resets the number of bits in the rank-support-bit string.

#### Parameters

`bitString` | The rank-support-bit string.
`newLength` | The number of elements which should be stored in the compressed suffix array. Types: UnsignedIntegerConcept.

#### Returns

`TSize` | The number of elements in the rank-support-bit string. Types: The result of Size of the rank-support-bit string.

#### Note If the new length is smaller than the actual one then the last `x`items of the rank-support-bit string are deleted with x = oldLength - newLength.``

#### Data Races

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

### `save(bitString, fileName [, openMode])`

This functions saves a RankSupportBitString to disk.

#### Parameters

`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`
`bitString` | The bit string to be saved.
`fileName` | C-style character string containing the file name.

#### Returns

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

#### Data Races

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

### `setBitTo(bitString, pos, value)`

Set the bit with the given position to the given value.

#### Parameters

`pos` | Position of the bit. Types: UnsignedIntegerConcept
`bitString` | The bit string.
`bit` | The value of the bit. Note that values different from 0 are interpreted as 1.

#### Returns

`TReturn` | `void`

#### Examples

#### Data Races

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

#### See Also

- isBitSet

#### Dox Sources

    /*!
     * @class RankSupportBitString
     *
     * @headerfile <seqan/index.h>
     *
     * @brief A bit string supporting rank queries in constant time.
     *
     * @signature template <typename TSpec> class RankSupportBitString;
     *
     * @tparam TSpec Specialisation tag. Default: void
     *
     * The constant rank query time is achieved by evaluating precomputed
     * subsolutions. In order to do so, the bit string is divided into blocks of
     * length l. A super block string stores for each block of l blocks the number
     * of bits set from the beginning. In addition a block string stores the number
     * of bits set in each block from the start of the last super block block.
     * Therefore it is possible to compute the result of a rank query in constant
     * time by adding information from the bit, block and super block string.
     *
     * @fn RankSupportBitString#appendValue
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief Appends a bit to a @link RankSupportBitString @endlink.
     *
     * @signature appendValue(bitString, bit)
     *
     * @param target A container. Types: RankSupportBitString
     * @param bit Value that is appended to <tt>target</tt>.If the value is
     *            different from 0 it is interpreted as 1. Types: @link
     *            UnsignedIntegerConcept @endlink, bool
     *
     * @fn RankSupportBitString#clear
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Resets an rank-support-bit string.
     *
     * @signature clear(bitString)
     *
     * @param bitString The bit string to be cleared.
     *
     * @fn RankSupportBitString#getRank
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns the rank (the number of bits set from the start of the bit
     *        string) of a specified position.
     *
     * @signature getRank(bitString, pos)
     *
     * @param bitString The bit string. Types: @link RankSupportBitString @endlink
     * @param pos Position of a bit.
     *
     * @return TReturn @link Value @endlink of @link Fibre @endlink of the rank-
     *                 support-bit string.
     *
     * @fn RankSupportBitString#empty
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Checks whether or not a rank-support-bit string contains any elements.
     *
     * @signature bool empty(bitString)
     *
     * @param bitString The rank-support-bit string to be checked.
     *
     * @return bool Returns true if the rank-support-bit string is empty and false
     *              otherwise.
     *
     * @fn RankSupportBitString#isBitSet
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns whether the bit with the given index is set to 1.
     *
     * @signature isSetBit(bitString, pos)
     *
     * @param bitString The bit string.
     * @param pos Position of the bit. Types: @link UnsignedIntegerConcept @endlink
     *
     * @return TReturn Returns whether a specified bit is set or not.
     *
     * @fn RankSupportBitString#getFibre
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns a specific fibre of a rank-support-bit string.
     *
     * @signature getFibre(bitString, fibreTag)
     *
     * @param fibreTag A tag that identifies the @link Fibre @endlink. Types: @link
     *                 RankSupportBitStringFibres RankSupportBitString Fibres
     *                 @endlink.
     * @param bitString The rank-support-bit string holding the fibre.
     *
     * @return TReturn A reference to the @link Fibre @endlink object.
     *
     * @fn RankSupportBitString#length
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns the number of bits in the rank-support-bit string.
     *
     * @signature length(bitString)
     *
     * @param bitString The rank-support-bit string.
     *
     * @return TReturn Types: @link Value @endlink of @link Fibre @endlink of the
     *                 rank-support-bit string.
     *
     * @fn RankSupportBitString#resize
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Resets the number of bits in the rank-support-bit string.
     *
     * @signature TSize resize(bitString, newLenght)
     *
     * @param bitString The rank-support-bit string.
     * @param 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 rank-support-bit string. Types:
     *               The result of @link Size @endlink of the rank-support-bit
     *               string.
     *
     * @section Note If the new length is smaller than the actual one then the last
     *          <tt>x<tt> items of the rank-support-bit string are deleted with x =
     *          oldLength - newLength.
     *
     * @fn RankSupportBitString#setBitTo
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Set the bit with the given position to the given value.
     *
     * @signature setBitTo(bitString, pos, value)
     *
     * @param pos Position of the bit. Types: @link UnsignedIntegerConcept @endlink
     * @param bitString The bit string.
     * @param bit The value of the bit. Note that values different from 0 are
     *            interpreted as 1.
     *
     * @return TReturn <tt>void</tt>
     *
     * @section Examples
     *
     * @see RankSupportBitString#isBitSet
     *
     * @fn RankSupportBitString#open
     *
     * @headerfile <seqan/index.h>
     *
     * @brief This functions opens a @link RankSupportBitString @endlink from disk.
     *
     * @signature open(bitString, fileName [, openMode])
     *
     * @param 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>
     * @param bitString The bit string to be opened.
     * @param fileName C-style character string containing the file name.
     *
     * @return TReturn A <tt>bool</tt> which is <tt>true</tt> on success.
     *
     * @fn RankSupportBitString#save
     *
     * @headerfile <seqan/index.h>
     *
     * @brief This functions saves a @link RankSupportBitString @endlink to disk.
     *
     * @signature save(bitString, fileName [, openMode])
     *
     * @param 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>
     * @param bitString The bit string to be saved.
     * @param fileName C-style character string containing the file name.
     *
     * @return TReturn A <tt>bool</tt> which is <tt>true</tt> on success.
     */