KDELibs4Support

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

KDE's Doxygen guidelines are available online.