src/corelib/tools/qvarlengtharray.qdoc

   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 documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \class QVarLengthArray
  30     \brief The QVarLengthArray class provides a low-level variable-length array.
  31
  32     \ingroup tools
  33     \reentrant
  34
  35     The C++ language doesn't support variable-length arrays on the stack.
  36     For example, the following code won't compile:
  37
  38     \snippet doc/src/snippets/code/doc_src_qvarlengtharray.cpp 0
  39
  40     The alternative is to allocate the array on the heap (with
  41     \c{new}):
  42
  43     \snippet doc/src/snippets/code/doc_src_qvarlengtharray.cpp 1
  44
  45     However, if myfunc() is called very frequently from the
  46     application's inner loop, heap allocation can be a major source
  47     of slowdown.
  48
  49     QVarLengthArray is an attempt to work around this gap in the C++
  50     language. It allocates a certain number of elements on the stack,
  51     and if you resize the array to a larger size, it automatically
  52     uses the heap instead. Stack allocation has the advantage that
  53     it is much faster than heap allocation.
  54
  55     Example:
  56     \snippet doc/src/snippets/code/doc_src_qvarlengtharray.cpp 2
  57
  58     In the example above, QVarLengthArray will preallocate 1024
  59     elements on the stack and use them unless \c{n + 1} is greater
  60     than 1024. If you omit the second template argument,
  61     QVarLengthArray's default of 256 is used.
  62
  63     QVarLengthArray's value type must be an \l{assignable data type}.
  64     This covers most data types that are commonly used, but the
  65     compiler won't let you, for example, store a QWidget as a value;
  66     instead, store a QWidget *.
  67
  68     QVarLengthArray, like QVector, provides a resizable array data
  69     structure. The main differences between the two classes are:
  70
  71     \list
  72     \li QVarLengthArray's API is much more low-level. It provides no
  73        iterators and lacks much of QVector's functionality.
  74
  75     \li QVarLengthArray doesn't initialize the memory if the value is
  76        a basic type. (QVector always does.)
  77
  78     \li QVector uses \l{implicit sharing} as a memory optimization.
  79        QVarLengthArray doesn't provide that feature; however, it
  80        usually produces slightly better performance due to reduced
  81        overhead, especially in tight loops.
  82     \endlist
  83
  84     In summary, QVarLengthArray is a low-level optimization class
  85     that only makes sense in very specific cases. It is used a few
  86     places inside Qt and was added to Qt's public API for the
  87     convenience of advanced users.
  88
  89     \sa QVector, QList, QLinkedList
  90 */
  91
  92 /*! \fn QVarLengthArray::QVarLengthArray(int size)
  93
  94     Constructs an array with an initial size of \a size elements.
  95
  96     If the value type is a primitive type (e.g., char, int, float) or
  97     a pointer type (e.g., QWidget *), the elements are not
  98     initialized. For other types, the elements are initialized with a
  99     \l{default-constructed value}.
 100 */
 101
 102 /*! \fn QVarLengthArray::~QVarLengthArray()
 103
 104     Destroys the array.
 105 */
 106
 107 /*! \fn int QVarLengthArray::size() const
 108
 109     Returns the number of elements in the array.
 110
 111     \sa isEmpty(), resize()
 112 */
 113
 114 /*! \fn int QVarLengthArray::count() const
 115
 116     Same as size().
 117
 118     \sa isEmpty(), resize()
 119 */
 120
 121 /*! \fn int QVarLengthArray::length() const
 122
 123     Same as size().
 124
 125     \sa isEmpty(), resize()
 126 */
 127
 128 /*! \fn T& QVarLengthArray::first()
 129
 130     Returns a reference to the first item in the array. The array must
 131     not be empty. If the array can be empty, check isEmpty() before
 132     calling this function.
 133
 134     \sa last(), isEmpty()
 135 */
 136
 137 /*! \fn const T& QVarLengthArray::first() const
 138
 139     \overload
 140 */
 141
 142 /*! \fn T& QVarLengthArray::last()
 143
 144     Returns a reference to the last item in the array.  The array must
 145     not be empty. If the array can be empty, check isEmpty() before
 146     calling this function.
 147
 148     \sa first(), isEmpty()
 149 */
 150
 151 /*! \fn const T& QVarLengthArray::last() const
 152
 153     \overload
 154 */
 155
 156
 157
 158 /*! \fn bool QVarLengthArray::isEmpty() const
 159
 160     Returns true if the array has size 0; otherwise returns false.
 161
 162     \sa size(), resize()
 163 */
 164
 165 /*! \fn void QVarLengthArray::clear()
 166
 167     Removes all the elements from the array.
 168
 169     Same as resize(0).
 170 */
 171
 172 /*! \fn void QVarLengthArray::resize(int size)
 173
 174     Sets the size of the array to \a size. If \a size is greater than
 175     the current size, elements are added to the end. If \a size is
 176     less than the current size, elements are removed from the end.
 177
 178     If the value type is a primitive type (e.g., char, int, float) or
 179     a pointer type (e.g., QWidget *), new elements are not
 180     initialized. For other types, the elements are initialized with a
 181     \l{default-constructed value}.
 182
 183     \sa size()
 184 */
 185
 186 /*! \fn int QVarLengthArray::capacity() const
 187
 188     Returns the maximum number of elements that can be stored in the
 189     array without forcing a reallocation.
 190
 191     The sole purpose of this function is to provide a means of fine
 192     tuning QVarLengthArray's memory usage. In general, you will rarely ever
 193     need to call this function. If you want to know how many items are
 194     in the array, call size().
 195
 196     \sa reserve()
 197 */
 198
 199 /*! \fn void QVarLengthArray::reserve(int size)
 200
 201     Attempts to allocate memory for at least \a size elements. If you
 202     know in advance how large the array can get, you can call this
 203     function and if you call resize() often, you are likely to get
 204     better performance. If \a size is an underestimate, the worst
 205     that will happen is that the QVarLengthArray will be a bit
 206     slower.
 207
 208     The sole purpose of this function is to provide a means of fine
 209     tuning QVarLengthArray's memory usage. In general, you will
 210     rarely ever need to call this function. If you want to change the
 211     size of the array, call resize().
 212
 213     \sa capacity()
 214 */
 215
 216 /*! \fn T &QVarLengthArray::operator[](int i)
 217
 218     Returns a reference to the item at index position \a i.
 219
 220     \a i must be a valid index position in the array (i.e., 0 <= \a i
 221     < size()).
 222
 223     \sa data(), at()
 224 */
 225
 226 /*! \fn const T &QVarLengthArray::operator[](int i) const
 227
 228     \overload
 229 */
 230
 231
 232 /*!
 233     \fn void QVarLengthArray::append(const T &t)
 234
 235     Appends item \a t to the array, extending the array if necessary.
 236
 237     \sa removeLast()
 238 */
 239
 240
 241 /*!
 242     \fn inline void QVarLengthArray::removeLast()
 243     \since 4.5
 244
 245     Decreases the size of the array by one.  The allocated size is not changed.
 246
 247     \sa append()
 248 */
 249
 250 /*!
 251     \fn void QVarLengthArray::append(const T *buf, int size)
 252
 253     Appends \a size amount of items referenced by \a buf to this array.
 254 */
 255
 256
 257 /*! \fn T *QVarLengthArray::data()
 258
 259     Returns a pointer to the data stored in the array. The pointer can
 260     be used to access and modify the items in the array.
 261
 262     Example:
 263     \snippet doc/src/snippets/code/doc_src_qvarlengtharray.cpp 3
 264
 265     The pointer remains valid as long as the array isn't reallocated.
 266
 267     This function is mostly useful to pass an array to a function
 268     that accepts a plain C++ array.
 269
 270     \sa constData(), operator[]()
 271 */
 272
 273 /*! \fn const T *QVarLengthArray::data() const
 274
 275     \overload
 276 */
 277
 278 /*! \fn const T *QVarLengthArray::constData() const
 279
 280     Returns a const pointer to the data stored in the array. The
 281     pointer can be used to access the items in the array. The
 282     pointer remains valid as long as the array isn't reallocated.
 283
 284     This function is mostly useful to pass an array to a function
 285     that accepts a plain C++ array.
 286
 287     \sa data(), operator[]()
 288 */
 289
 290 /*! \fn QVarLengthArray<T, Prealloc> &QVarLengthArray::operator=(const QVarLengthArray<T, Prealloc> &other)
 291     Assigns \a other to this array and returns a reference to this array.
 292  */
 293
 294 /*! \fn QVarLengthArray::QVarLengthArray(const QVarLengthArray<T, Prealloc> &other)
 295     Constructs a copy of \a other.
 296  */
 297
 298 /*! \fn const T &QVarLengthArray::at(int i) const
 299
 300     Returns a reference to the item at index position \a i.
 301
 302     \a i must be a valid index position in the array (i.e., 0 <= \a i
 303     < size()).
 304
 305     \sa value(), operator[]()
 306 */
 307
 308 /*! \fn T QVarLengthArray::value(int i) const
 309
 310     Returns the value at index position \a i.
 311
 312     If the index \a i is out of bounds, the function returns
 313     a \l{default-constructed value}. If you are certain that
 314     \a i is within bounds, you can use at() instead, which is slightly
 315     faster.
 316
 317     \sa at(), operator[]()
 318 */
 319
 320 /*! \fn T QVarLengthArray::value(int i, const T &defaultValue) const
 321
 322     \overload
 323
 324     If the index \a i is out of bounds, the function returns
 325     \a defaultValue.
 326 */
 327
 328 /*!
 329     \typedef QVarLengthArray::size_type
 330     \since 4.7
 331
 332     Typedef for int. Provided for STL compatibility.
 333 */
 334
 335 /*!
 336     \typedef QVarLengthArray::value_type
 337     \since 4.7
 338
 339     Typedef for T. Provided for STL compatibility.
 340 */
 341
 342 /*!
 343     \typedef QVarLengthArray::difference_type
 344     \since 4.7
 345
 346     Typedef for ptrdiff_t. Provided for STL compatibility.
 347 */
 348
 349 /*!
 350     \typedef QVarLengthArray::pointer
 351     \since 4.7
 352
 353     Typedef for T *. Provided for STL compatibility.
 354 */
 355
 356 /*!
 357     \typedef QVarLengthArray::const_pointer
 358     \since 4.7
 359
 360     Typedef for const T *. Provided for STL compatibility.
 361 */
 362
 363 /*!
 364     \typedef QVarLengthArray::reference
 365     \since 4.7
 366
 367     Typedef for T &. Provided for STL compatibility.
 368 */
 369
 370 /*!
 371     \typedef QVarLengthArray::const_reference
 372     \since 4.7
 373
 374     Typedef for const T &. Provided for STL compatibility.
 375 */
 376
 377 /*!
 378     \typedef QVarLengthArray::const_iterator
 379     \since 4.7
 380
 381     Typedef for const T *. Provided for STL compatibility.
 382 */
 383
 384 /*!
 385     \typedef QVarLengthArray::iterator
 386     \since 4.7
 387
 388     Typedef for T *. Provided for STL compatibility.
 389 */
 390
 391 /*! \fn void QVarLengthArray::prepend(const T &value)
 392
 393     \since 4.8
 394     Inserts \a value at the beginning of the array.
 395
 396
 397     This is the same as vector.insert(0, \a value).
 398
 399     For large arrays, this operation can be slow (\l{linear time}),
 400     because it requires moving all the items in the vector by one
 401     position further in memory. If you want a container class that
 402     provides a fast prepend() function, use QList or QLinkedList
 403     instead.
 404
 405     \sa append(), insert()
 406 */
 407
 408 /*! \fn void QVarLengthArray::replace(int i, const T &value)
 409
 410     \since 4.8
 411     Replaces the item at index position \a i with \a value.
 412
 413     \a i must be a valid index position in the array (i.e., 0 <= \a
 414     i < size()).
 415
 416     \sa operator[](), remove()
 417 */
 418
 419 /*! \fn void QVarLengthArray::remove(int i)
 420
 421     \overload
 422     \since 4.8
 423
 424     Removes the element at index position \a i.
 425
 426     \sa insert(), replace()
 427 */
 428
 429 /*! \fn void QVarLengthArray::remove(int i, int count)
 430
 431     \overload
 432     \since 4.8
 433
 434     Removes \a count elements from the middle of the array, starting at
 435     index position \a i.
 436
 437     \sa insert(), replace()
 438 */
 439
 440 /*! \fn QVarLengthArray::iterator QVarLengthArray::begin()
 441     \since 4.8
 442
 443     Returns an \l{STL-style iterator} pointing to the first item in
 444     the array.
 445
 446     \sa constBegin(), end()
 447 */
 448
 449 /*! \fn QVarLengthArray::const_iterator QVarLengthArray::begin() const
 450     \since 4.8
 451     \overload
 452 */
 453
 454 /*! \fn QVarLengthArray::const_iterator QVarLengthArray::cbegin() const
 455     \since 5.0
 456
 457     Returns a const \l{STL-style iterator} pointing to the first item
 458     in the array.
 459
 460     \sa begin(), cend()
 461 */
 462
 463 /*! \fn QVarLengthArray::const_iterator QVarLengthArray::constBegin() const
 464     \since 4.8
 465
 466     Returns a const \l{STL-style iterator} pointing to the first item
 467     in the array.
 468
 469     \sa begin(), constEnd()
 470 */
 471
 472 /*! \fn QVarLengthArray::iterator QVarLengthArray::end()
 473     \since 4.8
 474
 475     Returns an \l{STL-style iterator} pointing to the imaginary item
 476     after the last item in the array.
 477
 478     \sa begin(), constEnd()
 479 */
 480
 481 /*! \fn QVarLengthArray::const_iterator QVarLengthArray::end() const
 482     \since 4.8
 483
 484     \overload
 485 */
 486
 487 /*! \fn QVarLengthArray::const_iterator QVarLengthArray::cend() const
 488     \since 5.0
 489
 490     Returns a const \l{STL-style iterator} pointing to the imaginary
 491     item after the last item in the array.
 492
 493     \sa cbegin(), end()
 494 */
 495
 496 /*! \fn QVarLengthArray::const_iterator QVarLengthArray::constEnd() const
 497     \since 4.8
 498
 499     Returns a const \l{STL-style iterator} pointing to the imaginary
 500     item after the last item in the array.
 501
 502     \sa constBegin(), end()
 503 */
 504
 505 /*! \fn QVarLengthArray::iterator QVarLengthArray::erase(iterator pos)
 506     \since 4.8
 507
 508     Removes the item pointed to by the iterator \a pos from the
 509     vector, and returns an iterator to the next item in the vector
 510     (which may be end()).
 511
 512     \sa insert(), remove()
 513 */
 514
 515 /*! \fn QVarLengthArray::iterator QVarLengthArray::erase(iterator begin, iterator end)
 516
 517     \overload
 518     \since 4.8
 519
 520     Removes all the items from \a begin up to (but not including) \a
 521     end. Returns an iterator to the same item that \a end referred to
 522     before the call.
 523 */
 524
 525 /*! \fn void QVarLengthArray::insert(int i, const T &value)
 526     \since 4.8
 527
 528     Inserts \a value at index position \a i in the array. If \a i is
 529     0, the value is prepended to the vector. If \a i is size(), the
 530     value is appended to the vector.
 531
 532     For large arrays, this operation can be slow (\l{linear time}),
 533     because it requires moving all the items at indexes \a i and
 534     above by one position further in memory. If you want a container
 535     class that provides a fast insert() function, use QLinkedList
 536     instead.
 537
 538     \sa remove()
 539 */
 540
 541 /*! \fn void QVarLengthArray::insert(int i, int count, const T &value)
 542
 543     \overload
 544     \since 4.8
 545
 546     Inserts \a count copies of \a value at index position \a i in the
 547     vector.
 548 */
 549
 550 /*! \fn QVarLengthArray::iterator QVarLengthArray::insert(iterator before, const T &value)
 551
 552     \overload
 553     \since 4.8
 554
 555     Inserts \a value in front of the item pointed to by the iterator
 556     \a before. Returns an iterator pointing at the inserted item.
 557 */
 558
 559 /*! \fn QVarLengthArray::iterator QVarLengthArray::insert(iterator before, int count, const T &value)
 560
 561     \since 4.8
 562     Inserts \a count copies of \a value in front of the item pointed to
 563     by the iterator \a before. Returns an iterator pointing at the
 564     first of the inserted items.
 565 */
 566
 567
 568
 569 /*! \fn bool operator==(const QVarLengthArray<T, Prealloc1> &left, const QVarLengthArray<T, Prealloc2> &right)
 570
 571     \relates QVarLengthArray
 572     \since 4.8
 573     Returns true if the two arrays, specified by \a left and \a right, are equal.
 574
 575     Two arrays are considered equal if they contain the same values
 576     in the same order.
 577
 578     This function requires the value type to have an implementation
 579     of \c operator==().
 580
 581     \sa operator!=()
 582 */
 583
 584 /*! \fn bool operator!=(const QVarLengthArray<T, Prealloc1> &left, const QVarLengthArray<T, Prealloc2> &right)
 585
 586     \relates QVarLengthArray
 587     \since 4.8
 588     Returns true if the two arrays, specified by \a left and \a right, are \e not equal.
 589
 590     Two arrays are considered equal if they contain the same values
 591     in the same order.
 592
 593     This function requires the value type to have an implementation
 594     of \c operator==().
 595
 596     \sa operator==()
 597 */
 598
 599 /*! \fn QVarLengthArray &QVarLengthArray::operator<<(const T &value)
 600
 601     \since 4.8
 602     Appends \a value to the array and returns a reference to this
 603     vector.
 604
 605     \sa append(), operator+=()
 606 */
 607
 608 /*! \fn QVarLengthArray &QVarLengthArray::operator+=(const T &value)
 609
 610     \since 4.8
 611     Appends \a value to the array and returns a reference to this
 612     vector.
 613
 614     \sa append(), operator<<()
 615 */
 616