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 <[email protected]>
5  SPDX-FileCopyrightText: 2007 David Jarvie <[email protected]>
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 <[email protected]>
15  @author David Jarvie <[email protected]>
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 
27 class QDateTime;
28 
29 namespace 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 */
43 class KCALENDARCORE_EXPORT Duration
44 {
45 public:
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 
306 private:
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  */
321 KCALENDARCORE_EXPORT QDataStream &operator<<(QDataStream &out, const KCalendarCore::Duration &);
322 
323 /**
324  * Duration deserializer.
325  *
326  * @since 4.12
327  */
328 KCALENDARCORE_EXPORT QDataStream &operator>>(QDataStream &in, KCalendarCore::Duration &);
329 
330 inline uint qHash(const Duration &duration, uint seed = 0)
331 {
332  QtPrivate::QHashCombine hash;
333  seed = hash(seed, duration.isDaily());
334  seed = hash(seed, duration.asSeconds());
335  return seed;
336 }
337 
338 }
339 
340 Q_DECLARE_METATYPE(KCalendarCore::Duration)
341 
342 #endif
Duration operator/(int value) const
Divides a duration by a value.
Definition: duration.h:257
KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &out, const KCalendarCore::Alarm::Ptr &)
Alarm serializer.
Definition: alarm.cpp:820
Represents a span of time measured in seconds or days.
Definition: duration.h:43
bool operator!=(const Duration &other) const
Returns true if this duration is not equal to the other.
Definition: duration.h:175
@ Seconds
duration is a number of seconds
Definition: duration.h:50
Namespace for all KCalendarCore types.
Definition: alarm.h:36
KCALENDARCORE_EXPORT QDataStream & operator>>(QDataStream &in, const KCalendarCore::Alarm::Ptr &)
Alarm deserializer.
Definition: alarm.cpp:833
bool operator<=(const Duration &other) const
Returns true if this duration is smaller than or equal to the other.
Definition: duration.h:136
@ Days
duration is a number of days
Definition: duration.h:51
bool operator!() const
Returns true if this duration is zero.
Definition: duration.h:121
Q_SCRIPTABLE Q_NOREPLY void start()
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
Adds two durations.
Definition: duration.h:196
Duration operator*(int value) const
Multiplies a duration by a value.
Definition: duration.h:240
bool operator>(const Duration &other) const
Returns true if this duration is greater than the other.
Definition: duration.h:145
Duration operator-(const Duration &other) const
Returns the difference between another duration and this.
Definition: duration.h:223
Type
The unit of time used to define the duration.
Definition: duration.h:49
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Sep 22 2023 03:55:21 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.