[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-core-devel
Subject:    Review Request: Add more date formatting options
From:       "John Layt" <johnlayt () googlemail ! com>
Date:       2009-11-15 2:21:16
Message-ID: 20091115022116.10402.32161 () localhost
[Download RAW message or body]


-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
http://reviewboard.kde.org/r/2177/
-----------------------------------------------------------

Review request for kdelibs.


Summary
-------

This change adds a number of new options for date formatting.

1) New versions of formatDate() and readDate() have already been added to \
KCalendarSystem in 4.4 to accept a date format string of the coders choice rather \
than the locale defaults.  This saves coders writing something like:

    KLocale *myLocale = new KLocale( *KGlobal::locale() );
    myLocale->setDateFormatShort( "%m %d" );
    QString myDateString = myLocal->dateFormat( myDate, KLocale::ShortDate );

They can now write:

    QString myDateString = KGlobal::locale()->calendar()->dateFormat( myDate, "%m %d" \
);

This change adds new format codes to these methods to bring them into line with the C \
/ POSIX / CU / GNU standards:

The following codes are added to formatDate():

    %C the 'century' portion of the year
    %j the day of the year number to three digits (e.g. "001"  for 1 Jan)
    %V the ISO week of the year number to two digits
    %G the year number in long form of the ISO week of the year
    %g the year number in short form of the ISO week of the year
    %u the day of the week number (e.g. "1"  for Monday)
    %D the US short date format (e.g. "%m/%d/%y")
    %F the ISO short date format (e.g. "%Y-%m-%d")
    %x the KDE locale short date format
    %t a tab character

formatDate() also adds the ability to define the case modifier, padding character, \
and padding width as defined in the GNU version of the standard, e.g. "%05Y" = \
"02009".  See the comprehensive apidox documentation for details.

There are 2 significant differences between the long-standing KDE implementation and \
the standard:

    %e in GNU/POSIX is space padded to 2 digits, in KDE is not padded
    %n in GNU/POSIX is newline, in KDE is short month number

Should we fix these to match the standard, or just live with them?

The following codes are added to readDate():

	%j the day of the year number
	%V the ISO week of the year number
	%u the day of the week number

Note that only the codes supported by readDate() will be allowed to be used in the \
locale global date formats, and coders are encouraged to use the locale formats \
unless really necessary.

2) New isValid() and setDate() methods to validate and set the date using either Year \
and Day of Year, or Year, ISO Week Number, and Day of Week number, as required by the \
readDate() changes above and as defined in the ISO standard.

3) KDE4.3 introduced the ability to use different numeric Digit Sets, e.g. \
Arabic-Indic or Devenagari instead of Arabic.  While some numeric methods in \
KCalendarSystem have versions to return a string form which returns the correct digit \
set (e.g. day() and dayString()), many do not have a string version such as \
weekNumber().  This means a coder needs to know and remember to do the digit set \
conversion themselves:

    KGlobal::locale()->convertDigits(KGlobal::locale()->calendar()->weekNumber(date), \
locale()->dateTimeDigitSet());

This change adds the following convenience methods to improve this:

    monthsInYearString()
    weeksInYearString()
    daysInYearString()
    daysInMonthString()
    daysInWeekString()
    dayOfYearString()
    dayOfWeekString()
    weekNumberString()

The existing string methods have all been converted to use the formatDate() method.

4) A change this big to something so core couldn't be done without significant \
testing.  The first real comprehensive unit tests for formatDate() and readDate() are \
included.  In fact, the test cases took longer to write than the code :-)

5) A number of corner-case bugs were uncovered in the existing code by the new test \
cases which have been fixed as well.


Diffs
-----

  trunk/KDE/kdelibs/kdecore/date/kcalendarsystem.h 1046844 
  trunk/KDE/kdelibs/kdecore/date/kcalendarsystem.cpp 1046844 
  trunk/KDE/kdelibs/kdecore/date/kcalendarsystemgregorian.cpp 1046844 
  trunk/KDE/kdelibs/kdecore/tests/kcalendartest.h 1046844 
  trunk/KDE/kdelibs/kdecore/tests/kcalendartest.cpp 1046844 

Diff: http://reviewboard.kde.org/r/2177/diff


Testing
-------

Extensive new unit tests written, as attached, which showed up a number of bugs in \
the existing code.  More tests to be added for rest of calendar systems in next few \
weeks.


Thanks,

John


[prev in list] [next in list] [prev in thread] [next in thread]