[icu-design] ICU4C API proposal: FieldPositionIterator in RelativeDateTimeFormat

[Daniel E. <lit...@ig...>]

Dear ICU team & users,

I would like to propose the following as a *technology preview* for:
*ICU 62*
Please provide feedback by: *Monday, 2018-03-05*
Designated API reviewer: Yoshito (?)
Ticket: http://bugs.icu-project.org/trac/ticket/13256

DateFormat and NumberFormat support format methods which take a
FieldPositionIterator as an argument. Would it be reasonable to add this
for other formatters, such as 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, as part of a consistent surface
for all formatters.

The API is added on both the C++ and C sides.
- In C++, as one method in RelativeDateFormatter.
- In C++, as a function in ureldatefmt.h

In this proposal, only format and not formatNumeric is added; this is
just out of minimalism for what I would be using, but it would work
perfectly analogously to add formatNumeric equivalents. I'd be open to
either path.

Some JavaScript engines use ICU's C++ API, and some use ICU's C API,
so it is useful to have both here.

[1] ​https://github.com/caridy/proposal-intl-relative-time ,
​https://github.com/tc39/ecma402/issues/35

enum class URelativeDateFormatterField {
  U_RELATIVE_DATE_FORMATTER_LITERAL_FIELD = -1,
  U_RELATIVE_DATE_FORMATTER_NUMBER_FIELD = 0
};

C++ class RelativeDateFormatter

    /**
     * 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 URelativeDateFormatField.
     *                  Can be NULL.
     * @param status    ICU error code returned here.
     * @return          appendTo
     * @internal ICU 61 technology preview, may be changed or removed in
     *                  the future
     */
    UnicodeString& format(
            double offset,
            URelativeDateTimeUnit unit,
            UnicodeString& appendTo,
            FieldPositionIterator* posIter,
            UErrorCode& status) const;

ureldatefmt.h

/**
 * 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
 *          URelativeDateFormatterField 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.
 * @internal ICU 61 technology preview, may be changed or removed in the
future
 */
U_STABLE int32_t U_EXPORT2
ureldatefmt_formatForFields(
                    const URelativeDateTimeFormatter* reldatefmt,
                    double                offset,
                    URelativeDateTimeUnit unit,
                    UChar*                result,
                    int32_t               resultCapacity,
                    UFieldPositionIterator* fpositer,
                    UErrorCode*           status);


Thanks,
Daniel