1 | /* |
2 | This file is part of the kcalcore library. |
3 | |
4 | Copyright (c) 2001-2003 Cornelius Schumacher <schumacher@kde.org> |
5 | |
6 | This library is free software; you can redistribute it and/or |
7 | modify it under the terms of the GNU Library General Public |
8 | License as published by the Free Software Foundation; either |
9 | version 2 of the License, or (at your option) any later version. |
10 | |
11 | This library is distributed in the hope that it will be useful, |
12 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | Library General Public License for more details. |
15 | |
16 | You should have received a copy of the GNU Library General Public License |
17 | along with this library; see the file COPYING.LIB. If not, write to |
18 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
19 | Boston, MA 02110-1301, USA. |
20 | */ |
21 | /** |
22 | @file |
23 | This file is part of the API for handling calendar data and |
24 | defines the Period class. |
25 | |
26 | @brief |
27 | Represents a period of time. |
28 | |
29 | @author Cornelius Schumacher \<schumacher@kde.org\> |
30 | */ |
31 | #ifndef KCALCORE_PERIOD_H |
32 | #define KCALCORE_PERIOD_H |
33 | |
34 | #include "kcalcore_export.h" |
35 | #include "duration.h" |
36 | |
37 | #include <KDE/KDateTime> |
38 | |
39 | #include <QtCore/QDataStream> |
40 | #include <QtCore/QMetaType> |
41 | #include <QtCore/QVector> |
42 | |
43 | namespace KCalCore { |
44 | |
45 | /** |
46 | The period can be defined by either a start time and an end time or |
47 | by a start time and a duration. |
48 | */ |
49 | class KCALCORE_EXPORT Period |
50 | { |
51 | public: |
52 | /** |
53 | List of periods. |
54 | */ |
55 | typedef QVector<Period> List; |
56 | |
57 | /** |
58 | Constructs a period without a duration. |
59 | */ |
60 | Period(); |
61 | |
62 | /** |
63 | Constructs a period from @p start to @p end. |
64 | |
65 | @param start the time the period begins. |
66 | @param end the time the period ends. |
67 | */ |
68 | Period(const KDateTime &start, const KDateTime &end); |
69 | |
70 | /** |
71 | Constructs a period from @p start and lasting @p duration. |
72 | |
73 | @param start the time when the period starts. |
74 | @param duration how long the period lasts. |
75 | */ |
76 | Period(const KDateTime &start, const Duration &duration); |
77 | |
78 | /** |
79 | Constructs a period by copying another period object |
80 | |
81 | @param period the period to copy |
82 | */ |
83 | |
84 | Period(const Period &period); |
85 | |
86 | /** |
87 | Destroys a period. |
88 | */ |
89 | ~Period(); |
90 | |
91 | /** |
92 | Returns true if the start of this period is earlier than the start of |
93 | the @p other one. |
94 | |
95 | @param other is the other period to compare. |
96 | */ |
97 | bool operator<(const Period &other) const; |
98 | |
99 | /** |
100 | Returns true if the start of this period is later than the start of |
101 | the @p other one. |
102 | |
103 | @param other the other period to compare |
104 | */ |
105 | bool operator>(const Period &other) const { |
106 | return other.operator<(*this); |
107 | } |
108 | |
109 | /** |
110 | Returns true if this period is equal to the @p other one. |
111 | Even if their start and end times are the same, two periods are |
112 | considered not equal if one is defined in terms of a duration and the |
113 | other in terms of a start and end time. |
114 | |
115 | @param other the other period to compare |
116 | */ |
117 | bool operator==(const Period &other) const; |
118 | |
119 | /** |
120 | Returns true if this period is not equal to the @p other one. |
121 | |
122 | @param other the other period to compare |
123 | @see operator==() |
124 | */ |
125 | bool operator!=(const Period &other) const { |
126 | return !operator==(other); |
127 | } |
128 | |
129 | /** |
130 | Sets this period equal to the @p other one. |
131 | |
132 | @param other is the other period to compare. |
133 | */ |
134 | Period &operator=(const Period &other); |
135 | |
136 | /** |
137 | Returns when this period starts. |
138 | */ |
139 | KDateTime start() const; |
140 | |
141 | /** |
142 | Returns when this period ends. |
143 | */ |
144 | KDateTime end() const; |
145 | |
146 | /** |
147 | Returns the duration of the period. |
148 | |
149 | If the period is defined in terms of a start and end time, the duration |
150 | is computed from these. In this case, if the time of day in @p start and |
151 | @p end is equal, and their time specifications (i.e. time zone etc.) are |
152 | the same, the duration will be set in terms of days. Otherwise, the |
153 | duration will be set in terms of seconds. |
154 | |
155 | If the period is defined in terms of a duration, that duration is |
156 | returned unchanged. |
157 | */ |
158 | Duration duration() const; |
159 | |
160 | /** |
161 | Returns the duration of the period. |
162 | |
163 | If the period is defined in terms of a start and end time, the duration |
164 | is first computed from these. |
165 | |
166 | If @p type is Days, and the duration is not an exact number of days, |
167 | the duration will be rounded down to the nearest whole number of days. |
168 | |
169 | @param type the unit of time to use (seconds or days) |
170 | */ |
171 | Duration duration(Duration::Type type) const; |
172 | |
173 | /** |
174 | Returns true if this period has a set duration, false |
175 | if it just has a start and an end. |
176 | */ |
177 | bool hasDuration() const; |
178 | |
179 | /** |
180 | Shift the times of the period so that they appear at the same clock |
181 | time as before but in a new time zone. The shift is done from a viewing |
182 | time zone rather than from the actual period time zone. |
183 | |
184 | For example, shifting a period whose start time is 09:00 America/New York, |
185 | using an old viewing time zone (@p oldSpec) of Europe/London, to a new |
186 | time zone (@p newSpec) of Europe/Paris, will result in the time being |
187 | shifted from 14:00 (which is the London time of the period start) to |
188 | 14:00 Paris time. |
189 | |
190 | @param oldSpec the time specification which provides the clock times |
191 | @param newSpec the new time specification |
192 | */ |
193 | void shiftTimes(const KDateTime::Spec &oldSpec, |
194 | const KDateTime::Spec &newSpec); |
195 | |
196 | private: |
197 | //@cond PRIVATE |
198 | class Private; |
199 | Private *const d; |
200 | //@endcond |
201 | |
202 | friend KCALCORE_EXPORT QDataStream &operator<<(QDataStream &stream, |
203 | const KCalCore::Period &period); |
204 | |
205 | friend KCALCORE_EXPORT QDataStream &operator>>(QDataStream &stream, |
206 | KCalCore::Period &period); |
207 | }; |
208 | |
209 | /** Write @p period to the datastream @p stream, in binary format. */ |
210 | KCALCORE_EXPORT QDataStream &operator<<(QDataStream &stream, const KCalCore::Period &period); |
211 | |
212 | /** Read a Period object into @p period from @p stream, in binary format. */ |
213 | KCALCORE_EXPORT QDataStream &operator>>(QDataStream &stream, KCalCore::Period &period); |
214 | } |
215 | |
216 | /** |
217 | Return a hash value for a Period argument. |
218 | @param key is a Period. |
219 | */ |
220 | KCALCORE_EXPORT uint qHash(const KCalCore::Period &key); |
221 | |
222 | //@cond PRIVATE |
223 | Q_DECLARE_METATYPE(KCalCore::Period) |
224 | //@endcond |
225 | |
226 | #endif |
227 | |