KAlarmCal::KADateTime

#include <kadatetime.h>

Classes

class  Spec
 

Public Types

enum  Comparison {
  Before = 0x01, AtStart = 0x02, Inside = 0x04, AtEnd = 0x08,
  After = 0x10, Equal = AtStart | Inside | AtEnd, Outside = Before | AtStart | Inside | AtEnd | After, StartsAt = AtStart | Inside | AtEnd | After,
  EndsAt = Before | AtStart | Inside | AtEnd
}
 
enum  SpecType {
  Invalid, UTC, OffsetFromUTC, TimeZone,
  LocalZone
}
 
enum  TimeFormat {
  ISODate, ISODateFull, RFCDate, RFCDateDay,
  QtTextDate, LocalDate, RFC3339Date
}
 

Public Member Functions

 KADateTime ()
 
 KADateTime (const QDate &date, const Spec &spec=Spec(LocalZone))
 
 KADateTime (const QDate &date, const QTime &time, const Spec &spec=Spec(LocalZone))
 
 KADateTime (const QDateTime &dt, const Spec &spec)
 
 KADateTime (const QDateTime &dt)
 
 KADateTime (const KADateTime &other)
 
KADateTime addDays (qint64 days) const
 
KADateTime addMonths (int months) const
 
KADateTime addMSecs (qint64 msecs) const
 
KADateTime addSecs (qint64 secs) const
 
KADateTime addYears (int years) const
 
Comparison compare (const KADateTime &other) const
 
QDate date () const
 
qint64 daysTo (const KADateTime &other) const
 
void detach ()
 
bool isDateOnly () const
 
bool isLocalZone () const
 
bool isNull () const
 
bool isOffsetFromUtc () const
 
bool isSecondOccurrence () const
 
bool isUtc () const
 
bool isValid () const
 
qint64 msecsTo (const KADateTime &other) const
 
bool operator!= (const KADateTime &other) const
 
bool operator< (const KADateTime &other) const
 
bool operator<= (const KADateTime &other) const
 
KADateTimeoperator= (const KADateTime &other)
 
bool operator== (const KADateTime &other) const
 
bool operator> (const KADateTime &other) const
 
bool operator>= (const KADateTime &other) const
 
QDateTime qDateTime () const
 
qint64 secsTo (const KADateTime &other) const
 
void setDate (const QDate &date)
 
void setDateOnly (bool dateOnly)
 
void setSecondOccurrence (bool second)
 
void setSecsSinceEpoch (qint64 seconds)
 
void setTime (const QTime &time)
 
KALARMCAL_DEPRECATED void setTime_t (qint64 seconds)
 
void setTimeSpec (const Spec &spec)
 
QTime time () const
 
Spec timeSpec () const
 
SpecType timeType () const
 
QTimeZone timeZone () const
 
KADateTime toLocalZone () const
 
KADateTime toOffsetFromUtc () const
 
KADateTime toOffsetFromUtc (int utcOffset) const
 
qint64 toSecsSinceEpoch () const
 
QString toString (const QString &format) const
 
QString toString (TimeFormat format=ISODate) const
 
KALARMCAL_DEPRECATED uint toTime_t () const
 
KADateTime toTimeSpec (const Spec &spec) const
 
KADateTime toTimeSpec (const KADateTime &dt) const
 
KADateTime toUtc () const
 
KADateTime toZone (const QTimeZone &zone) const
 
int utcOffset () const
 

Static Public Member Functions

static KADateTime currentDateTime (const Spec &spec)
 
static QDate currentLocalDate ()
 
static KADateTime currentLocalDateTime ()
 
static QTime currentLocalTime ()
 
static KADateTime currentUtcDateTime ()
 
static KADateTime fromString (const QString &string, TimeFormat format=ISODate, bool *negZero=nullptr)
 
static KADateTime fromString (const QString &string, const QString &format, const QList< QTimeZone > *zones=nullptr, bool offsetIfAmbiguous=true)
 
static KADateTime realCurrentLocalDateTime ()
 
static void setFromStringDefault (const Spec &spec)
 
static void setSimulatedSystemTime (const KADateTime &newTime)
 

Friends

QDataStreamoperator<< (QDataStream &out, const KADateTime &dateTime)
 
QDataStreamoperator>> (QDataStream &in, KADateTime &dateTime)
 

Detailed Description

A class representing a date and time with an associated time zone.

Topics:

intro

The class KADateTime extends the functionality of QDateTime. It combines a date and time with support for an associated time zone or UTC offset. When manipulating KADateTime objects, their time zones or UTC offsets are automatically taken into account. Extensions to QDateTime are:

  • KADateTime can be set to represent a date-only value with no associated time.
  • Local date/times which occur twice due to daylight savings time shifts, are handled properly, so that the two occurrences can be distinguished.
  • Extra string formatting functions are provided.

The class uses QDateTime internally to represent date/time values. This imposes the following limitations:

  • QDateTime uses the Gregorian calendar retroactively. If you need the Julian calendar for historical dates (as commonly used prior to some date between 1582 and 1923 depending on nation), please use KCalendarSystem and related classes.
  • QDateTime does not handle daylight savings time changes properly before 1970, even when the system's time zone database contains this information.

The time specification types which KADateTime supports are:

  • the UTC time zone
  • a local time with a specified offset from UTC
  • a local time in a specified time zone
  • a local time using the current system time zone. This follows any changes to the system time zone.

These characteristics are more fully described in the description of the SpecType enumeration. Also see W3C: Working with Time Zones for a good overview of the different ways of representing times.

To set the time specification, use one of the setTimeSpec() methods. To get the time specification, call timeSpec(), isUtc(), isLocalZone(), or isOffsetFromUtc(). To determine whether two KADateTime instances have the same time specification, call timeSpec() on each and compare the returned values using KADateTime::Spec::operator==().

manipulation

A KADateTime object can be created by passing a date and time in its constructor, together with a time specification.

If both the date and time are null, isNull() returns true. If the date, time and time specification are all valid, isValid() returns true.

