ICU API Proposal: Add length-aware AM/PM getter and setter in DateFormatSymbols

[Shane Carr]

Dear ICU team & users,

I would like to propose the following API change for: ICU 78
Please provide feedback by: this Thursday, 2025-08-28
Designated API reviewer: Peter E
Ticket: https://unicode-org.atlassian.net/browse/ICU-23177

PR: https://github.com/unicode-org/icu/pull/3611

Currently, DateFormatSymbols has a single getter for AM/PM strings. It currently returns the long AM/PM string, but controls the formatting of the abbreviated "a" datetime pattern character.

I would like to add a getter and setter that take a width parameter for the Abbreviated, Wide, and Narrow versions of the AM/PM strings. I propose adding them as overloads on the existing functions.

In C++, dtfmtsym.h:

    /**
     * Gets AM/PM strings with the specified width. For example: "A" and "P".
     * @param count    Filled in with length of the array.
     * @param width    The width of returned strings, either WIDE, ABBREVIATED, or NARROW.
     * @return         The AM/PM strings. (DateFormatSymbols retains ownership.)
     * @draft ICU 78
     */
    U_I18N_API const UnicodeString* getAmPmStrings(int32_t& count, DtWidthType width) const;

    /**
     * Sets AM/PM strings with the specified width. For example: "A" and "P".
     * @param ampms   The new AM/PM strings. (not adopted; caller retains ownership)
     * @param count   The number of strings in the array.
     * @param width   The width of set strings, either WIDE, ABBREVIATED, or NARROW.
     * @draft ICU 78
     */
    U_I18N_API void setAmPmStrings(const UnicodeString* ampms, int32_t count, DtWidthType width);

Java to follow.

I wanted to send this right away in order to allow for feedback on the shape of the API with at least a whole day for the ICU TC to review it. If anyone or the ICU TC does not wish to accept this change into ICU 78, I will merge a smaller change that only impacts data loading without exposing the public API.

Thanks,

Shane

[Peter Edberg]

This looks good to me, we should have done this long ago. Please add this to the ICU 78 API proposals status doc.

Thanks,

Peter

--
You received this message because you are subscribed to the Google Groups "icu-design" group.
To unsubscribe from this group and stop receiving emails from it, send an email to icu-design+...@unicode.org.
To view this discussion visit https://groups.google.com/a/unicode.org/d/msgid/icu-design/CABxsp%3DmQ7%2Br6Es%3D4YwhcVYjvKFLxg8HReUond9P_GPU7czPQSg%40mail.gmail.com.
For more options, visit https://groups.google.com/a/unicode.org/d/optout.

[Elango Cheran]

Slightly newbie question: for the getter method getAmPmStrings,  when we have an API that uses "input/output arguments", do they need to be passed in by reference? I don't see that for DtWidthType width, but I do see it for int32_t& count. The setter method doesn't have return values in the same way, so the question shouldn't pertain there, it only pertains to the getter here.

Otherwise, the APIs look fine and the Java ones would be good to have, and yes as Peter said, also put that in the API proposal doc.

To view this discussion visit https://groups.google.com/a/unicode.org/d/msgid/icu-design/A05C4D51-57DD-4661-B7E5-3D896E7D4C4D%40unicode.org.

[Peter Edberg]

Width should be input only

[Shane Carr]

Java version:

    /**
     * Returns am/pm strings with the specified width. For example: "AM" and "PM".
     * @param width    The width or the AM/PM strings,
     *                 either WIDE, ABBREVIATED, or NARROW.
     * @return the weekday strings.

     * @draft ICU 78
     */

    public String[] getAmPmStrings(int width)

    /**
     * Sets am/pm strings with the specified width. For example: "AM" and "PM".
     * @param newAmpms the new ampm strings.
     * @param width    The width or the AM/PM strings,
     *                 either WIDE, ABBREVIATED, or NARROW.

     * @draft ICU 78
     */

    public void setAmPmStrings(String[] newAmpms, int width)

[Shane Carr]

> Slightly newbie question: for the getter method getAmPmStrings,  when we have an API that uses "input/output arguments", do they need to be passed in by reference? I don't see that for DtWidthType width, but I do see it for int32_t& count. The setter method doesn't have return values in the same way, so the question shouldn't pertain there, it only pertains to the getter here.

For this API, I copied the convention from elsewhere in the file. For example, there is already:

    U_I18N_API const UnicodeString* getWeekdays(int32_t& count,
                                                DtContextType context,
                                                DtWidthType width) const;

    U_I18N_API void setWeekdays(const UnicodeString* weekdays,
                                int32_t count,
                                DtContextType context,
                                DtWidthType width);

The signature of each parameter is the same for my AmPm functions.

For the getter, the width is an input argument only, not an output argument.

Those functions contain a DtContextType parameter. I could add it, although we don't currently load or format data for it, as far as I can tell. Happy for feedback from the TC on whether I should add the DtContextType parameter.