[icu-design] ICU4C 61 API Discussion/Proposal: API for date/time field names

[Peter E. <pe...@ap...>]

Dear ICU team & users,

I would like to discuss the following API issues for ICU 61, and possibly agree on an API to solve them.
Please provide feedback by: next Wednesday, 2018-02-14
Designated API discussant: Yoshito
Ticket: http://bugs.icu-project.org/trac/ticket/12740 <http://bugs.icu-project.org/trac/ticket/12740> 

A. Background

Currently the CLDR data in ICU provides localized display names for various date/time fields which correspond to the DateTimePatternGenerator fields, as shown in the table below.

  CLDR wide key*  J selector            C UDateTimePatternField value
  --------------  --------------------  --------------------------------
  era             ERA                   UDATPG_ERA_FIELD    
  year            YEAR                  UDATPG_YEAR_FIELD    
  quarter         QUARTER               UDATPG_QUARTER_FIELD    
  month           MONTH                 UDATPG_MONTH_FIELD    
  week            WEEK_OF_YEAR          UDATPG_WEEK_OF_YEAR_FIELD    
  weekOfMonth     WEEK_OF_MONTH         UDATPG_WEEK_OF_MONTH_FIELD    
  weekday         WEEKDAY               UDATPG_WEEKDAY_FIELD    
  dayOfYear       DAY_OF_YEAR           UDATPG_DAY_OF_YEAR_FIELD    
  weekdayOfMonth  DAY_OF_WEEK_IN_MONTH  UDATPG_DAY_OF_WEEK_IN_MONTH_FIELD    
  day             DAY                   UDATPG_DAY_FIELD    
  dayperiod       DAYPERIOD             UDATPG_DAYPERIOD_FIELD    
  hour            HOUR                  UDATPG_HOUR_FIELD    
  minute          MINUTE                UDATPG_MINUTE_FIELD    
  second          SECOND                UDATPG_SECOND_FIELD    
  ---             FRACTIONAL_SECOND     UDATPG_FRACTIONAL_SECOND_FIELD    
  zone            ZONE                  UDATPG_ZONE_FIELD    

  * The CLDR keys also come with suffixes -short, -narrow for the shorter versions

The CLDR data comes in three widths: wide (or full), short, and narrow. There is a need to be able to access these display names in all of the available widths, see the ticket above. The question is: how best to do this?

Currently the wide versions of these display names (only) are used by the DateTimePatternGenerator class for the appendField operation; when it cannot match a complete skeleton to an existing availableFormats entry, it will match part of the skeleton then append names and associated values for the other skeleton fields. It provides methods to get and set the append field name:

# Java
  java.lang.String getAppendItemName(int field);
  void setAppendItemName(int field, java.lang.String value);
# C++
  const UnicodeString& getAppendItemName(UDateTimePatternField field) const;
  void setAppendItemName(UDateTimePatternField field, const UnicodeString &value);
# C
  void udatpg_setAppendItemName(UDateTimePatternGenerator *dtpg,
                                UDateTimePatternField field, const UChar *value, int32_t length);
  const UChar* udatpg_getAppendItemName(const UDateTimePatternGenerator *dtpg,
                                        UDateTimePatternField field, int32_t *pLength);

B. Proposal discussion/motivation

I propose to add new getFieldName APIs in DateTimePatternGenerator that take separate parameters for field type (as in the APIs above) and display width (i.e.wide, abbreviated/short, narrow):
• I suggest these be in DateTimePatternGenerator rather than, say, DateFormat, to prevent duplication of data storage, since DateTimePatternGenerator is already loading the wide versions of these names.
• For the time being, I think only the "get" APIs are needed, I do not yet see a use case for the "set" APIs. Note that a client using setAppendItemName to set the wide name for a particular field would affect the name returned by the same DateTimePatternGenerator object for the wide version of that field.
• The name "getFieldName" suggests the broader usage compared to "getAppendItemName".
• The plain C udatpg_getFieldName function should follow the usual convention of taking a UChar buffer to fill in and returning the length, rather than the approach used with udatpg_getAppendItemName, and needs a UErrorCode parameter.
• As for how to specify the width, see below.

Currently, DateFormatSymbols has constants or enum values for specifying display width independently of symbol type.
• Java DateFormatSymbols: WIDE, ABBREVIATED, NARROW, SHORT (between ABBREVIATED and NARROW)
• C++ DateFormatSymbols::DtWidthType: ABBREVIATED, WIDE, NARROW, SHORT
However, these are not available in plain C, DateTimePatternGenerator does not currently depend on DateFormatSymbols, and the selection of display widths available for calendar symbol names is not necessarily be the same as the selection for field display names (and in fact some calendar symbols have the additional SHORT width). Therefore I propose a new enum in DateTimePatternGenerator for the available display widths.

C. Specific proposal, based on the above discussion

# Java DateTimePatternGenerator, add:

    public enum DisplayWidth {
        WIDE,
        ABBREVIATED,
        NARROW
    }

    java.lang.String getFieldName(int field, DisplayWidth width);

# C udatpg.h, add

typedef enum UDateTimeWidth {
    UDATPG_WIDE,
    UDATPG_ABBREVIATED,
    UDATPG_NARROW,
    /**
     * @deprecated
     */
    UDATPG_WIDTH_COUNT
} UDateTimeWidth;

int32_t
udatpg_getFieldName(UDateTimePatternGenerator *dtpg,
                    UDateTimePatternField field, UDateTimeWidth width,
                    UChar *fieldName, int32_t capacity,
                    UErrorCode *pErrorCode);

# C++ DateTimePatternGenerator, add:

    const UnicodeString& getFieldName(UDateTimePatternField field, UDateTimeWidth width) const;


- Peter E