This is an automatically generated e-mail. To reply, visit: http://svn.reviewb= oard.kde.org/r/5692/

Review request for kdelibs.

By John Layt.

Updated 2010-10-30 22:30:16.219842

Changes

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 K=
Locale and KCalendarSystem changes I've only posted the headers as that=
's the interesting part.

Updates:
1) Added lots of apidox, but still not finished, I just need a day off tomo=
rrow 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 ove=
rride.
4) Added KLocale::WeekNumberSystem enum and api for different Week Number S=
ystems (originally planned for 4.7), although we only have the ISO Weeks im=
plemented 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::DateTimeCompo=
nent enum to specify which component to return.  This cleans up a lot of me=
ssy api.  I've done the enum as flags so in the future we can do dynami=
c date formats, e.g. request just a Day and Month and have it automatically=
 formatted correctly for the locale without needing translations or extra D=
ateFormat enum values (again something originally planned to start in 4.7)
7) Added a DefaultComponentFormat value to the KLocale::DateTimeComponentFo=
rmat enum so I don't have to hard code default values into the api, all=
owing the default to be changed based on locale.

This is all in addition to the new KLocale::CalendarSystem enum I've po=
sted 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.

Phew!

Descripti= on

The KCalendarSystem api for localizing dates is awkward, inc=
onvenient, unintuitive, and long-winded, causing many mistakes to be made o=
r localization to be ignored altogether.  This change adds a new KDate clas=
s designed to make localizing dates as easy as using QDate.

Some QDate code may look like:

    QDate myDate( aYear, aMonth, aDay );
    int doy =3D myDate.dayOfYear();

The KDE localized date code looks something like:

    QDate myDate;
    KGlobal::locale()->calendar()->setDate( myDate, aYear, aMonth, aD=
ay );
    int doy =3D KGlobal::locale()->calendar()->dayOfYear( myDate );

The localized KDate code would look like:

    KDate myDate( aYear, aMonth, aDay );
    int doy =3D myDate.dayOfYear();

Much easier.

KDate is a thin wrapper around KCalendarSystem and QDate, with a near ident=
ical api to QDate and as such can be used as a drop-in replacement with ver=
y few changes.  Some deprecated or unnecessary KCalendarSystem methods have=
 not been included, but these can still be accessed via the calendar() meth=
ods.  Some new convenience methods have also been added such as setCurrentD=
ate() and addYearsOn().

Some methods have QDate overloads for convenience, and the assignment and c=
omparison 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 intern=
ally 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 th=
e case.  If people think this will be a problem KLocalizedDate is an altern=
ative if more awkward name.

Testing <= /h1>

Full unit tests included.

Diffs= (updated)

/trunk/KDE/kdelibs/kdecore/date/klocalizeddate.h (PRE-CREATION)
/trunk/KDE/kdelibs/kdecore/date/kcalendarsystem.h (1191250)
/trunk/KDE/kdelibs/kdecore/date/klocalizeddate.cpp (PRE-CREATION)
/trunk/KDE/kdelibs/kdecore/localization/klocale.h (1191250)

View Diff