kdatetime.h

Go to the documentation of this file.

/*
    This file is part of the KDE libraries
    Copyright (c) 2005-2010 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.
*/

#ifndef _KDATETIME_H_
#define _KDATETIME_H_

#include <kdecore_export.h>
#include <ktimezone.h>

#include <QtCore/QMetaType>
#include <QtCore/QSharedDataPointer>

class QDataStream;
class KDateTimePrivate;
class KDateTimeSpecPrivate;

class KDECORE_EXPORT KDateTime //krazy:exclude=dpointer (implicitly shared)
{
  public:
    enum SpecType
    {
        Invalid,    
        UTC,        
        OffsetFromUTC, 
        TimeZone,   
        LocalZone,  
        ClockTime   
    };

    class KDECORE_EXPORT Spec
    {
      public:
        Spec();

        Spec(const KTimeZone &tz);   // allow implicit conversion

        Spec(SpecType type, int utcOffset = 0);   // allow implicit conversion

        Spec(const Spec& spec);

        Spec& operator=(const Spec& spec);

        ~Spec();

        bool isValid() const;

        KTimeZone timeZone() const;

        SpecType type() const;

        bool isLocalZone() const;

        bool isClockTime() const;

        bool isUtc() const;

        bool isOffsetFromUtc() const;

        int utcOffset() const;

        void setType(SpecType type, int utcOffset = 0);

        void setType(const KTimeZone &tz);

        bool operator==(const Spec &other) const;

        bool operator!=(const Spec &other) const { return !operator==(other); }

        bool equivalentTo(const Spec &other) const;

        static Spec UTC();

        static Spec ClockTime();

        static Spec OffsetFromUTC(int utcOffset);

        static Spec LocalZone();

    private:
        KDateTimeSpecPrivate* const d;
    };

    enum TimeFormat
    {
        ISODate,    
        RFCDate,    
        RFCDateDay, 
        QtTextDate, 
        LocalDate   
    };

    enum Comparison
    {
        Before  = 0x01, 
        AtStart = 0x02, 
        Inside  = 0x04, 
        AtEnd   = 0x08, 
        After   = 0x10, 
        Equal = AtStart | Inside | AtEnd,
        Outside = Before | AtStart | Inside | AtEnd | After,
        StartsAt = AtStart | Inside | AtEnd | After,
        EndsAt = Before | AtStart | Inside | AtEnd
   };

  
    KDateTime();

    explicit KDateTime(const QDate &date, const Spec &spec = Spec(LocalZone));

    KDateTime(const QDate &date, const QTime &time, const Spec &spec = Spec(LocalZone));

    KDateTime(const QDateTime &dt, const Spec &spec);

    explicit KDateTime(const QDateTime &dt);

    KDateTime(const KDateTime &other);
    ~KDateTime();

    KDateTime &operator=(const KDateTime &other);

    bool isNull() const;

    bool isValid() const;

    bool isDateOnly() const;

    QDate date() const;

    QTime time() const;

    QDateTime dateTime() const;

    KTimeZone timeZone() const;

    Spec timeSpec() const;

    SpecType timeType() const;

    bool isLocalZone() const;

    bool isClockTime() const;

    bool isUtc() const;

    bool isOffsetFromUtc() const;

    int utcOffset() const;

    bool isSecondOccurrence() const;

    KDateTime toUtc() const;

    KDateTime toOffsetFromUtc() const;

    KDateTime toOffsetFromUtc(int utcOffset) const;

    KDateTime toLocalZone() const;

    KDateTime toClockTime() const;

    KDateTime toZone(const KTimeZone &zone) const;

    KDateTime toTimeSpec(const Spec &spec) const;

    KDateTime toTimeSpec(const KDateTime &dt) const;

    uint toTime_t() const;

    void setTime_t(qint64 seconds);

    void setDateOnly(bool dateOnly);

    void setDate(const QDate &date);

    void setTime(const QTime &time);

    void setDateTime(const QDateTime &dt);

    void setTimeSpec(const Spec &spec);

    void setSecondOccurrence(bool second);

    KDateTime addMSecs(qint64 msecs) const;

    KDateTime addSecs(qint64 secs) const;

    KDateTime addDays(int days) const;

    KDateTime addMonths(int months) const;

    KDateTime addYears(int years) const;

    int secsTo(const KDateTime &other) const;

    qint64 secsTo_long(const KDateTime &other) const;

    int daysTo(const KDateTime &other) const;

    static KDateTime currentLocalDateTime();

    static KDateTime currentUtcDateTime();

    static KDateTime currentDateTime(const Spec &spec);

    static QDate currentLocalDate();

    static QTime currentLocalTime();

    QString toString(const QString &format) const;

    QString toString(TimeFormat format = ISODate) const;

    static KDateTime fromString(const QString &string, TimeFormat format = ISODate, bool *negZero = 0);

    static KDateTime fromString(const QString &string, const QString &format,
                                const KTimeZones *zones = 0, bool offsetIfAmbiguous = true);

    static void setFromStringDefault(const Spec &spec);


    bool outOfRange() const;

    Comparison compare(const KDateTime &other) const;

    bool operator==(const KDateTime &other) const;

    bool operator!=(const KDateTime &other) const { return !(*this == other); }

    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); }

    void detach();

    static void setSimulatedSystemTime(const KDateTime& newTime);

    static KDateTime realCurrentLocalDateTime();

    friend QDataStream KDECORE_EXPORT &operator<<(QDataStream &out, const KDateTime &dateTime);
    friend QDataStream KDECORE_EXPORT &operator>>(QDataStream &in, KDateTime &dateTime);

  private:
    QSharedDataPointer<KDateTimePrivate> d;
};

Q_DECLARE_METATYPE(KDateTime)
Q_DECLARE_METATYPE(KDateTime::Spec)

QDataStream KDECORE_EXPORT &operator<<(QDataStream &out, const KDateTime::Spec &spec);
QDataStream KDECORE_EXPORT &operator>>(QDataStream &in, KDateTime::Spec &spec);

QDataStream KDECORE_EXPORT &operator<<(QDataStream &out, const KDateTime &dateTime);
QDataStream KDECORE_EXPORT &operator>>(QDataStream &in, KDateTime &dateTime);

#endif