Gaps - SeqAn API Documentation

# Class Gaps
Store the gapped version of a sequence.

Implements | ContainerConcept
All Subcl's | AnchorGaps, ArrayGaps
All Impl'd | AssignableConcept, ContainerConcept, DestructibleConcept
Defined in | <seqan/align.h>
Signature | `template <typename TSequence, typename TSpec> class Gaps;`

## Template Parameters

`TSequence` | The type of the underlying sequence.
`TSpec` | Tag for specialization.

## Member Function Overview

### Member Functions Inherited From AssignableConcept

- `operator=`

## Interface Function Overview

- `void assignSource(gaps, seq);`
  Assign the source of a gaps object, copying data.
- `TPos beginPosition(gaps);`
  Return the clipping begin position as a source position.
- `void clearClipping(gaps);`
  Clear clipping from Gaps objects.
- `void clearGaps(gaps);`
  Clear gaps from Gaps objects.
- `TPos clippedBeginPosition(gaps);`
  Return begin position of the clipping.
- `TPos clippedEndPosition(gaps);`
  Return end position of the clipping.
- `void clipSemiGlobal(global, local);`
  Clip the Gaps objects to reflect a semi-global alignment.
- `void copyClipping(dest, source);`
  Copy clipping information from one Gaps object to another.
- `void copyGaps(dest, source);`
  Copy gaps from one Gaps object to another (in the clipped view of both arguments).
- `TSize countCharacters(gaps, viewPos[, dir]);`
  The number of characters following a position.
- `TSize countGapExtensions(gaps);`
  The number of gap extensions.
- `TSize countGapOpens(gaps);`
  The number of gap openings.
- `TSize countGaps(gaps, viewPos[, dir]);`
  The number of gaps following a position.
- `TSize countLeadingGaps(gaps);`
  The number of leading gaps.
- `TSize countTrailingGaps(gaps);`
  The number of trailing gaps.
- `TPos endPosition(gaps);`
  Return the clipping end position as a source position.
- `void insertGap(gaps, viewPos);`
  Insert one gap character.
- `void insertGaps(gaps, viewPos, count);`
  Insert gap characters.
- `bool isCharacter(gaps, viewPos);`
  Query positions in a Gaps object for being a character.
- `bool isGap(gaps, viewPos);`
  Query positions in a Gaps object for being a gap.
- `TIterator iter(gaps, viewPos[, tag]);`
  Return an iterator to a specific position in the current clipping.
- `TSize length(gaps);`
  Return number of gap and characters between the beginning and the end of the clipping.
- `TSize removeGap(gaps, viewPos);`
  Remove one gap from a Gaps object.
- `TSize removeGaps(gaps, viewPos, count);`
  Remove gaps from a Gaps object.
- `void setBeginPosition(gaps, sourcePos);`
  Set the begin position of the clipped gapped sequence, given a source position.
- `void setClippedBeginPosition(gaps, unclippedViewPos);`
  Set the begin position of the clipping.
- `void setClippedEndPosition(gaps, unclippedViewPos);`
  Set the end position of the clipping.
- `void setEndPosition(gaps, sourcePos);`
  Set the end position of the clipped gapped sequence, given a source position.
- `TSource source(gaps);`
  Return underlying object.
- `TPos toSourcePosition(gaps, viewPos);`
  Conversion from view position (including gaps and clipping) to source (without gaps or clipping).
- `TPos toViewPosition(gaps, sourcePos);`
  Conversion from source (without gaps or clipping) to view position (including gaps and clipping).
- `TSize unclippedLength(gaps);`
  Return length of the gapped sequence without clipping.

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

### Interface Metafunctions Inherited From ContainerConcept

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

## Detailed Description

Gaps wrap a Sequence and allows one to (1) insert gaps into the sequence and (2) select an infix of the gapped sequence (clipping). The gaps are not inserted into the underlying sequence (source) but stored separately. Using the clipping is optional and meant for selecting parts of the alignment as a part of the result of a local alignment algorithm.

In the figure above, the source sequence has seven characters, the gapped sequence has four gaps and thus consists of eleven characters. The gapped sequence is clipped to start at position 0 in the gapped sequence and to end at position 8 in the gapped sequence (the positions given as half-open intervals `[begin, end)`).

