StringConcept - SeqAn API Documentation

# Concept StringConcept
Sequences are dense linear containers that have positions.

Extends | RandomAccessContainerConcept
All Extended | AssignableConcept, ContainerConcept, DestructibleConcept, ForwardContainerConcept, RandomAccessContainerConcept, ReversibleContainerConcept
Defined in | <seqan/basic.h>
Signature | `StringConcept<T>`

## Member Function Overview

### Member Functions Inherited From AssignableConcept

- `operator=`

### Member Functions Inherited From RandomAccessContainerConcept

- `operator[]`

## Interface Function Overview

- `void append(seq, other);`
  Append a sequence to another one.
- `void appendValue(seq, val);`
  Append a value to a sequence.
- `TReference back(seq);`
  Return reference to the last element.
- `TSize capacity(seq);`
  Returns the capacity of a sequence.
- `void clear(seq);`
  Remove all elements from the sequences.
- `TSize computeGenerousCapacity(seq, capacity);`
  Capacity for generous expansion.
- `void erase(seq, pos[, posEnd)`
  Erase an element or a range of elements from a sequence.
- `void eraseBack(seq);`
  Erase last element in a sequence.
- `void eraseFront(seq);`
  Erase first element in a sequence.
- `TReference front(seq);`
  Return reference to the first element.
- `void insert(seq, pos, src[, tag]);`
  Inserts a sequence into another sequence.
- `void insertValue(seq, pos, val[, tag]);`
  Inserts an element into a sequence.
- `TIterator iter(seq, pos[, tag]);`
  Iterator to the item at the given position in a container.
- `void replace(target, posBegin, posEnd, source[, limit][, resizeTag]);`
  Replaces a part of a sequence with another sequence.
- `void resize(seq, len[, val]);`
  Resize a sequence.

### Interface Functions Inherited From AssignableConcept

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

### Interface Functions Inherited From ContainerConcept

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

### Interface Functions Inherited From RandomAccessContainerConcept

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

## Interface Metafunction Overview

### Interface Metafunctions Inherited From ContainerConcept

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

## Interface Functions Detail

### `void append(seq, other);`

Append a sequence to another one.

#### Parameters

`seq` | The sequence to append the other sequence to.
`other` | The other sequence to append to `seq`. Of same type as `seq`.

#### Data Races

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

### `void appendValue(seq, val);`

Append a value to a sequence.

#### Parameters

`seq` | The sequence to append a value to (type `TSequence`).
`val` | A value to append to the sequence. Convertible to `Value<TSequence>::Type`.

#### Data Races

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

### `TReference back(seq);`

Return reference to the last element.

#### Parameters

`seq` | The sequence to get the last element of.

#### Returns

`TReference` | A reference to the last element of `seq`.

#### Data Races

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

### `TSize capacity(seq);`

Returns the capacity of a sequence.

#### Parameters

`seq` | The sequence to query for its capacity.

#### Returns

`TSize` | Returns the capacity of the sequence. `TSize` is the result of `Size<TSequence>::type` where `TSequence` is the type of `seq`.

The size of a sequence can never exceed its capacity but some container support resizing of the capacity. Some functions do that implicitely if they are called with a suitable tag. The function reserve can be used to change the capacity explicitely.

#### Data Races

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

### `void clear(seq);`

Remove all elements from the sequences.

#### Parameters

`seq` | Sequence to clear.

#### Data Races

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

### `TSize computeGenerousCapacity(seq, capacity);`

Capacity for generous expansion.

#### Parameters

`seq` | The sequence to compute the generous capacity for.
`capacity` | The minimal required capacity.

#### Returns

`TSize` | A value larger than `capacity` that should be used as the new capacity for `container` when it is expanded using the `Generous` overflow strategy.

#### Data Races

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

### `void erase(seq, pos[, posEnd)`

Erase an element or a range of elements from a sequence.

#### Parameters

`seq` | Sequence to remove range from.
`pos` | Begin position of the range to remove.
`posEnd` | Optional end position of the range to remove. If omitted, `pos + 1` is used.

#### Data Races

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

### `void eraseBack(seq);`

Erase last element in a sequence.

#### Parameters

`seq` | The sequence to remove the last element from.

#### Data Races

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

### `void eraseFront(seq);`

Erase first element in a sequence.

#### Parameters

`seq` | The sequence to remove the first element from.

#### Data Races

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

### `TReference front(seq);`

Return reference to the first element.

#### Parameters

