StringSet - SeqAn API Documentation

# Class StringSet
A container class for a set of strings.

Implements | SegmentableConcept, StringConcept, TextConcept
All Subcl's | ConcatDirectStringSet, DependentStringSet, GenerousDependentStringSet, JournaledSet, OwnerStringSet, TightDependentStringSet
All Impl'd | AssignableConcept, ContainerConcept, DestructibleConcept, ForwardContainerConcept, RandomAccessContainerConcept, ReversibleContainerConcept, SegmentableConcept, StringConcept, TextConcept
Defined in | <seqan/sequence.h>
Signature | `template <typename TString, typename TSpec> class StringSet;`

## Template Parameters

`TString` | The type of the string to store in the string set.
`TSpec` | A tag for selecting the specialization of the string set. Default: `Owner<Generous>`.

## Member Function Overview

### Member Functions Inherited From AssignableConcept

- `operator=`

### Member Functions Inherited From RandomAccessContainerConcept

- `operator[]`

## Interface Function Overview

- `void assignValue(set, pos, s);`
  Set the member of a string set by the position.
- `TId assignValueById(set, s[, id]);`
  Set the member of a string set by its id. Note: Position is the same as id for all string sets but the DependentStringSet.
- `void clear(stringSet);`
  Clear the StringSet.
- `TConcat concat(set);`
  Returns the concatenation sequence of all sequences in a string set.
- `TString getValueById(s, id);`
  Get the value from a string set by its id. Note: Position is the same as id for all string sets but the DependentStringSet.
- `TPos idToPosition(set, id);`
  Convert a string id to a position/index in the string set. Note: Position is the same as id for all string sets but the DependentStringSet.
- `TSize lengthSum(s);`
  Returns total length of all strings in the string set.
- `Id positionToId(set, pos);`
  Convert a position/index in the string set to a string id. Note: Position is the same as id for all string sets but the DependentStringSet.
- `void removeValueById(set, id);`
  Remove a value from a string set by its id. Note: Position is the same as id for all string sets but the DependentStringSet.
- `TSize reserve(s, newCapacity, tag);`
  Reserve memory for string set.
- `void strSplit(result, sequence[, sep[, allowEmptyStrings[, maxSplit]]]);`
  Split a sequence using a delimiter and append the results to a target string set
- `TString valueById(s, id);`
  Get the value from a string set by its id. Note: Position is the same as id for all string sets but the DependentStringSet.

### Interface Functions Inherited From AssignableConcept

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

### Interface Functions Inherited From ContainerConcept

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

### Interface Functions Inherited From RandomAccessContainerConcept

- `value`
- `assignValue`
- `getValue`

### Interface Functions Inherited From SegmentableConcept

- `prefix`
- `infixWithLength`
- `infix`
- `suffix`

### Interface Functions Inherited From StringConcept

- `iter`
- `append`
- `appendValue`
- `front`
- `back`
- `resize`
- `clear`
- `erase`
- `eraseFront`
- `eraseBack`
- `capacity`
- `computeGenerousCapacity`
- `insert`
- `insertValue`
- `replace`

### Interface Functions Inherited From TextConcept

- `stringSetLimits`
- `posLocalToX`
- `posLocalize`
- `posGlobalize`
- `getSeqNo`
- `getSeqOffset`

## Interface Metafunction Overview

- `Concatenator<TStringSet>::Type`
  Return the type of the concatenated sequence of all sequences in a StringSet.
- `GetSequenceByNo<TStringSet>::Type`
  Type for getting sequence by number.
- `Id<TStringSet>::Type`
  Return the id type for the string set. Note: Position is the same as id for all string sets but the DependentStringSet.
- `LengthSum<TStringSet>::Type`
  Length sum type type in string set.
- `StringSetPosition<TStringSet>::Type`
  Returns position type in string set.

### Interface Metafunctions Inherited From ContainerConcept

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

### Interface Metafunctions Inherited From SegmentableConcept

- `Infix`
- `Prefix`
- `Suffix`

### Interface Metafunctions Inherited From TextConcept

- `SAValue`
- `StringSetLimits`

## Detailed Description

String sets are containers for strings. They have two advantages over a string of strings:

First, they allow to express the common intent in Bioinformatics to have a list of strings, e.g. for the chromosomes of a genome. This facilitates writing generic data structures and algorithms to operate on single strings and genomes which is captured by the TextConcept.

Second, the DependentStringSet specialization allows one to create subsets of string sets without storing copies of strings and identifying strings by a common id.

