KCalendarCore

period.h
Go to the documentation of this file.
1 /*
2  This file is part of the kcalcore library.
3 
4  SPDX-FileCopyrightText: 2001-2003 Cornelius Schumacher <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 /**
9  @file
10  This file is part of the API for handling calendar data and
11  defines the Period class.
12 
13  @brief
14  Represents a period of time.
15 
16  @author Cornelius Schumacher <[email protected]>
17 */
18 #ifndef KCALCORE_PERIOD_H
19 #define KCALCORE_PERIOD_H
20 
21 #include "duration.h"
22 #include "kcalendarcore_export.h"
23 
24 #include <QDataStream>
25 #include <QDateTime>
26 #include <QMetaType>
27 #include <QVector>
28 
29 class QTimeZone;
30 
31 namespace KCalendarCore
32 {
33 /**
34  The period can be defined by either a start time and an end time or
35  by a start time and a duration.
36 */
37 class KCALENDARCORE_EXPORT Period
38 {
39 public:
40  /**
41  List of periods.
42  */
44 
45  /**
46  Constructs a period without a duration.
47  */
48  Period();
49 
50  /**
51  Constructs a period from @p start to @p end.
52 
53  @param start the time the period begins.
54  @param end the time the period ends.
55  */
56  Period(const QDateTime &start, const QDateTime &end);
57 
58  /**
59  Constructs a period from @p start and lasting @p duration.
60 
61  @param start the time when the period starts.
62  @param duration how long the period lasts.
63  */
64  Period(const QDateTime &start, const Duration &duration);
65 
66  /**
67  Constructs a period by copying another period object
68 
69  @param period the period to copy
70  */
71 
72  Period(const Period &period);
73 
74  /**
75  Destroys a period.
76  */
77  ~Period();
78 
79  /**
80  Returns true if the start of this period is earlier than the start of
81  the @p other one.
82 
83  @param other is the other period to compare.
84  */
85  bool operator<(const Period &other) const;
86 
87  /**
88  Returns true if the start of this period is later than the start of
89  the @p other one.
90 
91  @param other the other period to compare
92  */
93  bool operator>(const Period &other) const
94  {
95  return other.operator<(*this);
96  }
97 
98  /**
99  Returns true if this period is equal to the @p other one.
100  Even if their start and end times are the same, two periods are
101  considered not equal if one is defined in terms of a duration and the
102  other in terms of a start and end time.
103 
104  @param other the other period to compare
105  */
106  bool operator==(const Period &other) const;
107 
108  /**
109  Returns true if this period is not equal to the @p other one.
110 
111  @param other the other period to compare
112  @see operator==()
113  */
114  bool operator!=(const Period &other) const
115  {
116  return !operator==(other);
117  }
118 
119  /**
120  Sets this period equal to the @p other one.
121 
122  @param other is the other period to compare.
123  */
124  Period &operator=(const Period &other);
125 
126  /**
127  Returns true if the Period is not empty.
128  @since 5.87
129  */
130  Q_REQUIRED_RESULT bool isValid() const;
131 
132  /**
133  Returns when this period starts.
134  */
135  Q_REQUIRED_RESULT QDateTime start() const;
136 
137  /**
138  Returns when this period ends.
139  */
140  Q_REQUIRED_RESULT QDateTime end() const;
141 
142  /**
143  Returns the duration of the period.
144 
145  If the period is defined in terms of a start and end time, the duration
146  is computed from these. In this case, if the time of day in @p start and
147  @p end is equal, and their time specifications (i.e. time zone etc.) are
148  the same, the duration will be set in terms of days. Otherwise, the
149  duration will be set in terms of seconds.
150 
151  If the period is defined in terms of a duration, that duration is
152  returned unchanged.
153  */
154  Q_REQUIRED_RESULT Duration duration() const;
155 
156  /**
157  Returns the duration of the period.
158 
159  If the period is defined in terms of a start and end time, the duration
160  is first computed from these.
161 
162  If @p type is Days, and the duration is not an exact number of days,
163  the duration will be rounded down to the nearest whole number of days.
164 
165  @param type the unit of time to use (seconds or days)
166  */
167  Q_REQUIRED_RESULT Duration duration(Duration::Type type) const;
168 
169  /**
170  Returns true if this period has a set duration, false
171  if it just has a start and an end.
172  */
173  Q_REQUIRED_RESULT bool hasDuration() const;
174 
175  /**
176  Shift the times of the period so that they appear at the same clock
177  time as before but in a new time zone. The shift is done from a viewing
178  time zone rather than from the actual period time zone.
179 
180  For example, shifting a period whose start time is 09:00 America/New York,
181  using an old viewing time zone (@p oldSpec) of Europe/London, to a new
182  time zone (@p newSpec) of Europe/Paris, will result in the time being
183  shifted from 14:00 (which is the London time of the period start) to
184  14:00 Paris time.
185 
186  @param oldZone the time zone which provides the clock times
187  @param newZone the new time zone
188  */
189  void shiftTimes(const QTimeZone &oldZone, const QTimeZone &newZone);
190 
191 private:
192  //@cond PRIVATE
193  class Private;
194  Private *const d;
195  //@endcond
196 
197  friend KCALENDARCORE_EXPORT QDataStream &operator<<(QDataStream &stream, const KCalendarCore::Period &period);
198 
199  friend KCALENDARCORE_EXPORT QDataStream &operator>>(QDataStream &stream, KCalendarCore::Period &period);
200 };
201 
202 /** Write @p period to the datastream @p stream, in binary format. */
203 KCALENDARCORE_EXPORT QDataStream &operator<<(QDataStream &stream, const KCalendarCore::Period &period);
204 
205 /** Read a Period object into @p period from @p stream, in binary format. */
206 KCALENDARCORE_EXPORT QDataStream &operator>>(QDataStream &stream, KCalendarCore::Period &period);
207 
208 /**
209  Return a hash value for a Period argument.
210  @param key is a Period.
211 */
212 KCALENDARCORE_EXPORT uint qHash(const KCalendarCore::Period &key);
213 }
214 
215 //@cond PRIVATE
216 Q_DECLARE_METATYPE(KCalendarCore::Period)
217 Q_DECLARE_TYPEINFO(KCalendarCore::Period, Q_MOVABLE_TYPE);
218 //@endcond
219 
220 #endif
KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &out, const KCalendarCore::Alarm::Ptr &)
Alarm serializer.
Definition: alarm.cpp:820
bool operator!=(const Period &other) const
Returns true if this period is not equal to the other one.
Definition: period.h:114
KCALENDARCORE_EXPORT QDataStream & operator>>(QDataStream &in, const KCalendarCore::Alarm::Ptr &)
Alarm deserializer.
Definition: alarm.cpp:833
Represents a span of time measured in seconds or days.
Definition: duration.h:43
The period can be defined by either a start time and an end time or by a start time and a duration...
Definition: period.h:37
QVector< Period > List
List of periods.
Definition: period.h:43
KCALENDARCORE_EXPORT uint qHash(const KCalendarCore::Period &key)
Return a hash value for a Period argument.
Definition: period.cpp:158
This file is part of the API for handling calendar data and defines the Duration class.
Type
The unit of time used to define the duration.
Definition: duration.h:49
bool operator>(const Period &other) const
Returns true if the start of this period is later than the start of the other one.
Definition: period.h:93
Namespace for all KCalendarCore types.
Definition: alarm.h:36
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu Sep 23 2021 22:51:47 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.