[icu-design] proposal on interval date format API change from ICU4.0 d02 (part2)

[xiaomei j. <xia...@gm...>]

One more change from today's review:

in DateIntervalInfo:
previously:
   void setFallbackIntervalPattern(const UnicodeString& fallbackPattern);

Will be changed to:
    void setFallbackIntervalPattern(const UnicodeString& fallbackPattern,
                                    UErrorCode& status);


reasoning: it would be better if we validate the fallback pattern user set.
In which case, we need an error code to set for wrong pattern.

Please let me know if there is any problems.

Thanks,
Xiaomei




---------- Forwarded message ----------
From: xiaomei ji <xia...@gm...>
Date: Thu, Jun 12, 2008 at 7:39 PM
Subject: proposal on interval date format API change from ICU4.0 d02
To: icu...@li...


Andy is reviewing the date interval format code. After some discussion with
Mark, we proposed the following API changes:

1. In DateIntervalFormat
1.1  DateIntervalFormat factory methods:

The 2 factory methods which take a pointer of DateIntervalInfo as parameter,

will be changed to take a const reference of DateIntervalInfo as parameter.

For example:
     static DateIntervalFormat* U_EXPORT2 createInstance(
                                               const UnicodeString&
skeleton,
                                              DateIntervalInfo* dtitvinf,
                                               UErrorCode& status);


will change to:
     static DateIntervalFormat* U_EXPORT2 createInstance(
                                               const UnicodeString&
skeleton,
                                               const DateIntervalInfo&
dtitvinf,
                                               UErrorCode& status);


The reason is: taking pointer of DateIntervalInfo as parameter means
DateIntervalFormat takes ownership of DateIntervalInfo, which means if user
wants to re-use this DateIntervalInfo, he needs to clone it.
Instead of putting this burden to user,  DateIntervalFormat takes care of
the clone.

Currently, DateIntervalInfo is not shared. If there is performance hit
later, we will improve it.



1. 2.
The following 2 adopt methods will be removed:
    void adoptDateIntervalInfo(DateIntervalInfo* newIntervalPatterns,
                               UErrorCode& status);

    void adoptDateFormat(DateFormat* newDateFormat, UErrorCode& status);

The following  setter will be removed. And it applies to Java too.
    void setDateFormat(const DateFormat& newDateFormat, UErrorCode& status);


The reason are: there is no clear usage scenario of the adopt methods. As to
the setter, there is no clear usage of it, and it is not symmetric to the
factory method ( all the factory methods take skeleton as parameter, none of
them takes date formatter as parameter), and the functionality is not very
clear on whether we should re-set the skeleton or not when reset the date
formatter.
If we want them later, it is always easier to add them in than removing
them.



1. 3.

Since parseObject() is not supported, will change it to be internal instead
of public. And it applies to Java too.



2.. in DateFormat

the newly added internal API will take one more parameter -- the error code

     static DateFormat* U_EXPORT2 createPatternInstance(
                                                 const UnicodeString&
skeleton,
                                                const Locale& locale);


will be changed to:
     static DateFormat* U_EXPORT2 createPatternInstance(
                                                 const UnicodeString&
skeleton,
                                                const Locale& locale,
                                                UErrorCode& status);



3. some other changes:
3.1. in DateIntervalInfo: make the clone() and operator==() as virtual
functions.
3.2. in DateInterval: make destructor; clone(), and operator==() as virtual
functions, remove the non-necessary "const" from "const UDate" in
constructor.



Please let me know if you have any questions on those changes.

Thanks,
Xiaomei