A KADateTime object can be converted to a different time specification by using toUtc() or toLocalZone(). It can be converted to a specific time zone by toZone(). To return the time as an elapsed time since 1 January 1970 (as used by time(2)), use toSecsSinceEpoch(). The results of time zone conversions are cached to minimize the need for recalculation. Each KADateTime object caches its UTC equivalent and the last time zone conversion performed.

The date and time can be set either in the constructor, or afterwards by calling setDate() or setTime(). To return the date and/or time components of the KADateTime, use date(), time() and qDateTime(). You can determine whether the KADateTime represents a date and time, or a date only, by isDateOnly(). You can change between a date and time or a date only value using setDateOnly().

You can increment or decrement the date/time using addSecs(), addDays(), addMonths() and addYears(). The interval between two date/time values can be found using secsTo() or daysTo().

The comparison operators (operator==(), operator<(), etc.) all take the time zone properly into account; if the two KADateTime objects have different time zones, they are first converted to UTC before the comparison is performed. An alternative to the comparison operators is compare() which will in addition tell you if a KADateTime object overlaps with another when one or both are date-only values.

KADateTime values may be converted to and from a string representation using the toString() and fromString() methods. These handle a variety of text formats including ISO 8601 and RFC 2822.

KADateTime uses Qt's facilities to implicitly share data. Copying instances is very efficient, and copied instances share cached UTC and time zone conversions even after the copy is performed. A separate copy of the data is created whenever a non-const method is called. If you want to force the creation of a separate copy of the data (e.g. if you want two copies to cache different time zone conversions), call detach().

compatibility

KADateTime's interface is designed to be as compatible as possible with that of QDateTime. Because QDateTime lacks virtual methods, KADateTime is not inherited from QDateTime, but instead is implemented using a private QDateTime object.

simulation

This class provides a facility to simulate the local system time, which affects all functions using or returning the system time. This facility is provided for testing purposes only, and is only available if the library is compiled with debug enabled. In release mode, simulation is inoperative and the real local system time is used at all times. Use setSimulatedSystemTime() to set or clear the simulated time. To read the real (not simulated) system time, use realCurrentLocalDateTime().

See also
QTimeZone, QDateTime, QDate, QTime
W3C: Working with Time Zones
Author
David Jarvie <djarv[email protected][email protected][email protected]de.or[email protected]g>.

Definition at line 145 of file kadatetime.h.

Member Enumeration Documentation

How this KADateTime compares with another.

If any date-only value is involved, comparison of KADateTime values requires them to be considered as representing time periods. A date-only instance represents a time period from 00:00:00 to 23:59:59.999 on a given date, while a date/time instance can be considered to represent a time period whose start and end times are the same. They may therefore be earlier or later, or may overlap or be contained one within the other.

Values may be OR'ed with each other in any combination of 'consecutive' intervals to represent different types of relationship.

In the descriptions of the values below,

  • s1 = start time of this instance
  • e1 = end time of this instance
  • s2 = start time of other instance
  • e2 = end time of other instance.
Enumerator
Before 

This KADateTime is strictly earlier than the other, i.e.

e1 < s2.

AtStart 

This KADateTime starts at the same time as the other, and ends before the end of the other, i.e.

s1 = s2, e1 < e2.

Inside 

This KADateTime starts after the start of the other, and ends before the end of the other, i.e.

s1 > s2, e1 < e2.

AtEnd 

This KADateTime starts after the start of the other, and ends at the same time as the other, i.e.

s1 > s2, e1 = e2.

After 

This KADateTime is strictly later than the other, i.e.

s1 > e2.

Equal 

Simultaneous, i.e.

s1 = s2 && e1 = e2.

Outside 

This KADateTime starts before the start of the other, and ends after the end of the other, i.e.

s1 < s2, e1 > e2.

StartsAt 

This KADateTime starts at the same time as the other, and ends after the end of the other, i.e.

s1 = s2, e1 > e2.

EndsAt 

This KADateTime starts before the start of the other, and ends at the same time as the other, i.e.

s1 < s2, e1 = e2.

Definition at line 429 of file kadatetime.h.

The time specification type of a KADateTime instance.

This specifies how the date/time component of the KADateTime instance should be interpreted, i.e. what type of time zone (if any) the date/time is expressed in. For the full time specification (including time zone details), see KADateTime::Spec.

Enumerator
Invalid 

an invalid time specification.

UTC 

a UTC time.

OffsetFromUTC 

a local time which has a fixed offset from UTC.

TimeZone 

a time in a specified time zone.

If the time zone happens to be the current system time zone (i.e. that returned by QTimeZone::systemTimeZone()), that time zone will continue to be used, unlike in the case of LocalZone, even if the system changes to use a different time zone.

LocalZone 

a time in the current system time zone.

Note that if the system is changed to a different time zone afterwards, the KADateTime instance will then use the new system time zone, as returned currently by QTimeZone::systemTimeZone().

Definition at line 155 of file kadatetime.h.

Format for strings representing date/time values.

Enumerator
ISODate 

ISO 8601 format, i.e.

[±]YYYY-MM-DDThh[:mm[:ss[.sss]]]TZ, where TZ is the time zone offset (blank for local time, Z for UTC, or ±hhmm for an offset from UTC). When parsing a string, the ISO 8601 basic format, [±]YYYYMMDDThh[mm[ss[.sss]]]TZ, is also accepted. For date-only values, the formats [±]YYYY-MM-DD and [±]YYYYMMDD (without time zone specifier) are used. All formats may contain a day of the year instead of day and month. To allow for years past 9999, the year may optionally contain more than 4 digits. To avoid ambiguity, this is not allowed in the basic format containing a day of the year (i.e. when the date part is [±]YYYYDDD).

ISODateFull 

ISO 8601 format, always including a time zone.

This is the same as ISODate, except that the current system time zone offset is appended for local times (type LocalZone).

RFCDate 

RFC 2822 format, i.e.

"[Wdy,] DD Mon YYYY hh:mm[:ss] ±hhmm". This format also covers RFCs 822, 850, 1036 and 1123. When parsing a string, it also accepts the format "Wdy Mon DD HH:MM:SS YYYY" specified by RFCs 850 and

  1. There is no valid date-only format.
