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
43namespace 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*/
49class KCALCORE_EXPORT Period
50{
51public:
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
196private:
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. */
210KCALCORE_EXPORT QDataStream &operator<<(QDataStream &stream, const KCalCore::Period &period);
211
212/** Read a Period object into @p period from @p stream, in binary format. */
213KCALCORE_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*/
220KCALCORE_EXPORT uint qHash(const KCalCore::Period &key);
221
222//@cond PRIVATE
223Q_DECLARE_METATYPE(KCalCore::Period)
224//@endcond
225
226#endif
227