2
* datetime.h - date/time with start-of-day time for date-only values
4
* Copyright © 2003,2005-2007,2009 by David Jarvie <djarvie@kde.org>
6
* This program is free software; you can redistribute it and/or modify
7
* it under the terms of the GNU General Public License as published by
8
* the Free Software Foundation; either version 2 of the License, or
9
* (at your option) any later version.
11
* This program 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
14
* GNU General Public License for more details.
16
* You should have received a copy of the GNU General Public License along
17
* with this program; if not, write to the Free Software Foundation, Inc.,
18
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
23
#include "kalarm_cal_export.h"
25
#include <kdatetime.h>
29
* @short A KDateTime with date-only option.
31
* The DateTime class holds a date, with or without a time.
33
* DateTime is very similar to the KDateTime class. The time assumed for date-only values
34
* is the start-of-day time set by setStartOfDay().
36
* @author David Jarvie <djarvie@kde.org>
38
class KALARM_CAL_EXPORT DateTime
41
/** Default constructor.
42
* Constructs an invalid date-time.
45
/** Constructor for a date-only value. */
46
DateTime(const QDate& d, const KDateTime::Spec& spec)
47
: mDateTime(d, spec) { }
48
/** Constructor for a date-time value. */
49
DateTime(const QDate& d, const QTime& t, const KDateTime::Spec& spec)
50
: mDateTime(d, t, spec) { }
51
/** Constructor for a date-time value. */
52
DateTime(const QDateTime& dt, const KDateTime::Spec& spec)
53
: mDateTime(dt, spec) { }
54
/** Constructor for a date-time value. */
55
DateTime(const KDateTime& dt) : mDateTime(dt) { }
56
/** Assignment operator.
57
* Sets the value to a specified date-time.
59
DateTime& operator=(const KDateTime& dt)
60
{ mDateTime = dt; return *this; }
61
/** Returns true if the date is null and, if it is a date-time value, the time is also null. */
62
bool isNull() const { return mDateTime.isNull(); }
63
/** Returns true if the date is valid and, if it is a date-time value, the time is also valid. */
64
bool isValid() const { return mDateTime.isValid(); }
65
/** Returns true if it is date-only value. */
66
bool isDateOnly() const { return mDateTime.isDateOnly(); }
67
/** Returns the date part of the value. */
68
QDate date() const { return mDateTime.date(); }
69
/** Returns the date and time of the value.
70
* If the value is date-only, the time part returned is 00:00:00. */
71
QDateTime rawDateTime() const { return mDateTime.dateTime(); }
72
/** Returns the date and time of the value as a KDateTime. */
73
KDateTime kDateTime() const { return mDateTime; }
74
/** Returns the time part of the value.
75
* If the value is date-only, the time returned is the start-of-day time set by setStartOfDay().
77
QTime effectiveTime() const;
78
/** Returns the date and time of the value.
79
* If the value is date-only, the time part returned is equal to the start-of-day time set
82
QDateTime effectiveDateTime() const;
83
/** Returns the date and time of the value.
84
* If the value is date-only, the time part returned is equal to the start-of-day time set
87
KDateTime effectiveKDateTime() const;
88
/** Returns the date and time of the value as written in the calendar.
89
* If the value is date-only, the time part returned is 00:00.
91
KDateTime calendarKDateTime() const;
92
/** Returns the time zone of the value. */
93
KTimeZone timeZone() const { return mDateTime.timeZone(); }
94
/** Returns the time specification of the value. */
95
KDateTime::Spec timeSpec() const { return mDateTime.timeSpec(); }
96
/** Returns the time specification type of the date/time, i.e. whether it is
97
* UTC, has a time zone, etc. */
98
KDateTime::SpecType timeType() const { return mDateTime.timeType(); }
99
/** Returns whether the time zone for the date/time is the current local system time zone. */
100
bool isLocalZone() const { return mDateTime.isLocalZone(); }
101
/** Returns whether the date/time is a local clock time. */
102
bool isClockTime() const { return mDateTime.isClockTime(); }
103
/** Returns whether the date/time is a UTC time. */
104
bool isUtc() const { return mDateTime.isUtc(); }
105
/** Returns whether the date/time is a local time at a fixed offset from UTC. */
106
bool isOffsetFromUtc() const { return mDateTime.isOffsetFromUtc(); }
107
/** Returns the UTC offset associated with the date/time. */
108
int utcOffset() const { return mDateTime.utcOffset(); }
109
/** Returns whether the date/time is the second occurrence of this time. */
110
bool isSecondOccurrence() const { return mDateTime.isSecondOccurrence(); }
111
/** Returns the time converted to UTC. */
112
DateTime toUtc() const { return DateTime(mDateTime.toUtc()); }
113
/** Returns the time expressed as an offset from UTC, using the UTC offset
114
* associated with this instance's date/time. */
115
DateTime toOffsetFromUtc() const { return DateTime(mDateTime.toOffsetFromUtc()); }
116
/** Returns the time expressed as a specified offset from UTC. */
117
DateTime toOffsetFromUtc(int utcOffset) const { return DateTime(mDateTime.toOffsetFromUtc(utcOffset)); }
118
/** Returns the time converted to the current local system time zone. */
119
DateTime toLocalZone() const { return DateTime(mDateTime.toLocalZone()); }
120
/** Returns the time converted to the local clock time. */
121
DateTime toClockTime() const { return DateTime(mDateTime.toClockTime()); }
122
/** Returns the time converted to a specified time zone. */
123
DateTime toZone(const KTimeZone& zone) const { return DateTime(mDateTime.toZone(zone)); }
124
/** Returns the time converted to a new time specification. */
125
DateTime toTimeSpec(const KDateTime::Spec &spec) const { return DateTime(mDateTime.toTimeSpec(spec)); }
126
/** Converts the time to a UTC time, measured in seconds since 00:00:00 UTC
127
* 1st January 1970 (as returned by time(2)). */
128
uint toTime_t() const { return mDateTime.toTime_t(); }
129
/** Sets the value to be either date-only or date-time.
130
* @param d True to set the value to be date-only; false to set it to a date-time value.
132
void setDateOnly(bool d) { mDateTime.setDateOnly(d); }
133
/** Sets the date component of the value. */
134
void setDate(const QDate& d) { mDateTime.setDate(d); }
135
/** Sets the time component of the value.
136
* The value is converted if necessary to be a date-time value. */
137
void setTime(const QTime& t) { mDateTime.setTime(t); }
138
/** Sets the date/time component of the value. */
139
void setDateTime(const QDateTime& dt) { mDateTime.setDateTime(dt); }
140
/** Changes the time specification of the value. */
141
void setTimeSpec(const KDateTime::Spec &spec) { mDateTime.setTimeSpec(spec); }
142
/** Sets whether this is the second occurrence of this date/time. */
143
void setSecondOccurrence(bool second) { mDateTime.setSecondOccurrence(second); }
144
/** Sets the value to a specified date-time value.
145
* @param secs The time_t date-time value, expressed as the number of seconds elapsed
146
* since 1970-01-01 00:00:00 UTC.
148
void setTime_t(uint secs) { mDateTime.setTime_t(secs); }
149
/** Returns a DateTime value @p secs seconds later than the value of this object. */
150
DateTime addSecs(qint64 n) const { return DateTime(mDateTime.addSecs(n)); }
151
/** Returns a DateTime value @p mins minutes later than the value of this object. */
152
DateTime addMins(qint64 n) const { return DateTime(mDateTime.addSecs(n * 60)); }
153
/** Returns a DateTime value @p n days later than the value of this object. */
154
DateTime addDays(int n) const { return DateTime(mDateTime.addDays(n)); }
155
/** Returns a DateTime value @p n months later than the value of this object. */
156
DateTime addMonths(int n) const { return DateTime(mDateTime.addMonths(n)); }
157
/** Returns a DateTime value @p n years later than the value of this object. */
158
DateTime addYears(int n) const { return DateTime(mDateTime.addYears(n)); }
159
/** Returns the number of days from this date or date-time to @p dt. */
160
int daysTo(const DateTime& dt) const { return mDateTime.daysTo(dt.mDateTime); }
161
/** Returns the number of minutes from this date or date-time to @p dt. */
162
int minsTo(const DateTime& dt) const { return mDateTime.secsTo(dt.mDateTime) / 60; }
163
/** Returns the number of seconds from this date or date-time to @p dt. */
164
int secsTo(const DateTime& dt) const { return mDateTime.secsTo(dt.mDateTime); }
165
qint64 secsTo_long(const DateTime& dt) const { return mDateTime.secsTo_long(dt.mDateTime); }
166
/** Returns the value as a string.
167
* If it is a date-time, both time and date are included in the output.
168
* If it is date-only, only the date is included in the output.
170
QString toString(Qt::DateFormat f = Qt::TextDate) const
172
if (mDateTime.isDateOnly())
173
return mDateTime.date().toString(f);
175
return mDateTime.dateTime().toString(f);
177
/** Returns the value as a string.
178
* If it is a date-time, both time and date are included in the output.
179
* If it is date-only, only the date is included in the output.
181
QString toString(const QString& format) const
183
if (mDateTime.isDateOnly())
184
return mDateTime.date().toString(format);
186
return mDateTime.dateTime().toString(format);
188
/** Returns the value as a string, formatted according to the user's locale.
189
* If it is a date-time, both time and date are included in the output.
190
* If it is date-only, only the date is included in the output.
192
QString formatLocale(bool shortFormat = true) const;
193
/** Sets the start-of-day time.
194
* The default value is midnight (0000 hrs).
196
static void setStartOfDay(const QTime& sod) { mStartOfDay = sod; }
197
/** Compare this value with another. */
198
KDateTime::Comparison compare(const DateTime &other) const { return mDateTime.compare(other.mDateTime); }
199
/** Returns the start-of-day time. */
200
static QTime startOfDay() { return mStartOfDay; }
202
friend bool operator==(const DateTime& dt1, const DateTime& dt2);
203
friend bool operator==(const KDateTime& dt1, const DateTime& dt2);
204
KALARM_CAL_EXPORT friend bool operator<(const DateTime& dt1, const DateTime& dt2);
205
friend bool operator<(const KDateTime& dt1, const DateTime& dt2);
208
static QTime mStartOfDay;
212
/** Returns true if the two values are equal. */
213
inline bool operator==(const DateTime& dt1, const DateTime& dt2) { return dt1.mDateTime == dt2.mDateTime; }
214
inline bool operator==(const KDateTime& dt1, const DateTime& dt2) { return dt1 == dt2.mDateTime; }
215
/** Returns true if the two values are not equal. */
216
inline bool operator!=(const DateTime& dt1, const DateTime& dt2) { return !operator==(dt1, dt2); }
217
inline bool operator!=(const KDateTime& dt1, const DateTime& dt2) { return !operator==(dt1, dt2); }
218
/** Returns true if the @p dt1 is earlier than @p dt2.
219
* If the two values have the same date, and one value is date-only while the other is a date-time, the
220
* time used for the date-only value is the start-of-day time set in the KAlarm Preferences dialog.
222
KALARM_CAL_EXPORT bool operator<(const DateTime& dt1, const DateTime& dt2);
223
inline bool operator<(const KDateTime& dt1, const DateTime& dt2) { return operator<(DateTime(dt1), dt2); }
224
/** Returns true if the @p dt1 is later than @p dt2.
225
* If the two values have the same date, and one value is date-only while the other is a date-time, the
226
* time used for the date-only value is the start-of-day time set in the KAlarm Preferences dialog.
228
inline bool operator>(const DateTime& dt1, const DateTime& dt2) { return operator<(dt2, dt1); }
229
inline bool operator>(const KDateTime& dt1, const DateTime& dt2) { return operator<(dt2, DateTime(dt1)); }
230
/** Returns true if the @p dt1 is later than or equal to @p dt2.
231
* If the two values have the same date, and one value is date-only while the other is a date-time, the
232
* time used for the date-only value is the start-of-day time set in the KAlarm Preferences dialog.
234
inline bool operator>=(const DateTime& dt1, const DateTime& dt2) { return !operator<(dt1, dt2); }
235
inline bool operator>=(const KDateTime& dt1, const DateTime& dt2) { return !operator<(DateTime(dt1), dt2); }
236
/** Returns true if the @p dt1 is earlier than or equal to @p dt2.
237
* If the two values have the same date, and one value is date-only while the other is a date-time, the
238
* time used for the date-only value is the start-of-day time set in the KAlarm Preferences dialog.
240
inline bool operator<=(const DateTime& dt1, const DateTime& dt2) { return !operator<(dt2, dt1); }
241
inline bool operator<=(const KDateTime& dt1, const DateTime& dt2) { return !operator<(dt2, DateTime(dt1)); }
added
removed
kalarm/cal/datetime.h
