csp2: CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/ubidi.h annotate

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

planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d

author	jpayne
date	Tue, 18 Mar 2025 17:55:14 -0400
parents
children

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

Mercurial > repos > rliterman > csp2

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