diff options
Diffstat (limited to 'src/corelib/tools/qvector.qdoc')
| -rw-r--r-- | src/corelib/tools/qvector.qdoc | 1424 |
1 files changed, 0 insertions, 1424 deletions
diff --git a/src/corelib/tools/qvector.qdoc b/src/corelib/tools/qvector.qdoc deleted file mode 100644 index 116d962411..0000000000 --- a/src/corelib/tools/qvector.qdoc +++ /dev/null @@ -1,1424 +0,0 @@ -/**************************************************************************** -** -** 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} -*/ |