Warning: That file was not part of the compilation database. It may have many parsing errors.

1 | /**************************************************************************** |
---|---|

2 | ** |

3 | ** Copyright (C) 2016 The Qt Company Ltd. |

4 | ** Contact: https://www.qt.io/licensing/ |

5 | ** |

6 | ** This file is part of the documentation of the Qt Toolkit. |

7 | ** |

8 | ** $QT_BEGIN_LICENSE:FDL$ |

9 | ** Commercial License Usage |

10 | ** Licensees holding valid commercial Qt licenses may use this file in |

11 | ** accordance with the commercial license agreement provided with the |

12 | ** Software or, alternatively, in accordance with the terms contained in |

13 | ** a written agreement between you and The Qt Company. For licensing terms |

14 | ** and conditions see https://www.qt.io/terms-conditions. For further |

15 | ** information use the contact form at https://www.qt.io/contact-us. |

16 | ** |

17 | ** GNU Free Documentation License Usage |

18 | ** Alternatively, this file may be used under the terms of the GNU Free |

19 | ** Documentation License version 1.3 as published by the Free Software |

20 | ** Foundation and appearing in the file included in the packaging of |

21 | ** this file. Please review the following information to ensure |

22 | ** the GNU Free Documentation License version 1.3 requirements |

23 | ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |

24 | ** $QT_END_LICENSE$ |

25 | ** |

26 | ****************************************************************************/ |

27 | |

28 | /*! |

29 | \class QPair |

30 | \inmodule QtCore |

31 | \brief The QPair class is a template class that stores a pair of items. |

32 | |

33 | \ingroup tools |

34 | |

35 | QPair\<T1, T2\> can be used in your application if the STL \c |

36 | pair type is not available. It stores one value of type T1 and |

37 | one value of type T2. It can be used as a return value for a |

38 | function that needs to return two values, or as the value type of |

39 | a \l{Container classes}{generic container}. |

40 | |

41 | Here's an example of a QPair that stores one QString and one \c |

42 | double value: |

43 | |

44 | \snippet code/doc_src_qpair.cpp 0 |

45 | |

46 | The components are accessible as public data members called \l |

47 | first and \l second. For example: |

48 | |

49 | \snippet code/doc_src_qpair.cpp 1 |

50 | |

51 | Note, however, that it is almost always preferable to define a small struct |

52 | to hold the result of a function with multiple return values. A struct |

53 | trivially generalizes to more than two values, and allows more descriptive |

54 | member names than \c{first} and \c{second}: |

55 | |

56 | \snippet code/doc_src_qpair.cpp struct |

57 | |

58 | The advent of C++11 automatic variable type deduction (\c{auto}) shifts the |

59 | emphasis from the type name to the name of functions and members. Thus, QPair, |

60 | like \c{std::pair} and \c{std::tuple}, is mostly useful in generic (template) |

61 | code, where defining a dedicated type is not possible. |

62 | |

63 | QPair's template data types (T1 and T2) must be \l{assignable |

64 | data types}. You cannot, for example, store a QWidget as a value; |

65 | instead, store a QWidget *. A few functions have additional |

66 | requirements; these requirements are documented on a per-function |

67 | basis. |

68 | |

69 | \sa {Container Classes} |

70 | */ |

71 | |

72 | /*! \typedef QPair::first_type |

73 | |

74 | The type of the first element in the pair (T1). |

75 | |

76 | \sa first |

77 | */ |

78 | |

79 | /*! \typedef QPair::second_type |

80 | |

81 | The type of the second element in the pair (T2). |

82 | |

83 | \sa second |

84 | */ |

85 | |

86 | /*! \variable QPair::first |

87 | |

88 | The first element in the pair. |

89 | */ |

90 | |

91 | /*! \variable QPair::second |

92 | |

93 | The second element in the pair. |

94 | */ |

95 | |

96 | /*! \fn template <class T1, class T2> QPair<T1, T2>::QPair() |

97 | |

98 | Constructs an empty pair. The \c first and \c second elements are |

99 | initialized with \l{default-constructed value}s. |

100 | */ |

101 | |

102 | /*! |

103 | \fn template <class T1, class T2> QPair<T1, T2>::QPair(const T1 &value1, const T2 &value2) |

104 | |

105 | Constructs a pair and initializes the \c first element with \a |

106 | value1 and the \c second element with \a value2. |

107 | |

108 | \sa qMakePair() |

109 | */ |

110 | |

111 | /*! |

112 | \fn template <class T1, class T2> void QPair<T1, T2>::swap(QPair &other) |

113 | |

114 | \since 5.5 |

115 | Swaps this pair with \a other. |

116 | |

117 | Equivalent to |

118 | \code |

119 | qSwap(this->first, other.first); |

120 | qSwap(this->second, other.second); |

121 | \endcode |

122 | |

123 | Swap overloads are found in namespace \c std as well as via |

124 | argument-dependent lookup (ADL) in the namespace of \c{T} . |

125 | */ |

126 | |

127 | /*! |

128 | \fn template <class T1, class T2> void swap(QPair<T1, T2> &lhs, QPair<T1, T2> &rhs) |

129 | \overload |

130 | \relates QPair |

131 | \since 5.5 |

132 | |

133 | Swaps \a lhs with \a rhs. |

134 | */ |

135 | |

136 | /*! |

137 | \fn template <class T1, class T2> template <typename TT1, typename TT2> QPair<T1, T2>::QPair(const QPair<TT1, TT2> &p) |

138 | \since 5.2 |

139 | |

140 | Constructs a pair from the other pair \a p, of types TT1 and TT2. This |

141 | constructor will fail if \c first cannot be initialized from \c p.first or |

142 | if \c second cannot be initialized from \c p.second. |

143 | |

144 | \sa qMakePair() |

145 | */ |

