KDE Core/QtMerge/QDateTime
The initial proposal for merging KDE features in Qt5 as presented at QtCS is documented on the QtCS wiki at http://developer.qt.nokia.com/groups/qt_contributors_summit/wiki/QDateTime
This page documents specific API proposals.
Full CLDR Date Format and Calendar System support
The CLDR Date Format support and Calendar System support are closely connected and need to be designed together, although they will be separately implemented. The following API design is based on the CLDR standard.
Backwards source compatibility is required to be maintained by the QDate class using the QT4_COMPAT directive.
The Qt4 API is inconsistent, incomplete, and requires modification to fully support CLDR, so the opportunity should be taken to fully overhaul the API. Most apps will be unaffected as they should simply be using the default toString()/fromString() methods.
Object Model
The physical object model is still uncertain. The logical model is as follows:
QLocale - The locale class, container for type of calendar system, date/time formats, and date/time name translations, and accessor methods to format/parse date/times in that locale. Existing class to be modified.
QDate - A container class to hold a Julian Day number. Shouldn't have any ymd or string methods, but to maintain full backwards compatibility will use QT4_COMPAT for all existing ymd and string methods.
QDateCalculator. A calculator class for converting a QDate to/from YMD values. No virtuals to be used.
QDateTimeParser - Takes an input string, date/time format, and locale and returns a QDateTime. Existing private class to be modified.
QDateTimeFormatter - Takes a QDateTime, date/time format and locale and returns a QString. New private class based on the QLocale formatter. The QDateTime formatter is to be deleted.
The QDateCalculator will be awkward to use directly so we will provide either a QLocalDate class combining all the above in a single convenience wrapper, or a method on QDate to access the calculator such as QDate::calendar(), or both.
API Changes
Deprecate the old Qt and QDate enums:
// Merges both format and field type!
enum QLocale::FormatType { LongFormat, ShortFormat, NarrowFormat };
// Used for both month and day names!
enum QDate::MonthNameType { DateFormat = 0, StandaloneFormat };
enum Qt::DateFormat { TextDate, // default Qt
ISODate, // ISO 8601
SystemLocaleDate, // deprecated
LocalDate = SystemLocaleDate, // deprecated
LocaleDate, // deprecated
SystemLocaleShortDate,
SystemLocaleLongDate,
DefaultLocaleShortDate,
DefaultLocaleLongDate };
Delete or Deprecate the old QLocale enums:
// Merges both format type and field type!
enum QLocale::FormatType { LongFormat, ShortFormat, NarrowFormat };
Add new QLocale enums:
// CLDR format length attribute for date/time/number/currency
enum QLocale::StringFormat { FullFormat,
LongFormat,
MediumFormat,
ShortFormat };
// CLDR field width attribute
enum QLocale::FieldFormat { LongName, // e.g. January
ShortName, // e.g. Jan
NarrowName, // e.g. J
LongNumber, // e.g. 01
ShortNumber }; // e.g. 1
// CLDR context attribute
enum QLocale::FieldContext { FormatContext, // Use in a format
StandaloneContext }; // Use standalone
// CLDR calendar attribute
enum QLocale::CalendarSystem { DefaultCalendar = 0, // i.e. locale default
GregorianCalendar = 1,
JulianCalendar = 2,
... };
// CLDR year type attribute, in Qt or QDateTime namespace instead?
enum QLocale::YearType { StandardYear, LeapYear }
// CLDR date time fields, maybe in Qt or QLocale namespace?
enum QDateTime::DateTimeField { Year, Month, Day, Hour, Minute, Second, ... }
// Common standard formats, maybe in Qt or QLocale namespace?
enum QDateTime::DateTimeFormat { IsoFormat,
RfcFormat,
Rfc3339Format,
WeekFormat,
OrdinalFormat };
Add new QLocale calendar sytem methods:
CalendarSystem QLocale::calendarSystem(); const // current calendar, usually locale default
QList<CalendarSystem> QLocale::calendarSystems() const; // locale preferred list
QList<CalendarSystem> QLocale::allCalendarSystems() const; // all calendars list
QDateCalculator QLocale::calendar(); // current calendar calculator
Deprecate the old QDate name methods:
static QString QDate::shortMonthName(int month, MonthNameType type = QDate::DateFormat);
static QString QDate::shortDayName(int weekday, MonthNameType type = QDate::DateFormat);
static QString QDate::longMonthName(int month, MonthNameType type = QDate::DateFormat);
static QString QDate::longDayName(int weekday, MonthNameType type = QDate::DateFormat);
Delete or Deprecate the old QLocale name methods:
QString QLocale::monthName(int month, FormatType format = LongFormat) const;
QString QLocale::standaloneMonthName(int month, FormatType format = LongFormat) const;
QString QLocale::dayName(int weekday, FormatType format = LongFormat) const;
QString QLocale::standaloneDayName(int weekday, FormatType format = LongFormat) const;
QString QLocale::amText() const;
QString QLocale::pmText() const;
Add new QLocale name methods:
QString QLocale::monthName(int month,
FieldFormat format = LongName,
FieldContext context = StandaloneContext,
YearType yearType = StandardYear,
CalendarSystem calendar = DefaultCalendar) const;
QString QLocale::weekdayName(int weekday,
FieldFormat format = LongName,
FieldContext context = StandaloneContext,
CalendarSystem calendar = DefaultCalendar) const;
QString QLocale::dayPeriodName(QTime time,
FieldFormat format = LongName,
FieldContext context = StandaloneContext,
CalendarSystem calendar = DefaultCalendar) const;
QString QLocale::eraName(int year,
FieldFormat format = LongName,
FieldContext context = StandaloneContext,
CalendarSystem calendar = DefaultCalendar) const;
QString QLocale::quarterName(int quarter,
FieldFormat format = LongName,
FieldContext context = StandaloneContext,
CalendarSystem calendar = DefaultCalendar) const;
QString QLocale::calendarName(CalendarSystem calendar = DefaultCalendar,
FieldFormat format = LongName,
FieldContext context = Standaloneontext) const;
Modify the QLocale date/time format methods:
QString QLocale::dateFormat(FormatType format = LongFormat) const;
QString QLocale::timeFormat(FormatType format = LongFormat) const;
QString QLocale::dateTimeFormat(FormatType format = LongFormat) const;
to replace FormatType with StringType:
QString QLocale::dateFormat(StringFormat format = LongFormat) const;
QString QLocale::timeFormat(StringFormat format = LongFormat) const;
QString QLocale::dateTimeFormat(StringFormat format = LongFormat) const;
Deprecate all the QDateTime toString() and fromString() methods:
QString QDate::toString(Qt::DateFormat f = Qt::TextDate) const;
QString QDate::toString(const QString &format) const;
static QDate QDate::fromString(const QString &s, Qt::DateFormat f = Qt::TextDate);
static QDate QDate::fromString(const QString &s, const QString &format);
QString QTime::toString(Qt::DateFormat f = Qt::TextDate) const;
QString QTime::toString(const QString &format) const;
static QTime QTime::fromString(const QString &s, Qt::DateFormat f = Qt::TextDate);
static QTime QTime::fromString(const QString &s, const QString &format);
QString QDateTime::toString(Qt::DateFormat f = Qt::TextDate) const;
QString QDateTime::toString(const QString &format) const;
static QDateTime QDateTime::fromString(const QString &s, Qt::DateFormat f = Qt::TextDate);
static QDateTime QDateTime::fromString(const QString &s, const QString &format);
Mondify the QLocale toString() and fromString() methods:
QString QLocale::toString(const QDate &date, FormatType format = LongFormat) const;
QString QLocale::toString(const QTime &time, FormatType format = LongFormat) const;
QString QLocale::toString(const QDateTime &dateTime, FormatType format = LongFormat) const;
QDate QLocale::toDate(const QString &string, FormatType = LongFormat) const;
QTime QLocale::toTime(const QString &string, FormatType = LongFormat) const;
QDateTime QLocale::toDateTime(const QString &string, FormatType format = LongFormat) const;
to replace FormatType with StringType:
QString QLocale::toString(const QDate &date, StringType format = LongFormat) const;
QString QLocale::toString(const QTime &time, StringType format = LongFormat) const;
QString QLocale::toString(const QDateTime &dateTime, StringType format = LongFormat) const;
QDate QLocale::toDate(const QString &string, StringType = LongFormat) const;
QTime QLocale::toTime(const QString &string, StringType = LongFormat) const;
QDateTime QLocale::toDateTime(const QString &string, StringType format = LongFormat) const;
Add the following new toString/fromSting methods to QLocale
QString QLocale::toString(const QDate &date, QDateTime::DateTimeFormat format) const;
QString QLocale::toString(const QTime &time, QDateTime::DateTimeFormat format) const;
QString QLocale::toString(const QDateTime &dateTime, QDateTime::DateTimeFormat format) const;
QString QLocale::toString(const QDate &date, QDateTime::DateTimeField field,
FieldFormat format = LongName, FieldContext context = StandaloneContext) const;
QString QLocale::toString(const QTime &time, QDateTime::DateTimeField field,
FieldFormat format = LongName, FieldContext context = StandaloneContext) const;
QString QLocale::toString(const QDateTime &dateTime, QDateTime::DateTimeField field,
FieldFormat format = LongName, FieldContext context = StandaloneContext) const;
QDate QLocale::toDate(const QString &string, QDateTime::DateTimeFormat format) const;
QTime QLocale::toTime(const QString &string, QDateTime::DateTimeFormat format) const;
QDateTime QLocale::toDateTime(const QString &string, QDateTime::DateTimeFormat format) const;
QDate QLocale::toDate(const QString &string, QDateTime::DateTimeField field,
FieldFormat format = LongName, FieldContext context = StandaloneContext) const;
QTime QLocale::toTime(const QString &string, QDateTime::DateTimeField field,
FieldFormat format = LongName, FieldContext context = StandaloneContext) const;
QDateTime QLocale::toDateTime(const QString &string, QDateTime::DateTimeField field,
FieldFormat format = LongName, FieldContext context = StandaloneContext) const;
Modify the existing string date field format codes to be CLDR compliant as follows:
ddd - Weekday - Change to EEE
dddd - Weekday - Change to EEEE
AP - AM/PM - Remove, already have A
ap - am/pm - Remove, already have a
h - Hour - Modify behaviour to match CLDR
hh - Hour - Modify behaviour to match CLDR
t - Timezone - Change to z
Add new CLDR date field format codes for existing or new api:
ddddd - Weekday narrow name
MMMMM - Month narrow name
y - Year without leading zeros
d - Day of Year
w - Week of Year
Y - Week Year
L - Stand-alone Month
e - Weekday
E - Weekday
c - Stand-alone Weekday
G - Era name
z - Timezone
Z - Timezone
v - Timezone
V - Timezone
Q - Quarter of Year
q - Stand-alone Quarter of Year
W - Week of Month
F - Day of Week In Month
QDate API changes
The following QDate YMD methods will be deprecated using QT4_COMPAT:
QDate(int y, int m, int d);
int year() const;
int month() const;
int day() const;
int dayOfWeek() const;
int dayOfYear() const;
int daysInMonth() const;
int daysInYear() const;
int weekNumber(int *yearNum = 0) const;
bool setDate(int year, int month, int day);
void getDate(int *year, int *month, int *day);
QDate addDays(int days) const;
QDate addMonths(int months) const;
QDate addYears(int years) const;
int daysTo(const QDate &) const;
static bool isValid(int y, int m, int d);
static bool isLeapYear(int year);
The following new methods or variations will be added:
static QDate gregorianDate(int year, int month, int day);
static QDate localDate(int year, int month, int day, QLocale::CalendarSystem calSys = QLocale::DefaultCalendar);
Implementation Plan
The following phased implementation is planned:
- Clean-up current code where required. All existing tests should still pass.
- Separate private QDateTimeParser into own file. All existing tests should still pass.
- Create new private QDateTimeFormatter class, move current formatting code from QLocale into QDateTimeFormatter, change QDateTime to make calls to it. Delete QDateTime formatter code. All existing tests should still pass.
- Create new QDateCalculator class implementing most calendars. Write new unit tests.
Still fuzzy:
- Change QDateTimeFormatter and QDateTimeParser to fix the currently supported field codes to be CLDR compliant. Modify existing tests to ensure they still pass.
- Implement new formatting api but making calls to existing backend code, for options that don't yet have the backend coded just translate to a sensible replacement, i.e. for FullDate return LongDate. Only supported CalendarSystem is DefaultCalendar. All existing tests should still pass.
- Add to QDateTimeFormatter and QDateTimeParser the CLDR field codes that are already supported by existing QDate api. Write new tests.
- Convert unit tests from old api to new api. All existing tests should still pass.
- Convert widgets and other Qt code to new api. All existing tests should still pass.
- Remove old api. All existing tests should still pass.
- Modify QLocale CLDR backend to return full set of values for new api. Write new tests.
- Modify QLocale Mac backend to return full set of values for new api. Write new tests.
- Modify QLocale Windows backend to return full set of values for new api. Write new tests.
- Add Era support
- Add Week Date support