KDateTime Class Reference

from PyKDE4.kdecore import *

Detailed Description

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

Topics: - intro - manipulation - compatibility

Introduction

The class KDateTime combines a date and time with support for an associated time zone or UTC offset. When manipulating KDateTime objects, their time zones or UTC offsets are automatically taken into account. KDateTime can also be set to represent a date-only value with no associated time.

The class uses QDateTime internally to represent date/time values, and therefore uses the Gregorian calendar for dates starting from 15 October 1582, and the Julian calendar for dates up to 4 October 1582. The minimum year number is -4712 (4713 BC), while the upper limit is more than 11,000,000. The actual adoption of the Gregorian calendar after 1582 was slow; the last European country to adopt it, Greece, did so only in 1923. See QDateTime Considerations section below for further discussion of the date range limitations.

The time specification types which KDateTime 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 (a special case of the previous item) - local clock time, using whatever the local system clock says on whichever computer it happens to be on. In this case, the equivalent UTC time will vary depending on system. As a result, calculations involving local clock times do not necessarily produce reliable results.

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(), isOffsetFromUtc() or isClockTime(). To determine whether two KDateTime instances have the same time specification, call timeSpec() on each and compare the returned values using KDateTime.Spec.operator==().

Date and Time Manipulation

A KDateTime 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 KDateTime object can be converted to a different time specification by using toUtc(), toLocalZone() or toClockTime(). 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 toTime_t(). The results of time zone conversions are cached to minimize the need for recalculation. Each KDateTime 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(), setTime() or setDateTime(). To return the date and/or time components of the KDateTime, use date(), time() and dateTime(). You can determine whether the KDateTime 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 KDateTime 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 KDateTime object overlaps with another when one or both are date-only values.

KDateTime 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.

KDateTime 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().

QDateTime Considerations

KDateTime's interface is designed to be as compatible as possible with that of QDateTime, but with adjustments to cater for time zone handling. Because QDateTime lacks virtual methods, KDateTime is not inherited from QDateTime, but instead is implemented using a private QDateTime object.

The date range restriction due to the use of QDateTime internally may at first sight seem a design limitation. However, two factors should be considered:

- there are significant problems in the representation of dates before the Gregorian calendar was adopted. The date of adoption of the Gregorian calendar varied from place to place, and in the Julian calendar the date of the new year varied so that in different places the year number could differ by one. So any date/time system which attempted to represent dates as actually used in history would be too specialized to belong to the core KDE libraries. Date/time systems for scientific applications can be much simpler, but may differ from historical records.

- time zones were not invented until the middle of the 19th century. Before that, solar time was used.

Because of these issues, together with the fact that KDateTime's aim is to provide automatic time zone handling for date/time values, QDateTime was chosen as the basis for KDateTime. For those who need an extended date range, other classes exist.

Simulation Facility

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:: KTimeZone, KSystemTimeZones, QDateTime, QDate, QTime

See also:: W3C: Working with Time Zones

Author:: David Jarvie <djarvie@kde.org>.

Enumerations
Comparison	{ Before, AtStart, Inside, AtEnd, After, Equal, Outside, StartsAt, EndsAt }
SpecType	{ Invalid, UTC, OffsetFromUTC, TimeZone, LocalZone, ClockTime }
TimeFormat	{ ISODate, RFCDate, RFCDateDay, QtTextDate, LocalDate }
Methods
	__init__ (self)
	__init__ (self, QDate date, KDateTime.Spec spec=KDateTime.Spec(KDateTime.LocalZone))
	__init__ (self, QDate date, QTime time, KDateTime.Spec spec=KDateTime.Spec(KDateTime.LocalZone))
	__init__ (self, QDateTime dt, KDateTime.Spec spec)
	__init__ (self, QDateTime dt)
	__init__ (self, KDateTime other)
KDateTime	addDays (self, int days)
KDateTime	addMSecs (self, long msecs)
KDateTime	addMonths (self, int months)
KDateTime	addSecs (self, long secs)
KDateTime	addYears (self, int years)
KDateTime.Comparison	compare (self, KDateTime other)
QDate	date (self)
QDateTime	dateTime (self)
int	daysTo (self, KDateTime other)
	detach (self)
