1 // Copyright (C) 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-2013, International Business Machines 7 * Corporation and others. All Rights Reserved. 8 * 9 ****************************************************************************** 10 * file name: ubidi.h 11 * encoding: US-ASCII 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 "limit" 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 "runs". 53 * Such a "run" 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 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 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 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 * mimicks 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 * prologue = "<code>abc DE</code>"<br> 1102 * epilogue = none<br> 1103 * main text = "<code>FGH xyz</code>"<br> 1104 * paraLevel = UBIDI_LTR<br> 1105 * display without prologue = "<code>HGF xyz</code>" 1106 * ("HGF" is adjacent to "xyz")<br> 1107 * 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 Anned #9</a>, 1146 * version 13, 1147 * also described in The Unicode Standard, Version 4.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 * Except for that bit, it must be 1200 * <code>paraLevel<=embeddingLevels[]<=UBIDI_MAX_EXPLICIT_LEVEL</code>, 1201 * with one exception: a level of zero may be specified for a paragraph 1202 * separator even if <code>paraLevel>0</code> when multiple paragraphs 1203 * are submitted in the same call to <code>ubidi_setPara()</code>.<br><br> 1204 * <strong>Caution: </strong>A copy of this pointer, not of the levels, 1205 * will be stored in the <code>UBiDi</code> object; 1206 * the <code>embeddingLevels</code> array must not be 1207 * deallocated before the <code>UBiDi</code> structure is destroyed or reused, 1208 * and the <code>embeddingLevels</code> 1209 * should not be modified to avoid unexpected results on subsequent Bidi operations. 1210 * However, the <code>ubidi_setPara()</code> and 1211 * <code>ubidi_setLine()</code> functions may modify some or all of the levels.<br><br> 1212 * After the <code>UBiDi</code> object is reused or destroyed, the caller 1213 * must take care of the deallocation of the <code>embeddingLevels</code> array.<br><br> 1214 * <strong>Note:</strong> the <code>embeddingLevels</code> array must be 1215 * at least <code>length</code> long. 1216 * This pointer can be <code>NULL</code> if this 1217 * value is not necessary. 1218 * 1219 * @param pErrorCode must be a valid pointer to an error code value. 1220 * @stable ICU 2.0 1221 */ 1222 U_STABLE void U_EXPORT2 1223 ubidi_setPara(UBiDi *pBiDi, const UChar *text, int32_t length, 1224 UBiDiLevel paraLevel, UBiDiLevel *embeddingLevels, 1225 UErrorCode *pErrorCode); 1226 1227 /** 1228 * <code>ubidi_setLine()</code> sets a <code>UBiDi</code> to 1229 * contain the reordering information, especially the resolved levels, 1230 * for all the characters in a line of text. This line of text is 1231 * specified by referring to a <code>UBiDi</code> object representing 1232 * this information for a piece of text containing one or more paragraphs, 1233 * and by specifying a range of indexes in this text.<p> 1234 * In the new line object, the indexes will range from 0 to <code>limit-start-1</code>.<p> 1235 * 1236 * This is used after calling <code>ubidi_setPara()</code> 1237 * for a piece of text, and after line-breaking on that text. 1238 * It is not necessary if each paragraph is treated as a single line.<p> 1239 * 1240 * After line-breaking, rules (L1) and (L2) for the treatment of 1241 * trailing WS and for reordering are performed on 1242 * a <code>UBiDi</code> object that represents a line.<p> 1243 * 1244 * <strong>Important: </strong><code>pLineBiDi</code> shares data with 1245 * <code>pParaBiDi</code>. 1246 * You must destroy or reuse <code>pLineBiDi</code> before <code>pParaBiDi</code>. 1247 * In other words, you must destroy or reuse the <code>UBiDi</code> object for a line 1248 * before the object for its parent paragraph.<p> 1249 * 1250 * The text pointer that was stored in <code>pParaBiDi</code> is also copied, 1251 * and <code>start</code> is added to it so that it points to the beginning of the 1252 * line for this object. 1253 * 1254 * @param pParaBiDi is the parent paragraph object. It must have been set 1255 * by a successful call to ubidi_setPara. 1256 * 1257 * @param start is the line's first index into the text. 1258 * 1259 * @param limit is just behind the line's last index into the text 1260 * (its last index +1).<br> 1261 * It must be <code>0<=start<limit<=</code>containing paragraph limit. 1262 * If the specified line crosses a paragraph boundary, the function 1263 * will terminate with error code U_ILLEGAL_ARGUMENT_ERROR. 1264 * 1265 * @param pLineBiDi is the object that will now represent a line of the text. 1266 * 1267 * @param pErrorCode must be a valid pointer to an error code value. 1268 * 1269 * @see ubidi_setPara 1270 * @see ubidi_getProcessedLength 1271 * @stable ICU 2.0 1272 */ 1273 U_STABLE void U_EXPORT2 1274 ubidi_setLine(const UBiDi *pParaBiDi, 1275 int32_t start, int32_t limit, 1276 UBiDi *pLineBiDi, 1277 UErrorCode *pErrorCode); 1278 1279 /** 1280 * Get the directionality of the text. 1281 * 1282 * @param pBiDi is the paragraph or line <code>UBiDi</code> object. 1283 * 1284 * @return a value of <code>UBIDI_LTR</code>, <code>UBIDI_RTL</code> 1285 * or <code>UBIDI_MIXED</code> 1286 * that indicates if the entire text 1287 * represented by this object is unidirectional, 1288 * and which direction, or if it is mixed-directional. 1289 * Note - The value <code>UBIDI_NEUTRAL</code> is never returned from this method. 1290 * 1291 * @see UBiDiDirection 1292 * @stable ICU 2.0 1293 */ 1294 U_STABLE UBiDiDirection U_EXPORT2 1295 ubidi_getDirection(const UBiDi *pBiDi); 1296 1297 /** 1298 * Gets the base direction of the text provided according 1299 * to the Unicode Bidirectional Algorithm. The base direction 1300 * is derived from the first character in the string with bidirectional 1301 * character type L, R, or AL. If the first such character has type L, 1302 * <code>UBIDI_LTR</code> is returned. If the first such character has 1303 * type R or AL, <code>UBIDI_RTL</code> is returned. If the string does 1304 * not contain any character of these types, then 1305 * <code>UBIDI_NEUTRAL</code> is returned. 1306 * 1307 * This is a lightweight function for use when only the base direction 1308 * is needed and no further bidi processing of the text is needed. 1309 * 1310 * @param text is a pointer to the text whose base 1311 * direction is needed. 1312 * Note: the text must be (at least) @c length long. 1313 * 1314 * @param length is the length of the text; 1315 * if <code>length==-1</code> then the text 1316 * must be zero-terminated. 1317 * 1318 * @return <code>UBIDI_LTR</code>, <code>UBIDI_RTL</code>, 1319 * <code>UBIDI_NEUTRAL</code> 1320 * 1321 * @see UBiDiDirection 1322 * @stable ICU 4.6 1323 */ 1324 U_STABLE UBiDiDirection U_EXPORT2 1325 ubidi_getBaseDirection(const UChar *text, int32_t length ); 1326 1327 /** 1328 * Get the pointer to the text. 1329 * 1330 * @param pBiDi is the paragraph or line <code>UBiDi</code> object. 1331 * 1332 * @return The pointer to the text that the UBiDi object was created for. 1333 * 1334 * @see ubidi_setPara 1335 * @see ubidi_setLine 1336 * @stable ICU 2.0 1337 */ 1338 U_STABLE const UChar * U_EXPORT2 1339 ubidi_getText(const UBiDi *pBiDi); 1340 1341 /** 1342 * Get the length of the text. 1343 * 1344 * @param pBiDi is the paragraph or line <code>UBiDi</code> object. 1345 * 1346 * @return The length of the text that the UBiDi object was created for. 1347 * @stable ICU 2.0 1348 */ 1349 U_STABLE int32_t U_EXPORT2 1350 ubidi_getLength(const UBiDi *pBiDi); 1351 1352 /** 1353 * Get the paragraph level of the text. 1354 * 1355 * @param pBiDi is the paragraph or line <code>UBiDi</code> object. 1356 * 1357 * @return The paragraph level. If there are multiple paragraphs, their 1358 * level may vary if the required paraLevel is UBIDI_DEFAULT_LTR or 1359 * UBIDI_DEFAULT_RTL. In that case, the level of the first paragraph 1360 * is returned. 1361 * 1362 * @see UBiDiLevel 1363 * @see ubidi_getParagraph 1364 * @see ubidi_getParagraphByIndex 1365 * @stable ICU 2.0 1366 */ 1367 U_STABLE UBiDiLevel U_EXPORT2 1368 ubidi_getParaLevel(const UBiDi *pBiDi); 1369 1370 /** 1371 * Get the number of paragraphs. 1372 * 1373 * @param pBiDi is the paragraph or line <code>UBiDi</code> object. 1374 * 1375 * @return The number of paragraphs. 1376 * @stable ICU 3.4 1377 */ 1378 U_STABLE int32_t U_EXPORT2 1379 ubidi_countParagraphs(UBiDi *pBiDi); 1380 1381 /** 1382 * Get a paragraph, given a position within the text. 1383 * This function returns information about a paragraph.<br> 1384 * Note: if the paragraph index is known, it is more efficient to 1385 * retrieve the paragraph information using ubidi_getParagraphByIndex().<p> 1386 * 1387 * @param pBiDi is the paragraph or line <code>UBiDi</code> object. 1388 * 1389 * @param charIndex is the index of a character within the text, in the 1390 * range <code>[0..ubidi_getProcessedLength(pBiDi)-1]</code>. 1391 * 1392 * @param pParaStart will receive the index of the first character of the 1393 * paragraph in the text. 1394 * This pointer can be <code>NULL</code> if this 1395 * value is not necessary. 1396 * 1397 * @param pParaLimit will receive the limit of the paragraph. 1398 * The l-value that you point to here may be the 1399 * same expression (variable) as the one for 1400 * <code>charIndex</code>. 1401 * This pointer can be <code>NULL</code> if this 1402 * value is not necessary. 1403 * 1404 * @param pParaLevel will receive the level of the paragraph. 1405 * This pointer can be <code>NULL</code> if this 1406 * value is not necessary. 1407 * 1408 * @param pErrorCode must be a valid pointer to an error code value. 1409 * 1410 * @return The index of the paragraph containing the specified position. 1411 * 1412 * @see ubidi_getProcessedLength 1413 * @stable ICU 3.4 1414 */ 1415 U_STABLE int32_t U_EXPORT2 1416 ubidi_getParagraph(const UBiDi *pBiDi, int32_t charIndex, int32_t *pParaStart, 1417 int32_t *pParaLimit, UBiDiLevel *pParaLevel, 1418 UErrorCode *pErrorCode); 1419 1420 /** 1421 * Get a paragraph, given the index of this paragraph. 1422 * 1423 * This function returns information about a paragraph.<p> 1424 * 1425 * @param pBiDi is the paragraph <code>UBiDi</code> object. 1426 * 1427 * @param paraIndex is the number of the paragraph, in the 1428 * range <code>[0..ubidi_countParagraphs(pBiDi)-1]</code>. 1429 * 1430 * @param pParaStart will receive the index of the first character of the 1431 * paragraph in the text. 1432 * This pointer can be <code>NULL</code> if this 1433 * value is not necessary. 1434 * 1435 * @param pParaLimit will receive the limit of the paragraph. 1436 * This pointer can be <code>NULL</code> if this 1437 * value is not necessary. 1438 * 1439 * @param pParaLevel will receive the level of the paragraph. 1440 * This pointer can be <code>NULL</code> if this 1441 * value is not necessary. 1442 * 1443 * @param pErrorCode must be a valid pointer to an error code value. 1444 * 1445 * @stable ICU 3.4 1446 */ 1447 U_STABLE void U_EXPORT2 1448 ubidi_getParagraphByIndex(const UBiDi *pBiDi, int32_t paraIndex, 1449 int32_t *pParaStart, int32_t *pParaLimit, 1450 UBiDiLevel *pParaLevel, UErrorCode *pErrorCode); 1451 1452 /** 1453 * Get the level for one character. 1454 * 1455 * @param pBiDi is the paragraph or line <code>UBiDi</code> object. 1456 * 1457 * @param charIndex the index of a character. It must be in the range 1458 * [0..ubidi_getProcessedLength(pBiDi)]. 1459 * 1460 * @return The level for the character at charIndex (0 if charIndex is not 1461 * in the valid range). 1462 * 1463 * @see UBiDiLevel 1464 * @see ubidi_getProcessedLength 1465 * @stable ICU 2.0 1466 */ 1467 U_STABLE UBiDiLevel U_EXPORT2 1468 ubidi_getLevelAt(const UBiDi *pBiDi, int32_t charIndex); 1469 1470 /** 1471 * Get an array of levels for each character.<p> 1472 * 1473 * Note that this function may allocate memory under some 1474 * circumstances, unlike <code>ubidi_getLevelAt()</code>. 1475 * 1476 * @param pBiDi is the paragraph or line <code>UBiDi</code> object, whose 1477 * text length must be strictly positive. 1478 * 1479 * @param pErrorCode must be a valid pointer to an error code value. 1480 * 1481 * @return The levels array for the text, 1482 * or <code>NULL</code> if an error occurs. 1483 * 1484 * @see UBiDiLevel 1485 * @see ubidi_getProcessedLength 1486 * @stable ICU 2.0 1487 */ 1488 U_STABLE const UBiDiLevel * U_EXPORT2 1489 ubidi_getLevels(UBiDi *pBiDi, UErrorCode *pErrorCode); 1490 1491 /** 1492 * Get a logical run. 1493 * This function returns information about a run and is used 1494 * to retrieve runs in logical order.<p> 1495 * This is especially useful for line-breaking on a paragraph. 1496 * 1497 * @param pBiDi is the paragraph or line <code>UBiDi</code> object. 1498 * 1499 * @param logicalPosition is a logical position within the source text. 1500 * 1501 * @param pLogicalLimit will receive the limit of the corresponding run. 1502 * The l-value that you point to here may be the 1503 * same expression (variable) as the one for 1504 * <code>logicalPosition</code>. 1505 * This pointer can be <code>NULL</code> if this 1506 * value is not necessary. 1507 * 1508 * @param pLevel will receive the level of the corresponding run. 1509 * This pointer can be <code>NULL</code> if this 1510 * value is not necessary. 1511 * 1512 * @see ubidi_getProcessedLength 1513 * @stable ICU 2.0 1514 */ 1515 U_STABLE void U_EXPORT2 1516 ubidi_getLogicalRun(const UBiDi *pBiDi, int32_t logicalPosition, 1517 int32_t *pLogicalLimit, UBiDiLevel *pLevel); 1518 1519 /** 1520 * Get the number of runs. 1521 * This function may invoke the actual reordering on the 1522 * <code>UBiDi</code> object, after <code>ubidi_setPara()</code> 1523 * may have resolved only the levels of the text. Therefore, 1524 * <code>ubidi_countRuns()</code> may have to allocate memory, 1525 * and may fail doing so. 1526 * 1527 * @param pBiDi is the paragraph or line <code>UBiDi</code> object. 1528 * 1529 * @param pErrorCode must be a valid pointer to an error code value. 1530 * 1531 * @return The number of runs. 1532 * @stable ICU 2.0 1533 */ 1534 U_STABLE int32_t U_EXPORT2 1535 ubidi_countRuns(UBiDi *pBiDi, UErrorCode *pErrorCode); 1536 1537 /** 1538 * Get one run's logical start, length, and directionality, 1539 * which can be 0 for LTR or 1 for RTL. 1540 * In an RTL run, the character at the logical start is 1541 * visually on the right of the displayed run. 1542 * The length is the number of characters in the run.<p> 1543 * <code>ubidi_countRuns()</code> should be called 1544 * before the runs are retrieved. 1545 * 1546 * @param pBiDi is the paragraph or line <code>UBiDi</code> object. 1547 * 1548 * @param runIndex is the number of the run in visual order, in the 1549 * range <code>[0..ubidi_countRuns(pBiDi)-1]</code>. 1550 * 1551 * @param pLogicalStart is the first logical character index in the text. 1552 * The pointer may be <code>NULL</code> if this index is not needed. 1553 * 1554 * @param pLength is the number of characters (at least one) in the run. 1555 * The pointer may be <code>NULL</code> if this is not needed. 1556 * 1557 * @return the directionality of the run, 1558 * <code>UBIDI_LTR==0</code> or <code>UBIDI_RTL==1</code>, 1559 * never <code>UBIDI_MIXED</code>, 1560 * never <code>UBIDI_NEUTRAL</code>. 1561 * 1562 * @see ubidi_countRuns 1563 * 1564 * Example: 1565 * <pre> 1566 * \code 1567 * int32_t i, count=ubidi_countRuns(pBiDi), 1568 * logicalStart, visualIndex=0, length; 1569 * for(i=0; i<count; ++i) { 1570 * if(UBIDI_LTR==ubidi_getVisualRun(pBiDi, i, &logicalStart, &length)) { 1571 * do { // LTR 1572 * show_char(text[logicalStart++], visualIndex++); 1573 * } while(--length>0); 1574 * } else { 1575 * logicalStart+=length; // logicalLimit 1576 * do { // RTL 1577 * show_char(text[--logicalStart], visualIndex++); 1578 * } while(--length>0); 1579 * } 1580 * } 1581 *\endcode 1582 * </pre> 1583 * 1584 * Note that in right-to-left runs, code like this places 1585 * second surrogates before first ones (which is generally a bad idea) 1586 * and combining characters before base characters. 1587 * <p> 1588 * Use of <code>ubidi_writeReordered()</code>, optionally with the 1589 * <code>#UBIDI_KEEP_BASE_COMBINING</code> option, can be considered in order 1590 * to avoid these issues. 1591 * @stable ICU 2.0 1592 */ 1593 U_STABLE UBiDiDirection U_EXPORT2 1594 ubidi_getVisualRun(UBiDi *pBiDi, int32_t runIndex, 1595 int32_t *pLogicalStart, int32_t *pLength); 1596 1597 /** 1598 * Get the visual position from a logical text position. 1599 * If such a mapping is used many times on the same 1600 * <code>UBiDi</code> object, then calling 1601 * <code>ubidi_getLogicalMap()</code> is more efficient.<p> 1602 * 1603 * The value returned may be <code>#UBIDI_MAP_NOWHERE</code> if there is no 1604 * visual position because the corresponding text character is a Bidi control 1605 * removed from output by the option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code>. 1606 * <p> 1607 * When the visual output is altered by using options of 1608 * <code>ubidi_writeReordered()</code> such as <code>UBIDI_INSERT_LRM_FOR_NUMERIC</code>, 1609 * <code>UBIDI_KEEP_BASE_COMBINING</code>, <code>UBIDI_OUTPUT_REVERSE</code>, 1610 * <code>UBIDI_REMOVE_BIDI_CONTROLS</code>, the visual position returned may not 1611 * be correct. It is advised to use, when possible, reordering options 1612 * such as <code>UBIDI_OPTION_INSERT_MARKS</code> and <code>UBIDI_OPTION_REMOVE_CONTROLS</code>. 1613 * <p> 1614 * Note that in right-to-left runs, this mapping places 1615 * second surrogates before first ones (which is generally a bad idea) 1616 * and combining characters before base characters. 1617 * Use of <code>ubidi_writeReordered()</code>, optionally with the 1618 * <code>#UBIDI_KEEP_BASE_COMBINING</code> option can be considered instead 1619 * of using the mapping, in order to avoid these issues. 1620 * 1621 * @param pBiDi is the paragraph or line <code>UBiDi</code> object. 1622 * 1623 * @param logicalIndex is the index of a character in the text. 1624 * 1625 * @param pErrorCode must be a valid pointer to an error code value. 1626 * 1627 * @return The visual position of this character. 1628 * 1629 * @see ubidi_getLogicalMap 1630 * @see ubidi_getLogicalIndex 1631 * @see ubidi_getProcessedLength 1632 * @stable ICU 2.0 1633 */ 1634 U_STABLE int32_t U_EXPORT2 1635 ubidi_getVisualIndex(UBiDi *pBiDi, int32_t logicalIndex, UErrorCode *pErrorCode); 1636 1637 /** 1638 * Get the logical text position from a visual position. 1639 * If such a mapping is used many times on the same 1640 * <code>UBiDi</code> object, then calling 1641 * <code>ubidi_getVisualMap()</code> is more efficient.<p> 1642 * 1643 * The value returned may be <code>#UBIDI_MAP_NOWHERE</code> if there is no 1644 * logical position because the corresponding text character is a Bidi mark 1645 * inserted in the output by option <code>#UBIDI_OPTION_INSERT_MARKS</code>. 1646 * <p> 1647 * This is the inverse function to <code>ubidi_getVisualIndex()</code>. 1648 * <p> 1649 * When the visual output is altered by using options of 1650 * <code>ubidi_writeReordered()</code> such as <code>UBIDI_INSERT_LRM_FOR_NUMERIC</code>, 1651 * <code>UBIDI_KEEP_BASE_COMBINING</code>, <code>UBIDI_OUTPUT_REVERSE</code>, 1652 * <code>UBIDI_REMOVE_BIDI_CONTROLS</code>, the logical position returned may not 1653 * be correct. It is advised to use, when possible, reordering options 1654 * such as <code>UBIDI_OPTION_INSERT_MARKS</code> and <code>UBIDI_OPTION_REMOVE_CONTROLS</code>. 1655 * 1656 * @param pBiDi is the paragraph or line <code>UBiDi</code> object. 1657 * 1658 * @param visualIndex is the visual position of a character. 1659 * 1660 * @param pErrorCode must be a valid pointer to an error code value. 1661 * 1662 * @return The index of this character in the text. 1663 * 1664 * @see ubidi_getVisualMap 1665 * @see ubidi_getVisualIndex 1666 * @see ubidi_getResultLength 1667 * @stable ICU 2.0 1668 */ 1669 U_STABLE int32_t U_EXPORT2 1670 ubidi_getLogicalIndex(UBiDi *pBiDi, int32_t visualIndex, UErrorCode *pErrorCode); 1671 1672 /** 1673 * Get a logical-to-visual index map (array) for the characters in the UBiDi 1674 * (paragraph or line) object. 1675 * <p> 1676 * Some values in the map may be <code>#UBIDI_MAP_NOWHERE</code> if the 1677 * corresponding text characters are Bidi controls removed from the visual 1678 * output by the option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code>. 1679 * <p> 1680 * When the visual output is altered by using options of 1681 * <code>ubidi_writeReordered()</code> such as <code>UBIDI_INSERT_LRM_FOR_NUMERIC</code>, 1682 * <code>UBIDI_KEEP_BASE_COMBINING</code>, <code>UBIDI_OUTPUT_REVERSE</code>, 1683 * <code>UBIDI_REMOVE_BIDI_CONTROLS</code>, the visual positions returned may not 1684 * be correct. It is advised to use, when possible, reordering options 1685 * such as <code>UBIDI_OPTION_INSERT_MARKS</code> and <code>UBIDI_OPTION_REMOVE_CONTROLS</code>. 1686 * <p> 1687 * Note that in right-to-left runs, this mapping places 1688 * second surrogates before first ones (which is generally a bad idea) 1689 * and combining characters before base characters. 1690 * Use of <code>ubidi_writeReordered()</code>, optionally with the 1691 * <code>#UBIDI_KEEP_BASE_COMBINING</code> option can be considered instead 1692 * of using the mapping, in order to avoid these issues. 1693 * 1694 * @param pBiDi is the paragraph or line <code>UBiDi</code> object. 1695 * 1696 * @param indexMap is a pointer to an array of <code>ubidi_getProcessedLength()</code> 1697 * indexes which will reflect the reordering of the characters. 1698 * If option <code>#UBIDI_OPTION_INSERT_MARKS</code> is set, the number 1699 * of elements allocated in <code>indexMap</code> must be no less than 1700 * <code>ubidi_getResultLength()</code>. 1701 * The array does not need to be initialized.<br><br> 1702 * The index map will result in <code>indexMap[logicalIndex]==visualIndex</code>. 1703 * 1704 * @param pErrorCode must be a valid pointer to an error code value. 1705 * 1706 * @see ubidi_getVisualMap 1707 * @see ubidi_getVisualIndex 1708 * @see ubidi_getProcessedLength 1709 * @see ubidi_getResultLength 1710 * @stable ICU 2.0 1711 */ 1712 U_STABLE void U_EXPORT2 1713 ubidi_getLogicalMap(UBiDi *pBiDi, int32_t *indexMap, UErrorCode *pErrorCode); 1714 1715 /** 1716 * Get a visual-to-logical index map (array) for the characters in the UBiDi 1717 * (paragraph or line) object. 1718 * <p> 1719 * Some values in the map may be <code>#UBIDI_MAP_NOWHERE</code> if the 1720 * corresponding text characters are Bidi marks inserted in the visual output 1721 * by the option <code>#UBIDI_OPTION_INSERT_MARKS</code>. 1722 * <p> 1723 * When the visual output is altered by using options of 1724 * <code>ubidi_writeReordered()</code> such as <code>UBIDI_INSERT_LRM_FOR_NUMERIC</code>, 1725 * <code>UBIDI_KEEP_BASE_COMBINING</code>, <code>UBIDI_OUTPUT_REVERSE</code>, 1726 * <code>UBIDI_REMOVE_BIDI_CONTROLS</code>, the logical positions returned may not 1727 * be correct. It is advised to use, when possible, reordering options 1728 * such as <code>UBIDI_OPTION_INSERT_MARKS</code> and <code>UBIDI_OPTION_REMOVE_CONTROLS</code>. 1729 * 1730 * @param pBiDi is the paragraph or line <code>UBiDi</code> object. 1731 * 1732 * @param indexMap is a pointer to an array of <code>ubidi_getResultLength()</code> 1733 * indexes which will reflect the reordering of the characters. 1734 * If option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code> is set, the number 1735 * of elements allocated in <code>indexMap</code> must be no less than 1736 * <code>ubidi_getProcessedLength()</code>. 1737 * The array does not need to be initialized.<br><br> 1738 * The index map will result in <code>indexMap[visualIndex]==logicalIndex</code>. 1739 * 1740 * @param pErrorCode must be a valid pointer to an error code value. 1741 * 1742 * @see ubidi_getLogicalMap 1743 * @see ubidi_getLogicalIndex 1744 * @see ubidi_getProcessedLength 1745 * @see ubidi_getResultLength 1746 * @stable ICU 2.0 1747 */ 1748 U_STABLE void U_EXPORT2 1749 ubidi_getVisualMap(UBiDi *pBiDi, int32_t *indexMap, UErrorCode *pErrorCode); 1750 1751 /** 1752 * This is a convenience function that does not use a UBiDi object. 1753 * It is intended to be used for when an application has determined the levels 1754 * of objects (character sequences) and just needs to have them reordered (L2). 1755 * This is equivalent to using <code>ubidi_getLogicalMap()</code> on a 1756 * <code>UBiDi</code> object. 1757 * 1758 * @param levels is an array with <code>length</code> levels that have been determined by 1759 * the application. 1760 * 1761 * @param length is the number of levels in the array, or, semantically, 1762 * the number of objects to be reordered. 1763 * It must be <code>length>0</code>. 1764 * 1765 * @param indexMap is a pointer to an array of <code>length</code> 1766 * indexes which will reflect the reordering of the characters. 1767 * The array does not need to be initialized.<p> 1768 * The index map will result in <code>indexMap[logicalIndex]==visualIndex</code>. 1769 * @stable ICU 2.0 1770 */ 1771 U_STABLE void U_EXPORT2 1772 ubidi_reorderLogical(const UBiDiLevel *levels, int32_t length, int32_t *indexMap); 1773 1774 /** 1775 * This is a convenience function that does not use a UBiDi object. 1776 * It is intended to be used for when an application has determined the levels 1777 * of objects (character sequences) and just needs to have them reordered (L2). 1778 * This is equivalent to using <code>ubidi_getVisualMap()</code> on a 1779 * <code>UBiDi</code> object. 1780 * 1781 * @param levels is an array with <code>length</code> levels that have been determined by 1782 * the application. 1783 * 1784 * @param length is the number of levels in the array, or, semantically, 1785 * the number of objects to be reordered. 1786 * It must be <code>length>0</code>. 1787 * 1788 * @param indexMap is a pointer to an array of <code>length</code> 1789 * indexes which will reflect the reordering of the characters. 1790 * The array does not need to be initialized.<p> 1791 * The index map will result in <code>indexMap[visualIndex]==logicalIndex</code>. 1792 * @stable ICU 2.0 1793 */ 1794 U_STABLE void U_EXPORT2 1795 ubidi_reorderVisual(const UBiDiLevel *levels, int32_t length, int32_t *indexMap); 1796 1797 /** 1798 * Invert an index map. 1799 * The index mapping of the first map is inverted and written to 1800 * the second one. 1801 * 1802 * @param srcMap is an array with <code>length</code> elements 1803 * which defines the original mapping from a source array containing 1804 * <code>length</code> elements to a destination array. 1805 * Some elements of the source array may have no mapping in the 1806 * destination array. In that case, their value will be 1807 * the special value <code>UBIDI_MAP_NOWHERE</code>. 1808 * All elements must be >=0 or equal to <code>UBIDI_MAP_NOWHERE</code>. 1809 * Some elements may have a value >= <code>length</code>, if the 1810 * destination array has more elements than the source array. 1811 * There must be no duplicate indexes (two or more elements with the 1812 * same value except <code>UBIDI_MAP_NOWHERE</code>). 1813 * 1814 * @param destMap is an array with a number of elements equal to 1 + the highest 1815 * value in <code>srcMap</code>. 1816 * <code>destMap</code> will be filled with the inverse mapping. 1817 * If element with index i in <code>srcMap</code> has a value k different 1818 * from <code>UBIDI_MAP_NOWHERE</code>, this means that element i of 1819 * the source array maps to element k in the destination array. 1820 * The inverse map will have value i in its k-th element. 1821 * For all elements of the destination array which do not map to 1822 * an element in the source array, the corresponding element in the 1823 * inverse map will have a value equal to <code>UBIDI_MAP_NOWHERE</code>. 1824 * 1825 * @param length is the length of each array. 1826 * @see UBIDI_MAP_NOWHERE 1827 * @stable ICU 2.0 1828 */ 1829 U_STABLE void U_EXPORT2 1830 ubidi_invertMap(const int32_t *srcMap, int32_t *destMap, int32_t length); 1831 1832 /** option flags for ubidi_writeReordered() */ 1833 1834 /** 1835 * option bit for ubidi_writeReordered(): 1836 * keep combining characters after their base characters in RTL runs 1837 * 1838 * @see ubidi_writeReordered 1839 * @stable ICU 2.0 1840 */ 1841 #define UBIDI_KEEP_BASE_COMBINING 1 1842 1843 /** 1844 * option bit for ubidi_writeReordered(): 1845 * replace characters with the "mirrored" property in RTL runs 1846 * by their mirror-image mappings 1847 * 1848 * @see ubidi_writeReordered 1849 * @stable ICU 2.0 1850 */ 1851 #define UBIDI_DO_MIRRORING 2 1852 1853 /** 1854 * option bit for ubidi_writeReordered(): 1855 * surround the run with LRMs if necessary; 1856 * this is part of the approximate "inverse Bidi" algorithm 1857 * 1858 * <p>This option does not imply corresponding adjustment of the index 1859 * mappings.</p> 1860 * 1861 * @see ubidi_setInverse 1862 * @see ubidi_writeReordered 1863 * @stable ICU 2.0 1864 */ 1865 #define UBIDI_INSERT_LRM_FOR_NUMERIC 4 1866 1867 /** 1868 * option bit for ubidi_writeReordered(): 1869 * remove Bidi control characters 1870 * (this does not affect #UBIDI_INSERT_LRM_FOR_NUMERIC) 1871 * 1872 * <p>This option does not imply corresponding adjustment of the index 1873 * mappings.</p> 1874 * 1875 * @see ubidi_writeReordered 1876 * @stable ICU 2.0 1877 */ 1878 #define UBIDI_REMOVE_BIDI_CONTROLS 8 1879 1880 /** 1881 * option bit for ubidi_writeReordered(): 1882 * write the output in reverse order 1883 * 1884 * <p>This has the same effect as calling <code>ubidi_writeReordered()</code> 1885 * first without this option, and then calling 1886 * <code>ubidi_writeReverse()</code> without mirroring. 1887 * Doing this in the same step is faster and avoids a temporary buffer. 1888 * An example for using this option is output to a character terminal that 1889 * is designed for RTL scripts and stores text in reverse order.</p> 1890 * 1891 * @see ubidi_writeReordered 1892 * @stable ICU 2.0 1893 */ 1894 #define UBIDI_OUTPUT_REVERSE 16 1895 1896 /** 1897 * Get the length of the source text processed by the last call to 1898 * <code>ubidi_setPara()</code>. This length may be different from the length 1899 * of the source text if option <code>#UBIDI_OPTION_STREAMING</code> 1900 * has been set. 1901 * <br> 1902 * Note that whenever the length of the text affects the execution or the 1903 * result of a function, it is the processed length which must be considered, 1904 * except for <code>ubidi_setPara</code> (which receives unprocessed source 1905 * text) and <code>ubidi_getLength</code> (which returns the original length 1906 * of the source text).<br> 1907 * In particular, the processed length is the one to consider in the following 1908 * cases: 1909 * <ul> 1910 * <li>maximum value of the <code>limit</code> argument of 1911 * <code>ubidi_setLine</code></li> 1912 * <li>maximum value of the <code>charIndex</code> argument of 1913 * <code>ubidi_getParagraph</code></li> 1914 * <li>maximum value of the <code>charIndex</code> argument of 1915 * <code>ubidi_getLevelAt</code></li> 1916 * <li>number of elements in the array returned by <code>ubidi_getLevels</code></li> 1917 * <li>maximum value of the <code>logicalStart</code> argument of 1918 * <code>ubidi_getLogicalRun</code></li> 1919 * <li>maximum value of the <code>logicalIndex</code> argument of 1920 * <code>ubidi_getVisualIndex</code></li> 1921 * <li>number of elements filled in the <code>*indexMap</code> argument of 1922 * <code>ubidi_getLogicalMap</code></li> 1923 * <li>length of text processed by <code>ubidi_writeReordered</code></li> 1924 * </ul> 1925 * 1926 * @param pBiDi is the paragraph <code>UBiDi</code> object. 1927 * 1928 * @return The length of the part of the source text processed by 1929 * the last call to <code>ubidi_setPara</code>. 1930 * @see ubidi_setPara 1931 * @see UBIDI_OPTION_STREAMING 1932 * @stable ICU 3.6 1933 */ 1934 U_STABLE int32_t U_EXPORT2 1935 ubidi_getProcessedLength(const UBiDi *pBiDi); 1936 1937 /** 1938 * Get the length of the reordered text resulting from the last call to 1939 * <code>ubidi_setPara()</code>. This length may be different from the length 1940 * of the source text if option <code>#UBIDI_OPTION_INSERT_MARKS</code> 1941 * or option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code> has been set. 1942 * <br> 1943 * This resulting length is the one to consider in the following cases: 1944 * <ul> 1945 * <li>maximum value of the <code>visualIndex</code> argument of 1946 * <code>ubidi_getLogicalIndex</code></li> 1947 * <li>number of elements of the <code>*indexMap</code> argument of 1948 * <code>ubidi_getVisualMap</code></li> 1949 * </ul> 1950 * Note that this length stays identical to the source text length if 1951 * Bidi marks are inserted or removed using option bits of 1952 * <code>ubidi_writeReordered</code>, or if option 1953 * <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code> has been set. 1954 * 1955 * @param pBiDi is the paragraph <code>UBiDi</code> object. 1956 * 1957 * @return The length of the reordered text resulting from 1958 * the last call to <code>ubidi_setPara</code>. 1959 * @see ubidi_setPara 1960 * @see UBIDI_OPTION_INSERT_MARKS 1961 * @see UBIDI_OPTION_REMOVE_CONTROLS 1962 * @stable ICU 3.6 1963 */ 1964 U_STABLE int32_t U_EXPORT2 1965 ubidi_getResultLength(const UBiDi *pBiDi); 1966 1967 U_CDECL_BEGIN 1968 1969 #ifndef U_HIDE_DEPRECATED_API 1970 /** 1971 * Value returned by <code>UBiDiClassCallback</code> callbacks when 1972 * there is no need to override the standard Bidi class for a given code point. 1973 * 1974 * This constant is deprecated; use u_getIntPropertyMaxValue(UCHAR_BIDI_CLASS)+1 instead. 1975 * 1976 * @see UBiDiClassCallback 1977 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. 1978 */ 1979 #define U_BIDI_CLASS_DEFAULT U_CHAR_DIRECTION_COUNT 1980 #endif // U_HIDE_DEPRECATED_API 1981 1982 /** 1983 * Callback type declaration for overriding default Bidi class values with 1984 * custom ones. 1985 * <p>Usually, the function pointer will be propagated to a <code>UBiDi</code> 1986 * object by calling the <code>ubidi_setClassCallback()</code> function; 1987 * then the callback will be invoked by the UBA implementation any time the 1988 * class of a character is to be determined.</p> 1989 * 1990 * @param context is a pointer to the callback private data. 1991 * 1992 * @param c is the code point to get a Bidi class for. 1993 * 1994 * @return The directional property / Bidi class for the given code point 1995 * <code>c</code> if the default class has been overridden, or 1996 * <code>#U_BIDI_CLASS_DEFAULT=u_getIntPropertyMaxValue(UCHAR_BIDI_CLASS)+1</code> 1997 * if the standard Bidi class value for <code>c</code> is to be used. 1998 * @see ubidi_setClassCallback 1999 * @see ubidi_getClassCallback 2000 * @stable ICU 3.6 2001 */ 2002 typedef UCharDirection U_CALLCONV 2003 UBiDiClassCallback(const void *context, UChar32 c); 2004 2005 U_CDECL_END 2006 2007 /** 2008 * Retrieve the Bidi class for a given code point. 2009 * <p>If a <code>#UBiDiClassCallback</code> callback is defined and returns a 2010 * value other than <code>#U_BIDI_CLASS_DEFAULT=u_getIntPropertyMaxValue(UCHAR_BIDI_CLASS)+1</code>, 2011 * that value is used; otherwise the default class determination mechanism is invoked.</p> 2012 * 2013 * @param pBiDi is the paragraph <code>UBiDi</code> object. 2014 * 2015 * @param c is the code point whose Bidi class must be retrieved. 2016 * 2017 * @return The Bidi class for character <code>c</code> based 2018 * on the given <code>pBiDi</code> instance. 2019 * @see UBiDiClassCallback 2020 * @stable ICU 3.6 2021 */ 2022 U_STABLE UCharDirection U_EXPORT2 2023 ubidi_getCustomizedClass(UBiDi *pBiDi, UChar32 c); 2024 2025 /** 2026 * Set the callback function and callback data used by the UBA 2027 * implementation for Bidi class determination. 2028 * <p>This may be useful for assigning Bidi classes to PUA characters, or 2029 * for special application needs. For instance, an application may want to 2030 * handle all spaces like L or R characters (according to the base direction) 2031 * when creating the visual ordering of logical lines which are part of a report 2032 * organized in columns: there should not be interaction between adjacent 2033 * cells.<p> 2034 * 2035 * @param pBiDi is the paragraph <code>UBiDi</code> object. 2036 * 2037 * @param newFn is the new callback function pointer. 2038 * 2039 * @param newContext is the new callback context pointer. This can be NULL. 2040 * 2041 * @param oldFn fillin: Returns the old callback function pointer. This can be 2042 * NULL. 2043 * 2044 * @param oldContext fillin: Returns the old callback's context. This can be 2045 * NULL. 2046 * 2047 * @param pErrorCode must be a valid pointer to an error code value. 2048 * 2049 * @see ubidi_getClassCallback 2050 * @stable ICU 3.6 2051 */ 2052 U_STABLE void U_EXPORT2 2053 ubidi_setClassCallback(UBiDi *pBiDi, UBiDiClassCallback *newFn, 2054 const void *newContext, UBiDiClassCallback **oldFn, 2055 const void **oldContext, UErrorCode *pErrorCode); 2056 2057 /** 2058 * Get the current callback function used for Bidi class determination. 2059 * 2060 * @param pBiDi is the paragraph <code>UBiDi</code> object. 2061 * 2062 * @param fn fillin: Returns the callback function pointer. 2063 * 2064 * @param context fillin: Returns the callback's private context. 2065 * 2066 * @see ubidi_setClassCallback 2067 * @stable ICU 3.6 2068 */ 2069 U_STABLE void U_EXPORT2 2070 ubidi_getClassCallback(UBiDi *pBiDi, UBiDiClassCallback **fn, const void **context); 2071 2072 /** 2073 * Take a <code>UBiDi</code> object containing the reordering 2074 * information for a piece of text (one or more paragraphs) set by 2075 * <code>ubidi_setPara()</code> or for a line of text set by 2076 * <code>ubidi_setLine()</code> and write a reordered string to the 2077 * destination buffer. 2078 * 2079 * This function preserves the integrity of characters with multiple 2080 * code units and (optionally) combining characters. 2081 * Characters in RTL runs can be replaced by mirror-image characters 2082 * in the destination buffer. Note that "real" mirroring has 2083 * to be done in a rendering engine by glyph selection 2084 * and that for many "mirrored" characters there are no 2085 * Unicode characters as mirror-image equivalents. 2086 * There are also options to insert or remove Bidi control 2087 * characters; see the description of the <code>destSize</code> 2088 * and <code>options</code> parameters and of the option bit flags. 2089 * 2090 * @param pBiDi A pointer to a <code>UBiDi</code> object that 2091 * is set by <code>ubidi_setPara()</code> or 2092 * <code>ubidi_setLine()</code> and contains the reordering 2093 * information for the text that it was defined for, 2094 * as well as a pointer to that text.<br><br> 2095 * The text was aliased (only the pointer was stored 2096 * without copying the contents) and must not have been modified 2097 * since the <code>ubidi_setPara()</code> call. 2098 * 2099 * @param dest A pointer to where the reordered text is to be copied. 2100 * The source text and <code>dest[destSize]</code> 2101 * must not overlap. 2102 * 2103 * @param destSize The size of the <code>dest</code> buffer, 2104 * in number of UChars. 2105 * If the <code>UBIDI_INSERT_LRM_FOR_NUMERIC</code> 2106 * option is set, then the destination length could be 2107 * as large as 2108 * <code>ubidi_getLength(pBiDi)+2*ubidi_countRuns(pBiDi)</code>. 2109 * If the <code>UBIDI_REMOVE_BIDI_CONTROLS</code> option 2110 * is set, then the destination length may be less than 2111 * <code>ubidi_getLength(pBiDi)</code>. 2112 * If none of these options is set, then the destination length 2113 * will be exactly <code>ubidi_getProcessedLength(pBiDi)</code>. 2114 * 2115 * @param options A bit set of options for the reordering that control 2116 * how the reordered text is written. 2117 * The options include mirroring the characters on a code 2118 * point basis and inserting LRM characters, which is used 2119 * especially for transforming visually stored text 2120 * to logically stored text (although this is still an 2121 * imperfect implementation of an "inverse Bidi" algorithm 2122 * because it uses the "forward Bidi" algorithm at its core). 2123 * The available options are: 2124 * <code>#UBIDI_DO_MIRRORING</code>, 2125 * <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code>, 2126 * <code>#UBIDI_KEEP_BASE_COMBINING</code>, 2127 * <code>#UBIDI_OUTPUT_REVERSE</code>, 2128 * <code>#UBIDI_REMOVE_BIDI_CONTROLS</code> 2129 * 2130 * @param pErrorCode must be a valid pointer to an error code value. 2131 * 2132 * @return The length of the output string. 2133 * 2134 * @see ubidi_getProcessedLength 2135 * @stable ICU 2.0 2136 */ 2137 U_STABLE int32_t U_EXPORT2 2138 ubidi_writeReordered(UBiDi *pBiDi, 2139 UChar *dest, int32_t destSize, 2140 uint16_t options, 2141 UErrorCode *pErrorCode); 2142 2143 /** 2144 * Reverse a Right-To-Left run of Unicode text. 2145 * 2146 * This function preserves the integrity of characters with multiple 2147 * code units and (optionally) combining characters. 2148 * Characters can be replaced by mirror-image characters 2149 * in the destination buffer. Note that "real" mirroring has 2150 * to be done in a rendering engine by glyph selection 2151 * and that for many "mirrored" characters there are no 2152 * Unicode characters as mirror-image equivalents. 2153 * There are also options to insert or remove Bidi control 2154 * characters. 2155 * 2156 * This function is the implementation for reversing RTL runs as part 2157 * of <code>ubidi_writeReordered()</code>. For detailed descriptions 2158 * of the parameters, see there. 2159 * Since no Bidi controls are inserted here, the output string length 2160 * will never exceed <code>srcLength</code>. 2161 * 2162 * @see ubidi_writeReordered 2163 * 2164 * @param src A pointer to the RTL run text. 2165 * 2166 * @param srcLength The length of the RTL run. 2167 * 2168 * @param dest A pointer to where the reordered text is to be copied. 2169 * <code>src[srcLength]</code> and <code>dest[destSize]</code> 2170 * must not overlap. 2171 * 2172 * @param destSize The size of the <code>dest</code> buffer, 2173 * in number of UChars. 2174 * If the <code>UBIDI_REMOVE_BIDI_CONTROLS</code> option 2175 * is set, then the destination length may be less than 2176 * <code>srcLength</code>. 2177 * If this option is not set, then the destination length 2178 * will be exactly <code>srcLength</code>. 2179 * 2180 * @param options A bit set of options for the reordering that control 2181 * how the reordered text is written. 2182 * See the <code>options</code> parameter in <code>ubidi_writeReordered()</code>. 2183 * 2184 * @param pErrorCode must be a valid pointer to an error code value. 2185 * 2186 * @return The length of the output string. 2187 * @stable ICU 2.0 2188 */ 2189 U_STABLE int32_t U_EXPORT2 2190 ubidi_writeReverse(const UChar *src, int32_t srcLength, 2191 UChar *dest, int32_t destSize, 2192 uint16_t options, 2193 UErrorCode *pErrorCode); 2194 2195 /*#define BIDI_SAMPLE_CODE*/ 2196 /*@}*/ 2197 2198 #endif 2199