Changeset View
Changeset View
Standalone View
Standalone View
src/KDbDateTime.h
- This file was added.
1 | /* This file is part of the KDE project | ||||
---|---|---|---|---|---|
2 | Copyright (C) 2018 Jarosław Staniek <staniek@kde.org> | ||||
3 | | ||||
4 | This library 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 library 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 library; see the file COPYING.LIB. 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_DATETIME_H | ||||
21 | #define KDB_DATETIME_H | ||||
22 | | ||||
23 | #include "kdb_export.h" | ||||
24 | | ||||
25 | #include <QDateTime> | ||||
26 | #include <QDebug> | ||||
27 | | ||||
28 | /** | ||||
29 | * Generic year constant based on extended ISO 8601 specification | ||||
30 | * | ||||
31 | * This class as well as KDbDate, KDbTime and KDbDateTime is used as a replacement for Qt date/time | ||||
32 | * value classes in case when invalid values have to be preserved. Without this, SQL parsers would | ||||
33 | * not function properly because they would loose information about mistyped constants. | ||||
34 | * The KDb* make it possible for the user to store the constants in SQL expressions and fix them | ||||
35 | * at later time. | ||||
36 | * | ||||
37 | * See this page for specifications of the date/time formats supported: | ||||
38 | * https://community.kde.org/Kexi/Plugins/Queries/SQL_Constants#Date_constants | ||||
39 | * | ||||
40 | * @since 3.1.1 | ||||
41 | */ | ||||
42 | class KDB_EXPORT KDbYear | ||||
43 | { | ||||
44 | public: | ||||
45 | /** | ||||
46 | * Specifies sign which is used to annotate year | ||||
47 | */ | ||||
48 | enum class Sign { | ||||
49 | None, | ||||
50 | Plus, | ||||
51 | Minus | ||||
52 | }; | ||||
53 | | ||||
54 | /** | ||||
55 | * Constructs year based on given sign and string | ||||
56 | * | ||||
57 | * Resulting year can be invalid but the string is always preserved. | ||||
58 | */ | ||||
59 | KDbYear(Sign sign, const QByteArray &string) : m_sign(sign), m_string(string) | ||||
60 | { | ||||
61 | } | ||||
62 | | ||||
63 | /** | ||||
64 | * Constructs yea based on given string, with sign set to Sign::None | ||||
65 | * | ||||
66 | * Resulting year can be invalid but the string is always preserved. | ||||
67 | */ | ||||
68 | explicit KDbYear(const QByteArray &string) : KDbYear(Sign::None, string) | ||||
69 | { | ||||
70 | } | ||||
71 | | ||||
72 | /** | ||||
73 | * Contructs a null year | ||||
74 | */ | ||||
75 | KDbYear() : KDbYear(QByteArray()) | ||||
76 | { | ||||
77 | } | ||||
78 | | ||||
79 | bool operator==(const KDbYear &other) const; | ||||
80 | | ||||
81 | inline bool operator!=(const KDbYear &other) const { return !operator==(other); } | ||||
82 | | ||||
83 | bool operator<(const KDbYear &other) const; | ||||
84 | | ||||
85 | inline bool operator<=(const KDbYear &other) const { return operator<(other) || operator==(other); } | ||||
86 | | ||||
87 | inline bool operator>=(const KDbYear &other) const { return !operator<(other); } | ||||
88 | | ||||
89 | inline bool operator>(const KDbYear &other) const { return !operator<=(other); } | ||||
90 | | ||||
91 | /** | ||||
92 | * Returns @c true if the year is valid | ||||
93 | * | ||||
94 | * Year is invalid if it is null or if the supplied string is invalid according to specification. | ||||
95 | */ | ||||
96 | bool isValid() const; | ||||
97 | | ||||
98 | /** | ||||
99 | * Returns @c true if the year is null | ||||
100 | * | ||||
101 | * A year is null if its sign is equal to Sign::None and string is empty. | ||||
102 | */ | ||||
103 | bool isNull() const; | ||||
104 | | ||||
105 | /** | ||||
106 | * Returns the sign which is used to annotate year | ||||
107 | */ | ||||
108 | Sign sign() const { return m_sign; } | ||||
109 | | ||||
110 | QByteArray signString() const; | ||||
111 | | ||||
112 | /** | ||||
113 | * Returns the string representation of year value even if it is invalid | ||||
114 | */ | ||||
115 | QByteArray yearString() const { return m_string; } | ||||
116 | | ||||
117 | /** | ||||
118 | * Returns entire year value (with sign) converted to string even if it is invalid | ||||
119 | */ | ||||
120 | QByteArray toString() const; | ||||
121 | | ||||
122 | /** | ||||
123 | * Returns the integer year value as defined by extended ISO 8601 | ||||
124 | * | ||||
125 | * 0 is returned for invalid year. | ||||
126 | */ | ||||
127 | int toIsoValue() const; | ||||
128 | | ||||
129 | /** | ||||
130 | * Returns the integer year value as defined by the QDate API | ||||
131 | * | ||||
132 | * 0 is returned for invalid year. | ||||
133 | */ | ||||
134 | int toQDateValue() const; | ||||
135 | | ||||
136 | private: | ||||
137 | std::tuple<int, bool> intValue() const; | ||||
138 | | ||||
139 | const Sign m_sign; | ||||
140 | const QByteArray m_string; | ||||
141 | int m_isoValue = -1; //!< Cached value for intValue(), -1 if the cache is missing | ||||
142 | }; | ||||
143 | | ||||
144 | Q_DECLARE_METATYPE(KDbYear) | ||||
145 | | ||||
146 | //! Sends information about value @a sign to debug output @a dbg. | ||||
147 | KDB_EXPORT QDebug operator<<(QDebug dbg, KDbYear::Sign sign); | ||||
148 | | ||||
149 | //! Sends information about value @a year to debug output @a dbg. | ||||
150 | KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbYear &year); | ||||
151 | | ||||
152 | /** | ||||
153 | * Generic date constant | ||||
154 | * | ||||
155 | * @since 3.1.1 | ||||
156 | */ | ||||
157 | class KDB_EXPORT KDbDate | ||||
158 | { | ||||
159 | public: | ||||
160 | KDbDate(const KDbYear &year, const QByteArray &monthString, const QByteArray &dayString) | ||||
161 | : m_year(year), m_monthString(monthString), m_dayString(dayString) | ||||
162 | { | ||||
163 | } | ||||
164 | | ||||
165 | /** | ||||
166 | * Constructs a null date | ||||
167 | */ | ||||
168 | KDbDate() = default; | ||||
169 | | ||||
170 | bool operator==(const KDbDate &other) const; | ||||
171 | | ||||
172 | inline bool operator!=(const KDbDate &other) const { return !operator==(other); } | ||||
173 | | ||||
174 | bool operator<(const KDbDate &other) const; | ||||
175 | | ||||
176 | inline bool operator<=(const KDbDate &other) const { return operator<(other) || operator==(other); } | ||||
177 | | ||||
178 | inline bool operator>=(const KDbDate &other) const { return !operator<(other); } | ||||
179 | | ||||
180 | inline bool operator>(const KDbDate &other) const { return !operator<=(other); } | ||||
181 | | ||||
182 | /** | ||||
183 | * Returns @c true if the date is valid | ||||
184 | * | ||||
185 | * Validation is performed by converting to QDate (toQDate()) and checking if it is valid. | ||||
186 | */ | ||||
187 | bool isValid() const; | ||||
188 | | ||||
189 | /** | ||||
190 | * Returns @c true if the date is null | ||||
191 | * | ||||
192 | * A date is null if its year is null, month string is empty and date string is empty. | ||||
193 | */ | ||||
194 | bool isNull() const; | ||||
195 | | ||||
196 | /** | ||||
197 | * Returns the date converted to QDate value | ||||
198 | * | ||||
199 | * Invalid QDate is returned if the KDbDate is invalid. | ||||
200 | */ | ||||
201 | QDate toQDate() const; | ||||
202 | | ||||
203 | /** | ||||
204 | * Returns the date value converted to string even if it is invalid | ||||
205 | * | ||||
206 | * For null dates empty string is returned. | ||||
207 | */ | ||||
208 | QByteArray toString() const; | ||||
209 | | ||||
210 | /** | ||||
211 | * Returns the year part of the date | ||||
212 | */ | ||||
213 | KDbYear year() const { return m_year; } | ||||
214 | | ||||
215 | /** | ||||
216 | * Returns the month part of the date converted to integer | ||||
217 | * | ||||
218 | * Correct values are in range 1..12, -1 is returned for invalid month. | ||||
219 | */ | ||||
220 | int month() const; | ||||
221 | | ||||
222 | /** | ||||
223 | * Returns the month part of the date | ||||
224 | * | ||||
225 | * It is original string passed to the KDbDate object and may be invalid. | ||||
226 | */ | ||||
227 | QByteArray monthString() const { return m_monthString; } | ||||
228 | | ||||
229 | /** | ||||
230 | * Returns the day part of the date converted to integer | ||||
231 | * | ||||
232 | * Correct values are in range 1..31, -1 is returned for invalid day. | ||||
233 | * THe date can be still invalid for valid integer, e.g. February 31st. | ||||
234 | */ | ||||
235 | int day() const; | ||||
236 | | ||||
237 | /** | ||||
238 | * Returns the day part of the date | ||||
239 | * | ||||
240 | * It is original string passed to the KDbDate object and may be invalid. | ||||
241 | */ | ||||
242 | QByteArray dayString() const { return m_dayString; } | ||||
243 | | ||||
244 | private: | ||||
245 | const KDbYear m_year; | ||||
246 | const QByteArray m_monthString; | ||||
247 | const QByteArray m_dayString; | ||||
248 | }; | ||||
249 | | ||||
250 | Q_DECLARE_METATYPE(KDbDate) | ||||
251 | | ||||
252 | //! Sends information about value @a date to debug output @a dbg. | ||||
253 | KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbDate &date); | ||||
254 | | ||||
255 | /** | ||||
256 | * Generic time constant | ||||
257 | * | ||||
258 | * @since 3.1.1 | ||||
259 | */ | ||||
260 | class KDB_EXPORT KDbTime | ||||
261 | { | ||||
262 | public: | ||||
263 | /** | ||||
264 | * Specifies hour period | ||||
265 | */ | ||||
266 | enum class Period { | ||||
267 | None, //!< 2-hour time | ||||
268 | Am, //!< AM, before noon | ||||
269 | Pm //!< PM, after noon, before midnight | ||||
270 | }; | ||||
271 | | ||||
272 | KDbTime(const QByteArray &hourString, const QByteArray &minuteString, | ||||
273 | const QByteArray &secondString = QByteArray(), | ||||
274 | const QByteArray &msecString = QByteArray(), Period period = Period::None) | ||||
275 | : m_hourString(hourString) | ||||
276 | , m_minuteString(minuteString) | ||||
277 | , m_secondString(secondString) | ||||
278 | , m_msecString(msecString) | ||||
279 | , m_period(period) | ||||
280 | { | ||||
281 | } | ||||
282 | | ||||
283 | /** | ||||
284 | * Constructs a null time | ||||
285 | */ | ||||
286 | KDbTime() = default; | ||||
287 | | ||||
288 | bool operator==(const KDbTime &other) const; | ||||
289 | | ||||
290 | inline bool operator!=(const KDbTime &other) const { return !operator==(other); } | ||||
291 | | ||||
292 | bool operator<(const KDbTime &other) const; | ||||
293 | | ||||
294 | inline bool operator<=(const KDbTime &other) const { return operator<(other) || operator==(other); } | ||||
295 | | ||||
296 | inline bool operator>=(const KDbTime &other) const { return !operator<(other); } | ||||
297 | | ||||
298 | inline bool operator>(const KDbTime &other) const { return !operator<=(other); } | ||||
299 | | ||||
300 | /** | ||||
301 | * Returns @c true if the time is valid | ||||
302 | * | ||||
303 | * Validation is performed by converting to QTime (toQTime()) and checking if it is valid. | ||||
304 | */ | ||||
305 | bool isValid() const; | ||||
306 | | ||||
307 | /** | ||||
308 | * Returns @c true if the time is null | ||||
309 | * | ||||
310 | * A time is null if its hour string or minute string is empty. | ||||
311 | */ | ||||
312 | bool isNull() const; | ||||
313 | | ||||
314 | /** | ||||
315 | * Returns the time value converted to QTime type | ||||
316 | * | ||||
317 | * Invalid QTime is returned if the KDbTime is invalid. | ||||
318 | */ | ||||
319 | QTime toQTime() const; | ||||
320 | | ||||
321 | /** | ||||
322 | * Returns the time value converted to string even if it is invalid | ||||
323 | * | ||||
324 | * For null times empty string is returned. | ||||
325 | */ | ||||
326 | QByteArray toString() const; | ||||
327 | | ||||
328 | /** | ||||
329 | * Returns the hour part of the time converted to integer | ||||
330 | * | ||||
331 | * Correct values are in range 0..23 for None period, and 1..12 for Am and Pm periods. | ||||
332 | * -1 is returned for invalid hour. | ||||
333 | */ | ||||
334 | int hour() const; | ||||
335 | | ||||
336 | /** | ||||
337 | * Returns the hour part of the date | ||||
338 | * | ||||
339 | * It is original string passed to the KDbTime object and may be invalid. | ||||
340 | */ | ||||
341 | QByteArray hourString() const { return m_hourString; } | ||||
342 | | ||||
343 | /** | ||||
344 | * Returns the minute part of the time converted to integer | ||||
345 | * | ||||
346 | * Correct values are in range 0..59. -1 is returned for invalid minute. | ||||
347 | */ | ||||
348 | int minute() const; | ||||
349 | | ||||
350 | /** | ||||
351 | * Returns the minute part of the date | ||||
352 | * | ||||
353 | * It is original string passed to the KDbTime object and may be invalid. | ||||
354 | */ | ||||
355 | QByteArray minuteString() const { return m_minuteString; } | ||||
356 | | ||||
357 | /** | ||||
358 | * Returns the second part of the time converted to integer | ||||
359 | * | ||||
360 | * Correct values are in range 0..59. -1 is returned for invalid second. | ||||
361 | */ | ||||
362 | int second() const; | ||||
363 | | ||||
364 | /** | ||||
365 | * Returns the second part of the date | ||||
366 | * | ||||
367 | * It is original string passed to the KDbTime object and may be invalid. | ||||
368 | */ | ||||
369 | QByteArray secondString() const { return m_secondString; } | ||||
370 | | ||||
371 | int msec() const; | ||||
372 | | ||||
373 | /** | ||||
374 | * Returns the milliseconds part of the date | ||||
375 | * | ||||
376 | * It is original string passed to the KDbTime object and may be invalid. | ||||
377 | */ | ||||
378 | QByteArray msecString() const { return m_msecString; } | ||||
379 | | ||||
380 | /** | ||||
381 | * Specifies hour period | ||||
382 | */ | ||||
383 | Period period() const { return m_period; } | ||||
384 | | ||||
385 | private: | ||||
386 | const QByteArray m_hourString; | ||||
387 | const QByteArray m_minuteString; | ||||
388 | const QByteArray m_secondString; | ||||
389 | const QByteArray m_msecString; | ||||
390 | const Period m_period = Period::None; | ||||
391 | }; | ||||
392 | | ||||
393 | Q_DECLARE_METATYPE(KDbTime) | ||||
394 | | ||||
395 | //! Sends information about value @a time to debug output @a dbg. | ||||
396 | KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbTime &time); | ||||
397 | | ||||
398 | /** | ||||
399 | * Generic date/time constant | ||||
400 | * | ||||
401 | * @since 3.1.1 | ||||
402 | */ | ||||
403 | class KDB_EXPORT KDbDateTime | ||||
404 | { | ||||
405 | public: | ||||
406 | KDbDateTime(const KDbDate &date, const KDbTime &time) : m_date(date), m_time(time) | ||||
407 | { | ||||
408 | } | ||||
409 | | ||||
410 | /** | ||||
411 | * Constructs a null date/time | ||||
412 | */ | ||||
413 | KDbDateTime() = default; | ||||
414 | | ||||
415 | bool operator==(const KDbDateTime &other) const; | ||||
416 | | ||||
417 | inline bool operator!=(const KDbDateTime &other) const { return !operator==(other); } | ||||
418 | | ||||
419 | bool operator<(const KDbDateTime &other) const; | ||||
420 | | ||||
421 | inline bool operator<=(const KDbDateTime &other) const { return operator<(other) || operator==(other); } | ||||
422 | | ||||
423 | inline bool operator>=(const KDbDateTime &other) const { return !operator<(other); } | ||||
424 | | ||||
425 | inline bool operator>(const KDbDateTime &other) const { return !operator<=(other); } | ||||
426 | | ||||
427 | /** | ||||
428 | * Returns @c true if the date/time is valid | ||||
429 | * | ||||
430 | * Validation is performed by converting to QDateTime (toQDateTime()) and checking if it is valid. | ||||
431 | */ | ||||
432 | bool isValid() const; | ||||
433 | | ||||
434 | /** | ||||
435 | * Returns @c true if the date/time is null | ||||
436 | * | ||||
437 | * A time is null if its date or time is null. | ||||
438 | */ | ||||
439 | bool isNull() const; | ||||
440 | | ||||
441 | /** | ||||
442 | * Returns the date/time converted to QDateTime value | ||||
443 | * | ||||
444 | * Invalid QDateTime is returned if the KDbDateTime is invalid. | ||||
445 | */ | ||||
446 | QDateTime toQDateTime() const; | ||||
447 | | ||||
448 | /** | ||||
449 | * Returns the date/time value converted to string even if it is invalid | ||||
450 | * | ||||
451 | * For null date/times empty string is returned. | ||||
452 | */ | ||||
453 | QByteArray toString() const; | ||||
454 | | ||||
455 | /** | ||||
456 | * Returns the date part of the date/time | ||||
457 | */ | ||||
458 | KDbDate date() const { return m_date; } | ||||
459 | | ||||
460 | /** | ||||
461 | * Returns the time part of the date/time | ||||
462 | */ | ||||
463 | KDbTime time() const { return m_time; } | ||||
464 | | ||||
465 | private: | ||||
466 | const KDbDate m_date; | ||||
467 | const KDbTime m_time; | ||||
468 | }; | ||||
469 | | ||||
470 | Q_DECLARE_METATYPE(KDbDateTime) | ||||
471 | | ||||
472 | //! Sends information about value @a dateTime to debug output @a dbg. | ||||
473 | KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbDateTime &dateTime); | ||||
474 | | ||||
475 | #endif |