The figure shows the three coordinate systems that are used with Gaps objects. The source position is the position in the underlying sequence. The unclipped view position is the position in the gapped sequence without gaps. The view position is the position in the gapped sequence but including the clipping: All (clipped) view positions have the clipping begin position subtracted from them.

### Examples

The following example shows the construction of the gaps object from the image above together with some calls to `toViewPosition` and `toSourcePosition`.

    #include <seqan/align.h>
    #include <seqan/basic.h>
    #include <seqan/stream.h>  // for printing Seqan strings

    using namespace seqan;

    int main()
    {
        Dna5String seq = "CGGTATC";

        // Construct the gaps object.
        Gaps<Dna5String> gaps(seq);

        // Insert gaps (view position, unclipped as of yet).  Note that inserting
        // the gaps changes the coordinates.
        insertGap(gaps, 3);
        insertGap(gaps, 5);
        insertGaps(gaps, 7, 2);

        // Clip the gaps object.  Note that the coordinates are in unclipped view position.
        setClippedBeginPosition(gaps, 1);
        setClippedEndPosition(gaps, 8);

        // Print the resulting gaps object and some coordinate transformation.
        std::cout << "Resulting gaps: " << gaps << "\n"
                  << "toSourcePosition(gaps, 0) == " << toSourcePosition(gaps, 0) << "\n"
                  << "toSourcePosition(gaps, 4) == " << toSourcePosition(gaps, 4) << "\n"
                  << "toViewPosition(gaps, 0) == " << toViewPosition(gaps, 0) << "\n"
                  << "toViewPosition(gaps, 5) == " << toViewPosition(gaps, 6) << "\n";

        return 0;
    }

Demo: demos/dox/align/gaps_example.cpp

The output is as follows:

    Resulting gaps: GG-T-A-
    toSourcePosition(gaps, 0) == 1
    toSourcePosition(gaps, 4) == 4
    toViewPosition(gaps, 0) == -1
    toViewPosition(gaps, 5) == 9

## Interface Functions Detail

### `void assignSource(gaps, seq);`

Assign the source of a gaps object, copying data.

#### Parameters

`gaps` | The Gaps object to assign the source of.
`seq` | The sequence to assign to the underlying string.

#### Data Races

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

### `TPos beginPosition(gaps);`

Return the clipping begin position as a source position.

#### Parameters

`gaps` | The Gaps object to query.

#### Returns

`TPos` | The clipping begin position in the source (Metafunction: Position).

#### Example

In the following gaps configuration, the result of `beginPosition(gaps)` is $1$. The clipping starts in a gap and the source position of the first non-gap character right of the clipping begin has source position 1.

    clipping                   [     )
      (half-open interval)

    gapped sequence:          X--XXX-XX-

    source position:          0111234456
    unclipped view position:  0123456789
    clipped view position:     0123456

#### Data Races

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

### `void clearClipping(gaps);`

Clear clipping from Gaps objects.

#### Parameters

`gaps` | Object to clear clipping from.

#### Data Races

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

### `void clearGaps(gaps);`

Clear gaps from Gaps objects.

#### Parameters

`gaps` | Object to clear gaps from.

#### Data Races

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

### `TPos clippedBeginPosition(gaps);`

Return begin position of the clipping.

#### Parameters

`gaps` | The Gaps object to query.

#### Returns

`TPos` | The begin position of the unclipped view (Metafunction: Position).

#### Example

In the following gaps configuration, the result of `clippedBeginPosition(gaps)` is 1.

    clipping                   [     )
      (half-open interval)

    gapped sequence:          X--XXX-XX-

    source position:          0111234456
    unclipped view position:  0123456789
    clipped view position:     0123456

#### Data Races

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

### `TPos clippedEndPosition(gaps);`

Return end position of the clipping.

#### Parameters

`gaps` | The Gaps object to query.

#### Returns

`TPos` | The end position of the unclipped view (Metafunction: Position).

#### Example

In the following gaps configuration, the result of `clippedEndPosition(gaps)` is 7.

    clipping                   [     )
      (half-open interval)

    gapped sequence:          X--XXX-XX-

    source position:          0111234456
    unclipped view position:  0123456789
    clipped view position:     0123456