### Examples

    #include <seqan/basic.h>
    #include <seqan/sequence.h>
    #include <seqan/stream.h>

    using namespace seqan;

    int main()
    {
        StringSet<String<char> > stringSet;
        appendValue(stringSet, "Hello World!");                    // Append string to the end of the string set.

        std::cout << "Number of elements: " << length(stringSet) << std::endl;

        resize(stringSet, 3, Exact());                             // Adapt the size of the container, while keeping existing values.

        String<char> seq = "To be or not to be!";
        stringSet[1] = seq;                                        // Use subscript operator to assign a new value.
        stringSet[2] = "A man, a plan, a canal - Panama!";

        std::cout << "Number of elements: " << length(stringSet) << std::endl;

        typedef Iterator<StringSet<String<char> >, Standard>::Type TIterator;
        for (TIterator it = begin(stringSet, Standard()); it != end(stringSet, Standard()); ++it)
            std::cout << "Element " << position(it, stringSet) << ": " << *it << std::endl;

        clear(stringSet);                                           // Clear the contents of the StringSet.

        std::cout << "Number of elements: " << length(stringSet) << std::endl;

        return 0;
    }

Demo: demos/dox/sequence/stringset.cpp

The output is as follows:

    Number of elements: 1
    Number of elements: 3
    Element 0: Hello World!
    Element 1: To be or not to be!
    Element 2: A man, a plan, a canal - Panama!
    Number of elements: 0

## Interface Functions Detail

### `void assignValue(set, pos, s);`

Set the member of a string set by the position.

#### Parameters

`set` | The string set to assign value in.
`pos` | The position to modify value at.
`s` | The string to assign to the given position.

#### Data Races

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

### `TId assignValueById(set, s[, id]);`

Set the member of a string set by its id. Note: Position is the same as id for all string sets but the DependentStringSet.

#### Parameters

`set` | The string set to assign value in.
`s` | The string set to assign.
`id` | The id of the string to set. If omitted, `s` will be appended to `set`.

#### Returns

`TId` | The id of the new string in the string set.

#### Data Races

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

### `void clear(stringSet);`

Clear the StringSet.

#### Parameters

`seedSet` | The StringSet to clear.

#### Data Races

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

### `TConcat concat(set);`

Returns the concatenation sequence of all sequences in a string set.

#### Parameters

`set` | The string set to get the concatenation sequence for.

#### Returns

`TConcat` | The concatenation sequence.

#### Data Races

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

### `TString getValueById(s, id);`

Get the value from a string set by its id. Note: Position is the same as id for all string sets but the DependentStringSet.

#### Parameters

`s` | The string set to get string from.
`id` | The id of the string to get.

#### Returns

`TString` | Reference to the string with the given id.

#### Data Races

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

### `TPos idToPosition(set, id);`

Convert a string id to a position/index in the string set. Note: Position is the same as id for all string sets but the DependentStringSet.

#### Parameters

`set` | The string to convert positions for.
`id` | The id to convert.

#### Returns

`TPos` | The resulting position.

#### Data Races

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

### `TSize lengthSum(s);`

Returns total length of all strings in the string set.

#### Parameters

`s` | The string set to get length sum of.

#### Returns

`TSize` | The sum of the lengths of all strings in the string set.

#### Data Races

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

### `Id positionToId(set, pos);`

Convert a position/index in the string set to a string id. Note: Position is the same as id for all string sets but the DependentStringSet.

#### Parameters

`set` | The string to convert positions for.
`pos` | The position to convert.

#### Returns

`TId` | The resulting id.

#### Data Races

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

### `void removeValueById(set, id);`

Remove a value from a string set by its id. Note: Position is the same as id for all string sets but the DependentStringSet.

#### Parameters

`set` | The string to remove value in.
`id` | The id of the string to remove.

#### Data Races

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

### `TSize reserve(s, newCapacity, tag);`

Reserve memory for string set.

#### Parameters

`s` | The string set to reserve memory for.
`newCapacity` | The target capacity.
`tag` | A tag to select the reservation strategy.

#### Data Races

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

### `void strSplit(result, sequence[, sep[, allowEmptyStrings[, maxSplit]]]);`

Split a sequence using a delimiter and append the results to a target string set

#### Parameters

`result` | The resulting string set (can be any ContainerOfContainer, also STL)
`sequence` | The sequence to split.
`sep` | The splitter to use (default `' '`).
`allowEmptyString` | Whether or not to allow empty strings (`bool`, defaults to `true` iff `sep` is given).
`maxSplit` | The maximal number of split operations to do if given.

