← Back to branch summary

~smartboyhw/ubuntu/raring/calligra/2.6.0-0ubuntu1

« back to all changes in this revision

Viewing changes to libs/db/tristate.h

  • Committer: Package Import Robot
  • Author(s): Philip Muškovac
  • Date: 2012-10-23 21:09:16 UTC
  • mfrom: (1.1.13)
  • Revision ID: package-import@ubuntu.com-20121023210916-m82w6zxnxhaxz7va
Tags: 1:2.5.90-0ubuntu1
https://launchpad.net/bugs/1070436
https://launchpad.net/bugs/1071686
* New upstream alpha release (LP: #1070436)
  - Add libkactivities-dev and libopenimageio-dev to build-depends
  - Add kubuntu_build_calligraactive.diff to build calligraactive by default
  - Add package for calligraauthor and move files that are shared between
    calligrawords and calligraauthor to calligrawords-common
* Document the patches
* Remove numbers from patches so they follow the same naming scheme as
  the rest of our patches.
* calligra-data breaks replaces krita-data (<< 1:2.5.3) (LP: #1071686)

Show diffs side-by-side

added added

removed removed

Lines of Context:
libs/db/tristate.h
 
1
/* This file is part of the KDE project
 
2
   Copyright (C) 2004, 2006 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 _TRISTATE_TYPE_H_
 
21
#define _TRISTATE_TYPE_H_
 
22
 
 
23
#include <QString>
 
24
 
 
25
/**
 
26
 * \e cancelled value, in most cases usable if there is a need for returning
 
27
 * \e cancelled value explicitly. Example use:
 
28
 * \code
 
29
 * tristate myFunctionThatCanBeCancelled() {
 
30
 *   doSomething();
 
31
 *   if (userCancelledOperation())
 
32
 *     return cancelled; //neither success or failure is returned here
 
33
 *   return operationSucceeded(); //return success or failure
 
34
 * }
 
35
 * \endcode
 
36
 * Even though ~ operator of tristate class can be used, it is also possible to test:
 
37
 * \code
 
38
 * if (cancelled == myFunctionThatCanBeCancelled()) { .... }
 
39
 * \endcode
 
40
 */
 
41
static const char cancelled = 2;
 
42
 
 
43
/**
 
44
 * Convenience name, the same as cancelled value.
 
45
 */
 
46
static const char dontKnow = cancelled;
 
47
 
 
48
/**
 
49
 * 3-state logical type with three values: \e true, \e false and \e cancelled and convenient operators.
 
50
 *
 
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.
 
56
 *
 
57
 * Objects of this class can be used with similar convenience as standard bool type:
 
58
 * - use as return value when 'cancelled'
 
59
 *   \code
 
60
 *   tristate doSomething();
 
61
 *   \endcode
 
62
 * - convert from bool (1) or to bool (2)
 
63
 *   \code
 
64
 *   tristate t = true; //(1)
 
65
 *   setVisible(t);   //(2)
 
66
 *   \endcode
 
67
 * - clear comparisons
 
68
 *   \code
 
69
 *   tristate t = doSomething();
 
70
 *   if (t) doSomethingIfTrue();
 
71
 *   if (!t) doSomethingIfFalse();
 
72
 *   if (~t) doSomethingIfCancelled();
 
73
 *   \endcode
 
74
 *
 
75
 * "! ~" can be used as "not cancelled".
 
76
 *
 
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.
 
80
 *
 
81
 * Other use for tristate class could be to allow cancellation within
 
82
 * a callback function or a Qt slot. Example:
 
83
 * \code
 
84
 * public slots:
 
85
 *   void validateData(tristate& result);
 
86
 * \endcode
 
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.
 
96
 *
 
97
 * @author Jarosław Staniek
 
98
 */
 
99
class tristate
 
100
{
 
101
public:
 
102
    /**
 
103
     * Default constructor, object has \e cancelled value set.
 
104
     */
 
105
    tristate()
 
106
            : m_value(Cancelled) {
 
107
    }
 
108
 
 
109
    /**
 
110
     * Constructor accepting a boolean value.
 
111
     */
 
112
    tristate(bool boolValue)
 
113
            : m_value(boolValue ? True : False) {
 
114
    }
 
115
 
 
116
    /**
 
117
     * Constructor accepting a char value.
 
118
     * It is converted in the following way:
 
119
     * - 2 -> cancelled
 
120
     * - 1 -> true
 
121
     * - other -> false
 
122
     */
 
123
    tristate(char c)
 
124
            : m_value(c == cancelled ? tristate::Cancelled : (c == 1 ? True : False)) {
 
125
    }
 
126
 
 
127
    /** Constructor accepting an integer value.
 
128
     * It is converted in the following way:
 
129
     * - 2 -> cancelled
 
130
     * - 1 -> true
 
131
     * - other -> false
 
132
     */
 
133
    tristate(int intValue)
 
134
            : m_value(intValue == (int)cancelled ? tristate::Cancelled : (intValue == 1 ? True : False)) {
 
135
    }
 
136
 
 
137
    /**
 
138
     * Casting to bool type with negation: true is only returned
 
139
     * if the original tristate value is equal to false.
 
140
     */
 
141
    bool operator!() const {
 
142
        return m_value == False;
 
143
    }
 
144
 
 
145
    /**
 
146
     * Special casting to bool type: true is only returned
 
147
     * if the original tristate value is equal to \e cancelled.
 
148
     */
 
149
    bool operator~() const {
 
150
        return m_value == Cancelled;
 
151
    }
 
152
 
 
153
    tristate& operator=(const tristate& tsValue) {
 
154
        m_value = tsValue.m_value; return *this;
 
155
    }
 
156
 
 
157
    friend inline bool operator==(bool boolValue, tristate tsValue);
 
158
 
 
159
    friend inline bool operator==(tristate tsValue, bool boolValue);
 
160
 
 
161
    friend inline bool operator!=(bool boolValue, tristate tsValue);
 
162
 
 
163
    friend inline bool operator!=(tristate tsValue, bool boolValue);
 
164
 
 
165
    /**
 
166
     * \return text representation of the value: "true", "false" or "cancelled".
 
167
     */
 
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");
 
172
    }
 
173
 
 
174
private:
 
175
    /**
 
176
     * @internal
 
177
     * States used internally.
 
178
     */
 
179
    enum Value {
 
180
        False = 0,
 
181
        True = 1,
 
182
        Cancelled = 2
 
183
    };
 
184
 
 
185
    /**
 
186
     * @internal
 
187
     */
 
188
    Value m_value;
 
189
};
 
190
 
 
191
/**
 
192
 * Inequality operator comparing a bool value @p boolValue and a tristate value @p tsValue.
 
193
 *
 
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.
 
197
*/
 
198
inline bool operator!=(bool boolValue, tristate tsValue)
 
199
{
 
200
    return !((tsValue.m_value == tristate::True && boolValue)
 
201
             || (tsValue.m_value == tristate::False && !boolValue));
 
202
}
 
203
 
 
204
/**
 
205
 * Inequality operator comparing a tristate value @p tsValue and a bool value @p boolValue.
 
206
 * @see bool operator!=(bool boolValue, tristate tsValue)
 
207
*/
 
208
inline bool operator!=(tristate tsValue, bool boolValue)
 
209
{
 
210
    return !((tsValue.m_value == tristate::True && boolValue)
 
211
             || (tsValue.m_value == tristate::False && !boolValue));
 
212
}
 
213
 
 
214
/**
 
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.
 
220
  */
 
221
inline bool operator==(tristate tsValue, bool boolValue)
 
222
{
 
223
    return (tsValue.m_value == tristate::True && boolValue)
 
224
           || (tsValue.m_value == tristate::False && !boolValue);
 
225
}
 
226
 
 
227
/**
 
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.
 
233
  */
 
234
inline bool operator==(bool boolValue, tristate tsValue)
 
235
{
 
236
    return (tsValue.m_value == tristate::True && boolValue)
 
237
           || (tsValue.m_value == tristate::False && !boolValue);
 
238
}
 
239
 
 
240
#endif