TextConcept - SeqAn API Documentation

# Concept TextConcept
Concept for a type that can be as text of an index.

Defined in | <seqan/sequence.h>
Signature | `concept TextConcept;`

## Detailed Description

Certain algorithms and data structures can work for both strings and string sets but need to treat these two types slightly different. Examples are index data structures and algorithms that build the indices and use the indices for lookup.

To facilitate writing of generic algorithms, the TextConcept concept gives a common interface to both for this kind of algorithms.

## See Also

- String
- StringSet

## Interface Function Overview

- `TSeqNo getSeqNo(pos[, limits]);`
  Returns the sequence number of a position.
- `TOffset getSeqOffset(pos[, limits]);`
  Returns the local sequence offset of a position.
- `TPos posGlobalize(pos, limits)`
  Converts a local/global to a global position.
- `void posLocalize(result, pos, limits)`
  Converts a local/global to a local position.
- `void posLocalToX(dst, localPos, limits);`
  Converts a local to a local/global position.
- `TStringSetLimits stringSetLimits(text);`
  Return string delimiter positions for TextConcept types.

## Interface Metafunction Overview

- `SAValue<TText>::Type`
  The default alphabet type of a suffix array, i.e. the type to store a position of a string or string set.
- `StringSetLimits<TText>::Type;`
  Return type of string set limits for TextConcept types.

## Interface Functions Detail

### `TSeqNo getSeqNo(pos[, limits]);`

Returns the sequence number of a position.

#### Parameters

`pos` | A position. Types: Pair
`limits` | The limits string returned by stringSetLimits.

#### Returns

`TSeqNo` | A single integer value that identifies the string within the stringset `pos` points at. If `limits` is omitted or Nothing `getSeqNo` returns 0.If `pos` is a local position (of class Pair) then `i1` is returned.If `pos` is a global position (integer type and `limits` is a String) then `pos` is converted to a local position and `i1` is returned.

#### Data Races

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

### `TOffset getSeqOffset(pos[, limits]);`

Returns the local sequence offset of a position.

#### Parameters

`pos` | A position. Types: Pair
`limits` | The limits string returned by stringSetLimits.

#### Returns

`TOffset` | A single integer value that identifies the position within the string `pos` points at.If `limits` is omitted or Nothing `getSeqNo` returns `pos`. If `pos` is a local position (of class Pair) then `i2` is returned.If `pos` is a global position (integer type and `limits` is a String) then `pos` is converted to a local position and `i2` is returned.

#### Data Races

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

### `TPos posGlobalize(pos, limits)`

Converts a local/global to a global position.

#### Parameters

`pos` | A local or global position (pair or integer value). Types: Pair
`limits` | The limits string returned by stringSetLimits.

#### Returns

`TPos` | The corresponding global position of `pos`. If `pos` is an integral type `pos` is returned. If not, `limits[getSeqNo(pos, limits)] + getSeqOffset(pos, limits)` is returned.

#### Data Races

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

### `void posLocalize(result, pos, limits)`

Converts a local/global to a local position.

#### Parameters

`pos` | A local or global position (pair or integer value).
`limits` | The limits string returned by stringSetLimits.
`result` | Reference to the resulting corresponding local position of `pos`.

#### Data Races

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

### `void posLocalToX(dst, localPos, limits);`

Converts a local to a local/global position.

#### Parameters

`dst` | The local or global position (pair or integer value) is written here.
`localPos` | The local position.
`limits` | The string limits as returned by stringSetLimits.

#### Data Races

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

### `TStringSetLimits stringSetLimits(text);`

Return string delimiter positions for TextConcept types.

#### Parameters

`text` | The text to query for its string set limits.

#### Returns

`TStringSetLimits` | The string set limits (of type StringSetLimits).

#### Data Races

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

## Interface Metafunctions Detail

### `SAValue<TText>::Type`

The default alphabet type of a suffix array, i.e. the type to store a position of a string or string set.

#### Template Parameters

`TText` | The text type to query.

#### Returns

`TReturn` | A type to store a position in a `TText`. This could be an integer for strings or a pair of integers for string sets.

#### Usage

This type should be removed for functions returning positions in texts such as online or index-based search. Thus, always use this metafunction for declaring position variables.

Use the functions posLocalize, posGlobalize, getSeqNo, and getSeqOffset for conversion between local and global positions in texts.

#### Examples

The following shows the original definition of the SAValue metafunction in SeqAn.

    template <typename TString, typename TSpec>
    struct SAValue<StringSet<TString, TSpec> >
    {
        typedef Pair<
                typename Size<StringSet<TString, TSpec> >::Type,
                typename SAValue<TString>::Type,
                Pack
            > Type;
    };

### `StringSetLimits<TText>::Type;`

Return type of string set limits for TextConcept types.

#### Template Parameters

`TText` | The type of the text.

#### Returns

`Type` | The type of string set limits objects.

