Top Down History Iterator - SeqAn API Documentation

# Spec Top Down History Iterator
String tree iterator that can go down, right, and up. Supports depth- first search.

Extends | TopDownIterator
Implements | ForwardIteratorConcept
All Extended | Iter, TopDownIterator, VSTreeIterator
All Impl'd | CopyConstructibleConcept, DefaultConstructibleConcept, EqualityComparableConcept, ForwardIteratorConcept, InputIteratorConcept, IteratorAssociatedTypesConcept
Defined in | <seqan/index.h>
Signature | `template <typename TIndex, typename TSpec> class Iter<TIndex, VSTree<TopDown<ParentLinks<TSpec> > > >;`

## Template Parameters

`TSpec` | Specifies the depth-first search mode. Types: DfsOrder
`TIndex` | Type of the container that can be iterated. Types: IndexDfi, IndexEsa, IndexWotd, FMIndex, IndexSa

## Member Function Overview

- `Iter::Iter(index);, Iter::Iter(iterator);`
  Constructor

### Member Functions Inherited From Iter

- `Iter`

### Member Functions Inherited From TopDownIterator

- `Iterator`

### Member Functions Inherited From EqualityComparableConcept

- `operator!=`
- `operator==`

## Interface Function Overview

- `bool goUp(iterator);`
  Iterates up one or multiple edges to the parent in a tree/trie. E.g., after using goDown(iterator, string [, lcp]) on a suffix or prefix trie (e.g. IndexSa or FMIndex) and thus going down multiple edges at once, goUp(iterator) will go up as many edges as the corresponding call of goDown(iterator, string[, lcp]) has moved down.
- `bool lca(a, b, result);`
  Returns the last common ancestor of two tree nodes.
- `TSize lcp(a, b);`
  Returns the length of the longest-common-prefix of two suffix tree nodes.
- `TSize nodeDepth(iterator);`
  Returns the zero-based node depth of the `iterator` node.

### Interface Functions Inherited From TopDownIterator

- `emptyParentEdge`
- `goDown`
- `goRight`
- `nodeUp`
- `parentEdgeFirstChar`
- `parentEdgeLabel`
- `parentEdgeLength`
- `parentRepLength`

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

- `operator++(suffix)`
- `operator++(prefix)`
- `operator->`
- `goNext`

### 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<TContainer, TopDown<ParentLinks<TSpec> > >::Type (which is Iter<TContainer, VSTree<ParentLinks<TopDown<TSpec> > > >).

If not copy-constructed the TopDownHistoryIterator starts in the root node of the string tree. Depending on the depth-first search mode the root is not the first DFS node. To go to the first DFS node use goBegin.

### Example

DemoConstraintIterator

## Member Functions Detail

### `Iter::Iter(index); Iter::Iter(iterator);`

Constructor

#### Parameters

`index` | An index object.
`iterator` | Another TopDownHistory iterator. (copy constructor) Types: TopDownHistory Iterator

If not copy-constructed the TopDownHistoryIterator starts in the root node of the string tree.

#### Data Races

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

## Interface Functions Detail

### `bool goUp(iterator);`

Iterates up one or multiple edges to the parent in a tree/trie. E.g., after using goDown(iterator, string [, lcp]) on a suffix or prefix trie (e.g. IndexSa or FMIndex) and thus going down multiple edges at once, goUp(iterator) will go up as many edges as the corresponding call of goDown(iterator, string[, lcp]) has moved down.

#### Parameters

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

#### Returns

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

#### Example

The following code shows how the function goUp is used.

    #include <seqan/index.h>

    using namespace seqan2;

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

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

        do
        {
            // Print the letters from the root to the current node
            std::cout << representative(it) << std::endl;

            if (!goDown(it) && !goRight(it))
                while (goUp(it) && !goRight(it))
                    ;
        }
        while (!isRoot(it));

        return 0;
    }

Demo: demos/dox/index/iterator.cpp

    be
    beornottobe
    e
    eornottobe
    nottobe
    o
    obe
    obeornottobe
    ornottobe
    ottobe
    rnottobe
    t
    tobe
    tobeornottobe
    ttobe

#### Data Races

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

### `bool lca(a, b, result);`

Returns the last common ancestor of two tree nodes.

#### Parameters

`a` | The first node. Types: TopDownHistoryIterator
`b` | The second node. Types: TopDownHistoryIterator
`result` | A reference to the resulting lca node. Types: TopDownHistoryIterator

#### Returns

`TReturn` | `false` if the lca of `a` and `b` is the root node, otherwise `true`.

#### Data Races

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

### `TSize lcp(a, b);`

Returns the length of the longest-common-prefix of two suffix tree nodes.

#### Parameters

`a` | The first node. Types: TopDownHistoryIterator
`b` | The second node. Types: TopDownHistoryIterator

#### Returns

`TSize` | The lcp-length of `a` and `b`. The type of the result is the result of the metafunction Size of the Index of the iterator

#### Data Races

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

### `TSize nodeDepth(iterator);`

Returns the zero-based node depth of the `iterator` node.

#### Parameters

`iterator` | An iterator of a string tree.

#### Returns

`TSize` | The length of the path from root to `iterator` node, e.g. 0 is returned for the root node. The type of the result 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.

#### Dox Sources

    /*!
     * @class TopDownHistoryIterator Top Down History Iterator
     *
     * @implements ForwardIteratorConcept
     *
     * @extends TopDownIterator
     *
     * @headerfile <seqan/index.h>
     *
     * @brief String tree iterator that can go down, right, and up. Supports depth-
     *        first search.
     *
     * @note Instead of using the class Iter directly we recommend to use the result
     *       of the metafunction Iterator&lt;TContainer,
     *       TopDown&lt;ParentLinks&lt;TSpec&gt; &gt; &gt;::Type (which is
     *       Iter&lt;TContainer, VSTree&lt;ParentLinks&lt;TopDown&lt;TSpec&gt; &gt;
     *       &gt; &gt;).
     *
     * @signature template <typename TIndex, typename TSpec> class Iter<TIndex,
     *            VSTree<TopDown<ParentLinks<TSpec> > > >;
     *
     * @tparam TSpec Specifies the depth-first search mode. Types: @link DfsOrder
     *               @endlink
     * @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 TopDownHistoryIterator @endlink starts in
     * the root node of the string tree. Depending on the depth-first search mode
     * the root is not the first DFS node. To go to the first DFS node use @link
     * VSTreeIterator#goBegin @endlink.
     *
     * @section Example
     *
     * @link DemoConstraintIterator @endlink
     *
     * @fn TopDownHistoryIterator::Iterator
     *
     * @brief Constructor
     *
     * @signature Iter::Iter(index);
     * @signature Iter::Iter(iterator);
     *
     * @param[in] index An index object.
     * @param[in] iterator Another TopDownHistory iterator. (copy constructor)
     *                     Types: TopDownHistory Iterator
     *
     * If not copy-constructed the @link TopDownHistoryIterator @endlink starts in
     * the root node of the string tree.
     *
     * @fn TopDownHistoryIterator#nodeDepth
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns the zero-based node depth of the <tt>iterator</tt> node.
     *
     * @signature TSize nodeDepth(iterator);
     *
     * @param[in] iterator An iterator of a string tree.
     *
     * @return TSize The length of the path from root to <tt>iterator</tt> node,
     *               e.g. 0 is returned for the root node. The type of the result is
     *               the result of the metafunction @link Size @endlink of the
     *               underlying index.
     *
     * @fn TopDownHistoryIterator#lca
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns the last common ancestor of two tree nodes.
     *
     * @signature bool lca(a, b, result);
     *
     * @param[in] a The first node. Types: @link TopDownHistoryIterator @endlink
     * @param[in] b The second node. Types: @link TopDownHistoryIterator @endlink
     * @param[out] result A reference to the resulting lca node. Types: @link
     *                    TopDownHistoryIterator @endlink
     *
     * @return TReturn <tt>false</tt> if the lca of <tt>a</tt> and <tt>b</tt> is the
     *                 root node, otherwise <tt>true</tt>.
     *
     * @fn TopDownHistoryIterator#lcp
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Returns the length of the longest-common-prefix of two suffix tree
     *        nodes.
     *
     * @signature TSize lcp(a, b);
     *
     * @param[in] a The first node. Types: @link TopDownHistoryIterator @endlink
     * @param[in] b The second node. Types: @link TopDownHistoryIterator @endlink
     *
     * @return TSize The lcp-length of <tt>a</tt> and <tt>b</tt>. The type of the
     *               result is the result of the metafunction @link Size @endlink of
     *               the @link Index @endlink of the iterator
     *
     * @fn TopDownHistoryIterator#goUp
     *
     * @headerfile <seqan/index.h>
     *
     * @brief Iterates up one or multiple edges to the parent in a tree/trie. E.g.,
     *        after using goDown(iterator, string [, lcp]) on a suffix or prefix
     *        trie (e.g. IndexSa or FMIndex) and thus going down multiple edges at
     *        once, goUp(iterator) will go up as many edges as the corresponding
     *        call of goDown(iterator, string[, lcp]) has moved down.
     *
     * @signature bool goUp(iterator);
     *
     * @param[in,out] iterator An iterator of a string tree/trie.
     *
     * @return bool <tt>true</tt> if the iterator could be moved, otherwise
     *              <tt>false</tt>.
     *
     * @section Example
     *
     * The following code shows how the function @link TopDownHistoryIterator#goUp
     * @endlink is used.
     *
     * @include demos/dox/index/iterator.cpp
     *
     * @code{.output}
     * be
     * beornottobe
     * e
     * eornottobe
     * nottobe
     * o
     * obe
     * obeornottobe
     * ornottobe
     * ottobe
     * rnottobe
     * t
     * tobe
     * tobeornottobe
     * ttobe
     *
     * @endcode
     */