mirror of
https://bitbucket.org/smil3y/kde-playground.git
synced 2025-02-23 18:32:51 +00:00
267 lines
12 KiB
C++
267 lines
12 KiB
C++
/*
|
|
* datetime.h - date/time with start-of-day time for date-only values
|
|
* This file is part of kalarmcal library, which provides access to KAlarm
|
|
* calendar data.
|
|
* Copyright © 2003,2005-2007,2009,2011 by David Jarvie <djarvie@kde.org>
|
|
*
|
|
* This library is free software; you can redistribute it and/or modify
|
|
* it under the terms of the GNU Library General Public License as published
|
|
* by the Free Software Foundation; either version 2 of the License, or (at
|
|
* your option) any later version.
|
|
*
|
|
* This library is distributed in the hope that it will be useful, but WITHOUT
|
|
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
|
|
* License for more details.
|
|
*
|
|
* You should have received a copy of the GNU Library General Public License
|
|
* along with this library; see the file COPYING.LIB. If not, write to the
|
|
* Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
|
|
* MA 02110-1301, USA.
|
|
*/
|
|
#ifndef KALARM_DATETIME_H
|
|
#define KALARM_DATETIME_H
|
|
|
|
#include "kalarmcal_export.h"
|
|
|
|
#include <kdatetime.h>
|
|
|
|
namespace KAlarmCal
|
|
{
|
|
|
|
/**
|
|
* @short As KDateTime, but with a configurable start-of-day time for date-only values.
|
|
*
|
|
* The DateTime class holds a date, with or without a time.
|
|
*
|
|
* DateTime is very similar to the KDateTime class. The time assumed for date-only values
|
|
* is the start-of-day time set by setStartOfDay().
|
|
*
|
|
* @author David Jarvie <djarvie@kde.org>
|
|
*/
|
|
class KALARMCAL_EXPORT DateTime
|
|
{
|
|
public:
|
|
/** Default constructor.
|
|
* Constructs an invalid date-time.
|
|
*/
|
|
DateTime();
|
|
/** Constructor for a date-only value. */
|
|
DateTime(const QDate& d, const KDateTime::Spec& spec);
|
|
/** Constructor for a date-time value. */
|
|
DateTime(const QDate& d, const QTime& t, const KDateTime::Spec& spec);
|
|
/** Constructor for a date-time value. */
|
|
DateTime(const QDateTime& dt, const KDateTime::Spec& spec);
|
|
/** Constructor for a date-time value. */
|
|
DateTime(const KDateTime& dt);
|
|
/** Copy constructor. */
|
|
DateTime(const DateTime& dt);
|
|
|
|
~DateTime();
|
|
/** Assignment operator. */
|
|
DateTime& operator=(const DateTime& dt);
|
|
/** Assignment operator.
|
|
* Sets the value to a specified date-time.
|
|
*/
|
|
DateTime& operator=(const KDateTime& dt);
|
|
|
|
/** Returns true if the date is null and, if it is a date-time value, the time is also null. */
|
|
bool isNull() const;
|
|
/** Returns true if the date is valid and, if it is a date-time value, the time is also valid. */
|
|
bool isValid() const;
|
|
/** Returns true if it is date-only value. */
|
|
bool isDateOnly() const;
|
|
/** Sets the value to be either date-only or date-time.
|
|
* @param d True to set the value to be date-only; false to set it to a date-time value.
|
|
*/
|
|
void setDateOnly(bool d);
|
|
|
|
/** Returns the date part of the value. */
|
|
QDate date() const;
|
|
/** Sets the date component of the value. */
|
|
void setDate(const QDate& d);
|
|
|
|
/** Returns the date and time of the value.
|
|
* If the value is date-only, the time part returned is 00:00:00. */
|
|
QDateTime rawDateTime() const;
|
|
/** Returns the date and time of the value as a KDateTime. */
|
|
KDateTime kDateTime() const;
|
|
/** Returns the time part of the value.
|
|
* If the value is date-only, the time returned is the start-of-day time set by setStartOfDay().
|
|
*/
|
|
QTime effectiveTime() const;
|
|
/** Sets the time component of the value.
|
|
* The value is converted if necessary to be a date-time value. */
|
|
void setTime(const QTime& t);
|
|
/** Returns the date and time of the value.
|
|
* If the value is date-only, the time part returned is equal to the start-of-day time set
|
|
* by setStartOfDay().
|
|
*/
|
|
QDateTime effectiveDateTime() const;
|
|
/** Sets the date/time component of the value. */
|
|
void setDateTime(const QDateTime& dt);
|
|
|
|
/** Returns the date and time of the value.
|
|
* If the value is date-only, the time part returned is equal to the start-of-day time set
|
|
* by setStartOfDay().
|
|
*/
|
|
KDateTime effectiveKDateTime() const;
|
|
/** Returns the date and time of the value as written in the calendar.
|
|
* If the value is date-only, the time part returned is 00:00.
|
|
*/
|
|
KDateTime calendarKDateTime() const;
|
|
|
|
/** Returns the time zone of the value. */
|
|
KTimeZone timeZone() const;
|
|
/** Returns the time specification of the value. */
|
|
KDateTime::Spec timeSpec() const;
|
|
/** Changes the time specification of the value. */
|
|
void setTimeSpec(const KDateTime::Spec &spec);
|
|
/** Returns the time specification type of the date/time, i.e. whether it is
|
|
* UTC, has a time zone, etc. */
|
|
KDateTime::SpecType timeType() const;
|
|
/** Returns whether the time zone for the date/time is the current local system time zone. */
|
|
bool isLocalZone() const;
|
|
/** Returns whether the date/time is a local clock time. */
|
|
bool isClockTime() const;
|
|
/** Returns whether the date/time is a UTC time. */
|
|
bool isUtc() const;
|
|
/** Returns whether the date/time is a local time at a fixed offset from UTC. */
|
|
bool isOffsetFromUtc() const;
|
|
/** Returns the UTC offset associated with the date/time. */
|
|
int utcOffset() const;
|
|
|
|
/** Returns whether the date/time is the second occurrence of this time. */
|
|
bool isSecondOccurrence() const;
|
|
/** Sets whether this is the second occurrence of this date/time. */
|
|
void setSecondOccurrence(bool second);
|
|
|
|
/** Returns the time converted to UTC. */
|
|
DateTime toUtc() const;
|
|
/** Returns the time expressed as an offset from UTC, using the UTC offset
|
|
* associated with this instance's date/time. */
|
|
DateTime toOffsetFromUtc() const;
|
|
/** Returns the time expressed as a specified offset from UTC. */
|
|
DateTime toOffsetFromUtc(int utcOffset) const;
|
|
/** Returns the time converted to the current local system time zone. */
|
|
DateTime toLocalZone() const;
|
|
/** Returns the time converted to the local clock time. */
|
|
DateTime toClockTime() const;
|
|
/** Returns the time converted to a specified time zone. */
|
|
DateTime toZone(const KTimeZone& zone) const;
|
|
/** Returns the time converted to a new time specification. */
|
|
DateTime toTimeSpec(const KDateTime::Spec &spec) const;
|
|
|
|
/** Converts the time to a UTC time, measured in seconds since 00:00:00 UTC
|
|
* 1st January 1970 (as returned by time(2)). */
|
|
uint toTime_t() const;
|
|
/** Sets the value to a specified date-time value.
|
|
* @param secs The time_t date-time value, expressed as the number of seconds elapsed
|
|
* since 1970-01-01 00:00:00 UTC.
|
|
*/
|
|
void setTime_t(uint secs);
|
|
|
|
/** Returns a DateTime value @p secs seconds later than the value of this object. */
|
|
DateTime addSecs(qint64 n) const;
|
|
/** Returns a DateTime value @p mins minutes later than the value of this object. */
|
|
DateTime addMins(qint64 n) const;
|
|
/** Returns a DateTime value @p n days later than the value of this object. */
|
|
DateTime addDays(int n) const;
|
|
/** Returns a DateTime value @p n months later than the value of this object. */
|
|
DateTime addMonths(int n) const;
|
|
/** Returns a DateTime value @p n years later than the value of this object. */
|
|
DateTime addYears(int n) const;
|
|
|
|
/** Returns the number of days from this date or date-time to @p dt. */
|
|
int daysTo(const DateTime& dt) const;
|
|
/** Returns the number of minutes from this date or date-time to @p dt. */
|
|
int minsTo(const DateTime& dt) const;
|
|
/** Returns the number of seconds from this date or date-time to @p dt.
|
|
*
|
|
* @warning The return value can overflow if the two values are far enough
|
|
* apart. Use sectTo_long() to avoid this.
|
|
*/
|
|
int secsTo(const DateTime& dt) const;
|
|
/** Returns the number of seconds as a qint64 from this date or date-time to @p dt. */
|
|
qint64 secsTo_long(const DateTime& dt) const;
|
|
|
|
/** Returns the value as a string.
|
|
* If it is a date-time, both time and date are included in the output.
|
|
* If it is date-only, only the date is included in the output.
|
|
*/
|
|
QString toString(Qt::DateFormat f = Qt::TextDate) const;
|
|
/** Returns the value as a string.
|
|
* If it is a date-time, both time and date are included in the output.
|
|
* If it is date-only, only the date is included in the output.
|
|
*/
|
|
QString toString(const QString& format) const;
|
|
/** Returns the value as a string, formatted according to the user's locale.
|
|
* If it is a date-time, both time and date are included in the output.
|
|
* If it is date-only, only the date is included in the output.
|
|
*/
|
|
QString formatLocale(bool shortFormat = true) const;
|
|
|
|
/** Sets the start-of-day time.
|
|
* The default value is midnight (0000 hrs).
|
|
*/
|
|
static void setStartOfDay(const QTime& sod);
|
|
|
|
/** Returns the start-of-day time. */
|
|
static QTime startOfDay();
|
|
|
|
/** Compare this value with another. */
|
|
KDateTime::Comparison compare(const DateTime &other) const;
|
|
|
|
KALARMCAL_EXPORT friend bool operator==(const KAlarmCal::DateTime& dt1, const KAlarmCal::DateTime& dt2);
|
|
KALARMCAL_EXPORT friend bool operator==(const KDateTime& dt1, const KAlarmCal::DateTime& dt2);
|
|
KALARMCAL_EXPORT friend bool operator<(const KAlarmCal::DateTime& dt1, const KAlarmCal::DateTime& dt2);
|
|
friend bool operator<(const KDateTime& dt1, const KAlarmCal::DateTime& dt2);
|
|
|
|
private:
|
|
//@cond PRIVATE
|
|
class Private;
|
|
Private* const d;
|
|
//@endcond
|
|
};
|
|
|
|
/** Returns true if the two values are equal. */
|
|
KALARMCAL_EXPORT bool operator==(const DateTime& dt1, const DateTime& dt2);
|
|
KALARMCAL_EXPORT bool operator==(const KDateTime& dt1, const DateTime& dt2);
|
|
|
|
/** Returns true if the two values are not equal. */
|
|
inline bool operator!=(const DateTime& dt1, const DateTime& dt2) { return !operator==(dt1, dt2); }
|
|
inline bool operator!=(const KDateTime& dt1, const DateTime& dt2) { return !operator==(dt1, dt2); }
|
|
|
|
/** Returns true if the @p dt1 is earlier than @p dt2.
|
|
* If the two values have the same date, and one value is date-only while the other is a date-time, the
|
|
* time used for the date-only value is the start-of-day time set in the KAlarm Preferences dialog.
|
|
*/
|
|
KALARMCAL_EXPORT bool operator<(const DateTime& dt1, const DateTime& dt2);
|
|
inline bool operator<(const KDateTime& dt1, const DateTime& dt2) { return operator<(DateTime(dt1), dt2); }
|
|
|
|
/** Returns true if the @p dt1 is later than @p dt2.
|
|
* If the two values have the same date, and one value is date-only while the other is a date-time, the
|
|
* time used for the date-only value is the start-of-day time set in the KAlarm Preferences dialog.
|
|
*/
|
|
inline bool operator>(const DateTime& dt1, const DateTime& dt2) { return operator<(dt2, dt1); }
|
|
inline bool operator>(const KDateTime& dt1, const DateTime& dt2) { return operator<(dt2, DateTime(dt1)); }
|
|
|
|
/** Returns true if the @p dt1 is later than or equal to @p dt2.
|
|
* If the two values have the same date, and one value is date-only while the other is a date-time, the
|
|
* time used for the date-only value is the start-of-day time set in the KAlarm Preferences dialog.
|
|
*/
|
|
inline bool operator>=(const DateTime& dt1, const DateTime& dt2) { return !operator<(dt1, dt2); }
|
|
inline bool operator>=(const KDateTime& dt1, const DateTime& dt2) { return !operator<(DateTime(dt1), dt2); }
|
|
|
|
/** Returns true if the @p dt1 is earlier than or equal to @p dt2.
|
|
* If the two values have the same date, and one value is date-only while the other is a date-time, the
|
|
* time used for the date-only value is the start-of-day time set in the KAlarm Preferences dialog.
|
|
*/
|
|
inline bool operator<=(const DateTime& dt1, const DateTime& dt2) { return !operator<(dt2, dt1); }
|
|
inline bool operator<=(const KDateTime& dt1, const DateTime& dt2) { return !operator<(dt2, DateTime(dt1)); }
|
|
|
|
} // namespace KAlarmCal
|
|
|
|
#endif // KALARM_DATETIME_H
|
|
|
|
// vim: et sw=4:
|