1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/common/unicode/ubidi.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,2186 @@
1.4 +/*
1.5 +******************************************************************************
1.6 +*
1.7 +* Copyright (C) 1999-2013, International Business Machines
1.8 +* Corporation and others. All Rights Reserved.
1.9 +*
1.10 +******************************************************************************
1.11 +* file name: ubidi.h
1.12 +* encoding: US-ASCII
1.13 +* tab size: 8 (not used)
1.14 +* indentation:4
1.15 +*
1.16 +* created on: 1999jul27
1.17 +* created by: Markus W. Scherer, updated by Matitiahu Allouche
1.18 +*/
1.19 +
1.20 +#ifndef UBIDI_H
1.21 +#define UBIDI_H
1.22 +
1.23 +#include "unicode/utypes.h"
1.24 +#include "unicode/uchar.h"
1.25 +#include "unicode/localpointer.h"
1.26 +
1.27 +/**
1.28 + *\file
1.29 + * \brief C API: Bidi algorithm
1.30 + *
1.31 + * <h2>Bidi algorithm for ICU</h2>
1.32 + *
1.33 + * This is an implementation of the Unicode Bidirectional Algorithm.
1.34 + * The algorithm is defined in the
1.35 + * <a href="http://www.unicode.org/unicode/reports/tr9/">Unicode Standard Annex #9</a>.<p>
1.36 + *
1.37 + * Note: Libraries that perform a bidirectional algorithm and
1.38 + * reorder strings accordingly are sometimes called "Storage Layout Engines".
1.39 + * ICU's Bidi and shaping (u_shapeArabic()) APIs can be used at the core of such
1.40 + * "Storage Layout Engines".
1.41 + *
1.42 + * <h3>General remarks about the API:</h3>
1.43 + *
1.44 + * In functions with an error code parameter,
1.45 + * the <code>pErrorCode</code> pointer must be valid
1.46 + * and the value that it points to must not indicate a failure before
1.47 + * the function call. Otherwise, the function returns immediately.
1.48 + * After the function call, the value indicates success or failure.<p>
1.49 + *
1.50 + * The "limit" of a sequence of characters is the position just after their
1.51 + * last character, i.e., one more than that position.<p>
1.52 + *
1.53 + * Some of the API functions provide access to "runs".
1.54 + * Such a "run" is defined as a sequence of characters
1.55 + * that are at the same embedding level
1.56 + * after performing the Bidi algorithm.<p>
1.57 + *
1.58 + * @author Markus W. Scherer
1.59 + * @version 1.0
1.60 + *
1.61 + *
1.62 + * <h4> Sample code for the ICU Bidi API </h4>
1.63 + *
1.64 + * <h5>Rendering a paragraph with the ICU Bidi API</h5>
1.65 + *
1.66 + * This is (hypothetical) sample code that illustrates
1.67 + * how the ICU Bidi API could be used to render a paragraph of text.
1.68 + * Rendering code depends highly on the graphics system,
1.69 + * therefore this sample code must make a lot of assumptions,
1.70 + * which may or may not match any existing graphics system's properties.
1.71 + *
1.72 + * <p>The basic assumptions are:</p>
1.73 + * <ul>
1.74 + * <li>Rendering is done from left to right on a horizontal line.</li>
1.75 + * <li>A run of single-style, unidirectional text can be rendered at once.</li>
1.76 + * <li>Such a run of text is passed to the graphics system with
1.77 + * characters (code units) in logical order.</li>
1.78 + * <li>The line-breaking algorithm is very complicated
1.79 + * and Locale-dependent -
1.80 + * and therefore its implementation omitted from this sample code.</li>
1.81 + * </ul>
1.82 + *
1.83 + * <pre>
1.84 + * \code
1.85 + *#include "unicode/ubidi.h"
1.86 + *
1.87 + *typedef enum {
1.88 + * styleNormal=0, styleSelected=1,
1.89 + * styleBold=2, styleItalics=4,
1.90 + * styleSuper=8, styleSub=16
1.91 + *} Style;
1.92 + *
1.93 + *typedef struct { int32_t limit; Style style; } StyleRun;
1.94 + *
1.95 + *int getTextWidth(const UChar *text, int32_t start, int32_t limit,
1.96 + * const StyleRun *styleRuns, int styleRunCount);
1.97 + *
1.98 + * // set *pLimit and *pStyleRunLimit for a line
1.99 + * // from text[start] and from styleRuns[styleRunStart]
1.100 + * // using ubidi_getLogicalRun(para, ...)
1.101 + *void getLineBreak(const UChar *text, int32_t start, int32_t *pLimit,
1.102 + * UBiDi *para,
1.103 + * const StyleRun *styleRuns, int styleRunStart, int *pStyleRunLimit,
1.104 + * int *pLineWidth);
1.105 + *
1.106 + * // render runs on a line sequentially, always from left to right
1.107 + *
1.108 + * // prepare rendering a new line
1.109 + * void startLine(UBiDiDirection textDirection, int lineWidth);
1.110 + *
1.111 + * // render a run of text and advance to the right by the run width
1.112 + * // the text[start..limit-1] is always in logical order
1.113 + * void renderRun(const UChar *text, int32_t start, int32_t limit,
1.114 + * UBiDiDirection textDirection, Style style);
1.115 + *
1.116 + * // We could compute a cross-product
1.117 + * // from the style runs with the directional runs
1.118 + * // and then reorder it.
1.119 + * // Instead, here we iterate over each run type
1.120 + * // and render the intersections -
1.121 + * // with shortcuts in simple (and common) cases.
1.122 + * // renderParagraph() is the main function.
1.123 + *
1.124 + * // render a directional run with
1.125 + * // (possibly) multiple style runs intersecting with it
1.126 + * void renderDirectionalRun(const UChar *text,
1.127 + * int32_t start, int32_t limit,
1.128 + * UBiDiDirection direction,
1.129 + * const StyleRun *styleRuns, int styleRunCount) {
1.130 + * int i;
1.131 + *
1.132 + * // iterate over style runs
1.133 + * if(direction==UBIDI_LTR) {
1.134 + * int styleLimit;
1.135 + *
1.136 + * for(i=0; i<styleRunCount; ++i) {
1.137 + * styleLimit=styleRun[i].limit;
1.138 + * if(start<styleLimit) {
1.139 + * if(styleLimit>limit) { styleLimit=limit; }
1.140 + * renderRun(text, start, styleLimit,
1.141 + * direction, styleRun[i].style);
1.142 + * if(styleLimit==limit) { break; }
1.143 + * start=styleLimit;
1.144 + * }
1.145 + * }
1.146 + * } else {
1.147 + * int styleStart;
1.148 + *
1.149 + * for(i=styleRunCount-1; i>=0; --i) {
1.150 + * if(i>0) {
1.151 + * styleStart=styleRun[i-1].limit;
1.152 + * } else {
1.153 + * styleStart=0;
1.154 + * }
1.155 + * if(limit>=styleStart) {
1.156 + * if(styleStart<start) { styleStart=start; }
1.157 + * renderRun(text, styleStart, limit,
1.158 + * direction, styleRun[i].style);
1.159 + * if(styleStart==start) { break; }
1.160 + * limit=styleStart;
1.161 + * }
1.162 + * }
1.163 + * }
1.164 + * }
1.165 + *
1.166 + * // the line object represents text[start..limit-1]
1.167 + * void renderLine(UBiDi *line, const UChar *text,
1.168 + * int32_t start, int32_t limit,
1.169 + * const StyleRun *styleRuns, int styleRunCount) {
1.170 + * UBiDiDirection direction=ubidi_getDirection(line);
1.171 + * if(direction!=UBIDI_MIXED) {
1.172 + * // unidirectional
1.173 + * if(styleRunCount<=1) {
1.174 + * renderRun(text, start, limit, direction, styleRuns[0].style);
1.175 + * } else {
1.176 + * renderDirectionalRun(text, start, limit,
1.177 + * direction, styleRuns, styleRunCount);
1.178 + * }
1.179 + * } else {
1.180 + * // mixed-directional
1.181 + * int32_t count, i, length;
1.182 + * UBiDiLevel level;
1.183 + *
1.184 + * count=ubidi_countRuns(para, pErrorCode);
1.185 + * if(U_SUCCESS(*pErrorCode)) {
1.186 + * if(styleRunCount<=1) {
1.187 + * Style style=styleRuns[0].style;
1.188 + *
1.189 + * // iterate over directional runs
1.190 + * for(i=0; i<count; ++i) {
1.191 + * direction=ubidi_getVisualRun(para, i, &start, &length);
1.192 + * renderRun(text, start, start+length, direction, style);
1.193 + * }
1.194 + * } else {
1.195 + * int32_t j;
1.196 + *
1.197 + * // iterate over both directional and style runs
1.198 + * for(i=0; i<count; ++i) {
1.199 + * direction=ubidi_getVisualRun(line, i, &start, &length);
1.200 + * renderDirectionalRun(text, start, start+length,
1.201 + * direction, styleRuns, styleRunCount);
1.202 + * }
1.203 + * }
1.204 + * }
1.205 + * }
1.206 + * }
1.207 + *
1.208 + *void renderParagraph(const UChar *text, int32_t length,
1.209 + * UBiDiDirection textDirection,
1.210 + * const StyleRun *styleRuns, int styleRunCount,
1.211 + * int lineWidth,
1.212 + * UErrorCode *pErrorCode) {
1.213 + * UBiDi *para;
1.214 + *
1.215 + * if(pErrorCode==NULL || U_FAILURE(*pErrorCode) || length<=0) {
1.216 + * return;
1.217 + * }
1.218 + *
1.219 + * para=ubidi_openSized(length, 0, pErrorCode);
1.220 + * if(para==NULL) { return; }
1.221 + *
1.222 + * ubidi_setPara(para, text, length,
1.223 + * textDirection ? UBIDI_DEFAULT_RTL : UBIDI_DEFAULT_LTR,
1.224 + * NULL, pErrorCode);
1.225 + * if(U_SUCCESS(*pErrorCode)) {
1.226 + * UBiDiLevel paraLevel=1&ubidi_getParaLevel(para);
1.227 + * StyleRun styleRun={ length, styleNormal };
1.228 + * int width;
1.229 + *
1.230 + * if(styleRuns==NULL || styleRunCount<=0) {
1.231 + * styleRunCount=1;
1.232 + * styleRuns=&styleRun;
1.233 + * }
1.234 + *
1.235 + * // assume styleRuns[styleRunCount-1].limit>=length
1.236 + *
1.237 + * width=getTextWidth(text, 0, length, styleRuns, styleRunCount);
1.238 + * if(width<=lineWidth) {
1.239 + * // everything fits onto one line
1.240 + *
1.241 + * // prepare rendering a new line from either left or right
1.242 + * startLine(paraLevel, width);
1.243 + *
1.244 + * renderLine(para, text, 0, length,
1.245 + * styleRuns, styleRunCount);
1.246 + * } else {
1.247 + * UBiDi *line;
1.248 + *
1.249 + * // we need to render several lines
1.250 + * line=ubidi_openSized(length, 0, pErrorCode);
1.251 + * if(line!=NULL) {
1.252 + * int32_t start=0, limit;
1.253 + * int styleRunStart=0, styleRunLimit;
1.254 + *
1.255 + * for(;;) {
1.256 + * limit=length;
1.257 + * styleRunLimit=styleRunCount;
1.258 + * getLineBreak(text, start, &limit, para,
1.259 + * styleRuns, styleRunStart, &styleRunLimit,
1.260 + * &width);
1.261 + * ubidi_setLine(para, start, limit, line, pErrorCode);
1.262 + * if(U_SUCCESS(*pErrorCode)) {
1.263 + * // prepare rendering a new line
1.264 + * // from either left or right
1.265 + * startLine(paraLevel, width);
1.266 + *
1.267 + * renderLine(line, text, start, limit,
1.268 + * styleRuns+styleRunStart,
1.269 + * styleRunLimit-styleRunStart);
1.270 + * }
1.271 + * if(limit==length) { break; }
1.272 + * start=limit;
1.273 + * styleRunStart=styleRunLimit-1;
1.274 + * if(start>=styleRuns[styleRunStart].limit) {
1.275 + * ++styleRunStart;
1.276 + * }
1.277 + * }
1.278 + *
1.279 + * ubidi_close(line);
1.280 + * }
1.281 + * }
1.282 + * }
1.283 + *
1.284 + * ubidi_close(para);
1.285 + *}
1.286 + *\endcode
1.287 + * </pre>
1.288 + */
1.289 +
1.290 +/*DOCXX_TAG*/
1.291 +/*@{*/
1.292 +
1.293 +/**
1.294 + * UBiDiLevel is the type of the level values in this
1.295 + * Bidi implementation.
1.296 + * It holds an embedding level and indicates the visual direction
1.297 + * by its bit 0 (even/odd value).<p>
1.298 + *
1.299 + * It can also hold non-level values for the
1.300 + * <code>paraLevel</code> and <code>embeddingLevels</code>
1.301 + * arguments of <code>ubidi_setPara()</code>; there:
1.302 + * <ul>
1.303 + * <li>bit 7 of an <code>embeddingLevels[]</code>
1.304 + * value indicates whether the using application is
1.305 + * specifying the level of a character to <i>override</i> whatever the
1.306 + * Bidi implementation would resolve it to.</li>
1.307 + * <li><code>paraLevel</code> can be set to the
1.308 + * pseudo-level values <code>UBIDI_DEFAULT_LTR</code>
1.309 + * and <code>UBIDI_DEFAULT_RTL</code>.</li>
1.310 + * </ul>
1.311 + *
1.312 + * @see ubidi_setPara
1.313 + *
1.314 + * <p>The related constants are not real, valid level values.
1.315 + * <code>UBIDI_DEFAULT_XXX</code> can be used to specify
1.316 + * a default for the paragraph level for
1.317 + * when the <code>ubidi_setPara()</code> function
1.318 + * shall determine it but there is no
1.319 + * strongly typed character in the input.<p>
1.320 + *
1.321 + * Note that the value for <code>UBIDI_DEFAULT_LTR</code> is even
1.322 + * and the one for <code>UBIDI_DEFAULT_RTL</code> is odd,
1.323 + * just like with normal LTR and RTL level values -
1.324 + * these special values are designed that way. Also, the implementation
1.325 + * assumes that UBIDI_MAX_EXPLICIT_LEVEL is odd.
1.326 + *
1.327 + * @see UBIDI_DEFAULT_LTR
1.328 + * @see UBIDI_DEFAULT_RTL
1.329 + * @see UBIDI_LEVEL_OVERRIDE
1.330 + * @see UBIDI_MAX_EXPLICIT_LEVEL
1.331 + * @stable ICU 2.0
1.332 + */
1.333 +typedef uint8_t UBiDiLevel;
1.334 +
1.335 +/** Paragraph level setting.<p>
1.336 + *
1.337 + * Constant indicating that the base direction depends on the first strong
1.338 + * directional character in the text according to the Unicode Bidirectional
1.339 + * Algorithm. If no strong directional character is present,
1.340 + * then set the paragraph level to 0 (left-to-right).<p>
1.341 + *
1.342 + * If this value is used in conjunction with reordering modes
1.343 + * <code>UBIDI_REORDER_INVERSE_LIKE_DIRECT</code> or
1.344 + * <code>UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL</code>, the text to reorder
1.345 + * is assumed to be visual LTR, and the text after reordering is required
1.346 + * to be the corresponding logical string with appropriate contextual
1.347 + * direction. The direction of the result string will be RTL if either
1.348 + * the righmost or leftmost strong character of the source text is RTL
1.349 + * or Arabic Letter, the direction will be LTR otherwise.<p>
1.350 + *
1.351 + * If reordering option <code>UBIDI_OPTION_INSERT_MARKS</code> is set, an RLM may
1.352 + * be added at the beginning of the result string to ensure round trip
1.353 + * (that the result string, when reordered back to visual, will produce
1.354 + * the original source text).
1.355 + * @see UBIDI_REORDER_INVERSE_LIKE_DIRECT
1.356 + * @see UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL
1.357 + * @stable ICU 2.0
1.358 + */
1.359 +#define UBIDI_DEFAULT_LTR 0xfe
1.360 +
1.361 +/** Paragraph level setting.<p>
1.362 + *
1.363 + * Constant indicating that the base direction depends on the first strong
1.364 + * directional character in the text according to the Unicode Bidirectional
1.365 + * Algorithm. If no strong directional character is present,
1.366 + * then set the paragraph level to 1 (right-to-left).<p>
1.367 + *
1.368 + * If this value is used in conjunction with reordering modes
1.369 + * <code>UBIDI_REORDER_INVERSE_LIKE_DIRECT</code> or
1.370 + * <code>UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL</code>, the text to reorder
1.371 + * is assumed to be visual LTR, and the text after reordering is required
1.372 + * to be the corresponding logical string with appropriate contextual
1.373 + * direction. The direction of the result string will be RTL if either
1.374 + * the righmost or leftmost strong character of the source text is RTL
1.375 + * or Arabic Letter, or if the text contains no strong character;
1.376 + * the direction will be LTR otherwise.<p>
1.377 + *
1.378 + * If reordering option <code>UBIDI_OPTION_INSERT_MARKS</code> is set, an RLM may
1.379 + * be added at the beginning of the result string to ensure round trip
1.380 + * (that the result string, when reordered back to visual, will produce
1.381 + * the original source text).
1.382 + * @see UBIDI_REORDER_INVERSE_LIKE_DIRECT
1.383 + * @see UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL
1.384 + * @stable ICU 2.0
1.385 + */
1.386 +#define UBIDI_DEFAULT_RTL 0xff
1.387 +
1.388 +/**
1.389 + * Maximum explicit embedding level.
1.390 + * (The maximum resolved level can be up to <code>UBIDI_MAX_EXPLICIT_LEVEL+1</code>).
1.391 + * @stable ICU 2.0
1.392 + */
1.393 +#define UBIDI_MAX_EXPLICIT_LEVEL 125
1.394 +
1.395 +/** Bit flag for level input.
1.396 + * Overrides directional properties.
1.397 + * @stable ICU 2.0
1.398 + */
1.399 +#define UBIDI_LEVEL_OVERRIDE 0x80
1.400 +
1.401 +/**
1.402 + * Special value which can be returned by the mapping functions when a logical
1.403 + * index has no corresponding visual index or vice-versa. This may happen
1.404 + * for the logical-to-visual mapping of a Bidi control when option
1.405 + * <code>#UBIDI_OPTION_REMOVE_CONTROLS</code> is specified. This can also happen
1.406 + * for the visual-to-logical mapping of a Bidi mark (LRM or RLM) inserted
1.407 + * by option <code>#UBIDI_OPTION_INSERT_MARKS</code>.
1.408 + * @see ubidi_getVisualIndex
1.409 + * @see ubidi_getVisualMap
1.410 + * @see ubidi_getLogicalIndex
1.411 + * @see ubidi_getLogicalMap
1.412 + * @stable ICU 3.6
1.413 + */
1.414 +#define UBIDI_MAP_NOWHERE (-1)
1.415 +
1.416 +/**
1.417 + * <code>UBiDiDirection</code> values indicate the text direction.
1.418 + * @stable ICU 2.0
1.419 + */
1.420 +enum UBiDiDirection {
1.421 + /** Left-to-right text. This is a 0 value.
1.422 + * <ul>
1.423 + * <li>As return value for <code>ubidi_getDirection()</code>, it means
1.424 + * that the source string contains no right-to-left characters, or
1.425 + * that the source string is empty and the paragraph level is even.
1.426 + * <li> As return value for <code>ubidi_getBaseDirection()</code>, it
1.427 + * means that the first strong character of the source string has
1.428 + * a left-to-right direction.
1.429 + * </ul>
1.430 + * @stable ICU 2.0
1.431 + */
1.432 + UBIDI_LTR,
1.433 + /** Right-to-left text. This is a 1 value.
1.434 + * <ul>
1.435 + * <li>As return value for <code>ubidi_getDirection()</code>, it means
1.436 + * that the source string contains no left-to-right characters, or
1.437 + * that the source string is empty and the paragraph level is odd.
1.438 + * <li> As return value for <code>ubidi_getBaseDirection()</code>, it
1.439 + * means that the first strong character of the source string has
1.440 + * a right-to-left direction.
1.441 + * </ul>
1.442 + * @stable ICU 2.0
1.443 + */
1.444 + UBIDI_RTL,
1.445 + /** Mixed-directional text.
1.446 + * <p>As return value for <code>ubidi_getDirection()</code>, it means
1.447 + * that the source string contains both left-to-right and
1.448 + * right-to-left characters.
1.449 + * @stable ICU 2.0
1.450 + */
1.451 + UBIDI_MIXED,
1.452 + /** No strongly directional text.
1.453 + * <p>As return value for <code>ubidi_getBaseDirection()</code>, it means
1.454 + * that the source string is missing or empty, or contains neither left-to-right
1.455 + * nor right-to-left characters.
1.456 + * @stable ICU 4.6
1.457 + */
1.458 + UBIDI_NEUTRAL
1.459 +};
1.460 +
1.461 +/** @stable ICU 2.0 */
1.462 +typedef enum UBiDiDirection UBiDiDirection;
1.463 +
1.464 +/**
1.465 + * Forward declaration of the <code>UBiDi</code> structure for the declaration of
1.466 + * the API functions. Its fields are implementation-specific.<p>
1.467 + * This structure holds information about a paragraph (or multiple paragraphs)
1.468 + * of text with Bidi-algorithm-related details, or about one line of
1.469 + * such a paragraph.<p>
1.470 + * Reordering can be done on a line, or on one or more paragraphs which are
1.471 + * then interpreted each as one single line.
1.472 + * @stable ICU 2.0
1.473 + */
1.474 +struct UBiDi;
1.475 +
1.476 +/** @stable ICU 2.0 */
1.477 +typedef struct UBiDi UBiDi;
1.478 +
1.479 +/**
1.480 + * Allocate a <code>UBiDi</code> structure.
1.481 + * Such an object is initially empty. It is assigned
1.482 + * the Bidi properties of a piece of text containing one or more paragraphs
1.483 + * by <code>ubidi_setPara()</code>
1.484 + * or the Bidi properties of a line within a paragraph by
1.485 + * <code>ubidi_setLine()</code>.<p>
1.486 + * This object can be reused for as long as it is not deallocated
1.487 + * by calling <code>ubidi_close()</code>.<p>
1.488 + * <code>ubidi_setPara()</code> and <code>ubidi_setLine()</code> will allocate
1.489 + * additional memory for internal structures as necessary.
1.490 + *
1.491 + * @return An empty <code>UBiDi</code> object.
1.492 + * @stable ICU 2.0
1.493 + */
1.494 +U_STABLE UBiDi * U_EXPORT2
1.495 +ubidi_open(void);
1.496 +
1.497 +/**
1.498 + * Allocate a <code>UBiDi</code> structure with preallocated memory
1.499 + * for internal structures.
1.500 + * This function provides a <code>UBiDi</code> object like <code>ubidi_open()</code>
1.501 + * with no arguments, but it also preallocates memory for internal structures
1.502 + * according to the sizings supplied by the caller.<p>
1.503 + * Subsequent functions will not allocate any more memory, and are thus
1.504 + * guaranteed not to fail because of lack of memory.<p>
1.505 + * The preallocation can be limited to some of the internal memory
1.506 + * by setting some values to 0 here. That means that if, e.g.,
1.507 + * <code>maxRunCount</code> cannot be reasonably predetermined and should not
1.508 + * be set to <code>maxLength</code> (the only failproof value) to avoid
1.509 + * wasting memory, then <code>maxRunCount</code> could be set to 0 here
1.510 + * and the internal structures that are associated with it will be allocated
1.511 + * on demand, just like with <code>ubidi_open()</code>.
1.512 + *
1.513 + * @param maxLength is the maximum text or line length that internal memory
1.514 + * will be preallocated for. An attempt to associate this object with a
1.515 + * longer text will fail, unless this value is 0, which leaves the allocation
1.516 + * up to the implementation.
1.517 + *
1.518 + * @param maxRunCount is the maximum anticipated number of same-level runs
1.519 + * that internal memory will be preallocated for. An attempt to access
1.520 + * visual runs on an object that was not preallocated for as many runs
1.521 + * as the text was actually resolved to will fail,
1.522 + * unless this value is 0, which leaves the allocation up to the implementation.<br><br>
1.523 + * The number of runs depends on the actual text and maybe anywhere between
1.524 + * 1 and <code>maxLength</code>. It is typically small.
1.525 + *
1.526 + * @param pErrorCode must be a valid pointer to an error code value.
1.527 + *
1.528 + * @return An empty <code>UBiDi</code> object with preallocated memory.
1.529 + * @stable ICU 2.0
1.530 + */
1.531 +U_STABLE UBiDi * U_EXPORT2
1.532 +ubidi_openSized(int32_t maxLength, int32_t maxRunCount, UErrorCode *pErrorCode);
1.533 +
1.534 +/**
1.535 + * <code>ubidi_close()</code> must be called to free the memory
1.536 + * associated with a UBiDi object.<p>
1.537 + *
1.538 + * <strong>Important: </strong>
1.539 + * A parent <code>UBiDi</code> object must not be destroyed or reused if
1.540 + * it still has children.
1.541 + * If a <code>UBiDi</code> object has become the <i>child</i>
1.542 + * of another one (its <i>parent</i>) by calling
1.543 + * <code>ubidi_setLine()</code>, then the child object must
1.544 + * be destroyed (closed) or reused (by calling
1.545 + * <code>ubidi_setPara()</code> or <code>ubidi_setLine()</code>)
1.546 + * before the parent object.
1.547 + *
1.548 + * @param pBiDi is a <code>UBiDi</code> object.
1.549 + *
1.550 + * @see ubidi_setPara
1.551 + * @see ubidi_setLine
1.552 + * @stable ICU 2.0
1.553 + */
1.554 +U_STABLE void U_EXPORT2
1.555 +ubidi_close(UBiDi *pBiDi);
1.556 +
1.557 +#if U_SHOW_CPLUSPLUS_API
1.558 +
1.559 +U_NAMESPACE_BEGIN
1.560 +
1.561 +/**
1.562 + * \class LocalUBiDiPointer
1.563 + * "Smart pointer" class, closes a UBiDi via ubidi_close().
1.564 + * For most methods see the LocalPointerBase base class.
1.565 + *
1.566 + * @see LocalPointerBase
1.567 + * @see LocalPointer
1.568 + * @stable ICU 4.4
1.569 + */
1.570 +U_DEFINE_LOCAL_OPEN_POINTER(LocalUBiDiPointer, UBiDi, ubidi_close);
1.571 +
1.572 +U_NAMESPACE_END
1.573 +
1.574 +#endif
1.575 +
1.576 +/**
1.577 + * Modify the operation of the Bidi algorithm such that it
1.578 + * approximates an "inverse Bidi" algorithm. This function
1.579 + * must be called before <code>ubidi_setPara()</code>.
1.580 + *
1.581 + * <p>The normal operation of the Bidi algorithm as described
1.582 + * in the Unicode Technical Report is to take text stored in logical
1.583 + * (keyboard, typing) order and to determine the reordering of it for visual
1.584 + * rendering.
1.585 + * Some legacy systems store text in visual order, and for operations
1.586 + * with standard, Unicode-based algorithms, the text needs to be transformed
1.587 + * to logical order. This is effectively the inverse algorithm of the
1.588 + * described Bidi algorithm. Note that there is no standard algorithm for
1.589 + * this "inverse Bidi" and that the current implementation provides only an
1.590 + * approximation of "inverse Bidi".</p>
1.591 + *
1.592 + * <p>With <code>isInverse</code> set to <code>TRUE</code>,
1.593 + * this function changes the behavior of some of the subsequent functions
1.594 + * in a way that they can be used for the inverse Bidi algorithm.
1.595 + * Specifically, runs of text with numeric characters will be treated in a
1.596 + * special way and may need to be surrounded with LRM characters when they are
1.597 + * written in reordered sequence.</p>
1.598 + *
1.599 + * <p>Output runs should be retrieved using <code>ubidi_getVisualRun()</code>.
1.600 + * Since the actual input for "inverse Bidi" is visually ordered text and
1.601 + * <code>ubidi_getVisualRun()</code> gets the reordered runs, these are actually
1.602 + * the runs of the logically ordered output.</p>
1.603 + *
1.604 + * <p>Calling this function with argument <code>isInverse</code> set to
1.605 + * <code>TRUE</code> is equivalent to calling
1.606 + * <code>ubidi_setReorderingMode</code> with argument
1.607 + * <code>reorderingMode</code>
1.608 + * set to <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>.<br>
1.609 + * Calling this function with argument <code>isInverse</code> set to
1.610 + * <code>FALSE</code> is equivalent to calling
1.611 + * <code>ubidi_setReorderingMode</code> with argument
1.612 + * <code>reorderingMode</code>
1.613 + * set to <code>#UBIDI_REORDER_DEFAULT</code>.
1.614 + *
1.615 + * @param pBiDi is a <code>UBiDi</code> object.
1.616 + *
1.617 + * @param isInverse specifies "forward" or "inverse" Bidi operation.
1.618 + *
1.619 + * @see ubidi_setPara
1.620 + * @see ubidi_writeReordered
1.621 + * @see ubidi_setReorderingMode
1.622 + * @stable ICU 2.0
1.623 + */
1.624 +U_STABLE void U_EXPORT2
1.625 +ubidi_setInverse(UBiDi *pBiDi, UBool isInverse);
1.626 +
1.627 +/**
1.628 + * Is this Bidi object set to perform the inverse Bidi algorithm?
1.629 + * <p>Note: calling this function after setting the reordering mode with
1.630 + * <code>ubidi_setReorderingMode</code> will return <code>TRUE</code> if the
1.631 + * reordering mode was set to <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>,
1.632 + * <code>FALSE</code> for all other values.</p>
1.633 + *
1.634 + * @param pBiDi is a <code>UBiDi</code> object.
1.635 + * @return TRUE if the Bidi object is set to perform the inverse Bidi algorithm
1.636 + * by handling numbers as L.
1.637 + *
1.638 + * @see ubidi_setInverse
1.639 + * @see ubidi_setReorderingMode
1.640 + * @stable ICU 2.0
1.641 + */
1.642 +
1.643 +U_STABLE UBool U_EXPORT2
1.644 +ubidi_isInverse(UBiDi *pBiDi);
1.645 +
1.646 +/**
1.647 + * Specify whether block separators must be allocated level zero,
1.648 + * so that successive paragraphs will progress from left to right.
1.649 + * This function must be called before <code>ubidi_setPara()</code>.
1.650 + * Paragraph separators (B) may appear in the text. Setting them to level zero
1.651 + * means that all paragraph separators (including one possibly appearing
1.652 + * in the last text position) are kept in the reordered text after the text
1.653 + * that they follow in the source text.
1.654 + * When this feature is not enabled, a paragraph separator at the last
1.655 + * position of the text before reordering will go to the first position
1.656 + * of the reordered text when the paragraph level is odd.
1.657 + *
1.658 + * @param pBiDi is a <code>UBiDi</code> object.
1.659 + *
1.660 + * @param orderParagraphsLTR specifies whether paragraph separators (B) must
1.661 + * receive level 0, so that successive paragraphs progress from left to right.
1.662 + *
1.663 + * @see ubidi_setPara
1.664 + * @stable ICU 3.4
1.665 + */
1.666 +U_STABLE void U_EXPORT2
1.667 +ubidi_orderParagraphsLTR(UBiDi *pBiDi, UBool orderParagraphsLTR);
1.668 +
1.669 +/**
1.670 + * Is this Bidi object set to allocate level 0 to block separators so that
1.671 + * successive paragraphs progress from left to right?
1.672 + *
1.673 + * @param pBiDi is a <code>UBiDi</code> object.
1.674 + * @return TRUE if the Bidi object is set to allocate level 0 to block
1.675 + * separators.
1.676 + *
1.677 + * @see ubidi_orderParagraphsLTR
1.678 + * @stable ICU 3.4
1.679 + */
1.680 +U_STABLE UBool U_EXPORT2
1.681 +ubidi_isOrderParagraphsLTR(UBiDi *pBiDi);
1.682 +
1.683 +/**
1.684 + * <code>UBiDiReorderingMode</code> values indicate which variant of the Bidi
1.685 + * algorithm to use.
1.686 + *
1.687 + * @see ubidi_setReorderingMode
1.688 + * @stable ICU 3.6
1.689 + */
1.690 +typedef enum UBiDiReorderingMode {
1.691 + /** Regular Logical to Visual Bidi algorithm according to Unicode.
1.692 + * This is a 0 value.
1.693 + * @stable ICU 3.6 */
1.694 + UBIDI_REORDER_DEFAULT = 0,
1.695 + /** Logical to Visual algorithm which handles numbers in a way which
1.696 + * mimicks the behavior of Windows XP.
1.697 + * @stable ICU 3.6 */
1.698 + UBIDI_REORDER_NUMBERS_SPECIAL,
1.699 + /** Logical to Visual algorithm grouping numbers with adjacent R characters
1.700 + * (reversible algorithm).
1.701 + * @stable ICU 3.6 */
1.702 + UBIDI_REORDER_GROUP_NUMBERS_WITH_R,
1.703 + /** Reorder runs only to transform a Logical LTR string to the Logical RTL
1.704 + * string with the same display, or vice-versa.<br>
1.705 + * If this mode is set together with option
1.706 + * <code>#UBIDI_OPTION_INSERT_MARKS</code>, some Bidi controls in the source
1.707 + * text may be removed and other controls may be added to produce the
1.708 + * minimum combination which has the required display.
1.709 + * @stable ICU 3.6 */
1.710 + UBIDI_REORDER_RUNS_ONLY,
1.711 + /** Visual to Logical algorithm which handles numbers like L
1.712 + * (same algorithm as selected by <code>ubidi_setInverse(TRUE)</code>.
1.713 + * @see ubidi_setInverse
1.714 + * @stable ICU 3.6 */
1.715 + UBIDI_REORDER_INVERSE_NUMBERS_AS_L,
1.716 + /** Visual to Logical algorithm equivalent to the regular Logical to Visual
1.717 + * algorithm.
1.718 + * @stable ICU 3.6 */
1.719 + UBIDI_REORDER_INVERSE_LIKE_DIRECT,
1.720 + /** Inverse Bidi (Visual to Logical) algorithm for the
1.721 + * <code>UBIDI_REORDER_NUMBERS_SPECIAL</code> Bidi algorithm.
1.722 + * @stable ICU 3.6 */
1.723 + UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL,
1.724 + /** Number of values for reordering mode.
1.725 + * @stable ICU 3.6 */
1.726 + UBIDI_REORDER_COUNT
1.727 +} UBiDiReorderingMode;
1.728 +
1.729 +/**
1.730 + * Modify the operation of the Bidi algorithm such that it implements some
1.731 + * variant to the basic Bidi algorithm or approximates an "inverse Bidi"
1.732 + * algorithm, depending on different values of the "reordering mode".
1.733 + * This function must be called before <code>ubidi_setPara()</code>, and stays
1.734 + * in effect until called again with a different argument.
1.735 + *
1.736 + * <p>The normal operation of the Bidi algorithm as described
1.737 + * in the Unicode Standard Annex #9 is to take text stored in logical
1.738 + * (keyboard, typing) order and to determine how to reorder it for visual
1.739 + * rendering.</p>
1.740 + *
1.741 + * <p>With the reordering mode set to a value other than
1.742 + * <code>#UBIDI_REORDER_DEFAULT</code>, this function changes the behavior of
1.743 + * some of the subsequent functions in a way such that they implement an
1.744 + * inverse Bidi algorithm or some other algorithm variants.</p>
1.745 + *
1.746 + * <p>Some legacy systems store text in visual order, and for operations
1.747 + * with standard, Unicode-based algorithms, the text needs to be transformed
1.748 + * into logical order. This is effectively the inverse algorithm of the
1.749 + * described Bidi algorithm. Note that there is no standard algorithm for
1.750 + * this "inverse Bidi", so a number of variants are implemented here.</p>
1.751 + *
1.752 + * <p>In other cases, it may be desirable to emulate some variant of the
1.753 + * Logical to Visual algorithm (e.g. one used in MS Windows), or perform a
1.754 + * Logical to Logical transformation.</p>
1.755 + *
1.756 + * <ul>
1.757 + * <li>When the reordering mode is set to <code>#UBIDI_REORDER_DEFAULT</code>,
1.758 + * the standard Bidi Logical to Visual algorithm is applied.</li>
1.759 + *
1.760 + * <li>When the reordering mode is set to
1.761 + * <code>#UBIDI_REORDER_NUMBERS_SPECIAL</code>,
1.762 + * the algorithm used to perform Bidi transformations when calling
1.763 + * <code>ubidi_setPara</code> should approximate the algorithm used in
1.764 + * Microsoft Windows XP rather than strictly conform to the Unicode Bidi
1.765 + * algorithm.
1.766 + * <br>
1.767 + * The differences between the basic algorithm and the algorithm addressed
1.768 + * by this option are as follows:
1.769 + * <ul>
1.770 + * <li>Within text at an even embedding level, the sequence "123AB"
1.771 + * (where AB represent R or AL letters) is transformed to "123BA" by the
1.772 + * Unicode algorithm and to "BA123" by the Windows algorithm.</li>
1.773 + * <li>Arabic-Indic numbers (AN) are handled by the Windows algorithm just
1.774 + * like regular numbers (EN).</li>
1.775 + * </ul></li>
1.776 + *
1.777 + * <li>When the reordering mode is set to
1.778 + * <code>#UBIDI_REORDER_GROUP_NUMBERS_WITH_R</code>,
1.779 + * numbers located between LTR text and RTL text are associated with the RTL
1.780 + * text. For instance, an LTR paragraph with content "abc 123 DEF" (where
1.781 + * upper case letters represent RTL characters) will be transformed to
1.782 + * "abc FED 123" (and not "abc 123 FED"), "DEF 123 abc" will be transformed
1.783 + * to "123 FED abc" and "123 FED abc" will be transformed to "DEF 123 abc".
1.784 + * This makes the algorithm reversible and makes it useful when round trip
1.785 + * (from visual to logical and back to visual) must be achieved without
1.786 + * adding LRM characters. However, this is a variation from the standard
1.787 + * Unicode Bidi algorithm.<br>
1.788 + * The source text should not contain Bidi control characters other than LRM
1.789 + * or RLM.</li>
1.790 + *
1.791 + * <li>When the reordering mode is set to
1.792 + * <code>#UBIDI_REORDER_RUNS_ONLY</code>,
1.793 + * a "Logical to Logical" transformation must be performed:
1.794 + * <ul>
1.795 + * <li>If the default text level of the source text (argument <code>paraLevel</code>
1.796 + * in <code>ubidi_setPara</code>) is even, the source text will be handled as
1.797 + * LTR logical text and will be transformed to the RTL logical text which has
1.798 + * the same LTR visual display.</li>
1.799 + * <li>If the default level of the source text is odd, the source text
1.800 + * will be handled as RTL logical text and will be transformed to the
1.801 + * LTR logical text which has the same LTR visual display.</li>
1.802 + * </ul>
1.803 + * This mode may be needed when logical text which is basically Arabic or
1.804 + * Hebrew, with possible included numbers or phrases in English, has to be
1.805 + * displayed as if it had an even embedding level (this can happen if the
1.806 + * displaying application treats all text as if it was basically LTR).
1.807 + * <br>
1.808 + * This mode may also be needed in the reverse case, when logical text which is
1.809 + * basically English, with possible included phrases in Arabic or Hebrew, has to
1.810 + * be displayed as if it had an odd embedding level.
1.811 + * <br>
1.812 + * Both cases could be handled by adding LRE or RLE at the head of the text,
1.813 + * if the display subsystem supports these formatting controls. If it does not,
1.814 + * the problem may be handled by transforming the source text in this mode
1.815 + * before displaying it, so that it will be displayed properly.<br>
1.816 + * The source text should not contain Bidi control characters other than LRM
1.817 + * or RLM.</li>
1.818 + *
1.819 + * <li>When the reordering mode is set to
1.820 + * <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>, an "inverse Bidi" algorithm
1.821 + * is applied.
1.822 + * Runs of text with numeric characters will be treated like LTR letters and
1.823 + * may need to be surrounded with LRM characters when they are written in
1.824 + * reordered sequence (the option <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code> can
1.825 + * be used with function <code>ubidi_writeReordered</code> to this end. This
1.826 + * mode is equivalent to calling <code>ubidi_setInverse()</code> with
1.827 + * argument <code>isInverse</code> set to <code>TRUE</code>.</li>
1.828 + *
1.829 + * <li>When the reordering mode is set to
1.830 + * <code>#UBIDI_REORDER_INVERSE_LIKE_DIRECT</code>, the "direct" Logical to Visual
1.831 + * Bidi algorithm is used as an approximation of an "inverse Bidi" algorithm.
1.832 + * This mode is similar to mode <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>
1.833 + * but is closer to the regular Bidi algorithm.
1.834 + * <br>
1.835 + * For example, an LTR paragraph with the content "FED 123 456 CBA" (where
1.836 + * upper case represents RTL characters) will be transformed to
1.837 + * "ABC 456 123 DEF", as opposed to "DEF 123 456 ABC"
1.838 + * with mode <code>UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>.<br>
1.839 + * When used in conjunction with option
1.840 + * <code>#UBIDI_OPTION_INSERT_MARKS</code>, this mode generally
1.841 + * adds Bidi marks to the output significantly more sparingly than mode
1.842 + * <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code> with option
1.843 + * <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code> in calls to
1.844 + * <code>ubidi_writeReordered</code>.</li>
1.845 + *
1.846 + * <li>When the reordering mode is set to
1.847 + * <code>#UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL</code>, the Logical to Visual
1.848 + * Bidi algorithm used in Windows XP is used as an approximation of an "inverse Bidi" algorithm.
1.849 + * <br>
1.850 + * For example, an LTR paragraph with the content "abc FED123" (where
1.851 + * upper case represents RTL characters) will be transformed to "abc 123DEF."</li>
1.852 + * </ul>
1.853 + *
1.854 + * <p>In all the reordering modes specifying an "inverse Bidi" algorithm
1.855 + * (i.e. those with a name starting with <code>UBIDI_REORDER_INVERSE</code>),
1.856 + * output runs should be retrieved using
1.857 + * <code>ubidi_getVisualRun()</code>, and the output text with
1.858 + * <code>ubidi_writeReordered()</code>. The caller should keep in mind that in
1.859 + * "inverse Bidi" modes the input is actually visually ordered text and
1.860 + * reordered output returned by <code>ubidi_getVisualRun()</code> or
1.861 + * <code>ubidi_writeReordered()</code> are actually runs or character string
1.862 + * of logically ordered output.<br>
1.863 + * For all the "inverse Bidi" modes, the source text should not contain
1.864 + * Bidi control characters other than LRM or RLM.</p>
1.865 + *
1.866 + * <p>Note that option <code>#UBIDI_OUTPUT_REVERSE</code> of
1.867 + * <code>ubidi_writeReordered</code> has no useful meaning and should not be
1.868 + * used in conjunction with any value of the reordering mode specifying
1.869 + * "inverse Bidi" or with value <code>UBIDI_REORDER_RUNS_ONLY</code>.
1.870 + *
1.871 + * @param pBiDi is a <code>UBiDi</code> object.
1.872 + * @param reorderingMode specifies the required variant of the Bidi algorithm.
1.873 + *
1.874 + * @see UBiDiReorderingMode
1.875 + * @see ubidi_setInverse
1.876 + * @see ubidi_setPara
1.877 + * @see ubidi_writeReordered
1.878 + * @stable ICU 3.6
1.879 + */
1.880 +U_STABLE void U_EXPORT2
1.881 +ubidi_setReorderingMode(UBiDi *pBiDi, UBiDiReorderingMode reorderingMode);
1.882 +
1.883 +/**
1.884 + * What is the requested reordering mode for a given Bidi object?
1.885 + *
1.886 + * @param pBiDi is a <code>UBiDi</code> object.
1.887 + * @return the current reordering mode of the Bidi object
1.888 + * @see ubidi_setReorderingMode
1.889 + * @stable ICU 3.6
1.890 + */
1.891 +U_STABLE UBiDiReorderingMode U_EXPORT2
1.892 +ubidi_getReorderingMode(UBiDi *pBiDi);
1.893 +
1.894 +/**
1.895 + * <code>UBiDiReorderingOption</code> values indicate which options are
1.896 + * specified to affect the Bidi algorithm.
1.897 + *
1.898 + * @see ubidi_setReorderingOptions
1.899 + * @stable ICU 3.6
1.900 + */
1.901 +typedef enum UBiDiReorderingOption {
1.902 + /**
1.903 + * option value for <code>ubidi_setReorderingOptions</code>:
1.904 + * disable all the options which can be set with this function
1.905 + * @see ubidi_setReorderingOptions
1.906 + * @stable ICU 3.6
1.907 + */
1.908 + UBIDI_OPTION_DEFAULT = 0,
1.909 +
1.910 + /**
1.911 + * option bit for <code>ubidi_setReorderingOptions</code>:
1.912 + * insert Bidi marks (LRM or RLM) when needed to ensure correct result of
1.913 + * a reordering to a Logical order
1.914 + *
1.915 + * <p>This option must be set or reset before calling
1.916 + * <code>ubidi_setPara</code>.</p>
1.917 + *
1.918 + * <p>This option is significant only with reordering modes which generate
1.919 + * a result with Logical order, specifically:</p>
1.920 + * <ul>
1.921 + * <li><code>#UBIDI_REORDER_RUNS_ONLY</code></li>
1.922 + * <li><code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code></li>
1.923 + * <li><code>#UBIDI_REORDER_INVERSE_LIKE_DIRECT</code></li>
1.924 + * <li><code>#UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL</code></li>
1.925 + * </ul>
1.926 + *
1.927 + * <p>If this option is set in conjunction with reordering mode
1.928 + * <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code> or with calling
1.929 + * <code>ubidi_setInverse(TRUE)</code>, it implies
1.930 + * option <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code>
1.931 + * in calls to function <code>ubidi_writeReordered()</code>.</p>
1.932 + *
1.933 + * <p>For other reordering modes, a minimum number of LRM or RLM characters
1.934 + * will be added to the source text after reordering it so as to ensure
1.935 + * round trip, i.e. when applying the inverse reordering mode on the
1.936 + * resulting logical text with removal of Bidi marks
1.937 + * (option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code> set before calling
1.938 + * <code>ubidi_setPara()</code> or option <code>#UBIDI_REMOVE_BIDI_CONTROLS</code>
1.939 + * in <code>ubidi_writeReordered</code>), the result will be identical to the
1.940 + * source text in the first transformation.
1.941 + *
1.942 + * <p>This option will be ignored if specified together with option
1.943 + * <code>#UBIDI_OPTION_REMOVE_CONTROLS</code>. It inhibits option
1.944 + * <code>UBIDI_REMOVE_BIDI_CONTROLS</code> in calls to function
1.945 + * <code>ubidi_writeReordered()</code> and it implies option
1.946 + * <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code> in calls to function
1.947 + * <code>ubidi_writeReordered()</code> if the reordering mode is
1.948 + * <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code>.</p>
1.949 + *
1.950 + * @see ubidi_setReorderingMode
1.951 + * @see ubidi_setReorderingOptions
1.952 + * @stable ICU 3.6
1.953 + */
1.954 + UBIDI_OPTION_INSERT_MARKS = 1,
1.955 +
1.956 + /**
1.957 + * option bit for <code>ubidi_setReorderingOptions</code>:
1.958 + * remove Bidi control characters
1.959 + *
1.960 + * <p>This option must be set or reset before calling
1.961 + * <code>ubidi_setPara</code>.</p>
1.962 + *
1.963 + * <p>This option nullifies option <code>#UBIDI_OPTION_INSERT_MARKS</code>.
1.964 + * It inhibits option <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code> in calls
1.965 + * to function <code>ubidi_writeReordered()</code> and it implies option
1.966 + * <code>#UBIDI_REMOVE_BIDI_CONTROLS</code> in calls to that function.</p>
1.967 + *
1.968 + * @see ubidi_setReorderingMode
1.969 + * @see ubidi_setReorderingOptions
1.970 + * @stable ICU 3.6
1.971 + */
1.972 + UBIDI_OPTION_REMOVE_CONTROLS = 2,
1.973 +
1.974 + /**
1.975 + * option bit for <code>ubidi_setReorderingOptions</code>:
1.976 + * process the output as part of a stream to be continued
1.977 + *
1.978 + * <p>This option must be set or reset before calling
1.979 + * <code>ubidi_setPara</code>.</p>
1.980 + *
1.981 + * <p>This option specifies that the caller is interested in processing large
1.982 + * text object in parts.
1.983 + * The results of the successive calls are expected to be concatenated by the
1.984 + * caller. Only the call for the last part will have this option bit off.</p>
1.985 + *
1.986 + * <p>When this option bit is on, <code>ubidi_setPara()</code> may process
1.987 + * less than the full source text in order to truncate the text at a meaningful
1.988 + * boundary. The caller should call <code>ubidi_getProcessedLength()</code>
1.989 + * immediately after calling <code>ubidi_setPara()</code> in order to
1.990 + * determine how much of the source text has been processed.
1.991 + * Source text beyond that length should be resubmitted in following calls to
1.992 + * <code>ubidi_setPara</code>. The processed length may be less than
1.993 + * the length of the source text if a character preceding the last character of
1.994 + * the source text constitutes a reasonable boundary (like a block separator)
1.995 + * for text to be continued.<br>
1.996 + * If the last character of the source text constitutes a reasonable
1.997 + * boundary, the whole text will be processed at once.<br>
1.998 + * If nowhere in the source text there exists
1.999 + * such a reasonable boundary, the processed length will be zero.<br>
1.1000 + * The caller should check for such an occurrence and do one of the following:
1.1001 + * <ul><li>submit a larger amount of text with a better chance to include
1.1002 + * a reasonable boundary.</li>
1.1003 + * <li>resubmit the same text after turning off option
1.1004 + * <code>UBIDI_OPTION_STREAMING</code>.</li></ul>
1.1005 + * In all cases, this option should be turned off before processing the last
1.1006 + * part of the text.</p>
1.1007 + *
1.1008 + * <p>When the <code>UBIDI_OPTION_STREAMING</code> option is used,
1.1009 + * it is recommended to call <code>ubidi_orderParagraphsLTR()</code> with
1.1010 + * argument <code>orderParagraphsLTR</code> set to <code>TRUE</code> before
1.1011 + * calling <code>ubidi_setPara</code> so that later paragraphs may be
1.1012 + * concatenated to previous paragraphs on the right.</p>
1.1013 + *
1.1014 + * @see ubidi_setReorderingMode
1.1015 + * @see ubidi_setReorderingOptions
1.1016 + * @see ubidi_getProcessedLength
1.1017 + * @see ubidi_orderParagraphsLTR
1.1018 + * @stable ICU 3.6
1.1019 + */
1.1020 + UBIDI_OPTION_STREAMING = 4
1.1021 +} UBiDiReorderingOption;
1.1022 +
1.1023 +/**
1.1024 + * Specify which of the reordering options
1.1025 + * should be applied during Bidi transformations.
1.1026 + *
1.1027 + * @param pBiDi is a <code>UBiDi</code> object.
1.1028 + * @param reorderingOptions is a combination of zero or more of the following
1.1029 + * options:
1.1030 + * <code>#UBIDI_OPTION_DEFAULT</code>, <code>#UBIDI_OPTION_INSERT_MARKS</code>,
1.1031 + * <code>#UBIDI_OPTION_REMOVE_CONTROLS</code>, <code>#UBIDI_OPTION_STREAMING</code>.
1.1032 + *
1.1033 + * @see ubidi_getReorderingOptions
1.1034 + * @stable ICU 3.6
1.1035 + */
1.1036 +U_STABLE void U_EXPORT2
1.1037 +ubidi_setReorderingOptions(UBiDi *pBiDi, uint32_t reorderingOptions);
1.1038 +
1.1039 +/**
1.1040 + * What are the reordering options applied to a given Bidi object?
1.1041 + *
1.1042 + * @param pBiDi is a <code>UBiDi</code> object.
1.1043 + * @return the current reordering options of the Bidi object
1.1044 + * @see ubidi_setReorderingOptions
1.1045 + * @stable ICU 3.6
1.1046 + */
1.1047 +U_STABLE uint32_t U_EXPORT2
1.1048 +ubidi_getReorderingOptions(UBiDi *pBiDi);
1.1049 +
1.1050 +/**
1.1051 + * Set the context before a call to ubidi_setPara().<p>
1.1052 + *
1.1053 + * ubidi_setPara() computes the left-right directionality for a given piece
1.1054 + * of text which is supplied as one of its arguments. Sometimes this piece
1.1055 + * of text (the "main text") should be considered in context, because text
1.1056 + * appearing before ("prologue") and/or after ("epilogue") the main text
1.1057 + * may affect the result of this computation.<p>
1.1058 + *
1.1059 + * This function specifies the prologue and/or the epilogue for the next
1.1060 + * call to ubidi_setPara(). The characters specified as prologue and
1.1061 + * epilogue should not be modified by the calling program until the call
1.1062 + * to ubidi_setPara() has returned. If successive calls to ubidi_setPara()
1.1063 + * all need specification of a context, ubidi_setContext() must be called
1.1064 + * before each call to ubidi_setPara(). In other words, a context is not
1.1065 + * "remembered" after the following successful call to ubidi_setPara().<p>
1.1066 + *
1.1067 + * If a call to ubidi_setPara() specifies UBIDI_DEFAULT_LTR or
1.1068 + * UBIDI_DEFAULT_RTL as paraLevel and is preceded by a call to
1.1069 + * ubidi_setContext() which specifies a prologue, the paragraph level will
1.1070 + * be computed taking in consideration the text in the prologue.<p>
1.1071 + *
1.1072 + * When ubidi_setPara() is called without a previous call to
1.1073 + * ubidi_setContext, the main text is handled as if preceded and followed
1.1074 + * by strong directional characters at the current paragraph level.
1.1075 + * Calling ubidi_setContext() with specification of a prologue will change
1.1076 + * this behavior by handling the main text as if preceded by the last
1.1077 + * strong character appearing in the prologue, if any.
1.1078 + * Calling ubidi_setContext() with specification of an epilogue will change
1.1079 + * the behavior of ubidi_setPara() by handling the main text as if followed
1.1080 + * by the first strong character or digit appearing in the epilogue, if any.<p>
1.1081 + *
1.1082 + * Note 1: if <code>ubidi_setContext</code> is called repeatedly without
1.1083 + * calling <code>ubidi_setPara</code>, the earlier calls have no effect,
1.1084 + * only the last call will be remembered for the next call to
1.1085 + * <code>ubidi_setPara</code>.<p>
1.1086 + *
1.1087 + * Note 2: calling <code>ubidi_setContext(pBiDi, NULL, 0, NULL, 0, &errorCode)</code>
1.1088 + * cancels any previous setting of non-empty prologue or epilogue.
1.1089 + * The next call to <code>ubidi_setPara()</code> will process no
1.1090 + * prologue or epilogue.<p>
1.1091 + *
1.1092 + * Note 3: users must be aware that even after setting the context
1.1093 + * before a call to ubidi_setPara() to perform e.g. a logical to visual
1.1094 + * transformation, the resulting string may not be identical to what it
1.1095 + * would have been if all the text, including prologue and epilogue, had
1.1096 + * been processed together.<br>
1.1097 + * Example (upper case letters represent RTL characters):<br>
1.1098 + * prologue = "<code>abc DE</code>"<br>
1.1099 + * epilogue = none<br>
1.1100 + * main text = "<code>FGH xyz</code>"<br>
1.1101 + * paraLevel = UBIDI_LTR<br>
1.1102 + * display without prologue = "<code>HGF xyz</code>"
1.1103 + * ("HGF" is adjacent to "xyz")<br>
1.1104 + * display with prologue = "<code>abc HGFED xyz</code>"
1.1105 + * ("HGF" is not adjacent to "xyz")<br>
1.1106 + *
1.1107 + * @param pBiDi is a paragraph <code>UBiDi</code> object.
1.1108 + *
1.1109 + * @param prologue is a pointer to the text which precedes the text that
1.1110 + * will be specified in a coming call to ubidi_setPara().
1.1111 + * If there is no prologue to consider, then <code>proLength</code>
1.1112 + * must be zero and this pointer can be NULL.
1.1113 + *
1.1114 + * @param proLength is the length of the prologue; if <code>proLength==-1</code>
1.1115 + * then the prologue must be zero-terminated.
1.1116 + * Otherwise proLength must be >= 0. If <code>proLength==0</code>, it means
1.1117 + * that there is no prologue to consider.
1.1118 + *
1.1119 + * @param epilogue is a pointer to the text which follows the text that
1.1120 + * will be specified in a coming call to ubidi_setPara().
1.1121 + * If there is no epilogue to consider, then <code>epiLength</code>
1.1122 + * must be zero and this pointer can be NULL.
1.1123 + *
1.1124 + * @param epiLength is the length of the epilogue; if <code>epiLength==-1</code>
1.1125 + * then the epilogue must be zero-terminated.
1.1126 + * Otherwise epiLength must be >= 0. If <code>epiLength==0</code>, it means
1.1127 + * that there is no epilogue to consider.
1.1128 + *
1.1129 + * @param pErrorCode must be a valid pointer to an error code value.
1.1130 + *
1.1131 + * @see ubidi_setPara
1.1132 + * @stable ICU 4.8
1.1133 + */
1.1134 +U_STABLE void U_EXPORT2
1.1135 +ubidi_setContext(UBiDi *pBiDi,
1.1136 + const UChar *prologue, int32_t proLength,
1.1137 + const UChar *epilogue, int32_t epiLength,
1.1138 + UErrorCode *pErrorCode);
1.1139 +
1.1140 +/**
1.1141 + * Perform the Unicode Bidi algorithm. It is defined in the
1.1142 + * <a href="http://www.unicode.org/unicode/reports/tr9/">Unicode Standard Anned #9</a>,
1.1143 + * version 13,
1.1144 + * also described in The Unicode Standard, Version 4.0 .<p>
1.1145 + *
1.1146 + * This function takes a piece of plain text containing one or more paragraphs,
1.1147 + * with or without externally specified embedding levels from <i>styled</i>
1.1148 + * text and computes the left-right-directionality of each character.<p>
1.1149 + *
1.1150 + * If the entire text is all of the same directionality, then
1.1151 + * the function may not perform all the steps described by the algorithm,
1.1152 + * i.e., some levels may not be the same as if all steps were performed.
1.1153 + * This is not relevant for unidirectional text.<br>
1.1154 + * For example, in pure LTR text with numbers the numbers would get
1.1155 + * a resolved level of 2 higher than the surrounding text according to
1.1156 + * the algorithm. This implementation may set all resolved levels to
1.1157 + * the same value in such a case.<p>
1.1158 + *
1.1159 + * The text can be composed of multiple paragraphs. Occurrence of a block
1.1160 + * separator in the text terminates a paragraph, and whatever comes next starts
1.1161 + * a new paragraph. The exception to this rule is when a Carriage Return (CR)
1.1162 + * is followed by a Line Feed (LF). Both CR and LF are block separators, but
1.1163 + * in that case, the pair of characters is considered as terminating the
1.1164 + * preceding paragraph, and a new paragraph will be started by a character
1.1165 + * coming after the LF.
1.1166 + *
1.1167 + * @param pBiDi A <code>UBiDi</code> object allocated with <code>ubidi_open()</code>
1.1168 + * which will be set to contain the reordering information,
1.1169 + * especially the resolved levels for all the characters in <code>text</code>.
1.1170 + *
1.1171 + * @param text is a pointer to the text that the Bidi algorithm will be performed on.
1.1172 + * This pointer is stored in the UBiDi object and can be retrieved
1.1173 + * with <code>ubidi_getText()</code>.<br>
1.1174 + * <strong>Note:</strong> the text must be (at least) <code>length</code> long.
1.1175 + *
1.1176 + * @param length is the length of the text; if <code>length==-1</code> then
1.1177 + * the text must be zero-terminated.
1.1178 + *
1.1179 + * @param paraLevel specifies the default level for the text;
1.1180 + * it is typically 0 (LTR) or 1 (RTL).
1.1181 + * If the function shall determine the paragraph level from the text,
1.1182 + * then <code>paraLevel</code> can be set to
1.1183 + * either <code>#UBIDI_DEFAULT_LTR</code>
1.1184 + * or <code>#UBIDI_DEFAULT_RTL</code>; if the text contains multiple
1.1185 + * paragraphs, the paragraph level shall be determined separately for
1.1186 + * each paragraph; if a paragraph does not include any strongly typed
1.1187 + * character, then the desired default is used (0 for LTR or 1 for RTL).
1.1188 + * Any other value between 0 and <code>#UBIDI_MAX_EXPLICIT_LEVEL</code>
1.1189 + * is also valid, with odd levels indicating RTL.
1.1190 + *
1.1191 + * @param embeddingLevels (in) may be used to preset the embedding and override levels,
1.1192 + * ignoring characters like LRE and PDF in the text.
1.1193 + * A level overrides the directional property of its corresponding
1.1194 + * (same index) character if the level has the
1.1195 + * <code>#UBIDI_LEVEL_OVERRIDE</code> bit set.<br><br>
1.1196 + * Except for that bit, it must be
1.1197 + * <code>paraLevel<=embeddingLevels[]<=UBIDI_MAX_EXPLICIT_LEVEL</code>,
1.1198 + * with one exception: a level of zero may be specified for a paragraph
1.1199 + * separator even if <code>paraLevel>0</code> when multiple paragraphs
1.1200 + * are submitted in the same call to <code>ubidi_setPara()</code>.<br><br>
1.1201 + * <strong>Caution: </strong>A copy of this pointer, not of the levels,
1.1202 + * will be stored in the <code>UBiDi</code> object;
1.1203 + * the <code>embeddingLevels</code> array must not be
1.1204 + * deallocated before the <code>UBiDi</code> structure is destroyed or reused,
1.1205 + * and the <code>embeddingLevels</code>
1.1206 + * should not be modified to avoid unexpected results on subsequent Bidi operations.
1.1207 + * However, the <code>ubidi_setPara()</code> and
1.1208 + * <code>ubidi_setLine()</code> functions may modify some or all of the levels.<br><br>
1.1209 + * After the <code>UBiDi</code> object is reused or destroyed, the caller
1.1210 + * must take care of the deallocation of the <code>embeddingLevels</code> array.<br><br>
1.1211 + * <strong>Note:</strong> the <code>embeddingLevels</code> array must be
1.1212 + * at least <code>length</code> long.
1.1213 + * This pointer can be <code>NULL</code> if this
1.1214 + * value is not necessary.
1.1215 + *
1.1216 + * @param pErrorCode must be a valid pointer to an error code value.
1.1217 + * @stable ICU 2.0
1.1218 + */
1.1219 +U_STABLE void U_EXPORT2
1.1220 +ubidi_setPara(UBiDi *pBiDi, const UChar *text, int32_t length,
1.1221 + UBiDiLevel paraLevel, UBiDiLevel *embeddingLevels,
1.1222 + UErrorCode *pErrorCode);
1.1223 +
1.1224 +/**
1.1225 + * <code>ubidi_setLine()</code> sets a <code>UBiDi</code> to
1.1226 + * contain the reordering information, especially the resolved levels,
1.1227 + * for all the characters in a line of text. This line of text is
1.1228 + * specified by referring to a <code>UBiDi</code> object representing
1.1229 + * this information for a piece of text containing one or more paragraphs,
1.1230 + * and by specifying a range of indexes in this text.<p>
1.1231 + * In the new line object, the indexes will range from 0 to <code>limit-start-1</code>.<p>
1.1232 + *
1.1233 + * This is used after calling <code>ubidi_setPara()</code>
1.1234 + * for a piece of text, and after line-breaking on that text.
1.1235 + * It is not necessary if each paragraph is treated as a single line.<p>
1.1236 + *
1.1237 + * After line-breaking, rules (L1) and (L2) for the treatment of
1.1238 + * trailing WS and for reordering are performed on
1.1239 + * a <code>UBiDi</code> object that represents a line.<p>
1.1240 + *
1.1241 + * <strong>Important: </strong><code>pLineBiDi</code> shares data with
1.1242 + * <code>pParaBiDi</code>.
1.1243 + * You must destroy or reuse <code>pLineBiDi</code> before <code>pParaBiDi</code>.
1.1244 + * In other words, you must destroy or reuse the <code>UBiDi</code> object for a line
1.1245 + * before the object for its parent paragraph.<p>
1.1246 + *
1.1247 + * The text pointer that was stored in <code>pParaBiDi</code> is also copied,
1.1248 + * and <code>start</code> is added to it so that it points to the beginning of the
1.1249 + * line for this object.
1.1250 + *
1.1251 + * @param pParaBiDi is the parent paragraph object. It must have been set
1.1252 + * by a successful call to ubidi_setPara.
1.1253 + *
1.1254 + * @param start is the line's first index into the text.
1.1255 + *
1.1256 + * @param limit is just behind the line's last index into the text
1.1257 + * (its last index +1).<br>
1.1258 + * It must be <code>0<=start<limit<=</code>containing paragraph limit.
1.1259 + * If the specified line crosses a paragraph boundary, the function
1.1260 + * will terminate with error code U_ILLEGAL_ARGUMENT_ERROR.
1.1261 + *
1.1262 + * @param pLineBiDi is the object that will now represent a line of the text.
1.1263 + *
1.1264 + * @param pErrorCode must be a valid pointer to an error code value.
1.1265 + *
1.1266 + * @see ubidi_setPara
1.1267 + * @see ubidi_getProcessedLength
1.1268 + * @stable ICU 2.0
1.1269 + */
1.1270 +U_STABLE void U_EXPORT2
1.1271 +ubidi_setLine(const UBiDi *pParaBiDi,
1.1272 + int32_t start, int32_t limit,
1.1273 + UBiDi *pLineBiDi,
1.1274 + UErrorCode *pErrorCode);
1.1275 +
1.1276 +/**
1.1277 + * Get the directionality of the text.
1.1278 + *
1.1279 + * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1.1280 + *
1.1281 + * @return a value of <code>UBIDI_LTR</code>, <code>UBIDI_RTL</code>
1.1282 + * or <code>UBIDI_MIXED</code>
1.1283 + * that indicates if the entire text
1.1284 + * represented by this object is unidirectional,
1.1285 + * and which direction, or if it is mixed-directional.
1.1286 + * Note - The value <code>UBIDI_NEUTRAL</code> is never returned from this method.
1.1287 + *
1.1288 + * @see UBiDiDirection
1.1289 + * @stable ICU 2.0
1.1290 + */
1.1291 +U_STABLE UBiDiDirection U_EXPORT2
1.1292 +ubidi_getDirection(const UBiDi *pBiDi);
1.1293 +
1.1294 +/**
1.1295 + * Gets the base direction of the text provided according
1.1296 + * to the Unicode Bidirectional Algorithm. The base direction
1.1297 + * is derived from the first character in the string with bidirectional
1.1298 + * character type L, R, or AL. If the first such character has type L,
1.1299 + * <code>UBIDI_LTR</code> is returned. If the first such character has
1.1300 + * type R or AL, <code>UBIDI_RTL</code> is returned. If the string does
1.1301 + * not contain any character of these types, then
1.1302 + * <code>UBIDI_NEUTRAL</code> is returned.
1.1303 + *
1.1304 + * This is a lightweight function for use when only the base direction
1.1305 + * is needed and no further bidi processing of the text is needed.
1.1306 + *
1.1307 + * @param text is a pointer to the text whose base
1.1308 + * direction is needed.
1.1309 + * Note: the text must be (at least) @c length long.
1.1310 + *
1.1311 + * @param length is the length of the text;
1.1312 + * if <code>length==-1</code> then the text
1.1313 + * must be zero-terminated.
1.1314 + *
1.1315 + * @return <code>UBIDI_LTR</code>, <code>UBIDI_RTL</code>,
1.1316 + * <code>UBIDI_NEUTRAL</code>
1.1317 + *
1.1318 + * @see UBiDiDirection
1.1319 + * @stable ICU 4.6
1.1320 + */
1.1321 +U_STABLE UBiDiDirection U_EXPORT2
1.1322 +ubidi_getBaseDirection(const UChar *text, int32_t length );
1.1323 +
1.1324 +/**
1.1325 + * Get the pointer to the text.
1.1326 + *
1.1327 + * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1.1328 + *
1.1329 + * @return The pointer to the text that the UBiDi object was created for.
1.1330 + *
1.1331 + * @see ubidi_setPara
1.1332 + * @see ubidi_setLine
1.1333 + * @stable ICU 2.0
1.1334 + */
1.1335 +U_STABLE const UChar * U_EXPORT2
1.1336 +ubidi_getText(const UBiDi *pBiDi);
1.1337 +
1.1338 +/**
1.1339 + * Get the length of the text.
1.1340 + *
1.1341 + * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1.1342 + *
1.1343 + * @return The length of the text that the UBiDi object was created for.
1.1344 + * @stable ICU 2.0
1.1345 + */
1.1346 +U_STABLE int32_t U_EXPORT2
1.1347 +ubidi_getLength(const UBiDi *pBiDi);
1.1348 +
1.1349 +/**
1.1350 + * Get the paragraph level of the text.
1.1351 + *
1.1352 + * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1.1353 + *
1.1354 + * @return The paragraph level. If there are multiple paragraphs, their
1.1355 + * level may vary if the required paraLevel is UBIDI_DEFAULT_LTR or
1.1356 + * UBIDI_DEFAULT_RTL. In that case, the level of the first paragraph
1.1357 + * is returned.
1.1358 + *
1.1359 + * @see UBiDiLevel
1.1360 + * @see ubidi_getParagraph
1.1361 + * @see ubidi_getParagraphByIndex
1.1362 + * @stable ICU 2.0
1.1363 + */
1.1364 +U_STABLE UBiDiLevel U_EXPORT2
1.1365 +ubidi_getParaLevel(const UBiDi *pBiDi);
1.1366 +
1.1367 +/**
1.1368 + * Get the number of paragraphs.
1.1369 + *
1.1370 + * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1.1371 + *
1.1372 + * @return The number of paragraphs.
1.1373 + * @stable ICU 3.4
1.1374 + */
1.1375 +U_STABLE int32_t U_EXPORT2
1.1376 +ubidi_countParagraphs(UBiDi *pBiDi);
1.1377 +
1.1378 +/**
1.1379 + * Get a paragraph, given a position within the text.
1.1380 + * This function returns information about a paragraph.<br>
1.1381 + * Note: if the paragraph index is known, it is more efficient to
1.1382 + * retrieve the paragraph information using ubidi_getParagraphByIndex().<p>
1.1383 + *
1.1384 + * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1.1385 + *
1.1386 + * @param charIndex is the index of a character within the text, in the
1.1387 + * range <code>[0..ubidi_getProcessedLength(pBiDi)-1]</code>.
1.1388 + *
1.1389 + * @param pParaStart will receive the index of the first character of the
1.1390 + * paragraph in the text.
1.1391 + * This pointer can be <code>NULL</code> if this
1.1392 + * value is not necessary.
1.1393 + *
1.1394 + * @param pParaLimit will receive the limit of the paragraph.
1.1395 + * The l-value that you point to here may be the
1.1396 + * same expression (variable) as the one for
1.1397 + * <code>charIndex</code>.
1.1398 + * This pointer can be <code>NULL</code> if this
1.1399 + * value is not necessary.
1.1400 + *
1.1401 + * @param pParaLevel will receive the level of the paragraph.
1.1402 + * This pointer can be <code>NULL</code> if this
1.1403 + * value is not necessary.
1.1404 + *
1.1405 + * @param pErrorCode must be a valid pointer to an error code value.
1.1406 + *
1.1407 + * @return The index of the paragraph containing the specified position.
1.1408 + *
1.1409 + * @see ubidi_getProcessedLength
1.1410 + * @stable ICU 3.4
1.1411 + */
1.1412 +U_STABLE int32_t U_EXPORT2
1.1413 +ubidi_getParagraph(const UBiDi *pBiDi, int32_t charIndex, int32_t *pParaStart,
1.1414 + int32_t *pParaLimit, UBiDiLevel *pParaLevel,
1.1415 + UErrorCode *pErrorCode);
1.1416 +
1.1417 +/**
1.1418 + * Get a paragraph, given the index of this paragraph.
1.1419 + *
1.1420 + * This function returns information about a paragraph.<p>
1.1421 + *
1.1422 + * @param pBiDi is the paragraph <code>UBiDi</code> object.
1.1423 + *
1.1424 + * @param paraIndex is the number of the paragraph, in the
1.1425 + * range <code>[0..ubidi_countParagraphs(pBiDi)-1]</code>.
1.1426 + *
1.1427 + * @param pParaStart will receive the index of the first character of the
1.1428 + * paragraph in the text.
1.1429 + * This pointer can be <code>NULL</code> if this
1.1430 + * value is not necessary.
1.1431 + *
1.1432 + * @param pParaLimit will receive the limit of the paragraph.
1.1433 + * This pointer can be <code>NULL</code> if this
1.1434 + * value is not necessary.
1.1435 + *
1.1436 + * @param pParaLevel will receive the level of the paragraph.
1.1437 + * This pointer can be <code>NULL</code> if this
1.1438 + * value is not necessary.
1.1439 + *
1.1440 + * @param pErrorCode must be a valid pointer to an error code value.
1.1441 + *
1.1442 + * @stable ICU 3.4
1.1443 + */
1.1444 +U_STABLE void U_EXPORT2
1.1445 +ubidi_getParagraphByIndex(const UBiDi *pBiDi, int32_t paraIndex,
1.1446 + int32_t *pParaStart, int32_t *pParaLimit,
1.1447 + UBiDiLevel *pParaLevel, UErrorCode *pErrorCode);
1.1448 +
1.1449 +/**
1.1450 + * Get the level for one character.
1.1451 + *
1.1452 + * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1.1453 + *
1.1454 + * @param charIndex the index of a character. It must be in the range
1.1455 + * [0..ubidi_getProcessedLength(pBiDi)].
1.1456 + *
1.1457 + * @return The level for the character at charIndex (0 if charIndex is not
1.1458 + * in the valid range).
1.1459 + *
1.1460 + * @see UBiDiLevel
1.1461 + * @see ubidi_getProcessedLength
1.1462 + * @stable ICU 2.0
1.1463 + */
1.1464 +U_STABLE UBiDiLevel U_EXPORT2
1.1465 +ubidi_getLevelAt(const UBiDi *pBiDi, int32_t charIndex);
1.1466 +
1.1467 +/**
1.1468 + * Get an array of levels for each character.<p>
1.1469 + *
1.1470 + * Note that this function may allocate memory under some
1.1471 + * circumstances, unlike <code>ubidi_getLevelAt()</code>.
1.1472 + *
1.1473 + * @param pBiDi is the paragraph or line <code>UBiDi</code> object, whose
1.1474 + * text length must be strictly positive.
1.1475 + *
1.1476 + * @param pErrorCode must be a valid pointer to an error code value.
1.1477 + *
1.1478 + * @return The levels array for the text,
1.1479 + * or <code>NULL</code> if an error occurs.
1.1480 + *
1.1481 + * @see UBiDiLevel
1.1482 + * @see ubidi_getProcessedLength
1.1483 + * @stable ICU 2.0
1.1484 + */
1.1485 +U_STABLE const UBiDiLevel * U_EXPORT2
1.1486 +ubidi_getLevels(UBiDi *pBiDi, UErrorCode *pErrorCode);
1.1487 +
1.1488 +/**
1.1489 + * Get a logical run.
1.1490 + * This function returns information about a run and is used
1.1491 + * to retrieve runs in logical order.<p>
1.1492 + * This is especially useful for line-breaking on a paragraph.
1.1493 + *
1.1494 + * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1.1495 + *
1.1496 + * @param logicalPosition is a logical position within the source text.
1.1497 + *
1.1498 + * @param pLogicalLimit will receive the limit of the corresponding run.
1.1499 + * The l-value that you point to here may be the
1.1500 + * same expression (variable) as the one for
1.1501 + * <code>logicalPosition</code>.
1.1502 + * This pointer can be <code>NULL</code> if this
1.1503 + * value is not necessary.
1.1504 + *
1.1505 + * @param pLevel will receive the level of the corresponding run.
1.1506 + * This pointer can be <code>NULL</code> if this
1.1507 + * value is not necessary.
1.1508 + *
1.1509 + * @see ubidi_getProcessedLength
1.1510 + * @stable ICU 2.0
1.1511 + */
1.1512 +U_STABLE void U_EXPORT2
1.1513 +ubidi_getLogicalRun(const UBiDi *pBiDi, int32_t logicalPosition,
1.1514 + int32_t *pLogicalLimit, UBiDiLevel *pLevel);
1.1515 +
1.1516 +/**
1.1517 + * Get the number of runs.
1.1518 + * This function may invoke the actual reordering on the
1.1519 + * <code>UBiDi</code> object, after <code>ubidi_setPara()</code>
1.1520 + * may have resolved only the levels of the text. Therefore,
1.1521 + * <code>ubidi_countRuns()</code> may have to allocate memory,
1.1522 + * and may fail doing so.
1.1523 + *
1.1524 + * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1.1525 + *
1.1526 + * @param pErrorCode must be a valid pointer to an error code value.
1.1527 + *
1.1528 + * @return The number of runs.
1.1529 + * @stable ICU 2.0
1.1530 + */
1.1531 +U_STABLE int32_t U_EXPORT2
1.1532 +ubidi_countRuns(UBiDi *pBiDi, UErrorCode *pErrorCode);
1.1533 +
1.1534 +/**
1.1535 + * Get one run's logical start, length, and directionality,
1.1536 + * which can be 0 for LTR or 1 for RTL.
1.1537 + * In an RTL run, the character at the logical start is
1.1538 + * visually on the right of the displayed run.
1.1539 + * The length is the number of characters in the run.<p>
1.1540 + * <code>ubidi_countRuns()</code> should be called
1.1541 + * before the runs are retrieved.
1.1542 + *
1.1543 + * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1.1544 + *
1.1545 + * @param runIndex is the number of the run in visual order, in the
1.1546 + * range <code>[0..ubidi_countRuns(pBiDi)-1]</code>.
1.1547 + *
1.1548 + * @param pLogicalStart is the first logical character index in the text.
1.1549 + * The pointer may be <code>NULL</code> if this index is not needed.
1.1550 + *
1.1551 + * @param pLength is the number of characters (at least one) in the run.
1.1552 + * The pointer may be <code>NULL</code> if this is not needed.
1.1553 + *
1.1554 + * @return the directionality of the run,
1.1555 + * <code>UBIDI_LTR==0</code> or <code>UBIDI_RTL==1</code>,
1.1556 + * never <code>UBIDI_MIXED</code>,
1.1557 + * never <code>UBIDI_NEUTRAL</code>.
1.1558 + *
1.1559 + * @see ubidi_countRuns
1.1560 + *
1.1561 + * Example:
1.1562 + * <pre>
1.1563 + * \code
1.1564 + * int32_t i, count=ubidi_countRuns(pBiDi),
1.1565 + * logicalStart, visualIndex=0, length;
1.1566 + * for(i=0; i<count; ++i) {
1.1567 + * if(UBIDI_LTR==ubidi_getVisualRun(pBiDi, i, &logicalStart, &length)) {
1.1568 + * do { // LTR
1.1569 + * show_char(text[logicalStart++], visualIndex++);
1.1570 + * } while(--length>0);
1.1571 + * } else {
1.1572 + * logicalStart+=length; // logicalLimit
1.1573 + * do { // RTL
1.1574 + * show_char(text[--logicalStart], visualIndex++);
1.1575 + * } while(--length>0);
1.1576 + * }
1.1577 + * }
1.1578 + *\endcode
1.1579 + * </pre>
1.1580 + *
1.1581 + * Note that in right-to-left runs, code like this places
1.1582 + * second surrogates before first ones (which is generally a bad idea)
1.1583 + * and combining characters before base characters.
1.1584 + * <p>
1.1585 + * Use of <code>ubidi_writeReordered()</code>, optionally with the
1.1586 + * <code>#UBIDI_KEEP_BASE_COMBINING</code> option, can be considered in order
1.1587 + * to avoid these issues.
1.1588 + * @stable ICU 2.0
1.1589 + */
1.1590 +U_STABLE UBiDiDirection U_EXPORT2
1.1591 +ubidi_getVisualRun(UBiDi *pBiDi, int32_t runIndex,
1.1592 + int32_t *pLogicalStart, int32_t *pLength);
1.1593 +
1.1594 +/**
1.1595 + * Get the visual position from a logical text position.
1.1596 + * If such a mapping is used many times on the same
1.1597 + * <code>UBiDi</code> object, then calling
1.1598 + * <code>ubidi_getLogicalMap()</code> is more efficient.<p>
1.1599 + *
1.1600 + * The value returned may be <code>#UBIDI_MAP_NOWHERE</code> if there is no
1.1601 + * visual position because the corresponding text character is a Bidi control
1.1602 + * removed from output by the option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code>.
1.1603 + * <p>
1.1604 + * When the visual output is altered by using options of
1.1605 + * <code>ubidi_writeReordered()</code> such as <code>UBIDI_INSERT_LRM_FOR_NUMERIC</code>,
1.1606 + * <code>UBIDI_KEEP_BASE_COMBINING</code>, <code>UBIDI_OUTPUT_REVERSE</code>,
1.1607 + * <code>UBIDI_REMOVE_BIDI_CONTROLS</code>, the visual position returned may not
1.1608 + * be correct. It is advised to use, when possible, reordering options
1.1609 + * such as <code>UBIDI_OPTION_INSERT_MARKS</code> and <code>UBIDI_OPTION_REMOVE_CONTROLS</code>.
1.1610 + * <p>
1.1611 + * Note that in right-to-left runs, this mapping places
1.1612 + * second surrogates before first ones (which is generally a bad idea)
1.1613 + * and combining characters before base characters.
1.1614 + * Use of <code>ubidi_writeReordered()</code>, optionally with the
1.1615 + * <code>#UBIDI_KEEP_BASE_COMBINING</code> option can be considered instead
1.1616 + * of using the mapping, in order to avoid these issues.
1.1617 + *
1.1618 + * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1.1619 + *
1.1620 + * @param logicalIndex is the index of a character in the text.
1.1621 + *
1.1622 + * @param pErrorCode must be a valid pointer to an error code value.
1.1623 + *
1.1624 + * @return The visual position of this character.
1.1625 + *
1.1626 + * @see ubidi_getLogicalMap
1.1627 + * @see ubidi_getLogicalIndex
1.1628 + * @see ubidi_getProcessedLength
1.1629 + * @stable ICU 2.0
1.1630 + */
1.1631 +U_STABLE int32_t U_EXPORT2
1.1632 +ubidi_getVisualIndex(UBiDi *pBiDi, int32_t logicalIndex, UErrorCode *pErrorCode);
1.1633 +
1.1634 +/**
1.1635 + * Get the logical text position from a visual position.
1.1636 + * If such a mapping is used many times on the same
1.1637 + * <code>UBiDi</code> object, then calling
1.1638 + * <code>ubidi_getVisualMap()</code> is more efficient.<p>
1.1639 + *
1.1640 + * The value returned may be <code>#UBIDI_MAP_NOWHERE</code> if there is no
1.1641 + * logical position because the corresponding text character is a Bidi mark
1.1642 + * inserted in the output by option <code>#UBIDI_OPTION_INSERT_MARKS</code>.
1.1643 + * <p>
1.1644 + * This is the inverse function to <code>ubidi_getVisualIndex()</code>.
1.1645 + * <p>
1.1646 + * When the visual output is altered by using options of
1.1647 + * <code>ubidi_writeReordered()</code> such as <code>UBIDI_INSERT_LRM_FOR_NUMERIC</code>,
1.1648 + * <code>UBIDI_KEEP_BASE_COMBINING</code>, <code>UBIDI_OUTPUT_REVERSE</code>,
1.1649 + * <code>UBIDI_REMOVE_BIDI_CONTROLS</code>, the logical position returned may not
1.1650 + * be correct. It is advised to use, when possible, reordering options
1.1651 + * such as <code>UBIDI_OPTION_INSERT_MARKS</code> and <code>UBIDI_OPTION_REMOVE_CONTROLS</code>.
1.1652 + *
1.1653 + * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1.1654 + *
1.1655 + * @param visualIndex is the visual position of a character.
1.1656 + *
1.1657 + * @param pErrorCode must be a valid pointer to an error code value.
1.1658 + *
1.1659 + * @return The index of this character in the text.
1.1660 + *
1.1661 + * @see ubidi_getVisualMap
1.1662 + * @see ubidi_getVisualIndex
1.1663 + * @see ubidi_getResultLength
1.1664 + * @stable ICU 2.0
1.1665 + */
1.1666 +U_STABLE int32_t U_EXPORT2
1.1667 +ubidi_getLogicalIndex(UBiDi *pBiDi, int32_t visualIndex, UErrorCode *pErrorCode);
1.1668 +
1.1669 +/**
1.1670 + * Get a logical-to-visual index map (array) for the characters in the UBiDi
1.1671 + * (paragraph or line) object.
1.1672 + * <p>
1.1673 + * Some values in the map may be <code>#UBIDI_MAP_NOWHERE</code> if the
1.1674 + * corresponding text characters are Bidi controls removed from the visual
1.1675 + * output by the option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code>.
1.1676 + * <p>
1.1677 + * When the visual output is altered by using options of
1.1678 + * <code>ubidi_writeReordered()</code> such as <code>UBIDI_INSERT_LRM_FOR_NUMERIC</code>,
1.1679 + * <code>UBIDI_KEEP_BASE_COMBINING</code>, <code>UBIDI_OUTPUT_REVERSE</code>,
1.1680 + * <code>UBIDI_REMOVE_BIDI_CONTROLS</code>, the visual positions returned may not
1.1681 + * be correct. It is advised to use, when possible, reordering options
1.1682 + * such as <code>UBIDI_OPTION_INSERT_MARKS</code> and <code>UBIDI_OPTION_REMOVE_CONTROLS</code>.
1.1683 + * <p>
1.1684 + * Note that in right-to-left runs, this mapping places
1.1685 + * second surrogates before first ones (which is generally a bad idea)
1.1686 + * and combining characters before base characters.
1.1687 + * Use of <code>ubidi_writeReordered()</code>, optionally with the
1.1688 + * <code>#UBIDI_KEEP_BASE_COMBINING</code> option can be considered instead
1.1689 + * of using the mapping, in order to avoid these issues.
1.1690 + *
1.1691 + * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1.1692 + *
1.1693 + * @param indexMap is a pointer to an array of <code>ubidi_getProcessedLength()</code>
1.1694 + * indexes which will reflect the reordering of the characters.
1.1695 + * If option <code>#UBIDI_OPTION_INSERT_MARKS</code> is set, the number
1.1696 + * of elements allocated in <code>indexMap</code> must be no less than
1.1697 + * <code>ubidi_getResultLength()</code>.
1.1698 + * The array does not need to be initialized.<br><br>
1.1699 + * The index map will result in <code>indexMap[logicalIndex]==visualIndex</code>.
1.1700 + *
1.1701 + * @param pErrorCode must be a valid pointer to an error code value.
1.1702 + *
1.1703 + * @see ubidi_getVisualMap
1.1704 + * @see ubidi_getVisualIndex
1.1705 + * @see ubidi_getProcessedLength
1.1706 + * @see ubidi_getResultLength
1.1707 + * @stable ICU 2.0
1.1708 + */
1.1709 +U_STABLE void U_EXPORT2
1.1710 +ubidi_getLogicalMap(UBiDi *pBiDi, int32_t *indexMap, UErrorCode *pErrorCode);
1.1711 +
1.1712 +/**
1.1713 + * Get a visual-to-logical index map (array) for the characters in the UBiDi
1.1714 + * (paragraph or line) object.
1.1715 + * <p>
1.1716 + * Some values in the map may be <code>#UBIDI_MAP_NOWHERE</code> if the
1.1717 + * corresponding text characters are Bidi marks inserted in the visual output
1.1718 + * by the option <code>#UBIDI_OPTION_INSERT_MARKS</code>.
1.1719 + * <p>
1.1720 + * When the visual output is altered by using options of
1.1721 + * <code>ubidi_writeReordered()</code> such as <code>UBIDI_INSERT_LRM_FOR_NUMERIC</code>,
1.1722 + * <code>UBIDI_KEEP_BASE_COMBINING</code>, <code>UBIDI_OUTPUT_REVERSE</code>,
1.1723 + * <code>UBIDI_REMOVE_BIDI_CONTROLS</code>, the logical positions returned may not
1.1724 + * be correct. It is advised to use, when possible, reordering options
1.1725 + * such as <code>UBIDI_OPTION_INSERT_MARKS</code> and <code>UBIDI_OPTION_REMOVE_CONTROLS</code>.
1.1726 + *
1.1727 + * @param pBiDi is the paragraph or line <code>UBiDi</code> object.
1.1728 + *
1.1729 + * @param indexMap is a pointer to an array of <code>ubidi_getResultLength()</code>
1.1730 + * indexes which will reflect the reordering of the characters.
1.1731 + * If option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code> is set, the number
1.1732 + * of elements allocated in <code>indexMap</code> must be no less than
1.1733 + * <code>ubidi_getProcessedLength()</code>.
1.1734 + * The array does not need to be initialized.<br><br>
1.1735 + * The index map will result in <code>indexMap[visualIndex]==logicalIndex</code>.
1.1736 + *
1.1737 + * @param pErrorCode must be a valid pointer to an error code value.
1.1738 + *
1.1739 + * @see ubidi_getLogicalMap
1.1740 + * @see ubidi_getLogicalIndex
1.1741 + * @see ubidi_getProcessedLength
1.1742 + * @see ubidi_getResultLength
1.1743 + * @stable ICU 2.0
1.1744 + */
1.1745 +U_STABLE void U_EXPORT2
1.1746 +ubidi_getVisualMap(UBiDi *pBiDi, int32_t *indexMap, UErrorCode *pErrorCode);
1.1747 +
1.1748 +/**
1.1749 + * This is a convenience function that does not use a UBiDi object.
1.1750 + * It is intended to be used for when an application has determined the levels
1.1751 + * of objects (character sequences) and just needs to have them reordered (L2).
1.1752 + * This is equivalent to using <code>ubidi_getLogicalMap()</code> on a
1.1753 + * <code>UBiDi</code> object.
1.1754 + *
1.1755 + * @param levels is an array with <code>length</code> levels that have been determined by
1.1756 + * the application.
1.1757 + *
1.1758 + * @param length is the number of levels in the array, or, semantically,
1.1759 + * the number of objects to be reordered.
1.1760 + * It must be <code>length>0</code>.
1.1761 + *
1.1762 + * @param indexMap is a pointer to an array of <code>length</code>
1.1763 + * indexes which will reflect the reordering of the characters.
1.1764 + * The array does not need to be initialized.<p>
1.1765 + * The index map will result in <code>indexMap[logicalIndex]==visualIndex</code>.
1.1766 + * @stable ICU 2.0
1.1767 + */
1.1768 +U_STABLE void U_EXPORT2
1.1769 +ubidi_reorderLogical(const UBiDiLevel *levels, int32_t length, int32_t *indexMap);
1.1770 +
1.1771 +/**
1.1772 + * This is a convenience function that does not use a UBiDi object.
1.1773 + * It is intended to be used for when an application has determined the levels
1.1774 + * of objects (character sequences) and just needs to have them reordered (L2).
1.1775 + * This is equivalent to using <code>ubidi_getVisualMap()</code> on a
1.1776 + * <code>UBiDi</code> object.
1.1777 + *
1.1778 + * @param levels is an array with <code>length</code> levels that have been determined by
1.1779 + * the application.
1.1780 + *
1.1781 + * @param length is the number of levels in the array, or, semantically,
1.1782 + * the number of objects to be reordered.
1.1783 + * It must be <code>length>0</code>.
1.1784 + *
1.1785 + * @param indexMap is a pointer to an array of <code>length</code>
1.1786 + * indexes which will reflect the reordering of the characters.
1.1787 + * The array does not need to be initialized.<p>
1.1788 + * The index map will result in <code>indexMap[visualIndex]==logicalIndex</code>.
1.1789 + * @stable ICU 2.0
1.1790 + */
1.1791 +U_STABLE void U_EXPORT2
1.1792 +ubidi_reorderVisual(const UBiDiLevel *levels, int32_t length, int32_t *indexMap);
1.1793 +
1.1794 +/**
1.1795 + * Invert an index map.
1.1796 + * The index mapping of the first map is inverted and written to
1.1797 + * the second one.
1.1798 + *
1.1799 + * @param srcMap is an array with <code>length</code> elements
1.1800 + * which defines the original mapping from a source array containing
1.1801 + * <code>length</code> elements to a destination array.
1.1802 + * Some elements of the source array may have no mapping in the
1.1803 + * destination array. In that case, their value will be
1.1804 + * the special value <code>UBIDI_MAP_NOWHERE</code>.
1.1805 + * All elements must be >=0 or equal to <code>UBIDI_MAP_NOWHERE</code>.
1.1806 + * Some elements may have a value >= <code>length</code>, if the
1.1807 + * destination array has more elements than the source array.
1.1808 + * There must be no duplicate indexes (two or more elements with the
1.1809 + * same value except <code>UBIDI_MAP_NOWHERE</code>).
1.1810 + *
1.1811 + * @param destMap is an array with a number of elements equal to 1 + the highest
1.1812 + * value in <code>srcMap</code>.
1.1813 + * <code>destMap</code> will be filled with the inverse mapping.
1.1814 + * If element with index i in <code>srcMap</code> has a value k different
1.1815 + * from <code>UBIDI_MAP_NOWHERE</code>, this means that element i of
1.1816 + * the source array maps to element k in the destination array.
1.1817 + * The inverse map will have value i in its k-th element.
1.1818 + * For all elements of the destination array which do not map to
1.1819 + * an element in the source array, the corresponding element in the
1.1820 + * inverse map will have a value equal to <code>UBIDI_MAP_NOWHERE</code>.
1.1821 + *
1.1822 + * @param length is the length of each array.
1.1823 + * @see UBIDI_MAP_NOWHERE
1.1824 + * @stable ICU 2.0
1.1825 + */
1.1826 +U_STABLE void U_EXPORT2
1.1827 +ubidi_invertMap(const int32_t *srcMap, int32_t *destMap, int32_t length);
1.1828 +
1.1829 +/** option flags for ubidi_writeReordered() */
1.1830 +
1.1831 +/**
1.1832 + * option bit for ubidi_writeReordered():
1.1833 + * keep combining characters after their base characters in RTL runs
1.1834 + *
1.1835 + * @see ubidi_writeReordered
1.1836 + * @stable ICU 2.0
1.1837 + */
1.1838 +#define UBIDI_KEEP_BASE_COMBINING 1
1.1839 +
1.1840 +/**
1.1841 + * option bit for ubidi_writeReordered():
1.1842 + * replace characters with the "mirrored" property in RTL runs
1.1843 + * by their mirror-image mappings
1.1844 + *
1.1845 + * @see ubidi_writeReordered
1.1846 + * @stable ICU 2.0
1.1847 + */
1.1848 +#define UBIDI_DO_MIRRORING 2
1.1849 +
1.1850 +/**
1.1851 + * option bit for ubidi_writeReordered():
1.1852 + * surround the run with LRMs if necessary;
1.1853 + * this is part of the approximate "inverse Bidi" algorithm
1.1854 + *
1.1855 + * <p>This option does not imply corresponding adjustment of the index
1.1856 + * mappings.</p>
1.1857 + *
1.1858 + * @see ubidi_setInverse
1.1859 + * @see ubidi_writeReordered
1.1860 + * @stable ICU 2.0
1.1861 + */
1.1862 +#define UBIDI_INSERT_LRM_FOR_NUMERIC 4
1.1863 +
1.1864 +/**
1.1865 + * option bit for ubidi_writeReordered():
1.1866 + * remove Bidi control characters
1.1867 + * (this does not affect #UBIDI_INSERT_LRM_FOR_NUMERIC)
1.1868 + *
1.1869 + * <p>This option does not imply corresponding adjustment of the index
1.1870 + * mappings.</p>
1.1871 + *
1.1872 + * @see ubidi_writeReordered
1.1873 + * @stable ICU 2.0
1.1874 + */
1.1875 +#define UBIDI_REMOVE_BIDI_CONTROLS 8
1.1876 +
1.1877 +/**
1.1878 + * option bit for ubidi_writeReordered():
1.1879 + * write the output in reverse order
1.1880 + *
1.1881 + * <p>This has the same effect as calling <code>ubidi_writeReordered()</code>
1.1882 + * first without this option, and then calling
1.1883 + * <code>ubidi_writeReverse()</code> without mirroring.
1.1884 + * Doing this in the same step is faster and avoids a temporary buffer.
1.1885 + * An example for using this option is output to a character terminal that
1.1886 + * is designed for RTL scripts and stores text in reverse order.</p>
1.1887 + *
1.1888 + * @see ubidi_writeReordered
1.1889 + * @stable ICU 2.0
1.1890 + */
1.1891 +#define UBIDI_OUTPUT_REVERSE 16
1.1892 +
1.1893 +/**
1.1894 + * Get the length of the source text processed by the last call to
1.1895 + * <code>ubidi_setPara()</code>. This length may be different from the length
1.1896 + * of the source text if option <code>#UBIDI_OPTION_STREAMING</code>
1.1897 + * has been set.
1.1898 + * <br>
1.1899 + * Note that whenever the length of the text affects the execution or the
1.1900 + * result of a function, it is the processed length which must be considered,
1.1901 + * except for <code>ubidi_setPara</code> (which receives unprocessed source
1.1902 + * text) and <code>ubidi_getLength</code> (which returns the original length
1.1903 + * of the source text).<br>
1.1904 + * In particular, the processed length is the one to consider in the following
1.1905 + * cases:
1.1906 + * <ul>
1.1907 + * <li>maximum value of the <code>limit</code> argument of
1.1908 + * <code>ubidi_setLine</code></li>
1.1909 + * <li>maximum value of the <code>charIndex</code> argument of
1.1910 + * <code>ubidi_getParagraph</code></li>
1.1911 + * <li>maximum value of the <code>charIndex</code> argument of
1.1912 + * <code>ubidi_getLevelAt</code></li>
1.1913 + * <li>number of elements in the array returned by <code>ubidi_getLevels</code></li>
1.1914 + * <li>maximum value of the <code>logicalStart</code> argument of
1.1915 + * <code>ubidi_getLogicalRun</code></li>
1.1916 + * <li>maximum value of the <code>logicalIndex</code> argument of
1.1917 + * <code>ubidi_getVisualIndex</code></li>
1.1918 + * <li>number of elements filled in the <code>*indexMap</code> argument of
1.1919 + * <code>ubidi_getLogicalMap</code></li>
1.1920 + * <li>length of text processed by <code>ubidi_writeReordered</code></li>
1.1921 + * </ul>
1.1922 + *
1.1923 + * @param pBiDi is the paragraph <code>UBiDi</code> object.
1.1924 + *
1.1925 + * @return The length of the part of the source text processed by
1.1926 + * the last call to <code>ubidi_setPara</code>.
1.1927 + * @see ubidi_setPara
1.1928 + * @see UBIDI_OPTION_STREAMING
1.1929 + * @stable ICU 3.6
1.1930 + */
1.1931 +U_STABLE int32_t U_EXPORT2
1.1932 +ubidi_getProcessedLength(const UBiDi *pBiDi);
1.1933 +
1.1934 +/**
1.1935 + * Get the length of the reordered text resulting from the last call to
1.1936 + * <code>ubidi_setPara()</code>. This length may be different from the length
1.1937 + * of the source text if option <code>#UBIDI_OPTION_INSERT_MARKS</code>
1.1938 + * or option <code>#UBIDI_OPTION_REMOVE_CONTROLS</code> has been set.
1.1939 + * <br>
1.1940 + * This resulting length is the one to consider in the following cases:
1.1941 + * <ul>
1.1942 + * <li>maximum value of the <code>visualIndex</code> argument of
1.1943 + * <code>ubidi_getLogicalIndex</code></li>
1.1944 + * <li>number of elements of the <code>*indexMap</code> argument of
1.1945 + * <code>ubidi_getVisualMap</code></li>
1.1946 + * </ul>
1.1947 + * Note that this length stays identical to the source text length if
1.1948 + * Bidi marks are inserted or removed using option bits of
1.1949 + * <code>ubidi_writeReordered</code>, or if option
1.1950 + * <code>#UBIDI_REORDER_INVERSE_NUMBERS_AS_L</code> has been set.
1.1951 + *
1.1952 + * @param pBiDi is the paragraph <code>UBiDi</code> object.
1.1953 + *
1.1954 + * @return The length of the reordered text resulting from
1.1955 + * the last call to <code>ubidi_setPara</code>.
1.1956 + * @see ubidi_setPara
1.1957 + * @see UBIDI_OPTION_INSERT_MARKS
1.1958 + * @see UBIDI_OPTION_REMOVE_CONTROLS
1.1959 + * @stable ICU 3.6
1.1960 + */
1.1961 +U_STABLE int32_t U_EXPORT2
1.1962 +ubidi_getResultLength(const UBiDi *pBiDi);
1.1963 +
1.1964 +U_CDECL_BEGIN
1.1965 +/**
1.1966 + * value returned by <code>UBiDiClassCallback</code> callbacks when
1.1967 + * there is no need to override the standard Bidi class for a given code point.
1.1968 + * @see UBiDiClassCallback
1.1969 + * @stable ICU 3.6
1.1970 + */
1.1971 +#define U_BIDI_CLASS_DEFAULT U_CHAR_DIRECTION_COUNT
1.1972 +
1.1973 +/**
1.1974 + * Callback type declaration for overriding default Bidi class values with
1.1975 + * custom ones.
1.1976 + * <p>Usually, the function pointer will be propagated to a <code>UBiDi</code>
1.1977 + * object by calling the <code>ubidi_setClassCallback()</code> function;
1.1978 + * then the callback will be invoked by the UBA implementation any time the
1.1979 + * class of a character is to be determined.</p>
1.1980 + *
1.1981 + * @param context is a pointer to the callback private data.
1.1982 + *
1.1983 + * @param c is the code point to get a Bidi class for.
1.1984 + *
1.1985 + * @return The directional property / Bidi class for the given code point
1.1986 + * <code>c</code> if the default class has been overridden, or
1.1987 + * <code>#U_BIDI_CLASS_DEFAULT</code> if the standard Bidi class value
1.1988 + * for <code>c</code> is to be used.
1.1989 + * @see ubidi_setClassCallback
1.1990 + * @see ubidi_getClassCallback
1.1991 + * @stable ICU 3.6
1.1992 + */
1.1993 +typedef UCharDirection U_CALLCONV
1.1994 +UBiDiClassCallback(const void *context, UChar32 c);
1.1995 +
1.1996 +U_CDECL_END
1.1997 +
1.1998 +/**
1.1999 + * Retrieve the Bidi class for a given code point.
1.2000 + * <p>If a <code>#UBiDiClassCallback</code> callback is defined and returns a
1.2001 + * value other than <code>#U_BIDI_CLASS_DEFAULT</code>, that value is used;
1.2002 + * otherwise the default class determination mechanism is invoked.</p>
1.2003 + *
1.2004 + * @param pBiDi is the paragraph <code>UBiDi</code> object.
1.2005 + *
1.2006 + * @param c is the code point whose Bidi class must be retrieved.
1.2007 + *
1.2008 + * @return The Bidi class for character <code>c</code> based
1.2009 + * on the given <code>pBiDi</code> instance.
1.2010 + * @see UBiDiClassCallback
1.2011 + * @stable ICU 3.6
1.2012 + */
1.2013 +U_STABLE UCharDirection U_EXPORT2
1.2014 +ubidi_getCustomizedClass(UBiDi *pBiDi, UChar32 c);
1.2015 +
1.2016 +/**
1.2017 + * Set the callback function and callback data used by the UBA
1.2018 + * implementation for Bidi class determination.
1.2019 + * <p>This may be useful for assigning Bidi classes to PUA characters, or
1.2020 + * for special application needs. For instance, an application may want to
1.2021 + * handle all spaces like L or R characters (according to the base direction)
1.2022 + * when creating the visual ordering of logical lines which are part of a report
1.2023 + * organized in columns: there should not be interaction between adjacent
1.2024 + * cells.<p>
1.2025 + *
1.2026 + * @param pBiDi is the paragraph <code>UBiDi</code> object.
1.2027 + *
1.2028 + * @param newFn is the new callback function pointer.
1.2029 + *
1.2030 + * @param newContext is the new callback context pointer. This can be NULL.
1.2031 + *
1.2032 + * @param oldFn fillin: Returns the old callback function pointer. This can be
1.2033 + * NULL.
1.2034 + *
1.2035 + * @param oldContext fillin: Returns the old callback's context. This can be
1.2036 + * NULL.
1.2037 + *
1.2038 + * @param pErrorCode must be a valid pointer to an error code value.
1.2039 + *
1.2040 + * @see ubidi_getClassCallback
1.2041 + * @stable ICU 3.6
1.2042 + */
1.2043 +U_STABLE void U_EXPORT2
1.2044 +ubidi_setClassCallback(UBiDi *pBiDi, UBiDiClassCallback *newFn,
1.2045 + const void *newContext, UBiDiClassCallback **oldFn,
1.2046 + const void **oldContext, UErrorCode *pErrorCode);
1.2047 +
1.2048 +/**
1.2049 + * Get the current callback function used for Bidi class determination.
1.2050 + *
1.2051 + * @param pBiDi is the paragraph <code>UBiDi</code> object.
1.2052 + *
1.2053 + * @param fn fillin: Returns the callback function pointer.
1.2054 + *
1.2055 + * @param context fillin: Returns the callback's private context.
1.2056 + *
1.2057 + * @see ubidi_setClassCallback
1.2058 + * @stable ICU 3.6
1.2059 + */
1.2060 +U_STABLE void U_EXPORT2
1.2061 +ubidi_getClassCallback(UBiDi *pBiDi, UBiDiClassCallback **fn, const void **context);
1.2062 +
1.2063 +/**
1.2064 + * Take a <code>UBiDi</code> object containing the reordering
1.2065 + * information for a piece of text (one or more paragraphs) set by
1.2066 + * <code>ubidi_setPara()</code> or for a line of text set by
1.2067 + * <code>ubidi_setLine()</code> and write a reordered string to the
1.2068 + * destination buffer.
1.2069 + *
1.2070 + * This function preserves the integrity of characters with multiple
1.2071 + * code units and (optionally) combining characters.
1.2072 + * Characters in RTL runs can be replaced by mirror-image characters
1.2073 + * in the destination buffer. Note that "real" mirroring has
1.2074 + * to be done in a rendering engine by glyph selection
1.2075 + * and that for many "mirrored" characters there are no
1.2076 + * Unicode characters as mirror-image equivalents.
1.2077 + * There are also options to insert or remove Bidi control
1.2078 + * characters; see the description of the <code>destSize</code>
1.2079 + * and <code>options</code> parameters and of the option bit flags.
1.2080 + *
1.2081 + * @param pBiDi A pointer to a <code>UBiDi</code> object that
1.2082 + * is set by <code>ubidi_setPara()</code> or
1.2083 + * <code>ubidi_setLine()</code> and contains the reordering
1.2084 + * information for the text that it was defined for,
1.2085 + * as well as a pointer to that text.<br><br>
1.2086 + * The text was aliased (only the pointer was stored
1.2087 + * without copying the contents) and must not have been modified
1.2088 + * since the <code>ubidi_setPara()</code> call.
1.2089 + *
1.2090 + * @param dest A pointer to where the reordered text is to be copied.
1.2091 + * The source text and <code>dest[destSize]</code>
1.2092 + * must not overlap.
1.2093 + *
1.2094 + * @param destSize The size of the <code>dest</code> buffer,
1.2095 + * in number of UChars.
1.2096 + * If the <code>UBIDI_INSERT_LRM_FOR_NUMERIC</code>
1.2097 + * option is set, then the destination length could be
1.2098 + * as large as
1.2099 + * <code>ubidi_getLength(pBiDi)+2*ubidi_countRuns(pBiDi)</code>.
1.2100 + * If the <code>UBIDI_REMOVE_BIDI_CONTROLS</code> option
1.2101 + * is set, then the destination length may be less than
1.2102 + * <code>ubidi_getLength(pBiDi)</code>.
1.2103 + * If none of these options is set, then the destination length
1.2104 + * will be exactly <code>ubidi_getProcessedLength(pBiDi)</code>.
1.2105 + *
1.2106 + * @param options A bit set of options for the reordering that control
1.2107 + * how the reordered text is written.
1.2108 + * The options include mirroring the characters on a code
1.2109 + * point basis and inserting LRM characters, which is used
1.2110 + * especially for transforming visually stored text
1.2111 + * to logically stored text (although this is still an
1.2112 + * imperfect implementation of an "inverse Bidi" algorithm
1.2113 + * because it uses the "forward Bidi" algorithm at its core).
1.2114 + * The available options are:
1.2115 + * <code>#UBIDI_DO_MIRRORING</code>,
1.2116 + * <code>#UBIDI_INSERT_LRM_FOR_NUMERIC</code>,
1.2117 + * <code>#UBIDI_KEEP_BASE_COMBINING</code>,
1.2118 + * <code>#UBIDI_OUTPUT_REVERSE</code>,
1.2119 + * <code>#UBIDI_REMOVE_BIDI_CONTROLS</code>
1.2120 + *
1.2121 + * @param pErrorCode must be a valid pointer to an error code value.
1.2122 + *
1.2123 + * @return The length of the output string.
1.2124 + *
1.2125 + * @see ubidi_getProcessedLength
1.2126 + * @stable ICU 2.0
1.2127 + */
1.2128 +U_STABLE int32_t U_EXPORT2
1.2129 +ubidi_writeReordered(UBiDi *pBiDi,
1.2130 + UChar *dest, int32_t destSize,
1.2131 + uint16_t options,
1.2132 + UErrorCode *pErrorCode);
1.2133 +
1.2134 +/**
1.2135 + * Reverse a Right-To-Left run of Unicode text.
1.2136 + *
1.2137 + * This function preserves the integrity of characters with multiple
1.2138 + * code units and (optionally) combining characters.
1.2139 + * Characters can be replaced by mirror-image characters
1.2140 + * in the destination buffer. Note that "real" mirroring has
1.2141 + * to be done in a rendering engine by glyph selection
1.2142 + * and that for many "mirrored" characters there are no
1.2143 + * Unicode characters as mirror-image equivalents.
1.2144 + * There are also options to insert or remove Bidi control
1.2145 + * characters.
1.2146 + *
1.2147 + * This function is the implementation for reversing RTL runs as part
1.2148 + * of <code>ubidi_writeReordered()</code>. For detailed descriptions
1.2149 + * of the parameters, see there.
1.2150 + * Since no Bidi controls are inserted here, the output string length
1.2151 + * will never exceed <code>srcLength</code>.
1.2152 + *
1.2153 + * @see ubidi_writeReordered
1.2154 + *
1.2155 + * @param src A pointer to the RTL run text.
1.2156 + *
1.2157 + * @param srcLength The length of the RTL run.
1.2158 + *
1.2159 + * @param dest A pointer to where the reordered text is to be copied.
1.2160 + * <code>src[srcLength]</code> and <code>dest[destSize]</code>
1.2161 + * must not overlap.
1.2162 + *
1.2163 + * @param destSize The size of the <code>dest</code> buffer,
1.2164 + * in number of UChars.
1.2165 + * If the <code>UBIDI_REMOVE_BIDI_CONTROLS</code> option
1.2166 + * is set, then the destination length may be less than
1.2167 + * <code>srcLength</code>.
1.2168 + * If this option is not set, then the destination length
1.2169 + * will be exactly <code>srcLength</code>.
1.2170 + *
1.2171 + * @param options A bit set of options for the reordering that control
1.2172 + * how the reordered text is written.
1.2173 + * See the <code>options</code> parameter in <code>ubidi_writeReordered()</code>.
1.2174 + *
1.2175 + * @param pErrorCode must be a valid pointer to an error code value.
1.2176 + *
1.2177 + * @return The length of the output string.
1.2178 + * @stable ICU 2.0
1.2179 + */
1.2180 +U_STABLE int32_t U_EXPORT2
1.2181 +ubidi_writeReverse(const UChar *src, int32_t srcLength,
1.2182 + UChar *dest, int32_t destSize,
1.2183 + uint16_t options,
1.2184 + UErrorCode *pErrorCode);
1.2185 +
1.2186 +/*#define BIDI_SAMPLE_CODE*/
1.2187 +/*@}*/
1.2188 +
1.2189 +#endif
