ktimezone.h

Go to the documentation of this file.

/*
   This file is part of the KDE libraries
   Copyright (c) 2005-2007 David Jarvie <djarvie@kde.org>
   Copyright (c) 2005 S.R.Haque <srhaque@iee.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 _KTIMEZONES_H
#define _KTIMEZONES_H

#include <kdecore_export.h>

#include <sys/time.h>
#include <ctime>

#include <QtCore/QDateTime>
#include <QtCore/QMap>
#include <QtCore/QList>
#include <QtCore/QString>
#include <QtCore/QByteArray>
#include <QtCore/QSharedDataPointer>

class KTimeZone;
class KTimeZoneBackend;
class KTimeZoneData;
class KTimeZoneSource;
class KTimeZonesPrivate;
class KTimeZonePrivate;
class KTimeZoneSourcePrivate;
class KTimeZoneDataPrivate;
class KTimeZoneTransitionPrivate;
class KTimeZoneLeapSecondsPrivate;

class KDECORE_EXPORT KTimeZones
{
public:
    KTimeZones();
    ~KTimeZones();

    KTimeZone zone(const QString &name) const;

    typedef QMap<QString, KTimeZone> ZoneMap;

    const ZoneMap zones() const;

    bool add(const KTimeZone &zone);

    KTimeZone remove(const KTimeZone &zone);

    KTimeZone remove(const QString &name);

    void clear();

private:
    KTimeZones(const KTimeZones &);              // prohibit copying
    KTimeZones &operator=(const KTimeZones &);   // prohibit copying

    KTimeZonesPrivate * const d;
};


class KDECORE_EXPORT KTimeZone  //krazy:exclude=dpointer (has non-const d-pointer to Backend class)
{
public:

    /*
     * Time zone phase.
     *
     * A phase can be daylight savings time or standard time. It holds the
     * UTC offset and time zone abbreviation (e.g. EST, GMT).
     *
     * @short Time zone phase
     * @author David Jarvie <djarvie@kde.org>.
     */
    class KDECORE_EXPORT Phase
    {
    public:
        Phase();

        Phase(int utcOffset, const QByteArray &abbreviations, bool dst,
              const QString &comment = QString());

        Phase(int utcOffset, const QList<QByteArray> &abbreviations, bool dst,
              const QString &comment = QString());

        Phase(const Phase &rhs);
        ~Phase();
        Phase &operator=(const Phase &rhs);
        bool operator==(const Phase &rhs) const;
        bool operator!=(const Phase &rhs) const  { return !operator==(rhs); }

        int utcOffset() const;

        QList<QByteArray> abbreviations() const;

        bool isDst() const;

        QString comment() const;

    private:
        QSharedDataPointer<class KTimeZonePhasePrivate> d;
    };


    /*
     * Time zone daylight saving time transition.
     *
     * A Transition instance holds details of a transition to daylight saving time or
     * standard time, including the UTC time of the change.
     *
     * @short Time zone transition
     * @author David Jarvie <djarvie@kde.org>.
     */
    class KDECORE_EXPORT Transition
    {
    public:
        Transition();
        Transition(const QDateTime &dt, const Phase &phase);
        Transition(const KTimeZone::Transition &t);
        ~Transition();
        Transition &operator=(const KTimeZone::Transition &t);

        QDateTime time() const;

        Phase phase() const;

        bool operator<(const Transition &rhs) const;

    private:
        KTimeZoneTransitionPrivate *const d;
    };


    /*
     * Leap seconds adjustment for a time zone.
     *
     * This class defines a leap seconds adjustment for a time zone by its UTC time of
     * occurrence and the cumulative number of leap seconds to be added at that time.
     *
     * @short Leap seconds adjustment for a time zone
     * @see KTimeZone, KTimeZoneData
     * @ingroup timezones
     * @author David Jarvie <djarvie@kde.org>.
     */
    class KDECORE_EXPORT LeapSeconds
    {
    public:
        LeapSeconds();
        LeapSeconds(const QDateTime &utcTime, int leapSeconds, const QString &comment = QString());
        LeapSeconds(const LeapSeconds &c);
        ~LeapSeconds();
        LeapSeconds &operator=(const LeapSeconds &c);
        bool operator<(const LeapSeconds &c) const;    // needed by qSort()

        bool isValid() const;

        QDateTime dateTime() const;

        int leapSeconds() const;

        QString comment() const;

    private:
        KTimeZoneLeapSecondsPrivate *const d;
    };


    KTimeZone();

    explicit KTimeZone(const QString &name);

    KTimeZone(const KTimeZone &tz);
    KTimeZone &operator=(const KTimeZone &tz);

    virtual ~KTimeZone();

    bool operator==(const KTimeZone &rhs) const;
    bool operator!=(const KTimeZone &rhs) const  { return !operator==(rhs); }

    QByteArray type() const;

    bool isValid() const;

    QString name() const;

    QString countryCode() const;

    float latitude() const;

    float longitude() const;

    QString comment() const;

    QList<QByteArray> abbreviations() const;

    QByteArray abbreviation(const QDateTime &utcDateTime) const;

    QList<int> utcOffsets() const;

    QDateTime convert(const KTimeZone &newZone, const QDateTime &zoneDateTime) const;

    QDateTime toUtc(const QDateTime &zoneDateTime) const;

    QDateTime toZoneTime(const QDateTime &utcDateTime, bool *secondOccurrence = 0) const;

    int currentOffset(Qt::TimeSpec basis = Qt::UTC) const;

    virtual int offsetAtZoneTime(const QDateTime &zoneDateTime, int *secondOffset = 0) const;

    virtual int offsetAtUtc(const QDateTime &utcDateTime) const;

    virtual int offset(time_t t) const;

    virtual bool isDstAtUtc(const QDateTime &utcDateTime) const;

    virtual bool isDst(time_t t) const;

    QList<Phase> phases() const;

    virtual bool hasTransitions() const;

    QList<KTimeZone::Transition> transitions(const QDateTime &start = QDateTime(), const QDateTime &end = QDateTime()) const;

    const KTimeZone::Transition *transition(const QDateTime &dt, const Transition **secondTransition = 0, bool *validTime = 0) const;

    int transitionIndex(const QDateTime &dt, int *secondIndex = 0, bool *validTime = 0) const;

    QList<QDateTime> transitionTimes(const Phase &phase, const QDateTime &start = QDateTime(), const QDateTime &end = QDateTime()) const;

    QList<LeapSeconds> leapSecondChanges() const;

    KTimeZoneSource *source() const;

    bool parse() const;

    const KTimeZoneData *data(bool create = false) const;

    bool updateBase(const KTimeZone &other);

    static QDateTime fromTime_t(time_t t);

    static time_t toTime_t(const QDateTime &utcDateTime);

    static KTimeZone utc();

    static const int InvalidOffset;

    static const time_t InvalidTime_t;

    static const float UNKNOWN;

