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,and is not Source Compatible with Qt4. The Qt4 API is inconsistent 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 will simply be using the default toString()/fromString() methods.

Replace the old enums:

 enum QLocale::FormatType { LongFormat, ShortFormat, NarrowFormat };

 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 };

with new 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 = -1,  // i.e. locale default
                                GregorianCalendar = 0,
                                ... };

 // CLDR year type attribute
 // Would prefer in QDateTime namespace, but needed for QLocale::monthName()
 enum QLocale::YearType { StandardYear, LeapYear }

 enum QDateTime::DateTimeFormat { IsoFormat,
                                  RfcFormat,
                                  Rfc3339Format,	
                                  WeekFormat,
                                  OrdinalFormat };

Replace the old 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;

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

with new name methods:

 QString QLocale::monthName(int month,
                            FieldFormat format = LongName,
                            FieldContext context = FormatContext,
                            YearType yearType = StandardYear,
                            CalendarSystem calendar = DefaultCalendar) const;
 QString QLocale::weekdayName(int weekday,
                              FieldFormat format = LongName,
                              FieldContext context = FormatContext,
                              CalendarSystem calendar = DefaultCalendar) const;

and extend with new feature name methods:

 QString QLocale::quarterName(int quarter,
                              FieldFormat format = LongName,
                              FieldContext context = FormatContext,
                              CalendarSystem calendar = DefaultCalendar) const;
 QString QLocale::eraName(int year,
                          FieldFormat format = LongName,
                          FieldContext context = FormatContext,
                          CalendarSystem calendar = DefaultCalendar) const;
 QString QLocale::calendarName(CalendarSystem calendar = DefaultCalendar,
                               FieldFormat format = LongName,
                               FieldContext context = FormatContext) const;
 QString QLocale::dayPeriodName(QTime time,
                                FieldFormat format = LongName,
                                FieldContext context = FormatContext,
                                CalendarSystem calendar = DefaultCalendar) const;

Note the QDate methods are removed as being redundent, see also the QDate::setLocale() method below.

Modify the date/time format methods to use the new enums:

 QString QLocale::dateFormat(StringFormat format = LongFormat);
 QString QLocale::timeFormat(StringFormat format = LongFormat);
 QString QLocale::dateTimeFormat(StringFormat format = LongFormat);

Remove all the QLocale toString(), toDate(), toTime(), toDateTime() methods, all formatting/parsing to be done in QDate/QTime/QDateTime

Replace all the QDate toString() and fromString() methods with the following:

 QString QDate::toString(const QString &format) const;
 QString QDate::toString(QLocale::StringFormat format = QLocale::LongFormat) const;
 QString QDate::toString(QDateTime::DateTimeFormat format) const;

 static QDate QDate::fromString(const QString &string, const QString &format);
 static QDate QDate::fromString(const QString &string, QLocale::StringFormat format = QLocale::LongFormat);
 static QDate QDate::fromString(const QString &string, QDateTime::DateTimeFormat format);

Repeat exactly the same for QTime and QDateTime.

Add the following new methods to support calendar systems:

 CalendarSystem QLocale::calendarSystem()            // locale default calendar
 QList<CalendarSystem> QLocale::calendarSystems()    // locale preferred list
 QList<CalendarSystem> QLocale::allCalendarSystems() // all calendars list

 void QDate::setCalendarSystem(KLocale::CalendarSystem calendar);
 QLocale::CalendarSystem QDate::calendarSystem();

 void QDate::setLocale(const QLocale & locale);
 QLocale QDate::locale();

 int QDate::eraYear()
 int QDate::monthsInYear()
 int QDate::weeksInYear()
 int QDate::daysInWeek()