ModCyclicShape ModifiedString - SeqAn API Documentation

# Spec ModCyclicShape ModifiedString
A string leaving out don't-care-positions defined in CyclicShape.

Extends | ModifiedString
All Extended | ModifiedString
All Impl'd | AssignableConcept, ContainerConcept, DestructibleConcept
Defined in | <seqan/modifier.h>
Signature | `template <typename THost, typename TSpec> class ModifiedString<THost, ModCyclicShape<CyclicShape<TSpec> > >;`

## Template Parameters

`THost` | The host string.
`TSpec` | The specialization of CyclicShape.

## Member Function Overview

### Member Functions Inherited From AssignableConcept

- `operator=`

## Interface Function Overview

- `TIterator end(modStr[, tag]);`
  Returns an iterator to the end of the container.

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

- `Cargo<ModifiedString<THost, ModCyclicShape<CyclicShape<TSpec> > > >::Type;`
  Cargo of ModCyclicShape ModCyclicShape Modified Iterator and ModCyclicShape Modified String.

### Interface Metafunctions Inherited From ContainerConcept

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

## Detailed Description

Note:

ModCyclicShape Modifier should only be used to view/read a sequence, never to change the underlying sequence. Some operations will work, e.g. you can use the `operator*()` of the ModifiedIterator to change a character, but other operations like `replace` or `append` are unsafe or even conceptionally wrong.

Applies a CyclicShape to a string. The resulting modified string skips don't-care positions and can thus be shorter than the original string. Of course the underlying string is not changed by the modifier.

### Examples

Use case for GenericCyclicShapes:

            typedef ModifiedString<CharString, ModCyclicShape<TShape> > TModString;

            CharString str = "das ist das Haus vom Nikolaus";
            TModString modStr(str, shape);

            std::cout << str << " => " << modStr << std::endl;

Snippet from: demos/dox/modifier/cyclic_shape_snippets.cpp

Use case for FixedCyclicShapes:

            typedef ModifiedString<CharString, ModCyclicShape<TShape> > TModString;

            CharString str = "das ist das Haus vom Nikolaus";
            TModString modStr(str);

            std::cout << str << " => " << modStr << std::endl;

Snippet from: demos/dox/modifier/cyclic_shape_snippets.cpp

## See Also

- CyclicShape
- ModCyclicShapeModifiedIterator

## Interface Functions Detail

### `TIterator end(modStr[, tag]);`

Returns an iterator to the end of the container.

#### Template Parameters

`TIterator` | ModCyclicShape Modified Iterator to be returned.

#### Parameters

`modStr` | ModCyclicShape Modified String.
`An` | optional tag for selecting the type of the iterator. One of Standard and Rooted. When left out, DefaultGetIteratorSpec of `modStr` is used.

#### Returns

`Iterator` | to the end of the container, the type is selected by #Fn<>ContainerConcept#Iterator with the given (or default) tag.

The end iterator is not guaranteed to be at position `length(modStr)`, where a standard iterator ends. Due to the jumping-tequniche of ModCyclicShape Modified Iterator, the end iterator is set to the first care position after the end of the string. The invariant is: `host(end(modStr)) >= end(host(modStr))`where the the larger or equal operator refers to the position in the sequence.``

If for some reason you use the host iterator to check an end condition, make sure you use `for(...; host(modIter) >= end(host(modStr)); ...)` instead of `for(...; host(modIter) != end(host(modStr)); ...)` .

#### Data Races

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

## Interface Metafunctions Detail

### `Cargo<ModifiedString<THost, ModCyclicShape<CyclicShape<TSpec> > > >::Type;`

Cargo of ModCyclicShape ModCyclicShape Modified Iterator and ModCyclicShape Modified String.

#### Template Parameters

`THost` | Host container of ModifiedString.
`TSpec` | Specialization of CyclicShape.

#### Returns

`Cargo` | type of ModCyclicShape Modified String is the CyclicShape itself.

#### Dox Sources

    /*!
     * @class ModCyclicShapeModifiedString ModCyclicShape ModifiedString
     *
     * @extends ModifiedString
     *
     * @headerfile <seqan/modifier.h>
     *
     * @brief A string leaving out don't-care-positions defined in CyclicShape.
     *
     * @note ModCyclicShape Modifier should only be used to <b>view/read a
     *       sequence</b>, never to change the underlying sequence. Some operations
     *       will work, e.g. you can use the <tt>operator*()</tt> of the
     *       ModifiedIterator to change a character, but other operations like
     *       <tt>replace</tt> or <tt>append</tt> are unsafe or even conceptionally
     *       wrong.
     *
     * @signature template <typename THost, typename TSpec> class
     *            ModifiedString<THost, ModCyclicShape<CyclicShape<TSpec> > >;
     *
     * @tparam THost The host string.
     * @tparam TSpec The specialization of CyclicShape.
     *
     * Applies a CyclicShape to a string. The resulting modified string skips
     * don't-care positions and can thus be shorter than the original string. Of
     * course the underlying string is not changed by the modifier.
     *
     * @section Examples
     *
     * Use case for GenericCyclicShapes:
     *
     * @snippet demos/dox/modifier/cyclic_shape_snippets.cpp Define GenericCyclicShape Modified String
     *
     * Use case for FixedCyclicShapes:
     *
     * @snippet demos/dox/modifier/cyclic_shape_snippets.cpp Define FixedCyclicShape Modified String
     *
     * @see CyclicShape
     * @see ModCyclicShapeModifiedIterator
     *
     * @mfn ModCyclicShapeModifiedString#Cargo
     *
     * @headerfile <seqan/modifier.h>
     *
     * @brief Cargo of ModCyclicShape ModCyclicShape Modified Iterator and
     *        ModCyclicShape Modified String.
     *
     * @signature Cargo<ModifiedString<THost, ModCyclicShape<CyclicShape<TSpec> > >
     *            >::Type;
     *
     * @tparam THost Host container of ModifiedString.
     * @tparam TSpec Specialization of CyclicShape.
     *
     * @return Cargo type of ModCyclicShape Modified String is the CyclicShape
     *               itself.
     *
     * @fn ModCyclicShapeModifiedString#end
     *
     * @headerfile <seqan/modifier.h>
     *
     * @brief Returns an iterator to the end of the container.
     *
     * @signature TIterator end(modStr[, tag]);
     *
     * @tparam TIterator ModCyclicShape Modified Iterator to be returned.
     *
     * @param[in] modStr ModCyclicShape Modified String.
     * @param[in] An optional tag for selecting the type of the iterator. One of
     *               Standard and Rooted. When left out, @link
     *               ContainerConcept#DefaultGetIteratorSpec @endlink of
     *               <tt>modStr</tt> is used.
     *
     * @return Iterator to the end of the container, the type is selected by
     *                  #Fn<>ContainerConcept#Iterator with the given (or default)
     *                  tag.
     *
     * The end iterator is not guaranteed to be at position <tt>length(modStr)</tt>,
     * where a standard iterator ends. Due to the jumping-tequniche of
     * ModCyclicShape Modified Iterator, the end iterator is set to the first care
     * position after the end of the string. The invariant is: <tt>host(end(modStr))
     * >= end(host(modStr))<tt> where the the larger or equal operator refers to the
     * position in the sequence.
     *
     * If for some reason you use the host iterator to check an end condition, make
     * sure you use <tt> for(...; host(modIter) >= end(host(modStr)); ...) </tt>
     * instead of <tt> for(...; host(modIter) != end(host(modStr)); ...) </tt>.
     */