`seq` | The sequence to get the first element of.

#### Returns

`TReference` | A reference to the first element of `seq`.

#### Data Races

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

### `void insert(seq, pos, src[, tag]);`

Inserts a sequence into another sequence.

#### Parameters

`seq` | The sequence to insert element sinto.
`pos` | The position to start inserting at.
`src` | The sequence to insert at pos.
`tag` | The resize tag, defaults to what `OverflowStrategyImplicit` returns.

#### Data Races

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

### `void insertValue(seq, pos, val[, tag]);`

Inserts an element into a sequence.

#### Parameters

`seq` | The sequence to insert element into.
`pos` | The position to insert at.
`val` | The value to insert at `pos` into `seq``.`
`tag` | The resize tag, defaults to what `OverflowStrategyImplicit` returns.

#### Data Races

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

### `TIterator iter(seq, pos[, tag]);`

Iterator to the item at the given position in a container.

#### Parameters

`seq` | The sequence to get the iterator for.
`pos` | The position to get the iterator for.
`tag` | The tag to pick the type of the iterator.

#### Returns

`TIterator` | The resulting iterator. If `TTag` is the type of `tag` and `TSequence` the type of `seq` then TIterator is of the type `Iterator<TSequence, TTag>::Type`.

#### Remarks

If `pos` is out of range then the iterator is invalid.

#### Data Races

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

### `void replace(target, posBegin, posEnd, source[, limit][, resizeTag]);`

Replaces a part of a sequence with another sequence.

#### Parameters

`target` | The sequence to modify.
`posBegin` | The begin position of the range to replace.
`posEnd` | The end position of the range to replace.
`source` | The source sequence to replace `[posBegin, posEnd)` with.
`limit` | Largest size of `target` after the operation.
`resizeTag` | Specify the resizing behaviour. Defaults to what `DefaultOverflowImplicit` returns.

#### Data Races

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

### `void resize(seq, len[, val]);`

Resize a sequence.

#### Parameters

`seq` | Sequence to resize.
`len` | Length to resize `seq` to.
`val` | When increasing the size, `val` is used to fill new entries. When omitted, `TValue()` is used where `TValue` is the Value type of the sequence.

#### Data Races

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

