Re: [icu-design] ICU API proposal: Fast string direction detection

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

I see no fundamental problem with this API.  A few remarks.

1) The name of the function "ubidi_getParagraphLevelDirectionUBA" is 
really long.  There is no need to mention UBA, everything Bidi in ICU 
follows the UBA.  On the other hand, "Default" should be mentioned, since 
this is the paragraph level which would be assigned with the existing API. 
 I suggest "ubidi_resolveDefaultBaseDirection" or even "
ubidi_resolveDefaultDirection".

2) It is worth mentioning in the comments why this function exists: it is 
a lightweight function when only the direction is needed and no further 
Bidi processing of the text is needed.

3) Instead of "paragraph level direction", I would say "base direction", 
this is the term used in the comments for UBIDI_DEFAULT_xxx.


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




From:   Norbert Lindenberg ♻ <nor...@ya...>
To:     icu...@li...
Date:   30/06/2010 03:56
Subject:        [icu-design] ICU API proposal: Fast string direction 
detection



Dear ICU team and users,

I would like to propose the addition of a fast function for string 
direction detection to the Bidi API, for ICU 4.6. This function 
determines the paragraph level direction of a string without creating 
a UBidi object. This direction can currently be derived from 
ubidi_getParaLevel, but at the substantial cost of initializing a 
UBidi object. To give callers control over the handling of strings 
with no strong direction, the new function allows for a NEUTRAL result 
value in addition to LTR and RTL values.

Ticket: http://bugs.icu-project.org/trac/ticket/7772
Designated API reviewer: Mark Davis

Please provide feedback by Wednesday, 2010-07-07T18:00:00Z.

Best regards,
Norbert



ICU4C API changes - bidi.h:
http://icu-project.org/apiref/icu4c/ubidi_8h.html

- add constant UBIDI_NEUTRAL to enum UBiDiDirection:

UBIDI_NEUTRAL /**< No strongly directional text. */

- in ubidi_getDirection, clarify that UBIDI_NEUTRAL is not returned.

- in ubidi_getVisualRun, clarify that UBIDI_NEUTRAL is not returned.

- add ubidi_getParagraphLevelDirectionUBA:

/**
  * Gets the paragraph level direction of the text provided according 
to the Unicode
  * Bidirectional Algorithm. The paragraph level direction is derived 
from the first
  * character in the string with bidirectional character type L, R, or 
AL. If the first such
  * character has type L, UBIDI_LTR is returned. If the first such 
character has type R or AL,
  * UBIDI_RTL is returned. If the string does not contain any 
character of these types, then
  * UBIDI_NEUTRAL is returned.
  * @param text is a pointer to the text whose paragraph level 
direction is needed.
  * Note: the text must be (at least) @c length long.
  * @param length is the length of the text; if <code>length==-1</ 
code> then the text
  * must be zero-terminated.
  * @return  UBIDI_LTR, UBIDI_RTL, UBIDI_NEUTRAL
  */
UBiDiDirection ubidi_getParagraphLevelDirectionUBA(const UChar *text,
int32_t length)


ICU4J API changes - Bidi.java:
http://icu-project.org/apiref/icu4j/com/ibm/icu/text/Bidi.html

- add constant Bidi.NEUTRAL:

/**
  * No strongly directional text.
  */
public static final byte NEUTRAL;

- add Bidi.getParagraphLevelDirectionUBA:

/**
  * Gets the paragraph level direction of the text provided according 
to the Unicode
  * Bidirectional Algorithm. The paragraph level direction is derived 
from the first
  * character in the string with bidirectional character type L, R, or 
AL. If the first such
  * character has type L, LTR is returned. If the first such character 
has type R or AL,
  * RTL is returned. If the string does not contain any character of 
these types, then
  * NEUTRAL is returned.
  * @param paragraph the text whose paragraph level direction is needed.
  * @return LTR, RTL, NEUTRAL
  * @see LTR
  * @see RTL
  * @see NEUTRAL
  * /
public static byte getParagraphLevelDirectionUBA(String paragraph)


-------------------------------------
Norbert Lindenberg
Yahoo! Internationalization Architect