Class Journaled String Tree

This data structure represents a virtual set of strings using a veritcal compression scheme.

/*!
 * @class JournaledStringTree Journaled String Tree
 * 
 * @headerfile <seqan/journaled_string_tree.h>
 * 
 * @brief This data structure represents a virtual set of strings using a
 *        veritcal compression scheme.
 * 
 * @signature template <typename TSequence[, typename TConfig][, TSpec]> class
 *            JournaledStringTree<TDeltaStore, TConfig, TSpec>;
 * 
 * @tparam TSequence Type of underlying base sequence.
 * @tparam TConfig A configuration object, whose traits can be used to
 *                 specialize the underlying @link DeltaMap @endlink. Defaults
 *                 to @link DefaultJstConfig @endlink.
 * @tparam TSpec The specialization tag for the journaled string tree. Defaults
 *               to @link Default @endlink.
 * 
 * This data structure stores a virtual set of sequences in a compressed form.
 * The sequences are described in form of a pointer to a common reference
 * sequence and in addition delta events, which are stored in a @link DeltaMap
 * @endlink. The interface is a hybrid between a container interface and a
 * associative container interface. So it uses typical string set intrefaces to
 * access the virtual strings. On the other hand it implements an associative
 * container to store the delta events given their reference position as a key.
 * This data structure can then be traversed efficiently, while exploring only
 * those sequence contexts, that are unique to the set of sequences. This means,
 * that redundant parts, that are shared by one or many sequences is traversed
 * only once.
 * 
 * @mfn JournaledStringTree#Spec
 * 
 * @headerfile <seqan/journaled_string_tree.h>
 * 
 * @brief Returns the specialization type.
 * 
 * @signature Spec<TJst>::Type;
 * 
 * @tparam TJst The JST type to query the specialization type for.
 * 
 * @return TSpec The specialization type.
 * 
 * @mfn JournaledStringTree#Size
 * 
 * @headerfile <seqan/journaled_string_tree.h>
 * 
 * @brief The size type.
 * 
 * @signature Size<TJst>::Type;
 * 
 * @tparam TJst The JST type to get the size type for.
 * 
 * @return TSize The size type.
 * 
 * @mfn JournaledStringTree#Position
 * 
 * @headerfile <seqan/journaled_string_tree.h>
 * 
 * @brief The position type.
 * 
 * @signature Position<TJst>::Type;
 * 
 * @tparam TJst The JST type to get the position type for.
 * 
 * @return TPosition The position type.
 * 
 * @mfn JournaledStringTree#Host
 * 
 * @headerfile <seqan/journaled_string_tree.h>
 * 
 * @brief The host type.
 * 
 * @signature Host<TJst>::Type;
 * 
 * @tparam TJst The JST type to get the host type for.
 * 
 * @return THost The type of the underlying data structure.
 * 
 * @fn JournaledStringTree::JournaledStringTree
 * 
 * @headerfile <seqan/journaled_string_tree.h>
 * 
 * @brief Constructor.
 * 
 * @signature JournaledStringTree();
 * @signature JournaledStringTree(size);
 * @signature JournaledStringTree(source, size);
 * 
 * @param size The number of sequences represented by the JST.
 * @param source The underlying base sequence to which the sequences are
 *               compressed.
 * 
 * @fn JournaledStringTree#host
 * 
 * @headerfile <seqan/journaled_string_tree.h>
 * 
 * @brief Returns the set base sequence.
 * 
 * @signature THost host(jst);
 * 
 * @param[in] jst The journaled string tree.
 * 
 * @return THost A reference to the host of type @link JournaledStringTree#Host
 *               @endlink.
 * 
 * @fn JournaledStringTree#setHost
 * 
 * @headerfile <seqan/journaled_string_tree.h>
 * 
 * @brief Sets the base sequence of the journaled string tree.
 * 
 * @signature void setHost(jst, host);
 * 
 * @param[in,out] jst The journaled string tree.
 * @param[in] host The new host to set.
 * 
 * When setting a new host, the <tt>jst</tt> will be cleared all previous
 * information are lost.
 * 
 * @fn JournaledStringTree#length
 * 
 * @headerfile <seqan/journaled_string_tree.h>
 * 
 * @brief Returns the number of sequences represented by the journaled string
 *        tree.
 * 
 * @signature TSize length(jst);
 * 
 * @param[in] jst The journaled string tree to query the length for.
 * 
 * @return TSize The number of sequences represented by the <tt>jst<\tt>. Of
 *               type @link JournaledStringTree#Size @endlink.
 * 
 * @fn JournaledStringTree#resize
 * 
 * @headerfile <seqan/journaled_string_tree.h>
 * 
 * @brief Resizes the number of sequences represented by the journaled string
 *        tree.
 * 
 * @signature void resize(jst, size);
 * 
 * @param[in,out] jst The journaled string tree to resize.
 * @param[in] size The new size of the <tt>jst</tt>.
 * 
 * Note, when invoking this method all stored delta events are parsed and their
 * coverage is resized to the given <tt>size</tt>. If <tt>size</tt> is smaller
 * than the previous size this reduces the actual size of the stored coverages.
 * If <tt>size</tt> is bigger than the previous size, the coverages are filled
 * up with 0s, i.e. they represent a copy of the underlying base sequence. Hence
 * the performance is linear in the number of stored delta events times the
 * linear time for resizing the coverages.
 * 
 * @see JournaledStringTree#length
 * 
 * @fn JournaledStringTree#clear
 * 
 * @headerfile <seqan/journaled_string_tree.h>
 * 
 * @brief Clears the journaled string tree.
 * 
 * @signature void clear(jst);
 * 
 * @param[in,out] jst The journaled string tree to be cleared.
 * 
 * @fn JournaledStringTree#insert
 * 
 * @headerfile <seqan/journaled_string_tree.h>
 * 
 * @brief Adds a new delta ecent to the journaled string tree.
 * 
 * @signature bool insert(jst, pos, val, ids, type);
 * 
 * @param[in,out] jst The journaled string tree to be modified.
 * @param[in] pos The position of the host to place the new delta event at. This
 *                position must not exceed length of the @link
 *                JournaledStringTree#host @endlink.
 * @param[in] val The value of the delta event.
 * @param[in] ids An object of @link ContainerConcept @endlink storing the ids
 *                of the sequences covering this delta event. The ids must be in
 *                the range [0, @link JournaledStringTree#length @endlink).
 * @param[in] type A tag representing the type of the delta event. One of @link
 *                 DeltaTypeTags @endlink.
 * 
 * Note the value given by <tt>val<\tt> depends on the <tt>type<\tt>, which can
 * be a single character, a string, an integer or a pair of integer and string,
 * representing a SNP, an insertion, a deletion or a structural variant
 * respectively.
 * 
 * When inserting a deletion of size > 1 (the same holds for the structural
 * variant), the event is split into a left begin and a right begin and two
 * events are inserted into the underlying @link DeltaMap @endlink. Hence the
 * number of inserted events can differ from the actual number of calls to the
 * insert function.
 * 
 * @remark The insertion time depends on the implementation of the underlying
 * @link DeltaMap @endlink. See @link DeltaMap#insert @endlink for more details.
 * 
 * @see JournaledStringTree#erase
 * 
 * @fn JournaledStringTree#erase
 * 
 * @headerfile <seqan/journaled_string_tree.h>
 * 
 * @brief Erases a delta event in the journaled string tree.
 * 
 * @signature bool erase(jst, pos, type);
 * 
 * @param[in,out] jst The journaled string tree to be modified.
 * @param[in] pos The host source position of the delta event.
 * @param[in] type A tag representing the type of the delta event. One of @link
 *                 DeltaTypeTags @endlink. Note there can be multiple nodes at
 *                 the same <tt>pos<\tt> with different <tt>type<\tt>.
 * 
 * A delta event is described by it's host position and the type. If a left end
 * of a deletion is deleted its accompanied right end is deleted as well.
 * 
 * @remark The deletion time is depends on the implementation of the underlying
 * @link DeltaMap @endlink. See @link DeltaMap#erase @endlink for detailed
 * information.
 * 
 * @see JournaledStringTree#insert
 */