icuSources/common/unicode/ubidi.h

   1 /*
   2 ******************************************************************************
   3 *
   4 *   Copyright (C) 1999-2004, 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  * javadoc-style comments are intended to be transformed into HTML
  25  * using DOC++ - see
  26  * http://www.zib.de/Visual/software/doc++/index.html .
  27  *
  28  * The HTML documentation is created with
  29  *  doc++ -H ubidi.h
  30  *
  31  * The following #define trick allows us to do it all in one file
  32  * and still be able to compile it.
  33  */
  34 /*#define DOCXX_TAG*/
  35 /*#define BIDI_SAMPLE_CODE*/
  36
  37 /**
  38  *\file
  39  * \brief C API: BIDI algorithm
  40  *
  41  * <h2>BIDI algorithm for ICU</h2>
  42  *
  43  * This is an implementation of the Unicode Bidirectional algorithm.
  44  * The algorithm is defined in the
  45  * <a href="http://www.unicode.org/unicode/reports/tr9/">Unicode Standard Annex #9</a>,
  46  * version 13, also described in The Unicode Standard, Version 4.0 .<p>
  47  *
  48  * Note: Libraries that perform a bidirectional algorithm and
  49  * reorder strings accordingly are sometimes called "Storage Layout Engines".
  50  * ICU's BiDi and shaping (u_shapeArabic()) APIs can be used at the core of such
  51  * "Storage Layout Engines".
  52  *
  53  * <h3>General remarks about the API:</h3>
  54  *
  55  * In functions with an error code parameter,
  56  * the <code>pErrorCode</code> pointer must be valid
  57  * and the value that it points to must not indicate a failure before
  58  * the function call. Otherwise, the function returns immediately.
  59  * After the function call, the value indicates success or failure.<p>
  60  *
  61  * The &quot;limit&quot; of a sequence of characters is the position just after their
  62  * last character, i.e., one more than that position.<p>
  63  *
  64  * Some of the API functions provide access to &quot;runs&quot;.
  65  * Such a &quot;run&quot; is defined as a sequence of characters
  66  * that are at the same embedding level
  67  * after performing the BIDI algorithm.<p>
  68  *
  69  * @author Markus W. Scherer
  70  * @version 1.0
  71  *
  72  *
  73  * <h4> Sample code for the ICU BIDI API </h4>
  74  *
  75  * <h5>Rendering a paragraph with the ICU BiDi API</h5>
  76  *
  77  * This is (hypothetical) sample code that illustrates
  78  * how the ICU BiDi API could be used to render a paragraph of text.
  79  * Rendering code depends highly on the graphics system,
  80  * therefore this sample code must make a lot of assumptions,
  81  * which may or may not match any existing graphics system's properties.
  82  *
  83  * <p>The basic assumptions are:</p>
  84  * <ul>
  85  * <li>Rendering is done from left to right on a horizontal line.</li>
  86  * <li>A run of single-style, unidirectional text can be rendered at once.</li>
  87  * <li>Such a run of text is passed to the graphics system with
  88  *     characters (code units) in logical order.</li>
  89  * <li>The line-breaking algorithm is very complicated
  90  *     and Locale-dependent -
  91  *     and therefore its implementation omitted from this sample code.</li>
  92  * </ul>
  93  *
  94  * <pre>
  95  * \code
  96  *#include "unicode/ubidi.h"
  97  *
  98  *typedef enum {
  99  *     styleNormal=0, styleSelected=1,
 100  *     styleBold=2, styleItalics=4,
 101  *     styleSuper=8, styleSub=16
 102  *} Style;
 103  *
 104  *typedef struct { int32_t limit; Style style; } StyleRun;
 105  *
 106  *int getTextWidth(const UChar *text, int32_t start, int32_t limit,
 107  *                  const StyleRun *styleRuns, int styleRunCount);
 108  *
 109  * // set *pLimit and *pStyleRunLimit for a line
 110  * // from text[start] and from styleRuns[styleRunStart]
 111  * // using ubidi_getLogicalRun(para, ...)
 112  *void getLineBreak(const UChar *text, int32_t start, int32_t *pLimit,
 113  *                  UBiDi *para,
 114  *                  const StyleRun *styleRuns, int styleRunStart, int *pStyleRunLimit,
 115  *                  int *pLineWidth);
 116  *
 117  * // render runs on a line sequentially, always from left to right
 118  *
 119  * // prepare rendering a new line
 120  * void startLine(UBiDiDirection textDirection, int lineWidth);
 121  *
 122  * // render a run of text and advance to the right by the run width
 123  * // the text[start..limit-1] is always in logical order
 124  * void renderRun(const UChar *text, int32_t start, int32_t limit,
 125  *               UBiDiDirection textDirection, Style style);
 126  *
 127  * // We could compute a cross-product
 128  * // from the style runs with the directional runs
 129  * // and then reorder it.
 130  * // Instead, here we iterate over each run type
 131  * // and render the intersections -
 132  * // with shortcuts in simple (and common) cases.
 133  * // renderParagraph() is the main function.
 134  *
 135  * // render a directional run with
 136  * // (possibly) multiple style runs intersecting with it
 137  * void renderDirectionalRun(const UChar *text,
 138  *                           int32_t start, int32_t limit,
 139  *                           UBiDiDirection direction,
 140  *                           const StyleRun *styleRuns, int styleRunCount) {
 141  *     int i;
 142  *
 143  *     // iterate over style runs
 144  *     if(direction==UBIDI_LTR) {
 145  *         int styleLimit;
 146  *
 147  *         for(i=0; i<styleRunCount; ++i) {
 148  *             styleLimit=styleRun[i].limit;
 149  *             if(start<styleLimit) {
 150  *                 if(styleLimit>limit) { styleLimit=limit; }
 151  *                 renderRun(text, start, styleLimit,
 152  *                           direction, styleRun[i].style);
 153  *                 if(styleLimit==limit) { break; }
 154  *                 start=styleLimit;
 155  *             }
 156  *         }
 157  *     } else {
 158  *         int styleStart;
 159  *
 160  *         for(i=styleRunCount-1; i>=0; --i) {
 161  *             if(i>0) {
 162  *                 styleStart=styleRun[i-1].limit;
 163  *             } else {
 164  *                 styleStart=0;
 165  *             }
 166  *             if(limit>=styleStart) {
 167  *                 if(styleStart<start) { styleStart=start; }
 168  *                 renderRun(text, styleStart, limit,
 169  *                           direction, styleRun[i].style);
 170  *                 if(styleStart==start) { break; }
 171  *                 limit=styleStart;
 172  *             }
 173  *         }
 174  *     }
 175  * }
 176  *
 177  * // the line object represents text[start..limit-1]
 178  * void renderLine(UBiDi *line, const UChar *text,
 179  *                 int32_t start, int32_t limit,
 180  *                 const StyleRun *styleRuns, int styleRunCount) {
 181  *     UBiDiDirection direction=ubidi_getDirection(line);
 182  *     if(direction!=UBIDI_MIXED) {
 183  *         // unidirectional
 184  *         if(styleRunCount<=1) {
 185  *             renderRun(text, start, limit, direction, styleRuns[0].style);
 186  *         } else {
 187  *             renderDirectionalRun(text, start, limit,
 188  *                                  direction, styleRuns, styleRunCount);
 189  *         }
 190  *     } else {
 191  *         // mixed-directional
 192  *         int32_t count, i, length;
 193  *         UBiDiLevel level;
 194  *
 195  *         count=ubidi_countRuns(para, pErrorCode);
 196  *         if(U_SUCCESS(*pErrorCode)) {
 197  *             if(styleRunCount<=1) {
 198  *                 Style style=styleRuns[0].style;
 199  *
 200  *                 // iterate over directional runs
 201  *                for(i=0; i<count; ++i) {
 202  *                    direction=ubidi_getVisualRun(para, i, &start, &length);
 203  *                     renderRun(text, start, start+length, direction, style);
 204  *                }
 205  *             } else {
 206  *                 int32_t j;
 207  *
 208  *                 // iterate over both directional and style runs
 209  *                 for(i=0; i<count; ++i) {
 210  *                     direction=ubidi_getVisualRun(line, i, &start, &length);
 211  *                     renderDirectionalRun(text, start, start+length,
 212  *                                          direction, styleRuns, styleRunCount);
 213  *                 }
 214  *             }
 215  *         }
 216  *     }
 217  * }
 218  *
 219  *void renderParagraph(const UChar *text, int32_t length,
 220  *                     UBiDiDirection textDirection,
 221  *                      const StyleRun *styleRuns, int styleRunCount,
 222  *                      int lineWidth,
 223  *                      UErrorCode *pErrorCode) {
 224  *     UBiDi *para;
 225  *
 226  *     if(pErrorCode==NULL || U_FAILURE(*pErrorCode) || length<=0) {
 227  *         return;
 228  *     }
 229  *
 230  *     para=ubidi_openSized(length, 0, pErrorCode);
 231  *     if(para==NULL) { return; }
 232  *
 233  *     ubidi_setPara(para, text, length,
 234  *                   textDirection ? UBIDI_DEFAULT_RTL : UBIDI_DEFAULT_LTR,
 235  *                   NULL, pErrorCode);
 236  *     if(U_SUCCESS(*pErrorCode)) {
 237  *         UBiDiLevel paraLevel=1&ubidi_getParaLevel(para);
 238  *         StyleRun styleRun={ length, styleNormal };
 239  *         int width;
 240  *
 241  *         if(styleRuns==NULL || styleRunCount<=0) {
 242  *            styleRunCount=1;
 243  *             styleRuns=&styleRun;
 244  *         }
 245  *
 246  *        // assume styleRuns[styleRunCount-1].limit>=length
 247  *
 248  *         width=getTextWidth(text, 0, length, styleRuns, styleRunCount);
 249  *         if(width<=lineWidth) {
 250  *             // everything fits onto one line
 251  *
 252  *            // prepare rendering a new line from either left or right
 253  *             startLine(paraLevel, width);
 254  *
 255  *             renderLine(para, text, 0, length,
 256  *                        styleRuns, styleRunCount);
 257  *         } else {
 258  *             UBiDi *line;
 259  *
 260  *             // we need to render several lines
 261  *             line=ubidi_openSized(length, 0, pErrorCode);
 262  *             if(line!=NULL) {
 263  *                 int32_t start=0, limit;
 264  *                 int styleRunStart=0, styleRunLimit;
 265  *
 266  *                 for(;;) {
 267  *                     limit=length;
 268  *                     styleRunLimit=styleRunCount;
 269  *                     getLineBreak(text, start, &limit, para,
 270  *                                  styleRuns, styleRunStart, &styleRunLimit,
 271  *                                 &width);
 272  *                     ubidi_setLine(para, start, limit, line, pErrorCode);
 273  *                     if(U_SUCCESS(*pErrorCode)) {
 274  *                         // prepare rendering a new line
 275  *                         // from either left or right
 276  *                         startLine(paraLevel, width);
 277  *
 278  *                         renderLine(line, text, start, limit,
 279  *                                    styleRuns+styleRunStart,
 280  *                                    styleRunLimit-styleRunStart);
 281  *                     }
 282  *                     if(limit==length) { break; }
 283  *                     start=limit;
 284  *                     styleRunStart=styleRunLimit-1;
 285  *                     if(start>=styleRuns[styleRunStart].limit) {
 286  *                         ++styleRunStart;
 287  *                     }
 288  *                 }
 289  *
 290  *                 ubidi_close(line);
 291  *             }
 292  *        }
 293  *    }
 294  *
 295  *     ubidi_close(para);
 296  *}
 297  *\endcode
 298  * </pre>
 299  */
 300
 301 /*DOCXX_TAG*/
 302 /*@{*/
 303
 304 /**
 305  * UBiDiLevel is the type of the level values in this
 306  * BiDi implementation.
 307  * It holds an embedding level and indicates the visual direction
 308  * by its bit&nbsp;0 (even/odd value).<p>
 309  *
 310  * It can also hold non-level values for the
 311  * <code>paraLevel</code> and <code>embeddingLevels</code>
 312  * arguments of <code>ubidi_setPara()</code>; there:
 313  * <ul>
 314  * <li>bit&nbsp;7 of an <code>embeddingLevels[]</code>
 315  * value indicates whether the using application is
 316  * specifying the level of a character to <i>override</i> whatever the
 317  * BiDi implementation would resolve it to.</li>
 318  * <li><code>paraLevel</code> can be set to the
 319  * pseudo-level values <code>UBIDI_DEFAULT_LTR</code>
 320  * and <code>UBIDI_DEFAULT_RTL</code>.</li>
 321  * </ul>
 322  *
 323  * @see ubidi_setPara
 324  *
 325  * <p>The related constants are not real, valid level values.
 326  * <code>UBIDI_DEFAULT_XXX</code> can be used to specify
 327  * a default for the paragraph level for
 328  * when the <code>ubidi_setPara()</code> function
 329  * shall determine it but there is no
 330  * strongly typed character in the input.<p>
 331  *
 332  * Note that the value for <code>UBIDI_DEFAULT_LTR</code> is even
 333  * and the one for <code>UBIDI_DEFAULT_RTL</code> is odd,
 334  * just like with normal LTR and RTL level values -
 335  * these special values are designed that way. Also, the implementation
 336  * assumes that UBIDI_MAX_EXPLICIT_LEVEL is odd.
 337  *
 338  * @see UBIDI_DEFAULT_LTR
 339  * @see UBIDI_DEFAULT_RTL
 340  * @see UBIDI_LEVEL_OVERRIDE
 341  * @see UBIDI_MAX_EXPLICIT_LEVEL
 342  * @stable ICU 2.0
 343  */
 344 typedef uint8_t UBiDiLevel;
 345
 346 /** Paragraph level setting.
 347  *  If there is no strong character, then set the paragraph level to 0 (left-to-right).
 348  * @stable ICU 2.0
 349  */
 350 #define UBIDI_DEFAULT_LTR 0xfe
 351
 352 /** Paragraph level setting.
 353  *  If there is no strong character, then set the paragraph level to 1 (right-to-left).
 354  * @stable ICU 2.0
 355  */
 356 #define UBIDI_DEFAULT_RTL 0xff
 357
 358 /**
 359  * Maximum explicit embedding level.
 360  * (The maximum resolved level can be up to <code>UBIDI_MAX_EXPLICIT_LEVEL+1</code>).
 361  * @stable ICU 2.0
 362  */
 363 #define UBIDI_MAX_EXPLICIT_LEVEL 61
 364
 365 /** Bit flag for level input.
 366  *  Overrides directional properties.
 367  * @stable ICU 2.0
 368  */
 369 #define UBIDI_LEVEL_OVERRIDE 0x80
 370
 371 /**
 372  * <code>UBiDiDirection</code> values indicate the text direction.
 373  * @stable ICU 2.0
 374  */
 375 enum UBiDiDirection {
 376     /** All left-to-right text. This is a 0 value. @stable ICU 2.0 */
 377     UBIDI_LTR,
 378     /** All right-to-left text. This is a 1 value. @stable ICU 2.0 */
 379     UBIDI_RTL,
 380     /** Mixed-directional text. @stable ICU 2.0 */
 381     UBIDI_MIXED
 382 };
 383
 384 /** @stable ICU 2.0 */
 385 typedef enum UBiDiDirection UBiDiDirection;
 386
 387 /**
 388  * Forward declaration of the <code>UBiDi</code> structure for the declaration of
 389  * the API functions. Its fields are implementation-specific.<p>
 390  * This structure holds information about a paragraph of text
 391  * with BiDi-algorithm-related details, or about one line of
 392  * such a paragraph.<p>
 393  * Reordering can be done on a line, or on a paragraph which is
 394  * then interpreted as one single line.
 395  * @stable ICU 2.0
 396  */
 397 struct UBiDi;
 398
 399 /** @stable ICU 2.0 */
 400 typedef struct UBiDi UBiDi;
 401
 402 /**
 403  * Allocate a <code>UBiDi</code> structure.
 404  * Such an object is initially empty. It is assigned
 405  * the BiDi properties of a paragraph by <code>ubidi_setPara()</code>
 406  * or the BiDi properties of a line of a paragraph by
 407  * <code>ubidi_setLine()</code>.<p>
 408  * This object can be reused for as long as it is not deallocated
 409  * by calling <code>ubidi_close()</code>.<p>
 410  * <code>ubidi_set()</code> will allocate additional memory for
 411  * internal structures as necessary.
 412  *
 413  * @return An empty <code>UBiDi</code> object.
 414  * @stable ICU 2.0
 415  */
 416 U_STABLE UBiDi * U_EXPORT2
 417 ubidi_open(void);
 418
 419 /**
 420  * Allocate a <code>UBiDi</code> structure with preallocated memory
 421  * for internal structures.
 422  * This function provides a <code>UBiDi</code> object like <code>ubidi_open()</code>
 423  * with no arguments, but it also preallocates memory for internal structures
 424  * according to the sizings supplied by the caller.<p>
 425  * Subsequent functions will not allocate any more memory, and are thus
 426  * guaranteed not to fail because of lack of memory.<p>
 427  * The preallocation can be limited to some of the internal memory
 428  * by setting some values to 0 here. That means that if, e.g.,
 429  * <code>maxRunCount</code> cannot be reasonably predetermined and should not
 430  * be set to <code>maxLength</code> (the only failproof value) to avoid
 431  * wasting memory, then <code>maxRunCount</code> could be set to 0 here
 432  * and the internal structures that are associated with it will be allocated
 433  * on demand, just like with <code>ubidi_open()</code>.
 434  *
 435  * @param maxLength is the maximum paragraph or line length that internal memory
 436  *        will be preallocated for. An attempt to associate this object with a
 437  *        longer text will fail, unless this value is 0, which leaves the allocation
 438  *        up to the implementation.
 439  *
 440  * @param maxRunCount is the maximum anticipated number of same-level runs
 441  *        that internal memory will be preallocated for. An attempt to access
 442  *        visual runs on an object that was not preallocated for as many runs
 443  *        as the text was actually resolved to will fail,
 444  *        unless this value is 0, which leaves the allocation up to the implementation.<p>
 445  *        The number of runs depends on the actual text and maybe anywhere between
 446  *        1 and <code>maxLength</code>. It is typically small.<p>
 447  *
 448  * @param pErrorCode must be a valid pointer to an error code value,
 449  *        which must not indicate a failure before the function call.
 450  *
 451  * @return An empty <code>UBiDi</code> object with preallocated memory.
 452  * @stable ICU 2.0
 453  */
 454 U_STABLE UBiDi * U_EXPORT2
 455 ubidi_openSized(int32_t maxLength, int32_t maxRunCount, UErrorCode *pErrorCode);
 456
 457 /**
 458  * <code>ubidi_close()</code> must be called to free the memory
 459  * associated with a UBiDi object.<p>
 460  *
 461  * <strong>Important: </strong>
 462  * A parent <code>UBiDi</code> object must not be destroyed or reused if
 463  * it still has children.
 464  * If a <code>UBiDi</code> object is the <i>child</i>
 465  * of another one (its <i>parent</i>), after calling
 466  * <code>ubidi_setLine()</code>, then the child object must
 467  * be destroyed (closed) or reused (by calling
 468  * <code>ubidi_setPara()</code> or <code>ubidi_setLine()</code>)
 469  * before the parent object.
 470  *
 471  * @param pBiDi is a <code>UBiDi</code> object.
 472  *
 473  * @see ubidi_setPara
 474  * @see ubidi_setLine
 475  * @stable ICU 2.0
 476  */
 477 U_STABLE void U_EXPORT2
 478 ubidi_close(UBiDi *pBiDi);
 479
 480 /**
 481  * Modify the operation of the BiDi algorithm such that it
 482  * approximates an "inverse BiDi" algorithm. This function
 483  * must be called before <code>ubidi_setPara()</code>.
 484  *
 485  * <p>The normal operation of the BiDi algorithm as described
 486  * in the Unicode Technical Report is to take text stored in logical
 487  * (keyboard, typing) order and to determine the reordering of it for visual
 488  * rendering.
 489  * Some legacy systems store text in visual order, and for operations
 490  * with standard, Unicode-based algorithms, the text needs to be transformed
 491  * to logical order. This is effectively the inverse algorithm of the
 492  * described BiDi algorithm. Note that there is no standard algorithm for
 493  * this "inverse BiDi" and that the current implementation provides only an
 494  * approximation of "inverse BiDi".</p>
 495  *
 496  * <p>With <code>isInverse</code> set to <code>TRUE</code>,
 497  * this function changes the behavior of some of the subsequent functions
 498  * in a way that they can be used for the inverse BiDi algorithm.
 499  * Specifically, runs of text with numeric characters will be treated in a
 500  * special way and may need to be surrounded with LRM characters when they are
 501  * written in reordered sequence.</p>
 502  *
 503  * <p>Output runs should be retrieved using <code>ubidi_getVisualRun()</code>.
 504  * Since the actual input for "inverse BiDi" is visually ordered text and
 505  * <code>ubidi_getVisualRun()</code> gets the reordered runs, these are actually
 506  * the runs of the logically ordered output.</p>
 507  *
 508  * @param pBiDi is a <code>UBiDi</code> object.
 509  *
 510  * @param isInverse specifies "forward" or "inverse" BiDi operation
 511  *
 512  * @see ubidi_setPara
 513  * @see ubidi_writeReordered
 514  * @stable ICU 2.0
 515  */
 516 U_STABLE void U_EXPORT2
 517 ubidi_setInverse(UBiDi *pBiDi, UBool isInverse);
 518
 519 /**
 520  * Is this BiDi object set to perform the inverse BiDi algorithm?
 521  *
 522  * @param pBiDi is a <code>UBiDi</code> object.
 523  * @return TRUE if the BiDi object set to perform the inverse BiDi algorithm
 524  *
 525  * @see ubidi_setInverse
 526  * @stable ICU 2.0
 527  */
 528 U_STABLE UBool U_EXPORT2
 529 ubidi_isInverse(UBiDi *pBiDi);
 530
 531 /**
 532  * Perform the Unicode BiDi algorithm. It is defined in the
 533  * <a href="http://www.unicode.org/unicode/reports/tr9/">Unicode Standard Anned #9</a>,
 534  * version 13,
 535  * also described in The Unicode Standard, Version 4.0 .<p>
 536  *
 537  * This function takes a single plain text paragraph with or without
 538  * externally specified embedding levels from <i>styled</i> text
 539  * and computes the left-right-directionality of each character.<p>
 540  *
 541  * If the entire paragraph consists of text of only one direction, then
 542  * the function may not perform all the steps described by the algorithm,
 543  * i.e., some levels may not be the same as if all steps were performed.
 544  * This is not relevant for unidirectional text.<br>
 545  * For example, in pure LTR text with numbers the numbers would get
 546  * a resolved level of 2 higher than the surrounding text according to
 547  * the algorithm. This implementation may set all resolved levels to
 548  * the same value in such a case.<p>
 549  *
 550  * The text must be externally split into separate paragraphs (rule P1).
 551  * Paragraph separators (B) should appear at most at the very end.
 552  *
 553  * @param pBiDi A <code>UBiDi</code> object allocated with <code>ubidi_open()</code>
 554  *        which will be set to contain the reordering information,
 555  *        especially the resolved levels for all the characters in <code>text</code>.
 556  *
 557  * @param text is a pointer to the single-paragraph text that the
 558  *        BiDi algorithm will be performed on
 559  *        (step (P1) of the algorithm is performed externally).
 560  *        <strong>The text must be (at least) <code>length</code> long.</strong>
 561  *        This pointer is stored in the UBiDi object and can be retrieved
 562  *        with <code>ubidi_getText()</code>.
 563  *
 564  * @param length is the length of the text; if <code>length==-1</code> then
 565  *        the text must be zero-terminated.
 566  *
 567  * @param paraLevel specifies the default level for the paragraph;
 568  *        it is typically 0 (LTR) or 1 (RTL).
 569  *        If the function shall determine the paragraph level from the text,
 570  *        then <code>paraLevel</code> can be set to
 571  *        either <code>UBIDI_DEFAULT_LTR</code>
 572  *        or <code>UBIDI_DEFAULT_RTL</code>;
 573  *        if there is no strongly typed character, then
 574  *        the desired default is used (0 for LTR or 1 for RTL).
 575  *        Any other value between 0 and <code>UBIDI_MAX_EXPLICIT_LEVEL</code> is also valid,
 576  *        with odd levels indicating RTL.
 577  *
 578  * @param embeddingLevels (in) may be used to preset the embedding and override levels,
 579  *        ignoring characters like LRE and PDF in the text.
 580  *        A level overrides the directional property of its corresponding
 581  *        (same index) character if the level has the
 582  *        <code>UBIDI_LEVEL_OVERRIDE</code> bit set.<p>
 583  *        Except for that bit, it must be
 584  *        <code>paraLevel<=embeddingLevels[]<=UBIDI_MAX_EXPLICIT_LEVEL</code>.<p>
 585  *        <strong>Caution: </strong>A copy of this pointer, not of the levels,
 586  *        will be stored in the <code>UBiDi</code> object;
 587  *        the <code>embeddingLevels</code> array must not be
 588  *        deallocated before the <code>UBiDi</code> structure is destroyed or reused,
 589  *        and the <code>embeddingLevels</code>
 590  *        should not be modified to avoid unexpected results on subsequent BiDi operations.
 591  *        However, the <code>ubidi_setPara()</code> and
 592  *        <code>ubidi_setLine()</code> functions may modify some or all of the levels.<p>
 593  *        After the <code>UBiDi</code> object is reused or destroyed, the caller
 594  *        must take care of the deallocation of the <code>embeddingLevels</code> array.<p>
 595  *        <strong>The <code>embeddingLevels</code> array must be
 596  *        at least <code>length</code> long.</strong>
 597  *
 598  * @param pErrorCode must be a valid pointer to an error code value,
 599  *        which must not indicate a failure before the function call.
 600  * @stable ICU 2.0
 601  */
 602 U_STABLE void U_EXPORT2
 603 ubidi_setPara(UBiDi *pBiDi, const UChar *text, int32_t length,
 604               UBiDiLevel paraLevel, UBiDiLevel *embeddingLevels,
 605               UErrorCode *pErrorCode);
 606
 607 /**
 608  * <code>ubidi_setLine()</code> sets a <code>UBiDi</code> to
 609  * contain the reordering information, especially the resolved levels,
 610  * for all the characters in a line of text. This line of text is
 611  * specified by referring to a <code>UBiDi</code> object representing
 612  * this information for a paragraph of text, and by specifying
 613  * a range of indexes in this paragraph.<p>
 614  * In the new line object, the indexes will range from 0 to <code>limit-start-1</code>.<p>
 615  *
 616  * This is used after calling <code>ubidi_setPara()</code>
 617  * for a paragraph, and after line-breaking on that paragraph.
 618  * It is not necessary if the paragraph is treated as a single line.<p>
 619  *
 620  * After line-breaking, rules (L1) and (L2) for the treatment of
 621  * trailing WS and for reordering are performed on
 622  * a <code>UBiDi</code> object that represents a line.<p>
 623  *
 624  * <strong>Important: </strong><code>pLineBiDi</code> shares data with
 625  * <code>pParaBiDi</code>.
 626  * You must destroy or reuse <code>pLineBiDi</code> before <code>pParaBiDi</code>.
 627  * In other words, you must destroy or reuse the <code>UBiDi</code> object for a line
 628  * before the object for its parent paragraph.<p>
 629  *
 630  * The text pointer that was stored in <code>pParaBiDi</code> is also copied,
 631  * and <code>start</code> is added to it so that it points to the beginning of the
 632  * line for this object.
 633  *
 634  * @param pParaBiDi is the parent paragraph object.
 635  *
 636  * @param start is the line's first index into the paragraph text.
 637  *
 638  * @param limit is just behind the line's last index into the paragraph text
 639  *        (its last index +1).<br>
 640  *        It must be <code>0<=start<=limit<=</code>paragraph length.
 641  *
 642  * @param pLineBiDi is the object that will now represent a line of the paragraph.
 643  *
 644  * @param pErrorCode must be a valid pointer to an error code value,
 645  *        which must not indicate a failure before the function call.
 646  *
 647  * @see ubidi_setPara
 648  * @stable ICU 2.0
 649  */
 650 U_STABLE void U_EXPORT2
 651 ubidi_setLine(const UBiDi *pParaBiDi,
 652               int32_t start, int32_t limit,
 653               UBiDi *pLineBiDi,
 654               UErrorCode *pErrorCode);
 655
 656 /**
 657  * Get the directionality of the text.
 658  *
 659  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
 660  *
 661  * @return A <code>UBIDI_XXX</code> value that indicates if the entire text
 662  *         represented by this object is unidirectional,
 663  *         and which direction, or if it is mixed-directional.
 664  *
 665  * @see UBiDiDirection
 666  * @stable ICU 2.0
 667  */
 668 U_STABLE UBiDiDirection U_EXPORT2
 669 ubidi_getDirection(const UBiDi *pBiDi);
 670
 671 /**
 672  * Get the pointer to the text.
 673  *
 674  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
 675  *
 676  * @return The pointer to the text that the UBiDi object was created for.
 677  *
 678  * @see ubidi_setPara
 679  * @see ubidi_setLine
 680  * @stable ICU 2.0
 681  */
 682 U_STABLE const UChar * U_EXPORT2
 683 ubidi_getText(const UBiDi *pBiDi);
 684
 685 /**
 686  * Get the length of the text.
 687  *
 688  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
 689  *
 690  * @return The length of the text that the UBiDi object was created for.
 691  * @stable ICU 2.0
 692  */
 693 U_STABLE int32_t U_EXPORT2
 694 ubidi_getLength(const UBiDi *pBiDi);
 695
 696 /**
 697  * Get the paragraph level of the text.
 698  *
 699  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
 700  *
 701  * @return The paragraph level.
 702  *
 703  * @see UBiDiLevel
 704  * @stable ICU 2.0
 705  */
 706 U_STABLE UBiDiLevel U_EXPORT2
 707 ubidi_getParaLevel(const UBiDi *pBiDi);
 708
 709 /**
 710  * Get the level for one character.
 711  *
 712  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
 713  *
 714  * @param charIndex the index of a character.
 715  *
 716  * @return The level for the character at charIndex.
 717  *
 718  * @see UBiDiLevel
 719  * @stable ICU 2.0
 720  */
 721 U_STABLE UBiDiLevel U_EXPORT2
 722 ubidi_getLevelAt(const UBiDi *pBiDi, int32_t charIndex);
 723
 724 /**
 725  * Get an array of levels for each character.<p>
 726  *
 727  * Note that this function may allocate memory under some
 728  * circumstances, unlike <code>ubidi_getLevelAt()</code>.
 729  *
 730  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
 731  *
 732  * @param pErrorCode must be a valid pointer to an error code value,
 733  *        which must not indicate a failure before the function call.
 734  *
 735  * @return The levels array for the text,
 736  *         or <code>NULL</code> if an error occurs.
 737  *
 738  * @see UBiDiLevel
 739  * @stable ICU 2.0
 740  */
 741 U_STABLE const UBiDiLevel * U_EXPORT2
 742 ubidi_getLevels(UBiDi *pBiDi, UErrorCode *pErrorCode);
 743
 744 /**
 745  * Get a logical run.
 746  * This function returns information about a run and is used
 747  * to retrieve runs in logical order.<p>
 748  * This is especially useful for line-breaking on a paragraph.
 749  *
 750  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
 751  *
 752  * @param logicalStart is the first character of the run.
 753  *
 754  * @param pLogicalLimit will receive the limit of the run.
 755  *        The l-value that you point to here may be the
 756  *        same expression (variable) as the one for
 757  *        <code>logicalStart</code>.
 758  *        This pointer can be <code>NULL</code> if this
 759  *        value is not necessary.
 760  *
 761  * @param pLevel will receive the level of the run.
 762  *        This pointer can be <code>NULL</code> if this
 763  *        value is not necessary.
 764  * @stable ICU 2.0
 765  */
 766 U_STABLE void U_EXPORT2
 767 ubidi_getLogicalRun(const UBiDi *pBiDi, int32_t logicalStart,
 768                     int32_t *pLogicalLimit, UBiDiLevel *pLevel);
 769
 770 /**
 771  * Get the number of runs.
 772  * This function may invoke the actual reordering on the
 773  * <code>UBiDi</code> object, after <code>ubidi_setPara()</code>
 774  * may have resolved only the levels of the text. Therefore,
 775  * <code>ubidi_countRuns()</code> may have to allocate memory,
 776  * and may fail doing so.
 777  *
 778  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
 779  *
 780  * @param pErrorCode must be a valid pointer to an error code value,
 781  *        which must not indicate a failure before the function call.
 782  *
 783  * @return The number of runs.
 784  * @stable ICU 2.0
 785  */
 786 U_STABLE int32_t U_EXPORT2
 787 ubidi_countRuns(UBiDi *pBiDi, UErrorCode *pErrorCode);
 788
 789 /**
 790  * Get one run's logical start, length, and directionality,
 791  * which can be 0 for LTR or 1 for RTL.
 792  * In an RTL run, the character at the logical start is
 793  * visually on the right of the displayed run.
 794  * The length is the number of characters in the run.<p>
 795  * <code>ubidi_countRuns()</code> should be called
 796  * before the runs are retrieved.
 797  *
 798  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
 799  *
 800  * @param runIndex is the number of the run in visual order, in the
 801  *        range <code>[0..ubidi_countRuns(pBiDi)-1]</code>.
 802  *
 803  * @param pLogicalStart is the first logical character index in the text.
 804  *        The pointer may be <code>NULL</code> if this index is not needed.
 805  *
 806  * @param pLength is the number of characters (at least one) in the run.
 807  *        The pointer may be <code>NULL</code> if this is not needed.
 808  *
 809  * @return the directionality of the run,
 810  *         <code>UBIDI_LTR==0</code> or <code>UBIDI_RTL==1</code>,
 811  *         never <code>UBIDI_MIXED</code>.
 812  *
 813  * @see ubidi_countRuns
 814  *
 815  * Example:
 816  * <pre>
 817  * \code
 818  * int32_t i, count=ubidi_countRuns(pBiDi),
 819  *         logicalStart, visualIndex=0, length;
 820  * for(i=0; i<count; ++i) {
 821  *    if(UBIDI_LTR==ubidi_getVisualRun(pBiDi, i, &logicalStart, &length)) {
 822  *         do { // LTR
 823  *             show_char(text[logicalStart++], visualIndex++);
 824  *         } while(--length>0);
 825  *     } else {
 826  *         logicalStart+=length;  // logicalLimit
 827  *         do { // RTL
 828  *             show_char(text[--logicalStart], visualIndex++);
 829  *         } while(--length>0);
 830  *     }
 831  * }
 832  *\endcode
 833  * </pre>
 834  *
 835  * Note that in right-to-left runs, code like this places
 836  * modifier letters before base characters and second surrogates
 837  * before first ones.
 838  * @stable ICU 2.0
 839  */
 840 U_STABLE UBiDiDirection U_EXPORT2
 841 ubidi_getVisualRun(UBiDi *pBiDi, int32_t runIndex,
 842                    int32_t *pLogicalStart, int32_t *pLength);
 843
 844 /**
 845  * Get the visual position from a logical text position.
 846  * If such a mapping is used many times on the same
 847  * <code>UBiDi</code> object, then calling
 848  * <code>ubidi_getLogicalMap()</code> is more efficient.<p>
 849  *
 850  * Note that in right-to-left runs, this mapping places
 851  * modifier letters before base characters and second surrogates
 852  * before first ones.
 853  *
 854  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
 855  *
 856  * @param logicalIndex is the index of a character in the text.
 857  *
 858  * @param pErrorCode must be a valid pointer to an error code value,
 859  *        which must not indicate a failure before the function call.
 860  *
 861  * @return The visual position of this character.
 862  *
 863  * @see ubidi_getLogicalMap
 864  * @see ubidi_getLogicalIndex
 865  * @stable ICU 2.0
 866  */
 867 U_STABLE int32_t U_EXPORT2
 868 ubidi_getVisualIndex(UBiDi *pBiDi, int32_t logicalIndex, UErrorCode *pErrorCode);
 869
 870 /**
 871  * Get the logical text position from a visual position.
 872  * If such a mapping is used many times on the same
 873  * <code>UBiDi</code> object, then calling
 874  * <code>ubidi_getVisualMap()</code> is more efficient.<p>
 875  *
 876  * This is the inverse function to <code>ubidi_getVisualIndex()</code>.
 877  *
 878  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
 879  *
 880  * @param visualIndex is the visual position of a character.
 881  *
 882  * @param pErrorCode must be a valid pointer to an error code value,
 883  *        which must not indicate a failure before the function call.
 884  *
 885  * @return The index of this character in the text.
 886  *
 887  * @see ubidi_getVisualMap
 888  * @see ubidi_getVisualIndex
 889  * @stable ICU 2.0
 890  */
 891 U_STABLE int32_t U_EXPORT2
 892 ubidi_getLogicalIndex(UBiDi *pBiDi, int32_t visualIndex, UErrorCode *pErrorCode);
 893
 894 /**
 895  * Get a logical-to-visual index map (array) for the characters in the UBiDi
 896  * (paragraph or line) object.
 897  *
 898  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
 899  *
 900  * @param indexMap is a pointer to an array of <code>ubidi_getLength()</code>
 901  *        indexes which will reflect the reordering of the characters.
 902  *        The array does not need to be initialized.<p>
 903  *        The index map will result in <code>indexMap[logicalIndex]==visualIndex</code>.<p>
 904  *
 905  * @param pErrorCode must be a valid pointer to an error code value,
 906  *        which must not indicate a failure before the function call.
 907  *
 908  * @see ubidi_getVisualMap
 909  * @see ubidi_getVisualIndex
 910  * @stable ICU 2.0
 911  */
 912 U_STABLE void U_EXPORT2
 913 ubidi_getLogicalMap(UBiDi *pBiDi, int32_t *indexMap, UErrorCode *pErrorCode);
 914
 915 /**
 916  * Get a visual-to-logical index map (array) for the characters in the UBiDi
 917  * (paragraph or line) object.
 918  *
 919  * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
 920  *
 921  * @param indexMap is a pointer to an array of <code>ubidi_getLength()</code>
 922  *        indexes which will reflect the reordering of the characters.
 923  *        The array does not need to be initialized.<p>
 924  *        The index map will result in <code>indexMap[visualIndex]==logicalIndex</code>.<p>
 925  *
 926  * @param pErrorCode must be a valid pointer to an error code value,
 927  *        which must not indicate a failure before the function call.
 928  *
 929  * @see ubidi_getLogicalMap
 930  * @see ubidi_getLogicalIndex
 931  * @stable ICU 2.0
 932  */
 933 U_STABLE void U_EXPORT2
 934 ubidi_getVisualMap(UBiDi *pBiDi, int32_t *indexMap, UErrorCode *pErrorCode);
 935
 936 /**
 937  * This is a convenience function that does not use a UBiDi object.
 938  * It is intended to be used for when an application has determined the levels
 939  * of objects (character sequences) and just needs to have them reordered (L2).
 940  * This is equivalent to using <code>ubidi_getLogicalMap</code> on a
 941  * <code>UBiDi</code> object.
 942  *
 943  * @param levels is an array with <code>length</code> levels that have been determined by
 944  *        the application.
 945  *
 946  * @param length is the number of levels in the array, or, semantically,
 947  *        the number of objects to be reordered.
 948  *        It must be <code>length>0</code>.
 949  *
 950  * @param indexMap is a pointer to an array of <code>length</code>
 951  *        indexes which will reflect the reordering of the characters.
 952  *        The array does not need to be initialized.<p>
 953  *        The index map will result in <code>indexMap[logicalIndex]==visualIndex</code>.
 954  * @stable ICU 2.0
 955  */
 956 U_STABLE void U_EXPORT2
 957 ubidi_reorderLogical(const UBiDiLevel *levels, int32_t length, int32_t *indexMap);
 958
 959 /**
 960  * This is a convenience function that does not use a UBiDi object.
 961  * It is intended to be used for when an application has determined the levels
 962  * of objects (character sequences) and just needs to have them reordered (L2).
 963  * This is equivalent to using <code>ubidi_getVisualMap</code> on a
 964  * <code>UBiDi</code> object.
 965  *
 966  * @param levels is an array with <code>length</code> levels that have been determined by
 967  *        the application.
 968  *
 969  * @param length is the number of levels in the array, or, semantically,
 970  *        the number of objects to be reordered.
 971  *        It must be <code>length>0</code>.
 972  *
 973  * @param indexMap is a pointer to an array of <code>length</code>
 974  *        indexes which will reflect the reordering of the characters.
 975  *        The array does not need to be initialized.<p>
 976  *        The index map will result in <code>indexMap[visualIndex]==logicalIndex</code>.
 977  * @stable ICU 2.0
 978  */
 979 U_STABLE void U_EXPORT2
 980 ubidi_reorderVisual(const UBiDiLevel *levels, int32_t length, int32_t *indexMap);
 981
 982 /**
 983  * Invert an index map.
 984  * The one-to-one index mapping of the first map is inverted and written to
 985  * the second one.
 986  *
 987  * @param srcMap is an array with <code>length</code> indexes
 988  *        which define the original mapping.
 989  *
 990  * @param destMap is an array with <code>length</code> indexes
 991  *        which will be filled with the inverse mapping.
 992  *
 993  * @param length is the length of each array.
 994  * @stable ICU 2.0
 995  */
 996 U_STABLE void U_EXPORT2
 997 ubidi_invertMap(const int32_t *srcMap, int32_t *destMap, int32_t length);
 998
 999 /** option flags for ubidi_writeReordered() */
