1
/* This file is part of the KDE project
2
Copyright (C) 2004, 2006 Jarosław Staniek <staniek@kde.org>
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.
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.
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.
20
#ifndef _TRISTATE_TYPE_H_
21
#define _TRISTATE_TYPE_H_
26
* \e cancelled value, in most cases usable if there is a need for returning
27
* \e cancelled value explicitly. Example use:
29
* tristate myFunctionThatCanBeCancelled() {
31
* if (userCancelledOperation())
32
* return cancelled; //neither success or failure is returned here
33
* return operationSucceeded(); //return success or failure
36
* Even though ~ operator of tristate class can be used, it is also possible to test:
38
* if (cancelled == myFunctionThatCanBeCancelled()) { .... }
41
static const char cancelled = 2;
44
* Convenience name, the same as cancelled value.
46
static const char dontKnow = cancelled;
49
* 3-state logical type with three values: \e true, \e false and \e cancelled and convenient operators.
51
* \e cancelled state can be also called \e dontKnow, it behaves as \e null in SQL.
52
* A main goal of this class is to improve readibility when there's a need
53
* for storing third, \e cancelled, state, especially in case C++ exceptions are not in use.
54
* With it, developer can forget about declaring a specific enum type
55
* having just three values: \e true, \e false, \e cancelled.
57
* Objects of this class can be used with similar convenience as standard bool type:
58
* - use as return value when 'cancelled'
60
* tristate doSomething();
62
* - convert from bool (1) or to bool (2)
64
* tristate t = true; //(1)
65
* setVisible(t); //(2)
69
* tristate t = doSomething();
70
* if (t) doSomethingIfTrue();
71
* if (!t) doSomethingIfFalse();
72
* if (~t) doSomethingIfCancelled();
75
* "! ~" can be used as "not cancelled".
77
* With tristate class, developer can also forget about
78
* it's additional meaning and treat it just as a bool, if the third state
79
* is irrelevant to the current situation.
81
* Other use for tristate class could be to allow cancellation within
82
* a callback function or a Qt slot. Example:
85
* void validateData(tristate& result);
87
* Having the single parameter, signals and slots have still simple look.
88
* Developers can alter their code (by replacing 'bool& result' with 'tristate& result')
89
* in case when a possibility of canceling of, say, data provessing needs to be implemented.
90
* Let's say \e validateData() function uses a QDialog to get some validation from a user.
91
* While QDialog::Rejected is returned after cancellation of the validation process,
92
* the information about cancellation needs to be transferred up to a higher level of the program.
93
* Storing values of type QDialog::DialogCode there could be found as unreadable, and
94
* casting these to int is not typesafe. With tristate class it's easier to make it obvious that
95
* cancellation should be taken into account.
97
* @author Jarosław Staniek
103
* Default constructor, object has \e cancelled value set.
106
: m_value(Cancelled) {
110
* Constructor accepting a boolean value.
112
tristate(bool boolValue)
113
: m_value(boolValue ? True : False) {
117
* Constructor accepting a char value.
118
* It is converted in the following way:
124
: m_value(c == cancelled ? tristate::Cancelled : (c == 1 ? True : False)) {
127
/** Constructor accepting an integer value.
128
* It is converted in the following way:
133
tristate(int intValue)
134
: m_value(intValue == (int)cancelled ? tristate::Cancelled : (intValue == 1 ? True : False)) {
138
* Casting to bool type with negation: true is only returned
139
* if the original tristate value is equal to false.
141
bool operator!() const {
142
return m_value == False;
146
* Special casting to bool type: true is only returned
147
* if the original tristate value is equal to \e cancelled.
149
bool operator~() const {
150
return m_value == Cancelled;
153
tristate& operator=(const tristate& tsValue) {
154
m_value = tsValue.m_value; return *this;
157
friend inline bool operator==(bool boolValue, tristate tsValue);
159
friend inline bool operator==(tristate tsValue, bool boolValue);
161
friend inline bool operator!=(bool boolValue, tristate tsValue);
163
friend inline bool operator!=(tristate tsValue, bool boolValue);
166
* \return text representation of the value: "true", "false" or "cancelled".
168
QString toString() const {
169
if (m_value == False)
170
return QString::fromLatin1("false");
171
return m_value == True ? QString::fromLatin1("true") : QString::fromLatin1("cancelled");
177
* States used internally.
192
* Inequality operator comparing a bool value @p boolValue and a tristate value @p tsValue.
194
* @return false if both @p boolValue and @p tsValue are true
195
* or if both @p boolValue and @p tsValue are false.
196
* Else, returns true.
198
inline bool operator!=(bool boolValue, tristate tsValue)
200
return !((tsValue.m_value == tristate::True && boolValue)
201
|| (tsValue.m_value == tristate::False && !boolValue));
205
* Inequality operator comparing a tristate value @p tsValue and a bool value @p boolValue.
206
* @see bool operator!=(bool boolValue, tristate tsValue)
208
inline bool operator!=(tristate tsValue, bool boolValue)
210
return !((tsValue.m_value == tristate::True && boolValue)
211
|| (tsValue.m_value == tristate::False && !boolValue));
215
* Equality operator comparing a tristate value @p tsValue and a bool value @p boolValue.
216
* \return true if both
217
* - both @p tsValue value and @p boolValue are true, or
218
* - both @p tsValue value and @p boolValue are false
219
* If the tristate value has value of cancelled, false is returned.
221
inline bool operator==(tristate tsValue, bool boolValue)
223
return (tsValue.m_value == tristate::True && boolValue)
224
|| (tsValue.m_value == tristate::False && !boolValue);
228
* Equality operator comparing a bool value @p boolValue and a tristate value @p tsValue.
229
* \return true if both
230
* - both @p tsValue value and @p boolValue are true, or
231
* - both @p tsValue value and @p boolValue are false
232
* If the tristate value has value of cancelled, false is returned.
234
inline bool operator==(bool boolValue, tristate tsValue)
236
return (tsValue.m_value == tristate::True && boolValue)
237
|| (tsValue.m_value == tristate::False && !boolValue);
added
removed
kexi/kexiutils/tristate.h
