KCalendarCore

period.h
Go to the documentation of this file.
1/*
2 This file is part of the kcalcore library.
3
4 SPDX-FileCopyrightText: 2001-2003 Cornelius Schumacher <schumacher@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8/**
9 @file
10 This file is part of the API for handling calendar data and
11 defines the Period class.
12
13 @brief
14 Represents a period of time.
15
16 @author Cornelius Schumacher <schumacher@kde.org>
17*/
18#ifndef KCALCORE_PERIOD_H
19#define KCALCORE_PERIOD_H
20
21#include "duration.h"
22#include "kcalendarcore_export.h"
23
24#include <QDataStream>
25#include <QDateTime>
26#include <QList>
27#include <QMetaType>
28
29class QTimeZone;
30
31namespace KCalendarCore
32{
33/**
34 The period can be defined by either a start time and an end time or
35 by a start time and a duration.
36*/
37class KCALENDARCORE_EXPORT Period
38{
39public:
40 /**
41 List of periods.
42 */
44
45 /**
46 Constructs a period without a duration.
47 */
48 Period();
49
50 /**
51 Constructs a period from @p start to @p end.
52
53 @param start the time the period begins.
54 @param end the time the period ends.
55 */
56 Period(const QDateTime &start, const QDateTime &end);
57
58 /**
59 Constructs a period from @p start and lasting @p duration.
60
61 @param start the time when the period starts.
62 @param duration how long the period lasts.
63 */
64 Period(const QDateTime &start, const Duration &duration);
65
66 /**
67 Constructs a period by copying another period object
68
69 @param period the period to copy
70 */
71
72 Period(const Period &period);
73
74 /**
75 Destroys a period.
76 */
77 ~Period();
78
79 /**
80 Returns true if the start of this period is earlier than the start of
81 the @p other one.
82
83 @param other is the other period to compare.
84 */
85 bool operator<(const Period &other) const;
86
87 /**
88 Returns true if the start of this period is later than the start of
89 the @p other one.
90
91 @param other the other period to compare
92 */
93 bool operator>(const Period &other) const
94 {
95 return other.operator<(*this);
96 }
97
98 /**
99 Returns true if this period is equal to the @p other one.
100 Even if their start and end times are the same, two periods are
101 considered not equal if one is defined in terms of a duration and the
102 other in terms of a start and end time.
103
104 @param other the other period to compare
105 */
106 bool operator==(const Period &other) const;
107
108 /**
109 Returns true if this period is not equal to the @p other one.
110
111 @param other the other period to compare
112 @see operator==()
113 */
114 bool operator!=(const Period &other) const
115 {
116 return !operator==(other);
117 }
118
119 /**
120 Sets this period equal to the @p other one.
121
122 @param other is the other period to compare.
123 */
124 Period &operator=(const Period &other);
125
126 /**
127 Returns true if the Period is not empty.
128 @since 5.87
129 */
130 Q_REQUIRED_RESULT bool isValid() const;
131
132 /**
133 Returns when this period starts.
134 */
135 Q_REQUIRED_RESULT QDateTime start() const;
136
137 /**
138 Returns when this period ends.
139 */
140 Q_REQUIRED_RESULT QDateTime end() const;
141
142 /**
143 Returns the duration of the period.
144
145 If the period is defined in terms of a start and end time, the duration
146 is computed from these. In this case, if the time of day in @p start and
147 @p end is equal, and their time specifications (i.e. time zone etc.) are
148 the same, the duration will be set in terms of days. Otherwise, the
149 duration will be set in terms of seconds.
150
151 If the period is defined in terms of a duration, that duration is
152 returned unchanged.
153 */
154 Q_REQUIRED_RESULT Duration duration() const;
155
156 /**
157 Returns the duration of the period.
158
159 If the period is defined in terms of a start and end time, the duration
160 is first computed from these.
161
162 If @p type is Days, and the duration is not an exact number of days,
163 the duration will be rounded down to the nearest whole number of days.
164
165 @param type the unit of time to use (seconds or days)
166 */
167 Q_REQUIRED_RESULT Duration duration(Duration::Type type) const;
168
169 /**
170 Returns true if this period has a set duration, false
171 if it just has a start and an end.
172 */
173 Q_REQUIRED_RESULT bool hasDuration() const;
174
175 /**
176 Shift the times of the period so that they appear at the same clock
177 time as before but in a new time zone. The shift is done from a viewing
178 time zone rather than from the actual period time zone.
179
180 For example, shifting a period whose start time is 09:00 America/New York,
181 using an old viewing time zone (@p oldSpec) of Europe/London, to a new
182 time zone (@p newSpec) of Europe/Paris, will result in the time being
183 shifted from 14:00 (which is the London time of the period start) to
184 14:00 Paris time.
185
186 @param oldZone the time zone which provides the clock times
187 @param newZone the new time zone
188 */
189 void shiftTimes(const QTimeZone &oldZone, const QTimeZone &newZone);
190
191private:
192 //@cond PRIVATE
193 class Private;
194 Private *const d;
195 //@endcond
196
197 friend KCALENDARCORE_EXPORT QDataStream &operator<<(QDataStream &stream, const KCalendarCore::Period &period);
198
199 friend KCALENDARCORE_EXPORT QDataStream &operator>>(QDataStream &stream, KCalendarCore::Period &period);
200};
201
202/** Write @p period to the datastream @p stream, in binary format. */
203KCALENDARCORE_EXPORT QDataStream &operator<<(QDataStream &stream, const KCalendarCore::Period &period);
204
205/** Read a Period object into @p period from @p stream, in binary format. */
206KCALENDARCORE_EXPORT QDataStream &operator>>(QDataStream &stream, KCalendarCore::Period &period);
207
208/**
209 Return a hash value for a Period argument.
210 @param key is a Period.
211*/
212KCALENDARCORE_EXPORT size_t qHash(const KCalendarCore::Period &key, size_t seed = 0);
213}
214
215//@cond PRIVATE
216Q_DECLARE_METATYPE(KCalendarCore::Period)
217Q_DECLARE_TYPEINFO(KCalendarCore::Period, Q_RELOCATABLE_TYPE);
218//@endcond
219
220#endif
Represents a span of time measured in seconds or days.
Definition duration.h:44
Type
The unit of time used to define the duration.
Definition duration.h:49
The period can be defined by either a start time and an end time or by a start time and a duration.
Definition period.h:38
friend KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &stream, const KCalendarCore::Period &period)
Write period to the datastream stream, in binary format.
friend KCALENDARCORE_EXPORT QDataStream & operator>>(QDataStream &stream, KCalendarCore::Period &period)
Read a Period object into period from stream, in binary format.
bool operator!=(const Period &other) const
Returns true if this period is not equal to the other one.
Definition period.h:114
QList< Period > List
List of periods.
Definition period.h:43
bool operator>(const Period &other) const
Returns true if the start of this period is later than the start of the other one.
Definition period.h:93
This file is part of the API for handling calendar data and defines the Duration class.
Q_SCRIPTABLE Q_NOREPLY void start()
Namespace for all KCalendarCore types.
Definition alarm.h:37
KCALENDARCORE_EXPORT QDataStream & operator>>(QDataStream &in, const KCalendarCore::Alarm::Ptr &)
Alarm deserializer.
Definition alarm.cpp:833
KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &out, const KCalendarCore::Alarm::Ptr &)
Alarm serializer.
Definition alarm.cpp:820
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:13:47 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.