<commit_before>// ==========================================================================
//                 SeqAn - The Library for Sequence Analysis
// ==========================================================================
// Copyright (c) 2006-2013, <NAME>, FU Berlin
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are met:
//
//     * Redistributions of source code must retain the above copyright
//       notice, this list of conditions and the following disclaimer.
//     * Redistributions in binary form must reproduce the above copyright
//       notice, this list of conditions and the following disclaimer in the
//       documentation and/or other materials provided with the distribution.
//     * Neither the name of Knut Reinert or the FU Berlin nor the names of
//       its contributors may be used to endorse or promote products derived
//       from this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
// ARE DISCLAIMED. IN NO EVENT SHALL KNUT REINERT OR THE FU BERLIN BE LIABLE
// FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
// DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
// SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
// LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
// OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
// DAMAGE.
//
// ==========================================================================
// Author: <NAME> <<EMAIL>>
// ==========================================================================
// Default implementations for sequences.
//
// TODO(holtgrew): There appears to be some overlap with string_base.h. Maybe it is a good idea to move everything related to strings to string_base.h and remove all default-container behaviour.
// TODO(holtgrew): Each value is a container by itself. This is highly undesirable since it introduces the set-of-sets problem and when users confuse atomic values with containers, bugs are hard to find. This feature should be removed.
// ==========================================================================

#ifndef SEQAN_SEQUENCE_SEQUENCE_INTERFACE_H_
#define SEQAN_SEQUENCE_SEQUENCE_INTERFACE_H_

