[icu-design] API proposal as per ticket #3660

[Matitiahu A. <ma...@il...>]

ICU ticket 3660 (http://bugs.icu-project.org/trac/ticket/3660) asks for 
the ability to specify out-of-band context when performing a Bidi 
transformation on a string.  This needs a new API for which you will find 
my proposal below.  It is targetted for R4.2.

A few design considerations which guided this proposal.

a) This proposal only addresses ICU4C.  Once there is an agreement on 
ICU4C, I will submit a parallel proposal for ICU4J.

b) The context arguments belong in essence to function ubidi_setPara. 
However, this function already has 6 arguments and adding 4 more arguments 
(for prologue/epilogue strings and their lengths) would make it quite 
unwieldy.  So, I designed setting the context as a separate API.

c) The proposed API does not include an error code argument, in order to 
simplify.  All the arguments are either pointers or integers representing 
string lengths.  Null pointers can validly represent an unneeded argument, 
and length < -1 will also mean to ignore the corresponding string pointer.
If public opinion asks for an error code argument, I will add it.

d) The new API being called ubidi_setContext suggests associating a 
corresponding ubidi_getContext.  It seems to me that the get API has no 
real usefulness, so I did not include it in the proposal.  If reviewers 
demand it, I will add it to the proposal.

Here is the proposal.

<start of text>
/**
 * Set the context before a call to ubidi_setPara().<p>
 *
 * ubidi_setPara() computes the left-right directionality for a given 
piece
 * of text which is supplied as one of its arguments. Sometimes this piece
 * of text (the "main text") should be considered in context, because text
 * which appears before ("prologue") and/or after ("epilogue") the main 
text
 * may affect the result of this computation.<p>
 *
 * This function specifies the prologue and/or the epilogue for the next
 * call to ubidi_setPara(). The characters specified as prologue and
 * epilogue should not be modified by the calling program until the call
 * to ubidi_setPara() has returned. If successive calls to ubidi_setPara()
 * all need specification of a context, ubidi_setContext() must be called
 * before each call to ubidi_setPara(). In other words, a context is not
 * "remembered" after the following call to ubidi_setPara().<p>
 *
 * If a call to ubidi_setPara() specifies UBIDI_DEFAULT_LTR or
 * UBIDI_DEFAULT_RTL as paraLevel and is preceded by a call to
 * ubidi_setContext() which specifies a prologue, the paragraph level will
 * be computed taking in consideration the text in the prologue.<p>
 *
 * When ubidi_setPara() is called without a previous call to
 * ubidi_setContext, the main text is handled as if preceded and followed
 * by strong directional characters at the current paragraph level.
 * Calling ubidi_setContext() with specification of a prologue will change
 * this behavior by handling the main text as if preceded by the last
 * strong character appearing in the prologue, if any.
 * Calling ubidi_setContext() with specification of an epilogue will 
change
 * the behavior of ubidi_setPara() by handling the main text as if 
followed
 * by the first strong character or digit appearing in the epilogue, if 
any.<p>
 *
 * @param pBiDi is a paragraph <code>UBiDi</code> object.
 *
 * @param prologue is a pointer to the text which precedes the text that
 *        will be specified in a coming call to ubidi_setPara().
 *        This pointer may be NULL if there is no prologue to consider.
 *
 * @param proLength is the length of the prologue; if 
<code>proLength==-1</code>
 *        then the prologue must be zero-terminated.
 *
 * @param epilogue is a pointer to the text which follows the text that
 *        will be specified in a coming call to ubidi_setPara().
 *        This pointer may be NULL if there is no epilogue to consider.
 *
 * @param epiLength is the length of the epilogue; if 
<code>epiLength==-1</code>
 *        then the epilogue must be zero-terminated.
 *
 *
 * @draft ICU 4.2
 */
U_DRAFT void U_EXPORT2
ubidi_setContext(UBiDi *pBiDi, const UChar *prologue, int32_t proLength,
                 const UChar *epilogue, int32_t epiLength);
<end of text>


Shalom (Regards),  Mati
           Bidi Architect
           Globalization Center Of Competency - Bidirectional Scripts
           IBM Israel
           Phone: +972 2 5888802    Fax: +972 2 5870333    Mobile: +972 52 
2554160