class KDateTime


Module kdecore
Namespace
Class KDateTime
Inherits
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.

See also KTimeZone, KSystemTimeZones, QDateTime, QDate, QTime

See also W3C: Working with Time Zones Author David Jarvie \.



enums

enum details

methods