KDE Core/QtMerge/QDateTime

The following are proposed additions to Qt's Date/Time support which KDE would like to see to enable dropping of our own Date/Time support, or would help improve Qt's localization under Win/OSX/CLDR.

Date Range

The date is stored as a Julian Day Number in a uint with jd == 0 considered to be invalid. This restricts dates to a range of 4713BC and later. Changing the uint into an int32 or a int64 will make this date range more useful scientifically. Invalidity (e.g. when adding and you go out-of-bounds) will probably need a bool.

Date/Time Format Codes

Goal: To add more date/time to/from string format codes

Rationale: Format codes part of standard CLDR, Posix, Windows and OSX date formats and localization, so Qt may not be localizing dates to country or users system date/time format. Many are string form of existing Qt api. Convenience for coders.

QDateTime formats are mostly based on the Unicode CLDR fomats:

• http://www.unicode.org/reports/tr35/tr35-15.html#Date_Format_Patterns

However only a sub-set of these are implemented. Qt currently supports the following format codes:

d    Day as a number without a leading zero (1 to 31)
dd   Day as a number with a leading zero (01 to 31)
ddd  Weekday abbreviated localized name (e.g. 'Mon' to 'Sun').
dddd Weekday long localized name (e.g. 'Monday' to 'Sunday').
M    Month as a number without a leading zero (1 to 12)
MM   Month as a number with a leading zero (01 to 12)
MMM  Month abbreviated localized name (e.g. 'Jan' to 'Dec').
MMMM Month long localized name (e.g. 'January' to 'December').
yy   Year as two digit number (00 to 99)
yyyy Year as four digit number. (-9999 to 9999)

h    Hour without a leading zero (0 to 23 or 1 to 12 if AM/PM)
hh   Hour with a leading zero (00 to 23 or 01 to 12 if AM/PM)
H    24 Hour without a leading zero (0 to 23)
HH   24 Hour with a leading zero (00 to 23)
m    Minute without a leading zero (0 to 59)
mm   Minute with a leading zero (00 to 59)
s    Second without a leading zero (0 to 59)
ss   Second with a leading zero (00 to 59)
z    Milliseconds without leading zeroes (0 to 999)
zzz  Milliseconds with leading zeroes (000 to 999)
AP   AM/PM uppercase
ap   AM/PM lowercase
A    AM/PM uppercase
a    AM/PM lowercase
t    Timezone (for example "CEST")

Note that:

ddd and dddd formats are not valid CLDR forms but derived from Windows, they should be EEE and EEEE instead.
AP and ap are not valid CLDR forms
h and hh do not exactly match the CLDR definition
t is not a valid CLDR form

The following CLDR codes are suggested to be supported:

ddddd Day narrow localized name (e.g. 'M' to 'S').
MMMMM Month narrow localized name (e.g. 'J' to 'D').
y     Year without a leading zero (1 to 9999)

D (1..3)
Day of Year, numeric with or without leading zeros.
Matches existing dayOfYear() api.

w (1-2)
Week of Year, numeric with or without leading zero.
Matches existing weekNumber() api.

Y (1..n)
Week year, e.g. for ISO Week Number year week falls in, forms to match y.
Matches existing weekNumber() api.

E (1..5)
Weekday, abbreviated (e.g. 'Mon'), long (e.g. 'Monday') and narrow (e.g. 'M')

G (1..5)
Era localized name, abbreviated (e.g. 'AD'), long (e.g. 'Anno Domini') and narrow (e.g. 'A')

z/Z/v/V
Timezones.  TODO.  Depends on QTime support.

The following CLDR codes may be implemented but are not considered as important:

Q (1..4)
Quarter in year, '2', '02', 'Q2' or '2nd Quarter'

W (1)
Week of Month, numeric.

F (1)
Day of Week In Month, e.g. if today is 2nd Monday in Month = 2

e (1..5)
Weekday, localized numeric (1 or 01), abbreviated (e.g. 'Mon'), long (e.g. 'Monday') and narrow (e.g. 'M').
Would require QLocale support for localized week number, i.e. US week as well as ISO week.