protected:
    KTimeZone(KTimeZoneBackend *impl);

    void setData(KTimeZoneData *data, KTimeZoneSource *source = 0);

private:
    KTimeZoneBackend *d;
};


class KDECORE_EXPORT KTimeZoneBackend  //krazy:exclude=dpointer (non-const d-pointer for KTimeZoneBackend-derived classes)
{
public:
    KTimeZoneBackend();
    explicit KTimeZoneBackend(const QString &name);

    KTimeZoneBackend(const KTimeZoneBackend &other);
    KTimeZoneBackend &operator=(const KTimeZoneBackend &other);
    virtual ~KTimeZoneBackend();

    virtual KTimeZoneBackend *clone() const;

    virtual QByteArray type() const;

    virtual int offsetAtZoneTime(const KTimeZone* caller, const QDateTime &zoneDateTime, int *secondOffset) const;
    virtual int offsetAtUtc(const KTimeZone* caller, const QDateTime &utcDateTime) const;
    virtual int offset(const KTimeZone* caller, time_t t) const;
    virtual bool isDstAtUtc(const KTimeZone* caller, const QDateTime &utcDateTime) const;
    virtual bool isDst(const KTimeZone* caller, time_t t) const;
    virtual bool hasTransitions(const KTimeZone* caller) const;

protected:
    KTimeZoneBackend(KTimeZoneSource *source, const QString &name,
                     const QString &countryCode = QString(), float latitude = KTimeZone::UNKNOWN,
                     float longitude = KTimeZone::UNKNOWN, const QString &comment = QString());

private:
    KTimeZonePrivate *d;   // non-const
    friend class KTimeZone;
};

class KDECORE_EXPORT KTimeZoneSource
{
public:
    KTimeZoneSource();
    virtual ~KTimeZoneSource();

    virtual KTimeZoneData *parse(const KTimeZone &zone) const;

    bool useZoneParse() const;

protected:
    explicit KTimeZoneSource(bool useZoneParse);

private:
    KTimeZoneSourcePrivate * const d;
};


class KDECORE_EXPORT KTimeZoneData
{
    friend class KTimeZone;

public:
    KTimeZoneData();
    KTimeZoneData(const KTimeZoneData &c);
    virtual ~KTimeZoneData();
    KTimeZoneData &operator=(const KTimeZoneData &c);

    virtual KTimeZoneData *clone() const;

    virtual QList<QByteArray> abbreviations() const;

    virtual QByteArray abbreviation(const QDateTime &utcDateTime) const;

    virtual QList<int> utcOffsets() const;

    int previousUtcOffset() const;

    QList<KTimeZone::Phase> phases() const;

    virtual bool hasTransitions() const;

    QList<KTimeZone::Transition> transitions(const QDateTime &start = QDateTime(), const QDateTime &end = QDateTime()) const;

    const KTimeZone::Transition *transition(const QDateTime &dt, const KTimeZone::Transition **secondTransition = 0, bool *validTime = 0) const;

    int transitionIndex(const QDateTime &dt, int *secondIndex = 0, bool *validTime = 0) const;

    QList<QDateTime> transitionTimes(const KTimeZone::Phase &phase, const QDateTime &start = QDateTime(), const QDateTime &end = QDateTime()) const;

    QList<KTimeZone::LeapSeconds> leapSecondChanges() const;

    KTimeZone::LeapSeconds leapSecondChange(const QDateTime &utc) const;

protected:
    void setPhases(const QList<KTimeZone::Phase> &phases, const KTimeZone::Phase& previousPhase);

    void setPhases(const QList<KTimeZone::Phase> &phases, int previousUtcOffset);

    void setTransitions(const QList<KTimeZone::Transition> &transitions);

    void setLeapSecondChanges(const QList<KTimeZone::LeapSeconds> &adjusts);

private:
    KTimeZoneDataPrivate * const d;
};

#endif