1 /*==========================================================================
2 SeqAn - The Library for Sequence Analysis
4 ============================================================================
7 This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Lesser General Public
9 License as published by the Free Software Foundation; either
10 version 3 of the License, or (at your option) any later version.
12 This library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Lesser General Public License for more details.
17 ============================================================================
18 $Id: sequence_interface.h,v 1.1 2008/08/25 16:20:04 langmead Exp $
19 ==========================================================================*/
21 #ifndef SEQAN_HEADER_SEQUENCE_INTERFACE_H
22 #define SEQAN_HEADER_SEQUENCE_INTERFACE_H
24 namespace SEQAN_NAMESPACE_MAIN
27 //////////////////////////////////////////////////////////////////////////////
29 //////////////////////////////////////////////////////////////////////////////
32 .Tag.Overflow Strategy:
33 ..summary:The strategy for resizing containers.
34 ..tag.Insist:No capacity check.
35 ...remarks:The user has to ensure that the container's capacity is large enough.
36 ..tag.Limit:Limit the contents to current capacity.
37 ...remarks: All entries that exceed the capacity are lost.
38 ..tag.Exact:Expand as far as needed.
39 ...remarks: The capacity is only changed if the current capacity is not large enough.
40 If the capacity can only be expanded up to a certain ammount, it will be increased as far as possible
41 and the contents are limited to the new capacity.
42 ...remarks:Note that the capacity will never be shrinked.
43 Use @Function.shrinkToFit@ to resize the capacity down to the current length.
44 ..tag.Generous:Expand if needed, get precautionary extra space.
45 ...remarks:Whenever the capacity has to be increased, the new capacity is choosen somewhat large than actually needed.
46 This strategy limits the number of capacity changes, so that resizing takes armotized constant time.
47 Use this strategy if the total amount of storage is unkown at first.
48 ...remarks:The new capacity is computed by @Function.computeGenerousCapacity@.
49 By default, it is guaranteed not to exceed about
50 tree halfs of the space that is used to store the data.
51 The user can overload @Function.computeGenerousCapacity@ in order to change this behavior.
52 ..remarks:Changing the capacity of a container can invalidate the iterators of this container.
53 ..remarks:If no overflow tag is specified, most operations use the default overflow strategy given by @Metafunction.DefaultOverflowImplicit@
54 or @Metafunction.DefaultOverflowExplicit@, depending on the kind of operation.
57 typedef Tag<TagInsist_> const Insist;
58 typedef Tag<TagInsist_> const Tight;
62 typedef Tag<TagLimit_> const Limit;
66 typedef Tag<TagGenerous_> const Generous;
70 typedef Tag<TagExact_> const Exact;
73 //____________________________________________________________________________
76 .Metafunction.DefaultOverflowImplicit:
78 ..summary:The default overflow strategy for implicit resize.
79 ..signature:DefaultOverflowImplicit<T>::Type
80 ..param.T:Type for which the overflow strategy is determined.
82 ..returns.param.Type:Expansion tag for type of $T$.
83 ..remarks:This function is used for functions that cause an implicit change of a container's size, like
84 e.g. @Function.assign@, @Function.append@, and @Function.replace@.
85 ..see:Tag.Overflow Strategy
88 struct DefaultOverflowImplicit
93 //____________________________________________________________________________
96 .Metafunction.DefaultOverflowExplicit:
98 ..summary:The default overflow strategy for explicit resize.
99 ..signature:DefaultOverflowExplicit<T>::Type
100 ..param.T:Type for which the overflow strategy is determined.
102 ..returns.param.Type:Expansion tag for type of $T$.
103 ..remarks:This function is used for functions that change a container's size explicit, like e.g. @Function.resize@.
104 ..see:Tag.Overflow Strategy
105 ..see:Metafunction.DefaultOverflowImplicit
107 template <typename T>
108 struct DefaultOverflowExplicit
113 //////////////////////////////////////////////////////////////////////////////
115 //////////////////////////////////////////////////////////////////////////////
117 .Metafunction.IsContiguous:
118 ..summary:Determines whether a container stores its elements in a contiguous array.
119 ..signature:IsContiguous<T>::VALUE
120 ..param.T:Type that is tested for being a string.
121 ..returns.param.VALUE:$true$ if $T$ is a string, $false$ otherwise.
122 ..remarks:Definition: A sequence container is "contiguous", if its elements
123 are stored in a single contiguous array.
124 Examples for contiguous sequences are @Spec.Alloc String@ or @Adaption.char array@.
125 ..remarks:If an object $obj$ is a contiguous sequence, then $begin(obj)$ can be
126 converted to a pointer to the first element of the content array.
128 template <typename T>
132 enum { VALUE = false };
134 template <typename T>
135 struct IsContiguous<T const>:
136 public IsContiguous<T> {};
138 //////////////////////////////////////////////////////////////////////////////
140 //////////////////////////////////////////////////////////////////////////////
142 .Metafunction.IsSequence:
143 ..summary:Determines whether a container stores its elements in sequential order.
144 ..signature:IsSequence<T>::VALUE
145 ..param.T:Type that is tested for being a sequence.
146 ..returns.param.VALUE:$true$ if $T$ is a sequence, $false$ otherwise.
147 ..remarks:For example @Class.String@ and @Class.Segment@ return $true$.
149 template <typename T>
153 enum { VALUE = false };
155 template <typename T>
156 struct IsSequence<T const>:
157 public IsSequence<T> {};
159 //////////////////////////////////////////////////////////////////////////////
160 // AllowsFastRandomAccess
161 //////////////////////////////////////////////////////////////////////////////
163 .Metafunction.AllowsFastRandomAccess:
164 ..summary:Determines whether a sequence efficiently supports random access.
165 ..signature:AllowsFastRandomAccess<T>::VALUE
166 ..param.T:Type that is tested for fast random access.
167 ..returns.param.VALUE:$true$ if $T$ supports fast random access, $false$ otherwise.
168 ..remarks:For example @Spec.Alloc String@, @Class.Segment@, and @Spec.Block String@ return $true$.
170 template <typename T>
171 struct AllowsFastRandomAccess
174 enum { VALUE = true };
176 template <typename T>
177 struct AllowsFastRandomAccess<T const>:
178 public AllowsFastRandomAccess<T> {};
180 //////////////////////////////////////////////////////////////////////////////
182 //////////////////////////////////////////////////////////////////////////////
186 ..summary:A value that identifies the underlying sequence.
187 ..signature:void const * id(object)
188 ..param.object:The object for which the id will be determined.
189 ..returns:The id of $sequence$.
190 ..remarks.text:Two sequences should have the same id, if they share the same resource, e.g. the same memory buffer.
191 ..remarks.text:The exact semantic of the returned id can vary for different classes.
192 Typically, the id of a string is a $void const *$ to the end of the string.
193 ..remarks.note:The id of a single character need not to be the id of its container.
194 ..example.code:String<char> str = "hallo seqan";
195 bool b1 = (id(str) == id(infix(str, 3, 7)); //true
196 bool b2 = (id(str) == id(String<char>(str))); //false
197 bool b3 = (id(str) == id(toCString(str)));
198 ..example.text:In this example, $b1$ is $true$, since the segment object returned by $infix()$
199 is just a filter and uses the buffer of it's host object $str$.
200 ..example.text:$String<char>(str)$ constructs a temporary copy of $str$, so these two
201 strings have different id values.
202 ..example.text:The result of the last comparison depends on the implementation of $toCString$
203 and cannot be predicted at compile time.
205 template <typename T>
210 return end(me, Standard());
213 //////////////////////////////////////////////////////////////////////////////
216 .Function.shareResources:
218 ..summary:Determines whether two sequences share the same resource.
219 ..signature:bool shareResources(sequence1, sequence2)
220 ..param.sequence1, sequence2:Two sequences.
221 ..returns:$false$ if it can be guaranteed that $sequence1$ and $sequence2$ can be modified without changing each other, $true$ otherwise.
222 ..remarks:Non-sequences are interpreted as sequences of size 1.
223 ..remarks:Note that this function may not work properly for argument types that are not listed here.
226 template <typename T1, typename T2>
228 shareResources(T1 const & obj1,
232 return id(obj1) == id(obj2);
235 //////////////////////////////////////////////////////////////////////////////
237 //////////////////////////////////////////////////////////////////////////////
243 ..summary:The begin of a container.
244 ..signature:Iterator begin(object [, tag])
245 ..param.object:A container.
247 ...concept:Concept.Container
248 ..param.tag:An @Tag.Iterator Spec.iterator spec@ tag that specifies the kind of the iterator returned. (optional)
249 ...default:Given by @Metafunction.DefaultGetIteratorSpec@.
250 ..returns:An iterator to the first item in $object$.
251 ...metafunction:Metafunction.Iterator
252 ..remarks.text:If the container does not contain any items at all, the function may return 0.
254 ..see:Metafunction.Iterator
256 template <typename T>
257 inline typename Iterator<T, typename DefaultGetIteratorSpec<T>::Type>::Type
261 return begin(me, typename DefaultGetIteratorSpec<T>::Type()) ;
263 template <typename T>
264 inline typename Iterator<T const, typename DefaultGetIteratorSpec<T>::Type>::Type
268 return begin(me, typename DefaultGetIteratorSpec<T>::Type()) ;
271 //____________________________________________________________________________
273 //* ???Anti Default Sequences
274 template <typename T>
275 inline typename Iterator<T, Standard>::Type
276 _begin_default(T & me,
282 template <typename T>
283 inline typename Iterator<T const, Standard>::Type
284 _begin_default(T const & me,
292 //____________________________________________________________________________
294 template <typename T>
295 inline typename Iterator<T, Rooted>::Type
296 _begin_default(T & me,
300 typedef typename Iterator<T, Rooted>::Type TIterator;
301 return TIterator(me, begin(me, Standard()));
303 template <typename T>
304 inline typename Iterator<T const, Rooted>::Type
305 _begin_default(T const & me,
309 typedef typename Iterator<T const, Rooted>::Type TIterator;
310 return TIterator(me, begin(me, Standard()));
312 //____________________________________________________________________________
314 //folgende forward Deklaration wurde wegen Phaenomene bei VC++ 2003 hinzugenommen
315 //implemented in string_pointer.h
316 template <typename TValue>
317 inline typename Iterator<TValue const *, Standard>::Type
318 begin(TValue const * me,
321 //____________________________________________________________________________
323 template <typename T, typename TSpec>
324 inline typename Iterator<T, Tag<TSpec> const>::Type
326 Tag<TSpec> const tag_)
329 return _begin_default(me, tag_);
331 template <typename T, typename TSpec>
332 inline typename Iterator<T const, Tag<TSpec> const>::Type
334 Tag<TSpec> const tag_)
337 return _begin_default(me, tag_);
342 template <typename TValue>
343 inline typename Iterator<TValue *, Standard>::Type
351 //folgende Version wurde wegen eines seltsamen Phaenomens bei VC++ hinzugenommen
352 template <typename TValue>
353 inline typename Iterator<TValue const *, Standard>::Type
354 begin(TValue const * me,
361 template <typename TValue, typename TSpec>
362 inline typename Iterator<TValue *, Standard>::Type
364 Tag<TSpec> const tag_)
371 //folgende Version wurde wegen eines seltsamen Phaenomens bei VC++ hinzugenommen
372 template <typename TValue, typename TSpec>
373 inline typename Iterator<TValue const *, Standard>::Type
374 begin(TValue const * me,
375 Tag<TSpec> const tag_)
386 //////////////////////////////////////////////////////////////////////////////
388 //////////////////////////////////////////////////////////////////////////////
390 .Function.beginPosition:
392 ..summary:Begin position of object in host.
393 ..signature:Position beginPosition(object)
394 ..param.object:An object.
396 ...concept:Concept.Container
397 ..returns:The position of the first item in $host(object)$ that belongs of $object$.
398 ...metafunction:Metafunction.Position
400 ...text:For most classes $beginPosition$ always returns 0. Exceptions are e.g. @Spec.InfixSegment@ and @Spec.SuffixSegment@.
403 template <typename T>
404 inline typename Position<T>::Type
410 template <typename T>
411 inline typename Position<T>::Type
412 beginPosition(T const &)
418 //////////////////////////////////////////////////////////////////////////////
420 //////////////////////////////////////////////////////////////////////////////
426 ..summary:The end of a container.
427 ..signature:Iterator end(object [, tag])
428 ..param.object:A container.
430 ...concept:Concept.Container
431 ..param.tag:An @Tag.Iterator Spec.iterator spec@ tag that specifies the kind of the iterator returned. (optional)
432 ...default:Given by @Metafunction.DefaultGetIteratorSpec@.
433 ..returns:An iterator that points behind the last item in $object$.
434 ...metafunction:Metafunction.Iterator
435 ..remarks.text:If the container does not contain any items at all, the function may return 0.
437 ..see:Metafunction.Iterator
439 template <typename T>
440 inline typename Iterator<T, typename DefaultGetIteratorSpec<T>::Type>::Type
444 return end(me, typename DefaultGetIteratorSpec<T>::Type()) ;
446 template <typename T>
447 inline typename Iterator<T const, typename DefaultGetIteratorSpec<T>::Type>::Type
451 return end(me, typename DefaultGetIteratorSpec<T>::Type()) ;
454 //____________________________________________________________________________
456 //* ???Anti Default Sequences
457 template <typename T>
458 inline typename Iterator<T, Standard>::Type
465 template <typename T>
466 inline typename Iterator<T const, Standard>::Type
467 _end_default(T const & me,
475 //____________________________________________________________________________
477 template <typename T>
478 inline typename Iterator<T, Rooted>::Type
483 typedef typename Iterator<T, Rooted>::Type TIterator;
484 return TIterator(me, end(me, Standard()));
486 template <typename T>
487 inline typename Iterator<T const, Rooted>::Type
488 _end_default(T const & me,
492 typedef typename Iterator<T const, Rooted>::Type TIterator;
493 return TIterator(me, end(me, Standard()));
496 //____________________________________________________________________________
498 template <typename T, typename TSpec>
499 inline typename Iterator<T, Tag<TSpec> const>::Type
501 Tag<TSpec> const tag_)
504 return _end_default(me, tag_);
506 template <typename T, typename TSpec>
507 inline typename Iterator<T const, Tag<TSpec> const>::Type
509 Tag<TSpec> const tag_)
512 return _end_default(me, tag_);
515 //////////////////////////////////////////////////////////////////////////////
517 //////////////////////////////////////////////////////////////////////////////
520 .Function.endPosition:
522 ..summary:End position of object in host.
523 ..signature:Position endPosition(object)
524 ..param.object:An object.
525 ...concept:Concept.Container
527 ..returns:The position behind the last item in $host(object)$ that belongs of $object$.
528 ...metafunction:Metafunction.Position
530 ..see:Function.beginPosition
532 template <typename T>
533 inline typename Position<T>::Type
539 template <typename T>
540 inline typename Position<T>::Type
541 endPosition(T const & me)
547 //////////////////////////////////////////////////////////////////////////////
549 //////////////////////////////////////////////////////////////////////////////
555 ..summary:Reference to the value.
556 ..signature:Reference value(container, position)
557 ..param.container:A container of values.
558 ..param.position:A position in $container$ on which the value should be accessed.
559 ..returns:A reference or proxy to the value.
560 ...metafunction:Metafunction.Reference
563 //* ???Anti Default Sequences
564 template <typename T, typename TPos>
565 inline typename Reference<T>::Type
572 template <typename T, typename TPos>
573 inline typename Reference<T const>::Type
582 //////////////////////////////////////////////////////////////////////////////
584 //////////////////////////////////////////////////////////////////////////////
588 ..summary:Access to the value.
590 ..cat:Content Manipulation
591 ..signature:GetValue getValue(container, pos)
592 ..param.container:A container.
593 ...concept:Concept.Container
594 ..param.pos:The position of an item in $object$.
595 ...remarks:$pos$ should be convertible to $Position<T>::Type$ for $container$-type $T$.
596 ..returns:The item at position $pos$ in $container$.
597 This can either be a reference to the item or a temporary copy of the item.
598 ...metafunction:Metafunction.GetValue
600 ...text:If $pos$ is out of range, then the behavior of the function is undefined.
601 ..see:Metafunction.GetValue
602 ..see:Metafunction.Position
606 template <typename T, typename TPos>
607 inline typename GetValue<T>::Type
612 return (typename GetValue<T>::Type) value(me, pos);
614 template <typename T, typename TPos>
615 inline typename GetValue<T const>::Type
616 getValue(T const & me,
620 return value(me, pos);
623 //////////////////////////////////////////////////////////////////////////////
625 //////////////////////////////////////////////////////////////////////////////
628 .Function.Container#front:
630 ..summary:The first item in container.
631 ..signature:Iterator front(container)
632 ..param.container:A container.
633 ...concept:Concept.Container
634 ..returns:A @Metafunction.Reference.reference@ of the first item in $container$.
635 ...metafunction:Metafunction.Reference
636 ..remarks:This function is equivalent to $value(me, beginPosition(me))$.
642 template <typename T>
643 inline typename Reference<T>::Type
647 return value(me, beginPosition(me));
649 template <typename T>
650 inline typename Reference<T const>::Type
654 return value(me, beginPosition(me));
657 //////////////////////////////////////////////////////////////////////////////
659 //////////////////////////////////////////////////////////////////////////////
664 ..summary:The last item in container.
665 ..signature:Iterator back(container)
666 ..param.container:A container.
667 ...concept:Concept.Container
668 ..returns:A @Metafunction.Reference.reference@ of the last item in $container$.
669 ...metafunction:Metafunction.Reference
670 ..remarks:This function is equivalent to $value(me, endPosition(me) - 1)$.
673 ..see:Function.Container#front
676 template <typename T>
677 inline typename Reference<T const>::Type
681 return value(me, endPosition(me) - 1);
684 template <typename T>
685 inline typename Reference<T>::Type
689 return value(me, endPosition(me) - 1);
692 //////////////////////////////////////////////////////////////////////////////
694 //////////////////////////////////////////////////////////////////////////////
699 ..summary:Iterator to item at given position.
700 ..signature:Iterator iter(object, pos [, tag])
701 ..param.object:A container.
703 ..param.pos:The position of an item in $object$.
704 ...metafunction:Metafunction.Position
705 ..param.tag:An @Tag.Iterator Spec.iterator spec@ tag that specifies the kind of the iterator returned. (optional)
706 ...default:Given by @Metafunction.DefaultGetIteratorSpec@.
707 ..returns:An iterator to the item at position $pos$ in $object$.
708 ...metafunction:Metafunction.Iterator
710 ...text:If $pos$ is out of range, then the behavior of the function is undefined.
712 ..see:Metafunction.Iterator
713 ..see:Metafunction.Position
716 template <typename T, typename TPos>
717 inline typename Iterator<T, typename DefaultGetIteratorSpec<T>::Type>::Type
722 return iter(me, pos, typename DefaultGetIteratorSpec<T>::Type());
724 template <typename T, typename TPos>
725 inline typename Iterator<T const, typename DefaultGetIteratorSpec<T>::Type>::Type
730 return iter(me, pos, typename DefaultGetIteratorSpec<T const>::Type());
734 template <typename T, typename TPos, typename TTag>
735 inline typename Iterator<T, Tag<TTag> const>::Type
738 Tag<TTag> const tag_)
741 return begin(me, tag_) + pos;
743 template <typename T, typename TPos, typename TTag>
744 inline typename Iterator<T const, Tag<TTag> const>::Type
747 Tag<TTag> const tag_)
750 return begin(me, tag_) + pos;
753 //////////////////////////////////////////////////////////////////////////////
755 //////////////////////////////////////////////////////////////////////////////
757 .Function.assignValue:
758 ..cat:Content Manipulation
759 ..signature:assignValue(container, pos, value)
760 ..param.container:A container.
761 ...concept:Concept.Container
762 ..param.pos:Position of the item in $container$ to that $value$ is assigned.
763 ..remarks:If $object$ is a container (that is $pos$ is not specified),
764 the whole content of $object$ is replaced by $value$.
766 If $value$ is not used again after calling this function,
767 then consider to use @Function.moveValue@ that could be faster in some cases instead.
770 template <typename T, typename TValue, typename TPos>
774 TValue const & _value)
777 assign(value(me, pos), _value);
780 //////////////////////////////////////////////////////////////////////////////
782 //////////////////////////////////////////////////////////////////////////////
785 ..cat:Content Manipulation
786 ..signature:moveValue(container, pos, value)
788 ...concept:Concept.Container
789 ..param.container:A container.
790 ...concept:Concept.Container
791 ..param.pos:Position of the item in $container$ to that $value$ is moved to.
792 ..remarks:If $object$ is a container (that is $pos$ is not specified),
793 the whole content of $object$ is replaced by $value$.
795 This function possibly clears $value$.
796 If $value$ should be used further, consider to use @Function.assignValue@ instead.
799 template <typename T, typename TValue, typename TPos>
803 TValue const & _value)
806 move(value(me, pos), _value);
809 //////////////////////////////////////////////////////////////////////////////
811 //////////////////////////////////////////////////////////////////////////////
815 ..summary:The number of items/characters.
816 ..signature:Size length(object)
817 ..param.object:A container.
818 ...concept:Concept.Container
819 ..returns:The number of items/characters in $object$.
820 ...metafunction:Metafunction.Size
821 ..remarks.text:The length of a sequence can never exceed it's capacity.
822 ..see:Function.capacity
825 //* ???Anti Default Sequences
826 template <typename T>
827 inline typename Size<T const>::Type
828 length(T const & /*me*/)
835 //////////////////////////////////////////////////////////////////////////////
837 //////////////////////////////////////////////////////////////////////////////
842 ..summary:The maximal length.
843 ..signature:Size capacity(object)
844 ..param.object:A container.
845 ...remarks: If $object$ cannot be converted to one of these types, the function returns 1.
846 ..returns:The maximal number of items/characters that can be stored in $object$.
847 ...metafunction:Metafunction.Size
848 ..remarks.text:The size of a sequence can never exceed it's capacity, but some containers support
849 resizing of the capacity.
850 Some functions do that implicitely if they are called with a suitable @Tag.Overflow Strategy.overflow strategy@.
851 The function @Function.reserve@ can be used to change the capacity explicitely.
853 template <typename T>
854 inline typename Size<T const>::Type
855 capacity(T const & me)
861 //////////////////////////////////////////////////////////////////////////////
863 //////////////////////////////////////////////////////////////////////////////
868 ..summary:Test a container for being empty.
869 ..signature:bool empty(object)
870 ..param.object:A container.
871 ..returns:$true$ if $object$ contains no elements, otherwise $false$.
872 ..remarks.text:$empty(x)$ is guaranteed to be at least as fast as $length(me) == 0$,
873 but can be significantly faster in some cases.
874 ..see:Function.length
876 template <typename T>
881 return (length(me) == 0);
884 //////////////////////////////////////////////////////////////////////////////
885 // _computeSize4Capacity
886 //////////////////////////////////////////////////////////////////////////////
888 // note: for value types of size 1 or 2,
889 // an extra position for the termination character is allocated.
890 // This speeds up a conversion to a c style string (see Spec.CStyle String)
891 // note that this extra position is necessary not only for char and wchar_t,
892 // but also for all other value types of size 1 and 2 to make the application
893 // of the funciton move for in-place alphabet conversion.
896 template <typename T, typename TSize>
898 _computeSize4Capacity(T const & /*me*/,
902 if (sizeof(T) <= 2) return capacity + 1;
903 else return capacity;
907 //////////////////////////////////////////////////////////////////////////////
908 // computeGenerousCapacity
909 //////////////////////////////////////////////////////////////////////////////
911 .Function.computeGenerousCapacity:
914 ..summary:Capacity for generous expansion.
915 ..signature:Size computeGenerousCapacity(container, capacity)
916 ..param.container:A container that should be expanded.
917 ..param.capacity:Minimal capacity needed.
918 ..returns:A value larger than $capacity$ that should be used as new capacity for $container$
919 when it is expanded using the @Tag.Overflow Strategy."Generous" overflow strategy@.
920 ...metafunction:Metafunction.Size
921 ..see:Tag.Overflow Strategy
923 template <typename T, typename TSize>
925 computeGenerousCapacity(T const & /*me*/,
929 if (capacity <= 32) return 32;
930 return capacity + (capacity >> 1);
933 //////////////////////////////////////////////////////////////////////////////
935 //////////////////////////////////////////////////////////////////////////////
938 template <typename T>
940 _storageUpdated(T & me,
945 template <typename T>
947 _storageUpdated(T & me)
949 _storageUpdated_(me, (T *) 0);
952 template <typename T>
954 _storageUpdated(T const & me)
956 _storageUpdated_(me, (T const *) 0);
961 //////////////////////////////////////////////////////////////////////////////
963 //////////////////////////////////////////////////////////////////////////////
965 template<typename TTarget, typename TSource>
967 assign(TTarget & target,
969 typename Size<TTarget>::Type limit)
972 assign(target, source, limit, typename DefaultOverflowImplicit<TTarget>::Type());
974 template<typename TTarget, typename TSource>
976 assign(TTarget const & target,
978 typename Size<TTarget>::Type limit)
981 assign(target, source, limit, typename DefaultOverflowImplicit<TTarget const>::Type());
983 template<typename TTarget, typename TSource>
985 assign(TTarget & target,
986 TSource const & source,
987 typename Size<TTarget>::Type limit)
990 assign(target, source, limit, typename DefaultOverflowImplicit<TTarget>::Type());
992 template<typename TTarget, typename TSource>
994 assign(TTarget const & target,
995 TSource const & source,
996 typename Size<TTarget>::Type limit)
999 assign(target, source, limit, typename DefaultOverflowImplicit<TTarget const>::Type());
1002 //////////////////////////////////////////////////////////////////////////////
1004 //////////////////////////////////////////////////////////////////////////////
1008 ..summary:Concatenate two containers.
1009 ..cat:Content Manipulation
1010 ..signature:append(target, source [, limit] [,resize_tag])
1011 ..param.target: A container $source$ is append to.
1012 ..param.source: A container that is append to $target$.
1013 ...remarks:The function does not modify this container.
1014 ..param.limit: The maximal length of $target$ after the operation. (optional)
1015 ..param.resize_tag: Specifies the strategy that is applied if $target$ has not enough capacity to store the complete content. (optional)
1016 ...type:Tag.Overflow Strategy
1017 ...default:Specified by @Metafunction.DefaultOverflowImplicit@ of the $target$ type.
1018 ..remarks:The result of this operation is stored in $target$.
1019 ..see:Function.assign
1021 template<typename TTarget, typename TSource>
1023 append(TTarget & target,
1027 append(target, source, typename DefaultOverflowImplicit<TTarget>::Type());
1029 template<typename TTarget, typename TSource>
1031 append(TTarget const & target,
1035 append(target, source, typename DefaultOverflowImplicit<TTarget const>::Type());
1037 template<typename TTarget, typename TSource>
1039 append(TTarget & target,
1040 TSource const & source)
1043 append(target, source, typename DefaultOverflowImplicit<TTarget>::Type());
1045 template<typename TTarget, typename TSource>
1047 append(TTarget const & target,
1048 TSource const & source)
1051 append(target, source, typename DefaultOverflowImplicit<TTarget const>::Type());
1054 //____________________________________________________________________________
1056 template<typename TTarget, typename TSource>
1058 append(TTarget & target,
1060 typename Size<TTarget>::Type limit)
1063 append(target, source, limit, typename DefaultOverflowImplicit<TTarget>::Type());
1065 template<typename TTarget, typename TSource>
1067 append(TTarget const & target,
1069 typename Size<TTarget>::Type limit)
1072 append(target, source, limit, typename DefaultOverflowImplicit<TTarget const>::Type());
1074 template<typename TTarget, typename TSource>
1076 append(TTarget & target,
1077 TSource const & source,
1078 typename Size<TTarget>::Type limit)
1081 append(target, source, limit, typename DefaultOverflowImplicit<TTarget>::Type());
1083 template<typename TTarget, typename TSource>
1085 append(TTarget const & target,
1086 TSource const & source,
1087 typename Size<TTarget>::Type limit)
1090 append(target, source, limit, typename DefaultOverflowImplicit<TTarget const>::Type());
1094 //////////////////////////////////////////////////////////////////////////////
1096 //////////////////////////////////////////////////////////////////////////////
1098 .Function.appendValue:
1099 ..signature:appendValue(target, value [, resize_tag])
1100 ..cat:Content Manipulation
1101 ..summary:Appends a value to a container.
1102 ..param.target:A container.
1103 ..param.value:Value that is appended to $target$.
1105 ..param.resize_tag: Specifies the strategy that is applied if $target$ has not enough capacity to store the complete content. (optional)
1106 ...type:Tag.Overflow Strategy
1107 ...default:Specified by @Metafunction.DefaultOverflowImplicit@ of the $target$ type.
1110 template <typename T, typename TValue>
1113 TValue const & _value)
1116 appendValue(me, _value, typename DefaultOverflowImplicit<T>::Type());
1118 template <typename T, typename TValue>
1120 appendValue(T const & me,
1121 TValue const & _value)
1124 appendValue(me, _value, typename DefaultOverflowImplicit<T const>::Type());
1127 //////////////////////////////////////////////////////////////////////////////
1129 //////////////////////////////////////////////////////////////////////////////
1131 .Function.insertValue:
1132 ..cat:Content Manipulation
1133 ..summary:Inserts a single value into a container.
1134 ..signature:insertValue(target, pos, value [, resize_tag])
1135 ..param.target:The container
1136 ..param.pos:Position within $target$ at which $value$ is to be inserted.
1137 ..param.value:Value that will be inserted into $target$.
1138 ..param.resize_tag:Strategy that is applied if $target$ has not enough capacity to store the complete content.
1139 ...type:Tag.Overflow Strategy
1140 ..see:Function.assignValue
1141 ..see:Function.appendValue
1144 template <typename T, typename TPosition, typename TValue>
1148 TValue const & _value)
1151 insertValue(me, pos, _value, typename DefaultOverflowImplicit<T>::Type());
1153 template <typename T, typename TPosition, typename TValue>
1155 insertValue(T const & me,
1157 TValue const & _value)
1160 insertValue(me, pos, _value, typename DefaultOverflowImplicit<T const>::Type());
1163 //////////////////////////////////////////////////////////////////////////////
1165 //////////////////////////////////////////////////////////////////////////////
1169 ..summary:Replaces a part of a container with another container.
1170 ..cat:Content Manipulation
1171 ..signature:replace(target, pos_begin, pos_end, source [, limit] [,resize_tag])
1172 ..param.target: A container that is modified.
1173 ..param.pos_begin: Begin of replaced area.
1174 ...text:The first position in $target$ of the area that is replaced by $source$.
1175 ..param.pos_end: End of replaced area.
1176 ...text:The position behind the last position in $target$ of the area that is replaced by $source$.
1177 ..param.source: A container that is inserted into $target$.
1178 ...remarks:The function does not modify this container.
1179 ..param.limit: The maximal length of $target$ after the operation. (optional)
1180 ..param.resize_tag: Specifies the strategy that is applied if $target$ has not enough capacity to store the complete content. (optional)
1181 ...type:Tag.Overflow Strategy
1182 ...default:Specified by @Metafunction.DefaultOverflowImplicit@ of the $target$ type.
1183 ..see:Function.assign
1184 ..see:Function.append
1185 ..remarks.text:Some compilers have difficulties if $pos_begin$ and $pos_end$ are both 0, since 0 can be
1186 both a position or an iterator. The workaround is to convert at least one of these arguments
1187 explicite to the position or to the interator type.
1189 template<typename TTarget, typename TPositionBegin, typename TPositionEnd, typename TSource>
1191 replace(TTarget & target,
1192 TPositionBegin pos_begin,
1193 TPositionEnd pos_end,
1196 replace(target, pos_begin, pos_end, source, typename DefaultOverflowImplicit<TTarget>::Type());
1198 template<typename TTarget, typename TPositionBegin, typename TPositionEnd, typename TSource>
1200 replace(TTarget const & target,
1201 TPositionBegin pos_begin,
1202 TPositionEnd pos_end,
1205 replace(target, pos_begin, pos_end, source, typename DefaultOverflowImplicit<TTarget const>::Type());
1207 template<typename TTarget, typename TPositionBegin, typename TPositionEnd, typename TSource>
1209 replace(TTarget & target,
1210 TPositionBegin pos_begin,
1211 TPositionEnd pos_end,
1212 TSource const & source)
1214 replace(target, pos_begin, pos_end, source, typename DefaultOverflowImplicit<TTarget>::Type());
1216 template<typename TTarget, typename TPositionBegin, typename TPositionEnd, typename TSource>
1218 replace(TTarget const & target,
1219 TPositionBegin pos_begin,
1220 TPositionEnd pos_end,
1221 TSource const & source)
1223 replace(target, pos_begin, pos_end, source, typename DefaultOverflowImplicit<TTarget const>::Type());
1226 //____________________________________________________________________________
1228 template<typename TTarget, typename TPositionBegin, typename TPositionEnd, typename TSource>
1230 replace(TTarget & target,
1231 TPositionBegin pos_begin,
1232 TPositionEnd pos_end,
1234 typename Size<TTarget>::Type limit)
1236 replace(target, pos_begin, pos_end, source, limit, typename DefaultOverflowImplicit<TTarget>::Type());
1238 template<typename TTarget, typename TPositionBegin, typename TPositionEnd, typename TSource>
1240 replace(TTarget const & target,
1241 TPositionBegin pos_begin,
1242 TPositionEnd pos_end,
1244 typename Size<TTarget>::Type limit)
1246 replace(target, pos_begin, pos_end, source, limit, typename DefaultOverflowImplicit<TTarget const>::Type());
1248 template<typename TTarget, typename TPositionBegin, typename TPositionEnd, typename TSource>
1250 replace(TTarget & target,
1251 TPositionBegin pos_begin,
1252 TPositionEnd pos_end,
1253 TSource const & source,
1254 typename Size<TTarget>::Type limit)
1256 replace(target, pos_begin, pos_end, source, limit, typename DefaultOverflowImplicit<TTarget>::Type());
1258 template<typename TTarget, typename TPositionBegin, typename TPositionEnd, typename TSource>
1260 replace(TTarget const & target,
1261 TPositionBegin pos_begin,
1262 TPositionEnd pos_end,
1263 TSource const & source,
1264 typename Size<TTarget>::Type limit)
1266 replace(target, pos_begin, pos_end, source, limit, typename DefaultOverflowImplicit<TTarget const>::Type());
1270 //////////////////////////////////////////////////////////////////////////////
1272 //////////////////////////////////////////////////////////////////////////////
1277 ..summary:Increases the capacity.
1278 ..signature:Size reserve(object, new_capacity [, resize_tag])
1279 ..param.object: A container.
1280 ..param.new_capacity: The new capacity $object$ will get.
1281 ..param.resize_tag: Specifies the strategy that is applied for changing the capacity. (optional)
1282 ...type:Tag.Overflow Strategy
1283 ...default:Specified by @Metafunction.DefaultOverflowExplicit@.
1284 ..returns:The ammout of the requested capacity that was available.
1285 That is the function returns the minimum of $new_capacity$ and $capacity(me)$.
1286 ...metafunction:Metafunction.Size
1287 ..remarks:At the end of the operation, $capacity(me)$ can be larger than $new_capacity$.
1288 If $new_capacity$ is smaller than $capacity(me)$ at the beginning of the operation,
1289 the operation need not to change the capacity at all.
1290 ..remarks:This operation does not changes the content of $object$.
1291 ...note:This operation may invalidate iterators of $object$.
1292 ..see:Function.capacity
1294 template <typename T, typename TSize>
1295 inline typename Size<T>::Type
1302 return new_capacity;
1305 template <typename T, typename TSize>
1306 inline typename Size<T>::Type
1313 typename Size<T>::Type me_capacity = capacity(me);
1314 if (me_capacity < (typename Size<T>::Type) new_capacity) return me_capacity;
1315 return new_capacity;
1318 template <typename T, typename TSize>
1319 inline typename Size<T>::Type
1325 return reserve(me, new_capacity, typename DefaultOverflowExplicit<T>::Type());
1328 //////////////////////////////////////////////////////////////////////////////
1330 //////////////////////////////////////////////////////////////////////////////
1335 ..summary:Changes the length.
1336 ..signature:Size resize(object, new_length [, resize_tag])
1337 ..param.object: A container.
1338 ...type:Class.String
1339 ..param.new_length: The new length $object$ will get.
1340 ..param.resize_tag: Specifies the strategy that is applied if the capacity of $object$ is less than $new_length$. (optional)
1341 ...type:Tag.Overflow Strategy
1342 ...default:Specified by @Metafunction.DefaultOverflowExplicit@.
1343 ..returns:The new length $length(object)$.
1344 ...metafunction:Metafunction.Size
1345 ..remarks:This function can be used both for expanding and for shrinking $object$.
1347 If $new_length$ is too large for $object$ (i.e. the @Function.capacity@ of $object$ is too small), then $object$ is
1348 expanded as far as possible. The resulting length
1349 of $object$ could be less than $new_length$, depending on the type of $object$ and the available storage.
1350 ..see:Function.length
1351 ..see:Function.reserve
1353 template <typename T, typename TSize>
1354 inline typename Size<T>::Type
1360 return resize(me, new_length, typename DefaultOverflowExplicit<T>::Type());
1363 //////////////////////////////////////////////////////////////////////////////
1365 //////////////////////////////////////////////////////////////////////////////
1368 .Function.resizeSpace:
1370 ..summary:Makes free space in container
1371 ..signature:Size resizeSpace(object, size, pos_begin, pos_end [, limit] [, resize_tag])
1372 ..param.object:The container.
1373 ...type:Class.String
1374 ..param.size:Number of characters that should be freed.
1375 ..param.pos_begin:Position of the first item in $object$ that is to be destroyed.
1376 ..param.pos_end:Position behind the last item in $object$ that is to be destroyed.
1377 ...remarks:If $pos_end == pos_begin$, no item in $object$ will be destroyed.
1378 ..param.limit:Maximal length $object$ can get after this operation. (optional)
1379 ..param.resize_tag:Strategy that is applied if $object$ has not enough capacity to store the complete content. (optional)
1380 ...metafunction:Metafunction.DefaultOverflowExplicit
1381 ..returns:The number of free characters.
1382 ...metafunction:Metafunction.Size
1383 ...remarks:Depeding on the @Tag.Overflow Strategy.overflow strategy@ specified by $resize_tag$,
1384 this could be $size$ or less than $size$ if $object$ has not enough @Function.capacity@.
1387 template<typename T, typename TSize, typename TPosition>
1391 TPosition pos_begin,
1395 return resizeSpace(me, size, pos_begin, pos_end, typename DefaultOverflowExplicit<T>::Type());
1398 template<typename T, typename TSize, typename TPosition>
1402 TPosition pos_begin,
1407 return resizeSpace(me, size, pos_begin, pos_end, limit, typename DefaultOverflowExplicit<T>::Type());
1410 //////////////////////////////////////////////////////////////////////////////
1412 //////////////////////////////////////////////////////////////////////////////
1416 ..summary:Erases a part of a container
1418 ..signature:erase(object, pos [, pos_end])
1419 ..param.object:The container.
1420 ...type:Class.String
1421 ..param.pos:Position of the first item in $object$ that is to be destroyed.
1422 ..param.pos_end:Position behind the last item in $object$ that is to be destroyed. (optional)
1423 ...default:$pos + 1$
1424 ...remarks:If $pos_end$ is omitted, only one element in $object$ at position $pos$ is destroyed.
1425 ..remarks:$erase(object, pos, pos_end)$ is semantically the same as @Function.resizeSpace.resizeSpace(object, 0, pos, pos_end)@.
1428 template<typename T, typename TPosition>
1435 resizeSpace(me, 0, pos, pos_end);
1438 template<typename T, typename TPosition>
1444 resizeSpace(me, 0, pos, pos + 1);
1447 //////////////////////////////////////////////////////////////////////////////
1449 //////////////////////////////////////////////////////////////////////////////
1454 ..summary:Resizes and fills a container.
1455 ..signature:Size fill(object, new_length, value [, resize_tag])
1456 ..param.object: A container.
1457 ...type:Class.String
1458 ..param.new_length: The new length $object$ will get.
1459 ..param.value: Value that is copied if new items are created in $object$.
1460 ...remarks:If the $value$ argument is omitted, the default constructor is used to create
1461 new items in $object$.
1462 ..param.resize_tag: Specifies the strategy that is applied if the capacity of $object$ is less than $new_length$. (optional)
1463 ...type:Tag.Overflow Strategy
1464 ...default:Specified by @Metafunction.DefaultOverflowExplicit@.
1465 ..returns:The new length $length(object)$.
1466 ...metafunction:Metafunction.Size
1467 ..remarks:This function can be used both for expanding and for shrinking $object$.
1469 If $new_length$ is too large for $object$ (i.e. the @Function.capacity@ of $object$ is too small), then $object$ is
1470 expanded as far as possible. The resulting length
1471 of $object$ could be less than $new_length$, depending on the type of $object$ and the available storage.
1472 ..see:Function.length
1473 ..see:Function.reserve
1474 ..see:Function.resize
1477 template <typename T, typename TSize, typename TValue>
1478 inline typename Size<T>::Type
1485 return fill(me, new_length, val, typename DefaultOverflowExplicit<T>::Type());
1488 //////////////////////////////////////////////////////////////////////////////
1490 //////////////////////////////////////////////////////////////////////////////
1493 .Function.shrinkToFit:
1495 ..summary:Resizes container to minimum capacity
1496 ..signature:shrinkToFit(object)
1497 ..param.object: A container.
1499 ...text:$shrinkToFit(object)$ is equivalent to $reserve(object, length(object), Exact())$.
1500 ..see:Function.capacity
1501 ..see:Function.length
1502 ..see:Function.reserve
1505 template <typename T, typename TSize, typename TValue>
1510 reserve(me, length(me), Exact());
1512 //////////////////////////////////////////////////////////////////////////////
1514 } //namespace SEQAN_NAMESPACE_MAIN
1516 #endif //#ifndef SEQAN_HEADER_...