KDELibs4Support

ktimezone.h
Go to the documentation of this file.
1 /*
2  This file is part of the KDE libraries
3  Copyright (c) 2005-2007 David Jarvie <[email protected]>
4  Copyright (c) 2005 S.R.Haque <[email protected]>.
5 
6  This library is free software; you can redistribute it and/or
7  modify it under the terms of the GNU Library General Public
8  License as published by the Free Software Foundation; either
9  version 2 of the License, or (at your option) any later version.
10 
11  This library is distributed in the hope that it will be useful,
12  but WITHOUT ANY WARRANTY; without even the implied warranty of
13  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  Library General Public License for more details.
15 
16  You should have received a copy of the GNU Library General Public License
17  along with this library; see the file COPYING.LIB. If not, write to
18  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19  Boston, MA 02110-1301, USA.
20 */
21 
28 #ifndef _KTIMEZONES_H
29 #define _KTIMEZONES_H
30 
31 #include <kdelibs4support_export.h>
32 
33 #include <sys/time.h>
34 #include <ctime>
35 
36 #include <QDateTime>
37 #include <QMap>
38 #include <QList>
39 #include <QString>
40 #include <QByteArray>
41 #include <QSharedDataPointer>
42 
43 class KTimeZone;
44 class KTimeZoneBackend;
45 class KTimeZoneData;
46 class KTimeZoneSource;
47 class KTimeZonesPrivate;
48 class KTimeZonePrivate;
49 class KTimeZoneSourcePrivate;
50 class KTimeZoneDataPrivate;
51 class KTimeZoneTransitionPrivate;
52 class KTimeZoneLeapSecondsPrivate;
53 
308 class KDELIBS4SUPPORT_EXPORT KTimeZones
309 {
310 public:
311  KTimeZones();
312  ~KTimeZones();
313 
320  KTimeZone zone(const QString &name) const;
321 
324 
330  const ZoneMap zones() const;
331 
340  bool add(const KTimeZone &zone);
341 
349  KTimeZone remove(const KTimeZone &zone);
350 
358  KTimeZone remove(const QString &name);
359 
365  void clear();
366 
367 private:
368  KTimeZones(const KTimeZones &); // prohibit copying
369  KTimeZones &operator=(const KTimeZones &); // prohibit copying
370 
371  KTimeZonesPrivate *const d;
372 };
373 
415 class KDELIBS4SUPPORT_EXPORT KTimeZone //krazy:exclude=dpointer (has non-const d-pointer to Backend class)
416 {
417 public:
418 
419  /*
420  * Time zone phase.
421  *
422  * A phase can be daylight savings time or standard time. It holds the
423  * UTC offset and time zone abbreviation (e.g. EST, GMT).
424  *
425  * @short Time zone phase
426  * @author David Jarvie <[email protected]>.
427  */
428  class KDELIBS4SUPPORT_EXPORT Phase
429  {
430  public:
435  Phase();
436 
446  Phase(int utcOffset, const QByteArray &abbreviations, bool dst,
447  const QString &comment = QString());
448 
457  Phase(int utcOffset, const QList<QByteArray> &abbreviations, bool dst,
458  const QString &comment = QString());
459 
460  Phase(const Phase &rhs);
461  ~Phase();
462  Phase &operator=(const Phase &rhs);
463  bool operator==(const Phase &rhs) const;
464  bool operator!=(const Phase &rhs) const
465  {
466  return !operator==(rhs);
467  }
468 
476  int utcOffset() const;
477 
485  QList<QByteArray> abbreviations() const;
486 
492  bool isDst() const;
493 
499  QString comment() const;
500 
501  private:
503  };
504 
505  /*
506  * Time zone daylight saving time transition.
507  *
508  * A Transition instance holds details of a transition to daylight saving time or
509  * standard time, including the UTC time of the change.
510  *
511  * @short Time zone transition
512  * @author David Jarvie <[email protected]>.
513  */
514  class KDELIBS4SUPPORT_EXPORT Transition
515  {
516  public:
517  Transition();
518  Transition(const QDateTime &dt, const Phase &phase);
519  Transition(const KTimeZone::Transition &t);
520  ~Transition();
521  Transition &operator=(const KTimeZone::Transition &t);
522 
528  QDateTime time() const;
529 
535  Phase phase() const;
536 
543  bool operator<(const Transition &rhs) const;
544 
545  private:
546  KTimeZoneTransitionPrivate *const d;
547  };
548 
549  /*
550  * Leap seconds adjustment for a time zone.
551  *
552  * This class defines a leap seconds adjustment for a time zone by its UTC time of
553  * occurrence and the cumulative number of leap seconds to be added at that time.
554  *
555  * @short Leap seconds adjustment for a time zone
556  * @see KTimeZone, KTimeZoneData
557  * @ingroup timezones
558  * @author David Jarvie <[email protected]>.
559  */
560  class KDELIBS4SUPPORT_EXPORT LeapSeconds
561  {
562  public:
563  LeapSeconds();
564  LeapSeconds(const QDateTime &utcTime, int leapSeconds, const QString &comment = QString());
565  LeapSeconds(const LeapSeconds &c);
566  ~LeapSeconds();
567  LeapSeconds &operator=(const LeapSeconds &c);
568  bool operator<(const LeapSeconds &c) const; // needed by qSort()
569 
575  bool isValid() const;
576 
582  QDateTime dateTime() const;
583 
590  int leapSeconds() const;
591 
597  QString comment() const;
598 
599  private:
600  KTimeZoneLeapSecondsPrivate *const d;
601  };
602 
608  KTimeZone();
609 
615  KDELIBS4SUPPORT_DEPRECATED explicit KTimeZone(const QString &name);
616 
617  KTimeZone(const KTimeZone &tz);
618  KTimeZone &operator=(const KTimeZone &tz);
619 
620  virtual ~KTimeZone();
621 
631  bool operator==(const KTimeZone &rhs) const;
632  bool operator!=(const KTimeZone &rhs) const
633  {
634  return !operator==(rhs);
635  }
636 
644  QByteArray type() const;
645 
651  bool isValid() const;
652 
660  QString name() const;
661 
667  QString countryCode() const;
668 
674  float latitude() const;
675 
681  float longitude() const;
682 
688  QString comment() const;
689 
698  QList<QByteArray> abbreviations() const;
699 
708  QByteArray abbreviation(const QDateTime &utcDateTime) const;
709 
724  QList<int> utcOffsets() const;
725 
736  QDateTime convert(const KTimeZone &newZone, const QDateTime &zoneDateTime) const;
737 
751  QDateTime toUtc(const QDateTime &zoneDateTime) const;
752 
767  QDateTime toZoneTime(const QDateTime &utcDateTime, bool *secondOccurrence = nullptr) const;
768 
782  int currentOffset(Qt::TimeSpec basis = Qt::UTC) const;
783 
804  virtual int offsetAtZoneTime(const QDateTime &zoneDateTime, int *secondOffset = nullptr) const;
805 
825  virtual int offsetAtUtc(const QDateTime &utcDateTime) const;
826 
841  virtual int offset(time_t t) const;
842 
859  virtual bool isDstAtUtc(const QDateTime &utcDateTime) const;
860 
872  virtual bool isDst(time_t t) const;
873 
884  QList<Phase> phases() const;
885 
894  virtual bool hasTransitions() const;
895 
913  QList<KTimeZone::Transition> transitions(const QDateTime &start = QDateTime(), const QDateTime &end = QDateTime()) const;
914 
935  const KTimeZone::Transition *transition(const QDateTime &dt, const Transition **secondTransition = nullptr, bool *validTime = nullptr) const;
936 
959  int transitionIndex(const QDateTime &dt, int *secondIndex = nullptr, bool *validTime = nullptr) const;
960 
980  QList<QDateTime> transitionTimes(const Phase &phase, const QDateTime &start = QDateTime(), const QDateTime &end = QDateTime()) const;
981 
991  QList<LeapSeconds> leapSecondChanges() const;
992 
998  KTimeZoneSource *source() const;
999 
1005  bool parse() const;
1006 
1015  const KTimeZoneData *data(bool create = false) const;
1016 
1033  bool updateBase(const KTimeZone &other);
1034 
1044  static QDateTime fromTime_t(time_t t);
1045 
1058  static time_t toTime_t(const QDateTime &utcDateTime);
1059 
1070  static KTimeZone utc();
1071 
1075  static const int InvalidOffset;
1076 
1079  static const time_t InvalidTime_t;
1080 
1085  static const float UNKNOWN;
1086 
1087 protected:
1088  KTimeZone(KTimeZoneBackend *impl);
1089 
1099  void setData(KTimeZoneData *data, KTimeZoneSource *source = nullptr);
1100 
1101 private:
1102  KTimeZoneBackend *d;
1103 };
1104 
1121 class KDELIBS4SUPPORT_EXPORT KTimeZoneBackend //krazy:exclude=dpointer (non-const d-pointer for KTimeZoneBackend-derived classes)
1122 {
1123 public:
1125  KTimeZoneBackend();
1127  KDELIBS4SUPPORT_DEPRECATED explicit KTimeZoneBackend(const QString &name);
1128 
1129  KTimeZoneBackend(const KTimeZoneBackend &other);
1130  KTimeZoneBackend &operator=(const KTimeZoneBackend &other);
1131  virtual ~KTimeZoneBackend();
1132 
1140  virtual KTimeZoneBackend *clone() const;
1141 
1151  virtual QByteArray type() const;
1152 
1158  virtual int offsetAtZoneTime(const KTimeZone *caller, const QDateTime &zoneDateTime, int *secondOffset) const;
1164  virtual int offsetAtUtc(const KTimeZone *caller, const QDateTime &utcDateTime) const;
1170  virtual int offset(const KTimeZone *caller, time_t t) const;
1176  virtual bool isDstAtUtc(const KTimeZone *caller, const QDateTime &utcDateTime) const;
1182  virtual bool isDst(const KTimeZone *caller, time_t t) const;
1188  virtual bool hasTransitions(const KTimeZone *caller) const;
1189 
1190 protected:
1203  KTimeZoneBackend(KTimeZoneSource *source, const QString &name,
1204  const QString &countryCode = QString(), float latitude = KTimeZone::UNKNOWN,
1205  float longitude = KTimeZone::UNKNOWN, const QString &comment = QString());
1206 
1207 private:
1208  KTimeZonePrivate *d; // non-const
1209  friend class KTimeZone;
1210 };
1211 
1231 class KDELIBS4SUPPORT_EXPORT KTimeZoneSource
1232 {
1233 public:
1234  KTimeZoneSource();
1235  virtual ~KTimeZoneSource();
1236 
1253  virtual KTimeZoneData *parse(const KTimeZone &zone) const;
1254 
1262  bool useZoneParse() const;
1263 
1264 protected:
1282  KDELIBS4SUPPORT_DEPRECATED explicit KTimeZoneSource(bool useZoneParse);
1283 
1284 private:
1285  KTimeZoneSourcePrivate *const d;
1286 };
1287 
1302 class KDELIBS4SUPPORT_EXPORT KTimeZoneData
1303 {
1304  friend class KTimeZone;
1305 
1306 public:
1307  KTimeZoneData();
1308  KTimeZoneData(const KTimeZoneData &c);
1309  virtual ~KTimeZoneData();
1310  KTimeZoneData &operator=(const KTimeZoneData &c);
1311 
1320  virtual KTimeZoneData *clone() const;
1321 
1330  virtual QList<QByteArray> abbreviations() const;
1331 
1340  virtual QByteArray abbreviation(const QDateTime &utcDateTime) const;
1341 
1351  virtual QList<int> utcOffsets() const;
1352 
1358  int previousUtcOffset() const;
1359 
1371 
1380  virtual bool hasTransitions() const;
1381 
1399  QList<KTimeZone::Transition> transitions(const QDateTime &start = QDateTime(), const QDateTime &end = QDateTime()) const;
1400 
1421  const KTimeZone::Transition *transition(const QDateTime &dt, const KTimeZone::Transition **secondTransition = nullptr, bool *validTime = nullptr) const;
1422 
1445  int transitionIndex(const QDateTime &dt, int *secondIndex = nullptr, bool *validTime = nullptr) const;
1446 
1466  QList<QDateTime> transitionTimes(const KTimeZone::Phase &phase, const QDateTime &start = QDateTime(), const QDateTime &end = QDateTime()) const;
1467 
1478 
1486  KTimeZone::LeapSeconds leapSecondChange(const QDateTime &utc) const;
1487 
1488 protected:
1498  void setPhases(const QList<KTimeZone::Phase> &phases, const KTimeZone::Phase &previousPhase);
1499 
1510  void setPhases(const QList<KTimeZone::Phase> &phases, int previousUtcOffset);
1511 
1518  void setTransitions(const QList<KTimeZone::Transition> &transitions);
1519 
1526  void setLeapSecondChanges(const QList<KTimeZone::LeapSeconds> &adjusts);
1527 
1528 private:
1529  KTimeZoneDataPrivate *const d;
1530 };
1531 
1532 #endif
Base class for the parsed data returned by a KTimeZoneSource class.
Definition: ktimezone.h:1302
The KTimeZones class represents a time zone database which consists of a collection of individual tim...
Definition: ktimezone.h:308
virtual bool hasTransitions() const
Return whether daylight saving transitions are available for the time zone.
Definition: ktimezone.cpp:700
TimeSpec
QByteArray abbreviation(const QDateTime &utcDateTime) const
Returns the time zone abbreviation current at a specified time.
Definition: ktimezone.cpp:676
QList< Phase > phases() const
Return all daylight savings time phases for the time zone.
Definition: ktimezone.cpp:692
static const float UNKNOWN
A representation for unknown locations; this is a float that does not represent a real latitude or lo...
Definition: ktimezone.h:1085
static const time_t InvalidTime_t
Indicates an invalid time_t value.
Definition: ktimezone.h:1079
int transitionIndex(const QDateTime &dt, int *secondIndex=nullptr, bool *validTime=nullptr) const
Find the index to the last daylight savings time transition at or before a given UTC or local time...
Definition: ktimezone.cpp:725
static const int InvalidOffset
Indicates an invalid UTC offset.
Definition: ktimezone.h:1075
const KTimeZone::Transition * transition(const QDateTime &dt, const Transition **secondTransition=nullptr, bool *validTime=nullptr) const
Find the last daylight savings time transition at or before a given UTC or local time.
Definition: ktimezone.cpp:713
Base class representing a time zone.
Definition: ktimezone.h:415
QList< LeapSeconds > leapSecondChanges() const
Return all leap second adjustments, in time order.
Definition: ktimezone.cpp:744
QList< QDateTime > transitionTimes(const Phase &phase, const QDateTime &start=QDateTime(), const QDateTime &end=QDateTime()) const
Return the times of all daylight saving transitions to a given time zone phase, in time order...
Definition: ktimezone.cpp:736
QList< KTimeZone::Transition > transitions(const QDateTime &start=QDateTime(), const QDateTime &end=QDateTime()) const
Return all daylight saving transitions, in time order.
Definition: ktimezone.cpp:705
QMap< QString, KTimeZone > ZoneMap
Map of KTimeZone instances, indexed by time zone name.
Definition: ktimezone.h:323
Base class representing a source of time zone information.
Definition: ktimezone.h:1231
QList< int > utcOffsets() const
Returns the complete list of UTC offsets used by the time zone.
Definition: ktimezone.cpp:684
QList< QByteArray > abbreviations() const
Returns the list of time zone abbreviations used by the time zone.
Definition: ktimezone.cpp:668
static KTimeZone utc()
Returns a standard UTC time zone, with name "UTC".
Definition: ktimezone.cpp:916
Base backend class for KTimeZone classes.
Definition: ktimezone.h:1121
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Fri Aug 14 2020 22:58:21 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.