Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/ubidi.h @ 69:33d812a61356

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