[icu-design] ICU4C API proposal: normalize UTF-8 technology preview

[Markus S. <mar...@gm...>]

Dear ICU team & users,

I would like to propose the following as a *technology preview* for: *ICU
60*
Please provide feedback by: *Tuesday, 2017-06-06*
Designated API reviewer: *Mark*
Ticket: http://bugs.icu-project.org/trac/ticket/13197

This is patterned after class Casemap (options & edits) and some other
existing UTF-8 API (StringPiece & ByteSink).

C++ class Normalizer2

    /**
     * Normalizes a UTF-8 string and optionally records edits.
     *
     * Currently implemented completely only for "compose" modes,
     * such as for NFC, NFKC, and NFKC_Casefold
     * (UNORM2_COMPOSE and UNORM2_COMPOSE_CONTIGUOUS).
     * Otherwise currently converts to & from UTF-16 and does not support
edits.
     *
     * @param options   Options bit set, usually 0. See
UCASEMAP_OMIT_UNCHANGED_TEXT.
     * @param src       Source UTF-8 string.
     * @param sink      A ByteSink to which the normalized UTF-8 result
string is written.
     *                  sink.Flush() is called at the end.
     * @param edits     Records edits for index mapping, working with
styled text,
     *                  and getting only changes (if any).
     *                  The Edits contents is undefined if any error occurs.
     *                  This function calls edits->reset() first. edits can
be nullptr.
     * @param errorCode Standard ICU error code. Its input value must
     *                  pass the U_SUCCESS() test, or else the function
returns
     *                  immediately. Check for U_FAILURE() on output or use
with
     *                  function chaining. (See User Guide for details.)
     * @internal ICU 60 technology preview, may be changed or removed in
the future
     */
    virtual void
    normalizeUTF8(uint32_t options, StringPiece src, ByteSink &sink,
                  Edits *edits, UErrorCode &errorCode) const;

Sincerely,
markus