#### Data Races

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

### `void clipSemiGlobal(global, local);`

Clip the Gaps objects to reflect a semi-global alignment.

#### Parameters

`global` | The global Gaps object.
`local` | The local Gaps object.

Leading and trailing gaps are clipped in the local Gaps object. The global Gaps object is updated accordingly.

#### Data Races

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

### `void copyClipping(dest, source);`

Copy clipping information from one Gaps object to another.

#### Parameters

`dest` | The destination Gaps object.
`source` | The source Gaps object.

#### Data Races

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

### `void copyGaps(dest, source);`

Copy gaps from one Gaps object to another (in the clipped view of both arguments).

#### Parameters

`dest` | The destination Gaps object (appropriate clipping, no gaps).
`source` | The source Gaps object.

The user is responsible for ensuring that the gaps are over sequences of same length and appropriate clipping.

#### Data Races

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

### `TSize countCharacters(gaps, viewPos[, dir]);`

The number of characters following a position.

#### Parameters

`gaps` | The Gaps object to query.
`viewPos` | View position (including clipping and gaps) to query at.
`dir` | A tag to specify the counting direction. One of GapDirectionTags. Defaults to RightOfViewPos.

#### Returns

`TSize` | The number of non-gaps characters characters at `viewPos` (Metafunction: Size).

If the the direction tag is RightOfViewPos the current view position will be included in the count, and excluded when LeftOfViewPos is selected.

#### Data Races

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

### `TSize countGapExtensions(gaps);`

The number of gap extensions.

#### Parameters

`gaps` | The Gaps object to query.

#### Returns

`TSize` | The total number of gap extensions (Metafunction: Size).

#### Data Races

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

### `TSize countGapOpens(gaps);`

The number of gap openings.

#### Parameters

`gaps` | The Gaps object to query.

#### Returns

`TSize` | The total number of gap openings (Metafunction: Size).

#### Data Races

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

### `TSize countGaps(gaps, viewPos[, dir]);`

The number of gaps following a position.

#### Parameters

`gaps` | The Gaps object to query.
`viewPos` | View position (including clipping and gaps) to query at.
`dir` | A tag to specify the counting direction. One of GapDirectionTags. Defaults to RightOfViewPos.

#### Returns

`TSize` | The number of gap characters at `viewPos` (Metafunction: Size).

If the the direction tag is RightOfViewPos the current view position will be included in the count, and excluded when LeftOfViewPos is selected.

#### Data Races

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

### `TSize countLeadingGaps(gaps);`

The number of leading gaps.

#### Parameters

`gaps` | The Gaps object to query.

#### Returns

`TSize` | The number of leading gap characters (Metafunction: Size).

#### Data Races

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

### `TSize countTrailingGaps(gaps);`

The number of trailing gaps.

#### Parameters

`gaps` | The Gaps object to query.

#### Returns

`TSize` | The number of trailing gap characters (Metafunction: Size).

#### Data Races

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

### `TPos endPosition(gaps);`

Return the clipping end position as a source position.

#### Parameters

`gaps` | The Gaps object to query for the end position as a source position.

#### Returns

`TPos` | The end position as a source position (Metafunction: Position).

#### Example

In the following gaps configuration, the result of `endPositioN(gaps)` is 4.

    clipping                   [     )
      (half-open interval)

    gapped sequence:          X--XXX-XX-

    source position:          0111234456
    unclipped view position:  0123456789
    clipped view position:     0123456

#### Data Races

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

### `void insertGap(gaps, viewPos);`

Insert one gap character.

#### Parameters

`gaps` | The Gaps object to insert gap into.
`viewPos` | The view position (including clipping and gaps) to insert the gap at.

#### Data Races

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

### `void insertGaps(gaps, viewPos, count);`

Insert gap characters.

#### Parameters

`gaps` | The Gaps object to insert gaps into.
`viewPos` | The view position (including clipping and gaps) to insert gaps at.
`count` | The number of gaps to insert.

#### Data Races

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

### `bool isCharacter(gaps, viewPos);`

