SeqAn-1.1/seqan/sequence/sequence_interface.h

   1  /*==========================================================================
   2                 SeqAn - The Library for Sequence Analysis
   3                           http://www.seqan.de
   4  ============================================================================
   5   Copyright (C) 2007
   6
   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.
  11
  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.
  16
  17  ============================================================================
  18   $Id: sequence_interface.h,v 1.1 2008/08/25 16:20:04 langmead Exp $
  19  ==========================================================================*/
  20
  21 #ifndef SEQAN_HEADER_SEQUENCE_INTERFACE_H
  22 #define SEQAN_HEADER_SEQUENCE_INTERFACE_H
  23
  24 namespace SEQAN_NAMESPACE_MAIN
  25 {
  26
  27 //////////////////////////////////////////////////////////////////////////////
  28 // Expand
  29 //////////////////////////////////////////////////////////////////////////////
  30
  31 /**
  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.
  55 */
  56 struct TagInsist_;
  57 typedef Tag<TagInsist_> const Insist;
  58 typedef Tag<TagInsist_> const Tight;
  59 //Insist INSIST;
  60
  61 struct TagLimit_;
  62 typedef Tag<TagLimit_> const Limit;
  63 //Limit LIMIT;
  64
  65 struct TagGenerous_;
  66 typedef Tag<TagGenerous_> const Generous;
  67 //Generous GENEROUS;
  68
  69 struct TagExact_;
  70 typedef Tag<TagExact_> const Exact;
  71 //Exact EXACT;
  72
  73 //____________________________________________________________________________
  74
  75 /**
  76 .Metafunction.DefaultOverflowImplicit:
  77 ..hidefromindex
  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.
  81 ...type:Class.String
  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
  86 */
  87 template <typename T>
  88 struct DefaultOverflowImplicit
  89 {
  90         typedef Insist Type;
  91 };
  92
  93 //____________________________________________________________________________
  94
  95 /**
  96 .Metafunction.DefaultOverflowExplicit:
  97 ..hidefromindex
  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.
 101 ...type:Class.String
 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
 106 */
 107 template <typename T>
 108 struct DefaultOverflowExplicit
 109 {
 110         typedef Exact Type;
 111 };
 112
 113 //////////////////////////////////////////////////////////////////////////////
 114 // IsContiguous
 115 //////////////////////////////////////////////////////////////////////////////
 116 /**
 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.
 127 */
 128 template <typename T>
 129 struct IsContiguous
 130 {
 131     typedef False Type;
 132         enum { VALUE = false };
 133 };
 134 template <typename T>
 135 struct IsContiguous<T const>:
 136         public IsContiguous<T> {};
 137
 138 //////////////////////////////////////////////////////////////////////////////
 139 // IsSequence
 140 //////////////////////////////////////////////////////////////////////////////
 141 /**
 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$.
 148 */
 149 template <typename T>
 150 struct IsSequence
 151 {
 152     typedef False Type;
 153         enum { VALUE = false };
 154 };
 155 template <typename T>
 156 struct IsSequence<T const>:
 157         public IsSequence<T> {};
 158
 159 //////////////////////////////////////////////////////////////////////////////
 160 // AllowsFastRandomAccess
 161 //////////////////////////////////////////////////////////////////////////////
 162 /**
 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$.
 169 */
 170 template <typename T>
 171 struct AllowsFastRandomAccess
 172 {
 173     typedef True Type;
 174         enum { VALUE = true };
 175 };
 176 template <typename T>
 177 struct AllowsFastRandomAccess<T const>:
 178         public AllowsFastRandomAccess<T> {};
 179
 180 //////////////////////////////////////////////////////////////////////////////
 181 // identification
 182 //////////////////////////////////////////////////////////////////////////////
 183 /**
 184 .Function.id:
 185 ..cat:Miscellaneous
 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.
 204 */
 205 template <typename T>
 206 inline void const *
 207 id(T const & me)
 208 {
 209 SEQAN_CHECKPOINT
 210         return end(me, Standard());
 211 }
 212
 213 //////////////////////////////////////////////////////////////////////////////
 214
 215 /**
 216 .Function.shareResources:
 217 ..cat:Miscellaneous
 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.
 224 */
 225
 226 template <typename T1, typename T2>
 227 inline bool
 228 shareResources(T1 const & obj1,
 229                            T2 const & obj2)
 230 {
 231 SEQAN_CHECKPOINT
 232         return id(obj1) == id(obj2);
 233 }
 234
 235 //////////////////////////////////////////////////////////////////////////////
 236 // begin
 237 //////////////////////////////////////////////////////////////////////////////
 238
 239 /**
 240 .Function.begin:
 241 ..cat:Iteration
 242 ..cat:Containers
 243 ..summary:The begin of a container.
 244 ..signature:Iterator begin(object [, tag])
 245 ..param.object:A container.
 246 ...type:Class.String
 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.
 253 ..see:Function.end
 254 ..see:Metafunction.Iterator
 255 */
 256 template <typename T>
 257 inline typename Iterator<T, typename DefaultGetIteratorSpec<T>::Type>::Type
 258 begin(T & me)
 259 {
 260 SEQAN_CHECKPOINT
 261         return begin(me, typename DefaultGetIteratorSpec<T>::Type()) ;
 262 }
 263 template <typename T>
 264 inline typename Iterator<T const, typename DefaultGetIteratorSpec<T>::Type>::Type
 265 begin(T const & me)
 266 {
 267 SEQAN_CHECKPOINT
 268         return begin(me, typename DefaultGetIteratorSpec<T>::Type()) ;
 269 }
 270
 271 //____________________________________________________________________________
 272
 273 //* ???Anti Default Sequences
 274 template <typename T>
 275 inline typename Iterator<T, Standard>::Type
 276 _begin_default(T & me,
 277                            Standard)
 278 {
 279 SEQAN_CHECKPOINT
 280         return & me;
 281 }
 282 template <typename T>
 283 inline typename Iterator<T const, Standard>::Type
 284 _begin_default(T const & me,
 285                            Standard)
 286 {
 287 SEQAN_CHECKPOINT
 288         return & me;
 289 }
 290 //*/
 291
 292 //____________________________________________________________________________
 293
 294 template <typename T>
 295 inline typename Iterator<T, Rooted>::Type
 296 _begin_default(T & me,
 297                            Rooted)
 298 {
 299 SEQAN_CHECKPOINT
 300         typedef typename Iterator<T, Rooted>::Type TIterator;
 301         return TIterator(me, begin(me, Standard()));
 302 }
 303 template <typename T>
 304 inline typename Iterator<T const, Rooted>::Type
 305 _begin_default(T const & me,
 306                            Rooted)
 307 {
 308 SEQAN_CHECKPOINT
 309         typedef typename Iterator<T const, Rooted>::Type TIterator;
 310         return TIterator(me, begin(me, Standard()));
 311 }
 312 //____________________________________________________________________________
 313
 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,
 319           Standard);
 320
 321 //____________________________________________________________________________
 322
 323 template <typename T, typename TSpec>
 324 inline typename Iterator<T, Tag<TSpec> const>::Type
 325 begin(T & me,
 326           Tag<TSpec> const tag_)
 327 {
 328 SEQAN_CHECKPOINT
 329         return _begin_default(me, tag_);
 330 }
 331 template <typename T, typename TSpec>
 332 inline typename Iterator<T const, Tag<TSpec> const>::Type
 333 begin(T const & me,
 334           Tag<TSpec> const tag_)
 335 {
 336 SEQAN_CHECKPOINT
 337         return _begin_default(me, tag_);
 338 }
 339
 340
 341 /*
 342 template <typename TValue>
 343 inline typename Iterator<TValue *, Standard>::Type
 344 begin(TValue * me,
 345           Standard)
 346 {
 347 SEQAN_CHECKPOINT
 348         return me;
 349 }
 350
 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,
 355           Standard)
 356 {
 357 SEQAN_CHECKPOINT
 358         return me;
 359 }
 360
 361 template <typename TValue, typename TSpec>
 362 inline typename Iterator<TValue *, Standard>::Type
 363 begin(TValue * me,
 364           Tag<TSpec> const tag_)
 365 //        Standard)
 366 {
 367 SEQAN_CHECKPOINT
 368         return me;
 369 }
 370
 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_)
 376 //        Standard)
 377 {
 378 SEQAN_CHECKPOINT
 379         return me;
 380 }
 381
 382 */
 383
 384
 385
 386 //////////////////////////////////////////////////////////////////////////////
 387 // beginPosition
 388 //////////////////////////////////////////////////////////////////////////////
 389 /**
 390 .Function.beginPosition:
 391 ..cat:Containers
 392 ..summary:Begin position of object in host.
 393 ..signature:Position beginPosition(object)
 394 ..param.object:An object.
 395 ...type:Class.String
 396 ...concept:Concept.Container
 397 ..returns:The position of the first item in $host(object)$ that belongs of $object$.
 398 ...metafunction:Metafunction.Position
 399 ..remarks
 400 ...text:For most classes $beginPosition$ always returns 0. Exceptions are e.g. @Spec.InfixSegment@ and @Spec.SuffixSegment@.
 401 ..see:Function.begin
 402 */
 403 template <typename T>
 404 inline typename Position<T>::Type
 405 beginPosition(T &)
 406 {
 407 SEQAN_CHECKPOINT
 408         return 0;
 409 }
 410 template <typename T>
 411 inline typename Position<T>::Type
 412 beginPosition(T const &)
 413 {
 414 SEQAN_CHECKPOINT
 415         return 0;
 416 }
 417
 418 //////////////////////////////////////////////////////////////////////////////
 419 // end
 420 //////////////////////////////////////////////////////////////////////////////
 421
 422 /**
 423 .Function.end:
 424 ..cat:Iteration
 425 ..cat:Containers
 426 ..summary:The end of a container.
 427 ..signature:Iterator end(object [, tag])
 428 ..param.object:A container.
 429 ...type:Class.String
 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.
 436 ..see:Function.begin
 437 ..see:Metafunction.Iterator
 438 */
 439 template <typename T>
 440 inline typename Iterator<T, typename DefaultGetIteratorSpec<T>::Type>::Type
 441 end(T & me)
 442 {
 443 SEQAN_CHECKPOINT
 444         return end(me, typename DefaultGetIteratorSpec<T>::Type()) ;
 445 }
 446 template <typename T>
 447 inline typename Iterator<T const, typename DefaultGetIteratorSpec<T>::Type>::Type
 448 end(T const & me)
 449 {
 450 SEQAN_CHECKPOINT
 451         return end(me, typename DefaultGetIteratorSpec<T>::Type()) ;
 452 }
 453
 454 //____________________________________________________________________________
 455
 456 //* ???Anti Default Sequences
 457 template <typename T>
 458 inline typename Iterator<T, Standard>::Type
 459 _end_default(T & me,
 460                          Standard)
 461 {
 462 SEQAN_CHECKPOINT
 463         return (& me) + 1;
 464 }
 465 template <typename T>
 466 inline typename Iterator<T const, Standard>::Type
 467 _end_default(T const & me,
 468                          Standard)
 469 {
 470 SEQAN_CHECKPOINT
 471         return (& me) + 1;
 472 }
 473 //*/
 474
 475 //____________________________________________________________________________
 476
 477 template <typename T>
 478 inline typename Iterator<T, Rooted>::Type
 479 _end_default(T & me,
 480                          Rooted)
 481 {
 482 SEQAN_CHECKPOINT
 483         typedef typename Iterator<T, Rooted>::Type TIterator;
 484         return TIterator(me, end(me, Standard()));
 485 }
 486 template <typename T>
 487 inline typename Iterator<T const, Rooted>::Type
 488 _end_default(T const & me,
 489                          Rooted)
 490 {
 491 SEQAN_CHECKPOINT
 492         typedef typename Iterator<T const, Rooted>::Type TIterator;
 493         return TIterator(me, end(me, Standard()));
 494 }
 495
 496 //____________________________________________________________________________
 497
 498 template <typename T, typename TSpec>
 499 inline typename Iterator<T, Tag<TSpec> const>::Type
 500 end(T & me,
 501         Tag<TSpec> const tag_)
 502 {
 503 SEQAN_CHECKPOINT
 504         return _end_default(me, tag_);
 505 }
 506 template <typename T, typename TSpec>
 507 inline typename Iterator<T const, Tag<TSpec> const>::Type
 508 end(T const & me,
 509         Tag<TSpec> const tag_)
 510 {
 511 SEQAN_CHECKPOINT
 512         return _end_default(me, tag_);
 513 }
 514
 515 //////////////////////////////////////////////////////////////////////////////
 516 // endPosition
 517 //////////////////////////////////////////////////////////////////////////////
 518
 519 /**
 520 .Function.endPosition:
 521 ..cat:Containers
 522 ..summary:End position of object in host.
 523 ..signature:Position endPosition(object)
 524 ..param.object:An object.
 525 ...concept:Concept.Container
 526 ...type:Class.String
 527 ..returns:The position behind the last item in $host(object)$ that belongs of $object$.
 528 ...metafunction:Metafunction.Position
 529 ..see:Function.end
 530 ..see:Function.beginPosition
 531 */
 532 template <typename T>
 533 inline typename Position<T>::Type
 534 endPosition(T & me)
 535 {
 536 SEQAN_CHECKPOINT
 537         return length(me);
 538 }
 539 template <typename T>
 540 inline typename Position<T>::Type
 541 endPosition(T const & me)
 542 {
 543 SEQAN_CHECKPOINT
 544         return length(me);
 545 }
 546
 547 //////////////////////////////////////////////////////////////////////////////
 548 // value
 549 //////////////////////////////////////////////////////////////////////////////
 550
 551 /**
 552 .Function.value:
 553 ..cat:Iteration
 554 ..cat:Containers
 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
 561 */
 562
 563 //* ???Anti Default Sequences
 564 template <typename T, typename TPos>
 565 inline typename Reference<T>::Type
 566 value(T & me,
 567           TPos /*pos*/)
 568 {
 569 SEQAN_CHECKPOINT
 570         return me;
 571 }
 572 template <typename T, typename TPos>
 573 inline typename Reference<T const>::Type
 574 value(T const & me,
 575           TPos /*pos*/)
 576 {
 577 SEQAN_CHECKPOINT
 578         return me;
 579 }
 580 //*/
 581
 582 //////////////////////////////////////////////////////////////////////////////
 583 // getValue
 584 //////////////////////////////////////////////////////////////////////////////
 585
 586 /**
 587 .Function.getValue:
 588 ..summary:Access to the value.
 589 ..cat:Containers
 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
 599 ..remarks:
 600 ...text:If $pos$ is out of range, then the behavior of the function is undefined.
 601 ..see:Metafunction.GetValue
 602 ..see:Metafunction.Position
 603 ..see:Function.value
 604 */
 605
 606 template <typename T, typename TPos>
 607 inline typename GetValue<T>::Type
 608 getValue(T & me,
 609                  TPos pos)
 610 {
 611 SEQAN_CHECKPOINT
 612         return (typename GetValue<T>::Type) value(me, pos);
 613 }
 614 template <typename T, typename TPos>
 615 inline typename GetValue<T const>::Type
 616 getValue(T const & me,
 617                  TPos pos)
 618 {
 619 SEQAN_CHECKPOINT
 620         return value(me, pos);
 621 }
 622
 623 //////////////////////////////////////////////////////////////////////////////
 624 // front
 625 //////////////////////////////////////////////////////////////////////////////
 626
 627 /**
 628 .Function.Container#front:
 629 ..cat:Containers
 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))$.
 637 ..see:Function.value
 638 ..see:Function.begin
 639 */
 640
 641
 642 template <typename T>
 643 inline typename Reference<T>::Type
 644 front(T & me)
 645 {
 646 SEQAN_CHECKPOINT
 647     return value(me, beginPosition(me));
 648 }
 649 template <typename T>
 650 inline typename Reference<T const>::Type
 651 front(T const & me)
 652 {
 653 SEQAN_CHECKPOINT
 654     return value(me, beginPosition(me));
 655 }
 656
 657 //////////////////////////////////////////////////////////////////////////////
 658 // back
 659 //////////////////////////////////////////////////////////////////////////////
 660
 661 /**
 662 .Function.back:
 663 ..cat:Containers
 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)$.
 671 ..see:Function.value
 672 ..see:Function.end
 673 ..see:Function.Container#front
 674 */
 675
 676 template <typename T>
 677 inline typename Reference<T const>::Type
 678 back(T const & me)
 679 {
 680 SEQAN_CHECKPOINT
 681     return value(me, endPosition(me) - 1);
 682 }
 683
 684 template <typename T>
 685 inline typename Reference<T>::Type
 686 back(T & me)
 687 {
 688 SEQAN_CHECKPOINT
 689     return value(me, endPosition(me) - 1);
 690 }
 691
 692 //////////////////////////////////////////////////////////////////////////////
 693 // iter
 694 //////////////////////////////////////////////////////////////////////////////
 695
 696 /**
 697 .Function.iter:
 698 ..cat:Containers
 699 ..summary:Iterator to item at given position.
 700 ..signature:Iterator iter(object, pos [, tag])
 701 ..param.object:A container.
 702 ...type:Class.String
 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
 709 ..remarks:
 710 ...text:If $pos$ is out of range, then the behavior of the function is undefined.
 711 ..see:Function.value
 712 ..see:Metafunction.Iterator
 713 ..see:Metafunction.Position
 714 */
 715
 716 template <typename T, typename TPos>
 717 inline typename Iterator<T, typename DefaultGetIteratorSpec<T>::Type>::Type
 718 iter(T & me,
 719          TPos pos)
 720 {
 721 SEQAN_CHECKPOINT
 722         return iter(me, pos, typename DefaultGetIteratorSpec<T>::Type());
 723 }
 724 template <typename T, typename TPos>
 725 inline typename Iterator<T const, typename DefaultGetIteratorSpec<T>::Type>::Type
 726 iter(T const & me,
 727          TPos pos)
 728 {
 729 SEQAN_CHECKPOINT
 730         return iter(me, pos, typename DefaultGetIteratorSpec<T const>::Type());
 731 }
 732
 733
 734 template <typename T, typename TPos, typename TTag>
 735 inline typename Iterator<T, Tag<TTag> const>::Type
 736 iter(T & me,
 737          TPos pos,
 738          Tag<TTag> const tag_)
 739 {
 740 SEQAN_CHECKPOINT
 741         return begin(me, tag_) + pos;
 742 }
 743 template <typename T, typename TPos, typename TTag>
 744 inline typename Iterator<T const, Tag<TTag> const>::Type
 745 iter(T const & me,
 746          TPos pos,
 747          Tag<TTag> const tag_)
 748 {
 749 SEQAN_CHECKPOINT
 750         return begin(me, tag_) + pos;
 751 }
 752
 753 //////////////////////////////////////////////////////////////////////////////
 754 // assignValue (3)
 755 //////////////////////////////////////////////////////////////////////////////
 756 /**
 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$.
 765 ..remarks.text:
 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.
 768 */
 769
 770 template <typename T, typename TValue, typename TPos>
 771 inline void
 772 assignValue(T & me,
 773                         TPos pos,
 774                         TValue const & _value)
 775 {
 776 SEQAN_CHECKPOINT
 777         assign(value(me, pos), _value);
 778 }
 779
 780 //////////////////////////////////////////////////////////////////////////////
 781 // moveValue (3)
 782 //////////////////////////////////////////////////////////////////////////////
 783 /**
 784 .Function.moveValue:
 785 ..cat:Content Manipulation
 786 ..signature:moveValue(container, pos, value)
 787 ..param.object:
 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$.
 794 ..remarks.text:
 795         This function possibly clears $value$.
 796         If $value$ should be used further, consider to use @Function.assignValue@ instead.
 797 */
 798
 799 template <typename T, typename TValue, typename TPos>
 800 inline void
 801 moveValue(T & me,
 802                   TPos pos,
 803                   TValue const & _value)
 804 {
 805 SEQAN_CHECKPOINT
 806         move(value(me, pos), _value);
 807 }
 808
 809 //////////////////////////////////////////////////////////////////////////////
 810 // length
 811 //////////////////////////////////////////////////////////////////////////////
 812 /**
 813 .Function.length:
 814 ..cat:Containers
 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
 823 */
 824
 825 //* ???Anti Default Sequences
 826 template <typename T>
 827 inline typename Size<T const>::Type
 828 length(T const & /*me*/)
 829 {
 830 SEQAN_CHECKPOINT
 831         return 1;
 832 }
 833 //*/
 834
 835 //////////////////////////////////////////////////////////////////////////////
 836 // capacity
 837 //////////////////////////////////////////////////////////////////////////////
 838
 839 /**
 840 .Function.capacity:
 841 ..cat:Containers
 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.
 852 */
 853 template <typename T>
 854 inline typename Size<T const>::Type
 855 capacity(T const & me)
 856 {
 857 SEQAN_CHECKPOINT
 858         return length(me);
 859 }
 860
 861 //////////////////////////////////////////////////////////////////////////////
 862 // empty
 863 //////////////////////////////////////////////////////////////////////////////
 864
 865 /**
 866 .Function.empty:
 867 ..cat:Containers
 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
 875 */
 876 template <typename T>
 877 inline bool
 878 empty(T const & me)
 879 {
 880 SEQAN_CHECKPOINT
 881         return (length(me) == 0);
 882 }
 883
 884 //////////////////////////////////////////////////////////////////////////////
 885 // _computeSize4Capacity
 886 //////////////////////////////////////////////////////////////////////////////
 887
 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.
 894
 895
 896 template <typename T, typename TSize>
 897 inline TSize
 898 _computeSize4Capacity(T const & /*me*/,
 899                                           TSize capacity)
 900 {
 901 SEQAN_CHECKPOINT
 902         if (sizeof(T) <= 2) return capacity + 1;
 903         else return capacity;
 904 }
 905
 906
 907 //////////////////////////////////////////////////////////////////////////////
 908 // computeGenerousCapacity
 909 //////////////////////////////////////////////////////////////////////////////
 910 /**
 911 .Function.computeGenerousCapacity:
 912 ..hidefromindex
 913 ..cat:Containers
 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
 922 */
 923 template <typename T, typename TSize>
 924 inline TSize
 925 computeGenerousCapacity(T const & /*me*/,
 926                                                  TSize capacity)
 927 {
 928 SEQAN_CHECKPOINT
 929         if (capacity <= 32) return 32;
 930         return capacity + (capacity >> 1);
 931 }
 932
 933 //////////////////////////////////////////////////////////////////////////////
 934 // _storageUpdated
 935 //////////////////////////////////////////////////////////////////////////////
 936
 937 /*
 938 template <typename T>
 939 inline void
 940 _storageUpdated(T & me,
 941                                 void const *)
 942 {
 943 }
 944
 945 template <typename T>
 946 inline void
 947 _storageUpdated(T & me)
 948 {
 949         _storageUpdated_(me, (T *) 0);
 950 }
 951
 952 template <typename T>
 953 inline void
 954 _storageUpdated(T const & me)
 955 {
 956         _storageUpdated_(me, (T const *) 0);
 957 }
 958 */
 959
 960
 961 //////////////////////////////////////////////////////////////////////////////
 962 // assign
 963 //////////////////////////////////////////////////////////////////////////////
 964
 965 template<typename TTarget, typename TSource>
 966 inline void
 967 assign(TTarget & target,
 968            TSource & source,
 969            typename Size<TTarget>::Type limit)
 970 {
 971 SEQAN_CHECKPOINT
 972         assign(target, source, limit, typename DefaultOverflowImplicit<TTarget>::Type());
 973 }
 974 template<typename TTarget, typename TSource>
 975 inline void
 976 assign(TTarget const & target,
 977            TSource & source,
 978            typename Size<TTarget>::Type limit)
 979 {
 980 SEQAN_CHECKPOINT
 981         assign(target, source, limit, typename DefaultOverflowImplicit<TTarget const>::Type());
 982 }
 983 template<typename TTarget, typename TSource>
 984 inline void
 985 assign(TTarget & target,
 986            TSource const & source,
 987            typename Size<TTarget>::Type limit)
 988 {
 989 SEQAN_CHECKPOINT
 990         assign(target, source, limit, typename DefaultOverflowImplicit<TTarget>::Type());
 991 }
 992 template<typename TTarget, typename TSource>
 993 inline void
 994 assign(TTarget const & target,
 995            TSource const & source,
 996            typename Size<TTarget>::Type limit)
 997 {
 998 SEQAN_CHECKPOINT
 999         assign(target, source, limit, typename DefaultOverflowImplicit<TTarget const>::Type());
1000 }
1001
1002 //////////////////////////////////////////////////////////////////////////////
1003 // append
1004 //////////////////////////////////////////////////////////////////////////////
1005
1006 /**
1007 .Function.append:
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
1020 */
1021 template<typename TTarget, typename TSource>
1022 inline void
1023 append(TTarget & target,
1024            TSource & source)
1025 {
1026 SEQAN_CHECKPOINT
1027         append(target, source, typename DefaultOverflowImplicit<TTarget>::Type());
1028 }
1029 template<typename TTarget, typename TSource>
1030 inline void
1031 append(TTarget const & target,
1032            TSource & source)
1033 {
1034 SEQAN_CHECKPOINT
1035         append(target, source, typename DefaultOverflowImplicit<TTarget const>::Type());
1036 }
1037 template<typename TTarget, typename TSource>
1038 inline void
1039 append(TTarget & target,
1040            TSource const & source)
1041 {
1042 SEQAN_CHECKPOINT
1043         append(target, source, typename DefaultOverflowImplicit<TTarget>::Type());
1044 }
1045 template<typename TTarget, typename TSource>
1046 inline void
1047 append(TTarget const & target,
1048            TSource const & source)
1049 {
1050 SEQAN_CHECKPOINT
1051         append(target, source, typename DefaultOverflowImplicit<TTarget const>::Type());
1052 }
1053
1054 //____________________________________________________________________________
1055
1056 template<typename TTarget, typename TSource>
1057 inline void
1058 append(TTarget & target,
1059            TSource & source,
1060            typename Size<TTarget>::Type limit)
1061 {
1062 SEQAN_CHECKPOINT
1063         append(target, source, limit, typename DefaultOverflowImplicit<TTarget>::Type());
1064 }
1065 template<typename TTarget, typename TSource>
1066 inline void
1067 append(TTarget const & target,
1068            TSource & source,
1069            typename Size<TTarget>::Type limit)
1070 {
1071 SEQAN_CHECKPOINT
1072         append(target, source, limit, typename DefaultOverflowImplicit<TTarget const>::Type());
1073 }
1074 template<typename TTarget, typename TSource>
1075 inline void
1076 append(TTarget & target,
1077            TSource const & source,
1078            typename Size<TTarget>::Type limit)
1079 {
1080 SEQAN_CHECKPOINT
1081         append(target, source, limit, typename DefaultOverflowImplicit<TTarget>::Type());
1082 }
1083 template<typename TTarget, typename TSource>
1084 inline void
1085 append(TTarget const & target,
1086            TSource const & source,
1087            typename Size<TTarget>::Type limit)
1088 {
1089 SEQAN_CHECKPOINT
1090         append(target, source, limit, typename DefaultOverflowImplicit<TTarget const>::Type());
1091 }
1092
1093
1094 //////////////////////////////////////////////////////////////////////////////
1095 // appendValue
1096 //////////////////////////////////////////////////////////////////////////////
1097 /**
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$.
1104 ..param.resize_tag:
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.
1108 */
1109
1110 template <typename T, typename TValue>
1111 inline void
1112 appendValue(T & me,
1113                         TValue const & _value)
1114 {
1115 SEQAN_CHECKPOINT
1116         appendValue(me, _value, typename DefaultOverflowImplicit<T>::Type());
1117 }
1118 template <typename T, typename TValue>
1119 inline void
1120 appendValue(T const & me,
1121                         TValue const & _value)
1122 {
1123 SEQAN_CHECKPOINT
1124         appendValue(me, _value, typename DefaultOverflowImplicit<T const>::Type());
1125 }
1126
1127 //////////////////////////////////////////////////////////////////////////////
1128 // insertValue
1129 //////////////////////////////////////////////////////////////////////////////
1130 /**
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
1142 */
1143
1144 template <typename T, typename TPosition, typename TValue>
1145 inline void
1146 insertValue(T & me,
1147                         TPosition pos,
1148                         TValue const & _value)
1149 {
1150 SEQAN_CHECKPOINT
1151         insertValue(me, pos, _value, typename DefaultOverflowImplicit<T>::Type());
1152 }
1153 template <typename T, typename TPosition, typename TValue>
1154 inline void
1155 insertValue(T const & me,
1156                         TPosition pos,
1157                         TValue const & _value)
1158 {
1159 SEQAN_CHECKPOINT
1160         insertValue(me, pos, _value, typename DefaultOverflowImplicit<T const>::Type());
1161 }
1162
1163 //////////////////////////////////////////////////////////////////////////////
1164 // replace
1165 //////////////////////////////////////////////////////////////////////////////
1166
1167 /**
1168 .Function.replace:
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.
1188 */
1189 template<typename TTarget, typename TPositionBegin, typename TPositionEnd, typename TSource>
1190 inline void
1191 replace(TTarget & target,
1192                 TPositionBegin pos_begin,
1193                 TPositionEnd pos_end,
1194                 TSource & source)
1195 {
1196         replace(target, pos_begin, pos_end, source, typename DefaultOverflowImplicit<TTarget>::Type());
1197 }
1198 template<typename TTarget, typename TPositionBegin, typename TPositionEnd, typename TSource>
1199 inline void
1200 replace(TTarget const & target,
1201                 TPositionBegin pos_begin,
1202                 TPositionEnd pos_end,
1203                 TSource & source)
1204 {
1205         replace(target, pos_begin, pos_end, source, typename DefaultOverflowImplicit<TTarget const>::Type());
1206 }
1207 template<typename TTarget, typename TPositionBegin, typename TPositionEnd, typename TSource>
1208 inline void
1209 replace(TTarget & target,
1210                 TPositionBegin pos_begin,
1211                 TPositionEnd pos_end,
1212                 TSource const & source)
1213 {
1214         replace(target, pos_begin, pos_end, source, typename DefaultOverflowImplicit<TTarget>::Type());
1215 }
1216 template<typename TTarget, typename TPositionBegin, typename TPositionEnd, typename TSource>
1217 inline void
1218 replace(TTarget const & target,
1219                 TPositionBegin pos_begin,
1220                 TPositionEnd pos_end,
1221                 TSource const & source)
1222 {
1223         replace(target, pos_begin, pos_end, source, typename DefaultOverflowImplicit<TTarget const>::Type());
1224 }
1225
1226 //____________________________________________________________________________
1227
1228 template<typename TTarget, typename TPositionBegin, typename TPositionEnd, typename TSource>
1229 inline void
1230 replace(TTarget & target,
1231                 TPositionBegin pos_begin,
1232                 TPositionEnd pos_end,
1233                 TSource & source,
1234                 typename Size<TTarget>::Type limit)
1235 {
1236         replace(target, pos_begin, pos_end, source, limit, typename DefaultOverflowImplicit<TTarget>::Type());
1237 }
1238 template<typename TTarget, typename TPositionBegin, typename TPositionEnd, typename TSource>
1239 inline void
1240 replace(TTarget const & target,
1241                 TPositionBegin pos_begin,
1242                 TPositionEnd pos_end,
1243                 TSource & source,
1244                 typename Size<TTarget>::Type limit)
1245 {
1246         replace(target, pos_begin, pos_end, source, limit, typename DefaultOverflowImplicit<TTarget const>::Type());
1247 }
1248 template<typename TTarget, typename TPositionBegin, typename TPositionEnd, typename TSource>
1249 inline void
1250 replace(TTarget & target,
1251                 TPositionBegin pos_begin,
1252                 TPositionEnd pos_end,
1253                 TSource const & source,
1254                 typename Size<TTarget>::Type limit)
1255 {
1256         replace(target, pos_begin, pos_end, source, limit, typename DefaultOverflowImplicit<TTarget>::Type());
1257 }
1258 template<typename TTarget, typename TPositionBegin, typename TPositionEnd, typename TSource>
1259 inline void
1260 replace(TTarget const & target,
1261                 TPositionBegin pos_begin,
1262                 TPositionEnd pos_end,
1263                 TSource const & source,
1264                 typename Size<TTarget>::Type limit)
1265 {
1266         replace(target, pos_begin, pos_end, source, limit, typename DefaultOverflowImplicit<TTarget const>::Type());
1267 }
1268
1269
1270 //////////////////////////////////////////////////////////////////////////////
1271 // reserve
1272 //////////////////////////////////////////////////////////////////////////////
1273
1274 /**
1275 .Function.reserve:
1276 ..cat:Containers
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
1293 */
1294 template <typename T, typename TSize>
1295 inline typename Size<T>::Type
1296 reserve(
1297         T & /*me*/,
1298         TSize new_capacity,
1299         Insist)
1300 {
1301 SEQAN_CHECKPOINT
1302         return new_capacity;
1303 }
1304
1305 template <typename T, typename TSize>
1306 inline typename Size<T>::Type
1307 reserve(
1308         T & me,
1309         TSize new_capacity,
1310         Limit)
1311 {
1312 SEQAN_CHECKPOINT
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;
1316 }
1317
1318 template <typename T, typename TSize>
1319 inline typename Size<T>::Type
1320 reserve(
1321         T & me,
1322         TSize new_capacity)
1323 {
1324 SEQAN_CHECKPOINT
1325         return reserve(me, new_capacity, typename DefaultOverflowExplicit<T>::Type());
1326 }
1327
1328 //////////////////////////////////////////////////////////////////////////////
1329 // resize
1330 //////////////////////////////////////////////////////////////////////////////
1331
1332 /**
1333 .Function.resize:
1334 ..cat:Containers
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$.
1346 ...text:
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
1352 */
1353 template <typename T, typename TSize>
1354 inline typename Size<T>::Type
1355 resize(
1356         T & me,
1357         TSize new_length)
1358 {
1359 SEQAN_CHECKPOINT
1360         return resize(me, new_length, typename DefaultOverflowExplicit<T>::Type());
1361 }
1362
1363 //////////////////////////////////////////////////////////////////////////////
1364 // resizeSpace
1365 //////////////////////////////////////////////////////////////////////////////
1366
1367 /**
1368 .Function.resizeSpace:
1369 ..cat:Containers
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@.
1385 */
1386
1387 template<typename T, typename TSize, typename TPosition>
1388 inline TSize
1389 resizeSpace(T & me,
1390                         TSize size,
1391                         TPosition pos_begin,
1392                         TPosition pos_end)
1393 {
1394 SEQAN_CHECKPOINT
1395         return resizeSpace(me, size, pos_begin, pos_end, typename DefaultOverflowExplicit<T>::Type());
1396 }
1397
1398 template<typename T, typename TSize, typename TPosition>
1399 inline TSize
1400 resizeSpace(T & me,
1401                         TSize size,
1402                         TPosition pos_begin,
1403                         TPosition pos_end,
1404                         TSize limit)
1405 {
1406 SEQAN_CHECKPOINT
1407         return resizeSpace(me, size, pos_begin, pos_end, limit, typename DefaultOverflowExplicit<T>::Type());
1408 }
1409
1410 //////////////////////////////////////////////////////////////////////////////
1411 // erase
1412 //////////////////////////////////////////////////////////////////////////////
1413
1414 /**
1415 .Function.erase:
1416 ..summary:Erases a part of a container
1417 ..cat:Containers
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)@.
1426 */
1427
1428 template<typename T, typename TPosition>
1429 inline void
1430 erase(T & me,
1431           TPosition pos,
1432           TPosition pos_end)
1433 {
1434 SEQAN_CHECKPOINT
1435         resizeSpace(me, 0, pos, pos_end);
1436 }
1437
1438 template<typename T, typename TPosition>
1439 inline void
1440 erase(T & me,
1441           TPosition pos)
1442 {
1443 SEQAN_CHECKPOINT
1444         resizeSpace(me, 0, pos, pos + 1);
1445 }
1446
1447 //////////////////////////////////////////////////////////////////////////////
1448 // fill
1449 //////////////////////////////////////////////////////////////////////////////
1450
1451 /**
1452 .Function.fill:
1453 ..cat:Containers
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$.
1468 ...text:
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
1475 */
1476
1477 template <typename T, typename TSize, typename TValue>
1478 inline typename Size<T>::Type
1479 fill(
1480         T & me,
1481         TSize new_length,
1482         TValue const & val)
1483 {
1484 SEQAN_CHECKPOINT
1485         return fill(me, new_length, val, typename DefaultOverflowExplicit<T>::Type());
1486 }
1487
1488 //////////////////////////////////////////////////////////////////////////////
1489 // shrinkToFit
1490 //////////////////////////////////////////////////////////////////////////////
1491
1492 /**
1493 .Function.shrinkToFit:
1494 ..cat:Containers
1495 ..summary:Resizes container to minimum capacity
1496 ..signature:shrinkToFit(object)
1497 ..param.object: A container.
1498 ..remarks
1499 ...text:$shrinkToFit(object)$ is equivalent to $reserve(object, length(object), Exact())$.
1500 ..see:Function.capacity
1501 ..see:Function.length
1502 ..see:Function.reserve
1503 */
1504
1505 template <typename T, typename TSize, typename TValue>
1506 inline void
1507 shrinkToFit(T & me)
1508 {
1509 SEQAN_CHECKPOINT
1510         reserve(me, length(me), Exact());
1511 }
1512 //////////////////////////////////////////////////////////////////////////////
1513
1514 } //namespace SEQAN_NAMESPACE_MAIN
1515
1516 #endif //#ifndef SEQAN_HEADER_...