1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
7 \brief The QVarLengthArray class provides a low-level variable-length array.
12 The C++ language doesn't support variable-length arrays on the stack.
13 For example, the following code won't compile:
15 \snippet code/doc_src_qvarlengtharray.cpp 0
17 The alternative is to allocate the array on the heap (with
20 \snippet code/doc_src_qvarlengtharray.cpp 1
22 However, if myfunc() is called very frequently from the
23 application's inner loop, heap allocation can be a major source
26 QVarLengthArray is an attempt to work around this gap in the C++
27 language. It allocates a certain number of elements on the stack,
28 and if you resize the array to a larger size, it automatically
29 uses the heap instead. Stack allocation has the advantage that
30 it is much faster than heap allocation.
33 \snippet code/doc_src_qvarlengtharray.cpp 2
35 In the example above, QVarLengthArray will preallocate 1024
36 elements on the stack and use them unless \c{n + 1} is greater
37 than 1024. If you omit the second template argument,
38 QVarLengthArray's default of 256 is used.
40 QVarLengthArray's value type must be an \l{assignable data type}.
41 This covers most data types that are commonly used, but the
42 compiler won't let you, for example, store a QWidget as a value;
43 instead, store a QWidget *.
45 QVarLengthArray, like QList, provides a resizable array data
46 structure. The main differences between the two classes are:
49 \li QVarLengthArray's API is much more low-level and it lacks
50 some of QList's functionality.
52 \li QVarLengthArray doesn't initialize the memory if the value is
53 a basic type. (QList always does.)
55 \li QList uses \l{implicit sharing} as a memory optimization.
56 QVarLengthArray doesn't provide that feature; however, it
57 usually produces slightly better performance due to reduced
58 overhead, especially in tight loops.
61 In summary, QVarLengthArray is a low-level optimization class
62 that only makes sense in very specific cases. It is used a few
63 places inside Qt and was added to Qt's public API for the
64 convenience of advanced users.
69/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::QVarLengthArray()
71 Constructs an array with an initial size of zero.
74/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::QVarLengthArray(qsizetype size)
76 Constructs an array with an initial size of \a size elements.
78 If the value type is a primitive type (e.g., char, int, float) or
79 a pointer type (e.g., QWidget *), the elements are not
80 initialized. For other types, the elements are initialized with a
81 \l{default-constructed value}.
85 \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::QVarLengthArray(qsizetype size, const T &v)
88 Constructs an array with an initial size of \a size elements filled with
91 \note This constructor is only available when \c T is copy-constructible.
97/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::QVarLengthArray(std::initializer_list<T> args)
100 Constructs an array from the std::initializer_list given by \a args.
103/*! \fn template<class T, qsizetype Prealloc> template<typename InputIterator, QVarLengthArray<T, Prealloc>::if_input_iterator<InputIterator>> QVarLengthArray<T, Prealloc>::QVarLengthArray(InputIterator first, InputIterator last)
106 Constructs an array with the contents in the iterator range [\a first, \a last).
108 This constructor only participates in overload resolution if
109 \c InputIterator meets the requirements of an
110 \l {https://en.cppreference.com/w/cpp/named_req/InputIterator} {LegacyInputIterator}.
112 The value type of \c InputIterator must be convertible to \c T.
116/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::~QVarLengthArray()
121/*! \fn template<class T, qsizetype Prealloc> qsizetype QVarLengthArray<T, Prealloc>::size() const
123 Returns the number of elements in the array.
125 \sa isEmpty(), resize()
128/*! \fn template<class T, qsizetype Prealloc> qsizetype QVarLengthArray<T, Prealloc>::count() const
132 \sa isEmpty(), resize()
135/*! \fn template<class T, qsizetype Prealloc> qsizetype QVarLengthArray<T, Prealloc>::length() const
140 \sa isEmpty(), resize()
143/*! \fn template<class T, qsizetype Prealloc> qsizetype QVarLengthArray<T, Prealloc>::max_size()
146 This function is provided for STL compatibility.
147 It returns the maximum number of elements that the array can
148 theoretically hold. In practice, the number can be much smaller,
149 limited by the amount of memory available to the system.
152/*! \fn template<class T, qsizetype Prealloc> T& QVarLengthArray<T, Prealloc>::first()
154 Returns a reference to the first item in the array. The array must
155 not be empty. If the array can be empty, check isEmpty() before
156 calling this function.
158 \sa last(), isEmpty()
161/*! \fn template<class T, qsizetype Prealloc> const T& QVarLengthArray<T, Prealloc>::first() const
166/*! \fn template<class T, qsizetype Prealloc> T& QVarLengthArray<T, Prealloc>::front()
169 Same as first(). Provided for STL-compatibility.
172/*! \fn template<class T, qsizetype Prealloc> const T& QVarLengthArray<T, Prealloc>::front() const
178/*! \fn template<class T, qsizetype Prealloc> T& QVarLengthArray<T, Prealloc>::last()
180 Returns a reference to the last item in the array. The array must
181 not be empty. If the array can be empty, check isEmpty() before
182 calling this function.
184 \sa first(), isEmpty()
187/*! \fn template<class T, qsizetype Prealloc> const T& QVarLengthArray<T, Prealloc>::last() const
192/*! \fn template<class T, qsizetype Prealloc> T& QVarLengthArray<T, Prealloc>::back()
195 Same as last(). Provided for STL-compatibility.
198/*! \fn template<class T, qsizetype Prealloc> const T& QVarLengthArray<T, Prealloc>::back() const
204/*! \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::shrink_to_fit()
207 Same as squeeze(). Provided for STL-compatibility.
210/*! \fn template<class T, qsizetype Prealloc> bool QVarLengthArray<T, Prealloc>::isEmpty() const
212 Returns \c true if the array has size 0; otherwise returns \c false.
217/*! \fn template<class T, qsizetype Prealloc> bool QVarLengthArray<T, Prealloc>::empty() const
220 Returns \c true if the array has size 0; otherwise returns \c false.
222 Same as isEmpty(). Provided for STL-compatibility.
225/*! \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::clear()
227 Removes all the elements from the array.
232/*! \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::resize(qsizetype size)
234 Sets the size of the array to \a size. If \a size is greater than
235 the current size, elements are added to the end. If \a size is
236 less than the current size, elements are removed from the end.
238 If the value type is a primitive type (e.g., char, int, float) or
239 a pointer type (e.g., QWidget *), new elements are not
240 initialized. For other types, the elements are initialized with a
241 \l{default-constructed value}.
243 \sa size(), squeeze()
247 \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::resize(qsizetype size, const T &v)
250 Sets the size of the array to \a size. If \a size is greater than
251 the current size, copies of \a v are added to the end. If \a size is
252 less than the current size, elements are removed from the end.
254 \note This function is only available when \c T is copy-constructible.
256 \sa size(), squeeze()
259/*! \fn template<class T, qsizetype Prealloc> qsizetype QVarLengthArray<T, Prealloc>::capacity() const
261 Returns the maximum number of elements that can be stored in the
262 array without forcing a reallocation.
264 The sole purpose of this function is to provide a means of fine
265 tuning QVarLengthArray's memory usage. In general, you will rarely ever
266 need to call this function. If you want to know how many items are
267 in the array, call size().
269 \sa reserve(), squeeze()
272/*! \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::reserve(qsizetype size)
274 Attempts to allocate memory for at least \a size elements. If you
275 know in advance how large the array can get, you can call this
276 function and if you call resize() often, you are likely to get
277 better performance. If \a size is an underestimate, the worst
278 that will happen is that the QVarLengthArray will be a bit
281 The sole purpose of this function is to provide a means of fine
282 tuning QVarLengthArray's memory usage. In general, you will
283 rarely ever need to call this function. If you want to change the
284 size of the array, call resize().
286 \sa capacity(), squeeze()
289/*! \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::squeeze()
292 Releases any memory not required to store the items.
293 If the container can fit its storage on the stack allocation,
294 it will free the heap allocation and copy the elements back to the stack.
296 The sole purpose of this function is to provide a means of fine
297 tuning QVarLengthArray's memory usage. In general, you will rarely ever
298 need to call this function.
300 \sa reserve(), capacity(), resize()
303/*! \fn template<class T, qsizetype Prealloc> T &QVarLengthArray<T, Prealloc>::operator[](qsizetype i)
305 Returns a reference to the item at index position \a i.
307 \a i must be a valid index position in the array (i.e., 0 <= \a i
313/*! \fn template<class T, qsizetype Prealloc> const T &QVarLengthArray<T, Prealloc>::operator[](qsizetype i) const
320 \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::append(const T &t)
322 Appends item \a t to the array, extending the array if necessary.
328 \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::push_back(const T &t)
331 Appends item \a t to the array, extending the array if necessary.
332 Provided for STL-compatibility.
336 \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::append(T &&t)
340 \note Unlike the lvalue overload of append(), passing a reference to
341 an object that is already an element of \c *this leads to undefined
345 vla.append(std::move(vla[0])); // BUG: passing an object that is already in the container
350 \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::push_back(T &&t)
354 \note Unlike the lvalue overload of push_back(), passing a reference to
355 an object that is already an element of \c *this leads to undefined
359 vla.push_back(std::move(vla[0])); // BUG: passing an object that is already in the container
364 \fn template<class T, qsizetype Prealloc> inline void QVarLengthArray<T, Prealloc>::removeLast()
367 Decreases the size of the array by one. The allocated size is not changed.
373 \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::pop_back()
376 Same as removeLast(). Provided for STL-compatibility.
380 \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::append(const T *buf, qsizetype size)
382 Appends \a size amount of items referenced by \a buf to this array.
386/*! \fn template<class T, qsizetype Prealloc> T *QVarLengthArray<T, Prealloc>::data()
388 Returns a pointer to the data stored in the array. The pointer can
389 be used to access and modify the items in the array.
392 \snippet code/doc_src_qvarlengtharray.cpp 3
394 The pointer remains valid as long as the array isn't reallocated.
396 This function is mostly useful to pass an array to a function
397 that accepts a plain C++ array.
399 \sa constData(), operator[]()
402/*! \fn template<class T, qsizetype Prealloc> const T *QVarLengthArray<T, Prealloc>::data() const
407/*! \fn template<class T, qsizetype Prealloc> const T *QVarLengthArray<T, Prealloc>::constData() const
409 Returns a const pointer to the data stored in the array. The
410 pointer can be used to access the items in the array. The
411 pointer remains valid as long as the array isn't reallocated.
413 This function is mostly useful to pass an array to a function
414 that accepts a plain C++ array.
416 \sa data(), operator[]()
419/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc> &QVarLengthArray<T, Prealloc>::operator=(const QVarLengthArray<T, Prealloc> &other)
420 Assigns \a other to this array and returns a reference to this array.
423/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc> &QVarLengthArray<T, Prealloc>::operator=(QVarLengthArray<T, Prealloc> &&other)
424 Move-assigns \a other to this array and returns a reference to this array.
425 After the move, \a other is empty.
429/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc> &QVarLengthArray<T, Prealloc>::operator=(std::initializer_list<T> list)
432 Assigns the values of \a list to this array, and returns a reference to this array.
435/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::QVarLengthArray(const QVarLengthArray<T, Prealloc> &other)
436 Constructs a copy of \a other.
439/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::QVarLengthArray(QVarLengthArray<T, Prealloc> &&other)
440 Move-constructs this variable-length array from \a other. After the move, \a other is empty.
444/*! \fn template<class T, qsizetype Prealloc> const T &QVarLengthArray<T, Prealloc>::at(qsizetype i) const
446 Returns a reference to the item at index position \a i.
448 \a i must be a valid index position in the array (i.e., 0 <= \a i
451 \sa value(), operator[]()
454/*! \fn template<class T, qsizetype Prealloc> T QVarLengthArray<T, Prealloc>::value(qsizetype i) const
456 Returns the value at index position \a i.
458 If the index \a i is out of bounds, the function returns
459 a \l{default-constructed value}. If you are certain that
460 \a i is within bounds, you can use at() instead, which is slightly
463 \sa at(), operator[]()
466/*! \fn template<class T, qsizetype Prealloc> T QVarLengthArray<T, Prealloc>::value(qsizetype i, const T &defaultValue) const
470 If the index \a i is out of bounds, the function returns
475 \var QVarLengthArray::PreallocatedSize
478 The same value as the \c{Prealloc} template argument. Provided for easier
479 access compared to manually extracting the value from the template
484 \typedef QVarLengthArray::size_type
487 Typedef for int. Provided for STL compatibility.
491 \typedef QVarLengthArray::value_type
494 Typedef for T. Provided for STL compatibility.
498 \typedef QVarLengthArray::difference_type
501 Typedef for ptrdiff_t. Provided for STL compatibility.
505 \typedef QVarLengthArray::pointer
508 Typedef for T *. Provided for STL compatibility.
512 \typedef QVarLengthArray::const_pointer
515 Typedef for const T *. Provided for STL compatibility.
519 \typedef QVarLengthArray::reference
522 Typedef for T &. Provided for STL compatibility.
526 \typedef QVarLengthArray::const_reference
529 Typedef for const T &. Provided for STL compatibility.
533 \typedef QVarLengthArray::const_iterator
536 Typedef for const T *. Provided for STL compatibility.
540 \typedef QVarLengthArray::iterator
543 Typedef for T *. Provided for STL compatibility.
547 \typedef QVarLengthArray::const_reverse_iterator
550 Typedef for \c{std::reverse_iterator<const T*>}. Provided for STL compatibility.
554 \typedef QVarLengthArray::reverse_iterator
557 Typedef for \c{std::reverse_iterator<T*>}. Provided for STL compatibility.
561 \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::prepend(const T &value)
562 \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::prepend(T &&value)
565 \deprecated [6.3] This is slow. If you must, use \c{insert(cbegin(), ~~~)} instead.
567 Inserts \a value at the beginning of the array.
570 This is the same as vector.insert(0, \a value).
572 For large arrays, this operation can be slow (\l{linear time}),
573 because it requires moving all the items in the vector by one
574 position further in memory. If you want a container class that
575 provides a fast prepend() function, use std::list instead.
577 \sa append(), insert()
580/*! \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::replace(qsizetype i, const T &value)
583 Replaces the item at index position \a i with \a value.
585 \a i must be a valid index position in the array (i.e., 0 <= \a
588 \sa operator[](), remove()
591/*! \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::remove(qsizetype i, qsizetype count)
596 Removes \a count elements from the middle of the array, starting at
599 \sa insert(), replace()
602/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::iterator QVarLengthArray<T, Prealloc>::begin()
605 Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first item in
608 \sa constBegin(), end()
611/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::const_iterator QVarLengthArray<T, Prealloc>::begin() const
616/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::const_iterator QVarLengthArray<T, Prealloc>::cbegin() const
619 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item
625/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::const_iterator QVarLengthArray<T, Prealloc>::constBegin() const
628 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item
631 \sa begin(), constEnd()
634/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::iterator QVarLengthArray<T, Prealloc>::end()
637 Returns an \l{STL-style iterators}{STL-style iterator} pointing to the imaginary item
638 after the last item in the array.
640 \sa begin(), constEnd()
643/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::const_iterator QVarLengthArray<T, Prealloc>::end() const
649/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::const_iterator QVarLengthArray<T, Prealloc>::cend() const
652 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
653 item after the last item in the array.
658/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::const_iterator QVarLengthArray<T, Prealloc>::constEnd() const
661 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
662 item after the last item in the array.
664 \sa constBegin(), end()
667/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::reverse_iterator QVarLengthArray<T, Prealloc>::rbegin()
670 Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to the first
671 item in the variable length array, in reverse order.
673 \sa begin(), crbegin(), rend()
676/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::const_reverse_iterator QVarLengthArray<T, Prealloc>::rbegin() const
681/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::const_reverse_iterator QVarLengthArray<T, Prealloc>::crbegin() const
684 Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing to the first
685 item in the variable length array, in reverse order.
687 \sa begin(), rbegin(), rend()
690/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::reverse_iterator QVarLengthArray<T, Prealloc>::rend()
693 Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to one past
694 the last item in the variable length array, in reverse order.
696 \sa end(), crend(), rbegin()
699/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::const_reverse_iterator QVarLengthArray<T, Prealloc>::rend() const
704/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::const_reverse_iterator QVarLengthArray<T, Prealloc>::crend() const
707 Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing to one
708 past the last item in the variable length array, in reverse order.
710 \sa end(), rend(), rbegin()
713/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::iterator QVarLengthArray<T, Prealloc>::erase(const_iterator pos)
716 Removes the item pointed to by the iterator \a pos from the
717 vector, and returns an iterator to the next item in the vector
718 (which may be end()).
720 \sa insert(), remove()
723/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::iterator QVarLengthArray<T, Prealloc>::erase(const_iterator begin, const_iterator end)
728 Removes all the items from \a begin up to (but not including) \a
729 end. Returns an iterator to the same item that \a end referred to
734 \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::insert(qsizetype i, const T &value)
735 \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::insert(qsizetype i, T &&value)
738 Inserts \a value at index position \a i in the array. If \a i is
739 0, the value is prepended to the vector. If \a i is size(), the
740 value is appended to the vector.
742 For large arrays, this operation can be slow (\l{linear time}),
743 because it requires moving all the items at indexes \a i and
744 above by one position further in memory. If you want a container
745 class that provides a fast insert() function, use std::list
751/*! \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::insert(qsizetype i, qsizetype count, const T &value)
756 Inserts \a count copies of \a value at index position \a i in the
760/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::iterator QVarLengthArray<T, Prealloc>::insert(const_iterator before, const T &value)
761 \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::iterator QVarLengthArray<T, Prealloc>::insert(const_iterator before, T &&value)
766 Inserts \a value in front of the item pointed to by the iterator
767 \a before. Returns an iterator pointing at the inserted item.
771 \fn template <class T, qsizetype Prealloc> template <typename...Args> QVarLengthArray<T, Prealloc>::iterator QVarLengthArray<T, Prealloc>::emplace(const_iterator pos, Args &&...args)
775 Inserts an item in front of the item pointed to by the iterator
776 \a pos, passing \a args to its constructor.
778 Returns an iterator pointing at the emplaced item.
782 \fn template <class T, qsizetype Prealloc> template <typename...Args> T &QVarLengthArray<T, Prealloc>::emplace_back(Args &&...args)
785 Inserts an item at the back of this QVarLengthArray, passing
786 \a args to its constructor.
788 Returns a reference to the emplaced item.
791/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::iterator QVarLengthArray<T, Prealloc>::insert(const_iterator before, qsizetype count, const T &value)
794 Inserts \a count copies of \a value in front of the item pointed to
795 by the iterator \a before. Returns an iterator pointing at the
796 first of the inserted items.
801/*! \fn template<class T, qsizetype Prealloc1, qsizetype Prealloc2> bool operator==(const QVarLengthArray<T, Prealloc1> &left, const QVarLengthArray<T, Prealloc2> &right)
803 \relates QVarLengthArray
805 Returns \c true if the two arrays, specified by \a left and \a right, are equal.
807 Two arrays are considered equal if they contain the same values
810 This function requires the value type to have an implementation
813 \sa {operator!=(const QVarLengthArray<T, Prealloc1> &left, const QVarLengthArray<T, Prealloc2> &right)}{operator!=()}
816/*! \fn template<typename T, qsizetype Prealloc1, qsizetype Prealloc2> bool operator!=(const QVarLengthArray<T, Prealloc1> &left, const QVarLengthArray<T, Prealloc2> &right)
818 \relates QVarLengthArray
820 Returns \c true if the two arrays, specified by \a left and \a right, are \e not equal.
822 Two arrays are considered equal if they contain the same values
825 This function requires the value type to have an implementation
828 \sa {operator==(const QVarLengthArray<T, Prealloc1> &left, const QVarLengthArray<T, Prealloc2> &right)}{operator==()}
831/*! \fn template<typename T, qsizetype Prealloc1, qsizetype Prealloc2> bool operator<(const QVarLengthArray<T,Prealloc1> &lhs, const QVarLengthArray<T,Prealloc2> &rhs)
833 \relates QVarLengthArray
835 Returns \c true if variable length array \a lhs is
836 \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare}
837 {lexicographically less than} \a rhs; otherwise returns \c false.
839 This function requires the value type to have an implementation
843/*! \fn template<typename T, qsizetype Prealloc1, qsizetype Prealloc2> bool operator<=(const QVarLengthArray<T,Prealloc1> &lhs, const QVarLengthArray<T,Prealloc2> &rhs)
845 \relates QVarLengthArray
847 Returns \c true if variable length array \a lhs is
848 \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare}
849 {lexicographically less than or equal to} \a rhs; otherwise returns \c false.
851 This function requires the value type to have an implementation
855/*! \fn template<typename T, qsizetype Prealloc1, qsizetype Prealloc2> bool operator>(const QVarLengthArray<T,Prealloc1> &lhs, const QVarLengthArray<T,Prealloc2> &rhs)
857 \relates QVarLengthArray
859 Returns \c true if variable length array \a lhs is
860 \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare}
861 {lexicographically greater than} \a rhs; otherwise returns \c false.
863 This function requires the value type to have an implementation
867/*! \fn template<typename T, qsizetype Prealloc1, qsizetype Prealloc2> bool operator>=(const QVarLengthArray<T,Prealloc1> &lhs, const QVarLengthArray<T,Prealloc2> &rhs)
869 \relates QVarLengthArray
871 Returns \c true if variable length array \a lhs is
872 \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare}
873 {lexicographically greater than or equal to} \a rhs; otherwise returns \c false.
875 This function requires the value type to have an implementation
879/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc> &QVarLengthArray<T, Prealloc>::operator<<(const T &value)
882 Appends \a value to the array and returns a reference to this
885 \sa append(), operator+=()
888/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc> &QVarLengthArray<T, Prealloc>::operator<<(T &&value)
893 \sa append(), operator+=()
896/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc> &QVarLengthArray<T, Prealloc>::operator+=(const T &value)
899 Appends \a value to the array and returns a reference to this vector.
901 \sa append(), operator<<()
904/*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc> &QVarLengthArray<T, Prealloc>::operator+=(T &&value)
909 \sa append(), operator<<()
912/*! \fn template<class T, qsizetype Prealloc> template <typename AT = T> qsizetype QVarLengthArray<T, Prealloc>::indexOf(const AT &value, qsizetype from = 0) const
915 Returns the index position of the first occurrence of \a value in
916 the array, searching forward from index position \a from.
917 Returns -1 if no item matched.
919 This function requires the value type to have an implementation of
922 \sa lastIndexOf(), contains()
925/*! \fn template<class T, qsizetype Prealloc> template <typename AT = T> qsizetype QVarLengthArray<T, Prealloc>::lastIndexOf(const AT &value, qsizetype from = -1) const
928 Returns the index position of the last occurrence of the value \a
929 value in the array, searching backward from index position \a
930 from. If \a from is -1 (the default), the search starts at the
931 last item. Returns -1 if no item matched.
933 This function requires the value type to have an implementation of
936 \sa indexOf(), contains()
939/*! \fn template<class T, qsizetype Prealloc> template <typename AT = T> bool QVarLengthArray<T, Prealloc>::contains(const AT &value) const
942 Returns \c true if the array contains an occurrence of \a value;
943 otherwise returns \c false.
945 This function requires the value type to have an implementation of
948 \sa indexOf(), lastIndexOf()
952 \fn template <typename T, qsizetype Prealloc> size_t qHash(const QVarLengthArray<T, Prealloc> &key, size_t seed = 0)
953 \relates QVarLengthArray
956 Returns the hash value for \a key, using \a seed to seed the
960/*! \fn template <typename T, qsizetype Prealloc> template <typename AT = T> qsizetype QVarLengthArray<T, Prealloc>::removeAll(const AT &t)
963 Removes all elements that compare equal to \a t from the
964 array. Returns the number of elements removed, if any.
969/*! \fn template <typename T, qsizetype Prealloc> template <typename AT = T> bool QVarLengthArray<T, Prealloc>::removeOne(const AT &t)
972 Removes the first element that compares equal to \a t from the
973 array. Returns whether an element was, in fact, removed.
978/*! \fn template <typename T, qsizetype Prealloc> template <typename Predicate> qsizetype QVarLengthArray<T, Prealloc>::removeIf(Predicate pred)
981 Removes all elements for which the predicate \a pred returns true
982 from the array. Returns the number of elements removed, if any.
987/*! \fn template <typename T, qsizetype Prealloc, typename AT> qsizetype erase(QVarLengthArray<T, Prealloc> &array, const AT &t)
988 \relates QVarLengthArray
991 Removes all elements that compare equal to \a t from the
992 array \a array. Returns the number of elements removed, if any.
994 \note \a t is not allowed to be a reference to an element inside \a
995 array. If you cannot be sure that this is not the case, take a copy
996 of \a t and call this function with the copy.
1001/*! \fn template <typename T, qsizetype Prealloc, typename Predicate> qsizetype erase_if(QVarLengthArray<T, Prealloc> &array, Predicate pred)
1002 \relates QVarLengthArray
1005 Removes all elements for which the predicate \a pred returns true
1006 from the list \a array. Returns the number of elements removed, if
1012/*! \fn template <class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>& QVarLengthArray<T, Prealloc>::assign(qsizetype n, const T &t)
1015 Replaces the contents of this container with \a n copies of \a t.
1017 The size of this container will be equal to \a n. This function will only
1018 allocate memory if \a n exceeds the capacity of the container.
1021/*! \fn template <class T, qsizetype Prealloc> template <typename InputIterator, QVarLengthArray<T, Prealloc>::if_input_iterator<InputIterator>> QVarLengthArray<T, Prealloc>& QVarLengthArray<T, Prealloc>::assign(InputIterator first, InputIterator last)
1024 Replaces the contents of this container with a copy of the elements in the
1025 iterator range [\a first, \a last).
1027 The size of this container will be equal to the number of elements in the
1028 range [\a first, \a last). This function will only allocate memory if the
1029 number of elements in the range exceeds the capacity of the container.
1031 This function overload only participates in overload resolution if
1032 \c InputIterator meets the requirements of an
1033 \l {https://en.cppreference.com/w/cpp/named_req/InputIterator} {LegacyInputIterator}.
1035 The behavior is undefined if either argument is an iterator into *this.
1038/*! \fn template <class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>& QVarLengthArray<T, Prealloc>::assign(std::initializer_list<T> list)
1041 Replaces the contents of this container with a copy of the elements of \a list.
1043 The size of this container will be equal to the number of elements in \a list.
1045 This function only allocates memory if the number of elements in \a list
1046 exceeds the capacity of the container.