Query positions in a Gaps object for being a character.

#### Parameters

`gaps` | The Gaps object to query.
`viewPos` | The view position (including clipping and gaps).

#### Returns

`bool` | The query result.

#### Data Races

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

### `bool isGap(gaps, viewPos);`

Query positions in a Gaps object for being a gap.

#### Parameters

`gaps` | The Gaps object to query.
`viewPos` | The view position (including clipping and gaps).

#### Returns

`bool` | The query result.

#### Data Races

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

### `TIterator iter(gaps, viewPos[, tag]);`

Return an iterator to a specific position in the current clipping.

#### Parameters

`gaps` | The Gaps object to get an iterator into.
`viewPos` | View position to get an iterator to (Metafunction: Position).
`tag` | An optional tag for selecting the iterator type.

#### Returns

`TIterator` | The resulting iterator. The type is `Iterator<TGaps, TTag>::Type` where `TTag` is the type of `tag`.

#### Data Races

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

### `TSize length(gaps);`

Return number of gap and characters between the beginning and the end of the clipping.

#### Parameters

`gaps` | The Gaps object to query for its length.

#### Returns

`TSize` | The number of gaps and characters between the beginning and the end of the clipping (Metafunction: Size).

#### Data Races

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

### `TSize removeGap(gaps, viewPos);`

Remove one gap from a Gaps object.

#### Parameters

`gaps` | The gaps object to remove one gap character from.
`viewPos` | The view positions to remove one gap character from.

#### Returns

`TSize` | The number of gap characters removed (Metafunction: Size).

#### Data Races

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

### `TSize removeGaps(gaps, viewPos, count);`

Remove gaps from a Gaps object.

#### Parameters

`gaps` | The gaps object to remove gap characters from.
`viewPos` | The view positions to remove gap characters from.
`count` | The number of gap characters to remove.

#### Returns

`TSize` | The number of gap characters removed (Metafunction: Size).

#### Data Races

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

### `void setBeginPosition(gaps, sourcePos);`

Set the begin position of the clipped gapped sequence, given a source position.

#### Parameters

`gaps` | The Gaps object to set the begin position in.
`sourcePos` | Position in the underlying sequence to set clipping to.

#### Data Races

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

### `void setClippedBeginPosition(gaps, unclippedViewPos);`

Set the begin position of the clipping.

#### Parameters

`gaps` | The Gaps object to set the clipping begin position of.
`unclippedViewPos` | View position (including gaps but excluding clipping) to set the clipping begin to.

#### Data Races

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

### `void setClippedEndPosition(gaps, unclippedViewPos);`

Set the end position of the clipping.

#### Parameters

`gaps` | The Gaps object to set the clipping end position of.
`unclippedViewPos` | View position (including gaps but excluding clipping) to set the clipping end to.

#### Data Races

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

### `void setEndPosition(gaps, sourcePos);`

Set the end position of the clipped gapped sequence, given a source position.

#### Parameters

`gaps` | The Gaps object to set the end position in.
`sourcePos` | Position in the underlying sequence to set clipping to.

#### Data Races

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

### `TSource source(gaps);`

Return underlying object.

#### Parameters

`gaps` | The Gaps object to return the underling sequence for.

#### Returns

`TSource` | Reference to the source of the Gaps.

#### Data Races

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

### `TPos toSourcePosition(gaps, viewPos);`

Conversion from view position (including gaps and clipping) to source (without gaps or clipping).

#### Parameters

`gaps` | The gaps object to use for translation.
`sourcePos` | The view position (including gaps and clipping) to translate.

#### Returns

`TPos` | The resulting position in the underlying sequence (Metafunction: Position).

#### Data Races

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

### `TPos toViewPosition(gaps, sourcePos);`

Conversion from source (without gaps or clipping) to view position (including gaps and clipping).

#### Parameters

`gaps` | The gaps object to use for translation.
`sourcePos` | The source position (in the underlying sequence) to translate.

#### Returns

`TPos` | The resulting position in the view (Metafunction: Position).

#### Data Races

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

### `TSize unclippedLength(gaps);`

Return length of the gapped sequence without clipping.

#### Parameters

`gaps` | The Gaps object to query.

