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

KDE's Doxygen guidelines are available online.