RFCDateDay 

RFC 2822 format including day of the week, i.e.

"Wdy, DD Mon YYYY hh:mm:ss ±hhmm"

QtTextDate 

Same format as Qt::TextDate (i.e.

Day Mon DD hh:mm:ss YYYY) with, if not local time, the UTC offset appended. The time may be omitted to indicate a date-only value.

LocalDate 

Same format as Qt::LocalDate (i.e.

locale dependent) with, if not local time, the UTC offset appended. The time may be omitted to indicate a date-only value.

RFC3339Date 

RFC 3339 format, i.e.

"YYYY-MM-DDThh:mm:ss[.sss](Z|±hh:mm)". There is no valid date-only format.

Definition at line 366 of file kadatetime.h.

Constructor & Destructor Documentation

KAlarmCal::KADateTime::KADateTime ( )

Constructs an invalid date/time.

Definition at line 878 of file kadatetime.cpp.

KAlarmCal::KADateTime::KADateTime ( const QDate date,
const Spec spec = Spec(LocalZone) 
)
explicit

Constructs a date-only value expressed in a given time specification.

The time is set to 00:00:00.

The instance is initialised according to the time specification type of spec as follows:

  • UTC : date is stored as UTC.
  • OffsetFromUTC : date is a local time at the specified offset from UTC.
  • TimeZone : date is a local time in the specified time zone.
  • LocalZone : date is a local date in whatever the system time zone is currently.
Parameters
datedate in the time zone indicated by spec
spectime specification

Definition at line 883 of file kadatetime.cpp.

KAlarmCal::KADateTime::KADateTime ( const QDate date,
const QTime time,
const Spec spec = Spec(LocalZone) 
)

Constructs a date/time expressed as specified by spec.

date and time are interpreted and stored according to the value of spec as follows:

  • UTC : date and time are in UTC.
  • OffsetFromUTC : date/time is a local time at the specified offset from UTC.
  • TimeZone : date/time is a local time in the specified time zone.
  • LocalZone : date and time are local times in whatever the system time zone is currently.
Parameters
datedate in the time zone indicated by spec
timetime in the time zone indicated by spec
spectime specification

Definition at line 888 of file kadatetime.cpp.

KAlarmCal::KADateTime::KADateTime ( const QDateTime dt,
const Spec spec 
)

Constructs a date/time expressed in a given time specification.

In detail, dt is interpreted and stored according to the time specification type of spec as follows:

  • UTC : dt is stored as a UTC value. If dt.timeSpec() is not Qt::UTC, dt is first converted to UTC before storage.
  • OffsetFromUTC : date/time is stored as a time at the specified offset from UTC. If dt.timeSpec() is not Qt::UTC, the time is converted to UTC and then adjusted by the UTC offset before storage.
  • TimeZone : date/time is stored as a local time in the specified time zone. If dt.timeSpec() is not the same time zone, dt is converted to the specified time zone before storage.
  • LocalZone : dt is stored as a local time in the current system time zone. If dt.timeSpec() is not Qt::LocalTime, dt is first converted to the system time zone before storage.
Parameters
dtdate and time
spectime specification

Definition at line 893 of file kadatetime.cpp.

KAlarmCal::KADateTime::KADateTime ( const QDateTime dt)
explicit

Constructs a date/time from a QDateTime.

The KADateTime's time specification is determined according to dt.timeSpec().

Parameters
dtdate and time

Definition at line 898 of file kadatetime.cpp.

Member Function Documentation

KADateTime KAlarmCal::KADateTime::addDays ( qint64  days) const

Returns a date/time days days later than the stored date/time.

The result is expressed using the same time specification as the original instance.

Returns
resultant date/time
See also
addSecs(), addMonths(), addYears(), daysTo()

Definition at line 1215 of file kadatetime.cpp.

KADateTime KAlarmCal::KADateTime::addMonths ( int  months) const

Returns a date/time months months later than the stored date/time.

The result is expressed using the same time specification as the original instance.

Returns
resultant date/time
See also
addSecs(), addDays(), addYears(), daysTo()

Definition at line 1224 of file kadatetime.cpp.

KADateTime KAlarmCal::KADateTime::addMSecs ( qint64  msecs) const

Returns a date/time msecs milliseconds later than the stored date/time.

The calculation is done in UTC to ensure that the result takes proper account of clock changes (e.g. daylight savings) in the time zone. The result is expressed using the same time specification as the original instance.

If the instance is date-only, msecs is rounded down to a whole number of days and that value is added to the date to find the result.

Returns
resultant date/time
See also
addSecs(), addDays(), addMonths(), addYears(), secsTo()

Definition at line 1195 of file kadatetime.cpp.

KADateTime KAlarmCal::KADateTime::addSecs ( qint64  secs) const

Returns a date/time secs seconds later than the stored date/time.

The calculation is done in UTC to ensure that the result takes proper account of clock changes (e.g. daylight savings) in the time zone. The result is expressed using the same time specification as the original instance.

If the instance is date-only, secs is rounded down to a whole number of days and that value is added to the date to find the result.

Returns
resultant date/time
See also
addMSecs(), addDays(), addMonths(), addYears(), secsTo()

Definition at line 1210 of file kadatetime.cpp.

KADateTime KAlarmCal::KADateTime::addYears ( int  years) const

Returns a date/time years years later than the stored date/time.

The result is expressed using the same time specification as the original instance.

Returns
resultant date/time
See also
addSecs(), addDays(), addMonths(), daysTo()

Definition at line 1233 of file kadatetime.cpp.

KADateTime::Comparison KAlarmCal::KADateTime::compare ( const KADateTime other) const

Compare this instance with another to determine whether they are simultaneous, earlier or later, and in the case of date-only values, whether they overlap (i.e.

partly coincide but are not wholly simultaneous). The comparison takes time zones into account: if the two instances have different time zones, they are first converted to UTC before comparing.

If both instances are date/time values, this instance is considered to be either simultaneous, earlier or later, and does not overlap.

