src/third_party/icu/source/common/unicode/ubidi.h

   1 /*
   2 ******************************************************************************
   3 *
   4 *   Copyright (C) 1999-2013, International Business Machines
   5 *   Corporation and others.  All Rights Reserved.
   6 *
   7 ******************************************************************************
   8 *   file name:  ubidi.h
   9 *   encoding:   US-ASCII
  10 *   tab size:   8 (not used)
  11 *   indentation:4
  12 *
  13 *   created on: 1999jul27
  14 *   created by: Markus W. Scherer, updated by Matitiahu Allouche
  15 */
  16
  17 #ifndef UBIDI_H
  18 #define UBIDI_H
  19
  20 #include "unicode/utypes.h"
  21 #include "unicode/uchar.h"
  22 #include "unicode/localpointer.h"
  23
  24 /**
  25  *\file
  26  * \brief C API: Bidi algorithm
  27  *
  28  * <h2>Bidi algorithm for ICU</h2>
  29  *
  30  * This is an implementation of the Unicode Bidirectional Algorithm.
  31  * The algorithm is defined in the
  32  * <a href="http://www.unicode.org/unicode/reports/tr9/">Unicode Standard Annex #9</a>.<p>
  33  *
  34  * Note: Libraries that perform a bidirectional algorithm and
  35  * reorder strings accordingly are sometimes called "Storage Layout Engines".
  36  * ICU's Bidi and shaping (u_shapeArabic()) APIs can be used at the core of such
  37  * "Storage Layout Engines".
  38  *
  39  * <h3>General remarks about the API:</h3>
  40  *
  41  * In functions with an error code parameter,
  42  * the <code>pErrorCode</code> pointer must be valid
  43  * and the value that it points to must not indicate a failure before
  44  * the function call. Otherwise, the function returns immediately.
  45  * After the function call, the value indicates success or failure.<p>
  46  *
  47  * The &quot;limit&quot; of a sequence of characters is the position just after their
  48  * last character, i.e., one more than that position.<p>
  49  *
  50  * Some of the API functions provide access to &quot;runs&quot;.
  51  * Such a &quot;run&quot; is defined as a sequence of characters
  52  * that are at the same embedding level
  53  * after performing the Bidi algorithm.<p>
  54  *
  55  * @author Markus W. Scherer
  56  * @version 1.0
  57  *
  58  *
  59  * <h4> Sample code for the ICU Bidi API </h4>
  60  *
  61  * <h5>Rendering a paragraph with the ICU Bidi API</h5>
  62  *
  63  * This is (hypothetical) sample code that illustrates
  64  * how the ICU Bidi API could be used to render a paragraph of text.
  65  * Rendering code depends highly on the graphics system,
  66  * therefore this sample code must make a lot of assumptions,
  67  * which may or may not match any existing graphics system's properties.
  68  *
  69  * <p>The basic assumptions are:</p>
  70  * <ul>
  71  * <li>Rendering is done from left to right on a horizontal line.</li>
  72  * <li>A run of single-style, unidirectional text can be rendered at once.</li>
  73  * <li>Such a run of text is passed to the graphics system with
  74  *     characters (code units) in logical order.</li>
  75  * <li>The line-breaking algorithm is very complicated
  76  *     and Locale-dependent -
  77  *     and therefore its implementation omitted from this sample code.</li>
  78  * </ul>
  79  *
  80  * <pre>
  81  * \code
  82  *#include "unicode/ubidi.h"
  83  *
  84  *typedef enum {
  85  *     styleNormal=0, styleSelected=1,
  86  *     styleBold=2, styleItalics=4,
  87  *     styleSuper=8, styleSub=16
  88  *} Style;
  89  *
  90  *typedef struct { int32_t limit; Style style; } StyleRun;
  91  *
  92  *int getTextWidth(const UChar *text, int32_t start, int32_t limit,
  93  *                  const StyleRun *styleRuns, int styleRunCount);
  94  *
  95  * // set *pLimit and *pStyleRunLimit for a line
  96  * // from text[start] and from styleRuns[styleRunStart]
  97  * // using ubidi_getLogicalRun(para, ...)
  98  *void getLineBreak(const UChar *text, int32_t start, int32_t *pLimit,
  99  *                  UBiDi *para,
 100  *                  const StyleRun *styleRuns, int styleRunStart, int *pStyleRunLimit,
 101  *                  int *pLineWidth);
 102  *
 103  * // render runs on a line sequentially, always from left to right
 104  *
 105  * // prepare rendering a new line
 106  * void startLine(UBiDiDirection textDirection, int lineWidth);
 107  *
 108  * // render a run of text and advance to the right by the run width
 109  * // the text[start..limit-1] is always in logical order
 110  * void renderRun(const UChar *text, int32_t start, int32_t limit,
 111  *               UBiDiDirection textDirection, Style style);
 112  *
 113  * // We could compute a cross-product
 114  * // from the style runs with the directional runs
 115  * // and then reorder it.
 116  * // Instead, here we iterate over each run type
 117  * // and render the intersections -
 118  * // with shortcuts in simple (and common) cases.
 119  * // renderParagraph() is the main function.
 120  *
 121  * // render a directional run with
 122  * // (possibly) multiple style runs intersecting with it
 123  * void renderDirectionalRun(const UChar *text,
 124  *                           int32_t start, int32_t limit,
 125  *                           UBiDiDirection direction,
 126  *                           const StyleRun *styleRuns, int styleRunCount) {
 127  *     int i;
 128  *
 129  *     // iterate over style runs
 130  *     if(direction==UBIDI_LTR) {
 131  *         int styleLimit;
 132  *
 133  *         for(i=0; i<styleRunCount; ++i) {
 134  *             styleLimit=styleRun[i].limit;
 135  *             if(start<styleLimit) {
 136  *                 if(styleLimit>limit) { styleLimit=limit; }
 137  *                 renderRun(text, start, styleLimit,
 138  *                           direction, styleRun[i].style);
 139  *                 if(styleLimit==limit) { break; }
 140  *                 start=styleLimit;
 141  *             }
 142  *         }
 143  *     } else {
 144  *         int styleStart;
 145  *
 146  *         for(i=styleRunCount-1; i>=0; --i) {
 147  *             if(i>0) {
 148  *                 styleStart=styleRun[i-1].limit;
 149  *             } else {
 150  *                 styleStart=0;
 151  *             }
 152  *             if(limit>=styleStart) {
 153  *                 if(styleStart<start) { styleStart=start; }
 154  *                 renderRun(text, styleStart, limit,
 155  *                           direction, styleRun[i].style);
 156  *                 if(styleStart==start) { break; }
 157  *                 limit=styleStart;
 158  *             }
 159  *         }
 160  *     }
 161  * }
 162  *
 163  * // the line object represents text[start..limit-1]
 164  * void renderLine(UBiDi *line, const UChar *text,
 165  *                 int32_t start, int32_t limit,
 166  *                 const StyleRun *styleRuns, int styleRunCount) {
 167  *     UBiDiDirection direction=ubidi_getDirection(line);
 168  *     if(direction!=UBIDI_MIXED) {
 169  *         // unidirectional
 170  *         if(styleRunCount<=1) {
 171  *             renderRun(text, start, limit, direction, styleRuns[0].style);
 172  *         } else {
 173  *             renderDirectionalRun(text, start, limit,
 174  *                                  direction, styleRuns, styleRunCount);
 175  *         }
 176  *     } else {
 177  *         // mixed-directional
 178  *         int32_t count, i, length;
 179  *         UBiDiLevel level;
 180  *
 181  *         count=ubidi_countRuns(para, pErrorCode);
 182  *         if(U_SUCCESS(*pErrorCode)) {
 183  *             if(styleRunCount<=1) {
 184  *                 Style style=styleRuns[0].style;
 185  *
 186  *                 // iterate over directional runs
 187  *                for(i=0; i<count; ++i) {
 188  *                    direction=ubidi_getVisualRun(para, i, &start, &length);
 189  *                     renderRun(text, start, start+length, direction, style);
 190  *                }
 191  *             } else {
 192  *                 int32_t j;
 193  *
 194  *                 // iterate over both directional and style runs
 195  *                 for(i=0; i<count; ++i) {
 196  *                     direction=ubidi_getVisualRun(line, i, &start, &length);
 197  *                     renderDirectionalRun(text, start, start+length,
 198  *                                          direction, styleRuns, styleRunCount);
 199  *                 }
 200  *             }
 201  *         }
 202  *     }
 203  * }
 204  *
 205  *void renderParagraph(const UChar *text, int32_t length,
 206  *                     UBiDiDirection textDirection,
 207  *                      const StyleRun *styleRuns, int styleRunCount,
 208  *                      int lineWidth,
 209  *                      UErrorCode *pErrorCode) {
 210  *     UBiDi *para;
 211  *
 212  *     if(pErrorCode==NULL || U_FAILURE(*pErrorCode) || length<=0) {
 213  *         return;
 214  *     }
 215  *
 216  *     para=ubidi_openSized(length, 0, pErrorCode);
 217  *     if(para==NULL) { return; }
 218  *
 219  *     ubidi_setPara(para, text, length,
 220  *                   textDirection ? UBIDI_DEFAULT_RTL : UBIDI_DEFAULT_LTR,
 221  *                   NULL, pErrorCode);
 222  *     if(U_SUCCESS(*pErrorCode)) {
 223  *         UBiDiLevel paraLevel=1&ubidi_getParaLevel(para);
 224  *         StyleRun styleRun={ length, styleNormal };
 225  *         int width;
 226  *
 227  *         if(styleRuns==NULL || styleRunCount<=0) {
 228  *            styleRunCount=1;
 229  *             styleRuns=&styleRun;
 230  *         }
 231  *
 232  *        // assume styleRuns[styleRunCount-1].limit>=length
 233  *
 234  *         width=getTextWidth(text, 0, length, styleRuns, styleRunCount);
 235  *         if(width<=lineWidth) {
 236  *             // everything fits onto one line
 237  *
 238  *            // prepare rendering a new line from either left or right
 239  *             startLine(paraLevel, width);
 240  *
 241  *             renderLine(para, text, 0, length,
 242  *                        styleRuns, styleRunCount);
 243  *         } else {
 244  *             UBiDi *line;
 245  *
 246  *             // we need to render several lines
 247  *             line=ubidi_openSized(length, 0, pErrorCode);
 248  *             if(line!=NULL) {
 249  *                 int32_t start=0, limit;
 250  *                 int styleRunStart=0, styleRunLimit;
 251  *
 252  *                 for(;;) {
 253  *                     limit=length;
 254  *                     styleRunLimit=styleRunCount;
 255  *                     getLineBreak(text, start, &limit, para,
 256  *                                  styleRuns, styleRunStart, &styleRunLimit,
 257  *                                 &width);
 258  *                     ubidi_setLine(para, start, limit, line, pErrorCode);
 259  *                     if(U_SUCCESS(*pErrorCode)) {
 260  *                         // prepare rendering a new line
 261  *                         // from either left or right
 262  *                         startLine(paraLevel, width);
 263  *
 264  *                         renderLine(line, text, start, limit,
 265  *                                    styleRuns+styleRunStart,
 266  *                                    styleRunLimit-styleRunStart);
 267  *                     }
 268  *                     if(limit==length) { break; }
 269  *                     start=limit;
 270  *                     styleRunStart=styleRunLimit-1;
 271  *                     if(start>=styleRuns[styleRunStart].limit) {
 272  *                         ++styleRunStart;
 273  *                     }
 274  *                 }
 275  *
 276  *                 ubidi_close(line);
 277  *             }
 278  *        }
 279  *    }
 280  *
 281  *     ubidi_close(para);
 282  *}
 283  *\endcode
 284  * </pre>
 285  */
 286
 287 /*DOCXX_TAG*/
 288 /*@{*/
 289
 290 /**
 291  * UBiDiLevel is the type of the level values in this
 292  * Bidi implementation.
 293  * It holds an embedding level and indicates the visual direction
 294  * by its bit&nbsp;0 (even/odd value).<p>
 295  *
 296  * It can also hold non-level values for the
 297  * <code>paraLevel</code> and <code>embeddingLevels</code>
 298  * arguments of <code>ubidi_setPara()</code>; there:
 299  * <ul>
 300  * <li>bit&nbsp;7 of an <code>embeddingLevels[]</code>
 301  * value indicates whether the using application is
 302  * specifying the level of a character to <i>override</i> whatever the
 303  * Bidi implementation would resolve it to.</li>
 304  * <li><code>paraLevel</code> can be set to the
 305  * pseudo-level values <code>UBIDI_DEFAULT_LTR</code>
 306  * and <code>UBIDI_DEFAULT_RTL</code>.</li>
 307  * </ul>
 308  *
 309  * @see ubidi_setPara
 310  *
 311  * <p>The related constants are not real, valid level values.
 312  * <code>UBIDI_DEFAULT_XXX</code> can be used to specify
 313  * a default for the paragraph level for
 314  * when the <code>ubidi_setPara()</code> function
 315  * shall determine it but there is no
 316  * strongly typed character in the input.<p>
 317  *
 318  * Note that the value for <code>UBIDI_DEFAULT_LTR</code> is even
 319  * and the one for <code>UBIDI_DEFAULT_RTL</code> is odd,
 320  * just like with normal LTR and RTL level values -
 321  * these special values are designed that way. Also, the implementation
 322  * assumes that UBIDI_MAX_EXPLICIT_LEVEL is odd.
 323  *
 324  * @see UBIDI_DEFAULT_LTR
 325  * @see UBIDI_DEFAULT_RTL
 326  * @see UBIDI_LEVEL_OVERRIDE
 327  * @see UBIDI_MAX_EXPLICIT_LEVEL
 328  * @stable ICU 2.0
 329  */
 330 typedef uint8_t UBiDiLevel;
 331
 332 /** Paragraph level setting.<p>
 333  *
 334  * Constant indicating that the base direction depends on the first strong
 335  * directional character in the text according to the Unicode Bidirectional
 336  * Algorithm. If no strong directional character is present,
 337  * then set the paragraph level to 0 (left-to-right).<p>
 338  *
 339  * If this value is used in conjunction with reordering modes
 340  * <code>UBIDI_REORDER_INVERSE_LIKE_DIRECT</code> or
 341  * <code>UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL</code>, the text to reorder
 342  * is assumed to be visual LTR, and the text after reordering is required
 343  * to be the corresponding logical string with appropriate contextual
 344  * direction. The direction of the result string will be RTL if either
 345  * the righmost or leftmost strong character of the source text is RTL
 346  * or Arabic Letter, the direction will be LTR otherwise.<p>
 347  *
 348  * If reordering option <code>UBIDI_OPTION_INSERT_MARKS</code> is set, an RLM may
 349  * be added at the beginning of the result string to ensure round trip
 350  * (that the result string, when reordered back to visual, will produce
 351  * the original source text).
 352  * @see UBIDI_REORDER_INVERSE_LIKE_DIRECT
 353  * @see UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL
 354  * @stable ICU 2.0
 355  */
 356 #define UBIDI_DEFAULT_LTR 0xfe
 357
 358 /** Paragraph level setting.<p>
 359  *
 360  * Constant indicating that the base direction depends on the first strong
 361  * directional character in the text according to the Unicode Bidirectional
 362  * Algorithm. If no strong directional character is present,
 363  * then set the paragraph level to 1 (right-to-left).<p>
 364  *
 365  * If this value is used in conjunction with reordering modes
 366  * <code>UBIDI_REORDER_INVERSE_LIKE_DIRECT</code> or
 367  * <code>UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL</code>, the text to reorder
 368  * is assumed to be visual LTR, and the text after reordering is required
 369  * to be the corresponding logical string with appropriate contextual
 370  * direction. The direction of the result string will be RTL if either
 371  * the righmost or leftmost strong character of the source text is RTL
 372  * or Arabic Letter, or if the text contains no strong character;
 373  * the direction will be LTR otherwise.<p>
 374  *
 375  * If reordering option <code>UBIDI_OPTION_INSERT_MARKS</code> is set, an RLM may
 376  * be added at the beginning of the result string to ensure round trip
 377  * (that the result string, when reordered back to visual, will produce
 378  * the original source text).
 379  * @see UBIDI_REORDER_INVERSE_LIKE_DIRECT
 380  * @see UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL
 381  * @stable ICU 2.0
 382  */
 383 #define UBIDI_DEFAULT_RTL 0xff
 384
 385 /**
 386  * Maximum explicit embedding level.
 387  * (The maximum resolved level can be up to <code>UBIDI_MAX_EXPLICIT_LEVEL+1</code>).
 388  * @stable ICU 2.0
 389  */
 390 #define UBIDI_MAX_EXPLICIT_LEVEL 125
 391
 392 /** Bit flag for level input.
 393  *  Overrides directional properties.
 394  * @stable ICU 2.0
 395  */
 396 #define UBIDI_LEVEL_OVERRIDE 0x80
 397
 398 /**
 399  * Special value which can be returned by the mapping functions when a logical
 400  * index has no corresponding visual index or vice-versa. This may happen
 401  * for the logical-to-visual mapping of a Bidi control when option
 402  * <code>#UBIDI_OPTION_REMOVE_CONTROLS</code> is specified. This can also happen
 403  * for the visual-to-logical mapping of a Bidi mark (LRM or RLM) inserted
 404  * by option <code>#UBIDI_OPTION_INSERT_MARKS</code>.
 405  * @see ubidi_getVisualIndex
 406  * @see ubidi_getVisualMap
 407  * @see ubidi_getLogicalIndex
 408  * @see ubidi_getLogicalMap
 409  * @stable ICU 3.6
 410  */
 411 #define UBIDI_MAP_NOWHERE   (-1)
 412
 413 /**
 414  * <code>UBiDiDirection</code> values indicate the text direction.
 415  * @stable ICU 2.0
 416  */
 417 enum UBiDiDirection {
 418   /** Left-to-right text. This is a 0 value.
 419    * <ul>
 420    * <li>As return value for <code>ubidi_getDirection()</code>, it means
 421    *     that the source string contains no right-to-left characters, or
 422    *     that the source string is empty and the paragraph level is even.
 423    * <li> As return value for <code>ubidi_getBaseDirection()</code>, it
 424    *      means that the first strong character of the source string has
 425    *      a left-to-right direction.
 426    * </ul>
 427    * @stable ICU 2.0
 428    */
 429   UBIDI_LTR,
 430   /** Right-to-left text. This is a 1 value.
 431    * <ul>
 432    * <li>As return value for <code>ubidi_getDirection()</code>, it means
 433    *     that the source string contains no left-to-right characters, or
 434    *     that the source string is empty and the paragraph level is odd.
 435    * <li> As return value for <code>ubidi_getBaseDirection()</code>, it
 436    *      means that the first strong character of the source string has
 437    *      a right-to-left direction.
 438    * </ul>
 439    * @stable ICU 2.0
 440    */
 441   UBIDI_RTL,
 442   /** Mixed-directional text.
 443    * <p>As return value for <code>ubidi_getDirection()</code>, it means
 444    *    that the source string contains both left-to-right and
 445    *    right-to-left characters.
 446    * @stable ICU 2.0
 447    */
 448   UBIDI_MIXED,
 449   /** No strongly directional text.
 450    * <p>As return value for <code>ubidi_getBaseDirection()</code>, it means
 451    *    that the source string is missing or empty, or contains neither left-to-right
 452    *    nor right-to-left characters.
 453    * @stable ICU 4.6
 454    */
 455   UBIDI_NEUTRAL
 456 };
 457
 458 /** @stable ICU 2.0 */
 459 typedef enum UBiDiDirection UBiDiDirection;
 460
 461 /**
 462  * Forward declaration of the <code>UBiDi</code> structure for the declaration of
 463  * the API functions. Its fields are implementation-specific.<p>
 464  * This structure holds information about a paragraph (or multiple paragraphs)
 465  * of text with Bidi-algorithm-related details, or about one line of
 466  * such a paragraph.<p>
 467  * Reordering can be done on a line, or on one or more paragraphs which are
 468  * then interpreted each as one single line.
 469  * @stable ICU 2.0
 470  */
 471 struct UBiDi;
 472
 473 /** @stable ICU 2.0 */
 474 typedef struct UBiDi UBiDi;
 475
 476 /**
 477  * Allocate a <code>UBiDi</code> structure.
 478  * Such an object is initially empty. It is assigned
 479  * the Bidi properties of a piece of text containing one or more paragraphs
 480  * by <code>ubidi_setPara()</code>
 481  * or the Bidi properties of a line within a paragraph by
 482  * <code>ubidi_setLine()</code>.<p>
 483  * This object can be reused for as long as it is not deallocated
 484  * by calling <code>ubidi_close()</code>.<p>
 485  * <code>ubidi_setPara()</code> and <code>ubidi_setLine()</code> will allocate
 486  * additional memory for internal structures as necessary.
 487  *
 488  * @return An empty <code>UBiDi</code> object.
 489  * @stable ICU 2.0
 490  */
 491 U_STABLE UBiDi * U_EXPORT2
 492 ubidi_open(void);
 493
 494 /**
 495  * Allocate a <code>UBiDi</code> structure with preallocated memory
 496  * for internal structures.
 497  * This function provides a <code>UBiDi</code> object like <code>ubidi_open()</code>
 498  * with no arguments, but it also preallocates memory for internal structures
 499  * according to the sizings supplied by the caller.<p>
 500  * Subsequent functions will not allocate any more memory, and are thus
 501  * guaranteed not to fail because of lack of memory.<p>
 502  * The preallocation can be limited to some of the internal memory
 503  * by setting some values to 0 here. That means that if, e.g.,
 504  * <code>maxRunCount</code> cannot be reasonably predetermined and should not
 505  * be set to <code>maxLength</code> (the only failproof value) to avoid
 506  * wasting memory, then <code>maxRunCount</code> could be set to 0 here
 507  * and the internal structures that are associated with it will be allocated
 508  * on demand, just like with <code>ubidi_open()</code>.
 509  *
 510  * @param maxLength is the maximum text or line length that internal memory
 511  *        will be preallocated for. An attempt to associate this object with a
 512  *        longer text will fail, unless this value is 0, which leaves the allocation
 513  *        up to the implementation.
 514  *
 515  * @param maxRunCount is the maximum anticipated number of same-level runs
 516  *        that internal memory will be preallocated for. An attempt to access
 517  *        visual runs on an object that was not preallocated for as many runs
 518  *        as the text was actually resolved to will fail,
 519  *        unless this value is 0, which leaves the allocation up to the implementation.<br><br>
 520  *        The number of runs depends on the actual text and maybe anywhere between
 521  *        1 and <code>maxLength</code>. It is typically small.
 522  *
 523  * @param pErrorCode must be a valid pointer to an error code value.
 524  *
 525  * @return An empty <code>UBiDi</code> object with preallocated memory.
 526  * @stable ICU 2.0
 527  */
 528 U_STABLE UBiDi * U_EXPORT2
 529 ubidi_openSized(int32_t maxLength, int32_t maxRunCount, UErrorCode *pErrorCode);
 530
 531 /**
 532  * <code>ubidi_close()</code> must be called to free the memory
 533  * associated with a UBiDi object.<p>
 534  *
 535  * <strong>Important: </strong>
 536  * A parent <code>UBiDi</code> object must not be destroyed or reused if
 537  * it still has children.
 538  * If a <code>UBiDi</code> object has become the <i>child</i>
 539  * of another one (its <i>parent</i>) by calling
 540  * <code>ubidi_setLine()</code>, then the child object must
 541  * be destroyed (closed) or reused (by calling
 542  * <code>ubidi_setPara()</code> or <code>ubidi_setLine()</code>)
 543  * before the parent object.
 544  *
 545  * @param pBiDi is a <code>UBiDi</code> object.
 546  *
 547  * @see ubidi_setPara
 548  * @see ubidi_setLine
 549  * @stable ICU 2.0
 550  */
 551 U_STABLE void U_EXPORT2
 552 ubidi_close(UBiDi *pBiDi);
 553
 554 #if U_SHOW_CPLUSPLUS_API
 555
 556 U_NAMESPACE_BEGIN
 557
 558 /**
 559  * \class LocalUBiDiPointer
 560  * "Smart pointer" class, closes a UBiDi via ubidi_close().
 561  * For most methods see the LocalPointerBase base class.
 562  *
 563  * @see LocalPointerBase
 564  * @see LocalPointer
 565  * @stable ICU 4.4
 566  */
 567 U_DEFINE_LOCAL_OPEN_POINTER(LocalUBiDiPointer, UBiDi, ubidi_close);
 568
 569 U_NAMESPACE_END
 570
 571 #endif
 572
 573 /**
 574  * Modify the operation of the Bidi algorithm such that it
 575  * approximates an "inverse Bidi" algorithm. This function
 576  * must be called before <code>ubidi_setPara()</code>.
 577  *
 578  * <p>The normal operation of the Bidi algorithm as described
 579  * in the Unicode Technical Report is to take text stored in logical
 580  * (keyboard, typing) order and to determine the reordering of it for visual
 581  * rendering.
 582  * Some legacy systems store text in visual order, and for operations
 583  * with standard, Unicode-based algorithms, the text needs to be transformed
 584  * to logical order. This is effectively the inverse algorithm of the
 585  * described Bidi algorithm. Note that there is no standard algorithm for
 586  * this "inverse Bidi" and that the current implementation provides only an
 587  * approximation of "inverse Bidi".</p>
 588  *
 589  * <p>With <code>isInverse</code> set to <code>TRUE</code>,
 590  * this function changes the behavior of some of the subsequent functions
 591  * in a way that they can be used for the inverse Bidi algorithm.
 592  * Specifically, runs of text with numeric characters will be treated in a
 593  * special way and may need to be surrounded with LRM characters when they are
 594  * written in reordered sequence.</p>
 595  *
 596  * <p>Output runs should be retrieved using <code>ubidi_getVisualRun()</code>.
 597  * Since the actual input for "inverse Bidi" is visually ordered text and
 598  * <code>ubidi_getVisualRun()</code> gets the reordered runs, these are actually
 599  * the runs of the logically ordered output.</p>
 600  *
 601  * <p>Calling this function with argument <code>isInverse</code> set to
 602  * <code>TRUE</code> is equivalent to calling
 603  * <code>ubidi_setReorderingMode</code> with argument
 604  * <code>reorderingMode</code>
 605  * set to <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>.<br>
 606  * Calling this function with argument <code>isInverse</code> set to
 607  * <code>FALSE</code> is equivalent to calling
 608  * <code>ubidi_setReorderingMode</code> with argument
 609  * <code>reorderingMode</code>
 610  * set to <code>#UBIDI_REORDER_DEFAULT</code>.
 611  *
 612  * @param pBiDi is a <code>UBiDi</code> object.
 613  *
 614  * @param isInverse specifies "forward" or "inverse" Bidi operation.
 615  *
 616  * @see ubidi_setPara
 617  * @see ubidi_writeReordered
 618  * @see ubidi_setReorderingMode
 619  * @stable ICU 2.0
 620  */
 621 U_STABLE void U_EXPORT2
 622 ubidi_setInverse(UBiDi *pBiDi, UBool isInverse);
 623
 624 /**
 625  * Is this Bidi object set to perform the inverse Bidi algorithm?
 626  * <p>Note: calling this function after setting the reordering mode with
 627  * <code>ubidi_setReorderingMode</code> will return <code>TRUE</code> if the
 628  * reordering mode was set to <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>,
 629  * <code>FALSE</code> for all other values.</p>
 630  *
 631  * @param pBiDi is a <code>UBiDi</code> object.
 632  * @return TRUE if the Bidi object is set to perform the inverse Bidi algorithm
 633  * by handling numbers as L.
 634  *
 635  * @see ubidi_setInverse
 636  * @see ubidi_setReorderingMode
 637  * @stable ICU 2.0
 638  */
 639
 640 U_STABLE UBool U_EXPORT2
 641 ubidi_isInverse(UBiDi *pBiDi);
 642
 643 /**
 644  * Specify whether block separators must be allocated level zero,
 645  * so that successive paragraphs will progress from left to right.
 646  * This function must be called before <code>ubidi_setPara()</code>.
 647  * Paragraph separators (B) may appear in the text.  Setting them to level zero
 648  * means that all paragraph separators (including one possibly appearing
 649  * in the last text position) are kept in the reordered text after the text
 650  * that they follow in the source text.
 651  * When this feature is not enabled, a paragraph separator at the last
 652  * position of the text before reordering will go to the first position
 653  * of the reordered text when the paragraph level is odd.
 654  *
 655  * @param pBiDi is a <code>UBiDi</code> object.
 656  *
 657  * @param orderParagraphsLTR specifies whether paragraph separators (B) must
 658  * receive level 0, so that successive paragraphs progress from left to right.
 659  *
 660  * @see ubidi_setPara
 661  * @stable ICU 3.4
 662  */
 663 U_STABLE void U_EXPORT2
 664 ubidi_orderParagraphsLTR(UBiDi *pBiDi, UBool orderParagraphsLTR);
 665
 666 /**
 667  * Is this Bidi object set to allocate level 0 to block separators so that
 668  * successive paragraphs progress from left to right?
 669  *
 670  * @param pBiDi is a <code>UBiDi</code> object.
 671  * @return TRUE if the Bidi object is set to allocate level 0 to block
 672  *         separators.
 673  *
 674  * @see ubidi_orderParagraphsLTR
 675  * @stable ICU 3.4
 676  */
 677 U_STABLE UBool U_EXPORT2
 678 ubidi_isOrderParagraphsLTR(UBiDi *pBiDi);
 679
 680 /**
 681  * <code>UBiDiReorderingMode</code> values indicate which variant of the Bidi
 682  * algorithm to use.
 683  *
 684  * @see ubidi_setReorderingMode
 685  * @stable ICU 3.6
 686  */
 687 typedef enum UBiDiReorderingMode {
 688     /** Regular Logical to Visual Bidi algorithm according to Unicode.
 689       * This is a 0 value.
 690       * @stable ICU 3.6 */
 691     UBIDI_REORDER_DEFAULT = 0,
 692     /** Logical to Visual algorithm which handles numbers in a way which
 693       * mimicks the behavior of Windows XP.
 694       * @stable ICU 3.6 */
 695     UBIDI_REORDER_NUMBERS_SPECIAL,
 696     /** Logical to Visual algorithm grouping numbers with adjacent R characters
 697       * (reversible algorithm).
 698       * @stable ICU 3.6 */
 699     UBIDI_REORDER_GROUP_NUMBERS_WITH_R,
 700     /** Reorder runs only to transform a Logical LTR string to the Logical RTL
 701       * string with the same display, or vice-versa.<br>
 702       * If this mode is set together with option
 703       * <code>#UBIDI_OPTION_INSERT_MARKS</code>, some Bidi controls in the source
 704       * text may be removed and other controls may be added to produce the
 705       * minimum combination which has the required display.
 706       * @stable ICU 3.6 */
 707     UBIDI_REORDER_RUNS_ONLY,
 708     /** Visual to Logical algorithm which handles numbers like L
 709       * (same algorithm as selected by <code>ubidi_setInverse(TRUE)</code>.
 710       * @see ubidi_setInverse
 711       * @stable ICU 3.6 */
 712     UBIDI_REORDER_INVERSE_NUMBERS_AS_L,
 713     /** Visual to Logical algorithm equivalent to the regular Logical to Visual
 714       * algorithm.
 715       * @stable ICU 3.6 */
 716     UBIDI_REORDER_INVERSE_LIKE_DIRECT,
 717     /** Inverse Bidi (Visual to Logical) algorithm for the
 718       * <code>UBIDI_REORDER_NUMBERS_SPECIAL</code> Bidi algorithm.
 719       * @stable ICU 3.6 */
 720     UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL,
 721     /** Number of values for reordering mode.
 722       * @stable ICU 3.6 */
 723     UBIDI_REORDER_COUNT
 724 } UBiDiReorderingMode;
 725
 726 /**
 727  * Modify the operation of the Bidi algorithm such that it implements some
 728  * variant to the basic Bidi algorithm or approximates an "inverse Bidi"
 729  * algorithm, depending on different values of the "reordering mode".
 730  * This function must be called before <code>ubidi_setPara()</code>, and stays
 731  * in effect until called again with a different argument.
 732  *
 733  * <p>The normal operation of the Bidi algorithm as described
 734  * in the Unicode Standard Annex #9 is to take text stored in logical
 735  * (keyboard, typing) order and to determine how to reorder it for visual
 736  * rendering.</p>
 737  *
 738  * <p>With the reordering mode set to a value other than
 739  * <code>#UBIDI_REORDER_DEFAULT</code>, this function changes the behavior of
 740  * some of the subsequent functions in a way such that they implement an
 741  * inverse Bidi algorithm or some other algorithm variants.</p>
 742  *
 743  * <p>Some legacy systems store text in visual order, and for operations
 744  * with standard, Unicode-based algorithms, the text needs to be transformed
 745  * into logical order. This is effectively the inverse algorithm of the
 746  * described Bidi algorithm. Note that there is no standard algorithm for
 747  * this "inverse Bidi", so a number of variants are implemented here.</p>
 748  *
 749  * <p>In other cases, it may be desirable to emulate some variant of the
 750  * Logical to Visual algorithm (e.g. one used in MS Windows), or perform a
 751  * Logical to Logical transformation.</p>
 752  *
 753  * <ul>
 754  * <li>When the reordering mode is set to <code>#UBIDI_REORDER_DEFAULT</code>,
 755  * the standard Bidi Logical to Visual algorithm is applied.</li>
 756  *
 757  * <li>When the reordering mode is set to
 758  * <code>#UBIDI_REORDER_NUMBERS_SPECIAL</code>,
 759  * the algorithm used to perform Bidi transformations when calling
 760  * <code>ubidi_setPara</code> should approximate the algorithm used in
 761  * Microsoft Windows XP rather than strictly conform to the Unicode Bidi
 762  * algorithm.
 763  * <br>
 764  * The differences between the basic algorithm and the algorithm addressed
 765  * by this option are as follows:
 766  * <ul>
 767  *   <li>Within text at an even embedding level, the sequence "123AB"
 768  *   (where AB represent R or AL letters) is transformed to "123BA" by the
 769  *   Unicode algorithm and to "BA123" by the Windows algorithm.</li>
 770  *   <li>Arabic-Indic numbers (AN) are handled by the Windows algorithm just
 771  *   like regular numbers (EN).</li>
 772  * </ul></li>
 773  *
 774  * <li>When the reordering mode is set to
 775  * <code>#UBIDI_REORDER_GROUP_NUMBERS_WITH_R</code>,
 776  * numbers located between LTR text and RTL text are associated with the RTL
 777  * text. For instance, an LTR paragraph with content "abc 123 DEF" (where
 778  * upper case letters represent RTL characters) will be transformed to
 779  * "abc FED 123" (and not "abc 123 FED"), "DEF 123 abc" will be transformed
 780  * to "123 FED abc" and "123 FED abc" will be transformed to "DEF 123 abc".
 781  * This makes the algorithm reversible and makes it useful when round trip
 782  * (from visual to logical and back to visual) must be achieved without
 783  * adding LRM characters. However, this is a variation from the standard
 784  * Unicode Bidi algorithm.<br>
 785  * The source text should not contain Bidi control characters other than LRM
 786  * or RLM.</li>
 787  *
 788  * <li>When the reordering mode is set to
 789  * <code>#UBIDI_REORDER_RUNS_ONLY</code>,
 790  * a "Logical to Logical" transformation must be performed:
 791  * <ul>
 792  * <li>If the default text level of the source text (argument <code>paraLevel</code>
 793  * in <code>ubidi_setPara</code>) is even, the source text will be handled as
 794  * LTR logical text and will be transformed to the RTL logical text which has
 795  * the same LTR visual display.</li>
 796  * <li>If the default level of the source text is odd, the source text
 797  * will be handled as RTL logical text and will be transformed to the
 798  * LTR logical text which has the same LTR visual display.</li>
 799  * </ul>
 800  * This mode may be needed when logical text which is basically Arabic or
 801  * Hebrew, with possible included numbers or phrases in English, has to be
 802  * displayed as if it had an even embedding level (this can happen if the
 803  * displaying application treats all text as if it was basically LTR).
 804  * <br>
 805  * This mode may also be needed in the reverse case, when logical text which is
 806  * basically English, with possible included phrases in Arabic or Hebrew, has to
 807  * be displayed as if it had an odd embedding level.
 808  * <br>
 809  * Both cases could be handled by adding LRE or RLE at the head of the text,
 810  * if the display subsystem supports these formatting controls. If it does not,
 811  * the problem may be handled by transforming the source text in this mode
 812  * before displaying it, so that it will be displayed properly.<br>
 813  * The source text should not contain Bidi control characters other than LRM
 814  * or RLM.</li>
 815  *
 816  * <li>When the reordering mode is set to
 817  * <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>, an "inverse Bidi" algorithm
 818  * is applied.
 819  * Runs of text with numeric characters will be treated like LTR letters and
 820  * may need to be surrounded with LRM characters when they are written in
 821  * reordered sequence (the option <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code> can
 822  * be used with function <code>ubidi_writeReordered</code> to this end. This
 823  * mode is equivalent to calling <code>ubidi_setInverse()</code> with
 824  * argument <code>isInverse</code> set to <code>TRUE</code>.</li>
 825  *
 826  * <li>When the reordering mode is set to
 827  * <code>#UBIDI_REORDER_INVERSE_LIKE_DIRECT</code>, the "direct" Logical to Visual
 828  * Bidi algorithm is used as an approximation of an "inverse Bidi" algorithm.
 829  * This mode is similar to mode <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>
 830  * but is closer to the regular Bidi algorithm.
 831  * <br>
 832  * For example, an LTR paragraph with the content "FED 123 456 CBA" (where
 833  * upper case represents RTL characters) will be transformed to
 834  * "ABC 456 123 DEF", as opposed to "DEF 123 456 ABC"
 835  * with mode <code>UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>.<br>
 836  * When used in conjunction with option
 837  * <code>#UBIDI_OPTION_INSERT_MARKS</code>, this mode generally
 838  * adds Bidi marks to the output significantly more sparingly than mode
 839  * <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code> with option
 840  * <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code> in calls to
 841  * <code>ubidi_writeReordered</code>.</li>
 842  *
 843  * <li>When the reordering mode is set to
 844  * <code>#UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL</code>, the Logical to Visual
 845  * Bidi algorithm used in Windows XP is used as an approximation of an "inverse Bidi" algorithm.
 846  * <br>
 847  * For example, an LTR paragraph with the content "abc FED123" (where
 848  * upper case represents RTL characters) will be transformed to "abc 123DEF."</li>
 849  * </ul>
 850  *
 851  * <p>In all the reordering modes specifying an "inverse Bidi" algorithm
 852  * (i.e. those with a name starting with <code>UBIDI_REORDER_INVERSE</code>),
 853  * output runs should be retrieved using
 854  * <code>ubidi_getVisualRun()</code>, and the output text with
 855  * <code>ubidi_writeReordered()</code>. The caller should keep in mind that in
 856  * "inverse Bidi" modes the input is actually visually ordered text and
 857  * reordered output returned by <code>ubidi_getVisualRun()</code> or
 858  * <code>ubidi_writeReordered()</code> are actually runs or character string
 859  * of logically ordered output.<br>
 860  * For all the "inverse Bidi" modes, the source text should not contain
 861  * Bidi control characters other than LRM or RLM.</p>
 862  *
 863  * <p>Note that option <code>#UBIDI_OUTPUT_REVERSE</code> of
 864  * <code>ubidi_writeReordered</code> has no useful meaning and should not be
 865  * used in conjunction with any value of the reordering mode specifying
 866  * "inverse Bidi" or with value <code>UBIDI_REORDER_RUNS_ONLY</code>.
 867  *
 868  * @param pBiDi is a <code>UBiDi</code> object.
 869  * @param reorderingMode specifies the required variant of the Bidi algorithm.
 870  *
 871  * @see UBiDiReorderingMode
 872  * @see ubidi_setInverse
 873  * @see ubidi_setPara
 874  * @see ubidi_writeReordered
 875  * @stable ICU 3.6
 876  */
 877 U_STABLE void U_EXPORT2
 878 ubidi_setReorderingMode(UBiDi *pBiDi, UBiDiReorderingMode reorderingMode);
 879
 880 /**
 881  * What is the requested reordering mode for a given Bidi object?
 882  *
 883  * @param pBiDi is a <code>UBiDi</code> object.
 884  * @return the current reordering mode of the Bidi object
 885  * @see ubidi_setReorderingMode
 886  * @stable ICU 3.6
 887  */
 888 U_STABLE UBiDiReorderingMode U_EXPORT2
 889 ubidi_getReorderingMode(UBiDi *pBiDi);
 890
 891 /**
 892  * <code>UBiDiReorderingOption</code> values indicate which options are
 893  * specified to affect the Bidi algorithm.
 894  *
 895  * @see ubidi_setReorderingOptions
 896  * @stable ICU 3.6
 897  */
 898 typedef enum UBiDiReorderingOption {
 899     /**
 900      * option value for <code>ubidi_setReorderingOptions</code>:
 901      * disable all the options which can be set with this function
 902      * @see ubidi_setReorderingOptions
 903      * @stable ICU 3.6
 904      */
 905     UBIDI_OPTION_DEFAULT = 0,
 906
 907     /**
 908      * option bit for <code>ubidi_setReorderingOptions</code>:
 909      * insert Bidi marks (LRM or RLM) when needed to ensure correct result of
 910      * a reordering to a Logical order
 911      *
 912      * <p>This option must be set or reset before calling
 913      * <code>ubidi_setPara</code>.</p>
 914      *
 915      * <p>This option is significant only with reordering modes which generate
 916      * a result with Logical order, specifically:</p>
 917      * <ul>
 918      *   <li><code>#UBIDI_REORDER_RUNS_ONLY</code></li>
 919      *   <li><code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code></li>
 920      *   <li><code>#UBIDI_REORDER_INVERSE_LIKE_DIRECT</code></li>
 921      *   <li><code>#UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL</code></li>
 922      * </ul>
 923      *
 924      * <p>If this option is set in conjunction with reordering mode
 925      * <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code> or with calling
 926      * <code>ubidi_setInverse(TRUE)</code>, it implies
 927      * option <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code>
 928      * in calls to function <code>ubidi_writeReordered()</code>.</p>
 929      *
 930      * <p>For other reordering modes, a minimum number of LRM or RLM characters
 931      * will be added to the source text after reordering it so as to ensure
 932      * round trip, i.e. when applying the inverse reordering mode on the
 933      * resulting logical text with removal of Bidi marks
 934      * (option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code> set before calling
 935      * <code>ubidi_setPara()</code> or option <code>#UBIDI_REMOVE_BIDI_CONTROLS</code>
 936      * in <code>ubidi_writeReordered</code>), the result will be identical to the
 937      * source text in the first transformation.
 938      *
 939      * <p>This option will be ignored if specified together with option
 940      * <code>#UBIDI_OPTION_REMOVE_CONTROLS</code>. It inhibits option
 941      * <code>UBIDI_REMOVE_BIDI_CONTROLS</code> in calls to function
 942      * <code>ubidi_writeReordered()</code> and it implies option
 943      * <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code> in calls to function
 944      * <code>ubidi_writeReordered()</code> if the reordering mode is
 945      * <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>.</p>
 946      *
 947      * @see ubidi_setReorderingMode
 948      * @see ubidi_setReorderingOptions
 949      * @stable ICU 3.6
 950      */
 951     UBIDI_OPTION_INSERT_MARKS = 1,
 952
 953     /**
 954      * option bit for <code>ubidi_setReorderingOptions</code>:
 955      * remove Bidi control characters
 956      *
 957      * <p>This option must be set or reset before calling
 958      * <code>ubidi_setPara</code>.</p>
 959      *
 960      * <p>This option nullifies option <code>#UBIDI_OPTION_INSERT_MARKS</code>.
 961      * It inhibits option <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code> in calls
 962      * to function <code>ubidi_writeReordered()</code> and it implies option
 963      * <code>#UBIDI_REMOVE_BIDI_CONTROLS</code> in calls to that function.</p>
 964      *
 965      * @see ubidi_setReorderingMode
 966      * @see ubidi_setReorderingOptions
 967      * @stable ICU 3.6
 968      */
 969     UBIDI_OPTION_REMOVE_CONTROLS = 2,
 970
 971     /**
 972      * option bit for <code>ubidi_setReorderingOptions</code>:
 973      * process the output as part of a stream to be continued
 974      *
 975      * <p>This option must be set or reset before calling
 976      * <code>ubidi_setPara</code>.</p>
 977      *
 978      * <p>This option specifies that the caller is interested in processing large
 979      * text object in parts.
 980      * The results of the successive calls are expected to be concatenated by the
 981      * caller. Only the call for the last part will have this option bit off.</p>
 982      *
 983      * <p>When this option bit is on, <code>ubidi_setPara()</code> may process
 984      * less than the full source text in order to truncate the text at a meaningful
 985      * boundary. The caller should call <code>ubidi_getProcessedLength()</code>
 986      * immediately after calling <code>ubidi_setPara()</code> in order to
 987      * determine how much of the source text has been processed.
 988      * Source text beyond that length should be resubmitted in following calls to
 989      * <code>ubidi_setPara</code>. The processed length may be less than
 990      * the length of the source text if a character preceding the last character of
 991      * the source text constitutes a reasonable boundary (like a block separator)
 992      * for text to be continued.<br>
 993      * If the last character of the source text constitutes a reasonable
 994      * boundary, the whole text will be processed at once.<br>
 995      * If nowhere in the source text there exists
 996      * such a reasonable boundary, the processed length will be zero.<br>
 997      * The caller should check for such an occurrence and do one of the following:
 998      * <ul><li>submit a larger amount of text with a better chance to include
 999      *         a reasonable boundary.</li>
1000      *     <li>resubmit the same text after turning off option
1001      *         <code>UBIDI_OPTION_STREAMING</code>.</li></ul>
1002      * In all cases, this option should be turned off before processing the last
1003      * part of the text.</p>
1004      *
1005      * <p>When the <code>UBIDI_OPTION_STREAMING</code> option is used,
1006      * it is recommended to call <code>ubidi_orderParagraphsLTR()</code> with
1007      * argument <code>orderParagraphsLTR</code> set to <code>TRUE</code> before
1008      * calling <code>ubidi_setPara</code> so that later paragraphs may be
1009      * concatenated to previous paragraphs on the right.</p>
1010      *
1011      * @see ubidi_setReorderingMode
1012      * @see ubidi_setReorderingOptions
1013      * @see ubidi_getProcessedLength
1014      * @see ubidi_orderParagraphsLTR
1015      * @stable ICU 3.6
1016      */
1017     UBIDI_OPTION_STREAMING = 4
1018 } UBiDiReorderingOption;
1019
1020 /**
1021  * Specify which of the reordering options
1022  * should be applied during Bidi transformations.
1023  *
1024  * @param pBiDi is a <code>UBiDi</code> object.
1025  * @param reorderingOptions is a combination of zero or more of the following
1026  * options:
1027  * <code>#UBIDI_OPTION_DEFAULT</code>, <code>#UBIDI_OPTION_INSERT_MARKS</code>,
1028  * <code>#UBIDI_OPTION_REMOVE_CONTROLS</code>, <code>#UBIDI_OPTION_STREAMING</code>.
1029  *
1030  * @see ubidi_getReorderingOptions
1031  * @stable ICU 3.6
1032  */
1033 U_STABLE void U_EXPORT2
1034 ubidi_setReorderingOptions(UBiDi *pBiDi, uint32_t reorderingOptions);
1035
1036 /**
1037  * What are the reordering options applied to a given Bidi object?
1038  *
1039  * @param pBiDi is a <code>UBiDi</code> object.
1040  * @return the current reordering options of the Bidi object
1041  * @see ubidi_setReorderingOptions
1042  * @stable ICU 3.6
1043  */
1044 U_STABLE uint32_t U_EXPORT2
1045 ubidi_getReorderingOptions(UBiDi *pBiDi);
1046
1047 /**
1048  * Set the context before a call to ubidi_setPara().<p>
1049  *
1050  * ubidi_setPara() computes the left-right directionality for a given piece
1051  * of text which is supplied as one of its arguments. Sometimes this piece
1052  * of text (the "main text") should be considered in context, because text
1053  * appearing before ("prologue") and/or after ("epilogue") the main text
1054  * may affect the result of this computation.<p>
1055  *
1056  * This function specifies the prologue and/or the epilogue for the next
1057  * call to ubidi_setPara(). The characters specified as prologue and
1058  * epilogue should not be modified by the calling program until the call
1059  * to ubidi_setPara() has returned. If successive calls to ubidi_setPara()
1060  * all need specification of a context, ubidi_setContext() must be called
1061  * before each call to ubidi_setPara(). In other words, a context is not
1062  * "remembered" after the following successful call to ubidi_setPara().<p>
1063  *
1064  * If a call to ubidi_setPara() specifies UBIDI_DEFAULT_LTR or
1065  * UBIDI_DEFAULT_RTL as paraLevel and is preceded by a call to
1066  * ubidi_setContext() which specifies a prologue, the paragraph level will
1067  * be computed taking in consideration the text in the prologue.<p>
1068  *
1069  * When ubidi_setPara() is called without a previous call to
1070  * ubidi_setContext, the main text is handled as if preceded and followed
1071  * by strong directional characters at the current paragraph level.
1072  * Calling ubidi_setContext() with specification of a prologue will change
1073  * this behavior by handling the main text as if preceded by the last
1074  * strong character appearing in the prologue, if any.
1075  * Calling ubidi_setContext() with specification of an epilogue will change
1076  * the behavior of ubidi_setPara() by handling the main text as if followed
1077  * by the first strong character or digit appearing in the epilogue, if any.<p>
1078  *
1079  * Note 1: if <code>ubidi_setContext</code> is called repeatedly without
1080  *         calling <code>ubidi_setPara</code>, the earlier calls have no effect,
1081  *         only the last call will be remembered for the next call to
1082  *         <code>ubidi_setPara</code>.<p>
1083  *
1084  * Note 2: calling <code>ubidi_setContext(pBiDi, NULL, 0, NULL, 0, &errorCode)</code>
1085  *         cancels any previous setting of non-empty prologue or epilogue.
1086  *         The next call to <code>ubidi_setPara()</code> will process no
1087  *         prologue or epilogue.<p>
1088  *
1089  * Note 3: users must be aware that even after setting the context
1090  *         before a call to ubidi_setPara() to perform e.g. a logical to visual
1091  *         transformation, the resulting string may not be identical to what it
1092  *         would have been if all the text, including prologue and epilogue, had
1093  *         been processed together.<br>
1094  * Example (upper case letters represent RTL characters):<br>
1095  * &nbsp;&nbsp;prologue = "<code>abc DE</code>"<br>
1096  * &nbsp;&nbsp;epilogue = none<br>
1097  * &nbsp;&nbsp;main text = "<code>FGH xyz</code>"<br>
1098  * &nbsp;&nbsp;paraLevel = UBIDI_LTR<br>
1099  * &nbsp;&nbsp;display without prologue = "<code>HGF xyz</code>"
1100  *             ("HGF" is adjacent to "xyz")<br>
1101  * &nbsp;&nbsp;display with prologue = "<code>abc HGFED xyz</code>"
1102  *             ("HGF" is not adjacent to "xyz")<br>
1103  *
1104  * @param pBiDi is a paragraph <code>UBiDi</code> object.
1105  *
1106  * @param prologue is a pointer to the text which precedes the text that
1107  *        will be specified in a coming call to ubidi_setPara().
1108  *        If there is no prologue to consider, then <code>proLength</code>
1109  *        must be zero and this pointer can be NULL.
1110  *
1111  * @param proLength is the length of the prologue; if <code>proLength==-1</code>
1112  *        then the prologue must be zero-terminated.
1113  *        Otherwise proLength must be >= 0. If <code>proLength==0</code>, it means
1114  *        that there is no prologue to consider.
1115  *
1116  * @param epilogue is a pointer to the text which follows the text that
1117  *        will be specified in a coming call to ubidi_setPara().
1118  *        If there is no epilogue to consider, then <code>epiLength</code>
1119  *        must be zero and this pointer can be NULL.
1120  *
1121  * @param epiLength is the length of the epilogue; if <code>epiLength==-1</code>
1122  *        then the epilogue must be zero-terminated.
1123  *        Otherwise epiLength must be >= 0. If <code>epiLength==0</code>, it means
1124  *        that there is no epilogue to consider.
1125  *
1126  * @param pErrorCode must be a valid pointer to an error code value.
1127  *
1128  * @see ubidi_setPara
1129  * @stable ICU 4.8
1130  */
1131 U_STABLE void U_EXPORT2
1132 ubidi_setContext(UBiDi *pBiDi,
1133                  const UChar *prologue, int32_t proLength,
1134                  const UChar *epilogue, int32_t epiLength,
1135                  UErrorCode *pErrorCode);
1136
1137 /**
1138  * Perform the Unicode Bidi algorithm. It is defined in the
1139  * <a href="http://www.unicode.org/unicode/reports/tr9/">Unicode Standard Anned #9</a>,
1140  * version 13,
1141  * also described in The Unicode Standard, Version 4.0 .<p>
1142  *
1143  * This function takes a piece of plain text containing one or more paragraphs,
1144  * with or without externally specified embedding levels from <i>styled</i>
1145  * text and computes the left-right-directionality of each character.<p>
1146  *
1147  * If the entire text is all of the same directionality, then
1148  * the function may not perform all the steps described by the algorithm,
1149  * i.e., some levels may not be the same as if all steps were performed.
1150  * This is not relevant for unidirectional text.<br>
1151  * For example, in pure LTR text with numbers the numbers would get
1152  * a resolved level of 2 higher than the surrounding text according to
1153  * the algorithm. This implementation may set all resolved levels to
1154  * the same value in such a case.<p>
1155  *
1156  * The text can be composed of multiple paragraphs. Occurrence of a block
1157  * separator in the text terminates a paragraph, and whatever comes next starts
1158  * a new paragraph. The exception to this rule is when a Carriage Return (CR)
1159  * is followed by a Line Feed (LF). Both CR and LF are block separators, but
1160  * in that case, the pair of characters is considered as terminating the
1161  * preceding paragraph, and a new paragraph will be started by a character
1162  * coming after the LF.
1163  *
1164  * @param pBiDi A <code>UBiDi</code> object allocated with <code>ubidi_open()</code>
1165  *        which will be set to contain the reordering information,
1166  *        especially the resolved levels for all the characters in <code>text</code>.
1167  *
1168  * @param text is a pointer to the text that the Bidi algorithm will be performed on.
1169  *        This pointer is stored in the UBiDi object and can be retrieved
1170  *        with <code>ubidi_getText()</code>.<br>
1171  *        <strong>Note:</strong> the text must be (at least) <code>length</code> long.
1172  *
1173  * @param length is the length of the text; if <code>length==-1</code> then
1174  *        the text must be zero-terminated.
1175  *
1176  * @param paraLevel specifies the default level for the text;
1177  *        it is typically 0 (LTR) or 1 (RTL).
1178  *        If the function shall determine the paragraph level from the text,
1179  *        then <code>paraLevel</code> can be set to
1180  *        either <code>#UBIDI_DEFAULT_LTR</code>
1181  *        or <code>#UBIDI_DEFAULT_RTL</code>; if the text contains multiple
1182  *        paragraphs, the paragraph level shall be determined separately for
1183  *        each paragraph; if a paragraph does not include any strongly typed
1184  *        character, then the desired default is used (0 for LTR or 1 for RTL).
1185  *        Any other value between 0 and <code>#UBIDI_MAX_EXPLICIT_LEVEL</code>
1186  *        is also valid, with odd levels indicating RTL.
1187  *
1188  * @param embeddingLevels (in) may be used to preset the embedding and override levels,
1189  *        ignoring characters like LRE and PDF in the text.
1190  *        A level overrides the directional property of its corresponding
1191  *        (same index) character if the level has the
1192  *        <code>#UBIDI_LEVEL_OVERRIDE</code> bit set.<br><br>
1193  *        Except for that bit, it must be
1194  *        <code>paraLevel<=embeddingLevels[]<=UBIDI_MAX_EXPLICIT_LEVEL</code>,
1195  *        with one exception: a level of zero may be specified for a paragraph
1196  *        separator even if <code>paraLevel>0</code> when multiple paragraphs
1197  *        are submitted in the same call to <code>ubidi_setPara()</code>.<br><br>
1198  *        <strong>Caution: </strong>A copy of this pointer, not of the levels,
1199  *        will be stored in the <code>UBiDi</code> object;
1200  *        the <code>embeddingLevels</code> array must not be
1201  *        deallocated before the <code>UBiDi</code> structure is destroyed or reused,
1202  *        and the <code>embeddingLevels</code>
1203  *        should not be modified to avoid unexpected results on subsequent Bidi operations.
1204  *        However, the <code>ubidi_setPara()</code> and
1205  *        <code>ubidi_setLine()</code> functions may modify some or all of the levels.<br><br>
1206  *        After the <code>UBiDi</code> object is reused or destroyed, the caller
1207  *        must take care of the deallocation of the <code>embeddingLevels</code> array.<br><br>
1208  *        <strong>Note:</strong> the <code>embeddingLevels</code> array must be
1209  *        at least <code>length</code> long.
1210  *        This pointer can be <code>NULL</code> if this
1211  *        value is not necessary.
1212  *
1213  * @param pErrorCode must be a valid pointer to an error code value.
1214  * @stable ICU 2.0
1215  */
1216 U_STABLE void U_EXPORT2
1217 ubidi_setPara(UBiDi *pBiDi, const UChar *text, int32_t length,
1218               UBiDiLevel paraLevel, UBiDiLevel *embeddingLevels,
1219               UErrorCode *pErrorCode);
1220
1221 /**
1222  * <code>ubidi_setLine()</code> sets a <code>UBiDi</code> to
1223  * contain the reordering information, especially the resolved levels,
1224  * for all the characters in a line of text. This line of text is
1225  * specified by referring to a <code>UBiDi</code> object representing
1226  * this information for a piece of text containing one or more paragraphs,
1227  * and by specifying a range of indexes in this text.<p>
1228  * In the new line object, the indexes will range from 0 to <code>limit-start-1</code>.<p>
1229  *
1230  * This is used after calling <code>ubidi_setPara()</code>
1231  * for a piece of text, and after line-breaking on that text.
1232  * It is not necessary if each paragraph is treated as a single line.<p>
1233  *
1234  * After line-breaking, rules (L1) and (L2) for the treatment of
1235  * trailing WS and for reordering are performed on
1236  * a <code>UBiDi</code> object that represents a line.<p>
1237  *
1238  * <strong>Important: </strong><code>pLineBiDi</code> shares data with
1239  * <code>pParaBiDi</code>.
1240  * You must destroy or reuse <code>pLineBiDi</code> before <code>pParaBiDi</code>.
1241  * In other words, you must destroy or reuse the <code>UBiDi</code> object for a line
1242  * before the object for its parent paragraph.<p>
1243  *
1244  * The text pointer that was stored in <code>pParaBiDi</code> is also copied,
1245  * and <code>start</code> is added to it so that it points to the beginning of the
1246  * line for this object.
1247  *
1248  * @param pParaBiDi is the parent paragraph object. It must have been set
1249  * by a successful call to ubidi_setPara.
1250  *
1251  * @param start is the line's first index into the text.
1252  *
1253  * @param limit is just behind the line's last index into the text
1254  *        (its last index +1).<br>
1255  *        It must be <code>0<=start<limit<=</code>containing paragraph limit.
1256  *        If the specified line crosses a paragraph boundary, the function
1257  *        will terminate with error code U_ILLEGAL_ARGUMENT_ERROR.
1258  *
1259  * @param pLineBiDi is the object that will now represent a line of the text.
1260  *
1261  * @param pErrorCode must be a valid pointer to an error code value.
1262  *
1263  * @see ubidi_setPara
1264  * @see ubidi_getProcessedLength
1265  * @stable ICU 2.0
1266  */
1267 U_STABLE void U_EXPORT2
1268 ubidi_setLine(const UBiDi *pParaBiDi,
1269               int32_t start, int32_t limit,
1270               UBiDi *pLineBiDi,
1271               UErrorCode *pErrorCode);
1272
1273 /**
1274  * Get the directionality of the text.
1275  *
1276  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1277  *
1278  * @return a value of <code>UBIDI_LTR</code>, <code>UBIDI_RTL</code>
1279  *         or <code>UBIDI_MIXED</code>
1280  *         that indicates if the entire text
1281  *         represented by this object is unidirectional,
1282  *         and which direction, or if it is mixed-directional.
1283  * Note -  The value <code>UBIDI_NEUTRAL</code> is never returned from this method.
1284  *
1285  * @see UBiDiDirection
1286  * @stable ICU 2.0
1287  */
1288 U_STABLE UBiDiDirection U_EXPORT2
1289 ubidi_getDirection(const UBiDi *pBiDi);
1290
1291 /**
1292  * Gets the base direction of the text provided according
1293  * to the Unicode Bidirectional Algorithm. The base direction
1294  * is derived from the first character in the string with bidirectional
1295  * character type L, R, or AL. If the first such character has type L,
1296  * <code>UBIDI_LTR</code> is returned. If the first such character has
1297  * type R or AL, <code>UBIDI_RTL</code> is returned. If the string does
1298  * not contain any character of these types, then
1299  * <code>UBIDI_NEUTRAL</code> is returned.
1300  *
1301  * This is a lightweight function for use when only the base direction
1302  * is needed and no further bidi processing of the text is needed.
1303  *
1304  * @param text is a pointer to the text whose base
1305  *             direction is needed.
1306  * Note: the text must be (at least) @c length long.
1307  *
1308  * @param length is the length of the text;
1309  *               if <code>length==-1</code> then the text
1310  *               must be zero-terminated.
1311  *
1312  * @return  <code>UBIDI_LTR</code>, <code>UBIDI_RTL</code>,
1313  *          <code>UBIDI_NEUTRAL</code>
1314  *
1315  * @see UBiDiDirection
1316  * @stable ICU 4.6
1317  */
1318 U_STABLE UBiDiDirection U_EXPORT2
1319 ubidi_getBaseDirection(const UChar *text,  int32_t length );
1320
1321 /**
1322  * Get the pointer to the text.
1323  *
1324  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1325  *
1326  * @return The pointer to the text that the UBiDi object was created for.
1327  *
1328  * @see ubidi_setPara
1329  * @see ubidi_setLine
1330  * @stable ICU 2.0
1331  */
1332 U_STABLE const UChar * U_EXPORT2
1333 ubidi_getText(const UBiDi *pBiDi);
1334
1335 /**
1336  * Get the length of the text.
1337  *
1338  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1339  *
1340  * @return The length of the text that the UBiDi object was created for.
1341  * @stable ICU 2.0
1342  */
1343 U_STABLE int32_t U_EXPORT2
1344 ubidi_getLength(const UBiDi *pBiDi);
1345
1346 /**
1347  * Get the paragraph level of the text.
1348  *
1349  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1350  *
1351  * @return The paragraph level. If there are multiple paragraphs, their
1352  *         level may vary if the required paraLevel is UBIDI_DEFAULT_LTR or
1353  *         UBIDI_DEFAULT_RTL.  In that case, the level of the first paragraph
1354  *         is returned.
1355  *
1356  * @see UBiDiLevel
1357  * @see ubidi_getParagraph
1358  * @see ubidi_getParagraphByIndex
1359  * @stable ICU 2.0
1360  */
1361 U_STABLE UBiDiLevel U_EXPORT2
1362 ubidi_getParaLevel(const UBiDi *pBiDi);
1363
1364 /**
1365  * Get the number of paragraphs.
1366  *
1367  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1368  *
1369  * @return The number of paragraphs.
1370  * @stable ICU 3.4
1371  */
1372 U_STABLE int32_t U_EXPORT2
1373 ubidi_countParagraphs(UBiDi *pBiDi);
1374
1375 /**
1376  * Get a paragraph, given a position within the text.
1377  * This function returns information about a paragraph.<br>
1378  * Note: if the paragraph index is known, it is more efficient to
1379  * retrieve the paragraph information using ubidi_getParagraphByIndex().<p>
1380  *
1381  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1382  *
1383  * @param charIndex is the index of a character within the text, in the
1384  *        range <code>[0..ubidi_getProcessedLength(pBiDi)-1]</code>.
1385  *
1386  * @param pParaStart will receive the index of the first character of the
1387  *        paragraph in the text.
1388  *        This pointer can be <code>NULL</code> if this
1389  *        value is not necessary.
1390  *
1391  * @param pParaLimit will receive the limit of the paragraph.
1392  *        The l-value that you point to here may be the
1393  *        same expression (variable) as the one for
1394  *        <code>charIndex</code>.
1395  *        This pointer can be <code>NULL</code> if this
1396  *        value is not necessary.
1397  *
1398  * @param pParaLevel will receive the level of the paragraph.
1399  *        This pointer can be <code>NULL</code> if this
1400  *        value is not necessary.
1401  *
1402  * @param pErrorCode must be a valid pointer to an error code value.
1403  *
1404  * @return The index of the paragraph containing the specified position.
1405  *
1406  * @see ubidi_getProcessedLength
1407  * @stable ICU 3.4
1408  */
1409 U_STABLE int32_t U_EXPORT2
1410 ubidi_getParagraph(const UBiDi *pBiDi, int32_t charIndex, int32_t *pParaStart,
1411                    int32_t *pParaLimit, UBiDiLevel *pParaLevel,
1412                    UErrorCode *pErrorCode);
1413
1414 /**
1415  * Get a paragraph, given the index of this paragraph.
1416  *
1417  * This function returns information about a paragraph.<p>
1418  *
1419  * @param pBiDi is the paragraph <code>UBiDi</code> object.
1420  *
1421  * @param paraIndex is the number of the paragraph, in the
1422  *        range <code>[0..ubidi_countParagraphs(pBiDi)-1]</code>.
1423  *
1424  * @param pParaStart will receive the index of the first character of the
1425  *        paragraph in the text.
1426  *        This pointer can be <code>NULL</code> if this
1427  *        value is not necessary.
1428  *
1429  * @param pParaLimit will receive the limit of the paragraph.
1430  *        This pointer can be <code>NULL</code> if this
1431  *        value is not necessary.
1432  *
1433  * @param pParaLevel will receive the level of the paragraph.
1434  *        This pointer can be <code>NULL</code> if this
1435  *        value is not necessary.
1436  *
1437  * @param pErrorCode must be a valid pointer to an error code value.
1438  *
1439  * @stable ICU 3.4
1440  */
1441 U_STABLE void U_EXPORT2
1442 ubidi_getParagraphByIndex(const UBiDi *pBiDi, int32_t paraIndex,
1443                           int32_t *pParaStart, int32_t *pParaLimit,
1444                           UBiDiLevel *pParaLevel, UErrorCode *pErrorCode);
1445
1446 /**
1447  * Get the level for one character.
1448  *
1449  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1450  *
1451  * @param charIndex the index of a character. It must be in the range
1452  *         [0..ubidi_getProcessedLength(pBiDi)].
1453  *
1454  * @return The level for the character at charIndex (0 if charIndex is not
1455  *         in the valid range).
1456  *
1457  * @see UBiDiLevel
1458  * @see ubidi_getProcessedLength
1459  * @stable ICU 2.0
1460  */
1461 U_STABLE UBiDiLevel U_EXPORT2
1462 ubidi_getLevelAt(const UBiDi *pBiDi, int32_t charIndex);
1463
1464 /**
1465  * Get an array of levels for each character.<p>
1466  *
1467  * Note that this function may allocate memory under some
1468  * circumstances, unlike <code>ubidi_getLevelAt()</code>.
1469  *
1470  * @param pBiDi is the paragraph or line <code>UBiDi</code> object, whose
1471  *        text length must be strictly positive.
1472  *
1473  * @param pErrorCode must be a valid pointer to an error code value.
1474  *
1475  * @return The levels array for the text,
1476  *         or <code>NULL</code> if an error occurs.
1477  *
1478  * @see UBiDiLevel
1479  * @see ubidi_getProcessedLength
1480  * @stable ICU 2.0
1481  */
1482 U_STABLE const UBiDiLevel * U_EXPORT2
1483 ubidi_getLevels(UBiDi *pBiDi, UErrorCode *pErrorCode);
1484
1485 /**
1486  * Get a logical run.
1487  * This function returns information about a run and is used
1488  * to retrieve runs in logical order.<p>
1489  * This is especially useful for line-breaking on a paragraph.
1490  *
1491  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1492  *
1493  * @param logicalPosition is a logical position within the source text.
1494  *
1495  * @param pLogicalLimit will receive the limit of the corresponding run.
1496  *        The l-value that you point to here may be the
1497  *        same expression (variable) as the one for
1498  *        <code>logicalPosition</code>.
1499  *        This pointer can be <code>NULL</code> if this
1500  *        value is not necessary.
1501  *
1502  * @param pLevel will receive the level of the corresponding run.
1503  *        This pointer can be <code>NULL</code> if this
1504  *        value is not necessary.
1505  *
1506  * @see ubidi_getProcessedLength
1507  * @stable ICU 2.0
1508  */
1509 U_STABLE void U_EXPORT2
1510 ubidi_getLogicalRun(const UBiDi *pBiDi, int32_t logicalPosition,
1511                     int32_t *pLogicalLimit, UBiDiLevel *pLevel);
1512
1513 /**
1514  * Get the number of runs.
1515  * This function may invoke the actual reordering on the
1516  * <code>UBiDi</code> object, after <code>ubidi_setPara()</code>
1517  * may have resolved only the levels of the text. Therefore,
1518  * <code>ubidi_countRuns()</code> may have to allocate memory,
1519  * and may fail doing so.
1520  *
1521  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1522  *
1523  * @param pErrorCode must be a valid pointer to an error code value.
1524  *
1525  * @return The number of runs.
1526  * @stable ICU 2.0
1527  */
1528 U_STABLE int32_t U_EXPORT2
1529 ubidi_countRuns(UBiDi *pBiDi, UErrorCode *pErrorCode);
1530
1531 /**
1532  * Get one run's logical start, length, and directionality,
1533  * which can be 0 for LTR or 1 for RTL.
1534  * In an RTL run, the character at the logical start is
1535  * visually on the right of the displayed run.
1536  * The length is the number of characters in the run.<p>
1537  * <code>ubidi_countRuns()</code> should be called
1538  * before the runs are retrieved.
1539  *
1540  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1541  *
1542  * @param runIndex is the number of the run in visual order, in the
1543  *        range <code>[0..ubidi_countRuns(pBiDi)-1]</code>.
1544  *
1545  * @param pLogicalStart is the first logical character index in the text.
1546  *        The pointer may be <code>NULL</code> if this index is not needed.
1547  *
1548  * @param pLength is the number of characters (at least one) in the run.
1549  *        The pointer may be <code>NULL</code> if this is not needed.
1550  *
1551  * @return the directionality of the run,
1552  *         <code>UBIDI_LTR==0</code> or <code>UBIDI_RTL==1</code>,
1553  *         never <code>UBIDI_MIXED</code>,
1554  *         never <code>UBIDI_NEUTRAL</code>.
1555  *
1556  * @see ubidi_countRuns
1557  *
1558  * Example:
1559  * <pre>
1560  * \code
1561  * int32_t i, count=ubidi_countRuns(pBiDi),
1562  *         logicalStart, visualIndex=0, length;
1563  * for(i=0; i<count; ++i) {
1564  *    if(UBIDI_LTR==ubidi_getVisualRun(pBiDi, i, &logicalStart, &length)) {
1565  *         do { // LTR
1566  *             show_char(text[logicalStart++], visualIndex++);
1567  *         } while(--length>0);
1568  *     } else {
1569  *         logicalStart+=length;  // logicalLimit
1570  *         do { // RTL
1571  *             show_char(text[--logicalStart], visualIndex++);
1572  *         } while(--length>0);
1573  *     }
1574  * }
1575  *\endcode
1576  * </pre>
1577  *
1578  * Note that in right-to-left runs, code like this places
1579  * second surrogates before first ones (which is generally a bad idea)
1580  * and combining characters before base characters.
1581  * <p>
1582  * Use of <code>ubidi_writeReordered()</code>, optionally with the
1583  * <code>#UBIDI_KEEP_BASE_COMBINING</code> option, can be considered in order
1584  * to avoid these issues.
1585  * @stable ICU 2.0
1586  */
1587 U_STABLE UBiDiDirection U_EXPORT2
1588 ubidi_getVisualRun(UBiDi *pBiDi, int32_t runIndex,
1589                    int32_t *pLogicalStart, int32_t *pLength);
1590
1591 /**
1592  * Get the visual position from a logical text position.
1593  * If such a mapping is used many times on the same
1594  * <code>UBiDi</code> object, then calling
1595  * <code>ubidi_getLogicalMap()</code> is more efficient.<p>
1596  *
1597  * The value returned may be <code>#UBIDI_MAP_NOWHERE</code> if there is no
1598  * visual position because the corresponding text character is a Bidi control
1599  * removed from output by the option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code>.
1600  * <p>
1601  * When the visual output is altered by using options of
1602  * <code>ubidi_writeReordered()</code> such as <code>UBIDI_INSERT_LRM_FOR_NUMERIC</code>,
1603  * <code>UBIDI_KEEP_BASE_COMBINING</code>, <code>UBIDI_OUTPUT_REVERSE</code>,
1604  * <code>UBIDI_REMOVE_BIDI_CONTROLS</code>, the visual position returned may not
1605  * be correct. It is advised to use, when possible, reordering options
1606  * such as <code>UBIDI_OPTION_INSERT_MARKS</code> and <code>UBIDI_OPTION_REMOVE_CONTROLS</code>.
1607  * <p>
1608  * Note that in right-to-left runs, this mapping places
1609  * second surrogates before first ones (which is generally a bad idea)
1610  * and combining characters before base characters.
1611  * Use of <code>ubidi_writeReordered()</code>, optionally with the
1612  * <code>#UBIDI_KEEP_BASE_COMBINING</code> option can be considered instead
1613  * of using the mapping, in order to avoid these issues.
1614  *
1615  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1616  *
1617  * @param logicalIndex is the index of a character in the text.
1618  *
1619  * @param pErrorCode must be a valid pointer to an error code value.
1620  *
1621  * @return The visual position of this character.
1622  *
1623  * @see ubidi_getLogicalMap
1624  * @see ubidi_getLogicalIndex
1625  * @see ubidi_getProcessedLength
1626  * @stable ICU 2.0
1627  */
1628 U_STABLE int32_t U_EXPORT2
1629 ubidi_getVisualIndex(UBiDi *pBiDi, int32_t logicalIndex, UErrorCode *pErrorCode);
1630
1631 /**
1632  * Get the logical text position from a visual position.
1633  * If such a mapping is used many times on the same
1634  * <code>UBiDi</code> object, then calling
1635  * <code>ubidi_getVisualMap()</code> is more efficient.<p>
1636  *
1637  * The value returned may be <code>#UBIDI_MAP_NOWHERE</code> if there is no
1638  * logical position because the corresponding text character is a Bidi mark
1639  * inserted in the output by option <code>#UBIDI_OPTION_INSERT_MARKS</code>.
1640  * <p>
1641  * This is the inverse function to <code>ubidi_getVisualIndex()</code>.
1642  * <p>
1643  * When the visual output is altered by using options of
1644  * <code>ubidi_writeReordered()</code> such as <code>UBIDI_INSERT_LRM_FOR_NUMERIC</code>,
1645  * <code>UBIDI_KEEP_BASE_COMBINING</code>, <code>UBIDI_OUTPUT_REVERSE</code>,
1646  * <code>UBIDI_REMOVE_BIDI_CONTROLS</code>, the logical position returned may not
1647  * be correct. It is advised to use, when possible, reordering options
1648  * such as <code>UBIDI_OPTION_INSERT_MARKS</code> and <code>UBIDI_OPTION_REMOVE_CONTROLS</code>.
1649  *
1650  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1651  *
1652  * @param visualIndex is the visual position of a character.
1653  *
1654  * @param pErrorCode must be a valid pointer to an error code value.
1655  *
1656  * @return The index of this character in the text.
1657  *
1658  * @see ubidi_getVisualMap
1659  * @see ubidi_getVisualIndex
1660  * @see ubidi_getResultLength
1661  * @stable ICU 2.0
1662  */
1663 U_STABLE int32_t U_EXPORT2
1664 ubidi_getLogicalIndex(UBiDi *pBiDi, int32_t visualIndex, UErrorCode *pErrorCode);
1665
1666 /**
1667  * Get a logical-to-visual index map (array) for the characters in the UBiDi
1668  * (paragraph or line) object.
1669  * <p>
1670  * Some values in the map may be <code>#UBIDI_MAP_NOWHERE</code> if the
1671  * corresponding text characters are Bidi controls removed from the visual
1672  * output by the option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code>.
1673  * <p>
1674  * When the visual output is altered by using options of
1675  * <code>ubidi_writeReordered()</code> such as <code>UBIDI_INSERT_LRM_FOR_NUMERIC</code>,
1676  * <code>UBIDI_KEEP_BASE_COMBINING</code>, <code>UBIDI_OUTPUT_REVERSE</code>,
1677  * <code>UBIDI_REMOVE_BIDI_CONTROLS</code>, the visual positions returned may not
1678  * be correct. It is advised to use, when possible, reordering options
1679  * such as <code>UBIDI_OPTION_INSERT_MARKS</code> and <code>UBIDI_OPTION_REMOVE_CONTROLS</code>.
1680  * <p>
1681  * Note that in right-to-left runs, this mapping places
1682  * second surrogates before first ones (which is generally a bad idea)
1683  * and combining characters before base characters.
1684  * Use of <code>ubidi_writeReordered()</code>, optionally with the
1685  * <code>#UBIDI_KEEP_BASE_COMBINING</code> option can be considered instead
1686  * of using the mapping, in order to avoid these issues.
1687  *
1688  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1689  *
1690  * @param indexMap is a pointer to an array of <code>ubidi_getProcessedLength()</code>
1691  *        indexes which will reflect the reordering of the characters.
1692  *        If option <code>#UBIDI_OPTION_INSERT_MARKS</code> is set, the number
1693  *        of elements allocated in <code>indexMap</code> must be no less than
1694  *        <code>ubidi_getResultLength()</code>.
1695  *        The array does not need to be initialized.<br><br>
1696  *        The index map will result in <code>indexMap[logicalIndex]==visualIndex</code>.
1697  *
1698  * @param pErrorCode must be a valid pointer to an error code value.
1699  *
1700  * @see ubidi_getVisualMap
1701  * @see ubidi_getVisualIndex
1702  * @see ubidi_getProcessedLength
1703  * @see ubidi_getResultLength
1704  * @stable ICU 2.0
1705  */
1706 U_STABLE void U_EXPORT2
1707 ubidi_getLogicalMap(UBiDi *pBiDi, int32_t *indexMap, UErrorCode *pErrorCode);
1708
1709 /**
1710  * Get a visual-to-logical index map (array) for the characters in the UBiDi
1711  * (paragraph or line) object.
1712  * <p>
1713  * Some values in the map may be <code>#UBIDI_MAP_NOWHERE</code> if the
1714  * corresponding text characters are Bidi marks inserted in the visual output
1715  * by the option <code>#UBIDI_OPTION_INSERT_MARKS</code>.
1716  * <p>
1717  * When the visual output is altered by using options of
1718  * <code>ubidi_writeReordered()</code> such as <code>UBIDI_INSERT_LRM_FOR_NUMERIC</code>,
1719  * <code>UBIDI_KEEP_BASE_COMBINING</code>, <code>UBIDI_OUTPUT_REVERSE</code>,
1720  * <code>UBIDI_REMOVE_BIDI_CONTROLS</code>, the logical positions returned may not
1721  * be correct. It is advised to use, when possible, reordering options
1722  * such as <code>UBIDI_OPTION_INSERT_MARKS</code> and <code>UBIDI_OPTION_REMOVE_CONTROLS</code>.
1723  *
1724  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1725  *
1726  * @param indexMap is a pointer to an array of <code>ubidi_getResultLength()</code>
1727  *        indexes which will reflect the reordering of the characters.
1728  *        If option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code> is set, the number
1729  *        of elements allocated in <code>indexMap</code> must be no less than
1730  *        <code>ubidi_getProcessedLength()</code>.
1731  *        The array does not need to be initialized.<br><br>
1732  *        The index map will result in <code>indexMap[visualIndex]==logicalIndex</code>.
1733  *
1734  * @param pErrorCode must be a valid pointer to an error code value.
1735  *
1736  * @see ubidi_getLogicalMap
1737  * @see ubidi_getLogicalIndex
1738  * @see ubidi_getProcessedLength
1739  * @see ubidi_getResultLength
1740  * @stable ICU 2.0
1741  */
1742 U_STABLE void U_EXPORT2
1743 ubidi_getVisualMap(UBiDi *pBiDi, int32_t *indexMap, UErrorCode *pErrorCode);
1744
1745 /**
1746  * This is a convenience function that does not use a UBiDi object.
1747  * It is intended to be used for when an application has determined the levels
1748  * of objects (character sequences) and just needs to have them reordered (L2).
1749  * This is equivalent to using <code>ubidi_getLogicalMap()</code> on a
1750  * <code>UBiDi</code> object.
1751  *
1752  * @param levels is an array with <code>length</code> levels that have been determined by
1753  *        the application.
1754  *
1755  * @param length is the number of levels in the array, or, semantically,
1756  *        the number of objects to be reordered.
1757  *        It must be <code>length>0</code>.
1758  *
1759  * @param indexMap is a pointer to an array of <code>length</code>
1760  *        indexes which will reflect the reordering of the characters.
1761  *        The array does not need to be initialized.<p>
1762  *        The index map will result in <code>indexMap[logicalIndex]==visualIndex</code>.
1763  * @stable ICU 2.0
1764  */
1765 U_STABLE void U_EXPORT2
1766 ubidi_reorderLogical(const UBiDiLevel *levels, int32_t length, int32_t *indexMap);
1767
1768 /**
1769  * This is a convenience function that does not use a UBiDi object.
1770  * It is intended to be used for when an application has determined the levels
1771  * of objects (character sequences) and just needs to have them reordered (L2).
1772  * This is equivalent to using <code>ubidi_getVisualMap()</code> on a
1773  * <code>UBiDi</code> object.
1774  *
1775  * @param levels is an array with <code>length</code> levels that have been determined by
1776  *        the application.
1777  *
1778  * @param length is the number of levels in the array, or, semantically,
1779  *        the number of objects to be reordered.
1780  *        It must be <code>length>0</code>.
1781  *
1782  * @param indexMap is a pointer to an array of <code>length</code>
1783  *        indexes which will reflect the reordering of the characters.
1784  *        The array does not need to be initialized.<p>
1785  *        The index map will result in <code>indexMap[visualIndex]==logicalIndex</code>.
1786  * @stable ICU 2.0
1787  */
1788 U_STABLE void U_EXPORT2
1789 ubidi_reorderVisual(const UBiDiLevel *levels, int32_t length, int32_t *indexMap);
1790
1791 /**
1792  * Invert an index map.
1793  * The index mapping of the first map is inverted and written to
1794  * the second one.
1795  *
1796  * @param srcMap is an array with <code>length</code> elements
1797  *        which defines the original mapping from a source array containing
1798  *        <code>length</code> elements to a destination array.
1799  *        Some elements of the source array may have no mapping in the
1800  *        destination array. In that case, their value will be
1801  *        the special value <code>UBIDI_MAP_NOWHERE</code>.
1802  *        All elements must be >=0 or equal to <code>UBIDI_MAP_NOWHERE</code>.
1803  *        Some elements may have a value >= <code>length</code>, if the
1804  *        destination array has more elements than the source array.
1805  *        There must be no duplicate indexes (two or more elements with the
1806  *        same value except <code>UBIDI_MAP_NOWHERE</code>).
1807  *
1808  * @param destMap is an array with a number of elements equal to 1 + the highest
1809  *        value in <code>srcMap</code>.
1810  *        <code>destMap</code> will be filled with the inverse mapping.
1811  *        If element with index i in <code>srcMap</code> has a value k different
1812  *        from <code>UBIDI_MAP_NOWHERE</code>, this means that element i of
1813  *        the source array maps to element k in the destination array.
1814  *        The inverse map will have value i in its k-th element.
1815  *        For all elements of the destination array which do not map to
1816  *        an element in the source array, the corresponding element in the
1817  *        inverse map will have a value equal to <code>UBIDI_MAP_NOWHERE</code>.
1818  *
1819  * @param length is the length of each array.
1820  * @see UBIDI_MAP_NOWHERE
1821  * @stable ICU 2.0
1822  */
1823 U_STABLE void U_EXPORT2
1824 ubidi_invertMap(const int32_t *srcMap, int32_t *destMap, int32_t length);
1825
1826 /** option flags for ubidi_writeReordered() */
1827
1828 /**
1829  * option bit for ubidi_writeReordered():
1830  * keep combining characters after their base characters in RTL runs
1831  *
1832  * @see ubidi_writeReordered
1833  * @stable ICU 2.0
1834  */
1835 #define UBIDI_KEEP_BASE_COMBINING       1
1836
1837 /**
1838  * option bit for ubidi_writeReordered():
1839  * replace characters with the "mirrored" property in RTL runs
1840  * by their mirror-image mappings
1841  *
1842  * @see ubidi_writeReordered
1843  * @stable ICU 2.0
1844  */
1845 #define UBIDI_DO_MIRRORING              2
1846
1847 /**
1848  * option bit for ubidi_writeReordered():
1849  * surround the run with LRMs if necessary;
1850  * this is part of the approximate "inverse Bidi" algorithm
1851  *
1852  * <p>This option does not imply corresponding adjustment of the index
1853  * mappings.</p>
1854  *
1855  * @see ubidi_setInverse
1856  * @see ubidi_writeReordered
1857  * @stable ICU 2.0
1858  */
1859 #define UBIDI_INSERT_LRM_FOR_NUMERIC    4
1860
1861 /**
1862  * option bit for ubidi_writeReordered():
1863  * remove Bidi control characters
1864  * (this does not affect #UBIDI_INSERT_LRM_FOR_NUMERIC)
1865  *
1866  * <p>This option does not imply corresponding adjustment of the index
1867  * mappings.</p>
1868  *
1869  * @see ubidi_writeReordered
1870  * @stable ICU 2.0
1871  */
1872 #define UBIDI_REMOVE_BIDI_CONTROLS      8
1873
1874 /**
1875  * option bit for ubidi_writeReordered():
1876  * write the output in reverse order
1877  *
1878  * <p>This has the same effect as calling <code>ubidi_writeReordered()</code>
1879  * first without this option, and then calling
1880  * <code>ubidi_writeReverse()</code> without mirroring.
1881  * Doing this in the same step is faster and avoids a temporary buffer.
1882  * An example for using this option is output to a character terminal that
1883  * is designed for RTL scripts and stores text in reverse order.</p>
1884  *
1885  * @see ubidi_writeReordered
1886  * @stable ICU 2.0
1887  */
1888 #define UBIDI_OUTPUT_REVERSE            16
1889
1890 /**
1891  * Get the length of the source text processed by the last call to
1892  * <code>ubidi_setPara()</code>. This length may be different from the length
1893  * of the source text if option <code>#UBIDI_OPTION_STREAMING</code>
1894  * has been set.
1895  * <br>
1896  * Note that whenever the length of the text affects the execution or the
1897  * result of a function, it is the processed length which must be considered,
1898  * except for <code>ubidi_setPara</code> (which receives unprocessed source
1899  * text) and <code>ubidi_getLength</code> (which returns the original length
1900  * of the source text).<br>
1901  * In particular, the processed length is the one to consider in the following
1902  * cases:
1903  * <ul>
1904  * <li>maximum value of the <code>limit</code> argument of
1905  * <code>ubidi_setLine</code></li>
1906  * <li>maximum value of the <code>charIndex</code> argument of
1907  * <code>ubidi_getParagraph</code></li>
1908  * <li>maximum value of the <code>charIndex</code> argument of
1909  * <code>ubidi_getLevelAt</code></li>
1910  * <li>number of elements in the array returned by <code>ubidi_getLevels</code></li>
1911  * <li>maximum value of the <code>logicalStart</code> argument of
1912  * <code>ubidi_getLogicalRun</code></li>
1913  * <li>maximum value of the <code>logicalIndex</code> argument of
1914  * <code>ubidi_getVisualIndex</code></li>
1915  * <li>number of elements filled in the <code>*indexMap</code> argument of
1916  * <code>ubidi_getLogicalMap</code></li>
1917  * <li>length of text processed by <code>ubidi_writeReordered</code></li>
1918  * </ul>
1919  *
1920  * @param pBiDi is the paragraph <code>UBiDi</code> object.
1921  *
1922  * @return The length of the part of the source text processed by
1923  *         the last call to <code>ubidi_setPara</code>.
1924  * @see ubidi_setPara
1925  * @see UBIDI_OPTION_STREAMING
1926  * @stable ICU 3.6
1927  */
1928 U_STABLE int32_t U_EXPORT2
1929 ubidi_getProcessedLength(const UBiDi *pBiDi);
1930
1931 /**
1932  * Get the length of the reordered text resulting from the last call to
1933  * <code>ubidi_setPara()</code>. This length may be different from the length
1934  * of the source text if option <code>#UBIDI_OPTION_INSERT_MARKS</code>
1935  * or option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code> has been set.
1936  * <br>
1937  * This resulting length is the one to consider in the following cases:
1938  * <ul>
1939  * <li>maximum value of the <code>visualIndex</code> argument of
1940  * <code>ubidi_getLogicalIndex</code></li>
1941  * <li>number of elements of the <code>*indexMap</code> argument of
1942  * <code>ubidi_getVisualMap</code></li>
1943  * </ul>
1944  * Note that this length stays identical to the source text length if
1945  * Bidi marks are inserted or removed using option bits of
1946  * <code>ubidi_writeReordered</code>, or if option
1947  * <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code> has been set.
1948  *
1949  * @param pBiDi is the paragraph <code>UBiDi</code> object.
1950  *
1951  * @return The length of the reordered text resulting from
1952  *         the last call to <code>ubidi_setPara</code>.
1953  * @see ubidi_setPara
1954  * @see UBIDI_OPTION_INSERT_MARKS
1955  * @see UBIDI_OPTION_REMOVE_CONTROLS
1956  * @stable ICU 3.6
1957  */
1958 U_STABLE int32_t U_EXPORT2
1959 ubidi_getResultLength(const UBiDi *pBiDi);
1960
1961 U_CDECL_BEGIN
1962 /**
1963  * value returned by <code>UBiDiClassCallback</code> callbacks when
1964  * there is no need to override the standard Bidi class for a given code point.
1965  * @see UBiDiClassCallback
1966  * @stable ICU 3.6
1967  */
1968 #define U_BIDI_CLASS_DEFAULT  U_CHAR_DIRECTION_COUNT
1969
1970 /**
1971  * Callback type declaration for overriding default Bidi class values with
1972  * custom ones.
1973  * <p>Usually, the function pointer will be propagated to a <code>UBiDi</code>
1974  * object by calling the <code>ubidi_setClassCallback()</code> function;
1975  * then the callback will be invoked by the UBA implementation any time the
1976  * class of a character is to be determined.</p>
1977  *
1978  * @param context is a pointer to the callback private data.
1979  *
1980  * @param c       is the code point to get a Bidi class for.
1981  *
1982  * @return The directional property / Bidi class for the given code point
1983  *         <code>c</code> if the default class has been overridden, or
1984  *         <code>#U_BIDI_CLASS_DEFAULT</code> if the standard Bidi class value
1985  *         for <code>c</code> is to be used.
1986  * @see ubidi_setClassCallback
1987  * @see ubidi_getClassCallback
1988  * @stable ICU 3.6
1989  */
1990 typedef UCharDirection U_CALLCONV
1991 UBiDiClassCallback(const void *context, UChar32 c);
1992
1993 U_CDECL_END
1994
1995 /**
1996  * Retrieve the Bidi class for a given code point.
1997  * <p>If a <code>#UBiDiClassCallback</code> callback is defined and returns a
1998  * value other than <code>#U_BIDI_CLASS_DEFAULT</code>, that value is used;
1999  * otherwise the default class determination mechanism is invoked.</p>
2000  *
2001  * @param pBiDi is the paragraph <code>UBiDi</code> object.
2002  *
2003  * @param c     is the code point whose Bidi class must be retrieved.
2004  *
2005  * @return The Bidi class for character <code>c</code> based
2006  *         on the given <code>pBiDi</code> instance.
2007  * @see UBiDiClassCallback
2008  * @stable ICU 3.6
2009  */
2010 U_STABLE UCharDirection U_EXPORT2
2011 ubidi_getCustomizedClass(UBiDi *pBiDi, UChar32 c);
2012
2013 /**
2014  * Set the callback function and callback data used by the UBA
2015  * implementation for Bidi class determination.
2016  * <p>This may be useful for assigning Bidi classes to PUA characters, or
2017  * for special application needs. For instance, an application may want to
2018  * handle all spaces like L or R characters (according to the base direction)
2019  * when creating the visual ordering of logical lines which are part of a report
2020  * organized in columns: there should not be interaction between adjacent
2021  * cells.<p>
2022  *
2023  * @param pBiDi is the paragraph <code>UBiDi</code> object.
2024  *
2025  * @param newFn is the new callback function pointer.
2026  *
2027  * @param newContext is the new callback context pointer. This can be NULL.
2028  *
2029  * @param oldFn fillin: Returns the old callback function pointer. This can be
2030  *                      NULL.
2031  *
2032  * @param oldContext fillin: Returns the old callback's context. This can be
2033  *                           NULL.
2034  *
2035  * @param pErrorCode must be a valid pointer to an error code value.
2036  *
2037  * @see ubidi_getClassCallback
2038  * @stable ICU 3.6
2039  */
2040 U_STABLE void U_EXPORT2
2041 ubidi_setClassCallback(UBiDi *pBiDi, UBiDiClassCallback *newFn,
2042                        const void *newContext, UBiDiClassCallback **oldFn,
2043                        const void **oldContext, UErrorCode *pErrorCode);
2044
2045 /**
2046  * Get the current callback function used for Bidi class determination.
2047  *
2048  * @param pBiDi is the paragraph <code>UBiDi</code> object.
2049  *
2050  * @param fn fillin: Returns the callback function pointer.
2051  *
2052  * @param context fillin: Returns the callback's private context.
2053  *
2054  * @see ubidi_setClassCallback
2055  * @stable ICU 3.6
2056  */
2057 U_STABLE void U_EXPORT2
2058 ubidi_getClassCallback(UBiDi *pBiDi, UBiDiClassCallback **fn, const void **context);
2059
2060 /**
2061  * Take a <code>UBiDi</code> object containing the reordering
2062  * information for a piece of text (one or more paragraphs) set by
2063  * <code>ubidi_setPara()</code> or for a line of text set by
2064  * <code>ubidi_setLine()</code> and write a reordered string to the
2065  * destination buffer.
2066  *
2067  * This function preserves the integrity of characters with multiple
2068  * code units and (optionally) combining characters.
2069  * Characters in RTL runs can be replaced by mirror-image characters
2070  * in the destination buffer. Note that "real" mirroring has
2071  * to be done in a rendering engine by glyph selection
2072  * and that for many "mirrored" characters there are no
2073  * Unicode characters as mirror-image equivalents.
2074  * There are also options to insert or remove Bidi control
2075  * characters; see the description of the <code>destSize</code>
2076  * and <code>options</code> parameters and of the option bit flags.
2077  *
2078  * @param pBiDi A pointer to a <code>UBiDi</code> object that
2079  *              is set by <code>ubidi_setPara()</code> or
2080  *              <code>ubidi_setLine()</code> and contains the reordering
2081  *              information for the text that it was defined for,
2082  *              as well as a pointer to that text.<br><br>
2083  *              The text was aliased (only the pointer was stored
2084  *              without copying the contents) and must not have been modified
2085  *              since the <code>ubidi_setPara()</code> call.
2086  *
2087  * @param dest A pointer to where the reordered text is to be copied.
2088  *             The source text and <code>dest[destSize]</code>
2089  *             must not overlap.
2090  *
2091  * @param destSize The size of the <code>dest</code> buffer,
2092  *                 in number of UChars.
2093  *                 If the <code>UBIDI_INSERT_LRM_FOR_NUMERIC</code>
2094  *                 option is set, then the destination length could be
2095  *                 as large as
2096  *                 <code>ubidi_getLength(pBiDi)+2*ubidi_countRuns(pBiDi)</code>.
2097  *                 If the <code>UBIDI_REMOVE_BIDI_CONTROLS</code> option
2098  *                 is set, then the destination length may be less than
2099  *                 <code>ubidi_getLength(pBiDi)</code>.
2100  *                 If none of these options is set, then the destination length
2101  *                 will be exactly <code>ubidi_getProcessedLength(pBiDi)</code>.
2102  *
2103  * @param options A bit set of options for the reordering that control
2104  *                how the reordered text is written.
2105  *                The options include mirroring the characters on a code
2106  *                point basis and inserting LRM characters, which is used
2107  *                especially for transforming visually stored text
2108  *                to logically stored text (although this is still an
2109  *                imperfect implementation of an "inverse Bidi" algorithm
2110  *                because it uses the "forward Bidi" algorithm at its core).
2111  *                The available options are:
2112  *                <code>#UBIDI_DO_MIRRORING</code>,
2113  *                <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code>,
2114  *                <code>#UBIDI_KEEP_BASE_COMBINING</code>,
2115  *                <code>#UBIDI_OUTPUT_REVERSE</code>,
2116  *                <code>#UBIDI_REMOVE_BIDI_CONTROLS</code>
2117  *
2118  * @param pErrorCode must be a valid pointer to an error code value.
2119  *
2120  * @return The length of the output string.
2121  *
2122  * @see ubidi_getProcessedLength
2123  * @stable ICU 2.0
2124  */
2125 U_STABLE int32_t U_EXPORT2
2126 ubidi_writeReordered(UBiDi *pBiDi,
2127                      UChar *dest, int32_t destSize,
2128                      uint16_t options,
2129                      UErrorCode *pErrorCode);
2130
2131 /**
2132  * Reverse a Right-To-Left run of Unicode text.
2133  *
2134  * This function preserves the integrity of characters with multiple
2135  * code units and (optionally) combining characters.
2136  * Characters can be replaced by mirror-image characters
2137  * in the destination buffer. Note that "real" mirroring has
2138  * to be done in a rendering engine by glyph selection
2139  * and that for many "mirrored" characters there are no
2140  * Unicode characters as mirror-image equivalents.
2141  * There are also options to insert or remove Bidi control
2142  * characters.
2143  *
2144  * This function is the implementation for reversing RTL runs as part
2145  * of <code>ubidi_writeReordered()</code>. For detailed descriptions
2146  * of the parameters, see there.
2147  * Since no Bidi controls are inserted here, the output string length
2148  * will never exceed <code>srcLength</code>.
2149  *
2150  * @see ubidi_writeReordered
2151  *
2152  * @param src A pointer to the RTL run text.
2153  *
2154  * @param srcLength The length of the RTL run.
2155  *
2156  * @param dest A pointer to where the reordered text is to be copied.
2157  *             <code>src[srcLength]</code> and <code>dest[destSize]</code>
2158  *             must not overlap.
2159  *
2160  * @param destSize The size of the <code>dest</code> buffer,
2161  *                 in number of UChars.
2162  *                 If the <code>UBIDI_REMOVE_BIDI_CONTROLS</code> option
2163  *                 is set, then the destination length may be less than
2164  *                 <code>srcLength</code>.
2165  *                 If this option is not set, then the destination length
2166  *                 will be exactly <code>srcLength</code>.
2167  *
2168  * @param options A bit set of options for the reordering that control
2169  *                how the reordered text is written.
2170  *                See the <code>options</code> parameter in <code>ubidi_writeReordered()</code>.
2171  *
2172  * @param pErrorCode must be a valid pointer to an error code value.
2173  *
2174  * @return The length of the output string.
2175  * @stable ICU 2.0
2176  */
2177 U_STABLE int32_t U_EXPORT2
2178 ubidi_writeReverse(const UChar *src, int32_t srcLength,
2179                    UChar *dest, int32_t destSize,
2180                    uint16_t options,
2181                    UErrorCode *pErrorCode);
2182
2183 /*#define BIDI_SAMPLE_CODE*/
2184 /*@}*/
2185
2186 #endif