Review Request: Add new KDate class to simplify date localization
johnlayt at googlemail.com
Sat Oct 30 23:30:16 BST 2010
This is an automatically generated e-mail. To reply, visit:
(Updated 2010-10-30 22:30:16.219842)
Review request for kdelibs.
Crikey, what started as a quick one night hack has now taken on a life of it's own with tentacles reaching everywhere, but it's good to get the new api right up front then have to hack it around later. I've only posted the KLocalizedDate implementation, for the upstream KLocale and KCalendarSystem changes I've only posted the headers as that's the interesting part.
1) Added lots of apidox, but still not finished, I just need a day off tomorrow so I'm posting it so the api can have another going over :-)
2) Figured out how to allow special use case for setting custom Locales and Calendar Systems, this is fully documented in the apidox.
3) Made readDate() methods static using global local but with option to override.
4) Added KLocale::WeekNumberSystem enum and api for different Week Number Systems (originally planned for 4.7), although we only have the ISO Weeks implemented at the moment.
5) Added KLocale::DateTimeParseMode enum and api for setting strictness of date parsing (originally planned for 4.7), although only Liberal parsing is available for now.
6) Removed all the dayString() type methods and replaced them with a single formatDateComponent() method. This call uses a new KLocale::DateTimeComponent enum to specify which component to return. This cleans up a lot of messy api. I've done the enum as flags so in the future we can do dynamic date formats, e.g. request just a Day and Month and have it automatically formatted correctly for the locale without needing translations or extra DateFormat enum values (again something originally planned to start in 4.7)
7) Added a DefaultComponentFormat value to the KLocale::DateTimeComponentFormat enum so I don't have to hard code default values into the api, allowing the default to be changed based on locale.
This is all in addition to the new KLocale::CalendarSystem enum I've posted in a separate review, which KLocalizedDate now uses.
There's a few new enums there that are placeholders for now, but I'd rather get them into the api now than have to duplicate api later.
The KCalendarSystem api for localizing dates is awkward, inconvenient, unintuitive, and long-winded, causing many mistakes to be made or localization to be ignored altogether. This change adds a new KDate class designed to make localizing dates as easy as using QDate.
Some QDate code may look like:
QDate myDate( aYear, aMonth, aDay );
int doy = myDate.dayOfYear();
The KDE localized date code looks something like:
KGlobal::locale()->calendar()->setDate( myDate, aYear, aMonth, aDay );
int doy = KGlobal::locale()->calendar()->dayOfYear( myDate );
The localized KDate code would look like:
KDate myDate( aYear, aMonth, aDay );
int doy = myDate.dayOfYear();
KDate is a thin wrapper around KCalendarSystem and QDate, with a near identical api to QDate and as such can be used as a drop-in replacement with very few changes. Some deprecated or unnecessary KCalendarSystem methods have not been included, but these can still be accessed via the calendar() methods. Some new convenience methods have also been added such as setCurrentDate() and addYearsOn().
Some methods have QDate overloads for convenience, and the assignment and comparison operators partially work with QDate on the rhs. If anyone knows how to make it work with QDate on the lhs, or any other QDate compatibility ideas, I'm all ears.
For now I only intend this to be used as a convenience class by apps internally and not to be used in kdelibs api as I don't see much advantage in that, but I may do so if the demand for convenience is there.
I have named it KDate, but there is the possibility people may get confused and think that KDateTime also localizes datetime's, but that is not the case. If people think this will be a problem KLocalizedDate is an alternative if more awkward name.
Full unit tests included.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the kde-core-devel