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