1/* This file is part of the KDE project
2 Copyright 2007 Stefan Nikolaus <stefan.nikolaus@kdemail.net>
3 Copyright 2003,2004 Ariya Hidayat <ariya@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; only
8 version 2 of the License.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21#ifndef CALLIGRA_SHEETS_VALUE_H
22#define CALLIGRA_SHEETS_VALUE_H
23
24#include <complex>
25
26#include <QDateTime>
27#include <QSharedDataPointer>
28#include <QString>
29#include <QTextStream>
30#include <QVariant>
31
32#include <kdebug.h>
33
34#include "Number.h"
35
36using namespace std;
37
38namespace Calligra
39{
40namespace Sheets
41{
42class CalculationSettings;
43class ValueStorage;
44
45/**
46 * \ingroup Value
47 * Provides a wrapper for cell value.
48 *
49 * Each cell in a worksheet must hold a value, either as enterred by user
50 * or as a result of formula evaluation. Default cell holds empty value.
51 *
52 * Value uses implicit data sharing to reduce memory usage.
53 */
54class CALLIGRA_SHEETS_ODF_EXPORT Value
55{
56
57public:
58
59 enum Type {
60 Empty,
61 Boolean,
62 Integer,
63 Float,
64 Complex,
65 String,
66 Array,
67 CellRange, // not used yet
68 Error
69 };
70
71 enum Format {
72 fmt_None,
73 fmt_Boolean,
74 fmt_Number,
75 fmt_Percent,
76 fmt_Money,
77 fmt_DateTime,
78 fmt_Date,
79 fmt_Time,
80 fmt_String
81 };
82 /**
83 * Creates an empty value, i.e holds nothing.
84 */
85 Value();
86
87 /**
88 * Creates a value of certain type.
89 */
90 explicit Value(Type _type);
91
92 /**
93 * Destroys the value.
94 */
95 virtual ~Value();
96
97 /**
98 * Creates a copy from another value.
99 */
100 Value(const Value& _value);
101
102 /**
103 * Assigns from another value.
104 *
105 * Because the data is implicitly shared, such assignment is very fast and
106 * doesn't consume additional memory.
107 */
108 Value& operator= (const Value& _value);
109
110 /**
111 * Creates a boolean value.
112 */
113 explicit Value(bool b);
114
115 /**
116 * Creates an integer value.
117 */
118 explicit Value(qint64 i);
119
120 /**
121 * Creates an integer value.
122 */
123 explicit Value(int i);
124
125 /**
126 * Creates a floating-point value.
127 */
128 explicit Value(double f);
129
130 /**
131 * Creates a floating-point value.
132 */
133 explicit Value(long double f);
134
135#ifdef CALLIGRA_SHEETS_HIGH_PRECISION_SUPPORT
136 /**
137 * Creates a floating-point value.
138 */
139 explicit Value(Number f);
140#endif // CALLIGRA_SHEETS_HIGH_PRECISION_SUPPORT
141
142 /**
143 * Creates a complex number value.
144 */
145 explicit Value(const complex<Number>& c);
146
147 /**
148 * Creates a string value.
149 */
150 explicit Value(const QString& s);
151
152 /**
153 * Creates a string value.
154 */
155 explicit Value(const char *s);
156
157 /**
158 * Creates an array value using the data from \p array.
159 */
160 explicit Value(const ValueStorage& array, const QSize& size);
161
162 /**
163 * Creates a floating-point value from date/time.
164 *
165 * Internally date/time is represented as serial-number, i.e number of
166 * elapsed day since reference date. Day 61 is defined as March 1, 1900.
167 */
168 Value(const QDateTime& dt, const CalculationSettings* settings);
169
170 /**
171 * Creates a floating-point value from time.
172 * See also note above.
173 */
174 Value(const QTime& time, const CalculationSettings* settings);
175
176 /**
177 * Creates a floating-point value from date.
178 * See also note above.
179 */
180 Value(const QDate& date, const CalculationSettings* settings);
181
182 /**
183 * Returns the type of the value.
184 */
185 Type type() const;
186
187 /**
188 * Returns true if null.
189 *
190 * A null value is equal to an empty value (and the other way around) in
191 * every way, except for what isNull() returns.
192 */
193 bool isNull() const;
194
195 /**
196 * Returns the format of the value, i.e. how should it be interpreted.
197 */
198 Format format() const;
199
200 /**
201 * Sets format information for this value.
202 */
203 void setFormat(Format fmt);
204
205 /**
206 * Returns true if empty.
207 */
208 bool isEmpty() const {
209 return type() == Empty;
210 }
211
212 /**
213 * Returns true, if the type of this value is Boolean.
214 */
215 bool isBoolean() const {
216 return type() == Boolean;
217 }
218
219 /**
220 * Returns true, if the type of this value is integer.
221 */
222 bool isInteger() const {
223 return type() == Integer;
224 }
225
226 /**
227 * Returns true, if the type of this value is floating-point.
228 */
229 bool isFloat() const {
230 return type() == Float;
231 }
232
233 /**
234 * Returns true, if the type of this value is the complex number type.
235 */
236 bool isComplex() const {
237 return type() == Complex;
238 }
239
240 /**
241 * Returns true, if the type of this value is either
242 * integer, floating-point or complex number.
243 */
244 bool isNumber() const {
245 return (type() == Integer) || (type() == Float) || (type() == Complex);
246 }
247
248 /**
249 * Returns true, if the type of this value is string.
250 */
251 bool isString() const {
252 return type() == String;
253 }
254
255 /**
256 * Returns true, if the type of this value is array.
257 */
258 bool isArray() const {
259 return type() == Array;
260 }
261
262 /**
263 * Returns true, if this value holds error information.
264 */
265 bool isError() const {
266 return type() == Error;
267 }
268
269 /**
270 * Sets this value to hold error message.
271 */
272 void setError(const QString& msg);
273
274 /**
275 * Returns the boolean value of this value.
276 *
277 * Call this function only if isBoolean() returns true.
278 */
279 bool asBoolean() const;
280
281 /**
282 * Returns the integer value of this value.
283 *
284 * Call this function only if isNumber() returns true.
285 */
286 qint64 asInteger() const;
287
288 /**
289 * Returns the floating-point value of this value.
290 *
291 * Call this function only if isNumber() returns true.
292 */
293 Number asFloat() const;
294
295 /**
296 * Returns the complex number value of this value.
297 *
298 * Call this function only if isNumber() returns true.
299 */
300 complex<Number> asComplex() const;
301
302 /**
303 * Returns the string value of this value.
304 *
305 * Call this function only if isString() returns true.
306 */
307 QString asString() const;
308
309 /**
310 * Returns the double quoted string value of this value.
311 *
312 * Same as \a asString but with double quotes around. This
313 * is needed for example in Conditions::saveOdfConditionValue
314 * to save Value strings with double quotes.
315 */
316 QString asStringWithDoubleQuotes() const;
317
318 /**
319 * Returns the data as a QVariant
320 */
321 QVariant asVariant() const;
322
323 /**
324 * Returns the date/time representation of this value.
325 */
326 QDateTime asDateTime(const CalculationSettings* settings) const;
327
328 /**
329 * Returns the date representation of this value.
330 */
331 QDate asDate(const CalculationSettings* settings) const;
332
333 /**
334 * Returns the time representation of this value.
335 */
336 QTime asTime(const CalculationSettings* settings) const;
337
338 /**
339 * Returns an element in the array value.
340 */
341 Value element(unsigned column, unsigned row) const;
342
343 /**
344 * Returns an array element given by its index denoting its position in the
345 * row-wise sorted list of non-empty values.
346 * Usable to iterate over the array.
347 * \see count()
348 */
349 Value element(unsigned index) const;
350
351 /**
352 * Sets an element in the array value. Do not use if isArray() is false.
353 */
354 void setElement(unsigned column, unsigned row, const Value& value);
355
356 /**
357 * If this value is an array, return the number of columns.
358 * Returns 1, if isArray() returns false.
359 */
360 unsigned columns() const;
361
362 /**
363 * If this value is an array, return the number of rows.
364 * Returns 1, if isArray() returns false.
365 */
366 unsigned rows() const;
367
368 /**
369 * If this value is an array, return the number of non-empty elements.
370 * Returns 1 if isArray() returns false.
371 * Usable to iterate over the array.
372 * \see element(unsigned)
373 */
374 unsigned count() const;
375
376 /**
377 * Returns error message associated with this value.
378 *
379 * Call this function only if isError() returns true.
380 */
381 QString errorMessage() const;
382
383 /**
384 * Returns constant reference to empty value.
385 */
386 static const Value& empty();
387
388 /*
389 * Returns a constant reference to a null value.
390 *
391 * A null value is equal to an empty value (and the other way around) in
392 * every way, except for what isNull() returns.
393 */
394 static const Value& null();
395
396 /**
397 * Returns constant reference to '\#CIRCLE!' error.
398 *
399 * This is used to indicate circular cell references.
400 */
401 static const Value& errorCIRCLE();
402
403 /**
404 * Returns constant reference to '\#DEPEND!' error.
405 *
406 * This is used to indicate broken cell references.
407 */
408 static const Value& errorDEPEND();
409
410 /**
411 * Returns constant reference to '\#DIV/0!' error.
412 *
413 * This is used to indicate that a formula divides by 0 (zero).
414 */
415 static const Value& errorDIV0();
416
417 /**
418 * Returns constant reference to '\#N/A' error.
419 *
420 * This is to indicate that a value is not available to a function.
421 */
422 static const Value& errorNA();
423
424 /**
425 * Returns constant reference to '\#NAME?' error.
426 *
427 * This is to indicate that certain text inside formula is not
428 * recognized, possibly a misspelled name or name that
429 * does not exist.
430 */
431 static const Value& errorNAME();
432
433 /**
434 * Returns constant reference to '\#NUM!' error.
435 *
436 * This is to indicate a problem with a number in a formula.
437 */
438 static const Value& errorNUM();
439
440 /**
441 * Returns constant reference to '\#NULL!' error.
442 *
443 * This is to indicate that two area do not intersect.
444 */
445 static const Value& errorNULL();
446
447 /**
448 * Returns constant reference to '\#PARSE!' error.
449 *
450 * This is used to indicate that a formula could not be parsed correctly.
451 */
452 static const Value& errorPARSE();
453
454 /**
455 * Returns constant reference to '\#REF!' error.
456 *
457 * This is used to indicate an invalid cell reference.
458 */
459 static const Value& errorREF();
460
461 /**
462 * Returns constant reference to '\#VALUE!' error.
463 *
464 * This is to indicate that wrong type of argument or operand
465 * is used, usually within a function call, e.g SIN("some text").
466 */
467 static const Value& errorVALUE();
468
469 /**
470 * Returns true if it is OK to compare this value with v.
471 * If this function returns false, then return value of compare is undefined.
472 */
473 bool allowComparison(const Value& v) const;
474
475 /**
476 * Returns -1, 0, 1, depends whether this value is less than, equal to, or
477 * greater than v.
478 */
479 int compare(const Value& v, Qt::CaseSensitivity cs = Qt::CaseSensitive) const;
480
481 /**
482 * Returns true if this value is equal to v.
483 */
484 bool equal(const Value& v, Qt::CaseSensitivity cs = Qt::CaseSensitive) const;
485
486 /**
487 * Returns true if this value is less than v.
488 */
489 bool less(const Value& v, Qt::CaseSensitivity cs = Qt::CaseSensitive) const;
490
491 /**
492 * Returns true if this value is greater than v.
493 */
494 bool greater(const Value& v, Qt::CaseSensitivity cs = Qt::CaseSensitive) const;
495
496 // comparison operator - returns true only if strictly identical, unlike equal()/compare()
497 bool operator==(const Value& v) const;
498 inline bool operator!=(const Value& other) const {
499 return !operator==(other);
500 }
501
502 static int compare(Number v1, Number v2);
503
504 bool isZero() const;
505
506 static bool isZero(Number v);
507
508private:
509 class Private;
510 QSharedDataPointer<Private> d;
511};
512
513/***************************************************************************
514 QHash/QSet support
515****************************************************************************/
516
517uint qHash(const Value& value);
518
519} // namespace Sheets
520} // namespace Calligra
521
522Q_DECLARE_METATYPE(Calligra::Sheets::Value)
523Q_DECLARE_TYPEINFO(Calligra::Sheets::Value, Q_MOVABLE_TYPE);
524
525
526/***************************************************************************
527 QTextStream support
528****************************************************************************/
529
530CALLIGRA_SHEETS_ODF_EXPORT QTextStream& operator<<(QTextStream& ts, Calligra::Sheets::Value::Type type);
531CALLIGRA_SHEETS_ODF_EXPORT QTextStream& operator<<(QTextStream& ts, Calligra::Sheets::Value value);
532
533/***************************************************************************
534 kDebug support
535****************************************************************************/
536
537CALLIGRA_SHEETS_ODF_EXPORT QDebug operator<<(QDebug str, const Calligra::Sheets::Value& v);
538QDebug operator<<(QDebug stream, const Calligra::Sheets::Value::Format& f);
539
540#endif // CALLIGRA_SHEETS_VALUE_H
541