146 | |

147 | /*! |

148 | \fn template <class T1, class T2> template <typename TT1, typename TT2> QPair<T1, T2>::QPair(QPair<TT1, TT2> &&p) |

149 | \since 5.2 |

150 | |

151 | Move-constructs a QPair instance, making it point to the same object that \a p was pointing to. |

152 | */ |

153 | |

154 | /*! |

155 | \fn template <class T1, class T2> template <typename TT1, typename TT2> QPair & QPair<T1, T2>::operator=(const QPair<TT1, TT2> &p) |

156 | \since 5.2 |

157 | |

158 | Copies pair \a p into this pair. |

159 | |

160 | \sa qMakePair() |

161 | */ |

162 | |

163 | /*! |

164 | \fn template <class T1, class T2> template <typename TT1, typename TT2> QPair & QPair<T1, T2>::operator=(QPair<TT1, TT2> &&p) |

165 | \since 5.2 |

166 | |

167 | Move-assigns pair \a p into this pair instance. |

168 | */ |

169 | |

170 | /*! \fn template <class T1, class T2> bool operator==(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2) |

171 | |

172 | \relates QPair |

173 | |

174 | Returns \c true if \a p1 is equal to \a p2; otherwise returns \c false. |

175 | Two pairs compare equal if their \c first data members compare |

176 | equal and if their \c second data members compare equal. |

177 | |

178 | This function requires the T1 and T2 types to have an |

179 | implementation of \c operator==(). |

180 | */ |

181 | |

182 | /*! \fn template <class T1, class T2> bool operator!=(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2) |

183 | |

184 | \relates QPair |

185 | |

186 | Returns \c true if \a p1 is not equal to \a p2; otherwise returns |

187 | false. Two pairs compare as not equal if their \c first data |

188 | members are not equal or if their \c second data members are not |

189 | equal. |

190 | |

191 | This function requires the T1 and T2 types to have an |

192 | implementation of \c operator==(). |

193 | */ |

194 | |

195 | /*! \fn template <class T1, class T2> bool operator<(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2) |

196 | |

197 | \relates QPair |

198 | |

199 | Returns \c true if \a p1 is less than \a p2; otherwise returns |

200 | false. The comparison is done on the \c first members of \a p1 |

201 | and \a p2; if they compare equal, the \c second members are |

202 | compared to break the tie. |

203 | |

204 | This function requires the T1 and T2 types to have an |

205 | implementation of \c operator<(). |

206 | */ |

207 | |

208 | /*! \fn template <class T1, class T2> bool operator>(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2) |

209 | |

210 | \relates QPair |

211 | |

212 | Returns \c true if \a p1 is greater than \a p2; otherwise returns |

213 | false. The comparison is done on the \c first members of \a p1 |

214 | and \a p2; if they compare equal, the \c second members are |

215 | compared to break the tie. |

216 | |

217 | This function requires the T1 and T2 types to have an |

218 | implementation of \c operator<(). |

219 | */ |

220 | |

221 | /*! \fn template <class T1, class T2> bool operator<=(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2) |

222 | |

223 | \relates QPair |

224 | |

225 | Returns \c true if \a p1 is less than or equal to \a p2; otherwise |

226 | returns \c false. The comparison is done on the \c first members of |

227 | \a p1 and \a p2; if they compare equal, the \c second members are |

228 | compared to break the tie. |

229 | |

230 | This function requires the T1 and T2 types to have an |

231 | implementation of \c operator<(). |

232 | */ |

233 | |

234 | /*! \fn template <class T1, class T2> bool operator>=(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2) |

235 | |

236 | \relates QPair |

237 | |

238 | Returns \c true if \a p1 is greater than or equal to \a p2; |

239 | otherwise returns \c false. The comparison is done on the \c first |

240 | members of \a p1 and \a p2; if they compare equal, the \c second |

241 | members are compared to break the tie. |

242 | |

243 | This function requires the T1 and T2 types to have an |

244 | implementation of \c operator<(). |

245 | */ |

246 | |

247 | /*! |

248 | \fn template <class T1, class T2> QPair<T1, T2> qMakePair(const T1 &value1, const T2 &value2) |

249 | |

250 | \relates QPair |

251 | |

252 | Returns a QPair\<T1, T2\> that contains \a value1 and \a value2. |

253 | Example: |

254 | |

255 | \snippet code/doc_src_qpair.cpp 2 |

256 | |

257 | This is equivalent to QPair<T1, T2>(\a value1, \a value2), but |

258 | usually requires less typing. |

259 | */ |

260 | |

261 | /*! \fn template <class T1, class T2> QDataStream &operator>>(QDataStream &in, QPair<T1, T2> &pair) |

262 | |

263 | \relates QPair |

264 | |

265 | Reads a pair from stream \a in into \a pair. |

266 | |

267 | This function requires the T1 and T2 types to implement \c operator>>(). |

268 | |

269 | \sa {Serializing Qt Data Types} |

270 | */ |

271 | |

272 | /*! \fn template <class T1, class T2> QDataStream &operator<<(QDataStream &out, const QPair<T1, T2> &pair) |

273 | |

274 | \relates QPair |

275 | |

276 | Writes the pair \a pair to stream \a out. |

277 | |

278 | This function requires the T1 and T2 types to implement \c operator<<(). |

279 | |

280 | \sa {Serializing Qt Data Types} |

281 | */ |

282 |

Warning: That file was not part of the compilation database. It may have many parsing errors.