1/*
2 This file is part of the kcal 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
32#ifndef KCAL_PERIOD_H
33#define KCAL_PERIOD_H
34
35#include "kcal_export.h"
36#include "duration.h"
37
38#include <kdatetime.h>
39#include <QtCore/QList>
40
41namespace KCal {
42
43/**
44 The period can be defined by either a start time and an end time or
45 by a start time and a duration.
46*/
47class KCAL_DEPRECATED_EXPORT Period
48{
49 public:
50 /**
51 List of periods.
52 */
53 typedef QList<Period> List;
54
55 /**
56 Constructs a period without a duration.
57 */
58 Period();
59
60 /**
61 Constructs a period from @p start to @p end.
62
63 @param start the time the period begins.
64 @param end the time the period ends.
65 */
66 Period( const KDateTime &start, const KDateTime &end );
67
68 /**
69 Constructs a period from @p start and lasting @p duration.
70
71 @param start the time when the period starts.
72 @param duration how long the period lasts.
73 */
74 Period( const KDateTime &start, const Duration &duration );
75
76 /**
77 Constructs a period by copying another period object
78
79 @param period the period to copy
80 */
81
82 Period( const Period &period );
83
84 /**
85 Destroys a period.
86 */
87 ~Period();
88
89 /**
90 Returns true if the start of this period is earlier than the start of
91 the @p other one.
92
93 @param other is the other period to compare.
94 */
95 bool operator<( const Period &other ) const;
96
97 /**
98 Returns true if the start of this period is later than the start of
99 the @p other one.
100
101 @param other the other period to compare
102 */
103 bool operator>( const Period &other ) const { return other.operator<( *this ); }
104
105 /**
106 Returns true if this period is equal to the @p other one.
107 Even if their start and end times are the same, two periods are
108 considered not equal if one is defined in terms of a duration and the
109 other in terms of a start and end time.
110
111 @param other the other period to compare
112 */
113 bool operator==( const Period &other ) const;
114
115 /**
116 Returns true if this period is not equal to the @p other one.
117
118 @param other the other period to compare
119 @see operator==()
120 */
121 bool operator!=( const Period &other ) const { return !operator==( other ); }
122
123 /**
124 Sets this period equal to the @p other one.
125
126 @param other is the other period to compare.
127 */
128 Period &operator=( const Period &other );
129
130 /**
131 Returns when this period starts.
132 */
133 KDateTime start() const;
134
135 /**
136 Returns when this period ends.
137 */
138 KDateTime end() const;
139
140 /**
141 Returns the duration of the period.
142
143 If the period is defined in terms of a start and end time, the duration
144 is computed from these. In this case, if the time of day in @p start and
145 @p end is equal, and their time specifications (i.e. time zone etc.) are
146 the same, the duration will be set in terms of days. Otherwise, the
147 duration will be set in terms of seconds.
148
149 If the period is defined in terms of a duration, that duration is
150 returned unchanged.
151 */
152 Duration duration() const;
153
154 /**
155 Returns the duration of the period.
156
157 If the period is defined in terms of a start and end time, the duration
158 is first computed from these.
159
160 If @p type is Days, and the duration is not an exact number of days,
161 the duration will be rounded down to the nearest whole number of days.
162
163 @param type the unit of time to use (seconds or days)
164 */
165 Duration duration( Duration::Type type ) const;
166
167 /**
168 Returns true if this period has a set duration, false
169 if it just has a start and an end.
170 */
171 bool hasDuration() const;
172
173 /**
174 Shift the times of the period so that they appear at the same clock
175 time as before but in a new time zone. The shift is done from a viewing
176 time zone rather than from the actual period time zone.
177
178 For example, shifting a period whose start time is 09:00 America/New York,
179 using an old viewing time zone (@p oldSpec) of Europe/London, to a new
180 time zone (@p newSpec) of Europe/Paris, will result in the time being
181 shifted from 14:00 (which is the London time of the period start) to
182 14:00 Paris time.
183
184 @param oldSpec the time specification which provides the clock times
185 @param newSpec the new time specification
186 */
187 void shiftTimes( const KDateTime::Spec &oldSpec,
188 const KDateTime::Spec &newSpec );
189
190 private:
191 //@cond PRIVATE
192 class Private;
193 Private *const d;
194 //@endcond
195};
196
197}
198
199#endif
200