#### Data Races

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

### `TString valueById(s, id);`

Get the value from a string set by its id. Note: Position is the same as id for all string sets but the DependentStringSet.

#### Parameters

`s` | The string set to get string from.
`id` | The id of the string to get.

#### Returns

`TString` | Reference to the string with the given id.

#### Data Races

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

## Interface Metafunctions Detail

### `Concatenator<TStringSet>::Type`

Return the type of the concatenated sequence of all sequences in a StringSet.

#### Template Parameters

`TStringSet` | The type of the string set.

#### Returns

`Type` | The resulting concatenator type.

### `GetSequenceByNo<TStringSet>::Type`

Type for getting sequence by number.

#### Template Parameters

`TStringSet` | The StringSet to query for its sequence-by-number type.

#### Returns

`Type` | The given sequence-by-number type.

### `Id<TStringSet>::Type`

Return the id type for the string set. Note: Position is the same as id for all string sets but the DependentStringSet.

#### Template Parameters

`TStringSet` | The string set type to query for its id type.

#### Returns

`Type` | The resulting ID type.

### `LengthSum<TStringSet>::Type`

Length sum type type in string set.

#### Template Parameters

`TStringSet` | The StringSet to query for its length sum type.

#### Returns

`Type` | The resulting length sum type.

### `StringSetPosition<TStringSet>::Type`

Returns position type in string set.

#### Template Parameters

`TStringSet` | The StringSet to query for its position type.

#### Returns

`Type` | The position type of TStringSet.

