Dependent StringSet - SeqAn API Documentation

# Spec Dependent StringSet
StringSet implementation that only stores pointers to strings in other string sets.

Extends | StringSet
All Extended | StringSet
All Subcl's | GenerousDependentStringSet, 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<TString, Depedent<TSpec> >;`

## Template Parameters

`TString` | The type of the string to store in the string set.
`TSpec` | Tag for further specializing the string set.

## Member Function Overview

### Member Functions Inherited From AssignableConcept

- `operator=`

### Member Functions Inherited From RandomAccessContainerConcept

- `operator[]`

## Interface Function Overview

### Interface Functions Inherited From StringSet

- `assignValue`
- `assignValueById`
- `clear`
- `concat`
- `getValueById`
- `idToPosition`
- `lengthSum`
- `positionToId`
- `removeValueById`
- `reserve`
- `strSplit`
- `valueById`

### 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

### Interface Metafunctions Inherited From StringSet

- `Concatenator`
- `GetSequenceByNo`
- `Id`
- `LengthSum`
- `StringSetPosition`

### 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

Important: This is an abstract class. Use one of the following specializations: TightDependentStringSet and GenerousDependentStringSet.

A Dependent StringSet (DSS) can be used like a normal StringSet while internally storing only pointers to a source set.

### Modifying a Dependent StringSet

(1) Removing a sequence from a DSS only removes the pointer and does not change the source set.

(2) Appending a sequence to a DSS appends a pointer to that sequence and does not change the source set.

(3) Assigning a sequence to a position (or id) of a DSS, dereferences the pointer first and does thus additionally change the source set.

(4) Accessing the DSS at a position (or id) dereferences the pointer, and when stored as a reference, modifications also lead to a change in the source set.

### Position vs. Id

When a sequence is removed in a DSS, the positions of pointers shift and do not represent the exact position in the original source set anymore. To distinguish between new and original positions, we introduce the term `id` which refers to the original positions in the source set. Every modification of a DSS can be either based on the id (function ending on `ById()`) or the position depending on the behaviour you want to realize.

The following figure illustrates the behaviour when removing a sequence:

### Tight vs. Generous

The two different specializations `Tight` and `Generous` provide the same functionality but behave slightly different concerning run time and certain errors (e.g. index out of range). See the correspoinding documentation pages TightDependentStringSet and GenerousDependentStringSet for further details.

#### Dox Sources

    /*!
     * @class DependentStringSet Dependent StringSet
     *
     * @extends StringSet
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief StringSet implementation that only stores pointers to strings in other
     *        string sets.
     *
     * @signature template <typename TString, typename TSpec> class
     *            StringSet<TString, Depedent<TSpec> >;
     *
     * @tparam TString The type of the string to store in the string set.
     * @tparam TSpec Tag for further specializing the string set.
     *
     * Important: This is an abstract class. Use one of the following
     * specializations: @link TightDependentStringSet @endlink and @link
     * GenerousDependentStringSet @endlink.
     *
     * A Dependent StringSet (DSS) can be used like a normal StringSet while
     * internally storing only pointers to a source set.
     *
     * @section Modifying a Dependent StringSet
     *
     * (1) Removing a sequence from a DSS only removes the pointer and does not
     * change the source set.
     *
     * (2) Appending a sequence to a DSS appends a pointer to that sequence and does
     * not change the source set.
     *
     * (3) Assigning a sequence to a position (or id) of a DSS, dereferences the
     * pointer first and does thus additionally change the source set.
     *
     * (4) Accessing the DSS at a position (or id) dereferences the pointer, and
     * when stored as a reference, modifications also lead to a change in the source
     * set.
     *
     * @section Position vs. Id
     *
     * When a sequence is removed in a DSS, the positions of pointers shift and do
     * not represent the exact position in the original source set anymore. To
     * distinguish between new and original positions, we introduce the term
     * <tt>id</tt> which refers to the original positions in the source set. Every
     * modification of a DSS can be either based on the id (function ending on
     * <tt>ById()</tt>) or the position depending on the behaviour you want to
     * realize.
     *
     * The following figure illustrates the behaviour when removing a sequence:
     *
     * <img src="position_vs_id.png" title="Impact to positions and ids on removal
     * of an entry in an DSS" width="900">
     *
     * @section Tight vs. Generous
     *
     * The two different specializations <tt>Tight</tt> and <tt>Generous</tt>
     * provide the same functionality but behave slightly different concerning run
     * time and certain errors (e.g. index out of range). See the correspoinding
     * documentation pages @link TightDependentStringSet @endlink and @link
     * GenerousDependentStringSet @endlink for further details.
     */