source: branches/4.5.1/doc/src/qpair.qdoc@ 664

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

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.
File size: 7.0 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information (qt-info@nokia.com)
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 qt-sales@nokia.com.
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42/*!
43 \class QPair
44 \brief The QPair class is a template class that stores a pair of items.
45
46 \ingroup tools
47
48 QPair\<T1, T2\> can be used in your application if the STL \c
49 pair type is not available. It stores one value of type T1 and
50 one value of type T2. It can be used as a return value for a
51 function that needs to return two values, or as the value type of
52 a \l{generic container}.
53
54 Here's an example of a QPair that stores one QString and one \c
55 double value:
56
57 \snippet doc/src/snippets/code/doc_src_qpair.qdoc 0
58
59 The components are accessible as public data members called \l
60 first and \l second. For example:
61
62 \snippet doc/src/snippets/code/doc_src_qpair.qdoc 1
63
64 QPair's template data types (T1 and T2) must be \l{assignable
65 data types}. You cannot, for example, store a QWidget as a value;
66 instead, store a QWidget *. A few functions have additional
67 requirements; these requirements are documented on a per-function
68 basis.
69
70 \sa {Generic Containers}
71*/
72
73/*! \typedef QPair::first_type
74
75 The type of the first element in the pair (T1).
76
77 \sa first
78*/
79
80/*! \typedef QPair::second_type
81
82 The type of the second element in the pair (T2).
83
84 \sa second
85*/
86
87/*! \variable QPair::first
88
89 The first element in the pair.
90*/
91
92/*! \variable QPair::second
93
94 The second element in the pair.
95*/
96
97/*! \fn QPair::QPair()
98
99 Constructs an empty pair. The \c first and \c second elements are
100 initialized with \l{default-constructed values}.
101*/
102
103/*!
104 \fn QPair::QPair(const T1 &value1, const T2 &value2)
105
106 Constructs a pair and initializes the \c first element with \a
107 value1 and the \c second element with \a value2.
108
109 \sa qMakePair()
110*/
111
112/*!
113 \fn QPair<T1, T2> &QPair::operator=(const QPair<T1, T2> &other)
114
115 Assigns \a other to this pair.
116*/
117
118/*! \fn bool operator==(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2)
119
120 \relates QPair
121
122 Returns true if \a p1 is equal to \a p2; otherwise returns false.
123 Two pairs compare equal if their \c first data members compare
124 equal and if their \c second data members compare equal.
125
126 This function requires the T1 and T2 types to have an
127 implementation of \c operator==().
128*/
129
130/*! \fn bool operator!=(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2)
131
132 \relates QPair
133
134 Returns true if \a p1 is not equal to \a p2; otherwise returns
135 false. Two pairs compare as not equal if their \c first data
136 members are not equal or if their \c second data members are not
137 equal.
138
139 This function requires the T1 and T2 types to have an
140 implementation of \c operator==().
141*/
142
143/*! \fn bool operator<(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2)
144
145 \relates QPair
146
147 Returns true if \a p1 is less than \a p2; otherwise returns
148 false. The comparison is done on the \c first members of \a p1
149 and \a p2; if they compare equal, the \c second members are
150 compared to break the tie.
151
152 This function requires the T1 and T2 types to have an
153 implementation of \c operator<().
154*/
155
156/*! \fn bool operator>(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2)
157
158 \relates QPair
159
160 Returns true if \a p1 is greater than \a p2; otherwise returns
161 false. The comparison is done on the \c first members of \a p1
162 and \a p2; if they compare equal, the \c second members are
163 compared to break the tie.
164
165 This function requires the T1 and T2 types to have an
166 implementation of \c operator<().
167*/
168
169/*! \fn bool operator<=(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2)
170
171 \relates QPair
172
173 Returns true if \a p1 is less than or equal to \a p2; otherwise
174 returns false. The comparison is done on the \c first members of
175 \a p1 and \a p2; if they compare equal, the \c second members are
176 compared to break the tie.
177
178 This function requires the T1 and T2 types to have an
179 implementation of \c operator<().
180*/
181
182/*! \fn bool operator>=(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2)
183
184 \relates QPair
185
186 Returns true if \a p1 is greater than or equal to \a p2;
187 otherwise returns false. The comparison is done on the \c first
188 members of \a p1 and \a p2; if they compare equal, the \c second
189 members are compared to break the tie.
190
191 This function requires the T1 and T2 types to have an
192 implementation of \c operator<().
193*/
194
195/*!
196 \fn QPair<T1, T2> qMakePair(const T1 &value1, const T2 &value2)
197
198 \relates QPair
199
200 Returns a QPair\<T1, T2\> that contains \a value1 and \a value2.
201 Example:
202
203 \snippet doc/src/snippets/code/doc_src_qpair.qdoc 2
204
205 This is equivalent to QPair<T1, T2>(\a value1, \a value2), but
206 usually requires less typing.
207*/
208
209/*! \fn QDataStream &operator>>(QDataStream &in, QPair<T1, T2> &pair)
210
211 \relates QPair
212
213 Reads a pair from stream \a in into \a pair.
214
215 This function requires the T1 and T2 types to implement \c operator>>().
216
217 \sa {Format of the QDataStream operators}
218*/
219
220/*! \fn QDataStream &operator<<(QDataStream &out, const QPair<T1, T2> &pair)
221
222 \relates QPair
223
224 Writes the pair \a pair to stream \a out.
225
226 This function requires the T1 and T2 types to implement \c operator<<().
227
228 \sa {Format of the QDataStream operators}
229*/
Note: See TracBrowser for help on using the repository browser.