# Class CyclicShape
A pattern of zeros and ones to mark "don't care"-positions in a text.

All Subcl's | FixedCyclicShape, GenericCyclicShape
Defined in | <seqan/modifier.h>
Signature | `template <typename TShapeSpec> class CyclicShape<TShapeSpec>;`

## Template Parameters

`TShapeSpec` | The specializing type. Default is GenericShape, another option is FixedShape.
`TSize` | Size type of the CyclicShape

## Interface Function Overview

- `void carePositions(positions, cyclicShape);`
  Determine the indices of care positions in the range [0,span)
- `void cyclicShapeToString(bitmap, cyclicShape);`
  Print a given cyclic shape as a sequence of '1' (care position) and '0' (don't-care position).
- `void cyclicShapeToSuffixLengths(TString suffLengths, cyclicShape);`
  Calculates the number of characters of modified Strings shorter than the Shape's span.
- `TSize weight(const & cyclicShape);`
  Return the weight of a CyclicShape

## Interface Metafunction Overview

- `Size<CyclicShape<TSpec> >::Type;`
  Size type for parameters used in CyclicShape.

## Member Variable Overview

- `TSize CyclicShape::loffset`
  left offset (number of leading zeros) of the CyclicShape.
- `TSize CyclicShape::span`
  span of the CyclicShape.

## Detailed Description

CyclicShapes store a pattern like `11010100110` that mark care (match) positions and don't-care positions. Unlike Shape, the CyclicShape does not perform hashing of q-grams. It is instead useful to modify a text in such a way that zero position are ignored. The pattern is applied repeatedly on the whole text, as the example shows.

Note that CyclicShapes can start and end with zero characters, which is not allowed in Shape.

### Examples

    #include <seqan/modifier.h>
    #include <seqan/stream.h>

    using namespace seqan;

    int main(int argc, char const ** argv)
    {
        // create a (generic) CyclicShape
        typedef CyclicShape<GenericShape> TShape;
        TShape shape;
        stringToCyclicShape(shape, "1110010");

        // print cyclic Shape
        CharString out;
        cyclicShapeToString(out, shape);
        std::cout << "shape: " << out << std::endl;

        // determine weight and span
        std::cout << "weight: " << (int)weight(shape);
        std::cout << ", span: " << (int)shape.span << std::endl;

        // modify a text to leave out characters
        CharString str = "this is an original string";
        ModifiedString<CharString, ModCyclicShape<TShape> > modStr(str, shape);

        // modStr can be used like a normal String
        std::cout << str << " => " << modStr << std::endl;
        std::cout << "length: " << length(str) << " => " << length(modStr) << std::endl;

        return 0;
    }

Demo: demos/dox/modifier/cyclic_shape.cpp

The output is as follows:

    shape: 1110010
    weight: 4, span: 7
    this is an original string => thii anrgin tri
    length: 26 => 15

## See Also

- ModCyclicShapeModifiedIterator
- ModCyclicShapeModifiedString

## Interface Functions Detail

### `void carePositions(positions, cyclicShape);`

Determine the indices of care positions in the range [0,span)

#### Template Parameters

`TString` | String or array. Value type should be an integral size type.
`TSpec` | Specialization of CyclicShape.

#### Parameters

`cyclicShape` | CyclicShape object.
`positions` | The resulting String to store the care-positions in. Type TString.

This function can be used to convert `CyclicShape.diffs`, which stores the distances between care positions, to a `positions` string directly containing the care positions. See the example:

            std::cout << std::endl << "relative care positions: ";
            for (unsigned i = 0; i < weight(shape); ++i)
                std::cout << (int)shape.diffs[i] << ",";    // output: 1,1,3,2,4,

            std::cout << std::endl << "absolute care positions: ";
            String<int> carePos;
            carePositions(carePos, shape);

            for (unsigned i = 0; i < weight(shape); ++i)
                std::cout << carePos[i] << ",";             // output: 2,3,4,7,9,
            std::cout << std::endl;

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

#### Data Races

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

### `void cyclicShapeToString(bitmap, cyclicShape);`

Print a given cyclic shape as a sequence of '1' (care position) and '0' (don't-care position).

#### Parameters

`cyclicShape` | CyclicShape object. Types: CyclicShape
`bitmap` | The resulting sequence object. Type: String, e.g. CharString

#### Data Races

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

#### See Also

- stringToCyclicShape

### `void cyclicShapeToSuffixLengths(TString suffLengths, cyclicShape);`

Calculates the number of characters of modified Strings shorter than the Shape's span.

#### Template Parameters

`TString` | String type or array with an integral value type, i.e. unsigned or int.

#### Parameters

`cyclicShape` | CyclicShape object.
`suffLengths` | String to be filled. Must be resized beforehands. Fixed length arrays also work.

Given a CyclicShape, this function calculates a how many characters a String of length x contains after the CyclicShape is applied to it. This is done for all `0 <= x < span`. `suffLengths` therefore must be resized to the shape's span beforehands. The resizing is not done in this function so that it can be applied to arrays, too.

#### Data Races

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

### `TSize weight(const & cyclicShape);`

Return the weight of a CyclicShape

#### Template Parameters

`TSpec` | Specialisation of the CyclicShape.
`TSize` | Size type of CyclicShape

#### Parameters

`cyclicShape` | CyclicShape object

#### Returns

`weight` | of the CyclicShape (number of care positions)

#### Data Races

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

## Interface Metafunctions Detail

### `Size<CyclicShape<TSpec> >::Type;`

Size type for parameters used in CyclicShape.

#### Template Parameters

`TSpec` | The CyclicShape specialization.

#### Returns

`TReturn` | Currently the return type `unsigned char`.

#### Remarks

## Member Variables Detail

### `TSize CyclicShape::loffset`

left offset (number of leading zeros) of the CyclicShape.

### `TSize CyclicShape::span`

span of the CyclicShape.

#### Dox Sources

    /*!
     * @class CyclicShape
     *
     * @headerfile <seqan/modifier.h>
     *
     * @brief A pattern of zeros and ones to mark "don't care"-positions in a text.
     *
     * @signature template <typename TShapeSpec> class CyclicShape<TShapeSpec>;
     *
     * @tparam TShapeSpec The specializing type. Default is @link GenericCyclicShape
     *                    GenericShape @endlink, another option is @link
     *                    FixedCyclicShape FixedShape @endlink.
     * @tparam TSize Size type of the CyclicShape
     *
     * CyclicShapes store a pattern like <tt>11010100110</tt> that mark care (match)
     * positions and don't-care positions. Unlike @link Shape @endlink, the
     * CyclicShape does not perform hashing of q-grams. It is instead useful to
     * modify a text in such a way that zero position are ignored. The pattern is
     * applied repeatedly on the whole text, as the example shows.
     *
     * Note that CyclicShapes can start and end with zero characters, which is not
     * allowed in @link Shape @endlink.
     *
     * @section Examples
     *
     * @include demos/dox/modifier/cyclic_shape.cpp
     *
     * The output is as follows:
     *
     * @include demos/dox/modifier/cyclic_shape.cpp.stdout
     *
     * @see ModCyclicShapeModifiedString
     * @see ModCyclicShapeModifiedIterator
     *
     * @mfn CyclicShape#Size
     *
     * @headerfile <seqan/modifier.h>
     *
     * @brief Size type for parameters used in CyclicShape.
     *
     * @signature Size<CyclicShape<TSpec> >::Type;
     *
     * @tparam TSpec The CyclicShape specialization.
     *
     * @return TReturn Currently the return type <tt>unsigned char</tt>.
     *
     * @section Remarks
     *
     * @var TSize CyclicShape::span;
     *
     * @brief span of the CyclicShape.
     *
     * @var TSize CyclicShape::loffset;
     *
     * @brief left offset (number of leading zeros) of the CyclicShape.
     *
     * @fn CyclicShape#weight
     *
     * @headerfile <seqan/modifier.h>
     *
     * @brief Return the weight of a CyclicShape
     *
     * @signature TSize weight(const & cyclicShape);
     *
     * @tparam TSpec Specialisation of the CyclicShape.
     * @tparam TSize Size type of CyclicShape
     *
     * @param[in] cyclicShape CyclicShape object
     *
     * @return weight of the CyclicShape (number of care positions)
     *
     * @fn CyclicShape#cyclicShapeToString
     *
     * @brief Print a given cyclic shape as a sequence of '1' (care position) and
     *        '0' (don't-care position).
     *
     * @signature void cyclicShapeToString(bitmap, cyclicShape);
     *
     * @param[in] cyclicShape CyclicShape object. Types: @link CyclicShape @endlink
     * @param[out] bitmap The resulting sequence object. Type: @link String
     *                    @endlink, e.g. CharString
     *
     * @see GenericCyclicShape#stringToCyclicShape
     *
     * @fn CyclicShape#carePositions
     *
     * @brief Determine the indices of care positions in the range <i>[0,span)</i>
     *
     * @signature void carePositions(positions, cyclicShape);
     *
     * @tparam TString String or array. Value type should be an integral size type.
     * @tparam TSpec Specialization of CyclicShape.
     *
     * @param[in] cyclicShape CyclicShape object.
     * @param[out] positions The resulting @link String @endlink to store the care-
     *                       positions in. Type TString.
     *
     * This function can be used to convert <tt>CyclicShape.diffs</tt>, which stores
     * the distances between care positions, to a <tt>positions</tt> string directly
     * containing the care positions. See the example:
     *
     * @snippet demos/dox/modifier/cyclic_shape_snippets.cpp CyclicShape Care Positions
     *
     *
     *
     * @fn CyclicShape#cyclicShapeToSuffixLengths
     *
     * @brief Calculates the number of characters of modified Strings shorter than
     *        the Shape's span.
     *
     * @signature void cyclicShapeToSuffixLengths(TString suffLengths, cyclicShape);
     *
     * @tparam TString String type or array with an integral value type, i.e.
     *                 unsigned or int.
     *
     * @param[in] cyclicShape CyclicShape object.
     * @param[in,out] suffLengths String to be filled. Must be resized beforehands.
     *                            Fixed length arrays also work.
     *
     * Given a CyclicShape, this function calculates a how many characters a String
     * of length <i>x</i> contains after the CyclicShape is applied to it. This is
     * done for all <tt>0 <= x < span</tt>. <tt>suffLengths</tt> therefore must be
     * resized to the shape's span beforehands. The resizing is not done in this
     * function so that it can be applied to arrays, too.
     */