KAlarmCal

kadatetime.h
Go to the documentation of this file.
1 /*
2  This file is part of kalarmcal library, which provides access to KAlarm
3  calendar data. Qt5 version of KDE 4 kdelibs/kdecore/date/kdatetime.h.
4 
5  SPDX-FileCopyrightText: 2005-2019 David Jarvie <[email protected]>
6 
7  SPDX-License-Identifier: LGPL-2.0-or-later
8 */
9 
10 /** @file
11  * Date/times with associated time zone
12  * @author David Jarvie <[email protected]>.
13  */
14 
15 #pragma once
16 
17 #include "kalarmcal_export.h"
18 
19 #include <QDateTime>
20 #include <QMetaType>
21 #include <QSharedDataPointer>
22 
23 class QDataStream;
24 
25 namespace KAlarmCal
26 {
27 
28 class KADateTimePrivate;
29 class KADateTimeSpecPrivate;
30 
31 /**
32  * @short A class representing a date and time with an associated time zone
33  *
34  * Topics:
35  * - @ref intro
36  * - @ref manipulation
37  * - @ref compatibility
38  *
39  * @section intro Introduction
40  *
41  * The class KADateTime extends the functionality of QDateTime. It combines a
42  * date and time with support for an associated time zone or UTC offset. When
43  * manipulating KADateTime objects, their time zones or UTC offsets are
44  * automatically taken into account. Extensions to QDateTime are:
45  * - KADateTime can be set to represent a date-only value with no associated
46  * time.
47  * - Local date/times which occur twice due to daylight savings time shifts,
48  * are handled properly, so that the two occurrences can be distinguished.
49  * - Extra string formatting functions are provided.
50  *
51  * The class uses QDateTime internally to represent date/time values. This
52  * imposes the following limitations:
53  * - QDateTime uses the Gregorian calendar retroactively. If you need the
54  * Julian calendar for historical dates (as commonly used prior to some date
55  * between 1582 and 1923 depending on nation), please use @c KCalendarSystem
56  * and related classes.
57  * - QDateTime does not handle daylight savings time changes properly before
58  * 1970, even when the system's time zone database contains this information.
59  *
60  * The time specification types which KADateTime supports are:
61  * - the UTC time zone
62  * - a local time with a specified offset from UTC
63  * - a local time in a specified time zone
64  * - a local time using the current system time zone. This follows any changes
65  * to the system time zone.
66  *
67  * These characteristics are more fully described in the description of the
68  * SpecType enumeration. Also see
69  * <a href="http://www.w3.org/TR/timezone/">W3C: Working with Time Zones</a>
70  * for a good overview of the different ways of representing times.
71  *
72  * To set the time specification, use one of the setTimeSpec() methods. To get
73  * the time specification, call timeSpec(), isUtc(), isLocalZone(), or
74  * isOffsetFromUtc(). To determine whether two KADateTime instances have the
75  * same time specification, call timeSpec() on each and compare the returned
76  * values using KADateTime::Spec::operator==().
77  *
78  * @section manipulation Date and Time Manipulation
79  *
80  * A KADateTime object can be created by passing a date and time in its
81  * constructor, together with a time specification.
82  *
83  * If both the date and time are null, isNull() returns true. If the date, time
84  * and time specification are all valid, isValid() returns true.
85  *
86  * A KADateTime object can be converted to a different time specification by
87  * using toUtc() or toLocalZone(). It can be converted to a specific time zone
88  * by toZone(). To return the time as an elapsed time since 1 January 1970 (as
89  * used by time(2)), use toSecsSinceEpoch(). The results of time zone
90  * conversions are cached to minimize the need for recalculation. Each
91  * KADateTime object caches its UTC equivalent and the last time zone
92  * conversion performed.
93  *
94  * The date and time can be set either in the constructor, or afterwards by
95  * calling setDate() or setTime(). To return the date and/or time components of
96  * the KADateTime, use date(), time() and qDateTime(). You can determine whether
97  * the KADateTime represents a date and time, or a date only, by isDateOnly().
98  * You can change between a date and time or a date only value using
99  * setDateOnly().
100  *
101  * You can increment or decrement the date/time using addSecs(), addDays(),
102  * addMonths() and addYears(). The interval between two date/time values can
103  * be found using secsTo() or daysTo().
104  *
105  * The comparison operators (operator==(), operator<(), etc.) all take the time
106  * zone properly into account; if the two KADateTime objects have different time
107  * zones, they are first converted to UTC before the comparison is
108  * performed. An alternative to the comparison operators is compare() which will
109  * in addition tell you if a KADateTime object overlaps with another when one or
110  * both are date-only values.
111  *
112  * KADateTime values may be converted to and from a string representation using
113  * the toString() and fromString() methods. These handle a variety of text
114  * formats including ISO 8601 and RFC 2822.
115  *
116  * KADateTime uses Qt's facilities to implicitly share data. Copying instances
117  * is very efficient, and copied instances share cached UTC and time zone
118  * conversions even after the copy is performed. A separate copy of the data is
119  * created whenever a non-const method is called. If you want to force the
120  * creation of a separate copy of the data (e.g. if you want two copies to
121  * cache different time zone conversions), call detach().
122  *
123  * @section compatibility QDateTime Considerations
124  *
125  * KADateTime's interface is designed to be as compatible as possible with that
126  * of QDateTime. Because QDateTime lacks virtual methods, KADateTime is not
127  * inherited from QDateTime, but instead is implemented using a private
128  * QDateTime object.
129  *
130  * @section simulation Simulation Facility
131  *
132  * This class provides a facility to simulate the local system time, which
133  * affects all functions using or returning the system time. This facility is
134  * provided for testing purposes only, and is only available if the library is
135  * compiled with debug enabled. In release mode, simulation is inoperative and
136  * the real local system time is used at all times. Use
137  * setSimulatedSystemTime() to set or clear the simulated time. To read the
138  * real (not simulated) system time, use realCurrentLocalDateTime().
139  *
140  * @see QTimeZone, QDateTime, QDate, QTime
141  * @see <a href="http://www.w3.org/TR/timezone/">W3C: Working with Time Zones</a>
142  * @author David Jarvie <[email protected]>.
143  */
144 class KALARMCAL_EXPORT KADateTime //krazy:exclude=dpointer (implicitly shared)
145 {
146 public:
147  /**
148  * The time specification type of a KADateTime instance.
149  * This specifies how the date/time component of the KADateTime instance
150  * should be interpreted, i.e. what type of time zone (if any) the date/time
151  * is expressed in. For the full time specification (including time zone
152  * details), see KADateTime::Spec.
153  */
154  enum SpecType {
155  Invalid, /**< an invalid time specification. */
156  UTC, /**< a UTC time. */
157  OffsetFromUTC, /**< a local time which has a fixed offset from UTC. */
158  TimeZone, /**< a time in a specified time zone.
159  * If the time zone happens to be the current system time
160  * zone (i.e. that returned by QTimeZone::systemTimeZone()),
161  * that time zone will continue to be used, unlike in the
162  * case of LocalZone, even if the system changes to use a
163  * different time zone.
164  */
165  LocalZone /**< a time in the current system time zone.
166  * Note that if the system is changed to a different time
167  * zone afterwards, the KADateTime instance will then use
168  * the new system time zone, as returned currently by
169  * QTimeZone::systemTimeZone().
170  */
171  };
172 
173  /**
174  * The full time specification of a KADateTime instance.
175  * This specifies how the date/time component of the KADateTime instance
176  * should be interpreted, i.e. which time zone (if any) the date/time is
177  * expressed in.
178  */
179  class Spec
180  {
181  public:
182  /**
183  * Constructs an invalid time specification.
184  */
185  Spec();
186 
187  /**
188  * Constructs a time specification for a given time zone.
189  * If @p tz is QTimeZone::utc(), the time specification type is set to @c UTC.
190  *
191  * @param tz time zone
192  */
193  Spec(const QTimeZone &tz); // allow implicit conversion
194 
195  /**
196  * Constructs a time specification.
197  *
198  * @param type time specification type, which should not be @c TimeZone
199  * @param utcOffset number of seconds to add to UTC to get the local
200  * time. Ignored if @p type is not @c OffsetFromUTC.
201  */
202  Spec(SpecType type, int utcOffset = 0); // allow implicit conversion
203 
204  /**
205  * Copy constructor.
206  */
207  Spec(const Spec &spec);
208 
209  /**
210  * Assignment operator.
211  */
212  Spec &operator=(const Spec &spec);
213 
214  /**
215  * Destructor
216  */
217  ~Spec();
218 
219  /**
220  * Returns whether the time specification is valid.
221  *
222  * @return @c true if valid, else @c false
223  */
224  bool isValid() const;
225 
226  /**
227  * Returns the time zone for the date/time, according to the time
228  * specification type as follows:
229  * - @c TimeZone : the specified time zone is returned.
230  * - @c UTC : a UTC time zone is returned.
231  * - @c LocalZone : the current local time zone is returned.
232  *
233  * @return time zone as defined above, or invalid in all other cases
234  * @see isUtc(), isLocal()
235  */
236  QTimeZone timeZone() const;
237 
238  /**
239  * Returns the time specification type, i.e. whether it is
240  * UTC, has a time zone, etc.
241  *
242  * @return specification type
243  * @see isLocalZone(), isUtc(), timeZone()
244  */
245  SpecType type() const;
246 
247  /**
248  * Returns whether the time specification follows the current local
249  * system time zone.
250  *
251  * @return @c true if local system time zone
252  * @see isUtc(), isOffsetFromUtc(), timeZone()
253  */
254  bool isLocalZone() const;
255 
256  /**
257  * Returns whether the time specification is a UTC time.
258  * It is considered to be a UTC time if it is either type @c UTC,
259  * or is type @c OffsetFromUTC with a zero UTC offset.
260  *
261  * @return @c true if UTC
262  * @see isLocal(), isOffsetFromUtc(), timeZone()
263  */
264  bool isUtc() const;
265 
266  /**
267  * Returns whether the time specification is a local time at a fixed
268  * offset from UTC.
269  *
270  * @return @c true if local time at fixed offset from UTC
271  * @see isLocal(), isUtc(), utcOffset()
272  */
273  bool isOffsetFromUtc() const;
274 
275  /**
276  * Returns the UTC offset associated with the time specification. The
277  * UTC offset is the number of seconds to add to UTC to get the local time.
278  *
279  * @return UTC offset in seconds if type is @c OffsetFromUTC, else 0
280  * @see isOffsetFromUtc()
281  */
282  int utcOffset() const;
283 
284  /**
285  * Initialises the time specification.
286  *
287  * @param type the time specification type. Note that @c TimeZone
288  * is invalid here.
289  * @param utcOffset number of seconds to add to UTC to get the local
290  * time. Ignored if @p spec is not @c OffsetFromUTC.
291  * @see type(), setType(const QTimeZone&)
292  */
293  void setType(SpecType type, int utcOffset = 0);
294 
295  /**
296  * Sets the time zone for the time specification.
297  *
298  * Note that setting the time zone to the current local system time zone
299  * has a different effect from setType(LocalZone), since the latter
300  * will follow changes to the system time zone.
301  *
302  * @param tz new time zone
303  * @see timeZone(), setType(SpecType)
304  */
305  void setType(const QTimeZone &tz);
306 
307  /**
308  * Comparison operator.
309  *
310  * @return @c true if the two instances are identical, @c false otherwise
311  * @see equivalentTo()
312  */
313  bool operator==(const Spec &other) const;
314 
315  bool operator!=(const Spec &other) const
316  {
317  return !operator==(other);
318  }
319 
320  /**
321  * Checks whether this instance is equivalent to another.
322  * The two instances are considered to be equivalent if any of the following
323  * conditions apply:
324  * - both instances are type @c OffsetFromUTC and their offsets from UTC are equal.
325  * - both instances are type @c TimeZone and their time zones are equal.
326  * - one instance is type @c TimeZone, with the time zone set to the system time
327  * zone, and the other instance is type @c LocalZone.
328  * - both instances are type @c LocalZone.
329  * - both instances are UTC. An instance is considered to be UTC if it is
330  * either type @c UTC, or is type @c OffsetFromUTC with a zero UTC offset.
331  *
332  * @return @c true if the two instances are equivalent, @c false otherwise
333  * @see operator==()
334  */
335  bool equivalentTo(const Spec &other) const;
336 
337  /**
338  * The UTC time specification.
339  * Provided as a shorthand for KADateTime::Spec(KADateTime::UTC).
340  */
341  static Spec UTC();
342 
343  /**
344  * Returns a UTC offset time specification.
345  * Provided as a shorthand for KADateTime::Spec(KADateTime::OffsetFromUTC, utcOffset).
346  *
347  * @param utcOffset number of seconds to add to UTC to get the local time
348  * @return UTC offset time specification
349  */
350  static Spec OffsetFromUTC(int utcOffset);
351 
352  /**
353  * Returns a local time zone time specification.
354  * Provided as a shorthand for KADateTime::Spec(KADateTime::LocalZone).
355  *
356  * @return Local zone time specification
357  */
358  static Spec LocalZone();
359 
360  private:
361  KADateTimeSpecPrivate *const d;
362  };
363 
364  /** Format for strings representing date/time values. */
365  enum TimeFormat {
366  ISODate, /**< ISO 8601 format, i.e. [±]YYYY-MM-DDThh[:mm[:ss[.sss]]]TZ,
367  * where TZ is the time zone offset (blank for local
368  * time, Z for UTC, or ±hhmm for an offset from UTC).
369  * When parsing a string, the ISO 8601 basic format,
370  * [±]YYYYMMDDThh[mm[ss[.sss]]]TZ, is also accepted. For
371  * date-only values, the formats [±]YYYY-MM-DD and
372  * [±]YYYYMMDD (without time zone specifier) are used. All
373  * formats may contain a day of the year instead of day
374  * and month.
375  * To allow for years past 9999, the year may optionally
376  * contain more than 4 digits. To avoid ambiguity, this is
377  * not allowed in the basic format containing a day
378  * of the year (i.e. when the date part is [±]YYYYDDD).
379  */
380  ISODateFull,/**< ISO 8601 format, always including a time zone.
381  * This is the same as ISODate, except that the current
382  * system time zone offset is appended for local times
383  * (type LocalZone).
384  */
385  RFCDate, /**< RFC 2822 format,
386  * i.e. "[Wdy,] DD Mon YYYY hh:mm[:ss] ±hhmm". This format
387  * also covers RFCs 822, 850, 1036 and 1123.
388  * When parsing a string, it also accepts the format
389  * "Wdy Mon DD HH:MM:SS YYYY" specified by RFCs 850 and
390  * 1036. There is no valid date-only format.
391  */
392  RFCDateDay, /**< RFC 2822 format including day of the week,
393  * i.e. "Wdy, DD Mon YYYY hh:mm:ss ±hhmm"
394  */
395  QtTextDate, /**< Same format as Qt::TextDate (i.e. Day Mon DD hh:mm:ss YYYY)
396  * with, if not local time, the UTC offset appended. The
397  * time may be omitted to indicate a date-only value.
398  */
399  LocalDate, /**< Same format as Qt::LocalDate (i.e. locale dependent)
400  * with, if not local time, the UTC offset appended. The
401  * time may be omitted to indicate a date-only value.
402  */
403  RFC3339Date /**< RFC 3339 format,
404  * i.e. "YYYY-MM-DDThh:mm:ss[.sss](Z|±hh:mm)".
405  * There is no valid date-only format.
406  */
407 
408  };
409 
410  /**
411  * How this KADateTime compares with another.
412  * If any date-only value is involved, comparison of KADateTime values
413  * requires them to be considered as representing time periods. A date-only
414  * instance represents a time period from 00:00:00 to 23:59:59.999 on a given
415  * date, while a date/time instance can be considered to represent a time
416  * period whose start and end times are the same. They may therefore be
417  * earlier or later, or may overlap or be contained one within the other.
418  *
419  * Values may be OR'ed with each other in any combination of 'consecutive'
420  * intervals to represent different types of relationship.
421  *
422  * In the descriptions of the values below,
423  * - s1 = start time of this instance
424  * - e1 = end time of this instance
425  * - s2 = start time of other instance
426  * - e2 = end time of other instance.
427  */
428  enum Comparison {
429  Before = 0x01, /**< This KADateTime is strictly earlier than the other,
430  * i.e. e1 < s2.
431  */
432  AtStart = 0x02, /**< This KADateTime starts at the same time as the other,
433  * and ends before the end of the other,
434  * i.e. s1 = s2, e1 < e2.
435  */
436  Inside = 0x04, /**< This KADateTime starts after the start of the other,
437  * and ends before the end of the other,
438  * i.e. s1 > s2, e1 < e2.
439  */
440  AtEnd = 0x08, /**< This KADateTime starts after the start of the other,
441  * and ends at the same time as the other,
442  * i.e. s1 > s2, e1 = e2.
443  */
444  After = 0x10, /**< This KADateTime is strictly later than the other,
445  * i.e. s1 > e2.
446  */
447  Equal = AtStart | Inside | AtEnd,
448  /**< Simultaneous, i.e. s1 = s2 && e1 = e2.
449  */
450  Outside = Before | AtStart | Inside | AtEnd | After,
451  /**< This KADateTime starts before the start of the other,
452  * and ends after the end of the other,
453  * i.e. s1 < s2, e1 > e2.
454  */
455  StartsAt = AtStart | Inside | AtEnd | After,
456  /**< This KADateTime starts at the same time as the other,
457  * and ends after the end of the other,
458  * i.e. s1 = s2, e1 > e2.
459  */
460  EndsAt = Before | AtStart | Inside | AtEnd
461  /**< This KADateTime starts before the start of the other,
462  * and ends at the same time as the other,
463  * i.e. s1 < s2, e1 = e2.
464  */
465  };
466 
467  /**
468  * Constructs an invalid date/time.
469  */
470  KADateTime();
471 
472  /**
473  * Constructs a date-only value expressed in a given time specification. The
474  * time is set to 00:00:00.
475  *
476  * The instance is initialised according to the time specification type of
477  * @p spec as follows:
478  * - @c UTC : date is stored as UTC.
479  * - @c OffsetFromUTC : date is a local time at the specified offset
480  * from UTC.
481  * - @c TimeZone : date is a local time in the specified time zone.
482  * - @c LocalZone : date is a local date in whatever the system time
483  * zone is currently.
484  *
485  * @param date date in the time zone indicated by @p spec
486  * @param spec time specification
487  */
488  explicit KADateTime(const QDate &date, const Spec &spec = Spec(LocalZone));
489 
490  /**
491  * Constructs a date/time expressed as specified by @p spec.
492  *
493  * @p date and @p time are interpreted and stored according to the value of
494  * @p spec as follows:
495  * - @c UTC : @p date and @p time are in UTC.
496  * - @c OffsetFromUTC : date/time is a local time at the specified offset
497  * from UTC.
498  * - @c TimeZone : date/time is a local time in the specified time zone.
499  * - @c LocalZone : @p date and @p time are local times in whatever the
500  * system time zone is currently.
501  *
502  * @param date date in the time zone indicated by @p spec
503  * @param time time in the time zone indicated by @p spec
504  * @param spec time specification
505  */
506  KADateTime(const QDate &date, const QTime &time, const Spec &spec = Spec(LocalZone));
507 
508  /**
509  * Constructs a date/time expressed in a given time specification.
510  *
511  * In detail, @p dt is interpreted and stored according to the time
512  * specification type of @p spec as follows:
513  * - @c UTC : @p dt is stored as a UTC value. If @c dt.timeSpec()
514  * is not @c Qt::UTC, @p dt is first converted to UTC
515  * before storage.
516  * - @c OffsetFromUTC : date/time is stored as a time at the specified offset
517  * from UTC. If @c dt.timeSpec() is not @c Qt::UTC,
518  * the time is converted to UTC and then adjusted by
519  * the UTC offset before storage.
520  * - @c TimeZone : date/time is stored as a local time in the specified
521  * time zone. If @c dt.timeSpec() is not the same time
522  * zone, @p dt is converted to the specified time zone
523  * before storage.
524  * - @c LocalZone : @p dt is stored as a local time in the current system
525  * time zone. If @c dt.timeSpec() is not @c Qt::LocalTime,
526  * @p dt is first converted to the system time zone before
527  * storage.
528  *
529  * @param dt date and time
530  * @param spec time specification
531  */
532  KADateTime(const QDateTime &dt, const Spec &spec);
533 
534  /**
535  * Constructs a date/time from a QDateTime.
536  * The KADateTime's time specification is determined according to @p dt.timeSpec().
537  *
538  * @param dt date and time
539  */
540  explicit KADateTime(const QDateTime &dt);
541 
542  KADateTime(const KADateTime &other);
543  ~KADateTime();
544 
545  KADateTime &operator=(const KADateTime &other);
546 
547  /**
548  * Returns whether the date/time is null.
549  *
550  * @return @c true if both date and time are null, else @c false
551  * @see isValid(), QDateTime::isNull()
552  */
553  bool isNull() const;
554 
555  /**
556  * Returns whether the date/time is valid.
557  *
558  * @return @c true if both date and time are valid, else @c false
559  * @see isNull(), QDateTime::isValid()
560  */
561  bool isValid() const;
562 
563  /**
564  * Returns whether the instance represents a date/time or a date-only value.
565  *
566  * @return @c true if date-only, @c false if date and time
567  */
568  bool isDateOnly() const;
569 
570  /**
571  * Returns the date part of the date/time. The value returned should be
572  * interpreted in terms of the instance's time zone or UTC offset.
573  *
574  * @return date value
575  * @see time(), qDateTime()
576  */
577  QDate date() const;
578 
579  /**
580  * Returns the time part of the date/time. The value returned should be
581  * interpreted in terms of the instance's time zone or UTC offset. If
582  * the instance is date-only, the time returned is 00:00:00.
583  *
584  * @return time value
585  * @see date(), qDateTime(), isDateOnly()
586  */
587  QTime time() const;
588 
589  /**
590  * Converts the instance to a QDateTime value.
591  *
592  * If the instance is date-only, the time value is set to 00:00:00.
593  *
594  * @return date/time
595  * @see date(), time()
596  */
597  QDateTime qDateTime() const;
598 
599  /**
600  * Returns the time zone for the date/time. If the date/time is specified
601  * as a UTC time, a UTC time zone is always returned. If it is specified as
602  * LocalZone, the system time zone is returned.
603  *
604  * @return time zone, or invalid if a local time at a fixed UTC offset
605  * @see isUtc(), isLocal()
606  */
607  QTimeZone timeZone() const;
608 
609  /**
610  * Returns the time specification of the date/time, i.e. whether it is
611  * UTC, what time zone it is, etc.
612  *
613  * @return time specification
614  * @see isLocalZone(), isUtc(), timeZone()
615  */
616  Spec timeSpec() const;
617 
618  /**
619  * Returns the time specification type of the date/time, i.e. whether it is
620  * UTC, has a time zone, etc.
621  *
622  * @return specification type
623  * @see timeSpec(), isLocalZone(), isUtc(), timeZone()
624  */
625  SpecType timeType() const;
626 
627  /**
628  * Returns whether the time zone for the date/time follows the current local
629  * system time zone.
630  *
631  * @return @c true if local system time zone
632  * @see isUtc(), isOffsetFromUtc(), timeZone()
633  */
634  bool isLocalZone() const;
635 
636  /**
637  * Returns whether the date/time is a UTC time.
638  * It is considered to be a UTC time if it either has a UTC time
639  * specification (SpecType == UTC), or has a zero offset from UTC
640  * (SpecType == OffsetFromUTC with zero UTC offset).
641  *
642  * @return @c true if UTC
643  * @see isLocal(), isOffsetFromUtc(), timeZone()
644  */
645  bool isUtc() const;
646 
647  /**
648  * Returns whether the date/time is a local time at a fixed offset from
649  * UTC.
650  *
651  * @return @c true if local time at fixed offset from UTC
652  * @see isLocal(), isUtc(), utcOffset()
653  */
654  bool isOffsetFromUtc() const;
655 
656  /**
657  * Returns the UTC offset associated with the date/time. The UTC offset is
658  * the number of seconds to add to UTC to get the local time.
659  *
660  * @return UTC offset in seconds
661  */
662  int utcOffset() const;
663 
664  /**
665  * Returns whether the date/time is the second occurrence of this time. This
666  * is only applicable to a date/time expressed in terms of a time zone (type
667  * @c TimeZone or @c LocalZone), around the time of change from daylight
668  * savings to standard time.
669  *
670  * When a shift from daylight savings time to standard time occurs, the local
671  * times (typically the previous hour) immediately preceding the shift occur
672  * twice. For example, if a time shift of 1 hour happens at 03:00, the clock
673  * jumps backwards to 02:00, so the local times between 02:00:00 and 02:59:59
674  * occur once before the shift, and again after the shift.
675  *
676  * For instances which are not of type @c TimeZone, or when the date/time is
677  * not near to a time shift, @c false is returned.
678  *
679  * @return @c true if the time is the second occurrence, @c false otherwise
680  * @see setSecondOccurrence()
681  */
682  bool isSecondOccurrence() const;
683 
684  /**
685  * Returns the time converted to UTC. The converted time has a UTC offset
686  * of zero.
687  * If the instance is a date-only value, a date-only UTC value is returned,
688  * with the date unchanged.
689  *
690  * @return converted time
691  * @see toOffsetFromUtc(), toLocalZone(), toZone(), toTimeSpec(), toSecsSinceEpoch(), QTimeZone::convert()
692  */
693  KADateTime toUtc() const;
694 
695  /**
696  * Returns the time expressed as an offset from UTC, using the UTC offset
697  * associated with this instance's date/time. The date and time
698  * components are unchanged. For example, 14:15 on 12 Jan 2001, US Eastern
699  * time zone would return a KADateTime value of 14:15 on 12 Jan 2001 with a
700  * UTC offset of -18000 seconds (i.e. -5 hours).
701  *
702  * If the instance is a date-only value, the offset is set to that at the
703  * start of the day.
704  *
705  * @return converted time
706  * @see toUtc(), toOffsetFromUtc(int), toLocalZone(), toZone(), toTimeSpec(), toSecsSinceEpoch(), QTimeZone::convert()
707  */
708  KADateTime toOffsetFromUtc() const;
709 
710  /**
711  * Returns the time expressed as a specified offset from UTC.
712  *
713  * If the instance is a date-only value, a date-only UTC offset time value
714  * is returned, with the date unchanged.
715  *
716  * @param utcOffset number of seconds to add to UTC to get the local time.
717  * @return converted time
718  * @see toUtc(), toOffsetFromUtc(), toLocalZone(), toZone(), toTimeSpec(), toSecsSinceEpoch(), QTimeZone::convert()
719  */
720  KADateTime toOffsetFromUtc(int utcOffset) const;
721 
722  /**
723  * Returns the time converted to the current local system time zone.
724  * If the instance is a date-only value, a date-only local time zone value
725  * is returned, with the date unchanged.
726  *
727  * @return converted time
728  * @see toUtc(), toOffsetFromUtc(), toZone(), toTimeSpec(), QTimeZone::convert()
729  */
730  KADateTime toLocalZone() const;
731 
732  /**
733  * Returns the time converted to a specified time zone.
734  * If the instance is a date-only value, a date-only value in @p zone is
735  * returned, with the date unchanged.
736  *
737  * @param zone time zone to convert to
738  * @return converted time
739  * @see toUtc(), toOffsetFromUtc(), toLocalZone(), toTimeSpec(), QTimeZone::convert()
740  */
741  KADateTime toZone(const QTimeZone &zone) const;
742 
743  /**
744  * Returns the time converted to a new time specification.
745  * If the instance is a date-only value, a date-only value is returned,
746  * with the date unchanged.
747  *
748  * @param spec new time specification
749  * @return converted time
750  * @see toLocalZone(), toUtc(), toOffsetFromUtc(), toZone(), QTimeZone::convert()
751  */
752  KADateTime toTimeSpec(const Spec &spec) const;
753 
754  /**
755  * Returns the time converted to the time specification of another instance.
756  * If this instance is a date-only value, a date-only value is returned,
757  * with the date unchanged.
758  *
759  * @param dt instance providing the new time specification
760  * @return converted time
761  * @see toLocalZone(), toUtc(), toOffsetFromUtc(), toZone(), QTimeZone::convert()
762  */
763  KADateTime toTimeSpec(const KADateTime &dt) const;
764 
765  /**
766  * Converts the time to a UTC time, measured in seconds since 00:00:00 UTC
767  * 1st January 1970 (as returned by time(2)).
768  *
769  * @return converted time, or @c LLONG_MIN if the date is out of range or invalid
770  * @see setSecsSinceEpoch()
771  */
772  qint64 toSecsSinceEpoch() const;
773 
774  /**
775  * Converts the time to a UTC time, measured in seconds since 00:00:00 UTC
776  * 1st January 1970 (as returned by time(2)).
777  *
778  * @return converted time, or @c uint(-1) if the date is out of range or invalid
779  * @see setTime_t()
780  * @deprecated Use toSecsSinceEpoch()
781  */
782  KALARMCAL_DEPRECATED uint toTime_t() const;
783 
784  /**
785  * Sets the time to a UTC time, specified as seconds since 00:00:00 UTC
786  * 1st January 1970 (as returned by time(2)).
787  *
788  * @param seconds number of seconds since 00:00:00 UTC 1st January 1970
789  * @see toSecsSinceEpoch()
790  */
791  void setSecsSinceEpoch(qint64 seconds);
792 
793  /**
794  * Sets the time to a UTC time, specified as seconds since 00:00:00 UTC
795  * 1st January 1970 (as returned by time(2)).
796  *
797  * @param seconds number of seconds since 00:00:00 UTC 1st January 1970
798  * @see toTime_t()
799  * @deprecated Use setSecsSinceEpoch()
800  */
801  KALARMCAL_DEPRECATED void setTime_t(qint64 seconds);
802 
803  /**
804  * Sets the instance either to being a date and time value, or a date-only
805  * value. If its status is changed to date-only, its time is set to
806  * 00:00:00.
807  *
808  * @param dateOnly @c true to set to date-only, @c false to set to date
809  * and time.
810  * @see isDateOnly(), setTime()
811  */
812  void setDateOnly(bool dateOnly);
813 
814  /**
815  * Sets the date part of the date/time.
816  *
817  * @param date new date value
818  * @see date(), setTime(), setTimeSpec(), setSecsSinceEpoch(), setDateOnly()
819  */
820  void setDate(const QDate &date);
821 
822  /**
823  * Sets the time part of the date/time. If the instance was date-only, it
824  * is changed to being a date and time value.
825  *
826  * @param time new time value
827  * @see time(), setDate(), setTimeSpec(), setSecsSinceEpoch()
828  */
829  void setTime(const QTime &time);
830 
831  /**
832  * Changes the time specification of the instance.
833  *
834  * Any previous time zone is forgotten. The stored date/time component of
835  * the instance is left unchanged (except that its Qt::TimeSpec setting is
836  * set to correspond with @p spec). Usually this method will change the
837  * absolute time which this instance represents.
838  *
839  * @param spec new time specification
840  * @see timeSpec(), timeZone()
841  */
842  void setTimeSpec(const Spec &spec);
843 
844  /**
845  * Sets whether the date/time is the second occurrence of this time. This
846  * is only applicable to a date/time expressed in terms of a time zone (type
847  * @c TimeZone or @c LocalZone), around the time of change from daylight
848  * savings to standard time.
849  *
850  * When a shift from daylight savings time to standard time occurs, the local
851  * times (typically the previous hour) immediately preceding the shift occur
852  * twice. For example, if a time shift of 1 hour happens at 03:00, the clock
853  * jumps backwards to 02:00, so the local times between 02:00:00 and 02:59:59
854  * occur once before the shift, and again after the shift.
855  *
856  * For instances which are not of type @c TimeZone, or when the date/time is
857  * not near to a time shift, calling this method has no effect.
858  *
859  * Note that most other setting methods clear the second occurrence indicator,
860  * so if you want to retain its setting, you must call setSecondOccurrence()
861  * again after changing the instance's value.
862  *
863  * @param second @c true to set as the second occurrence, @c false to set as
864  * the first occurrence
865  * @see isSecondOccurrence()
866  */
867  void setSecondOccurrence(bool second);
868 
869  /**
870  * Returns a date/time @p msecs milliseconds later than the stored date/time.
871  *
872  * The calculation is done in UTC to ensure that the result takes proper
873  * account of clock changes (e.g. daylight savings) in the time zone. The
874  * result is expressed using the same time specification as the original
875  * instance.
876  *
877  * If the instance is date-only, @p msecs is rounded down to a whole number
878  * of days and that value is added to the date to find the result.
879  *
880  * @return resultant date/time
881  * @see addSecs(), addDays(), addMonths(), addYears(), secsTo()
882  */
883  KADateTime addMSecs(qint64 msecs) const;
884 
885  /**
886  * Returns a date/time @p secs seconds later than the stored date/time.
887  *
888  * The calculation is done in UTC to ensure that the result takes proper
889  * account of clock changes (e.g. daylight savings) in the time zone. The
890  * result is expressed using the same time specification as the original
891  * instance.
892  *
893  * If the instance is date-only, @p secs is rounded down to a whole number
894  * of days and that value is added to the date to find the result.
895  *
896  * @return resultant date/time
897  * @see addMSecs(), addDays(), addMonths(), addYears(), secsTo()
898  */
899  KADateTime addSecs(qint64 secs) const;
900 
901  /**
902  * Returns a date/time @p days days later than the stored date/time.
903  * The result is expressed using the same time specification as the
904  * original instance.
905  *
906  * @return resultant date/time
907  * @see addSecs(), addMonths(), addYears(), daysTo()
908  */
909  KADateTime addDays(qint64 days) const;
910 
911  /**
912  * Returns a date/time @p months months later than the stored date/time.
913  * The result is expressed using the same time specification as the
914  * original instance.
915  *
916  * @return resultant date/time
917  * @see addSecs(), addDays(), addYears(), daysTo()
918  */
919  KADateTime addMonths(int months) const;
920 
921  /**
922  * Returns a date/time @p years years later than the stored date/time.
923  * The result is expressed using the same time specification as the
924  * original instance.
925  *
926  * @return resultant date/time
927  * @see addSecs(), addDays(), addMonths(), daysTo()
928  */
929  KADateTime addYears(int years) const;
930 
931  /**
932  * Returns the number of milliseconds from this date/time to the @p other date/time.
933  *
934  * Before performing the comparison, the two date/times are converted to UTC
935  * to ensure that the result is correct if one of the two date/times has
936  * daylight saving time (DST) and the other doesn't.
937  *
938  * If one instance is date-only and the other is date-time, the date-time
939  * value is first converted to the same time specification as the date-only
940  * value, and the result is the difference in days between the resultant
941  * date and the date-only date.
942  *
943  * If both instances are date-only, the result is the difference in days
944  * between the two dates, ignoring time zones.
945  *
946  * @param other other date/time
947  * @return number of milliseconds difference
948  * @see addSecs(), daysTo()
949  */
950  qint64 msecsTo(const KADateTime &other) const;
951 
952  /**
953  * Returns the number of seconds from this date/time to the @p other date/time.
954  *
955  * Before performing the comparison, the two date/times are converted to UTC
956  * to ensure that the result is correct if one of the two date/times has
957  * daylight saving time (DST) and the other doesn't.
958  *
959  * If one instance is date-only and the other is date-time, the date-time
960  * value is first converted to the same time specification as the date-only
961  * value, and the result is the difference in days between the resultant
962  * date and the date-only date.
963  *
964  * If both instances are date-only, the result is the difference in days
965  * between the two dates, ignoring time zones.
966  *
967  * @param other other date/time
968  * @return number of seconds difference
969  * @see addSecs(), daysTo()
970  */
971  qint64 secsTo(const KADateTime &other) const;
972 
973  /**
974  * Calculates the number of days from this date/time to the @p other date/time.
975  * In calculating the result, @p other is first converted to this instance's
976  * time zone. The number of days difference is then calculated ignoring
977  * the time parts of the two date/times. For example, if this date/time
978  * was 13:00 on 1 January 2000, and @p other was 02:00 on 2 January 2000,
979  * the result would be 1.
980  *
981  * If one instance is date-only and the other is date-time, the date-time
982  * value is first converted to the same time specification as the date-only
983  * value, and the result is the difference in days between the resultant
984  * date and the date-only date.
985  *
986  * If both instances are date-only, the calculation ignores time zones.
987  *
988  * @param other other date/time
989  * @return number of days difference
990  * @see secsTo(), addDays()
991  */
992  qint64 daysTo(const KADateTime &other) const;
993 
994  /**
995  * Returns the current date and time, as reported by the system clock,
996  * expressed in the local system time zone (type LocalZone).
997  *
998  * @return current date/time
999  * @see currentUtcDateTime(), currentDateTime()
1000  */
1001  static KADateTime currentLocalDateTime();
1002 
1003  /**
1004  * Returns the current date and time, as reported by the system clock,
1005  * expressed in UTC.
1006  *
1007  * @return current date/time
1008  * @see currentLocalDateTime(), currentDateTime(), currentLocalDate(), currentLocalTime()
1009  */
1010  static KADateTime currentUtcDateTime();
1011 
1012  /**
1013  * Returns the current date and time, as reported by the system clock,
1014  * expressed in a given time specification.
1015  *
1016  * @note To fetch the current date and time expressed in UTC or in the local
1017  * system time zone, it is more efficient to use currentUtcDateTime() or
1018  * currentLocalDateTime().
1019  *
1020  * @param spec time specification
1021  * @return current date/time
1022  * @see currentUtcDateTime(), currentLocalDateTime()
1023  */
1024  static KADateTime currentDateTime(const Spec &spec);
1025 
1026  /**
1027  * Returns the current date in the local time zone, as reported by the
1028  * system clock.
1029  *
1030  * @return current date
1031  * @see currentLocalDateTime(), currentLocalTime()
1032  * @since 4.3
1033  */
1034  static QDate currentLocalDate();
1035 
1036  /**
1037  * Returns the current time of day in the local time zone, as reported
1038  * by the system clock.
1039  *
1040  * @return current date
1041  * @see currentLocalDateTime(), currentLocalDate()
1042  * @since 4.3
1043  */
1044  static QTime currentLocalTime();
1045 
1046  /**
1047  * Returns the date/time as a string. The @p format parameter determines the
1048  * format of the result string. The @p format codes used for the date and time
1049  * components follow those used elsewhere in KDE, and are similar but not
1050  * identical to those used by strftime(3). Conversion specifiers are
1051  * introduced by a '\%' character, and are replaced in @p format as follows:
1052  *
1053  * \b Date
1054  *
1055  * - \%y 2-digit year excluding century (00 - 99). Conversion is undefined
1056  * if year < 0.
1057  * - \%Y full year number
1058  * - %:m month number, without leading zero (1 - 12)
1059  * - \%m month number, 2 digits (01 - 12)
1060  * - \%b abbreviated month name in current locale
1061  * - \%B full month name in current locale
1062  * - %:b abbreviated month name in English (Jan, Feb, ...)
1063  * - %:B full month name in English
1064  * - \%e day of the month (1 - 31)
1065  * - \%d day of the month, 2 digits (01 - 31)
1066  * - \%a abbreviated weekday name in current locale
1067  * - \%A full weekday name in current locale
1068  * - %:a abbreviated weekday name in English (Mon, Tue, ...)
1069  * - %:A full weekday name in English
1070  *
1071  * \b Time
1072  *
1073  * - \%H hour in the 24 hour clock, 2 digits (00 - 23)
1074  * - \%k hour in the 24 hour clock, without leading zero (0 - 23)
1075  * - \%I hour in the 12 hour clock, 2 digits (01 - 12)
1076  * - \%l hour in the 12 hour clock, without leading zero (1 - 12)
1077  * - \%M minute, 2 digits (00 - 59)
1078  * - \%S seconds (00 - 59)
1079  * - %:S seconds preceded with ':', but omitted if seconds value is zero
1080  * - %:s milliseconds, 3 digits (000 - 999)
1081  * - \%P "am" or "pm" in the current locale, or if undefined there, in English
1082  * - \%p "AM" or "PM" in the current locale, or if undefined there, in English
1083  * - %:P "am" or "pm"
1084  * - %:p "AM" or "PM"
1085  *
1086  * \b Time zone
1087  *
1088  * - %:u UTC offset of the time zone in hours, e.g. -02. If the offset
1089  * is not a whole number of hours, the output is the same as for '\%U'.
1090  * - \%z UTC offset of the time zone in hours and minutes, e.g. -0200.
1091  * - %:z UTC offset of the time zone in hours and minutes, e.g. +02:00.
1092  * - \%Z time zone abbreviation, e.g. UTC, EDT, GMT. This is not guaranteed
1093  * to be unique among different time zones. If not applicable (i.e. if
1094  * the instance is type OffsetFromUTC), the UTC offset is substituted.
1095  * - %:Z time zone name, e.g. Europe/London. This is system dependent. If
1096  * not applicable (i.e. if the instance is type OffsetFromUTC), the
1097  * UTC offset is substituted.
1098  *
1099  * \b Other
1100  *
1101  * - %% literal '\%' character
1102  *
1103  * If you want to use the current locale's date format, you should call
1104  * KLocale::formatDate() to format the date part of the KADateTime.
1105  *
1106  * @param format format for the string
1107  * @return formatted string
1108  * @see fromString(), KLocale::formatDate()
1109  */
1110  QString toString(const QString &format) const;
1111 
1112  /**
1113  * Returns the date/time as a string, formatted according to the @p format
1114  * parameter, with the UTC offset appended.
1115  *
1116  * If the instance is date-only, the time will when @p format permits be
1117  * omitted from the output string. This applies to @p format = QtTextDate
1118  * or LocalDate. For all other cases, a time of 00:00:00 will be output.
1119  *
1120  * For RFC 2822 format, set @p format to RFCDateDay to include the day
1121  * of the week, or to RFCDate to omit it.
1122  *
1123  * @param format format for output string
1124  * @return formatted string
1125  * @see fromString(), QDateTime::toString()
1126  */
1127  QString toString(TimeFormat format = ISODate) const;
1128 
1129  /**
1130  * Returns the KADateTime represented by @p string, using the @p format given.
1131  *
1132  * This method is the inverse of toString(TimeFormat), except that it can
1133  * only return a time specification of UTC or OffsetFromUTC. An actual
1134  * named time zone cannot be returned since an offset from UTC only
1135  * partially specifies a time zone.
1136  *
1137  * The time specification of the result is determined by the UTC offset
1138  * present in the string:
1139  * - if the UTC offset is zero the result is type @c UTC.
1140  * - if the UTC offset is non-zero, the result is type @c OffsetFromUTC.
1141  * - if there is no UTC offset (when @p format permits this), the result is
1142  * by default type @c LocalZone. You can use setFromStringDefault() to
1143  * change this default.
1144  *
1145  * If no time is found in @p string, a date-only value is returned, except
1146  * when the specified @p format does not permit the time to be omitted, in
1147  * which case an error is returned. An error is therefore returned for
1148  * ISODate when @p string includes a time zone specification, and for
1149  * RFCDate in all cases.
1150  *
1151  * For RFC format strings (not RFC 3339), you should normally set @p format
1152  * to RFCDate. Only set it to RFCDateDay if you want to return an error
1153  * when the day of the week is omitted.
1154  *
1155  * @param string string to convert
1156  * @param format format code. LocalDate cannot be used here.
1157  * @param negZero if non-null, the value is set to true if a UTC offset of
1158  * '-0000' is found or, for RFC 2822 format, an unrecognised
1159  * or invalid time zone abbreviation is found, else false.
1160  * @return KADateTime value, or an invalid KADateTime if either parameter is invalid
1161  * @see setFromStringDefault(), toString(), QString::fromString()
1162  */
1163  static KADateTime fromString(const QString &string, TimeFormat format = ISODate, bool *negZero = nullptr);
1164 
1165  /**
1166  * Returns the KADateTime represented by @p string, using the @p format
1167  * given, optionally using a time zone collection @p zones as the source of
1168  * time zone definitions. The @p format codes are basically the same as
1169  * those for toString(), and are similar but not identical to those used by
1170  * strftime(3).
1171  *
1172  * The @p format string consists of the same codes as that for
1173  * toString(). However, some codes which are distinct in toString() have
1174  * the same function as each other here.
1175  *
1176  * Numeric values without a stated number of digits permit, but do not
1177  * require, leading zeroes. The maximum number of digits consumed by a
1178  * numeric code is the minimum needed to cover the possible range of the
1179  * number (e.g. for minutes, the range is 0 - 59, so the maximum number of
1180  * digits consumed is 2). All non-numeric values are case insensitive.
1181  *
1182  * \b Date
1183  *
1184  * - \%y year excluding century (0 - 99). Years 0 - 50 return 2000 - 2050,
1185  * while years 51 - 99 return 1951 - 1999.
1186  * - \%Y full year number (4 digits with optional sign)
1187  * - %:Y full year number (>= 4 digits with optional sign)
1188  * - %:m month number (1 - 12)
1189  * - \%m month number, 2 digits (01 - 12)
1190  * - \%b
1191  * - \%B month name in the current locale or, if no match, in English,
1192  * abbreviated or in full
1193  * - %:b
1194  * - %:B month name in English, abbreviated or in full
1195  * - \%e day of the month (1 - 31)
1196  * - \%d day of the month, 2 digits (01 - 31)
1197  * - \%a
1198  * - \%A weekday name in the current locale or, if no match, in English,
1199  * abbreviated or in full
1200  * - %:a
1201  * - %:A weekday name in English, abbreviated or in full
1202  *
1203  * \b Time
1204  *
1205  * - \%H hour in the 24 hour clock, 2 digits (00 - 23)
1206  * - \%k hour in the 24 hour clock (0 - 23)
1207  * - \%I hour in the 12 hour clock, 2 digits (01 - 12)
1208  * - \%l hour in the 12 hour clock (1 - 12)
1209  * - \%M minute, 2 digits (00 - 59)
1210  * - %:M minute (0 - 59)
1211  * - \%S seconds, 2 digits (00 - 59)
1212  * - \%s seconds (0 - 59)
1213  * - %:S optional seconds value (0 - 59) preceded with ':'. If no colon is
1214  * found in @p string, no input is consumed and the seconds value is
1215  * set to zero.
1216  * - %:s fractional seconds value, preceded with a decimal point (either '.'
1217  * or the locale's decimal point symbol)
1218  * - \%P
1219  * - \%p "am" or "pm", in the current locale or, if no match, in
1220  * English. This format is only useful when used with \%I or \%l.
1221  * - %:P
1222  * - %:p "am" or "pm" in English. This format is only useful when used with
1223  * \%I or \%l.
1224  *
1225  * \b Time zone
1226  *
1227  * - %:u
1228  * - \%z UTC offset of the time zone in hours and optionally minutes,
1229  * e.g. -02, -0200.
1230  * - %:z UTC offset of the time zone in hours and minutes, colon separated,
1231  * e.g. +02:00.
1232  * - \%Z time zone abbreviation, consisting of alphanumeric characters,
1233  * e.g. UTC, EDT, GMT.
1234  * - %:Z time zone name, e.g. Europe/London. The name may contain any
1235  * characters and is delimited by the following character in the
1236  * @p format string. It will not work if you follow %:Z with another
1237  * escape sequence (except %% or \%t).
1238  *
1239  * \b Other
1240  *
1241  * - \%t matches one or more whitespace characters
1242  * - %% literal '\%' character
1243  *
1244  * Any other character must have a matching character in @p string, except
1245  * that a space will match zero or more whitespace characters in the input
1246  * string.
1247  *
1248  * If any time zone information is present in the string, the function
1249  * attempts to find a matching time zone in the @p zones collection. A time
1250  * zone name (format code %:Z) will provide an unambiguous look up in
1251  * @p zones. Any other type of time zone information (an abbreviated time
1252  * zone code (\%Z) or UTC offset (\%z, %:z, %:u) is searched for in @p zones
1253  * and if only one time zone is found to match, the result is set to that
1254  * zone. Otherwise:
1255  * - If more than one match of a UTC offset is found, the action taken is
1256  * determined by @p offsetIfAmbiguous: if @p offsetIfAmbiguous is true,
1257  * a local time with an offset from UTC (type @c OffsetFromUTC) will be
1258  * returned; if false an invalid KADateTime is returned.
1259  * - If more than one match of a time zone abbreviation is found, the UTC
1260  * offset for each matching time zone is compared and, if the offsets are
1261  * the same, a local time with an offset from UTC (type @c OffsetFromUTC)
1262  * will be returned provided that @p offsetIfAmbiguous is true. Otherwise
1263  * an invalid KADateTime is returned.
1264  * - If a time zone abbreviation does not match any time zone in @p zones,
1265  * or the abbreviation does not apply at the parsed date/time, an
1266  * invalid KADateTime is returned.
1267  * - If a time zone name does not match any time zone in @p zones, an
1268  * invalid KADateTime is returned.
1269  * - If the time zone UTC offset does not match any time zone in @p zones,
1270  * a local time with an offset from UTC (type @c OffsetFromUTC) is
1271  * returned.
1272  * If @p format contains more than one time zone or UTC offset code, an
1273  * error is returned.
1274  *
1275  * If no time zone information is present in the string, by default a local
1276  * time (type @c LocalZone) is returned. You can use setFromStringDefault()
1277  * to change this default.
1278  *
1279  * If no time is found in @p string, a date-only value is returned.
1280  *
1281  * If any inconsistencies are found, i.e. the same item of information
1282  * appears more than once but with different values, the weekday name does
1283  * not tally with the date, an invalid KADateTime is returned.
1284  *
1285  * @param string string to convert
1286  * @param format format string
1287  * @param zones time zone collection, or null for none
1288  * @param offsetIfAmbiguous specifies what to do if more than one zone
1289  * matches the UTC offset found in the
1290  * string. Ignored if @p zones is null.
1291  * @return KADateTime value, or an invalid KADateTime if an error occurs, if
1292  * time zone information doesn't match any in @p zones, or if the
1293  * time zone information is ambiguous and @p offsetIfAmbiguous is
1294  * false
1295  * @see setFromStringDefault(), toString()
1296  */
1297  static KADateTime fromString(const QString &string, const QString &format,
1298  const QList<QTimeZone>* zones = nullptr, bool offsetIfAmbiguous = true);
1299 
1300  /**
1301  * Sets the default time specification for use by fromString() when no time
1302  * zone or UTC offset is found in the string being parsed, or when "-0000"
1303  * is found in an RFC 2822 string.
1304  *
1305  * By default, fromString() returns a local time (type @c LocalZone) when
1306  * no definite zone or UTC offset is found. You can use this method to make
1307  * it return UTC, or whatever you wish.
1308  *
1309  * @param spec the new default time specification
1310  * @see fromString()
1311  */
1312  static void setFromStringDefault(const Spec &spec);
1313 
1314  /**
1315  * Compare this instance with another to determine whether they are
1316  * simultaneous, earlier or later, and in the case of date-only values,
1317  * whether they overlap (i.e. partly coincide but are not wholly
1318  * simultaneous).
1319  * The comparison takes time zones into account: if the two instances have
1320  * different time zones, they are first converted to UTC before comparing.
1321  *
1322  * If both instances are date/time values, this instance is considered to
1323  * be either simultaneous, earlier or later, and does not overlap.
1324  *
1325  * If one instance is date-only and the other is a date/time, this instance
1326  * is either strictly earlier, strictly later, or overlaps.
1327  *
1328  * If both instance are date-only, they are considered simultaneous if both
1329  * their start of day and end of day times are simultaneous with each
1330  * other. (Both start and end of day times need to be considered in case a
1331  * daylight savings change occurs during that day.) Otherwise, this instance
1332  * can be strictly earlier, earlier but overlapping, later but overlapping,
1333  * or strictly later.
1334  *
1335  * @return @c true if the two instances represent the same time, @c false otherwise
1336  * @see operator==(), operator!=(), operator<(), operator<=(), operator>=(), operator>()
1337  */
1338  Comparison compare(const KADateTime &other) const;
1339 
1340  /**
1341  * Check whether this date/time is simultaneous with another.
1342  * The comparison takes time zones into account: if the two instances have
1343  * different time zones, they are first converted to UTC before comparing.
1344  *
1345  * If one instance is date-only and the other is date/time, they are
1346  * considered unequal.
1347  *
1348  * If both instances are date-only, they are considered simultaneous if both
1349  * their start of day and end of day times are simultaneous with each
1350  * other. (Both start and end of day times need to be considered in case a
1351  * daylight saving change occurs during that day.)
1352  *
1353  * @return @c true if the two instances represent the same time, @c false otherwise
1354  * @see compare()
1355  */
1356  bool operator==(const KADateTime &other) const;
1357 
1358  bool operator!=(const KADateTime &other) const
1359  {
1360  return !(*this == other);
1361  }
1362 
1363  /**
1364  * Check whether this date/time is earlier than another.
1365  * The comparison takes time zones into account: if the two instances have
1366  * different time zones, they are first converted to UTC before comparing.
1367  *
1368  * If one or both instances are date-only, the comparison returns true if
1369  * this date/time or day, falls wholly before the other date/time or
1370  * day. To achieve this, the time used in the comparison is the end of day
1371  * (if this instance is date-only) or the start of day (if the other
1372  * instance is date-only).
1373  *
1374  * @return @c true if this instance represents an earlier time than @p other,
1375  * @c false otherwise
1376  * @see compare()
1377  */
1378  bool operator<(const KADateTime &other) const;
1379 
1380  bool operator<=(const KADateTime &other) const
1381  {
1382  return !(other < *this);
1383  }
1384  bool operator>(const KADateTime &other) const
1385  {
1386  return other < *this;
1387  }
1388  bool operator>=(const KADateTime &other) const
1389  {
1390  return !(*this < other);
1391  }
1392 
1393  /**
1394  * Create a separate copy of this instance's data if it is implicitly shared
1395  * with another instance.
1396  *
1397  * You would normally only call this if you want different copies of the
1398  * same date/time value to cache conversions to different time zones. Because
1399  * only the last conversion to another time zone is cached, and the cached
1400  * value is implicitly shared, judicious use of detach() could improve
1401  * efficiency when handling several time zones. But take care: if used
1402  * inappropriately, it will reduce efficiency!
1403  */
1404  void detach();
1405 
1406  /**
1407  * Set an adjustment to be applied when fetching the current system time.
1408  * This is applied by all KADateTime methods which return the system date
1409  * and/or time.
1410  *
1411  * The supplied date/time is used as the current simulated time and the
1412  * time adjustment is set to the difference between the real current time
1413  * and @p newTime. If @p newTime has a time zone, that time zone is set
1414  * to be the simulated local system time zone.
1415  *
1416  * To cancel time simulation, supply an invalid @p newTime parameter.
1417  *
1418  * @warning This function is provided only for testing purposes, and should
1419  * not be used in released code. If the library is compiled without
1420  * debug enabled, setSimulatedSystemTime() has no effect.
1421  * To avoid confusion, it is recommended that calls to it should be
1422  * conditionally compiled, e.g.:
1423  * \code
1424  * #ifndef NDEBUG
1425  * KADateTime::simulateSystemTime(kdt);
1426  * #endif
1427  * \endcode
1428  *
1429  * @param newTime the current simulated time, or invalid to cancel simulation
1430  *
1431  * @see currentDateTime(), currentLocalDateTime(), currentUtcDateTime(),
1432  * currentLocalDate(), currentLocalTime()
1433  * @since 4.3
1434  */
1435  static void setSimulatedSystemTime(const KADateTime &newTime);
1436 
1437  /**
1438  * Return the real (not simulated) system time.
1439  *
1440  * @warning This method is provided only for testing purposes, and should
1441  * not be used in released code. If the library is compiled without
1442  * debug enabled, currentLocalDateTime() and realCurrentLocalDateTime()
1443  * both return the real system time.
1444  * To avoid confusion, it is recommended that calls to
1445  * realCurrentLocalDateTime() should be conditionally compiled, e.g.:
1446  * \code
1447  * #ifndef NDEBUG
1448  * dt = KADateTime::realCurrentLocalDateTime();
1449  * #endif
1450  * \endcode
1451  *
1452  * @since 4.3
1453  */
1454  static KADateTime realCurrentLocalDateTime();
1455 
1456 private:
1458 };
1459 
1460 /** Write @p spec to the datastream @p out, in binary format. */
1461 KALARMCAL_EXPORT QDataStream &operator<<(QDataStream &out, const KADateTime::Spec &spec);
1462 /** Read a KADateTime::Spec object into @p spec from @p in, in binary format. */
1463 KALARMCAL_EXPORT QDataStream &operator>>(QDataStream &in, KADateTime::Spec &spec);
1464 
1465 /** Write @p dateTime to the datastream @p out, in binary format. */
1466 KALARMCAL_EXPORT QDataStream &operator<<(QDataStream &out, const KADateTime &dateTime);
1467 /** Read a KADateTime object into @p dateTime from @p in, in binary format. */
1468 KALARMCAL_EXPORT QDataStream &operator>>(QDataStream &in, KADateTime &dateTime);
1469 
1470 } // namespace KAlarmCal
1471 
1472 Q_DECLARE_METATYPE(KAlarmCal::KADateTime)
1473 Q_DECLARE_METATYPE(KAlarmCal::KADateTime::Spec)
1474 
1475 
1476 // vim: et sw=4:
an invalid time specification.
Definition: kadatetime.h:155
A class representing a date and time with an associated time zone.
Definition: kadatetime.h:144
QDataStream & operator>>(QDataStream &in, KDateTime::Spec &spec)
Comparison
How this KADateTime compares with another.
Definition: kadatetime.h:428
QDataStream & operator<<(QDataStream &out, const KDateTime::Spec &spec)
a local time which has a fixed offset from UTC.
Definition: kadatetime.h:157
SpecType
The time specification type of a KADateTime instance.
Definition: kadatetime.h:154
TimeFormat
Format for strings representing date/time values.
Definition: kadatetime.h:365
The full time specification of a KADateTime instance.
Definition: kadatetime.h:179
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sun Jun 20 2021 23:10:33 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.