If one instance is date-only and the other is a date/time, this instance is either strictly earlier, strictly later, or overlaps.

If both instance are date-only, they are considered simultaneous if both their start of day and end of day times are simultaneous with each other. (Both start and end of day times need to be considered in case a daylight savings change occurs during that day.) Otherwise, this instance can be strictly earlier, earlier but overlapping, later but overlapping, or strictly later.

Returns
true if the two instances represent the same time, false otherwise
See also
operator==(), operator!=(), operator<(), operator<=(), operator>=(), operator>()

Definition at line 1364 of file kadatetime.cpp.

KADateTime KAlarmCal::KADateTime::currentDateTime ( const Spec spec)
static

Returns the current date and time, as reported by the system clock, expressed in a given time specification.

Note
To fetch the current date and time expressed in UTC or in the local system time zone, it is more efficient to use currentUtcDateTime() or currentLocalDateTime().
Parameters
spectime specification
Returns
current date/time
See also
currentUtcDateTime(), currentLocalDateTime()

Definition at line 1336 of file kadatetime.cpp.

QDate KAlarmCal::KADateTime::currentLocalDate ( )
static

Returns the current date in the local time zone, as reported by the system clock.

Returns
current date
See also
currentLocalDateTime(), currentLocalTime()
Since
4.3

Definition at line 1354 of file kadatetime.cpp.

KADateTime KAlarmCal::KADateTime::currentLocalDateTime ( )
static

Returns the current date and time, as reported by the system clock, expressed in the local system time zone (type LocalZone).

Returns
current date/time
See also
currentUtcDateTime(), currentDateTime()

Definition at line 1303 of file kadatetime.cpp.

QTime KAlarmCal::KADateTime::currentLocalTime ( )
static

Returns the current time of day in the local time zone, as reported by the system clock.

Returns
current date
See also
currentLocalDateTime(), currentLocalDate()
Since
4.3

Definition at line 1359 of file kadatetime.cpp.

KADateTime KAlarmCal::KADateTime::currentUtcDateTime ( )
static

Returns the current date and time, as reported by the system clock, expressed in UTC.

Returns
current date/time
See also
currentLocalDateTime(), currentDateTime(), currentLocalDate(), currentLocalTime()

Definition at line 1322 of file kadatetime.cpp.

QDate KAlarmCal::KADateTime::date ( ) const

Returns the date part of the date/time.

The value returned should be interpreted in terms of the instance's time zone or UTC offset.

Returns
date value
See also
time(), qDateTime()

Definition at line 951 of file kadatetime.cpp.

qint64 KAlarmCal::KADateTime::daysTo ( const KADateTime other) const

Calculates the number of days from this date/time to the other date/time.

In calculating the result, other is first converted to this instance's time zone. The number of days difference is then calculated ignoring the time parts of the two date/times. For example, if this date/time was 13:00 on 1 January 2000, and other was 02:00 on 2 January 2000, the result would be 1.

If one instance is date-only and the other is date-time, the date-time value is first converted to the same time specification as the date-only value, and the result is the difference in days between the resultant date and the date-only date.

If both instances are date-only, the calculation ignores time zones.

Parameters
otherother date/time
Returns
number of days difference
See also
secsTo(), addDays()

Definition at line 1270 of file kadatetime.cpp.

void KAlarmCal::KADateTime::detach ( )

Create a separate copy of this instance's data if it is implicitly shared with another instance.

You would normally only call this if you want different copies of the same date/time value to cache conversions to different time zones. Because only the last conversion to another time zone is cached, and the cached value is implicitly shared, judicious use of detach() could improve efficiency when handling several time zones. But take care: if used inappropriately, it will reduce efficiency!

Definition at line 919 of file kadatetime.cpp.

KADateTime KAlarmCal::KADateTime::fromString ( const QString string,
TimeFormat  format = ISODate,
bool *  negZero = nullptr 
)
static

Returns the KADateTime represented by string, using the format given.

This method is the inverse of toString(TimeFormat), except that it can only return a time specification of UTC or OffsetFromUTC. An actual named time zone cannot be returned since an offset from UTC only partially specifies a time zone.

The time specification of the result is determined by the UTC offset present in the string:

  • if the UTC offset is zero the result is type UTC.
  • if the UTC offset is non-zero, the result is type OffsetFromUTC.
  • if there is no UTC offset (when format permits this), the result is by default type LocalZone. You can use setFromStringDefault() to change this default.

If no time is found in string, a date-only value is returned, except when the specified format does not permit the time to be omitted, in which case an error is returned. An error is therefore returned for ISODate when string includes a time zone specification, and for RFCDate in all cases.

For RFC format strings (not RFC 3339), you should normally set format to RFCDate. Only set it to RFCDateDay if you want to return an error when the day of the week is omitted.

Parameters
stringstring to convert
formatformat code. LocalDate cannot be used here.
negZeroif non-null, the value is set to true if a UTC offset of '-0000' is found or, for RFC 2822 format, an unrecognised or invalid time zone abbreviation is found, else false.
Returns
KADateTime value, or an invalid KADateTime if either parameter is invalid
See also
setFromStringDefault(), toString(), QString::fromString()

Definition at line 1860 of file kadatetime.cpp.

KADateTime KAlarmCal::KADateTime::fromString ( const QString string,
const QString format,
const QList< QTimeZone > *  zones = nullptr,
bool  offsetIfAmbiguous = true 
)
static

Returns the KADateTime represented by string, using the format given, optionally using a time zone collection zones as the source of time zone definitions.

The format codes are basically the same as those for toString(), and are similar but not identical to those used by strftime(3).

The format string consists of the same codes as that for toString(). However, some codes which are distinct in toString() have the same function as each other here.

Numeric values without a stated number of digits permit, but do not require, leading zeroes. The maximum number of digits consumed by a numeric code is the minimum needed to cover the possible range of the number (e.g. for minutes, the range is 0 - 59, so the maximum number of digits consumed is 2). All non-numeric values are case insensitive.

