codekingpro/portable-devtools
116k
1// © 2016 and later: Unicode, Inc. and others.
2// License & terms of use: http://www.unicode.org/copyright.html
3/*
4******************************************************************************
5*
6* Copyright (C) 1999-2013, International Business Machines
7* Corporation and others. All Rights Reserved.
8*
9******************************************************************************
10* file name: ubidi.h
11* encoding: UTF-8
12* tab size: 8 (not used)
13* indentation:4
14*
15* created on: 1999jul27
16* created by: Markus W. Scherer, updated by Matitiahu Allouche
17*/
18
19#ifndef UBIDI_H
20#define UBIDI_H
21
22#include "unicode/utypes.h"
23#include "unicode/uchar.h"
24#include "unicode/localpointer.h"
25
26/**
27 *\file
28 * \brief C API: Bidi algorithm
29 *
30 * <h2>Bidi algorithm for ICU</h2>
31 *
32 * This is an implementation of the Unicode Bidirectional Algorithm.
33 * The algorithm is defined in the
34 * <a href="http://www.unicode.org/unicode/reports/tr9/">Unicode Standard Annex #9</a>.<p>
35 *
36 * Note: Libraries that perform a bidirectional algorithm and
37 * reorder strings accordingly are sometimes called "Storage Layout Engines".
38 * ICU's Bidi and shaping (u_shapeArabic()) APIs can be used at the core of such
39 * "Storage Layout Engines".
40 *
41 * <h3>General remarks about the API:</h3>
42 *
43 * In functions with an error code parameter,
44 * the <code>pErrorCode</code> pointer must be valid
45 * and the value that it points to must not indicate a failure before
46 * the function call. Otherwise, the function returns immediately.
47 * After the function call, the value indicates success or failure.<p>
48 *
49 * The "limit" of a sequence of characters is the position just after their
50 * last character, i.e., one more than that position.<p>
51 *
52 * Some of the API functions provide access to "runs".
53 * Such a "run" is defined as a sequence of characters
54 * that are at the same embedding level
55 * after performing the Bidi algorithm.<p>
56 *
57 * @author Markus W. Scherer
58 * @version 1.0
59 *
60 *
61 * <h4> Sample code for the ICU Bidi API </h4>
62 *
63 * <h5>Rendering a paragraph with the ICU Bidi API</h5>
64 *
65 * This is (hypothetical) sample code that illustrates
66 * how the ICU Bidi API could be used to render a paragraph of text.
67 * Rendering code depends highly on the graphics system,
68 * therefore this sample code must make a lot of assumptions,
69 * which may or may not match any existing graphics system's properties.
70 *
71 * <p>The basic assumptions are:</p>
72 * <ul>
73 * <li>Rendering is done from left to right on a horizontal line.</li>
74 * <li>A run of single-style, unidirectional text can be rendered at once.</li>
75 * <li>Such a run of text is passed to the graphics system with
76 * characters (code units) in logical order.</li>
77 * <li>The line-breaking algorithm is very complicated
78 * and Locale-dependent -
79 * and therefore its implementation omitted from this sample code.</li>
80 * </ul>
81 *
82 * <pre>
83 * \code
84 *#include "unicode/ubidi.h"
85 *
86 *typedef enum {
87 * styleNormal=0, styleSelected=1,
88 * styleBold=2, styleItalics=4,
89 * styleSuper=8, styleSub=16
90 *} Style;
91 *
92 *typedef struct { int32_t limit; Style style; } StyleRun;
93 *
94 *int getTextWidth(const UChar *text, int32_t start, int32_t limit,
95 * const StyleRun *styleRuns, int styleRunCount);
96 *
97 * // set *pLimit and *pStyleRunLimit for a line
98 * // from text[start] and from styleRuns[styleRunStart]
99 * // using ubidi_getLogicalRun(para, ...)
100 *void getLineBreak(const UChar *text, int32_t start, int32_t *pLimit,
101 * UBiDi *para,
102 * const StyleRun *styleRuns, int styleRunStart, int *pStyleRunLimit,
103 * int *pLineWidth);
104 *
105 * // render runs on a line sequentially, always from left to right
106 *
107 * // prepare rendering a new line
108 * void startLine(UBiDiDirection textDirection, int lineWidth);
109 *
110 * // render a run of text and advance to the right by the run width
111 * // the text[start..limit-1] is always in logical order
112 * void renderRun(const UChar *text, int32_t start, int32_t limit,
113 * UBiDiDirection textDirection, Style style);
114 *
115 * // We could compute a cross-product
116 * // from the style runs with the directional runs
117 * // and then reorder it.
118 * // Instead, here we iterate over each run type
119 * // and render the intersections -
120 * // with shortcuts in simple (and common) cases.
121 * // renderParagraph() is the main function.
122 *
123 * // render a directional run with
124 * // (possibly) multiple style runs intersecting with it
125 * void renderDirectionalRun(const UChar *text,
126 * int32_t start, int32_t limit,
127 * UBiDiDirection direction,
128 * const StyleRun *styleRuns, int styleRunCount) {
129 * int i;
130 *
131 * // iterate over style runs
132 * if(direction==UBIDI_LTR) {
133 * int styleLimit;
134 *
135 * for(i=0; i<styleRunCount; ++i) {
136 * styleLimit=styleRun[i].limit;
137 * if(start<styleLimit) {
138 * if(styleLimit>limit) { styleLimit=limit; }
139 * renderRun(text, start, styleLimit,
140 * direction, styleRun[i].style);
141 * if(styleLimit==limit) { break; }
142 * start=styleLimit;
143 * }
144 * }
145 * } else {
146 * int styleStart;
147 *
148 * for(i=styleRunCount-1; i>=0; --i) {
149 * if(i>0) {
150 * styleStart=styleRun[i-1].limit;
151 * } else {
152 * styleStart=0;
153 * }
154 * if(limit>=styleStart) {
155 * if(styleStart<start) { styleStart=start; }
156 * renderRun(text, styleStart, limit,
157 * direction, styleRun[i].style);
158 * if(styleStart==start) { break; }
159 * limit=styleStart;
160 * }
161 * }
162 * }
163 * }
164 *
165 * // the line object represents text[start..limit-1]
166 * void renderLine(UBiDi *line, const UChar *text,
167 * int32_t start, int32_t limit,
168 * const StyleRun *styleRuns, int styleRunCount) {
169 * UBiDiDirection direction=ubidi_getDirection(line);
170 * if(direction!=UBIDI_MIXED) {
171 * // unidirectional
172 * if(styleRunCount<=1) {
173 * renderRun(text, start, limit, direction, styleRuns[0].style);
174 * } else {
175 * renderDirectionalRun(text, start, limit,
176 * direction, styleRuns, styleRunCount);
177 * }
178 * } else {
179 * // mixed-directional
180 * int32_t count, i, length;
181 * UBiDiLevel level;
182 *
183 * count=ubidi_countRuns(para, pErrorCode);
184 * if(U_SUCCESS(*pErrorCode)) {
185 * if(styleRunCount<=1) {
186 * Style style=styleRuns[0].style;
187 *
188 * // iterate over directional runs
189 * for(i=0; i<count; ++i) {
190 * direction=ubidi_getVisualRun(para, i, &start, &length);
191 * renderRun(text, start, start+length, direction, style);
192 * }
193 * } else {
194 * int32_t j;
195 *
196 * // iterate over both directional and style runs
197 * for(i=0; i<count; ++i) {
198 * direction=ubidi_getVisualRun(line, i, &start, &length);
199 * renderDirectionalRun(text, start, start+length,
200 * direction, styleRuns, styleRunCount);
201 * }
202 * }
203 * }
204 * }
205 * }
206 *
207 *void renderParagraph(const UChar *text, int32_t length,
208 * UBiDiDirection textDirection,
209 * const StyleRun *styleRuns, int styleRunCount,
210 * int lineWidth,
211 * UErrorCode *pErrorCode) {
212 * UBiDi *para;
213 *
214 * if(pErrorCode==NULL || U_FAILURE(*pErrorCode) || length<=0) {
215 * return;
216 * }
217 *
218 * para=ubidi_openSized(length, 0, pErrorCode);
219 * if(para==NULL) { return; }
220 *
221 * ubidi_setPara(para, text, length,
222 * textDirection ? UBIDI_DEFAULT_RTL : UBIDI_DEFAULT_LTR,
223 * NULL, pErrorCode);
224 * if(U_SUCCESS(*pErrorCode)) {
225 * UBiDiLevel paraLevel=1&ubidi_getParaLevel(para);
226 * StyleRun styleRun={ length, styleNormal };
227 * int width;
228 *
229 * if(styleRuns==NULL || styleRunCount<=0) {
230 * styleRunCount=1;
231 * styleRuns=&styleRun;
232 * }
233 *
234 * // assume styleRuns[styleRunCount-1].limit>=length
235 *
236 * width=getTextWidth(text, 0, length, styleRuns, styleRunCount);
237 * if(width<=lineWidth) {
238 * // everything fits onto one line
239 *
240 * // prepare rendering a new line from either left or right
241 * startLine(paraLevel, width);
242 *
243 * renderLine(para, text, 0, length,
244 * styleRuns, styleRunCount);
245 * } else {
246 * UBiDi *line;
247 *
248 * // we need to render several lines
249 * line=ubidi_openSized(length, 0, pErrorCode);
250 * if(line!=NULL) {
251 * int32_t start=0, limit;
252 * int styleRunStart=0, styleRunLimit;
253 *
254 * for(;;) {
255 * limit=length;
256 * styleRunLimit=styleRunCount;
257 * getLineBreak(text, start, &limit, para,
258 * styleRuns, styleRunStart, &styleRunLimit,
259 * &width);
260 * ubidi_setLine(para, start, limit, line, pErrorCode);
261 * if(U_SUCCESS(*pErrorCode)) {
262 * // prepare rendering a new line
263 * // from either left or right
264 * startLine(paraLevel, width);
265 *
266 * renderLine(line, text, start, limit,
267 * styleRuns+styleRunStart,
268 * styleRunLimit-styleRunStart);
269 * }
270 * if(limit==length) { break; }
271 * start=limit;
272 * styleRunStart=styleRunLimit-1;
273 * if(start>=styleRuns[styleRunStart].limit) {
274 * ++styleRunStart;
275 * }
276 * }
277 *
278 * ubidi_close(line);
279 * }
280 * }
281 * }
282 *
283 * ubidi_close(para);
284 *}
285 *\endcode
286 * </pre>
287 */
288
289/*DOCXX_TAG*/
290/*@{*/
291
292/**
293 * UBiDiLevel is the type of the level values in this
294 * Bidi implementation.
295 * It holds an embedding level and indicates the visual direction
296 * by its bit 0 (even/odd value).<p>
297 *
298 * It can also hold non-level values for the
299 * <code>paraLevel</code> and <code>embeddingLevels</code>
300 * arguments of <code>ubidi_setPara()</code>; there:
301 * <ul>
302 * <li>bit 7 of an <code>embeddingLevels[]</code>
303 * value indicates whether the using application is
304 * specifying the level of a character to <i>override</i> whatever the
305 * Bidi implementation would resolve it to.</li>
306 * <li><code>paraLevel</code> can be set to the
307 * pseudo-level values <code>UBIDI_DEFAULT_LTR</code>
308 * and <code>UBIDI_DEFAULT_RTL</code>.</li>
309 * </ul>
310 *
311 * @see ubidi_setPara
312 *
313 * <p>The related constants are not real, valid level values.
314 * <code>UBIDI_DEFAULT_XXX</code> can be used to specify
315 * a default for the paragraph level for
316 * when the <code>ubidi_setPara()</code> function
317 * shall determine it but there is no
318 * strongly typed character in the input.<p>
319 *
320 * Note that the value for <code>UBIDI_DEFAULT_LTR</code> is even
321 * and the one for <code>UBIDI_DEFAULT_RTL</code> is odd,
322 * just like with normal LTR and RTL level values -
323 * these special values are designed that way. Also, the implementation
324 * assumes that UBIDI_MAX_EXPLICIT_LEVEL is odd.
325 *
326 * Note: The numeric values of the related constants will not change:
327 * They are tied to the use of 7-bit byte values (plus the override bit)
328 * and of the UBiDiLevel=uint8_t data type in this API.
329 *
330 * @see UBIDI_DEFAULT_LTR
331 * @see UBIDI_DEFAULT_RTL
332 * @see UBIDI_LEVEL_OVERRIDE
333 * @see UBIDI_MAX_EXPLICIT_LEVEL
334 * @stable ICU 2.0
335 */
336typedef 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 */
425enum 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 */
467typedef 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 */
479struct UBiDi;
480
481/** @stable ICU 2.0 */
482typedef 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 */
499U_STABLE UBiDi * U_EXPORT2
500ubidi_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 */
536U_STABLE UBiDi * U_EXPORT2
537ubidi_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 */
559U_STABLE void U_EXPORT2
560ubidi_close(UBiDi *pBiDi);
561
562#if U_SHOW_CPLUSPLUS_API
563
564U_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 */
575U_DEFINE_LOCAL_OPEN_POINTER(LocalUBiDiPointer, UBiDi, ubidi_close);
576
577U_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 */
629U_STABLE void U_EXPORT2
630ubidi_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
648U_STABLE UBool U_EXPORT2
649ubidi_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 */
671U_STABLE void U_EXPORT2
672ubidi_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 */
685U_STABLE UBool U_EXPORT2
686ubidi_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 */
695typedef 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 */
889U_STABLE void U_EXPORT2
890ubidi_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 */
900U_STABLE UBiDiReorderingMode U_EXPORT2
901ubidi_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 */
910typedef 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 */
1045U_STABLE void U_EXPORT2
1046ubidi_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 */
1056U_STABLE uint32_t U_EXPORT2
1057ubidi_getReorderingOptions(UBiDi *pBiDi);
1058
1059/**
1060 * Set the context before a call to ubidi_setPara().<p>
1061 *
1062 * ubidi_setPara() computes the left-right directionality for a given piece
1063 * of text which is supplied as one of its arguments. Sometimes this piece
1064 * of text (the "main text") should be considered in context, because text
1065 * appearing before ("prologue") and/or after ("epilogue") the main text
1066 * may affect the result of this computation.<p>
1067 *
1068 * This function specifies the prologue and/or the epilogue for the next
1069 * call to ubidi_setPara(). The characters specified as prologue and
1070 * epilogue should not be modified by the calling program until the call
1071 * to ubidi_setPara() has returned. If successive calls to ubidi_setPara()
1072 * all need specification of a context, ubidi_setContext() must be called
1073 * before each call to ubidi_setPara(). In other words, a context is not
1074 * "remembered" after the following successful call to ubidi_setPara().<p>
1075 *
1076 * If a call to ubidi_setPara() specifies UBIDI_DEFAULT_LTR or
1077 * UBIDI_DEFAULT_RTL as paraLevel and is preceded by a call to
1078 * ubidi_setContext() which specifies a prologue, the paragraph level will
1079 * be computed taking in consideration the text in the prologue.<p>
1080 *
1081 * When ubidi_setPara() is called without a previous call to
1082 * ubidi_setContext, the main text is handled as if preceded and followed
1083 * by strong directional characters at the current paragraph level.
1084 * Calling ubidi_setContext() with specification of a prologue will change
1085 * this behavior by handling the main text as if preceded by the last
1086 * strong character appearing in the prologue, if any.
1087 * Calling ubidi_setContext() with specification of an epilogue will change
1088 * the behavior of ubidi_setPara() by handling the main text as if followed
1089 * by the first strong character or digit appearing in the epilogue, if any.<p>
1090 *
1091 * Note 1: if <code>ubidi_setContext</code> is called repeatedly without
1092 * calling <code>ubidi_setPara</code>, the earlier calls have no effect,
1093 * only the last call will be remembered for the next call to
1094 * <code>ubidi_setPara</code>.<p>
1095 *
1096 * Note 2: calling <code>ubidi_setContext(pBiDi, NULL, 0, NULL, 0, &errorCode)</code>
1097 * cancels any previous setting of non-empty prologue or epilogue.
1098 * The next call to <code>ubidi_setPara()</code> will process no
1099 * prologue or epilogue.<p>
1100 *
1101 * Note 3: users must be aware that even after setting the context
1102 * before a call to ubidi_setPara() to perform e.g. a logical to visual
1103 * transformation, the resulting string may not be identical to what it
1104 * would have been if all the text, including prologue and epilogue, had
1105 * been processed together.<br>
1106 * Example (upper case letters represent RTL characters):<br>
1107 * prologue = "<code>abc DE</code>"<br>
1108 * epilogue = none<br>
1109 * main text = "<code>FGH xyz</code>"<br>
1110 * paraLevel = UBIDI_LTR<br>
1111 * display without prologue = "<code>HGF xyz</code>"
1112 * ("HGF" is adjacent to "xyz")<br>
1113 * display with prologue = "<code>abc HGFED xyz</code>"
1114 * ("HGF" is not adjacent to "xyz")<br>
1115 *
1116 * @param pBiDi is a paragraph <code>UBiDi</code> object.
1117 *
1118 * @param prologue is a pointer to the text which precedes the text that
1119 * will be specified in a coming call to ubidi_setPara().
1120 * If there is no prologue to consider, then <code>proLength</code>
1121 * must be zero and this pointer can be NULL.
1122 *
1123 * @param proLength is the length of the prologue; if <code>proLength==-1</code>
1124 * then the prologue must be zero-terminated.
1125 * Otherwise proLength must be >= 0. If <code>proLength==0</code>, it means
1126 * that there is no prologue to consider.
1127 *
1128 * @param epilogue is a pointer to the text which follows the text that
1129 * will be specified in a coming call to ubidi_setPara().
1130 * If there is no epilogue to consider, then <code>epiLength</code>
1131 * must be zero and this pointer can be NULL.
1132 *
1133 * @param epiLength is the length of the epilogue; if <code>epiLength==-1</code>
1134 * then the epilogue must be zero-terminated.
1135 * Otherwise epiLength must be >= 0. If <code>epiLength==0</code>, it means
1136 * that there is no epilogue to consider.
1137 *
1138 * @param pErrorCode must be a valid pointer to an error code value.
1139 *
1140 * @see ubidi_setPara
1141 * @stable ICU 4.8
1142 */
1143U_STABLE void U_EXPORT2
1144ubidi_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,