namespace seqan {

// ============================================================================
// Forwards
// ============================================================================

// ============================================================================
// Tags, Classes, Enums
// ============================================================================

/**
.Tag.Overflow Strategy:
..cat:Sequences
..summary:The strategy for resizing containers.
..tag.Insist:No capacity check.
...remarks:The user has to ensure that the container's capacity is large enough.
..tag.Limit:Limit the contents to current capacity.
...remarks: All entries that exceed the capacity are lost.
..tag.Exact:Expand as far as needed.
...remarks: The capacity is only changed if the current capacity is not large enough.
 If the capacity can only be expanded up to a certain ammount, it will be increased as far as possible
 and the contents are limited to the new capacity.
...remarks:Note that the capacity will never be shrinked.
 Use @Function.shrinkToFit@ to resize the capacity down to the current length.
..tag.Generous:Expand if needed, get precautionary extra space.
...remarks:Whenever the capacity has to be increased, the new capacity is choosen somewhat large than actually needed.
 This strategy limits the number of capacity changes, so that resizing takes armotized constant time.
 Use this strategy if the total amount of storage is unkown at first.
...remarks:The new capacity is computed by @Function.computeGenerousCapacity@.
By default, it is guaranteed not to exceed about
 tree halfs of the space that is used to store the data.
 The user can overload @Function.computeGenerousCapacity@ in order to change this behavior.
..remarks:Changing the capacity of a container can invalidate the iterators of this container.
..remarks:If no overflow tag is specified, most operations use the default overflow strategy given by @Metafunction.DefaultOverflowImplicit@
or @Metafunction.DefaultOverflowExplicit@, depending on the kind of operation.
..include:seqan/sequence.h
*/
struct TagInsist_;
typedef Tag<TagInsist_> Insist;
typedef Tag<TagInsist_> Tight;

struct TagLimit_;
typedef Tag<TagLimit_> Limit;

struct TagGenerous_;
typedef Tag<TagGenerous_> Generous;

struct TagExact_;
typedef Tag<TagExact_> Exact;

// ============================================================================
// Metafunctions
// ============================================================================

// --------------------------------------------------------------------------
// Metafunction DefaultOverflowImplicit
// --------------------------------------------------------------------------

/**
.Metafunction.DefaultOverflowImplicit:
..hidefromindex
..class:Class.String
..summary:The default overflow strategy for implicit resize.
..signature:DefaultOverflowImplicit<T>::Type
..param.T:Type for which the overflow strategy is determined.
...type:Class.String
..returns.param.Type:Expansion tag for type of $T$.
..remarks:This function is used for functions that cause an implicit change of a container's size, like
e.g. @Function.assign@, @Function.append@, and @Function.replace@.
..see:Tag.Overflow Strategy
..include:seqan/sequence.h
*/
template <typename T>
struct DefaultOverflowImplicit
{
    typedef Generous Type;
};

// --------------------------------------------------------------------------
// Metafunction DefaultOverflowExplicit
// --------------------------------------------------------------------------

/**
.Metafunction.DefaultOverflowExplicit:
..hidefromindex
..class:Class.String
..summary:The default overflow strategy for explicit resize.
..signature:DefaultOverflowExplicit<T>::Type
..param.T:Type for which the overflow strategy is determined.
...type:Class.String
..returns.param.Type:Expansion tag for type of $T$.
..remarks:This function is used for functions that change a container's size explicit, like e.g. @Function.resize@.
..see:Tag.Overflow Strategy
..see:Metafunction.DefaultOverflowImplicit
..include:seqan/sequence.h
*/
template <typename T>
struct DefaultOverflowExplicit
{
    typedef Generous Type;
};

// --------------------------------------------------------------------------
// Metafunction IsContiguous
// --------------------------------------------------------------------------

/**
.Metafunction.IsContiguous:
..cat:Sequences
..summary:Determines whether a container stores its elements in a contiguous array.
..signature:IsContiguous<T>::VALUE
..param.T:Type that is tested for being a string.
..returns.param.VALUE:$true$ if $T$ is a string, $false$ otherwise.
..remarks:Definition: A sequence container is "contiguous", if its elements
    are stored in a single contiguous array.
    Examples for contiguous sequences are @Spec.Alloc String@ or @Adaption.char array@.
..remarks:If an object $obj$ is a contiguous sequence, then $begin(obj)$ can be
    converted to a pointer to the first element of the content array.
..include:seqan/sequence.h
*/
template <typename T>
struct IsContiguous
{
    typedef False Type;
    enum { VALUE = false };
};

template <typename T>
struct IsContiguous<T const>
    : public IsContiguous<T> {};

// --------------------------------------------------------------------------
// Metafunction IsSequence
// --------------------------------------------------------------------------

/**
.Metafunction.IsSequence:
..cat:Sequences
..summary:Determines whether a container stores its elements in sequential order.
..signature:IsSequence<T>::VALUE
..param.T:Type that is tested for being a sequence.
..returns.param.VALUE:$true$ if $T$ is a sequence, $false$ otherwise.
..remarks:For example @Class.String@ and @Class.Segment@ return $true$.
..include:seqan/sequence.h
*/
template <typename T>
struct IsSequence
{
    typedef False Type;
    enum { VALUE = false };
};

template <typename T>
struct IsSequence<T const>
    : public IsSequence<T> {};

// --------------------------------------------------------------------------
// Metafunction AllowsFastRandomAccess
// --------------------------------------------------------------------------

/**
.Metafunction.AllowsFastRandomAccess:
..cat:Sequences
..summary:Determines whether a sequence efficiently supports random access.
..signature:AllowsFastRandomAccess<T>::VALUE
..param.T:Type that is tested for fast random access.
..returns.param.VALUE:$true$ if $T$ supports fast random access, $false$ otherwise.
..remarks:For example @Spec.Alloc String@, @Class.Segment@, and @Spec.Block String@ return $true$.
..include:seqan/sequence.h
*/
template <typename T>
struct AllowsFastRandomAccess
{
    typedef True Type;
    enum { VALUE = true };
};

template <typename T>
struct AllowsFastRandomAccess<T const>
    : public AllowsFastRandomAccess<T> {};

// ============================================================================
// Functions
// ============================================================================

// --------------------------------------------------------------------------
// Function getObjectId()
// --------------------------------------------------------------------------

/**
.Function.getObjectId:
..cat:Miscellaneous
..class:Class.String
..summary:A value that identifies the underlying sequence.
..signature:void const * getObjectId(object)
..param.object:The object for which the id will be determined.
..returns:The id of $sequence$.
..remarks.text:Two sequences should have the same id, if they share the same resource, e.g. the same memory buffer.
..remarks.text:The exact semantic of the returned id can vary for different classes.
Typically, the id of a string is a $void const *$ to the end of the string.
..remarks.note:The id of a single character need not to be the id of its container.
..example.code: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)));
..example.text:In this example, $b1$ is $true$, since the segment object returned by $infix()$
is just a filter and uses the buffer of it's host object $str$.
..example.text:$String<char>(str)$ constructs a temporary copy of $str$, so these two
strings have different id values.
..example.text:The result of the last comparison depends on the implementation of $toCString$
and cannot be predicted at compile time.
..include:seqan/sequence.h
*/
template <typename T>
inline void const *
getObjectId(T const & me)
{
    SEQAN_CHECKPOINT;
    return end(me, Standard());
}

// --------------------------------------------------------------------------
// Function shareResources()
// --------------------------------------------------------------------------

/**
.Function.shareResources:
..cat:Miscellaneous
..class:Class.String
..summary:Determines whether two sequences share the same resource.
..signature:bool shareResources(sequence1, sequence2)
..param.sequence1, sequence2:Two sequences.
..returns:$false$ if it can be guaranteed that $sequence1$ and $sequence2$ can be modified without changing each other, $true$ otherwise.
..remarks:Non-sequences are interpreted as sequences of size 1.
..remarks:Note that this function may not work properly for argument types that are not listed here.
..include:seqan/sequence.h
*/

template <typename T1, typename T2>
inline bool
shareResources(T1 const & obj1,
               T2 const & obj2)
{
    SEQAN_CHECKPOINT;
    return getObjectId(obj1) == getObjectId(obj2);
}

// --------------------------------------------------------------------------
// Function _beginDefault()
// --------------------------------------------------------------------------

//* ???Anti Default Sequences
// TODO(holtgrew): Evil -- each value is a container of length 1.
template <typename T>
inline typename Iterator<T, Standard>::Type
_beginDefault(T & me,
               Standard)
{
    SEQAN_CHECKPOINT;
    return & me;
}
// TODO(holtgrew): Evil -- each value is a container of length 1.
template <typename T>
inline typename Iterator<T const, Standard>::Type
_beginDefault(T const & me,
               Standard)
{
    SEQAN_CHECKPOINT;
    return & me;
}
//*/

template <typename T>
inline typename Iterator<T, Rooted>::Type
_beginDefault(T & me,
               Rooted)
{
    SEQAN_CHECKPOINT;
    typedef typename Iterator<T, Rooted>::Type TIterator;
    return TIterator(me, begin(me, Standard()));
}
template <typename T>
inline typename Iterator<T const, Rooted>::Type
_beginDefault(T const & me,
               Rooted)
{
    SEQAN_CHECKPOINT;
    typedef typename Iterator<T const, Rooted>::Type TIterator;
    return TIterator(me, begin(me, Standard()));
}

// --------------------------------------------------------------------------
// Function begin()
// --------------------------------------------------------------------------

/**
.Function.begin:
..cat:Iteration
..cat:Containers
..class:Class.String
..class:Concept.ContainerConcept
..summary:The begin of a container.
..signature:Iterator begin(object [, tag])
..param.object:A container.
...type:Class.String
...concept:Concept.ContainerConcept
..param.tag:An @Tag.Iterator Spec.iterator spec@ tag that specifies the kind of the iterator returned. (optional)
...default:Given by @Metafunction.DefaultGetIteratorSpec@.
..returns:An iterator to the first item in $object$.
...metafunction:Metafunction.Iterator
..remarks.text:If the container does not contain any items at all, the function may return 0.
..see:Function.end
..see:Metafunction.Iterator
..include:seqan/sequence.h
*/
template <typename T>
inline typename Iterator<T, typename DefaultGetIteratorSpec<T>::Type>::Type
begin(T & me)
{
    SEQAN_CHECKPOINT;
    return begin(me, typename DefaultGetIteratorSpec<T>::Type()) ;
}

template <typename T>
inline typename Iterator<T const, typename DefaultGetIteratorSpec<T>::Type>::Type
begin(T const & me)
{
    SEQAN_CHECKPOINT;
    return begin(me, typename DefaultGetIteratorSpec<T>::Type()) ;
}

//folgende forward Deklaration wurde wegen Phaenomene bei VC++ 2003 hinzugenommen
//implemented in string_pointer.h
template <typename TValue>
inline typename Iterator<TValue const *, Standard>::Type
begin(TValue const * me,
      Standard);

template <typename T, typename TSpec>
inline typename Iterator<T, Tag<TSpec> const>::Type
begin(T & me,
      Tag<TSpec> const tag_)
{
    SEQAN_CHECKPOINT;
    return _beginDefault(me, tag_);
}
template <typename T, typename TSpec>
inline typename Iterator<T const, Tag<TSpec> const>::Type
begin(T const & me,
      Tag<TSpec> const tag_)
{
    SEQAN_CHECKPOINT;
    return _beginDefault(me, tag_);
}

/*
template <typename TValue>
inline typename Iterator<TValue *, Standard>::Type
begin(TValue * me,
      Standard)
{
    SEQAN_CHECKPOINT;
    return me;
}

//folgende Version wurde wegen eines seltsamen Phaenomens bei VC++ hinzugenommen
template <typename TValue>
inline typename Iterator<TValue const *, Standard>::Type
begin(TValue const * me,
      Standard)
{
    SEQAN_CHECKPOINT;
    return me;
}

template <typename TValue, typename TSpec>
inline typename Iterator<TValue *, Standard>::Type
begin(TValue * me,
      Tag<TSpec> const tag_)
//    Standard)
{
    SEQAN_CHECKPOINT;
    return me;
}

//folgende Version wurde wegen eines seltsamen Phaenomens bei VC++ hinzugenommen
template <typename TValue, typename TSpec>
inline typename Iterator<TValue const *, Standard>::Type
begin(TValue const * me,
      Tag<TSpec> const tag_)
//    Standard)
{
    SEQAN_CHECKPOINT;
    return me;
}
*/

// --------------------------------------------------------------------------
// Function beginPosition()
// --------------------------------------------------------------------------

/**
.Function.beginPosition:
..cat:Containers
..summary:Begin position of object in host.
..signature:Position beginPosition(object)
..class:Class.String
..class:Concept.ContainerConcept
..param.object:An object.
...type:Class.String
...concept:Concept.ContainerConcept
..returns:The position of the first item in $host(object)$ that belongs of $object$.
...metafunction:Metafunction.Position
..remarks
...text:For most classes $beginPosition$ always returns 0. Exceptions are e.g. @Spec.InfixSegment@ and @Spec.SuffixSegment@.
..see:Function.begin
..include:seqan/sequence.h
..example.code:
CharString str = "ABCDEF";
std::cout << beginPosition(str) << std::endl;

Infix<CharString >::Type myInfix = infix(str, 1, 5);
std::cout << beginPosition(myInfix) << std::endl;
*/
template <typename T>
inline typename Position<T>::Type
beginPosition(T &)
{
    SEQAN_CHECKPOINT;
    return 0;
}

template <typename T>
inline typename Position<T>::Type
beginPosition(T const &)
{
    SEQAN_CHECKPOINT;
    return 0;
}

// --------------------------------------------------------------------------
// Function _endDefault()
// --------------------------------------------------------------------------

//* ???Anti Default Sequences
template <typename T>
inline typename Iterator<T, Standard>::Type
_endDefault(T & me,
             Standard)
{
    SEQAN_CHECKPOINT;
    return (& me) + 1;
}
template <typename T>
inline typename Iterator<T const, Standard>::Type
_endDefault(T const & me,
             Standard)
{
    SEQAN_CHECKPOINT;
    return (& me) + 1;
}
//*/

template <typename T>
inline typename Iterator<T, Rooted>::Type
_endDefault(T & me,
             Rooted)
{
    SEQAN_CHECKPOINT;
    typedef typename Iterator<T, Rooted>::Type TIterator;
    return TIterator(me, end(me, Standard()));
}
template <typename T>
inline typename Iterator<T const, Rooted>::Type
_endDefault(T const & me,
             Rooted)
{
    SEQAN_CHECKPOINT;
    typedef typename Iterator<T const, Rooted>::Type TIterator;
    return TIterator(me, end(me, Standard()));
}

// --------------------------------------------------------------------------
// Function end()
// --------------------------------------------------------------------------

/**
.Function.end:
..cat:Iteration
..cat:Containers
..class:Class.String
..concept:Concept.ContainerConcept
..summary:The end of a container.
..signature:Iterator end(object [, tag])
..param.object:A container.
...type:Class.String
...concept:Concept.ContainerConcept
..param.tag:An @Tag.Iterator Spec.iterator spec@ tag that specifies the kind of the iterator returned. (optional)
...default:Given by @Metafunction.DefaultGetIteratorSpec@.
..returns:An iterator that points behind the last item in $object$.
...metafunction:Metafunction.Iterator
..remarks.text:If the container does not contain any items at all, the function may return 0.
..see:Function.begin
..see:Metafunction.Iterator
..include:seqan/sequence.h
*/
template <typename T>
inline typename Iterator<T, typename DefaultGetIteratorSpec<T>::Type>::Type
end(T & me)
{
    SEQAN_CHECKPOINT;
    return end(me, typename DefaultGetIteratorSpec<T>::Type()) ;
}

template <typename T>
inline typename Iterator<T const, typename DefaultGetIteratorSpec<T>::Type>::Type
end(T const & me)
{
    SEQAN_CHECKPOINT;
    return end(me, typename DefaultGetIteratorSpec<T>::Type()) ;
}

template <typename T, typename TSpec>
inline typename Iterator<T, Tag<TSpec> const>::Type
end(T & me,
    Tag<TSpec> const tag_)
{
    SEQAN_CHECKPOINT;
    return _endDefault(me, tag_);
}

template <typename T, typename TSpec>
inline typename Iterator<T const, Tag<TSpec> const>::Type
end(T const & me,
    Tag<TSpec> const tag_)
{
    SEQAN_CHECKPOINT;
    return _endDefault(me, tag_);
}

// --------------------------------------------------------------------------
// Function endPosition()
// --------------------------------------------------------------------------

/**
.Function.endPosition:
..cat:Containers
..class:Class.String
..concept:Concept.ContainerConcept
..summary:End position of object in host.
..signature:Position endPosition(object)
..param.object:An object.
...concept:Concept.ContainerConcept
...type:Class.String
..returns:The position behind the last item in $host(object)$ that belongs of $object$.
...metafunction:Metafunction.Position
..see:Function.end
..see:Function.beginPosition
..include:seqan/sequence.h
*/
template <typename T>
inline typename Position<T>::Type
endPosition(T & me)
{
    SEQAN_CHECKPOINT;
    return length(me);
}

template <typename T>
inline typename Position<T>::Type
endPosition(T const & me)
{
    SEQAN_CHECKPOINT;
    return length(me);
}

// --------------------------------------------------------------------------
// Function value()
// --------------------------------------------------------------------------

/**
.Function.value:
..cat:Iteration
..cat:Containers
..concept:Concept.ContainerConcept
..summary:Reference to the value.
..signature:Reference value(container, position)
..param.container:A container of values.
..param.position:A position in $container$ on which the value should be accessed.
..returns:A reference or proxy to the value.
...metafunction:Metafunction.Reference
..include:seqan/sequence.h
*/
//* ???Anti Default Sequences
template <typename T, typename TPos>
inline typename Reference<T>::Type
value(T & me,
      TPos /*pos*/)
{
    SEQAN_CHECKPOINT;
    return me;
}

template <typename T, typename TPos>
inline typename Reference<T const>::Type
value(T const & me,
      TPos /*pos*/)
{
    SEQAN_CHECKPOINT;
    return me;
}
//*/

// --------------------------------------------------------------------------
// Function getValue()
// --------------------------------------------------------------------------

/**
.Function.getValue:
..summary:Access to the value.
..cat:Containers
..cat:Content Manipulation
..concept:Concept.ContainerConcept
..signature:GetValue getValue(container, pos)
..param.container:A container.
...concept:Concept.ContainerConcept
..param.pos:The position of an item in $object$.
...remarks:$pos$ should be convertible to $Position<T>::Type$ for $container$-type $T$.
..returns:The item at position $pos$ in $container$.
This can either be a reference to the item or a temporary copy of the item.
...metafunction:Metafunction.GetValue
..remarks:
...text:If $pos$ is out of range, then the behavior of the function is undefined.
..see:Metafunction.GetValue
..see:Metafunction.Position
..see:Function.value
..include:seqan/sequence.h
*/
template <typename T, typename TPos>
inline typename GetValue<T>::Type
getValue(T & me,
         TPos pos)
{
    SEQAN_CHECKPOINT;
    return (typename GetValue<T>::Type) value(me, pos);
}

template <typename T, typename TPos>
inline typename GetValue<T const>::Type
getValue(T const & me,
         TPos pos)
{
    SEQAN_CHECKPOINT;
    return value(me, pos);
}

// --------------------------------------------------------------------------
// Function front()
// --------------------------------------------------------------------------

/**
.Function.front:
..cat:Containers
..concept:Concept.ContainerConcept
..summary:The first item in container.
..signature:Iterator front(container)
..param.container:A container.
...concept:Concept.ContainerConcept
..returns:A @Metafunction.Reference.reference@ of the first item in $container$.
...metafunction:Metafunction.Reference
..remarks:This function is equivalent to $value(me, 0)$.
..see:Function.value
..see:Function.begin
..include:seqan/sequence.h
*/

template <typename T>
inline typename Reference<T>::Type
front(T & me)
{
    SEQAN_CHECKPOINT;
    return value(me, 0);
}
template <typename T>
inline typename Reference<T const>::Type
front(T const & me)
{
    SEQAN_CHECKPOINT;
    return value(me, 0);
}

// --------------------------------------------------------------------------
// Function back()
// --------------------------------------------------------------------------

/**
.Function.back:
..cat:Containers
..concept:Concept.ContainerConcept
..summary:The last item in container.
..signature:Iterator back(container)
..param.container:A container.
...concept:Concept.ContainerConcept
..returns:A @Metafunction.Reference.reference@ of the last item in $container$.
...metafunction:Metafunction.Reference
..remarks:This function is equivalent to $value(me, length(me) - 1)$.
..see:Function.value
..see:Function.end
..see:Function.front
..include:seqan/sequence.h
*/

template <typename T>
inline typename Reference<T const>::Type
back(T const & me)
{
    SEQAN_CHECKPOINT;
    return value(me, length(me) - 1);
}

template <typename T>
inline typename Reference<T>::Type
back(T & me)
{
    SEQAN_CHECKPOINT;
    return value(me, length(me) - 1);
}

// --------------------------------------------------------------------------
// Function iter()
// --------------------------------------------------------------------------

/**
.Function.iter:
..cat:Containers
..class:Class.String
..summary:Iterator to item at given position.
..signature:Iterator iter(object, pos [, tag])
..param.object:A container.
...type:Class.String
..param.pos:The position of an item in $object$.
...metafunction:Metafunction.Position
..param.tag:An @Tag.Iterator Spec.iterator spec@ tag that specifies the kind of the iterator returned. (optional)
...default:Given by @Metafunction.DefaultGetIteratorSpec@.
..returns:An iterator to the item at position $pos$ in $object$.
...metafunction:Metafunction.Iterator
..remarks:
...text:If $pos$ is out of range, then the behavior of the function is undefined.
..see:Function.value
..see:Metafunction.Iterator
..see:Metafunction.Position
..include:seqan/sequence.h
 */
template <typename T, typename TPos>
inline typename Iterator<T, typename DefaultGetIteratorSpec<T>::Type>::Type
iter(T & me,
     TPos pos)
{
    SEQAN_CHECKPOINT;
    return iter(me, pos, typename DefaultGetIteratorSpec<T>::Type());<commit_msg>[DOC,FIXES-#1057] Explicitely stating the return type of `begin()` and `end()`.<commit_after>// ==========================================================================
//                 SeqAn - The Library for Sequence Analysis
// ==========================================================================
// Copyright (c) 2006-2013, <NAME>, FU Berlin
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are met:
//
//     * Redistributions of source code must retain the above copyright
//       notice, this list of conditions and the following disclaimer.
//     * Redistributions in binary form must reproduce the above copyright
//       notice, this list of conditions and the following disclaimer in the
//       documentation and/or other materials provided with the distribution.
//     * Neither the name of <NAME> or the FU Berlin nor the names of
//       its contributors may be used to endorse or promote products derived
//       from this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
// ARE DISCLAIMED. IN NO EVENT SHALL KNUT REINERT OR THE FU BERLIN BE LIABLE
// FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
// DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
// SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
// LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
// OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
// DAMAGE.
//
// ==========================================================================
// Author: <NAME> <<EMAIL>>
// ==========================================================================
// Default implementations for sequences.
//
// TODO(holtgrew): There appears to be some overlap with string_base.h. Maybe it is a good idea to move everything related to strings to string_base.h and remove all default-container behaviour.
// TODO(holtgrew): Each value is a container by itself. This is highly undesirable since it introduces the set-of-sets problem and when users confuse atomic values with containers, bugs are hard to find. This feature should be removed.
// ==========================================================================

#ifndef SEQAN_SEQUENCE_SEQUENCE_INTERFACE_H_
#define SEQAN_SEQUENCE_SEQUENCE_INTERFACE_H_

namespace seqan {

// ============================================================================
// Forwards
// ============================================================================

// ============================================================================
// Tags, Classes, Enums
// ============================================================================

/**
.Tag.Overflow Strategy:
..cat:Sequences
..summary:The strategy for resizing containers.
..tag.Insist:No capacity check.
...remarks:The user has to ensure that the container's capacity is large enough.
..tag.Limit:Limit the contents to current capacity.
...remarks: All entries that exceed the capacity are lost.
..tag.Exact:Expand as far as needed.
...remarks: The capacity is only changed if the current capacity is not large enough.
 If the capacity can only be expanded up to a certain ammount, it will be increased as far as possible
 and the contents are limited to the new capacity.
...remarks:Note that the capacity will never be shrinked.
 Use @Function.shrinkToFit@ to resize the capacity down to the current length.
..tag.Generous:Expand if needed, get precautionary extra space.
...remarks:Whenever the capacity has to be increased, the new capacity is choosen somewhat large than actually needed.
 This strategy limits the number of capacity changes, so that resizing takes armotized constant time.
 Use this strategy if the total amount of storage is unkown at first.
...remarks:The new capacity is computed by @Function.computeGenerousCapacity@.
By default, it is guaranteed not to exceed about
 tree halfs of the space that is used to store the data.
 The user can overload @Function.computeGenerousCapacity@ in order to change this behavior.
..remarks:Changing the capacity of a container can invalidate the iterators of this container.
..remarks:If no overflow tag is specified, most operations use the default overflow strategy given by @Metafunction.DefaultOverflowImplicit@
or @Metafunction.DefaultOverflowExplicit@, depending on the kind of operation.
..include:seqan/sequence.h
*/
struct TagInsist_;
typedef Tag<TagInsist_> Insist;
typedef Tag<TagInsist_> Tight;

struct TagLimit_;
typedef Tag<TagLimit_> Limit;

struct TagGenerous_;
typedef Tag<TagGenerous_> Generous;

struct TagExact_;
typedef Tag<TagExact_> Exact;

// ============================================================================
// Metafunctions
// ============================================================================

// --------------------------------------------------------------------------
// Metafunction DefaultOverflowImplicit
// --------------------------------------------------------------------------

/**
.Metafunction.DefaultOverflowImplicit:
..hidefromindex
..class:Class.String
..summary:The default overflow strategy for implicit resize.
..signature:DefaultOverflowImplicit<T>::Type
..param.T:Type for which the overflow strategy is determined.
...type:Class.String
..returns.param.Type:Expansion tag for type of $T$.
..remarks:This function is used for functions that cause an implicit change of a container's size, like
e.g. @Function.assign@, @Function.append@, and @Function.replace@.
..see:Tag.Overflow Strategy
..include:seqan/sequence.h
*/
template <typename T>
struct DefaultOverflowImplicit
{
    typedef Generous Type;
};

// --------------------------------------------------------------------------
// Metafunction DefaultOverflowExplicit
// --------------------------------------------------------------------------

/**
.Metafunction.DefaultOverflowExplicit:
..hidefromindex
..class:Class.String
..summary:The default overflow strategy for explicit resize.
..signature:DefaultOverflowExplicit<T>::Type
..param.T:Type for which the overflow strategy is determined.
...type:Class.String
..returns.param.Type:Expansion tag for type of $T$.
..remarks:This function is used for functions that change a container's size explicit, like e.g. @Function.resize@.
..see:Tag.Overflow Strategy
..see:Metafunction.DefaultOverflowImplicit
..include:seqan/sequence.h
*/
template <typename T>
struct DefaultOverflowExplicit
{
    typedef Generous Type;
};

// --------------------------------------------------------------------------
// Metafunction IsContiguous
// --------------------------------------------------------------------------

/**
.Metafunction.IsContiguous:
..cat:Sequences
..summary:Determines whether a container stores its elements in a contiguous array.
..signature:IsContiguous<T>::VALUE
..param.T:Type that is tested for being a string.
..returns.param.VALUE:$true$ if $T$ is a string, $false$ otherwise.
..remarks:Definition: A sequence container is "contiguous", if its elements
    are stored in a single contiguous array.
    Examples for contiguous sequences are @Spec.Alloc String@ or @Adaption.char array@.
..remarks:If an object $obj$ is a contiguous sequence, then $begin(obj)$ can be
    converted to a pointer to the first element of the content array.
..include:seqan/sequence.h
*/
template <typename T>
struct IsContiguous
{
    typedef False Type;
    enum { VALUE = false };
};

template <typename T>
struct IsContiguous<T const>
    : public IsContiguous<T> {};

// --------------------------------------------------------------------------
// Metafunction IsSequence
// --------------------------------------------------------------------------

/**
.Metafunction.IsSequence:
..cat:Sequences
..summary:Determines whether a container stores its elements in sequential order.
..signature:IsSequence<T>::VALUE
..param.T:Type that is tested for being a sequence.
..returns.param.VALUE:$true$ if $T$ is a sequence, $false$ otherwise.
..remarks:For example @Class.String@ and @Class.Segment@ return $true$.
..include:seqan/sequence.h
*/
template <typename T>
struct IsSequence
{
    typedef False Type;
    enum { VALUE = false };
};

template <typename T>
struct IsSequence<T const>
    : public IsSequence<T> {};

// --------------------------------------------------------------------------
// Metafunction AllowsFastRandomAccess
// --------------------------------------------------------------------------

/**
.Metafunction.AllowsFastRandomAccess:
..cat:Sequences
..summary:Determines whether a sequence efficiently supports random access.
..signature:AllowsFastRandomAccess<T>::VALUE
..param.T:Type that is tested for fast random access.
..returns.param.VALUE:$true$ if $T$ supports fast random access, $false$ otherwise.
..remarks:For example @Spec.Alloc String@, @Class.Segment@, and @Spec.Block String@ return $true$.
..include:seqan/sequence.h
*/
template <typename T>
struct AllowsFastRandomAccess
{
    typedef True Type;
    enum { VALUE = true };
};

template <typename T>
struct AllowsFastRandomAccess<T const>
    : public AllowsFastRandomAccess<T> {};

// ============================================================================
// Functions
// ============================================================================

// --------------------------------------------------------------------------
// Function getObjectId()
// --------------------------------------------------------------------------

/**
.Function.getObjectId:
..cat:Miscellaneous
..class:Class.String
..summary:A value that identifies the underlying sequence.
..signature:void const * getObjectId(object)
..param.object:The object for which the id will be determined.
..returns:The id of $sequence$.
..remarks.text:Two sequences should have the same id, if they share the same resource, e.g. the same memory buffer.
..remarks.text:The exact semantic of the returned id can vary for different classes.
Typically, the id of a string is a $void const *$ to the end of the string.
..remarks.note:The id of a single character need not to be the id of its container.
..example.code: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)));
..example.text:In this example, $b1$ is $true$, since the segment object returned by $infix()$
is just a filter and uses the buffer of it's host object $str$.
..example.text:$String<char>(str)$ constructs a temporary copy of $str$, so these two
strings have different id values.
..example.text:The result of the last comparison depends on the implementation of $toCString$
and cannot be predicted at compile time.
..include:seqan/sequence.h
*/
template <typename T>
inline void const *
getObjectId(T const & me)
{
    SEQAN_CHECKPOINT;
    return end(me, Standard());
}

// --------------------------------------------------------------------------
// Function shareResources()
// --------------------------------------------------------------------------

/**
.Function.shareResources:
..cat:Miscellaneous
..class:Class.String
..summary:Determines whether two sequences share the same resource.
..signature:bool shareResources(sequence1, sequence2)
..param.sequence1, sequence2:Two sequences.
..returns:$false$ if it can be guaranteed that $sequence1$ and $sequence2$ can be modified without changing each other, $true$ otherwise.
..remarks:Non-sequences are interpreted as sequences of size 1.
..remarks:Note that this function may not work properly for argument types that are not listed here.
..include:seqan/sequence.h
*/

template <typename T1, typename T2>
inline bool
shareResources(T1 const & obj1,
               T2 const & obj2)
{
    SEQAN_CHECKPOINT;
    return getObjectId(obj1) == getObjectId(obj2);
}

// --------------------------------------------------------------------------
// Function _beginDefault()
// --------------------------------------------------------------------------

//* ???Anti Default Sequences
// TODO(holtgrew): Evil -- each value is a container of length 1.
template <typename T>
inline typename Iterator<T, Standard>::Type
_beginDefault(T & me,
               Standard)
{
    SEQAN_CHECKPOINT;
    return & me;
}
// TODO(holtgrew): Evil -- each value is a container of length 1.
template <typename T>
inline typename Iterator<T const, Standard>::Type
_beginDefault(T const & me,
               Standard)
{
    SEQAN_CHECKPOINT;
    return & me;
}
//*/

template <typename T>
inline typename Iterator<T, Rooted>::Type
_beginDefault(T & me,
               Rooted)
{
    SEQAN_CHECKPOINT;
    typedef typename Iterator<T, Rooted>::Type TIterator;
    return TIterator(me, begin(me, Standard()));
}
template <typename T>
inline typename Iterator<T const, Rooted>::Type
_beginDefault(T const & me,
               Rooted)
{
    SEQAN_CHECKPOINT;
    typedef typename Iterator<T const, Rooted>::Type TIterator;
    return TIterator(me, begin(me, Standard()));
}

// --------------------------------------------------------------------------
// Function begin()
// --------------------------------------------------------------------------

/**
.Function.begin:
..cat:Iteration
..cat:Containers
..class:Class.String
..class:Concept.ContainerConcept
..summary:The begin of a container.
..signature:Iterator begin(object [, tag])
..param.object:A container.
...type:Class.String
...concept:Concept.ContainerConcept
..param.tag:An @Tag.Iterator Spec.iterator spec@ tag that specifies the kind of the iterator returned. (optional)
...default:Given by @Metafunction.DefaultGetIteratorSpec@.
..returns:An iterator to the first item in $object$. The type is the result of $Iterator<TContainer, TTag>::Type$ where $TContainer$ is the type of $object$ and $TTag$ is the type of $tag$.
...metafunction:Metafunction.Iterator
..remarks.text:If the container does not contain any items at all, the function may return 0.
..see:Function.end
..see:Metafunction.Iterator
..include:seqan/sequence.h
*/
template <typename T>
inline typename Iterator<T, typename DefaultGetIteratorSpec<T>::Type>::Type
begin(T & me)
{
    SEQAN_CHECKPOINT;
    return begin(me, typename DefaultGetIteratorSpec<T>::Type()) ;
}

template <typename T>
inline typename Iterator<T const, typename DefaultGetIteratorSpec<T>::Type>::Type
begin(T const & me)
{
    SEQAN_CHECKPOINT;
    return begin(me, typename DefaultGetIteratorSpec<T>::Type()) ;
}

//folgende forward Deklaration wurde wegen Phaenomene bei VC++ 2003 hinzugenommen
//implemented in string_pointer.h
template <typename TValue>
inline typename Iterator<TValue const *, Standard>::Type
begin(TValue const * me,
      Standard);

template <typename T, typename TSpec>
inline typename Iterator<T, Tag<TSpec> const>::Type
begin(T & me,
      Tag<TSpec> const tag_)
{
    SEQAN_CHECKPOINT;
    return _beginDefault(me, tag_);
}
template <typename T, typename TSpec>
inline typename Iterator<T const, Tag<TSpec> const>::Type
begin(T const & me,
      Tag<TSpec> const tag_)
{
    SEQAN_CHECKPOINT;
    return _beginDefault(me, tag_);
}

/*
template <typename TValue>
inline typename Iterator<TValue *, Standard>::Type
begin(TValue * me,
      Standard)
{
    SEQAN_CHECKPOINT;
    return me;
}

//folgende Version wurde wegen eines seltsamen Phaenomens bei VC++ hinzugenommen
template <typename TValue>
inline typename Iterator<TValue const *, Standard>::Type
begin(TValue const * me,
      Standard)
{
    SEQAN_CHECKPOINT;
    return me;
}

template <typename TValue, typename TSpec>
inline typename Iterator<TValue *, Standard>::Type
begin(TValue * me,
      Tag<TSpec> const tag_)
//    Standard)
{
    SEQAN_CHECKPOINT;
    return me;
}

//folgende Version wurde wegen eines seltsamen Phaenomens bei VC++ hinzugenommen
template <typename TValue, typename TSpec>
inline typename Iterator<TValue const *, Standard>::Type
begin(TValue const * me,
      Tag<TSpec> const tag_)
//    Standard)
{
    SEQAN_CHECKPOINT;
    return me;
}
*/

// --------------------------------------------------------------------------
// Function beginPosition()
// --------------------------------------------------------------------------

/**
.Function.beginPosition:
..cat:Containers
..summary:Begin position of object in host.
..signature:Position beginPosition(object)
..class:Class.String
..class:Concept.ContainerConcept
..param.object:An object.
...type:Class.String
...concept:Concept.ContainerConcept
..returns:The position of the first item in $host(object)$ that belongs of $object$.
...metafunction:Metafunction.Position
..remarks
...text:For most classes $beginPosition$ always returns 0. Exceptions are e.g. @Spec.InfixSegment@ and @Spec.SuffixSegment@.
..see:Function.begin
..include:seqan/sequence.h
..example.code:
CharString str = "ABCDEF";
std::cout << beginPosition(str) << std::endl;

Infix<CharString >::Type myInfix = infix(str, 1, 5);
std::cout << beginPosition(myInfix) << std::endl;
*/
template <typename T>
inline typename Position<T>::Type
beginPosition(T &)
{
    SEQAN_CHECKPOINT;
    return 0;
}

template <typename T>
inline typename Position<T>::Type
beginPosition(T const &)
{
    SEQAN_CHECKPOINT;
    return 0;
}

// --------------------------------------------------------------------------
// Function _endDefault()
// --------------------------------------------------------------------------

//* ???Anti Default Sequences
template <typename T>
inline typename Iterator<T, Standard>::Type
_endDefault(T & me,
             Standard)
{
    SEQAN_CHECKPOINT;
    return (& me) + 1;
}
template <typename T>
inline typename Iterator<T const, Standard>::Type
_endDefault(T const & me,
             Standard)
{
    SEQAN_CHECKPOINT;
    return (& me) + 1;
}
//*/

template <typename T>
inline typename Iterator<T, Rooted>::Type
_endDefault(T & me,
             Rooted)
{
    SEQAN_CHECKPOINT;
    typedef typename Iterator<T, Rooted>::Type TIterator;
    return TIterator(me, end(me, Standard()));
}
template <typename T>
inline typename Iterator<T const, Rooted>::Type
_endDefault(T const & me,
             Rooted)
{
    SEQAN_CHECKPOINT;
    typedef typename Iterator<T const, Rooted>::Type TIterator;
    return TIterator(me, end(me, Standard()));
}

// --------------------------------------------------------------------------
// Function end()
// --------------------------------------------------------------------------

/**
.Function.end:
..cat:Iteration
..cat:Containers
..class:Class.String
..concept:Concept.ContainerConcept
..summary:The end of a container.
..signature:Iterator end(object [, tag])
..param.object:A container.
...type:Class.String
...concept:Concept.ContainerConcept
..param.tag:An @Tag.Iterator Spec.iterator spec@ tag that specifies the kind of the iterator returned. (optional)
...default:Given by @Metafunction.DefaultGetIteratorSpec@.
..returns:An iterator that points behind the last item in $object$. The type is the result of $Iterator<TContainer, TTag>::Type$ where $TContainer$ is the type of $object$ and $TTag$ is the type of $tag$.
...metafunction:Metafunction.Iterator
..remarks.text:If the container does not contain any items at all, the function may return 0.
..see:Function.begin
..see:Metafunction.Iterator
..include:seqan/sequence.h
*/
template <typename T>
inline typename Iterator<T, typename DefaultGetIteratorSpec<T>::Type>::Type
end(T & me)
{
    SEQAN_CHECKPOINT;
    return end(me, typename DefaultGetIteratorSpec<T>::Type()) ;
}

template <typename T>
inline typename Iterator<T const, typename DefaultGetIteratorSpec<T>::Type>::Type
end(T const & me)
{
    SEQAN_CHECKPOINT;
    return end(me, typename DefaultGetIteratorSpec<T>::Type()) ;
}

template <typename T, typename TSpec>
inline typename Iterator<T, Tag<TSpec> const>::Type
end(T & me,
    Tag<TSpec> const tag_)
{
    SEQAN_CHECKPOINT;
    return _endDefault(me, tag_);
}

template <typename T, typename TSpec>
inline typename Iterator<T const, Tag<TSpec> const>::Type
end(T const & me,
    Tag<TSpec> const tag_)
{
    SEQAN_CHECKPOINT;
    return _endDefault(me, tag_);
}

// --------------------------------------------------------------------------
// Function endPosition()
// --------------------------------------------------------------------------

/**
.Function.endPosition:
..cat:Containers
..class:Class.String
..concept:Concept.ContainerConcept
..summary:End position of object in host.
..signature:Position endPosition(object)
..param.object:An object.
...concept:Concept.ContainerConcept
...type:Class.String
..returns:The position behind the last item in $host(object)$ that belongs of $object$.
...metafunction:Metafunction.Position
..see:Function.end
..see:Function.beginPosition
..include:seqan/sequence.h
*/
template <typename T>
inline typename Position<T>::Type
endPosition(T & me)
{
    SEQAN_CHECKPOINT;
    return length(me);
}

template <typename T>
inline typename Position<T>::Type
endPosition(T const & me)
{
    SEQAN_CHECKPOINT;
    return length(me);
}

// --------------------------------------------------------------------------
// Function value()
// --------------------------------------------------------------------------

/**
.Function.value:
..cat:Iteration
..cat:Containers
..concept:Concept.ContainerConcept
..summary:Reference to the value.
..signature:Reference value(container, position)
..param.container:A container of values.
..param.position:A position in $container$ on which the value should be accessed.
..returns:A reference or proxy to the value.
...metafunction:Metafunction.Reference
..include:seqan/sequence.h
*/
//* ???Anti Default Sequences
template <typename T, typename TPos>
inline typename Reference<T>::Type
value(T & me,
      TPos /*pos*/)
{
    SEQAN_CHECKPOINT;
    return me;
}

template <typename T, typename TPos>
inline typename Reference<T const>::Type
value(T const & me,
      TPos /*pos*/)
{
    SEQAN_CHECKPOINT;
    return me;
}
//*/

// --------------------------------------------------------------------------
// Function getValue()
// --------------------------------------------------------------------------

/**
.Function.getValue:
..summary:Access to the value.
..cat:Containers
..cat:Content Manipulation
..concept:Concept.ContainerConcept
..signature:GetValue getValue(container, pos)
..param.container:A container.
...concept:Concept.ContainerConcept
..param.pos:The position of an item in $object$.
...remarks:$pos$ should be convertible to $Position<T>::Type$ for $container$-type $T$.
..returns:The item at position $pos$ in $container$.
This can either be a reference to the item or a temporary copy of the item.
...metafunction:Metafunction.GetValue
..remarks:
...text:If $pos$ is out of range, then the behavior of the function is undefined.
..see:Metafunction.GetValue
..see:Metafunction.Position
..see:Function.value
..include:seqan/sequence.h
*/
template <typename T, typename TPos>
inline typename GetValue<T>::Type
getValue(T & me,
         TPos pos)
{
    SEQAN_CHECKPOINT;
    return (typename GetValue<T>::Type) value(me, pos);
}

template <typename T, typename TPos>
inline typename GetValue<T const>::Type
getValue(T const & me,
         TPos pos)
{
    SEQAN_CHECKPOINT;
    return value(me, pos);
}

// --------------------------------------------------------------------------
// Function front()
// --------------------------------------------------------------------------

/**
.Function.front:
..cat:Containers
..concept:Concept.ContainerConcept
..summary:The first item in container.
..signature:Iterator front(container)
..param.container:A container.
...concept:Concept.ContainerConcept
..returns:A @Metafunction.Reference.reference@ of the first item in $container$.
...metafunction:Metafunction.Reference
..remarks:This function is equivalent to $value(me, 0)$.
..see:Function.value
..see:Function.begin
..include:seqan/sequence.h
*/

template <typename T>
inline typename Reference<T>::Type
front(T & me)
{
    SEQAN_CHECKPOINT;
    return value(me, 0);
}
template <typename T>
inline typename Reference<T const>::Type
front(T const & me)
{
    SEQAN_CHECKPOINT;
    return value(me, 0);
}

// --------------------------------------------------------------------------
// Function back()
// --------------------------------------------------------------------------

/**
.Function.back:
..cat:Containers
..concept:Concept.ContainerConcept
..summary:The last item in container.
..signature:Iterator back(container)
..param.container:A container.
...concept:Concept.ContainerConcept
..returns:A @Metafunction.Reference.reference@ of the last item in $container$.
...metafunction:Metafunction.Reference
..remarks:This function is equivalent to $value(me, length(me) - 1)$.
..see:Function.value
..see:Function.end
..see:Function.front
..include:seqan/sequence.h
*/

template <typename T>
inline typename Reference<T const>::Type
back(T const & me)
{
    SEQAN_CHECKPOINT;
    return value(me, length(me) - 1);
}

template <typename T>
inline typename Reference<T>::Type
back(T & me)
{
    SEQAN_CHECKPOINT;
    return value(me, length(me) - 1);
}

// --------------------------------------------------------------------------
// Function iter()
// --------------------------------------------------------------------------

/**
.Function.iter:
..cat:Containers
..class:Class.String
..summary:Iterator to item at given position.
..signature:Iterator iter(object, pos [, tag])
..param.object:A container.
...type:Class.String
..param.pos:The position of an item in $object$.
...metafunction:Metafunction.Position
..param.tag:An @Tag.Iterator Spec.iterator spec@ tag that specifies the kind of the iterator returned. (optional)
...default:Given by @Metafunction.DefaultGetIteratorSpec@.
..returns:An iterator to the item at position $pos$ in $object$. The type is the result of $Iterator<TContainer, TTag>::Type$ where $TContainer$ is the type of $object$ and $TTag$ is the type of $tag$.
...metafunction:Metafunction.Iterator
..remarks:
...text:If $pos$ is out of range, then the behavior of the function is undefined.
..see:Function.value
..see:Metafunction.Iterator
..see:Metafunction.Position
..include:seqan/sequence.h
 */
template <typename T, typename TPos>
inline typename Iterator<T, typename DefaultGetIteratorSpec<T>::Type>::Type
iter(T & me,
     TPos pos)
{
    SEQAN_CHECKPOINT;
    return iter(me, pos, typename DefaultGetIteratorSpec<T>::Type());
{'fraction_non_alphanumeric': 0.23849694692343823, 'fraction_numerical': 0.0019539689995302957, 'mean_word_length': 2.722097902097902, 'pattern_counts': {'":': 0, '<': 279, '<?xml version=': 0, '>': 263, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7313349', 'n_tokens_mistral': 14132, 'n_tokens_neox': 13522, 'n_words': 4615}