Date

  • %y year excluding century (0 - 99). Years 0 - 50 return 2000 - 2050, while years 51 - 99 return 1951 - 1999.
  • %Y full year number (4 digits with optional sign)
  • %:Y full year number (>= 4 digits with optional sign)
  • %:m month number (1 - 12)
  • %m month number, 2 digits (01 - 12)
  • %b
  • %B month name in the current locale or, if no match, in English, abbreviated or in full
  • %:b
  • %:B month name in English, abbreviated or in full
  • %e day of the month (1 - 31)
  • %d day of the month, 2 digits (01 - 31)
  • %a
  • %A weekday name in the current locale or, if no match, in English, abbreviated or in full
  • %:a
  • %:A weekday name in English, abbreviated or in full

Time

  • %H hour in the 24 hour clock, 2 digits (00 - 23)
  • %k hour in the 24 hour clock (0 - 23)
  • %I hour in the 12 hour clock, 2 digits (01 - 12)
  • %l hour in the 12 hour clock (1 - 12)
  • %M minute, 2 digits (00 - 59)
  • %:M minute (0 - 59)
  • %S seconds, 2 digits (00 - 59)
  • %s seconds (0 - 59)
  • %:S optional seconds value (0 - 59) preceded with ':'. If no colon is found in string, no input is consumed and the seconds value is set to zero.
  • %:s fractional seconds value, preceded with a decimal point (either '.' or the locale's decimal point symbol)
  • %P
  • %p "am" or "pm", in the current locale or, if no match, in English. This format is only useful when used with %I or %l.
  • %:P
  • %:p "am" or "pm" in English. This format is only useful when used with %I or %l.

Time zone

  • %:u
  • %z UTC offset of the time zone in hours and optionally minutes, e.g. -02, -0200.
  • %:z UTC offset of the time zone in hours and minutes, colon separated, e.g. +02:00.
  • %Z time zone abbreviation, consisting of alphanumeric characters, e.g. UTC, EDT, GMT.
  • %:Z time zone name, e.g. Europe/London. The name may contain any characters and is delimited by the following character in the format string. It will not work if you follow %:Z with another escape sequence (except %% or %t).

Other

  • %t matches one or more whitespace characters
  • %% literal '%' character

Any other character must have a matching character in string, except that a space will match zero or more whitespace characters in the input string.

If any time zone information is present in the string, the function attempts to find a matching time zone in the zones collection. A time zone name (format code %:Z) will provide an unambiguous look up in zones. Any other type of time zone information (an abbreviated time zone code (%Z) or UTC offset (%z, %:z, %:u) is searched for in zones and if only one time zone is found to match, the result is set to that zone. Otherwise:

  • If more than one match of a UTC offset is found, the action taken is determined by offsetIfAmbiguous: if offsetIfAmbiguous is true, a local time with an offset from UTC (type OffsetFromUTC) will be returned; if false an invalid KADateTime is returned.
  • If more than one match of a time zone abbreviation is found, the UTC offset for each matching time zone is compared and, if the offsets are the same, a local time with an offset from UTC (type OffsetFromUTC) will be returned provided that offsetIfAmbiguous is true. Otherwise an invalid KADateTime is returned.
  • If a time zone abbreviation does not match any time zone in zones, or the abbreviation does not apply at the parsed date/time, an invalid KADateTime is returned.
  • If a time zone name does not match any time zone in zones, an invalid KADateTime is returned.
  • If the time zone UTC offset does not match any time zone in zones, a local time with an offset from UTC (type OffsetFromUTC) is returned. If format contains more than one time zone or UTC offset code, an error is returned.

If no time zone information is present in the string, by default a local time (type LocalZone) is returned. You can use setFromStringDefault() to change this default.

If no time is found in string, a date-only value is returned.

If any inconsistencies are found, i.e. the same item of information appears more than once but with different values, the weekday name does not tally with the date, an invalid KADateTime is returned.

Parameters
stringstring to convert
formatformat string
zonestime zone collection, or null for none
offsetIfAmbiguousspecifies what to do if more than one zone matches the UTC offset found in the string. Ignored if zones is null.
Returns
KADateTime value, or an invalid KADateTime if an error occurs, if time zone information doesn't match any in zones, or if the time zone information is ambiguous and offsetIfAmbiguous is false
See also
setFromStringDefault(), toString()

Definition at line 2256 of file kadatetime.cpp.

bool KAlarmCal::KADateTime::isDateOnly ( ) const

Returns whether the instance represents a date/time or a date-only value.

Returns
true if date-only, false if date and time

Definition at line 931 of file kadatetime.cpp.

bool KAlarmCal::KADateTime::isLocalZone ( ) const

Returns whether the time zone for the date/time follows the current local system time zone.

Returns
true if local system time zone
See also
isUtc(), isOffsetFromUtc(), timeZone()

Definition at line 935 of file kadatetime.cpp.

bool KAlarmCal::KADateTime::isNull ( ) const

Returns whether the date/time is null.

Returns
true if both date and time are null, else false
See also
isValid(), QDateTime::isNull()

Definition at line 923 of file kadatetime.cpp.

bool KAlarmCal::KADateTime::isOffsetFromUtc ( ) const

Returns whether the date/time is a local time at a fixed offset from UTC.

Returns
true if local time at fixed offset from UTC
See also
isLocal(), isUtc(), utcOffset()

Definition at line 943 of file kadatetime.cpp.

bool KAlarmCal::KADateTime::isSecondOccurrence ( ) const

Returns whether the date/time is the second occurrence of this time.

This is only applicable to a date/time expressed in terms of a time zone (type TimeZone or LocalZone), around the time of change from daylight savings to standard time.

When a shift from daylight savings time to standard time occurs, the local times (typically the previous hour) immediately preceding the shift occur twice. For example, if a time shift of 1 hour happens at 03:00, the clock jumps backwards to 02:00, so the local times between 02:00:00 and 02:59:59 occur once before the shift, and again after the shift.

For instances which are not of type TimeZone, or when the date/time is not near to a time shift, false is returned.

Returns
true if the time is the second occurrence, false otherwise
See also
setSecondOccurrence()

Definition at line 947 of file kadatetime.cpp.

bool KAlarmCal::KADateTime::isUtc ( ) const

Returns whether the date/time is a UTC time.

It is considered to be a UTC time if it either has a UTC time specification (SpecType == UTC), or has a zero offset from UTC (SpecType == OffsetFromUTC with zero UTC offset).

Returns
true if UTC
See also
isLocal(), isOffsetFromUtc(), timeZone()

Definition at line 939 of file kadatetime.cpp.

bool KAlarmCal::KADateTime::isValid ( ) const

Returns whether the date/time is valid.

Returns
true if both date and time are valid, else false
See also
isNull(), QDateTime::isValid()

Definition at line 927 of file kadatetime.cpp.

qint64 KAlarmCal::KADateTime::msecsTo ( const KADateTime other) const

Returns the number of milliseconds from this date/time to the other date/time.

Before performing the comparison, the two date/times are converted to UTC to ensure that the result is correct if one of the two date/times has daylight saving time (DST) and the other doesn't.

If one instance is date-only and the other is date-time, the date-time value is first converted to the same time specification as the date-only value, and the result is the difference in days between the resultant date and the date-only date.

If both instances are date-only, the result is the difference in days between the two dates, ignoring time zones.

Parameters
otherother date/time
Returns
number of milliseconds difference
See also
addSecs(), daysTo()

Definition at line 1242 of file kadatetime.cpp.

bool KAlarmCal::KADateTime::operator< ( const KADateTime other) const

Check whether this date/time is earlier than another.

The comparison takes time zones into account: if the two instances have different time zones, they are first converted to UTC before comparing.

If one or both instances are date-only, the comparison returns true if this date/time or day, falls wholly before the other date/time or day. To achieve this, the time used in the comparison is the end of day (if this instance is date-only) or the start of day (if the other instance is date-only).

Returns
true if this instance represents an earlier time than other, false otherwise
See also
compare()

Definition at line 1456 of file kadatetime.cpp.

bool KAlarmCal::KADateTime::operator== ( const KADateTime other) const

Check whether this date/time is simultaneous with another.

The comparison takes time zones into account: if the two instances have different time zones, they are first converted to UTC before comparing.

If one instance is date-only and the other is date/time, they are considered unequal.

If both instances are date-only, they are considered simultaneous if both their start of day and end of day times are simultaneous with each other. (Both start and end of day times need to be considered in case a daylight saving change occurs during that day.)

Returns
true if the two instances represent the same time, false otherwise
See also
compare()

Definition at line 1425 of file kadatetime.cpp.

QDateTime KAlarmCal::KADateTime::qDateTime ( ) const

Converts the instance to a QDateTime value.

If the instance is date-only, the time value is set to 00:00:00.

Returns
date/time
See also
date(), time()

Definition at line 959 of file kadatetime.cpp.

KADateTime KAlarmCal::KADateTime::realCurrentLocalDateTime ( )
static

Return the real (not simulated) system time.

Warning
This method is provided only for testing purposes, and should not be used in released code. If the library is compiled without debug enabled, currentLocalDateTime() and realCurrentLocalDateTime() both return the real system time. To avoid confusion, it is recommended that calls to realCurrentLocalDateTime() should be conditionally compiled, e.g.:
#ifndef NDEBUG
#endif
Since
4.3

Definition at line 2459 of file kadatetime.cpp.

qint64 KAlarmCal::KADateTime::secsTo ( const KADateTime other) const

Returns the number of seconds from this date/time to the other date/time.

Before performing the comparison, the two date/times are converted to UTC to ensure that the result is correct if one of the two date/times has daylight saving time (DST) and the other doesn't.

If one instance is date-only and the other is date-time, the date-time value is first converted to the same time specification as the date-only value, and the result is the difference in days between the resultant date and the date-only date.

If both instances are date-only, the result is the difference in days between the two dates, ignoring time zones.

Parameters
otherother date/time
Returns
number of seconds difference
See also
addSecs(), daysTo()

Definition at line 1256 of file kadatetime.cpp.

void KAlarmCal::KADateTime::setDate ( const QDate date)

Sets the date part of the date/time.

Parameters
datenew date value
See also
date(), setTime(), setTimeSpec(), setSecsSinceEpoch(), setDateOnly()

Definition at line 1166 of file kadatetime.cpp.

void KAlarmCal::KADateTime::setDateOnly ( bool  dateOnly)

Sets the instance either to being a date and time value, or a date-only value.

If its status is changed to date-only, its time is set to 00:00:00.

Parameters
dateOnlytrue to set to date-only, false to set to date and time.
See also
isDateOnly(), setTime()

Definition at line 1161 of file kadatetime.cpp.

void KAlarmCal::KADateTime::setFromStringDefault ( const Spec spec)
static

Sets the default time specification for use by fromString() when no time zone or UTC offset is found in the string being parsed, or when "-0000" is found in an RFC 2822 string.

By default, fromString() returns a local time (type LocalZone) when no definite zone or UTC offset is found. You can use this method to make it return UTC, or whatever you wish.

Parameters
specthe new default time specification
See also
fromString()

Definition at line 2438 of file kadatetime.cpp.

void KAlarmCal::KADateTime::setSecondOccurrence ( bool  second)

Sets whether the date/time is the second occurrence of this time.

This is only applicable to a date/time expressed in terms of a time zone (type TimeZone or LocalZone), around the time of change from daylight savings to standard time.

When a shift from daylight savings time to standard time occurs, the local times (typically the previous hour) immediately preceding the shift occur twice. For example, if a time shift of 1 hour happens at 03:00, the clock jumps backwards to 02:00, so the local times between 02:00:00 and 02:59:59 occur once before the shift, and again after the shift.

For instances which are not of type TimeZone, or when the date/time is not near to a time shift, calling this method has no effect.

Note that most other setting methods clear the second occurrence indicator, so if you want to retain its setting, you must call setSecondOccurrence() again after changing the instance's value.

Parameters
secondtrue to set as the second occurrence, false to set as the first occurrence
See also
isSecondOccurrence()

Definition at line 1181 of file kadatetime.cpp.

void KAlarmCal::KADateTime::setSecsSinceEpoch ( qint64  seconds)

Sets the time to a UTC time, specified as seconds since 00:00:00 UTC 1st January 1970 (as returned by time(2)).

Parameters
secondsnumber of seconds since 00:00:00 UTC 1st January 1970
See also
toSecsSinceEpoch()

Definition at line 1146 of file kadatetime.cpp.

void KAlarmCal::KADateTime::setSimulatedSystemTime ( const KADateTime newTime)
static

Set an adjustment to be applied when fetching the current system time.

This is applied by all KADateTime methods which return the system date and/or time.

The supplied date/time is used as the current simulated time and the time adjustment is set to the difference between the real current time and newTime. If newTime has a time zone, that time zone is set to be the simulated local system time zone.

To cancel time simulation, supply an invalid newTime parameter.

Warning
This function is provided only for testing purposes, and should not be used in released code. If the library is compiled without debug enabled, setSimulatedSystemTime() has no effect. To avoid confusion, it is recommended that calls to it should be conditionally compiled, e.g.:
#ifndef NDEBUG
KADateTime::simulateSystemTime(kdt);
#endif
Parameters
newTimethe current simulated time, or invalid to cancel simulation
See also
currentDateTime(), currentLocalDateTime(), currentUtcDateTime(), currentLocalDate(), currentLocalTime()
Since
4.3

Definition at line 2443 of file kadatetime.cpp.

void KAlarmCal::KADateTime::setTime ( const QTime time)

Sets the time part of the date/time.

If the instance was date-only, it is changed to being a date and time value.

Parameters
timenew time value
See also
time(), setDate(), setTimeSpec(), setSecsSinceEpoch()

Definition at line 1171 of file kadatetime.cpp.

void KAlarmCal::KADateTime::setTime_t ( qint64  seconds)

Sets the time to a UTC time, specified as seconds since 00:00:00 UTC 1st January 1970 (as returned by time(2)).

Parameters
secondsnumber of seconds since 00:00:00 UTC 1st January 1970
See also
toTime_t()
Deprecated:
Use setSecsSinceEpoch()

Definition at line 1156 of file kadatetime.cpp.

void KAlarmCal::KADateTime::setTimeSpec ( const Spec spec)

Changes the time specification of the instance.

Any previous time zone is forgotten. The stored date/time component of the instance is left unchanged (except that its Qt::TimeSpec setting is set to correspond with spec). Usually this method will change the absolute time which this instance represents.

Parameters
specnew time specification
See also
timeSpec(), timeZone()

Definition at line 1176 of file kadatetime.cpp.

QTime KAlarmCal::KADateTime::time ( ) const

Returns the time part of the date/time.

The value returned should be interpreted in terms of the instance's time zone or UTC offset. If the instance is date-only, the time returned is 00:00:00.

Returns
time value
See also
date(), qDateTime(), isDateOnly()

Definition at line 955 of file kadatetime.cpp.

KADateTime::Spec KAlarmCal::KADateTime::timeSpec ( ) const

Returns the time specification of the date/time, i.e.

whether it is UTC, what time zone it is, etc.

Returns
time specification
See also
isLocalZone(), isUtc(), timeZone()

Definition at line 964 of file kadatetime.cpp.

KADateTime::SpecType KAlarmCal::KADateTime::timeType ( ) const

Returns the time specification type of the date/time, i.e.

whether it is UTC, has a time zone, etc.

Returns
specification type
See also
timeSpec(), isLocalZone(), isUtc(), timeZone()

Definition at line 968 of file kadatetime.cpp.

QTimeZone KAlarmCal::KADateTime::timeZone ( ) const

Returns the time zone for the date/time.

If the date/time is specified as a UTC time, a UTC time zone is always returned. If it is specified as LocalZone, the system time zone is returned.

Returns
time zone, or invalid if a local time at a fixed UTC offset
See also
isUtc(), isLocal()

Definition at line 973 of file kadatetime.cpp.

KADateTime KAlarmCal::KADateTime::toLocalZone ( ) const

Returns the time converted to the current local system time zone.

If the instance is a date-only value, a date-only local time zone value is returned, with the date unchanged.

Returns
converted time
See also
toUtc(), toOffsetFromUtc(), toZone(), toTimeSpec(), QTimeZone::convert()

Definition at line 1067 of file kadatetime.cpp.

KADateTime KAlarmCal::KADateTime::toOffsetFromUtc ( ) const

Returns the time expressed as an offset from UTC, using the UTC offset associated with this instance's date/time.

The date and time components are unchanged. For example, 14:15 on 12 Jan 2001, US Eastern time zone would return a KADateTime value of 14:15 on 12 Jan 2001 with a UTC offset of -18000 seconds (i.e. -5 hours).

If the instance is a date-only value, the offset is set to that at the start of the day.

Returns
converted time
See also
toUtc(), toOffsetFromUtc(int), toLocalZone(), toZone(), toTimeSpec(), toSecsSinceEpoch(), QTimeZone::convert()

Definition at line 1019 of file kadatetime.cpp.

KADateTime KAlarmCal::KADateTime::toOffsetFromUtc ( int  utcOffset) const

Returns the time expressed as a specified offset from UTC.

If the instance is a date-only value, a date-only UTC offset time value is returned, with the date unchanged.

Parameters
utcOffsetnumber of seconds to add to UTC to get the local time.
Returns
converted time
See also
toUtc(), toOffsetFromUtc(), toLocalZone(), toZone(), toTimeSpec(), toSecsSinceEpoch(), QTimeZone::convert()

Definition at line 1055 of file kadatetime.cpp.

qint64 KAlarmCal::KADateTime::toSecsSinceEpoch ( ) const

Converts the time to a UTC time, measured in seconds since 00:00:00 UTC 1st January 1970 (as returned by time(2)).

Returns
converted time, or LLONG_MIN if the date is out of range or invalid
See also
setSecsSinceEpoch()

Definition at line 1129 of file kadatetime.cpp.

QString KAlarmCal::KADateTime::toString ( const QString format) const

Returns the date/time as a string.

The format parameter determines the format of the result string. The format codes used for the date and time components follow those used elsewhere in KDE, and are similar but not identical to those used by strftime(3). Conversion specifiers are introduced by a '%' character, and are replaced in format as follows:

Date

  • %y 2-digit year excluding century (00 - 99). Conversion is undefined if year < 0.
  • %Y full year number
  • %:m month number, without leading zero (1 - 12)
  • %m month number, 2 digits (01 - 12)
  • %b abbreviated month name in current locale
  • %B full month name in current locale
  • %:b abbreviated month name in English (Jan, Feb, ...)
  • %:B full month name in English
  • %e day of the month (1 - 31)
  • %d day of the month, 2 digits (01 - 31)
  • %a abbreviated weekday name in current locale
  • %A full weekday name in current locale
  • %:a abbreviated weekday name in English (Mon, Tue, ...)
  • %:A full weekday name in English

Time

  • %H hour in the 24 hour clock, 2 digits (00 - 23)
  • %k hour in the 24 hour clock, without leading zero (0 - 23)
  • %I hour in the 12 hour clock, 2 digits (01 - 12)
  • %l hour in the 12 hour clock, without leading zero (1 - 12)
  • %M minute, 2 digits (00 - 59)
  • %S seconds (00 - 59)
  • %:S seconds preceded with ':', but omitted if seconds value is zero
  • %:s milliseconds, 3 digits (000 - 999)
  • %P "am" or "pm" in the current locale, or if undefined there, in English
  • %p "AM" or "PM" in the current locale, or if undefined there, in English
  • %:P "am" or "pm"
  • %:p "AM" or "PM"

Time zone

  • %:u UTC offset of the time zone in hours, e.g. -02. If the offset is not a whole number of hours, the output is the same as for '%U'.
  • %z UTC offset of the time zone in hours and minutes, e.g. -0200.
  • %:z UTC offset of the time zone in hours and minutes, e.g. +02:00.
  • %Z time zone abbreviation, e.g. UTC, EDT, GMT. This is not guaranteed to be unique among different time zones. If not applicable (i.e. if the instance is type OffsetFromUTC), the UTC offset is substituted.
  • %:Z time zone name, e.g. Europe/London. This is system dependent. If not applicable (i.e. if the instance is type OffsetFromUTC), the UTC offset is substituted.

Other

  • %% literal '%' character

If you want to use the current locale's date format, you should call KLocale::formatDate() to format the date part of the KADateTime.

Parameters
formatformat for the string
Returns
formatted string
See also
fromString(), KLocale::formatDate()

Definition at line 1495 of file kadatetime.cpp.

QString KAlarmCal::KADateTime::toString ( TimeFormat  format = ISODate) const

Returns the date/time as a string, formatted according to the format parameter, with the UTC offset appended.

If the instance is date-only, the time will when format permits be omitted from the output string. This applies to format = QtTextDate or LocalDate. For all other cases, a time of 00:00:00 will be output.

For RFC 2822 format, set format to RFCDateDay to include the day of the week, or to RFCDate to omit it.

Parameters
formatformat for output string
Returns
formatted string
See also
fromString(), QDateTime::toString()

Definition at line 1738 of file kadatetime.cpp.

uint KAlarmCal::KADateTime::toTime_t ( ) const

Converts the time to a UTC time, measured in seconds since 00:00:00 UTC 1st January 1970 (as returned by time(2)).

Returns
converted time, or uint(-1) if the date is out of range or invalid
See also
setTime_t()
Deprecated:
Use toSecsSinceEpoch()

Definition at line 1138 of file kadatetime.cpp.

KADateTime KAlarmCal::KADateTime::toTimeSpec ( const Spec spec) const

Returns the time converted to a new time specification.

If the instance is a date-only value, a date-only value is returned, with the date unchanged.

Parameters
specnew time specification
Returns
converted time
See also
toLocalZone(), toUtc(), toOffsetFromUtc(), toZone(), QTimeZone::convert()

Definition at line 1111 of file kadatetime.cpp.

KADateTime KAlarmCal::KADateTime::toTimeSpec ( const KADateTime dt) const

Returns the time converted to the time specification of another instance.

If this instance is a date-only value, a date-only value is returned, with the date unchanged.

Parameters
dtinstance providing the new time specification
Returns
converted time
See also
toLocalZone(), toUtc(), toOffsetFromUtc(), toZone(), QTimeZone::convert()

Definition at line 1106 of file kadatetime.cpp.

KADateTime KAlarmCal::KADateTime::toUtc ( ) const

Returns the time converted to UTC.

The converted time has a UTC offset of zero. If the instance is a date-only value, a date-only UTC value is returned, with the date unchanged.

Returns
converted time
See also
toOffsetFromUtc(), toLocalZone(), toZone(), toTimeSpec(), toSecsSinceEpoch(), QTimeZone::convert()

Definition at line 1004 of file kadatetime.cpp.

KADateTime KAlarmCal::KADateTime::toZone ( const QTimeZone zone) const

Returns the time converted to a specified time zone.

If the instance is a date-only value, a date-only value in zone is returned, with the date unchanged.

Parameters
zonetime zone to convert to
Returns
converted time
See also
toUtc(), toOffsetFromUtc(), toLocalZone(), toTimeSpec(), QTimeZone::convert()

Definition at line 1092 of file kadatetime.cpp.

int KAlarmCal::KADateTime::utcOffset ( ) const

Returns the UTC offset associated with the date/time.

The UTC offset is the number of seconds to add to UTC to get the local time.

Returns
UTC offset in seconds

Definition at line 987 of file kadatetime.cpp.

Friends And Related Function Documentation

QDataStream& operator<< ( QDataStream out,
const KADateTime dateTime 
)
friend

Write dateTime to the datastream out, in binary format.

Definition at line 2464 of file kadatetime.cpp.

QDataStream& operator>> ( QDataStream in,
KADateTime dateTime 
)
friend

Read a KADateTime object into dateTime from in, in binary format.

Definition at line 2470 of file kadatetime.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Mon Sep 21 2020 23:10:35 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.