bool	isClockTime (self)
bool	isDateOnly (self)
bool	isLocalZone (self)
bool	isNull (self)
bool	isOffsetFromUtc (self)
bool	isSecondOccurrence (self)
bool	isUtc (self)
bool	isValid (self)
bool	operator != (self, KDateTime other)
bool	operator < (self, KDateTime other)
bool	operator <= (self, KDateTime other)
bool	operator == (self, KDateTime other)
bool	operator > (self, KDateTime other)
bool	operator >= (self, KDateTime other)
bool	outOfRange (self)
int	secsTo (self, KDateTime other)
long	secsTo_long (self, KDateTime other)
	setDate (self, QDate date)
	setDateOnly (self, bool dateOnly)
	setDateTime (self, QDateTime dt)
	setSecondOccurrence (self, bool second)
	setTime (self, QTime time)
	setTimeSpec (self, KDateTime.Spec spec)
	setTime_t (self, long seconds)
QTime	time (self)
KDateTime.Spec	timeSpec (self)
KDateTime.SpecType	timeType (self)
KTimeZone	timeZone (self)
KDateTime	toClockTime (self)
KDateTime	toLocalZone (self)
KDateTime	toOffsetFromUtc (self)
KDateTime	toOffsetFromUtc (self, int utcOffset)
QString	toString (self, QString format)
QString	toString (self, KDateTime.TimeFormat format=KDateTime.ISODate)
KDateTime	toTimeSpec (self, KDateTime.Spec spec)
KDateTime	toTimeSpec (self, KDateTime dt)
long	toTime_t (self)
KDateTime	toUtc (self)
KDateTime	toZone (self, KTimeZone zone)
int	utcOffset (self)
Static Methods
KDateTime	currentDateTime (KDateTime.Spec spec)
QDate	currentLocalDate ()
KDateTime	currentLocalDateTime ()
QTime	currentLocalTime ()
KDateTime	currentUtcDateTime ()
KDateTime, bool (negZero)	fromString (QString string, KDateTime.TimeFormat format=KDateTime.ISODate, )
KDateTime	fromString (QString string, QString format, KTimeZones zones=0, bool offsetIfAmbiguous=1)
KDateTime	realCurrentLocalDateTime ()
	setFromStringDefault (KDateTime.Spec spec)
	setSimulatedSystemTime (KDateTime newTime)

Method Documentation

__init__ ( self )

Constructs an invalid date/time.

__init__	(	self,
		QDate	date,
		KDateTime.Spec	spec=KDateTime.Spec(KDateTime.LocalZone)
	)

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 the current system time zone. - ClockTime : time zones are ignored.

Parameters:

	date	date in the time zone indicated by spec
	spec	time specification