#### Returns

`TSize` | The result (Metafunction: Size).

#### Data Races

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

#### Dox Sources

    /*!
     * @class Gaps
     *
     * @implements ContainerConcept
     *
     * @headerfile <seqan/align.h>
     *
     * @brief Store the gapped version of a sequence.
     *
     * @signature template <typename TSequence, typename TSpec> class Gaps;
     *
     * @tparam TSequence The type of the underlying sequence.
     * @tparam TSpec Tag for specialization.
     *
     * Gaps wrap a @link ContainerConcept Sequence @endlink and allows one to (1)
     * insert gaps into the sequence and (2) select an infix of the gapped sequence
     * (clipping). The gaps are not inserted into the underlying sequence (source)
     * but stored separately. Using the clipping is optional and meant for selecting
     * parts of the alignment as a part of the result of a local alignment
     * algorithm.
     *
     * <img src="gaps_illustration.png" title="Illustration of Gaps object and
     * positions with clipping." />
     *
     * In the figure above, the source sequence has seven characters, the gapped
     * sequence has four gaps and thus consists of eleven characters. The gapped
     * sequence is clipped to start at position 0 in the gapped sequence and to end
     * at position 8 in the gapped sequence (the positions given as half-open
     * intervals <tt>[begin, end)</tt>).
     *
     * The figure shows the three coordinate systems that are used with Gaps
     * objects. The source position is the position in the underlying sequence. The
     * unclipped view position is the position in the gapped sequence without gaps.
     * The view position is the position in the gapped sequence but including the
     * clipping: All (clipped) view positions have the clipping begin position
     * subtracted from them.
     *
     * @section Examples
     *
     * The following example shows the construction of the gaps object from the
     * image above together with some calls to <tt>toViewPosition</tt> and
     * <tt>toSourcePosition</tt>.
     *
     * @include demos/dox/align/gaps_example.cpp
     *
     * The output is as follows:
     *
     * @include demos/dox/align/gaps_example.cpp.stdout
     *
     *
     *
     * @fn Gaps#iter
     *
     * @brief Return an iterator to a specific position in the current clipping.
     *
     * @signature TIterator iter(gaps, viewPos[, tag]);
     *
     * @param[in] gaps The Gaps object to get an iterator into.
     * @param[in] viewPos View position to get an iterator to (Metafunction: @link
     *                    ContainerConcept#Position @endlink).
     * @param[in] tag An optional tag for selecting the iterator type.
     *
     * @return TIterator The resulting iterator. The type is <tt>Iterator<TGaps,
     *                   TTag>::Type</tt> where <tt>TTag</tt> is the type of
     *                   <tt>tag</tt>.
     *
     * @fn Gaps#clearClipping
     *
     * @brief Clear clipping from Gaps objects.
     *
     * @signature void clearClipping(gaps);
     *
     * @param[in,out] gaps Object to clear clipping from.
     *
     * @fn Gaps#clearGaps
     *
     * @brief Clear gaps from Gaps objects.
     *
     * @signature void clearGaps(gaps);
     *
     * @param[in,out] gaps Object to clear gaps from.
     *
     * @fn Gaps#length
     *
     * @brief Return number of gap and characters between the beginning and the end
     *        of the clipping.
     *
     * @signature TSize length(gaps);
     *
     * @param[in] gaps The @link Gaps @endlink object to query for its length.
     *
     * @return TSize The number of gaps and characters between the beginning and the
     *               end of the clipping (Metafunction: @link ContainerConcept#Size
     *               @endlink).
     *
     * @fn Gaps#unclippedLength
     *
     * @brief Return length of the gapped sequence without clipping.
     *
     * @signature TSize unclippedLength(gaps);
     *
     * @param[in] gaps The Gaps object to query.
     *
     * @return TSize The result (Metafunction: @link ContainerConcept#Size
     *               @endlink).
     *
     * @fn Gaps#toViewPosition
     *
     * @brief Conversion from source (without gaps or clipping) to view position
     *        (including gaps and clipping).
     *
     * @signature TPos toViewPosition(gaps, sourcePos);
     *
     * @param[in] gaps The gaps object to use for translation.
     * @param[in] sourcePos The source position (in the underlying sequence) to
     *                      translate.
     *
     * @return TPos The resulting position in the view (Metafunction: @link
     *              ContainerConcept#Position @endlink).
     *
     * @fn Gaps#toSourcePosition
     *
     * @brief Conversion from view position (including gaps and clipping) to source
     *        (without gaps or clipping).
     *
     * @signature TPos toSourcePosition(gaps, viewPos);
     *
     * @param[in] gaps The gaps object to use for translation.
     * @param[in] sourcePos The view position (including gaps and clipping) to
     *                      translate.
     *
     * @return TPos The resulting position in the underlying sequence (Metafunction:
     *              @link ContainerConcept#Position @endlink).
     *
     * @fn Gaps#isGap
     *
     * @brief Query positions in a Gaps object for being a gap.
     *
     * @signature bool isGap(gaps, viewPos);
     *
     * @param[in] gaps The Gaps object to query.
     * @param[in] viewPos The view position (including clipping and gaps).
     *
     * @return bool The query result.
     *
     * @fn Gaps#isCharacer
     *
     * @brief Query positions in a Gaps object for being a character.
     *
     * @signature bool isCharacter(gaps, viewPos);
     *
     * @param[in] gaps The Gaps object to query.
     * @param[in] viewPos The view position (including clipping and gaps).
     *
     * @return bool The query result.
     *
     * @fn Gaps#insertGaps
     *
     * @brief Insert gap characters.
     *
     * @signature void insertGaps(gaps, viewPos, count);
     *
     * @param[in,out] gaps The Gaps object to insert gaps into.
     * @param[in] viewPos The view position (including clipping and gaps) to insert
     *                    gaps at.
     * @param[in] count The number of gaps to insert.
     *
     * @fn Gaps#insertGap
     *
     * @brief Insert one gap character.
     *
     * @signature void insertGap(gaps, viewPos);
     *
     * @param[in,out] gaps The Gaps object to insert gap into.
     * @param[in] viewPos The view position (including clipping and gaps) to insert
     *                    the gap at.
     *
     * @fn Gaps#removeGaps
     *
     * @brief Remove gaps from a Gaps object.
     *
     * @signature TSize removeGaps(gaps, viewPos, count);
     *
     * @param[in,out] gaps The gaps object to remove gap characters from.
     * @param[in] viewPos The view positions to remove gap characters from.
     * @param[in] count The number of gap characters to remove.
     *
     * @return TSize The number of gap characters removed (Metafunction: @link
     *               ContainerConcept#Size @endlink).
     *
     * @fn Gaps#removeGap
     *
     * @brief Remove one gap from a Gaps object.
     *
     * @signature TSize removeGap(gaps, viewPos);
     *
     * @param[in,out] gaps The gaps object to remove one gap character from.
     * @param[in] viewPos The view positions to remove one gap character from.
     *
     * @return TSize The number of gap characters removed (Metafunction: @link
     *               ContainerConcept#Size @endlink).
     *
     * @fn Gaps#countGaps
     *
     * @brief The number of gaps following a position.
     *
     * @signature TSize countGaps(gaps, viewPos[, dir]);
     *
     * @param[in] gaps The Gaps object to query.
     * @param[in] viewPos View position (including clipping and gaps) to query at.
     * @param[in] dir A tag to specify the counting direction. One of @link
     *                GapDirectionTags @endlink. Defaults to @link
     *                GapDirectionTags#RightOfViewPos @endlink.
     *
     * @return TSize The number of gap characters at <tt>viewPos</tt> (Metafunction:
     *               @link ContainerConcept#Size @endlink).
     *
     * If the the direction tag is @link GapDirectionTags#RightOfViewPos @endlink
     * the current view position will be included in the count, and excluded when
     * @link GapDirectionTags#LeftOfViewPos @endlink is selected.
     *
     * @fn Gaps#countLeadingGaps
     *
     * @brief The number of leading gaps.
     *
     * @signature TSize countLeadingGaps(gaps);
     *
     * @param[in] gaps The Gaps object to query.
     *
     * @return TSize The number of leading gap characters (Metafunction: @link
     *               ContainerConcept#Size @endlink).
     *
     * @fn Gaps#countTrailingGaps
     *
     * @brief The number of trailing gaps.
     *
     * @signature TSize countTrailingGaps(gaps);
     *
     * @param[in] gaps The Gaps object to query.
     *
     * @return TSize The number of trailing gap characters (Metafunction: @link
     *               ContainerConcept#Size @endlink).
     *
     * @fn Gaps#countGapOpens
     *
     * @brief The number of gap openings.
     *
     * @signature TSize countGapOpens(gaps);
     *
     * @param[in] gaps The Gaps object to query.
     *
     * @return TSize The total number of gap openings (Metafunction: @link
     *               ContainerConcept#Size @endlink).
     *
     * @fn Gaps#countGapExtensions
     *
     * @brief The number of gap extensions.
     *
     * @signature TSize countGapExtensions(gaps);
     *
     * @param[in] gaps The Gaps object to query.
     *
     * @return TSize The total number of gap extensions (Metafunction: @link
     *               ContainerConcept#Size @endlink).
     *
     * @fn Gaps#countCharacters
     *
     * @brief The number of characters following a position.
     *
     * @signature TSize countCharacters(gaps, viewPos[, dir]);
     *
     * @param[in] gaps The Gaps object to query.
     * @param[in] viewPos View position (including clipping and gaps) to query at.
     * @param[in] dir A tag to specify the counting direction. One of @link
     *                GapDirectionTags @endlink. Defaults to @link
     *                GapDirectionTags#RightOfViewPos @endlink.
     *
     * @return TSize The number of non-gaps characters characters at
     *               <tt>viewPos</tt> (Metafunction: @link ContainerConcept#Size
     *               @endlink).
     *
     * If the the direction tag is @link GapDirectionTags#RightOfViewPos @endlink
     * the current view position will be included in the count, and excluded when
     * @link GapDirectionTags#LeftOfViewPos @endlink is selected.
     *
     * @fn Gaps#setClippedBeginPosition
     *
     * @brief Set the begin position of the clipping.
     *
     * @signature void setClippedBeginPosition(gaps, unclippedViewPos);
     *
     * @param[in,out] gaps The Gaps object to set the clipping begin position of.
     * @param[in] unclippedViewPos View position (including gaps but excluding
     *                             clipping) to set the clipping begin to.
     *
     * @fn Gaps#setClippedEndPosition
     *
     * @brief Set the end position of the clipping.
     *
     * @signature void setClippedEndPosition(gaps, unclippedViewPos);
     *
     * @param[in,out] gaps The Gaps object to set the clipping end position of.
     * @param[in] unclippedViewPos View position (including gaps but excluding
     *                             clipping) to set the clipping end to.
     *
     * @fn Gaps#clippedBeginPosition
     *
     * @brief Return begin position of the clipping.
     *
     * @signature TPos clippedBeginPosition(gaps);
     *
     * @param[in] gaps The Gaps object to query.
     *
     * @return TPos The begin position of the unclipped view (Metafunction: @link
     *              ContainerConcept#Position @endlink).
     *
     * @section Example
     *
     * In the following gaps configuration, the result of
     * <tt>clippedBeginPosition(gaps)</tt> is 1.
     *
     * @code{.txt}
     * clipping                   [     )
     *   (half-open interval)
     *
     * gapped sequence:          X--XXX-XX-
     *
     * source position:          0111234456
     * unclipped view position:  0123456789
     * clipped view position:     0123456
     * @endcode
     *
     *
     * @fn Gaps#clippedEndPosition
     *
     * @brief Return end position of the clipping.
     *
     * @signature TPos clippedEndPosition(gaps);
     *
     * @param[in] gaps The Gaps object to query.
     *
     * @return TPos The end position of the unclipped view (Metafunction: @link
     *              ContainerConcept#Position @endlink).
     *
     * @section Example
     *
     * In the following gaps configuration, the result of
     * <tt>clippedEndPosition(gaps)</tt> is 7.
     *
     * @code{.txt}
     * clipping                   [     )
     *   (half-open interval)
     *
     * gapped sequence:          X--XXX-XX-
     *
     * source position:          0111234456
     * unclipped view position:  0123456789
     * clipped view position:     0123456
     * @endcode
     *
     *
     * @fn Gaps#setBeginPosition
     *
     * @brief Set the begin position of the clipped gapped sequence, given a source
     *        position.
     *
     * @signature void setBeginPosition(gaps, sourcePos);
     *
     * @param[in,out] gaps The Gaps object to set the begin position in.
     * @param[in] sourcePos Position in the underlying sequence to set clipping to.
     *
     * @fn Gaps#setEndPosition
     *
     * @brief Set the end position of the clipped gapped sequence, given a source
     *        position.
     *
     * @signature void setEndPosition(gaps, sourcePos);
     *
     * @param[in,out] gaps The Gaps object to set the end position in.
     * @param[in] sourcePos Position in the underlying sequence to set clipping to.
     *
     * @fn Gaps#beginPosition
     *
     * @brief Return the clipping begin position as a source position.
     *
     * @signature TPos beginPosition(gaps);
     *
     * @param[in] gaps The Gaps object to query.
     *
     * @return TPos The clipping begin position in the source (Metafunction: @link
     *              ContainerConcept#Position @endlink).
     *
     * @section Example
     *
     * In the following gaps configuration, the result of
     * <tt>beginPosition(gaps)</tt> is $1$. The clipping starts in a gap and the
     * source position of the first non-gap character right of the clipping begin
     * has source position 1.
     *
     * @code{.txt}
     * clipping                   [     )
     *   (half-open interval)
     *
     * gapped sequence:          X--XXX-XX-
     *
     * source position:          0111234456
     * unclipped view position:  0123456789
     * clipped view position:     0123456
     * @endcode
     *
     *
     * @fn Gaps#endPosition
     *
     * @brief Return the clipping end position as a source position.
     *
     * @signature TPos endPosition(gaps);
     *
     * @param[in] gaps The Gaps object to query for the end position as a source
     *                 position.
     *
     * @return TPos The end position as a source position (Metafunction: @link
     *              ContainerConcept#Position @endlink).
     *
     * @section Example
     *
     * In the following gaps configuration, the result of <tt>endPositioN(gaps)</tt>
     * is 4.
     *
     * @code{.txt}
     * clipping                   [     )
     *   (half-open interval)
     *
     * gapped sequence:          X--XXX-XX-
     *
     * source position:          0111234456
     * unclipped view position:  0123456789
     * clipped view position:     0123456
     * @endcode
     *
     *
     * @fn Gaps#source
     *
     * @brief Return underlying object.
     *
     * @signature TSource source(gaps);
     *
     * @param[in] gaps The Gaps object to return the underling sequence for.
     *
     * @return TSource Reference to the source of the Gaps.
     *
     * @fn Gaps#assignSource
     *
     * @brief Assign the source of a gaps object, copying data.
     *
     * @signature void assignSource(gaps, seq);
     *
     * @param[in,out] gaps The Gaps object to assign the source of.
     * @param[in] seq The @link ContainerConcept sequence @endlink to assign to the
     *                underlying string.
     *
     * @fn Gaps#copyGaps
     *
     * @brief Copy gaps from one Gaps object to another (in the clipped view of both
     *        arguments).
     *
     * @signature void copyGaps(dest, source);
     *
     * @param[in,out] dest The destination Gaps object (appropriate clipping, no
     *                     gaps).
     * @param[in] source The source Gaps object.
     *
     * The user is responsible for ensuring that the gaps are over sequences of same
     * length and appropriate clipping.
     *
     * @fn Gaps#copyClipping
     *
     * @brief Copy clipping information from one Gaps object to another.
     *
     * @signature void copyClipping(dest, source);
     *
     * @param[in,out] dest The destination Gaps object.
     * @param[in] source The source Gaps object.
     *
     * @fn Gaps#clipSemiGlobal
     *
     * @brief Clip the Gaps objects to reflect a semi-global alignment.
     *
     * @signature void clipSemiGlobal(global, local);
     *
     * @param[in,out] global The global Gaps object.
     * @param[in,out] local The local Gaps object.
     *
     * Leading and trailing gaps are clipped in the local Gaps object. The global
     * Gaps object is updated accordingly.
     */