Concept ContainerConcept

A container is an object that stores other objects (elements).

/*!
 * @concept ContainerConcept
 * 
 * @headerfile <seqan/basic.h>
 * 
 * @extends AssignableConcept
 * @extends DestructibleConcept
 * 
 * @brief A container is an object that stores other objects (<i>elements</i>).
 * 
 * @signature ContainerConcept<T>
 * 
 * Containers store multiple entries of the same type (the <i>element type</i>)
 * and provide means to access these items. More specific, each container has an
 * iterator type that is used for accessing its elements.
 * 
 * There is no guarantee for the elements to be in a particular order (the order
 * can vary between two iterations) and no guarantee for the time complexity of
 * element access. Furthermore, there is no guarantee that there can be more
 * than one iterator in the container. Modification of a container through an
 * iterator invalidates all other iterators.
 * 
 * Refinements of the Container concept or specific implementations can provide
 * these guarantees, however.
 * 
 * A container owns its elements and the elements are destructed when their
 * owning container is destructed. The elements must fulfill the concepts @link
 * AssignableConcept @endlink and @link DestructibleConcept @endlink.
 * 
 * @fn ContainerConcept#directionIterator
 * 
 * @brief Returns direction iterator for a container.
 * 
 * @signature TDirIter directionIterator(streamBuf, dirTag);
 * 
 * @param[in] streamBuf The @link ContainerConcept container @endlink object to
 *                      compute iterator for.
 * @param[in] dirTag Direction tag, one of the @link DirectionTags @endlink.
 * 
 * @return TDirIter The resulting @link ContainerConcept#DirectionIterator
 *                  @endlink.
 * 
 * @fn ContainerConcept#getObjectId
 * 
 * @headerfile <seqan/sequence.h>
 * 
 * @brief A value that identifies the underlying sequence.
 * 
 * @signature TVoidPtr getObjectId(cont);
 * 
 * @param[in] cont The object for which to determine the id.
 * 
 * @return TVoidPtr a <tt>void const *</tt> value identying the object.
 * 
 * Two sequences should have the same id, if they share the same resource, e.g.
 * the same memory buffer.
 * 
 * The exact semantic of the returned id can vary for different classes.
 * Typically, the id of a string is a <tt>void const *</tt> to the end of the
 * string.
 * 
 * @section Examples
 * 
 * @code{.cpp}
 * String<char> str = "hallo seqan";
 * bool b1 = (getObjectId(str) == getObjectId(infix(str, 3, 7));   //true
 * bool b2 = (getObjectId(str) == getObjectId(String<char>(str))); //false
 * bool b3 = (getObjectId(str) == getObjectId(toCString(str)));
 * @endcode
 * 
 * 
 * In this example, <tt>b1</tt> is <tt>true</tt., since the segment object
 * returned by <tt>infix()</tt> is just a filter and uses the buffer of it's
 * host object str.
 * 
 * <tt>String&lt;char&gt;(str)</tt> constructs a temporary copy of <tt>str</tt>,
 * so these two strings have different id values.
 * 
 * The result of the last comparison depends on the implementation of
 * <tt>toCString</tt> and cannot be predicted at compile time.
 * 
 * @fn ContainerConcept#moveValue
 * 
 * @headerfile <seqan/sequence.h>
 * 
 * @brief Move a value into a container at a given position.
 * 
 * @signature void moveValue(container, pos, value);
 * 
 * @param[in,out] container The container to manipulate.
 * @param[in] pos The position of the item in the container to manipulate.
 * @param[in,out] value The value to move to <tt>container[pos]</tt>.
 * 
 * @fn ContainerConcept#append
 * 
 * @headerfile <seqan/sequence.h>
 * 
 * @brief Concatenate a container to another.
 * 
 * @signature void append(target, source);
 * 
 * @param[in,out] target The @link ContainerConcept container @endlink to append
 *                       <tt>source</tt> to.
 * @param[in] source This @link ContainerConcept container @endlink will be
 *                   appended to <tt>source</tt>.
 * 
 * @fn ContainerConcept#appendValue
 * 
 * @headerfile <seqan/sequence.h>
 * 
 * @brief Append a value to a container.
 * 
 * @signature void appendValue(target, val[, tag]);
 * 
 * @param[in,out] target The container to append <tt>val</tt> to.
 * @param[in] val The value to append to <tt>target</tt>.
 * @param[in] tag The resize tag to use. Defaults to What
 *                DefaultOverflowImplicit returns for the type of
 *                <tt>target</tt>.
 * 
 * @fn ContainerConcept#shrinkToFit
 * 
 * @headerfile <seqan/sequence.h>
 * 
 * @brief Resizes container to minimum capacity.
 * 
 * @signature void shrinkToFit(cont);
 * 
 * @param[in] cont The container to shrink.
 * 
 * @fn ContainerConcept#begin
 * 
 * @brief Returns an iterator to the beginning of the container.
 * 
 * @signature TIterator begin(c[, tag]);
 * 
 * @param[in] c The container to get the begin iterator for (type
 *              <tt>TContainer</tt>).
 * @param[in] tag An optional tag for selecting the type of the iterator. One of
 *                <tt>Standard</tt> and <tt>Rooted</tt>. When left out, @link
 *                ContainerConcept#DefaultGetIteratorSpec @endlink of
 *                <tt>TContainer</tt> is used.
 * 
 * @return TIterator Iterator to the beginning of the container, the type is
 *                   selected by @link ContainerConcept#Iterator @endlink with
 *                   the given (or default) tag.
 * 
 * When empty, <tt>begin(c) == end(c)</tt>.
 * 
 * @fn ContainerConcept#end
 * 
 * @brief Returns an iterator to the end of the container.
 * 
 * @signature TIterator end(c[, tag]);
 * 
 * @param[in] c The container to get the end iterator for (type
 *              <tt>TContainer</tt>).
 * @param[in] tag An optional tag for selecting the type of the iterator. One of
 *                <tt>Standard</tt> and <tt>Rooted</tt>. When left out, @link
 *                ContainerConcept#DefaultGetIteratorSpec @endlink of
 *                <tt>TContainer</tt> is used.
 * 
 * @return TIterator Iterator to the end of the container, the type is selected
 *                   by @link ContainerConcept#Iterator @endlink with the given
 *                   (or default) tag.
 * 
 * When empty, <tt>begin(c) == end(c)</tt>.
 * 
 * @fn ContainerConcept#length
 * 
 * @brief Returns the size of the container.
 * 
 * @signature TSize length(c);
 * 
 * @param[in] c The container to query for its size.
 * 
 * @return TSize The number of elements in the container.
 * 
 * @fn ContainerConcept#empty
 * 
 * @brief Returns whether the container is empty.
 * 
 * @signature bool empty(c);
 * 
 * @param[in] c The container to query.
 * 
 * @return bool Whether or not the container is empty.
 * 
 * @fn ContainerConcept#swap
 * 
 * @brief Swap the contents of two containers.
 * 
 * @signature void swap(c1, c2);
 * 
 * @param[in,out] c1 The first container.
 * @param[in,out] c2 The second container.
 * 
 * Swaps the contents of <tt>c1</tt> and <tt>c2</tt>. The <tt>swap</tt> function
 * must be defined in the same namespace as the container for Koenig lookup to
 * work. In the heart of sorting algorithms, for example, the swap function is
 * properly used as follows. This way, both the generic <tt>std::swap</tt> and
 * the specialized <tt>swap</tt> function of the container are available:
 * 
 * @code{.cpp}
 * TContainer c1, c2; // ...
 * using std::swap;
 * swap(c1, c2);
 * @endcode
 * 
 * 
 * @fn ContainerConcept#writeValue
 * 
 * @brief Write a value at the end of a container.
 * 
 * @signature void writeValue(container, val);
 * 
 * @param[in,out] container to append to.
 * @param[in] val The value to append.
 * 
 * @see ContainerConcept#appendValue
 * 
 * @fn ContainerConcept#write
 * 
 * @brief Write to a container.
 * 
 * @signature void write(container, iter, n);
 * 
 * @param[in,out] container The container to append to.
 * @param[in,out] iter The @link ForwardIteratorConcept forward iterator
 *                     @endlink to take the values from.
 * @param[in] n Number of elements to write from <tt>iter</tt>.
 * 
 * This function reads <tt>n</tt> values from <tt>iter</tt> and appends them to
 * the back of <tt>container</tt>.
 * 
 * @mfn ContainerConcept#Value
 * 
 * @brief Returns the value type of the container.
 * 
 * @signature Value<TContainer>::Type
 * 
 * @tparam TContainer The Container to query.
 * 
 * @return Type The element type of the container.
 * 
 * The value type is the type that can be used for storing copies of the
 * elements in the container.
 * 
 * @section Valid Expressions
 * 
 * The variable v has the value type of the container TContainer whereas it is
 * an iterator into the container. Thus, copies of values from TContainer (*it)
 * ca be stored in v.
 * 
 * @code{.cpp}
 * Value<TContainer>::Type v = *it;
 * @endcode
 * 
 * 
 * @mfn ContainerConcept#GetValue
 * 
 * @brief Returns the get-value type of the container.
 * 
 * @signature GetValue<TContainer>::Type
 * 
 * @tparam TContainer The Container to query.
 * 
 * @return Type The get-value type of the container.
 * 
 * The get-value type of the container is a type for efficient read-only access
 * to the elements in the container. For small types (e.g. <tt>int</tt>), this
 * can be a copy (thus <tt>int</tt>), for larger types, this can be a const
 * reference to the value type.
 * 
 * @section Valid Expressions
 * 
 * The variable v has the get-value type of the container TContainer whereas it
 * is an iterator into the container. Thus, we can store a get-value in v.
 * 
 * @code{.cpp}
 * GetValue<TContainer>::Type v = *it;
 * @endcode
 * 
 * 
 * @mfn ContainerConcept#Reference
 * 
 * @brief Returns the reference type of the container.
 * 
 * @signature Reference<TContainer>::Type
 * 
 * @tparam TContainer The Container to query.
 * 
 * @return Type The reference type of the container.
 * 
 * Different from STL containers, the const-ness of <tt>TContainer</tt> decides
 * whether the returned type is a const reference or a reference for modifying
 * elements.
 * 
 * Note that the reference type is not guaranteed to be <tt>TValue &amp;</tt> if
 * the value type of the container is <tt>TValue</tt>. The reference can be
 * implemented as a proxy, similar to <tt>std::vector&lt;bool&gt;</tt>.
 * 
 * @section Valid Expressions
 * 
 * The variable r has the reference type of the container TContainer whereas it
 * is an iterator into the container. Thus, we can store a reference to a value
 * in the container in r. Then, we can assign the value of v, a value of the
 * container.
 * 
 * @code{.cpp}
 * Reference<TContainer>::Type r = *it;  // reference into container
 * r = v;  // updates value in container, thus also *it
 * @endcode
 * 
 * 
 * @mfn ContainerConcept#Iterator
 * 
 * @brief Returns the iterator type of the container.
 * 
 * @signature Iterator<TContainer[, TSpec]>::Type
 * 
 * @tparam TContainer The Container type to query.
 * @tparam TSpec Optionally, a tag for selecting the kind of iterator. If not
 *               given, then @link ContainerConcept#DefaultIteratorSpec @endlink
 *               of TContainer is used. When given, one of <tt>Standard</tt> and
 *               <tt>Rooted</tt>.
 * 
 * @return Type The iterator type.
 * 
 * Different from the STL the <tt>const</tt> attribute of <tt>TContainer</tt>
 * determines whether the resturned iterator is a const iterator or a non-const
 * iterator.
 * 
 * @see ContainerIteratorTags
 * 
 * @mfn ContainerConcept#Size
 * 
 * @brief Returns the size type of a container.
 * 
 * @signature Size<TContainer>::Type
 * 
 * @tparam TContainer The Container type to query.
 * 
 * @return Type The type to use for storing container sizes.
 * 
 * @mfn ContainerConcept#Position
 * 
 * @brief Returns the position type of a container.
 * 
 * @signature Positin<TContainer>::Type
 * 
 * @tparam TContainer The Container type to query.
 * 
 * @return Type The type to use for storing container positions.
 * 
 * @mfn ContainerConcept#Difference
 * 
 * @brief Returns the type for distances between two iterators.
 * 
 * @signature Size<TContainer>::Type
 * 
 * @tparam TContainer The Container type to query.
 * 
 * @return Type The type to use for storing iterator distances sizes.
 * 
 * This must be the same type as the distance type of the containers iterators.
 * 
 * @mfn ContainerConcept#DirectionIterator
 * 
 * @brief Return the direction iterator for the given direction.
 * 
 * @signature DirectionIterator<TContainer>::Type;
 * 
 * @tparam TContainer The container to query for its direction iterator.
 * 
 * @return Type The resulting direction iterator.
 * 
 * @mfn ContainerConcept#DefaultIteratorSpec
 * 
 * @brief Returns the default iterator specialization.
 * 
 * @signature DefaultIteratorSpec<TContainer>::Type
 * 
 * @tparam TContainer The Container type to query.
 * 
 * @return Type The iterator specialization tag type.
 * 
 * Used by @link ContainerConcept#Iterator @endlink to select the default value
 * for <tt>TSpec</tt>.
 * 
 * @see ContainerConcept#Iterator
 * 
 * @mfn ContainerConcept#DefaultGetIteratorSpec
 * 
 * @brief Returns the default iterator specialization for functions.
 * 
 * @signature DefaultGetIteratorSpec<TContainer>::Type
 * 
 * @tparam TContainer The Container type to query.
 * 
 * @return Type The iterator specialization tag type.
 * 
 * Used by functions such as @link ContainerConcept#begin @endlink and @link
 * ContainerConcept#end @endlink for the <tt>TSpec</tt> parameter.
 * 
 * @see ContainerConcept#Iterator
 */