#### Dox Sources

    /*!
     * @concept TextConcept
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief Concept for a type that can be as text of an index.
     *
     * @signature concept TextConcept;
     *
     * Certain algorithms and data structures can work for both strings and string
     * sets but need to treat these two types slightly different. Examples are index
     * data structures and algorithms that build the indices and use the indices for
     * lookup.
     *
     * To facilitate writing of generic algorithms, the TextConcept concept gives a
     * common interface to both for this kind of algorithms.
     *
     * @see String
     * @see StringSet
     *
     * @mfn TextConcept#StringSetLimits
     *
     * @brief Return type of string set limits for TextConcept types.
     *
     * @signature StringSetLimits<TText>::Type;
     *
     * @tparam TText The type of the text.
     *
     * @return Type The type of string set limits objects.
     *
     * @mfn TextConcept#SAValue
     *
     * @brief The default alphabet type of a suffix array, i.e. the type to store a
     *        position of a string or string set.
     *
     * @signature SAValue<TText>::Type
     *
     * @tparam TText The text type to query.
     *
     * @return TReturn A type to store a position in a <tt>TText</tt>. This could be
     *                 an integer for strings or a pair of integers for string sets.
     *
     * @section Usage
     *
     * This type should be removed for functions returning positions in texts such
     * as online or index-based search. Thus, always use this metafunction for
     * declaring position variables.
     *
     * Use the functions @link TextConcept#posLocalize @endlink, @link
     * TextConcept#posGlobalize @endlink, @link TextConcept#getSeqNo @endlink, and
     * @link TextConcept#getSeqOffset @endlink for conversion between local and
     * global positions in texts.
     *
     * @section Examples
     *
     * The following shows the original definition of the SAValue metafunction in
     * SeqAn.
     *
     * @code{.cpp}
     * template <typename TString, typename TSpec>
     * struct SAValue<StringSet<TString, TSpec> >
     * {
     *     typedef Pair<
     *             typename Size<StringSet<TString, TSpec> >::Type,
     *             typename SAValue<TString>::Type,
     *             Pack
     *         > Type;
     * };
     * @endcode
     *
     *
     * @fn TextConcept#stringSetLimits
     *
     * @brief Return string delimiter positions for TextConcept types.
     *
     * @signature TStringSetLimits stringSetLimits(text);
     *
     * @param[in] text The text to query for its string set limits.
     *
     * @return TStringSetLimits The string set limits (of type @link
     *                          TextConcept#StringSetLimits @endlink).
     *
     * @fn TextConcept#posLocalToX
     *
     * @brief Converts a local to a local/global position.
     *
     * @signature void posLocalToX(dst, localPos, limits);
     *
     * @param[in] dst The local or global position (pair or integer value) is
     *                written here.
     * @param[in] localPos The local position.
     * @param[in] limits The string limits as returned by @link
     *                   TextConcept#stringSetLimits @endlink.
     *
     * @fn TextConcept#posLocalize
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief Converts a local/global to a local position.
     *
     * @signature void posLocalize(result, pos, limits)
     *
     * @param[in] pos A local or global position (pair or integer value).
     * @param[in] limits The limits string returned by @link
     *                   TextConcept#stringSetLimits @endlink.
     * @param[in] result Reference to the resulting corresponding local position of
     *                   <tt>pos</tt>.
     *
     * @fn TextConcept#posGlobalize
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief Converts a local/global to a global position.
     *
     * @signature TPos posGlobalize(pos, limits)
     *
     * @param[in] pos A local or global position (pair or integer value). Types:
     *                Pair
     * @param[in] limits The limits string returned by @link
     *                   TextConcept#stringSetLimits @endlink.
     *
     * @return TPos The corresponding global position of <tt>pos</tt>. If
     *              <tt>pos</tt> is an integral type <tt>pos</tt> is returned. If
     *              not, <tt>limits[getSeqNo(pos, limits)] + getSeqOffset(pos,
     *              limits)</tt> is returned.
     *
     * @fn TextConcept#getSeqNo
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief Returns the sequence number of a position.
     *
     * @signature TSeqNo getSeqNo(pos[, limits]);
     *
     * @param[in] pos A position. Types: Pair
     * @param[in] limits The limits string returned by @link
     *                   TextConcept#stringSetLimits @endlink.
     *
     * @return TSeqNo A single integer value that identifies the string within the
     *                stringset <tt>pos</tt> points at. If <tt>limits</tt> is
     *                omitted or @link Nothing @endlink <tt>getSeqNo</tt> returns
     *                0.If <tt>pos</tt> is a local position (of class @link Pair
     *                @endlink) then <tt>i1</tt> is returned.If <tt>pos</tt> is a
     *                global position (integer type and <tt>limits</tt> is a @link
     *                String @endlink) then <tt>pos</tt> is converted to a local
     *                position and <tt>i1</tt> is returned.
     *
     * @fn TextConcept#getSeqOffset
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief Returns the local sequence offset of a position.
     *
     * @signature TOffset getSeqOffset(pos[, limits]);
     *
     * @param[in] pos A position. Types: Pair
     * @param[in] limits The limits string returned by @link
     *                   TextConcept#stringSetLimits @endlink.
     *
     * @return TOffset A single integer value that identifies the position within
     *                 the string <tt>pos</tt> points at.If <tt>limits</tt> is
     *                 omitted or @link Nothing @endlink <tt>getSeqNo</tt> returns
     *                 <tt>pos</tt>. If <tt>pos</tt> is a local position (of class
     *                 @link Pair @endlink) then <tt>i2</tt> is returned.If
     *                 <tt>pos</tt> is a global position (integer type and
     *                 <tt>limits</tt> is a @link String @endlink) then <tt>pos</tt>
     *                 is converted to a local position and <tt>i2</tt> is returned.
     */