__init__	(	self,
		QDate	date,
		QTime	time,
		KDateTime.Spec	spec=KDateTime.Spec(KDateTime.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 the current system time zone. - ClockTime : time zones are ignored.

Parameters:

	date	date in the time zone indicated by spec
	time	time in the time zone indicated by spec
	spec	time specification

__init__	(	self,
		QDateTime	dt,
		KDateTime.Spec	spec
	)

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

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 Qt.LocalTime, dt is first converted from the current system time zone to UTC before storage. - OffsetFromUTC : date/time is stored as a local time at the specified offset from UTC. If dt.timeSpec() is Qt.UTC, the time is adjusted by the UTC offset before storage. If dt.timeSpec() is Qt.LocalTime, it is assumed to be a local time at the specified offset from UTC, and is stored without adjustment. - TimeZone : if dt is specified as a UTC time (i.e. dt.timeSpec() is Qt.UTC), it is first converted to local time in specified time zone before being stored. - LocalZone : dt is stored as a local time in the current system time zone. If dt.timeSpec() is Qt.UTC, dt is first converted to local time before storage. - ClockTime : If dt.timeSpec() is Qt.UTC, dt is first converted to local time in the current system time zone before storage. After storage, the time is treated as a simple clock time, ignoring time zones.

Parameters:

	dt	date and time
	spec	time specification

__init__	(	self,
		QDateTime	dt
	)

Constructs a date/time from a QDateTime. The KDateTime is expressed in either UTC or the local system time zone, according to dt.timeSpec().

Parameters:

date and time

__init__	(	self,
		KDateTime	other
	)

KDateTime addDays	(	self,
		int	days
	)

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.

Note that if the instance is a local clock time (type ClockTime), any daylight savings changes or time zone changes during the period may render the result inaccurate.

Returns:: resultant date/time

See also:: addSecs(), addMonths(), addYears(), daysTo()

KDateTime addMSecs	(	self,
		long	msecs
	)

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

Except when the instance is a local clock time (type ClockTime), 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.

Note that if the instance is a local clock time (type ClockTime), any daylight savings changes or time zone changes during the period will render the result inaccurate.

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()

KDateTime addMonths	(	self,
		int	months
	)

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.

Note that if the instance is a local clock time (type ClockTime), any daylight savings changes or time zone changes during the period may render the result inaccurate.

Returns:: resultant date/time

See also:: addSecs(), addDays(), addYears(), daysTo()

KDateTime addSecs	(	self,
		long	secs
	)

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

Note that if the instance is a local clock time (type ClockTime), any daylight savings changes or time zone changes during the period will render the result inaccurate.

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()

KDateTime addYears	(	self,
		int	years
	)

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.

Note that if the instance is a local clock time (type ClockTime), any daylight savings changes or time zone changes during the period may render the result inaccurate.

Returns:: resultant date/time

See also:: addSecs(), addDays(), addMonths(), daysTo()

KDateTime.Comparison compare	(	self,
		KDateTime	other
	)

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.

Note that if either instance is a local clock time (type ClockTime), the result cannot be guaranteed to be correct, since by definition they contain no information about time zones or daylight savings changes.

Returns:: true if the two instances represent the same time, false otherwise

See also:: operator==(), operator!=(), operator<(), operator<=(), operator>=(), operator>()

KDateTime currentDateTime	(	KDateTime.Spec	spec
	)

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

Parameters:

spec

time specification

Returns:: current date/time

See also:: currentUtcDateTime(), currentLocalDateTime()

QDate currentLocalDate ( )

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

Returns:: current date

See also:: currentLocalDateTime(), currentLocalTime()

KDateTime currentLocalDateTime ( )

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

Returns:: current date/time

See also:: currentUtcDateTime(), currentDateTime()

QTime currentLocalTime ( )

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

Returns:: current date

See also:: currentLocalDateTime(), currentLocalDate()

KDateTime currentUtcDateTime ( )

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()

QDate date ( self )

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(), dateTime()

QDateTime dateTime ( self )

Returns the date/time component of the instance, ignoring the time zone. The value returned should be interpreted in terms of the instance's time zone or UTC offset. The returned value's timeSpec() value will be Qt.UTC if the instance is a UTC time, else Qt.LocalTime. If the instance is date-only, the time value is set to 00:00:00.

Returns:: date/time

See also:: date(), time()

int daysTo	(	self,
		KDateTime	other
	)

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.

Note that if either instance is a local clock time (type ClockTime), the result cannot be guaranteed to be accurate, since by definition they contain no information about time zones or daylight savings changes.

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:

other

other date/time

Returns:: number of days difference

See also:: secsTo(), addDays()

detach ( self )

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!

KDateTime, bool (negZero) fromString	(	QString	string,
		KDateTime.TimeFormat	format=KDateTime.ISODate,
	)

Returns the KDateTime 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, OffsetFromUTC or ClockTime. 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, the result is by default type ClockTime. 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, 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.

For format = ISODate or RFCDate[Day], if an invalid KDateTime is returned, you can check why format was considered invalid by use of outOfRange(). If that method returns true, it indicates that format was in fact valid, but the date lies outside the range which can be represented by QDate.

Parameters:

	string	string to convert
	format	format code. LocalDate cannot be used here.
	negZero	if 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:: KDateTime value, or an invalid KDateTime if either parameter is invalid

See also:: setFromStringDefault(), toString(), outOfRange(), QString.fromString()

KDateTime fromString	(	QString	string,
		QString	format,
		KTimeZones	zones=0,
		bool	offsetIfAmbiguous=1
	)

Returns the KDateTime 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 KDateTime 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 KDateTime 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 KDateTime is returned. - If a time zone name does not match any time zone in zones, an invalid KDateTime 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 clock time (type ClockTime) 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 KDateTime is returned.

If an invalid KDateTime is returned, you can check why format was considered invalid by use of outOfRange(). If that method returns true, it indicates that format was in fact valid, but the date lies outside the range which can be represented by QDate.

Parameters:

	string	string to convert
	format	format string
	zones	time zone collection, or null for none
	offsetIfAmbiguous	specifies what to do if more than one zone matches the UTC offset found in the string. Ignored if zones is null.

Returns:: KDateTime value, or an invalid KDateTime 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(), outOfRange()

bool isClockTime ( self )

Returns whether the date/time is a local clock time.

Returns:: true if local clock time

See also:: isUtc(), timeZone()

bool isDateOnly ( self )

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

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

bool isLocalZone ( self )

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

Returns:: true if local system time zone

See also:: isUtc(), isOffsetFromUtc(), timeZone()

bool isNull ( self )

Returns whether the date/time is null.

Returns:: true if both date and time are null, else false

See also:: isValid(), QDateTime.isNull()

bool isOffsetFromUtc ( self )

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()

bool isSecondOccurrence ( self )

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()

bool isUtc ( self )

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()

bool isValid ( self )

Returns whether the date/time is valid.

Returns:: true if both date and time are valid, else false

See also:: isNull(), QDateTime.isValid()

bool operator !=	(	self,
		KDateTime	other
	)

bool operator <	(	self,
		KDateTime	other
	)

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()

bool operator <=	(	self,
		KDateTime	other
	)

bool operator ==	(	self,
		KDateTime	other
	)

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 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()

bool operator >	(	self,
		KDateTime	other
	)

bool operator >=	(	self,
		KDateTime	other
	)

bool outOfRange ( self )

Checks whether the date/time returned by the last call to fromString() was invalid because an otherwise valid date was outside the range which can be represented by QDate. This status occurs when fromString() read a valid string containing a year earlier than -4712 (4713 BC). On exit from fromString(), if outOfRange() returns true, isValid() will return false.

Returns:: true if date was earlier than -4712, else false

See also:: isValid(), fromString()

KDateTime realCurrentLocalDateTime ( )

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
             dt = KDateTime.realCurrentLocalDateTime();
          #endif

int secsTo	(	self,
		KDateTime	other
	)

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. The exception is when both instances are local clock time, in which case no conversion to UTC is done.

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

Parameters:

other

other date/time

Returns:: number of seconds difference

See also:: secsTo_long(), addSecs(), daysTo()

long secsTo_long	(	self,
		KDateTime	other
	)

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

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

Parameters:

other

other date/time

Returns:: number of seconds difference

See also:: secsTo(), addSecs(), daysTo()

setDate	(	self,
		QDate	date
	)

Sets the date part of the date/time.

Parameters:

date

new date value

See also:: date(), setTime(), setTimeSpec(), setTime_t(), setDateOnly()

setDateOnly	(	self,
		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:

dateOnly

true to set to date-only, false to set to date and time.

See also:: isDateOnly(), setTime()

setDateTime	(	self,
		QDateTime	dt
	)

Sets the date/time part of the instance, leaving the time specification unaffected.

If dt is a local time (\code dt.timeSpec() == Qt.LocalTime \endcode) and the instance is UTC, dt is first converted from the current system time zone to UTC before being stored.

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

Parameters:

date and time

See also:: dateTime(), setDate(), setTime(), setTimeSpec()

setFromStringDefault	(	KDateTime.Spec	spec
	)

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 clock time (type ClockTime) when no definite zone or UTC offset is found. You can use this method to make it return the local time zone, UTC, or whatever you wish.

Parameters:

spec

the new default time specification

See also:: fromString()

setSecondOccurrence	(	self,
		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.

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:

second

true to set as the second occurrence, false to set as the first occurrence

See also:: isSecondOccurrence()

setSimulatedSystemTime	(	KDateTime	newTime
	)

Set an adjustment to be applied when fetching the current system time. This is applied by all KDateTime 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 by calling KSystemTimeZones.setLocalZone()).

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
             KDateTime.simulateSystemTime(kdt);
          #endif

Parameters:

the current simulated time, or invalid to cancel simulation

See also:: currentDateTime(), currentLocalDateTime(), currentUtcDateTime(), currentLocalDate(), currentLocalTime()

setTime	(	self,
		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:

time

new time value

See also:: time(), setDate(), setTimeSpec(), setTime_t()

setTimeSpec	(	self,
		KDateTime.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 UTC/local time setting is set to correspond with spec). Usually this method will change the absolute time which this instance represents.

Parameters:

spec

new time specification

See also:: timeSpec(), timeZone()

setTime_t	(	self,
		long	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:

seconds

number of seconds since 00:00:00 UTC 1st January 1970

See also:: toTime_t()

QTime time ( self )

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(), dateTime(), isDateOnly()

KDateTime.Spec timeSpec ( self )

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(), isClockTime(), isUtc(), timeZone()

KDateTime.SpecType timeType ( self )

Returns the time specification type of the date/time, i.e. whether it is UTC, has a time zone, etc. If the type is the local time zone, TimeZone is returned; use isLocalZone() to check for the local time zone.

Returns:: specification type

See also:: timeSpec(), isLocalZone(), isClockTime(), isUtc(), timeZone()

KTimeZone timeZone ( self )

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.

Returns:: time zone, or invalid if a local time at a fixed UTC offset or a local clock time

See also:: isUtc(), isLocal()

KDateTime toClockTime ( self )

Returns the time converted to the local clock time. The time is first converted to the local system time zone before setting its type to ClockTime, i.e. no associated time zone. If the instance is a date-only value, a date-only clock time value is returned, with the date unchanged.

Returns:: converted time

See also:: toLocalZone(), toTimeSpec()

KDateTime toLocalZone ( self )

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(), KTimeZone.convert()

KDateTime toOffsetFromUtc ( self )

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 KDateTime value of 14:15 on 12 Jan 2001 with a UTC offset of -18000 seconds (i.e. -5 hours).

If the instance is a local clock time, the offset is set to that of the local time zone. 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(), toTime_t(), KTimeZone.convert()

KDateTime toOffsetFromUtc	(	self,
		int	utcOffset
	)

Returns the time expressed as a specified offset from UTC.

If the instance is a local clock time, it is first set to the local time zone, and then converted to the UTC offset. If the instance is a date-only value, a date-only clock time value is returned, with the date unchanged.

Parameters:

utcOffset

number of seconds to add to UTC to get the local time.

Returns:: converted time

See also:: toUtc(), toOffsetFromUtc(), toLocalZone(), toZone(), toTimeSpec(), toTime_t(), KTimeZone.convert()

QString toString	(	self,
		QString	format
	)

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

Note that if the instance has a time specification of ClockTime, the time zone or UTC offset in the result will be blank.

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

Parameters:

format

format for the string

Returns:: formatted string

See also:: fromString(), KLocale.formatDate()

QString toString	(	self,
		KDateTime.TimeFormat	format=KDateTime.ISODate
	)

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

Note that if the instance has a time specification of ClockTime, the UTC offset in the result will be blank, except for RFC 2822 format in which it will be the offset for the local system time zone.

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. It also applies to format = ISODate when the instance has a time specification of ClockTime. 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:

format

format for output string

Returns:: formatted string

See also:: fromString(), QDateTime.toString()

KDateTime toTimeSpec	(	self,
		KDateTime.Spec	spec
	)

Returns the time converted to a new time specification. If the instance is a local clock time, it is first set to the local time zone, and then converted to the spec time specification. If the instance is a date-only value, a date-only value is returned, with the date unchanged.

Parameters:

spec

new time specification

Returns:: converted time

See also:: toLocalZone(), toUtc(), toOffsetFromUtc(), toZone(), KTimeZone.convert()

KDateTime toTimeSpec	(	self,
		KDateTime	dt
	)

Returns the time converted to the time specification of another instance. If this instance is a local clock time, it is first set to the local time zone, and then converted to the spec time specification. If this instance is a date-only value, a date-only value is returned, with the date unchanged.

Parameters:

instance providing the new time specification

Returns:: converted time

See also:: toLocalZone(), toUtc(), toOffsetFromUtc(), toZone(), KTimeZone.convert()

long toTime_t ( self )

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()

KDateTime toUtc ( self )

Returns the time converted to UTC. The converted time has a UTC offset of zero. If the instance is a local clock time, it is first set to the local time zone, and then converted to UTC. 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(), toTime_t(), KTimeZone.convert()

KDateTime toZone	(	self,
		KTimeZone	zone
	)

Returns the time converted to a specified time zone. If the instance is a local clock time, it is first set to the local time zone, and then converted to zone. If the instance is a date-only value, a date-only value in zone is returned, with the date unchanged.

Parameters:

zone

time zone to convert to

Returns:: converted time

See also:: toUtc(), toOffsetFromUtc(), toLocalZone(), toTimeSpec(), KTimeZone.convert()

int utcOffset ( self )

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, or 0 if local clock time

See also:: isClockTime()

Enumeration Documentation

Comparison

How this KDateTime compares with another. If any date-only value is involved, comparison of KDateTime 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 = 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

SpecType

The time specification type of a KDateTime instance. This specifies how the date/time component of the KDateTime 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 KDateTime.Spec.

Enumerator:

Invalid
UTC
OffsetFromUTC
TimeZone
LocalZone
ClockTime

TimeFormat

Enumerator:

ISODate
RFCDate
RFCDateDay
QtTextDate
LocalDate

KDateTime Class Reference

Detailed Description

Enumerations

Methods

Static Methods

Method Documentation

Enumeration Documentation

Modules