Segment - SeqAn API Documentation

# Class Segment
A contiguous part of a sequence.

Implements | RandomAccessContainerConcept, SegmentableConcept
All Subcl's | InfixSegment, PrefixSegment, SuffixSegment
All Impl'd | AssignableConcept, ContainerConcept, DestructibleConcept, ForwardContainerConcept, RandomAccessContainerConcept, ReversibleContainerConcept, SegmentableConcept
Defined in | <seqan/sequence.h>
Signature | `template <typename THost, typename TSpec> class Segment;`

## Template Parameters

`THost` | The underlying sequence type.
`TSpec` | The tag to use for selecting the Segment specialization.

## Member Function Overview

### Member Functions Inherited From AssignableConcept

- `operator=`

### Member Functions Inherited From RandomAccessContainerConcept

- `operator[]`

## Interface Function Overview

- `TPos beginPosition(seg);`
  Return segment's begin position.
- `TPos endPosition(seg);`
  Return segment's end position.

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

### Interface Metafunctions Inherited From ContainerConcept

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

### Interface Metafunctions Inherited From SegmentableConcept

- `Infix`
- `Prefix`
- `Suffix`

## Detailed Description

Also known as:

substring

Segments are lightweight representations of an underlying sequence (host). Only a pointer to the host and begin and/or end position have to be stored.

Segments support element access (reading and writing) as well as random access iteration.

        typedef Prefix<String<char> >::Type TPrefix;
        typedef Infix<String<char> >::Type  TInfix;
        typedef Suffix<String<char> >::Type TSuffix;

        String<char> text = "This is a text!";

        TPrefix preA(text, 4);
        TInfix infA(text, 10, 14);
        TSuffix sufA(text, 10);
        std::cout << preA << " " << infA << " " << sufA << "\n";  // => "This text text!"

        String<char> str;
        append(str, preA);
        append(str, infA);
        append(str, sufA);
        std::cout << str << "\n";  // => "This text text!"

        std::cout << preA[0] << " " << infA[0] << " " << sufA[0] << "\n";  // => "T t t"

        preA[0] = 'X';
        infA[0] = 'X';
        sufA[1] = 'X';
        std::cout << text << "\n";  // => "Xhis is a XXxt!"

        typedef Iterator<TInfix, Standard>::Type TIter;
        TIter it = begin(preA, Standard());
        it += 2;
        *it = 'Y';
        std::cout << text << "\n";  // => "XhYs is a XXxt!"

Snippet from: demos/dox/sequence/segment.cpp

You can get the type of the infix/prefix/suffix of a sequence using Infix, Prefix, and Suffix. These metafunctions will "flatten" the type such that using these metafunctions, the infix of an infix is an infix and not an Infix Segment with an Infix Segment as its host. Instead, it will again be an Infix Segment of the host of the inner type.

A suffix of a suffix remains a suffix, a prefix of a prefix remains a prefix. Any other combination leads to the resulting type being a infix segment.

        typedef Infix<TInfix>::Type  TInfix2;  // == TInfix
        typedef Prefix<TInfix>::Type TInfix3;  // == TInfix
        typedef Suffix<TInfix>::Type TInfix4;  // == TInfix

        typedef Infix<TPrefix>::Type  TInfix5;   // == TInfix
        typedef Prefix<TPrefix>::Type TPrefix2;  // == TPrefix
        typedef Suffix<TPrefix>::Type TInfix6;   // == TInfix

        typedef Infix<TSuffix>::Type  TInfix7;   // == TInfix
        typedef Prefix<TSuffix>::Type TInfix8;   // == TPrefix
        typedef Suffix<TSuffix>::Type TSuffix2;  // == TSuffix

Snippet from: demos/dox/sequence/segment.cpp

If you explicitely need a segment and keep the underlying sequence as it is, explicitely use the `Segment` template class.

        typedef Segment<TSuffix, PrefixSegment> TExplicitPrefix;
        TExplicitPrefix preB(sufA, 3);
        std::cout << preB << "\n";  // => "XXx"

Snippet from: demos/dox/sequence/segment.cpp

## Interface Functions Detail

### `TPos beginPosition(seg);`

Return segment's begin position.

#### Parameters

`seg` | The Segment to query for its begin position.

#### Returns

`TPos` | The begin position of the segment. TPos is the position type of the Segment as returned by Position.

#### Data Races

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

### `TPos endPosition(seg);`

Return segment's end position.

#### Parameters

`seg` | The Segment to query for its end position.

#### Returns

`TPos` | The end position of the segment. TPos is the position type of the Segment as returned by Position.

#### Data Races

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

#### Dox Sources

    /*!
     * @class Segment
     *
     * @implements RandomAccessContainerConcept
     * @implements SegmentableConcept
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief A contiguous part of a sequence.
     *
     * @signature template <typename THost, typename TSpec> class Segment;
     *
     * @tparam THost The underlying @link ContainerConcept sequence @endlink type.
     * @tparam TSpec The tag to use for selecting the Segment specialization.
     *
     * Segments are lightweight representations of an underlying sequence (host).
     * Only a pointer to the host and begin and/or end position have to be stored.
     *
     * Segments support element access (reading and writing) as well as random
     * access iteration.
     *
     * @snippet demos/dox/sequence/segment.cpp basic operations
     *
     * You can get the type of the infix/prefix/suffix of a sequence using @link
     * SegmentableConcept#Infix @endlink, @link SegmentableConcept#Prefix @endlink,
     * and @link SegmentableConcept#Suffix @endlink. These metafunctions will
     * "flatten" the type such that using these metafunctions, the infix of an infix
     * is an infix and not an Infix Segment with an Infix Segment as its host.
     * Instead, it will again be an Infix Segment of the host of the inner type.
     *
     * A suffix of a suffix remains a suffix, a prefix of a prefix remains a prefix.
     * Any other combination leads to the resulting type being a infix segment.
     *
     * @snippet demos/dox/sequence/segment.cpp metafunction examples
     *
     * If you explicitely need a segment and keep the underlying sequence as it is,
     * explicitely use the <tt>Segment</tt> template class.
     *
     * @snippet demos/dox/sequence/segment.cpp explicit segment
     *
     * @fn Segment#beginPosition
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief Return segment's begin position.
     *
     * @signature TPos beginPosition(seg);
     *
     * @param[in] seg The Segment to query for its begin position.
     *
     * @return TPos The begin position of the segment. TPos is the position type of
     *              the Segment as returned by @link ContainerConcept#Position
     *              Position @endlink.
     *
     * @fn Segment#endPosition
     *
     * @headerfile <seqan/sequence.h>
     *
     * @brief Return segment's end position.
     *
     * @signature TPos endPosition(seg);
     *
     * @param[in] seg The Segment to query for its end position.
     *
     * @return TPos The end position of the segment. TPos is the position type of
     *              the Segment as returned by @link ContainerConcept#Position
     *              Position @endlink.
     */