KDb

KDbDateTime.h
1 /* This file is part of the KDE project
2  Copyright (C) 2018 JarosÅ‚aw Staniek <[email protected]>
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  */
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  */
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.2.0
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.2.0
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.2.0
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  */
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 
467 private:
468  const KDbDate m_date;
469  const KDbTime m_time;
470 };
471 
472 Q_DECLARE_METATYPE(KDbDateTime)
473 
474 //! Sends information about value @a dateTime to debug output @a dbg.
475 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbDateTime &dateTime);
476 
477 #endif
QByteArray monthString() const
Returns the month part of the date.
Definition: KDbDateTime.h:227
QByteArray minuteString() const
Returns the minute part of the date.
Definition: KDbDateTime.h:355
Sign
Specifies sign which is used to annotate year.
Definition: KDbDateTime.h:48
KDbDate date() const
Returns the date part of the date/time.
Definition: KDbDateTime.h:460
QByteArray yearString() const
Returns the string representation of year value even if it is invalid.
Definition: KDbDateTime.h:115
QByteArray msecString() const
Returns the milliseconds part of the date.
Definition: KDbDateTime.h:378
Period period() const
Specifies hour period.
Definition: KDbDateTime.h:383
KDbYear(Sign sign, const QByteArray &string)
Constructs year based on given sign and string.
Definition: KDbDateTime.h:59
QDataStream & operator<<(QDataStream &out, const KDateTime &dateTime)
KDbTime time() const
Returns the time part of the date/time.
Definition: KDbDateTime.h:465
KDbYear(const QByteArray &string)
Constructs yea based on given string, with sign set to Sign::None.
Definition: KDbDateTime.h:68
bool operator==(const Qt3DRender::QGraphicsApiFilter &reference, const Qt3DRender::QGraphicsApiFilter &sample)
char * toString(const T &value)
QByteArray dayString() const
Returns the day part of the date.
Definition: KDbDateTime.h:242
Sign sign() const
Returns the sign which is used to annotate year.
Definition: KDbDateTime.h:108
bool operator!=(const Qt3DRender::QGraphicsApiFilter &reference, const Qt3DRender::QGraphicsApiFilter &sample)
Generic time constant.
Definition: KDbDateTime.h:260
KDbYear()
Contructs a null year.
Definition: KDbDateTime.h:75
Generic date/time constant.
Definition: KDbDateTime.h:403
Generic year constant based on extended ISO 8601 specification.
Definition: KDbDateTime.h:42
Period
Specifies hour period.
Definition: KDbDateTime.h:266
bool isValid(QStringView ifopt)
QByteArray secondString() const
Returns the second part of the date.
Definition: KDbDateTime.h:369
Generic date constant.
Definition: KDbDateTime.h:157
KDbDateTime()
Constructs a null date/time.
Definition: KDbDateTime.h:413
KDbYear year() const
Returns the year part of the date.
Definition: KDbDateTime.h:213
QByteArray hourString() const
Returns the hour part of the date.
Definition: KDbDateTime.h:341
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sat Jun 25 2022 06:21:33 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.