diff options
Diffstat (limited to 'doc/src/q3valuevector.qdoc')
| -rw-r--r-- | doc/src/q3valuevector.qdoc | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/doc/src/q3valuevector.qdoc b/doc/src/q3valuevector.qdoc new file mode 100644 index 0000000000..1af2bf3c24 --- /dev/null +++ b/doc/src/q3valuevector.qdoc @@ -0,0 +1,274 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3ValueVector + \brief The Q3ValueVector class is a value-based template class that provides a dynamic array. + \compat + + Q3ValueVector is a Qt implementation of an STL-like vector + container. It can be used in your application if the standard \c + vector is not available for your target platforms. + + Q3ValueVector\<T\> defines a template instance to create a vector + of values that all have the class T. Q3ValueVector does not store + pointers to the members of the vector; it holds a copy of every + member. Q3ValueVector is said to be value based; in contrast, + Q3PtrList and Q3Dict are pointer based. + + Q3ValueVector contains and manages a collection of objects of type + T and provides random access iterators that allow the contained + objects to be addressed. Q3ValueVector owns the contained + elements. For more relaxed ownership semantics, see Q3PtrCollection + and friends, which are pointer-based containers. + + Q3ValueVector provides good performance if you append or remove + elements from the end of the vector. If you insert or remove + elements from anywhere but the end, performance is very bad. The + reason for this is that elements must to be copied into new + positions. + + Some classes cannot be used within a Q3ValueVector: for example, + all classes derived from QObject and thus all classes that + implement widgets. Only values can be used in a Q3ValueVector. To + qualify as a value the class must provide: + \list + \i a copy constructor; + \i an assignment operator; + \i a default constructor, i.e., a constructor that does not take any arguments. + \endlist + + Note that C++ defaults to field-by-field assignment operators and + copy constructors if no explicit version is supplied. In many + cases this is sufficient. + + Q3ValueVector uses an STL-like syntax to manipulate and address the + objects it contains. + + Example: + \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 0 + + Program output: + \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 1 + + As you can see, the most recent change to Joe's salary did not + affect the value in the vector because the vector created a copy + of Joe's entry. + + Many Qt functions return const value vectors; to iterate over + these you should make a copy and iterate over the copy. + + There are several ways to find items in the vector. The begin() + and end() functions return iterators to the beginning and end of + the vector. The advantage of getting an iterator is that you can + move forward or backward from this position by + incrementing/decrementing the iterator. The iterator returned by + end() points to the element which is one past the last element in + the container. The past-the-end iterator is still associated with + the vector it belongs to, however it is \e not dereferenceable; + operator*() will not return a well-defined value. If the vector is + empty(), the iterator returned by begin() will equal the iterator + returned by end(). + + The fastest way to access an element of a vector is by using + operator[]. This function provides random access and will return + a reference to the element located at the specified index. Thus, + you can access every element directly, in constant time, providing + you know the location of the element. It is undefined to access + an element that does not exist (your application will probably + crash). For example: + + \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 2 + + Whenever inserting, removing or referencing elements in a vector, + always make sure you are referring to valid positions. For + example: + + \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 3 + + The iterators provided by vector are random access iterators, + therefore you can use them with many generic algorithms, for + example, algorithms provided by the STL. + + It is safe to have multiple iterators on the vector at the same + time. Since Q3ValueVector manages memory dynamically, all iterators + can become invalid if a memory reallocation occurs. For example, + if some member of the vector is removed, iterators that point to + the removed element and to all following elements become + invalidated. Inserting into the middle of the vector will + invalidate all iterators. For convenience, the function back() + returns a reference to the last element in the vector, and front() + returns a reference to the first element. If the vector is + empty(), both back() and front() have undefined behavior (your + application will crash or do unpredictable things). Use back() and + front() with caution, for example: + + \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 4 + + Because Q3ValueVector manages memory dynamically, it is recommended + that you contruct a vector with an initial size. Inserting and + removing elements happens fastest when: + \list + \i Inserting or removing elements happens at the end() of the + vector; + \i The vector does not need to allocate additional memory. + \endlist + + By creating a Q3ValueVector with a sufficiently large initial size, + there will be less memory allocations. Do not use an initial size + that is too big, since it will still take time to construct all + the empty entries, and the extra space will be wasted if it is + never used. + + Because Q3ValueVector is value-based there is no need to be careful + about deleting elements in the vector. The vector holds its own + copies and will free them if the corresponding member or the + vector itself is deleted. You can force the vector to free all of + its items with clear(). + + Q3ValueVector is shared implicitly, which means it can be copied in + constant time. If multiple Q3ValueVector instances share the same + data and one needs to modify its contents, this modifying instance + makes a copy and modifies its private copy; it thus does not + affect the other instances. This is often called "copy on write". + If a Q3ValueVector is being used in a multi-threaded program, you + must protect all access to the vector. See QMutex. + + There are several ways to insert elements into the vector. The + push_back() function insert elements into the end of the vector, + and is usually fastest. The insert() function can be used to add + elements at specific positions within the vector. + + Items can be also be removed from the vector in several ways. + There are several variants of the erase() function which removes a + specific element, or range of elements, from the vector. + + Q3ValueVector stores its elements in contiguous memory. This means + that you can use a Q3ValueVector in any situation that requires an + array. +*/ + +/*! + \fn Q3ValueVector::Q3ValueVector() + + Constructs an empty vector without any elements. To create a + vector which reserves an initial amount of space for elements, use + \c Q3ValueVector(size_type n). +*/ + +/*! + \fn Q3ValueVector::Q3ValueVector( const Q3ValueVector<T>& v ) + + Constructs a copy of \a v. + + This operation costs O(1) time because Q3ValueVector is implicitly + shared. + + The first modification to the vector does takes O(n) time, because + the elements must be copied. +*/ + +/*! + \fn Q3ValueVector::Q3ValueVector( const std::vector<T>& v ) + + This operation costs O(n) time because \a v is copied. +*/ + +/*! + \fn Q3ValueVector::Q3ValueVector( QVector<T>::size_type n, const T& val ) + + Constructs a vector with an initial size of \a n elements. Each + element is initialized with the value of \a val. +*/ + +/*! + \fn Q3ValueVector<T>& Q3ValueVector::operator=( const Q3ValueVector<T>& v ) + + Assigns \a v to this vector and returns a reference to this vector. + + All iterators of the current vector become invalidated by this + operation. The cost of such an assignment is O(1) since + Q3ValueVector is implicitly shared. +*/ + +/*! + \fn Q3ValueVector<T>& Q3ValueVector::operator=( const std::vector<T>& v ) + + \overload + + Assigns \a v to this vector and returns a reference to this vector. + + All iterators of the current vector become invalidated by this + operation. The cost of this assignment is O(n) since \a v is + copied. +*/ + +/*! + \fn T &Q3ValueVector::at( int i , bool* ok ) + + Returns a reference to the element with index \a i. If \a ok is + non-null, and the index \a i is out of range, *\a ok is set to + FALSE and the returned reference is undefined. If the index \a i + is within the range of the vector, and \a ok is non-null, *\a ok + is set to TRUE and the returned reference is well defined. +*/ + +/*! + \fn const T &Q3ValueVector::at( int i , bool* ok ) const + + \overload + + Returns a const reference to the element with index \a i. If \a ok + is non-null, and the index \a i is out of range, *\a ok is set to + FALSE and the returned reference is undefined. If the index \a i + is within the range of the vector, and \a ok is non-null, *\a ok + is set to TRUE and the returned reference is well defined. +*/ + +/*! + \fn void Q3ValueVector::resize( int n, const T& val = T() ) + + Changes the size of the vector to \a n. If \a n is greater than + the current size(), elements are added to the end and initialized + with the value of \a val. If \a n is less than size(), elements + are removed from the end. If \a n is equal to size() nothing + happens. +*/ |