Support for the Stand Alone forms should also be considered.

The following new api will be required in QDateTime to support the format codes.

enum QDate::NameFormat( NarrowName, ShortName, LongName )
QString QDate::monthName(NameFormat format)
QString QDate::weekdayName(NameFormat format)
QStringQDate:: eraName(NameFormat format)
int QDate::quarter()
int QDate::weekOfMonth()
int QDate::weekdayInMonth()

Note the month and day name api are already marked for change in Qt5.

Date/Time Named Formats

Goal: To add more date/time named formats

Rationale: Convenience for coders

Qt currently provides the following named date formats via an enum:

   enum DateFormat {
       TextDate,      // default Qt
       ISODate,       // ISO 8601
       SystemLocaleShortDate,
       SystemLocaleLongDate,
       DefaultLocaleShortDate,
       DefaultLocaleLongDate
   };

The following named date/time formats would be useful:

ISOTime          ISO 8601 format time
                 "hh[:mm[:ss[.sss]]]TZ"
ISODateTime      ISO 8601 format date and time
                 "[±]YYYY-MM-DDThh[:mm[:ss[.sss]]]TZ"
RFCDateTime      RFC 822/850/1036/1123/2822 format
                 "[Wdy,] DD Mon YYYY hh:mm[:ss] ±hhmm"
                 "Wdy Mon DD HH:MM:SS YYYY"
RFCDateTimeDay   RFC format including day of the week
                 "Wdy, DD Mon YYYY hh:mm:ss ±hhmm"
RFC3339DateTime  RFC 3339 format
                 "YYYY-MM-DDThh:mm:ss[.sss](Z|±hh:mm)"
ISOWeekDate,     ISO 8601 Week Date format
                 "YYYY-Www-D", e.g. 2009-W01-1
ISOOrdinalDate   ISO 8601 Ordinal Date format
                 "YYYY-DDD", e.g. 2009-001

Note the ISO dates should accept both basic and expanded formats.

Calendar Systems

The following api changes will be required

isNull() - Will now indicate an invalid date in any calendar system, e.g. addition resulting in out-of-bounds
isValid() - Will now indicate if date is valid within current calendar system, but date may still be valid in another calendar system.

Widgets

The various widgets will need modification to match the new features and api.

From qt-interest list: QCalendarWidget to use Start of Week from Qlocale, but be able to override if needed.

Summary all api proposals

void QDate::setCalendarSystem(CalendarSystem)
CalendarSystem QDate::calendarSystem()
QDate::setLocale(QString)???
QString QDate::locale()???

bool QDate::isValidOrdinalDate(int year, int dayOfYear)
bool QDate::setOrdinalDate(int year, int dayOfYear)

bool QDate::isValidEraDate(QString eraName, int yearInEra, int month, int day)
bool QDate::setEraDate(QString eraName, int yearInEra, int month, int day)

bool QDate::isValidWeekDate(int year, int weekOfYear, int dayOfWeek)
bool QDate::setWeekDate(int year, int weekOfYear, int dayOfWeek)

QString QDate::eraName()
int QDate::yearInEra()

int QDate::monthsInYear()
int QDate::weeksInYear()

enum QDate::NameFormat( NarrowName, ShortName, LongName )
QString QDate::monthName(NameFormat format)
QString QDate::weekdayName(NameFormat format)
QStringQDate:: eraName(NameFormat format)
int QDate::quarter()
int QDate::weekOfMonth()
int QDate::weekdayInMonth()

void QDate::dateDifference(const QDate &toDate, int *years, int *months, int *days, int *dir)
int QDate::yearsDifference(const QDate &toDate)
int QDate::monthsDifference(const QDate &toDate)
int QDate::daysDifference(const QDate &toDate)

QDate QDate::firstDayOfYear()
QDate QDate::lastDayOfYear()
QDate QDate::firstDayOfMonth()
QDate QDate::lastDayOfMonth()