1000
1001 /**
1002  * option bit for ubidi_writeReordered():
1003  * keep combining characters after their base characters in RTL runs
1004  *
1005  * @see ubidi_writeReordered
1006  * @stable ICU 2.0
1007  */
1008 #define UBIDI_KEEP_BASE_COMBINING       1
1009
1010 /**
1011  * option bit for ubidi_writeReordered():
1012  * replace characters with the "mirrored" property in RTL runs
1013  * by their mirror-image mappings
1014  *
1015  * @see ubidi_writeReordered
1016  * @stable ICU 2.0
1017  */
1018 #define UBIDI_DO_MIRRORING              2
1019
1020 /**
1021  * option bit for ubidi_writeReordered():
1022  * surround the run with LRMs if necessary;
1023  * this is part of the approximate "inverse BiDi" algorithm
1024  *
1025  * @see ubidi_setInverse
1026  * @see ubidi_writeReordered
1027  * @stable ICU 2.0
1028  */
1029 #define UBIDI_INSERT_LRM_FOR_NUMERIC    4
1030
1031 /**
1032  * option bit for ubidi_writeReordered():
1033  * remove BiDi control characters
1034  * (this does not affect UBIDI_INSERT_LRM_FOR_NUMERIC)
1035  *
1036  * @see ubidi_writeReordered
1037  * @stable ICU 2.0
1038  */
1039 #define UBIDI_REMOVE_BIDI_CONTROLS      8
1040
1041 /**
1042  * option bit for ubidi_writeReordered():
1043  * write the output in reverse order
1044  *
1045  * <p>This has the same effect as calling <code>ubidi_writeReordered()</code>
1046  * first without this option, and then calling
1047  * <code>ubidi_writeReverse()</code> without mirroring.
1048  * Doing this in the same step is faster and avoids a temporary buffer.
1049  * An example for using this option is output to a character terminal that
1050  * is designed for RTL scripts and stores text in reverse order.</p>
1051  *
1052  * @see ubidi_writeReordered
1053  * @stable ICU 2.0
1054  */
1055 #define UBIDI_OUTPUT_REVERSE            16
1056
1057 /**
1058  * Take a <code>UBiDi</code> object containing the reordering
1059  * information for one paragraph or line of text as set by
1060  * <code>ubidi_setPara()</code> or <code>ubidi_setLine()</code> and
1061  * write a reordered string to the destination buffer.
1062  *
1063  * This function preserves the integrity of characters with multiple
1064  * code units and (optionally) modifier letters.
1065  * Characters in RTL runs can be replaced by mirror-image characters
1066  * in the destination buffer. Note that "real" mirroring has
1067  * to be done in a rendering engine by glyph selection
1068  * and that for many "mirrored" characters there are no
1069  * Unicode characters as mirror-image equivalents.
1070  * There are also options to insert or remove BiDi control
1071  * characters; see the description of the <code>destSize</code>
1072  * and <code>options</code> parameters and of the option bit flags.
1073  *
1074  * @see UBIDI_DO_MIRRORING
1075  * @see UBIDI_INSERT_LRM_FOR_NUMERIC
1076  * @see UBIDI_KEEP_BASE_COMBINING
1077  * @see UBIDI_OUTPUT_REVERSE
1078  * @see UBIDI_REMOVE_BIDI_CONTROLS
1079  *
1080  * @param pBiDi A pointer to a <code>UBiDi</code> object that
1081  *              is set by <code>ubidi_setPara()</code> or
1082  *              <code>ubidi_setLine()</code> and contains the reordering
1083  *              information for the text that it was defined for,
1084  *              as well as a pointer to that text.
1085  *              <p>The text was aliased (only the pointer was stored
1086  *              without copying the contents) and must not have been modified
1087  *              since the <code>ubidi_setPara()</code> call.</p>
1088  *
1089  * @param dest A pointer to where the reordered text is to be copied.
1090  *             The source text and <code>dest[destSize]</code>
1091  *             must not overlap.
1092  *
1093  * @param destSize The size of the <code>dest</code> buffer,
1094  *                 in number of UChars.
1095  *                 If the <code>UBIDI_INSERT_LRM_FOR_NUMERIC</code>
1096  *                 option is set, then the destination length could be
1097  *                 as large as
1098  *                 <code>ubidi_getLength(pBiDi)+2*ubidi_countRuns(pBiDi)</code>.
1099  *                 If the <code>UBIDI_REMOVE_BIDI_CONTROLS</code> option
1100  *                 is set, then the destination length may be less than
1101  *                 <code>ubidi_getLength(pBiDi)</code>.
1102  *                 If none of these options is set, then the destination length
1103  *                 will be exactly <code>ubidi_getLength(pBiDi)</code>.
1104  *
1105  * @param options A bit set of options for the reordering that control
1106  *                how the reordered text is written.
1107  *                The options include mirroring the characters on a code
1108  *                point basis and inserting LRM characters, which is used
1109  *                especially for transforming visually stored text
1110  *                to logically stored text (although this is still an
1111  *                imperfect implementation of an "inverse BiDi" algorithm
1112  *                because it uses the "forward BiDi" algorithm at its core).
1113  *                The available options are:
1114  *                <code>#UBIDI_DO_MIRRORING</code>,
1115  *                <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code>,
1116  *                <code>#UBIDI_KEEP_BASE_COMBINING</code>,
1117  *                <code>#UBIDI_OUTPUT_REVERSE</code>,
1118  *                <code>#UBIDI_REMOVE_BIDI_CONTROLS</code>
1119  *
1120  * @param pErrorCode must be a valid pointer to an error code value,
1121  *        which must not indicate a failure before the function call.
1122  *
1123  * @return The length of the output string.
1124  * @stable ICU 2.0
1125  */
1126 U_STABLE int32_t U_EXPORT2
1127 ubidi_writeReordered(UBiDi *pBiDi,
1128                      UChar *dest, int32_t destSize,
1129                      uint16_t options,
1130                      UErrorCode *pErrorCode);
1131
1132 /**
1133  * Reverse a Right-To-Left run of Unicode text.
1134  *
1135  * This function preserves the integrity of characters with multiple
1136  * code units and (optionally) modifier letters.
1137  * Characters can be replaced by mirror-image characters
1138  * in the destination buffer. Note that "real" mirroring has
1139  * to be done in a rendering engine by glyph selection
1140  * and that for many "mirrored" characters there are no
1141  * Unicode characters as mirror-image equivalents.
1142  * There are also options to insert or remove BiDi control
1143  * characters.
1144  *
1145  * This function is the implementation for reversing RTL runs as part
1146  * of <code>ubidi_writeReordered()</code>. For detailed descriptions
1147  * of the parameters, see there.
1148  * Since no BiDi controls are inserted here, the output string length
1149  * will never exceed <code>srcLength</code>.
1150  *
1151  * @see ubidi_writeReordered
1152  *
1153  * @param src A pointer to the RTL run text.
1154  *
1155  * @param srcLength The length of the RTL run.
1156  *
1157  * @param dest A pointer to where the reordered text is to be copied.
1158  *             <code>src[srcLength]</code> and <code>dest[destSize]</code>
1159  *             must not overlap.
1160  *
1161  * @param destSize The size of the <code>dest</code> buffer,
1162  *                 in number of UChars.
1163  *                 If the <code>UBIDI_REMOVE_BIDI_CONTROLS</code> option
1164  *                 is set, then the destination length may be less than
1165  *                 <code>srcLength</code>.
1166  *                 If this option is not set, then the destination length
1167  *                 will be exactly <code>srcLength</code>.
1168  *
1169  * @param options A bit set of options for the reordering that control
1170  *                how the reordered text is written.
1171  *                See the <code>options</code> parameter in <code>ubidi_writeReordered()</code>.
1172  *
1173  * @param pErrorCode must be a valid pointer to an error code value,
1174  *        which must not indicate a failure before the function call.
1175  *
1176  * @return The length of the output string.
1177  * @stable ICU 2.0
1178  */
1179 U_STABLE int32_t U_EXPORT2
1180 ubidi_writeReverse(const UChar *src, int32_t srcLength,
1181                    UChar *dest, int32_t destSize,
1182                    uint16_t options,
1183                    UErrorCode *pErrorCode);
1184
1185 /*#define BIDI_SAMPLE_CODE*/
1186 /*@}*/
1187
1188 #endif