/*!
* @class AnnotationTreeIterator
*
* @extends Iter
*
* @headerfile <seqan/store.h>
*
* @brief Iterator of the annotation tree represetned by a @link FragmentStore
* @endlink.
*
* @signature template <typename TFragmentStore> class Iter<TFragmentStore,
* AnnotationTree<> >;
*
* @tparam TFragmentStore The FragmentStore to iterate over.
*
* This iterator can move @link AnnotationTreeIterator#goDown down @endlink,
* @link AnnotationTreeIterator#goRight right @endlink, and @link
* AnnotationTreeIterator#goUp up @endlink in the tree and supports a preorder
* DFS traversal using the functions @link
* RootedRandomAccessIteratorConcept#goBegin @endlink, @link
* InputIteratorConcept#goNext @endlink, and @link RootedIteratorConcept#atEnd
* @endlink.
*
* Preorder means that the iterator visits the node befor it visits its
* children.
*
* To obtain the type of the AnnotationTreeIterator for a FragmentStore
* specializiation <tt>TFragmentStore</tt>, you can use the metafunction @link
* ContainerConcept#Iterator Iterator @endlink as follows:
* <tt>Iterator<TFragmentStore>::Type</tt>.
*
* @section Remarks
*
* To access the annotation, the iterator points to, use @link
* AnnotationTreeIterator#getAnnotation @endlink. The annotation id is returned
* by @link IteratorAssociatedTypesConcept#value @endlink.
*
* @section Example
*
* <img src="AnnotationTree.png" title="Typical annotation tree hierarchy." />
*
* A new annotation iterator can be instantiated as follows:
*
* @code{.cpp}
* FragmentStore<> store;
* Iterator<FragmentStore<>, AnnotationTree<> >::Type it;
* it = begin(store, AnnotationTree<>());
* @endcode
*
*
* Or shorter:
*
* @code{.cpp}
* FragmentStore<> store;
* Iterator<FragmentStore<>, AnnotationTree<> >::Type it(store);
* @endcode
*
*
* @fn AnnotationTreeIterator::AnnotationTreeIterator
*
* @brief Constructor
*
* @signature Iter::Iter();
* @signature Iter::Iter(store[, startInNode]);
*
* @param[in] store The FragmentStore with the annotation tree to iterate.
* @param[in] startInNode Annotation id of the ndoe the iterator should start
* at. Default: 0, the root node id.
*
* The @link ContainerConcept#begin @endlink function can also be used to create
* a tree iterator that starts in the root node:
*
* @code{.cpp}
* FragmentStore<> store;
* Iterator<FragmentStore<>, AnnotationTree<> >::Type it;
* it = begin(store, AnnotationTree<>());
* @endcode
*
*
* @fn AnnotationTreeIterator#getAnnotation
*
* @brief Returns the current annotation.
*
* @signature TAnnotation getAnnotation(it);
*
* @param[in] it The AnnotationTreeIterator to query for its annotation.
*
* @return TAnnotation A reference to the AnnotationStoreElement the iterator
* points to.
*
* @fn AnnotationTreeIterator#getName
*
* @brief Returns the identifier of the current annotation.
*
* @signature TName getName(it);
*
* @param[in] it An AnnotationTreeIterator to query.
*
* @return TName The name of the current annotation. This is a reference to the
* corresponding position in @link
* FragmentStore::annotationNameStore @endlink.
*
* @see AnnotationTreeIterator#setName
*
* @fn AnnotationTreeIterator#setName
*
* @brief Sets the identifier of the current annotation.
*
* @signature void setName(it, name);
*
* @param[in,out] it Iterator to the annotation to set the name for.
* @param[in] name The new identifier of the annotation pointed to by it.
*
* @see AnnotationTreeIterator#getName
*
* @fn AnnotationTreeIterator#getParentName
*
* @brief Returns the identifier of the parent node in the annotationt ree of
* the current annotation.
*
* @signature TName getParentName(it);
*
* @param[in] it The AnnotationTreeIterator to get the name for.
*
* @return TName The name of the parent of the current annotation. This is a
* reference to the corresponding value in @link
* FragmentStore::annotationNameStore @endlink.
*
* @fn AnnotationTreeIterator#getType
*
* @brief Returns the type name of the current annotation.
*
* @signature TSeq getType(it);
*
* @param[in] it The AnnotationTreeIterator to query for its type.
*
* @return The name of the current annotation, e.g. "exon" or "mRNA". This is a
* reference to an entry in @link FragmentStore::annotationTypeStore
* @endlink.
*
* @see AnnotationTreeIterator#setType
*
* @fn AnnotationTreeIterator#setType
*
* @brief Sets the type name of the current annotation.
*
* @signature void setType(it, typeName);
*
* @param[in,out] it The iterator to the annotation to set the type name for.
* @param[in] typeName The name of the type (e.g. "exon" or "mRNA"). Type: @link
* ContainerConcept @endlink.
*
* @see AnnotationTreeIterator#getType
*
* @fn AnnotationTreeIterator#getUniqueName
*
* @brief Returns a unique name of the current annotation.
*
* @signature CharString getUniqueName(it);
*
* @param[in] it The AnnotationTreeIterator to query.
*
* @return CharString A unique name of the current annotation.
*
* Some annotation file formats do not require that every annotation has a non-
* empty name. This function returns the name if non-emtpy and otherwise
* generates one using the type an id.
*
* @see AnnotationTreeIterator#getName
*
* @fn AnnotationTreeIterator#clearValues
*
* @brief Clear all key-value pairs of a given annotation.
*
* @signature void clearValues(it);
*
* @param[in,out] it The AnnotationTreeIterator to clear all key-value pairs of
* the current annotation.
*
* @see AnnotationTreeIterator#assignValueByKey
* @see AnnotationTreeIterator#getValueByKey
*
* @fn AnnotationTreeIterator#assignValueByKey
*
* @brief Add or update a key-value pair of the current annotation.
*
* @signature void assignValueByKey(it, key, value);
*
* @param[in,out] it The AnnotationTreeIterator to
* @param[in] key The key whose value should be changed. Type: @link
* ContainerConcept @endlink.
* @param[in] value The value that should be assigned. Type: @link
* ContainerConcept @endlink.
*
* @see AnnotationTreeIterator#clearValues
* @see AnnotationTreeIterator#getValueByKey
*
* @fn AnnotationTreeIterator#getValueByKey
*
* @brief Retrieve a key's value in the current annotation.
*
* @signature bool getValueByKey(it, key);
* @signature bool getValueByKey(value, it, key);
*
* @param[in] it The AnnotationTreeIterator for which to retrieve the key.
* @param[in] key The key to get the value for.
* @param[out] value The resulting value.
*
* @see AnnotationTreeIterator#clearValues
* @see AnnotationTreeIterator#assignValueByKey
*
* @fn AnnotationTreeIterator#goTo
*
* @brief Moves the iterator to an arbitrary node giving its annotationId.
*
* @signature void goTo(it, annoId);
*
* @param[in,out] it The AnnotationTreeIterator to move.
* @param[in] annoId The id of the annotation to move to.
*
* @fn AnnotationTreeIterator#goNextRight
*
* @brief Go to the next node in preorder DFS skipping the current node's
* subtree.
*
* @signature void goNextUp(it);
*
* @param[in,out] it The AnnotationTreeIterator to
*
* @fn AnnotationTreeIterator#goNextUp
*
* @brief Go to the next node in preorder DFS skipping the subtrees of the
* current node and all of its siblings.
*
* @signature void goNextUp(it);
*
* @param[in,out] it The AnnotationTreeIterator to
*
* @fn AnnotationTreeIterator#goRoot
*
* @brief Move the iterator down to the tree root.
*
* @signature void goRoot(it);
*
* @param[in,out] it The AnnotationTreeIterator to move.
*
* @fn AnnotationTreeIterator#goUp
*
* @brief Move the iterator down to the parent in the annotation tree.
*
* @signature bool goUp(it);
*
* @param[in,out] it The AnnotationTreeIterator to move.
*
* @return bool <tt>true</tt> if the iterator could be moved and <tt>false</tt>
* otherwise.
*
* @see AnnotationTreeIterator#goDown
* @see AnnotationTreeIterator#goRight
*
* @fn AnnotationTreeIterator#goDown
*
* @brief Move the iterator down to the leftmost child in the annotation tree.
*
* @signature bool goDown(it);
*
* @param[in,out] it The AnnotationTreeIterator to move.
*
* @return bool <tt>true</tt> if the iterator could be moved and <tt>false</tt>
* otherwise.
*
* @see AnnotationTreeIterator#goUp
* @see AnnotationTreeIterator#goRight
*
* @fn AnnotationTreeIterator#goRight
*
* @brief Move the iterator right to the next sibling in the annotation tree.
*
* @signature bool goRight(it);
*
* @param[in,out] it The AnnotationTreeIterator to move.
*
* @return bool <tt>true</tt> if the iterator could be moved and <tt>false</tt>
* otherwise.
*
* @see AnnotationTreeIterator#goUp
* @see AnnotationTreeIterator#goDown
*
* @fn AnnotationTreeIterator#nodeUp
*
* @brief Returns a new iterator to the parent node of the current annotation in
* the annotation tree.
*
* @signature TIter nodeUp(it);
*
* @param[in] it The AnnotationTreeIterator to query.
*
* @return TIter Iterator to the parent node.
*
* @see AnnotationTreeIterator#nodeDown
* @see AnnotationTreeIterator#nodeRight
*
* @fn AnnotationTreeIterator#nodeDown
*
* @brief Returns a new iterator to the first child node of the current
* annotation in the annotation tree.
*
* @signature TIter nodeDown(it);
*
* @param[in] it The AnnotationTreeIterator to query.
*
* @return TIter Iterator to the first child node of it.
*
* @see AnnotationTreeIterator#nodeUp
* @see AnnotationTreeIterator#nodeRight
*
* @fn AnnotationTreeIterator#nodeRight
*
* @brief Returns a new iterator to the right sibling of the current annotation
* in the annotation tree.
*
* @signature TIter nodeRight(it);
*
* @param[in] it The AnnotationTreeIterator to query.
*
* @return TIter Iterator to the right sibling of it.
*
* @see AnnotationTreeIterator#nodeUp
* @see AnnotationTreeIterator#nodeDown
*
* @fn AnnotationTreeIterator#createLeftChild
*
* @brief Create a new leftmost child of the current node and returns an
* iterator to it.
*
* @signature TIter createLeftChild(it);
*
* @param[in,out] it The AnnotationTreeIterator to create a left child for.
*
* @return TIter Iterator to the new child.
*
* @see AnnotationTreeIterator#createRightChild
* @see AnnotationTreeIterator#createSibling
*
* @fn AnnotationTreeIterator#createRightChild
*
* @brief Creates a new rightmost child of the current node and returns an
* iterator to it.
*
* @signature TIter createRightChild(it);
*
* @param[in,out] it The AnnotationTreeIterator that was just created.
*
* @return TIter Iterator to the new child.
*
* @see AnnotationTreeIterator#createLeftChild
* @see AnnotationTreeIterator#createSibling
*
* @fn AnnotationTreeIterator#createSibling
*
* @brief Creates a new right sibling of the current node and return an iterator
* to it.
*
* @signature TIter createSibling(it);
*
* @param[in] it The AnnotationTreeIterator to create the sibling for.
*
* @return TIter Iterator to the new sibling.
*
* @see AnnotationTreeIterator#createLeftChild
* @see AnnotationTreeIterator#createRightChild
*
* @fn AnnotationTreeIterator#isRoot
*
* @brief Return a boolean indicating whether the annotation is the root.
*
* @signature bool isRoot(it);
*
* @param[in] it The AnnotationTreeIterator to query.
*
* @fn AnnotationTreeIterator#isLeaf
*
* @brief Return a boolean indicating whether the annotation is a leaf.
*
* @signature bool isLeaf(it);
*
* @param[in] it The AnnotationTreeIterator to query.
*
* @fn AnnotationTreeIterator#isLastChild
*
* @brief Returns a boolean value that indicates whether the current node is the
* last child.
*
* @signature bool isLastChild(it);
*
* @param[in] it The AnnotationTreeIterator to query.
*/