#### Dox Sources

    /*!
     * @concept StringConcept
     *
     * @headerfile <seqan/basic.h>
     *
     * @extends RandomAccessContainerConcept
     *
     * @brief Sequences are dense linear containers that have positions.
     *
     * @signature StringConcept<T>
     *
     * @fn StringConcept#iter
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief Iterator to the item at the given position in a container.
     *
     * @signature TIterator iter(seq, pos[, tag]);
     *
     * @param[in] seq The sequence to get the iterator for.
     * @param[in] pos The position to get the iterator for.
     * @param[in] tag The tag to pick the type of the iterator.
     *
     * @return TIterator The resulting iterator. If <tt>TTag</tt> is the type of
     *                   <tt>tag</tt> and <tt>TSequence</tt> the type of
     *                   <tt>seq</tt> then TIterator is of the type
     *                   <tt>Iterator&lt;TSequence, TTag&gt;::Type</tt>.
     *
     * @section Remarks
     *
     * If <tt>pos</tt> is out of range then the iterator is invalid.
     *
     * @fn StringConcept#append
     *
     * @brief Append a sequence to another one.
     *
     * @signature void append(seq, other);
     *
     * @param[in,out] seq The sequence to append the other sequence to.
     * @param[in] other The other sequence to append to <tt>seq</tt>. Of same type
     *                  as <tt>seq</tt>.
     *
     * @fn StringConcept#appendValue
     *
     * @brief Append a value to a sequence.
     *
     * @signature void appendValue(seq, val);
     *
     * @param[in,out] seq The sequence to append a value to (type
     *                    <tt>TSequence</tt>).
     * @param[in] val A value to append to the sequence. Convertible to
     *                <tt>Value&lt;TSequence&gt;::Type</tt>.
     *
     * @fn StringConcept#front
     *
     * @brief Return reference to the first element.
     *
     * @signature TReference front(seq);
     *
     * @param[in] seq The sequence to get the first element of.
     *
     * @return TReference A reference to the first element of <tt>seq</tt>.
     *
     * @fn StringConcept#back
     *
     * @brief Return reference to the last element.
     *
     * @signature TReference back(seq);
     *
     * @param[in] seq The sequence to get the last element of.
     *
     * @return TReference A reference to the last element of <tt>seq</tt>.
     *
     * @fn StringConcept#resize
     *
     * @brief Resize a sequence.
     *
     * @signature void resize(seq, len[, val]);
     *
     * @param[in,out] seq Sequence to resize.
     * @param[in] len Length to resize <tt>seq</tt> to.
     * @param[in] val When increasing the size, <tt>val</tt> is used to fill new
     *                entries. When omitted, <tt>TValue()</tt> is used where
     *                <tt>TValue</tt> is the @link ContainerConcept#Value @endlink
     *                type of the sequence.
     *
     * @fn StringConcept#clear
     *
     * @brief Remove all elements from the sequences.
     *
     * @signature void clear(seq);
     *
     * @param[in,out] seq Sequence to clear.
     *
     * @fn StringConcept#erase
     *
     * @brief Erase an element or a range of elements from a sequence.
     *
     * @signature void erase(seq, pos[, posEnd)
     *
     * @param[in,out] seq Sequence to remove range from.
     * @param[in] pos Begin position of the range to remove.
     * @param[in] posEnd Optional end position of the range to remove. If omitted,
     *                   <tt>pos + 1</tt> is used.
     *
     * @fn StringConcept#eraseFront
     *
     * @brief Erase first element in a sequence.
     *
     * @signature void eraseFront(seq);
     *
     * @param[in,out] seq The sequence to remove the first element from.
     *
     * @fn StringConcept#eraseBack
     *
     * @brief Erase last element in a sequence.
     *
     * @signature void eraseBack(seq);
     *
     * @param[in,out] seq The sequence to remove the last element from.
     *
     * @fn StringConcept#capacity
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief Returns the capacity of a sequence.
     *
     * @signature TSize capacity(seq);
     *
     * @param[in] seq The sequence to query for its capacity.
     *
     * @return TSize Returns the capacity of the sequence. <tt>TSize</tt> is the
     *               result of <tt>Size&lt;TSequence&gt;::type</tt> where
     *               <tt>TSequence</tt> is the type of <tt>seq</tt>.
     *
     * The size of a sequence can never exceed its capacity but some container
     * support resizing of the capacity. Some functions do that implicitely if they
     * are called with a suitable @link OverflowStrategyTags tag @endlink. The
     * function reserve can be used to change the capacity explicitely.
     *
     * @fn StringConcept#computeGenerousCapacity
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief Capacity for generous expansion.
     *
     * @signature TSize computeGenerousCapacity(seq, capacity);
     *
     * @param[in,out] seq The sequence to compute the generous capacity for.
     * @param[in] capacity The minimal required capacity.
     *
     * @return TSize A value larger than <tt>capacity</tt> that should be used as
     *               the new capacity for <tt>container</tt> when it is expanded
     *               using the <tt>Generous</tt> overflow strategy.
     *
     * @fn StringConcept#insert
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief Inserts a sequence into another sequence.
     *
     * @signature void insert(seq, pos, src[, tag]);
     *
     * @param[in,out] seq The sequence to insert element sinto.
     * @param[in] pos The position to start inserting at.
     * @param[in] src The sequence to insert at pos.
     * @param[in] tag The resize tag, defaults to what
     *                <tt>OverflowStrategyImplicit</tt> returns.
     *
     * @fn StringConcept#insertValue
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief Inserts an element into a sequence.
     *
     * @signature void insertValue(seq, pos, val[, tag]);
     *
     * @param[in,out] seq The @link StringConcept sequence @endlink to insert
     *                    element into.
     * @param[in] pos The position to insert at.
     * @param[in] val The value to insert at <tt>pos</tt> into <tt>seq<tt/>.
     * @param[in] tag The resize tag, defaults to what
     *                <tt>OverflowStrategyImplicit</tt> returns.
     *
     * @fn StringConcept#replace
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief Replaces a part of a sequence with another sequence.
     *
     * @signature void replace(target, posBegin, posEnd, source[, limit][,
     *            resizeTag]);
     *
     * @param[in,out] target The sequence to modify.
     * @param[in] posBegin The begin position of the range to replace.
     * @param[in] posEnd The end position of the range to replace.
     * @param[in] source The source sequence to replace <tt>[posBegin, posEnd)</tt>
     *                   with.
     * @param[in] limit Largest size of <tt>target</tt> after the operation.
     * @param[in] resizeTag Specify the resizing behaviour. Defaults to what
     *                      <tt>DefaultOverflowImplicit</tt> returns.
     */