summaryrefslogtreecommitdiffstats
path: root/src/corelib/tools
diff options
context:
space:
mode:
authorJason Barron <jbarron@trolltech.com>2009-08-18 06:34:18 (GMT)
committerJason Barron <jbarron@trolltech.com>2009-08-18 06:34:18 (GMT)
commitfd6740b6ade6e7f8e51a9cc558b723e7fae15ccf (patch)
treeaa2ba4ce64d047d73c29ab0616e8a89d352c3abd /src/corelib/tools
parentd24029e3d4639f1300e7a68858936911df969f69 (diff)
parent572e165dcb8cc8fcdfaa4ab9bdab050f6a6cc173 (diff)
downloadQt-fd6740b6ade6e7f8e51a9cc558b723e7fae15ccf.zip
Qt-fd6740b6ade6e7f8e51a9cc558b723e7fae15ccf.tar.gz
Qt-fd6740b6ade6e7f8e51a9cc558b723e7fae15ccf.tar.bz2
Merge commit 'qt/master'
Conflicts: doc/src/examples.qdoc doc/src/plugins-howto.qdoc doc/src/topics.qdoc examples/phonon/musicplayer/mainwindow.cpp src/3rdparty/freetype/src/base/ftobjs.c src/corelib/global/qglobal.h src/corelib/tools/qalgorithms.h src/corelib/tools/qshareddata.cpp src/corelib/tools/qsharedpointer.cpp src/corelib/tools/tools.pri src/corelib/xml/qxmlstream.h src/gui/painting/painting.pri src/gui/widgets/qdatetimeedit.cpp tests/auto/qdesktopservices/qdesktopservices.pro tests/auto/qgraphicsitem/tst_qgraphicsitem.cpp tests/auto/qtextcodec/test/test.pro
Diffstat (limited to 'src/corelib/tools')
-rw-r--r--src/corelib/tools/qalgorithms.h17
-rw-r--r--src/corelib/tools/qalgorithms.qdoc651
-rw-r--r--src/corelib/tools/qbytearray.cpp4
-rw-r--r--src/corelib/tools/qbytearraymatcher.cpp2
-rw-r--r--src/corelib/tools/qcache.qdoc244
-rw-r--r--src/corelib/tools/qchar.cpp4
-rw-r--r--src/corelib/tools/qdatetime.cpp6
-rw-r--r--src/corelib/tools/qeasingcurve.cpp2
-rw-r--r--src/corelib/tools/qhash.cpp4
-rw-r--r--src/corelib/tools/qiterator.qdoc1431
-rw-r--r--src/corelib/tools/qline.cpp4
-rw-r--r--src/corelib/tools/qlinkedlist.cpp2
-rw-r--r--src/corelib/tools/qlist.cpp (renamed from src/corelib/tools/qlistdata.cpp)2
-rw-r--r--src/corelib/tools/qlocale.cpp4
-rw-r--r--src/corelib/tools/qmap.cpp4
-rw-r--r--src/corelib/tools/qpair.qdoc229
-rw-r--r--src/corelib/tools/qpoint.cpp4
-rw-r--r--src/corelib/tools/qqueue.cpp2
-rw-r--r--src/corelib/tools/qrect.cpp4
-rw-r--r--src/corelib/tools/qregexp.cpp3
-rw-r--r--src/corelib/tools/qset.qdoc953
-rw-r--r--src/corelib/tools/qshareddata.cpp673
-rw-r--r--src/corelib/tools/qshareddata.h14
-rw-r--r--src/corelib/tools/qsharedpointer.cpp270
-rw-r--r--src/corelib/tools/qsharedpointer_impl.h76
-rw-r--r--src/corelib/tools/qsize.cpp4
-rw-r--r--src/corelib/tools/qstack.cpp2
-rw-r--r--src/corelib/tools/qstring.cpp10
-rw-r--r--src/corelib/tools/qstringbuilder.cpp8
-rw-r--r--src/corelib/tools/qstringlist.cpp4
-rw-r--r--src/corelib/tools/qstringmatcher.cpp2
-rw-r--r--src/corelib/tools/qtextboundaryfinder.cpp2
-rw-r--r--src/corelib/tools/qtimeline.cpp2
-rw-r--r--src/corelib/tools/qvarlengtharray.qdoc274
-rw-r--r--src/corelib/tools/qvector.cpp2
-rw-r--r--src/corelib/tools/tools.pri8
36 files changed, 4503 insertions, 424 deletions
diff --git a/src/corelib/tools/qalgorithms.h b/src/corelib/tools/qalgorithms.h
index d334a03..3e5c3cc 100644
--- a/src/corelib/tools/qalgorithms.h
+++ b/src/corelib/tools/qalgorithms.h
@@ -141,23 +141,6 @@ inline void qCount(const Container &container, const T &value, Size &n)
qCount(container.constBegin(), container.constEnd(), value, n);
}
-
-#if (defined Q_CC_MSVC && _MSC_VER < 1300) || defined(Q_CC_MWERKS)
-template <typename T>
-inline void qSwap(T &value1, T &value2)
-{
- qSwap_helper<T>(value1, value2, (T *)0);
-}
-#else
-template <typename T>
-inline void qSwap(T &value1, T &value2)
-{
- T t = value1;
- value1 = value2;
- value2 = t;
-}
-#endif
-
#ifdef qdoc
template <typename T>
LessThan qLess()
diff --git a/src/corelib/tools/qalgorithms.qdoc b/src/corelib/tools/qalgorithms.qdoc
new file mode 100644
index 0000000..f7b7798
--- /dev/null
+++ b/src/corelib/tools/qalgorithms.qdoc
@@ -0,0 +1,651 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (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 http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \headerfile <QtAlgorithms>
+ \title Generic Algorithms
+ \ingroup classlists
+
+ \brief The <QtAlgorithms> header provides generic template-based algorithms.
+
+ Qt provides a number of global template functions in \c
+ <QtAlgorithms> that work on containers and perform well-know
+ algorithms. You can use these algorithms with any \l {container
+ class} that provides STL-style iterators, including Qt's QList,
+ QLinkedList, QVector, QMap, and QHash classes.
+
+ These functions have taken their inspiration from similar
+ functions available in the STL \c <algorithm> header. Most of them
+ have a direct STL equivalent; for example, qCopyBackward() is the
+ same as STL's copy_backward() algorithm.
+
+ If STL is available on all your target platforms, you can use the
+ STL algorithms instead of their Qt counterparts. One reason why
+ you might want to use the STL algorithms is that STL provides
+ dozens and dozens of algorithms, whereas Qt only provides the most
+ important ones, making no attempt to duplicate functionality that
+ is already provided by the C++ standard.
+
+ Most algorithms take \l {STL-style iterators} as parameters. The
+ algorithms are generic in the sense that they aren't bound to a
+ specific iterator class; you can use them with any iterators that
+ meet a certain set of requirements.
+
+ Let's take the qFill() algorithm as an example. Unlike QVector,
+ QList has no fill() function that can be used to fill a list with
+ a particular value. If you need that functionality, you can use
+ qFill():
+
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 0
+
+ qFill() takes a begin iterator, an end iterator, and a value.
+ In the example above, we pass \c list.begin() and \c list.end()
+ as the begin and end iterators, but this doesn't have to be
+ the case:
+
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 1
+
+ Different algorithms can have different requirements for the
+ iterators they accept. For example, qFill() accepts two
+ \l {forward iterators}. The iterator types required are specified
+ for each algorithm. If an iterator of the wrong type is passed (for
+ example, if QList::ConstIterator is passed as an \l {output
+ iterator}), you will always get a compiler error, although not
+ necessarily a very informative one.
+
+ Some algorithms have special requirements on the value type
+ stored in the containers. For example, qEqual() requires that the
+ value type supports operator==(), which it uses to compare items.
+ Similarly, qDeleteAll() requires that the value type is a
+ non-const pointer type (for example, QWidget *). The value type
+ requirements are specified for each algorithm, and the compiler
+ will produce an error if a requirement isn't met.
+
+ \target binaryFind example
+
+ The generic algorithms can be used on other container classes
+ than those provided by Qt and STL. The syntax of STL-style
+ iterators is modeled after C++ pointers, so it's possible to use
+ plain arrays as containers and plain pointers as iterators. A
+ common idiom is to use qBinaryFind() together with two static
+ arrays: one that contains a list of keys, and another that
+ contains a list of associated values. For example, the following
+ code will look up an HTML entity (e.g., \c &amp;) in the \c
+ name_table array and return the corresponding Unicode value from
+ the \c value_table if the entity is recognized:
+
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 2
+
+ This kind of code is for advanced users only; for most
+ applications, a QMap- or QHash-based approach would work just as
+ well:
+
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 3
+
+ \section1 Types of Iterators
+
+ The algorithms have certain requirements on the iterator types
+ they accept, and these are specified individually for each
+ function. The compiler will produce an error if a requirement
+ isn't met.
+
+ \section2 Input Iterators
+
+ An \e{input iterator} is an iterator that can be used for reading
+ data sequentially from a container. It must provide the following
+ operators: \c{==} and \c{!=} for comparing two iterators, unary
+ \c{*} for retrieving the value stored in the item, and prefix
+ \c{++} for advancing to the next item.
+
+ The Qt containers' iterator types (const and non-const) are all
+ input iterators.
+
+ \section2 Output Iterators
+
+ An \e{output iterator} is an iterator that can be used for
+ writing data sequentially to a container or to some output
+ stream. It must provide the following operators: unary \c{*} for
+ writing a value (i.e., \c{*it = val}) and prefix \c{++} for
+ advancing to the next item.
+
+ The Qt containers' non-const iterator types are all output
+ iterators.
+
+ \section2 Forward Iterators
+
+ A \e{forward iterator} is an iterator that meets the requirements
+ of both input iterators and output iterators.
+
+ The Qt containers' non-const iterator types are all forward
+ iterators.
+
+ \section2 Bidirectional Iterators
+
+ A \e{bidirectional iterator} is an iterator that meets the
+ requirements of forward iterators but that in addition supports
+ prefix \c{--} for iterating backward.
+
+ The Qt containers' non-const iterator types are all bidirectional
+ iterators.
+
+ \section2 Random Access Iterators
+
+ The last category, \e{random access iterators}, is the most
+ powerful type of iterator. It supports all the requirements of a
+ bidirectional iterator, and supports the following operations:
+
+ \table
+ \row \i \c{i += n} \i advances iterator \c i by \c n positions
+ \row \i \c{i -= n} \i moves iterator \c i back by \c n positions
+ \row \i \c{i + n} or \c{n + i} \i returns the iterator for the item \c
+ n positions ahead of iterator \c i
+ \row \i \c{i - n} \i returns the iterator for the item \c n positions behind of iterator \c i
+ \row \i \c{i - j} \i returns the number of items between iterators \c i and \c j
+ \row \i \c{i[n]} \i same as \c{*(i + n)}
+ \row \i \c{i < j} \i returns true if iterator \c j comes after iterator \c i
+ \endtable
+
+ QList and QVector's non-const iterator types are random access iterators.
+
+ \sa {container classes}, <QtGlobal>
+*/
+
+/*! \fn OutputIterator qCopy(InputIterator begin1, InputIterator end1, OutputIterator begin2)
+ \relates <QtAlgorithms>
+
+ Copies the items from range [\a begin1, \a end1) to range [\a
+ begin2, ...), in the order in which they appear.
+
+ The item at position \a begin1 is assigned to that at position \a
+ begin2; the item at position \a begin1 + 1 is assigned to that at
+ position \a begin2 + 1; and so on.
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 4
+
+ \sa qCopyBackward(), {input iterators}, {output iterators}
+*/
+
+/*! \fn BiIterator2 qCopyBackward(BiIterator1 begin1, BiIterator1 end1, BiIterator2 end2)
+ \relates <QtAlgorithms>
+
+ Copies the items from range [\a begin1, \a end1) to range [...,
+ \a end2).
+
+ The item at position \a end1 - 1 is assigned to that at position
+ \a end2 - 1; the item at position \a end1 - 2 is assigned to that
+ at position \a end2 - 2; and so on.
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 5
+
+ \sa qCopy(), {bidirectional iterators}
+*/
+
+/*! \fn bool qEqual(InputIterator1 begin1, InputIterator1 end1, InputIterator2 begin2)
+ \relates <QtAlgorithms>
+
+ Compares the items in the range [\a begin1, \a end1) with the
+ items in the range [\a begin2, ...). Returns true if all the
+ items compare equal; otherwise returns false.
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 6
+
+ This function requires the item type (in the example above,
+ QString) to implement \c operator==().
+
+ \sa {input iterators}
+*/
+
+/*! \fn void qFill(ForwardIterator begin, ForwardIterator end, const T &value)
+ \relates <QtAlgorithms>
+
+ Fills the range [\a begin, \a end) with \a value.
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 7
+
+ \sa qCopy(), {forward iterators}
+*/
+
+/*! \fn void qFill(Container &container, const T &value)
+ \relates <QtAlgorithms>
+
+ \overload
+
+ This is the same as qFill(\a{container}.begin(), \a{container}.end(), \a value);
+*/
+
+/*! \fn InputIterator qFind(InputIterator begin, InputIterator end, const T &value)
+ \relates <QtAlgorithms>
+
+ Returns an iterator to the first occurrence of \a value in a
+ container in the range [\a begin, \a end). Returns \a end if \a
+ value isn't found.
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 8
+
+ This function requires the item type (in the example above,
+ QString) to implement \c operator==().
+
+ If the items in the range are in ascending order, you can get
+ faster results by using qLowerBound() or qBinaryFind() instead of
+ qFind().
+
+ \sa qBinaryFind(), {input iterators}
+*/
+
+/*! \fn void qFind(const Container &container, const T &value)
+ \relates <QtAlgorithms>
+
+ \overload
+
+ This is the same as qFind(\a{container}.begin(), \a{container}.end(), value);
+*/
+
+/*! \fn void qCount(InputIterator begin, InputIterator end, const T &value, Size &n)
+ \relates <QtAlgorithms>
+
+ Returns the number of occurrences of \a value in the range [\a begin, \a end),
+ which is returned in \a n. \a n is never initialized, the count is added to \a n.
+ It is the caller's responsibility to initialize \a n.
+
+ Example:
+
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 9
+
+ This function requires the item type (in the example above,
+ \c int) to implement \c operator==().
+
+ \sa {input iterators}
+*/
+
+/*! \fn void qCount(const Container &container, const T &value, Size &n)
+\relates <QtAlgorithms>
+
+\overload
+
+Instead of operating on iterators, as in the other overload, this function
+operates on the specified \a container to obtain the number of instances
+of \a value in the variable passed as a reference in argument \a n.
+*/
+
+/*! \fn void qSwap(T &var1, T &var2)
+ \relates <QtAlgorithms>
+
+ Exchanges the values of variables \a var1 and \a var2.
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 10
+*/
+
+/*! \fn void qSort(RandomAccessIterator begin, RandomAccessIterator end)
+ \relates <QtAlgorithms>
+
+ Sorts the items in range [\a begin, \a end) in ascending order
+ using the quicksort algorithm.
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 11
+
+ The sort algorithm is efficient on large data sets. It operates
+ in \l {linear-logarithmic time}, O(\e{n} log \e{n}).
+
+ This function requires the item type (in the example above,
+ \c{int}) to implement \c operator<().
+
+ If neither of the two items is "less than" the other, the items are
+ taken to be equal. It is then undefined which one of the two
+ items will appear before the other after the sort.
+
+ \sa qStableSort(), {random access iterators}
+*/
+
+/*! \fn void qSort(RandomAccessIterator begin, RandomAccessIterator end, LessThan lessThan)
+ \relates <QtAlgorithms>
+
+ \overload
+
+ Uses the \a lessThan function instead of \c operator<() to
+ compare the items.
+
+ For example, here's how to sort the strings in a QStringList
+ in case-insensitive alphabetical order:
+
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 12
+
+ To sort values in reverse order, pass
+ \l{qGreater()}{qGreater<T>()} as the \a lessThan parameter. For
+ example:
+
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 13
+
+ If neither of the two items is "less than" the other, the items are
+ taken to be equal. It is then undefined which one of the two
+ items will appear before the other after the sort.
+
+ An alternative to using qSort() is to put the items to sort in a
+ QMap, using the sort key as the QMap key. This is often more
+ convenient than defining a \a lessThan function. For example, the
+ following code shows how to sort a list of strings case
+ insensitively using QMap:
+
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 14
+
+ \sa QMap
+*/
+
+/*! \fn void qSort(Container &container)
+ \relates <QtAlgorithms>
+
+ \overload
+
+ This is the same as qSort(\a{container}.begin(), \a{container}.end());
+*/
+
+/*!
+ \fn void qStableSort(RandomAccessIterator begin, RandomAccessIterator end)
+ \relates <QtAlgorithms>
+
+ Sorts the items in range [\a begin, \a end) in ascending order
+ using a stable sorting algorithm.
+
+ If neither of the two items is "less than" the other, the items are
+ taken to be equal. The item that appeared before the other in the
+ original container will still appear first after the sort. This
+ property is often useful when sorting user-visible data.
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 15
+
+ The sort algorithm is efficient on large data sets. It operates
+ in \l {linear-logarithmic time}, O(\e{n} log \e{n}).
+
+ This function requires the item type (in the example above,
+ \c{int}) to implement \c operator<().
+
+ \sa qSort(), {random access iterators}
+*/
+
+/*!
+ \fn void qStableSort(RandomAccessIterator begin, RandomAccessIterator end, LessThan lessThan)
+ \relates <QtAlgorithms>
+
+ \overload
+
+ Uses the \a lessThan function instead of \c operator<() to
+ compare the items.
+
+ For example, here's how to sort the strings in a QStringList
+ in case-insensitive alphabetical order:
+
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 16
+
+ Note that earlier versions of Qt allowed using a lessThan function that took its
+ arguments by non-const reference. From 4.3 and on this is no longer possible,
+ the arguments has to be passed by const reference or value.
+
+ To sort values in reverse order, pass
+ \l{qGreater()}{qGreater<T>()} as the \a lessThan parameter. For
+ example:
+
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 17
+
+ If neither of the two items is "less than" the other, the items are
+ taken to be equal. The item that appeared before the other in the
+ original container will still appear first after the sort. This
+ property is often useful when sorting user-visible data.
+*/
+
+/*!
+ \fn void qStableSort(Container &container)
+ \relates <QtAlgorithms>
+
+ \overload
+
+ This is the same as qStableSort(\a{container}.begin(), \a{container}.end());
+*/
+
+/*! \fn RandomAccessIterator qLowerBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value)
+ \relates <QtAlgorithms>
+
+ Performs a binary search of the range [\a begin, \a end) and
+ returns the position of the first ocurrence of \a value. If no
+ such item is found, returns the position where it should be
+ inserted.
+
+ The items in the range [\a begin, \e end) must be sorted in
+ ascending order; see qSort().
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 18
+
+ This function requires the item type (in the example above,
+ \c{int}) to implement \c operator<().
+
+ qLowerBound() can be used in conjunction with qUpperBound() to
+ iterate over all occurrences of the same value:
+
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 19
+
+ \sa qUpperBound(), qBinaryFind()
+*/
+
+/*!
+ \fn RandomAccessIterator qLowerBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value, LessThan lessThan)
+ \relates <QtAlgorithms>
+
+ \overload
+
+ Uses the \a lessThan function instead of \c operator<() to
+ compare the items.
+
+ Note that the items in the range must be sorted according to the order
+ specified by the \a lessThan object.
+*/
+
+/*!
+ \fn void qLowerBound(const Container &container, const T &value)
+ \relates <QtAlgorithms>
+
+ \overload
+
+ For read-only iteration over containers, this function is broadly equivalent to
+ qLowerBound(\a{container}.begin(), \a{container}.end(), value). However, since it
+ returns a const iterator, you cannot use it to modify the container; for example,
+ to insert items.
+*/
+
+/*! \fn RandomAccessIterator qUpperBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value)
+ \relates <QtAlgorithms>
+
+ Performs a binary search of the range [\a begin, \a end) and
+ returns the position of the one-past-the-last occurrence of \a
+ value. If no such item is found, returns the position where the
+ item should be inserted.
+
+ The items in the range [\a begin, \e end) must be sorted in
+ ascending order; see qSort().
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 20
+
+ This function requires the item type (in the example above,
+ \c{int}) to implement \c operator<().
+
+ qUpperBound() can be used in conjunction with qLowerBound() to
+ iterate over all occurrences of the same value:
+
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 21
+
+ \sa qLowerBound(), qBinaryFind()
+*/
+
+/*!
+ \fn RandomAccessIterator qUpperBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value, LessThan lessThan)
+ \relates <QtAlgorithms>
+
+ \overload
+
+ Uses the \a lessThan function instead of \c operator<() to
+ compare the items.
+
+ Note that the items in the range must be sorted according to the order
+ specified by the \a lessThan object.
+*/
+
+/*!
+ \fn void qUpperBound(const Container &container, const T &value)
+ \relates <QtAlgorithms>
+
+ \overload
+
+ This is the same as qUpperBound(\a{container}.begin(), \a{container}.end(), value);
+*/
+
+
+/*! \fn RandomAccessIterator qBinaryFind(RandomAccessIterator begin, RandomAccessIterator end, const T &value)
+ \relates <QtAlgorithms>
+
+ Performs a binary search of the range [\a begin, \a end) and
+ returns the position of an occurrence of \a value. If there are
+ no occurrences of \a value, returns \a end.
+
+ The items in the range [\a begin, \a end) must be sorted in
+ ascending order; see qSort().
+
+ If there are many occurrences of the same value, any one of them
+ could be returned. Use qLowerBound() or qUpperBound() if you need
+ finer control.
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 22
+
+ This function requires the item type (in the example above,
+ QString) to implement \c operator<().
+
+ See the \l{<QtAlgorithms>#binaryFind example}{detailed
+ description} for an example usage.
+
+ \sa qLowerBound(), qUpperBound(), {random access iterators}
+*/
+
+/*! \fn RandomAccessIterator qBinaryFind(RandomAccessIterator begin, RandomAccessIterator end, const T &value, LessThan lessThan)
+ \relates <QtAlgorithms>
+
+ \overload
+
+ Uses the \a lessThan function instead of \c operator<() to
+ compare the items.
+
+ Note that the items in the range must be sorted according to the order
+ specified by the \a lessThan object.
+*/
+
+/*!
+ \fn void qBinaryFind(const Container &container, const T &value)
+ \relates <QtAlgorithms>
+
+ \overload
+
+ This is the same as qBinaryFind(\a{container}.begin(), \a{container}.end(), value);
+*/
+
+
+/*!
+ \fn void qDeleteAll(ForwardIterator begin, ForwardIterator end)
+ \relates <QtAlgorithms>
+
+ Deletes all the items in the range [\a begin, \a end) using the
+ C++ \c delete operator. The item type must be a pointer type (for
+ example, \c{QWidget *}).
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 23
+
+ Notice that qDeleteAll() doesn't remove the items from the
+ container; it merely calls \c delete on them. In the example
+ above, we call clear() on the container to remove the items.
+
+ This function can also be used to delete items stored in
+ associative containers, such as QMap and QHash. Only the objects
+ stored in each container will be deleted by this function; objects
+ used as keys will not be deleted.
+
+ \sa {forward iterators}
+*/
+
+/*!
+ \fn void qDeleteAll(const Container &c)
+ \relates <QtAlgorithms>
+
+ \overload
+
+ This is the same as qDeleteAll(\a{c}.begin(), \a{c}.end()).
+*/
+
+/*! \fn LessThan qLess()
+ \relates <QtAlgorithms>
+
+ Returns a functional object, or functor, that can be passed to qSort()
+ or qStableSort().
+
+ Example:
+
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 24
+
+ \sa {qGreater()}{qGreater<T>()}
+*/
+
+/*! \fn LessThan qGreater()
+ \relates <QtAlgorithms>
+
+ Returns a functional object, or functor, that can be passed to qSort()
+ or qStableSort().
+
+ Example:
+
+ \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 25
+
+ \sa {qLess()}{qLess<T>()}
+*/
diff --git a/src/corelib/tools/qbytearray.cpp b/src/corelib/tools/qbytearray.cpp
index 9600579..316aab7 100644
--- a/src/corelib/tools/qbytearray.cpp
+++ b/src/corelib/tools/qbytearray.cpp
@@ -594,8 +594,8 @@ QByteArray::Data QByteArray::shared_empty = { Q_BASIC_ATOMIC_INITIALIZER(1),
\ingroup tools
\ingroup shared
- \ingroup text
- \mainclass
+ \ingroup string-processing
+
\reentrant
QByteArray can be used to store both raw bytes (including '\\0's)
diff --git a/src/corelib/tools/qbytearraymatcher.cpp b/src/corelib/tools/qbytearraymatcher.cpp
index 1c10a4f..37cb9bb 100644
--- a/src/corelib/tools/qbytearraymatcher.cpp
+++ b/src/corelib/tools/qbytearraymatcher.cpp
@@ -94,7 +94,7 @@ static inline int bm_find(const uchar *cc, int l, int index, const uchar *puc, u
can be quickly matched in a byte array.
\ingroup tools
- \ingroup text
+ \ingroup string-processing
This class is useful when you have a sequence of bytes that you
want to repeatedly match against some byte arrays (perhaps in a
diff --git a/src/corelib/tools/qcache.qdoc b/src/corelib/tools/qcache.qdoc
new file mode 100644
index 0000000..4c008fa
--- /dev/null
+++ b/src/corelib/tools/qcache.qdoc
@@ -0,0 +1,244 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (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 http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \class QCache
+ \brief The QCache class is a template class that provides a cache.
+
+ \ingroup tools
+ \ingroup shared
+
+ \reentrant
+
+ QCache\<Key, T\> defines a cache that stores objects of type T
+ associated with keys of type Key. For example, here's the
+ definition of a cache that stores objects of type Employee
+ associated with an integer key:
+
+ \snippet doc/src/snippets/code/doc_src_qcache.qdoc 0
+
+ Here's how to insert an object in the cache:
+
+ \snippet doc/src/snippets/code/doc_src_qcache.qdoc 1
+
+ The advantage of using QCache over some other key-based data
+ structure (such as QMap or QHash) is that QCache automatically
+ takes ownership of the objects that are inserted into the cache and
+ deletes them to make room for new objects, if necessary. When
+ inserting an object into the cache, you can specify a \e{cost},
+ which should bear some approximate relationship to the amount of
+ memory taken by the object. When the sum of all objects' costs
+ (totalCost()) exceeds the cache's limit (maxCost()), QCache starts
+ deleting objects in the cache to keep under the limit, starting with
+ less recently accessed objects.
+
+ By default, QCache's maxCost() is 100. You can specify a
+ different value in the QCache constructor:
+
+ \snippet doc/src/snippets/code/doc_src_qcache.qdoc 2
+
+ Each time you call insert(), you can specify a cost as third
+ argument (after the key and a pointer to the object to insert).
+ After the call, the inserted object is owned by the QCache, which
+ may delete it at any time to make room for other objects.
+
+ To look up objects in the cache, use object() or
+ operator[](). This function looks up an object by its key, and
+ returns either a pointer to the cached object (which is owned by
+ the cache) or 0.
+
+ If you want to remove an object from the cache for a particular key,
+ call remove(). This will also delete the object. If you want to
+ remove an object from the cache without the QCache deleting it, use
+ take().
+
+ \sa QPixmapCache, QHash, QMap
+*/
+
+/*! \fn QCache::QCache(int maxCost = 100)
+
+ Constructs a cache whose contents will never have a total cost
+ greater than \a maxCost.
+*/
+
+/*! \fn QCache::~QCache()
+
+ Destroys the cache. Deletes all the objects in the cache.
+*/
+
+/*! \fn int QCache::maxCost() const
+
+ Returns the maximum allowed total cost of the cache.
+
+ \sa setMaxCost(), totalCost()
+*/
+
+/*! \fn void QCache::setMaxCost(int cost)
+
+ Sets the maximum allowed total cost of the cache to \a cost. If
+ the current total cost is greater than \a cost, some objects are
+ deleted immediately.
+
+ \sa maxCost(), totalCost()
+*/
+
+/*! \fn int QCache::totalCost() const
+
+ Returns the total cost of the objects in the cache.
+
+ This value is normally below maxCost(), but QCache makes an
+ exception for Qt's \l{implicitly shared} classes. If a cached
+ object shares its internal data with another instance, QCache may
+ keep the object lying around, possibly contributing to making
+ totalCost() larger than maxCost().
+
+ \sa setMaxCost()
+*/
+
+/*! \fn int QCache::size() const
+
+ Returns the number of objects in the cache.
+
+ \sa isEmpty()
+*/
+
+/*! \fn int QCache::count() const
+
+ Same as size().
+*/
+
+/*! \fn bool QCache::isEmpty() const
+
+ Returns true if the cache contains no objects; otherwise
+ returns false.
+
+ \sa size()
+*/
+
+/*! \fn QList<Key> QCache::keys() const
+
+ Returns a list of the keys in the cache.
+*/
+
+/*! \fn void QCache::clear();
+
+ Deletes all the objects in the cache.
+
+ \sa remove(), take()
+*/
+
+
+/*! \fn bool QCache::insert(const Key &key, T *object, int cost = 1)
+
+ Inserts \a object into the cache with key \a key and
+ associated cost \a cost. Any object with the same key already in
+ the cache will be removed.
+
+ After this call, \a object is owned by the QCache and may be
+ deleted at any time. In particular, if \a cost is greater than
+ maxCost(), the object will be deleted immediately.
+
+ The function returns true if the object was inserted into the
+ cache; otherwise it returns false.
+
+ \sa take(), remove()
+*/
+
+/*! \fn T *QCache::object(const Key &key) const
+
+ Returns the object associated with key \a key, or 0 if the key does
+ not exist in the cache.
+
+ \warning The returned object is owned by QCache and may be
+ deleted at any time.
+
+ \sa take(), remove()
+*/
+
+/*! \fn bool QCache::contains(const Key &key) const
+
+ Returns true if the cache contains an object associated with key \a
+ key; otherwise returns false.
+
+ \sa take(), remove()
+*/
+
+/*! \fn T *QCache::operator[](const Key &key) const
+
+ Returns the object associated with key \a key, or 0 if the key does
+ not exist in the cache.
+
+ This is the same as object().
+
+ \warning The returned object is owned by QCache and may be
+ deleted at any time.
+*/
+
+/*! \fn bool QCache::remove(const Key &key)
+
+ Deletes the object associated with key \a key. Returns true if the
+ object was found in the cache; otherwise returns false.
+
+ \sa take(), clear()
+*/
+
+/*! \fn T *QCache::take(const Key &key)
+
+ Takes the object associated with key \a key out of the cache
+ without deleting it. Returns a pointer to the object taken out, or
+ 0 if the key does not exist in the cache.
+
+ The ownership of the returned object is passed to the caller.
+
+ \sa remove()
+*/
+
+/*!
+ \fn QCache::QCache(int maxCost, int dummy)
+
+ Use QCache(int) instead.
+*/
+
+/*!
+ \fn T *QCache::find(const Key &key) const
+
+ Use object() instead.
+*/
diff --git a/src/corelib/tools/qchar.cpp b/src/corelib/tools/qchar.cpp
index ab84603..e9f9552 100644
--- a/src/corelib/tools/qchar.cpp
+++ b/src/corelib/tools/qchar.cpp
@@ -70,7 +70,7 @@ QT_BEGIN_NAMESPACE
/*! \class QLatin1Char
\brief The QLatin1Char class provides an 8-bit ASCII/Latin-1 character.
- \ingroup text
+ \ingroup string-processing
This class is only useful to avoid the codec for C strings business
in the QChar(ch) constructor. You can avoid it by writing
@@ -104,7 +104,7 @@ QT_BEGIN_NAMESPACE
\class QChar
\brief The QChar class provides a 16-bit Unicode character.
- \ingroup text
+ \ingroup string-processing
\reentrant
In Qt, Unicode characters are 16-bit entities without any markup
diff --git a/src/corelib/tools/qdatetime.cpp b/src/corelib/tools/qdatetime.cpp
index 0758afa..8b9d202 100644
--- a/src/corelib/tools/qdatetime.cpp
+++ b/src/corelib/tools/qdatetime.cpp
@@ -193,8 +193,6 @@ static QString fmtDateTime(const QString& f, const QTime* dt = 0, const QDate* d
\reentrant
\brief The QDate class provides date functions.
- \ingroup time
- \mainclass
A QDate object contains a calendar date, i.e. year, month, and day
numbers, in the Gregorian calendar. (see \l{QDate G and J} {Use of
@@ -1411,8 +1409,6 @@ void QDate::julianToGregorian(uint jd, int &y, int &m, int &d)
\brief The QTime class provides clock time functions.
- \ingroup time
- \mainclass
A QTime object contains a clock time, i.e. the number of hours,
minutes, seconds, and milliseconds since midnight. It can read the
@@ -2075,8 +2071,6 @@ int QTime::elapsed() const
\reentrant
\brief The QDateTime class provides date and time functions.
- \ingroup time
- \mainclass
A QDateTime object contains a calendar date and a clock time (a
"datetime"). It is a combination of the QDate and QTime classes.
diff --git a/src/corelib/tools/qeasingcurve.cpp b/src/corelib/tools/qeasingcurve.cpp
index 5cc8080..e84e3f0 100644
--- a/src/corelib/tools/qeasingcurve.cpp
+++ b/src/corelib/tools/qeasingcurve.cpp
@@ -301,7 +301,7 @@
#ifndef QT_NO_DEBUG_STREAM
#include <QtCore/qdebug.h>
-#include <QtCore/QString>
+#include <QtCore/qstring.h>
#endif
QT_BEGIN_NAMESPACE
diff --git a/src/corelib/tools/qhash.cpp b/src/corelib/tools/qhash.cpp
index 308ba23..8bc9f29 100644
--- a/src/corelib/tools/qhash.cpp
+++ b/src/corelib/tools/qhash.cpp
@@ -539,7 +539,7 @@ void QHashData::checkSanity()
\ingroup tools
\ingroup shared
- \mainclass
+
\reentrant
QHash\<Key, T\> is one of Qt's generic \l{container classes}. It
@@ -1672,7 +1672,7 @@ void QHashData::checkSanity()
\ingroup tools
\ingroup shared
- \mainclass
+
\reentrant
QMultiHash\<Key, T\> is one of Qt's generic \l{container classes}.
diff --git a/src/corelib/tools/qiterator.qdoc b/src/corelib/tools/qiterator.qdoc
new file mode 100644
index 0000000..c767be3
--- /dev/null
+++ b/src/corelib/tools/qiterator.qdoc
@@ -0,0 +1,1431 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (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 http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \class QListIterator
+ \inmodule QtCore
+
+ \brief The QListIterator class provides a Java-style const iterator for QList and QQueue.
+
+ QList has both \l{Java-style iterators} and \l{STL-style
+ iterators}. The Java-style iterators are more high-level and
+ easier to use than the STL-style iterators; on the other hand,
+ they are slightly less efficient.
+
+ An alternative to using iterators is to use index positions. Most
+ QList member functions take an index as their first parameter,
+ making it possible to access, modify, and remove items without
+ using iterators.
+
+ QListIterator\<T\> allows you to iterate over a QList\<T\> (or a
+ QQueue\<T\>). If you want to modify the list as you iterate over
+ it, use QMutableListIterator\<T\> instead.
+
+ The QListIterator constructor takes a QList as argument. After
+ construction, the iterator is located at the very beginning of
+ the list (before the first item). Here's how to iterate over all
+ the elements sequentially:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 0
+
+ The next() function returns the next item in the list and
+ advances the iterator. Unlike STL-style iterators, Java-style
+ iterators point \e between items rather than directly \e at
+ items. The first call to next() advances the iterator to the
+ position between the first and second item, and returns the first
+ item; the second call to next() advances the iterator to the
+ position between the second and third item, and returns the second
+ item; and so on.
+
+ \img javaiterators1.png
+
+ Here's how to iterate over the elements in reverse order:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 1
+
+ If you want to find all occurrences of a particular value, use
+ findNext() or findPrevious() in a loop.
+
+ Multiple iterators can be used on the same list. If the list is
+ modified while a QListIterator is active, the QListIterator will
+ continue iterating over the original list, ignoring the modified
+ copy.
+
+ \sa QMutableListIterator, QList::const_iterator
+*/
+
+/*!
+ \class QLinkedListIterator
+ \inmodule QtCore
+
+ \brief The QLinkedListIterator class provides a Java-style const iterator for QLinkedList.
+
+ QLinkedList has both \l{Java-style iterators} and
+ \l{STL-style iterators}. The Java-style iterators are more
+ high-level and easier to use than the STL-style iterators; on the
+ other hand, they are slightly less efficient.
+
+ QLinkedListIterator\<T\> allows you to iterate over a
+ QLinkedList\<T\>. If you want to modify the list as you iterate
+ over it, use QMutableLinkedListIterator\<T\> instead.
+
+ The QLinkedListIterator constructor takes a QLinkedList as
+ argument. After construction, the iterator is located at the very
+ beginning of the list (before the first item). Here's how to
+ iterate over all the elements sequentially:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 2
+
+ The next() function returns the next item in the list and
+ advances the iterator. Unlike STL-style iterators, Java-style
+ iterators point \e between items rather than directly \e at
+ items. The first call to next() advances the iterator to the
+ position between the first and second item, and returns the first
+ item; the second call to next() advances the iterator to the
+ position between the second and third item, and returns the second
+ item; and so on.
+
+ \img javaiterators1.png
+
+ Here's how to iterate over the elements in reverse order:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 3
+
+ If you want to find all occurrences of a particular value, use
+ findNext() or findPrevious() in a loop.
+
+ Multiple iterators can be used on the same list. If the list is
+ modified while a QLinkedListIterator is active, the
+ QLinkedListIterator will continue iterating over the original
+ list, ignoring the modified copy.
+
+ \sa QMutableLinkedListIterator, QLinkedList::const_iterator
+*/
+
+/*!
+ \class QVectorIterator
+ \inmodule QtCore
+ \brief The QVectorIterator class provides a Java-style const iterator for QVector and QStack.
+
+ QVector has both \l{Java-style iterators} and \l{STL-style
+ iterators}. The Java-style iterators are more high-level and
+ easier to use than the STL-style iterators; on the other hand,
+ they are slightly less efficient.
+
+ An alternative to using iterators is to use index positions. Most
+ QVector member functions take an index as their first parameter,
+ making it possible to access, insert, and remove items without
+ using iterators.
+
+ QVectorIterator\<T\> allows you to iterate over a QVector\<T\>
+ (or a QStack\<T\>). If you want to modify the vector as you
+ iterate over it, use QMutableVectorIterator\<T\> instead.
+
+ The QVectorIterator constructor takes a QVector as argument.
+ After construction, the iterator is located at the very beginning
+ of the vector (before the first item). Here's how to iterate over
+ all the elements sequentially:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 4
+
+ The next() function returns the next item in the vector and
+ advances the iterator. Unlike STL-style iterators, Java-style
+ iterators point \e between items rather than directly \e at
+ items. The first call to next() advances the iterator to the
+ position between the first and second item, and returns the first
+ item; the second call to next() advances the iterator to the
+ position between the second and third item, returning the second
+ item; and so on.
+
+ \img javaiterators1.png
+
+ Here's how to iterate over the elements in reverse order:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 5
+
+ If you want to find all occurrences of a particular value, use
+ findNext() or findPrevious() in a loop.
+
+ Multiple iterators can be used on the same vector. If the vector
+ is modified while a QVectorIterator is active, the QVectorIterator
+ will continue iterating over the original vector, ignoring the
+ modified copy.
+
+ \sa QMutableVectorIterator, QVector::const_iterator
+*/
+
+/*!
+ \class QSetIterator
+ \inmodule QtCore
+ \brief The QSetIterator class provides a Java-style const iterator for QSet.
+
+ QSet supports both \l{Java-style iterators} and \l{STL-style
+ iterators}. The Java-style iterators are more high-level and
+ easier to use than the STL-style iterators; on the other hand,
+ they are slightly less efficient.
+
+ QSetIterator\<T\> allows you to iterate over a QSet\<T\>. If you
+ want to modify the set as you iterate over it, use
+ QMutableSetIterator\<T\> instead.
+
+ The constructor takes a QSet as argument. After construction, the
+ iterator is located at the very beginning of the set (before
+ the first item). Here's how to iterate over all the elements
+ sequentially:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 6
+
+ The next() function returns the next item in the set and
+ advances the iterator. Unlike STL-style iterators, Java-style
+ iterators point \e between items rather than directly \e at
+ items. The first call to next() advances the iterator to the
+ position between the first and second item, and returns the first
+ item; the second call to next() advances the iterator to the
+ position between the second and third item, returning the second
+ item; and so on.
+
+ \img javaiterators1.png
+
+ Here's how to iterate over the elements in reverse order:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 7
+
+ If you want to find all occurrences of a particular value, use
+ findNext() or findPrevious() in a loop.
+
+ Multiple iterators can be used on the same set. If the set
+ is modified while a QSetIterator is active, the QSetIterator
+ will continue iterating over the original set, ignoring the
+ modified copy.
+
+ \sa QMutableSetIterator, QSet::const_iterator
+*/
+
+/*!
+ \class QMutableListIterator
+ \inmodule QtCore
+
+ \brief The QMutableListIterator class provides a Java-style non-const iterator for QList and QQueue.
+
+ QList has both \l{Java-style iterators} and \l{STL-style
+ iterators}. The Java-style iterators are more high-level and
+ easier to use than the STL-style iterators; on the other hand,
+ they are slightly less efficient.
+
+ An alternative to using iterators is to use index positions. Most
+ QList member functions take an index as their first parameter,
+ making it possible to access, insert, and remove items without
+ using iterators.
+
+ QMutableListIterator\<T\> allows you to iterate over a QList\<T\>
+ (or a QQueue\<T\>) and modify the list. If you don't want to
+ modify the list (or have a const QList), use the slightly faster
+ QListIterator\<T\> instead.
+
+ The QMutableListIterator constructor takes a QList as argument.
+ After construction, the iterator is located at the very beginning
+ of the list (before the first item). Here's how to iterate over
+ all the elements sequentially:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 8
+
+ The next() function returns the next item in the list and
+ advances the iterator. Unlike STL-style iterators, Java-style
+ iterators point \e between items rather than directly \e at
+ items. The first call to next() advances the iterator to the
+ position between the first and second item, and returns the first
+ item; the second call to next() advances the iterator to the
+ position between the second and third item, returning the second
+ item; and so on.
+
+ \img javaiterators1.png
+
+ Here's how to iterate over the elements in reverse order:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 9
+
+ If you want to find all occurrences of a particular value, use
+ findNext() or findPrevious() in a loop.
+
+ If you want to remove items as you iterate over the list, use
+ remove(). If you want to modify the value of an item, use
+ setValue(). If you want to insert a new item in the list, use
+ insert().
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 10
+
+ The example traverses a list, replacing negative numbers with
+ their absolute values, and eliminating zeroes.
+
+ Only one mutable iterator can be active on a given list at any
+ time. Furthermore, no changes should be done directly to the list
+ while the iterator is active (as opposed to through the
+ iterator), since this could invalidate the iterator and lead to
+ undefined behavior.
+
+ \sa QListIterator, QList::iterator
+*/
+
+/*!
+ \class QMutableLinkedListIterator
+ \inmodule QtCore
+
+ \brief The QMutableLinkedListIterator class provides a Java-style non-const iterator for QLinkedList.
+
+ QLinkedList has both \l{Java-style iterators} and
+ \l{STL-style iterators}. The Java-style iterators are more
+ high-level and easier to use than the STL-style iterators; on the
+ other hand, they are slightly less efficient.
+
+ QMutableLinkedListIterator\<T\> allows you to iterate over a
+ QLinkedList\<T\> and modify the list. If you don't want to modify
+ the list (or have a const QLinkedList), use the slightly faster
+ QLinkedListIterator\<T\> instead.
+
+ The QMutableLinkedListIterator constructor takes a QLinkedList as
+ argument. After construction, the iterator is located at the very
+ beginning of the list (before the first item). Here's how to
+ iterate over all the elements sequentially:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 11
+
+ The next() function returns the next item in the list and
+ advances the iterator. Unlike STL-style iterators, Java-style
+ iterators point \e between items rather than directly \e at
+ items. The first call to next() advances the iterator to the
+ position between the first and second item, and returns the first
+ item; the second call to next() advances the iterator to the
+ position between the second and third item, returning the second
+ item; and so on.
+
+ \img javaiterators1.png
+
+ Here's how to iterate over the elements in reverse order:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 12
+
+ If you want to find all occurrences of a particular value, use
+ findNext() or findPrevious() in a loop.
+
+ If you want to remove items as you iterate over the list, use
+ remove(). If you want to modify the value of an item, use
+ setValue(). If you want to insert a new item in the list, use
+ insert().
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 13
+
+ The example traverses a list, replacing negative numbers with
+ their absolute values, and eliminating zeroes.
+
+ Only one mutable iterator can be active on a given list at any
+ time. Furthermore, no changes should be done directly to the list
+ while the iterator is active (as opposed to through the
+ iterator), since this could invalidate the iterator and lead to
+ undefined behavior.
+
+ \sa QLinkedListIterator, QLinkedList::iterator
+*/
+
+/*!
+ \class QMutableVectorIterator
+ \inmodule QtCore
+
+ \brief The QMutableVectorIterator class provides a Java-style non-const iterator for QVector and QStack.
+
+ QVector has both \l{Java-style iterators} and \l{STL-style
+ iterators}. The Java-style iterators are more high-level and
+ easier to use than the STL-style iterators; on the other hand,
+ they are slightly less efficient.
+
+ An alternative to using iterators is to use index positions. Most
+ QVector member functions take an index as their first parameter,
+ making it possible to access, insert, and remove items without
+ using iterators.
+
+ QMutableVectorIterator\<T\> allows you to iterate over a
+ QVector\<T\> and modify the vector. If you don't want to modify
+ the vector (or have a const QVector), use the slightly faster
+ QVectorIterator\<T\> instead.
+
+ The QMutableVectorIterator constructor takes a QVector as
+ argument. After construction, the iterator is located at the very
+ beginning of the list (before the first item). Here's how to
+ iterate over all the elements sequentially:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 14
+
+ The next() function returns the next item in the vector and
+ advances the iterator. Unlike STL-style iterators, Java-style
+ iterators point \e between items rather than directly \e at
+ items. The first call to next() advances the iterator to the
+ position between the first and second item, and returns the first
+ item; the second call to next() advances the iterator to the
+ position between the second and third item, returning the second
+ item; and so on.
+
+ \img javaiterators1.png
+
+ Here's how to iterate over the elements in reverse order:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 15
+
+ If you want to find all occurrences of a particular value, use
+ findNext() or findPrevious() in a loop.
+
+ If you want to remove items as you iterate over the vector, use
+ remove(). If you want to modify the value of an item, use
+ setValue(). If you want to insert a new item in the vector, use
+ insert().
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 16
+
+ The example traverses a vector, replacing negative numbers with
+ their absolute values, and eliminating zeroes.
+
+ Only one mutable iterator can be active on a given vector at any
+ time. Furthermore, no changes should be done directly to the
+ vector while the iterator is active (as opposed to through the
+ iterator), since this could invalidate the iterator and lead to
+ undefined behavior.
+
+ \sa QVectorIterator, QVector::iterator
+*/
+
+/*!
+ \class QMutableSetIterator
+ \inmodule QtCore
+ \since 4.2
+
+ \brief The QMutableSetIterator class provides a Java-style non-const iterator for QSet.
+
+ QSet has both \l{Java-style iterators} and \l{STL-style
+ iterators}. The Java-style iterators are more high-level and
+ easier to use than the STL-style iterators; on the other hand,
+ they are slightly less efficient.
+
+ QMutableSetIterator\<T\> allows you to iterate over a QSet\<T\>
+ and remove items from the set as you iterate. If you don't want
+ to modify the set (or have a const QSet), use the slightly faster
+ QSetIterator\<T\> instead.
+
+ The QMutableSetIterator constructor takes a QSet as argument.
+ After construction, the iterator is located at the very beginning
+ of the set (before the first item). Here's how to iterate over
+ all the elements sequentially:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 17
+
+ The next() function returns the next item in the set and
+ advances the iterator. Unlike STL-style iterators, Java-style
+ iterators point \e between items rather than directly \e at
+ items. The first call to next() advances the iterator to the
+ position between the first and second item, and returns the first
+ item; the second call to next() advances the iterator to the
+ position between the second and third item, returning the second
+ item; and so on.
+
+ \img javaiterators1.png
+
+ Here's how to iterate over the elements in reverse order:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 18
+
+ If you want to remove items as you iterate over the set, use
+ remove().
+
+ Only one mutable iterator can be active on a given set at any
+ time. Furthermore, no changes should be done directly to the set
+ while the iterator is active (as opposed to through the
+ iterator), since this could invalidate the iterator and lead to
+ undefined behavior.
+
+ \sa QSetIterator, QSet::iterator
+*/
+
+/*!
+ \fn QListIterator::QListIterator(const QList<T> &list)
+ \fn QLinkedListIterator::QLinkedListIterator(const QLinkedList<T> &list)
+ \fn QMutableListIterator::QMutableListIterator(QList<T> &list)
+ \fn QMutableLinkedListIterator::QMutableLinkedListIterator(QLinkedList<T> &list)
+
+ Constructs an iterator for traversing \a list. The iterator is
+ set to be at the front of the list (before the first item).
+
+ \sa operator=()
+*/
+
+/*!
+ \fn QVectorIterator::QVectorIterator(const QVector<T> &vector)
+ \fn QMutableVectorIterator::QMutableVectorIterator(QVector<T> &vector)
+
+ Constructs an iterator for traversing \a vector. The iterator is
+ set to be at the front of the vector (before the first item).
+
+ \sa operator=()
+*/
+
+/*!
+ \fn QSetIterator::QSetIterator(const QSet<T> &set)
+ \fn QMutableSetIterator::QMutableSetIterator(QSet<T> &set)
+
+ Constructs an iterator for traversing \a set. The iterator is
+ set to be at the front of the set (before the first item).
+
+ \sa operator=()
+*/
+
+/*!
+ \fn QMutableListIterator::~QMutableListIterator()
+ \fn QMutableLinkedListIterator::~QMutableLinkedListIterator()
+ \fn QMutableVectorIterator::~QMutableVectorIterator()
+ \fn QMutableSetIterator::~QMutableSetIterator()
+
+ Destroys the iterator.
+
+ \sa operator=()
+*/
+
+/*! \fn QMutableListIterator &QMutableListIterator::operator=(QList<T> &list)
+ \fn QMutableLinkedListIterator &QMutableLinkedListIterator::operator=(QLinkedList<T> &list)
+ \fn QListIterator &QListIterator::operator=(const QList<T> &list)
+ \fn QLinkedListIterator &QLinkedListIterator::operator=(const QLinkedList<T> &list)
+
+ Makes the iterator operate on \a list. The iterator is set to be
+ at the front of the list (before the first item).
+
+ \sa toFront(), toBack()
+*/
+
+/*! \fn QVectorIterator &QVectorIterator::operator=(const QVector<T> &vector)
+ \fn QMutableVectorIterator &QMutableVectorIterator::operator=(QVector<T> &vector)
+
+ Makes the iterator operate on \a vector. The iterator is set to be
+ at the front of the vector (before the first item).
+
+ \sa toFront(), toBack()
+*/
+
+/*! \fn QSetIterator &QSetIterator::operator=(const QSet<T> &set)
+ \fn QMutableSetIterator &QMutableSetIterator::operator=(QSet<T> &set)
+
+ Makes the iterator operate on \a set. The iterator is set to be
+ at the front of the set (before the first item).
+
+ \sa toFront(), toBack()
+*/
+
+/*! \fn void QListIterator::toFront()
+ \fn void QLinkedListIterator::toFront()
+ \fn void QVectorIterator::toFront()
+ \fn void QSetIterator::toFront()
+ \fn void QMutableListIterator::toFront()
+ \fn void QMutableLinkedListIterator::toFront()
+ \fn void QMutableVectorIterator::toFront()
+ \fn void QMutableSetIterator::toFront()
+
+ Moves the iterator to the front of the container (before the
+ first item).
+
+ \sa toBack(), next()
+*/
+
+/*! \fn void QListIterator::toBack()
+ \fn void QLinkedListIterator::toBack()
+ \fn void QVectorIterator::toBack()
+ \fn void QSetIterator::toBack()
+ \fn void QMutableListIterator::toBack()
+ \fn void QMutableLinkedListIterator::toBack()
+ \fn void QMutableVectorIterator::toBack()
+ \fn void QMutableSetIterator::toBack()
+
+ Moves the iterator to the back of the container (after the last
+ item).
+
+ \sa toFront(), previous()
+*/
+
+/*! \fn bool QListIterator::hasNext() const
+ \fn bool QLinkedListIterator::hasNext() const
+ \fn bool QVectorIterator::hasNext() const
+ \fn bool QSetIterator::hasNext() const
+ \fn bool QMutableListIterator::hasNext() const
+ \fn bool QMutableLinkedListIterator::hasNext() const
+ \fn bool QMutableVectorIterator::hasNext() const
+ \fn bool QMutableSetIterator::hasNext() const
+
+ Returns true if there is at least one item ahead of the iterator,
+ i.e. the iterator is \e not at the back of the container;
+ otherwise returns false.
+
+ \sa hasPrevious(), next()
+*/
+
+/*! \fn const T &QListIterator::next()
+ \fn const T &QLinkedListIterator::next()
+ \fn const T &QVectorIterator::next()
+ \fn const T &QSetIterator::next()
+ \fn const T &QMutableSetIterator::next()
+
+ Returns the next item and advances the iterator by one position.
+
+ Calling this function on an iterator located at the back of the
+ container leads to undefined results.
+
+ \sa hasNext(), peekNext(), previous()
+*/
+
+/*! \fn T &QMutableListIterator::next()
+ \fn T &QMutableLinkedListIterator::next()
+ \fn T &QMutableVectorIterator::next()
+
+ Returns a reference to the next item, and advances the iterator
+ by one position.
+
+ Calling this function on an iterator located at the back of the
+ container leads to undefined results.
+
+ \sa hasNext(), peekNext(), previous()
+*/
+
+/*! \fn const T &QListIterator::peekNext() const
+ \fn const T &QLinkedListIterator::peekNext() const
+ \fn const T &QVectorIterator::peekNext() const
+ \fn const T &QSetIterator::peekNext() const
+ \fn const T &QMutableSetIterator::peekNext() const
+
+ Returns the next item without moving the iterator.
+
+ Calling this function on an iterator located at the back of the
+ container leads to undefined results.
+
+ \sa hasNext(), next(), peekPrevious()
+*/
+
+/*! \fn T &QMutableListIterator::peekNext() const
+ \fn T &QMutableLinkedListIterator::peekNext() const
+ \fn T &QMutableVectorIterator::peekNext() const
+
+ Returns a reference to the next item, without moving the iterator.
+
+ Calling this function on an iterator located at the back of the
+ container leads to undefined results.
+
+ \sa hasNext(), next(), peekPrevious()
+*/
+
+/*! \fn bool QListIterator::hasPrevious() const
+ \fn bool QLinkedListIterator::hasPrevious() const
+ \fn bool QVectorIterator::hasPrevious() const
+ \fn bool QSetIterator::hasPrevious() const
+ \fn bool QMutableListIterator::hasPrevious() const
+ \fn bool QMutableLinkedListIterator::hasPrevious() const
+ \fn bool QMutableVectorIterator::hasPrevious() const
+ \fn bool QMutableSetIterator::hasPrevious() const
+
+ Returns true if there is at least one item behind the iterator,
+ i.e. the iterator is \e not at the front of the container;
+ otherwise returns false.
+
+ \sa hasNext(), previous()
+*/
+
+/*! \fn const T &QListIterator::previous()
+ \fn const T &QLinkedListIterator::previous()
+ \fn const T &QVectorIterator::previous()
+ \fn const T &QSetIterator::previous()
+ \fn const T &QMutableSetIterator::previous()
+
+ Returns the previous item and moves the iterator back by one
+ position.
+
+ Calling this function on an iterator located at the front of the
+ container leads to undefined results.
+
+ \sa hasPrevious(), peekPrevious(), next()
+*/
+
+/*! \fn T &QMutableListIterator::previous()
+ \fn T &QMutableLinkedListIterator::previous()
+ \fn T &QMutableVectorIterator::previous()
+
+ Returns a reference to the previous item and moves the iterator
+ back by one position.
+
+ Calling this function on an iterator located at the front of the
+ container leads to undefined results.
+
+ \sa hasPrevious(), peekPrevious(), next()
+*/
+
+/*! \fn const T &QListIterator::peekPrevious() const
+ \fn const T &QLinkedListIterator::peekPrevious() const
+ \fn const T &QVectorIterator::peekPrevious() const
+ \fn const T &QSetIterator::peekPrevious() const
+ \fn const T &QMutableSetIterator::peekPrevious() const
+
+ Returns the previous item without moving the iterator.
+
+ Calling this function on an iterator located at the front of the
+ container leads to undefined results.
+
+ \sa hasPrevious(), previous(), peekNext()
+*/
+
+/*! \fn T &QMutableListIterator::peekPrevious() const
+ \fn T &QMutableLinkedListIterator::peekPrevious() const
+ \fn T &QMutableVectorIterator::peekPrevious() const
+
+ Returns a reference to the previous item, without moving the iterator.
+
+ Calling this function on an iterator located at the front of the
+ container leads to undefined results.
+
+ \sa hasPrevious(), previous(), peekNext()
+*/
+
+/*! \fn bool QListIterator::findNext(const T &value)
+ \fn bool QLinkedListIterator::findNext(const T &value)
+ \fn bool QVectorIterator::findNext(const T &value)
+ \fn bool QSetIterator::findNext(const T &value)
+ \fn bool QMutableListIterator::findNext(const T &value)
+ \fn bool QMutableLinkedListIterator::findNext(const T &value)
+ \fn bool QMutableVectorIterator::findNext(const T &value)
+ \fn bool QMutableSetIterator::findNext(const T &value)
+
+ Searches for \a value starting from the current iterator position
+ forward. Returns true if \a value is found; otherwise returns false.
+
+ After the call, if \a value was found, the iterator is positioned
+ just after the matching item; otherwise, the iterator is
+ positioned at the back of the container.
+
+ \sa findPrevious()
+*/
+
+/*! \fn bool QListIterator::findPrevious(const T &value)
+ \fn bool QLinkedListIterator::findPrevious(const T &value)
+ \fn bool QVectorIterator::findPrevious(const T &value)
+ \fn bool QSetIterator::findPrevious(const T &value)
+ \fn bool QMutableListIterator::findPrevious(const T &value)
+ \fn bool QMutableLinkedListIterator::findPrevious(const T &value)
+ \fn bool QMutableVectorIterator::findPrevious(const T &value)
+ \fn bool QMutableSetIterator::findPrevious(const T &value)
+
+ Searches for \a value starting from the current iterator position
+ backward. Returns true if \a value is found; otherwise returns
+ false.
+
+ After the call, if \a value was found, the iterator is positioned
+ just before the matching item; otherwise, the iterator is
+ positioned at the front of the container.
+
+ \sa findNext()
+*/
+
+/*! \fn void QMutableListIterator::remove()
+
+ Removes the last item that was jumped over using one of the
+ traversal functions (next(), previous(), findNext(), findPrevious()).
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 19
+
+ \sa insert(), setValue()
+*/
+
+/*! \fn void QMutableLinkedListIterator::remove()
+
+ Removes the last item that was jumped over using one of the
+ traversal functions (next(), previous(), findNext(), findPrevious()).
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 20
+
+ \sa insert(), setValue()
+*/
+
+/*! \fn void QMutableVectorIterator::remove()
+
+ Removes the last item that was jumped over using one of the
+ traversal functions (next(), previous(), findNext(), findPrevious()).
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 21
+
+ \sa insert(), setValue()
+*/
+
+/*! \fn void QMutableSetIterator::remove()
+
+ Removes the last item that was jumped over using one of the
+ traversal functions (next(), previous(), findNext(), findPrevious()).
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 22
+
+ \sa value()
+*/
+
+/*! \fn void QMutableListIterator::setValue(const T &value) const
+
+ Replaces the value of the last item that was jumped over using
+ one of the traversal functions with \a value.
+
+ The traversal functions are next(), previous(), findNext(), and
+ findPrevious().
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 23
+
+ \sa value(), remove(), insert()
+*/
+
+/*! \fn void QMutableLinkedListIterator::setValue(const T &value) const
+
+ Replaces the value of the last item that was jumped over using
+ one of the traversal functions with \a value.
+
+ The traversal functions are next(), previous(), findNext(), and
+ findPrevious().
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 24
+
+ \sa value(), remove(), insert()
+*/
+
+/*! \fn void QMutableVectorIterator::setValue(const T &value) const
+
+ Replaces the value of the last item that was jumped over using
+ one of the traversal functions with \a value.
+
+ The traversal functions are next(), previous(), findNext(), and
+ findPrevious().
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 25
+
+ \sa value(), remove(), insert()
+*/
+
+/*! \fn const T &QMutableListIterator::value() const
+ \fn const T &QMutableLinkedListIterator::value() const
+ \fn const T &QMutableVectorIterator::value() const
+ \fn const T &QMutableSetIterator::value() const
+
+ Returns the value of the last item that was jumped over using one
+ of the traversal functions (next(), previous(), findNext(),
+ findPrevious()).
+
+ After a call to next() or findNext(), value() is equivalent to
+ peekPrevious(). After a call to previous() or findPrevious(), value() is
+ equivalent to peekNext().
+*/
+
+/*!
+ \fn T &QMutableListIterator::value()
+ \fn T &QMutableLinkedListIterator::value()
+ \fn T &QMutableVectorIterator::value()
+ \overload
+
+ Returns a non-const reference to the value of the last item that
+ was jumped over using one of the traversal functions.
+*/
+
+/*! \fn void QMutableListIterator::insert(const T &value)
+ \fn void QMutableLinkedListIterator::insert(const T &value)
+ \fn void QMutableVectorIterator::insert(const T &value)
+
+ Inserts \a value at the current iterator position. After the
+ call, the iterator is located just after the inserted item.
+
+ \sa remove(), setValue()
+*/
+
+/*!
+ \class QMapIterator
+ \inmodule QtCore
+
+ \brief The QMapIterator class provides a Java-style const iterator for QMap and QMultiMap.
+
+ QMap has both \l{Java-style iterators} and \l{STL-style
+ iterators}. The Java-style iterators are more high-level and
+ easier to use than the STL-style iterators; on the other hand,
+ they are slightly less efficient.
+
+ QMapIterator\<Key, T\> allows you to iterate over a QMap (or a
+ QMultiMap). If you want to modify the map as you iterate over
+ it, use QMutableMapIterator instead.
+
+ The QMapIterator constructor takes a QMap as argument. After
+ construction, the iterator is located at the very beginning of
+ the map (before the first item). Here's how to iterate over all
+ the elements sequentially:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 26
+
+ The next() function returns the next item in the map and
+ advances the iterator. The key() and value() functions return the
+ key and value of the last item that was jumped over.
+
+ Unlike STL-style iterators, Java-style iterators point \e between
+ items rather than directly \e at items. The first call to next()
+ advances the iterator to the position between the first and
+ second item, and returns the first item; the second call to
+ next() advances the iterator to the position between the second
+ and third item; and so on.
+
+ \img javaiterators1.png
+
+ Here's how to iterate over the elements in reverse order:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 27
+
+ If you want to find all occurrences of a particular value, use
+ findNext() or findPrevious() in a loop. For example:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 28
+
+ Multiple iterators can be used on the same map. If the map is
+ modified while a QMapIterator is active, the QMapIterator will
+ continue iterating over the original map, ignoring the modified
+ copy.
+
+ \sa QMutableMapIterator, QMap::const_iterator
+*/
+
+/*!
+ \class QHashIterator
+ \inmodule QtCore
+
+ \brief The QHashIterator class provides a Java-style const iterator for QHash and QMultiHash.
+
+ QHash has both \l{Java-style iterators} and \l{STL-style
+ iterators}. The Java-style iterators are more high-level and
+ easier to use than the STL-style iterators; on the other hand,
+ they are slightly less efficient.
+
+ QHashIterator\<Key, T\> allows you to iterate over a QHash (or a
+ QMultiHash). If you want to modify the hash as you iterate over
+ it, use QMutableHashIterator instead.
+
+ The QHashIterator constructor takes a QHash as argument. After
+ construction, the iterator is located at the very beginning of
+ the hash (before the first item). Here's how to iterate over all
+ the elements sequentially:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 29
+
+ The next() function returns the next item in the hash and
+ advances the iterator. The key() and value() functions return the
+ key and value of the last item that was jumped over.
+
+ Unlike STL-style iterators, Java-style iterators point \e between
+ items rather than directly \e at items. The first call to next()
+ advances the iterator to the position between the first and
+ second item, and returns the first item; the second call to
+ next() advances the iterator to the position between the second
+ and third item; and so on.
+
+ \img javaiterators1.png
+
+ Here's how to iterate over the elements in reverse order:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 30
+
+ If you want to find all occurrences of a particular value, use
+ findNext() or findPrevious() in a loop. For example:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 31
+
+ Multiple iterators can be used on the same hash. If the hash is
+ modified while a QHashIterator is active, the QHashIterator will
+ continue iterating over the original hash, ignoring the modified
+ copy.
+
+ \sa QMutableHashIterator, QHash::const_iterator
+*/
+
+/*!
+ \class QMutableMapIterator
+ \inmodule QtCore
+
+ \brief The QMutableMapIterator class provides a Java-style non-const iterator for QMap and QMultiMap.
+
+ QMap has both \l{Java-style iterators} and \l{STL-style
+ iterators}. The Java-style iterators are more high-level and
+ easier to use than the STL-style iterators; on the other hand,
+ they are slightly less efficient.
+
+ QMutableMapIterator\<Key, T\> allows you to iterate over a QMap
+ (or a QMultiMap) and modify the map. If you don't want to modify
+ the map (or have a const QMap), use the slightly faster
+ QMapIterator instead.
+
+ The QMutableMapIterator constructor takes a QMap as argument.
+ After construction, the iterator is located at the very beginning
+ of the map (before the first item). Here's how to iterate over
+ all the elements sequentially:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 32
+
+ The next() function returns the next item in the map and
+ advances the iterator. The key() and value() functions return the
+ key and value of the last item that was jumped over.
+
+ Unlike STL-style iterators, Java-style iterators point \e between
+ items rather than directly \e at items. The first call to next()
+ advances the iterator to the position between the first and
+ second item, and returns the first item; the second call to
+ next() advances the iterator to the position between the second
+ and third item; and so on.
+
+ \img javaiterators1.png
+
+ Here's how to iterate over the elements in reverse order:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 33
+
+ If you want to find all occurrences of a particular value, use
+ findNext() or findPrevious() in a loop. For example:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 34
+
+ If you want to remove items as you iterate over the map, use
+ remove(). If you want to modify the value of an item, use
+ setValue().
+
+ Example:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 35
+
+ The example removes all (key, value) pairs where the key and the
+ value are the same.
+
+ Only one mutable iterator can be active on a given map at any
+ time. Furthermore, no changes should be done directly to the map
+ while the iterator is active (as opposed to through the
+ iterator), since this could invalidate the iterator and lead to
+ undefined behavior.
+
+ \sa QMapIterator, QMap::iterator
+*/
+
+/*!
+ \class QMutableHashIterator
+ \inmodule QtCore
+
+ \brief The QMutableHashIterator class provides a Java-style non-const iterator for QHash and QMultiHash.
+
+ QHash has both \l{Java-style iterators} and \l{STL-style
+ iterators}. The Java-style iterators are more high-level and
+ easier to use than the STL-style iterators; on the other hand,
+ they are slightly less efficient.
+
+ QMutableHashIterator\<Key, T\> allows you to iterate over a QHash
+ (or a QMultiHash) and modify the hash. If you don't want to modify
+ the hash (or have a const QHash), use the slightly faster
+ QHashIterator instead.
+
+ The QMutableHashIterator constructor takes a QHash as argument.
+ After construction, the iterator is located at the very beginning
+ of the hash (before the first item). Here's how to iterate over
+ all the elements sequentially:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 36
+
+ The next() function returns the next item in the hash and
+ advances the iterator. The key() and value() functions return the
+ key and value of the last item that was jumped over.
+
+ Unlike STL-style iterators, Java-style iterators point \e between
+ items rather than directly \e at items. The first call to next()
+ advances the iterator to the position between the first and
+ second item, and returns the first item; the second call to
+ next() advances the iterator to the position between the second
+ and third item; and so on.
+
+ \img javaiterators1.png
+
+ Here's how to iterate over the elements in reverse order:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 37
+
+ If you want to find all occurrences of a particular value, use
+ findNext() or findPrevious() in a loop. For example:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 38
+
+ If you want to remove items as you iterate over the hash, use
+ remove(). If you want to modify the value of an item, use
+ setValue().
+
+ Example:
+
+ \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 39
+
+ The example removes all (key, value) pairs where the key and the
+ value are the same.
+
+ Only one mutable iterator can be active on a given hash at any
+ time. Furthermore, no changes should be done directly to the hash
+ while the iterator is active (as opposed to through the
+ iterator), since this could invalidate the iterator and lead to
+ undefined behavior.
+
+ \sa QHashIterator, QHash::iterator
+*/
+
+/*! \fn QMapIterator::QMapIterator(const QMap<Key, T> &map)
+ \fn QMutableMapIterator::QMutableMapIterator(QMap<Key, T> &map)
+
+ Constructs an iterator for traversing \a map. The iterator is set
+ to be at the front of the map (before the first item).
+
+ \sa operator=()
+*/
+
+/*! \fn QHashIterator::QHashIterator(const QHash<Key, T> &hash)
+ \fn QMutableHashIterator::QMutableHashIterator(QHash<Key, T> &hash)
+
+ Constructs an iterator for traversing \a hash. The iterator is
+ set to be at the front of the hash (before the first item).
+
+ \sa operator=()
+*/
+
+/*!
+ \fn QMutableMapIterator::~QMutableMapIterator()
+ \fn QMutableHashIterator::~QMutableHashIterator()
+
+ Destroys the iterator.
+
+ \sa operator=()
+*/
+
+/*! \fn QMapIterator &QMapIterator::operator=(const QMap<Key, T> &map)
+ \fn QMutableMapIterator &QMutableMapIterator::operator=(QMap<Key, T> &map)
+
+ Makes the iterator operate on \a map. The iterator is set to be
+ at the front of the map (before the first item).
+
+ \sa toFront(), toBack()
+*/
+
+/*! \fn QHashIterator &QHashIterator::operator=(const QHash<Key, T> &hash)
+ \fn QMutableHashIterator &QMutableHashIterator::operator=(QHash<Key, T> &hash)
+
+ Makes the iterator operate on \a hash. The iterator is set to be
+ at the front of the hash (before the first item).
+
+ \sa toFront(), toBack()
+*/
+
+/*! \fn void QMapIterator::toFront()
+ \fn void QHashIterator::toFront()
+ \fn void QMutableMapIterator::toFront()
+ \fn void QMutableHashIterator::toFront()
+
+ Moves the iterator to the front of the container (before the
+ first item).
+
+ \sa toBack(), next()
+*/
+
+/*! \fn void QMapIterator::toBack()
+ \fn void QHashIterator::toBack()
+ \fn void QMutableMapIterator::toBack()
+ \fn void QMutableHashIterator::toBack()
+
+ Moves the iterator to the back of the container (after the last
+ item).
+
+ \sa toFront(), previous()
+*/
+
+/*! \fn bool QMapIterator::hasNext() const
+ \fn bool QHashIterator::hasNext() const
+ \fn bool QMutableMapIterator::hasNext() const
+ \fn bool QMutableHashIterator::hasNext() const
+
+ Returns true if there is at least one item ahead of the iterator,
+ i.e. the iterator is \e not at the back of the container;
+ otherwise returns false.
+
+ \sa hasPrevious(), next()
+*/
+
+/*! \fn QMapIterator::Item QMapIterator::next()
+ \fn QHashIterator::Item QHashIterator::next()
+
+ Returns the next item and advances the iterator by one position.
+
+ Call key() on the return value to obtain the item's key, and
+ value() to obtain the value.
+
+ Calling this function on an iterator located at the back of the
+ container leads to undefined results.
+
+ \sa hasNext(), peekNext(), previous()
+*/
+
+/*! \fn QMutableMapIterator::Item QMutableMapIterator::next()
+ \fn QMutableHashIterator::Item QMutableHashIterator::next()
+
+ Returns the next item and advances the iterator by one position.
+
+ Call key() on the return value to obtain the item's key, and
+ value() to obtain the value.
+
+ Calling this function on an iterator located at the back of the
+ container leads to undefined results.
+
+ \sa hasNext(), peekNext(), previous()
+*/
+
+/*! \fn QMapIterator::Item QMapIterator::peekNext() const
+ \fn QHashIterator::Item QHashIterator::peekNext() const
+
+ Returns the next item without moving the iterator.
+
+ Call key() on the return value to obtain the item's key, and
+ value() to obtain the value.
+
+ Calling this function on an iterator located at the back of the
+ container leads to undefined results.
+
+ \sa hasNext(), next(), peekPrevious()
+*/
+
+/*! \fn QMutableMapIterator::Item QMutableMapIterator::peekNext() const
+ \fn QMutableHashIterator::Item QMutableHashIterator::peekNext() const
+
+ Returns a reference to the next item without moving the iterator.
+
+ Call key() on the return value to obtain the item's key, and
+ value() to obtain the value.
+
+ Calling this function on an iterator located at the back of the
+ container leads to undefined results.
+
+ \sa hasNext(), next(), peekPrevious()
+*/
+
+/*! \fn bool QMapIterator::hasPrevious() const
+ \fn bool QHashIterator::hasPrevious() const
+ \fn bool QMutableMapIterator::hasPrevious() const
+ \fn bool QMutableHashIterator::hasPrevious() const
+
+ Returns true if there is at least one item behind the iterator,
+ i.e. the iterator is \e not at the front of the container;
+ otherwise returns false.
+
+ \sa hasNext(), previous()
+*/
+
+/*! \fn QMapIterator::Item QMapIterator::previous()
+ \fn QHashIterator::Item QHashIterator::previous()
+
+ Returns the previous item and moves the iterator back by one
+ position.
+
+ Call key() on the return value to obtain the item's key, and
+ value() to obtain the value.
+
+ Calling this function on an iterator located at the front of the
+ container leads to undefined results.
+
+ \sa hasPrevious(), peekPrevious(), next()
+*/
+
+/*! \fn QMutableMapIterator::Item QMutableMapIterator::previous()
+ \fn QMutableHashIterator::Item QMutableHashIterator::previous()
+
+ Returns the previous item and moves the iterator back by one
+ position.
+
+ Call key() on the return value to obtain the item's key, and
+ value() to obtain the value.
+
+ Calling this function on an iterator located at the front of the
+ container leads to undefined results.
+
+ \sa hasPrevious(), peekPrevious(), next()
+*/
+
+/*! \fn QMapIterator::Item QMapIterator::peekPrevious() const
+ \fn QHashIterator::Item QHashIterator::peekPrevious() const
+
+ Returns the previous item without moving the iterator.
+
+ Call key() on the return value to obtain the item's key, and
+ value() to obtain the value.
+
+ Calling this function on an iterator located at the front of the
+ container leads to undefined results.
+
+ \sa hasPrevious(), previous(), peekNext()
+*/
+
+/*! \fn QMutableMapIterator::Item QMutableMapIterator::peekPrevious() const
+ \fn QMutableHashIterator::Item QMutableHashIterator::peekPrevious() const
+
+ Returns the previous item without moving the iterator.
+
+ Call key() on the return value to obtain the item's key, and
+ value() to obtain the value.
+
+ Calling this function on an iterator located at the front of the
+ container leads to undefined results.
+
+ \sa hasPrevious(), previous(), peekNext()
+*/
+
+/*! \fn const T &QMapIterator::value() const
+ \fn const T &QHashIterator::value() const
+
+ Returns the value of the last item that was jumped over using one
+ of the traversal functions (next(), previous(), findNext(),
+ findPrevious()).
+
+ After a call to next() or findNext(), value() is
+ equivalent to peekPrevious().value(). After a call to previous()
+ or findPrevious(), value() is equivalent to peekNext().value().
+
+ \sa key()
+*/
+
+/*!
+ \fn const T &QMutableMapIterator::value() const
+ \fn const T &QMutableHashIterator::value() const
+
+ Returns the value of the last item that was jumped over using one
+ of the traversal functions (next(), previous(), findNext(),
+ findPrevious()).
+
+ After a call to next() or findNext(), value() is
+ equivalent to peekPrevious().value(). After a call to previous()
+ or findPrevious(), value() is equivalent to peekNext().value().
+
+ \sa key(), setValue()
+*/
+
+/*!
+ \fn T &QMutableMapIterator::value()
+ \fn T &QMutableHashIterator::value()
+ \overload
+
+ Returns a non-const reference to the value of
+ the last item that was jumped over using one
+ of the traversal functions.
+*/
+
+/*! \fn const Key &QMapIterator::key() const
+ \fn const Key &QHashIterator::key() const
+ \fn const Key &QMutableMapIterator::key() const
+ \fn const Key &QMutableHashIterator::key() const
+
+ Returns the key of the last item that was jumped over using one
+ of the traversal functions (next(), previous(), findNext(),
+ findPrevious()).
+
+ After a call to next() or findNext(), key() is
+ equivalent to peekPrevious().key(). After a call to previous() or
+ findPrevious(), key() is equivalent to peekNext().key().
+
+ \sa value()
+*/
+
+/*! \fn bool QMapIterator::findNext(const T &value)
+ \fn bool QHashIterator::findNext(const T &value)
+ \fn bool QMutableMapIterator::findNext(const T &value)
+ \fn bool QMutableHashIterator::findNext(const T &value)
+
+ Searches for \a value starting from the current iterator position
+ forward. Returns true if a (key, value) pair with value \a value
+ is found; otherwise returns false.
+
+ After the call, if \a value was found, the iterator is positioned
+ just after the matching item; otherwise, the iterator is
+ positioned at the back of the container.
+
+ \sa findPrevious()
+*/
+
+/*! \fn bool QMapIterator::findPrevious(const T &value)
+ \fn bool QHashIterator::findPrevious(const T &value)
+ \fn bool QMutableMapIterator::findPrevious(const T &value)
+ \fn bool QMutableHashIterator::findPrevious(const T &value)
+
+ Searches for \a value starting from the current iterator position
+ backward. Returns true if a (key, value) pair with value \a value
+ is found; otherwise returns false.
+
+ After the call, if \a value was found, the iterator is positioned
+ just before the matching item; otherwise, the iterator is
+ positioned at the front of the container.
+
+ \sa findNext()
+*/
+
+/*! \fn void QMutableMapIterator::remove()
+ \fn void QMutableHashIterator::remove()
+
+ Removes the last item that was jumped over using one of the
+ traversal functions (next(), previous(), findNext(), findPrevious()).
+
+ \sa setValue()
+*/
+
+/*! \fn void QMutableMapIterator::setValue(const T &value)
+ \fn void QMutableHashIterator::setValue(const T &value)
+
+ Replaces the value of the last item that was jumped over using
+ one of the traversal functions with \a value.
+
+ The traversal functions are next(), previous(), findNext(), and
+ findPrevious().
+
+ \sa key(), value(), remove()
+*/
diff --git a/src/corelib/tools/qline.cpp b/src/corelib/tools/qline.cpp
index e6ad9d1..02c1128 100644
--- a/src/corelib/tools/qline.cpp
+++ b/src/corelib/tools/qline.cpp
@@ -49,7 +49,7 @@ QT_BEGIN_NAMESPACE
/*!
\class QLine
- \ingroup multimedia
+ \ingroup painting
\brief The QLine class provides a two-dimensional vector using
integer precision.
@@ -309,7 +309,7 @@ QDataStream &operator>>(QDataStream &stream, QLine &line)
/*!
\class QLineF
- \ingroup multimedia
+ \ingroup painting
\brief The QLineF class provides a two-dimensional vector using
floating point precision.
diff --git a/src/corelib/tools/qlinkedlist.cpp b/src/corelib/tools/qlinkedlist.cpp
index e5c0145..39758ed 100644
--- a/src/corelib/tools/qlinkedlist.cpp
+++ b/src/corelib/tools/qlinkedlist.cpp
@@ -53,7 +53,7 @@ QLinkedListData QLinkedListData::shared_null = {
\ingroup tools
\ingroup shared
- \mainclass
+
\reentrant
QLinkedList\<T\> is one of Qt's generic \l{container classes}. It
diff --git a/src/corelib/tools/qlistdata.cpp b/src/corelib/tools/qlist.cpp
index be57359..d954160 100644
--- a/src/corelib/tools/qlistdata.cpp
+++ b/src/corelib/tools/qlist.cpp
@@ -304,7 +304,7 @@ void **QListData::erase(void **xi)
\ingroup tools
\ingroup shared
- \mainclass
+
\reentrant
QList\<T\> is one of Qt's generic \l{container classes}. It
diff --git a/src/corelib/tools/qlocale.cpp b/src/corelib/tools/qlocale.cpp
index 7c4d0c0..0881671 100644
--- a/src/corelib/tools/qlocale.cpp
+++ b/src/corelib/tools/qlocale.cpp
@@ -1479,9 +1479,9 @@ QDataStream &operator>>(QDataStream &ds, QLocale &l)
\reentrant
\ingroup i18n
- \ingroup text
+ \ingroup string-processing
\ingroup shared
- \mainclass
+
QLocale is initialized with a language/country pair in its
constructor and offers number-to-string and string-to-number
diff --git a/src/corelib/tools/qmap.cpp b/src/corelib/tools/qmap.cpp
index ed33764..e913232 100644
--- a/src/corelib/tools/qmap.cpp
+++ b/src/corelib/tools/qmap.cpp
@@ -207,7 +207,7 @@ void QMapData::dump()
\ingroup tools
\ingroup shared
- \mainclass
+
\reentrant
QMap\<Key, T\> is one of Qt's generic \l{container classes}. It
@@ -1330,7 +1330,7 @@ void QMapData::dump()
\ingroup tools
\ingroup shared
- \mainclass
+
\reentrant
QMultiMap\<Key, T\> is one of Qt's generic \l{container classes}.
diff --git a/src/corelib/tools/qpair.qdoc b/src/corelib/tools/qpair.qdoc
new file mode 100644
index 0000000..9c8ac89
--- /dev/null
+++ b/src/corelib/tools/qpair.qdoc
@@ -0,0 +1,229 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (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 http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \class QPair
+ \brief The QPair class is a template class that stores a pair of items.
+
+ \ingroup tools
+
+ QPair\<T1, T2\> can be used in your application if the STL \c
+ pair type is not available. It stores one value of type T1 and
+ one value of type T2. It can be used as a return value for a
+ function that needs to return two values, or as the value type of
+ a \l{generic container}.
+
+ Here's an example of a QPair that stores one QString and one \c
+ double value:
+
+ \snippet doc/src/snippets/code/doc_src_qpair.qdoc 0
+
+ The components are accessible as public data members called \l
+ first and \l second. For example:
+
+ \snippet doc/src/snippets/code/doc_src_qpair.qdoc 1
+
+ QPair's template data types (T1 and T2) must be \l{assignable
+ data types}. You cannot, for example, store a QWidget as a value;
+ instead, store a QWidget *. A few functions have additional
+ requirements; these requirements are documented on a per-function
+ basis.
+
+ \sa {Generic Containers}
+*/
+
+/*! \typedef QPair::first_type
+
+ The type of the first element in the pair (T1).
+
+ \sa first
+*/
+
+/*! \typedef QPair::second_type
+
+ The type of the second element in the pair (T2).
+
+ \sa second
+*/
+
+/*! \variable QPair::first
+
+ The first element in the pair.
+*/
+
+/*! \variable QPair::second
+
+ The second element in the pair.
+*/
+
+/*! \fn QPair::QPair()
+
+ Constructs an empty pair. The \c first and \c second elements are
+ initialized with \l{default-constructed values}.
+*/
+
+/*!
+ \fn QPair::QPair(const T1 &value1, const T2 &value2)
+
+ Constructs a pair and initializes the \c first element with \a
+ value1 and the \c second element with \a value2.
+
+ \sa qMakePair()
+*/
+
+/*!
+ \fn QPair<T1, T2> &QPair::operator=(const QPair<T1, T2> &other)
+
+ Assigns \a other to this pair.
+*/
+
+/*! \fn bool operator==(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2)
+
+ \relates QPair
+
+ Returns true if \a p1 is equal to \a p2; otherwise returns false.
+ Two pairs compare equal if their \c first data members compare
+ equal and if their \c second data members compare equal.
+
+ This function requires the T1 and T2 types to have an
+ implementation of \c operator==().
+*/
+
+/*! \fn bool operator!=(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2)
+
+ \relates QPair
+
+ Returns true if \a p1 is not equal to \a p2; otherwise returns
+ false. Two pairs compare as not equal if their \c first data
+ members are not equal or if their \c second data members are not
+ equal.
+
+ This function requires the T1 and T2 types to have an
+ implementation of \c operator==().
+*/
+
+/*! \fn bool operator<(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2)
+
+ \relates QPair
+
+ Returns true if \a p1 is less than \a p2; otherwise returns
+ false. The comparison is done on the \c first members of \a p1
+ and \a p2; if they compare equal, the \c second members are
+ compared to break the tie.
+
+ This function requires the T1 and T2 types to have an
+ implementation of \c operator<().
+*/
+
+/*! \fn bool operator>(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2)
+
+ \relates QPair
+
+ Returns true if \a p1 is greater than \a p2; otherwise returns
+ false. The comparison is done on the \c first members of \a p1
+ and \a p2; if they compare equal, the \c second members are
+ compared to break the tie.
+
+ This function requires the T1 and T2 types to have an
+ implementation of \c operator<().
+*/
+
+/*! \fn bool operator<=(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2)
+
+ \relates QPair
+
+ Returns true if \a p1 is less than or equal to \a p2; otherwise
+ returns false. The comparison is done on the \c first members of
+ \a p1 and \a p2; if they compare equal, the \c second members are
+ compared to break the tie.
+
+ This function requires the T1 and T2 types to have an
+ implementation of \c operator<().
+*/
+
+/*! \fn bool operator>=(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2)
+
+ \relates QPair
+
+ Returns true if \a p1 is greater than or equal to \a p2;
+ otherwise returns false. The comparison is done on the \c first
+ members of \a p1 and \a p2; if they compare equal, the \c second
+ members are compared to break the tie.
+
+ This function requires the T1 and T2 types to have an
+ implementation of \c operator<().
+*/
+
+/*!
+ \fn QPair<T1, T2> qMakePair(const T1 &value1, const T2 &value2)
+
+ \relates QPair
+
+ Returns a QPair\<T1, T2\> that contains \a value1 and \a value2.
+ Example:
+
+ \snippet doc/src/snippets/code/doc_src_qpair.qdoc 2
+
+ This is equivalent to QPair<T1, T2>(\a value1, \a value2), but
+ usually requires less typing.
+*/
+
+/*! \fn QDataStream &operator>>(QDataStream &in, QPair<T1, T2> &pair)
+
+ \relates QPair
+
+ Reads a pair from stream \a in into \a pair.
+
+ This function requires the T1 and T2 types to implement \c operator>>().
+
+ \sa {Format of the QDataStream operators}
+*/
+
+/*! \fn QDataStream &operator<<(QDataStream &out, const QPair<T1, T2> &pair)
+
+ \relates QPair
+
+ Writes the pair \a pair to stream \a out.
+
+ This function requires the T1 and T2 types to implement \c operator<<().
+
+ \sa {Format of the QDataStream operators}
+*/
diff --git a/src/corelib/tools/qpoint.cpp b/src/corelib/tools/qpoint.cpp
index cba7fef..7c05eaa 100644
--- a/src/corelib/tools/qpoint.cpp
+++ b/src/corelib/tools/qpoint.cpp
@@ -47,7 +47,7 @@ QT_BEGIN_NAMESPACE
/*!
\class QPoint
- \ingroup multimedia
+ \ingroup painting
\brief The QPoint class defines a point in the plane using integer
precision.
@@ -380,7 +380,7 @@ QDebug operator<<(QDebug d, const QPointF &p)
/*!
\class QPointF
- \ingroup multimedia
+ \ingroup painting
\brief The QPointF class defines a point in the plane using
floating point precision.
diff --git a/src/corelib/tools/qqueue.cpp b/src/corelib/tools/qqueue.cpp
index 108f103..1c1e6d2 100644
--- a/src/corelib/tools/qqueue.cpp
+++ b/src/corelib/tools/qqueue.cpp
@@ -45,7 +45,7 @@
\ingroup tools
\ingroup shared
- \mainclass
+
\reentrant
QQueue\<T\> is one of Qt's generic \l{container classes}. It
diff --git a/src/corelib/tools/qrect.cpp b/src/corelib/tools/qrect.cpp
index eb493f0..bdd09a2 100644
--- a/src/corelib/tools/qrect.cpp
+++ b/src/corelib/tools/qrect.cpp
@@ -50,7 +50,7 @@ QT_BEGIN_NAMESPACE
/*!
\class QRect
- \ingroup multimedia
+ \ingroup painting
\brief The QRect class defines a rectangle in the plane using
integer precision.
@@ -1324,7 +1324,7 @@ QDebug operator<<(QDebug dbg, const QRect &r) {
/*!
\class QRectF
- \ingroup multimedia
+ \ingroup painting
\brief The QRectF class defines a rectangle in the plane using floating
point precision.
diff --git a/src/corelib/tools/qregexp.cpp b/src/corelib/tools/qregexp.cpp
index fd3b33e..ed7fe9e 100644
--- a/src/corelib/tools/qregexp.cpp
+++ b/src/corelib/tools/qregexp.cpp
@@ -83,9 +83,8 @@ int qFindString(const QChar *haystack, int haystackLen, int from,
\brief The QRegExp class provides pattern matching using regular expressions.
\ingroup tools
- \ingroup misc
\ingroup shared
- \mainclass
+
\keyword regular expression
A regular expression, or "regexp", is a pattern for matching
diff --git a/src/corelib/tools/qset.qdoc b/src/corelib/tools/qset.qdoc
new file mode 100644
index 0000000..55baa18
--- /dev/null
+++ b/src/corelib/tools/qset.qdoc
@@ -0,0 +1,953 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (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 http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \class QSet
+ \brief The QSet class is a template class that provides a hash-table-based set.
+
+ \ingroup tools
+ \ingroup shared
+ \reentrant
+
+
+ QSet<T> is one of Qt's generic \l{container classes}. It stores
+ values in an unspecified order and provides very fast lookup of
+ the values. Internally, QSet<T> is implemented as a QHash.
+
+ Here's an example QSet with QString values:
+
+ \snippet doc/src/snippets/code/doc_src_qset.qdoc 0
+
+ To insert a value into the set, use insert():
+
+ \snippet doc/src/snippets/code/doc_src_qset.qdoc 1
+
+ Another way to insert items into the set is to use operator<<():
+
+ \snippet doc/src/snippets/code/doc_src_qset.qdoc 2
+
+ To test whether an item belongs to the set or not, use contains():
+
+ \snippet doc/src/snippets/code/doc_src_qset.qdoc 3
+
+ If you want to navigate through all the values stored in a QSet,
+ you can use an iterator. QSet supports both \l{Java-style
+ iterators} (QSetIterator and QMutableSetIterator) and \l{STL-style
+ iterators} (QSet::iterator and QSet::const_iterator). Here's how
+ to iterate over a QSet<QWidget *> using a Java-style iterator:
+
+ \snippet doc/src/snippets/code/doc_src_qset.qdoc 4
+
+ Here's the same code, but using an STL-style iterator:
+
+ \snippet doc/src/snippets/code/doc_src_qset.qdoc 5
+
+ QSet is unordered, so an iterator's sequence cannot be assumed to
+ be predictable. If ordering by key is required, use a QMap.
+
+ To navigate through a QSet, you can also use \l{foreach}:
+
+ \snippet doc/src/snippets/code/doc_src_qset.qdoc 6
+
+ Items can be removed from the set using remove(). There is also a
+ clear() function that removes all items.
+
+ QSet's value data type must be an \l{assignable data type}. You
+ cannot, for example, store a QWidget as a value; instead, store a
+ QWidget *. In addition, the type must provide \c operator==(), and
+ there must also be a global qHash() function that returns a hash
+ value for an argument of the key's type. See the QHash
+ documentation for a list of types supported by qHash().
+
+ Internally, QSet uses a hash table to perform lookups. The hash
+ table automatically grows and shrinks to provide fast lookups
+ without wasting memory. You can still control the size of the hash
+ table by calling reserve(), if you already know approximately how
+ many elements the QSet will contain, but this isn't necessary to
+ obtain good performance. You can also call capacity() to retrieve
+ the hash table's size.
+
+ \sa QSetIterator, QMutableSetIterator, QHash, QMap
+*/
+
+/*!
+ \fn QSet::QSet()
+
+ Constructs an empty set.
+
+ \sa clear()
+*/
+
+/*!
+ \fn QSet::QSet(const QSet<T> &other)
+
+ Constructs a copy of \a other.
+
+ This operation occurs in \l{constant time}, because QSet is
+ \l{implicitly shared}. This makes returning a QSet from a
+ function very fast. If a shared instance is modified, it will be
+ copied (copy-on-write), and this takes \l{linear time}.
+
+ \sa operator=()
+*/
+
+/*!
+ \fn QSet<T> &QSet::operator=(const QSet<T> &other)
+
+ Assigns the \a other set to this set and returns a reference to
+ this set.
+*/
+
+/*!
+ \fn bool QSet::operator==(const QSet<T> &other) const
+
+ Returns true if the \a other set is equal to this set; otherwise
+ returns false.
+
+ Two sets are considered equal if they contain the same elements.
+
+ This function requires the value type to implement \c operator==().
+
+ \sa operator!=()
+*/
+
+/*!
+ \fn bool QSet::operator!=(const QSet<T> &other) const
+
+ Returns true if the \a other set is not equal to this set; otherwise
+ returns false.
+
+ Two sets are considered equal if they contain the same elements.
+
+ This function requires the value type to implement \c operator==().
+
+ \sa operator==()
+*/
+
+/*!
+ \fn int QSet::size() const
+
+ Returns the number of items in the set.
+
+ \sa isEmpty(), count()
+*/
+
+/*!
+ \fn bool QSet::isEmpty() const
+
+ Returns true if the set contains no elements; otherwise returns
+ false.
+
+ \sa size()
+*/
+
+/*!
+ \fn int QSet::capacity() const
+
+ Returns the number of buckets in the set's internal hash
+ table.
+
+ The sole purpose of this function is to provide a means of fine
+ tuning QSet'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 set, call size().
+
+ \sa reserve(), squeeze()
+*/
+
+/*! \fn void QSet::reserve(int size)
+
+ Ensures that the set's internal hash table consists of at
+ least \a size buckets.
+
+ This function is useful for code that needs to build a huge set
+ and wants to avoid repeated reallocation. For example:
+
+ \snippet doc/src/snippets/code/doc_src_qset.qdoc 7
+
+ Ideally, \a size should be slightly more than the maximum number
+ of elements expected in the set. \a size doesn't have to be prime,
+ because QSet will use a prime number internally anyway. If \a size
+ is an underestimate, the worst that will happen is that the QSet
+ will be a bit slower.
+
+ In general, you will rarely ever need to call this function.
+ QSet's internal hash table automatically shrinks or grows to
+ provide good performance without wasting too much memory.
+
+ \sa squeeze(), capacity()
+*/
+
+/*!
+ \fn void QSet::squeeze()
+
+ Reduces the size of the set's internal hash table to save
+ memory.
+
+ The sole purpose of this function is to provide a means of fine
+ tuning QSet's memory usage. In general, you will rarely ever
+ need to call this function.
+
+ \sa reserve(), capacity()
+*/
+
+/*!
+ \fn void QSet::detach()
+
+ \internal
+
+ Detaches this set from any other sets with which it may share
+ data.
+
+ \sa isDetached()
+*/
+
+/*! \fn bool QSet::isDetached() const
+
+ \internal
+
+ Returns true if the set's internal data isn't shared with any
+ other set object; otherwise returns false.
+
+ \sa detach()
+*/
+
+/*!
+ \fn void QSet::setSharable(bool sharable)
+ \internal
+*/
+
+/*!
+ \fn void QSet::clear()
+
+ Removes all elements from the set.
+
+ \sa remove()
+*/
+
+/*!
+ \fn bool QSet::remove(const T &value)
+
+ Removes any occurrence of item \a value from the set. Returns
+ true if an item was actually removed; otherwise returns false.
+
+ \sa contains(), insert()
+*/
+
+/*!
+ \fn QSet::iterator QSet::erase(iterator pos)
+ \since 4.2
+
+ Removes the item at the iterator position \a pos from the set, and
+ returns an iterator positioned at the next item in the set.
+
+ Unlike remove(), this function never causes QSet to rehash its
+ internal data structure. This means that it can safely be called
+ while iterating, and won't affect the order of items in the set.
+
+ \sa remove(), find()
+*/
+
+/*! \fn QSet::const_iterator QSet::find(const T &value) const
+ \since 4.2
+
+ Returns a const iterator positioned at the item \a value in the
+ set. If the set contains no item \a value, the function returns
+ constEnd().
+
+ \sa constFind(), contains()
+*/
+
+/*! \fn QSet::iterator QSet::find(const T &value)
+ \since 4.2
+ \overload
+
+ Returns a non-const iterator positioned at the item \a value in
+ the set. If the set contains no item \a value, the function
+ returns end().
+*/
+
+/*! \fn QSet::const_iterator QSet::constFind(const T &value) const
+ \since 4.2
+
+ Returns a const iterator positioned at the item \a value in the
+ set. If the set contains no item \a value, the function returns
+ constEnd().
+
+ \sa find(), contains()
+*/
+
+/*!
+ \fn bool QSet::contains(const T &value) const
+
+ Returns true if the set contains item \a value; otherwise returns
+ false.
+
+ \sa insert(), remove(), find()
+*/
+
+/*!
+ \fn bool QSet::contains(const QSet<T> &other) const
+ \since 4.6
+
+ Returns true if the set contains all items from the \a other set;
+ otherwise returns false.
+
+ \sa insert(), remove(), find()
+*/
+
+/*! \fn QSet::const_iterator QSet::begin() const
+
+ Returns a const \l{STL-style iterator} positioned at the first
+ item in the set.
+
+ \sa constBegin(), end()
+*/
+
+/*! \fn QSet::iterator QSet::begin()
+ \since 4.2
+ \overload
+
+ Returns a non-const \l{STL-style iterator} positioned at the first
+ item in the set.
+*/
+
+/*! \fn QSet::const_iterator QSet::constBegin() const
+
+ Returns a const \l{STL-style iterator} positioned at the first
+ item in the set.
+
+ \sa begin(), constEnd()
+*/
+
+/*! \fn QSet::const_iterator QSet::end() const
+
+ Returns a const \l{STL-style iterator} positioned at the imaginary
+ item after the last item in the set.
+
+ \sa constEnd(), begin()
+*/
+
+/*! \fn QSet::iterator QSet::end()
+ \since 4.2
+ \overload
+
+ Returns a non-const \l{STL-style iterator} pointing to the
+ imaginary item after the last item in the set.
+*/
+
+/*! \fn QSet::const_iterator QSet::constEnd() const
+
+ Returns a const \l{STL-style iterator} pointing to the imaginary
+ item after the last item in the set.
+
+ \sa constBegin(), end()
+*/
+
+/*!
+ \typedef QSet::Iterator
+ \since 4.2
+
+ Qt-style synonym for QSet::iterator.
+*/
+
+/*!
+ \typedef QSet::ConstIterator
+
+ Qt-style synonym for QSet::const_iterator.
+*/
+
+/*!
+ \typedef QSet::const_pointer
+
+ Typedef for const T *. Provided for STL compatibility.
+*/
+
+/*!
+ \typedef QSet::const_reference
+
+ Typedef for const T &. Provided for STL compatibility.
+*/
+
+/*!
+ \typedef QSet::difference_type
+
+ Typedef for const ptrdiff_t. Provided for STL compatibility.
+*/
+
+/*!
+ \typedef QSet::key_type
+
+ Typedef for T. Provided for STL compatibility.
+*/
+
+/*!
+ \typedef QSet::pointer
+
+ Typedef for T *. Provided for STL compatibility.
+*/
+
+/*!
+ \typedef QSet::reference
+
+ Typedef for T &. Provided for STL compatibility.
+*/
+
+/*!
+ \typedef QSet::size_type
+
+ Typedef for int. Provided for STL compatibility.
+*/
+
+/*!
+ \typedef QSet::value_type
+
+ Typedef for T. Provided for STL compatibility.
+*/
+
+/*!
+ \fn QSet::const_iterator QSet::insert(const T &value)
+
+ Inserts item \a value into the set, if \a value isn't already
+ in the set, and returns an iterator pointing at the inserted
+ item.
+
+ \sa operator<<(), remove(), contains()
+*/
+
+/*!
+ \fn QSet<T> &QSet::unite(const QSet<T> &other)
+
+ Each item in the \a other set that isn't already in this set is
+ inserted into this set. A reference to this set is returned.
+
+ \sa operator|=(), intersect(), subtract()
+*/
+
+/*!
+ \fn QSet<T> &QSet::intersect(const QSet<T> &other)
+
+ Removes all items from this set that are not contained in the
+ \a other set. A reference to this set is returned.
+
+ \sa operator&=(), unite(), subtract()
+*/
+
+/*!
+ \fn QSet<T> &QSet::subtract(const QSet<T> &other)
+
+ Removes all items from this set that are contained in the
+ \a other set. Returns a reference to this set.
+
+ \sa operator-=(), unite(), intersect()
+*/
+
+/*!
+ \fn bool QSet::empty() const
+
+ Returns true if the set is empty. This function is provided
+ for STL compatibility. It is equivalent to isEmpty().
+*/
+
+/*!
+ \fn bool QSet::count() const
+
+ Same as size().
+*/
+
+/*!
+ \fn QSet<T> &QSet::operator<<(const T &value)
+ \fn QSet<T> &QSet::operator+=(const T &value)
+ \fn QSet<T> &QSet::operator|=(const T &value)
+
+ Inserts a new item \a value and returns a reference to the set.
+ If \a value already exists in the set, the set is left unchanged.
+
+ \sa insert()
+*/
+
+/*!
+ \fn QSet<T> &QSet::operator-=(const T &value)
+
+ Removes the occurrence of item \a value from the set, if
+ it is found, and returns a reference to the set. If the
+ \a value is not contained the set, nothing is removed.
+
+ \sa remove()
+*/
+
+/*!
+ \fn QSet<T> &QSet::operator|=(const QSet<T> &other)
+ \fn QSet<T> &QSet::operator+=(const QSet<T> &other)
+
+ Same as unite(\a other).
+
+ \sa operator|(), operator&=(), operator-=()
+*/
+
+/*!
+ \fn QSet<T> &QSet::operator&=(const QSet<T> &other)
+
+ Same as intersect(\a other).
+
+ \sa operator&(), operator|=(), operator-=()
+*/
+
+/*!
+ \fn QSet<T> &QSet::operator&=(const T &value)
+
+ \overload
+
+ Same as intersect(\e{other}), if we consider \e{other} to be a set
+ that contains the singleton \a value.
+*/
+
+
+/*!
+ \fn QSet<T> &QSet::operator-=(const QSet<T> &other)
+
+ Same as subtract(\a{other}).
+
+ \sa operator-(), operator|=(), operator&=()
+*/
+
+/*!
+ \fn QSet<T> QSet::operator|(const QSet<T> &other) const
+ \fn QSet<T> QSet::operator+(const QSet<T> &other) const
+
+ Returns a new QSet that is the union of this set and the
+ \a other set.
+
+ \sa unite(), operator|=(), operator&(), operator-()
+*/
+
+/*!
+ \fn QSet<T> QSet::operator&(const QSet<T> &other) const
+
+ Returns a new QSet that is the intersection of this set and the
+ \a other set.
+
+ \sa intersect(), operator&=(), operator|(), operator-()
+*/
+
+/*!
+ \fn QSet<T> QSet::operator-(const QSet<T> &other) const
+
+ Returns a new QSet that is the set difference of this set and
+ the \a other set, i.e., this set - \a other set.
+
+ \sa subtract(), operator-=(), operator|(), operator&()
+*/
+
+/*!
+ \fn QSet<T> QSet::operator-(const QSet<T> &other)
+ \fn QSet<T> QSet::operator|(const QSet<T> &other)
+ \fn QSet<T> QSet::operator+(const QSet<T> &other)
+ \fn QSet<T> QSet::operator&(const QSet<T> &other)
+ \internal
+
+ These will go away in Qt 5.
+*/
+
+/*!
+ \class QSet::iterator
+ \since 4.2
+ \brief The QSet::iterator class provides an STL-style non-const iterator for QSet.
+
+ QSet features both \l{STL-style iterators} and
+ \l{Java-style iterators}. The STL-style iterators are more
+ low-level and more cumbersome to use; on the other hand, they are
+ slightly faster and, for developers who already know STL, have
+ the advantage of familiarity.
+
+ QSet<T>::iterator allows you to iterate over a QSet and to remove
+ items (using QSet::erase()) while you iterate. (QSet doesn't let
+ you \e modify a value through an iterator, because that
+ would potentially require moving the value in the internal hash
+ table used by QSet.) If you want to iterate over a const QSet,
+ you should use QSet::const_iterator. It is generally good
+ practice to use QSet::const_iterator on a non-const QSet as well,
+ unless you need to change the QSet through the iterator. Const
+ iterators are slightly faster, and can improve code readability.
+
+ QSet\<T\>::iterator allows you to iterate over a QSet\<T\> and
+ modify it as you go (using QSet::erase()). However,
+
+ The default QSet::iterator constructor creates an uninitialized
+ iterator. You must initialize it using a function like
+ QSet::begin(), QSet::end(), or QSet::insert() before you can
+ start iterating. Here's a typical loop that prints all the items
+ stored in a set:
+
+ \snippet doc/src/snippets/code/doc_src_qset.qdoc 8
+
+ Here's a loop that removes certain items (all those that start
+ with 'J') from a set while iterating:
+
+ \snippet doc/src/snippets/code/doc_src_qset.qdoc 9
+
+ STL-style iterators can be used as arguments to \l{generic
+ algorithms}. For example, here's how to find an item in the set
+ using the qFind() algorithm:
+
+ \snippet doc/src/snippets/code/doc_src_qset.qdoc 10
+
+ Multiple iterators can be used on the same set. However, you may
+ not attempt to modify the container while iterating on it.
+
+ \sa QSet::const_iterator, QMutableSetIterator
+*/
+
+/*!
+ \class QSet::const_iterator
+ \brief The QSet::const_iterator class provides an STL-style const iterator for QSet.
+ \since 4.2
+
+ QSet features both \l{STL-style iterators} and
+ \l{Java-style iterators}. The STL-style iterators are more
+ low-level and more cumbersome to use; on the other hand, they are
+ slightly faster and, for developers who already know STL, have
+ the advantage of familiarity.
+
+ QSet\<Key, T\>::const_iterator allows you to iterate over a QSet.
+ If you want to modify the QSet as you iterate over it, you must
+ use QSet::iterator instead. It is generally good practice to use
+ QSet::const_iterator on a non-const QSet as well, unless you need
+ to change the QSet through the iterator. Const iterators are
+ slightly faster, and can improve code readability.
+
+ The default QSet::const_iterator constructor creates an
+ uninitialized iterator. You must initialize it using a function
+ like QSet::begin(), QSet::end(), or QSet::insert() before you can
+ start iterating. Here's a typical loop that prints all the items
+ stored in a set:
+
+ \snippet doc/src/snippets/code/doc_src_qset.qdoc 11
+
+ STL-style iterators can be used as arguments to \l{generic
+ algorithms}. For example, here's how to find an item in the set
+ using the qFind() algorithm:
+
+ \snippet doc/src/snippets/code/doc_src_qset.qdoc 12
+
+ Multiple iterators can be used on the same set. However, you may
+ not attempt to modify the container while iterating on it.
+
+ \sa QSet::iterator, QSetIterator
+*/
+
+/*!
+ \fn QSet::iterator::iterator()
+ \fn QSet::const_iterator::const_iterator()
+
+ Constructs an uninitialized iterator.
+
+ Functions like operator*() and operator++() should not be called
+ on an uninitialized iterator. Use operator=() to assign a value
+ to it before using it.
+
+ \sa QSet::begin(), QSet::end()
+*/
+
+/*!
+ \fn QSet::iterator::iterator(typename Hash::iterator i)
+ \fn QSet::const_iterator::const_iterator(typename Hash::const_iterator i)
+
+ \internal
+*/
+
+/*!
+ \typedef QSet::iterator::iterator_category
+ \typedef QSet::const_iterator::iterator_category
+
+ Synonyms for \e {std::bidirectional_iterator_tag} indicating
+ these iterators are bidirectional iterators.
+ */
+
+/*!
+ \typedef QSet::iterator::difference_type
+ \typedef QSet::const_iterator::difference_type
+
+ \internal
+*/
+
+/*!
+ \typedef QSet::iterator::value_type
+ \typedef QSet::const_iterator::value_type
+
+ \internal
+*/
+
+/*!
+ \typedef QSet::iterator::pointer
+ \typedef QSet::const_iterator::pointer
+
+ \internal
+*/
+
+/*!
+ \typedef QSet::iterator::reference
+ \typedef QSet::const_iterator::reference
+
+ \internal
+*/
+
+/*!
+ \fn QSet::iterator::iterator(const iterator &other)
+ \fn QSet::const_iterator::const_iterator(const const_iterator &other)
+
+ Constructs a copy of \a other.
+*/
+
+/*!
+ \fn QSet::const_iterator::const_iterator(const iterator &other)
+ \since 4.2
+ \overload
+
+ Constructs a copy of \a other.
+*/
+
+/*!
+ \fn QSet::iterator &QSet::iterator::operator=(const iterator &other)
+ \fn QSet::const_iterator &QSet::const_iterator::operator=(const const_iterator &other)
+
+ Assigns \a other to this iterator.
+*/
+
+/*!
+ \fn const T &QSet::iterator::operator*() const
+ \fn const T &QSet::const_iterator::operator*() const
+
+ Returns a reference to the current item.
+
+ \sa operator->()
+*/
+
+/*!
+ \fn const T *QSet::iterator::operator->() const
+ \fn const T *QSet::const_iterator::operator->() const
+
+ Returns a pointer to the current item.
+
+ \sa operator*()
+*/
+
+/*!
+ \fn bool QSet::iterator::operator==(const iterator &other) const
+ \fn bool QSet::const_iterator::operator==(const const_iterator &other) const
+
+ Returns true if \a other points to the same item as this
+ iterator; otherwise returns false.
+
+ \sa operator!=()
+*/
+
+/*!
+ \fn bool QSet::iterator::operator==(const const_iterator &other) const
+ \fn bool QSet::iterator::operator!=(const const_iterator &other) const
+
+ \overload
+*/
+
+/*!
+ \fn bool QSet::iterator::operator!=(const iterator &other) const
+ \fn bool QSet::const_iterator::operator!=(const const_iterator &other) const
+
+ Returns true if \a other points to a different item than this
+ iterator; otherwise returns false.
+
+ \sa operator==()
+*/
+
+/*!
+ \fn QSet::iterator &QSet::iterator::operator++()
+ \fn QSet::const_iterator &QSet::const_iterator::operator++()
+
+ The prefix ++ operator (\c{++it}) advances the iterator to the
+ next item in the set and returns an iterator to the new current
+ item.
+
+ Calling this function on QSet::constEnd() leads to
+ undefined results.
+
+ \sa operator--()
+*/
+
+/*!
+ \fn QSet::iterator QSet::iterator::operator++(int)
+ \fn QSet::const_iterator QSet::const_iterator::operator++(int)
+
+ \overload
+
+ The postfix ++ operator (\c{it++}) advances the iterator to the
+ next item in the set and returns an iterator to the previously
+ current item.
+*/
+
+/*!
+ \fn QSet::iterator &QSet::iterator::operator--()
+ \fn QSet::const_iterator &QSet::const_iterator::operator--()
+
+ The prefix -- operator (\c{--it}) makes the preceding item
+ current and returns an iterator to the new current item.
+
+ Calling this function on QSet::begin() leads to undefined
+ results.
+
+ \sa operator++()
+*/
+
+/*!
+ \fn QSet::iterator QSet::iterator::operator--(int)
+ \fn QSet::const_iterator QSet::const_iterator::operator--(int)
+
+ \overload
+
+ The postfix -- operator (\c{it--}) makes the preceding item
+ current and returns an iterator to the previously current item.
+*/
+
+/*!
+ \fn QSet::iterator QSet::iterator::operator+(int j) const
+ \fn QSet::const_iterator QSet::const_iterator::operator+(int j) const
+
+ Returns an iterator to the item at \a j positions forward from
+ this iterator. (If \a j is negative, the iterator goes backward.)
+
+ This operation can be slow for large \a j values.
+
+ \sa operator-()
+*/
+
+/*!
+ \fn QSet::iterator QSet::iterator::operator-(int j) const
+ \fn QSet::const_iterator QSet::const_iterator::operator-(int j) const
+
+ Returns an iterator to the item at \a j positions backward from
+ this iterator. (If \a j is negative, the iterator goes forward.)
+
+ This operation can be slow for large \a j values.
+
+ \sa operator+()
+*/
+
+/*!
+ \fn QSet::iterator &QSet::iterator::operator+=(int j)
+ \fn QSet::const_iterator &QSet::const_iterator::operator+=(int j)
+
+ Advances the iterator by \a j items. (If \a j is negative, the
+ iterator goes backward.)
+
+ This operation can be slow for large \a j values.
+
+ \sa operator-=(), operator+()
+*/
+
+/*!
+ \fn QSet::iterator &QSet::iterator::operator-=(int j)
+ \fn QSet::const_iterator &QSet::const_iterator::operator-=(int j)
+
+ Makes the iterator go back by \a j items. (If \a j is negative,
+ the iterator goes forward.)
+
+ This operation can be slow for large \a j values.
+
+ \sa operator+=(), operator-()
+*/
+
+/*! \fn QList<T> QSet<T>::toList() const
+
+ Returns a new QList containing the elements in the set. The
+ order of the elements in the QList is undefined.
+
+ Example:
+
+ \snippet doc/src/snippets/code/doc_src_qset.qdoc 13
+
+ \sa fromList(), QList::fromSet(), qSort()
+*/
+
+/*! \fn QList<T> QSet<T>::values() const
+
+ Returns a new QList containing the elements in the set. The
+ order of the elements in the QList is undefined.
+
+ This is the same as toList().
+
+ \sa fromList(), QList::fromSet(), qSort()
+*/
+
+
+/*! \fn QSet<T> QSet<T>::fromList(const QList<T> &list)
+
+ Returns a new QSet object containing the data contained in \a
+ list. Since QSet doesn't allow duplicates, the resulting QSet
+ might be smaller than the \a list, because QList can contain
+ duplicates.
+
+ Example:
+
+ \snippet doc/src/snippets/code/doc_src_qset.qdoc 14
+
+ \sa toList(), QList::toSet()
+*/
+
+/*!
+ \fn QDataStream &operator<<(QDataStream &out, const QSet<T> &set)
+ \relates QSet
+
+ Writes the \a set to stream \a out.
+
+ This function requires the value type to implement \c operator<<().
+
+ \sa \link datastreamformat.html Format of the QDataStream operators \endlink
+*/
+
+/*!
+ \fn QDataStream &operator>>(QDataStream &in, QSet<T> &set)
+ \relates QSet
+
+ Reads a set from stream \a in into \a set.
+
+ This function requires the value type to implement \c operator>>().
+
+ \sa \link datastreamformat.html Format of the QDataStream operators \endlink
+*/
diff --git a/src/corelib/tools/qshareddata.cpp b/src/corelib/tools/qshareddata.cpp
index c96e058..e1f090b 100644
--- a/src/corelib/tools/qshareddata.cpp
+++ b/src/corelib/tools/qshareddata.cpp
@@ -44,507 +44,512 @@
QT_BEGIN_NAMESPACE
/*!
- \class QSharedData
- \brief The QSharedData class is a base class for shared data objects.
- \reentrant
- \ingroup misc
+ \class QSharedData
+ \brief The QSharedData class is a base class for shared data objects.
+ \reentrant
- QSharedData is designed to be used with QSharedDataPointer or
- QExplicitlySharedDataPointer to implement custom \l{implicitly
- shared} or explicitly shared classes. QSharedData provides
- \l{thread-safe} reference counting.
+ QSharedData is designed to be used with QSharedDataPointer or
+ QExplicitlySharedDataPointer to implement custom \l{implicitly
+ shared} or explicitly shared classes. QSharedData provides
+ \l{thread-safe} reference counting.
- See QSharedDataPointer and QExplicitlySharedDataPointer for details.
+ See QSharedDataPointer and QExplicitlySharedDataPointer for details.
*/
/*! \fn QSharedData::QSharedData()
- Constructs a QSharedData object with a reference count of 0.
+ Constructs a QSharedData object with a reference count of 0.
*/
/*! \fn QSharedData::QSharedData(const QSharedData& other)
- Constructs a QSharedData object with reference count 0.
- \a other is ignored.
+ Constructs a QSharedData object with reference count 0.
+ \a other is ignored.
*/
/*!
- \class QSharedDataPointer
- \brief The QSharedDataPointer class represents a pointer to an implicitly shared object.
- \since 4.0
- \reentrant
- \ingroup misc
- \mainclass
+ \class QSharedDataPointer
+ \brief The QSharedDataPointer class represents a pointer to an implicitly shared object.
+ \since 4.0
+ \reentrant
- QSharedDataPointer\<T\> makes writing your own \l {implicitly
- shared} classes easy. QSharedDataPointer implements \l {thread-safe}
- reference counting, ensuring that adding QSharedDataPointers to your
- \l {reentrant} classes won't make them non-reentrant.
+ QSharedDataPointer\<T\> makes writing your own \l {implicitly
+ shared} classes easy. QSharedDataPointer implements \l {thread-safe}
+ reference counting, ensuring that adding QSharedDataPointers to your
+ \l {reentrant} classes won't make them non-reentrant.
- \l {Implicit sharing} is used by many Qt classes to combine the
- speed and memory efficiency of pointers with the ease of use of
- classes. See the \l{Shared Classes} page for more information.
+ \l {Implicit sharing} is used by many Qt classes to combine the
+ speed and memory efficiency of pointers with the ease of use of
+ classes. See the \l{Shared Classes} page for more information.
- \target Employee example
- Suppose you want to make an \c Employee class implicitly shared. The
- procedure is:
+ \target Employee example
+ Suppose you want to make an \c Employee class implicitly shared. The
+ procedure is:
- \list
+ \list
- \o Define the class \c Employee to have a single data member of
+ \o Define the class \c Employee to have a single data member of
type \c {QSharedDataPointer<EmployeeData>}.
- \o Define the \c EmployeeData class derived from \l QSharedData to
+ \o Define the \c EmployeeData class derived from \l QSharedData to
contain all the data members you would normally have put in the
\c Employee class.
- \endlist
-
- To show this in practice, we review the source code for the
- implicitly shared \c Employee class. In the header file we define the
- two classes \c Employee and \c EmployeeData.
-
- \snippet doc/src/snippets/sharedemployee/employee.h 0
-
- In class \c Employee, note the single data member, a \e {d pointer}
- of type \c {QSharedDataPointer<EmployeeData>}. All accesses of
- employee data must go through the \e {d pointer's} \c
- {operator->()}. For write accesses, \c {operator->()} will
- automatically call detach(), which creates a copy of the shared data
- object if the shared data object's reference count is greater than
- 1. This ensures that writes to one \c Employee object don't affect
- any other \c Employee objects that share the same \c EmployeeData
- object.
-
- Class \c EmployeeData inherits QSharedData, which provides the
- \e{behind the scenes} reference counter. \c EmployeeData has a default
- constructor, a copy constructor, and a destructor. Normally, trivial
- implementations of these are all that is needed in the \e {data}
- class for an implicitly shared class.
-
- Implementing the two constructors for class \c Employee is also
- straightforward. Both create a new instance of \c EmployeeData
- and assign it to the \e{d pointer} .
-
- \snippet doc/src/snippets/sharedemployee/employee.h 1
- \codeline
- \snippet doc/src/snippets/sharedemployee/employee.h 2
-
- Note that class \c Employee also has a trivial copy constructor
- defined, which is not strictly required in this case.
-
- \snippet doc/src/snippets/sharedemployee/employee.h 7
-
- The copy constructor is not strictly required here, because class \c
- EmployeeData is included in the same file as class \c Employee
- (\c{employee.h}). However, including the private subclass of
- QSharedData in the same file as the public class containing the
- QSharedDataPointer is not typical. Normally, the idea is to hide the
- private subclass of QSharedData from the user by putting it in a
- separate file which would not be included in the public file. In
- this case, we would normally put class \c EmployeeData in a separate
- file, which would \e{not} be included in \c{employee.h}. Instead, we
- would just predeclare the private subclass \c EmployeeData in \c
- {employee.h} this way:
-
- \code
- class EmployeeData;
- \endcode
-
- If we had done it that way here, the copy constructor shown would be
- required. Since the copy constructor is trivial, you might as well
- just always include it.
-
- Behind the scenes, QSharedDataPointer automatically increments the
- reference count whenever an \c Employee object is copied, assigned,
- or passed as a parameter. It decrements the reference count whenever
- an \c Employee object is deleted or goes out of scope. The shared
- \c EmployeeData object is deleted automatically if and when the
- reference count reaches 0.
-
- In a non-const member function of \c Employee, whenever the \e {d
- pointer} is dereferenced, QSharedDataPointer automatically calls
- detach() to ensure that the function operates on its own copy of the
- data.
-
- \snippet doc/src/snippets/sharedemployee/employee.h 3
- \codeline
- \snippet doc/src/snippets/sharedemployee/employee.h 4
-
- Note that if detach() is called more than once in a member function
- due to multiple dereferences of the \e {d pointer}, detach() will
- only create a copy of the shared data the first time it is called,
- if at all, because on the second and subsequent calls of detach(),
- the reference count will be 1 again.
-
- But note that in the second \c Employee constructor, which takes an
- employee ID and a name, both setId() and setName() are called, but
- they don't cause \e{copy on write}, because the reference count for
- the newly constructed \c EmployeeData object has just been set to 1.
-
- In \c Employee's \e const member functions, dereferencing the \e {d
- pointer} does \e not cause detach() to be called.
-
- \snippet doc/src/snippets/sharedemployee/employee.h 5
- \codeline
- \snippet doc/src/snippets/sharedemployee/employee.h 6
-
- Notice that there is no need to implement a copy constructor or an
- assignment operator for the \c Employee class, because the copy
- constructor and assignment operator provided by the C++ compiler
- will do the \e{member by member} shallow copy required. The only
- member to copy is the \e {d pointer}, which is a QSharedDataPointer,
- whose \c {operator=()} just increments the reference count of the
- shared \c EmployeeData object.
-
- \target Implicit vs Explicit Sharing
- \section1 Implicit vs Explicit Sharing
-
- Implicit sharing might not be right for the \c Employee class.
- Consider a simple example that creates two instances of the
- implicitly shared \c Employee class.
-
- \snippet doc/src/snippets/sharedemployee/main.cpp 0
-
- After the second employee e2 is created and e1 is assigned to it,
- both \c e1 and \c e2 refer to Albrecht Durer, employee 1001. Both \c
- Employee objects point to the same instance of \c EmployeeData,
- which has reference count 2. Then \c {e1.setName("Hans Holbein")} is
- called to change the employee name, but because the reference count
- is greater than 1, a \e{copy on write} is performed before the name
- is changed. Now \c e1 and \c e2 point to different \c EmployeeData
- objects. They have different names, but both have ID 1001, which is
- probably not what you want. You can, of course, just continue with
- \c {e1.setId(1002)}, if you really mean to create a second, unique
- employee, but if you only want to change the employee's name
- everywhere, consider using \l {QExplicitlySharedDataPointer}
- {explicit sharing} in the \c Employee class instead of implicit
- sharing.
-
- If you declare the \e {d pointer} in the \c Employee class to be
- \c {QExplicitlySharedDataPointer<EmployeeData>}, then explicit
- sharing is used and \e{copy on write} operations are not performed
- automatically (i.e. detach() is not called in non-const
- functions). In that case, after \c {e1.setName("Hans Holbein")}, the
- employee's name has been changed, but both e1 and e2 still refer to
- the same instance of \c EmployeeData, so there is only one employee
- with ID 1001.
-
- In the member function documentation, \e{d pointer} always refers
- to the internal pointer to the shared data object.
-
- \sa QSharedData, QExplicitlySharedDataPointer, QScopedPointer, QSharedPointer
+ \endlist
+
+ To show this in practice, we review the source code for the
+ implicitly shared \c Employee class. In the header file we define the
+ two classes \c Employee and \c EmployeeData.
+
+ \snippet doc/src/snippets/sharedemployee/employee.h 0
+
+ In class \c Employee, note the single data member, a \e {d pointer}
+ of type \c {QSharedDataPointer<EmployeeData>}. All accesses of
+ employee data must go through the \e {d pointer's} \c
+ {operator->()}. For write accesses, \c {operator->()} will
+ automatically call detach(), which creates a copy of the shared data
+ object if the shared data object's reference count is greater than
+ 1. This ensures that writes to one \c Employee object don't affect
+ any other \c Employee objects that share the same \c EmployeeData
+ object.
+
+ Class \c EmployeeData inherits QSharedData, which provides the
+ \e{behind the scenes} reference counter. \c EmployeeData has a default
+ constructor, a copy constructor, and a destructor. Normally, trivial
+ implementations of these are all that is needed in the \e {data}
+ class for an implicitly shared class.
+
+ Implementing the two constructors for class \c Employee is also
+ straightforward. Both create a new instance of \c EmployeeData
+ and assign it to the \e{d pointer} .
+
+ \snippet doc/src/snippets/sharedemployee/employee.h 1
+ \codeline
+ \snippet doc/src/snippets/sharedemployee/employee.h 2
+
+ Note that class \c Employee also has a trivial copy constructor
+ defined, which is not strictly required in this case.
+
+ \snippet doc/src/snippets/sharedemployee/employee.h 7
+
+ The copy constructor is not strictly required here, because class \c
+ EmployeeData is included in the same file as class \c Employee
+ (\c{employee.h}). However, including the private subclass of
+ QSharedData in the same file as the public class containing the
+ QSharedDataPointer is not typical. Normally, the idea is to hide the
+ private subclass of QSharedData from the user by putting it in a
+ separate file which would not be included in the public file. In
+ this case, we would normally put class \c EmployeeData in a separate
+ file, which would \e{not} be included in \c{employee.h}. Instead, we
+ would just predeclare the private subclass \c EmployeeData in \c
+ {employee.h} this way:
+
+ \code
+ class EmployeeData;
+ \endcode
+
+ If we had done it that way here, the copy constructor shown would be
+ required. Since the copy constructor is trivial, you might as well
+ just always include it.
+
+ Behind the scenes, QSharedDataPointer automatically increments the
+ reference count whenever an \c Employee object is copied, assigned,
+ or passed as a parameter. It decrements the reference count whenever
+ an \c Employee object is deleted or goes out of scope. The shared
+ \c EmployeeData object is deleted automatically if and when the
+ reference count reaches 0.
+
+ In a non-const member function of \c Employee, whenever the \e {d
+ pointer} is dereferenced, QSharedDataPointer automatically calls
+ detach() to ensure that the function operates on its own copy of the
+ data.
+
+ \snippet doc/src/snippets/sharedemployee/employee.h 3
+ \codeline
+ \snippet doc/src/snippets/sharedemployee/employee.h 4
+
+ Note that if detach() is called more than once in a member function
+ due to multiple dereferences of the \e {d pointer}, detach() will
+ only create a copy of the shared data the first time it is called,
+ if at all, because on the second and subsequent calls of detach(),
+ the reference count will be 1 again.
+
+ But note that in the second \c Employee constructor, which takes an
+ employee ID and a name, both setId() and setName() are called, but
+ they don't cause \e{copy on write}, because the reference count for
+ the newly constructed \c EmployeeData object has just been set to 1.
+
+ In \c Employee's \e const member functions, dereferencing the \e {d
+ pointer} does \e not cause detach() to be called.
+
+ \snippet doc/src/snippets/sharedemployee/employee.h 5
+ \codeline
+ \snippet doc/src/snippets/sharedemployee/employee.h 6
+
+ Notice that there is no need to implement a copy constructor or an
+ assignment operator for the \c Employee class, because the copy
+ constructor and assignment operator provided by the C++ compiler
+ will do the \e{member by member} shallow copy required. The only
+ member to copy is the \e {d pointer}, which is a QSharedDataPointer,
+ whose \c {operator=()} just increments the reference count of the
+ shared \c EmployeeData object.
+
+ \target Implicit vs Explicit Sharing
+ \section1 Implicit vs Explicit Sharing
+
+ Implicit sharing might not be right for the \c Employee class.
+ Consider a simple example that creates two instances of the
+ implicitly shared \c Employee class.
+
+ \snippet doc/src/snippets/sharedemployee/main.cpp 0
+
+ After the second employee e2 is created and e1 is assigned to it,
+ both \c e1 and \c e2 refer to Albrecht Durer, employee 1001. Both \c
+ Employee objects point to the same instance of \c EmployeeData,
+ which has reference count 2. Then \c {e1.setName("Hans Holbein")} is
+ called to change the employee name, but because the reference count
+ is greater than 1, a \e{copy on write} is performed before the name
+ is changed. Now \c e1 and \c e2 point to different \c EmployeeData
+ objects. They have different names, but both have ID 1001, which is
+ probably not what you want. You can, of course, just continue with
+ \c {e1.setId(1002)}, if you really mean to create a second, unique
+ employee, but if you only want to change the employee's name
+ everywhere, consider using \l {QExplicitlySharedDataPointer}
+ {explicit sharing} in the \c Employee class instead of implicit
+ sharing.
+
+ If you declare the \e {d pointer} in the \c Employee class to be
+ \c {QExplicitlySharedDataPointer<EmployeeData>}, then explicit
+ sharing is used and \e{copy on write} operations are not performed
+ automatically (i.e. detach() is not called in non-const
+ functions). In that case, after \c {e1.setName("Hans Holbein")}, the
+ employee's name has been changed, but both e1 and e2 still refer to
+ the same instance of \c EmployeeData, so there is only one employee
+ with ID 1001.
+
+ In the member function documentation, \e{d pointer} always refers
+ to the internal pointer to the shared data object.
+
+ \sa QSharedData, QExplicitlySharedDataPointer, QScopedPointer, QSharedPointer
*/
/*! \fn T& QSharedDataPointer::operator*()
- Provides access to the shared data object's members.
- This function calls detach().
+ Provides access to the shared data object's members.
+ This function calls detach().
*/
/*! \fn const T& QSharedDataPointer::operator*() const
- Provides const access to the shared data object's members.
- This function does \e not call detach().
+ Provides const access to the shared data object's members.
+ This function does \e not call detach().
*/
/*! \fn T* QSharedDataPointer::operator->()
- Provides access to the shared data object's members.
- This function calls detach().
+ Provides access to the shared data object's members.
+ This function calls detach().
*/
/*! \fn const T* QSharedDataPointer::operator->() const
- Provides const access to the shared data object's members.
- This function does \e not call detach().
+ Provides const access to the shared data object's members.
+ This function does \e not call detach().
*/
/*! \fn QSharedDataPointer::operator T*()
- Returns a pointer to the shared data object.
- This function calls detach().
+ Returns a pointer to the shared data object.
+ This function calls detach().
- \sa data(), constData()
+ \sa data(), constData()
*/
/*! \fn QSharedDataPointer::operator const T*() const
- Returns a pointer to the shared data object.
- This function does \e not call detach().
+ Returns a pointer to the shared data object.
+ This function does \e not call detach().
*/
/*! \fn T* QSharedDataPointer::data()
- Returns a pointer to the shared data object.
- This function calls detach().
+ Returns a pointer to the shared data object.
+ This function calls detach().
- \sa constData()
+ \sa constData()
*/
/*! \fn const T* QSharedDataPointer::data() const
- Returns a pointer to the shared data object.
- This function does \e not call detach().
+ Returns a pointer to the shared data object.
+ This function does \e not call detach().
*/
/*! \fn const T* QSharedDataPointer::constData() const
- Returns a const pointer to the shared data object.
- This function does \e not call detach().
+ Returns a const pointer to the shared data object.
+ This function does \e not call detach().
- \sa data()
+ \sa data()
*/
+/*! \fn void QSharedDataPointer::swap(QSharedDataPointer &other)
+ Swap this instance's shared data pointer with the shared
+ data pointer in \a other.
+ */
+
/*! \fn bool QSharedDataPointer::operator==(const QSharedDataPointer<T>& other) const
- Returns true if \a other and \e this have the same \e{d pointer}.
- This function does \e not call detach().
+ Returns true if \a other and \e this have the same \e{d pointer}.
+ This function does \e not call detach().
*/
/*! \fn bool QSharedDataPointer::operator!=(const QSharedDataPointer<T>& other) const
- Returns true if \a other and \e this do \e not have the same
- \e{d pointer}. This function does \e not call detach().
+ Returns true if \a other and \e this do \e not have the same
+ \e{d pointer}. This function does \e not call detach().
*/
/*! \fn QSharedDataPointer::QSharedDataPointer()
- Constructs a QSharedDataPointer initialized with a null \e{d pointer}.
+ Constructs a QSharedDataPointer initialized with a null \e{d pointer}.
*/
/*! \fn QSharedDataPointer::~QSharedDataPointer()
- Decrements the reference count of the shared data object.
- If the reference count becomes 0, the shared data object
- is deleted. \e This is then destroyed.
+ Decrements the reference count of the shared data object.
+ If the reference count becomes 0, the shared data object
+ is deleted. \e This is then destroyed.
*/
/*! \fn QSharedDataPointer::QSharedDataPointer(T* sharedData)
- Constructs a QSharedDataPointer with \e{d pointer} set to
- \a sharedData and increments \a{sharedData}'s reference count.
+ Constructs a QSharedDataPointer with \e{d pointer} set to
+ \a sharedData and increments \a{sharedData}'s reference count.
*/
/*! \fn QSharedDataPointer::QSharedDataPointer(const QSharedDataPointer<T>& other)
- Sets the \e{d pointer} of \e this to the \e{d pointer} in
- \a other and increments the reference count of the shared
- data object.
+ Sets the \e{d pointer} of \e this to the \e{d pointer} in
+ \a other and increments the reference count of the shared
+ data object.
*/
/*! \fn QSharedDataPointer<T>& QSharedDataPointer::operator=(const QSharedDataPointer<T>& other)
- Sets the \e{d pointer} of \e this to the \e{d pointer} of
- \a other and increments the reference count of the shared
- data object. The reference count of the old shared data
- object of \e this is decremented. If the reference count
- of the old shared data object becomes 0, the old shared
- data object is deleted.
+ Sets the \e{d pointer} of \e this to the \e{d pointer} of
+ \a other and increments the reference count of the shared
+ data object. The reference count of the old shared data
+ object of \e this is decremented. If the reference count
+ of the old shared data object becomes 0, the old shared
+ data object is deleted.
*/
/*! \fn QSharedDataPointer& QSharedDataPointer::operator=(T* sharedData)
- Sets the \e{d pointer} og \e this to \a sharedData and increments
- \a{sharedData}'s reference count. The reference count of the old
- shared data object of \e this is decremented. If the reference
- count of the old shared data object becomes 0, the old shared data
- object is deleted.
+ Sets the \e{d pointer} og \e this to \a sharedData and increments
+ \a{sharedData}'s reference count. The reference count of the old
+ shared data object of \e this is decremented. If the reference
+ count of the old shared data object becomes 0, the old shared data
+ object is deleted.
*/
/*! \fn bool QSharedDataPointer::operator!() const
- Returns true if the \e{d pointer} of \e this is null.
+ Returns true if the \e{d pointer} of \e this is null.
*/
/*! \fn void QSharedDataPointer::detach()
- If the shared data object's reference count is greater than 1, this
- function creates a deep copy of the shared data object and sets the
- \e{d pointer} of \e this to the copy.
-
- This function is called automatically by non-const member
- functions of QSharedDataPointer if \e{copy on write} is
- required. You don't need to call it yourself.
+ If the shared data object's reference count is greater than 1, this
+ function creates a deep copy of the shared data object and sets the
+ \e{d pointer} of \e this to the copy.
+
+ This function is called automatically by non-const member
+ functions of QSharedDataPointer if \e{copy on write} is
+ required. You don't need to call it yourself.
*/
/*! \fn T *QSharedDataPointer::clone()
\since 4.5
- Creates and returns a deep copy of the current data. This function
- is called by detach() when the reference count is greater than 1 in
- order to create the new copy. This function uses the \e {operator
- new} and calls the copy constructor of the type T.
+ Creates and returns a deep copy of the current data. This function
+ is called by detach() when the reference count is greater than 1 in
+ order to create the new copy. This function uses the \e {operator
+ new} and calls the copy constructor of the type T.
- This function is provided so that you may support "virtual copy
- constructors" for your own types. In order to so, you should declare
- a template-specialization of this function for your own type, like
- the example below:
+ This function is provided so that you may support "virtual copy
+ constructors" for your own types. In order to so, you should declare
+ a template-specialization of this function for your own type, like
+ the example below:
- \code
+ \code
template<>
EmployeeData *QSharedDataPointer<EmployeeData>::clone()
{
return d->clone();
}
- \endcode
+ \endcode
- In the example above, the template specialization for the clone()
- function calls the \e {EmployeeData::clone()} virtual function. A
- class derived from EmployeeData could override that function and
- return the proper polymorphic type.
+ In the example above, the template specialization for the clone()
+ function calls the \e {EmployeeData::clone()} virtual function. A
+ class derived from EmployeeData could override that function and
+ return the proper polymorphic type.
*/
/*!
- \class QExplicitlySharedDataPointer
- \brief The QExplicitlySharedDataPointer class represents a pointer to an explicitly shared object.
- \since 4.4
- \reentrant
- \ingroup misc
- \mainclass
-
- QExplicitlySharedDataPointer\<T\> makes writing your own explicitly
- shared classes easy. QExplicitlySharedDataPointer implements
- \l {thread-safe} reference counting, ensuring that adding
- QExplicitlySharedDataPointers to your \l {reentrant} classes won't
- make them non-reentrant.
-
- Except for one big difference, QExplicitlySharedDataPointer is just
- like QSharedDataPointer. The big difference is that member functions
- of QExplicitlySharedDataPointer \e{do not} do the automatic
- \e{copy on write} operation (detach()) that non-const members of
- QSharedDataPointer do before allowing the shared data object to be
- modified. There is a detach() function available, but if you really
- want to detach(), you have to call it yourself. This means that
- QExplicitlySharedDataPointers behave like regular C++ pointers,
- except that by doing reference counting and not deleting the shared
- data object until the reference count is 0, they avoid the dangling
- pointer problem.
-
- It is instructive to compare QExplicitlySharedDataPointer with
- QSharedDataPointer by way of an example. Consider the \l {Employee
- example} in QSharedDataPointer, modified to use explicit sharing as
- explained in the discussion \l {Implicit vs Explicit Sharing}.
-
- Note that if you use this class but find you are calling detach() a
- lot, you probably should be using QSharedDataPointer instead.
-
- In the member function documentation, \e{d pointer} always refers
- to the internal pointer to the shared data object.
-
- \sa QSharedData, QSharedDataPointer
+ \class QExplicitlySharedDataPointer
+ \brief The QExplicitlySharedDataPointer class represents a pointer to an explicitly shared object.
+ \since 4.4
+ \reentrant
+
+ QExplicitlySharedDataPointer\<T\> makes writing your own explicitly
+ shared classes easy. QExplicitlySharedDataPointer implements
+ \l {thread-safe} reference counting, ensuring that adding
+ QExplicitlySharedDataPointers to your \l {reentrant} classes won't
+ make them non-reentrant.
+
+ Except for one big difference, QExplicitlySharedDataPointer is just
+ like QSharedDataPointer. The big difference is that member functions
+ of QExplicitlySharedDataPointer \e{do not} do the automatic
+ \e{copy on write} operation (detach()) that non-const members of
+ QSharedDataPointer do before allowing the shared data object to be
+ modified. There is a detach() function available, but if you really
+ want to detach(), you have to call it yourself. This means that
+ QExplicitlySharedDataPointers behave like regular C++ pointers,
+ except that by doing reference counting and not deleting the shared
+ data object until the reference count is 0, they avoid the dangling
+ pointer problem.
+
+ It is instructive to compare QExplicitlySharedDataPointer with
+ QSharedDataPointer by way of an example. Consider the \l {Employee
+ example} in QSharedDataPointer, modified to use explicit sharing as
+ explained in the discussion \l {Implicit vs Explicit Sharing}.
+
+ Note that if you use this class but find you are calling detach() a
+ lot, you probably should be using QSharedDataPointer instead.
+
+ In the member function documentation, \e{d pointer} always refers
+ to the internal pointer to the shared data object.
+
+ \sa QSharedData, QSharedDataPointer
*/
/*! \fn T& QExplicitlySharedDataPointer::operator*() const
- Provides access to the shared data object's members.
+ Provides access to the shared data object's members.
*/
/*! \fn T* QExplicitlySharedDataPointer::operator->()
- Provides access to the shared data object's members.
+ Provides access to the shared data object's members.
*/
/*! \fn const T* QExplicitlySharedDataPointer::operator->() const
- Provides const access to the shared data object's members.
+ Provides const access to the shared data object's members.
*/
/*! \fn T* QExplicitlySharedDataPointer::data() const
- Returns a pointer to the shared data object.
+ Returns a pointer to the shared data object.
*/
/*! \fn const T* QExplicitlySharedDataPointer::constData() const
- Returns a const pointer to the shared data object.
+ Returns a const pointer to the shared data object.
- \sa data()
+ \sa data()
*/
+/*! \fn void QExplicitlySharedDataPointer::swap(QExplicitlySharedDataPointer &other)
+ Swap this instance's explicitly shared data pointer with
+ the explicitly shared data pointer in \a other.
+ */
+
/*! \fn bool QExplicitlySharedDataPointer::operator==(const QExplicitlySharedDataPointer<T>& other) const
- Returns true if \a other and \e this have the same \e{d pointer}.
+ Returns true if \a other and \e this have the same \e{d pointer}.
*/
/*! \fn bool QExplicitlySharedDataPointer::operator==(const T* ptr) const
- Returns true if the \e{d pointer} of \e this is \a ptr.
+ Returns true if the \e{d pointer} of \e this is \a ptr.
*/
/*! \fn bool QExplicitlySharedDataPointer::operator!=(const QExplicitlySharedDataPointer<T>& other) const
- Returns true if \a other and \e this do \e not have the same
- \e{d pointer}.
+ Returns true if \a other and \e this do \e not have the same
+ \e{d pointer}.
*/
/*! \fn bool QExplicitlySharedDataPointer::operator!=(const T* ptr) const
- Returns true if the \e{d pointer} of \e this is \e not \a ptr.
+ Returns true if the \e{d pointer} of \e this is \e not \a ptr.
*/
/*! \fn QExplicitlySharedDataPointer::QExplicitlySharedDataPointer()
- Constructs a QExplicitlySharedDataPointer initialized with a null
- \e{d pointer}.
+ Constructs a QExplicitlySharedDataPointer initialized with a null
+ \e{d pointer}.
*/
/*! \fn QExplicitlySharedDataPointer::~QExplicitlySharedDataPointer()
- Decrements the reference count of the shared data object.
- If the reference count becomes 0, the shared data object
- is deleted. \e This is then destroyed.
+ Decrements the reference count of the shared data object.
+ If the reference count becomes 0, the shared data object
+ is deleted. \e This is then destroyed.
*/
/*! \fn QExplicitlySharedDataPointer::QExplicitlySharedDataPointer(T* sharedData)
- Constructs a QExplicitlySharedDataPointer with \e{d pointer}
- set to \a sharedData and increments \a{sharedData}'s reference
- count.
+ Constructs a QExplicitlySharedDataPointer with \e{d pointer}
+ set to \a sharedData and increments \a{sharedData}'s reference
+ count.
*/
/*! \fn QExplicitlySharedDataPointer::QExplicitlySharedDataPointer(const QExplicitlySharedDataPointer<T>& other)
- This standard copy constructor sets the \e {d pointer} of \e this to
- the \e {d pointer} in \a other and increments the reference count of
- the shared data object.
+ This standard copy constructor sets the \e {d pointer} of \e this to
+ the \e {d pointer} in \a other and increments the reference count of
+ the shared data object.
*/
/*! \fn QExplicitlySharedDataPointer::QExplicitlySharedDataPointer(const QExplicitlySharedDataPointer<X>& other)
- This copy constructor is different in that it allows \a other to be
- a different type of explicitly shared data pointer but one that has
- a compatible shared data object. It performs a static cast of the
- \e{d pointer} in \a other and sets the \e {d pointer} of \e this to
- the converted \e{d pointer}. It increments the reference count of
- the shared data object.
- */
+ This copy constructor is different in that it allows \a other to be
+ a different type of explicitly shared data pointer but one that has
+ a compatible shared data object. It performs a static cast of the
+ \e{d pointer} in \a other and sets the \e {d pointer} of \e this to
+ the converted \e{d pointer}. It increments the reference count of
+ the shared data object.
+*/
/*! \fn QExplicitlySharedDataPointer<T>& QExplicitlySharedDataPointer::operator=(const QExplicitlySharedDataPointer<T>& other)
- Sets the \e{d pointer} of \e this to the \e{d pointer} of
- \a other and increments the reference count of the shared
- data object. The reference count of the old shared data
- object of \e this is decremented. If the reference count
- of the old shared data object becomes 0, the old shared
- data object is deleted.
+ Sets the \e{d pointer} of \e this to the \e{d pointer} of
+ \a other and increments the reference count of the shared
+ data object. The reference count of the old shared data
+ object of \e this is decremented. If the reference count
+ of the old shared data object becomes 0, the old shared
+ data object is deleted.
*/
/*! \fn QExplicitlySharedDataPointer& QExplicitlySharedDataPointer::operator=(T* sharedData)
- Sets the \e{d pointer} of \e this to \a sharedData and
- increments \a{sharedData}'s reference count. The reference
- count of the old shared data object of \e this is decremented.
- If the reference count of the old shared data object becomes
- 0, the old shared data object is deleted.
+ Sets the \e{d pointer} of \e this to \a sharedData and
+ increments \a{sharedData}'s reference count. The reference
+ count of the old shared data object of \e this is decremented.
+ If the reference count of the old shared data object becomes
+ 0, the old shared data object is deleted.
*/
/*! \fn void QExplicitlySharedDataPointer::reset()
- Resets \e this to be null. i.e., this function sets the
- \e{d pointer} of \e this to 0, but first it decrements
- the reference count of the shared data object and deletes
- the shared data object if the reference count became 0.
+ Resets \e this to be null. i.e., this function sets the
+ \e{d pointer} of \e this to 0, but first it decrements
+ the reference count of the shared data object and deletes
+ the shared data object if the reference count became 0.
*/
/*! \fn QExplicitlySharedDataPointer::operator bool () const
- Returns true if the \e{d pointer} of \e this is \e not null.
+ Returns true if the \e{d pointer} of \e this is \e not null.
*/
/*! \fn bool QExplicitlySharedDataPointer::operator!() const
- Returns true if the \e{d pointer} of \e this is null.
+ Returns true if the \e{d pointer} of \e this is null.
*/
/*! \fn void QExplicitlySharedDataPointer::detach()
- If the shared data object's reference count is greater than 1, this
- function creates a deep copy of the shared data object and sets the
- \e{d pointer} of \e this to the copy.
+ If the shared data object's reference count is greater than 1, this
+ function creates a deep copy of the shared data object and sets the
+ \e{d pointer} of \e this to the copy.
- Because QExplicitlySharedDataPointer does not do the automatic
- \e{copy on write} operations that members of QSharedDataPointer do,
- detach() is \e not called automatically anywhere in the member
- functions of this class. If you find that you are calling detach()
- everywhere in your code, consider using QSharedDataPointer instead.
+ Because QExplicitlySharedDataPointer does not do the automatic
+ \e{copy on write} operations that members of QSharedDataPointer do,
+ detach() is \e not called automatically anywhere in the member
+ functions of this class. If you find that you are calling detach()
+ everywhere in your code, consider using QSharedDataPointer instead.
*/
/*! \fn T *QExplicitlySharedDataPointer::clone()
\since 4.5
- Creates and returns a deep copy of the current data. This function
- is called by detach() when the reference count is greater than 1 in
- order to create the new copy. This function uses the \e {operator
- new} and calls the copy constructor of the type T.
+ Creates and returns a deep copy of the current data. This function
+ is called by detach() when the reference count is greater than 1 in
+ order to create the new copy. This function uses the \e {operator
+ new} and calls the copy constructor of the type T.
- See QSharedDataPointer::clone() for an explanation of how to use it.
+ See QSharedDataPointer::clone() for an explanation of how to use it.
*/
/*!
- \typedef QExplicitlySharedDataPointer::Type
+ \typedef QExplicitlySharedDataPointer::Type
- This is the type of the shared data object. The \e{d pointer}
- points to an object of this type.
- */
+ This is the type of the shared data object. The \e{d pointer}
+ points to an object of this type.
+*/
QT_END_NAMESPACE
diff --git a/src/corelib/tools/qshareddata.h b/src/corelib/tools/qshareddata.h
index e13e37c..dde6e88 100644
--- a/src/corelib/tools/qshareddata.h
+++ b/src/corelib/tools/qshareddata.h
@@ -111,6 +111,9 @@ public:
inline bool operator!() const { return !d; }
+ inline void swap(QSharedDataPointer &other)
+ { qSwap(d, other.d); }
+
protected:
T *clone();
@@ -186,6 +189,9 @@ public:
inline bool operator!() const { return !d; }
+ inline void swap(QExplicitlySharedDataPointer &other)
+ { qSwap(d, other.d); }
+
protected:
T *clone();
@@ -235,6 +241,14 @@ template <class T>
Q_INLINE_TEMPLATE QExplicitlySharedDataPointer<T>::QExplicitlySharedDataPointer(T *adata) : d(adata)
{ if (d) d->ref.ref(); }
+template <class T>
+Q_INLINE_TEMPLATE void qSwap(QSharedDataPointer<T> &p1, QSharedDataPointer<T> &p2)
+{ p1.swap(p2); }
+
+template <class T>
+Q_INLINE_TEMPLATE void qSwap(QExplicitlySharedDataPointer<T> &p1, QExplicitlySharedDataPointer<T> &p2)
+{ p1.swap(p2); }
+
QT_END_NAMESPACE
QT_END_HEADER
diff --git a/src/corelib/tools/qsharedpointer.cpp b/src/corelib/tools/qsharedpointer.cpp
index f0e85d2..641d990 100644
--- a/src/corelib/tools/qsharedpointer.cpp
+++ b/src/corelib/tools/qsharedpointer.cpp
@@ -50,7 +50,6 @@
\since 4.5
\reentrant
- \ingroup misc
The QSharedPointer is an automatic, shared pointer in C++. It
behaves exactly like a normal pointer for normal purposes,
@@ -112,6 +111,249 @@
cases, since they have the same functionality. See
\l{QWeakPointer#tracking-qobject} for more information.
+ \section1 Optional pointer tracking
+
+ A feature of QSharedPointer that can be enabled at compile-time for
+ debugging purposes is a pointer tracking mechanism. When enabled,
+ QSharedPointer registers in a global set all the pointers that it tracks.
+ This allows one to catch mistakes like assigning the same pointer to two
+ QSharedPointer objects.
+
+ This function is enabled by defining the \tt{QT_SHAREDPOINTER_TRACK_POINTERS}
+ macro before including the QSharedPointer header.
+
+ It is safe to use this feature even with code compiled without the
+ feature. QSharedPointer will ensure that the pointer is removed from the
+ tracker even from code compiled without pointer tracking.
+
+ Note, however, that the pointer tracking feature has limitations on
+ multiple- or virtual-inheritance (that is, in cases where two different
+ pointer addresses can refer to the same object). In that case, if a
+ pointer is cast to a different type and its value changes,
+ QSharedPointer's pointer tracking mechanism mail fail to detect that the
+ object being tracked is the same.
+
+ \omit
+ \secton1 QSharedPointer internals
+
+ QSharedPointer is in reality implemented by two ancestor classes:
+ QtSharedPointer::Basic and QtSharedPointer::ExternalRefCount. The reason
+ for having that split is now mostly legacy: in the beginning,
+ QSharedPointer was meant to support both internal reference counting and
+ external reference counting.
+
+ QtSharedPointer::Basic implements the basic functionality that is shared
+ between internal- and external-reference counting. That is, it's mostly
+ the accessor functions into QSharedPointer. Those are all inherited by
+ QSharedPointer, which adds another level of shared functionality (the
+ constructors and assignment operators). The Basic class has one member
+ variable, which is the actual pointer being tracked.
+
+ QtSharedPointer::ExternalRefCount implements the actual reference
+ counting and introduces the d-pointer for QSharedPointer. That d-pointer
+ itself is shared with with other QSharedPointer objects as well as
+ QWeakPointer.
+
+ The reason for keeping the pointer value itself outside the d-pointer is
+ because of multiple inheritance needs. If you have two QSharedPointer
+ objects of different pointer types, but pointing to the same object in
+ memory, it could happen that the pointer values are different. The \tt
+ differentPointers autotest exemplifies this problem. The same thing could
+ happen in the case of virtual inheritance: a pointer of class matching
+ the virtual base has different address compared to the pointer of the
+ complete object. See the \tt virtualBaseDifferentPointers autotest for
+ this problem.
+
+ The d pointer is of type QtSharedPointer::ExternalRefCountData for simple
+ QSharedPointer objects, but could be of a derived type in some cases. It
+ is basically a reference-counted reference-counter.
+
+ \section2 d-pointer
+ \section3 QtSharedPointer::ExternalRefCountData
+
+ This class is basically a reference-counted reference-counter. It has two
+ members: \tt strongref and \tt weakref. The strong reference counter is
+ controlling the lifetime of the object tracked by QSharedPointer. a
+ positive value indicates that the object is alive. It's also the number
+ of QSharedObject instances that are attached to this Data.
+
+ When the strong reference count decreases to zero, the object is deleted
+ (see below for information on custom deleters). The strong reference
+ count can also exceptionally be -1, indicating that there are no
+ QSharedPointers attached to an object, which is tracked too. The only
+ case where this is possible is that of
+ \l{QWeakPointer#tracking-qobject}{QWeakPointers tracking a QObject}.
+
+ The weak reference count controls the lifetime of the d-pointer itself.
+ It can be thought of as an internal/intrusive reference count for
+ ExternalRefCountData itself. This count is equal to the number of
+ QSharedPointers and QWeakPointers that are tracking this object. (In case
+ the object tracked derives from QObject, this number is increased by 1,
+ since QObjectPrivate tracks it too).
+
+ ExternalRefCountData is a virtual class: it has a virtual destructor and
+ a virtual destroy() function. The destroy() function is supposed to
+ delete the object being tracked and return true if it does so. Otherwise,
+ it returns false to indicate that the caller must simply call delete.
+ This allows the normal use-case of QSharedPointer without custom deleters
+ to use only one 12- or 16-byte (depending on whether it's a 32- or 64-bit
+ architecture) external descriptor structure, without paying the price for
+ the custom deleter that it isn't using.
+
+ \section3 QtSharedPointer::ExternalRefCountDataWithDestroyFn
+
+ This class is not used directly, per se. It only exists to enable the two
+ classes that derive from it. It adds one member variable, which is a
+ pointer to a function (which returns void and takes an
+ ExternalRefCountData* as a parameter). It also overrides the destroy()
+ function: it calls that function pointer with \tt this as parameter, and
+ returns true.
+
+ That means when ExternalRefCountDataWithDestroyFn is used, the \tt
+ destroyer field must be set to a valid function that \b will delete the
+ object tracked.
+
+ This class also adds an operator delete function to ensure that simply
+ calls the global operator delete. That should be the behaviour in all
+ compilers already, but to be on the safe side, this class ensures that no
+ funny business happens.
+
+ On a 32-bit architecture, this class is 16 bytes in size, whereas it's 24
+ bytes on 64-bit. (On Itanium where function pointers contain the global
+ pointer, it can be 32 bytes).
+
+ \section3 QtSharedPointer::ExternalRefCountWithCustomDeleter
+
+ This class derives from ExternalRefCountDataWithDestroyFn and is a
+ template class. As template parameters, it has the type of the pointer
+ being tracked (\tt T) and a \tt Deleter, which is anything. It adds two
+ fields to its parent class, matching those template parameters: a member
+ of type \tt Deleter and a member of type \tt T*.
+
+ The purpose of this class is to store the pointer to be deleted and the
+ deleter code along with the d-pointer. This allows the last strong
+ reference to call any arbitrary function that disposes of the object. For
+ example, this allows calling QObject::deleteLater() on a given object.
+ The pointer to the object is kept here to avoid the extra cost of keeping
+ the deleter in the generic case.
+
+ This class is never instantiated directly: the constructors and
+ destructor are private. Only the create() function may be called to
+ return an object of this type. See below for construction details.
+
+ The size of this class depends on the size of \tt Deleter. If it's an
+ empty functor (i.e., no members), ABIs generally assign it the size of 1.
+ But given that it's followed by a pointer, up to 3 or 7 padding bytes may
+ be inserted: in that case, the size of this class is 16+4+4 = 24 bytes on
+ 32-bit architectures, or 24+8+8 = 40 bytes on 64-bit architectures (48
+ bytes on Itanium with global pointers stored). If \tt Deleter is a
+ function pointer, the size should be the same as the empty structure
+ case, except for Itanium where it may be 56 bytes due to another global
+ pointer. If \tt Deleter is a pointer to a member function (PMF), the size
+ will be even bigger and will depend on the ABI. For architectures using
+ the Itanium C++ ABI, a PMF is twice the size of a normal pointer, or 24
+ bytes on Itanium itself. In that case, the size of this structure will be
+ 16+8+4 = 28 bytes on 32-bit architectures, 24+16+8 = 48 bytes on 64-bit,
+ and 32+24+8 = 64 bytes on Itanium.
+
+ (Values for Itanium consider an LP64 architecture; for ILP32, pointers
+ are 32-bit in length, function pointers are 64-bit and PMF are 96-bit, so
+ the sizes are slightly less)
+
+ \section3 QtSharedPointer::ExternalRefCountWithContiguousData
+
+ This class also derives from ExternalRefCountDataWithDestroyFn and it is
+ also a template class. The template parameter is the type \tt T of the
+ class which QSharedPointer tracks. It adds only one member to its parent,
+ which is of type \tt T (the actual type, not a pointer to it).
+
+ The purpose of this class is to lay the \tt T object out next to the
+ reference counts, saving one memory allocation per shared pointer. This
+ is particularly interesting for small \tt T or for the cases when there
+ are few if any QWeakPointer tracking the object. This class exists to
+ implement the QSharedPointer::create() call.
+
+ Like ExternalRefCountWithCustomDeleter, this class is never instantiated
+ directly. This class also provides a create() member that returns the
+ pointer, and hides its constructors and destructor. (With C++0x, we'd
+ delete them).
+
+ The size of this class depends on the size of \tt T.
+
+ \section3 Instantiating ExternalRefCountWithCustomDeleter and ExternalRefCountWithContiguousData
+
+ Like explained above, these classes have private constructors. Moreover,
+ they are not defined anywhere, so trying to call \tt{new ClassType} would
+ result in a compilation or linker error. Instead, these classes must be
+ constructed via their create() methods.
+
+ Instead of instantiating the class by the normal way, the create() method
+ calls \tt{operator new} directly with the size of the class, then calls
+ the parent class's constructor only (ExternalRefCountDataWithDestroyFn).
+ This ensures that the inherited members are initialised properly, as well
+ as the virtual table pointer, which must point to
+ ExternalRefCountDataWithDestroyFn's virtual table. That way, we also
+ ensure that the virtual destructor being called is
+ ExternalRefCountDataWithDestroyFn's.
+
+ After initialising the base class, the
+ ExternalRefCountWithCustomDeleter::create() function initialises the new
+ members directly, by using the placement \tt{operator new}. In the case
+ of the ExternalRefCountWithContiguousData::create() function, the address
+ to the still-uninitialised \tt T member is saved for the callee to use.
+ The member is only initialised in QSharedPointer::create(), so that we
+ avoid having many variants of the internal functions according to the
+ arguments in use for calling the constructor.
+
+ When initialising the parent class, the create() functions pass the
+ address of the static deleter() member function. That is, when the
+ virtual destroy() is called by QSharedPointer, the deleter() functions
+ are called instead. These functiosn static_cast the ExternalRefCountData*
+ parameter to their own type and execute their deletion: for the
+ ExternalRefCountWithCustomDeleter::deleter() case, it runs the user's
+ custom deleter, then destroys the deleter; for
+ ExternalRefCountWithContiguousData::deleter, it simply calls the \tt T
+ destructor directly.
+
+ By not calling the constructor of the derived classes, we avoid
+ instantiating their virtual tables. Since these classes are
+ template-based, there would be one virtual table per \tt T and \tt
+ Deleter type. (This is what Qt 4.5 did)
+
+ Instead, only one non-inline function is required per template, which is
+ the deleter() static member. All the other functions can be inlined.
+ What's more, the address of deleter() is calculated only in code, which
+ can be resolved at link-time if the linker can determine that the
+ function lies in the current application or library module (since these
+ classes are not exported, that is the case for Windows or for builds with
+ \tt{-fvisibility=hidden}).
+
+ In contrast, a virtual table would require at least 3 relocations to be
+ resolved at module load-time, per module where these classes are used.
+ (In the Itanium C++ ABI, there would be more relocations, due to the
+ RTTI)
+
+ \section3 Modifications due to pointer-tracking
+
+ To ensure that pointers created with pointer-tracking enabled get
+ un-tracked when destroyed, even if destroyed by code compiled without the
+ feature, QSharedPointer modifies slightly the instructions of the
+ previous sections.
+
+ When ExternalRefCountWithCustomDeleter or
+ ExternalRefCountWithContiguousData are used, their create() functions
+ will set the ExternalRefCountDataWithDestroyFn::destroyer function
+ pointer to safetyCheckDeleter() instead. These static member functions
+ simply call internalSafetyCheckRemove2() before passing control to the
+ normal deleter() function.
+
+ If neither custom deleter nor QSharedPointer::create() are used, then
+ QSharedPointer uses a custom deleter of its own: the normalDeleter()
+ function, which simply calls \tt delete. By using a custom deleter, the
+ safetyCheckDeleter() procedure described above kicks in.
+
+ \endomit
+
\sa QSharedDataPointer, QWeakPointer, QScopedPointer
*/
@@ -120,7 +362,6 @@
\brief The QWeakPointer class holds a weak reference to a shared pointer
\since 4.5
\reentrant
- \ingroup misc
The QWeakPointer is an automatic weak reference to a
pointer in C++. It cannot be used to dereference the pointer
@@ -187,6 +428,29 @@
QWeakPointers created from QObject should never be passed to code that
hasn't been recompiled.
+ \omit
+ \secton1 QWeakPointer internals
+
+ QWeakPointer shares most of its internal functionality with
+ \l{QSharedPointer#qsharedpointer-internals}{QSharedPointer}, so see that
+ class's internal documentation for more information.
+
+ QWeakPointer requires an external reference counter in order to operate.
+ Therefore, it is incompatible by design with \l QSharedData-derived
+ classes.
+
+ It has a special QObject constructor, which works by calling
+ QtSharedPointer::ExternalRefCountData::getAndRef, which retrieves the
+ d-pointer from QObjectPrivate. If one isn't set yet, that function
+ creates the d-pointer and atomically sets it.
+
+ If getAndRef needs to create a d-pointer, it sets the strongref to -1,
+ indicating that the QObject is not shared: QWeakPointer is used only to
+ determine whether the QObject has been deleted. In that case, it cannot
+ be upgraded to QSharedPointer (see the previous section).
+
+ \endomit
+
\sa QSharedPointer, QScopedPointer
*/
@@ -951,7 +1215,7 @@
#include <qmutex.h>
#if !defined(QT_NO_QOBJECT)
-#include "../kernel/qobject_p.h"
+#include "private/qobject_p.h"
QT_BEGIN_NAMESPACE
diff --git a/src/corelib/tools/qsharedpointer_impl.h b/src/corelib/tools/qsharedpointer_impl.h
index e381433..bce4c64 100644
--- a/src/corelib/tools/qsharedpointer_impl.h
+++ b/src/corelib/tools/qsharedpointer_impl.h
@@ -115,6 +115,9 @@ namespace QtSharedPointer {
template <class T> struct RemovePointer<QSharedPointer<T> > { typedef T Type; };
template <class T> struct RemovePointer<QWeakPointer<T> > { typedef T Type; };
+ // This class provides the basic functionality of a pointer wrapper.
+ // Its existence is mostly legacy, since originally QSharedPointer
+ // could also be used for internally-refcounted objects.
template <class T>
class Basic
{
@@ -161,6 +164,12 @@ namespace QtSharedPointer {
Type *value;
};
+ // This class is the d-pointer of QSharedPointer and QWeakPointer.
+ //
+ // It is a reference-counted reference counter. "strongref" is the inner
+ // reference counter, and it tracks the lifetime of the pointer itself.
+ // "weakref" is the outer reference counter and it tracks the lifetime of
+ // the ExternalRefCountData object.
struct ExternalRefCountData
{
QBasicAtomicInt weakref;
@@ -168,12 +177,15 @@ namespace QtSharedPointer {
inline ExternalRefCountData()
{
- QBasicAtomicInt proto = Q_BASIC_ATOMIC_INITIALIZER(1);
- weakref = strongref = proto;
+ strongref = 1;
+ weakref = 1;
}
inline ExternalRefCountData(Qt::Initialization) { }
virtual inline ~ExternalRefCountData() { Q_ASSERT(!weakref); Q_ASSERT(strongref <= 0); }
+ // overridden by derived classes
+ // returns false to indicate caller should delete the pointer
+ // returns true in case it has already done so
virtual inline bool destroy() { return false; }
#ifndef QT_NO_QOBJECT
@@ -184,18 +196,8 @@ namespace QtSharedPointer {
};
// sizeof(ExternalRefCount) = 12 (32-bit) / 16 (64-bit)
- template <class T, typename Deleter>
- struct CustomDeleter
- {
- Deleter deleter;
- T *ptr;
-
- inline CustomDeleter(T *p, Deleter d) : deleter(d), ptr(p) {}
- };
- // sizeof(CustomDeleter) = sizeof(Deleter) + sizeof(void*)
- // for Deleter = function pointer: 8 (32-bit) / 16 (64-bit)
- // for Deleter = PMF: 12 (32-bit) / 24 (64-bit) (GCC)
-
+ // This class extends ExternalRefCountData with a pointer
+ // to a function, which is called by the destroy() function.
struct ExternalRefCountWithDestroyFn: public ExternalRefCountData
{
typedef void (*DestroyerFn)(ExternalRefCountData *);
@@ -210,13 +212,26 @@ namespace QtSharedPointer {
};
// sizeof(ExternalRefCountWithDestroyFn) = 16 (32-bit) / 24 (64-bit)
+ // This class extends ExternalRefCountWithDestroyFn and implements
+ // the static function that deletes the object. The pointer and the
+ // custom deleter are kept in the "extra" member.
template <class T, typename Deleter>
struct ExternalRefCountWithCustomDeleter: public ExternalRefCountWithDestroyFn
{
typedef ExternalRefCountWithCustomDeleter Self;
- typedef ExternalRefCountWithDestroyFn Parent;
- typedef CustomDeleter<T, Deleter> Next;
- Next extra;
+ typedef ExternalRefCountWithDestroyFn BaseClass;
+
+ struct CustomDeleter
+ {
+ Deleter deleter;
+ T *ptr;
+
+ inline CustomDeleter(T *p, Deleter d) : deleter(d), ptr(p) {}
+ };
+ CustomDeleter extra;
+ // sizeof(CustomDeleter) = sizeof(Deleter) + sizeof(void*)
+ // for Deleter = function pointer: 8 (32-bit) / 16 (64-bit)
+ // for Deleter = PMF: 12 (32-bit) / 24 (64-bit) (GCC)
static inline void deleter(ExternalRefCountData *self)
{
@@ -224,7 +239,7 @@ namespace QtSharedPointer {
executeDeleter(realself->extra.ptr, realself->extra.deleter);
// delete the deleter too
- realself->extra.~Next();
+ realself->extra.~CustomDeleter();
}
static void safetyCheckDeleter(ExternalRefCountData *self)
{
@@ -242,8 +257,8 @@ namespace QtSharedPointer {
Self *d = static_cast<Self *>(::operator new(sizeof(Self)));
// initialize the two sub-objects
- new (&d->extra) Next(ptr, userDeleter);
- new (d) Parent(destroy); // can't throw
+ new (&d->extra) CustomDeleter(ptr, userDeleter);
+ new (d) BaseClass(destroy); // can't throw
return d;
}
@@ -253,6 +268,10 @@ namespace QtSharedPointer {
~ExternalRefCountWithCustomDeleter();
};
+ // This class extends ExternalRefCountWithDestroyFn and adds a "T"
+ // member. That way, when the create() function is called, we allocate
+ // memory for both QSharedPointer's d-pointer and the actual object being
+ // tracked.
template <class T>
struct ExternalRefCountWithContiguousData: public ExternalRefCountWithDestroyFn
{
@@ -295,6 +314,8 @@ namespace QtSharedPointer {
~ExternalRefCountWithContiguousData();
};
+ // This is the main body of QSharedPointer. It implements the
+ // external reference counting functionality.
template <class T>
class ExternalRefCount: public Basic<T>
{
@@ -370,6 +391,12 @@ namespace QtSharedPointer {
delete this->value;
}
+ inline void internalSwap(ExternalRefCount &other)
+ {
+ qSwap(d, other.d);
+ qSwap(this->value, other.value);
+ }
+
#if defined(Q_NO_TEMPLATE_FRIENDS)
public:
#else
@@ -450,6 +477,9 @@ public:
inline QSharedPointer<T> &operator=(const QWeakPointer<X> &other)
{ BaseClass::internalSet(other.d, other.value); return *this; }
+ inline void swap(QSharedPointer &other)
+ { internalSwap(other); }
+
template <class X>
QSharedPointer<X> staticCast() const
{
@@ -673,6 +703,12 @@ Q_INLINE_TEMPLATE QWeakPointer<T> QSharedPointer<T>::toWeakRef() const
return QWeakPointer<T>(*this);
}
+template <class T>
+inline void qSwap(QSharedPointer<T> &p1, QSharedPointer<T> &p2)
+{
+ p1.swap(p2);
+}
+
namespace QtSharedPointer {
// helper functions:
template <class X, class T>
diff --git a/src/corelib/tools/qsize.cpp b/src/corelib/tools/qsize.cpp
index 6168fe9..a165917 100644
--- a/src/corelib/tools/qsize.cpp
+++ b/src/corelib/tools/qsize.cpp
@@ -47,7 +47,7 @@ QT_BEGIN_NAMESPACE
/*!
\class QSize
- \ingroup multimedia
+ \ingroup painting
\brief The QSize class defines the size of a two-dimensional
object using integer point precision.
@@ -432,7 +432,7 @@ QDebug operator<<(QDebug dbg, const QSize &s) {
\brief The QSizeF class defines the size of a two-dimensional object
using floating point precision.
- \ingroup multimedia
+ \ingroup painting
A size is specified by a width() and a height(). It can be set in
the constructor and changed using the setWidth(), setHeight(), or
diff --git a/src/corelib/tools/qstack.cpp b/src/corelib/tools/qstack.cpp
index f89149a..f97e546 100644
--- a/src/corelib/tools/qstack.cpp
+++ b/src/corelib/tools/qstack.cpp
@@ -45,7 +45,7 @@
\ingroup tools
\ingroup shared
- \mainclass
+
\reentrant
QStack\<T\> is one of Qt's generic \l{container classes}. It implements
diff --git a/src/corelib/tools/qstring.cpp b/src/corelib/tools/qstring.cpp
index c36bf6e..34178c1 100644
--- a/src/corelib/tools/qstring.cpp
+++ b/src/corelib/tools/qstring.cpp
@@ -359,7 +359,7 @@ const QString::Null QString::null = { };
\internal
- \ingroup text
+ \ingroup string-processing
When you get an object of type QCharRef, if you can assign to it,
the assignment will apply to the character in the string from
@@ -381,8 +381,8 @@ const QString::Null QString::null = { };
\ingroup tools
\ingroup shared
- \ingroup text
- \mainclass
+ \ingroup string-processing
+
QString stores a string of 16-bit \l{QChar}s, where each QChar
corresponds one Unicode 4.0 character. (Unicode characters
@@ -6942,7 +6942,7 @@ QString QString::fromRawData(const QChar *unicode, int size)
/*! \class QLatin1String
\brief The QLatin1String class provides a thin wrapper around an ASCII/Latin-1 encoded string literal.
- \ingroup text
+ \ingroup string-processing
\reentrant
Many of QString's member functions are overloaded to accept
@@ -7564,7 +7564,7 @@ QDataStream &operator>>(QDataStream &in, QString &str)
\brief The QStringRef class provides a thin wrapper around QString substrings.
\reentrant
\ingroup tools
- \ingroup text
+ \ingroup string-processing
QStringRef provides a read-only subset of the QString API.
diff --git a/src/corelib/tools/qstringbuilder.cpp b/src/corelib/tools/qstringbuilder.cpp
index 344e95b..04fbb93 100644
--- a/src/corelib/tools/qstringbuilder.cpp
+++ b/src/corelib/tools/qstringbuilder.cpp
@@ -52,8 +52,8 @@
\ingroup tools
\ingroup shared
- \ingroup text
- \mainclass
+ \ingroup string-processing
+
Unlike \c QLatin1String, a \c QLatin1Literal can retrieve its size
without iterating over the literal.
@@ -92,8 +92,8 @@
\ingroup tools
\ingroup shared
- \ingroup text
- \mainclass
+ \ingroup string-processing
+
To build a QString by multiple concatenations, QString::operator+()
is typically used. This causes \e{n - 1} reallocations when building
diff --git a/src/corelib/tools/qstringlist.cpp b/src/corelib/tools/qstringlist.cpp
index 952609e..231f74e 100644
--- a/src/corelib/tools/qstringlist.cpp
+++ b/src/corelib/tools/qstringlist.cpp
@@ -77,8 +77,8 @@ QT_BEGIN_NAMESPACE
\ingroup tools
\ingroup shared
- \ingroup text
- \mainclass
+ \ingroup string-processing
+
\reentrant
QStringList inherits from QList<QString>. Like QList, QStringList is
diff --git a/src/corelib/tools/qstringmatcher.cpp b/src/corelib/tools/qstringmatcher.cpp
index 75e1d45..8eb8238 100644
--- a/src/corelib/tools/qstringmatcher.cpp
+++ b/src/corelib/tools/qstringmatcher.cpp
@@ -129,7 +129,7 @@ static inline int bm_find(const ushort *uc, uint l, int index, const ushort *puc
can be quickly matched in a Unicode string.
\ingroup tools
- \ingroup text
+ \ingroup string-processing
This class is useful when you have a sequence of \l{QChar}s that
you want to repeatedly match against some strings (perhaps in a
diff --git a/src/corelib/tools/qtextboundaryfinder.cpp b/src/corelib/tools/qtextboundaryfinder.cpp
index bf1d654..8768a16 100644
--- a/src/corelib/tools/qtextboundaryfinder.cpp
+++ b/src/corelib/tools/qtextboundaryfinder.cpp
@@ -107,7 +107,7 @@ static void init(QTextBoundaryFinder::BoundaryType type, const QChar *chars, int
\since 4.4
\ingroup tools
\ingroup shared
- \ingroup text
+ \ingroup string-processing
\reentrant
QTextBoundaryFinder allows to find Unicode text boundaries in a
diff --git a/src/corelib/tools/qtimeline.cpp b/src/corelib/tools/qtimeline.cpp
index 11d4c43..c0ca931 100644
--- a/src/corelib/tools/qtimeline.cpp
+++ b/src/corelib/tools/qtimeline.cpp
@@ -165,7 +165,7 @@ void QTimeLinePrivate::setCurrentTime(int msecs)
\class QTimeLine
\brief The QTimeLine class provides a timeline for controlling animations.
\since 4.2
- \ingroup multimedia
+ \ingroup animation
It's most commonly used to animate a GUI control by calling a slot
periodically. You can construct a timeline by passing its duration in
diff --git a/src/corelib/tools/qvarlengtharray.qdoc b/src/corelib/tools/qvarlengtharray.qdoc
new file mode 100644
index 0000000..9cc7bef
--- /dev/null
+++ b/src/corelib/tools/qvarlengtharray.qdoc
@@ -0,0 +1,274 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (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 http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \class QVarLengthArray
+ \brief The QVarLengthArray class provides a low-level variable-length array.
+
+ \ingroup tools
+ \reentrant
+
+ The C++ language doesn't support variable-length arrays on the stack.
+ For example, the following code won't compile:
+
+ \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 0
+
+ The alternative is to allocate the array on the heap (with
+ \c{new}):
+
+ \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 1
+
+ However, if myfunc() is called very frequently from the
+ application's inner loop, heap allocation can be a major source
+ of slowdown.
+
+ QVarLengthArray is an attempt to work around this gap in the C++
+ language. It allocates a certain number of elements on the stack,
+ and if you resize the array to a larger size, it automatically
+ uses the heap instead. Stack allocation has the advantage that
+ it is much faster than heap allocation.
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 2
+
+ In the example above, QVarLengthArray will preallocate 1024
+ elements on the stack and use them unless \c{n + 1} is greater
+ than 1024. If you omit the second template argument,
+ QVarLengthArray's default of 256 is used.
+
+ QVarLengthArray'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 *.
+
+ QVarLengthArray, like QVector, provides a resizable array data
+ structure. The main differences between the two classes are:
+
+ \list
+ \o QVarLengthArray's API is much more low-level. It provides no
+ iterators and lacks much of QVector's functionality.
+
+ \o QVarLengthArray doesn't initialize the memory if the value is
+ a basic type. (QVector always does.)
+
+ \o QVector uses \l{implicit sharing} as a memory optimization.
+ QVarLengthArray doesn't provide that feature; however, it
+ usually produces slightly better performance due to reduced
+ overhead, especially in tight loops.
+ \endlist
+
+ In summary, QVarLengthArray is a low-level optimization class
+ that only makes sense in very specific cases. It is used a few
+ places inside Qt and was added to Qt's public API for the
+ convenience of advanced users.
+
+ \sa QVector, QList, QLinkedList
+*/
+
+/*! \fn QVarLengthArray::QVarLengthArray(int size)
+
+ Constructs an array with an initial size of \a size elements.
+
+ If the value type is a primitive type (e.g., char, int, float) or
+ a pointer type (e.g., QWidget *), the elements are not
+ initialized. For other types, the elements are initialized with a
+ \l{default-constructed value}.
+*/
+
+/*! \fn QVarLengthArray::~QVarLengthArray()
+
+ Destroys the array.
+*/
+
+/*! \fn int QVarLengthArray::size() const
+
+ Returns the number of elements in the array.
+
+ \sa isEmpty(), resize()
+*/
+
+/*! \fn int QVarLengthArray::count() const
+
+ Same as size().
+
+ \sa isEmpty(), resize()
+*/
+
+/*! \fn bool QVarLengthArray::isEmpty() const
+
+ Returns true if the array has size 0; otherwise returns false.
+
+ \sa size(), resize()
+*/
+
+/*! \fn void QVarLengthArray::clear()
+
+ Removes all the elements from the array.
+
+ Same as resize(0).
+*/
+
+/*! \fn void QVarLengthArray::resize(int size)
+
+ Sets the size of the array to \a size. If \a size is greater than
+ the current size, elements are added to the end. If \a size is
+ less than the current size, elements are removed from the end.
+
+ If the value type is a primitive type (e.g., char, int, float) or
+ a pointer type (e.g., QWidget *), new elements are not
+ initialized. For other types, the elements are initialized with a
+ \l{default-constructed value}.
+
+ \sa size()
+*/
+
+/*! \fn int QVarLengthArray::capacity() const
+
+ Returns the maximum number of elements that can be stored in the
+ array without forcing a reallocation.
+
+ The sole purpose of this function is to provide a means of fine
+ tuning QVarLengthArray'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 array, call size().
+
+ \sa reserve()
+*/
+
+/*! \fn void QVarLengthArray::reserve(int size)
+
+ Attempts to allocate memory for at least \a size elements. If you
+ know in advance how large the array can get, you can call this
+ function and if you call resize() often, you are likely to get
+ better performance. If \a size is an underestimate, the worst
+ that will happen is that the QVarLengthArray will be a bit
+ slower.
+
+ The sole purpose of this function is to provide a means of fine
+ tuning QVarLengthArray's memory usage. In general, you will
+ rarely ever need to call this function. If you want to change the
+ size of the array, call resize().
+
+ \sa capacity()
+*/
+
+/*! \fn T &QVarLengthArray::operator[](int i)
+
+ Returns a reference to the item at index position \a i.
+
+ \a i must be a valid index position in the array (i.e., 0 <= \a i
+ < size()).
+
+ \sa data()
+*/
+
+/*! \fn const T &QVarLengthArray::operator[](int i) const
+
+ \overload
+*/
+
+
+/*!
+ \fn void QVarLengthArray::append(const T &t)
+
+ Appends item \a t to the array, extending the array if necessary.
+
+ \sa removeLast()
+*/
+
+
+/*!
+ \fn inline void QVarLengthArray::removeLast()
+ \since 4.5
+
+ Decreases the size of the array by one. The allocated size is not changed.
+
+ \sa append()
+*/
+
+/*!
+ \fn void QVarLengthArray::append(const T *buf, int size)
+
+ Appends \a size amount of items referenced by \a buf to this array.
+*/
+
+
+/*! \fn T *QVarLengthArray::data()
+
+ Returns a pointer to the data stored in the array. The pointer can
+ be used to access and modify the items in the array.
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 3
+
+ The pointer remains valid as long as the array isn't reallocated.
+
+ This function is mostly useful to pass an array to a function
+ that accepts a plain C++ array.
+
+ \sa constData(), operator[]()
+*/
+
+/*! \fn const T *QVarLengthArray::data() const
+
+ \overload
+*/
+
+/*! \fn const T *QVarLengthArray::constData() const
+
+ Returns a const pointer to the data stored in the array. The
+ pointer can be used to access the items in the array. The
+ pointer remains valid as long as the array isn't reallocated.
+
+ This function is mostly useful to pass an array to a function
+ that accepts a plain C++ array.
+
+ \sa data(), operator[]()
+*/
+
+/*! \fn QVarLengthArray<T, Prealloc> &QVarLengthArray::operator=(const QVarLengthArray<T, Prealloc> &other)
+ Assigns \a other to this array and returns a reference to this array.
+ */
+
+/*! \fn QVarLengthArray::QVarLengthArray(const QVarLengthArray<T, Prealloc> &other)
+ Constructs a copy of \a other.
+ */
+
diff --git a/src/corelib/tools/qvector.cpp b/src/corelib/tools/qvector.cpp
index 67c4f74..e5c2c6a 100644
--- a/src/corelib/tools/qvector.cpp
+++ b/src/corelib/tools/qvector.cpp
@@ -68,7 +68,7 @@ int QVectorData::grow(int sizeofTypedData, int size, int sizeofT, bool excessive
\ingroup tools
\ingroup shared
- \mainclass
+
\reentrant
QVector\<T\> is one of Qt's generic \l{container classes}. It
diff --git a/src/corelib/tools/tools.pri b/src/corelib/tools/tools.pri
index e6c6169..464c60f 100644
--- a/src/corelib/tools/tools.pri
+++ b/src/corelib/tools/tools.pri
@@ -56,7 +56,7 @@ SOURCES += \
tools/qhash.cpp \
tools/qline.cpp \
tools/qlinkedlist.cpp \
- tools/qlistdata.cpp \
+ tools/qlist.cpp \
tools/qlocale.cpp \
tools/qpoint.cpp \
tools/qmap.cpp \
@@ -93,7 +93,7 @@ contains(QT_CONFIG, zlib) {
../3rdparty/zlib/uncompr.c \
../3rdparty/zlib/zutil.c
} else:!contains(QT_CONFIG, no-zlib) {
- unix:LIBS += -lz
+ unix:LIBS_PRIVATE += -lz
# win32:LIBS += libz.lib
}
@@ -114,4 +114,6 @@ HEADERS += tools/qharfbuzz_p.h
INCLUDEPATH += ../3rdparty/md5 \
../3rdparty/md4
-!macx-icc:unix:!symbian:!vxworks:LIBS += -lm
+# Note: libm should be present by default becaue this is C++
+!macx-icc:!vxworks:!symbian:unix:LIBS_PRIVATE += -lm
+