Menu
▾
▴
[icu-design] ICU API proposal: Add RelativeDateTimeFormatter.format(FieldPositionIterator) for C and C++
|
From: Frank T. (譚. <ft...@go...> - 2018-10-13 04:08:58
|
Dear ICU team & users, I would like to propose the following API for: *ICU 64* Please provide feedback by:* Tuesday after next week, 2018-10-23* Designated API reviewer: *Markus* Ticket: https://unicode-org.atlassian.net/browse/ICU-13256 DateFormat, NumberFormat and ListFormat support format methods which take a FieldPositionIterator as an argument. I would like to add this for RelativeDateTimeFormatter. This would be useful for JavaScript implementations of RelativeTimeFormat [1] This allows, for example, to make some parts of the result bold. ECMA-402 is adding these "formatToParts" methods for all new formatters being bound to ICU. The following proposal cover both C++ and C API. A follow up Java API proposal will come soon. [1] https://github.com/caridy/proposal-intl-relative-time , https://github.com/tc39/ecma402/issues/35 i18n/unicode/reldatefmt.h ... +#ifndef U_HIDE_DRAFT_API + /** + * Format a combination of URelativeDateTimeUnit and numeric offset + * using a numeric style, e.g. "1 week ago", "in 1 week", + * "5 weeks ago", "in 5 weeks". + * + * @param offset The signed offset for the specified unit. This + * will be formatted according to this object's + * NumberFormat object. + * @param unit The unit to use when formatting the relative + * date, e.g. UDAT_REL_UNIT_WEEK, + * UDAT_REL_UNIT_FRIDAY. + * @param appendTo The string to which the formatted result will be + * appended. + * @param posIter On return, can be used to iterate over positions of + * fields generated by this format call. Field values are + * defined in URelativeDateTimeFormatterField. Can be NULL. + * @param status ICU error code returned here. + * @return appendTo + * @draft ICU 64 + */ + UnicodeString& formatNumeric( + double offset, + URelativeDateTimeUnit unit, + UnicodeString& appendTo, + FieldPositionIterator* posIter, + UErrorCode& status) const; +#endif U_HIDE_DRAFT_API ... +#ifndef U_HIDE_DRAFT_API + /** + * Format a combination of URelativeDateTimeUnit and numeric offset + * using a text style if possible, e.g. "last week", "this week", + * "next week", "yesterday", "tomorrow". Falls back to numeric + * style if no appropriate text term is available for the specified + * offset in the object's locale. + * + * @param offset The signed offset for the specified unit. + * @param unit The unit to use when formatting the relative + * date, e.g. UDAT_REL_UNIT_WEEK, + * UDAT_REL_UNIT_FRIDAY. + * @param appendTo The string to which the formatted result will be + * appended. + * @param posIter On return, can be used to iterate over positions of + * fields generated by this format call. Field values are + * defined in URelativeDateTimeFormatterField. Can be NULL. + * @param status ICU error code returned here. + * @return appendTo + * @stable ICU 57 + */ + UnicodeString& format( + double offset, + URelativeDateTimeUnit unit, + UnicodeString& appendTo, + FieldPositionIterator* posIter, + UErrorCode& status) const; +#endif U_HIDE_DRAFT_API i18n/unicode/ureldatefmt.h ... #include "unicode/unum.h" #include "unicode/udisplaycontext.h" +#include "unicode/ufieldpositer.h" #include "unicode/localpointer.h" ... + +#ifndef U_HIDE_DRAFT_API +/** + * FieldPosition and UFieldPosition selectors for format fields + * defined by RelativeDateTimeFormatter. + * @draft ICU 64 + */ +typedef enum URelativeDateTimeFormatterField { + /** + * The literal text in the result which came from the resources. + * @draft ICU 64 + */ + URDTFMT_LITERAL_FIELD, + /** + * The element text in the result which came from the input interger. + * @draft ICU 64 + */ + URDTFMT_INTEGER_FIELD, + +} URelativeDateTimeFormatterField; +#endif // U_HIDE_DRAFT_API + ... +#ifndef U_HIDE_DRAFT_API +/** + * Format a combination of URelativeDateTimeUnit and numeric + * offset using a numeric style, e.g. "1 week ago", "in 1 week", + * "5 weeks ago", "in 5 weeks". + * + * @param reldatefmt + * The URelativeDateTimeFormatter object specifying the + * format conventions. + * @param offset + * The signed offset for the specified unit. This will + * be formatted according to this object's UNumberFormat + * object. + * @param unit + * The unit to use when formatting the relative + * date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY. + * @param result + * A pointer to a buffer to receive the formatted result. + * @param resultCapacity + * The maximum size of result. + * @param fpositer + * A pointer to a UFieldPositionIterator created by {@link #ufieldpositer_open} + * (may be NULL if field position information is not needed). Any + * iteration information already present in the UFieldPositionIterator + * will be deleted, and the iterator will be reset to apply to the + * fields in the formatted string created by this function call; the + * field values provided by {@link #ufieldpositer_next} will be from the + * URelativeDateTimeFormatterField enum. + * @param status + * A pointer to a UErrorCode to receive any errors. In + * case of error status, the contents of result are + * undefined. + * @return + * The length of the formatted result; may be greater + * than resultCapacity, in which case an error is returned. + * @draft ICU 64 + */ +U_STABLE int32_t U_EXPORT2 +ureldatefmt_formatNumericForFields( const URelativeDateTimeFormatter* reldatefmt, + double offset, + URelativeDateTimeUnit unit, + UChar* result, + int32_t resultCapacity, + UFieldPositionIterator* fpositer, + UErrorCode* status); +#endif U_HIDE_DRAFT_API + + ... +#ifndef U_HIDE_DRAFT_API +/** + * Format a combination of URelativeDateTimeUnit and numeric offset + * using a text style if possible, e.g. "last week", "this week", + * "next week", "yesterday", "tomorrow". Falls back to numeric + * style if no appropriate text term is available for the specified + * offset in the object's locale. + * + * @param reldatefmt + * The URelativeDateTimeFormatter object specifying the + * format conventions. + * @param offset + * The signed offset for the specified unit. + * @param unit + * The unit to use when formatting the relative + * date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY. + * @param result + * A pointer to a buffer to receive the formatted result. + * @param resultCapacity + * The maximum size of result. + * @param fpositer + * A pointer to a UFieldPositionIterator created by {@link #ufieldpositer_open} + * (may be NULL if field position information is not needed). Any + * iteration information already present in the UFieldPositionIterator + * will be deleted, and the iterator will be reset to apply to the + * fields in the formatted string created by this function call; the + * field values provided by {@link #ufieldpositer_next} will be from the + * URelativeDateTimeFormatterField enum. + * @param status + * A pointer to a UErrorCode to receive any errors. In + * case of error status, the contents of result are + * undefined. + * @return + * The length of the formatted result; may be greater + * than resultCapacity, in which case an error is returned. + * @stable ICU 57 + */ +U_STABLE int32_t U_EXPORT2 +ureldatefmt_formatForFields( const URelativeDateTimeFormatter* reldatefmt, + double offset, + URelativeDateTimeUnit unit, + UChar* result, + int32_t resultCapacity, + UFieldPositionIterator* fpositer, + UErrorCode* status); +#endif U_HIDE_DRAFT_API -- Frank Yung-Fong Tang 譚永鋒 / 🌭🍊 Sr. Software Engineer |
