Top Down Iterator - SeqAn API Documentation

# Spec Top Down Iterator
Iterator for virtual trees/tries that can go down and right beginning from the root.

Extends | VSTreeIterator
All Extended | Iter, VSTreeIterator
All Subcl's | TopDownHistoryIterator
All Impl'd | IteratorAssociatedTypesConcept
Defined in | <seqan/index.h>
Signature | `template <typename TIndex, typename TSpec> class Iter<TContainer, VSTree< TopDown<TSpec> > >;`

## Template Parameters

`TSpec` | The specialization type.
`TIndex` | Type of the container that can be iterated. Types: IndexDfi, IndexEsa, IndexWotd, FMIndex, IndexSa

## Member Function Overview

- `Iter::Iter(index[, vertexDesc]);, Iter::Iter(iterator);`
  Constructor

### Member Functions Inherited From Iter

- `Iter`

## Interface Function Overview

- `bool emptyParentEdge(iterator);`
  Returns `true` iff the edge label from the `iterator` node to its parent is empty.
- `bool goDown(iterator);, bool goDown(iterator, char);, bool goDown(iterator, text[, lcp]);`
  Iterates down one edge or a path in a tree.
- `bool goRight(iterator);`
  Iterates to the next sibling in a tree.
- `TVertexDiscriptor nodeUp(iterator);`
  Returns the vertex descriptor of the parent node.
- `TValue parentEdgeFirstChar(iterator);`
  Returns the first character of the edge from an `iterator` node to its parent.
- `TEdgeLabel parentEdgeLabel(iterator);`
  Returns a substring representing the edge from an `iterator` node to its parent.
- `TSize parentEdgeLength(iterator);`
  Returns the length of the edge from the `iterator` node to its parent.
- `TSize parentRepLength(iterator);`
  Returns the length of the substring representing the path from root to `iterator`'s parent node.

### Interface Functions Inherited From VSTreeIterator

- `alignment`
- `assignProperty`
- `atEnd`
- `childrenAreLeaves`
- `countChildren`
- `countOccurrences`
- `getFrequency`
- `getOccurrence`
- `getOccurrences`
- `getOccurrencesBwt`
- `getProperty`
- `goBegin`
- `goNext`
- `goRoot`
- `isLeaf`
- `isLeftMaximal`
- `isPartiallyLeftExtensible`
- `isRightTerminal`
- `isRoot`
- `isUnique`
- `nodeHullPredicate`
- `nodePredicate`
- `property`
- `range`
- `repLength`
- `representative`
- `value`

### Interface Functions Inherited From IteratorAssociatedTypesConcept

- `operator*`
- `value`
- `getValue`

## Interface Metafunction Overview

### Interface Metafunctions Inherited From Iter

- `Container`
- `IterComplementConst`
- `IterMakeConst`
- `Spec`

### Interface Metafunctions Inherited From VSTreeIterator

- `EdgeLabel`

### Interface Metafunctions Inherited From IteratorAssociatedTypesConcept

- `Difference`
- `GetValue`
- `Pointer`
- `Reference`
- `Value`

## Detailed Description

Note:

Instead of using the class Iter directly we recommend to use the result of the metafunction Iterator&t;TContainer, TopDown<TSpec> >::Type (which is Iter<TContainer, VSTree<TopDown<TSpec> > >).

If not copy-constructed the TopDownIterator starts in the root node of the virtual tree/trie.

## Member Functions Detail

### `Iter::Iter(index[, vertexDesc]); Iter::Iter(iterator);`

Constructor

#### Parameters

`index` | An index object.
`iterator` | Another TopDown iterator. (copy constructor) Types: TopDown Iterator, TopDownHistory Iterator
`vertexDesc` | The vertex descriptor of a node the iterator should start in. The iterator starts in the root node by default.

If not copy-constructed the TopDownIterator starts in the root node of the virtual tree.

#### Data Races

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

## Interface Functions Detail

### `bool emptyParentEdge(iterator);`

Returns `true` iff the edge label from the `iterator` node to its parent is empty.

#### Parameters

`iterator` | An iterator of a string tree. Types: TopDownIterator

#### Returns

`bool` | `true` if parentEdgeLength `returns 0, otherwise` false$.

#### Data Races

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

### `bool goDown(iterator); bool goDown(iterator, char); bool goDown(iterator, text[, lcp]);`

Iterates down one edge or a path in a tree.

#### Parameters

`char` | `iterator` goes down the edge beginning with `char`.
`text` | `iterator` goes down the path representing `text`. If `text` ends within an edge, `iterator` will point to the child-end of this edge.
`lcp` | A reference of a size type. When `goDown` returns, `lcp` contains the length of the longest-common-prefix of `text` and a path beginning at the `iterator` node. Types: String, Segment
`iterator` | An iterator of a tree.

#### Returns

`bool` | `true` if the edge or path to go down exists, otherwise `false`.

`goDown(iterator)` goes down the leftmost edge in the tree, i.e. the edge beginning with the lexicographically smallest character.

#### Example

