File indexing completed on 2023-09-24 04:04:47

 /*
     This file is part of the KDE libraries
     Copyright (c) 2005-2011 David Jarvie <djarvie@kde.org>
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Library General Public
     License as published by the Free Software Foundation; either
     version 2 of the License, or (at your option) any later version.
 
     This library is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     Library General Public License for more details.
 
     You should have received a copy of the GNU Library General Public License
     along with this library; see the file COPYING.LIB.  If not, write to
     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
     Boston, MA 02110-1301, USA.
 */
 
 /** @file
  * Date/times with associated time zone
  * @author David Jarvie <djarvie@kde.org>.
  */
 
 #ifndef _KDATETIME_H_
 #define _KDATETIME_H_
 
 #include <kdelibs4support_export.h>
 
 #include <QMetaType>
 #include <QSharedDataPointer>
 
 class QDataStream;
 class KDateTimePrivate;
 class KDateTimeSpecPrivate;
 class KTimeZone;
 class KTimeZones;
 
 /**
  * @short A class representing a date and time with an associated time zone
  *
  * Topics:
  *  - @ref intro
  *  - @ref manipulation
  *  - @ref compatibility
  *
  * @section intro Introduction
  *
  * The class KDateTime combines a date and time with support for an
  * associated time zone or UTC offset. When manipulating KDateTime objects,
  * their time zones or UTC offsets are automatically taken into account. KDateTime
  * can also be set to represent a date-only value with no associated time.
  *
  * The class uses QDateTime internally to represent date/time values, and
  * therefore uses the Gregorian calendar retroactively. If you need the Julian
  * calendar for historical dates (as commonly used prior to some date between 1582
  * and 1923 depending on nation), please use @c KCalendarSystem and related classes.
  *
  * The time specification types which KDateTime supports are:
  * - the UTC time zone
  * - a local time with a specified offset from UTC
  * - a local time in a specified time zone
  * - a local time using the current system time zone (a special case of the
  *   previous item)
  * - local clock time, using whatever the local system clock says on whichever
  *   computer it happens to be on. In this case, the equivalent UTC time will
  *   vary depending on system. As a result, calculations involving local clock
  *   times do not necessarily produce reliable results.
  *
  * These characteristics are more fully described in the description of the
  * SpecType enumeration. Also see
  * <a href="http://www.w3.org/TR/timezone/">W3C: Working with Time Zones</a>
  * for a good overview of the different ways of representing times.
  *
  * To set the time specification, use one of the setTimeSpec() methods, to get
  * the time specification, call timeSpec(), isUtc(), isLocalZone(),
  * isOffsetFromUtc() or isClockTime(). To determine whether two KDateTime
  * instances have the same time specification, call timeSpec() on each and
  * compare the returned values using KDateTime::Spec::operator==().
  *
  * @section manipulation Date and Time Manipulation
  *
  * A KDateTime object can be created by passing a date and time in its
  * constructor, together with a time specification.
  *
  * If both the date and time are null, isNull() returns true. If the date, time
  * and time specification are all valid, isValid() returns true.
  *
  * A KDateTime object can be converted to a different time specification by
  * using toUtc(), toLocalZone() or toClockTime(). It can be converted to a
  * specific time zone by toZone(). To return the time as an elapsed time since
  * 1 January 1970 (as used by time(2)), use toTime_t(). The results of time
  * zone conversions are cached to minimize the need for recalculation. Each
  * KDateTime object caches its UTC equivalent and the last time zone
  * conversion performed.
  *
  * The date and time can be set either in the constructor, or afterwards by
  * calling setDate(), setTime() or setDateTime(). To return the date and/or
  * time components of the KDateTime, use date(), time() and dateTime(). You
  * can determine whether the KDateTime represents a date and time, or a date
  * only, by isDateOnly(). You can change between a date and time or a date only
  * value using setDateOnly().
  *
  * You can increment or decrement the date/time using addSecs(), addDays(),
  * addMonths() and addYears(). The interval between two date/time values can
  * be found using secsTo() or daysTo().
  *
  * The comparison operators (operator==(), operator<(), etc.) all take the time
  * zone properly into account; if the two KDateTime objects have different time
  * zones, they are first converted to UTC before the comparison is
  * performed. An alternative to the comparison operators is compare() which will
  * in addition tell you if a KDateTime object overlaps with another when one or
  * both are date-only values.
  *
  * KDateTime values may be converted to and from a string representation using
  * the toString() and fromString() methods. These handle a variety of text
  * formats including ISO 8601 and RFC 2822.
  *
  * KDateTime uses Qt's facilities to implicitly share data. Copying instances
  * is very efficient, and copied instances share cached UTC and time zone
  * conversions even after the copy is performed. A separate copy of the data is
  * created whenever a non-const method is called. If you want to force the
  * creation of a separate copy of the data (e.g. if you want two copies to
  * cache different time zone conversions), call detach().
  *
  * @section compatibility QDateTime Considerations
  *
  * KDateTime's interface is designed to be as compatible as possible with that
  * of QDateTime, but with adjustments to cater for time zone handling. Because
  * QDateTime lacks virtual methods, KDateTime is not inherited from QDateTime,
  * but instead is implemented using a private QDateTime object.
  *
  * @section simulation Simulation Facility
  *
  * This class provides a facility to simulate the local system time, which
  * affects all functions using or returning the system time. This facility is
  * provided for testing purposes only, and is only available if the library is
  * compiled with debug enabled. In release mode, simulation is inoperative and
  * the real local system time is used at all times. Use
  * setSimulatedSystemTime() to set or clear the simulated time. To read the
  * real (not simulated) system time, use realCurrentLocalDateTime().
  *
  * @see KTimeZone, KSystemTimeZones, QDateTime, QDate, QTime
  * @see <a href="http://www.w3.org/TR/timezone/">W3C: Working with Time Zones</a>
  * @author David Jarvie \<djarvie@kde.org\>.
  */
 class KDELIBS4SUPPORT_EXPORT KDateTime //krazy:exclude=dpointer (implicitly shared)
 {
 public:
     /**
      * The time specification type of a KDateTime instance.
      * This specifies how the date/time component of the KDateTime instance
      * should be interpreted, i.e. what type of time zone (if any) the date/time
      * is expressed in. For the full time specification (including time zone
      * details), see KDateTime::Spec.
      */
     enum SpecType {
         Invalid,    /**< an invalid time specification. */
         UTC,        /**< a UTC time. */
         OffsetFromUTC, /**< a local time which has a fixed offset from UTC. */
         TimeZone,   /**< a time in a specified time zone. If the time zone is
                      *   the current system time zone (i.e. that returned by
                      *   KSystemTimeZones::local()), LocalZone may be used
                      *   instead.
                      */
         LocalZone,  /**< a time in the current system time zone.
                      *   When used to initialize a KDateTime or KDateTime::Spec
                      *   instance, this is simply a shorthand for calling the
                      *   setting method with a time zone parameter
                      *   KSystemTimeZones::local(). Note that if the system is
                      *   changed to a different time zone afterwards, the
                      *   KDateTime instance will still use the original system
                      *   time zone rather than adopting the new zone.
                      *   When returned by a method, it indicates that the time
                      *   zone stored in the instance is that currently returned
                      *   by KSystemTimeZones::local().
                      */
         ClockTime   /**< a clock time which ignores time zones and simply uses
                      *   whatever the local system clock says the time is. You
                      *   could, for example, set a wake-up time of 07:30 on
                      *   some date, and then no matter where you were in the
                      *   world, you would be in time for breakfast as long as
                      *   your computer was aligned with the local time.
                      *
                      *   Note that any calculations which involve clock times
                      *   cannot be guaranteed to be accurate, since by
                      *   definition they contain no information about time
                      *   zones or daylight savings changes.
                      */
     };
 
     /**
      * The full time specification of a KDateTime instance.
      * This specifies how the date/time component of the KDateTime instance
      * should be interpreted, i.e. which time zone (if any) the date/time is
      * expressed in.
      */
     class KDELIBS4SUPPORT_EXPORT Spec
     {
     public:
         /**
          * Constructs an invalid time specification.
          */
         Spec();
 
         /**
          * Constructs a time specification for a given time zone.
          * If @p tz is KTimeZone::utc(), the time specification type is set to @c UTC.
          *
          * @param tz  time zone
          */
         Spec(const KTimeZone &tz);   // allow implicit conversion
 
         /**
          * Constructs a time specification.
          *
          * @param type      time specification type, which should not be @c TimeZone
          * @param utcOffset number of seconds to add to UTC to get the local
          *                  time. Ignored if @p type is not @c OffsetFromUTC.
          */
         Spec(SpecType type, int utcOffset = 0);   // allow implicit conversion
 
         /**
          * Copy constructor.
          */
         Spec(const Spec &spec);
 
         /**
          * Assignment operator.
          */
         Spec &operator=(const Spec &spec);
 
         /**
          * Destructor
          */
         ~Spec();
 
         /**
          * Returns whether the time specification is valid.
          *
          * @return @c true if valid, else @c false
          */
         bool isValid() const;
 
         /**
          * Returns the time zone for the date/time, according to the time
          * specification type as follows:
          * - @c TimeZone  : the specified time zone is returned.
          * - @c UTC       : a UTC time zone is returned.
          * - @c LocalZone : the current local time zone is returned.
          *
          * @return time zone as defined above, or invalid in all other cases
          * @see isUtc(), isLocal()
          */
         KTimeZone timeZone() const;
 
         /**
          * Returns the time specification type, i.e. whether it is
          * UTC, has a time zone, etc. If the type is the local time zone,
          * @c TimeZone is returned; use isLocalZone() to check for the
          * local time zone.
          *
          * @return specification type
          * @see isLocalZone(), isClockTime(), isUtc(), timeZone()
          */
         SpecType type() const;
 
         /**
          * Returns whether the time specification is the current local
          * system time zone.
          *
          * @return @c true if local system time zone
          * @see isUtc(), isOffsetFromUtc(), timeZone()
          */
         bool isLocalZone() const;
 
         /**
          * Returns whether the time specification is a local clock time.
          *
          * @return @c true if local clock time
          * @see isUtc(), timeZone()
          */
         bool isClockTime() const;
 
         /**
          * Returns whether the time specification is a UTC time.
          * It is considered to be a UTC time if it is either type @c UTC,
          * or is type @c OffsetFromUTC with a zero UTC offset.
          *
          * @return @c true if UTC
          * @see isLocal(), isOffsetFromUtc(), timeZone()
          */
         bool isUtc() const;
 
         /**
          * Returns whether the time specification is a local time at a fixed
          * offset from UTC.
          *
          * @return @c true if local time at fixed offset from UTC
          * @see isLocal(), isUtc(), utcOffset()
          */
         bool isOffsetFromUtc() const;
 
         /**
          * Returns the UTC offset associated with the time specification. The
          * UTC offset is the number of seconds to add to UTC to get the local time.
          *
          * @return UTC offset in seconds if type is @c OffsetFromUTC, else 0
          * @see isOffsetFromUtc()
          */
         int utcOffset() const;
 
         /**
          * Initialises the time specification.
          *
          * @param type      the time specification type. Note that @c TimeZone
          *                  is invalid here.
          * @param utcOffset number of seconds to add to UTC to get the local
          *                  time. Ignored if @p spec is not @c OffsetFromUTC.
          * @see type(), setType(const KTimeZone&)
          */
         void setType(SpecType type, int utcOffset = 0);
 
         /**
          * Sets the time zone for the time specification.
          *
          * To set the time zone to the current local system time zone,
          * setType(LocalZone) may optionally be used instead.
          *
          * @param tz new time zone
          * @see timeZone(), setType(SpecType)
          */
         void setType(const KTimeZone &tz);
 
         /**
          * Comparison operator.
          *
          * @return @c true if the two instances are identical, @c false otherwise
          * @see equivalentTo()
          */
         bool operator==(const Spec &other) const;
 
         bool operator!=(const Spec &other) const
         {
             return !operator==(other);
         }
 
         /**
          * Checks whether this instance is equivalent to another.
          * The two instances are considered to be equivalent if any of the following
          * conditions apply:
          * - both instances are type @c ClockTime.
          * - both instances are type @c OffsetFromUTC and their offsets from UTC are equal.
          * - both instances are type @c TimeZone and their time zones are equal.
          * - both instances are UTC. An instance is considered to be UTC if it is
          *   either type @c UTC, or is type @c OffsetFromUTC with a zero UTC offset.
          *
          * @return @c true if the two instances are equivalent, @c false otherwise
          * @see operator==()
          */
         bool equivalentTo(const Spec &other) const;
 
         /**
          * The UTC time specification.
          * Provided as a shorthand for KDateTime::Spec(KDateTime::UTC).
          */
         static Spec UTC();
 
         /**
          * The ClockTime time specification.
          * Provided as a shorthand for KDateTime::Spec(KDateTime::ClockTime).
          */
         static Spec ClockTime();
 
         /**
          * Returns a UTC offset time specification.
          * Provided as a shorthand for KDateTime::Spec(KDateTime::OffsetFromUTC, utcOffset).
          *
          * @param utcOffset number of seconds to add to UTC to get the local time
          * @return UTC offset time specification
          */
         static Spec OffsetFromUTC(int utcOffset);
 
         /**
          * Returns a local time zone time specification.
          * Provided as a shorthand for KDateTime::Spec(KDateTime::LocalZone).
          *
          * @return Local zone time specification
          */
         static Spec LocalZone();
 
     private:
         KDateTimeSpecPrivate *const d;
     };
 
     /** Format for strings representing date/time values. */
     enum TimeFormat {
         ISODate,    /**< ISO 8601 format, i.e. [±]YYYY-MM-DDThh[:mm[:ss[.sss]]]TZ,
                      *   where TZ is the time zone offset (blank for local
                      *   time, Z for UTC, or ±hhmm for an offset from UTC).
                      *   When parsing a string, the ISO 8601 basic format,
                      *   [±]YYYYMMDDThh[mm[ss[.sss]]]TZ, is also accepted. For
                      *   date-only values, the formats [±]YYYY-MM-DD and
                      *   [±]YYYYMMDD (without time zone specifier) are used. All
                      *   formats may contain a day of the year instead of day
                      *   and month.
                      *   To allow for years past 9999, the year may optionally
                      *   contain more than 4 digits. To avoid ambiguity, this is
                      *   not allowed in the basic format containing a day
                      *   of the year (i.e. when the date part is [±]YYYYDDD).
                      */
         RFCDate,    /**< RFC 2822 format,
                      *   i.e. "[Wdy,] DD Mon YYYY hh:mm[:ss] ±hhmm". This format
                      *   also covers RFCs 822, 850, 1036 and 1123.
                      *   When parsing a string, it also accepts the format
                      *   "Wdy Mon DD HH:MM:SS YYYY" specified by RFCs 850 and
                      *   1036. There is no valid date-only format.
                      */
         RFCDateDay, /**< RFC 2822 format including day of the week,
                      *   i.e. "Wdy, DD Mon YYYY hh:mm:ss ±hhmm"
                      */
         QtTextDate, /**< Same format as Qt::TextDate (i.e. Day Mon DD hh:mm:ss YYYY)
                      *   with, if not local time, the UTC offset appended. The
                      *   time may be omitted to indicate a date-only value.
                      */
         LocalDate,  /**< Same format as Qt::LocalDate (i.e. locale dependent)
                      *   with, if not local time, the UTC offset appended. The
                      *   time may be omitted to indicate a date-only value.
                      */
         RFC3339Date /**< RFC 3339 format,
                      *   i.e. "YYYY-MM-DDThh:mm:ss[.sss](Z|±hh:mm)".
                      *   There is no valid date-only format.
                      */
 
     };
 
     /**
      * How this KDateTime compares with another.
      * If any date-only value is involved, comparison of KDateTime values
      * requires them to be considered as representing time periods. A date-only
      * instance represents a time period from 00:00:00 to 23:59:59.999 on a given
      * date, while a date/time instance can be considered to represent a time
      * period whose start and end times are the same. They may therefore be
      * earlier or later, or may overlap or be contained one within the other.
      *
      * Values may be OR'ed with each other in any combination of 'consecutive'
      * intervals to represent different types of relationship.
      *
      * In the descriptions of the values below,
      * - s1 = start time of this instance
      * - e1 = end time of this instance
      * - s2 = start time of other instance
      * - e2 = end time of other instance.
      */
     enum Comparison {
         Before  = 0x01, /**< This KDateTime is strictly earlier than the other,
                          *   i.e. e1 < s2.
                          */
         AtStart = 0x02, /**< This KDateTime starts at the same time as the other,
                          *   and ends before the end of the other,
                          *   i.e. s1 = s2, e1 < e2.
                          */
         Inside  = 0x04, /**< This KDateTime starts after the start of the other,
                          *   and ends before the end of the other,
                          *   i.e. s1 > s2, e1 < e2.
                          */
         AtEnd   = 0x08, /**< This KDateTime starts after the start of the other,
                          *   and ends at the same time as the other,
                          *   i.e. s1 > s2, e1 = e2.
                          */
         After   = 0x10, /**< This KDateTime is strictly later than the other,
                          *   i.e. s1 > e2.
                          */
         Equal = AtStart | Inside | AtEnd,
         /**< Simultaneous, i.e. s1 = s2 && e1 = e2.
          */
         Outside = Before | AtStart | Inside | AtEnd | After,
         /**< This KDateTime starts before the start of the other,
          *   and ends after the end of the other,
          *   i.e. s1 < s2, e1 > e2.
          */
         StartsAt = AtStart | Inside | AtEnd | After,
         /**< This KDateTime starts at the same time as the other,
          *   and ends after the end of the other,
          *   i.e. s1 = s2, e1 > e2.
          */
         EndsAt = Before | AtStart | Inside | AtEnd
                  /**< This KDateTime starts before the start of the other,
                   *   and ends at the same time as the other,
                   *   i.e. s1 < s2, e1 = e2.
                   */
     };
 
     /**
      * Constructs an invalid date/time.
      */
     KDateTime();
 
     /**
      * Constructs a date-only value expressed in a given time specification. The
      * time is set to 00:00:00.
      *
      * The instance is initialised according to the time specification type of
      * @p spec as follows:
      * - @c UTC           : date is stored as UTC.
      * - @c OffsetFromUTC : date is a local time at the specified offset
      *                      from UTC.
      * - @c TimeZone      : date is a local time in the specified time zone.
      * - @c LocalZone     : date is a local date in the current system time
      *                      zone.
      * - @c ClockTime     : time zones are ignored.
      *
      * @param date date in the time zone indicated by @p spec
      * @param spec time specification
      */
     KDELIBS4SUPPORT_DEPRECATED explicit KDateTime(const QDate &date, const Spec &spec = Spec(LocalZone));
 
     /**
      * Constructs a date/time expressed as specified by @p spec.
      *
      * @p date and @p time are interpreted and stored according to the value of
      * @p spec as follows:
      * - @c UTC           : @p date and @p time are in UTC.
      * - @c OffsetFromUTC : date/time is a local time at the specified offset
      *                      from UTC.
      * - @c TimeZone      : date/time is a local time in the specified time zone.
      * - @c LocalZone     : @p date and @p time are local times in the current
      *                      system time zone.
      * - @c ClockTime     : time zones are ignored.
      *
      * @param date date in the time zone indicated by @p spec
      * @param time time in the time zone indicated by @p spec
      * @param spec time specification
      */
     KDateTime(const QDate &date, const QTime &time, const Spec &spec = Spec(LocalZone));
 
     /**
      * Constructs a date/time expressed in a given time specification.
       *
      * @p dt is interpreted and stored according to the time specification type
      * of @p spec as follows:
      * - @c UTC           : @p dt is stored as a UTC value. If
      *                      @c dt.timeSpec() is @c Qt::LocalTime, @p dt is first
      *                      converted from the current system time zone to UTC
      *                      before storage.
      * - @c OffsetFromUTC : date/time is stored as a local time at the specified
      *                      offset from UTC. If @c dt.timeSpec() is @c Qt::UTC,
      *                      the time is adjusted by the UTC offset before
      *                      storage. If @c dt.timeSpec() is @c Qt::LocalTime,
      *                      it is assumed to be a local time at the specified
      *                      offset from UTC, and is stored without adjustment.
      * - @c TimeZone      : if @p dt is specified as a UTC time (i.e. @c dt.timeSpec()
      *                      is @c Qt::UTC), it is first converted to local time in
      *                      specified time zone before being stored.
      * - @c LocalZone     : @p dt is stored as a local time in the current system
      *                      time zone. If @c dt.timeSpec() is @c Qt::UTC, @p dt is
      *                      first converted to local time before storage.
      * - @c ClockTime     : If @c dt.timeSpec() is @c Qt::UTC, @p dt is first
      *                      converted to local time in the current system time zone
      *                      before storage. After storage, the time is treated as a
      *                      simple clock time, ignoring time zones.
      *
      * @param dt date and time
      * @param spec time specification
      */
     KDateTime(const QDateTime &dt, const Spec &spec);
 
     /**
      * Constructs a date/time from a QDateTime.
      * The KDateTime is expressed in either UTC or the local system time zone,
      * according to @p dt.timeSpec().
      *
      * @param dt date and time
      */
     KDELIBS4SUPPORT_DEPRECATED explicit KDateTime(const QDateTime &dt);
 
     KDateTime(const KDateTime &other);
     ~KDateTime();
 
     KDateTime &operator=(const KDateTime &other);
 
     /**
      * Returns whether the date/time is null.
      *
      * @return @c true if both date and time are null, else @c false
      * @see isValid(), QDateTime::isNull()
      */
     bool isNull() const;
 
     /**
      * Returns whether the date/time is valid.
      *
      * @return @c true if both date and time are valid, else @c false
      * @see isNull(), QDateTime::isValid()
      */
     bool isValid() const;
 
     /**
      * Returns whether the instance represents a date/time or a date-only value.
      *
      * @return @c true if date-only, @c false if date and time
      */
     bool isDateOnly() const;
 
     /**
      * Returns the date part of the date/time. The value returned should be
      * interpreted in terms of the instance's time zone or UTC offset.
      *
      * @return date value
      * @see time(), dateTime()
      */
     QDate date() const;
 
     /**
      * Returns the time part of the date/time. The value returned should be
      * interpreted in terms of the instance's time zone or UTC offset. If
      * the instance is date-only, the time returned is 00:00:00.
      *
      * @return time value
      * @see date(), dateTime(), isDateOnly()
      */
     QTime time() const;
 
     /**
      * Returns the date/time component of the instance, ignoring the time
      * zone. The value returned should be interpreted in terms of the
      * instance's time zone or UTC offset. The returned value's @c timeSpec()
      * value will be @c Qt::UTC if the instance is a UTC time, else
      * @c Qt::LocalTime. If the instance is date-only, the time value is set to
      * 00:00:00.
      *
      * @return date/time
      * @see date(), time()
      */
     QDateTime dateTime() const;
 
     /**
      * Returns the time zone for the date/time. If the date/time is specified
      * as a UTC time, a UTC time zone is always returned.
      *
      * @return time zone, or invalid if a local time at a fixed UTC offset or a
      *         local clock time
      * @see isUtc(), isLocal()
      */
     KTimeZone timeZone() const;
 
     /**
      * Returns the time specification of the date/time, i.e. whether it is
      * UTC, what time zone it is, etc.
      *
      * @return time specification
      * @see isLocalZone(), isClockTime(), isUtc(), timeZone()
      */
     Spec timeSpec() const;
 
     /**
      * Returns the time specification type of the date/time, i.e. whether it is
      * UTC, has a time zone, etc. If the type is the local time zone,
      * @c TimeZone is returned; use isLocalZone() to check for the local time
      * zone.
      *
      * @return specification type
      * @see timeSpec(), isLocalZone(), isClockTime(), isUtc(), timeZone()
      */
     SpecType timeType() const;
 
     /**
      * Returns whether the time zone for the date/time is the current local
      * system time zone.
      *
      * @return @c true if local system time zone
      * @see isUtc(), isOffsetFromUtc(), timeZone()
      */
     bool isLocalZone() const;
 
     /**
      * Returns whether the date/time is a local clock time.
      *
      * @return @c true if local clock time
      * @see isUtc(), timeZone()
      */
     bool isClockTime() const;
 
     /**
      * Returns whether the date/time is a UTC time.
      * It is considered to be a UTC time if it either has a UTC time
      * specification (SpecType == UTC), or has a zero offset from UTC
      * (SpecType == OffsetFromUTC with zero UTC offset).
      *
      * @return @c true if UTC
      * @see isLocal(), isOffsetFromUtc(), timeZone()
      */
     bool isUtc() const;
 
     /**
      * Returns whether the date/time is a local time at a fixed offset from
      * UTC.
      *
      * @return @c true if local time at fixed offset from UTC
      * @see isLocal(), isUtc(), utcOffset()
      */
     bool isOffsetFromUtc() const;
 
     /**
      * Returns the UTC offset associated with the date/time. The UTC offset is
      * the number of seconds to add to UTC to get the local time.
      *
      * @return UTC offset in seconds, or 0 if local clock time
      * @see isClockTime()
      */
     int utcOffset() const;
 
     /**
      * Returns whether the date/time is the second occurrence of this time. This
      * is only applicable to a date/time expressed in terms of a time zone (type
      * @c TimeZone or @c LocalZone), around the time of change from daylight
      * savings to standard time.
      *
      * When a shift from daylight savings time to standard time occurs, the local
      * times (typically the previous hour) immediately preceding the shift occur
      * twice. For example, if a time shift of 1 hour happens at 03:00, the clock
      * jumps backwards to 02:00, so the local times between 02:00:00 and 02:59:59
      * occur once before the shift, and again after the shift.
      *
      * For instances which are not of type @c TimeZone, or when the date/time is
      * not near to a time shift, @c false is returned.
      *
      * @return @c true if the time is the second occurrence, @c false otherwise
      * @see setSecondOccurrence()
      */
     bool isSecondOccurrence() const;
 
     /**
      * Returns the time converted to UTC. The converted time has a UTC offset
      * of zero.
      * If the instance is a local clock time, it is first set to the local time
      * zone, and then converted to UTC.
      * If the instance is a date-only value, a date-only UTC value is returned,
      * with the date unchanged.
      *
      * @return converted time
      * @see toOffsetFromUtc(), toLocalZone(), toZone(), toTimeSpec(), toTime_t(), KTimeZone::convert()
      */
     KDateTime toUtc() const;
 
     /**
      * Returns the time expressed as an offset from UTC, using the UTC offset
      * associated with this instance's date/time. The date and time
      * components are unchanged. For example, 14:15 on 12 Jan 2001, US Eastern
      * time zone would return a KDateTime value of 14:15 on 12 Jan 2001 with a
      * UTC offset of -18000 seconds (i.e. -5 hours).
      *
      * If the instance is a local clock time, the offset is set to that of the
      * local time zone.
      * If the instance is a date-only value, the offset is set to that at the
      * start of the day.
      *
      * @return converted time
      * @see toUtc(), toOffsetFromUtc(int), toLocalZone(), toZone(), toTimeSpec(), toTime_t(), KTimeZone::convert()
      */
     KDateTime toOffsetFromUtc() const;
 
     /**
      * Returns the time expressed as a specified offset from UTC.
      *
      * If the instance is a local clock time, it is first set to the local time
      * zone, and then converted to the UTC offset.
      * If the instance is a date-only value, a date-only clock time value is
      * returned, with the date unchanged.
      *
      * @param utcOffset number of seconds to add to UTC to get the local time.
      * @return converted time
      * @see toUtc(), toOffsetFromUtc(), toLocalZone(), toZone(), toTimeSpec(), toTime_t(), KTimeZone::convert()
      */
     KDateTime toOffsetFromUtc(int utcOffset) const;
 
     /**
      * Returns the time converted to the current local system time zone.
      * If the instance is a date-only value, a date-only local time zone value
      * is returned, with the date unchanged.
      *
      * @return converted time
      * @see toUtc(), toOffsetFromUtc(), toZone(), toTimeSpec(), KTimeZone::convert()
      */
     KDateTime toLocalZone() const;
 
     /**
      * Returns the time converted to the local clock time. The time is first
      * converted to the local system time zone before setting its type to
      * ClockTime, i.e. no associated time zone.
      * If the instance is a date-only value, a date-only clock time value is
      * returned, with the date unchanged.
      *
      * @return converted time
      * @see toLocalZone(), toTimeSpec()
      */
     KDateTime toClockTime() const;
 
     /**
      * Returns the time converted to a specified time zone.
      * If the instance is a local clock time, it is first set to the local time
      * zone, and then converted to @p zone.
      * If the instance is a date-only value, a date-only value in @p zone is
      * returned, with the date unchanged.
      *
      * @param zone time zone to convert to
      * @return converted time
      * @see toUtc(), toOffsetFromUtc(), toLocalZone(), toTimeSpec(), KTimeZone::convert()
      */
     KDateTime toZone(const KTimeZone &zone) const;
 
     /**
      * Returns the time converted to a new time specification.
      * If the instance is a local clock time, it is first set to the local time
      * zone, and then converted to the @p spec time specification.
      * If the instance is a date-only value, a date-only value is returned,
      * with the date unchanged.
      *
      * @param spec new time specification
      * @return converted time
      * @see toLocalZone(), toUtc(), toOffsetFromUtc(), toZone(), KTimeZone::convert()
      */
     KDateTime toTimeSpec(const Spec &spec) const;
 
     /**
      * Returns the time converted to the time specification of another instance.
      * If this instance is a local clock time, it is first set to the local time
      * zone, and then converted to the @p spec time specification.
      * If this instance is a date-only value, a date-only value is returned,
      * with the date unchanged.
      *
      * @param dt instance providing the new time specification
      * @return converted time
      * @see toLocalZone(), toUtc(), toOffsetFromUtc(), toZone(), KTimeZone::convert()
      */
     KDateTime toTimeSpec(const KDateTime &dt) const;
 
     /**
      * Converts the time to a UTC time, measured in seconds since 00:00:00 UTC
      * 1st January 1970 (as returned by time(2)).
      *
      * @return converted time, or @c uint(-1) if the date is out of range or invalid
      * @see setTime_t()
      */
     uint toTime_t() const;
 
     /**
      * Sets the time to a UTC time, specified as seconds since 00:00:00 UTC
      * 1st January 1970 (as returned by time(2)).
      *
      * @param seconds number of seconds since 00:00:00 UTC 1st January 1970
      * @see toTime_t()
      */
     void setTime_t(qint64 seconds);
 
     /**
      * Sets the instance either to being a date and time value, or a date-only
      * value. If its status is changed to date-only, its time is set to
      * 00:00:00.
      *
      * @param dateOnly @c true to set to date-only, @c false to set to date
      *                 and time.
      * @see isDateOnly(), setTime()
      */
     void setDateOnly(bool dateOnly);
 
     /**
      * Sets the date part of the date/time.
      *
      * @param date new date value
      * @see date(), setTime(), setTimeSpec(), setTime_t(), setDateOnly()
      */
     void setDate(const QDate &date);
 
     /**
      * Sets the time part of the date/time. If the instance was date-only, it
      * is changed to being a date and time value.
      *
      * @param time new time value
      * @see time(), setDate(), setTimeSpec(), setTime_t()
      */
     void setTime(const QTime &time);
 
     /**
      * Sets the date/time part of the instance, leaving the time specification
      * unaffected.
      *
      * If @p dt is a local time (\code dt.timeSpec() == Qt::LocalTime \endcode)
      * and the instance is UTC, @p dt is first converted from the current
      * system time zone to UTC before being stored.
      *
      * If the instance was date-only, it is changed to being a date and time
      * value.
      *
      * @param dt date and time
      * @see dateTime(), setDate(), setTime(), setTimeSpec()
      */
     void setDateTime(const QDateTime &dt);
 
     /**
      * Changes the time specification of the instance.
      *
      * Any previous time zone is forgotten. The stored date/time component of
      * the instance is left unchanged (except that its UTC/local time setting
      * is set to correspond with @p spec). Usually this method will change the
      * absolute time which this instance represents.
      *
      * @param spec new time specification
      * @see timeSpec(), timeZone()
      */
     void setTimeSpec(const Spec &spec);
 
     /**
      * Sets whether the date/time is the second occurrence of this time. This
      * is only applicable to a date/time expressed in terms of a time zone (type
      * @c TimeZone or @c LocalZone), around the time of change from daylight
      * savings to standard time.
      *
      * When a shift from daylight savings time to standard time occurs, the local
      * times (typically the previous hour) immediately preceding the shift occur
      * twice. For example, if a time shift of 1 hour happens at 03:00, the clock
      * jumps backwards to 02:00, so the local times between 02:00:00 and 02:59:59
      * occur once before the shift, and again after the shift.
      *
      * For instances which are not of type @c TimeZone, or when the date/time is
      * not near to a time shift, calling this method has no effect.
      *
      * Note that most other setting methods clear the second occurrence indicator,
      * so if you want to retain its setting, you must call setSecondOccurrence()
      * again after changing the instance's value.
      *
      * @param second @c true to set as the second occurrence, @c false to set as
      *               the first occurrence
      * @see isSecondOccurrence()
      */
     void setSecondOccurrence(bool second);
 
     /**
      * Returns a date/time @p msecs milliseconds later than the stored date/time.
      *
      * Except when the instance is a local clock time (type @c ClockTime), the
      * calculation is done in UTC to ensure that the result takes proper account
      * of clock changes (e.g. daylight savings) in the time zone. The result is
      * expressed using the same time specification as the original instance.
      *
      * Note that if the instance is a local clock time (type @c ClockTime), any
      * daylight savings changes or time zone changes during the period will
      * render the result inaccurate.
      *
      * If the instance is date-only, @p msecs is rounded down to a whole number
      * of days and that value is added to the date to find the result.
      *
      * @return resultant date/time
      * @see addSecs(), addDays(), addMonths(), addYears(), secsTo()
      */
     KDateTime addMSecs(qint64 msecs) const;
 
     /**
      * Returns a date/time @p secs seconds later than the stored date/time.
      *
      * Except when the instance is a local clock time (type @c ClockTime), the
      * calculation is done in UTC to ensure that the result takes proper account
      * of clock changes (e.g. daylight savings) in the time zone. The result is
      * expressed using the same time specification as the original instance.
      *
      * Note that if the instance is a local clock time (type @c ClockTime), any
      * daylight savings changes or time zone changes during the period will
      * render the result inaccurate.
      *
      * If the instance is date-only, @p secs is rounded down to a whole number
      * of days and that value is added to the date to find the result.
      *
      * @return resultant date/time
      * @see addMSecs(), addDays(), addMonths(), addYears(), secsTo()
      */
     KDateTime addSecs(qint64 secs) const;
 
     /**
      * Returns a date/time @p days days later than the stored date/time.
      * The result is expressed using the same time specification as the
      * original instance.
      *
      * Note that if the instance is a local clock time (type @c ClockTime), any
      * daylight savings changes or time zone changes during the period may
      * render the result inaccurate.
      *
      * @return resultant date/time
      * @see addSecs(), addMonths(), addYears(), daysTo()
      */
     KDateTime addDays(qint64 days) const;
 
     /**
      * Returns a date/time @p months months later than the stored date/time.
      * The result is expressed using the same time specification as the
      * original instance.
      *
      * Note that if the instance is a local clock time (type @c ClockTime), any
      * daylight savings changes or time zone changes during the period may
      * render the result inaccurate.
      *
      * @return resultant date/time
      * @see addSecs(), addDays(), addYears(), daysTo()
      */
     KDateTime addMonths(int months) const;
 
     /**
      * Returns a date/time @p years years later than the stored date/time.
      * The result is expressed using the same time specification as the
      * original instance.
      *
      * Note that if the instance is a local clock time (type @c ClockTime), any
      * daylight savings changes or time zone changes during the period may
      * render the result inaccurate.
      *
      * @return resultant date/time
      * @see addSecs(), addDays(), addMonths(), daysTo()
      */
     KDateTime addYears(int years) const;
 
     /**
      * Returns the number of seconds from this date/time to the @p other date/time.
      *
      * Before performing the comparison, the two date/times are converted to UTC
      * to ensure that the result is correct if one of the two date/times has
      * daylight saving time (DST) and the other doesn't. The exception is when
      * both instances are local clock time, in which case no conversion to UTC
      * is done.
      *
      * Note that if either instance is a local clock time (type @c ClockTime),
      * the result cannot be guaranteed to be accurate, since by definition they
      * contain no information about time zones or daylight savings changes.
      *
      * If one instance is date-only and the other is date-time, the date-time
      * value is first converted to the same time specification as the date-only
      * value, and the result is the difference in days between the resultant
      * date and the date-only date.
      *
      * If both instances are date-only, the result is the difference in days
      * between the two dates, ignoring time zones.
      *
      * @param other other date/time
      * @return number of seconds difference
      * @see addSecs(), daysTo()
      */
     qint64 secsTo(const KDateTime &other) const;
 
     /**
      * @deprecated Since 5.0, use @c secsTo instead
      *
      * Returns the number of seconds from this date/time to the @p other date/time.
      *
      * Before performing the comparison, the two date/times are converted to UTC
      * to ensure that the result is correct if one of the two date/times has
      * daylight saving time (DST) and the other doesn't. The exception is when
      * both instances are local clock time, in which case no conversion to UTC
      * is done.
      *
      * Note that if either instance is a local clock time (type @c ClockTime),
      * the result cannot be guaranteed to be accurate, since by definition they
      * contain no information about time zones or daylight savings changes.
      *
      * If one instance is date-only and the other is date-time, the date-time
      * value is first converted to the same time specification as the date-only
      * value, and the result is the difference in days between the resultant
      * date and the date-only date.
      *
      * If both instances are date-only, the result is the difference in days
      * between the two dates, ignoring time zones.
      *
      * @param other other date/time
      * @return number of seconds difference
      * @see secsTo(), addSecs(), daysTo()
      */
 #ifndef KDELIBS4SUPPORT_NO_DEPRECATED
     KDELIBS4SUPPORT_DEPRECATED inline qint64 secsTo_long(const KDateTime &other) const
     {
         return secsTo(other);
     }
 #endif
 
     /**
      * Calculates the number of days from this date/time to the @p other date/time.
      * In calculating the result, @p other is first converted to this instance's
      * time zone. The number of days difference is then calculated ignoring
      * the time parts of the two date/times. For example, if this date/time
      * was 13:00 on 1 January 2000, and @p other was 02:00 on 2 January 2000,
      * the result would be 1.
      *
      * Note that if either instance is a local clock time (type @c ClockTime),
      * the result cannot be guaranteed to be accurate, since by definition they
      * contain no information about time zones or daylight savings changes.
      *
      * If one instance is date-only and the other is date-time, the date-time
      * value is first converted to the same time specification as the date-only
      * value, and the result is the difference in days between the resultant
      * date and the date-only date.
      *
      * If both instances are date-only, the calculation ignores time zones.
      *
      * @param other other date/time
      * @return number of days difference
      * @see secsTo(), addDays()
      */
     qint64 daysTo(const KDateTime &other) const;
 
     /**
      * Returns the current date and time, as reported by the system clock,
      * expressed in the local system time zone.
      *
      * @return current date/time
      * @see currentUtcDateTime(), currentDateTime()
      */
     static KDateTime currentLocalDateTime();
 
     /**
      * Returns the current date and time, as reported by the system clock,
      * expressed in UTC.
      *
      * @return current date/time
      * @see currentLocalDateTime(), currentDateTime(), currentLocalDate(), currentLocalTime()
      */
     static KDateTime currentUtcDateTime();
 
     /**
      * Returns the current date and time, as reported by the system clock,
      * expressed in a given time specification.
      *
      * @note To fetch the current date and time expressed in UTC or in the local
      * system time zone, it is more efficient to use currentUtcDateTime() or
      * currentLocalDateTime().
      *
      * @param spec time specification
      * @return current date/time
      * @see currentUtcDateTime(), currentLocalDateTime()
      */
     static KDateTime currentDateTime(const Spec &spec);
 
     /**
      * Returns the current date in the local time zone, as reported by the
      * system clock.
      *
      * @return current date
      * @see currentLocalDateTime(), currentLocalTime()
      * @since 4.3
      */
     static QDate currentLocalDate();
 
     /**
      * Returns the current time of day in the local time zone, as reported
      * by the system clock.
      *
      * @return current date
      * @see currentLocalDateTime(), currentLocalDate()
      * @since 4.3
      */
     static QTime currentLocalTime();
 
     /**
      * Returns the date/time as a string. The @p format parameter determines the
      * format of the result string. The @p format codes used for the date and time
      * components follow those used elsewhere in KDE, and are similar but not
      * identical to those used by strftime(3). Conversion specifiers are
      * introduced by a '\%' character, and are replaced in @p format as follows:
      *
      * \b Date
      *
      * - \%y   2-digit year excluding century (00 - 99). Conversion is undefined
      *         if year < 0.
      * - \%Y   full year number
      * -  %:m  month number, without leading zero (1 - 12)
      * - \%m   month number, 2 digits (01 - 12)
      * - \%b   abbreviated month name in current locale
      * - \%B   full month name in current locale
      * -  %:b  abbreviated month name in English (Jan, Feb, ...)
      * -  %:B  full month name in English
      * - \%e   day of the month (1 - 31)
      * - \%d   day of the month, 2 digits (01 - 31)
      * - \%a   abbreviated weekday name in current locale
      * - \%A   full weekday name in current locale
      * -  %:a  abbreviated weekday name in English (Mon, Tue, ...)
      * -  %:A  full weekday name in English
      *
      * \b Time
      *
      * - \%H   hour in the 24 hour clock, 2 digits (00 - 23)
      * - \%k   hour in the 24 hour clock, without leading zero (0 - 23)
      * - \%I   hour in the 12 hour clock, 2 digits (01 - 12)
      * - \%l   hour in the 12 hour clock, without leading zero (1 - 12)
      * - \%M   minute, 2 digits (00 - 59)
      * - \%S   seconds (00 - 59)
      * -  %:S  seconds preceded with ':', but omitted if seconds value is zero
      * -  %:s  milliseconds, 3 digits (000 - 999)
      * - \%P   "am" or "pm" in the current locale, or if undefined there, in English
      * - \%p   "AM" or "PM" in the current locale, or if undefined there, in English
      * -  %:P  "am" or "pm"
      * -  %:p  "AM" or "PM"
      *
      * \b Time zone
      *
      * -  %:u  UTC offset of the time zone in hours, e.g. -02. If the offset
      *         is not a whole number of hours, the output is the same as for '\%U'.
      * - \%z   UTC offset of the time zone in hours and minutes, e.g. -0200.
      * -  %:z  UTC offset of the time zone in hours and minutes, e.g. +02:00.
      * - \%Z   time zone abbreviation, e.g. UTC, EDT, GMT. This is not guaranteed
      *         to be unique among different time zones. If not applicable (i.e. if
      *         the instance is type OffsetFromUTC), the UTC offset is substituted.
      * -  %:Z  time zone name, e.g. Europe/London. This is system dependent. If
      *         not applicable (i.e. if the instance is type OffsetFromUTC), the
      *         UTC offset is substituted.
      *
      * \b Other
      *
      * -  %%   literal '\%' character
      *
      * Note that if the instance has a time specification of ClockTime, the
      * time zone or UTC offset in the result will be blank.
      *
      * If you want to use the current locale's date format, you should call
      * KLocale::formatDate() to format the date part of the KDateTime.
      *
      * @param format format for the string
      * @return formatted string
      * @see fromString(), KLocale::formatDate()
      */
     QString toString(const QString &format) const;
 
     /**
      * Returns the date/time as a string, formatted according to the @p format
      * parameter, with the UTC offset appended.
      *
      * Note that if the instance has a time specification of ClockTime, the UTC
      * offset in the result will be blank, except for RFC 2822 and RFC 3339
      * formats in which it will be the offset for the local system time zone.
      *
      * If the instance is date-only, the time will when @p format permits be
      * omitted from the output string. This applies to @p format = QtTextDate
      * or LocalDate. It also applies to @p format = ISODate when the instance
      * has a time specification of ClockTime. For all other cases, a time of
      * 00:00:00 will be output.
      *
      * For RFC 2822 format, set @p format to RFCDateDay to include the day
      * of the week, or to RFCDate to omit it.
      *
      * @param format format for output string
      * @return formatted string
      * @see fromString(), QDateTime::toString()
      */
     QString toString(TimeFormat format = ISODate) const;
 
     /**
      * Returns the KDateTime represented by @p string, using the @p format given.
      *
      * This method is the inverse of toString(TimeFormat), except that it can
      * only return a time specification of UTC, OffsetFromUTC or ClockTime. An
      * actual named time zone cannot be returned since an offset from UTC only
      * partially specifies a time zone.
      *
      * The time specification of the result is determined by the UTC offset
      * present in the string:
      * - if the UTC offset is zero the result is type @c UTC.
      * - if the UTC offset is non-zero, the result is type @c OffsetFromUTC.
      * - if there is no UTC offset (when @p format permits this), the result is
      *   by default type @c ClockTime. You can use setFromStringDefault() to
      *   change this default.
      *
      * If no time is found in @p string, a date-only value is returned, except
      * when the specified @p format does not permit the time to be omitted, in
      * which case an error is returned. An error is therefore returned for
      * ISODate when @p string includes a time zone specification, and for
      * RFCDate in all cases.
      *
      * For RFC format strings (not RFC 3339), you should normally set @p format
      * to RFCDate. Only set it to RFCDateDay if you want to return an error
      * when the day of the week is omitted.
      *
      * @param string string to convert
      * @param format format code. LocalDate cannot be used here.
      * @param negZero if non-null, the value is set to true if a UTC offset of
      *                '-0000' is found or, for RFC 2822 format, an unrecognised
      *                or invalid time zone abbreviation is found, else false.
      * @return KDateTime value, or an invalid KDateTime if either parameter is invalid
      * @see setFromStringDefault(), toString(), QString::fromString()
      */
     static KDateTime fromString(const QString &string, TimeFormat format = ISODate, bool *negZero = nullptr);
 
     /**
      * Returns the KDateTime represented by @p string, using the @p format
      * given, optionally using a time zone collection @p zones as the source of
      * time zone definitions. The @p format codes are basically the same as
      * those for toString(), and are similar but not identical to those used by
      * strftime(3).
      *
      * The @p format string consists of the same codes as that for
      * toString(). However, some codes which are distinct in toString() have
      * the same function as each other here.
      *
      * Numeric values without a stated number of digits permit, but do not
      * require, leading zeroes. The maximum number of digits consumed by a
      * numeric code is the minimum needed to cover the possible range of the
      * number (e.g. for minutes, the range is 0 - 59, so the maximum number of
      * digits consumed is 2). All non-numeric values are case insensitive.
      *
      * \b Date
      *
      * - \%y   year excluding century (0 - 99). Years 0 - 50 return 2000 - 2050,
      *         while years 51 - 99 return 1951 - 1999.
      * - \%Y   full year number (4 digits with optional sign)
      * -  %:Y  full year number (>= 4 digits with optional sign)
      * -  %:m  month number (1 - 12)
      * - \%m   month number, 2 digits (01 - 12)
      * - \%b
      * - \%B   month name in the current locale or, if no match, in English,
      *         abbreviated or in full
      * -  %:b
      * -  %:B  month name in English, abbreviated or in full
      * - \%e   day of the month (1 - 31)
      * - \%d   day of the month, 2 digits (01 - 31)
      * - \%a
      * - \%A   weekday name in the current locale or, if no match, in English,
      *         abbreviated or in full
      * -  %:a
      * -  %:A  weekday name in English, abbreviated or in full
      *
      * \b Time
      *
      * - \%H   hour in the 24 hour clock, 2 digits (00 - 23)
      * - \%k   hour in the 24 hour clock (0 - 23)
      * - \%I   hour in the 12 hour clock, 2 digits (01 - 12)
      * - \%l   hour in the 12 hour clock (1 - 12)
      * - \%M   minute, 2 digits (00 - 59)
      * -  %:M  minute (0 - 59)
      * - \%S   seconds, 2 digits (00 - 59)
      * - \%s   seconds (0 - 59)
      * -  %:S  optional seconds value (0 - 59) preceded with ':'. If no colon is
      *         found in @p string, no input is consumed and the seconds value is
      *         set to zero.
      * -  %:s  fractional seconds value, preceded with a decimal point (either '.'
      *         or the locale's decimal point symbol)
      * - \%P
      * - \%p   "am" or "pm", in the current locale or, if no match, in
      *         English. This format is only useful when used with \%I or \%l.
      * -  %:P
      * -  %:p  "am" or "pm" in English. This format is only useful when used with
      *         \%I or \%l.
      *
      * \b Time zone
      *
      * -  %:u
      * - \%z   UTC offset of the time zone in hours and optionally minutes,
      *         e.g. -02, -0200.
      * -  %:z  UTC offset of the time zone in hours and minutes, colon separated,
      *         e.g. +02:00.
      * - \%Z   time zone abbreviation, consisting of alphanumeric characters,
      *         e.g. UTC, EDT, GMT.
      * -  %:Z  time zone name, e.g. Europe/London. The name may contain any
      *         characters and is delimited by the following character in the
      *         @p format string. It will not work if you follow %:Z with another
      *         escape sequence (except %% or \%t).
      *
      * \b Other
      *
      * - \%t   matches one or more whitespace characters
      * -  %%   literal '\%' character
      *
      * Any other character must have a matching character in @p string, except
      * that a space will match zero or more whitespace characters in the input
      * string.
      *
      * If any time zone information is present in the string, the function
      * attempts to find a matching time zone in the @p zones collection. A time
      * zone name (format code %:Z) will provide an unambiguous look up in
      * @p zones. Any other type of time zone information (an abbreviated time
      * zone code (\%Z) or UTC offset (\%z, %:z, %:u) is searched for in @p zones
      * and if only one time zone is found to match, the result is set to that
      * zone. Otherwise:
      * - If more than one match of a UTC offset is found, the action taken is
      *   determined by @p offsetIfAmbiguous: if @p offsetIfAmbiguous is true,
      *   a local time with an offset from UTC (type @c OffsetFromUTC) will be
      *   returned; if false an invalid KDateTime is returned.
      * - If more than one match of a time zone abbreviation is found, the UTC
      *   offset for each matching time zone is compared and, if the offsets are
      *   the same, a local time with an offset from UTC (type @c OffsetFromUTC)
      *   will be returned provided that @p offsetIfAmbiguous is true. Otherwise
      *   an invalid KDateTime is returned.
      * - If a time zone abbreviation does not match any time zone in @p zones,
      *   or the abbreviation does not apply at the parsed date/time, an
      *   invalid KDateTime is returned.
      * - If a time zone name does not match any time zone in @p zones, an
      *   invalid KDateTime is returned.
      * - If the time zone UTC offset does not match any time zone in @p zones,
      *   a local time with an offset from UTC (type @c OffsetFromUTC) is
      *   returned.
      * If @p format contains more than one time zone or UTC offset code, an
      * error is returned.
      *
      * If no time zone information is present in the string, by default a local
      * clock time (type @c ClockTime) is returned. You can use
      * setFromStringDefault() to change this default.
      *
      * If no time is found in @p string, a date-only value is returned.
      *
      * If any inconsistencies are found, i.e. the same item of information
      * appears more than once but with different values, the weekday name does
      * not tally with the date, an invalid KDateTime is returned.
      *
      * @param string string to convert
      * @param format format string
      * @param zones time zone collection, or null for none
      * @param offsetIfAmbiguous specifies what to do if more than one zone
      *                          matches the UTC offset found in the
      *                          string. Ignored if @p zones is null.
      * @return KDateTime value, or an invalid KDateTime if an error occurs, if
      *         time zone information doesn't match any in @p zones, or if the
      *         time zone information is ambiguous and @p offsetIfAmbiguous is
      *         false
      * @see setFromStringDefault(), toString()
      */
     static KDateTime fromString(const QString &string, const QString &format,
                                 const KTimeZones *zones = nullptr, bool offsetIfAmbiguous = true);
 
     /**
      * Sets the default time specification for use by fromString() when no time
      * zone or UTC offset is found in the string being parsed, or when "-0000"
      * is found in an RFC 2822 string.
      *
      * By default, fromString() returns a local clock time (type @c ClockTime)
      * when no definite zone or UTC offset is found. You can use this method
      * to make it return the local time zone, UTC, or whatever you wish.
      *
      * @param spec the new default time specification
      * @see fromString()
      */
     static void setFromStringDefault(const Spec &spec);
 
     /**
      * Always returns false, as dates earlier than -4712 are now supported by
      * @c KDateTime.
      *
      * @return @c false
      * @see isValid()
      * @deprecated Since 5.0, we now supports all valid dates.
      */
 #ifndef KDELIBS4SUPPORT_NO_DEPRECATED
     KDELIBS4SUPPORT_DEPRECATED inline bool outOfRange() const
     {
         return false;
     }
 #endif
 
     /**
      * Compare this instance with another to determine whether they are
      * simultaneous, earlier or later, and in the case of date-only values,
      * whether they overlap (i.e. partly coincide but are not wholly
      * simultaneous).
      * The comparison takes time zones into account: if the two instances have
      * different time zones, they are first converted to UTC before comparing.
      *
      * If both instances are date/time values, this instance is considered to
      * be either simultaneous, earlier or later, and does not overlap.
      *
      * If one instance is date-only and the other is a date/time, this instance
      * is either strictly earlier, strictly later, or overlaps.
      *
      * If both instance are date-only, they are considered simultaneous if both
      * their start of day and end of day times are simultaneous with each
      * other. (Both start and end of day times need to be considered in case a
      * daylight savings change occurs during that day.) Otherwise, this instance
      * can be strictly earlier, earlier but overlapping, later but overlapping,
      * or strictly later.
      *
      * Note that if either instance is a local clock time (type @c ClockTime),
      * the result cannot be guaranteed to be correct, since by definition they
      * contain no information about time zones or daylight savings changes.
      *
      * @return @c true if the two instances represent the same time, @c false otherwise
      * @see operator==(), operator!=(), operator<(), operator<=(), operator>=(), operator>()
      */
     Comparison compare(const KDateTime &other) const;
 
     /**
      * Check whether this date/time is simultaneous with another.
      * The comparison takes time zones into account: if the two instances have
      * different time zones, they are first converted to UTC before comparing.
      *
      * Note that if either instance is a local clock time (type @c ClockTime),
      * the result cannot be guaranteed to be correct, since by definition they
      * contain no information about time zones or daylight savings changes.
      *
      * If one instance is date-only and the other is date/time, they are
      * considered unequal.
      *
      * If both instances are date-only, they are considered simultaneous if both
      * their start of day and end of day times are simultaneous with each
      * other. (Both start and end of day times need to be considered in case a
      * daylight saving change occurs during that day.)
      *
      * @return @c true if the two instances represent the same time, @c false otherwise
      * @see compare()
      */
     bool operator==(const KDateTime &other) const;
 
     bool operator!=(const KDateTime &other) const
     {
         return !(*this == other);
     }
 
     /**
      * Check whether this date/time is earlier than another.
      * The comparison takes time zones into account: if the two instances have
      * different time zones, they are first converted to UTC before comparing.
      *
      * Note that if either instance is a local clock time (type @c ClockTime),
      * the result cannot be guaranteed to be correct, since by definition they
      * contain no information about time zones or daylight savings changes.
      *
      * If one or both instances are date-only, the comparison returns true if
      * this date/time or day, falls wholly before the other date/time or
      * day. To achieve this, the time used in the comparison is the end of day
      * (if this instance is date-only) or the start of day (if the other
      * instance is date-only).
      *
      * @return @c true if this instance represents an earlier time than @p other,
      *         @c false otherwise
      * @see compare()
      */
     bool operator<(const KDateTime &other) const;
 
     bool operator<=(const KDateTime &other) const
     {
         return !(other < *this);
     }
     bool operator>(const KDateTime &other) const
     {
         return other < *this;
     }
     bool operator>=(const KDateTime &other) const
     {
         return !(*this < other);
     }
 
     /**
      * Create a separate copy of this instance's data if it is implicitly shared
      * with another instance.
      *
      * You would normally only call this if you want different copies of the
      * same date/time value to cache conversions to different time zones. Because
      * only the last conversion to another time zone is cached, and the cached
      * value is implicitly shared, judicious use of detach() could improve
      * efficiency when handling several time zones. But take care: if used
      * inappropriately, it will reduce efficiency!
      */
     void detach();
 
     /**
      * Set an adjustment to be applied when fetching the current system time.
      * This is applied by all KDateTime methods which return the system date
      * and/or time.
      *
      * The supplied date/time is used as the current simulated time and the
      * time adjustment is set to the difference between the real current time
      * and @p newTime. If @p newTime has a time zone, that time zone is set
      * to be the simulated local system time zone by calling
      * KSystemTimeZones::setLocalZone()).
      *
      * To cancel time simulation, supply an invalid @p newTime parameter.
      *
      * @warning This function is provided only for testing purposes, and should
      *          not be used in released code. If the library is compiled without
      *          debug enabled, setSimulatedSystemTime() has no effect.
      *          To avoid confusion, it is recommended that calls to it should be
      *          conditionally compiled, e.g.:
      *          \code
      *          #ifndef NDEBUG
      *             KDateTime::simulateSystemTime(kdt);
      *          #endif
      *          \endcode
      *
      * @param newTime the current simulated time, or invalid to cancel simulation
      *
      * @see currentDateTime(), currentLocalDateTime(), currentUtcDateTime(),
      *      currentLocalDate(), currentLocalTime()
      * @since 4.3
      */
     static void setSimulatedSystemTime(const KDateTime &newTime);
 
     /**
      * Return the real (not simulated) system time.
      *
      * @warning This method is provided only for testing purposes, and should
      *          not be used in released code. If the library is compiled without
      *          debug enabled, currentLocalDateTime() and realCurrentLocalDateTime()
      *          both return the real system time.
      *          To avoid confusion, it is recommended that calls to
      *          realCurrentLocalDateTime() should be conditionally compiled, e.g.:
      *          \code
      *          #ifndef NDEBUG
      *             dt = KDateTime::realCurrentLocalDateTime();
      *          #endif
      *          \endcode
      *
      * @since 4.3
      */
     static KDateTime realCurrentLocalDateTime();
 
     friend QDataStream KDELIBS4SUPPORT_EXPORT &operator<<(QDataStream &out, const KDateTime &dateTime);
     friend QDataStream KDELIBS4SUPPORT_EXPORT &operator>>(QDataStream &in, KDateTime &dateTime);
 
 private:
     QSharedDataPointer<KDateTimePrivate> d;
 };
 
 Q_DECLARE_METATYPE(KDateTime)
 Q_DECLARE_METATYPE(KDateTime::Spec)
 
 /** Write @p spec to the datastream @p out, in binary format. */
 QDataStream KDELIBS4SUPPORT_EXPORT &operator<<(QDataStream &out, const KDateTime::Spec &spec);
 /** Read a KDateTime::Spec object into @p spec from @p in, in binary format. */
 QDataStream KDELIBS4SUPPORT_EXPORT &operator>>(QDataStream &in, KDateTime::Spec &spec);
 
 /** Write @p dateTime to the datastream @p out, in binary format. */
 QDataStream KDELIBS4SUPPORT_EXPORT &operator<<(QDataStream &out, const KDateTime &dateTime);
 /** Read a KDateTime object into @p dateTime from @p in, in binary format. */
 QDataStream KDELIBS4SUPPORT_EXPORT &operator>>(QDataStream &in, KDateTime &dateTime);
 
 #endif