| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** Alternatively, this file may be used under the terms of the GNU Free |
| ** Documentation License version 1.3 as published by the Free Software |
| ** Foundation and appearing in the file included in the packaging of |
| ** this file. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \class QVector |
| \inmodule QtCore |
| \brief The QVector class is a template class that provides a dynamic array. |
| |
| \ingroup tools |
| \ingroup shared |
| |
| \reentrant |
| |
| QVector\<T\> is one of Qt's generic \l{container classes}. It |
| stores its items in adjacent memory locations and provides fast |
| index-based access. |
| |
| QList\<T\>, QLinkedList\<T\>, QVector\<T\>, and QVarLengthArray\<T\> |
| provide similar APIs and functionality. They are often interchangeable, |
| but there are performance consequences. Here is an overview of use cases: |
| |
| \list |
| \li QVector should be your default first choice. |
| QVector\<T\> will usually give better performance than QList\<T\>, |
| because QVector\<T\> always stores its items sequentially in memory, |
| where QList\<T\> will allocate its items on the heap unless |
| \c {sizeof(T) <= sizeof(void*)} and T has been declared to be |
| either a \c{Q_MOVABLE_TYPE} or a \c{Q_PRIMITIVE_TYPE} using |
| \l {Q_DECLARE_TYPEINFO}. See the \l {Pros and Cons of Using QList} |
| for an explanation. |
| \li However, QList is used throughout the Qt APIs for passing |
| parameters and for returning values. Use QList to interface with |
| those APIs. |
| \li If you need a real linked list, which guarantees |
| \l{Algorithmic Complexity}{constant time} insertions mid-list and |
| uses iterators to items rather than indexes, use QLinkedList. |
| \endlist |
| |
| \note QVector and QVarLengthArray both guarantee C-compatible |
| array layout. QList does not. This might be important if your |
| application must interface with a C API. |
| |
| \note Iterators into a QLinkedList and references into |
| heap-allocating QLists remain valid as long as the referenced items |
| remain in the container. This is not true for iterators and |
| references into a QVector and non-heap-allocating QLists. |
| |
| Here's an example of a QVector that stores integers and a QVector |
| that stores QString values: |
| |
| \snippet code/src_corelib_tools_qvector.cpp 0 |
| |
| QVector stores its items in a vector (array). Typically, vectors |
| are created with an initial size. For example, the following code |
| constructs a QVector with 200 elements: |
| |
| \snippet code/src_corelib_tools_qvector.cpp 1 |
| |
| The elements are automatically initialized with a |
| \l{default-constructed value}. If you want to initialize the |
| vector with a different value, pass that value as the second |
| argument to the constructor: |
| |
| \snippet code/src_corelib_tools_qvector.cpp 2 |
| |
| You can also call fill() at any time to fill the vector with a |
| value. |
| |
| QVector uses 0-based indexes, just like C++ arrays. To access the |
| item at a particular index position, you can use operator[](). On |
| non-const vectors, operator[]() returns a reference to the item |
| that can be used on the left side of an assignment: |
| |
| \snippet code/src_corelib_tools_qvector.cpp 3 |
| |
| For read-only access, an alternative syntax is to use at(): |
| |
| \snippet code/src_corelib_tools_qvector.cpp 4 |
| |
| at() can be faster than operator[](), because it never causes a |
| \l{deep copy} to occur. |
| |
| Another way to access the data stored in a QVector is to call |
| data(). The function returns a pointer to the first item in the |
| vector. You can use the pointer to directly access and modify the |
| elements stored in the vector. The pointer is also useful if you |
| need to pass a QVector to a function that accepts a plain C++ |
| array. |
| |
| If you want to find all occurrences of a particular value in a |
| vector, use indexOf() or lastIndexOf(). The former searches |
| forward starting from a given index position, the latter searches |
| backward. Both return the index of the matching item if they found |
| one; otherwise, they return -1. For example: |
| |
| \snippet code/src_corelib_tools_qvector.cpp 5 |
| |
| If you simply want to check whether a vector contains a |
| particular value, use contains(). If you want to find out how |
| many times a particular value occurs in the vector, use count(). |
| |
| QVector provides these basic functions to add, move, and remove |
| items: insert(), replace(), remove(), prepend(), append(). With |
| the exception of append() and replace(), these functions can be slow |
| (\l{linear time}) for large vectors, because they require moving many |
| items in the vector by one position in memory. If you want a container |
| class that provides fast insertion/removal in the middle, use |
| QList or QLinkedList instead. |
| |
| Unlike plain C++ arrays, QVectors can be resized at any time by |
| calling resize(). If the new size is larger than the old size, |
| QVector might need to reallocate the whole vector. QVector tries |
| to reduce the number of reallocations by preallocating up to twice |
| as much memory as the actual data needs. |
| |
| If you know in advance approximately how many items the QVector |
| will contain, you can call reserve(), asking QVector to |
| preallocate a certain amount of memory. You can also call |
| capacity() to find out how much memory QVector actually |
| allocated. |
| |
| Note that using non-const operators and functions can cause |
| QVector to do a deep copy of the data. This is due to \l{implicit sharing}. |
| |
| QVector's value type must be an \l{assignable data type}. This |
| covers most data types that are commonly used, but the compiler |
| won't let you, for example, store a QWidget as a value; instead, |
| store a QWidget *. A few functions have additional requirements; |
| for example, indexOf() and lastIndexOf() expect the value type to |
| support \c operator==(). These requirements are documented on a |
| per-function basis. |
| |
| Like the other container classes, QVector provides \l{Java-style |
| iterators} (QVectorIterator and QMutableVectorIterator) and |
| \l{STL-style iterators} (QVector::const_iterator and |
| QVector::iterator). In practice, these are rarely used, because |
| you can use indexes into the QVector. |
| |
| In addition to QVector, Qt also provides QVarLengthArray, a very |
| low-level class with little functionality that is optimized for |
| speed. |
| |
| QVector does \e not support inserting, prepending, appending or replacing |
| with references to its own values. Doing so will cause your application to |
| abort with an error message. |
| |
| \section2 More Information on Using Qt Containers |
| |
| For a detailed discussion comparing Qt containers with each other and |
| with STL containers, see \l {Understand the Qt Containers}. |
| |
| \section1 Maximum size and out-of-memory conditions |
| |
| The current version of QVector is limited to just under 2 GB (2^31 bytes) |
| in size. The exact value is architecture-dependent, since it depends on the |
| overhead required for managing the data block, but is no more than 32 |
| bytes. The number of elements that can be stored in a QVector is that size |
| divided by the size of each element. |
| |
| In case memory allocation fails, QVector will use the \l Q_CHECK_PTR macro, |
| which will throw a \c std::bad_alloc exception if the application is being |
| compiled with exception support. If exceptions are disabled, then running |
| out of memory is undefined behavior. |
| |
| Note that the operating system may impose further limits on applications |
| holding a lot of allocated memory, especially large, contiguous blocks. |
| Such considerations, the configuration of such behavior or any mitigation |
| are outside the scope of the Qt API. |
| |
| \sa QVectorIterator, QMutableVectorIterator, QList, QLinkedList |
| */ |
| |
| /*! |
| \fn template <typename T> QVector<T> QVector<T>::mid(int pos, int length = -1) const |
| |
| Returns a sub-vector which contains elements from this vector, |
| starting at position \a pos. If \a length is -1 (the default), all |
| elements after \a pos are included; otherwise \a length elements (or |
| all remaining elements if there are less than \a length elements) |
| are included. |
| */ |
| |
| |
| /*! \fn template <typename T> QVector<T>::QVector() |
| |
| Constructs an empty vector. |
| |
| \sa resize() |
| */ |
| |
| /*! |
| \fn template <typename T> QVector<T>::QVector(QVector<T> &&other) |
| |
| Move-constructs a QVector instance, making it point at the same |
| object that \a other was pointing to. |
| |
| \since 5.2 |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::QVector(int size) |
| |
| Constructs a vector with an initial size of \a size elements. |
| |
| The elements are initialized with a \l{default-constructed |
| value}. |
| |
| \sa resize() |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::QVector(int size, const T &value) |
| |
| Constructs a vector with an initial size of \a size elements. |
| Each element is initialized with \a value. |
| |
| \sa resize(), fill() |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::QVector(const QVector<T> &other) |
| |
| Constructs a copy of \a other. |
| |
| This operation takes \l{Algorithmic Complexity}{constant time}, |
| because QVector is \l{implicitly shared}. This makes returning |
| a QVector from a function very fast. If a shared instance is |
| modified, it will be copied (copy-on-write), and that takes |
| \l{Algorithmic Complexity}{linear time}. |
| |
| \sa operator=() |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::QVector(std::initializer_list<T> args) |
| \since 4.8 |
| |
| Constructs a vector from the std::initializer_list given by \a args. |
| |
| This constructor is only enabled if the compiler supports C++11 initializer |
| lists. |
| */ |
| |
| /*! \fn template <typename T> template<typename InputIterator> QVector<T>::QVector(InputIterator first, InputIterator last) |
| \since 5.14 |
| |
| Constructs a vector with the contents in the iterator range [\a first, \a last). |
| |
| The value type of \c InputIterator must be convertible to \c T. |
| */ |
| |
| /*! |
| \fn template <typename T> QVector<T>::QVector(QArrayDataPointerRef<T> ref) |
| \internal |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::~QVector() |
| |
| Destroys the vector. |
| */ |
| |
| /*! \fn template <typename T> QVector<T> &QVector<T>::operator=(const QVector<T> &other) |
| |
| Assigns \a other to this vector and returns a reference to this |
| vector. |
| */ |
| |
| /*! |
| \fn template <typename T> QVector<T> &QVector<T>::operator=(QVector<T> &&other) |
| |
| Move-assigns \a other to this QVector instance. |
| |
| \since 5.2 |
| */ |
| |
| /*! |
| \fn template <typename T> QVector<T> &QVector<T>::operator=(std::initializer_list<T> args) |
| |
| Assigns the collection of values in \a args to this QVector instance. |
| |
| This operator is only enabled if the compiler supports C++11 initializer |
| lists. |
| |
| \since 5.14 |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::swap(QVector<T> &other) |
| \since 4.8 |
| |
| Swaps vector \a other with this vector. This operation is very fast and |
| never fails. |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::swapItemsAt(int i, int j) |
| \since 5.14 |
| |
| Exchange the item at index position \a i with the item at index |
| position \a j. This function assumes that both \a i and \a j are |
| at least 0 but less than size(). To avoid failure, test that both |
| \a i and \a j are at least 0 and less than size(). |
| */ |
| |
| |
| /*! \fn template <typename T> bool QVector<T>::operator==(const QVector<T> &other) const |
| |
| Returns \c true if \a other is equal to this vector; otherwise |
| returns \c false. |
| |
| Two vectors are considered equal if they contain the same values |
| in the same order. |
| |
| This function requires the value type to have an implementation |
| of \c operator==(). |
| |
| \sa operator!=() |
| */ |
| |
| /*! \fn template <typename T> bool QVector<T>::operator!=(const QVector<T> &other) const |
| |
| Returns \c true if \a other is not equal to this vector; otherwise |
| returns \c false. |
| |
| Two vectors are considered equal if they contain the same values |
| in the same order. |
| |
| This function requires the value type to have an implementation |
| of \c operator==(). |
| |
| \sa operator==() |
| */ |
| |
| /*! \fn template <typename T> bool operator<(const QVector<T> &lhs, const QVector<T> &rhs) |
| \since 5.6 |
| \relates QVector |
| |
| Returns \c true if vector \a lhs is |
| \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare} |
| {lexicographically less than} \a rhs; otherwise returns \c false. |
| |
| This function requires the value type to have an implementation |
| of \c operator<(). |
| */ |
| |
| /*! \fn template <typename T> bool operator<=(const QVector<T> &lhs, const QVector<T> &rhs) |
| \since 5.6 |
| \relates QVector |
| |
| Returns \c true if vector \a lhs is |
| \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare} |
| {lexicographically less than or equal to} \a rhs; otherwise returns \c false. |
| |
| This function requires the value type to have an implementation |
| of \c operator<(). |
| */ |
| |
| /*! \fn template <typename T> bool operator>(const QVector<T> &lhs, const QVector<T> &rhs) |
| \since 5.6 |
| \relates QVector |
| |
| Returns \c true if vector \a lhs is |
| \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare} |
| {lexicographically greater than} \a rhs; otherwise returns \c false. |
| |
| This function requires the value type to have an implementation |
| of \c operator<(). |
| */ |
| |
| /*! \fn template <typename T> bool operator>=(const QVector<T> &lhs, const QVector<T> &rhs) |
| \since 5.6 |
| \relates QVector |
| |
| Returns \c true if vector \a lhs is |
| \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare} |
| {lexicographically greater than or equal to} \a rhs; otherwise returns \c false. |
| |
| This function requires the value type to have an implementation |
| of \c operator<(). |
| */ |
| |
| /*! |
| \fn template <typename T> uint qHash(const QVector<T> &key, uint seed = 0) |
| \since 5.6 |
| \relates QVector |
| |
| Returns the hash value for \a key, |
| using \a seed to seed the calculation. |
| |
| This function requires qHash() to be overloaded for the value type \c T. |
| */ |
| |
| /*! \fn template <typename T> int QVector<T>::size() const |
| |
| Returns the number of items in the vector. |
| |
| \sa isEmpty(), resize() |
| */ |
| |
| /*! \fn template <typename T> bool QVector<T>::isEmpty() const |
| |
| Returns \c true if the vector has size 0; otherwise returns \c false. |
| |
| \sa size(), resize() |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::resize(int size) |
| |
| Sets the size of the vector to \a size. If \a size is greater than the |
| current size, elements are added to the end; the new elements are |
| initialized with a \l{default-constructed value}. If \a size is less |
| than the current size, elements are removed from the end. |
| |
| Since Qt 5.6, resize() doesn't shrink the capacity anymore. |
| To shed excess capacity, use squeeze(). |
| |
| \sa size() |
| */ |
| |
| /*! \fn template <typename T> int QVector<T>::capacity() const |
| |
| Returns the maximum number of items that can be stored in the |
| vector without forcing a reallocation. |
| |
| The sole purpose of this function is to provide a means of fine |
| tuning QVector's memory usage. In general, you will rarely ever |
| need to call this function. If you want to know how many items are |
| in the vector, call size(). |
| |
| \sa reserve(), squeeze() |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::reserve(int size) |
| |
| Attempts to allocate memory for at least \a size elements. If you |
| know in advance how large the vector will be, you should call this |
| function to prevent reallocations and memory fragmentation. |
| |
| If \a size is an underestimate, the worst that will happen is that |
| the QVector will be a bit slower. If \a size is an overestimate, you |
| may have used more memory than the normal QVector growth strategy |
| would have allocated—or you may have used less. |
| |
| An alternative to reserve() is calling resize(). Whether or not that is |
| faster than reserve() depends on the element type, because resize() |
| default-constructs all elements, and requires assignment to existing |
| entries rather than calling append(), which copy- or move-constructs. |
| For simple types, like \c int or \c double, resize() is typically faster, |
| but for anything more complex, you should prefer reserve(). |
| |
| \warning If the size passed to resize() was underestimated, you run out |
| of allocated space and into undefined behavior. This problem does not |
| exist with reserve(), because it treats the size as just a hint. |
| |
| \sa squeeze(), capacity() |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::squeeze() |
| |
| Releases any memory not required to store the items. |
| |
| The sole purpose of this function is to provide a means of fine |
| tuning QVector's memory usage. In general, you will rarely ever |
| need to call this function. |
| |
| \sa reserve(), capacity() |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::detach() |
| |
| \internal |
| */ |
| |
| /*! \fn template <typename T> bool QVector<T>::isDetached() const |
| |
| \internal |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::setSharable(bool sharable) |
| |
| \internal |
| */ |
| |
| /*! \fn template <typename T> bool QVector<T>::isSharedWith(const QVector<T> &other) const |
| |
| \internal |
| */ |
| |
| /*! \fn template <typename T> T *QVector<T>::data() |
| |
| Returns a pointer to the data stored in the vector. The pointer |
| can be used to access and modify the items in the vector. |
| |
| Example: |
| \snippet code/src_corelib_tools_qvector.cpp 6 |
| |
| The pointer remains valid as long as the vector isn't |
| reallocated. |
| |
| This function is mostly useful to pass a vector to a function |
| that accepts a plain C++ array. |
| |
| \sa constData(), operator[]() |
| */ |
| |
| /*! \fn template <typename T> const T *QVector<T>::data() const |
| |
| \overload |
| */ |
| |
| /*! \fn template <typename T> const T *QVector<T>::constData() const |
| |
| Returns a const pointer to the data stored in the vector. The |
| pointer can be used to access the items in the vector. |
| The pointer remains valid as long as the vector isn't |
| reallocated. |
| |
| This function is mostly useful to pass a vector to a function |
| that accepts a plain C++ array. |
| |
| \sa data(), operator[]() |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::clear() |
| |
| Removes all the elements from the vector. |
| |
| \note Until Qt 5.6, this also released the memory used by |
| the vector. From Qt 5.7, the capacity is preserved. To shed |
| all capacity, swap with a default-constructed vector: |
| \code |
| QVector<T> v ...; |
| QVector<T>().swap(v); |
| Q_ASSERT(v.capacity() == 0); |
| \endcode |
| or call squeeze(). |
| |
| \sa squeeze() |
| */ |
| |
| /*! \fn template <typename T> const T &QVector<T>::at(int i) const |
| |
| Returns the item at index position \a i in the vector. |
| |
| \a i must be a valid index position in the vector (i.e., 0 <= \a |
| i < size()). |
| |
| \sa value(), operator[]() |
| */ |
| |
| /*! \fn template <typename T> T &QVector<T>::operator[](int i) |
| |
| Returns the item at index position \a i as a modifiable reference. |
| |
| \a i must be a valid index position in the vector (i.e., 0 <= \a i |
| < size()). |
| |
| Note that using non-const operators can cause QVector to do a deep |
| copy. |
| |
| \sa at(), value() |
| */ |
| |
| /*! \fn template <typename T> const T &QVector<T>::operator[](int i) const |
| |
| \overload |
| |
| Same as at(\a i). |
| */ |
| |
| /*! |
| \fn template <typename T> void QVector<T>::append(const T &value) |
| |
| Inserts \a value at the end of the vector. |
| |
| Example: |
| \snippet code/src_corelib_tools_qvector.cpp 7 |
| |
| This is the same as calling resize(size() + 1) and assigning \a |
| value to the new last element in the vector. |
| |
| This operation is relatively fast, because QVector typically |
| allocates more memory than necessary, so it can grow without |
| reallocating the entire vector each time. |
| |
| \sa operator<<(), prepend(), insert() |
| */ |
| |
| /*! |
| \fn template <typename T> void QVector<T>::append(T &&value) |
| \since 5.6 |
| |
| \overload |
| |
| Example: |
| \snippet code/src_corelib_tools_qvector.cpp move-append |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::append(const QVector<T> &value) |
| |
| \overload |
| |
| \since 5.5 |
| |
| Appends the items of the \a value vector to this vector. |
| |
| \sa operator<<(), operator+=() |
| */ |
| |
| |
| /*! |
| \fn template <typename T> void QVector<T>::prepend(const T &value) |
| \fn template <typename T> void QVector<T>::prepend(T &&value) |
| |
| Inserts \a value at the beginning of the vector. |
| |
| Example: |
| \snippet code/src_corelib_tools_qvector.cpp 8 |
| |
| This is the same as vector.insert(0, \a value). |
| |
| For large vectors, this operation can be slow (\l{linear time}), |
| because it requires moving all the items in the vector by one |
| position further in memory. If you want a container class that |
| provides a fast prepend() function, use QList or QLinkedList |
| instead. |
| |
| \sa append(), insert() |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::insert(int i, const T &value) |
| \fn template <typename T> void QVector<T>::insert(int i, T &&value) |
| |
| Inserts \a value at index position \a i in the vector. If \a i is |
| 0, the value is prepended to the vector. If \a i is size(), the |
| value is appended to the vector. |
| |
| Example: |
| \snippet code/src_corelib_tools_qvector.cpp 9 |
| |
| For large vectors, this operation can be slow (\l{linear time}), |
| because it requires moving all the items at indexes \a i and |
| above by one position further in memory. If you want a container |
| class that provides a fast insert() function, use QLinkedList |
| instead. |
| |
| \sa append(), prepend(), remove() |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::insert(int i, int count, const T &value) |
| |
| \overload |
| |
| Inserts \a count copies of \a value at index position \a i in the |
| vector. |
| |
| Example: |
| \snippet code/src_corelib_tools_qvector.cpp 10 |
| */ |
| |
| /*! |
| \fn template <typename T> QVector<T>::iterator QVector<T>::insert(iterator before, const T &value) |
| \fn template <typename T> QVector<T>::iterator QVector<T>::insert(iterator before, T &&value) |
| |
| \overload |
| |
| Inserts \a value in front of the item pointed to by the iterator |
| \a before. Returns an iterator pointing at the inserted item. |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::iterator QVector<T>::insert(iterator before, int count, const T &value) |
| |
| Inserts \a count copies of \a value in front of the item pointed to |
| by the iterator \a before. Returns an iterator pointing at the |
| first of the inserted items. |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::replace(int i, const T &value) |
| |
| Replaces the item at index position \a i with \a value. |
| |
| \a i must be a valid index position in the vector (i.e., 0 <= \a |
| i < size()). |
| |
| \sa operator[](), remove() |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::remove(int i) |
| |
| \overload |
| |
| Removes the element at index position \a i. |
| |
| \sa insert(), replace(), fill() |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::remove(int i, int count) |
| |
| \overload |
| |
| Removes \a count elements from the middle of the vector, starting at |
| index position \a i. |
| |
| \sa insert(), replace(), fill() |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::removeAt(int i) |
| \since 5.2 |
| |
| Removes the element at index position \a i. |
| Equivalent to |
| \code |
| remove(i); |
| \endcode |
| |
| Provided for compatibility with QList. |
| |
| \sa remove(), QList::removeAt() |
| */ |
| |
| /*! \fn template <typename T> int QVector<T>::removeAll(const T &t) |
| \since 5.4 |
| |
| Removes all elements that compare equal to \a t from the |
| vector. Returns the number of elements removed, if any. |
| |
| Provided for compatibility with QList. |
| |
| \sa removeOne(), QList::removeAll() |
| */ |
| |
| /*! \fn template <typename T> bool QVector<T>::removeOne(const T &t) |
| \since 5.4 |
| |
| Removes the first element that compares equal to \a t from the |
| vector. Returns whether an element was, in fact, removed. |
| |
| Provided for compatibility with QList. |
| |
| \sa removeAll(), QList::removeOne() |
| */ |
| |
| /*! \fn template <typename T> int QVector<T>::length() const |
| \since 5.2 |
| |
| Same as size() and count(). |
| |
| Provided for compatibility with QList. |
| |
| \sa size(), count(), QList::length() |
| */ |
| |
| /*! \fn template <typename T> T QVector<T>::takeAt(int i) |
| \since 5.2 |
| |
| Removes the element at index position \a i and returns it. |
| |
| Equivalent to |
| \code |
| T t = at(i); |
| remove(i); |
| return t; |
| \endcode |
| |
| Provided for compatibility with QList. |
| |
| \sa takeFirst(), takeLast(), QList::takeAt() |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::move(int from, int to) |
| \since 5.6 |
| |
| Moves the item at index position \a from to index position \a to. |
| |
| Provided for compatibility with QList. |
| |
| \sa QList::move() |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::removeFirst() |
| \since 5.1 |
| Removes the first item in the vector. Calling this function is |
| equivalent to calling remove(0). The vector must not be empty. If |
| the vector can be empty, call isEmpty() before calling this |
| function. |
| |
| \sa remove(), takeFirst(), isEmpty() |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::removeLast() |
| \since 5.1 |
| Removes the last item in the vector. Calling this function is |
| equivalent to calling remove(size() - 1). The vector must not be |
| empty. If the vector can be empty, call isEmpty() before calling |
| this function. |
| |
| \sa remove(), takeLast(), removeFirst(), isEmpty() |
| */ |
| |
| /*! \fn template <typename T> T QVector<T>::takeFirst() |
| \since 5.1 |
| |
| Removes the first item in the vector and returns it. This function |
| assumes the vector is not empty. To avoid failure, call isEmpty() |
| before calling this function. |
| |
| \sa takeLast(), removeFirst() |
| */ |
| |
| /*! \fn template <typename T> T QVector<T>::takeLast() |
| \since 5.1 |
| |
| Removes the last item in the list and returns it. This function |
| assumes the vector is not empty. To avoid failure, call isEmpty() |
| before calling this function. |
| |
| If you don't use the return value, removeLast() is more |
| efficient. |
| |
| \sa takeFirst(), removeLast() |
| */ |
| |
| |
| /*! \fn template <typename T> QVector<T> &QVector<T>::fill(const T &value, int size = -1) |
| |
| Assigns \a value to all items in the vector. If \a size is |
| different from -1 (the default), the vector is resized to size \a |
| size beforehand. |
| |
| Example: |
| \snippet code/src_corelib_tools_qvector.cpp 11 |
| |
| \sa resize() |
| */ |
| |
| /*! \fn template <typename T> int QVector<T>::indexOf(const T &value, int from = 0) const |
| |
| Returns the index position of the first occurrence of \a value in |
| the vector, searching forward from index position \a from. |
| Returns -1 if no item matched. |
| |
| Example: |
| \snippet code/src_corelib_tools_qvector.cpp 12 |
| |
| This function requires the value type to have an implementation of |
| \c operator==(). |
| |
| \sa lastIndexOf(), contains() |
| */ |
| |
| /*! \fn template <typename T> int QVector<T>::lastIndexOf(const T &value, int from = -1) const |
| |
| Returns the index position of the last occurrence of the value \a |
| value in the vector, searching backward from index position \a |
| from. If \a from is -1 (the default), the search starts at the |
| last item. Returns -1 if no item matched. |
| |
| Example: |
| \snippet code/src_corelib_tools_qvector.cpp 13 |
| |
| This function requires the value type to have an implementation of |
| \c operator==(). |
| |
| \sa indexOf() |
| */ |
| |
| /*! \fn template <typename T> bool QVector<T>::contains(const T &value) const |
| |
| Returns \c true if the vector contains an occurrence of \a value; |
| otherwise returns \c false. |
| |
| This function requires the value type to have an implementation of |
| \c operator==(). |
| |
| \sa indexOf(), count() |
| */ |
| |
| /*! \fn template <typename T> bool QVector<T>::startsWith(const T &value) const |
| \since 4.5 |
| |
| Returns \c true if this vector is not empty and its first |
| item is equal to \a value; otherwise returns \c false. |
| |
| \sa isEmpty(), first() |
| */ |
| |
| /*! \fn template <typename T> bool QVector<T>::endsWith(const T &value) const |
| \since 4.5 |
| |
| Returns \c true if this vector is not empty and its last |
| item is equal to \a value; otherwise returns \c false. |
| |
| \sa isEmpty(), last() |
| */ |
| |
| |
| /*! \fn template <typename T> int QVector<T>::count(const T &value) const |
| |
| Returns the number of occurrences of \a value in the vector. |
| |
| This function requires the value type to have an implementation of |
| \c operator==(). |
| |
| \sa contains(), indexOf() |
| */ |
| |
| /*! \fn template <typename T> int QVector<T>::count() const |
| |
| \overload |
| |
| Same as size(). |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::iterator QVector<T>::begin() |
| |
| Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first item in |
| the vector. |
| |
| \sa constBegin(), end() |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::const_iterator QVector<T>::begin() const |
| |
| \overload |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::const_iterator QVector<T>::cbegin() const |
| \since 5.0 |
| |
| Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item |
| in the vector. |
| |
| \sa begin(), cend() |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::const_iterator QVector<T>::constBegin() const |
| |
| Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item |
| in the vector. |
| |
| \sa begin(), constEnd() |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::iterator QVector<T>::end() |
| |
| Returns an \l{STL-style iterators}{STL-style iterator} pointing to the imaginary item |
| after the last item in the vector. |
| |
| \sa begin(), constEnd() |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::const_iterator QVector<T>::end() const |
| |
| \overload |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::const_iterator QVector<T>::cend() const |
| \since 5.0 |
| |
| Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary |
| item after the last item in the vector. |
| |
| \sa cbegin(), end() |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::const_iterator QVector<T>::constEnd() const |
| |
| Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary |
| item after the last item in the vector. |
| |
| \sa constBegin(), end() |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::reverse_iterator QVector<T>::rbegin() |
| \since 5.6 |
| |
| Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to the first |
| item in the vector, in reverse order. |
| |
| \sa begin(), crbegin(), rend() |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::const_reverse_iterator QVector<T>::rbegin() const |
| \since 5.6 |
| \overload |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::const_reverse_iterator QVector<T>::crbegin() const |
| \since 5.6 |
| |
| Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing to the first |
| item in the vector, in reverse order. |
| |
| \sa begin(), rbegin(), rend() |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::reverse_iterator QVector<T>::rend() |
| \since 5.6 |
| |
| Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to one past |
| the last item in the vector, in reverse order. |
| |
| \sa end(), crend(), rbegin() |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::const_reverse_iterator QVector<T>::rend() const |
| \since 5.6 |
| \overload |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::const_reverse_iterator QVector<T>::crend() const |
| \since 5.6 |
| |
| Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing to one |
| past the last item in the vector, in reverse order. |
| |
| \sa end(), rend(), rbegin() |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::iterator QVector<T>::erase(iterator pos) |
| |
| Removes the item pointed to by the iterator \a pos from the |
| vector, and returns an iterator to the next item in the vector |
| (which may be end()). |
| |
| \sa insert(), remove() |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::iterator QVector<T>::erase(iterator begin, iterator end) |
| |
| \overload |
| |
| Removes all the items from \a begin up to (but not including) \a |
| end. Returns an iterator to the same item that \a end referred to |
| before the call. |
| */ |
| |
| /*! \fn template <typename T> T& QVector<T>::first() |
| |
| Returns a reference to the first item in the vector. This |
| function assumes that the vector isn't empty. |
| |
| \sa last(), isEmpty(), constFirst() |
| */ |
| |
| /*! \fn template <typename T> const T& QVector<T>::first() const |
| |
| \overload |
| */ |
| |
| /*! \fn template <typename T> const T& QVector<T>::constFirst() const |
| \since 5.6 |
| |
| Returns a const reference to the first item in the vector. This |
| function assumes that the vector isn't empty. |
| |
| \sa constLast(), isEmpty(), first() |
| */ |
| |
| /*! \fn template <typename T> T& QVector<T>::last() |
| |
| Returns a reference to the last item in the vector. This function |
| assumes that the vector isn't empty. |
| |
| \sa first(), isEmpty(), constLast() |
| */ |
| |
| /*! \fn template <typename T> const T& QVector<T>::last() const |
| |
| \overload |
| */ |
| |
| /*! \fn template <typename T> const T& QVector<T>::constLast() const |
| \since 5.6 |
| |
| Returns a const reference to the last item in the vector. This function |
| assumes that the vector isn't empty. |
| |
| \sa constFirst(), isEmpty(), last() |
| */ |
| |
| /*! \fn template <typename T> T QVector<T>::value(int i) const |
| |
| Returns the value at index position \a i in the vector. |
| |
| If the index \a i is out of bounds, the function returns |
| a \l{default-constructed value}. If you are certain that |
| \a i is within bounds, you can use at() instead, which is slightly |
| faster. |
| |
| \sa at(), operator[]() |
| */ |
| |
| /*! \fn template <typename T> T QVector<T>::value(int i, const T &defaultValue) const |
| |
| \overload |
| |
| If the index \a i is out of bounds, the function returns |
| \a defaultValue. |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::push_back(const T &value) |
| |
| This function is provided for STL compatibility. It is equivalent |
| to append(\a value). |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::push_back(T &&value) |
| \since 5.6 |
| \overload |
| */ |
| |
| /*! |
| \fn template <typename T> void QVector<T>::push_front(const T &value) |
| \fn template <typename T> void QVector<T>::push_front(T &&value) |
| |
| This function is provided for STL compatibility. It is equivalent |
| to prepend(\a value). |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::pop_front() |
| |
| This function is provided for STL compatibility. It is equivalent |
| to removeFirst(). |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::pop_back() |
| |
| This function is provided for STL compatibility. It is equivalent |
| to removeLast(). |
| */ |
| |
| /*! \fn template <typename T> T& QVector<T>::front() |
| |
| This function is provided for STL compatibility. It is equivalent |
| to first(). |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::const_reference QVector<T>::front() const |
| |
| \overload |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::reference QVector<T>::back() |
| |
| This function is provided for STL compatibility. It is equivalent |
| to last(). |
| */ |
| |
| /*! \fn template <typename T> QVector<T>::const_reference QVector<T>::back() const |
| |
| \overload |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::shrink_to_fit() |
| \since 5.10 |
| |
| This function is provided for STL compatibility. It is equivalent |
| to squeeze(). |
| */ |
| |
| /*! \fn template <typename T> bool QVector<T>::empty() const |
| |
| This function is provided for STL compatibility. It is equivalent |
| to isEmpty(), returning \c true if the vector is empty; otherwise |
| returns \c false. |
| */ |
| |
| /*! \fn template <typename T> QVector<T> &QVector<T>::operator+=(const QVector<T> &other) |
| |
| Appends the items of the \a other vector to this vector and |
| returns a reference to this vector. |
| |
| \sa operator+(), append() |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::operator+=(const T &value) |
| |
| \overload |
| |
| Appends \a value to the vector. |
| |
| \sa append(), operator<<() |
| */ |
| |
| /*! \fn template <typename T> void QVector<T>::operator+=(T &&value) |
| \since 5.11 |
| |
| \overload |
| |
| \sa append(), operator<<() |
| */ |
| |
| /*! \fn template <typename T> QVector<T> QVector<T>::operator+(const QVector<T> &other) const |
| |
| Returns a vector that contains all the items in this vector |
| followed by all the items in the \a other vector. |
| |
| \sa operator+=() |
| */ |
| |
| /*! \fn template <typename T> QVector<T> &QVector<T>::operator<<(const T &value) |
| |
| Appends \a value to the vector and returns a reference to this |
| vector. |
| |
| \sa append(), operator+=() |
| */ |
| |
| /*! \fn template <typename T> QVector<T> &QVector<T>::operator<<(T &&value) |
| \since 5.11 |
| |
| \overload |
| |
| \sa append(), operator+=() |
| */ |
| |
| |
| /*! \fn template <typename T> QVector<T> &QVector<T>::operator<<(const QVector<T> &other) |
| |
| Appends \a other to the vector and returns a reference to the |
| vector. |
| */ |
| |
| /*! \typedef QVector::iterator |
| |
| The QVector::iterator typedef provides an STL-style non-const |
| iterator for QVector and QStack. |
| |
| QVector provides both \l{STL-style iterators} and \l{Java-style |
| iterators}. The STL-style non-const iterator is simply a typedef |
| for "T *" (pointer to T). |
| |
| \warning Iterators on implicitly shared containers do not work |
| exactly like STL-iterators. You should avoid copying a container |
| while iterators are active on that container. For more information, |
| read \l{Implicit sharing iterator problem}. |
| |
| \sa QVector::begin(), QVector::end(), QVector::const_iterator, QMutableVectorIterator |
| */ |
| |
| /*! \typedef QVector::const_iterator |
| |
| The QVector::const_iterator typedef provides an STL-style const |
| iterator for QVector and QStack. |
| |
| QVector provides both \l{STL-style iterators} and \l{Java-style |
| iterators}. The STL-style const iterator is simply a typedef for |
| "const T *" (pointer to const T). |
| |
| \warning Iterators on implicitly shared containers do not work |
| exactly like STL-iterators. You should avoid copying a container |
| while iterators are active on that container. For more information, |
| read \l{Implicit sharing iterator problem}. |
| |
| \sa QVector::constBegin(), QVector::constEnd(), QVector::iterator, QVectorIterator |
| */ |
| |
| /*! \typedef QVector::reverse_iterator |
| \since 5.6 |
| |
| The QVector::reverse_iterator typedef provides an STL-style non-const |
| reverse iterator for QVector. |
| |
| It is simply a typedef for \c{std::reverse_iterator<T*>}. |
| |
| \warning Iterators on implicitly shared containers do not work |
| exactly like STL-iterators. You should avoid copying a container |
| while iterators are active on that container. For more information, |
| read \l{Implicit sharing iterator problem}. |
| |
| \sa QVector::rbegin(), QVector::rend(), QVector::const_reverse_iterator, QVector::iterator |
| */ |
| |
| /*! \typedef QVector::const_reverse_iterator |
| \since 5.6 |
| |
| The QVector::const_reverse_iterator typedef provides an STL-style const |
| reverse iterator for QVector. |
| |
| It is simply a typedef for \c{std::reverse_iterator<const T*>}. |
| |
| \warning Iterators on implicitly shared containers do not work |
| exactly like STL-iterators. You should avoid copying a container |
| while iterators are active on that container. For more information, |
| read \l{Implicit sharing iterator problem}. |
| |
| \sa QVector::rbegin(), QVector::rend(), QVector::reverse_iterator, QVector::const_iterator |
| */ |
| |
| /*! \typedef QVector::Iterator |
| |
| Qt-style synonym for QVector::iterator. |
| */ |
| |
| /*! \typedef QVector::ConstIterator |
| |
| Qt-style synonym for QVector::const_iterator. |
| */ |
| |
| /*! \typedef QVector::const_pointer |
| |
| Typedef for const T *. Provided for STL compatibility. |
| */ |
| |
| /*! \typedef QVector::const_reference |
| |
| Typedef for T &. Provided for STL compatibility. |
| */ |
| |
| /*! \typedef QVector::difference_type |
| |
| Typedef for ptrdiff_t. Provided for STL compatibility. |
| */ |
| |
| /*! \typedef QVector::pointer |
| |
| Typedef for T *. Provided for STL compatibility. |
| */ |
| |
| /*! \typedef QVector::reference |
| |
| Typedef for T &. Provided for STL compatibility. |
| */ |
| |
| /*! \typedef QVector::size_type |
| |
| Typedef for int. Provided for STL compatibility. |
| */ |
| |
| /*! \typedef QVector::value_type |
| |
| Typedef for T. Provided for STL compatibility. |
| */ |
| |
| /*! \fn template <typename T> QList<T> QVector<T>::toList() const |
| |
| Returns a QList object with the data contained in this QVector. |
| |
| Example: |
| |
| \snippet code/src_corelib_tools_qvector.cpp 14 |
| |
| \include containers-range-constructor.qdocinc |
| |
| \sa fromList(), QList::fromVector() |
| */ |
| |
| /*! \fn template <typename T> QVector<T> QVector<T>::fromList(const QList<T> &list) |
| |
| Returns a QVector object with the data contained in \a list. |
| |
| Example: |
| |
| \snippet code/src_corelib_tools_qvector.cpp 15 |
| |
| \include containers-range-constructor.qdocinc |
| |
| \sa toList(), QList::toVector() |
| */ |
| |
| /*! \fn template <typename T> QVector<T> QVector<T>::fromStdVector(const std::vector<T> &vector) |
| |
| Returns a QVector object with the data contained in \a vector. The |
| order of the elements in the QVector is the same as in \a vector. |
| |
| Example: |
| |
| \snippet code/src_corelib_tools_qvector.cpp 16 |
| |
| \include containers-range-constructor.qdocinc |
| |
| \sa toStdVector(), QList::fromStdList() |
| */ |
| |
| /*! \fn template <typename T> std::vector<T> QVector<T>::toStdVector() const |
| |
| Returns a std::vector object with the data contained in this QVector. |
| Example: |
| |
| \snippet code/src_corelib_tools_qvector.cpp 17 |
| |
| \include containers-range-constructor.qdocinc |
| |
| \sa fromStdVector(), QList::toStdList() |
| */ |
| |
| /*! \fn template <typename T> QDataStream &operator<<(QDataStream &out, const QVector<T> &vector) |
| \relates QVector |
| |
| Writes the vector \a vector to stream \a out. |
| |
| This function requires the value type to implement \c operator<<(). |
| |
| \sa{Serializing Qt Data Types}{Format of the QDataStream operators} |
| */ |
| |
| /*! \fn template <typename T> QDataStream &operator>>(QDataStream &in, QVector<T> &vector) |
| \relates QVector |
| |
| Reads a vector from stream \a in into \a vector. |
| |
| This function requires the value type to implement \c operator>>(). |
| |
| \sa{Serializing Qt Data Types}{Format of the QDataStream operators} |
| */ |