Spec AnnotationTreeIterator

Iterator of the annotation tree represetned by a FragmentStore.

/*!
 * @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&lt;TFragmentStore&gt;::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
 *                     SequenceConcept @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
 *                SequenceConcept @endlink.
 * @param[in] value The value that should be assigned. Type: @link
 *                  SequenceConcept @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, value);
 * 
 * @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.
 */