KDb

KDbTristate.h
1 /* This file is part of the KDE project
2  Copyright (C) 2004-2012 JarosÅ‚aw Staniek <[email protected]>
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 
26 enum 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  */
100 class tristate
101 {
102 public:
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  */
179  QString toString() const {
180  if (m_value == False) {
181  return QStringLiteral("false");
182  }
183  return m_value == True ? QStringLiteral("true") : QStringLiteral("cancelled");
184  }
185 
186 private:
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 
203 tristate& tristate::operator=(tristate tsValue)
204 {
205  m_value = tsValue.m_value;
206  return *this;
207 }
208 
209 tristate& tristate::operator=(bool boolValue)
210 {
211  m_value = boolValue ? True : False;
212  return *this;
213 }
214 
215 tristate& 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 */
228 inline 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 */
238 inline 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  */
251 inline 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  */
264 inline 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  */
274 inline 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  */
283 inline 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  */
292 inline 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  */
301 inline 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  */
310 inline 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  */
319 inline 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  */
328 inline 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  */
337 inline 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.
343 inline 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 
353 inline QDebug operator<<(QDebug dbg, tristate_cancelled_t)
354 {
355  dbg.nospace() << "cancelled";
356  return dbg.space();
357 }
358 
359 inline bool operator~(tristate_cancelled_t)
360 {
361  return true;
362 }
363 
364 inline bool operator!(tristate_cancelled_t)
365 {
366  return false;
367 }
368 
369 #endif
QDebug & nospace()
friend bool operator!=(bool boolValue, tristate tsValue)
Inequality operator comparing a bool value boolValue and a tristate value tsValue.
Definition: KDbTristate.h:228
QDebug & space()
QDataStream & operator<<(QDataStream &out, const KDateTime &dateTime)
QString toString() const
Definition: KDbTristate.h:179
friend QDebug operator<<(QDebug dbg, tristate tsValue)
qDebug() stream operator. Writes tristate value to the debug output in a nicely formatted way.
Definition: KDbTristate.h:343
bool operator~() const
Special casting to bool type: true is only returned if the original tristate value is equal to cancel...
Definition: KDbTristate.h:140
tristate()
Default constructor, object has cancelled value set.
Definition: KDbTristate.h:106
3-state logical type with three values: true, false and cancelled and convenient operators.
Definition: KDbTristate.h:100
bool operator!() const
Casting to bool type with negation: true is only returned if the original tristate value is equal to ...
Definition: KDbTristate.h:132
tristate(tristate_cancelled_t)
Constructor accepting a char value.
Definition: KDbTristate.h:124
tristate(bool boolValue)
Constructor accepting a boolean value.
Definition: KDbTristate.h:113
friend bool operator==(bool boolValue, tristate tsValue)
Equality operator comparing a bool value boolValue and a tristate value tsValue.
Definition: KDbTristate.h:264
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sat Jun 25 2022 06:21:34 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.