#### Dox Sources

    /*!
     * @class StringSet
     *
     * @implements StringConcept
     * @implements TextConcept
     * @implements SegmentableConcept
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief A container class for a set of strings.
     *
     * @signature template <typename TString, typename TSpec> class StringSet;
     *
     * @tparam TString The type of the string to store in the string set.
     * @tparam TSpec A tag for selecting the specialization of the string set.
     *               Default: <tt>Owner&lt;Generous&gt;</tt>.
     *
     * String sets are containers for strings. They have two advantages over a
     * string of strings:
     *
     * First, they allow to express the common intent in Bioinformatics to have a
     * list of strings, e.g. for the chromosomes of a genome. This facilitates
     * writing generic data structures and algorithms to operate on single strings
     * and genomes which is captured by the @link TextConcept @endlink.
     *
     * Second, the @link DependentStringSet @endlink specialization allows one to
     * create subsets of string sets without storing copies of strings and
     * identifying strings by a common id.
     *
     * @section Examples
     *
     * @include demos/dox/sequence/stringset.cpp
     *
     * The output is as follows:
     *
     * @include demos/dox/sequence/stringset.cpp.stdout
     *
     *
     *
     * @mfn StringSet#Concatenator
     *
     * @brief Return the type of the concatenated sequence of all sequences in a
     *        StringSet.
     *
     * @signature Concatenator<TStringSet>::Type
     *
     * @tparam TStringSet The type of the string set.
     *
     * @return Type The resulting concatenator type.
     *
     * @mfn StringSet#LengthSum
     *
     * @brief Length sum type type in string set.
     *
     * @signature LengthSum<TStringSet>::Type
     *
     * @tparam TStringSet The @link StringSet @endlink to query for its length sum
     *                    type.
     *
     * @return Type The resulting length sum type.
     *
     * @mfn StringSet#StringSetPosition
     *
     * @brief Returns position type in string set.
     *
     * @signature StringSetPosition<TStringSet>::Type
     *
     * @tparam TStringSet The @link StringSet @endlink to query for its position
     *                    type.
     *
     * @return Type The position type of TStringSet.
     *
     * @mfn StringSet#GetSequenceByNo
     *
     * @brief Type for getting sequence by number.
     *
     * @signature GetSequenceByNo<TStringSet>::Type
     *
     * @tparam TStringSet The StringSet to query for its sequence-by-number type.
     *
     * @return Type The given sequence-by-number type.
     *
     * @mfn StringSet#Id
     *
     * @brief Return the id type for the string set. Note: Position is the same as
     *        id for all string sets but the @link DependentStringSet @endlink.
     *
     * @signature Id<TStringSet>::Type
     *
     * @tparam TStringSet The string set type to query for its id type.
     *
     * @return Type The resulting ID type.
     *
     * @fn StringSet#lengthSum
     *
     * @brief Returns total length of all strings in the string set.
     *
     * @signature TSize lengthSum(s);
     *
     * @param[in] s The string set to get length sum of.
     *
     * @return TSize The sum of the lengths of all strings in the string set.
     *
     * @fn StringSet#clear
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief Clear the StringSet.
     *
     * @signature void clear(stringSet);
     *
     * @param[in,out] seedSet The StringSet to clear.
     *
     * @fn StringSet#reserve
     *
     * @brief Reserve memory for string set.
     *
     * @signature TSize reserve(s, newCapacity, tag);
     *
     * @param[in,out] s The string set to reserve memory for.
     * @param[in] newCapacity The target capacity.
     * @param[in] tag A tag to select the reservation strategy.
     *
     * @fn StringSet#getValueById
     *
     * @brief Get the value from a string set by its id. Note: Position is the same
     *        as id for all string sets but the @link DependentStringSet @endlink.
     *
     * @signature TString getValueById(s, id);
     *
     * @param[in] s The string set to get string from.
     * @param[in] id The id of the string to get.
     *
     * @return TString Reference to the string with the given id.
     *
     * @fn StringSet#valueById
     *
     * @brief Get the value from a string set by its id. Note: Position is the same
     *        as id for all string sets but the @link DependentStringSet @endlink.
     *
     * @signature TString valueById(s, id);
     *
     * @param[in] s The string set to get string from.
     * @param[in] id The id of the string to get.
     *
     * @return TString Reference to the string with the given id.
     *
     * @fn StringSet#assignValue
     *
     * @brief Set the member of a string set by the position.
     *
     * @signature void assignValue(set, pos, s);
     *
     * @param[in,out] set The string set to assign value in.
     * @param[in] pos The position to modify value at.
     * @param[in] s The string to assign to the given position.
     *
     * @fn StringSet#assignValueById
     *
     * @brief Set the member of a string set by its id. Note: Position is the same
     *        as id for all string sets but the @link DependentStringSet @endlink.
     *
     * @signature TId assignValueById(set, s[, id]);
     *
     * @param[in] set The string set to assign value in.
     * @param[in] s The string set to assign.
     * @param[in] id The id of the string to set. If omitted, <tt>s</tt> will be
     *               appended to <tt>set</tt>.
     *
     * @return TId The id of the new string in the string set.
     *
     * @fn StringSet#removeValueById
     *
     * @brief Remove a value from a string set by its id. Note: Position is the same
     *        as id for all string sets but the @link DependentStringSet @endlink.
     *
     * @signature void removeValueById(set, id);
     *
     * @param[in,out] set The string to remove value in.
     * @param[in] id The id of the string to remove.
     *
     * @fn StringSet#positionToId
     *
     * @brief Convert a position/index in the string set to a string id. Note:
     *        Position is the same as id for all string sets but the @link
     *        DependentStringSet @endlink.
     *
     * @signature Id positionToId(set, pos);
     *
     * @param[in] set The string to convert positions for.
     * @param[in] pos The position to convert.
     *
     * @return TId The resulting id.
     *
     * @fn StringSet#concat
     *
     * @brief Returns the concatenation sequence of all sequences in a string set.
     *
     * @signature TConcat concat(set);
     *
     * @param[in] set The string set to get the concatenation sequence for.
     *
     * @return TConcat The concatenation sequence.
     *
     * @fn StringSet#idToPosition
     *
     * @brief Convert a string id to a position/index in the string set. Note:
     *        Position is the same as id for all string sets but the @link
     *        DependentStringSet @endlink.
     *
     * @signature TPos idToPosition(set, id);
     *
     * @param[in] set The string to convert positions for.
     * @param[in] id The id to convert.
     *
     * @return TPos The resulting position.
     *
     * @fn StringSet#strSplit
     *
     * @brief Split a sequence using a delimiter and append the results to a target
     *        string set
     *
     * @signature void strSplit(result, sequence[, sep[, allowEmptyStrings[,
     *            maxSplit]]]);
     *
     * @param[out] result The resulting string set (can be any ContainerOfContainer,
     *                    also STL)
     * @param[in] sequence The sequence to split.
     * @param[in] sep The splitter to use (default <tt>' '</tt>).
     * @param[in] allowEmptyString Whether or not to allow empty strings
     *                             (<tt>bool</tt>, defaults to <tt>true</tt> iff
     *                             <tt>sep</tt> is given).
     * @param[in] maxSplit The maximal number of split operations to do if given.
     */