The following code shows a simple example how the function goDown is used.

    #include <seqan/index.h>

    using namespace seqan2;

    int main()
    {
        typedef Index<CharString> TIndex;

        TIndex index("MISSISSIPPI");
        Iterator<TIndex, TopDown<> >::Type it(index);

        goDown(it, "ISSI");
        std::cout << "The string " << representative(it) << " occurs " << range(it).i2 - range(it).i1 <<
        " times in MISSISSIPPI and has " << repLength(it) << " characters." << std::endl;

        // Note that goDown follows the path STARTING with a given text. It only stops at the next node. Therefore the
        // output for the following code is the same as above, even though the search string changed.
        goRoot(it);
        goDown(it, "ISS");

        std::cout << "The string " << representative(it) << " occurs " << range(it).i2 - range(it).i1 <<
        " times in MISSISSIPPI and has " << repLength(it) << " characters." << std::endl;

        return 0;
    }

Demo: demos/dox/index/begin_range_goDown_representative_repLength.cpp

    The string ISSI occurs 2 times in MISSISSIPPI and has 4 characters.
    The string ISSI occurs 2 times in MISSISSIPPI and has 4 characters.

#### Data Races

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

### `bool goRight(iterator);`

Iterates to the next sibling in a tree.

#### Parameters

`iterator` | An iterator of a string tree.

#### Returns

`bool` | `true` if the iterator could be moved, otherwise `false`.

#### Data Races

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

### `TVertexDiscriptor nodeUp(iterator);`

Returns the vertex descriptor of the parent node.

#### Parameters

`iterator` | An iterator of a string tree/trie.

#### Returns

`TVertexDescriptor` | The vertex descriptor of the parent node. The type is VertexDescriptor of TIndex. If `iterator` points at the root node, the vertex descriptor of it is returned.

#### Data Races

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

### `TValue parentEdgeFirstChar(iterator);`

Returns the first character of the edge from an `iterator` node to its parent.

#### Parameters

`iterator` | An iterator of a string tree.

#### Returns

`TValue` | A single character of type `Value<TIndex>::Type` which is identical to `Value<Fibre<TIndex, EsaRawText>::Type>::Type`.

#### Data Races

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

### `TEdgeLabel parentEdgeLabel(iterator);`

Returns a substring representing the edge from an `iterator` node to its parent.

#### Parameters

`iterator` | An iterator of a string tree/trie.

#### Returns

`TEdgeLabel` | Returns a substring representing the edge from an `iterator` node to its parent. and its type is the result of the metafunction EdgeLabel of the iterator.

#### Data Races

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

### `TSize parentEdgeLength(iterator);`

Returns the length of the edge from the `iterator` node to its parent.

#### Parameters

`iterator` | An iterator of a string tree.

#### Returns

`TSize` | The returned value is equal to `length(parentEdgeLabel(iterator))` and its type is the result of the metafunction Size of the underlying index.

#### Data Races

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

### `TSize parentRepLength(iterator);`

Returns the length of the substring representing the path from root to `iterator`'s parent node.

#### Parameters

`iterator` | An iterator of a string tree.

#### Returns

`TReturn` | The length of the sequence returned by representative of the parent node. The result type is the resultof the metafunction Size of the underlying index.

#### Data Races

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

