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