summaryrefslogtreecommitdiffstats
path: root/doc/src/q3valuevector.qdoc
diff options
context:
space:
mode:
authorLars Knoll <lars.knoll@nokia.com>2009-03-23 09:18:55 (GMT)
committerSimon Hausmann <simon.hausmann@nokia.com>2009-03-23 09:18:55 (GMT)
commite5fcad302d86d316390c6b0f62759a067313e8a9 (patch)
treec2afbf6f1066b6ce261f14341cf6d310e5595bc1 /doc/src/q3valuevector.qdoc
downloadQt-e5fcad302d86d316390c6b0f62759a067313e8a9.zip
Qt-e5fcad302d86d316390c6b0f62759a067313e8a9.tar.gz
Qt-e5fcad302d86d316390c6b0f62759a067313e8a9.tar.bz2
Long live Qt 4.5!
Diffstat (limited to 'doc/src/q3valuevector.qdoc')
-rw-r--r--doc/src/q3valuevector.qdoc274
1 files changed, 274 insertions, 0 deletions
diff --git a/doc/src/q3valuevector.qdoc b/doc/src/q3valuevector.qdoc
new file mode 100644
index 0000000..1af2bf3
--- /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.
+*/