#### Dox Sources

    /*!
     * @class TopDownIterator Top Down Iterator
     *
     * @extends VSTreeIterator
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Iterator for virtual trees/tries that can go down and right beginning
     *        from the root.
     *
     * @note Instead of using the class Iter directly we recommend to use the result
     *       of the metafunction Iterator&t;TContainer, TopDown&lt;TSpec&gt;
     *       &gt;::Type (which is Iter&lt;TContainer, VSTree&lt;TopDown&lt;TSpec&gt;
     *       &gt; &gt;).
     *
     * @signature template <typename TIndex, typename TSpec> class Iter<TContainer,
     *            VSTree< TopDown<TSpec> > >;
     *
     * @tparam TSpec The specialization type.
     * @tparam TIndex Type of the container that can be iterated. Types: @link
     *                IndexDfi @endlink, @link IndexEsa @endlink, @link IndexWotd
     *                @endlink, @link FMIndex @endlink, @link IndexSa @endlink
     *
     * If not copy-constructed the @link TopDownIterator @endlink starts in the root
     * node of the virtual tree/trie.
     *
     * @fn TopDownIterator::Iterator
     *
     * @brief Constructor
     *
     * @signature Iter::Iter(index[, vertexDesc]);
     * @signature Iter::Iter(iterator);
     *
     * @param[in] index An index object.
     * @param[in] iterator Another TopDown iterator. (copy constructor) Types:
     *                     TopDown Iterator, TopDownHistory Iterator
     * @param[in] vertexDesc The vertex descriptor of a node the iterator should
     *                       start in. The iterator starts in the root node by
     *                       default.
     *
     * If not copy-constructed the @link TopDownIterator @endlink starts in the root
     * node of the virtual tree.
     *
     * @fn TopDownIterator#parentRepLength
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns the length of the substring representing the path from root to
     *        <tt>iterator</tt>'s parent node.
     *
     * @signature TSize parentRepLength(iterator);
     *
     * @param[in] iterator An iterator of a string tree.
     *
     * @return TReturn The length of the sequence returned by @link
     *                 VSTreeIterator#representative @endlink of the parent node.
     *                 The result type is the resultof the metafunction @link Size
     *                 @endlink of the underlying index.
     *
     * @fn TopDownIterator#emptyParentEdge
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns <tt>true</tt> iff the edge label from the <tt>iterator</tt>
     *        node to its parent is empty.
     *
     * @signature bool emptyParentEdge(iterator);
     *
     * @param[in] iterator An iterator of a string tree. Types: @link
     *                     TopDownIterator @endlink
     *
     * @return bool <tt>true</tt> if @link TopDownIterator#parentEdgeLength
     *              @endlink<tt> returns 0, otherwise </tt>false$.
     *
     * @fn TopDownIterator#goDown
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Iterates down one edge or a path in a tree.
     *
     * @signature bool goDown(iterator);
     * @signature bool goDown(iterator, char);
     * @signature bool goDown(iterator, text[, lcp]);
     *
     * @param[in] char <tt>iterator</tt> goes down the edge beginning with
     *                 <tt>char</tt>.
     * @param[in] text <tt>iterator</tt> goes down the path representing
     *                 <tt>text</tt>. If <tt>text</tt> ends within an edge,
     *                 <tt>iterator</tt> will point to the child-end of this edge.
     * @param[in] lcp A reference of a size type. When <tt>goDown</tt> returns,
     *                <tt>lcp</tt> contains the length of the longest-common-prefix
     *                of <tt>text</tt> and a path beginning at the <tt>iterator</tt>
     *                node. Types: @link String @endlink, @link Segment @endlink
     * @param[in] iterator  An iterator of a tree.
     *
     * @return bool <tt>true</tt> if the edge or path to go down exists, otherwise
     *              <tt>false</tt>.
     *
     * <tt>goDown(iterator)</tt> goes down the leftmost edge in the tree, i.e. the
     * edge beginning with the lexicographically smallest character.
     *
     * @section Example
     *
     * The following code shows a simple example how the function @link
     * TopDownIterator#goDown @endlink is used.
     *
     * @include demos/dox/index/begin_range_goDown_representative_repLength.cpp
     *
     * @code{.output}
     * The string ISSI occurs 2 times in MISSISSIPPI and has 4 characters.
     * The string ISSI occurs 2 times in MISSISSIPPI and has 4 characters.
     * @endcode
     *
     *
     * @fn TopDownIterator#nodeUp
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns the vertex descriptor of the parent node.
     *
     * @signature TVertexDiscriptor nodeUp(iterator);
     *
     * @param[in,out] iterator An iterator of a string tree/trie.
     *
     * @return TVertexDescriptor The vertex descriptor of the parent node. The type
     *                           is @link VertexDescriptor @endlink of TIndex. If
     *                           <tt>iterator</tt> points at the root node, the
     *                           vertex descriptor of it is returned.
     *
     * @fn TopDownIterator#goRight
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Iterates to the next sibling in a tree.
     *
     * @signature bool goRight(iterator);
     *
     * @param[in,out] iterator An iterator of a string tree.
     *
     * @return bool <tt>true</tt> if the iterator could be moved, otherwise
     *              <tt>false</tt>.
     *
     * @fn TopDownIterator#parentEdgeLength
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns the length of the edge from the <tt>iterator</tt> node to its
     *        parent.
     *
     * @signature TSize parentEdgeLength(iterator);
     *
     * @param[in,out] iterator An iterator of a string tree.
     *
     * @return TSize The returned value is equal to
     *               <tt>length(parentEdgeLabel(iterator))</tt> and its type is the
     *               result of the metafunction @link Size @endlink of the
     *               underlying index.
     *
     * @fn TopDownIterator#parentEdgeLabel
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns a substring representing the edge from an <tt>iterator</tt>
     *        node to its parent.
     *
     * @signature TEdgeLabel parentEdgeLabel(iterator);
     *
     * @param[in] iterator An iterator of a string tree/trie.
     *
     * @return TEdgeLabel Returns a substring representing the edge from an
     *                    <tt>iterator</tt> node to its parent. and its type is the
     *                    result of the metafunction @link VSTreeIterator#EdgeLabel
     *                    @endlink of the iterator.
     *
     * @fn TopDownIterator#parentEdgeFirstChar
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns the first character of the edge from an <tt>iterator</tt> node
     *        to its parent.
     *
     * @signature TValue parentEdgeFirstChar(iterator);
     *
     * @param[in] iterator An iterator of a string tree.
     *
     * @return TValue A single character of type <tt>Value&lt;TIndex&gt;::Type</tt>
     *                which is identical to <tt>Value&lt;Fibre&lt;TIndex,
     *                EsaRawText&gt;::Type&gt;::Type</tt>.
     */