Your IP : 216.73.216.48
/*
* 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: