1 | /* |
2 | This file is part of the kcal 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 KCAL_DURATION_H |
32 | #define KCAL_DURATION_H |
33 | |
34 | #include "kcal_export.h" |
35 | |
36 | class KDateTime; |
37 | |
38 | namespace KCal { |
39 | |
40 | /** |
41 | @brief |
42 | Represents a span of time measured in seconds or days. |
43 | |
44 | A duration is a span of time measured in seconds or days. Construction can |
45 | be done by specifying a stop and end time, or simply by specifying the number |
46 | of seconds or days. |
47 | |
48 | Much of the time, it does not matter whether a duration is specified in |
49 | seconds or in days. But it does make a difference when a duration is used to |
50 | define a time period encompassing a daylight saving time change. |
51 | */ |
52 | class KCAL_DEPRECATED_EXPORT Duration |
53 | { |
54 | public: |
55 | /** |
56 | The unit of time used to define the duration. |
57 | */ |
58 | enum Type { |
59 | Seconds, /**< duration is a number of seconds */ |
60 | Days /**< duration is a number of days */ |
61 | }; |
62 | |
63 | /** |
64 | Constructs a duration of 0 seconds. |
65 | */ |
66 | Duration(); |
67 | |
68 | /** |
69 | Constructs a duration from @p start to @p end. |
70 | |
71 | If the time of day in @p start and @p end is equal, and their time |
72 | specifications (i.e. time zone etc.) are the same, the duration will be |
73 | set in terms of days. Otherwise, the duration will be set in terms of |
74 | seconds. |
75 | |
76 | @param start is the time the duration begins. |
77 | @param end is the time the duration ends. |
78 | */ |
79 | Duration( const KDateTime &start, const KDateTime &end ); |
80 | |
81 | /** |
82 | Constructs a duration from @p start to @p end. |
83 | |
84 | If @p type is Days, and the time of day in @p start's time zone differs |
85 | between @p start and @p end, the duration will be rounded down to the |
86 | nearest whole number of days. |
87 | |
88 | @param start is the time the duration begins. |
89 | @param end is the time the duration ends. |
90 | @param type the unit of time to use (seconds or days) |
91 | */ |
92 | Duration( const KDateTime &start, const KDateTime &end, Type type ); |
93 | |
94 | /** |
95 | Constructs a duration with a number of seconds or days. |
96 | |
97 | @param duration the number of seconds or days in the duration |
98 | @param type the unit of time to use (seconds or days) |
99 | */ |
100 | Duration( int duration, Type type = Seconds ); //krazy:exclude=explicit |
101 | |
102 | /** |
103 | Constructs a duration by copying another duration object. |
104 | |
105 | @param duration is the duration to copy. |
106 | */ |
107 | Duration( const Duration &duration ); |
108 | |
109 | /** |
110 | Destroys a duration. |
111 | */ |
112 | ~Duration(); |
113 | |
114 | /** |
115 | Sets this duration equal to @p duration. |
116 | |
117 | @param duration is the duration to copy. |
118 | */ |
119 | Duration &operator=( const Duration &duration ); |
120 | |
121 | /** |
122 | Returns true if this duration is non-zero. |
123 | */ |
124 | operator bool() const; |
125 | |
126 | /** |
127 | Returns true if this duration is zero. |
128 | */ |
129 | bool operator!() const { return !operator bool(); } |
130 | |
131 | /** |
132 | Returns true if this duration is smaller than the @p other. |
133 | @param other is the other duration to compare. |
134 | */ |
135 | bool operator<( const Duration &other ) const; |
136 | |
137 | /** |
138 | Returns true if this duration is smaller than or equal to the @p other. |
139 | @param other is the other duration to compare. |
140 | */ |
141 | bool operator<=( const Duration &other ) const |
142 | { return !other.operator<( *this ); } |
143 | |
144 | /** |
145 | Returns true if this duration is greater than the @p other. |
146 | @param other is the other duration to compare. |
147 | */ |
148 | bool operator>( const Duration &other ) const |
149 | { return other.operator<( *this ); } |
150 | |
151 | /** |
152 | Returns true if this duration is greater than or equal to the @p other. |
153 | @param other is the other duration to compare. |
154 | */ |
155 | bool operator>=( const Duration &other ) const |
156 | { return !operator<( other ); } |
157 | |
158 | /** |
159 | Returns true if this duration is equal to the @p other. |
160 | Daily and non-daily durations are always considered unequal, since a |
161 | day's duration may differ from 24 hours if it happens to span a daylight |
162 | saving time change. |
163 | @param other the other duration to compare |
164 | */ |
165 | bool operator==( const Duration &other ) const; |
166 | |
167 | /** |
168 | Returns true if this duration is not equal to the @p other. |
169 | Daily and non-daily durations are always considered unequal, since a |
170 | day's duration may differ from 24 hours if it happens to span a daylight |
171 | saving time change. |
172 | @param other is the other duration to compare. |
173 | */ |
174 | bool operator!=( const Duration &other ) const |
175 | { return !operator==( other ); } |
176 | |
177 | /** |
178 | Adds another duration to this one. |
179 | If one is in terms of days and the other in terms of seconds, |
180 | the result is in terms of seconds. |
181 | @param other the other duration to add |
182 | */ |
183 | Duration &operator+=( const Duration &other ); |
184 | |
185 | /** |
186 | Adds two durations. |
187 | If one is in terms of days and the other in terms of seconds, |
188 | the result is in terms of seconds. |
189 | |
190 | @param other the other duration to add |
191 | @return combined duration |
192 | */ |
193 | Duration operator+( const Duration &other ) const |
194 | { return Duration( *this ) += other; } |
195 | |
196 | /** |
197 | Returns the negative of this duration. |
198 | */ |
199 | Duration operator-() const; |
200 | |
201 | /** |
202 | Subtracts another duration from this one. |
203 | If one is in terms of days and the other in terms of seconds, |
204 | the result is in terms of seconds. |
205 | |
206 | @param other the other duration to subtract |
207 | */ |
208 | Duration &operator-=( const Duration &other ); |
209 | |
210 | /** |
211 | Returns the difference between another duration and this. |
212 | If one is in terms of days and the other in terms of seconds, |
213 | the result is in terms of seconds. |
214 | |
215 | @param other the other duration to subtract |
216 | @return difference in durations |
217 | */ |
218 | Duration operator-( const Duration &other ) const |
219 | { return Duration( *this ) += other; } |
220 | |
221 | /** |
222 | Multiplies this duration by a value. |
223 | @param value value to multiply by |
224 | */ |
225 | Duration &operator*=( int value ); |
226 | |
227 | /** |
228 | Multiplies a duration by a value. |
229 | |
230 | @param value value to multiply by |
231 | @return resultant duration |
232 | */ |
233 | Duration operator*( int value ) const |
234 | { return Duration( *this ) *= value; } |
235 | |
236 | /** |
237 | Divides this duration by a value. |
238 | @param value value to divide by |
239 | */ |
240 | Duration &operator/=( int value ); |
241 | |
242 | /** |
243 | Divides a duration by a value. |
244 | |
245 | @param value value to divide by |
246 | @return resultant duration |
247 | */ |
248 | Duration operator/( int value ) const |
249 | { return Duration( *this ) /= value; } |
250 | |
251 | /** |
252 | Computes a duration end time by adding the number of seconds or |
253 | days in the duration to the specified @p start time. |
254 | |
255 | @param start is the start time. |
256 | @return end time. |
257 | */ |
258 | KDateTime end( const KDateTime &start ) const; |
259 | |
260 | /** |
261 | Returns the time units (seconds or days) used to specify the duration. |
262 | */ |
263 | Type type() const; |
264 | |
265 | /** |
266 | Returns whether the duration is specified in terms of days rather |
267 | than seconds. |
268 | */ |
269 | bool isDaily() const; |
270 | |
271 | /** |
272 | Returns the length of the duration in seconds. |
273 | */ |
274 | int asSeconds() const; |
275 | |
276 | /** |
277 | Returns the length of the duration in days. If the duration is |
278 | not an exact number of days, it is rounded down to return the |
279 | number of whole days. |
280 | */ |
281 | int asDays() const; |
282 | |
283 | /** |
284 | Returns the length of the duration in seconds or days. |
285 | |
286 | @return if isDaily(), duration in days, else duration in seconds |
287 | */ |
288 | int value() const; |
289 | |
290 | private: |
291 | //@cond PRIVATE |
292 | class Private; |
293 | Private *const d; |
294 | //@endcond |
295 | }; |
296 | |
297 | } |
298 | |
299 | #endif |
300 | |