icuSources/common/unicode/ubidi.h

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