KDb

KDbDateTime.h
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.2.0
41 */
42class KDB_EXPORT KDbYear
43{
44public:
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 */
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
136private:
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
144Q_DECLARE_METATYPE(KDbYear)
145
146//! Sends information about value @a sign to debug output @a dbg.
147KDB_EXPORT QDebug operator<<(QDebug dbg, KDbYear::Sign sign);
148
149//! Sends information about value @a year to debug output @a dbg.
150KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbYear &year);
151
152/**
153 * Generic date constant
154 *
155 * @since 3.2.0
156 */
157class KDB_EXPORT KDbDate
158{
159public:
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
244private:
245 const KDbYear m_year;
246 const QByteArray m_monthString;
247 const QByteArray m_dayString;
248};
249
250Q_DECLARE_METATYPE(KDbDate)
251
252//! Sends information about value @a date to debug output @a dbg.
253KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbDate &date);
254
255/**
256 * Generic time constant
257 *
258 * @since 3.2.0
259 */
260class KDB_EXPORT KDbTime
261{
262public:
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
385private:
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
393Q_DECLARE_METATYPE(KDbTime)
394
395//! Sends information about value @a time to debug output @a dbg.
396KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbTime &time);
397
398/**
399 * Generic date/time constant
400 *
401 * @since 3.2.0
402 */
403class KDB_EXPORT KDbDateTime
404{
405public:
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 */
414 {
415 }
416
417 bool operator==(const KDbDateTime &other) const;
418
419 inline bool operator!=(const KDbDateTime &other) const { return !operator==(other); }
420
421 bool operator<(const KDbDateTime &other) const;
422
423 inline bool operator<=(const KDbDateTime &other) const { return operator<(other) || operator==(other); }
424
425 inline bool operator>=(const KDbDateTime &other) const { return !operator<(other); }
426
427 inline bool operator>(const KDbDateTime &other) const { return !operator<=(other); }
428
429 /**
430 * Returns @c true if the date/time is valid
431 *
432 * Validation is performed by converting to QDateTime (toQDateTime()) and checking if it is valid.
433 */
434 bool isValid() const;
435
436 /**
437 * Returns @c true if the date/time is null
438 *
439 * A time is null if its date or time is null.
440 */
441 bool isNull() const;
442
443 /**
444 * Returns the date/time converted to QDateTime value
445 *
446 * Invalid QDateTime is returned if the KDbDateTime is invalid.
447 */
448 QDateTime toQDateTime() const;
449
450 /**
451 * Returns the date/time value converted to string even if it is invalid
452 *
453 * For null date/times empty string is returned.
454 */
455 QByteArray toString() const;
456
457 /**
458 * Returns the date part of the date/time
459 */
460 KDbDate date() const { return m_date; }
461
462 /**
463 * Returns the time part of the date/time
464 */
465 KDbTime time() const { return m_time; }
466
467private:
468 const KDbDate m_date;
469 const KDbTime m_time;
470};
471
472Q_DECLARE_METATYPE(KDbDateTime)
473
474//! Sends information about value @a dateTime to debug output @a dbg.
475KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbDateTime &dateTime);
476
477#endif
Generic date/time constant.
KDbDate date() const
Returns the date part of the date/time.
KDbDateTime()
Constructs a null date/time.
KDbTime time() const
Returns the time part of the date/time.
Generic date constant.
KDbYear year() const
Returns the year part of the date.
QByteArray dayString() const
Returns the day part of the date.
QByteArray monthString() const
Returns the month part of the date.
KDbDate()=default
Constructs a null date.
Generic time constant.
Period period() const
Specifies hour period.
QByteArray msecString() const
Returns the milliseconds part of the date.
QByteArray minuteString() const
Returns the minute part of the date.
QByteArray secondString() const
Returns the second part of the date.
KDbTime()=default
Constructs a null time.
Period
Specifies hour period.
QByteArray hourString() const
Returns the hour part of the date.
Generic year constant based on extended ISO 8601 specification.
Definition KDbDateTime.h:43
Sign sign() const
Returns the sign which is used to annotate year.
KDbYear(Sign sign, const QByteArray &string)
Constructs year based on given sign and string.
Definition KDbDateTime.h:59
Sign
Specifies sign which is used to annotate year.
Definition KDbDateTime.h:48
KDbYear(const QByteArray &string)
Constructs yea based on given string, with sign set to Sign::None.
Definition KDbDateTime.h:68
QByteArray yearString() const
Returns the string representation of year value even if it is invalid.
KDbYear()
Contructs a null year.
Definition KDbDateTime.h:75
char * toString(const EngineQuery &query)
KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &out, const KCalendarCore::Alarm::Ptr &)
KIOCORE_EXPORT bool operator==(const UDSEntry &entry, const UDSEntry &other)
bool isValid(QStringView ifopt)
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Mon Nov 4 2024 16:38:30 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.