source: trunk/doc/src/qalgorithms.qdoc@ 551

Last change on this file since 551 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.
File size: 22.1 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information ([email protected])
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
23** In addition, as a special exception, Nokia gives you certain
24** additional rights. These rights are described in the Nokia Qt LGPL
25** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26** package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you are unsure which license is appropriate for your use, please
37** contact the sales department at [email protected].
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42/*!
43 \headerfile <QtAlgorithms>
44 \title Generic Algorithms
45 \ingroup architecture
46
47 \brief The <QtAlgorithms> header provides generic template-based algorithms.
48
49 Qt provides a number of global template functions in \c
50 <QtAlgorithms> that work on containers and perform well-know
51 algorithms. You can use these algorithms with any \l {container
52 class} that provides STL-style iterators, including Qt's QList,
53 QLinkedList, QVector, QMap, and QHash classes.
54
55 These functions have taken their inspiration from similar
56 functions available in the STL \c <algorithm> header. Most of them
57 have a direct STL equivalent; for example, qCopyBackward() is the
58 same as STL's copy_backward() algorithm.
59
60 If STL is available on all your target platforms, you can use the
61 STL algorithms instead of their Qt counterparts. One reason why
62 you might want to use the the STL algorithms is that STL provides
63 dozens and dozens of algorithms, whereas Qt only provides the most
64 important ones, making no attempt to duplicate functionality that
65 is already provided by the C++ standard.
66
67 Most algorithms take \l {STL-style iterators} as parameters. The
68 algorithms are generic in the sense that they aren't bound to a
69 specific iterator class; you can use them with any iterators that
70 meet a certain set of requirements.
71
72 Let's take the qFill() algorithm as an example. Unlike QVector,
73 QList has no fill() function that can be used to fill a list with
74 a particular value. If you need that functionality, you can use
75 qFill():
76
77 \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 0
78
79 qFill() takes a begin iterator, an end iterator, and a value.
80 In the example above, we pass \c list.begin() and \c list.end()
81 as the begin and end iterators, but this doesn't have to be
82 the case:
83
84 \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 1
85
86 Different algorithms can have different requirements for the
87 iterators they accept. For example, qFill() accepts two
88 \l {forward iterators}. The iterator types required are specified
89 for each algorithm. If an iterator of the wrong type is passed (for
90 example, if QList::ConstIterator is passed as an \l {output
91 iterator}), you will always get a compiler error, although not
92 necessarily a very informative one.
93
94 Some algorithms have special requirements on the value type
95 stored in the containers. For example, qEqual() requires that the