File indexing completed on 2024-04-21 03:52:45
0001 /* 0002 This file is part of the kcalcore library. 0003 0004 SPDX-FileCopyrightText: 2001-2003 Cornelius Schumacher <schumacher@kde.org> 0005 SPDX-FileCopyrightText: 2007 David Jarvie <djarvie@kde.org> 0006 0007 SPDX-License-Identifier: LGPL-2.0-or-later 0008 */ 0009 /** 0010 @file 0011 This file is part of the API for handling calendar data and 0012 defines the Duration class. 0013 0014 @author Cornelius Schumacher \<schumacher@kde.org\> 0015 @author David Jarvie \<djarvie@kde.org\> 0016 */ 0017 0018 #ifndef KCALCORE_DURATION_H 0019 #define KCALCORE_DURATION_H 0020 0021 #include "kcalendarcore_export.h" 0022 0023 #include <QDataStream> 0024 #include <QHash> 0025 #include <QMetaType> 0026 0027 class QDateTime; 0028 0029 namespace KCalendarCore 0030 { 0031 /** 0032 @brief 0033 Represents a span of time measured in seconds or days. 0034 0035 A duration is a span of time measured in seconds or days. Construction can 0036 be done by specifying a stop and end time, or simply by specifying the number 0037 of seconds or days. 0038 0039 Much of the time, it does not matter whether a duration is specified in 0040 seconds or in days. But it does make a difference when a duration is used to 0041 define a time period encompassing a daylight saving time change. 0042 */ 0043 class KCALENDARCORE_EXPORT Duration 0044 { 0045 public: 0046 /** 0047 The unit of time used to define the duration. 0048 */ 0049 enum Type { 0050 Seconds, /**< duration is a number of seconds */ 0051 Days, /**< duration is a number of days */ 0052 }; 0053 0054 /** 0055 Constructs a duration of 0 seconds. 0056 */ 0057 Duration(); 0058 0059 /** 0060 Constructs a duration from @p start to @p end. 0061 0062 If the time of day in @p start and @p end is equal, and their time 0063 specifications (i.e. time zone etc.) are the same, the duration will be 0064 set in terms of days. Otherwise, the duration will be set in terms of 0065 seconds. 0066 0067 @param start is the time the duration begins. 0068 @param end is the time the duration ends. 0069 */ 0070 Duration(const QDateTime &start, const QDateTime &end); 0071 0072 /** 0073 Constructs a duration from @p start to @p end. 0074 0075 If @p type is Days, and the time of day in @p start's time zone differs 0076 between @p start and @p end, the duration will be rounded down to the 0077 nearest whole number of days. 0078 0079 @param start is the time the duration begins. 0080 @param end is the time the duration ends. 0081 @param type the unit of time to use (seconds or days) 0082 */ 0083 Duration(const QDateTime &start, const QDateTime &end, Type type); 0084 0085 /** 0086 Constructs a duration with a number of seconds or days. 0087 0088 @param duration the number of seconds or days in the duration 0089 @param type the unit of time to use (seconds or days) 0090 */ 0091 // Keep the following implicit since instances are often used in integer evaluations. 0092 Duration(int duration, Type type = Seconds); // krazy:exclude=explicit 0093 0094 /** 0095 Constructs a duration by copying another duration object. 0096 0097 @param duration is the duration to copy. 0098 */ 0099 Duration(const Duration &duration); 0100 0101 /** 0102 Destroys a duration. 0103 */ 0104 ~Duration(); 0105 0106 /** 0107 Sets this duration equal to @p duration. 0108 0109 @param duration is the duration to copy. 0110 */ 0111 Duration &operator=(const Duration &duration); 0112 0113 /** 0114 Returns true if this duration is non-zero. 0115 */ 0116 operator bool() const; 0117 0118 /** 0119 Returns true if this duration is zero. 0120 */ 0121 bool operator!() const 0122 { 0123 return !operator bool(); 0124 } 0125 0126 /** 0127 Returns true if this duration is smaller than the @p other. 0128 @param other is the other duration to compare. 0129 */ 0130 bool operator<(const Duration &other) const; 0131 0132 /** 0133 Returns true if this duration is smaller than or equal to the @p other. 0134 @param other is the other duration to compare. 0135 */ 0136 bool operator<=(const Duration &other) const 0137 { 0138 return !other.operator<(*this); 0139 } 0140 0141 /** 0142 Returns true if this duration is greater than the @p other. 0143 @param other is the other duration to compare. 0144 */ 0145 bool operator>(const Duration &other) const 0146 { 0147 return other.operator<(*this); 0148 } 0149 0150 /** 0151 Returns true if this duration is greater than or equal to the @p other. 0152 @param other is the other duration to compare. 0153 */ 0154 bool operator>=(const Duration &other) const 0155 { 0156 return !operator<(other); 0157 } 0158 0159 /** 0160 Returns true if this duration is equal to the @p other. 0161 Daily and non-daily durations are always considered unequal, since a 0162 day's duration may differ from 24 hours if it happens to span a daylight 0163 saving time change. 0164 @param other the other duration to compare 0165 */ 0166 bool operator==(const Duration &other) const; 0167 0168 /** 0169 Returns true if this duration is not equal to the @p other. 0170 Daily and non-daily durations are always considered unequal, since a 0171 day's duration may differ from 24 hours if it happens to span a daylight 0172 saving time change. 0173 @param other is the other duration to compare. 0174 */ 0175 bool operator!=(const Duration &other) const 0176 { 0177 return !operator==(other); 0178 } 0179 0180 /** 0181 Adds another duration to this one. 0182 If one is in terms of days and the other in terms of seconds, 0183 the result is in terms of seconds. 0184 @param other the other duration to add 0185 */ 0186 Duration &operator+=(const Duration &other); 0187 0188 /** 0189 Adds two durations. 0190 If one is in terms of days and the other in terms of seconds, 0191 the result is in terms of seconds. 0192 0193 @param other the other duration to add 0194 @return combined duration 0195 */ 0196 Duration operator+(const Duration &other) const 0197 { 0198 return Duration(*this) += other; 0199 } 0200 0201 /** 0202 Returns the negative of this duration. 0203 */ 0204 Duration operator-() const; 0205 0206 /** 0207 Subtracts another duration from this one. 0208 If one is in terms of days and the other in terms of seconds, 0209 the result is in terms of seconds. 0210 0211 @param other the other duration to subtract 0212 */ 0213 Duration &operator-=(const Duration &other); 0214 0215 /** 0216 Returns the difference between another duration and this. 0217 If one is in terms of days and the other in terms of seconds, 0218 the result is in terms of seconds. 0219 0220 @param other the other duration to subtract 0221 @return difference in durations 0222 */ 0223 Duration operator-(const Duration &other) const 0224 { 0225 return Duration(*this) += other; 0226 } 0227 0228 /** 0229 Multiplies this duration by a value. 0230 @param value value to multiply by 0231 */ 0232 Duration &operator*=(int value); 0233 0234 /** 0235 Multiplies a duration by a value. 0236 0237 @param value value to multiply by 0238 @return resultant duration 0239 */ 0240 Duration operator*(int value) const 0241 { 0242 return Duration(*this) *= value; 0243 } 0244 0245 /** 0246 Divides this duration by a value. 0247 @param value value to divide by 0248 */ 0249 Duration &operator/=(int value); 0250 0251 /** 0252 Divides a duration by a value. 0253 0254 @param value value to divide by 0255 @return resultant duration 0256 */ 0257 Duration operator/(int value) const 0258 { 0259 return Duration(*this) /= value; 0260 } 0261 0262 /** 0263 Computes a duration end time by adding the number of seconds or 0264 days in the duration to the specified @p start time. 0265 0266 @param start is the start time. 0267 @return end time. 0268 */ 0269 Q_REQUIRED_RESULT QDateTime end(const QDateTime &start) const; 0270 0271 /** 0272 Returns the time units (seconds or days) used to specify the duration. 0273 */ 0274 Q_REQUIRED_RESULT Type type() const; 0275 0276 /** 0277 Returns whether the duration is specified in terms of days rather 0278 than seconds. 0279 */ 0280 Q_REQUIRED_RESULT bool isDaily() const; 0281 0282 /** 0283 Returns the length of the duration in seconds. 0284 */ 0285 Q_REQUIRED_RESULT int asSeconds() const; 0286 0287 /** 0288 Returns the length of the duration in days. If the duration is 0289 not an exact number of days, it is rounded down to return the 0290 number of whole days. 0291 */ 0292 Q_REQUIRED_RESULT int asDays() const; 0293 0294 /** 0295 Returns the length of the duration in seconds or days. 0296 0297 @return if isDaily(), duration in days, else duration in seconds 0298 */ 0299 Q_REQUIRED_RESULT int value() const; 0300 0301 /** 0302 Returns true if the duration is 0 seconds. 0303 */ 0304 Q_REQUIRED_RESULT bool isNull() const; 0305 0306 private: 0307 //@cond PRIVATE 0308 class Private; 0309 Private *const d; 0310 //@endcond 0311 0312 friend KCALENDARCORE_EXPORT QDataStream &operator<<(QDataStream &s, const KCalendarCore::Duration &); 0313 friend KCALENDARCORE_EXPORT QDataStream &operator>>(QDataStream &s, KCalendarCore::Duration &); 0314 }; 0315 0316 /** 0317 * Duration serializer. 0318 * 0319 * @since 4.12 0320 */ 0321 KCALENDARCORE_EXPORT QDataStream &operator<<(QDataStream &out, const KCalendarCore::Duration &); 0322 0323 /** 0324 * Duration deserializer. 0325 * 0326 * @since 4.12 0327 */ 0328 KCALENDARCORE_EXPORT QDataStream &operator>>(QDataStream &in, KCalendarCore::Duration &); 0329 0330 inline size_t qHash(const Duration &duration, size_t seed = 0) 0331 { 0332 return qHashMulti(seed, duration.isDaily(), duration.asSeconds()); 0333 } 0334 0335 } 0336 0337 Q_DECLARE_METATYPE(KCalendarCore::Duration) 0338 0339 #endif