KCalendarCore

duration.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 <schumacher@kde.org>
5 SPDX-FileCopyrightText: 2007 David Jarvie <djarvie@kde.org>
6
7 SPDX-License-Identifier: LGPL-2.0-or-later
8*/
9/**
10 @file
11 This file is part of the API for handling calendar data and
12 defines the Duration class.
13
14 @author Cornelius Schumacher <schumacher@kde.org>
15 @author David Jarvie <djarvie@kde.org>
16*/
17
18#ifndef KCALCORE_DURATION_H
19#define KCALCORE_DURATION_H
20
21#include "kcalendarcore_export.h"
22
23#include <QDataStream>
24#include <QHash>
25#include <QMetaType>
26
27class QDateTime;
28
29namespace KCalendarCore
30{
31/**
32 @brief
33 Represents a span of time measured in seconds or days.
34
35 A duration is a span of time measured in seconds or days. Construction can
36 be done by specifying a stop and end time, or simply by specifying the number
37 of seconds or days.
38
39 Much of the time, it does not matter whether a duration is specified in
40 seconds or in days. But it does make a difference when a duration is used to
41 define a time period encompassing a daylight saving time change.
42*/
43class KCALENDARCORE_EXPORT Duration
44{
45public:
46 /**
47 The unit of time used to define the duration.
48 */
49 enum Type {
50 Seconds, /**< duration is a number of seconds */
51 Days, /**< duration is a number of days */
52 };
53
54 /**
55 Constructs a duration of 0 seconds.
56 */
57 Duration();
58
59 /**
60 Constructs a duration from @p start to @p end.
61
62 If the time of day in @p start and @p end is equal, and their time
63 specifications (i.e. time zone etc.) are the same, the duration will be
64 set in terms of days. Otherwise, the duration will be set in terms of
65 seconds.
66
67 @param start is the time the duration begins.
68 @param end is the time the duration ends.
69 */
70 Duration(const QDateTime &start, const QDateTime &end);
71
72 /**
73 Constructs a duration from @p start to @p end.
74
75 If @p type is Days, and the time of day in @p start's time zone differs
76 between @p start and @p end, the duration will be rounded down to the
77 nearest whole number of days.
78
79 @param start is the time the duration begins.
80 @param end is the time the duration ends.
81 @param type the unit of time to use (seconds or days)
82 */
83 Duration(const QDateTime &start, const QDateTime &end, Type type);
84
85 /**
86 Constructs a duration with a number of seconds or days.
87
88 @param duration the number of seconds or days in the duration
89 @param type the unit of time to use (seconds or days)
90 */
91 // Keep the following implicit since instances are often used in integer evaluations.
92 Duration(int duration, Type type = Seconds); // krazy:exclude=explicit
93
94 /**
95 Constructs a duration by copying another duration object.
96
97 @param duration is the duration to copy.
98 */
99 Duration(const Duration &duration);
100
101 /**
102 Destroys a duration.
103 */
104 ~Duration();
105
106 /**
107 Sets this duration equal to @p duration.
108
109 @param duration is the duration to copy.
110 */
111 Duration &operator=(const Duration &duration);
112
113 /**
114 Returns true if this duration is non-zero.
115 */
116 operator bool() const;
117
118 /**
119 Returns true if this duration is zero.
120 */
121 bool operator!() const
122 {
123 return !operator bool();
124 }
125
126 /**
127 Returns true if this duration is smaller than the @p other.
128 @param other is the other duration to compare.
129 */
130 bool operator<(const Duration &other) const;
131
132 /**
133 Returns true if this duration is smaller than or equal to the @p other.
134 @param other is the other duration to compare.
135 */
136 bool operator<=(const Duration &other) const
137 {
138 return !other.operator<(*this);
139 }
140
141 /**
142 Returns true if this duration is greater than the @p other.
143 @param other is the other duration to compare.
144 */
145 bool operator>(const Duration &other) const
146 {
147 return other.operator<(*this);
148 }
149
150 /**
151 Returns true if this duration is greater than or equal to the @p other.
152 @param other is the other duration to compare.
153 */
154 bool operator>=(const Duration &other) const
155 {
156 return !operator<(other);
157 }
158
159 /**
160 Returns true if this duration is equal to the @p other.
161 Daily and non-daily durations are always considered unequal, since a
162 day's duration may differ from 24 hours if it happens to span a daylight
163 saving time change.
164 @param other the other duration to compare
165 */
166 bool operator==(const Duration &other) const;
167
168 /**
169 Returns true if this duration is not equal to the @p other.
170 Daily and non-daily durations are always considered unequal, since a
171 day's duration may differ from 24 hours if it happens to span a daylight
172 saving time change.
173 @param other is the other duration to compare.
174 */
175 bool operator!=(const Duration &other) const
176 {
177 return !operator==(other);
178 }
179
180 /**
181 Adds another duration to this one.
182 If one is in terms of days and the other in terms of seconds,
183 the result is in terms of seconds.
184 @param other the other duration to add
185 */
186 Duration &operator+=(const Duration &other);
187
188 /**
189 Adds two durations.
190 If one is in terms of days and the other in terms of seconds,
191 the result is in terms of seconds.
192
193 @param other the other duration to add
194 @return combined duration
195 */
196 Duration operator+(const Duration &other) const
197 {
198 return Duration(*this) += other;
199 }
200
201 /**
202 Returns the negative of this duration.
203 */
204 Duration operator-() const;
205
206 /**
207 Subtracts another duration from this one.
208 If one is in terms of days and the other in terms of seconds,
209 the result is in terms of seconds.
210
211 @param other the other duration to subtract
212 */
213 Duration &operator-=(const Duration &other);
214
215 /**
216 Returns the difference between another duration and this.
217 If one is in terms of days and the other in terms of seconds,
218 the result is in terms of seconds.
219
220 @param other the other duration to subtract
221 @return difference in durations
222 */
223 Duration operator-(const Duration &other) const
224 {
225 return Duration(*this) += other;
226 }
227
228 /**
229 Multiplies this duration by a value.
230 @param value value to multiply by
231 */
232 Duration &operator*=(int value);
233
234 /**
235 Multiplies a duration by a value.
236
237 @param value value to multiply by
238 @return resultant duration
239 */
240 Duration operator*(int value) const
241 {
242 return Duration(*this) *= value;
243 }
244
245 /**
246 Divides this duration by a value.
247 @param value value to divide by
248 */
249 Duration &operator/=(int value);
250
251 /**
252 Divides a duration by a value.
253
254 @param value value to divide by
255 @return resultant duration
256 */
257 Duration operator/(int value) const
258 {
259 return Duration(*this) /= value;
260 }
261
262 /**
263 Computes a duration end time by adding the number of seconds or
264 days in the duration to the specified @p start time.
265
266 @param start is the start time.
267 @return end time.
268 */
269 Q_REQUIRED_RESULT QDateTime end(const QDateTime &start) const;
270
271 /**
272 Returns the time units (seconds or days) used to specify the duration.
273 */
274 Q_REQUIRED_RESULT Type type() const;
275
276 /**
277 Returns whether the duration is specified in terms of days rather
278 than seconds.
279 */
280 Q_REQUIRED_RESULT bool isDaily() const;
281
282 /**
283 Returns the length of the duration in seconds.
284 */
285 Q_REQUIRED_RESULT int asSeconds() const;
286
287 /**
288 Returns the length of the duration in days. If the duration is
289 not an exact number of days, it is rounded down to return the
290 number of whole days.
291 */
292 Q_REQUIRED_RESULT int asDays() const;
293
294 /**
295 Returns the length of the duration in seconds or days.
296
297 @return if isDaily(), duration in days, else duration in seconds
298 */
299 Q_REQUIRED_RESULT int value() const;
300
301 /**
302 Returns true if the duration is 0 seconds.
303 */
304 Q_REQUIRED_RESULT bool isNull() const;
305
306private:
307 //@cond PRIVATE
308 class Private;
309 Private *const d;
310 //@endcond
311
312 friend KCALENDARCORE_EXPORT QDataStream &operator<<(QDataStream &s, const KCalendarCore::Duration &);
313 friend KCALENDARCORE_EXPORT QDataStream &operator>>(QDataStream &s, KCalendarCore::Duration &);
314};
315
316/**
317 * Duration serializer.
318 *
319 * @since 4.12
320 */
321KCALENDARCORE_EXPORT QDataStream &operator<<(QDataStream &out, const KCalendarCore::Duration &);
322
323/**
324 * Duration deserializer.
325 *
326 * @since 4.12
327 */
328KCALENDARCORE_EXPORT QDataStream &operator>>(QDataStream &in, KCalendarCore::Duration &);
329
330inline size_t qHash(const Duration &duration, size_t seed = 0)
331{
332 return qHashMulti(seed, duration.isDaily(), duration.asSeconds());
333}
334
335}
336
337Q_DECLARE_METATYPE(KCalendarCore::Duration)
338
339#endif
Represents a span of time measured in seconds or days.
Definition duration.h:44
friend KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &s, const KCalendarCore::Duration &)
Duration serializer.
bool operator>(const Duration &other) const
Returns true if this duration is greater than the other.
Definition duration.h:145
bool operator!=(const Duration &other) const
Returns true if this duration is not equal to the other.
Definition duration.h:175
Duration operator+(const Duration &other) const
Adds two durations.
Definition duration.h:196
Duration operator/(int value) const
Divides a duration by a value.
Definition duration.h:257
bool operator<=(const Duration &other) const
Returns true if this duration is smaller than or equal to the other.
Definition duration.h:136
Type
The unit of time used to define the duration.
Definition duration.h:49
@ Days
duration is a number of days
Definition duration.h:51
@ Seconds
duration is a number of seconds
Definition duration.h:50
bool isDaily() const
Returns whether the duration is specified in terms of days rather than seconds.
Definition duration.cpp:181
bool operator>=(const Duration &other) const
Returns true if this duration is greater than or equal to the other.
Definition duration.h:154
Duration operator-(const Duration &other) const
Returns the difference between another duration and this.
Definition duration.h:223
friend KCALENDARCORE_EXPORT QDataStream & operator>>(QDataStream &s, KCalendarCore::Duration &)
Duration deserializer.
bool operator!() const
Returns true if this duration is zero.
Definition duration.h:121
int asSeconds() const
Returns the length of the duration in seconds.
Definition duration.cpp:186
Duration operator*(int value) const
Multiplies a duration by a value.
Definition duration.h:240
Q_SCRIPTABLE Q_NOREPLY void start()
Namespace for all KCalendarCore types.
Definition alarm.h:37
KCALENDARCORE_EXPORT QDataStream & operator>>(QDataStream &in, const KCalendarCore::Alarm::Ptr &)
Alarm deserializer.
Definition alarm.cpp:833
KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &out, const KCalendarCore::Alarm::Ptr &)
Alarm serializer.
Definition alarm.cpp:820
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Oct 4 2024 12:01:42 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.