[prev in list] [next in list] [prev in thread] [next in thread]
List: kde-core-devel
Subject: Re: Review Request: Add new KDate class to simplify date localization
From: "John Layt" <johnlayt () googlemail ! com>
Date: 2010-10-30 22:30:16
Message-ID: 20101030223016.4476.80012 () vidsolbach ! de
[Download RAW message or body]
-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
http://svn.reviewboard.kde.org/r/5692/
-----------------------------------------------------------
(Updated 2010-10-30 22:30:16.219842)
Review request for kdelibs.
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 KLocale 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 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.
Phew!
Summary
-------
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:
QDate myDate;
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();
Much easier.
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.
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
Diff: http://svn.reviewboard.kde.org/r/5692/diff
Testing
-------
Full unit tests included.
Thanks,
John
[Attachment #3 (text/html)]
<html>
<body>
<div style="font-family: Verdana, Arial, Helvetica, Sans-Serif;">
<table bgcolor="#f9f3c9" width="100%" cellpadding="8" style="border: 1px #c9c399 \
solid;"> <tr>
<td>
This is an automatically generated e-mail. To reply, visit:
<a href="http://svn.reviewboard.kde.org/r/5692/">http://svn.reviewboard.kde.org/r/5692/</a>
</td>
</tr>
</table>
<br />
<table bgcolor="#fefadf" width="100%" cellspacing="0" cellpadding="8" \
style="background-image: \
url('http://svn.reviewboard.kde.orgrb/images/review_request_box_top_bg.png'); \
background-position: left top; background-repeat: repeat-x; border: 1px black \
solid;"> <tr>
<td>
<div>Review request for kdelibs.</div>
<div>By John Layt.</div>
<p style="color: grey;"><i>Updated 2010-10-30 22:30:16.219842</i></p>
<h1 style="color: #575012; font-size: 10pt; margin-top: 1.5em;">Changes</h1>
<table width="100%" bgcolor="#ffffff" cellspacing="0" cellpadding="10" style="border: \
1px solid #b8b5a0"> <tr>
<td>
<pre style="margin: 0; padding: 0; white-space: pre-wrap; white-space: \
-moz-pre-wrap; white-space: -pre-wrap; white-space: -o-pre-wrap; word-wrap: \
break-word;">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.
Updates:
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.
Phew!</pre>
</td>
</tr>
</table>
<h1 style="color: #575012; font-size: 10pt; margin-top: 1.5em;">Description </h1>
<table width="100%" bgcolor="#ffffff" cellspacing="0" cellpadding="10" style="border: \
1px solid #b8b5a0"> <tr>
<td>
<pre style="margin: 0; padding: 0; white-space: pre-wrap; white-space: \
-moz-pre-wrap; white-space: -pre-wrap; white-space: -o-pre-wrap; word-wrap: \
break-word;">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:
QDate myDate;
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();
Much easier.
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.</pre> </td>
</tr>
</table>
<h1 style="color: #575012; font-size: 10pt; margin-top: 1.5em;">Testing </h1>
<table width="100%" bgcolor="#ffffff" cellspacing="0" cellpadding="10" style="border: \
1px solid #b8b5a0"> <tr>
<td>
<pre style="margin: 0; padding: 0; white-space: pre-wrap; white-space: \
-moz-pre-wrap; white-space: -pre-wrap; white-space: -o-pre-wrap; word-wrap: \
break-word;">Full unit tests included.</pre> </td>
</tr>
</table>
<h1 style="color: #575012; font-size: 10pt; margin-top: 1.5em;">Diffs</b> \
(updated)</h1> <ul style="margin-left: 3em; padding-left: 0;">
<li>/trunk/KDE/kdelibs/kdecore/date/klocalizeddate.h <span style="color: \
grey">(PRE-CREATION)</span></li>
<li>/trunk/KDE/kdelibs/kdecore/date/kcalendarsystem.h <span style="color: \
grey">(1191250)</span></li>
<li>/trunk/KDE/kdelibs/kdecore/date/klocalizeddate.cpp <span style="color: \
grey">(PRE-CREATION)</span></li>
<li>/trunk/KDE/kdelibs/kdecore/localization/klocale.h <span style="color: \
grey">(1191250)</span></li>
</ul>
<p><a href="http://svn.reviewboard.kde.org/r/5692/diff/" style="margin-left: \
3em;">View Diff</a></p>
</td>
</tr>
</table>
</div>
</body>
</html>
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic