/*!
* @class String
*
* @implements StringConcept
* @implements TextConcept
* @implements SegmentableConcept
*
* @headerfile <seqan/sequence.h>
*
* @brief @link StringConcept Sequence @endlink container class.
*
* @signature template <typename TValue, typename TSpec> class String<TValue,
* TSpec>;
*
* @tparam TValue The element type of the string.
* @tparam TSpec The tag for selecting the string specialization.
*
* The String class is for storing sequences and thus at the core of the
* sequence analysis library SeqAn. They are models for the @link StringConcept
* sequence concept @endlink but extend the sequence concept by allowing
* implicit conversion of other sequence into strings as long as the element
* conversion works:
*
* @snippet demos/dox/sequence/string.cpp initializing strings
*
* Aside from that, the usual operations (appending, insertion, removing,
* element access) are available as well.
*
* @snippet demos/dox/sequence/string.cpp usual operations
*
* Strings have a size (the actual number of elements) and a capacity (the
* number of elements that memory has been allocated for). Note that clearing a
* string does not free the memory (as the STL, SeqAn assumes that strings will
* later require a similar amount of memory as before). Using @link
* ContainerConcept#shrinkToFit @endlink, the user can force a re-allocation of
* the memory such that the string afterward uses the minimal amount of memory
* to accomodate all of its objects.
*
* @snippet demos/dox/sequence/string.cpp clear and resize
*
* @section Examples
*
* This example shows a brute force pattern matching scheme for two character
* Strings. Creation of String "text" shows the usage of some available String
* operating functions. See class @link StringSet @endlink for an example of a
* String container with other than simple type values. See class @link Index
* @endlink example for efficiently finding the same pattern matches using an
* index.
*
* @include demos/dox/sequence/string2.cpp
*
* The output is as follows:
*
* @include demos/dox/sequence/string2.cpp.stdout
*
* @see StringSet
*
* @fn String#toCString
*
* @brief Access sequence as c-style string.
*
* @signature TValue* toCString(seq)
*
* @param seq The sequence to be accessed. Type: @link String @endlink
*
* @return TValue* For strings that store their elements in a contiguous block
* (see @link IsContiguous @endlink) a pointer to first element
* of $object$ is returned.
*
* @section Remarks
*
* If the alphabet of $object$ is $char$ or $wchar_t$ the return value is a
* c-style string representing the contents of <tt>object<tt/>.
*
* Calling this function for non-contiguous containers will raise a compilation
* error. To create c-style strings for non-contiguous strings or strings with
* different alphabets, use a @link CStyleString @endlink as an intermediate.
*
* @fn String#reserve
*
* @brief Increases the capacity.
*
* @signature TSize reserve(str, new_capacity[, tag]);
*
* @param[in,out] str The String to reserve space in.
* @param[in] newCapacity The new capacity <tt>str</tt> will get.
* @param[in] tag Specifies the strategy that is applied for changing the
* capacity.
*
* @return TSize The amount of the requested capacity that was available. That
* is the function returns the minimum of <tt>newCapacity</tt> and
* <tt>capacity(me)</tt>.
*
* This function allows one to increase the capacity but not the length of a
* container.
*
* Use @link StringConcept#resize @endlink if you want to change the size of a
* container.
*
* @section Remarks
*
* At the end of the operation, <tt>capacity(me)</tt> can be larger than
* <tt>new_capacity</tt>. If <tt>new_capacity</tt> is smaller than
* <tt>capacity(me)</tt> at the beginning of the operation, the operation need
* not to change the capacity at all.
*
* This operation does not changes the content of <tt>object</tt>.
*
* This operation may invalidate iterators of <tt>object</tt>.
*
* @fn String#resizeSpace
*
* @headerfile <seqan/sequence.h>
*
* @brief Makes free space in container
*
* @signature TSize resizeSpace(str, size, posBegin, posEnd [, limit][,
* resizeTag]);
*
* @param[in,out] str The String to modify.
* @param[in] size Number of characters that should be freed.
* @param[in] posEnd Position behind the last item in <tt>object</tt> that is to
* be destroyed. If <tt>posEnd == posBegin</tt>, no item in
* <tt>object</tt> will be destroyed.
* @param[in] posBegin Position of the first item in <tt>object</tt> that is to
* be destroyed.
* @param[in] limit Maximal length <tt>object</tt> can get after this operation.
* (optional)
* @param[in] resizeTag Strategy that is applied if <tt>object</tt> has not
* enough capacity to store the complete content.
* (optional)
*
* @return TSize The number of free characters.Depeding on resizeTag, this could
* be <tt>size</tt> or less than <tt>size</tt> if <tt>object</tt>
* has not enough <tt>capacity</tt>.
*
* @fn String#beginPosition
*
* @headerfile <seqan/sequence.h>
*
* @brief Return 0 for compatibility with @link Segment @endlink.
*
* @signature TPos beginPosition(str);
*
* @param[in] seg The String to use.
*
* @return TPos Always 0.
*
* @fn String#endPosition
*
* @headerfile <seqan/sequence.h>
*
* @brief Return length of string for compatibility with @link Segment @endlink.
*
* @signature TPos endPosition(str);
*
* @param[in] seg The string to use.
*
* @return TPos Length of the string.
*
* @fn String::String
*
* @brief Constructor.
*
* @signature String::String()
* @signature String::String(other)
*
* @param[in] other The source for the copy constructor. Can be of any @link
* StringConcept sequence @endlink type as long as
* <tt>other</tt>'s elements are convertible to the value type
* of this string.
*
* Default and copy constructor are implemented.
*
* @fn String::operator=
*
* @brief The String assignment operator allows assignment of convertible
* sequences.
*
* @signature TString String::operator=(other)
*
* @param[in] other The other string. Must be a sequence whose elements are
* convertible into this String's type.
*
* @return TString Reference to the String objecta after assignment.
*/