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