KDECore

KDateTime Class Reference

#include <kdatetime.h>

Detailed Description

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

Topics:

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.

See also:: KTimeZone, KSystemTimeZones, QDateTime, QDate, QTime
W3C: Working with Time Zones

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

Definition at line 160 of file kdatetime.h.


Public Types
enum	SpecType { Invalid, UTC, OffsetFromUTC, TimeZone, LocalZone, ClockTime }
enum	TimeFormat { ISODate, RFCDate, RFCDateDay, QtTextDate, LocalDate }
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 }
Public Member Functions
	KDateTime ()
	KDateTime (const QDate &date, const Spec &spec=Spec(LocalZone))
	KDateTime (const QDate &date, const QTime &time, const Spec &spec=Spec(LocalZone))
	KDateTime (const QDateTime &dt, const Spec &spec)
	KDateTime (const QDateTime &dt)
	KDateTime (const KDateTime &other)
	~KDateTime ()
KDateTime &	operator= (const KDateTime &other)
bool	isNull () const
bool	isValid () const
bool	isDateOnly () const
QDate	date () const
QTime	time () const
QDateTime	dateTime () const
KTimeZone	timeZone () const
Spec	timeSpec () const
SpecType	timeType () const
bool	isLocalZone () const
bool	isClockTime () const
bool	isUtc () const
bool	isOffsetFromUtc () const
int	utcOffset () const
bool	isSecondOccurrence () const
KDateTime	toUtc () const
KDateTime	toOffsetFromUtc () const
KDateTime	toOffsetFromUtc (int utcOffset) const
KDateTime	toLocalZone () const
KDateTime	toClockTime () const
KDateTime	toZone (const KTimeZone &zone) const
KDateTime	toTimeSpec (const Spec &spec) const
KDateTime	toTimeSpec (const KDateTime &dt) const
uint	toTime_t () const
void	setTime_t (qint64 seconds)
void	setDateOnly (bool dateOnly)
void	setDate (const QDate &date)
void	setTime (const QTime &time)
void	setDateTime (const QDateTime &dt)
void	setTimeSpec (const Spec &spec)
void	setSecondOccurrence (bool second)
KDateTime	addMSecs (qint64 msecs) const
KDateTime	addSecs (qint64 secs) const
KDateTime	addDays (int days) const
KDateTime	addMonths (int months) const
KDateTime	addYears (int years) const
int	secsTo (const KDateTime &other) const
qint64	secsTo_long (const KDateTime &other) const
int	daysTo (const KDateTime &other) const
QString	toString (const QString &format) const
QString	toString (TimeFormat format=ISODate) const
bool	outOfRange () const
Comparison	compare (const KDateTime &other) const
bool	operator== (const KDateTime &other) const
bool	operator!= (const KDateTime &other) const
bool	operator< (const KDateTime &other) const
bool	operator<= (const KDateTime &other) const
bool	operator> (const KDateTime &other) const
bool	operator>= (const KDateTime &other) const
void	detach ()
Static Public Member Functions
static KDateTime	currentLocalDateTime ()
static KDateTime	currentUtcDateTime ()
static KDateTime	currentDateTime (const Spec &spec)
static KDateTime	fromString (const QString &string, TimeFormat format=ISODate, bool *negZero=0)
static KDateTime	fromString (const QString &string, const QString &format, const KTimeZones *zones=0, bool offsetIfAmbiguous=true)
static void	setFromStringDefault (const Spec &spec)
Friends
QDataStream &	operator<< (QDataStream &out, const KDateTime &dateTime)
QDataStream &	operator>> (QDataStream &in, KDateTime &dateTime)
Classes
class	Spec
	The full time specification of a KDateTime instance. More...

Member Enumeration Documentation

enum KDateTime::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	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 is the current system time zone (i.e. that returned by KSystemTimeZones::local()), LocalZone may be used instead.
LocalZone	a time in the current system time zone. When used to initialize a KDateTime or KDateTime::Spec instance, this is simply a shorthand for calling the setting method with a time zone parameter KSystemTimeZones::local(). Note that if the system is changed to a different time zone afterwards, the KDateTime instance will still use the original system time zone rather than adopting the new zone. When returned by a method, it indicates that the time zone stored in the instance is that currently returned by KSystemTimeZones::local().
ClockTime	a clock time which ignores time zones and simply uses whatever the local system clock says the time is. You could, for example, set a wake-up time of 07:30 on some date, and then no matter where you were in the world, you would be in time for breakfast as long as your computer was aligned with the local time. Note that any calculations which involve clock times cannot be guaranteed to be accurate, since by definition they contain no information about time zones or daylight savings changes.

Definition at line 170 of file kdatetime.h.

enum KDateTime::TimeFormat

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).
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 1036. 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.

Definition at line 408 of file kdatetime.h.

