src/corelib/tools/qvector.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the QtCore module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** GNU Lesser General Public License Usage
  10 ** This file may be used under the terms of the GNU Lesser General Public
  11 ** License version 2.1 as published by the Free Software Foundation and
  12 ** appearing in the file LICENSE.LGPL included in the packaging of this
  13 ** file. Please review the following information to ensure the GNU Lesser
  14 ** General Public License version 2.1 requirements will be met:
  15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  16 **
  17 ** In addition, as a special exception, Nokia gives you certain additional
  18 ** rights. These rights are described in the Nokia Qt LGPL Exception
  19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  20 **
  21 ** GNU General Public License Usage
  22 ** Alternatively, this file may be used under the terms of the GNU General
  23 ** Public License version 3.0 as published by the Free Software Foundation
  24 ** and appearing in the file LICENSE.GPL included in the packaging of this
  25 ** file. Please review the following information to ensure the GNU General
  26 ** Public License version 3.0 requirements will be met:
  27 ** http://www.gnu.org/copyleft/gpl.html.
  28 **
  29 ** Other Usage
  30 ** Alternatively, this file may be used in accordance with the terms and
  31 ** conditions contained in a signed written agreement between you and Nokia.
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qvector.h"
  43 #include "qtools_p.h"
  44
  45 #include <string.h>
  46 #include <stdlib.h>
  47
  48 QT_BEGIN_NAMESPACE
  49
  50 static inline int alignmentThreshold()
  51 {
  52     // malloc on 32-bit platforms should return pointers that are 8-byte aligned or more
  53     // while on 64-bit platforms they should be 16-byte aligned or more
  54     return 2 * sizeof(void*);
  55 }
  56
  57 const QVectorData QVectorData::shared_null = { Q_REFCOUNT_INITIALIZE_STATIC, 0, 0, false, 0 };
  58
  59 QVectorData *QVectorData::allocate(int size, int alignment)
  60 {
  61     return static_cast<QVectorData *>(alignment > alignmentThreshold() ? qMallocAligned(size, alignment) : ::malloc(size));
  62 }
  63
  64 QVectorData *QVectorData::reallocate(QVectorData *x, int newsize, int oldsize, int alignment)
  65 {
  66     if (alignment > alignmentThreshold())
  67         return static_cast<QVectorData *>(qReallocAligned(x, newsize, oldsize, alignment));
  68     return static_cast<QVectorData *>(realloc(x, newsize));
  69 }
  70
  71 void QVectorData::free(QVectorData *x, int alignment)
  72 {
  73     if (alignment > alignmentThreshold())
  74         qFreeAligned(x);
  75     else
  76         ::free(x);
  77 }
  78
  79 int QVectorData::grow(int sizeOfHeader, int size, int sizeOfT)
  80 {
  81     return qAllocMore(size * sizeOfT, sizeOfHeader) / sizeOfT;
  82 }
  83
  84 /*!
  85     \class QVector
  86     \brief The QVector class is a template class that provides a dynamic array.
  87
  88     \ingroup tools
  89     \ingroup shared
  90
  91     \reentrant
  92
  93     QVector\<T\> is one of Qt's generic \l{container classes}. It
  94     stores its items in adjacent memory locations and provides fast
  95     index-based access.
  96
  97     QList\<T\>, QLinkedList\<T\>, and QVarLengthArray\<T\> provide
  98     similar functionality. Here's an overview:
  99
 100     \list
 101     \li For most purposes, QList is the right class to use. Operations
 102        like prepend() and insert() are usually faster than with
 103        QVector because of the way QList stores its items in memory
 104        (see \l{Algorithmic Complexity} for details),
 105        and its index-based API is more convenient than QLinkedList's
 106        iterator-based API. It also expands to less code in your
 107        executable.
 108     \li If you need a real linked list, with guarantees of \l{constant
 109        time} insertions in the middle of the list and iterators to
 110        items rather than indexes, use QLinkedList.
 111     \li If you want the items to occupy adjacent memory positions, or
 112        if your items are larger than a pointer and you want to avoid
 113        the overhead of allocating them on the heap individually at
 114        insertion time, then use QVector.
 115     \li If you want a low-level variable-size array, QVarLengthArray
 116        may be sufficient.
 117     \endlist
 118
 119     Here's an example of a QVector that stores integers and a QVector
 120     that stores QString values:
 121
 122     \snippet doc/src/snippets/code/src_corelib_tools_qvector.cpp 0
 123
 124     QVector stores a vector (or array) of items. Typically, vectors
 125     are created with an initial size. For example, the following code
 126     constructs a QVector with 200 elements:
 127
 128     \snippet doc/src/snippets/code/src_corelib_tools_qvector.cpp 1
 129
 130     The elements are automatically initialized with a
 131     \l{default-constructed value}. If you want to initialize the
 132     vector with a different value, pass that value as the second
 133     argument to the constructor:
 134
 135     \snippet doc/src/snippets/code/src_corelib_tools_qvector.cpp 2
 136
 137     You can also call fill() at any time to fill the vector with a
 138     value.
 139
 140     QVector uses 0-based indexes, just like C++ arrays. To access the
 141     item at a particular index position, you can use operator[](). On
 142     non-const vectors, operator[]() returns a reference to the item
 143     that can be used on the left side of an assignment:
 144
 145     \snippet doc/src/snippets/code/src_corelib_tools_qvector.cpp 3
 146
 147     For read-only access, an alternative syntax is to use at():
 148
 149     \snippet doc/src/snippets/code/src_corelib_tools_qvector.cpp 4
 150
 151     at() can be faster than operator[](), because it never causes a
 152     \l{deep copy} to occur.
 153
 154     Another way to access the data stored in a QVector is to call
 155     data(). The function returns a pointer to the first item in the
 156     vector. You can use the pointer to directly access and modify the
 157     elements stored in the vector. The pointer is also useful if you
 158     need to pass a QVector to a function that accepts a plain C++
 159     array.
 160
 161     If you want to find all occurrences of a particular value in a
 162     vector, use indexOf() or lastIndexOf(). The former searches
 163     forward starting from a given index position, the latter searches
 164     backward. Both return the index of the matching item if they found
 165     one; otherwise, they return -1. For example:
 166
 167     \snippet doc/src/snippets/code/src_corelib_tools_qvector.cpp 5
 168
 169     If you simply want to check whether a vector contains a
 170     particular value, use contains(). If you want to find out how
 171     many times a particular value occurs in the vector, use count().
 172
 173     QVector provides these basic functions to add, move, and remove
 174     items: insert(), replace(), remove(), prepend(), append(). With
 175     the exception of append() and replace(), these functions can be slow
 176     (\l{linear time}) for large vectors, because they require moving many
 177     items in the vector by one position in memory. If you want a container
 178     class that provides fast insertion/removal in the middle, use
 179     QList or QLinkedList instead.
 180
 181     Unlike plain C++ arrays, QVectors can be resized at any time by
 182     calling resize(). If the new size is larger than the old size,
 183     QVector might need to reallocate the whole vector. QVector tries
 184     to reduce the number of reallocations by preallocating up to twice
 185     as much memory as the actual data needs.
 186
 187     If you know in advance approximately how many items the QVector
 188     will contain, you can call reserve(), asking QVector to
 189     preallocate a certain amount of memory. You can also call
 190     capacity() to find out how much memory QVector actually
 191     allocated.
 192
 193     Note that using non-const operators and functions can cause
 194     QVector to do a deep copy of the data. This is due to \l{implicit sharing}.
 195
 196     QVector's value type must be an \l{assignable data type}. This
 197     covers most data types that are commonly used, but the compiler
 198     won't let you, for example, store a QWidget as a value; instead,
 199     store a QWidget *. A few functions have additional requirements;
 200     for example, indexOf() and lastIndexOf() expect the value type to
 201     support \c operator==().  These requirements are documented on a
 202     per-function basis.
 203
 204     Like the other container classes, QVector provides \l{Java-style
 205     iterators} (QVectorIterator and QMutableVectorIterator) and
 206     \l{STL-style iterators} (QVector::const_iterator and
 207     QVector::iterator). In practice, these are rarely used, because
 208     you can use indexes into the QVector.
 209
 210     In addition to QVector, Qt also provides QVarLengthArray, a very
 211     low-level class with little functionality that is optimized for
 212     speed.
 213
 214     QVector does \e not support inserting, prepending, appending or replacing
 215     with references to its own values. Doing so will cause your application to
 216     abort with an error message.
 217
 218     \sa QVectorIterator, QMutableVectorIterator, QList, QLinkedList
 219 */
 220
 221 /*!
 222     \fn QVector<T> QVector::mid(int pos, int length = -1) const
 223
 224     Returns a vector whose elements are copied from this vector,
 225     starting at position \a pos. If \a length is -1 (the default), all
 226     elements after \a pos are copied; otherwise \a length elements (or
 227     all remaining elements if there are less than \a length elements)
 228     are copied.
 229 */
 230
 231
 232 /*! \fn QVector::QVector()
 233
 234     Constructs an empty vector.
 235
 236     \sa resize()
 237 */
 238
 239 /*! \fn QVector::QVector(int size)
 240
 241     Constructs a vector with an initial size of \a size elements.
 242
 243     The elements are initialized with a \l{default-constructed
 244     value}.
 245
 246     \sa resize()
 247 */
 248
 249 /*! \fn QVector::QVector(int size, const T &value)
 250
 251     Constructs a vector with an initial size of \a size elements.
 252     Each element is initialized with \a value.
 253
 254     \sa resize(), fill()
 255 */
 256
 257 /*! \fn QVector::QVector(const QVector<T> &other)
 258
 259     Constructs a copy of \a other.
 260
 261     This operation takes \l{constant time}, because QVector is
 262     \l{implicitly shared}. This makes returning a QVector from a
 263     function very fast. If a shared instance is modified, it will be
 264     copied (copy-on-write), and that takes \l{linear time}.
 265
 266     \sa operator=()
 267 */
 268
 269 /*! \fn QVector::QVector(std::initializer_list<T> args)
 270     \since 4.8
 271
 272     Construct a vector from the std::initilizer_list given by \a args.
 273
 274     This constructor is only enabled if the compiler supports C++0x
 275 */
 276
 277
 278 /*! \fn QVector::~QVector()
 279
 280     Destroys the vector.
 281 */
 282
 283 /*! \fn QVector<T> &QVector::operator=(const QVector<T> &other)
 284
 285     Assigns \a other to this vector and returns a reference to this
 286     vector.
 287 */
 288
 289 /*! \fn void QVector::swap(QVector<T> &other)
 290     \since 4.8
 291
 292     Swaps vector \a other with this vector. This operation is very fast and
 293     never fails.
 294 */
 295
 296 /*! \fn bool QVector::operator==(const QVector<T> &other) const
 297
 298     Returns true if \a other is equal to this vector; otherwise
 299     returns false.
 300
 301     Two vectors are considered equal if they contain the same values
 302     in the same order.
 303
 304     This function requires the value type to have an implementation
 305     of \c operator==().
 306
 307     \sa operator!=()
 308 */
 309
 310 /*! \fn bool QVector::operator!=(const QVector<T> &other) const
 311
 312     Returns true if \a other is not equal to this vector; otherwise
 313     returns false.
 314
 315     Two vectors are considered equal if they contain the same values
 316     in the same order.
 317
 318     This function requires the value type to have an implementation
 319     of \c operator==().
 320
 321     \sa operator==()
 322 */
 323
 324 /*! \fn int QVector::size() const
 325
 326     Returns the number of items in the vector.
 327
 328     \sa isEmpty(), resize()
 329 */
 330
 331 /*! \fn bool QVector::isEmpty() const
 332
 333     Returns true if the vector has size 0; otherwise returns false.
 334
 335     \sa size(), resize()
 336 */
 337
 338 /*! \fn void QVector::resize(int size)
 339
 340     Sets the size of the vector to \a size. If \a size is greater than the
 341     current size, elements are added to the end; the new elements are
 342     initialized with a \l{default-constructed value}. If \a size is less
 343     than the current size, elements are removed from the end.
 344
 345     \sa size()
 346 */
 347
 348 /*! \fn int QVector::capacity() const
 349
 350     Returns the maximum number of items that can be stored in the
 351     vector without forcing a reallocation.
 352
 353     The sole purpose of this function is to provide a means of fine
 354     tuning QVector's memory usage. In general, you will rarely ever
 355     need to call this function. If you want to know how many items are
 356     in the vector, call size().
 357
 358     \sa reserve(), squeeze()
 359 */
 360
 361 /*! \fn void QVector::reserve(int size)
 362
 363     Attempts to allocate memory for at least \a size elements. If you
 364     know in advance how large the vector will be, you can call this
 365     function, and if you call resize() often you are likely to get
 366     better performance. If \a size is an underestimate, the worst
 367     that will happen is that the QVector will be a bit slower.
 368
 369     The sole purpose of this function is to provide a means of fine
 370     tuning QVector's memory usage. In general, you will rarely ever
 371     need to call this function. If you want to change the size of the
 372     vector, call resize().
 373
 374     \sa squeeze(), capacity()
 375 */
 376
 377 /*! \fn void QVector::squeeze()
 378
 379     Releases any memory not required to store the items.
 380
 381     The sole purpose of this function is to provide a means of fine
 382     tuning QVector's memory usage. In general, you will rarely ever
 383     need to call this function.
 384
 385     \sa reserve(), capacity()
 386 */
 387
 388 /*! \fn void QVector::detach()
 389
 390     \internal
 391 */
 392
 393 /*! \fn bool QVector::isDetached() const
 394
 395     \internal
 396 */
 397
 398 /*! \fn void QVector::setSharable(bool sharable)
 399
 400     \internal
 401 */
 402
 403 /*! \fn bool QVector::isSharedWith(const QVector<T> &other) const
 404
 405     \internal
 406 */
 407
 408 /*! \fn T *QVector::data()
 409
 410     Returns a pointer to the data stored in the vector. The pointer
 411     can be used to access and modify the items in the vector.
 412
 413     Example:
 414     \snippet doc/src/snippets/code/src_corelib_tools_qvector.cpp 6
 415
 416     The pointer remains valid as long as the vector isn't
 417     reallocated.
 418
 419     This function is mostly useful to pass a vector to a function
 420     that accepts a plain C++ array.
 421
 422     \sa constData(), operator[]()
 423 */
 424
 425 /*! \fn const T *QVector::data() const
 426
 427     \overload
 428 */
 429
 430 /*! \fn const T *QVector::constData() const
 431
 432     Returns a const pointer to the data stored in the vector. The
 433     pointer can be used to access the items in the vector.
 434     The pointer remains valid as long as the vector isn't
 435     reallocated.
 436
 437     This function is mostly useful to pass a vector to a function
 438     that accepts a plain C++ array.
 439
 440     \sa data(), operator[]()
 441 */
 442
 443 /*! \fn void QVector::clear()
 444
 445     Removes all the elements from the vector and releases the memory used by
 446     the vector.
 447 */
 448
 449 /*! \fn const T &QVector::at(int i) const
 450
 451     Returns the item at index position \a i in the vector.
 452
 453     \a i must be a valid index position in the vector (i.e., 0 <= \a
 454     i < size()).
 455
 456     \sa value(), operator[]()
 457 */
 458
 459 /*! \fn T &QVector::operator[](int i)
 460
 461     Returns the item at index position \a i as a modifiable reference.
 462
 463     \a i must be a valid index position in the vector (i.e., 0 <= \a i
 464     < size()).
 465
 466     Note that using non-const operators can cause QVector to do a deep
 467     copy.
 468
 469     \sa at(), value()
 470 */
 471
 472 /*! \fn const T &QVector::operator[](int i) const
 473
 474     \overload
 475
 476     Same as at(\a i).
 477 */
 478
 479 /*!
 480     \fn void QVector::append(const T &value)
 481
 482     Inserts \a value at the end of the vector.
 483
 484     Example:
 485     \snippet doc/src/snippets/code/src_corelib_tools_qvector.cpp 7
 486
 487     This is the same as calling resize(size() + 1) and assigning \a
 488     value to the new last element in the vector.
 489
 490     This operation is relatively fast, because QVector typically
 491     allocates more memory than necessary, so it can grow without
 492     reallocating the entire vector each time.
 493
 494     \sa operator<<(), prepend(), insert()
 495 */
 496
 497 /*! \fn void QVector::prepend(const T &value)
 498
 499     Inserts \a value at the beginning of the vector.
 500
 501     Example:
 502     \snippet doc/src/snippets/code/src_corelib_tools_qvector.cpp 8
 503
 504     This is the same as vector.insert(0, \a value).
 505
 506     For large vectors, this operation can be slow (\l{linear time}),
 507     because it requires moving all the items in the vector by one
 508     position further in memory. If you want a container class that
 509     provides a fast prepend() function, use QList or QLinkedList
 510     instead.
 511
 512     \sa append(), insert()
 513 */
 514
 515 /*! \fn void QVector::insert(int i, const T &value)
 516
 517     Inserts \a value at index position \a i in the vector. If \a i is
 518     0, the value is prepended to the vector. If \a i is size(), the
 519     value is appended to the vector.
 520
 521     Example:
 522     \snippet doc/src/snippets/code/src_corelib_tools_qvector.cpp 9
 523
 524     For large vectors, this operation can be slow (\l{linear time}),
 525     because it requires moving all the items at indexes \a i and
 526     above by one position further in memory. If you want a container
 527     class that provides a fast insert() function, use QLinkedList
 528     instead.
 529
 530     \sa append(), prepend(), remove()
 531 */
 532
 533 /*! \fn void QVector::insert(int i, int count, const T &value)
 534
 535     \overload
 536
 537     Inserts \a count copies of \a value at index position \a i in the
 538     vector.
 539
 540     Example:
 541     \snippet doc/src/snippets/code/src_corelib_tools_qvector.cpp 10
 542 */
 543
 544 /*! \fn QVector::iterator QVector::insert(iterator before, const T &value)
 545
 546     \overload
 547
 548     Inserts \a value in front of the item pointed to by the iterator
 549     \a before. Returns an iterator pointing at the inserted item.
 550 */
 551
 552 /*! \fn QVector::iterator QVector::insert(iterator before, int count, const T &value)
 553
 554     Inserts \a count copies of \a value in front of the item pointed to
 555     by the iterator \a before. Returns an iterator pointing at the
 556     first of the inserted items.
 557 */
 558
 559 /*! \fn void QVector::replace(int i, const T &value)
 560
 561     Replaces the item at index position \a i with \a value.
 562
 563     \a i must be a valid index position in the vector (i.e., 0 <= \a
 564     i < size()).
 565
 566     \sa operator[](), remove()
 567 */
 568
 569 /*! \fn void QVector::remove(int i)
 570
 571     \overload
 572
 573     Removes the element at index position \a i.
 574
 575     \sa insert(), replace(), fill()
 576 */
 577
 578 /*! \fn void QVector::remove(int i, int count)
 579
 580     \overload
 581
 582     Removes \a count elements from the middle of the vector, starting at
 583     index position \a i.
 584
 585     \sa insert(), replace(), fill()
 586 */
 587
 588 /*! \fn QVector &QVector::fill(const T &value, int size = -1)
 589
 590     Assigns \a value to all items in the vector. If \a size is
 591     different from -1 (the default), the vector is resized to size \a
 592     size beforehand.
 593
 594     Example:
 595     \snippet doc/src/snippets/code/src_corelib_tools_qvector.cpp 11
 596
 597     \sa resize()
 598 */
 599
 600 /*! \fn int QVector::indexOf(const T &value, int from = 0) const
 601
 602     Returns the index position of the first occurrence of \a value in
 603     the vector, searching forward from index position \a from.
 604     Returns -1 if no item matched.
 605
 606     Example:
 607     \snippet doc/src/snippets/code/src_corelib_tools_qvector.cpp 12
 608
 609     This function requires the value type to have an implementation of
 610     \c operator==().
 611
 612     \sa lastIndexOf(), contains()
 613 */
 614
 615 /*! \fn int QVector::lastIndexOf(const T &value, int from = -1) const
 616
 617     Returns the index position of the last occurrence of the value \a
 618     value in the vector, searching backward from index position \a
 619     from. If \a from is -1 (the default), the search starts at the
 620     last item. Returns -1 if no item matched.
 621
 622     Example:
 623     \snippet doc/src/snippets/code/src_corelib_tools_qvector.cpp 13
 624
 625     This function requires the value type to have an implementation of
 626     \c operator==().
 627
 628     \sa indexOf()
 629 */
 630
 631 /*! \fn bool QVector::contains(const T &value) const
 632
 633     Returns true if the vector contains an occurrence of \a value;
 634     otherwise returns false.
 635
 636     This function requires the value type to have an implementation of
 637     \c operator==().
 638
 639     \sa indexOf(), count()
 640 */
 641
 642 /*! \fn bool QVector::startsWith(const T &value) const
 643     \since 4.5
 644
 645     Returns true if this vector is not empty and its first
 646     item is equal to \a value; otherwise returns false.
 647
 648     \sa isEmpty(), first()
 649 */
 650
 651 /*! \fn bool QVector::endsWith(const T &value) const
 652     \since 4.5
 653
 654     Returns true if this vector is not empty and its last
 655     item is equal to \a value; otherwise returns false.
 656
 657     \sa isEmpty(), last()
 658 */
 659
 660
 661 /*! \fn int QVector::count(const T &value) const
 662
 663     Returns the number of occurrences of \a value in the vector.
 664
 665     This function requires the value type to have an implementation of
 666     \c operator==().
 667
 668     \sa contains(), indexOf()
 669 */
 670
 671 /*! \fn int QVector::count() const
 672
 673     \overload
 674
 675     Same as size().
 676 */
 677
 678 /*! \fn QVector::iterator QVector::begin()
 679
 680     Returns an \l{STL-style iterator} pointing to the first item in
 681     the vector.
 682
 683     \sa constBegin(), end()
 684 */
 685
 686 /*! \fn QVector::const_iterator QVector::begin() const
 687
 688     \overload
 689 */
 690
 691 /*! \fn QVector::const_iterator QVector::cbegin() const
 692     \since 5.0
 693
 694     Returns a const \l{STL-style iterator} pointing to the first item
 695     in the vector.
 696
 697     \sa begin(), cend()
 698 */
 699
 700 /*! \fn QVector::const_iterator QVector::constBegin() const
 701
 702     Returns a const \l{STL-style iterator} pointing to the first item
 703     in the vector.
 704
 705     \sa begin(), constEnd()
 706 */
 707
 708 /*! \fn QVector::iterator QVector::end()
 709
 710     Returns an \l{STL-style iterator} pointing to the imaginary item
 711     after the last item in the vector.
 712
 713     \sa begin(), constEnd()
 714 */
 715
 716 /*! \fn QVector::const_iterator QVector::end() const
 717
 718     \overload
 719 */
 720
 721 /*! \fn QVector::const_iterator QVector::cend() const
 722     \since 5.0
 723
 724     Returns a const \l{STL-style iterator} pointing to the imaginary
 725     item after the last item in the vector.
 726
 727     \sa cbegin(), end()
 728 */
 729
 730 /*! \fn QVector::const_iterator QVector::constEnd() const
 731
 732     Returns a const \l{STL-style iterator} pointing to the imaginary
 733     item after the last item in the vector.
 734
 735     \sa constBegin(), end()
 736 */
 737
 738 /*! \fn QVector::iterator QVector::erase(iterator pos)
 739
 740     Removes the item pointed to by the iterator \a pos from the
 741     vector, and returns an iterator to the next item in the vector
 742     (which may be end()).
 743
 744     \sa insert(), remove()
 745 */
 746
 747 /*! \fn QVector::iterator QVector::erase(iterator begin, iterator end)
 748
 749     \overload
 750
 751     Removes all the items from \a begin up to (but not including) \a
 752     end. Returns an iterator to the same item that \a end referred to
 753     before the call.
 754 */
 755
 756 /*! \fn T& QVector::first()
 757
 758     Returns a reference to the first item in the vector. This
 759     function assumes that the vector isn't empty.
 760
 761     \sa last(), isEmpty()
 762 */
 763
 764 /*! \fn const T& QVector::first() const
 765
 766     \overload
 767 */
 768
 769 /*! \fn T& QVector::last()
 770
 771     Returns a reference to the last item in the vector. This function
 772     assumes that the vector isn't empty.
 773
 774     \sa first(), isEmpty()
 775 */
 776
 777 /*! \fn const T& QVector::last() const
 778
 779     \overload
 780 */
 781
 782 /*! \fn T QVector::value(int i) const
 783
 784     Returns the value at index position \a i in the vector.
 785
 786     If the index \a i is out of bounds, the function returns
 787     a \l{default-constructed value}. If you are certain that
 788     \a i is within bounds, you can use at() instead, which is slightly
 789     faster.
 790
 791     \sa at(), operator[]()
 792 */
 793
 794 /*! \fn T QVector::value(int i, const T &defaultValue) const
 795
 796     \overload
 797
 798     If the index \a i is out of bounds, the function returns
 799     \a defaultValue.
 800 */
 801
 802 /*! \fn void QVector::push_back(const T &value)
 803
 804     This function is provided for STL compatibility. It is equivalent
 805     to append(\a value).
 806 */
 807
 808 /*! \fn void QVector::push_front(const T &value)
 809
 810     This function is provided for STL compatibility. It is equivalent
 811     to prepend(\a value).
 812 */
 813
 814 /*! \fn void QVector::pop_front()
 815
 816     This function is provided for STL compatibility. It is equivalent
 817     to erase(begin()).
 818 */
 819
 820 /*! \fn void QVector::pop_back()
 821
 822     This function is provided for STL compatibility. It is equivalent
 823     to erase(end() - 1).
 824 */
 825
 826 /*! \fn T& QVector::front()
 827
 828     This function is provided for STL compatibility. It is equivalent
 829     to first().
 830 */
 831
 832 /*! \fn QVector::const_reference QVector::front() const
 833
 834     \overload
 835 */
 836
 837 /*! \fn QVector::reference QVector::back()
 838
 839     This function is provided for STL compatibility. It is equivalent
 840     to last().
 841 */
 842
 843 /*! \fn QVector::const_reference QVector::back() const
 844
 845     \overload
 846 */
 847
 848 /*! \fn bool QVector::empty() const
 849
 850     This function is provided for STL compatibility. It is equivalent
 851     to isEmpty(), returning true if the vector is empty; otherwise
 852     returns false.
 853 */
 854
 855 /*! \fn QVector<T> &QVector::operator+=(const QVector<T> &other)
 856
 857     Appends the items of the \a other vector to this vector and
 858     returns a reference to this vector.
 859
 860     \sa operator+(), append()
 861 */
 862
 863 /*! \fn void QVector::operator+=(const T &value)
 864
 865     \overload
 866
 867     Appends \a value to the vector.
 868
 869     \sa append(), operator<<()
 870 */
 871
 872 /*! \fn QVector<T> QVector::operator+(const QVector<T> &other) const
 873
 874     Returns a vector that contains all the items in this vector
 875     followed by all the items in the \a other vector.
 876
 877     \sa operator+=()
 878 */
 879
 880 /*! \fn QVector<T> &QVector::operator<<(const T &value)
 881
 882     Appends \a value to the vector and returns a reference to this
 883     vector.
 884
 885     \sa append(), operator+=()
 886 */
 887
 888 /*! \fn QVector<T> &QVector::operator<<(const QVector<T> &other)
 889
 890     Appends \a other to the vector and returns a reference to the
 891     vector.
 892 */
 893
 894 /*! \typedef QVector::iterator
 895
 896     The QVector::iterator typedef provides an STL-style non-const
 897     iterator for QVector and QStack.
 898
 899     QVector provides both \l{STL-style iterators} and \l{Java-style
 900     iterators}. The STL-style non-const iterator is simply a typedef
 901     for "T *" (pointer to T).
 902
 903     \sa QVector::begin(), QVector::end(), QVector::const_iterator, QMutableVectorIterator
 904 */
 905
 906 /*! \typedef QVector::const_iterator
 907
 908     The QVector::const_iterator typedef provides an STL-style const
 909     iterator for QVector and QStack.
 910
 911     QVector provides both \l{STL-style iterators} and \l{Java-style
 912     iterators}. The STL-style const iterator is simply a typedef for
 913     "const T *" (pointer to const T).
 914
 915     \sa QVector::constBegin(), QVector::constEnd(), QVector::iterator, QVectorIterator
 916 */
 917
 918 /*! \typedef QVector::Iterator
 919
 920     Qt-style synonym for QVector::iterator.
 921 */
 922
 923 /*! \typedef QVector::ConstIterator
 924
 925     Qt-style synonym for QVector::const_iterator.
 926 */
 927
 928 /*! \typedef QVector::const_pointer
 929
 930     Typedef for const T *. Provided for STL compatibility.
 931 */
 932
 933 /*! \typedef QVector::const_reference
 934
 935     Typedef for T &. Provided for STL compatibility.
 936 */
 937
 938 /*! \typedef QVector::difference_type
 939
 940     Typedef for ptrdiff_t. Provided for STL compatibility.
 941 */
 942
 943 /*! \typedef QVector::pointer
 944
 945     Typedef for T *. Provided for STL compatibility.
 946 */
 947
 948 /*! \typedef QVector::reference
 949
 950     Typedef for T &. Provided for STL compatibility.
 951 */
 952
 953 /*! \typedef QVector::size_type
 954
 955     Typedef for int. Provided for STL compatibility.
 956 */
 957
 958 /*! \typedef QVector::value_type
 959
 960     Typedef for T. Provided for STL compatibility.
 961 */
 962
 963 /*! \fn QList<T> QVector<T>::toList() const
 964
 965     Returns a QList object with the data contained in this QVector.
 966
 967     Example:
 968
 969     \snippet doc/src/snippets/code/src_corelib_tools_qvector.cpp 14
 970
 971     \sa fromList(), QList::fromVector()
 972 */
 973
 974 /*! \fn QVector<T> QVector<T>::fromList(const QList<T> &list)
 975
 976     Returns a QVector object with the data contained in \a list.
 977
 978     Example:
 979
 980     \snippet doc/src/snippets/code/src_corelib_tools_qvector.cpp 15
 981
 982     \sa toList(), QList::toVector()
 983 */
 984
 985 /*! \fn QVector<T> QVector<T>::fromStdVector(const std::vector<T> &vector)
 986
 987     Returns a QVector object with the data contained in \a vector. The
 988     order of the elements in the QVector is the same as in \a vector.
 989
 990     Example:
 991
 992     \snippet doc/src/snippets/code/src_corelib_tools_qvector.cpp 16
 993
 994     \sa toStdVector(), QList::fromStdList()
 995 */
 996
 997 /*! \fn std::vector<T> QVector<T>::toStdVector() const
 998
 999     Returns a std::vector object with the data contained in this QVector.
1000     Example:
1001
1002     \snippet doc/src/snippets/code/src_corelib_tools_qvector.cpp 17
1003
1004     \sa fromStdVector(), QList::toStdList()
1005 */
1006
1007 /*! \fn QDataStream &operator<<(QDataStream &out, const QVector<T> &vector)
1008     \relates QVector
1009
1010     Writes the vector \a vector to stream \a out.
1011
1012     This function requires the value type to implement \c operator<<().
1013
1014     \sa \link datastreamformat.html Format of the QDataStream operators \endlink
1015 */
1016
1017 /*! \fn QDataStream &operator>>(QDataStream &in, QVector<T> &vector)
1018     \relates QVector
1019
1020     Reads a vector from stream \a in into \a vector.
1021
1022     This function requires the value type to implement \c operator>>().
1023
1024     \sa \link datastreamformat.html Format of the QDataStream operators \endlink
1025 */
1026
1027 QT_END_NAMESPACE