/*!
* @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<TSpec>
* >::Type (which is Iter<TContainer, VSTree<TopDown<TSpec>
* > >).
*
* @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/index/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<TIndex>::Type</tt>
* which is identical to <tt>Value<Fibre<TIndex,
* EsaRawText>::Type>::Type</tt>.
*/