enum KDateTime::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	This KDateTime is strictly earlier than the other, i.e. e1 < s2.
AtStart	This KDateTime starts at the same time as the other, and ends before the end of the other, i.e. s1 = s2, e1 < e2.
Inside	This KDateTime starts after the start of the other, and ends before the end of the other, i.e. s1 > s2, e1 < e2.
AtEnd	This KDateTime starts after the start of the other, and ends at the same time as the other, i.e. s1 > s2, e1 = e2.
After	This KDateTime is strictly later than the other, i.e. s1 > e2.
Equal	Simultaneous, i.e. s1 = s2 && e1 = e2.
Outside	This KDateTime starts before the start of the other, and ends after the end of the other, i.e. s1 < s2, e1 > e2.
StartsAt	This KDateTime starts at the same time as the other, and ends after the end of the other, i.e. s1 = s2, e1 > e2.
EndsAt	This KDateTime 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 462 of file kdatetime.h.

Constructor & Destructor Documentation

KDateTime::KDateTime ( )

Constructs an invalid date/time.

Definition at line 773 of file kdatetime.cpp.

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

Parameters:

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

Definition at line 778 of file kdatetime.cpp.

KDateTime::KDateTime	(	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 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

Definition at line 785 of file kdatetime.cpp.

KDateTime::KDateTime	(	const QDateTime &	dt,
		const 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

Definition at line 792 of file kdatetime.cpp.

KDateTime::KDateTime ( const QDateTime & dt ) [explicit]

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

Definition at line 805 of file kdatetime.cpp.

KDateTime::KDateTime ( const KDateTime & other )

Definition at line 810 of file kdatetime.cpp.

KDateTime::~KDateTime ( )

Definition at line 815 of file kdatetime.cpp.

Member Function Documentation

KDateTime & KDateTime::operator= ( const KDateTime & other )

Definition at line 819 of file kdatetime.cpp.

bool KDateTime::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 826 of file kdatetime.cpp.

bool KDateTime::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 827 of file kdatetime.cpp.

bool KDateTime::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 829 of file kdatetime.cpp.

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

Definition at line 835 of file kdatetime.cpp.

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

Definition at line 836 of file kdatetime.cpp.

QDateTime KDateTime::dateTime ( ) const

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

Definition at line 837 of file kdatetime.cpp.

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

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

See also:: isUtc(), isLocal()

Definition at line 842 of file kdatetime.cpp.

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

Definition at line 839 of file kdatetime.cpp.

KDateTime::SpecType KDateTime::timeType ( ) const

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

Definition at line 840 of file kdatetime.cpp.

bool KDateTime::isLocalZone ( ) const

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

Definition at line 830 of file kdatetime.cpp.

bool KDateTime::isClockTime ( ) const

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

Returns:: true if local clock time

See also:: isUtc(), timeZone()

Definition at line 831 of file kdatetime.cpp.

bool KDateTime::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 832 of file kdatetime.cpp.

bool KDateTime::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 833 of file kdatetime.cpp.

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

See also:: isClockTime()

Definition at line 855 of file kdatetime.cpp.

bool KDateTime::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 834 of file kdatetime.cpp.

KDateTime KDateTime::toUtc ( ) const

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

Definition at line 868 of file kdatetime.cpp.

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

Definition at line 882 of file kdatetime.cpp.

KDateTime KDateTime::toOffsetFromUtc ( int utcOffset ) const

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

Definition at line 913 of file kdatetime.cpp.

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

Definition at line 924 of file kdatetime.cpp.

KDateTime KDateTime::toClockTime ( ) const

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

Definition at line 950 of file kdatetime.cpp.

KDateTime KDateTime::toZone ( const KTimeZone & zone ) const

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

Definition at line 963 of file kdatetime.cpp.

KDateTime KDateTime::toTimeSpec ( const Spec & spec ) const

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

Definition at line 981 of file kdatetime.cpp.

KDateTime KDateTime::toTimeSpec ( const KDateTime & dt ) const

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

Definition at line 976 of file kdatetime.cpp.

uint KDateTime::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 -1 if the date is out of range

See also:: setTime_t()

Definition at line 998 of file kdatetime.cpp.

void KDateTime::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:

seconds

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

See also:: toTime_t()

Definition at line 1003 of file kdatetime.cpp.

void KDateTime::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:

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

See also:: isDateOnly(), setTime()

Definition at line 1014 of file kdatetime.cpp.

void KDateTime::setDate ( const QDate & date )

Sets the date part of the date/time.

Parameters:

date

new date value

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

Definition at line 1019 of file kdatetime.cpp.

void KDateTime::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:

time

new time value

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

Definition at line 1024 of file kdatetime.cpp.

void KDateTime::setDateTime ( const QDateTime & dt )

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

If dt is a local time (

 dt.timeSpec() == Qt::LocalTime

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

Definition at line 1029 of file kdatetime.cpp.

void KDateTime::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 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()

Definition at line 1044 of file kdatetime.cpp.

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

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

Definition at line 1049 of file kdatetime.cpp.

KDateTime KDateTime::addMSecs ( qint64 msecs ) const

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

Definition at line 1064 of file kdatetime.cpp.

KDateTime KDateTime::addSecs ( qint64 secs ) const

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

Except when the instance is a local clock t

KDECore

KDateTime Class Reference

Detailed Description

Introduction

Date and Time Manipulation

QDateTime Considerations

Public Types

Public Member Functions

Static Public Member Functions

Friends

Classes

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation