icuSources/common/unicode/ubidi.h

   1 /*
   2 ******************************************************************************
   3 *
   4 *   Copyright (C) 1999-2006, 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
  15 */
  16
  17 #ifndef UBIDI_H
  18 #define UBIDI_H
  19
  20 #include "unicode/utypes.h"
  21 #include "unicode/uchar.h"
  22
  23 /**
  24  *\file
  25  * \brief C API: BIDI algorithm
  26  *
  27  * <h2>BIDI algorithm for ICU</h2>
  28  *
  29  * This is an implementation of the Unicode Bidirectional algorithm.
  30  * The algorithm is defined in the
  31  * <a href="http://www.unicode.org/unicode/reports/tr9/">Unicode Standard Annex #9</a>,
  32  * version 13, also described in The Unicode Standard, Version 4.0 .<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.
 333  *  If there is no strong character, then set the paragraph level to 0 (left-to-right).
 334  * @stable ICU 2.0
 335  */
 336 #define UBIDI_DEFAULT_LTR 0xfe
 337
 338 /** Paragraph level setting.
 339  *  If there is no strong character, then set the paragraph level to 1 (right-to-left).
 340  * @stable ICU 2.0
 341  */
 342 #define UBIDI_DEFAULT_RTL 0xff
 343
 344 /**
 345  * Maximum explicit embedding level.
 346  * (The maximum resolved level can be up to <code>UBIDI_MAX_EXPLICIT_LEVEL+1</code>).
 347  * @stable ICU 2.0
 348  */
 349 #define UBIDI_MAX_EXPLICIT_LEVEL 61
 350
 351 /** Bit flag for level input.
 352  *  Overrides directional properties.
 353  * @stable ICU 2.0
 354  */
 355 #define UBIDI_LEVEL_OVERRIDE 0x80
 356
 357 /**
 358  * Special value which can be returned by the mapping functions when a logical
 359  * index has no corresponding visual index or vice-versa. This may happen
 360  * for the logical-to-visual mapping of a BiDi control when option
 361  * <code>#UBIDI_OPTION_REMOVE_CONTROLS</code> is specified. This can also happen
 362  * for the visual-to-logical mapping of a BiDi mark (LRM or RLM) inserted
 363  * by option <code>#UBIDI_OPTION_INSERT_MARKS</code>.
 364  * @see ubidi_getVisualIndex
 365  * @see ubidi_getVisualMap
 366  * @see ubidi_getLogicalIndex
 367  * @see ubidi_getLogicalMap
 368  * @draft ICU 3.6
 369  */
 370 #define UBIDI_MAP_NOWHERE   (-1)
 371
 372 /**
 373  * <code>UBiDiDirection</code> values indicate the text direction.
 374  * @stable ICU 2.0
 375  */
 376 enum UBiDiDirection {
 377     /** All left-to-right text. This is a 0 value. @stable ICU 2.0 */
 378     UBIDI_LTR,
 379     /** All right-to-left text. This is a 1 value. @stable ICU 2.0 */
 380     UBIDI_RTL,
 381     /** Mixed-directional text. @stable ICU 2.0 */
 382     UBIDI_MIXED
 383 };
 384
 385 /** @stable ICU 2.0 */
 386 typedef enum UBiDiDirection UBiDiDirection;
 387
 388 /**
 389  * Forward declaration of the <code>UBiDi</code> structure for the declaration of
 390  * the API functions. Its fields are implementation-specific.<p>
 391  * This structure holds information about a paragraph (or multiple paragraphs)
 392  * of text with BiDi-algorithm-related details, or about one line of
 393  * such a paragraph.<p>
 394  * Reordering can be done on a line, or on one or more paragraphs which are
 395  * then interpreted each as one single line.
 396  * @stable ICU 2.0
 397  */
 398 struct UBiDi;
 399
 400 /** @stable ICU 2.0 */
 401 typedef struct UBiDi UBiDi;
 402
 403 /**
 404  * Allocate a <code>UBiDi</code> structure.
 405  * Such an object is initially empty. It is assigned
 406  * the BiDi properties of a piece of text containing one or more paragraphs
 407  * by <code>ubidi_setPara()</code>
 408  * or the BiDi properties of a line within a paragraph by
 409  * <code>ubidi_setLine()</code>.<p>
 410  * This object can be reused for as long as it is not deallocated
 411  * by calling <code>ubidi_close()</code>.<p>
 412  * <code>ubidi_setPara()</code> and <code>ubidi_setLine()</code> will allocate
 413  * additional memory for internal structures as necessary.
 414  *
 415  * @return An empty <code>UBiDi</code> object.
 416  * @stable ICU 2.0
 417  */
 418 U_STABLE UBiDi * U_EXPORT2
 419 ubidi_open(void);
 420
 421 /**
 422  * Allocate a <code>UBiDi</code> structure with preallocated memory
 423  * for internal structures.
 424  * This function provides a <code>UBiDi</code> object like <code>ubidi_open()</code>
 425  * with no arguments, but it also preallocates memory for internal structures
 426  * according to the sizings supplied by the caller.<p>
 427  * Subsequent functions will not allocate any more memory, and are thus
 428  * guaranteed not to fail because of lack of memory.<p>
 429  * The preallocation can be limited to some of the internal memory
 430  * by setting some values to 0 here. That means that if, e.g.,
 431  * <code>maxRunCount</code> cannot be reasonably predetermined and should not
 432  * be set to <code>maxLength</code> (the only failproof value) to avoid
 433  * wasting memory, then <code>maxRunCount</code> could be set to 0 here
 434  * and the internal structures that are associated with it will be allocated
 435  * on demand, just like with <code>ubidi_open()</code>.
 436  *
 437  * @param maxLength is the maximum text or line length that internal memory
 438  *        will be preallocated for. An attempt to associate this object with a
 439  *        longer text will fail, unless this value is 0, which leaves the allocation
 440  *        up to the implementation.
 441  *
 442  * @param maxRunCount is the maximum anticipated number of same-level runs
 443  *        that internal memory will be preallocated for. An attempt to access
 444  *        visual runs on an object that was not preallocated for as many runs
 445  *        as the text was actually resolved to will fail,
 446  *        unless this value is 0, which leaves the allocation up to the implementation.<br><br>
 447  *        The number of runs depends on the actual text and maybe anywhere between
 448  *        1 and <code>maxLength</code>. It is typically small.
 449  *
 450  * @param pErrorCode must be a valid pointer to an error code value.
 451  *
 452  * @return An empty <code>UBiDi</code> object with preallocated memory.
 453  * @stable ICU 2.0
 454  */
 455 U_STABLE UBiDi * U_EXPORT2
 456 ubidi_openSized(int32_t maxLength, int32_t maxRunCount, UErrorCode *pErrorCode);
 457
 458 /**
 459  * <code>ubidi_close()</code> must be called to free the memory
 460  * associated with a UBiDi object.<p>
 461  *
 462  * <strong>Important: </strong>
 463  * A parent <code>UBiDi</code> object must not be destroyed or reused if
 464  * it still has children.
 465  * If a <code>UBiDi</code> object has become the <i>child</i>
 466  * of another one (its <i>parent</i>) by calling
 467  * <code>ubidi_setLine()</code>, then the child object must
 468  * be destroyed (closed) or reused (by calling
 469  * <code>ubidi_setPara()</code> or <code>ubidi_setLine()</code>)
 470  * before the parent object.
 471  *
 472  * @param pBiDi is a <code>UBiDi</code> object.
 473  *
 474  * @see ubidi_setPara
 475  * @see ubidi_setLine
 476  * @stable ICU 2.0
 477  */
 478 U_STABLE void U_EXPORT2
 479 ubidi_close(UBiDi *pBiDi);
 480
 481 /**
 482  * Modify the operation of the BiDi algorithm such that it
 483  * approximates an "inverse BiDi" algorithm. This function
 484  * must be called before <code>ubidi_setPara()</code>.
 485  *
 486  * <p>The normal operation of the BiDi algorithm as described
 487  * in the Unicode Technical Report is to take text stored in logical
 488  * (keyboard, typing) order and to determine the reordering of it for visual
 489  * rendering.
 490  * Some legacy systems store text in visual order, and for operations
 491  * with standard, Unicode-based algorithms, the text needs to be transformed
 492  * to logical order. This is effectively the inverse algorithm of the
 493  * described BiDi algorithm. Note that there is no standard algorithm for
 494  * this "inverse BiDi" and that the current implementation provides only an
 495  * approximation of "inverse BiDi".</p>
 496  *
 497  * <p>With <code>isInverse</code> set to <code>TRUE</code>,
 498  * this function changes the behavior of some of the subsequent functions
 499  * in a way that they can be used for the inverse BiDi algorithm.
 500  * Specifically, runs of text with numeric characters will be treated in a
 501  * special way and may need to be surrounded with LRM characters when they are
 502  * written in reordered sequence.</p>
 503  *
 504  * <p>Output runs should be retrieved using <code>ubidi_getVisualRun()</code>.
 505  * Since the actual input for "inverse BiDi" is visually ordered text and
 506  * <code>ubidi_getVisualRun()</code> gets the reordered runs, these are actually
 507  * the runs of the logically ordered output.</p>
 508  *
 509  * <p>Calling this function with argument <code>isInverse</code> set to
 510  * <code>TRUE</code> is equivalent to calling
 511  * <code>ubidi_setReorderingMode</code> with argument
 512  * <code>reorderingMode</code>
 513  * set to <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>.<br>
 514  * Calling this function with argument <code>isInverse</code> set to
 515  * <code>FALSE</code> is equivalent to calling
 516  * <code>ubidi_setReorderingMode</code> with argument
 517  * <code>reorderingMode</code>
 518  * set to <code>#UBIDI_REORDER_DEFAULT</code>.
 519  *
 520  * @param pBiDi is a <code>UBiDi</code> object.
 521  *
 522  * @param isInverse specifies "forward" or "inverse" BiDi operation.
 523  *
 524  * @see ubidi_setPara
 525  * @see ubidi_writeReordered
 526  * @see ubidi_setReorderingMode
 527  * @stable ICU 2.0
 528  */
 529 U_STABLE void U_EXPORT2
 530 ubidi_setInverse(UBiDi *pBiDi, UBool isInverse);
 531
 532 /**
 533  * Is this BiDi object set to perform the inverse BiDi algorithm?
 534  * <p>Note: calling this function after setting the reordering mode with
 535  * <code>ubidi_setReorderingMode</code> will return <code>TRUE</code> if the
 536  * reordering mode was set to <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>,
 537  * <code>FALSE</code> for all other values.</p>
 538  *
 539  * @param pBiDi is a <code>UBiDi</code> object.
 540  * @return TRUE if the BiDi object is set to perform the inverse BiDi algorithm
 541  * by handling numbers as L.
 542  *
 543  * @see ubidi_setInverse
 544  * @see ubidi_setReorderingMode
 545  * @stable ICU 2.0
 546  */
 547
 548 U_STABLE UBool U_EXPORT2
 549 ubidi_isInverse(UBiDi *pBiDi);
 550
 551 /**
 552  * Specify whether block separators must be allocated level zero,
 553  * so that successive paragraphs will progress from left to right.
 554  * This function must be called before <code>ubidi_setPara()</code>.
 555  * Paragraph separators (B) may appear in the text.  Setting them to level zero
 556  * means that all paragraph separators (including one possibly appearing
 557  * in the last text position) are kept in the reordered text after the text
 558  * that they follow in the source text.
 559  * When this feature is not enabled, a paragraph separator at the last
 560  * position of the text before reordering will go to the first position
 561  * of the reordered text when the paragraph level is odd.
 562  *
 563  * @param pBiDi is a <code>UBiDi</code> object.
 564  *
 565  * @param orderParagraphsLTR specifies whether paragraph separators (B) must
 566  * receive level 0, so that successive paragraphs progress from left to right.
 567  *
 568  * @see ubidi_setPara
 569  * @stable ICU 3.4
 570  */
 571 U_STABLE void U_EXPORT2
 572 ubidi_orderParagraphsLTR(UBiDi *pBiDi, UBool orderParagraphsLTR);
 573
 574 /**
 575  * Is this BiDi object set to allocate level 0 to block separators so that
 576  * successive paragraphs progress from left to right?
 577  *
 578  * @param pBiDi is a <code>UBiDi</code> object.
 579  * @return TRUE if the BiDi object is set to allocate level 0 to block
 580  *         separators.
 581  *
 582  * @see ubidi_orderParagraphsLTR
 583  * @stable ICU 3.4
 584  */
 585 U_STABLE UBool U_EXPORT2
 586 ubidi_isOrderParagraphsLTR(UBiDi *pBiDi);
 587
 588 /**
 589  * <code>UBiDiReorderingMode</code> values indicate which variant of the BiDi
 590  * algorithm to use.
 591  *
 592  * @see ubidi_setReorderingMode
 593  * @draft ICU 3.6
 594  */
 595 typedef enum UBiDiReorderingMode {
 596     /** Regular Logical to Visual BiDi algorithm according to Unicode.
 597       * This is a 0 value. @draft ICU 3.6 */
 598     UBIDI_REORDER_DEFAULT = 0,
 599     /** Logical to Visual algorithm which handles numbers in a way which
 600       * mimicks the behavior of Windows XP.
 601       * @draft ICU 3.6 */
 602     UBIDI_REORDER_NUMBERS_SPECIAL,
 603     /** Logical to Visual algorithm grouping numbers with adjacent R characters
 604       * (reversible algorithm).
 605       * @draft ICU 3.6 */
 606     UBIDI_REORDER_GROUP_NUMBERS_WITH_R,
 607     /** Reorder runs only to transform a Logical LTR string to the Logical RTL
 608       * string with the same display, or vice-versa.<br>
 609       * If this mode is set together with option
 610       * <code>#UBIDI_OPTION_INSERT_MARKS</code>, some BiDi controls in the source
 611       * text may be removed and other controls may be added to produce the
 612       * minimum combination which has the required display.
 613       * @draft ICU 3.6 */
 614     UBIDI_REORDER_RUNS_ONLY,
 615     /** Visual to Logical algorithm which handles numbers like L
 616       * (same algorithm as selected by <code>ubidi_setInverse(TRUE)</code>.
 617       * @see ubidi_setInverse
 618       * @draft ICU 3.6 */
 619     UBIDI_REORDER_INVERSE_NUMBERS_AS_L,
 620     /** Visual to Logical algorithm equivalent to the regular Logical to Visual
 621       * algorithm. @draft ICU 3.6 */
 622     UBIDI_REORDER_INVERSE_LIKE_DIRECT,
 623     /** Inverse BiDi (Visual to Logical) algorithm for the
 624       * <code>UBIDI_REORDER_NUMBERS_SPECIAL</code> BiDi algorithm.
 625       * @draft ICU 3.6 */
 626     UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL,
 627     /** Number of values for reordering mode.
 628       * @draft ICU 3.6 */
 629     UBIDI_REORDER_COUNT
 630 } UBiDiReorderingMode;
 631
 632 /**
 633  * Modify the operation of the BiDi algorithm such that it implements some
 634  * variant to the basic BiDi algorithm or approximates an "inverse BiDi"
 635  * algorithm, depending on different values of the "reordering mode".
 636  * This function must be called before <code>ubidi_setPara()</code>, and stays
 637  * in effect until called again with a different argument.
 638  *
 639  * <p>The normal operation of the BiDi algorithm as described
 640  * in the Unicode Standard Annex #9 is to take text stored in logical
 641  * (keyboard, typing) order and to determine how to reorder it for visual
 642  * rendering.</p>
 643  *
 644  * <p>With the reordering mode set to a value other than
 645  * <code>#UBIDI_REORDER_DEFAULT</code>, this function changes the behavior of
 646  * some of the subsequent functions in a way such that they implement an
 647  * inverse BiDi algorithm or some other algorithm variants.</p>
 648  *
 649  * <p>Some legacy systems store text in visual order, and for operations
 650  * with standard, Unicode-based algorithms, the text needs to be transformed
 651  * into logical order. This is effectively the inverse algorithm of the
 652  * described BiDi algorithm. Note that there is no standard algorithm for
 653  * this "inverse BiDi", so a number of variants are implemented here.</p>
 654  *
 655  * <p>In other cases, it may be desirable to emulate some variant of the
 656  * Logical to Visual algorithm (e.g. one used in MS Windows), or perform a
 657  * Logical to Logical transformation.</p>
 658  *
 659  * <ul>
 660  * <li>When the reordering mode is set to <code>#UBIDI_REORDER_DEFAULT</code>,
 661  * the standard BiDi Logical to Visual algorithm is applied.</li>
 662  *
 663  * <li>When the reordering mode is set to
 664  * <code>#UBIDI_REORDER_NUMBERS_SPECIAL</code>,
 665  * the algorithm used to perform BiDi transformations when calling
 666  * <code>ubidi_setPara</code> should approximate the algorithm used in
 667  * Microsoft Windows XP rather than strictly conform to the Unicode BiDi
 668  * algorithm.
 669  * <br>
 670  * The differences between the basic algorithm and the algorithm addressed
 671  * by this option are as follows:
 672  * <ul>
 673  *   <li>Within text at an even embedding level, the sequence "123AB"
 674  *   (where AB represent R or AL letters) is transformed to "123BA" by the
 675  *   Unicode algorithm and to "BA123" by the Windows algorithm.</li>
 676  *   <li>Arabic-Indic numbers (AN) are handled by the Windows algorithm just
 677  *   like regular numbers (EN).</li>
 678  * </ul></li>
 679  *
 680  * <li>When the reordering mode is set to
 681  * <code>#UBIDI_REORDER_GROUP_NUMBERS_WITH_R</code>,
 682  * numbers located between LTR text and RTL text are associated with the RTL
 683  * text. For instance, an LTR paragraph with content "abc 123 DEF" (where
 684  * upper case letters represent RTL characters) will be transformed to
 685  * "abc FED 123" (and not "abc 123 FED"), "DEF 123 abc" will be transformed
 686  * to "123 FED abc" and "123 FED abc" will be transformed to "DEF 123 abc".
 687  * This makes the algorithm reversible and makes it useful when round trip
 688  * (from visual to logical and back to visual) must be achieved without
 689  * adding LRM characters. However, this is a variation from the standard
 690  * Unicode Bidi algorithm.<br>
 691  * The source text should not contain BiDi control characters other than LRM
 692  * or RLM.</li>
 693  *
 694  * <li>When the reordering mode is set to
 695  * <code>#UBIDI_REORDER_RUNS_ONLY</code>,
 696  * a "Logical to Logical" transformation must be performed:
 697  * <ul>
 698  * <li>If the default text level of the source text (argument <code>paraLevel</code>
 699  * in <code>ubidi_setPara</code>) is even, the source text will be handled as
 700  * LTR logical text and will be transformed to the RTL logical text which has
 701  * the same LTR visual display.</li>
 702  * <li>If the default level of the source text is odd, the source text
 703  * will be handled as RTL logical text and will be transformed to the
 704  * LTR logical text which has the same LTR visual display.</li>
 705  * </ul>
 706  * This mode may be needed when logical text which is basically Arabic or
 707  * Hebrew, with possible included numbers or phrases in English, has to be
 708  * displayed as if it had an even embedding level (this can happen if the
 709  * displaying application treats all text as if it was basically LTR.
 710  * <br>
 711  * This mode may also be needed in the reverse case, when logical text which is
 712  * basically English, with possible included phrases in Arabic or Hebrew, has to
 713  * be displayed as if it had an odd embedding level.
 714  * <br>
 715  * Both cases could be handled by adding LRE or RLE at the head of the text,
 716  * if the display subsystem supports these formatting controls. If it does not,
 717  * the problem may be handled by transforming the source text in this mode
 718  * before displaying it, so that it will be displayed properly.<br>
 719  * The source text should not contain BiDi control characters other than LRM
 720  * or RLM.</li>
 721  *
 722  * <li>When the reordering mode is set to
 723  * <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>, an "inverse BiDi" algorithm
 724  * is applied.
 725  * Runs of text with numeric characters will be treated like LTR letters and
 726  * may need to be surrounded with LRM characters when they are written in
 727  * reordered sequence (the option <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code> can
 728  * be used with function <code>ubidi_writeReordered</code> to this end. This
 729  * mode is equivalent to calling <code>ubidi_setInverse()</code> with
 730  * argument <code>isInverse</code> set to <code>TRUE</code>.</li>
 731  *
 732  * <li>When the reordering mode is set to
 733  * <code>#UBIDI_REORDER_INVERSE_LIKE_DIRECT</code>, the "direct" Logical to Visual
 734  * BiDi algorithm is used as an approximation of an "inverse BiDi" algorithm.
 735  * This mode is similar to mode <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>
 736  * but is closer to the regular BiDi algorithm.
 737  * <br>
 738  * For example, an LTR paragraph with the content "FED 123 456 CBA" (where
 739  * upper case represents RTL characters) will be transformed to
 740  * "ABC 456 123 DEF", as opposed to "DEF 123 456 ABC"
 741  * with mode <code>UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>.<br>
 742  * When used in conjunction with option
 743  * <code>#UBIDI_OPTION_INSERT_MARKS</code>, this mode generally
 744  * adds BiDi marks to the output significantly more sparingly than mode
 745  * <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code> with option
 746  * <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code> in calls to
 747  * <code>ubidi_writeReordered</code>.</li>
 748  *
 749  * <li>When the reordering mode is set to
 750  * <code>#UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL</code>, the Logical to Visual
 751  * BiDi algorithm used in Windows XP is used as an approximation of an
 752  * "inverse BiDi" algorithm.
 753  * <br>
 754  * For example, an LTR paragraph with the content "abc FED123" (where
 755  * upper case represents RTL characters) will be transformed to
 756  * "abc 123DEF.</li>
 757  * </ul>
 758  *
 759  * <p>In all the reordering modes specifying an "inverse BiDi" algorithm
 760  * (i.e. those with a name starting with <code>UBIDI_REORDER_INVERSE</code>),
 761  * output runs should be retrieved using
 762  * <code>ubidi_getVisualRun()</code>, and the output text with
 763  * <code>ubidi_writeReordered()</code>. The caller should keep in mind that in
 764  * "inverse BiDi" modes the input is actually visually ordered text and
 765  * reordered output returned by <code>ubidi_getVisualRun()</code> or
 766  * <code>ubidi_writeReordered()</code> are actually runs or character string
 767  * of logically ordered output.<br>
 768  * For all the "inverse BiDi" modes, the source text should not contain
 769  * BiDi control characters other than LRM or RLM.</p>
 770  *
 771  * <p>Note that option <code>#UBIDI_OUTPUT_REVERSE</code> of
 772  * <code>ubidi_writeReordered</code> has no useful meaning and should not be
 773  * used in conjunction with any value of the reordering mode specifying
 774  * "inverse BiDi" or with value <code>UBIDI_REORDER_RUNS_ONLY</code>.
 775  *
 776  * @param pBiDi is a <code>UBiDi</code> object.
 777  * @param reorderingMode specifies the required variant of the BiDi algorithm.
 778  *
 779  * @see UBiDiReorderingMode
 780  * @see ubidi_setInverse
 781  * @see ubidi_setPara
 782  * @see ubidi_writeReordered
 783  * @draft ICU 3.6
 784  */
 785 U_DRAFT void U_EXPORT2
 786 ubidi_setReorderingMode(UBiDi *pBiDi, UBiDiReorderingMode reorderingMode);
 787
 788 /**
 789  * What is the requested reordering mode for a given BiDi object?
 790  *
 791  * @param pBiDi is a <code>UBiDi</code> object.
 792  * @return the current reordering mode of the BiDi object
 793  * @see ubidi_setReorderingMode
 794  * @draft ICU 3.6
 795  */
 796 U_DRAFT UBiDiReorderingMode U_EXPORT2
 797 ubidi_getReorderingMode(UBiDi *pBiDi);
 798
 799 /**
 800  * <code>UBiDiReorderingOption</code> values indicate which options are
 801  * specified to affect the BiDi algorithm.
 802  *
 803  * @see ubidi_setReorderingOptions
 804  * @draft ICU 3.6
 805  */
 806 typedef enum UBiDiReorderingOption {
 807     /**
 808      * option value for <code>ubidi_setReorderingOptions</code>:
 809      * disable all the options which can be set with this function
 810      * @see ubidi_setReorderingOptions
 811      * @draft ICU 3.6
 812      */
 813     UBIDI_OPTION_DEFAULT = 0,
 814
 815     /**
 816      * option bit for <code>ubidi_setReorderingOptions</code>:
 817      * insert BiDi marks (LRM or RLM) when needed to ensure correct result of
 818      * a reordering to a Logical order
 819      *
 820      * <p>This option must be set or reset before calling
 821      * <code>ubidi_setPara</code>.</p>
 822      *
 823      * <p>This option is significant only with reordering modes which generate
 824      * a result with Logical order, specifically:</p>
 825      * <ul>
 826      *   <li><code>#UBIDI_REORDER_RUNS_ONLY</code></li>
 827      *   <li><code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code></li>
 828      *   <li><code>#UBIDI_REORDER_INVERSE_LIKE_DIRECT</code></li>
 829      *   <li><code>#UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL</code></li>
 830      * </ul>
 831      *
 832      * <p>If this option is set in conjunction with reordering mode
 833      * <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code> or with calling
 834      * <code>ubidi_setInverse(TRUE)</code>, it implies
 835      * option <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code>
 836      * in calls to function <code>ubidi_writeReordered()</code>.</p>
 837      *
 838      * <p>For other reordering modes, a minimum number of LRM or RLM characters
 839      * will be added to the source text after reordering it so as to ensure
 840      * round trip, i.e. when applying the inverse reordering mode on the
 841      * resulting logical text with removal of BiDi marks
 842      * (option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code> set before calling
 843      * <code>ubidi_setPara()</code> or option <code>#UBIDI_REMOVE_BIDI_CONTROLS</code>
 844      * in <code>ubidi_writeReordered</code>), the result will be identical to the
 845      * source text in the first transformation.
 846      *
 847      * <p>This option will be ignored if specified together with option
 848      * <code>#UBIDI_OPTION_REMOVE_CONTROLS</code>. It inhibits option
 849      * <code>UBIDI_REMOVE_BIDI_CONTROLS</code> in calls to function
 850      * <code>ubidi_writeReordered()</code> and it implies option
 851      * <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code> in calls to function
 852      * <code>ubidi_writeReordered()</code> if the reordering mode is
 853      * <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>.</p>
 854      *
 855      * @see ubidi_setReorderingMode
 856      * @see ubidi_setReorderingOptions
 857      * @draft ICU 3.6
 858      */
 859     UBIDI_OPTION_INSERT_MARKS = 1,
 860
 861     /**
 862      * option bit for <code>ubidi_setReorderingOptions</code>:
 863      * remove BiDi control characters
 864      *
 865      * <p>This option must be set or reset before calling
 866      * <code>ubidi_setPara</code>.</p>
 867      *
 868      * <p>This option nullifies option <code>#UBIDI_OPTION_INSERT_MARKS</code>.
 869      * It inhibits option <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code> in calls
 870      * to function <code>ubidi_writeReordered()</code> and it implies option
 871      * <code>#UBIDI_REMOVE_BIDI_CONTROLS</code> in calls to that function.</p>
 872      *
 873      * @see ubidi_setReorderingMode
 874      * @see ubidi_setReorderingOptions
 875      * @draft ICU 3.6
 876      */
 877     UBIDI_OPTION_REMOVE_CONTROLS = 2,
 878
 879     /**
 880      * option bit for <code>ubidi_setReorderingOptions</code>:
 881      * process the output as part of a stream to be continued
 882      *
 883      * <p>This option must be set or reset before calling
 884      * <code>ubidi_setPara</code>.</p>
 885      *
 886      * <p>This option specifies that the caller is interested in processing large
 887      * text object in parts.
 888      * The results of the successive calls are expected to be concatenated by the
 889      * caller. Only the call for the last part will have this option bit off.</p>
 890      *
 891      * <p>When this option bit is on, <code>ubidi_setPara()</code> may process
 892      * less than the full source text in order to truncate the text at a meaningful
 893      * boundary. The caller should call <code>ubidi_getProcessedLength()</code>
 894      * immediately after calling <code>ubidi_setPara()</code> in order to
 895      * determine how much of the source text has been processed.
 896      * Source text beyond that length should be resubmitted in following calls to
 897      * <code>ubidi_setPara</code>. The processed length may be less than
 898      * the length of the source text if a character preceding the last character of
 899      * the source text constitutes a reasonable boundary (like a block separator)
 900      * for text to be continued.<br>
 901      * If the last character of the source text constitutes a reasonable
 902      * boundary, the whole text will be processed at once.<br>
 903      * If nowhere in the source text there exists
 904      * such a reasonable boundary, the processed length will be zero.<br>
 905      * The caller should check for such an occurrence and do one of the following:
 906      * <ul><li>submit a larger amount of text with a better chance to include
 907      *         a reasonable boundary.</li>
 908      *     <li>resubmit the same text after turning off option
 909      *         <code>UBIDI_OPTION_STREAMING</code>.</li></ul>
 910      * In all cases, this option should be turned off before processing the last
 911      * part of the text.</p>
 912      *
 913      * <p>When the <code>UBIDI_OPTION_STREAMING</code> option is used,
 914      * it is recommended to call <code>ubidi_orderParagraphsLTR()</code> with
 915      * argument <code>orderParagraphsLTR</code> set to <code>TRUE</code> before
 916      * calling <code>ubidi_setPara</code> so that later paragraphs may be
 917      * concatenated to previous paragraphs on the right.</p>
 918      *
 919      * @see ubidi_setReorderingMode
 920      * @see ubidi_setReorderingOptions
 921      * @see ubidi_getProcessedLength
 922      * @see ubidi_orderParagraphsLTR
 923      * @draft ICU 3.6
 924      */
 925     UBIDI_OPTION_STREAMING = 4
 926 } UBiDiReorderingOption;
 927
 928 /**
 929  * Specify which of the reordering options
 930  * should be applied during BiDi transformations.
 931  *
 932  * @param pBiDi is a <code>UBiDi</code> object.
 933  * @param reorderingOptions is a combination of zero or more of the following
 934  * options:
 935  * <code>#UBIDI_OPTION_DEFAULT</code>, <code>#UBIDI_OPTION_INSERT_MARKS</code>,
 936  * <code>#UBIDI_OPTION_REMOVE_CONTROLS</code>, <code>#UBIDI_OPTION_STREAMING</code>.
 937  *
 938  * @see ubidi_getReorderingOptions
 939  * @draft ICU 3.6
 940  */
 941 U_DRAFT void U_EXPORT2
 942 ubidi_setReorderingOptions(UBiDi *pBiDi, uint32_t reorderingOptions);
 943
 944 /**
 945  * What are the reordering options applied to a given BiDi object?
 946  *
 947  * @param pBiDi is a <code>UBiDi</code> object.
 948  * @return the current reordering options of the BiDi object
 949  * @see ubidi_setReorderingOptions
 950  * @draft ICU 3.6
 951  */
 952 U_DRAFT uint32_t U_EXPORT2
 953 ubidi_getReorderingOptions(UBiDi *pBiDi);
 954
 955 /**
 956  * Perform the Unicode BiDi algorithm. It is defined in the
 957  * <a href="http://www.unicode.org/unicode/reports/tr9/">Unicode Standard Anned #9</a>,
 958  * version 13,
 959  * also described in The Unicode Standard, Version 4.0 .<p>
 960  *
 961  * This function takes a piece of plain text containing one or more paragraphs,
 962  * with or without externally specified embedding levels from <i>styled</i>
 963  * text and computes the left-right-directionality of each character.<p>
 964  *
 965  * If the entire text is all of the same directionality, then
 966  * the function may not perform all the steps described by the algorithm,
 967  * i.e., some levels may not be the same as if all steps were performed.
 968  * This is not relevant for unidirectional text.<br>
 969  * For example, in pure LTR text with numbers the numbers would get
 970  * a resolved level of 2 higher than the surrounding text according to
 971  * the algorithm. This implementation may set all resolved levels to
 972  * the same value in such a case.<p>
 973  *
 974  * The text can be composed of multiple paragraphs. Occurrence of a block
 975  * separator in the text terminates a paragraph, and whatever comes next starts
 976  * a new paragraph. The exception to this rule is when a Carriage Return (CR)
 977  * is followed by a Line Feed (LF). Both CR and LF are block separators, but
 978  * in that case, the pair of characters is considered as terminating the
 979  * preceding paragraph, and a new paragraph will be started by a character
 980  * coming after the LF.
 981  *
 982  * @param pBiDi A <code>UBiDi</code> object allocated with <code>ubidi_open()</code>
 983  *        which will be set to contain the reordering information,
 984  *        especially the resolved levels for all the characters in <code>text</code>.
 985  *
 986  * @param text is a pointer to the text that the BiDi algorithm will be performed on.
 987  *        This pointer is stored in the UBiDi object and can be retrieved
 988  *        with <code>ubidi_getText()</code>.<br>
 989  *        <strong>Note:</strong> the text must be (at least) <code>length</code> long.
 990  *
 991  * @param length is the length of the text; if <code>length==-1</code> then
 992  *        the text must be zero-terminated.
 993  *
 994  * @param paraLevel specifies the default level for the text;
 995  *        it is typically 0 (LTR) or 1 (RTL).
 996  *        If the function shall determine the paragraph level from the text,
 997  *        then <code>paraLevel</code> can be set to
 998  *        either <code>#UBIDI_DEFAULT_LTR</code>
 999  *        or <code>#UBIDI_DEFAULT_RTL</code>; if the text contains multiple
1000  *        paragraphs, the paragraph level shall be determined separately for
1001  *        each paragraph; if a paragraph does not include any strongly typed
1002  *        character, then the desired default is used (0 for LTR or 1 for RTL).
1003  *        Any other value between 0 and <code>#UBIDI_MAX_EXPLICIT_LEVEL</code>
1004  *        is also valid, with odd levels indicating RTL.
1005  *
1006  * @param embeddingLevels (in) may be used to preset the embedding and override levels,
1007  *        ignoring characters like LRE and PDF in the text.
1008  *        A level overrides the directional property of its corresponding
1009  *        (same index) character if the level has the
1010  *        <code>#UBIDI_LEVEL_OVERRIDE</code> bit set.<br><br>
1011  *        Except for that bit, it must be
1012  *        <code>paraLevel<=embeddingLevels[]<=UBIDI_MAX_EXPLICIT_LEVEL</code>,
1013  *        with one exception: a level of zero may be specified for a paragraph
1014  *        separator even if <code>paraLevel>0</code> when multiple paragraphs
1015  *        are submitted in the same call to <code>ubidi_setPara()</code>.<br><br>
1016  *        <strong>Caution: </strong>A copy of this pointer, not of the levels,
1017  *        will be stored in the <code>UBiDi</code> object;
1018  *        the <code>embeddingLevels</code> array must not be
1019  *        deallocated before the <code>UBiDi</code> structure is destroyed or reused,
1020  *        and the <code>embeddingLevels</code>
1021  *        should not be modified to avoid unexpected results on subsequent BiDi operations.
1022  *        However, the <code>ubidi_setPara()</code> and
1023  *        <code>ubidi_setLine()</code> functions may modify some or all of the levels.<br><br>
1024  *        After the <code>UBiDi</code> object is reused or destroyed, the caller
1025  *        must take care of the deallocation of the <code>embeddingLevels</code> array.<br><br>
1026  *        <strong>Note:</strong> the <code>embeddingLevels</code> array must be
1027  *        at least <code>length</code> long.
1028  *
1029  * @param pErrorCode must be a valid pointer to an error code value.
1030  * @stable ICU 2.0
1031  */
1032 U_STABLE void U_EXPORT2
1033 ubidi_setPara(UBiDi *pBiDi, const UChar *text, int32_t length,
1034               UBiDiLevel paraLevel, UBiDiLevel *embeddingLevels,
1035               UErrorCode *pErrorCode);
1036
1037 /**
1038  * <code>ubidi_setLine()</code> sets a <code>UBiDi</code> to
1039  * contain the reordering information, especially the resolved levels,
1040  * for all the characters in a line of text. This line of text is
1041  * specified by referring to a <code>UBiDi</code> object representing
1042  * this information for a piece of text containing one or more paragraphs,
1043  * and by specifying a range of indexes in this text.<p>
1044  * In the new line object, the indexes will range from 0 to <code>limit-start-1</code>.<p>
1045  *
1046  * This is used after calling <code>ubidi_setPara()</code>
1047  * for a piece of text, and after line-breaking on that text.
1048  * It is not necessary if each paragraph is treated as a single line.<p>
1049  *
1050  * After line-breaking, rules (L1) and (L2) for the treatment of
1051  * trailing WS and for reordering are performed on
1052  * a <code>UBiDi</code> object that represents a line.<p>
1053  *
1054  * <strong>Important: </strong><code>pLineBiDi</code> shares data with
1055  * <code>pParaBiDi</code>.
1056  * You must destroy or reuse <code>pLineBiDi</code> before <code>pParaBiDi</code>.
1057  * In other words, you must destroy or reuse the <code>UBiDi</code> object for a line
1058  * before the object for its parent paragraph.<p>
1059  *
1060  * The text pointer that was stored in <code>pParaBiDi</code> is also copied,
1061  * and <code>start</code> is added to it so that it points to the beginning of the
1062  * line for this object.
1063  *
1064  * @param pParaBiDi is the parent paragraph object. It must have been set
1065  * by a successful call to ubidi_setPara.
1066  *
1067  * @param start is the line's first index into the text.
1068  *
1069  * @param limit is just behind the line's last index into the text
1070  *        (its last index +1).<br>
1071  *        It must be <code>0<=start<=limit<=</code>containing paragraph limit.
1072  *        If the specified line crosses a paragraph boundary, the function
1073  *        will terminate with error code U_ILLEGAL_ARGUMENT_ERROR.
1074  *
1075  * @param pLineBiDi is the object that will now represent a line of the text.
1076  *
1077  * @param pErrorCode must be a valid pointer to an error code value.
1078  *
1079  * @see ubidi_setPara
1080  * @see ubidi_getProcessedLength
1081  * @stable ICU 2.0
1082  */
1083 U_STABLE void U_EXPORT2
1084 ubidi_setLine(const UBiDi *pParaBiDi,
1085               int32_t start, int32_t limit,
1086               UBiDi *pLineBiDi,
1087               UErrorCode *pErrorCode);
1088
1089 /**
1090  * Get the directionality of the text.
1091  *
1092  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1093  *
1094  * @return A <code>UBIDI_XXX</code> value that indicates if the entire text
1095  *         represented by this object is unidirectional,
1096  *         and which direction, or if it is mixed-directional.
1097  *
1098  * @see UBiDiDirection
1099  * @stable ICU 2.0
1100  */
1101 U_STABLE UBiDiDirection U_EXPORT2
1102 ubidi_getDirection(const UBiDi *pBiDi);
1103
1104 /**
1105  * Get the pointer to the text.
1106  *
1107  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1108  *
1109  * @return The pointer to the text that the UBiDi object was created for.
1110  *
1111  * @see ubidi_setPara
1112  * @see ubidi_setLine
1113  * @stable ICU 2.0
1114  */
1115 U_STABLE const UChar * U_EXPORT2
1116 ubidi_getText(const UBiDi *pBiDi);
1117
1118 /**
1119  * Get the length of the text.
1120  *
1121  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1122  *
1123  * @return The length of the text that the UBiDi object was created for.
1124  * @stable ICU 2.0
1125  */
1126 U_STABLE int32_t U_EXPORT2
1127 ubidi_getLength(const UBiDi *pBiDi);
1128
1129 /**
1130  * Get the paragraph level of the text.
1131  *
1132  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1133  *
1134  * @return The paragraph level. If there are multiple paragraphs, their
1135  *         level may vary if the required paraLevel is UBIDI_DEFAULT_LTR or
1136  *         UBIDI_DEFAULT_RTL.  In that case, the level of the first paragraph
1137  *         is returned.
1138  *
1139  * @see UBiDiLevel
1140  * @see ubidi_getParagraph
1141  * @see ubidi_getParagraphByIndex
1142  * @stable ICU 2.0
1143  */
1144 U_STABLE UBiDiLevel U_EXPORT2
1145 ubidi_getParaLevel(const UBiDi *pBiDi);
1146
1147 /**
1148  * Get the number of paragraphs.
1149  *
1150  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1151  *
1152  * @return The number of paragraphs.
1153  * @stable ICU 3.4
1154  */
1155 U_STABLE int32_t U_EXPORT2
1156 ubidi_countParagraphs(UBiDi *pBiDi);
1157
1158 /**
1159  * Get a paragraph, given a position within the text.
1160  * This function returns information about a paragraph.<p>
1161  *
1162  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1163  *
1164  * @param charIndex is the index of a character within the text, in the
1165  *        range <code>[0..ubidi_getProcessedLength(pBiDi)-1]</code>.
1166  *
1167  * @param pParaStart will receive the index of the first character of the
1168  *        paragraph in the text.
1169  *        This pointer can be <code>NULL</code> if this
1170  *        value is not necessary.
1171  *
1172  * @param pParaLimit will receive the limit of the paragraph.
1173  *        The l-value that you point to here may be the
1174  *        same expression (variable) as the one for
1175  *        <code>charIndex</code>.
1176  *        This pointer can be <code>NULL</code> if this
1177  *        value is not necessary.
1178  *
1179  * @param pParaLevel will receive the level of the paragraph.
1180  *        This pointer can be <code>NULL</code> if this
1181  *        value is not necessary.
1182  *
1183  * @param pErrorCode must be a valid pointer to an error code value.
1184  *
1185  * @return The index of the paragraph containing the specified position.
1186  *
1187  * @see ubidi_getProcessedLength
1188  * @stable ICU 3.4
1189  */
1190 U_STABLE int32_t U_EXPORT2
1191 ubidi_getParagraph(const UBiDi *pBiDi, int32_t charIndex, int32_t *pParaStart,
1192                    int32_t *pParaLimit, UBiDiLevel *pParaLevel,
1193                    UErrorCode *pErrorCode);
1194
1195 /**
1196  * Get a paragraph, given the index of this paragraph.
1197  *
1198  * This function returns information about a paragraph.<p>
1199  *
1200  * @param pBiDi is the paragraph <code>UBiDi</code> object.
1201  *
1202  * @param paraIndex is the number of the paragraph, in the
1203  *        range <code>[0..ubidi_countParagraphs(pBiDi)-1]</code>.
1204  *
1205  * @param pParaStart will receive the index of the first character of the
1206  *        paragraph in the text.
1207  *        This pointer can be <code>NULL</code> if this
1208  *        value is not necessary.
1209  *
1210  * @param pParaLimit will receive the limit of the paragraph.
1211  *        This pointer can be <code>NULL</code> if this
1212  *        value is not necessary.
1213  *
1214  * @param pParaLevel will receive the level of the paragraph.
1215  *        This pointer can be <code>NULL</code> if this
1216  *        value is not necessary.
1217  *
1218  * @param pErrorCode must be a valid pointer to an error code value.
1219  *
1220  * @stable ICU 3.4
1221  */
1222 U_STABLE void U_EXPORT2
1223 ubidi_getParagraphByIndex(const UBiDi *pBiDi, int32_t paraIndex,
1224                           int32_t *pParaStart, int32_t *pParaLimit,
1225                           UBiDiLevel *pParaLevel, UErrorCode *pErrorCode);
1226
1227 /**
1228  * Get the level for one character.
1229  *
1230  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1231  *
1232  * @param charIndex the index of a character.
1233  *
1234  * @return The level for the character at charIndex.
1235  *
1236  * @see UBiDiLevel
1237  * @see ubidi_getProcessedLength
1238  * @stable ICU 2.0
1239  */
1240 U_STABLE UBiDiLevel U_EXPORT2
1241 ubidi_getLevelAt(const UBiDi *pBiDi, int32_t charIndex);
1242
1243 /**
1244  * Get an array of levels for each character.<p>
1245  *
1246  * Note that this function may allocate memory under some
1247  * circumstances, unlike <code>ubidi_getLevelAt()</code>.
1248  *
1249  * @param pBiDi is the paragraph or line <code>UBiDi</code> object, whose
1250  *        text length must be strictly positive.
1251  *
1252  * @param pErrorCode must be a valid pointer to an error code value.
1253  *
1254  * @return The levels array for the text,
1255  *         or <code>NULL</code> if an error occurs.
1256  *
1257  * @see UBiDiLevel
1258  * @see ubidi_getProcessedLength
1259  * @stable ICU 2.0
1260  */
1261 U_STABLE const UBiDiLevel * U_EXPORT2
1262 ubidi_getLevels(UBiDi *pBiDi, UErrorCode *pErrorCode);
1263
1264 /**
1265  * Get a logical run.
1266  * This function returns information about a run and is used
1267  * to retrieve runs in logical order.<p>
1268  * This is especially useful for line-breaking on a paragraph.
1269  *
1270  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1271  *
1272  * @param logicalStart is the first character of the run.
1273  *
1274  * @param pLogicalLimit will receive the limit of the run.
1275  *        The l-value that you point to here may be the
1276  *        same expression (variable) as the one for
1277  *        <code>logicalStart</code>.
1278  *        This pointer can be <code>NULL</code> if this
1279  *        value is not necessary.
1280  *
1281  * @param pLevel will receive the level of the run.
1282  *        This pointer can be <code>NULL</code> if this
1283  *        value is not necessary.
1284  *
1285  * @see ubidi_getProcessedLength
1286  * @stable ICU 2.0
1287  */
1288 U_STABLE void U_EXPORT2
1289 ubidi_getLogicalRun(const UBiDi *pBiDi, int32_t logicalStart,
1290                     int32_t *pLogicalLimit, UBiDiLevel *pLevel);
1291
1292 /**
1293  * Get the number of runs.
1294  * This function may invoke the actual reordering on the
1295  * <code>UBiDi</code> object, after <code>ubidi_setPara()</code>
1296  * may have resolved only the levels of the text. Therefore,
1297  * <code>ubidi_countRuns()</code> may have to allocate memory,
1298  * and may fail doing so.
1299  *
1300  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1301  *
1302  * @param pErrorCode must be a valid pointer to an error code value.
1303  *
1304  * @return The number of runs.
1305  * @stable ICU 2.0
1306  */
1307 U_STABLE int32_t U_EXPORT2
1308 ubidi_countRuns(UBiDi *pBiDi, UErrorCode *pErrorCode);
1309
1310 /**
1311  * Get one run's logical start, length, and directionality,
1312  * which can be 0 for LTR or 1 for RTL.
1313  * In an RTL run, the character at the logical start is
1314  * visually on the right of the displayed run.
1315  * The length is the number of characters in the run.<p>
1316  * <code>ubidi_countRuns()</code> should be called
1317  * before the runs are retrieved.
1318  *
1319  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1320  *
1321  * @param runIndex is the number of the run in visual order, in the
1322  *        range <code>[0..ubidi_countRuns(pBiDi)-1]</code>.
1323  *
1324  * @param pLogicalStart is the first logical character index in the text.
1325  *        The pointer may be <code>NULL</code> if this index is not needed.
1326  *
1327  * @param pLength is the number of characters (at least one) in the run.
1328  *        The pointer may be <code>NULL</code> if this is not needed.
1329  *
1330  * @return the directionality of the run,
1331  *         <code>UBIDI_LTR==0</code> or <code>UBIDI_RTL==1</code>,
1332  *         never <code>UBIDI_MIXED</code>.
1333  *
1334  * @see ubidi_countRuns
1335  *
1336  * Example:
1337  * <pre>
1338  * \code
1339  * int32_t i, count=ubidi_countRuns(pBiDi),
1340  *         logicalStart, visualIndex=0, length;
1341  * for(i=0; i<count; ++i) {
1342  *    if(UBIDI_LTR==ubidi_getVisualRun(pBiDi, i, &logicalStart, &length)) {
1343  *         do { // LTR
1344  *             show_char(text[logicalStart++], visualIndex++);
1345  *         } while(--length>0);
1346  *     } else {
1347  *         logicalStart+=length;  // logicalLimit
1348  *         do { // RTL
1349  *             show_char(text[--logicalStart], visualIndex++);
1350  *         } while(--length>0);
1351  *     }
1352  * }
1353  *\endcode
1354  * </pre>
1355  *
1356  * Note that in right-to-left runs, code like this places
1357  * modifier letters before base characters and second surrogates
1358  * before first ones.
1359  * @stable ICU 2.0
1360  */
1361 U_STABLE UBiDiDirection U_EXPORT2
1362 ubidi_getVisualRun(UBiDi *pBiDi, int32_t runIndex,
1363                    int32_t *pLogicalStart, int32_t *pLength);
1364
1365 /**
1366  * Get the visual position from a logical text position.
1367  * If such a mapping is used many times on the same
1368  * <code>UBiDi</code> object, then calling
1369  * <code>ubidi_getLogicalMap()</code> is more efficient.<p>
1370  *
1371  * The value returned may be <code>#UBIDI_MAP_NOWHERE</code> if there is no
1372  * visual position because the corresponding text character is a BiDi control
1373  * removed from output by the option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code>.
1374  * <p>
1375  * Note that in right-to-left runs, this mapping places
1376  * modifier letters before base characters and second surrogates
1377  * before first ones.
1378  *
1379  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1380  *
1381  * @param logicalIndex is the index of a character in the text.
1382  *
1383  * @param pErrorCode must be a valid pointer to an error code value.
1384  *
1385  * @return The visual position of this character.
1386  *
1387  * @see ubidi_getLogicalMap
1388  * @see ubidi_getLogicalIndex
1389  * @see ubidi_getProcessedLength
1390  * @stable ICU 2.0
1391  */
1392 U_STABLE int32_t U_EXPORT2
1393 ubidi_getVisualIndex(UBiDi *pBiDi, int32_t logicalIndex, UErrorCode *pErrorCode);
1394
1395 /**
1396  * Get the logical text position from a visual position.
1397  * If such a mapping is used many times on the same
1398  * <code>UBiDi</code> object, then calling
1399  * <code>ubidi_getVisualMap()</code> is more efficient.<p>
1400  *
1401  * The value returned may be <code>#UBIDI_MAP_NOWHERE</code> if there is no
1402  * logical position because the corresponding text character is a BiDi mark
1403  * inserted in the output by option <code>#UBIDI_OPTION_INSERT_MARKS</code>.
1404  * <p>
1405  * This is the inverse function to <code>ubidi_getVisualIndex()</code>.
1406  *
1407  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1408  *
1409  * @param visualIndex is the visual position of a character.
1410  *
1411  * @param pErrorCode must be a valid pointer to an error code value.
1412  *
1413  * @return The index of this character in the text.
1414  *
1415  * @see ubidi_getVisualMap
1416  * @see ubidi_getVisualIndex
1417  * @see ubidi_getResultLength
1418  * @stable ICU 2.0
1419  */
1420 U_STABLE int32_t U_EXPORT2
1421 ubidi_getLogicalIndex(UBiDi *pBiDi, int32_t visualIndex, UErrorCode *pErrorCode);
1422
1423 /**
1424  * Get a logical-to-visual index map (array) for the characters in the UBiDi
1425  * (paragraph or line) object.
1426  * <p>
1427  * Some values in the map may be <code>#UBIDI_MAP_NOWHERE</code> if the
1428  * corresponding text characters are BiDi controls removed from the visual
1429  * output by the option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code>.
1430  *
1431  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1432  *
1433  * @param indexMap is a pointer to an array of <code>ubidi_getProcessedLength()</code>
1434  *        indexes which will reflect the reordering of the characters.
1435  *        If option <code>#UBIDI_OPTION_INSERT_MARKS</code> is set, the number
1436  *        of elements allocated in <code>indexMap</code> must be no less than
1437  *        <code>ubidi_getResultLength()</code>.
1438  *        The array does not need to be initialized.<br><br>
1439  *        The index map will result in <code>indexMap[logicalIndex]==visualIndex</code>.
1440  *
1441  * @param pErrorCode must be a valid pointer to an error code value.
1442  *
1443  * @see ubidi_getVisualMap
1444  * @see ubidi_getVisualIndex
1445  * @see ubidi_getProcessedLength
1446  * @see ubidi_getResultLength
1447  * @stable ICU 2.0
1448  */
1449 U_STABLE void U_EXPORT2
1450 ubidi_getLogicalMap(UBiDi *pBiDi, int32_t *indexMap, UErrorCode *pErrorCode);
1451
1452 /**
1453  * Get a visual-to-logical index map (array) for the characters in the UBiDi
1454  * (paragraph or line) object.
1455  * <p>
1456  * Some values in the map may be <code>#UBIDI_MAP_NOWHERE</code> if the
1457  * corresponding text characters are BiDi marks inserted in the visual output
1458  * by the option <code>#UBIDI_OPTION_INSERT_MARKS</code>.
1459  *
1460  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1461  *
1462  * @param indexMap is a pointer to an array of <code>ubidi_getResultLength()</code>
1463  *        indexes which will reflect the reordering of the characters.
1464  *        If option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code> is set, the number
1465  *        of elements allocated in <code>indexMap</code> must be no less than
1466  *        <code>ubidi_getProcessedLength()</code>.
1467  *        The array does not need to be initialized.<br><br>
1468  *        The index map will result in <code>indexMap[visualIndex]==logicalIndex</code>.
1469  *
1470  * @param pErrorCode must be a valid pointer to an error code value.
1471  *
1472  * @see ubidi_getLogicalMap
1473  * @see ubidi_getLogicalIndex
1474  * @see ubidi_getProcessedLength
1475  * @see ubidi_getResultLength
1476  * @stable ICU 2.0
1477  */
1478 U_STABLE void U_EXPORT2
1479 ubidi_getVisualMap(UBiDi *pBiDi, int32_t *indexMap, UErrorCode *pErrorCode);
1480
1481 /**
1482  * This is a convenience function that does not use a UBiDi object.
1483  * It is intended to be used for when an application has determined the levels
1484  * of objects (character sequences) and just needs to have them reordered (L2).
1485  * This is equivalent to using <code>ubidi_getLogicalMap()</code> on a
1486  * <code>UBiDi</code> object.
1487  *
1488  * @param levels is an array with <code>length</code> levels that have been determined by
1489  *        the application.
1490  *
1491  * @param length is the number of levels in the array, or, semantically,
1492  *        the number of objects to be reordered.
1493  *        It must be <code>length>0</code>.
1494  *
1495  * @param indexMap is a pointer to an array of <code>length</code>
1496  *        indexes which will reflect the reordering of the characters.
1497  *        The array does not need to be initialized.<p>
1498  *        The index map will result in <code>indexMap[logicalIndex]==visualIndex</code>.
1499  * @stable ICU 2.0
1500  */
1501 U_STABLE void U_EXPORT2
1502 ubidi_reorderLogical(const UBiDiLevel *levels, int32_t length, int32_t *indexMap);
1503
1504 /**
1505  * This is a convenience function that does not use a UBiDi object.
1506  * It is intended to be used for when an application has determined the levels
1507  * of objects (character sequences) and just needs to have them reordered (L2).
1508  * This is equivalent to using <code>ubidi_getVisualMap()</code> on a
1509  * <code>UBiDi</code> object.
1510  *
1511  * @param levels is an array with <code>length</code> levels that have been determined by
1512  *        the application.
1513  *
1514  * @param length is the number of levels in the array, or, semantically,
1515  *        the number of objects to be reordered.
1516  *        It must be <code>length>0</code>.
1517  *
1518  * @param indexMap is a pointer to an array of <code>length</code>
1519  *        indexes which will reflect the reordering of the characters.
1520  *        The array does not need to be initialized.<p>
1521  *        The index map will result in <code>indexMap[visualIndex]==logicalIndex</code>.
1522  * @stable ICU 2.0
1523  */
1524 U_STABLE void U_EXPORT2
1525 ubidi_reorderVisual(const UBiDiLevel *levels, int32_t length, int32_t *indexMap);
1526
1527 /**
1528  * Invert an index map.
1529  * The index mapping of the first map is inverted and written to
1530  * the second one.
1531  *
1532  * @param srcMap is an array with <code>length</code> indexes
1533  *        which defines the original mapping from a source array containing
1534  *        <code>length</code> elements to a destination array.
1535  *        All indexes must be >=0 or equal to <code>UBIDI_MAP_NOWHERE</code>.
1536  *        This special value means that the corresponding elements in the source
1537  *        array have no matching element in the destination array.
1538  *        Some indexes may have a value >= <code>length</code>, if the
1539  *        destination array has more elements than the source array.
1540  *        There must be no duplicate indexes (two or more indexes with the
1541  *        same value except <code>UBIDI_MAP_NOWHERE</code>).
1542  *
1543  * @param destMap is an array with a number of indexes equal to 1 + the highest
1544  *        value in <code>srcMap</code>.
1545  *        <code>destMap</code> will be filled with the inverse mapping.
1546  *        Elements of <code>destMap</code> which have no matching elements in
1547  *        <code>srcMap</code> will receive an index equal to
1548  *        <code>UBIDI_MAP_NOWHERE</code>
1549  *
1550  * @param length is the length of each array.
1551  * @See UBIDI_MAP_NOWHERE
1552  * @stable ICU 2.0
1553  */
1554 U_STABLE void U_EXPORT2
1555 ubidi_invertMap(const int32_t *srcMap, int32_t *destMap, int32_t length);
1556
1557 /** option flags for ubidi_writeReordered() */
1558
1559 /**
1560  * option bit for ubidi_writeReordered():
1561  * keep combining characters after their base characters in RTL runs
1562  *
1563  * @see ubidi_writeReordered
1564  * @stable ICU 2.0
1565  */
1566 #define UBIDI_KEEP_BASE_COMBINING       1
1567
1568 /**
1569  * option bit for ubidi_writeReordered():
1570  * replace characters with the "mirrored" property in RTL runs
1571  * by their mirror-image mappings
1572  *
1573  * @see ubidi_writeReordered
1574  * @stable ICU 2.0
1575  */
1576 #define UBIDI_DO_MIRRORING              2
1577
1578 /**
1579  * option bit for ubidi_writeReordered():
1580  * surround the run with LRMs if necessary;
1581  * this is part of the approximate "inverse BiDi" algorithm
1582  *
1583  * <p>This option does not imply corresponding adjustment of the index
1584  * mappings.</p>
1585  *
1586  * @see ubidi_setInverse
1587  * @see ubidi_writeReordered
1588  * @stable ICU 2.0
1589  */
1590 #define UBIDI_INSERT_LRM_FOR_NUMERIC    4
1591
1592 /**
1593  * option bit for ubidi_writeReordered():
1594  * remove BiDi control characters
1595  * (this does not affect #UBIDI_INSERT_LRM_FOR_NUMERIC)
1596  *
1597  * <p>This option does not imply corresponding adjustment of the index
1598  * mappings.</p>
1599  *
1600  * @see ubidi_writeReordered
1601  * @stable ICU 2.0
1602  */
1603 #define UBIDI_REMOVE_BIDI_CONTROLS      8
1604
1605 /**
1606  * option bit for ubidi_writeReordered():
1607  * write the output in reverse order
1608  *
1609  * <p>This has the same effect as calling <code>ubidi_writeReordered()</code>
1610  * first without this option, and then calling
1611  * <code>ubidi_writeReverse()</code> without mirroring.
1612  * Doing this in the same step is faster and avoids a temporary buffer.
1613  * An example for using this option is output to a character terminal that
1614  * is designed for RTL scripts and stores text in reverse order.</p>
1615  *
1616  * @see ubidi_writeReordered
1617  * @stable ICU 2.0
1618  */
1619 #define UBIDI_OUTPUT_REVERSE            16
1620
1621 /**
1622  * Get the length of the source text processed by the last call to
1623  * <code>ubidi_setPara()</code>. This length may be different from the length
1624  * of the source text if option <code>#UBIDI_OPTION_STREAMING</code>
1625  * has been set.
1626  * <br>
1627  * Note that whenever the length of the text affects the execution or the
1628  * result of a function, it is the processed length which must be considered,
1629  * except for <code>ubidi_setPara</code> (which receives unprocessed source
1630  * text) and <code>ubidi_getLength</code> (which returns the original length
1631  * of the source text).<br>
1632  * In particular, the processed length is the one to consider in the following
1633  * cases:
1634  * <ul>
1635  * <li>maximum value of the <code>limit</code> argument of
1636  * <code>ubidi_setLine</code></li>
1637  * <li>maximum value of the <code>charIndex</code> argument of
1638  * <code>ubidi_getParagraph</code></li>
1639  * <li>maximum value of the <code>charIndex</code> argument of
1640  * <code>ubidi_getLevelAt</code></li>
1641  * <li>number of elements in the array returned by <code>ubidi_getLevels</code></li>
1642  * <li>maximum value of the <code>logicalStart</code> argument of
1643  * <code>ubidi_getLogicalRun</code></li>
1644  * <li>maximum value of the <code>logicalIndex</code> argument of
1645  * <code>ubidi_getVisualIndex</code></li>
1646  * <li>number of elements filled in the <code>*indexMap</code> argument of
1647  * <code>ubidi_getLogicalMap</code></li>
1648  * <li>length of text processed by <code>ubidi_writeReordered</code></li>
1649  * </ul>
1650  *
1651  * @param pBiDi is the paragraph <code>UBiDi</code> object.
1652  *
1653  * @return The length of the part of the source text processed by
1654  *         the last call to <code>ubidi_setPara</code>.
1655  * @see ubidi_setPara
1656  * @see UBIDI_OPTION_STREAMING
1657  * @draft ICU 3.6
1658  */
1659 U_DRAFT int32_t U_EXPORT2
1660 ubidi_getProcessedLength(const UBiDi *pBiDi);
1661
1662 /**
1663  * Get the length of the reordered text resulting from the last call to
1664  * <code>ubidi_setPara()</code>. This length may be different from the length
1665  * of the source text if option <code>#UBIDI_OPTION_INSERT_MARKS</code>
1666  * or option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code> has been set.
1667  * <br>
1668  * This resulting length is the one to consider in the following cases:
1669  * <ul>
1670  * <li>maximum value of the <code>visualIndex</code> argument of
1671  * <code>ubidi_getLogicalIndex</code></li>
1672  * <li>number of elements of the <code>*indexMap</code> argument of
1673  * <code>ubidi_getVisualMap</code></li>
1674  * </ul>
1675  * Note that this length stays identical to the source text length if
1676  * BiDi marks are inserted or removed using option bits of
1677  * <code>ubidi_writeReordered</code>, or if option
1678  * <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code> has been set.
1679  *
1680  * @param pBiDi is the paragraph <code>UBiDi</code> object.
1681  *
1682  * @return The length of the reordered text resulting from
1683  *         the last call to <code>ubidi_setPara</code>.
1684  * @see ubidi_setPara
1685  * @see UBIDI_OPTION_INSERT_MARKS
1686  * @see UBIDI_OPTION_REMOVE_CONTROLS
1687  * @draft ICU 3.6
1688  */
1689 U_DRAFT int32_t U_EXPORT2
1690 ubidi_getResultLength(const UBiDi *pBiDi);
1691
1692 U_CDECL_BEGIN
1693 /**
1694  * value returned by <code>UBiDiClassCallback</code> callbacks when
1695  * there is no need to override the standard BiDi class for a given code point.
1696  * @see UBiDiClassCallback
1697  * @draft ICU 3.6
1698  */
1699 #define U_BIDI_CLASS_DEFAULT  U_CHAR_DIRECTION_COUNT
1700
1701 /**
1702  * Callback type declaration for overriding default BiDi class values with
1703  * custom ones.
1704  * <p>Usually, the function pointer will be propagated to a <code>UBiDi</code>
1705  * object by calling the <code>ubidi_setClassCallback()</code> function;
1706  * then the callback will be invoked by the UBA implementation any time the
1707  * class of a character is to be determined.</p>
1708  *
1709  * @param context is a pointer to the callback private data.
1710  *
1711  * @param c       is the code point to get a BiDi class for.
1712  *
1713  * @return The directional property / BiDi class for the given code point
1714  *         <code>c</code> if the default class has been overridden, or
1715  *         <code>#U_BIDI_CLASS_DEFAULT</code> if the standard BiDi class value
1716  *         for <code>c</code> is to be used.
1717  * @see ubidi_setClassCallback
1718  * @see ubidi_getClassCallback
1719  * @draft ICU 3.6
1720  */
1721 typedef UCharDirection U_CALLCONV
1722 UBiDiClassCallback(const void *context, UChar32 c);
1723
1724 U_CDECL_END
1725
1726 /**
1727  * Retrieve the BiDi class for a given code point.
1728  * <p>If a <code>#UBiDiClassCallback</code> callback is defined and returns a
1729  * value other than <code>#U_BIDI_CLASS_DEFAULT</code>, that value is used;
1730  * otherwise the default class determination mechanism is invoked.</p>
1731  *
1732  * @param pBiDi is the paragraph <code>UBiDi</code> object.
1733  *
1734  * @param c     is the code point whose BiDi class must be retrieved.
1735  *
1736  * @return The BiDi class for character <code>c</code> based
1737  *         on the given <code>pBiDi</code> instance.
1738  * @see UBiDiClassCallback
1739  * @draft ICU 3.6
1740  */
1741 U_DRAFT UCharDirection U_EXPORT2
1742 ubidi_getCustomizedClass(UBiDi *pBiDi, UChar32 c);
1743
1744 /**
1745  * Set the callback function and callback data used by the UBA
1746  * implementation for BiDi class determination.
1747  * <p>This may be useful for assigning BiDi classes to PUA characters, or
1748  * for special application needs. For instance, an application may want to
1749  * handle all spaces like L or R characters (according to the base direction)
1750  * when creating the visual ordering of logical lines which are part of a report
1751  * organized in columns: there should not be interaction between adjacent
1752  * cells.<p>
1753  *
1754  * @param pBiDi is the paragraph <code>UBiDi</code> object.
1755  *
1756  * @param newFn is the new callback function pointer.
1757  *
1758  * @param newContext is the new callback context pointer. This can be NULL.
1759  *
1760  * @param oldFn fillin: Returns the old callback function pointer. This can be
1761  *                      NULL.
1762  *
1763  * @param oldContext fillin: Returns the old callback's context. This can be
1764  *                           NULL.
1765  *
1766  * @param pErrorCode must be a valid pointer to an error code value.
1767  *
1768  * @see ubidi_getClassCallback
1769  * @draft ICU 3.6
1770  */
1771 U_DRAFT void U_EXPORT2
1772 ubidi_setClassCallback(UBiDi *pBiDi, UBiDiClassCallback *newFn,
1773                        const void *newContext, UBiDiClassCallback **oldFn,
1774                        const void **oldContext, UErrorCode *pErrorCode);
1775
1776 /**
1777  * Get the current callback function used for BiDi class determination.
1778  *
1779  * @param pBiDi is the paragraph <code>UBiDi</code> object.
1780  *
1781  * @param fn fillin: Returns the callback function pointer.
1782  *
1783  * @param context fillin: Returns the callback's private context.
1784  *
1785  * @see ubidi_setClassCallback
1786  * @draft ICU 3.6
1787  */
1788 U_DRAFT void U_EXPORT2
1789 ubidi_getClassCallback(UBiDi *pBiDi, UBiDiClassCallback **fn, const void **context);
1790
1791 /**
1792  * Take a <code>UBiDi</code> object containing the reordering
1793  * information for a piece of text (one or more paragraphs) set by
1794  * <code>ubidi_setPara()</code> or for a line of text set by
1795  * <code>ubidi_setLine()</code> and write a reordered string to the
1796  * destination buffer.
1797  *
1798  * This function preserves the integrity of characters with multiple
1799  * code units and (optionally) modifier letters.
1800  * Characters in RTL runs can be replaced by mirror-image characters
1801  * in the destination buffer. Note that "real" mirroring has
1802  * to be done in a rendering engine by glyph selection
1803  * and that for many "mirrored" characters there are no
1804  * Unicode characters as mirror-image equivalents.
1805  * There are also options to insert or remove BiDi control
1806  * characters; see the description of the <code>destSize</code>
1807  * and <code>options</code> parameters and of the option bit flags.
1808  *
1809  * @param pBiDi A pointer to a <code>UBiDi</code> object that
1810  *              is set by <code>ubidi_setPara()</code> or
1811  *              <code>ubidi_setLine()</code> and contains the reordering
1812  *              information for the text that it was defined for,
1813  *              as well as a pointer to that text.<br><br>
1814  *              The text was aliased (only the pointer was stored
1815  *              without copying the contents) and must not have been modified
1816  *              since the <code>ubidi_setPara()</code> call.
1817  *
1818  * @param dest A pointer to where the reordered text is to be copied.
1819  *             The source text and <code>dest[destSize]</code>
1820  *             must not overlap.
1821  *
1822  * @param destSize The size of the <code>dest</code> buffer,
1823  *                 in number of UChars.
1824  *                 If the <code>UBIDI_INSERT_LRM_FOR_NUMERIC</code>
1825  *                 option is set, then the destination length could be
1826  *                 as large as
1827  *                 <code>ubidi_getLength(pBiDi)+2*ubidi_countRuns(pBiDi)</code>.
1828  *                 If the <code>UBIDI_REMOVE_BIDI_CONTROLS</code> option
1829  *                 is set, then the destination length may be less than
1830  *                 <code>ubidi_getLength(pBiDi)</code>.
1831  *                 If none of these options is set, then the destination length
1832  *                 will be exactly <code>ubidi_getLength(pBiDi)</code>.
1833  *
1834  * @param options A bit set of options for the reordering that control
1835  *                how the reordered text is written.
1836  *                The options include mirroring the characters on a code
1837  *                point basis and inserting LRM characters, which is used
1838  *                especially for transforming visually stored text
1839  *                to logically stored text (although this is still an
1840  *                imperfect implementation of an "inverse BiDi" algorithm
1841  *                because it uses the "forward BiDi" algorithm at its core).
1842  *                The available options are:
1843  *                <code>#UBIDI_DO_MIRRORING</code>,
1844  *                <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code>,
1845  *                <code>#UBIDI_KEEP_BASE_COMBINING</code>,
1846  *                <code>#UBIDI_OUTPUT_REVERSE</code>,
1847  *                <code>#UBIDI_REMOVE_BIDI_CONTROLS</code>
1848  *
1849  * @param pErrorCode must be a valid pointer to an error code value.
1850  *
1851  * @return The length of the output string.
1852  *
1853  * @see ubidi_getProcessedLength
1854  * @stable ICU 2.0
1855  */
1856 U_STABLE int32_t U_EXPORT2
1857 ubidi_writeReordered(UBiDi *pBiDi,
1858                      UChar *dest, int32_t destSize,
1859                      uint16_t options,
1860                      UErrorCode *pErrorCode);
1861
1862 /**
1863  * Reverse a Right-To-Left run of Unicode text.
1864  *
1865  * This function preserves the integrity of characters with multiple
1866  * code units and (optionally) modifier letters.
1867  * Characters can be replaced by mirror-image characters
1868  * in the destination buffer. Note that "real" mirroring has
1869  * to be done in a rendering engine by glyph selection
1870  * and that for many "mirrored" characters there are no
1871  * Unicode characters as mirror-image equivalents.
1872  * There are also options to insert or remove BiDi control
1873  * characters.
1874  *
1875  * This function is the implementation for reversing RTL runs as part
1876  * of <code>ubidi_writeReordered()</code>. For detailed descriptions
1877  * of the parameters, see there.
1878  * Since no BiDi controls are inserted here, the output string length
1879  * will never exceed <code>srcLength</code>.
1880  *
1881  * @see ubidi_writeReordered
1882  *
1883  * @param src A pointer to the RTL run text.
1884  *
1885  * @param srcLength The length of the RTL run.
1886  *
1887  * @param dest A pointer to where the reordered text is to be copied.
1888  *             <code>src[srcLength]</code> and <code>dest[destSize]</code>
1889  *             must not overlap.
1890  *
1891  * @param destSize The size of the <code>dest</code> buffer,
1892  *                 in number of UChars.
1893  *                 If the <code>UBIDI_REMOVE_BIDI_CONTROLS</code> option
1894  *                 is set, then the destination length may be less than
1895  *                 <code>srcLength</code>.
1896  *                 If this option is not set, then the destination length
1897  *                 will be exactly <code>srcLength</code>.
1898  *
1899  * @param options A bit set of options for the reordering that control
1900  *                how the reordered text is written.
1901  *                See the <code>options</code> parameter in <code>ubidi_writeReordered()</code>.
1902  *
1903  * @param pErrorCode must be a valid pointer to an error code value.
1904  *
1905  * @return The length of the output string.
1906  * @stable ICU 2.0
1907  */
1908 U_STABLE int32_t U_EXPORT2
1909 ubidi_writeReverse(const UChar *src, int32_t srcLength,
1910                    UChar *dest, int32_t destSize,
1911                    uint16_t options,
1912                    UErrorCode *pErrorCode);
1913
1914 /*#define BIDI_SAMPLE_CODE*/
1915 /*@}*/
1916
1917 #endif