1 // © 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
4 ******************************************************************************
6 * Copyright (C) 1999-2013, International Business Machines
7 * Corporation and others. All Rights Reserved.
9 ******************************************************************************
12 * tab size: 8 (not used)
15 * created on: 1999jul27
16 * created by: Markus W. Scherer, updated by Matitiahu Allouche
22 #include "unicode/utypes.h"
23 #include "unicode/uchar.h"
24 #include "unicode/localpointer.h"
28 * \brief C API: Bidi algorithm
30 * <h2>Bidi algorithm for ICU</h2>
32 * This is an implementation of the Unicode Bidirectional Algorithm.
33 * The algorithm is defined in the
34 * <a href="http://www.unicode.org/unicode/reports/tr9/">Unicode Standard Annex #9</a>.<p>
36 * Note: Libraries that perform a bidirectional algorithm and
37 * reorder strings accordingly are sometimes called "Storage Layout Engines".
38 * ICU's Bidi and shaping (u_shapeArabic()) APIs can be used at the core of such
39 * "Storage Layout Engines".
41 * <h3>General remarks about the API:</h3>
43 * In functions with an error code parameter,
44 * the <code>pErrorCode</code> pointer must be valid
45 * and the value that it points to must not indicate a failure before
46 * the function call. Otherwise, the function returns immediately.
47 * After the function call, the value indicates success or failure.<p>
49 * The "limit" of a sequence of characters is the position just after their
50 * last character, i.e., one more than that position.<p>
52 * Some of the API functions provide access to "runs".
53 * Such a "run" is defined as a sequence of characters
54 * that are at the same embedding level
55 * after performing the Bidi algorithm.<p>
57 * @author Markus W. Scherer
61 * <h4> Sample code for the ICU Bidi API </h4>
63 * <h5>Rendering a paragraph with the ICU Bidi API</h5>
65 * This is (hypothetical) sample code that illustrates
66 * how the ICU Bidi API could be used to render a paragraph of text.
67 * Rendering code depends highly on the graphics system,
68 * therefore this sample code must make a lot of assumptions,
69 * which may or may not match any existing graphics system's properties.
71 * <p>The basic assumptions are:</p>
73 * <li>Rendering is done from left to right on a horizontal line.</li>
74 * <li>A run of single-style, unidirectional text can be rendered at once.</li>
75 * <li>Such a run of text is passed to the graphics system with
76 * characters (code units) in logical order.</li>
77 * <li>The line-breaking algorithm is very complicated
78 * and Locale-dependent -
79 * and therefore its implementation omitted from this sample code.</li>
84 *#include "unicode/ubidi.h"
87 * styleNormal=0, styleSelected=1,
88 * styleBold=2, styleItalics=4,
89 * styleSuper=8, styleSub=16
92 *typedef struct { int32_t limit; Style style; } StyleRun;
94 *int getTextWidth(const UChar *text, int32_t start, int32_t limit,
95 * const StyleRun *styleRuns, int styleRunCount);
97 * // set *pLimit and *pStyleRunLimit for a line
98 * // from text[start] and from styleRuns[styleRunStart]
99 * // using ubidi_getLogicalRun(para, ...)
100 *void getLineBreak(const UChar *text, int32_t start, int32_t *pLimit,
102 * const StyleRun *styleRuns, int styleRunStart, int *pStyleRunLimit,
105 * // render runs on a line sequentially, always from left to right
107 * // prepare rendering a new line
108 * void startLine(UBiDiDirection textDirection, int lineWidth);
110 * // render a run of text and advance to the right by the run width
111 * // the text[start..limit-1] is always in logical order
112 * void renderRun(const UChar *text, int32_t start, int32_t limit,
113 * UBiDiDirection textDirection, Style style);
115 * // We could compute a cross-product
116 * // from the style runs with the directional runs
117 * // and then reorder it.
118 * // Instead, here we iterate over each run type
119 * // and render the intersections -
120 * // with shortcuts in simple (and common) cases.
121 * // renderParagraph() is the main function.
123 * // render a directional run with
124 * // (possibly) multiple style runs intersecting with it
125 * void renderDirectionalRun(const UChar *text,
126 * int32_t start, int32_t limit,
127 * UBiDiDirection direction,
128 * const StyleRun *styleRuns, int styleRunCount) {
131 * // iterate over style runs
132 * if(direction==UBIDI_LTR) {
135 * for(i=0; i<styleRunCount; ++i) {
136 * styleLimit=styleRun[i].limit;
137 * if(start<styleLimit) {
138 * if(styleLimit>limit) { styleLimit=limit; }
139 * renderRun(text, start, styleLimit,
140 * direction, styleRun[i].style);
141 * if(styleLimit==limit) { break; }
148 * for(i=styleRunCount-1; i>=0; --i) {
150 * styleStart=styleRun[i-1].limit;
154 * if(limit>=styleStart) {
155 * if(styleStart<start) { styleStart=start; }
156 * renderRun(text, styleStart, limit,
157 * direction, styleRun[i].style);
158 * if(styleStart==start) { break; }
165 * // the line object represents text[start..limit-1]
166 * void renderLine(UBiDi *line, const UChar *text,
167 * int32_t start, int32_t limit,
168 * const StyleRun *styleRuns, int styleRunCount) {
169 * UBiDiDirection direction=ubidi_getDirection(line);
170 * if(direction!=UBIDI_MIXED) {
172 * if(styleRunCount<=1) {
173 * renderRun(text, start, limit, direction, styleRuns[0].style);
175 * renderDirectionalRun(text, start, limit,
176 * direction, styleRuns, styleRunCount);
179 * // mixed-directional
180 * int32_t count, i, length;
183 * count=ubidi_countRuns(para, pErrorCode);
184 * if(U_SUCCESS(*pErrorCode)) {
185 * if(styleRunCount<=1) {
186 * Style style=styleRuns[0].style;
188 * // iterate over directional runs
189 * for(i=0; i<count; ++i) {
190 * direction=ubidi_getVisualRun(para, i, &start, &length);
191 * renderRun(text, start, start+length, direction, style);
196 * // iterate over both directional and style runs
197 * for(i=0; i<count; ++i) {
198 * direction=ubidi_getVisualRun(line, i, &start, &length);
199 * renderDirectionalRun(text, start, start+length,
200 * direction, styleRuns, styleRunCount);
207 *void renderParagraph(const UChar *text, int32_t length,
208 * UBiDiDirection textDirection,
209 * const StyleRun *styleRuns, int styleRunCount,
211 * UErrorCode *pErrorCode) {
214 * if(pErrorCode==NULL || U_FAILURE(*pErrorCode) || length<=0) {
218 * para=ubidi_openSized(length, 0, pErrorCode);
219 * if(para==NULL) { return; }
221 * ubidi_setPara(para, text, length,
222 * textDirection ? UBIDI_DEFAULT_RTL : UBIDI_DEFAULT_LTR,
224 * if(U_SUCCESS(*pErrorCode)) {
225 * UBiDiLevel paraLevel=1&ubidi_getParaLevel(para);
226 * StyleRun styleRun={ length, styleNormal };
229 * if(styleRuns==NULL || styleRunCount<=0) {
231 * styleRuns=&styleRun;
234 * // assume styleRuns[styleRunCount-1].limit>=length
236 * width=getTextWidth(text, 0, length, styleRuns, styleRunCount);
237 * if(width<=lineWidth) {
238 * // everything fits onto one line
240 * // prepare rendering a new line from either left or right
241 * startLine(paraLevel, width);
243 * renderLine(para, text, 0, length,
244 * styleRuns, styleRunCount);
248 * // we need to render several lines
249 * line=ubidi_openSized(length, 0, pErrorCode);
251 * int32_t start=0, limit;
252 * int styleRunStart=0, styleRunLimit;
256 * styleRunLimit=styleRunCount;
257 * getLineBreak(text, start, &limit, para,
258 * styleRuns, styleRunStart, &styleRunLimit,
260 * ubidi_setLine(para, start, limit, line, pErrorCode);
261 * if(U_SUCCESS(*pErrorCode)) {
262 * // prepare rendering a new line
263 * // from either left or right
264 * startLine(paraLevel, width);
266 * renderLine(line, text, start, limit,
267 * styleRuns+styleRunStart,
268 * styleRunLimit-styleRunStart);
270 * if(limit==length) { break; }
272 * styleRunStart=styleRunLimit-1;
273 * if(start>=styleRuns[styleRunStart].limit) {
293 * UBiDiLevel is the type of the level values in this
294 * Bidi implementation.
295 * It holds an embedding level and indicates the visual direction
296 * by its bit 0 (even/odd value).<p>
298 * It can also hold non-level values for the
299 * <code>paraLevel</code> and <code>embeddingLevels</code>
300 * arguments of <code>ubidi_setPara()</code>; there:
302 * <li>bit 7 of an <code>embeddingLevels[]</code>
303 * value indicates whether the using application is
304 * specifying the level of a character to <i>override</i> whatever the
305 * Bidi implementation would resolve it to.</li>
306 * <li><code>paraLevel</code> can be set to the
307 * pseudo-level values <code>UBIDI_DEFAULT_LTR</code>
308 * and <code>UBIDI_DEFAULT_RTL</code>.</li>
313 * <p>The related constants are not real, valid level values.
314 * <code>UBIDI_DEFAULT_XXX</code> can be used to specify
315 * a default for the paragraph level for
316 * when the <code>ubidi_setPara()</code> function
317 * shall determine it but there is no
318 * strongly typed character in the input.<p>
320 * Note that the value for <code>UBIDI_DEFAULT_LTR</code> is even
321 * and the one for <code>UBIDI_DEFAULT_RTL</code> is odd,
322 * just like with normal LTR and RTL level values -
323 * these special values are designed that way. Also, the implementation
324 * assumes that UBIDI_MAX_EXPLICIT_LEVEL is odd.
326 * @see UBIDI_DEFAULT_LTR
327 * @see UBIDI_DEFAULT_RTL
328 * @see UBIDI_LEVEL_OVERRIDE
329 * @see UBIDI_MAX_EXPLICIT_LEVEL
332 typedef uint8_t UBiDiLevel;
334 /** Paragraph level setting.<p>
336 * Constant indicating that the base direction depends on the first strong
337 * directional character in the text according to the Unicode Bidirectional
338 * Algorithm. If no strong directional character is present,
339 * then set the paragraph level to 0 (left-to-right).<p>
341 * If this value is used in conjunction with reordering modes
342 * <code>UBIDI_REORDER_INVERSE_LIKE_DIRECT</code> or
343 * <code>UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL</code>, the text to reorder
344 * is assumed to be visual LTR, and the text after reordering is required
345 * to be the corresponding logical string with appropriate contextual
346 * direction. The direction of the result string will be RTL if either
347 * the righmost or leftmost strong character of the source text is RTL
348 * or Arabic Letter, the direction will be LTR otherwise.<p>
350 * If reordering option <code>UBIDI_OPTION_INSERT_MARKS</code> is set, an RLM may
351 * be added at the beginning of the result string to ensure round trip
352 * (that the result string, when reordered back to visual, will produce
353 * the original source text).
354 * @see UBIDI_REORDER_INVERSE_LIKE_DIRECT
355 * @see UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL
358 #define UBIDI_DEFAULT_LTR 0xfe
360 /** Paragraph level setting.<p>
362 * Constant indicating that the base direction depends on the first strong
363 * directional character in the text according to the Unicode Bidirectional
364 * Algorithm. If no strong directional character is present,
365 * then set the paragraph level to 1 (right-to-left).<p>
367 * If this value is used in conjunction with reordering modes
368 * <code>UBIDI_REORDER_INVERSE_LIKE_DIRECT</code> or
369 * <code>UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL</code>, the text to reorder
370 * is assumed to be visual LTR, and the text after reordering is required
371 * to be the corresponding logical string with appropriate contextual
372 * direction. The direction of the result string will be RTL if either
373 * the righmost or leftmost strong character of the source text is RTL
374 * or Arabic Letter, or if the text contains no strong character;
375 * the direction will be LTR otherwise.<p>
377 * If reordering option <code>UBIDI_OPTION_INSERT_MARKS</code> is set, an RLM may
378 * be added at the beginning of the result string to ensure round trip
379 * (that the result string, when reordered back to visual, will produce
380 * the original source text).
381 * @see UBIDI_REORDER_INVERSE_LIKE_DIRECT
382 * @see UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL
385 #define UBIDI_DEFAULT_RTL 0xff
388 * Maximum explicit embedding level.
389 * (The maximum resolved level can be up to <code>UBIDI_MAX_EXPLICIT_LEVEL+1</code>).
392 #define UBIDI_MAX_EXPLICIT_LEVEL 125
394 /** Bit flag for level input.
395 * Overrides directional properties.
398 #define UBIDI_LEVEL_OVERRIDE 0x80
401 * Special value which can be returned by the mapping functions when a logical
402 * index has no corresponding visual index or vice-versa. This may happen
403 * for the logical-to-visual mapping of a Bidi control when option
404 * <code>#UBIDI_OPTION_REMOVE_CONTROLS</code> is specified. This can also happen
405 * for the visual-to-logical mapping of a Bidi mark (LRM or RLM) inserted
406 * by option <code>#UBIDI_OPTION_INSERT_MARKS</code>.
407 * @see ubidi_getVisualIndex
408 * @see ubidi_getVisualMap
409 * @see ubidi_getLogicalIndex
410 * @see ubidi_getLogicalMap
413 #define UBIDI_MAP_NOWHERE (-1)
416 * <code>UBiDiDirection</code> values indicate the text direction.
419 enum UBiDiDirection {
420 /** Left-to-right text. This is a 0 value.
422 * <li>As return value for <code>ubidi_getDirection()</code>, it means
423 * that the source string contains no right-to-left characters, or
424 * that the source string is empty and the paragraph level is even.
425 * <li> As return value for <code>ubidi_getBaseDirection()</code>, it
426 * means that the first strong character of the source string has
427 * a left-to-right direction.
432 /** Right-to-left text. This is a 1 value.
434 * <li>As return value for <code>ubidi_getDirection()</code>, it means
435 * that the source string contains no left-to-right characters, or
436 * that the source string is empty and the paragraph level is odd.
437 * <li> As return value for <code>ubidi_getBaseDirection()</code>, it
438 * means that the first strong character of the source string has
439 * a right-to-left direction.
444 /** Mixed-directional text.
445 * <p>As return value for <code>ubidi_getDirection()</code>, it means
446 * that the source string contains both left-to-right and
447 * right-to-left characters.
451 /** No strongly directional text.
452 * <p>As return value for <code>ubidi_getBaseDirection()</code>, it means
453 * that the source string is missing or empty, or contains neither left-to-right
454 * nor right-to-left characters.
460 /** @stable ICU 2.0 */
461 typedef enum UBiDiDirection UBiDiDirection;
464 * Forward declaration of the <code>UBiDi</code> structure for the declaration of
465 * the API functions. Its fields are implementation-specific.<p>
466 * This structure holds information about a paragraph (or multiple paragraphs)
467 * of text with Bidi-algorithm-related details, or about one line of
468 * such a paragraph.<p>
469 * Reordering can be done on a line, or on one or more paragraphs which are
470 * then interpreted each as one single line.
475 /** @stable ICU 2.0 */
476 typedef struct UBiDi UBiDi;
479 * Allocate a <code>UBiDi</code> structure.
480 * Such an object is initially empty. It is assigned
481 * the Bidi properties of a piece of text containing one or more paragraphs
482 * by <code>ubidi_setPara()</code>
483 * or the Bidi properties of a line within a paragraph by
484 * <code>ubidi_setLine()</code>.<p>
485 * This object can be reused for as long as it is not deallocated
486 * by calling <code>ubidi_close()</code>.<p>
487 * <code>ubidi_setPara()</code> and <code>ubidi_setLine()</code> will allocate
488 * additional memory for internal structures as necessary.
490 * @return An empty <code>UBiDi</code> object.
493 U_STABLE UBiDi * U_EXPORT2
497 * Allocate a <code>UBiDi</code> structure with preallocated memory
498 * for internal structures.
499 * This function provides a <code>UBiDi</code> object like <code>ubidi_open()</code>
500 * with no arguments, but it also preallocates memory for internal structures
501 * according to the sizings supplied by the caller.<p>
502 * Subsequent functions will not allocate any more memory, and are thus
503 * guaranteed not to fail because of lack of memory.<p>
504 * The preallocation can be limited to some of the internal memory
505 * by setting some values to 0 here. That means that if, e.g.,
506 * <code>maxRunCount</code> cannot be reasonably predetermined and should not
507 * be set to <code>maxLength</code> (the only failproof value) to avoid
508 * wasting memory, then <code>maxRunCount</code> could be set to 0 here
509 * and the internal structures that are associated with it will be allocated
510 * on demand, just like with <code>ubidi_open()</code>.
512 * @param maxLength is the maximum text or line length that internal memory
513 * will be preallocated for. An attempt to associate this object with a
514 * longer text will fail, unless this value is 0, which leaves the allocation
515 * up to the implementation.
517 * @param maxRunCount is the maximum anticipated number of same-level runs
518 * that internal memory will be preallocated for. An attempt to access
519 * visual runs on an object that was not preallocated for as many runs
520 * as the text was actually resolved to will fail,
521 * unless this value is 0, which leaves the allocation up to the implementation.<br><br>
522 * The number of runs depends on the actual text and maybe anywhere between
523 * 1 and <code>maxLength</code>. It is typically small.
525 * @param pErrorCode must be a valid pointer to an error code value.
527 * @return An empty <code>UBiDi</code> object with preallocated memory.
530 U_STABLE UBiDi * U_EXPORT2
531 ubidi_openSized(int32_t maxLength, int32_t maxRunCount, UErrorCode *pErrorCode);
534 * <code>ubidi_close()</code> must be called to free the memory
535 * associated with a UBiDi object.<p>
537 * <strong>Important: </strong>
538 * A parent <code>UBiDi</code> object must not be destroyed or reused if
539 * it still has children.
540 * If a <code>UBiDi</code> object has become the <i>child</i>
541 * of another one (its <i>parent</i>) by calling
542 * <code>ubidi_setLine()</code>, then the child object must
543 * be destroyed (closed) or reused (by calling
544 * <code>ubidi_setPara()</code> or <code>ubidi_setLine()</code>)
545 * before the parent object.
547 * @param pBiDi is a <code>UBiDi</code> object.
553 U_STABLE void U_EXPORT2
554 ubidi_close(UBiDi *pBiDi);
556 #if U_SHOW_CPLUSPLUS_API
561 * \class LocalUBiDiPointer
562 * "Smart pointer" class, closes a UBiDi via ubidi_close().
563 * For most methods see the LocalPointerBase base class.
565 * @see LocalPointerBase
569 U_DEFINE_LOCAL_OPEN_POINTER(LocalUBiDiPointer, UBiDi, ubidi_close);
576 * Modify the operation of the Bidi algorithm such that it
577 * approximates an "inverse Bidi" algorithm. This function
578 * must be called before <code>ubidi_setPara()</code>.
580 * <p>The normal operation of the Bidi algorithm as described
581 * in the Unicode Technical Report is to take text stored in logical
582 * (keyboard, typing) order and to determine the reordering of it for visual
584 * Some legacy systems store text in visual order, and for operations
585 * with standard, Unicode-based algorithms, the text needs to be transformed
586 * to logical order. This is effectively the inverse algorithm of the
587 * described Bidi algorithm. Note that there is no standard algorithm for
588 * this "inverse Bidi" and that the current implementation provides only an
589 * approximation of "inverse Bidi".</p>
591 * <p>With <code>isInverse</code> set to <code>TRUE</code>,
592 * this function changes the behavior of some of the subsequent functions
593 * in a way that they can be used for the inverse Bidi algorithm.
594 * Specifically, runs of text with numeric characters will be treated in a
595 * special way and may need to be surrounded with LRM characters when they are
596 * written in reordered sequence.</p>
598 * <p>Output runs should be retrieved using <code>ubidi_getVisualRun()</code>.
599 * Since the actual input for "inverse Bidi" is visually ordered text and
600 * <code>ubidi_getVisualRun()</code> gets the reordered runs, these are actually
601 * the runs of the logically ordered output.</p>
603 * <p>Calling this function with argument <code>isInverse</code> set to
604 * <code>TRUE</code> is equivalent to calling
605 * <code>ubidi_setReorderingMode</code> with argument
606 * <code>reorderingMode</code>
607 * set to <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>.<br>
608 * Calling this function with argument <code>isInverse</code> set to
609 * <code>FALSE</code> is equivalent to calling
610 * <code>ubidi_setReorderingMode</code> with argument
611 * <code>reorderingMode</code>
612 * set to <code>#UBIDI_REORDER_DEFAULT</code>.
614 * @param pBiDi is a <code>UBiDi</code> object.
616 * @param isInverse specifies "forward" or "inverse" Bidi operation.
619 * @see ubidi_writeReordered
620 * @see ubidi_setReorderingMode
623 U_STABLE void U_EXPORT2
624 ubidi_setInverse(UBiDi *pBiDi, UBool isInverse);
627 * Is this Bidi object set to perform the inverse Bidi algorithm?
628 * <p>Note: calling this function after setting the reordering mode with
629 * <code>ubidi_setReorderingMode</code> will return <code>TRUE</code> if the
630 * reordering mode was set to <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>,
631 * <code>FALSE</code> for all other values.</p>
633 * @param pBiDi is a <code>UBiDi</code> object.
634 * @return TRUE if the Bidi object is set to perform the inverse Bidi algorithm
635 * by handling numbers as L.
637 * @see ubidi_setInverse
638 * @see ubidi_setReorderingMode
642 U_STABLE UBool U_EXPORT2
643 ubidi_isInverse(UBiDi *pBiDi);
646 * Specify whether block separators must be allocated level zero,
647 * so that successive paragraphs will progress from left to right.
648 * This function must be called before <code>ubidi_setPara()</code>.
649 * Paragraph separators (B) may appear in the text. Setting them to level zero
650 * means that all paragraph separators (including one possibly appearing
651 * in the last text position) are kept in the reordered text after the text
652 * that they follow in the source text.
653 * When this feature is not enabled, a paragraph separator at the last
654 * position of the text before reordering will go to the first position
655 * of the reordered text when the paragraph level is odd.
657 * @param pBiDi is a <code>UBiDi</code> object.
659 * @param orderParagraphsLTR specifies whether paragraph separators (B) must
660 * receive level 0, so that successive paragraphs progress from left to right.
665 U_STABLE void U_EXPORT2
666 ubidi_orderParagraphsLTR(UBiDi *pBiDi, UBool orderParagraphsLTR);
669 * Is this Bidi object set to allocate level 0 to block separators so that
670 * successive paragraphs progress from left to right?
672 * @param pBiDi is a <code>UBiDi</code> object.
673 * @return TRUE if the Bidi object is set to allocate level 0 to block
676 * @see ubidi_orderParagraphsLTR
679 U_STABLE UBool U_EXPORT2
680 ubidi_isOrderParagraphsLTR(UBiDi *pBiDi);
683 * <code>UBiDiReorderingMode</code> values indicate which variant of the Bidi
686 * @see ubidi_setReorderingMode
689 typedef enum UBiDiReorderingMode {
690 /** Regular Logical to Visual Bidi algorithm according to Unicode.
693 UBIDI_REORDER_DEFAULT = 0,
694 /** Logical to Visual algorithm which handles numbers in a way which
695 * mimicks the behavior of Windows XP.
697 UBIDI_REORDER_NUMBERS_SPECIAL,
698 /** Logical to Visual algorithm grouping numbers with adjacent R characters
699 * (reversible algorithm).
701 UBIDI_REORDER_GROUP_NUMBERS_WITH_R,
702 /** Reorder runs only to transform a Logical LTR string to the Logical RTL
703 * string with the same display, or vice-versa.<br>
704 * If this mode is set together with option
705 * <code>#UBIDI_OPTION_INSERT_MARKS</code>, some Bidi controls in the source
706 * text may be removed and other controls may be added to produce the
707 * minimum combination which has the required display.
709 UBIDI_REORDER_RUNS_ONLY,
710 /** Visual to Logical algorithm which handles numbers like L
711 * (same algorithm as selected by <code>ubidi_setInverse(TRUE)</code>.
712 * @see ubidi_setInverse
714 UBIDI_REORDER_INVERSE_NUMBERS_AS_L,
715 /** Visual to Logical algorithm equivalent to the regular Logical to Visual
718 UBIDI_REORDER_INVERSE_LIKE_DIRECT,
719 /** Inverse Bidi (Visual to Logical) algorithm for the
720 * <code>UBIDI_REORDER_NUMBERS_SPECIAL</code> Bidi algorithm.
722 UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL,
723 #ifndef U_HIDE_DEPRECATED_API
725 * Number of values for reordering mode.
726 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
729 #endif // U_HIDE_DEPRECATED_API
730 } UBiDiReorderingMode;
733 * Modify the operation of the Bidi algorithm such that it implements some
734 * variant to the basic Bidi algorithm or approximates an "inverse Bidi"
735 * algorithm, depending on different values of the "reordering mode".
736 * This function must be called before <code>ubidi_setPara()</code>, and stays
737 * in effect until called again with a different argument.
739 * <p>The normal operation of the Bidi algorithm as described
740 * in the Unicode Standard Annex #9 is to take text stored in logical
741 * (keyboard, typing) order and to determine how to reorder it for visual
744 * <p>With the reordering mode set to a value other than
745 * <code>#UBIDI_REORDER_DEFAULT</code>, this function changes the behavior of
746 * some of the subsequent functions in a way such that they implement an
747 * inverse Bidi algorithm or some other algorithm variants.</p>
749 * <p>Some legacy systems store text in visual order, and for operations
750 * with standard, Unicode-based algorithms, the text needs to be transformed
751 * into logical order. This is effectively the inverse algorithm of the
752 * described Bidi algorithm. Note that there is no standard algorithm for
753 * this "inverse Bidi", so a number of variants are implemented here.</p>
755 * <p>In other cases, it may be desirable to emulate some variant of the
756 * Logical to Visual algorithm (e.g. one used in MS Windows), or perform a
757 * Logical to Logical transformation.</p>
760 * <li>When the reordering mode is set to <code>#UBIDI_REORDER_DEFAULT</code>,
761 * the standard Bidi Logical to Visual algorithm is applied.</li>
763 * <li>When the reordering mode is set to
764 * <code>#UBIDI_REORDER_NUMBERS_SPECIAL</code>,
765 * the algorithm used to perform Bidi transformations when calling
766 * <code>ubidi_setPara</code> should approximate the algorithm used in
767 * Microsoft Windows XP rather than strictly conform to the Unicode Bidi
770 * The differences between the basic algorithm and the algorithm addressed
771 * by this option are as follows:
773 * <li>Within text at an even embedding level, the sequence "123AB"
774 * (where AB represent R or AL letters) is transformed to "123BA" by the
775 * Unicode algorithm and to "BA123" by the Windows algorithm.</li>
776 * <li>Arabic-Indic numbers (AN) are handled by the Windows algorithm just
777 * like regular numbers (EN).</li>
780 * <li>When the reordering mode is set to
781 * <code>#UBIDI_REORDER_GROUP_NUMBERS_WITH_R</code>,
782 * numbers located between LTR text and RTL text are associated with the RTL
783 * text. For instance, an LTR paragraph with content "abc 123 DEF" (where
784 * upper case letters represent RTL characters) will be transformed to
785 * "abc FED 123" (and not "abc 123 FED"), "DEF 123 abc" will be transformed
786 * to "123 FED abc" and "123 FED abc" will be transformed to "DEF 123 abc".
787 * This makes the algorithm reversible and makes it useful when round trip
788 * (from visual to logical and back to visual) must be achieved without
789 * adding LRM characters. However, this is a variation from the standard
790 * Unicode Bidi algorithm.<br>
791 * The source text should not contain Bidi control characters other than LRM
794 * <li>When the reordering mode is set to
795 * <code>#UBIDI_REORDER_RUNS_ONLY</code>,
796 * a "Logical to Logical" transformation must be performed:
798 * <li>If the default text level of the source text (argument <code>paraLevel</code>
799 * in <code>ubidi_setPara</code>) is even, the source text will be handled as
800 * LTR logical text and will be transformed to the RTL logical text which has
801 * the same LTR visual display.</li>
802 * <li>If the default level of the source text is odd, the source text
803 * will be handled as RTL logical text and will be transformed to the
804 * LTR logical text which has the same LTR visual display.</li>
806 * This mode may be needed when logical text which is basically Arabic or
807 * Hebrew, with possible included numbers or phrases in English, has to be
808 * displayed as if it had an even embedding level (this can happen if the
809 * displaying application treats all text as if it was basically LTR).
811 * This mode may also be needed in the reverse case, when logical text which is
812 * basically English, with possible included phrases in Arabic or Hebrew, has to
813 * be displayed as if it had an odd embedding level.
815 * Both cases could be handled by adding LRE or RLE at the head of the text,
816 * if the display subsystem supports these formatting controls. If it does not,
817 * the problem may be handled by transforming the source text in this mode
818 * before displaying it, so that it will be displayed properly.<br>
819 * The source text should not contain Bidi control characters other than LRM
822 * <li>When the reordering mode is set to
823 * <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>, an "inverse Bidi" algorithm
825 * Runs of text with numeric characters will be treated like LTR letters and
826 * may need to be surrounded with LRM characters when they are written in
827 * reordered sequence (the option <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code> can
828 * be used with function <code>ubidi_writeReordered</code> to this end. This
829 * mode is equivalent to calling <code>ubidi_setInverse()</code> with
830 * argument <code>isInverse</code> set to <code>TRUE</code>.</li>
832 * <li>When the reordering mode is set to
833 * <code>#UBIDI_REORDER_INVERSE_LIKE_DIRECT</code>, the "direct" Logical to Visual
834 * Bidi algorithm is used as an approximation of an "inverse Bidi" algorithm.
835 * This mode is similar to mode <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>
836 * but is closer to the regular Bidi algorithm.
838 * For example, an LTR paragraph with the content "FED 123 456 CBA" (where
839 * upper case represents RTL characters) will be transformed to
840 * "ABC 456 123 DEF", as opposed to "DEF 123 456 ABC"
841 * with mode <code>UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>.<br>
842 * When used in conjunction with option
843 * <code>#UBIDI_OPTION_INSERT_MARKS</code>, this mode generally
844 * adds Bidi marks to the output significantly more sparingly than mode
845 * <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code> with option
846 * <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code> in calls to
847 * <code>ubidi_writeReordered</code>.</li>
849 * <li>When the reordering mode is set to
850 * <code>#UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL</code>, the Logical to Visual
851 * Bidi algorithm used in Windows XP is used as an approximation of an "inverse Bidi" algorithm.
853 * For example, an LTR paragraph with the content "abc FED123" (where
854 * upper case represents RTL characters) will be transformed to "abc 123DEF."</li>
857 * <p>In all the reordering modes specifying an "inverse Bidi" algorithm
858 * (i.e. those with a name starting with <code>UBIDI_REORDER_INVERSE</code>),
859 * output runs should be retrieved using
860 * <code>ubidi_getVisualRun()</code>, and the output text with
861 * <code>ubidi_writeReordered()</code>. The caller should keep in mind that in
862 * "inverse Bidi" modes the input is actually visually ordered text and
863 * reordered output returned by <code>ubidi_getVisualRun()</code> or
864 * <code>ubidi_writeReordered()</code> are actually runs or character string
865 * of logically ordered output.<br>
866 * For all the "inverse Bidi" modes, the source text should not contain
867 * Bidi control characters other than LRM or RLM.</p>
869 * <p>Note that option <code>#UBIDI_OUTPUT_REVERSE</code> of
870 * <code>ubidi_writeReordered</code> has no useful meaning and should not be
871 * used in conjunction with any value of the reordering mode specifying
872 * "inverse Bidi" or with value <code>UBIDI_REORDER_RUNS_ONLY</code>.
874 * @param pBiDi is a <code>UBiDi</code> object.
875 * @param reorderingMode specifies the required variant of the Bidi algorithm.
877 * @see UBiDiReorderingMode
878 * @see ubidi_setInverse
880 * @see ubidi_writeReordered
883 U_STABLE void U_EXPORT2
884 ubidi_setReorderingMode(UBiDi *pBiDi, UBiDiReorderingMode reorderingMode);
887 * What is the requested reordering mode for a given Bidi object?
889 * @param pBiDi is a <code>UBiDi</code> object.
890 * @return the current reordering mode of the Bidi object
891 * @see ubidi_setReorderingMode
894 U_STABLE UBiDiReorderingMode U_EXPORT2
895 ubidi_getReorderingMode(UBiDi *pBiDi);
898 * <code>UBiDiReorderingOption</code> values indicate which options are
899 * specified to affect the Bidi algorithm.
901 * @see ubidi_setReorderingOptions
904 typedef enum UBiDiReorderingOption {
906 * option value for <code>ubidi_setReorderingOptions</code>:
907 * disable all the options which can be set with this function
908 * @see ubidi_setReorderingOptions
911 UBIDI_OPTION_DEFAULT = 0,
914 * option bit for <code>ubidi_setReorderingOptions</code>:
915 * insert Bidi marks (LRM or RLM) when needed to ensure correct result of
916 * a reordering to a Logical order
918 * <p>This option must be set or reset before calling
919 * <code>ubidi_setPara</code>.</p>
921 * <p>This option is significant only with reordering modes which generate
922 * a result with Logical order, specifically:</p>
924 * <li><code>#UBIDI_REORDER_RUNS_ONLY</code></li>
925 * <li><code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code></li>
926 * <li><code>#UBIDI_REORDER_INVERSE_LIKE_DIRECT</code></li>
927 * <li><code>#UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL</code></li>
930 * <p>If this option is set in conjunction with reordering mode
931 * <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code> or with calling
932 * <code>ubidi_setInverse(TRUE)</code>, it implies
933 * option <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code>
934 * in calls to function <code>ubidi_writeReordered()</code>.</p>
936 * <p>For other reordering modes, a minimum number of LRM or RLM characters
937 * will be added to the source text after reordering it so as to ensure
938 * round trip, i.e. when applying the inverse reordering mode on the
939 * resulting logical text with removal of Bidi marks
940 * (option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code> set before calling
941 * <code>ubidi_setPara()</code> or option <code>#UBIDI_REMOVE_BIDI_CONTROLS</code>
942 * in <code>ubidi_writeReordered</code>), the result will be identical to the
943 * source text in the first transformation.
945 * <p>This option will be ignored if specified together with option
946 * <code>#UBIDI_OPTION_REMOVE_CONTROLS</code>. It inhibits option
947 * <code>UBIDI_REMOVE_BIDI_CONTROLS</code> in calls to function
948 * <code>ubidi_writeReordered()</code> and it implies option
949 * <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code> in calls to function
950 * <code>ubidi_writeReordered()</code> if the reordering mode is
951 * <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>.</p>
953 * @see ubidi_setReorderingMode
954 * @see ubidi_setReorderingOptions
957 UBIDI_OPTION_INSERT_MARKS = 1,
960 * option bit for <code>ubidi_setReorderingOptions</code>:
961 * remove Bidi control characters
963 * <p>This option must be set or reset before calling
964 * <code>ubidi_setPara</code>.</p>
966 * <p>This option nullifies option <code>#UBIDI_OPTION_INSERT_MARKS</code>.
967 * It inhibits option <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code> in calls
968 * to function <code>ubidi_writeReordered()</code> and it implies option
969 * <code>#UBIDI_REMOVE_BIDI_CONTROLS</code> in calls to that function.</p>
971 * @see ubidi_setReorderingMode
972 * @see ubidi_setReorderingOptions
975 UBIDI_OPTION_REMOVE_CONTROLS = 2,
978 * option bit for <code>ubidi_setReorderingOptions</code>:
979 * process the output as part of a stream to be continued
981 * <p>This option must be set or reset before calling
982 * <code>ubidi_setPara</code>.</p>
984 * <p>This option specifies that the caller is interested in processing large
985 * text object in parts.
986 * The results of the successive calls are expected to be concatenated by the
987 * caller. Only the call for the last part will have this option bit off.</p>
989 * <p>When this option bit is on, <code>ubidi_setPara()</code> may process
990 * less than the full source text in order to truncate the text at a meaningful
991 * boundary. The caller should call <code>ubidi_getProcessedLength()</code>
992 * immediately after calling <code>ubidi_setPara()</code> in order to
993 * determine how much of the source text has been processed.
994 * Source text beyond that length should be resubmitted in following calls to
995 * <code>ubidi_setPara</code>. The processed length may be less than
996 * the length of the source text if a character preceding the last character of
997 * the source text constitutes a reasonable boundary (like a block separator)
998 * for text to be continued.<br>
999 * If the last character of the source text constitutes a reasonable
1000 * boundary, the whole text will be processed at once.<br>
1001 * If nowhere in the source text there exists
1002 * such a reasonable boundary, the processed length will be zero.<br>
1003 * The caller should check for such an occurrence and do one of the following:
1004 * <ul><li>submit a larger amount of text with a better chance to include
1005 * a reasonable boundary.</li>
1006 * <li>resubmit the same text after turning off option
1007 * <code>UBIDI_OPTION_STREAMING</code>.</li></ul>
1008 * In all cases, this option should be turned off before processing the last
1009 * part of the text.</p>
1011 * <p>When the <code>UBIDI_OPTION_STREAMING</code> option is used,
1012 * it is recommended to call <code>ubidi_orderParagraphsLTR()</code> with
1013 * argument <code>orderParagraphsLTR</code> set to <code>TRUE</code> before
1014 * calling <code>ubidi_setPara</code> so that later paragraphs may be
1015 * concatenated to previous paragraphs on the right.</p>
1017 * @see ubidi_setReorderingMode
1018 * @see ubidi_setReorderingOptions
1019 * @see ubidi_getProcessedLength
1020 * @see ubidi_orderParagraphsLTR
1023 UBIDI_OPTION_STREAMING = 4
1024 } UBiDiReorderingOption;
1027 * Specify which of the reordering options
1028 * should be applied during Bidi transformations.
1030 * @param pBiDi is a <code>UBiDi</code> object.
1031 * @param reorderingOptions is a combination of zero or more of the following
1033 * <code>#UBIDI_OPTION_DEFAULT</code>, <code>#UBIDI_OPTION_INSERT_MARKS</code>,
1034 * <code>#UBIDI_OPTION_REMOVE_CONTROLS</code>, <code>#UBIDI_OPTION_STREAMING</code>.
1036 * @see ubidi_getReorderingOptions
1039 U_STABLE void U_EXPORT2
1040 ubidi_setReorderingOptions(UBiDi *pBiDi, uint32_t reorderingOptions);
1043 * What are the reordering options applied to a given Bidi object?
1045 * @param pBiDi is a <code>UBiDi</code> object.
1046 * @return the current reordering options of the Bidi object
1047 * @see ubidi_setReorderingOptions
1050 U_STABLE uint32_t U_EXPORT2
1051 ubidi_getReorderingOptions(UBiDi *pBiDi);
1054 * Set the context before a call to ubidi_setPara().<p>
1056 * ubidi_setPara() computes the left-right directionality for a given piece
1057 * of text which is supplied as one of its arguments. Sometimes this piece
1058 * of text (the "main text") should be considered in context, because text
1059 * appearing before ("prologue") and/or after ("epilogue") the main text
1060 * may affect the result of this computation.<p>
1062 * This function specifies the prologue and/or the epilogue for the next
1063 * call to ubidi_setPara(). The characters specified as prologue and
1064 * epilogue should not be modified by the calling program until the call
1065 * to ubidi_setPara() has returned. If successive calls to ubidi_setPara()
1066 * all need specification of a context, ubidi_setContext() must be called
1067 * before each call to ubidi_setPara(). In other words, a context is not
1068 * "remembered" after the following successful call to ubidi_setPara().<p>
1070 * If a call to ubidi_setPara() specifies UBIDI_DEFAULT_LTR or
1071 * UBIDI_DEFAULT_RTL as paraLevel and is preceded by a call to
1072 * ubidi_setContext() which specifies a prologue, the paragraph level will
1073 * be computed taking in consideration the text in the prologue.<p>
1075 * When ubidi_setPara() is called without a previous call to
1076 * ubidi_setContext, the main text is handled as if preceded and followed
1077 * by strong directional characters at the current paragraph level.
1078 * Calling ubidi_setContext() with specification of a prologue will change
1079 * this behavior by handling the main text as if preceded by the last
1080 * strong character appearing in the prologue, if any.
1081 * Calling ubidi_setContext() with specification of an epilogue will change
1082 * the behavior of ubidi_setPara() by handling the main text as if followed
1083 * by the first strong character or digit appearing in the epilogue, if any.<p>
1085 * Note 1: if <code>ubidi_setContext</code> is called repeatedly without
1086 * calling <code>ubidi_setPara</code>, the earlier calls have no effect,
1087 * only the last call will be remembered for the next call to
1088 * <code>ubidi_setPara</code>.<p>
1090 * Note 2: calling <code>ubidi_setContext(pBiDi, NULL, 0, NULL, 0, &errorCode)</code>
1091 * cancels any previous setting of non-empty prologue or epilogue.
1092 * The next call to <code>ubidi_setPara()</code> will process no
1093 * prologue or epilogue.<p>
1095 * Note 3: users must be aware that even after setting the context
1096 * before a call to ubidi_setPara() to perform e.g. a logical to visual
1097 * transformation, the resulting string may not be identical to what it
1098 * would have been if all the text, including prologue and epilogue, had
1099 * been processed together.<br>
1100 * Example (upper case letters represent RTL characters):<br>
1101 * prologue = "<code>abc DE</code>"<br>
1102 * epilogue = none<br>
1103 * main text = "<code>FGH xyz</code>"<br>
1104 * paraLevel = UBIDI_LTR<br>
1105 * display without prologue = "<code>HGF xyz</code>"
1106 * ("HGF" is adjacent to "xyz")<br>
1107 * display with prologue = "<code>abc HGFED xyz</code>"
1108 * ("HGF" is not adjacent to "xyz")<br>
1110 * @param pBiDi is a paragraph <code>UBiDi</code> object.
1112 * @param prologue is a pointer to the text which precedes the text that
1113 * will be specified in a coming call to ubidi_setPara().
1114 * If there is no prologue to consider, then <code>proLength</code>
1115 * must be zero and this pointer can be NULL.
1117 * @param proLength is the length of the prologue; if <code>proLength==-1</code>
1118 * then the prologue must be zero-terminated.
1119 * Otherwise proLength must be >= 0. If <code>proLength==0</code>, it means
1120 * that there is no prologue to consider.
1122 * @param epilogue is a pointer to the text which follows the text that
1123 * will be specified in a coming call to ubidi_setPara().
1124 * If there is no epilogue to consider, then <code>epiLength</code>
1125 * must be zero and this pointer can be NULL.
1127 * @param epiLength is the length of the epilogue; if <code>epiLength==-1</code>
1128 * then the epilogue must be zero-terminated.
1129 * Otherwise epiLength must be >= 0. If <code>epiLength==0</code>, it means
1130 * that there is no epilogue to consider.
1132 * @param pErrorCode must be a valid pointer to an error code value.
1134 * @see ubidi_setPara
1137 U_STABLE void U_EXPORT2
1138 ubidi_setContext(UBiDi *pBiDi,
1139 const UChar *prologue, int32_t proLength,
1140 const UChar *epilogue, int32_t epiLength,
1141 UErrorCode *pErrorCode);
1144 * Perform the Unicode Bidi algorithm. It is defined in the
1145 * <a href="http://www.unicode.org/unicode/reports/tr9/">Unicode Standard Anned #9</a>,
1147 * also described in The Unicode Standard, Version 4.0 .<p>
1149 * This function takes a piece of plain text containing one or more paragraphs,
1150 * with or without externally specified embedding levels from <i>styled</i>
1151 * text and computes the left-right-directionality of each character.<p>
1153 * If the entire text is all of the same directionality, then
1154 * the function may not perform all the steps described by the algorithm,
1155 * i.e., some levels may not be the same as if all steps were performed.
1156 * This is not relevant for unidirectional text.<br>
1157 * For example, in pure LTR text with numbers the numbers would get
1158 * a resolved level of 2 higher than the surrounding text according to
1159 * the algorithm. This implementation may set all resolved levels to
1160 * the same value in such a case.<p>
1162 * The text can be composed of multiple paragraphs. Occurrence of a block
1163 * separator in the text terminates a paragraph, and whatever comes next starts
1164 * a new paragraph. The exception to this rule is when a Carriage Return (CR)
1165 * is followed by a Line Feed (LF). Both CR and LF are block separators, but
1166 * in that case, the pair of characters is considered as terminating the
1167 * preceding paragraph, and a new paragraph will be started by a character
1168 * coming after the LF.
1170 * @param pBiDi A <code>UBiDi</code> object allocated with <code>ubidi_open()</code>
1171 * which will be set to contain the reordering information,
1172 * especially the resolved levels for all the characters in <code>text</code>.
1174 * @param text is a pointer to the text that the Bidi algorithm will be performed on.
1175 * This pointer is stored in the UBiDi object and can be retrieved
1176 * with <code>ubidi_getText()</code>.<br>
1177 * <strong>Note:</strong> the text must be (at least) <code>length</code> long.
1179 * @param length is the length of the text; if <code>length==-1</code> then
1180 * the text must be zero-terminated.
1182 * @param paraLevel specifies the default level for the text;
1183 * it is typically 0 (LTR) or 1 (RTL).
1184 * If the function shall determine the paragraph level from the text,
1185 * then <code>paraLevel</code> can be set to
1186 * either <code>#UBIDI_DEFAULT_LTR</code>
1187 * or <code>#UBIDI_DEFAULT_RTL</code>; if the text contains multiple
1188 * paragraphs, the paragraph level shall be determined separately for
1189 * each paragraph; if a paragraph does not include any strongly typed
1190 * character, then the desired default is used (0 for LTR or 1 for RTL).
1191 * Any other value between 0 and <code>#UBIDI_MAX_EXPLICIT_LEVEL</code>
1192 * is also valid, with odd levels indicating RTL.
1194 * @param embeddingLevels (in) may be used to preset the embedding and override levels,
1195 * ignoring characters like LRE and PDF in the text.
1196 * A level overrides the directional property of its corresponding
1197 * (same index) character if the level has the
1198 * <code>#UBIDI_LEVEL_OVERRIDE</code> bit set.<br><br>
1199 * Aside from that bit, it must be
1200 * <code>paraLevel<=embeddingLevels[]<=UBIDI_MAX_EXPLICIT_LEVEL</code>,
1201 * except that level 0 is always allowed.
1202 * Level 0 for a paragraph separator prevents reordering of paragraphs;
1203 * this only works reliably if <code>#UBIDI_LEVEL_OVERRIDE</code>
1204 * is also set for paragraph separators.
1205 * Level 0 for other characters is treated as a wildcard
1206 * and is lifted up to the resolved level of the surrounding paragraph.<br><br>
1207 * <strong>Caution: </strong>A copy of this pointer, not of the levels,
1208 * will be stored in the <code>UBiDi</code> object;
1209 * the <code>embeddingLevels</code> array must not be
1210 * deallocated before the <code>UBiDi</code> structure is destroyed or reused,
1211 * and the <code>embeddingLevels</code>
1212 * should not be modified to avoid unexpected results on subsequent Bidi operations.
1213 * However, the <code>ubidi_setPara()</code> and
1214 * <code>ubidi_setLine()</code> functions may modify some or all of the levels.<br><br>
1215 * After the <code>UBiDi</code> object is reused or destroyed, the caller
1216 * must take care of the deallocation of the <code>embeddingLevels</code> array.<br><br>
1217 * <strong>Note:</strong> the <code>embeddingLevels</code> array must be
1218 * at least <code>length</code> long.
1219 * This pointer can be <code>NULL</code> if this
1220 * value is not necessary.
1222 * @param pErrorCode must be a valid pointer to an error code value.
1225 U_STABLE void U_EXPORT2
1226 ubidi_setPara(UBiDi *pBiDi, const UChar *text, int32_t length,
1227 UBiDiLevel paraLevel, UBiDiLevel *embeddingLevels,
1228 UErrorCode *pErrorCode);
1231 * <code>ubidi_setLine()</code> sets a <code>UBiDi</code> to
1232 * contain the reordering information, especially the resolved levels,
1233 * for all the characters in a line of text. This line of text is
1234 * specified by referring to a <code>UBiDi</code> object representing
1235 * this information for a piece of text containing one or more paragraphs,
1236 * and by specifying a range of indexes in this text.<p>
1237 * In the new line object, the indexes will range from 0 to <code>limit-start-1</code>.<p>
1239 * This is used after calling <code>ubidi_setPara()</code>
1240 * for a piece of text, and after line-breaking on that text.
1241 * It is not necessary if each paragraph is treated as a single line.<p>
1243 * After line-breaking, rules (L1) and (L2) for the treatment of
1244 * trailing WS and for reordering are performed on
1245 * a <code>UBiDi</code> object that represents a line.<p>
1247 * <strong>Important: </strong><code>pLineBiDi</code> shares data with
1248 * <code>pParaBiDi</code>.
1249 * You must destroy or reuse <code>pLineBiDi</code> before <code>pParaBiDi</code>.
1250 * In other words, you must destroy or reuse the <code>UBiDi</code> object for a line
1251 * before the object for its parent paragraph.<p>
1253 * The text pointer that was stored in <code>pParaBiDi</code> is also copied,
1254 * and <code>start</code> is added to it so that it points to the beginning of the
1255 * line for this object.
1257 * @param pParaBiDi is the parent paragraph object. It must have been set
1258 * by a successful call to ubidi_setPara.
1260 * @param start is the line's first index into the text.
1262 * @param limit is just behind the line's last index into the text
1263 * (its last index +1).<br>
1264 * It must be <code>0<=start<limit<=</code>containing paragraph limit.
1265 * If the specified line crosses a paragraph boundary, the function
1266 * will terminate with error code U_ILLEGAL_ARGUMENT_ERROR.
1268 * @param pLineBiDi is the object that will now represent a line of the text.
1270 * @param pErrorCode must be a valid pointer to an error code value.
1272 * @see ubidi_setPara
1273 * @see ubidi_getProcessedLength
1276 U_STABLE void U_EXPORT2
1277 ubidi_setLine(const UBiDi *pParaBiDi,
1278 int32_t start, int32_t limit,
1280 UErrorCode *pErrorCode);
1283 * Get the directionality of the text.
1285 * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1287 * @return a value of <code>UBIDI_LTR</code>, <code>UBIDI_RTL</code>
1288 * or <code>UBIDI_MIXED</code>
1289 * that indicates if the entire text
1290 * represented by this object is unidirectional,
1291 * and which direction, or if it is mixed-directional.
1292 * Note - The value <code>UBIDI_NEUTRAL</code> is never returned from this method.
1294 * @see UBiDiDirection
1297 U_STABLE UBiDiDirection U_EXPORT2
1298 ubidi_getDirection(const UBiDi *pBiDi);
1301 * Gets the base direction of the text provided according
1302 * to the Unicode Bidirectional Algorithm. The base direction
1303 * is derived from the first character in the string with bidirectional
1304 * character type L, R, or AL. If the first such character has type L,
1305 * <code>UBIDI_LTR</code> is returned. If the first such character has
1306 * type R or AL, <code>UBIDI_RTL</code> is returned. If the string does
1307 * not contain any character of these types, then
1308 * <code>UBIDI_NEUTRAL</code> is returned.
1310 * This is a lightweight function for use when only the base direction
1311 * is needed and no further bidi processing of the text is needed.
1313 * @param text is a pointer to the text whose base
1314 * direction is needed.
1315 * Note: the text must be (at least) @c length long.
1317 * @param length is the length of the text;
1318 * if <code>length==-1</code> then the text
1319 * must be zero-terminated.
1321 * @return <code>UBIDI_LTR</code>, <code>UBIDI_RTL</code>,
1322 * <code>UBIDI_NEUTRAL</code>
1324 * @see UBiDiDirection
1327 U_STABLE UBiDiDirection U_EXPORT2
1328 ubidi_getBaseDirection(const UChar *text, int32_t length );
1331 * Get the pointer to the text.
1333 * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1335 * @return The pointer to the text that the UBiDi object was created for.
1337 * @see ubidi_setPara
1338 * @see ubidi_setLine
1341 U_STABLE const UChar * U_EXPORT2
1342 ubidi_getText(const UBiDi *pBiDi);
1345 * Get the length of the text.
1347 * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1349 * @return The length of the text that the UBiDi object was created for.
1352 U_STABLE int32_t U_EXPORT2
1353 ubidi_getLength(const UBiDi *pBiDi);
1356 * Get the paragraph level of the text.
1358 * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1360 * @return The paragraph level. If there are multiple paragraphs, their
1361 * level may vary if the required paraLevel is UBIDI_DEFAULT_LTR or
1362 * UBIDI_DEFAULT_RTL. In that case, the level of the first paragraph
1366 * @see ubidi_getParagraph
1367 * @see ubidi_getParagraphByIndex
1370 U_STABLE UBiDiLevel U_EXPORT2
1371 ubidi_getParaLevel(const UBiDi *pBiDi);
1374 * Get the number of paragraphs.
1376 * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1378 * @return The number of paragraphs.
1381 U_STABLE int32_t U_EXPORT2
1382 ubidi_countParagraphs(UBiDi *pBiDi);
1385 * Get a paragraph, given a position within the text.
1386 * This function returns information about a paragraph.<br>
1387 * Note: if the paragraph index is known, it is more efficient to
1388 * retrieve the paragraph information using ubidi_getParagraphByIndex().<p>
1390 * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1392 * @param charIndex is the index of a character within the text, in the
1393 * range <code>[0..ubidi_getProcessedLength(pBiDi)-1]</code>.
1395 * @param pParaStart will receive the index of the first character of the
1396 * paragraph in the text.
1397 * This pointer can be <code>NULL</code> if this
1398 * value is not necessary.
1400 * @param pParaLimit will receive the limit of the paragraph.
1401 * The l-value that you point to here may be the
1402 * same expression (variable) as the one for
1403 * <code>charIndex</code>.
1404 * This pointer can be <code>NULL</code> if this
1405 * value is not necessary.
1407 * @param pParaLevel will receive the level of the paragraph.
1408 * This pointer can be <code>NULL</code> if this
1409 * value is not necessary.
1411 * @param pErrorCode must be a valid pointer to an error code value.
1413 * @return The index of the paragraph containing the specified position.
1415 * @see ubidi_getProcessedLength
1418 U_STABLE int32_t U_EXPORT2
1419 ubidi_getParagraph(const UBiDi *pBiDi, int32_t charIndex, int32_t *pParaStart,
1420 int32_t *pParaLimit, UBiDiLevel *pParaLevel,
1421 UErrorCode *pErrorCode);
1424 * Get a paragraph, given the index of this paragraph.
1426 * This function returns information about a paragraph.<p>
1428 * @param pBiDi is the paragraph <code>UBiDi</code> object.
1430 * @param paraIndex is the number of the paragraph, in the
1431 * range <code>[0..ubidi_countParagraphs(pBiDi)-1]</code>.
1433 * @param pParaStart will receive the index of the first character of the
1434 * paragraph in the text.
1435 * This pointer can be <code>NULL</code> if this
1436 * value is not necessary.
1438 * @param pParaLimit will receive the limit of the paragraph.
1439 * This pointer can be <code>NULL</code> if this
1440 * value is not necessary.
1442 * @param pParaLevel will receive the level of the paragraph.
1443 * This pointer can be <code>NULL</code> if this
1444 * value is not necessary.
1446 * @param pErrorCode must be a valid pointer to an error code value.
1450 U_STABLE void U_EXPORT2
1451 ubidi_getParagraphByIndex(const UBiDi *pBiDi, int32_t paraIndex,
1452 int32_t *pParaStart, int32_t *pParaLimit,
1453 UBiDiLevel *pParaLevel, UErrorCode *pErrorCode);
1456 * Get the level for one character.
1458 * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1460 * @param charIndex the index of a character. It must be in the range
1461 * [0..ubidi_getProcessedLength(pBiDi)].
1463 * @return The level for the character at charIndex (0 if charIndex is not
1464 * in the valid range).
1467 * @see ubidi_getProcessedLength
1470 U_STABLE UBiDiLevel U_EXPORT2
1471 ubidi_getLevelAt(const UBiDi *pBiDi, int32_t charIndex);
1474 * Get an array of levels for each character.<p>
1476 * Note that this function may allocate memory under some
1477 * circumstances, unlike <code>ubidi_getLevelAt()</code>.
1479 * @param pBiDi is the paragraph or line <code>UBiDi</code> object, whose
1480 * text length must be strictly positive.
1482 * @param pErrorCode must be a valid pointer to an error code value.
1484 * @return The levels array for the text,
1485 * or <code>NULL</code> if an error occurs.
1488 * @see ubidi_getProcessedLength
1491 U_STABLE const UBiDiLevel * U_EXPORT2
1492 ubidi_getLevels(UBiDi *pBiDi, UErrorCode *pErrorCode);
1495 * Get a logical run.
1496 * This function returns information about a run and is used
1497 * to retrieve runs in logical order.<p>
1498 * This is especially useful for line-breaking on a paragraph.
1500 * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1502 * @param logicalPosition is a logical position within the source text.
1504 * @param pLogicalLimit will receive the limit of the corresponding run.
1505 * The l-value that you point to here may be the
1506 * same expression (variable) as the one for
1507 * <code>logicalPosition</code>.
1508 * This pointer can be <code>NULL</code> if this
1509 * value is not necessary.
1511 * @param pLevel will receive the level of the corresponding run.
1512 * This pointer can be <code>NULL</code> if this
1513 * value is not necessary.
1515 * @see ubidi_getProcessedLength
1518 U_STABLE void U_EXPORT2
1519 ubidi_getLogicalRun(const UBiDi *pBiDi, int32_t logicalPosition,
1520 int32_t *pLogicalLimit, UBiDiLevel *pLevel);
1523 * Get the number of runs.
1524 * This function may invoke the actual reordering on the
1525 * <code>UBiDi</code> object, after <code>ubidi_setPara()</code>
1526 * may have resolved only the levels of the text. Therefore,
1527 * <code>ubidi_countRuns()</code> may have to allocate memory,
1528 * and may fail doing so.
1530 * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1532 * @param pErrorCode must be a valid pointer to an error code value.
1534 * @return The number of runs.
1537 U_STABLE int32_t U_EXPORT2
1538 ubidi_countRuns(UBiDi *pBiDi, UErrorCode *pErrorCode);
1541 * Get one run's logical start, length, and directionality,
1542 * which can be 0 for LTR or 1 for RTL.
1543 * In an RTL run, the character at the logical start is
1544 * visually on the right of the displayed run.
1545 * The length is the number of characters in the run.<p>
1546 * <code>ubidi_countRuns()</code> should be called
1547 * before the runs are retrieved.
1549 * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1551 * @param runIndex is the number of the run in visual order, in the
1552 * range <code>[0..ubidi_countRuns(pBiDi)-1]</code>.
1554 * @param pLogicalStart is the first logical character index in the text.
1555 * The pointer may be <code>NULL</code> if this index is not needed.
1557 * @param pLength is the number of characters (at least one) in the run.
1558 * The pointer may be <code>NULL</code> if this is not needed.
1560 * @return the directionality of the run,
1561 * <code>UBIDI_LTR==0</code> or <code>UBIDI_RTL==1</code>,
1562 * never <code>UBIDI_MIXED</code>,
1563 * never <code>UBIDI_NEUTRAL</code>.
1565 * @see ubidi_countRuns
1570 * int32_t i, count=ubidi_countRuns(pBiDi),
1571 * logicalStart, visualIndex=0, length;
1572 * for(i=0; i<count; ++i) {
1573 * if(UBIDI_LTR==ubidi_getVisualRun(pBiDi, i, &logicalStart, &length)) {
1575 * show_char(text[logicalStart++], visualIndex++);
1576 * } while(--length>0);
1578 * logicalStart+=length; // logicalLimit
1580 * show_char(text[--logicalStart], visualIndex++);
1581 * } while(--length>0);
1587 * Note that in right-to-left runs, code like this places
1588 * second surrogates before first ones (which is generally a bad idea)
1589 * and combining characters before base characters.
1591 * Use of <code>ubidi_writeReordered()</code>, optionally with the
1592 * <code>#UBIDI_KEEP_BASE_COMBINING</code> option, can be considered in order
1593 * to avoid these issues.
1596 U_STABLE UBiDiDirection U_EXPORT2
1597 ubidi_getVisualRun(UBiDi *pBiDi, int32_t runIndex,
1598 int32_t *pLogicalStart, int32_t *pLength);
1601 * Get the visual position from a logical text position.
1602 * If such a mapping is used many times on the same
1603 * <code>UBiDi</code> object, then calling
1604 * <code>ubidi_getLogicalMap()</code> is more efficient.<p>
1606 * The value returned may be <code>#UBIDI_MAP_NOWHERE</code> if there is no
1607 * visual position because the corresponding text character is a Bidi control
1608 * removed from output by the option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code>.
1610 * When the visual output is altered by using options of
1611 * <code>ubidi_writeReordered()</code> such as <code>UBIDI_INSERT_LRM_FOR_NUMERIC</code>,
1612 * <code>UBIDI_KEEP_BASE_COMBINING</code>, <code>UBIDI_OUTPUT_REVERSE</code>,
1613 * <code>UBIDI_REMOVE_BIDI_CONTROLS</code>, the visual position returned may not
1614 * be correct. It is advised to use, when possible, reordering options
1615 * such as <code>UBIDI_OPTION_INSERT_MARKS</code> and <code>UBIDI_OPTION_REMOVE_CONTROLS</code>.
1617 * Note that in right-to-left runs, this mapping places
1618 * second surrogates before first ones (which is generally a bad idea)
1619 * and combining characters before base characters.
1620 * Use of <code>ubidi_writeReordered()</code>, optionally with the
1621 * <code>#UBIDI_KEEP_BASE_COMBINING</code> option can be considered instead
1622 * of using the mapping, in order to avoid these issues.
1624 * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1626 * @param logicalIndex is the index of a character in the text.
1628 * @param pErrorCode must be a valid pointer to an error code value.
1630 * @return The visual position of this character.
1632 * @see ubidi_getLogicalMap
1633 * @see ubidi_getLogicalIndex
1634 * @see ubidi_getProcessedLength
1637 U_STABLE int32_t U_EXPORT2
1638 ubidi_getVisualIndex(UBiDi *pBiDi, int32_t logicalIndex, UErrorCode *pErrorCode);
1641 * Get the logical text position from a visual position.
1642 * If such a mapping is used many times on the same
1643 * <code>UBiDi</code> object, then calling
1644 * <code>ubidi_getVisualMap()</code> is more efficient.<p>
1646 * The value returned may be <code>#UBIDI_MAP_NOWHERE</code> if there is no
1647 * logical position because the corresponding text character is a Bidi mark
1648 * inserted in the output by option <code>#UBIDI_OPTION_INSERT_MARKS</code>.
1650 * This is the inverse function to <code>ubidi_getVisualIndex()</code>.
1652 * When the visual output is altered by using options of
1653 * <code>ubidi_writeReordered()</code> such as <code>UBIDI_INSERT_LRM_FOR_NUMERIC</code>,
1654 * <code>UBIDI_KEEP_BASE_COMBINING</code>, <code>UBIDI_OUTPUT_REVERSE</code>,
1655 * <code>UBIDI_REMOVE_BIDI_CONTROLS</code>, the logical position returned may not
1656 * be correct. It is advised to use, when possible, reordering options
1657 * such as <code>UBIDI_OPTION_INSERT_MARKS</code> and <code>UBIDI_OPTION_REMOVE_CONTROLS</code>.
1659 * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1661 * @param visualIndex is the visual position of a character.
1663 * @param pErrorCode must be a valid pointer to an error code value.
1665 * @return The index of this character in the text.
1667 * @see ubidi_getVisualMap
1668 * @see ubidi_getVisualIndex
1669 * @see ubidi_getResultLength
1672 U_STABLE int32_t U_EXPORT2
1673 ubidi_getLogicalIndex(UBiDi *pBiDi, int32_t visualIndex, UErrorCode *pErrorCode);
1676 * Get a logical-to-visual index map (array) for the characters in the UBiDi
1677 * (paragraph or line) object.
1679 * Some values in the map may be <code>#UBIDI_MAP_NOWHERE</code> if the
1680 * corresponding text characters are Bidi controls removed from the visual
1681 * output by the option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code>.
1683 * When the visual output is altered by using options of
1684 * <code>ubidi_writeReordered()</code> such as <code>UBIDI_INSERT_LRM_FOR_NUMERIC</code>,
1685 * <code>UBIDI_KEEP_BASE_COMBINING</code>, <code>UBIDI_OUTPUT_REVERSE</code>,
1686 * <code>UBIDI_REMOVE_BIDI_CONTROLS</code>, the visual positions returned may not
1687 * be correct. It is advised to use, when possible, reordering options
1688 * such as <code>UBIDI_OPTION_INSERT_MARKS</code> and <code>UBIDI_OPTION_REMOVE_CONTROLS</code>.
1690 * Note that in right-to-left runs, this mapping places
1691 * second surrogates before first ones (which is generally a bad idea)
1692 * and combining characters before base characters.
1693 * Use of <code>ubidi_writeReordered()</code>, optionally with the
1694 * <code>#UBIDI_KEEP_BASE_COMBINING</code> option can be considered instead
1695 * of using the mapping, in order to avoid these issues.
1697 * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1699 * @param indexMap is a pointer to an array of <code>ubidi_getProcessedLength()</code>
1700 * indexes which will reflect the reordering of the characters.
1701 * If option <code>#UBIDI_OPTION_INSERT_MARKS</code> is set, the number
1702 * of elements allocated in <code>indexMap</code> must be no less than
1703 * <code>ubidi_getResultLength()</code>.
1704 * The array does not need to be initialized.<br><br>
1705 * The index map will result in <code>indexMap[logicalIndex]==visualIndex</code>.
1707 * @param pErrorCode must be a valid pointer to an error code value.
1709 * @see ubidi_getVisualMap
1710 * @see ubidi_getVisualIndex
1711 * @see ubidi_getProcessedLength
1712 * @see ubidi_getResultLength
1715 U_STABLE void U_EXPORT2
1716 ubidi_getLogicalMap(UBiDi *pBiDi, int32_t *indexMap, UErrorCode *pErrorCode);
1719 * Get a visual-to-logical index map (array) for the characters in the UBiDi
1720 * (paragraph or line) object.
1722 * Some values in the map may be <code>#UBIDI_MAP_NOWHERE</code> if the
1723 * corresponding text characters are Bidi marks inserted in the visual output
1724 * by the option <code>#UBIDI_OPTION_INSERT_MARKS</code>.
1726 * When the visual output is altered by using options of
1727 * <code>ubidi_writeReordered()</code> such as <code>UBIDI_INSERT_LRM_FOR_NUMERIC</code>,
1728 * <code>UBIDI_KEEP_BASE_COMBINING</code>, <code>UBIDI_OUTPUT_REVERSE</code>,
1729 * <code>UBIDI_REMOVE_BIDI_CONTROLS</code>, the logical positions returned may not
1730 * be correct. It is advised to use, when possible, reordering options
1731 * such as <code>UBIDI_OPTION_INSERT_MARKS</code> and <code>UBIDI_OPTION_REMOVE_CONTROLS</code>.
1733 * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1735 * @param indexMap is a pointer to an array of <code>ubidi_getResultLength()</code>
1736 * indexes which will reflect the reordering of the characters.
1737 * If option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code> is set, the number
1738 * of elements allocated in <code>indexMap</code> must be no less than
1739 * <code>ubidi_getProcessedLength()</code>.
1740 * The array does not need to be initialized.<br><br>
1741 * The index map will result in <code>indexMap[visualIndex]==logicalIndex</code>.
1743 * @param pErrorCode must be a valid pointer to an error code value.
1745 * @see ubidi_getLogicalMap
1746 * @see ubidi_getLogicalIndex
1747 * @see ubidi_getProcessedLength
1748 * @see ubidi_getResultLength
1751 U_STABLE void U_EXPORT2
1752 ubidi_getVisualMap(UBiDi *pBiDi, int32_t *indexMap, UErrorCode *pErrorCode);
1755 * This is a convenience function that does not use a UBiDi object.
1756 * It is intended to be used for when an application has determined the levels
1757 * of objects (character sequences) and just needs to have them reordered (L2).
1758 * This is equivalent to using <code>ubidi_getLogicalMap()</code> on a
1759 * <code>UBiDi</code> object.
1761 * @param levels is an array with <code>length</code> levels that have been determined by
1764 * @param length is the number of levels in the array, or, semantically,
1765 * the number of objects to be reordered.
1766 * It must be <code>length>0</code>.
1768 * @param indexMap is a pointer to an array of <code>length</code>
1769 * indexes which will reflect the reordering of the characters.
1770 * The array does not need to be initialized.<p>
1771 * The index map will result in <code>indexMap[logicalIndex]==visualIndex</code>.
1774 U_STABLE void U_EXPORT2
1775 ubidi_reorderLogical(const UBiDiLevel *levels, int32_t length, int32_t *indexMap);
1778 * This is a convenience function that does not use a UBiDi object.
1779 * It is intended to be used for when an application has determined the levels
1780 * of objects (character sequences) and just needs to have them reordered (L2).
1781 * This is equivalent to using <code>ubidi_getVisualMap()</code> on a
1782 * <code>UBiDi</code> object.
1784 * @param levels is an array with <code>length</code> levels that have been determined by
1787 * @param length is the number of levels in the array, or, semantically,
1788 * the number of objects to be reordered.
1789 * It must be <code>length>0</code>.
1791 * @param indexMap is a pointer to an array of <code>length</code>
1792 * indexes which will reflect the reordering of the characters.
1793 * The array does not need to be initialized.<p>
1794 * The index map will result in <code>indexMap[visualIndex]==logicalIndex</code>.
1797 U_STABLE void U_EXPORT2
1798 ubidi_reorderVisual(const UBiDiLevel *levels, int32_t length, int32_t *indexMap);
1801 * Invert an index map.
1802 * The index mapping of the first map is inverted and written to
1805 * @param srcMap is an array with <code>length</code> elements
1806 * which defines the original mapping from a source array containing
1807 * <code>length</code> elements to a destination array.
1808 * Some elements of the source array may have no mapping in the
1809 * destination array. In that case, their value will be
1810 * the special value <code>UBIDI_MAP_NOWHERE</code>.
1811 * All elements must be >=0 or equal to <code>UBIDI_MAP_NOWHERE</code>.
1812 * Some elements may have a value >= <code>length</code>, if the
1813 * destination array has more elements than the source array.
1814 * There must be no duplicate indexes (two or more elements with the
1815 * same value except <code>UBIDI_MAP_NOWHERE</code>).
1817 * @param destMap is an array with a number of elements equal to 1 + the highest
1818 * value in <code>srcMap</code>.
1819 * <code>destMap</code> will be filled with the inverse mapping.
1820 * If element with index i in <code>srcMap</code> has a value k different
1821 * from <code>UBIDI_MAP_NOWHERE</code>, this means that element i of
1822 * the source array maps to element k in the destination array.
1823 * The inverse map will have value i in its k-th element.
1824 * For all elements of the destination array which do not map to
1825 * an element in the source array, the corresponding element in the
1826 * inverse map will have a value equal to <code>UBIDI_MAP_NOWHERE</code>.
1828 * @param length is the length of each array.
1829 * @see UBIDI_MAP_NOWHERE
1832 U_STABLE void U_EXPORT2
1833 ubidi_invertMap(const int32_t *srcMap, int32_t *destMap, int32_t length);
1835 /** option flags for ubidi_writeReordered() */
1838 * option bit for ubidi_writeReordered():
1839 * keep combining characters after their base characters in RTL runs
1841 * @see ubidi_writeReordered
1844 #define UBIDI_KEEP_BASE_COMBINING 1
1847 * option bit for ubidi_writeReordered():
1848 * replace characters with the "mirrored" property in RTL runs
1849 * by their mirror-image mappings
1851 * @see ubidi_writeReordered
1854 #define UBIDI_DO_MIRRORING 2
1857 * option bit for ubidi_writeReordered():
1858 * surround the run with LRMs if necessary;
1859 * this is part of the approximate "inverse Bidi" algorithm
1861 * <p>This option does not imply corresponding adjustment of the index
1864 * @see ubidi_setInverse
1865 * @see ubidi_writeReordered
1868 #define UBIDI_INSERT_LRM_FOR_NUMERIC 4
1871 * option bit for ubidi_writeReordered():
1872 * remove Bidi control characters
1873 * (this does not affect #UBIDI_INSERT_LRM_FOR_NUMERIC)
1875 * <p>This option does not imply corresponding adjustment of the index
1878 * @see ubidi_writeReordered
1881 #define UBIDI_REMOVE_BIDI_CONTROLS 8
1884 * option bit for ubidi_writeReordered():
1885 * write the output in reverse order
1887 * <p>This has the same effect as calling <code>ubidi_writeReordered()</code>
1888 * first without this option, and then calling
1889 * <code>ubidi_writeReverse()</code> without mirroring.
1890 * Doing this in the same step is faster and avoids a temporary buffer.
1891 * An example for using this option is output to a character terminal that
1892 * is designed for RTL scripts and stores text in reverse order.</p>
1894 * @see ubidi_writeReordered
1897 #define UBIDI_OUTPUT_REVERSE 16
1900 * Get the length of the source text processed by the last call to
1901 * <code>ubidi_setPara()</code>. This length may be different from the length
1902 * of the source text if option <code>#UBIDI_OPTION_STREAMING</code>
1905 * Note that whenever the length of the text affects the execution or the
1906 * result of a function, it is the processed length which must be considered,
1907 * except for <code>ubidi_setPara</code> (which receives unprocessed source
1908 * text) and <code>ubidi_getLength</code> (which returns the original length
1909 * of the source text).<br>
1910 * In particular, the processed length is the one to consider in the following
1913 * <li>maximum value of the <code>limit</code> argument of
1914 * <code>ubidi_setLine</code></li>
1915 * <li>maximum value of the <code>charIndex</code> argument of
1916 * <code>ubidi_getParagraph</code></li>
1917 * <li>maximum value of the <code>charIndex</code> argument of
1918 * <code>ubidi_getLevelAt</code></li>
1919 * <li>number of elements in the array returned by <code>ubidi_getLevels</code></li>
1920 * <li>maximum value of the <code>logicalStart</code> argument of
1921 * <code>ubidi_getLogicalRun</code></li>
1922 * <li>maximum value of the <code>logicalIndex</code> argument of
1923 * <code>ubidi_getVisualIndex</code></li>
1924 * <li>number of elements filled in the <code>*indexMap</code> argument of
1925 * <code>ubidi_getLogicalMap</code></li>
1926 * <li>length of text processed by <code>ubidi_writeReordered</code></li>
1929 * @param pBiDi is the paragraph <code>UBiDi</code> object.
1931 * @return The length of the part of the source text processed by
1932 * the last call to <code>ubidi_setPara</code>.
1933 * @see ubidi_setPara
1934 * @see UBIDI_OPTION_STREAMING
1937 U_STABLE int32_t U_EXPORT2
1938 ubidi_getProcessedLength(const UBiDi *pBiDi);
1941 * Get the length of the reordered text resulting from the last call to
1942 * <code>ubidi_setPara()</code>. This length may be different from the length
1943 * of the source text if option <code>#UBIDI_OPTION_INSERT_MARKS</code>
1944 * or option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code> has been set.
1946 * This resulting length is the one to consider in the following cases:
1948 * <li>maximum value of the <code>visualIndex</code> argument of
1949 * <code>ubidi_getLogicalIndex</code></li>
1950 * <li>number of elements of the <code>*indexMap</code> argument of
1951 * <code>ubidi_getVisualMap</code></li>
1953 * Note that this length stays identical to the source text length if
1954 * Bidi marks are inserted or removed using option bits of
1955 * <code>ubidi_writeReordered</code>, or if option
1956 * <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code> has been set.
1958 * @param pBiDi is the paragraph <code>UBiDi</code> object.
1960 * @return The length of the reordered text resulting from
1961 * the last call to <code>ubidi_setPara</code>.
1962 * @see ubidi_setPara
1963 * @see UBIDI_OPTION_INSERT_MARKS
1964 * @see UBIDI_OPTION_REMOVE_CONTROLS
1967 U_STABLE int32_t U_EXPORT2
1968 ubidi_getResultLength(const UBiDi *pBiDi);
1972 #ifndef U_HIDE_DEPRECATED_API
1974 * Value returned by <code>UBiDiClassCallback</code> callbacks when
1975 * there is no need to override the standard Bidi class for a given code point.
1977 * This constant is deprecated; use u_getIntPropertyMaxValue(UCHAR_BIDI_CLASS)+1 instead.
1979 * @see UBiDiClassCallback
1980 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
1982 #define U_BIDI_CLASS_DEFAULT U_CHAR_DIRECTION_COUNT
1983 #endif // U_HIDE_DEPRECATED_API
1986 * Callback type declaration for overriding default Bidi class values with
1988 * <p>Usually, the function pointer will be propagated to a <code>UBiDi</code>
1989 * object by calling the <code>ubidi_setClassCallback()</code> function;
1990 * then the callback will be invoked by the UBA implementation any time the
1991 * class of a character is to be determined.</p>
1993 * @param context is a pointer to the callback private data.
1995 * @param c is the code point to get a Bidi class for.
1997 * @return The directional property / Bidi class for the given code point
1998 * <code>c</code> if the default class has been overridden, or
1999 * <code>#U_BIDI_CLASS_DEFAULT=u_getIntPropertyMaxValue(UCHAR_BIDI_CLASS)+1</code>
2000 * if the standard Bidi class value for <code>c</code> is to be used.
2001 * @see ubidi_setClassCallback
2002 * @see ubidi_getClassCallback
2005 typedef UCharDirection U_CALLCONV
2006 UBiDiClassCallback(const void *context, UChar32 c);
2011 * Retrieve the Bidi class for a given code point.
2012 * <p>If a <code>#UBiDiClassCallback</code> callback is defined and returns a
2013 * value other than <code>#U_BIDI_CLASS_DEFAULT=u_getIntPropertyMaxValue(UCHAR_BIDI_CLASS)+1</code>,
2014 * that value is used; otherwise the default class determination mechanism is invoked.</p>
2016 * @param pBiDi is the paragraph <code>UBiDi</code> object.
2018 * @param c is the code point whose Bidi class must be retrieved.
2020 * @return The Bidi class for character <code>c</code> based
2021 * on the given <code>pBiDi</code> instance.
2022 * @see UBiDiClassCallback
2025 U_STABLE UCharDirection U_EXPORT2
2026 ubidi_getCustomizedClass(UBiDi *pBiDi, UChar32 c);
2029 * Set the callback function and callback data used by the UBA
2030 * implementation for Bidi class determination.
2031 * <p>This may be useful for assigning Bidi classes to PUA characters, or
2032 * for special application needs. For instance, an application may want to
2033 * handle all spaces like L or R characters (according to the base direction)
2034 * when creating the visual ordering of logical lines which are part of a report
2035 * organized in columns: there should not be interaction between adjacent
2038 * @param pBiDi is the paragraph <code>UBiDi</code> object.
2040 * @param newFn is the new callback function pointer.
2042 * @param newContext is the new callback context pointer. This can be NULL.
2044 * @param oldFn fillin: Returns the old callback function pointer. This can be
2047 * @param oldContext fillin: Returns the old callback's context. This can be
2050 * @param pErrorCode must be a valid pointer to an error code value.
2052 * @see ubidi_getClassCallback
2055 U_STABLE void U_EXPORT2
2056 ubidi_setClassCallback(UBiDi *pBiDi, UBiDiClassCallback *newFn,
2057 const void *newContext, UBiDiClassCallback **oldFn,
2058 const void **oldContext, UErrorCode *pErrorCode);
2061 * Get the current callback function used for Bidi class determination.
2063 * @param pBiDi is the paragraph <code>UBiDi</code> object.
2065 * @param fn fillin: Returns the callback function pointer.
2067 * @param context fillin: Returns the callback's private context.
2069 * @see ubidi_setClassCallback
2072 U_STABLE void U_EXPORT2
2073 ubidi_getClassCallback(UBiDi *pBiDi, UBiDiClassCallback **fn, const void **context);
2076 * Take a <code>UBiDi</code> object containing the reordering
2077 * information for a piece of text (one or more paragraphs) set by
2078 * <code>ubidi_setPara()</code> or for a line of text set by
2079 * <code>ubidi_setLine()</code> and write a reordered string to the
2080 * destination buffer.
2082 * This function preserves the integrity of characters with multiple
2083 * code units and (optionally) combining characters.
2084 * Characters in RTL runs can be replaced by mirror-image characters
2085 * in the destination buffer. Note that "real" mirroring has
2086 * to be done in a rendering engine by glyph selection
2087 * and that for many "mirrored" characters there are no
2088 * Unicode characters as mirror-image equivalents.
2089 * There are also options to insert or remove Bidi control
2090 * characters; see the description of the <code>destSize</code>
2091 * and <code>options</code> parameters and of the option bit flags.
2093 * @param pBiDi A pointer to a <code>UBiDi</code> object that
2094 * is set by <code>ubidi_setPara()</code> or
2095 * <code>ubidi_setLine()</code> and contains the reordering
2096 * information for the text that it was defined for,
2097 * as well as a pointer to that text.<br><br>
2098 * The text was aliased (only the pointer was stored
2099 * without copying the contents) and must not have been modified
2100 * since the <code>ubidi_setPara()</code> call.
2102 * @param dest A pointer to where the reordered text is to be copied.
2103 * The source text and <code>dest[destSize]</code>
2106 * @param destSize The size of the <code>dest</code> buffer,
2107 * in number of UChars.
2108 * If the <code>UBIDI_INSERT_LRM_FOR_NUMERIC</code>
2109 * option is set, then the destination length could be
2111 * <code>ubidi_getLength(pBiDi)+2*ubidi_countRuns(pBiDi)</code>.
2112 * If the <code>UBIDI_REMOVE_BIDI_CONTROLS</code> option
2113 * is set, then the destination length may be less than
2114 * <code>ubidi_getLength(pBiDi)</code>.
2115 * If none of these options is set, then the destination length
2116 * will be exactly <code>ubidi_getProcessedLength(pBiDi)</code>.
2118 * @param options A bit set of options for the reordering that control
2119 * how the reordered text is written.
2120 * The options include mirroring the characters on a code
2121 * point basis and inserting LRM characters, which is used
2122 * especially for transforming visually stored text
2123 * to logically stored text (although this is still an
2124 * imperfect implementation of an "inverse Bidi" algorithm
2125 * because it uses the "forward Bidi" algorithm at its core).
2126 * The available options are:
2127 * <code>#UBIDI_DO_MIRRORING</code>,
2128 * <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code>,
2129 * <code>#UBIDI_KEEP_BASE_COMBINING</code>,
2130 * <code>#UBIDI_OUTPUT_REVERSE</code>,
2131 * <code>#UBIDI_REMOVE_BIDI_CONTROLS</code>
2133 * @param pErrorCode must be a valid pointer to an error code value.
2135 * @return The length of the output string.
2137 * @see ubidi_getProcessedLength
2140 U_STABLE int32_t U_EXPORT2
2141 ubidi_writeReordered(UBiDi *pBiDi,
2142 UChar *dest, int32_t destSize,
2144 UErrorCode *pErrorCode);
2147 * Reverse a Right-To-Left run of Unicode text.
2149 * This function preserves the integrity of characters with multiple
2150 * code units and (optionally) combining characters.
2151 * Characters can be replaced by mirror-image characters
2152 * in the destination buffer. Note that "real" mirroring has
2153 * to be done in a rendering engine by glyph selection
2154 * and that for many "mirrored" characters there are no
2155 * Unicode characters as mirror-image equivalents.
2156 * There are also options to insert or remove Bidi control
2159 * This function is the implementation for reversing RTL runs as part
2160 * of <code>ubidi_writeReordered()</code>. For detailed descriptions
2161 * of the parameters, see there.
2162 * Since no Bidi controls are inserted here, the output string length
2163 * will never exceed <code>srcLength</code>.
2165 * @see ubidi_writeReordered
2167 * @param src A pointer to the RTL run text.
2169 * @param srcLength The length of the RTL run.
2171 * @param dest A pointer to where the reordered text is to be copied.
2172 * <code>src[srcLength]</code> and <code>dest[destSize]</code>
2175 * @param destSize The size of the <code>dest</code> buffer,
2176 * in number of UChars.
2177 * If the <code>UBIDI_REMOVE_BIDI_CONTROLS</code> option
2178 * is set, then the destination length may be less than
2179 * <code>srcLength</code>.
2180 * If this option is not set, then the destination length
2181 * will be exactly <code>srcLength</code>.
2183 * @param options A bit set of options for the reordering that control
2184 * how the reordered text is written.
2185 * See the <code>options</code> parameter in <code>ubidi_writeReordered()</code>.
2187 * @param pErrorCode must be a valid pointer to an error code value.
2189 * @return The length of the output string.
2192 U_STABLE int32_t U_EXPORT2
2193 ubidi_writeReverse(const UChar *src, int32_t srcLength,
2194 UChar *dest, int32_t destSize,
2196 UErrorCode *pErrorCode);
2198 /*#define BIDI_SAMPLE_CODE*/