KDb

KDbTristate.h
1/* This file is part of the KDE project
2 Copyright (C) 2004-2012 Jarosław Staniek <staniek@kde.org>
3
4 This program is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License as published by the Free Software Foundation; either
7 version 2 of the License, or (at your option) any later version.
8
9 This program is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this program; see the file COPYING. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 * Boston, MA 02110-1301, USA.
18*/
19
20#ifndef KDB_TRISTATE_H
21#define KDB_TRISTATE_H
22
23#include <QString>
24#include <QtDebug>
25
26enum tristate_cancelled_t {
27 /**
28 * @e cancelled value, in most cases usable if there is a need for returning
29 * @e cancelled value explicitly. Example use:
30 * @code
31 * tristate myFunctionThatCanBeCancelled() {
32 * doSomething();
33 * if (userCancelledOperation())
34 * return cancelled; //neither success or failure is returned here
35 * return operationSucceeded(); //return success or failure
36 * }
37 * @endcode
38 * Even though ~ operator of tristate class can be used, it is also possible to test:
39 * @code
40 * if (cancelled == myFunctionThatCanBeCancelled()) { .... }
41 * @endcode
42 */
43 cancelled,
44
45 /**
46 * Convenience name, the same as cancelled value.
47 */
48 dontKnow = cancelled
49};
50
51/**
52 * 3-state logical type with three values: @e true, @e false and @e cancelled and convenient operators.
53 *
54 * @e cancelled state can be also called @e dontKnow, it behaves as @e null in SQL.
55 * A main goal of this class is to improve readibility when there's a need
56 * for storing third, @e cancelled, state, especially in case C++ exceptions are not in use.
57 * With it, developer can forget about declaring a specific enum type
58 * having just three values: @e true, @e false, @e cancelled.
59 *
60 * Objects of this class can be used with similar convenience as standard bool type:
61 * - use as return value when 'cancelled'
62 * @code
63 * tristate doSomething();
64 * @endcode
65 * - convert from bool (1) or to bool (2)
66 * @code
67 * tristate t = true; //(1)
68 * setVisible(t); //(2)
69 * @endcode
70 * - clear comparisons
71 * @code
72 * tristate t = doSomething();
73 * if (t) doSomethingIfTrue();
74 * if (!t) doSomethingIfFalse();
75 * if (~t) doSomethingIfCancelled();
76 * @endcode
77 *
78 * "! ~" can be used as "not cancelled".
79 *
80 * With tristate class, developer can also forget about
81 * it's additional meaning and treat it just as a bool, if the third state
82 * is irrelevant to the current situation.
83 *
84 * Other use for tristate class could be to allow cancellation within
85 * a callback function or a Qt slot. Example:
86 * @code
87 * public Q_SLOTS:
88 * void validateData(tristate *result);
89 * @endcode
90 * Having the single parameter, signals and slots have still simple look.
91 * Developers can alter their code (by replacing 'bool *result' with 'tristate *result')
92 * in case when a possibility of canceling of, say, data provessing needs to be implemented.
93 * Let's say @e validateData() function uses a QDialog to get some validation from a user.
94 * While QDialog::Rejected is returned after cancellation of the validation process,
95 * the information about cancellation needs to be transferred up to a higher level of the program.
96 * Storing values of type QDialog::DialogCode there could be found as unreadable, and
97 * casting these to int is not typesafe. With tristate class it's easier to make it obvious that
98 * cancellation should be taken into account.
99 */
101{
102public:
103 /**
104 * Default constructor, object has @e cancelled value set.
105 */
106 inline tristate()
107 : m_value(Cancelled) {
108 }
109
110 /**
111 * Constructor accepting a boolean value.
112 */
113 inline tristate(bool boolValue)
114 : m_value(boolValue ? True : False) {
115 }
116
117 /**
118 * Constructor accepting a char value.
119 * It is converted in the following way:
120 * - 2 -> cancelled
121 * - 1 -> true
122 * - other -> false
123 */
124 inline tristate(tristate_cancelled_t)
125 : m_value(tristate::Cancelled) {
126 }
127
128 /**
129 * Casting to bool type with negation: true is only returned
130 * if the original tristate value is equal to false.
131 */
132 inline bool operator!() const {
133 return m_value == False;
134 }
135
136 /**
137 * Special casting to bool type: true is only returned
138 * if the original tristate value is equal to @e cancelled.
139 */
140 inline bool operator~() const {
141 return m_value == Cancelled;
142 }
143
144 inline tristate& operator=(tristate tsValue);
145
146 inline tristate& operator=(bool boolValue);
147
148 inline tristate& operator=(tristate_cancelled_t);
149
150 friend inline bool operator==(bool boolValue, tristate tsValue);
151
152 friend inline bool operator==(tristate tsValue, bool boolValue);
153
154 friend inline bool operator!=(bool boolValue, tristate tsValue);
155
156 friend inline bool operator!=(tristate tsValue, bool boolValue);
157
158 friend inline bool operator==(tristate_cancelled_t, tristate tsValue);
159
160 friend inline bool operator==(tristate tsValue, tristate_cancelled_t);
161
162 friend inline bool operator!=(tristate_cancelled_t, tristate tsValue);
163
164 friend inline bool operator!=(tristate tsValue, tristate_cancelled_t);
165
166 friend inline bool operator==(tristate_cancelled_t, bool boolValue);
167
168 friend inline bool operator==(bool boolValue, tristate_cancelled_t);
169
170 friend inline bool operator!=(tristate_cancelled_t, bool boolValue);
171
172 friend inline bool operator!=(bool boolValue, tristate_cancelled_t);
173
174 friend inline QDebug operator<<(QDebug dbg, tristate tsValue);
175
176 /**
177 * @return text representation of the value: "true", "false" or "cancelled".
178 */
180 if (m_value == False) {
181 return QStringLiteral("false");
182 }
183 return m_value == True ? QStringLiteral("true") : QStringLiteral("cancelled");
184 }
185
186private:
187 /**
188 * @internal
189 * States used internally.
190 */
191 enum Value {
192 False = 0,
193 True = 1,
194 Cancelled = 2
195 };
196
197 /**
198 * @internal
199 */
200 Value m_value;
201};
202
203tristate& tristate::operator=(tristate tsValue)
204{
205 m_value = tsValue.m_value;
206 return *this;
207}
208
209tristate& tristate::operator=(bool boolValue)
210{
211 m_value = boolValue ? True : False;
212 return *this;
213}
214
215tristate& tristate::operator=(tristate_cancelled_t)
216{
217 m_value = Cancelled;
218 return *this;
219}
220
221/**
222 * Inequality operator comparing a bool value @p boolValue and a tristate value @p tsValue.
223 *
224 * @return false if both @p boolValue and @p tsValue are true
225 * or if both @p boolValue and @p tsValue are false.
226 * Else, returns true.
227*/
228inline bool operator!=(bool boolValue, tristate tsValue)
229{
230 return !((tsValue.m_value == tristate::True && boolValue)
231 || (tsValue.m_value == tristate::False && !boolValue));
232}
233
234/**
235 * Inequality operator comparing a tristate value @p tsValue and a bool value @p boolValue.
236 * @see bool operator!=(bool boolValue, tristate tsValue)
237*/
238inline bool operator!=(tristate tsValue, bool boolValue)
239{
240 return !((tsValue.m_value == tristate::True && boolValue)
241 || (tsValue.m_value == tristate::False && !boolValue));
242}
243
244/**
245 * Equality operator comparing a tristate value @p tsValue and a bool value @p boolValue.
246 * @return true if
247 * - both @p tsValue value and @p boolValue are true, or
248 * - both @p tsValue value and @p boolValue are false
249 * If the tristate value has value of cancelled, false is returned.
250 */
251inline bool operator==(tristate tsValue, bool boolValue)
252{
253 return (tsValue.m_value == tristate::True && boolValue)
254 || (tsValue.m_value == tristate::False && !boolValue);
255}
256
257/**
258 * Equality operator comparing a bool value @p boolValue and a tristate value @p tsValue.
259 * @return true if both
260 * - both @p tsValue value and @p boolValue are true, or
261 * - both @p tsValue value and @p boolValue are false
262 * If the tristate value has value of cancelled, false is returned.
263 */
264inline bool operator==(bool boolValue, tristate tsValue)
265{
266 return (tsValue.m_value == tristate::True && boolValue)
267 || (tsValue.m_value == tristate::False && !boolValue);
268}
269
270/**
271 * Equality operator comparing a cancelled and a tristate value @p tsValue.
272 * @return true if @p tsValue is equal to cancelled value.
273 */
274inline bool operator==(tristate_cancelled_t, tristate tsValue)
275{
276 return tsValue.m_value == tristate::Cancelled;
277}
278
279/**
280 * Equality operator comparing a cancelled and a tristate value @p tsValue.
281 * @return true if @p tsValue is equal to cancelled value.
282 */
283inline bool operator==(tristate tsValue, tristate_cancelled_t)
284{
285 return tsValue.m_value == tristate::Cancelled;
286}
287
288/**
289 * Equality operator comparing a cancelled and a bool value.
290 * @return false.
291 */
292inline bool operator==(tristate_cancelled_t, bool)
293{
294 return false;
295}
296
297/**
298 * Equality operator comparing a cancelled and a bool value.
299 * @return false.
300 */
301inline bool operator==(bool, tristate_cancelled_t)
302{
303 return false;
304}
305
306/**
307 * Inequality operator comparing a cancelled and a tristate value @p tsValue.
308 * @return true if @p tsValue is not equal to cancelled value.
309 */
310inline bool operator!=(tristate_cancelled_t, tristate tsValue)
311{
312 return tsValue.m_value != tristate::Cancelled;
313}
314
315/**
316 * Equality operator comparing a cancelled and a tristate value @p tsValue.
317 * @return true if @p tsValue is not equal to cancelled value.
318 */
319inline bool operator!=(tristate tsValue, tristate_cancelled_t)
320{
321 return tsValue.m_value != tristate::Cancelled;
322}
323
324/**
325 * Equality operator comparing a cancelled and a bool value.
326 * @return true.
327 */
328inline bool operator!=(tristate_cancelled_t, bool)
329{
330 return true;
331}
332
333/**
334 * Equality operator comparing a cancelled and a bool value.
335 * @return true.
336 */
337inline bool operator!=(bool, tristate_cancelled_t)
338{
339 return true;
340}
341
342//! qDebug() stream operator. Writes tristate value to the debug output in a nicely formatted way.
343inline QDebug operator<<(QDebug dbg, tristate tsValue)
344{
345 switch (tsValue.m_value) {
346 case tristate::True: dbg.nospace() << "true"; break;
347 case tristate::False: dbg.nospace() << "false"; break;
348 case tristate::Cancelled: dbg.nospace() << "cancelled"; break;
349 }
350 return dbg.space();
351}
352
353inline QDebug operator<<(QDebug dbg, tristate_cancelled_t)
354{
355 dbg.nospace() << "cancelled";
356 return dbg.space();
357}
358
359inline bool operator~(tristate_cancelled_t)
360{
361 return true;
362}
363
364inline bool operator!(tristate_cancelled_t)
365{
366 return false;
367}
368
369#endif
3-state logical type with three values: true, false and cancelled and convenient operators.
bool operator~() const
Special casting to bool type: true is only returned if the original tristate value is equal to cancel...
bool operator!() const
Casting to bool type with negation: true is only returned if the original tristate value is equal to ...
tristate(tristate_cancelled_t)
Constructor accepting a char value.
friend bool operator==(bool boolValue, tristate tsValue)
Equality operator comparing a bool value boolValue and a tristate value tsValue.
tristate()
Default constructor, object has cancelled value set.
friend QDebug operator<<(QDebug dbg, tristate tsValue)
qDebug() stream operator. Writes tristate value to the debug output in a nicely formatted way.
friend bool operator!=(bool boolValue, tristate tsValue)
Inequality operator comparing a bool value boolValue and a tristate value tsValue.
QString toString() const
tristate(bool boolValue)
Constructor accepting a boolean value.
QDebug & nospace()
QDebug & space()
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 17 2024 11:56:02 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.