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

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

The proposal was amended as shown below in TC discussion today, then approved as amended for draft 61 status:

# Java DateTimePatternGenerator, add:

    public enum DisplayWidth {
        WIDE,
        ABBREVIATED,
        NARROW
    }

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

# C udatpg.h, add

typedef enum UDateTimePGDisplayWidth {
    UDATPG_WIDE,
    UDATPG_ABBREVIATED,
    UDATPG_NARROW
} UDateTimePGDisplayWidth;

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

# C++ DateTimePatternGenerator, add:

    UnicodeString getFieldDisplayName(UDateTimePatternField field, UDateTimePGDisplayWidth width) const;
    [changed return from const UnicodeString&]


- Peter E

> On Feb 8, 2018, at 10:26 AM, Peter Edberg <pe...@ap...> wrote:
> 
> 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
> 
> 
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot_______________________________________________
> icu-design mailing list
> icu...@li...
> To Un/Subscribe: https://lists.sourceforge.net/lists/listinfo/icu-design