jpayne@69: // © 2016 and later: Unicode, Inc. and others. jpayne@69: // License & terms of use: http://www.unicode.org/copyright.html jpayne@69: /* jpayne@69: ****************************************************************************** jpayne@69: * jpayne@69: * Copyright (C) 1999-2013, International Business Machines jpayne@69: * Corporation and others. All Rights Reserved. jpayne@69: * jpayne@69: ****************************************************************************** jpayne@69: * file name: ubidi.h jpayne@69: * encoding: UTF-8 jpayne@69: * tab size: 8 (not used) jpayne@69: * indentation:4 jpayne@69: * jpayne@69: * created on: 1999jul27 jpayne@69: * created by: Markus W. Scherer, updated by Matitiahu Allouche jpayne@69: */ jpayne@69: jpayne@69: #ifndef UBIDI_H jpayne@69: #define UBIDI_H jpayne@69: jpayne@69: #include "unicode/utypes.h" jpayne@69: #include "unicode/uchar.h" jpayne@69: #include "unicode/localpointer.h" jpayne@69: jpayne@69: /** jpayne@69: *\file jpayne@69: * \brief C API: Bidi algorithm jpayne@69: * jpayne@69: *

Bidi algorithm for ICU

jpayne@69: * jpayne@69: * This is an implementation of the Unicode Bidirectional Algorithm. jpayne@69: * The algorithm is defined in the jpayne@69: * Unicode Standard Annex #9.

jpayne@69: * jpayne@69: * Note: Libraries that perform a bidirectional algorithm and jpayne@69: * reorder strings accordingly are sometimes called "Storage Layout Engines". jpayne@69: * ICU's Bidi and shaping (u_shapeArabic()) APIs can be used at the core of such jpayne@69: * "Storage Layout Engines". jpayne@69: * jpayne@69: *

General remarks about the API:

jpayne@69: * jpayne@69: * In functions with an error code parameter, jpayne@69: * the pErrorCode pointer must be valid jpayne@69: * and the value that it points to must not indicate a failure before jpayne@69: * the function call. Otherwise, the function returns immediately. jpayne@69: * After the function call, the value indicates success or failure.

jpayne@69: * jpayne@69: * The "limit" of a sequence of characters is the position just after their jpayne@69: * last character, i.e., one more than that position.

jpayne@69: * jpayne@69: * Some of the API functions provide access to "runs". jpayne@69: * Such a "run" is defined as a sequence of characters jpayne@69: * that are at the same embedding level jpayne@69: * after performing the Bidi algorithm.

jpayne@69: * jpayne@69: * @author Markus W. Scherer jpayne@69: * @version 1.0 jpayne@69: * jpayne@69: * jpayne@69: *

Sample code for the ICU Bidi API

jpayne@69: * jpayne@69: *

Rendering a paragraph with the ICU Bidi API

jpayne@69: * jpayne@69: * This is (hypothetical) sample code that illustrates jpayne@69: * how the ICU Bidi API could be used to render a paragraph of text. jpayne@69: * Rendering code depends highly on the graphics system, jpayne@69: * therefore this sample code must make a lot of assumptions, jpayne@69: * which may or may not match any existing graphics system's properties. jpayne@69: * jpayne@69: *

The basic assumptions are:

jpayne@69: *

Rendering is done from left to right on a horizontal line.
A run of single-style, unidirectional text can be rendered at once.
Such a run of text is passed to the graphics system with jpayne@69: * characters (code units) in logical order.
The line-breaking algorithm is very complicated jpayne@69: * and Locale-dependent - jpayne@69: * and therefore its implementation omitted from this sample code.

jpayne@69: * jpayne@69: *

jpayne@69:  * \code
jpayne@69:  *#include "unicode/ubidi.h"
jpayne@69:  *
jpayne@69:  *typedef enum {
jpayne@69:  *     styleNormal=0, styleSelected=1,
jpayne@69:  *     styleBold=2, styleItalics=4,
jpayne@69:  *     styleSuper=8, styleSub=16
jpayne@69:  *} Style;
jpayne@69:  *
jpayne@69:  *typedef struct { int32_t limit; Style style; } StyleRun;
jpayne@69:  *
jpayne@69:  *int getTextWidth(const UChar *text, int32_t start, int32_t limit,
jpayne@69:  *                  const StyleRun *styleRuns, int styleRunCount);
jpayne@69:  *
jpayne@69:  * // set *pLimit and *pStyleRunLimit for a line
jpayne@69:  * // from text[start] and from styleRuns[styleRunStart]
jpayne@69:  * // using ubidi_getLogicalRun(para, ...)
jpayne@69:  *void getLineBreak(const UChar *text, int32_t start, int32_t *pLimit,
jpayne@69:  *                  UBiDi *para,
jpayne@69:  *                  const StyleRun *styleRuns, int styleRunStart, int *pStyleRunLimit,
jpayne@69:  *                  int *pLineWidth);
jpayne@69:  *
jpayne@69:  * // render runs on a line sequentially, always from left to right
jpayne@69:  *
jpayne@69:  * // prepare rendering a new line
jpayne@69:  * void startLine(UBiDiDirection textDirection, int lineWidth);
jpayne@69:  *
jpayne@69:  * // render a run of text and advance to the right by the run width
jpayne@69:  * // the text[start..limit-1] is always in logical order
jpayne@69:  * void renderRun(const UChar *text, int32_t start, int32_t limit,
jpayne@69:  *               UBiDiDirection textDirection, Style style);
jpayne@69:  *
jpayne@69:  * // We could compute a cross-product
jpayne@69:  * // from the style runs with the directional runs
jpayne@69:  * // and then reorder it.
jpayne@69:  * // Instead, here we iterate over each run type
jpayne@69:  * // and render the intersections -
jpayne@69:  * // with shortcuts in simple (and common) cases.
jpayne@69:  * // renderParagraph() is the main function.
jpayne@69:  *
jpayne@69:  * // render a directional run with
jpayne@69:  * // (possibly) multiple style runs intersecting with it
jpayne@69:  * void renderDirectionalRun(const UChar *text,
jpayne@69:  *                           int32_t start, int32_t limit,
jpayne@69:  *                           UBiDiDirection direction,
jpayne@69:  *                           const StyleRun *styleRuns, int styleRunCount) {
jpayne@69:  *     int i;
jpayne@69:  *
jpayne@69:  *     // iterate over style runs
jpayne@69:  *     if(direction==UBIDI_LTR) {
jpayne@69:  *         int styleLimit;
jpayne@69:  *
jpayne@69:  *         for(i=0; ilimit) { styleLimit=limit; }
jpayne@69:  *                 renderRun(text, start, styleLimit,
jpayne@69:  *                           direction, styleRun[i].style);
jpayne@69:  *                 if(styleLimit==limit) { break; }
jpayne@69:  *                 start=styleLimit;
jpayne@69:  *             }
jpayne@69:  *         }
jpayne@69:  *     } else {
jpayne@69:  *         int styleStart;
jpayne@69:  *
jpayne@69:  *         for(i=styleRunCount-1; i>=0; --i) {
jpayne@69:  *             if(i>0) {
jpayne@69:  *                 styleStart=styleRun[i-1].limit;
jpayne@69:  *             } else {
jpayne@69:  *                 styleStart=0;
jpayne@69:  *             }
jpayne@69:  *             if(limit>=styleStart) {
jpayne@69:  *                 if(styleStart=length
jpayne@69:  *
jpayne@69:  *         width=getTextWidth(text, 0, length, styleRuns, styleRunCount);
jpayne@69:  *         if(width<=lineWidth) {
jpayne@69:  *             // everything fits onto one line
jpayne@69:  *
jpayne@69:  *            // prepare rendering a new line from either left or right
jpayne@69:  *             startLine(paraLevel, width);
jpayne@69:  *
jpayne@69:  *             renderLine(para, text, 0, length,
jpayne@69:  *                        styleRuns, styleRunCount);
jpayne@69:  *         } else {
jpayne@69:  *             UBiDi *line;
jpayne@69:  *
jpayne@69:  *             // we need to render several lines
jpayne@69:  *             line=ubidi_openSized(length, 0, pErrorCode);
jpayne@69:  *             if(line!=NULL) {
jpayne@69:  *                 int32_t start=0, limit;
jpayne@69:  *                 int styleRunStart=0, styleRunLimit;
jpayne@69:  *
jpayne@69:  *                 for(;;) {
jpayne@69:  *                     limit=length;
jpayne@69:  *                     styleRunLimit=styleRunCount;
jpayne@69:  *                     getLineBreak(text, start, &limit, para,
jpayne@69:  *                                  styleRuns, styleRunStart, &styleRunLimit,
jpayne@69:  *                                 &width);
jpayne@69:  *                     ubidi_setLine(para, start, limit, line, pErrorCode);
jpayne@69:  *                     if(U_SUCCESS(*pErrorCode)) {
jpayne@69:  *                         // prepare rendering a new line
jpayne@69:  *                         // from either left or right
jpayne@69:  *                         startLine(paraLevel, width);
jpayne@69:  *
jpayne@69:  *                         renderLine(line, text, start, limit,
jpayne@69:  *                                    styleRuns+styleRunStart,
jpayne@69:  *                                    styleRunLimit-styleRunStart);
jpayne@69:  *                     }
jpayne@69:  *                     if(limit==length) { break; }
jpayne@69:  *                     start=limit;
jpayne@69:  *                     styleRunStart=styleRunLimit-1;
jpayne@69:  *                     if(start>=styleRuns[styleRunStart].limit) {
jpayne@69:  *                         ++styleRunStart;
jpayne@69:  *                     }
jpayne@69:  *                 }
jpayne@69:  *
jpayne@69:  *                 ubidi_close(line);
jpayne@69:  *             }
jpayne@69:  *        }
jpayne@69:  *    }
jpayne@69:  *
jpayne@69:  *     ubidi_close(para);
jpayne@69:  *}
jpayne@69:  *\endcode
jpayne@69:  *

jpayne@69: */ jpayne@69: jpayne@69: /*DOCXX_TAG*/ jpayne@69: /*@{*/ jpayne@69: jpayne@69: /** jpayne@69: * UBiDiLevel is the type of the level values in this jpayne@69: * Bidi implementation. jpayne@69: * It holds an embedding level and indicates the visual direction jpayne@69: * by its bit 0 (even/odd value).

jpayne@69: * jpayne@69: * It can also hold non-level values for the jpayne@69: * paraLevel and embeddingLevels jpayne@69: * arguments of ubidi_setPara(); there: jpayne@69: *

bit 7 of an embeddingLevels[] jpayne@69: * value indicates whether the using application is jpayne@69: * specifying the level of a character to override whatever the jpayne@69: * Bidi implementation would resolve it to.
paraLevel can be set to the jpayne@69: * pseudo-level values UBIDI_DEFAULT_LTR jpayne@69: * and UBIDI_DEFAULT_RTL.

jpayne@69: * jpayne@69: * @see ubidi_setPara jpayne@69: * jpayne@69: *

The related constants are not real, valid level values. jpayne@69: * UBIDI_DEFAULT_XXX can be used to specify jpayne@69: * a default for the paragraph level for jpayne@69: * when the ubidi_setPara() function jpayne@69: * shall determine it but there is no jpayne@69: * strongly typed character in the input.

jpayne@69: * jpayne@69: * Note that the value for UBIDI_DEFAULT_LTR is even jpayne@69: * and the one for UBIDI_DEFAULT_RTL is odd, jpayne@69: * just like with normal LTR and RTL level values - jpayne@69: * these special values are designed that way. Also, the implementation jpayne@69: * assumes that UBIDI_MAX_EXPLICIT_LEVEL is odd. jpayne@69: * jpayne@69: * Note: The numeric values of the related constants will not change: jpayne@69: * They are tied to the use of 7-bit byte values (plus the override bit) jpayne@69: * and of the UBiDiLevel=uint8_t data type in this API. jpayne@69: * jpayne@69: * @see UBIDI_DEFAULT_LTR jpayne@69: * @see UBIDI_DEFAULT_RTL jpayne@69: * @see UBIDI_LEVEL_OVERRIDE jpayne@69: * @see UBIDI_MAX_EXPLICIT_LEVEL jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: typedef uint8_t UBiDiLevel; jpayne@69: jpayne@69: /** Paragraph level setting.

jpayne@69: * jpayne@69: * Constant indicating that the base direction depends on the first strong jpayne@69: * directional character in the text according to the Unicode Bidirectional jpayne@69: * Algorithm. If no strong directional character is present, jpayne@69: * then set the paragraph level to 0 (left-to-right).

jpayne@69: * jpayne@69: * If this value is used in conjunction with reordering modes jpayne@69: * UBIDI_REORDER_INVERSE_LIKE_DIRECT or jpayne@69: * UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL, the text to reorder jpayne@69: * is assumed to be visual LTR, and the text after reordering is required jpayne@69: * to be the corresponding logical string with appropriate contextual jpayne@69: * direction. The direction of the result string will be RTL if either jpayne@69: * the righmost or leftmost strong character of the source text is RTL jpayne@69: * or Arabic Letter, the direction will be LTR otherwise.

jpayne@69: * jpayne@69: * If reordering option UBIDI_OPTION_INSERT_MARKS is set, an RLM may jpayne@69: * be added at the beginning of the result string to ensure round trip jpayne@69: * (that the result string, when reordered back to visual, will produce jpayne@69: * the original source text). jpayne@69: * @see UBIDI_REORDER_INVERSE_LIKE_DIRECT jpayne@69: * @see UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: #define UBIDI_DEFAULT_RTL 0xff jpayne@69: jpayne@69: /** jpayne@69: * Maximum explicit embedding level. jpayne@69: * Same as the max_depth value in the jpayne@69: * Unicode Bidirectional Algorithm. jpayne@69: * (The maximum resolved level can be up to UBIDI_MAX_EXPLICIT_LEVEL+1). jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: #define UBIDI_MAX_EXPLICIT_LEVEL 125 jpayne@69: jpayne@69: /** Bit flag for level input. jpayne@69: * Overrides directional properties. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: #define UBIDI_LEVEL_OVERRIDE 0x80 jpayne@69: jpayne@69: /** jpayne@69: * Special value which can be returned by the mapping functions when a logical jpayne@69: * index has no corresponding visual index or vice-versa. This may happen jpayne@69: * for the logical-to-visual mapping of a Bidi control when option jpayne@69: * #UBIDI_OPTION_REMOVE_CONTROLS is specified. This can also happen jpayne@69: * for the visual-to-logical mapping of a Bidi mark (LRM or RLM) inserted jpayne@69: * by option #UBIDI_OPTION_INSERT_MARKS. jpayne@69: * @see ubidi_getVisualIndex jpayne@69: * @see ubidi_getVisualMap jpayne@69: * @see ubidi_getLogicalIndex jpayne@69: * @see ubidi_getLogicalMap jpayne@69: * @stable ICU 3.6 jpayne@69: */ jpayne@69: #define UBIDI_MAP_NOWHERE (-1) jpayne@69: jpayne@69: /** jpayne@69: * UBiDiDirection values indicate the text direction. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: enum UBiDiDirection { jpayne@69: /** Left-to-right text. This is a 0 value. jpayne@69: *

As return value for ubidi_getDirection(), it means jpayne@69: * that the source string contains no right-to-left characters, or jpayne@69: * that the source string is empty and the paragraph level is even. jpayne@69: *
As return value for ubidi_getBaseDirection(), it jpayne@69: * means that the first strong character of the source string has jpayne@69: * a left-to-right direction. jpayne@69: *

jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: UBIDI_LTR, jpayne@69: /** Right-to-left text. This is a 1 value. jpayne@69: *

As return value for ubidi_getDirection(), it means jpayne@69: * that the source string contains no left-to-right characters, or jpayne@69: * that the source string is empty and the paragraph level is odd. jpayne@69: *
As return value for ubidi_getBaseDirection(), it jpayne@69: * means that the first strong character of the source string has jpayne@69: * a right-to-left direction. jpayne@69: *

jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: UBIDI_RTL, jpayne@69: /** Mixed-directional text. jpayne@69: *

As return value for ubidi_getDirection(), it means jpayne@69: * that the source string contains both left-to-right and jpayne@69: * right-to-left characters. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: UBIDI_MIXED, jpayne@69: /** No strongly directional text. jpayne@69: *

As return value for ubidi_getBaseDirection(), it means jpayne@69: * that the source string is missing or empty, or contains neither left-to-right jpayne@69: * nor right-to-left characters. jpayne@69: * @stable ICU 4.6 jpayne@69: */ jpayne@69: UBIDI_NEUTRAL jpayne@69: }; jpayne@69: jpayne@69: /** @stable ICU 2.0 */ jpayne@69: typedef enum UBiDiDirection UBiDiDirection; jpayne@69: jpayne@69: /** jpayne@69: * Forward declaration of the UBiDi structure for the declaration of jpayne@69: * the API functions. Its fields are implementation-specific.

jpayne@69: * This structure holds information about a paragraph (or multiple paragraphs) jpayne@69: * of text with Bidi-algorithm-related details, or about one line of jpayne@69: * such a paragraph.

jpayne@69: * Reordering can be done on a line, or on one or more paragraphs which are jpayne@69: * then interpreted each as one single line. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: struct UBiDi; jpayne@69: jpayne@69: /** @stable ICU 2.0 */ jpayne@69: typedef struct UBiDi UBiDi; jpayne@69: jpayne@69: /** jpayne@69: * Allocate a UBiDi structure. jpayne@69: * Such an object is initially empty. It is assigned jpayne@69: * the Bidi properties of a piece of text containing one or more paragraphs jpayne@69: * by ubidi_setPara() jpayne@69: * or the Bidi properties of a line within a paragraph by jpayne@69: * ubidi_setLine().

jpayne@69: * This object can be reused for as long as it is not deallocated jpayne@69: * by calling ubidi_close().

jpayne@69: * ubidi_setPara() and ubidi_setLine() will allocate jpayne@69: * additional memory for internal structures as necessary. jpayne@69: * jpayne@69: * @return An empty UBiDi object. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE UBiDi * U_EXPORT2 jpayne@69: ubidi_open(void); jpayne@69: jpayne@69: /** jpayne@69: * Allocate a UBiDi structure with preallocated memory jpayne@69: * for internal structures. jpayne@69: * This function provides a UBiDi object like ubidi_open() jpayne@69: * with no arguments, but it also preallocates memory for internal structures jpayne@69: * according to the sizings supplied by the caller.

jpayne@69: * Subsequent functions will not allocate any more memory, and are thus jpayne@69: * guaranteed not to fail because of lack of memory.

jpayne@69: * The preallocation can be limited to some of the internal memory jpayne@69: * by setting some values to 0 here. That means that if, e.g., jpayne@69: * maxRunCount cannot be reasonably predetermined and should not jpayne@69: * be set to maxLength (the only failproof value) to avoid jpayne@69: * wasting memory, then maxRunCount could be set to 0 here jpayne@69: * and the internal structures that are associated with it will be allocated jpayne@69: * on demand, just like with ubidi_open(). jpayne@69: * jpayne@69: * @param maxLength is the maximum text or line length that internal memory jpayne@69: * will be preallocated for. An attempt to associate this object with a jpayne@69: * longer text will fail, unless this value is 0, which leaves the allocation jpayne@69: * up to the implementation. jpayne@69: * jpayne@69: * @param maxRunCount is the maximum anticipated number of same-level runs jpayne@69: * that internal memory will be preallocated for. An attempt to access jpayne@69: * visual runs on an object that was not preallocated for as many runs jpayne@69: * as the text was actually resolved to will fail, jpayne@69: * unless this value is 0, which leaves the allocation up to the implementation.

jpayne@69: * The number of runs depends on the actual text and maybe anywhere between jpayne@69: * 1 and maxLength. It is typically small. jpayne@69: * jpayne@69: * @param pErrorCode must be a valid pointer to an error code value. jpayne@69: * jpayne@69: * @return An empty UBiDi object with preallocated memory. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE UBiDi * U_EXPORT2 jpayne@69: ubidi_openSized(int32_t maxLength, int32_t maxRunCount, UErrorCode *pErrorCode); jpayne@69: jpayne@69: /** jpayne@69: * ubidi_close() must be called to free the memory jpayne@69: * associated with a UBiDi object.

jpayne@69: * jpayne@69: * Important: jpayne@69: * A parent UBiDi object must not be destroyed or reused if jpayne@69: * it still has children. jpayne@69: * If a UBiDi object has become the child jpayne@69: * of another one (its parent) by calling jpayne@69: * ubidi_setLine(), then the child object must jpayne@69: * be destroyed (closed) or reused (by calling jpayne@69: * ubidi_setPara() or ubidi_setLine()) jpayne@69: * before the parent object. jpayne@69: * jpayne@69: * @param pBiDi is a UBiDi object. jpayne@69: * jpayne@69: * @see ubidi_setPara jpayne@69: * @see ubidi_setLine jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ubidi_close(UBiDi *pBiDi); jpayne@69: jpayne@69: #if U_SHOW_CPLUSPLUS_API jpayne@69: jpayne@69: U_NAMESPACE_BEGIN jpayne@69: jpayne@69: /** jpayne@69: * \class LocalUBiDiPointer jpayne@69: * "Smart pointer" class, closes a UBiDi via ubidi_close(). jpayne@69: * For most methods see the LocalPointerBase base class. jpayne@69: * jpayne@69: * @see LocalPointerBase jpayne@69: * @see LocalPointer jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: U_DEFINE_LOCAL_OPEN_POINTER(LocalUBiDiPointer, UBiDi, ubidi_close); jpayne@69: jpayne@69: U_NAMESPACE_END jpayne@69: jpayne@69: #endif jpayne@69: jpayne@69: /** jpayne@69: * Modify the operation of the Bidi algorithm such that it jpayne@69: * approximates an "inverse Bidi" algorithm. This function jpayne@69: * must be called before ubidi_setPara(). jpayne@69: * jpayne@69: *

The normal operation of the Bidi algorithm as described jpayne@69: * in the Unicode Technical Report is to take text stored in logical jpayne@69: * (keyboard, typing) order and to determine the reordering of it for visual jpayne@69: * rendering. jpayne@69: * Some legacy systems store text in visual order, and for operations jpayne@69: * with standard, Unicode-based algorithms, the text needs to be transformed jpayne@69: * to logical order. This is effectively the inverse algorithm of the jpayne@69: * described Bidi algorithm. Note that there is no standard algorithm for jpayne@69: * this "inverse Bidi" and that the current implementation provides only an jpayne@69: * approximation of "inverse Bidi".

jpayne@69: * jpayne@69: *

With isInverse set to TRUE, jpayne@69: * this function changes the behavior of some of the subsequent functions jpayne@69: * in a way that they can be used for the inverse Bidi algorithm. jpayne@69: * Specifically, runs of text with numeric characters will be treated in a jpayne@69: * special way and may need to be surrounded with LRM characters when they are jpayne@69: * written in reordered sequence.

jpayne@69: * jpayne@69: *

Output runs should be retrieved using ubidi_getVisualRun(). jpayne@69: * Since the actual input for "inverse Bidi" is visually ordered text and jpayne@69: * ubidi_getVisualRun() gets the reordered runs, these are actually jpayne@69: * the runs of the logically ordered output.

jpayne@69: * jpayne@69: *

Calling this function with argument isInverse set to jpayne@69: * TRUE is equivalent to calling jpayne@69: * ubidi_setReorderingMode with argument jpayne@69: * reorderingMode jpayne@69: * set to #UBIDI_REORDER_INVERSE_NUMBERS_AS_L.
jpayne@69: * Calling this function with argument isInverse set to jpayne@69: * FALSE is equivalent to calling jpayne@69: * ubidi_setReorderingMode with argument jpayne@69: * reorderingMode jpayne@69: * set to #UBIDI_REORDER_DEFAULT. jpayne@69: * jpayne@69: * @param pBiDi is a UBiDi object. jpayne@69: * jpayne@69: * @param isInverse specifies "forward" or "inverse" Bidi operation. jpayne@69: * jpayne@69: * @see ubidi_setPara jpayne@69: * @see ubidi_writeReordered jpayne@69: * @see ubidi_setReorderingMode jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ubidi_setInverse(UBiDi *pBiDi, UBool isInverse); jpayne@69: jpayne@69: /** jpayne@69: * Is this Bidi object set to perform the inverse Bidi algorithm? jpayne@69: *

Note: calling this function after setting the reordering mode with jpayne@69: * ubidi_setReorderingMode will return TRUE if the jpayne@69: * reordering mode was set to #UBIDI_REORDER_INVERSE_NUMBERS_AS_L, jpayne@69: * FALSE for all other values.

jpayne@69: * jpayne@69: * @param pBiDi is a UBiDi object. jpayne@69: * @return TRUE if the Bidi object is set to perform the inverse Bidi algorithm jpayne@69: * by handling numbers as L. jpayne@69: * jpayne@69: * @see ubidi_setInverse jpayne@69: * @see ubidi_setReorderingMode jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: jpayne@69: U_STABLE UBool U_EXPORT2 jpayne@69: ubidi_isInverse(UBiDi *pBiDi); jpayne@69: jpayne@69: /** jpayne@69: * Specify whether block separators must be allocated level zero, jpayne@69: * so that successive paragraphs will progress from left to right. jpayne@69: * This function must be called before ubidi_setPara(). jpayne@69: * Paragraph separators (B) may appear in the text. Setting them to level zero jpayne@69: * means that all paragraph separators (including one possibly appearing jpayne@69: * in the last text position) are kept in the reordered text after the text jpayne@69: * that they follow in the source text. jpayne@69: * When this feature is not enabled, a paragraph separator at the last jpayne@69: * position of the text before reordering will go to the first position jpayne@69: * of the reordered text when the paragraph level is odd. jpayne@69: * jpayne@69: * @param pBiDi is a UBiDi object. jpayne@69: * jpayne@69: * @param orderParagraphsLTR specifies whether paragraph separators (B) must jpayne@69: * receive level 0, so that successive paragraphs progress from left to right. jpayne@69: * jpayne@69: * @see ubidi_setPara jpayne@69: * @stable ICU 3.4 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ubidi_orderParagraphsLTR(UBiDi *pBiDi, UBool orderParagraphsLTR); jpayne@69: jpayne@69: /** jpayne@69: * Is this Bidi object set to allocate level 0 to block separators so that jpayne@69: * successive paragraphs progress from left to right? jpayne@69: * jpayne@69: * @param pBiDi is a UBiDi object. jpayne@69: * @return TRUE if the Bidi object is set to allocate level 0 to block jpayne@69: * separators. jpayne@69: * jpayne@69: * @see ubidi_orderParagraphsLTR jpayne@69: * @stable ICU 3.4 jpayne@69: */ jpayne@69: U_STABLE UBool U_EXPORT2 jpayne@69: ubidi_isOrderParagraphsLTR(UBiDi *pBiDi); jpayne@69: jpayne@69: /** jpayne@69: * UBiDiReorderingMode values indicate which variant of the Bidi jpayne@69: * algorithm to use. jpayne@69: * jpayne@69: * @see ubidi_setReorderingMode jpayne@69: * @stable ICU 3.6 jpayne@69: */ jpayne@69: typedef enum UBiDiReorderingMode { jpayne@69: /** Regular Logical to Visual Bidi algorithm according to Unicode. jpayne@69: * This is a 0 value. jpayne@69: * @stable ICU 3.6 */ jpayne@69: UBIDI_REORDER_DEFAULT = 0, jpayne@69: /** Logical to Visual algorithm which handles numbers in a way which jpayne@69: * mimics the behavior of Windows XP. jpayne@69: * @stable ICU 3.6 */ jpayne@69: UBIDI_REORDER_NUMBERS_SPECIAL, jpayne@69: /** Logical to Visual algorithm grouping numbers with adjacent R characters jpayne@69: * (reversible algorithm). jpayne@69: * @stable ICU 3.6 */ jpayne@69: UBIDI_REORDER_GROUP_NUMBERS_WITH_R, jpayne@69: /** Reorder runs only to transform a Logical LTR string to the Logical RTL jpayne@69: * string with the same display, or vice-versa.
jpayne@69: * If this mode is set together with option jpayne@69: * #UBIDI_OPTION_INSERT_MARKS, some Bidi controls in the source jpayne@69: * text may be removed and other controls may be added to produce the jpayne@69: * minimum combination which has the required display. jpayne@69: * @stable ICU 3.6 */ jpayne@69: UBIDI_REORDER_RUNS_ONLY, jpayne@69: /** Visual to Logical algorithm which handles numbers like L jpayne@69: * (same algorithm as selected by ubidi_setInverse(TRUE). jpayne@69: * @see ubidi_setInverse jpayne@69: * @stable ICU 3.6 */ jpayne@69: UBIDI_REORDER_INVERSE_NUMBERS_AS_L, jpayne@69: /** Visual to Logical algorithm equivalent to the regular Logical to Visual jpayne@69: * algorithm. jpayne@69: * @stable ICU 3.6 */ jpayne@69: UBIDI_REORDER_INVERSE_LIKE_DIRECT, jpayne@69: /** Inverse Bidi (Visual to Logical) algorithm for the jpayne@69: * UBIDI_REORDER_NUMBERS_SPECIAL Bidi algorithm. jpayne@69: * @stable ICU 3.6 */ jpayne@69: UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL, jpayne@69: #ifndef U_HIDE_DEPRECATED_API jpayne@69: /** jpayne@69: * Number of values for reordering mode. jpayne@69: * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. jpayne@69: */ jpayne@69: UBIDI_REORDER_COUNT jpayne@69: #endif // U_HIDE_DEPRECATED_API jpayne@69: } UBiDiReorderingMode; jpayne@69: jpayne@69: /** jpayne@69: * Modify the operation of the Bidi algorithm such that it implements some jpayne@69: * variant to the basic Bidi algorithm or approximates an "inverse Bidi" jpayne@69: * algorithm, depending on different values of the "reordering mode". jpayne@69: * This function must be called before ubidi_setPara(), and stays jpayne@69: * in effect until called again with a different argument. jpayne@69: * jpayne@69: *

The normal operation of the Bidi algorithm as described jpayne@69: * in the Unicode Standard Annex #9 is to take text stored in logical jpayne@69: * (keyboard, typing) order and to determine how to reorder it for visual jpayne@69: * rendering.

jpayne@69: * jpayne@69: *

With the reordering mode set to a value other than jpayne@69: * #UBIDI_REORDER_DEFAULT, this function changes the behavior of jpayne@69: * some of the subsequent functions in a way such that they implement an jpayne@69: * inverse Bidi algorithm or some other algorithm variants.

jpayne@69: * jpayne@69: *

Some legacy systems store text in visual order, and for operations jpayne@69: * with standard, Unicode-based algorithms, the text needs to be transformed jpayne@69: * into logical order. This is effectively the inverse algorithm of the jpayne@69: * described Bidi algorithm. Note that there is no standard algorithm for jpayne@69: * this "inverse Bidi", so a number of variants are implemented here.

jpayne@69: * jpayne@69: *

In other cases, it may be desirable to emulate some variant of the jpayne@69: * Logical to Visual algorithm (e.g. one used in MS Windows), or perform a jpayne@69: * Logical to Logical transformation.

jpayne@69: * jpayne@69: *

When the reordering mode is set to #UBIDI_REORDER_DEFAULT, jpayne@69: * the standard Bidi Logical to Visual algorithm is applied.
When the reordering mode is set to jpayne@69: * #UBIDI_REORDER_NUMBERS_SPECIAL, jpayne@69: * the algorithm used to perform Bidi transformations when calling jpayne@69: * ubidi_setPara should approximate the algorithm used in jpayne@69: * Microsoft Windows XP rather than strictly conform to the Unicode Bidi jpayne@69: * algorithm. jpayne@69: *
jpayne@69: * The differences between the basic algorithm and the algorithm addressed jpayne@69: * by this option are as follows: jpayne@69: *
- Within text at an even embedding level, the sequence "123AB" jpayne@69: * (where AB represent R or AL letters) is transformed to "123BA" by the jpayne@69: * Unicode algorithm and to "BA123" by the Windows algorithm.
- Arabic-Indic numbers (AN) are handled by the Windows algorithm just jpayne@69: * like regular numbers (EN).
When the reordering mode is set to jpayne@69: * #UBIDI_REORDER_GROUP_NUMBERS_WITH_R, jpayne@69: * numbers located between LTR text and RTL text are associated with the RTL jpayne@69: * text. For instance, an LTR paragraph with content "abc 123 DEF" (where jpayne@69: * upper case letters represent RTL characters) will be transformed to jpayne@69: * "abc FED 123" (and not "abc 123 FED"), "DEF 123 abc" will be transformed jpayne@69: * to "123 FED abc" and "123 FED abc" will be transformed to "DEF 123 abc". jpayne@69: * This makes the algorithm reversible and makes it useful when round trip jpayne@69: * (from visual to logical and back to visual) must be achieved without jpayne@69: * adding LRM characters. However, this is a variation from the standard jpayne@69: * Unicode Bidi algorithm.
jpayne@69: * The source text should not contain Bidi control characters other than LRM jpayne@69: * or RLM.
When the reordering mode is set to jpayne@69: * #UBIDI_REORDER_RUNS_ONLY, jpayne@69: * a "Logical to Logical" transformation must be performed: jpayne@69: *
- If the default text level of the source text (argument paraLevel jpayne@69: * in ubidi_setPara) is even, the source text will be handled as jpayne@69: * LTR logical text and will be transformed to the RTL logical text which has jpayne@69: * the same LTR visual display.
- If the default level of the source text is odd, the source text jpayne@69: * will be handled as RTL logical text and will be transformed to the jpayne@69: * LTR logical text which has the same LTR visual display.
jpayne@69: * This mode may be needed when logical text which is basically Arabic or jpayne@69: * Hebrew, with possible included numbers or phrases in English, has to be jpayne@69: * displayed as if it had an even embedding level (this can happen if the jpayne@69: * displaying application treats all text as if it was basically LTR). jpayne@69: *
jpayne@69: * This mode may also be needed in the reverse case, when logical text which is jpayne@69: * basically English, with possible included phrases in Arabic or Hebrew, has to jpayne@69: * be displayed as if it had an odd embedding level. jpayne@69: *
jpayne@69: * Both cases could be handled by adding LRE or RLE at the head of the text, jpayne@69: * if the display subsystem supports these formatting controls. If it does not, jpayne@69: * the problem may be handled by transforming the source text in this mode jpayne@69: * before displaying it, so that it will be displayed properly.
jpayne@69: * The source text should not contain Bidi control characters other than LRM jpayne@69: * or RLM.
When the reordering mode is set to jpayne@69: * #UBIDI_REORDER_INVERSE_NUMBERS_AS_L, an "inverse Bidi" algorithm jpayne@69: * is applied. jpayne@69: * Runs of text with numeric characters will be treated like LTR letters and jpayne@69: * may need to be surrounded with LRM characters when they are written in jpayne@69: * reordered sequence (the option #UBIDI_INSERT_LRM_FOR_NUMERIC can jpayne@69: * be used with function ubidi_writeReordered to this end. This jpayne@69: * mode is equivalent to calling ubidi_setInverse() with jpayne@69: * argument isInverse set to TRUE.
When the reordering mode is set to jpayne@69: * #UBIDI_REORDER_INVERSE_LIKE_DIRECT, the "direct" Logical to Visual jpayne@69: * Bidi algorithm is used as an approximation of an "inverse Bidi" algorithm. jpayne@69: * This mode is similar to mode #UBIDI_REORDER_INVERSE_NUMBERS_AS_L jpayne@69: * but is closer to the regular Bidi algorithm. jpayne@69: *
jpayne@69: * For example, an LTR paragraph with the content "FED 123 456 CBA" (where jpayne@69: * upper case represents RTL characters) will be transformed to jpayne@69: * "ABC 456 123 DEF", as opposed to "DEF 123 456 ABC" jpayne@69: * with mode UBIDI_REORDER_INVERSE_NUMBERS_AS_L.
jpayne@69: * When used in conjunction with option jpayne@69: * #UBIDI_OPTION_INSERT_MARKS, this mode generally jpayne@69: * adds Bidi marks to the output significantly more sparingly than mode jpayne@69: * #UBIDI_REORDER_INVERSE_NUMBERS_AS_L with option jpayne@69: * #UBIDI_INSERT_LRM_FOR_NUMERIC in calls to jpayne@69: * ubidi_writeReordered.
When the reordering mode is set to jpayne@69: * #UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL, the Logical to Visual jpayne@69: * Bidi algorithm used in Windows XP is used as an approximation of an "inverse Bidi" algorithm. jpayne@69: *
jpayne@69: * For example, an LTR paragraph with the content "abc FED123" (where jpayne@69: * upper case represents RTL characters) will be transformed to "abc 123DEF."

jpayne@69: * jpayne@69: *

In all the reordering modes specifying an "inverse Bidi" algorithm jpayne@69: * (i.e. those with a name starting with UBIDI_REORDER_INVERSE), jpayne@69: * output runs should be retrieved using jpayne@69: * ubidi_getVisualRun(), and the output text with jpayne@69: * ubidi_writeReordered(). The caller should keep in mind that in jpayne@69: * "inverse Bidi" modes the input is actually visually ordered text and jpayne@69: * reordered output returned by ubidi_getVisualRun() or jpayne@69: * ubidi_writeReordered() are actually runs or character string jpayne@69: * of logically ordered output.
jpayne@69: * For all the "inverse Bidi" modes, the source text should not contain jpayne@69: * Bidi control characters other than LRM or RLM.

jpayne@69: * jpayne@69: *

Note that option #UBIDI_OUTPUT_REVERSE of jpayne@69: * ubidi_writeReordered has no useful meaning and should not be jpayne@69: * used in conjunction with any value of the reordering mode specifying jpayne@69: * "inverse Bidi" or with value UBIDI_REORDER_RUNS_ONLY. jpayne@69: * jpayne@69: * @param pBiDi is a UBiDi object. jpayne@69: * @param reorderingMode specifies the required variant of the Bidi algorithm. jpayne@69: * jpayne@69: * @see UBiDiReorderingMode jpayne@69: * @see ubidi_setInverse jpayne@69: * @see ubidi_setPara jpayne@69: * @see ubidi_writeReordered jpayne@69: * @stable ICU 3.6 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ubidi_setReorderingMode(UBiDi *pBiDi, UBiDiReorderingMode reorderingMode); jpayne@69: jpayne@69: /** jpayne@69: * What is the requested reordering mode for a given Bidi object? jpayne@69: * jpayne@69: * @param pBiDi is a UBiDi object. jpayne@69: * @return the current reordering mode of the Bidi object jpayne@69: * @see ubidi_setReorderingMode jpayne@69: * @stable ICU 3.6 jpayne@69: */ jpayne@69: U_STABLE UBiDiReorderingMode U_EXPORT2 jpayne@69: ubidi_getReorderingMode(UBiDi *pBiDi); jpayne@69: jpayne@69: /** jpayne@69: * UBiDiReorderingOption values indicate which options are jpayne@69: * specified to affect the Bidi algorithm. jpayne@69: * jpayne@69: * @see ubidi_setReorderingOptions jpayne@69: * @stable ICU 3.6 jpayne@69: */ jpayne@69: typedef enum UBiDiReorderingOption { jpayne@69: /** jpayne@69: * option value for ubidi_setReorderingOptions: jpayne@69: * disable all the options which can be set with this function jpayne@69: * @see ubidi_setReorderingOptions jpayne@69: * @stable ICU 3.6 jpayne@69: */ jpayne@69: UBIDI_OPTION_DEFAULT = 0, jpayne@69: jpayne@69: /** jpayne@69: * option bit for ubidi_setReorderingOptions: jpayne@69: * insert Bidi marks (LRM or RLM) when needed to ensure correct result of jpayne@69: * a reordering to a Logical order jpayne@69: * jpayne@69: *

This option must be set or reset before calling jpayne@69: * ubidi_setPara.

jpayne@69: * jpayne@69: *

This option is significant only with reordering modes which generate jpayne@69: * a result with Logical order, specifically:

jpayne@69: *

#UBIDI_REORDER_RUNS_ONLY
#UBIDI_REORDER_INVERSE_NUMBERS_AS_L
#UBIDI_REORDER_INVERSE_LIKE_DIRECT
#UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL

jpayne@69: * jpayne@69: *

If this option is set in conjunction with reordering mode jpayne@69: * #UBIDI_REORDER_INVERSE_NUMBERS_AS_L or with calling jpayne@69: * ubidi_setInverse(TRUE), it implies jpayne@69: * option #UBIDI_INSERT_LRM_FOR_NUMERIC jpayne@69: * in calls to function ubidi_writeReordered().

jpayne@69: * jpayne@69: *

For other reordering modes, a minimum number of LRM or RLM characters jpayne@69: * will be added to the source text after reordering it so as to ensure jpayne@69: * round trip, i.e. when applying the inverse reordering mode on the jpayne@69: * resulting logical text with removal of Bidi marks jpayne@69: * (option #UBIDI_OPTION_REMOVE_CONTROLS set before calling jpayne@69: * ubidi_setPara() or option #UBIDI_REMOVE_BIDI_CONTROLS jpayne@69: * in ubidi_writeReordered), the result will be identical to the jpayne@69: * source text in the first transformation. jpayne@69: * jpayne@69: *

This option will be ignored if specified together with option jpayne@69: * #UBIDI_OPTION_REMOVE_CONTROLS. It inhibits option jpayne@69: * UBIDI_REMOVE_BIDI_CONTROLS in calls to function jpayne@69: * ubidi_writeReordered() and it implies option jpayne@69: * #UBIDI_INSERT_LRM_FOR_NUMERIC in calls to function jpayne@69: * ubidi_writeReordered() if the reordering mode is jpayne@69: * #UBIDI_REORDER_INVERSE_NUMBERS_AS_L.

jpayne@69: * jpayne@69: * @see ubidi_setReorderingMode jpayne@69: * @see ubidi_setReorderingOptions jpayne@69: * @stable ICU 3.6 jpayne@69: */ jpayne@69: UBIDI_OPTION_INSERT_MARKS = 1, jpayne@69: jpayne@69: /** jpayne@69: * option bit for ubidi_setReorderingOptions: jpayne@69: * remove Bidi control characters jpayne@69: * jpayne@69: *

This option must be set or reset before calling jpayne@69: * ubidi_setPara.

jpayne@69: * jpayne@69: *

This option nullifies option #UBIDI_OPTION_INSERT_MARKS. jpayne@69: * It inhibits option #UBIDI_INSERT_LRM_FOR_NUMERIC in calls jpayne@69: * to function ubidi_writeReordered() and it implies option jpayne@69: * #UBIDI_REMOVE_BIDI_CONTROLS in calls to that function.

jpayne@69: * jpayne@69: * @see ubidi_setReorderingMode jpayne@69: * @see ubidi_setReorderingOptions jpayne@69: * @stable ICU 3.6 jpayne@69: */ jpayne@69: UBIDI_OPTION_REMOVE_CONTROLS = 2, jpayne@69: jpayne@69: /** jpayne@69: * option bit for ubidi_setReorderingOptions: jpayne@69: * process the output as part of a stream to be continued jpayne@69: * jpayne@69: *

This option must be set or reset before calling jpayne@69: * ubidi_setPara.

jpayne@69: * jpayne@69: *

This option specifies that the caller is interested in processing large jpayne@69: * text object in parts. jpayne@69: * The results of the successive calls are expected to be concatenated by the jpayne@69: * caller. Only the call for the last part will have this option bit off.

jpayne@69: * jpayne@69: *

When this option bit is on, ubidi_setPara() may process jpayne@69: * less than the full source text in order to truncate the text at a meaningful jpayne@69: * boundary. The caller should call ubidi_getProcessedLength() jpayne@69: * immediately after calling ubidi_setPara() in order to jpayne@69: * determine how much of the source text has been processed. jpayne@69: * Source text beyond that length should be resubmitted in following calls to jpayne@69: * ubidi_setPara. The processed length may be less than jpayne@69: * the length of the source text if a character preceding the last character of jpayne@69: * the source text constitutes a reasonable boundary (like a block separator) jpayne@69: * for text to be continued.
jpayne@69: * If the last character of the source text constitutes a reasonable jpayne@69: * boundary, the whole text will be processed at once.
jpayne@69: * If nowhere in the source text there exists jpayne@69: * such a reasonable boundary, the processed length will be zero.
jpayne@69: * The caller should check for such an occurrence and do one of the following: jpayne@69: *

submit a larger amount of text with a better chance to include jpayne@69: * a reasonable boundary.
resubmit the same text after turning off option jpayne@69: * UBIDI_OPTION_STREAMING.

jpayne@69: * In all cases, this option should be turned off before processing the last jpayne@69: * part of the text.

jpayne@69: * jpayne@69: *

When the UBIDI_OPTION_STREAMING option is used, jpayne@69: * it is recommended to call ubidi_orderParagraphsLTR() with jpayne@69: * argument orderParagraphsLTR set to TRUE before jpayne@69: * calling ubidi_setPara so that later paragraphs may be jpayne@69: * concatenated to previous paragraphs on the right.

jpayne@69: * jpayne@69: * @see ubidi_setReorderingMode jpayne@69: * @see ubidi_setReorderingOptions jpayne@69: * @see ubidi_getProcessedLength jpayne@69: * @see ubidi_orderParagraphsLTR jpayne@69: * @stable ICU 3.6 jpayne@69: */ jpayne@69: UBIDI_OPTION_STREAMING = 4 jpayne@69: } UBiDiReorderingOption; jpayne@69: jpayne@69: /** jpayne@69: * Specify which of the reordering options jpayne@69: * should be applied during Bidi transformations. jpayne@69: * jpayne@69: * @param pBiDi is a UBiDi object. jpayne@69: * @param reorderingOptions is a combination of zero or more of the following jpayne@69: * options: jpayne@69: * #UBIDI_OPTION_DEFAULT, #UBIDI_OPTION_INSERT_MARKS, jpayne@69: * #UBIDI_OPTION_REMOVE_CONTROLS, #UBIDI_OPTION_STREAMING. jpayne@69: * jpayne@69: * @see ubidi_getReorderingOptions jpayne@69: * @stable ICU 3.6 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ubidi_setReorderingOptions(UBiDi *pBiDi, uint32_t reorderingOptions); jpayne@69: jpayne@69: /** jpayne@69: * What are the reordering options applied to a given Bidi object? jpayne@69: * jpayne@69: * @param pBiDi is a UBiDi object. jpayne@69: * @return the current reordering options of the Bidi object jpayne@69: * @see ubidi_setReorderingOptions jpayne@69: * @stable ICU 3.6 jpayne@69: */ jpayne@69: U_STABLE uint32_t U_EXPORT2 jpayne@69: ubidi_getReorderingOptions(UBiDi *pBiDi); jpayne@69: jpayne@69: /** jpayne@69: * Set the context before a call to ubidi_setPara().

jpayne@69: * jpayne@69: * ubidi_setPara() computes the left-right directionality for a given piece jpayne@69: * of text which is supplied as one of its arguments. Sometimes this piece jpayne@69: * of text (the "main text") should be considered in context, because text jpayne@69: * appearing before ("prologue") and/or after ("epilogue") the main text jpayne@69: * may affect the result of this computation.

jpayne@69: * jpayne@69: * This function specifies the prologue and/or the epilogue for the next jpayne@69: * call to ubidi_setPara(). The characters specified as prologue and jpayne@69: * epilogue should not be modified by the calling program until the call jpayne@69: * to ubidi_setPara() has returned. If successive calls to ubidi_setPara() jpayne@69: * all need specification of a context, ubidi_setContext() must be called jpayne@69: * before each call to ubidi_setPara(). In other words, a context is not jpayne@69: * "remembered" after the following successful call to ubidi_setPara().

jpayne@69: * jpayne@69: * If a call to ubidi_setPara() specifies UBIDI_DEFAULT_LTR or jpayne@69: * UBIDI_DEFAULT_RTL as paraLevel and is preceded by a call to jpayne@69: * ubidi_setContext() which specifies a prologue, the paragraph level will jpayne@69: * be computed taking in consideration the text in the prologue.

jpayne@69: * jpayne@69: * When ubidi_setPara() is called without a previous call to jpayne@69: * ubidi_setContext, the main text is handled as if preceded and followed jpayne@69: * by strong directional characters at the current paragraph level. jpayne@69: * Calling ubidi_setContext() with specification of a prologue will change jpayne@69: * this behavior by handling the main text as if preceded by the last jpayne@69: * strong character appearing in the prologue, if any. jpayne@69: * Calling ubidi_setContext() with specification of an epilogue will change jpayne@69: * the behavior of ubidi_setPara() by handling the main text as if followed jpayne@69: * by the first strong character or digit appearing in the epilogue, if any.

jpayne@69: * jpayne@69: * Note 1: if ubidi_setContext is called repeatedly without jpayne@69: * calling ubidi_setPara, the earlier calls have no effect, jpayne@69: * only the last call will be remembered for the next call to jpayne@69: * ubidi_setPara.

jpayne@69: * jpayne@69: * Note 2: calling ubidi_setContext(pBiDi, NULL, 0, NULL, 0, &errorCode) jpayne@69: * cancels any previous setting of non-empty prologue or epilogue. jpayne@69: * The next call to ubidi_setPara() will process no jpayne@69: * prologue or epilogue.

jpayne@69: * jpayne@69: * Note 3: users must be aware that even after setting the context jpayne@69: * before a call to ubidi_setPara() to perform e.g. a logical to visual jpayne@69: * transformation, the resulting string may not be identical to what it jpayne@69: * would have been if all the text, including prologue and epilogue, had jpayne@69: * been processed together.
jpayne@69: * Example (upper case letters represent RTL characters):
jpayne@69: *   prologue = "abc DE"
jpayne@69: *   epilogue = none
jpayne@69: *   main text = "FGH xyz"
jpayne@69: *   paraLevel = UBIDI_LTR
jpayne@69: *   display without prologue = "HGF xyz" jpayne@69: * ("HGF" is adjacent to "xyz")
jpayne@69: *   display with prologue = "abc HGFED xyz" jpayne@69: * ("HGF" is not adjacent to "xyz")
jpayne@69: * jpayne@69: * @param pBiDi is a paragraph UBiDi object. jpayne@69: * jpayne@69: * @param prologue is a pointer to the text which precedes the text that jpayne@69: * will be specified in a coming call to ubidi_setPara(). jpayne@69: * If there is no prologue to consider, then proLength jpayne@69: * must be zero and this pointer can be NULL. jpayne@69: * jpayne@69: * @param proLength is the length of the prologue; if proLength==-1 jpayne@69: * then the prologue must be zero-terminated. jpayne@69: * Otherwise proLength must be >= 0. If proLength==0, it means jpayne@69: * that there is no prologue to consider. jpayne@69: * jpayne@69: * @param epilogue is a pointer to the text which follows the text that jpayne@69: * will be specified in a coming call to ubidi_setPara(). jpayne@69: * If there is no epilogue to consider, then epiLength jpayne@69: * must be zero and this pointer can be NULL. jpayne@69: * jpayne@69: * @param epiLength is the length of the epilogue; if epiLength==-1 jpayne@69: * then the epilogue must be zero-terminated. jpayne@69: * Otherwise epiLength must be >= 0. If epiLength==0, it means jpayne@69: * that there is no epilogue to consider. jpayne@69: * jpayne@69: * @param pErrorCode must be a valid pointer to an error code value. jpayne@69: * jpayne@69: * @see ubidi_setPara jpayne@69: * @stable ICU 4.8 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ubidi_setContext(UBiDi *pBiDi, jpayne@69: const UChar *prologue, int32_t proLength, jpayne@69: const UChar *epilogue, int32_t epiLength, jpayne@69: UErrorCode *pErrorCode); jpayne@69: jpayne@69: /** jpayne@69: * Perform the Unicode Bidi algorithm. It is defined in the jpayne@69: * Unicode Standard Annex #9, jpayne@69: * version 13, jpayne@69: * also described in The Unicode Standard, Version 4.0 .

jpayne@69: * jpayne@69: * This function takes a piece of plain text containing one or more paragraphs, jpayne@69: * with or without externally specified embedding levels from styled jpayne@69: * text and computes the left-right-directionality of each character.

jpayne@69: * jpayne@69: * If the entire text is all of the same directionality, then jpayne@69: * the function may not perform all the steps described by the algorithm, jpayne@69: * i.e., some levels may not be the same as if all steps were performed. jpayne@69: * This is not relevant for unidirectional text.
jpayne@69: * For example, in pure LTR text with numbers the numbers would get jpayne@69: * a resolved level of 2 higher than the surrounding text according to jpayne@69: * the algorithm. This implementation may set all resolved levels to jpayne@69: * the same value in such a case.

jpayne@69: * jpayne@69: * The text can be composed of multiple paragraphs. Occurrence of a block jpayne@69: * separator in the text terminates a paragraph, and whatever comes next starts jpayne@69: * a new paragraph. The exception to this rule is when a Carriage Return (CR) jpayne@69: * is followed by a Line Feed (LF). Both CR and LF are block separators, but jpayne@69: * in that case, the pair of characters is considered as terminating the jpayne@69: * preceding paragraph, and a new paragraph will be started by a character jpayne@69: * coming after the LF. jpayne@69: * jpayne@69: * @param pBiDi A UBiDi object allocated with ubidi_open() jpayne@69: * which will be set to contain the reordering information, jpayne@69: * especially the resolved levels for all the characters in text. jpayne@69: * jpayne@69: * @param text is a pointer to the text that the Bidi algorithm will be performed on. jpayne@69: * This pointer is stored in the UBiDi object and can be retrieved jpayne@69: * with ubidi_getText().
jpayne@69: * Note: the text must be (at least) length long. jpayne@69: * jpayne@69: * @param length is the length of the text; if length==-1 then jpayne@69: * the text must be zero-terminated. jpayne@69: * jpayne@69: * @param paraLevel specifies the default level for the text; jpayne@69: * it is typically 0 (LTR) or 1 (RTL). jpayne@69: * If the function shall determine the paragraph level from the text, jpayne@69: * then paraLevel can be set to jpayne@69: * either #UBIDI_DEFAULT_LTR jpayne@69: * or #UBIDI_DEFAULT_RTL; if the text contains multiple jpayne@69: * paragraphs, the paragraph level shall be determined separately for jpayne@69: * each paragraph; if a paragraph does not include any strongly typed jpayne@69: * character, then the desired default is used (0 for LTR or 1 for RTL). jpayne@69: * Any other value between 0 and #UBIDI_MAX_EXPLICIT_LEVEL jpayne@69: * is also valid, with odd levels indicating RTL. jpayne@69: * jpayne@69: * @param embeddingLevels (in) may be used to preset the embedding and override levels, jpayne@69: * ignoring characters like LRE and PDF in the text. jpayne@69: * A level overrides the directional property of its corresponding jpayne@69: * (same index) character if the level has the jpayne@69: * #UBIDI_LEVEL_OVERRIDE bit set.

jpayne@69: * Aside from that bit, it must be jpayne@69: * paraLevel<=embeddingLevels[]<=UBIDI_MAX_EXPLICIT_LEVEL, jpayne@69: * except that level 0 is always allowed. jpayne@69: * Level 0 for a paragraph separator prevents reordering of paragraphs; jpayne@69: * this only works reliably if #UBIDI_LEVEL_OVERRIDE jpayne@69: * is also set for paragraph separators. jpayne@69: * Level 0 for other characters is treated as a wildcard jpayne@69: * and is lifted up to the resolved level of the surrounding paragraph.

jpayne@69: * Caution: A copy of this pointer, not of the levels, jpayne@69: * will be stored in the UBiDi object; jpayne@69: * the embeddingLevels array must not be jpayne@69: * deallocated before the UBiDi structure is destroyed or reused, jpayne@69: * and the embeddingLevels jpayne@69: * should not be modified to avoid unexpected results on subsequent Bidi operations. jpayne@69: * However, the ubidi_setPara() and jpayne@69: * ubidi_setLine() functions may modify some or all of the levels.

jpayne@69: * After the UBiDi object is reused or destroyed, the caller jpayne@69: * must take care of the deallocation of the embeddingLevels array.

jpayne@69: * Note: the embeddingLevels array must be jpayne@69: * at least length long. jpayne@69: * This pointer can be NULL if this jpayne@69: * value is not necessary. jpayne@69: * jpayne@69: * @param pErrorCode must be a valid pointer to an error code value. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ubidi_setPara(UBiDi *pBiDi, const UChar *text, int32_t length, jpayne@69: UBiDiLevel paraLevel, UBiDiLevel *embeddingLevels, jpayne@69: UErrorCode *pErrorCode); jpayne@69: jpayne@69: /** jpayne@69: * ubidi_setLine() sets a UBiDi to jpayne@69: * contain the reordering information, especially the resolved levels, jpayne@69: * for all the characters in a line of text. This line of text is jpayne@69: * specified by referring to a UBiDi object representing jpayne@69: * this information for a piece of text containing one or more paragraphs, jpayne@69: * and by specifying a range of indexes in this text.

jpayne@69: * In the new line object, the indexes will range from 0 to limit-start-1.

jpayne@69: * jpayne@69: * This is used after calling ubidi_setPara() jpayne@69: * for a piece of text, and after line-breaking on that text. jpayne@69: * It is not necessary if each paragraph is treated as a single line.

jpayne@69: * jpayne@69: * After line-breaking, rules (L1) and (L2) for the treatment of jpayne@69: * trailing WS and for reordering are performed on jpayne@69: * a UBiDi object that represents a line.

jpayne@69: * jpayne@69: * Important: pLineBiDi shares data with jpayne@69: * pParaBiDi. jpayne@69: * You must destroy or reuse pLineBiDi before pParaBiDi. jpayne@69: * In other words, you must destroy or reuse the UBiDi object for a line jpayne@69: * before the object for its parent paragraph.

jpayne@69: * jpayne@69: * The text pointer that was stored in pParaBiDi is also copied, jpayne@69: * and start is added to it so that it points to the beginning of the jpayne@69: * line for this object. jpayne@69: * jpayne@69: * @param pParaBiDi is the parent paragraph object. It must have been set jpayne@69: * by a successful call to ubidi_setPara. jpayne@69: * jpayne@69: * @param start is the line's first index into the text. jpayne@69: * jpayne@69: * @param limit is just behind the line's last index into the text jpayne@69: * (its last index +1).
jpayne@69: * It must be 0<=startcontaining paragraph limit. jpayne@69: * If the specified line crosses a paragraph boundary, the function jpayne@69: * will terminate with error code U_ILLEGAL_ARGUMENT_ERROR. jpayne@69: * jpayne@69: * @param pLineBiDi is the object that will now represent a line of the text. jpayne@69: * jpayne@69: * @param pErrorCode must be a valid pointer to an error code value. jpayne@69: * jpayne@69: * @see ubidi_setPara jpayne@69: * @see ubidi_getProcessedLength jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ubidi_setLine(const UBiDi *pParaBiDi, jpayne@69: int32_t start, int32_t limit, jpayne@69: UBiDi *pLineBiDi, jpayne@69: UErrorCode *pErrorCode); jpayne@69: jpayne@69: /** jpayne@69: * Get the directionality of the text. jpayne@69: * jpayne@69: * @param pBiDi is the paragraph or line UBiDi object. jpayne@69: * jpayne@69: * @return a value of UBIDI_LTR, UBIDI_RTL jpayne@69: * or UBIDI_MIXED jpayne@69: * that indicates if the entire text jpayne@69: * represented by this object is unidirectional, jpayne@69: * and which direction, or if it is mixed-directional. jpayne@69: * Note - The value UBIDI_NEUTRAL is never returned from this method. jpayne@69: * jpayne@69: * @see UBiDiDirection jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE UBiDiDirection U_EXPORT2 jpayne@69: ubidi_getDirection(const UBiDi *pBiDi); jpayne@69: jpayne@69: /** jpayne@69: * Gets the base direction of the text provided according jpayne@69: * to the Unicode Bidirectional Algorithm. The base direction jpayne@69: * is derived from the first character in the string with bidirectional jpayne@69: * character type L, R, or AL. If the first such character has type L, jpayne@69: * UBIDI_LTR is returned. If the first such character has jpayne@69: * type R or AL, UBIDI_RTL is returned. If the string does jpayne@69: * not contain any character of these types, then jpayne@69: * UBIDI_NEUTRAL is returned. jpayne@69: * jpayne@69: * This is a lightweight function for use when only the base direction jpayne@69: * is needed and no further bidi processing of the text is needed. jpayne@69: * jpayne@69: * @param text is a pointer to the text whose base jpayne@69: * direction is needed. jpayne@69: * Note: the text must be (at least) @c length long. jpayne@69: * jpayne@69: * @param length is the length of the text; jpayne@69: * if length==-1 then the text jpayne@69: * must be zero-terminated. jpayne@69: * jpayne@69: * @return UBIDI_LTR, UBIDI_RTL, jpayne@69: * UBIDI_NEUTRAL jpayne@69: * jpayne@69: * @see UBiDiDirection jpayne@69: * @stable ICU 4.6 jpayne@69: */ jpayne@69: U_STABLE UBiDiDirection U_EXPORT2 jpayne@69: ubidi_getBaseDirection(const UChar *text, int32_t length ); jpayne@69: jpayne@69: /** jpayne@69: * Get the pointer to the text. jpayne@69: * jpayne@69: * @param pBiDi is the paragraph or line UBiDi object. jpayne@69: * jpayne@69: * @return The pointer to the text that the UBiDi object was created for. jpayne@69: * jpayne@69: * @see ubidi_setPara jpayne@69: * @see ubidi_setLine jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE const UChar * U_EXPORT2 jpayne@69: ubidi_getText(const UBiDi *pBiDi); jpayne@69: jpayne@69: /** jpayne@69: * Get the length of the text. jpayne@69: * jpayne@69: * @param pBiDi is the paragraph or line UBiDi object. jpayne@69: * jpayne@69: * @return The length of the text that the UBiDi object was created for. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: ubidi_getLength(const UBiDi *pBiDi); jpayne@69: jpayne@69: /** jpayne@69: * Get the paragraph level of the text. jpayne@69: * jpayne@69: * @param pBiDi is the paragraph or line UBiDi object. jpayne@69: * jpayne@69: * @return The paragraph level. If there are multiple paragraphs, their jpayne@69: * level may vary if the required paraLevel is UBIDI_DEFAULT_LTR or jpayne@69: * UBIDI_DEFAULT_RTL. In that case, the level of the first paragraph jpayne@69: * is returned. jpayne@69: * jpayne@69: * @see UBiDiLevel jpayne@69: * @see ubidi_getParagraph jpayne@69: * @see ubidi_getParagraphByIndex jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE UBiDiLevel U_EXPORT2 jpayne@69: ubidi_getParaLevel(const UBiDi *pBiDi); jpayne@69: jpayne@69: /** jpayne@69: * Get the number of paragraphs. jpayne@69: * jpayne@69: * @param pBiDi is the paragraph or line UBiDi object. jpayne@69: * jpayne@69: * @return The number of paragraphs. jpayne@69: * @stable ICU 3.4 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: ubidi_countParagraphs(UBiDi *pBiDi); jpayne@69: jpayne@69: /** jpayne@69: * Get a paragraph, given a position within the text. jpayne@69: * This function returns information about a paragraph. jpayne@69: * Note: if the paragraph index is known, it is more efficient to jpayne@69: * retrieve the paragraph information using ubidi_getParagraphByIndex().

jpayne@69: * jpayne@69: * @param pBiDi is the paragraph or line UBiDi object. jpayne@69: * jpayne@69: * @param charIndex is the index of a character within the text, in the jpayne@69: * range [0..ubidi_getProcessedLength(pBiDi)-1]. jpayne@69: * jpayne@69: * @param pParaStart will receive the index of the first character of the jpayne@69: * paragraph in the text. jpayne@69: * This pointer can be NULL if this jpayne@69: * value is not necessary. jpayne@69: * jpayne@69: * @param pParaLimit will receive the limit of the paragraph. jpayne@69: * The l-value that you point to here may be the jpayne@69: * same expression (variable) as the one for jpayne@69: * charIndex. jpayne@69: * This pointer can be NULL if this jpayne@69: * value is not necessary. jpayne@69: * jpayne@69: * @param pParaLevel will receive the level of the paragraph. jpayne@69: * This pointer can be NULL if this jpayne@69: * value is not necessary. jpayne@69: * jpayne@69: * @param pErrorCode must be a valid pointer to an error code value. jpayne@69: * jpayne@69: * @return The index of the paragraph containing the specified position. jpayne@69: * jpayne@69: * @see ubidi_getProcessedLength jpayne@69: * @stable ICU 3.4 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: ubidi_getParagraph(const UBiDi *pBiDi, int32_t charIndex, int32_t *pParaStart, jpayne@69: int32_t *pParaLimit, UBiDiLevel *pParaLevel, jpayne@69: UErrorCode *pErrorCode); jpayne@69: jpayne@69: /** jpayne@69: * Get a paragraph, given the index of this paragraph. jpayne@69: * jpayne@69: * This function returns information about a paragraph.

jpayne@69: * jpayne@69: * @param pBiDi is the paragraph UBiDi object. jpayne@69: * jpayne@69: * @param paraIndex is the number of the paragraph, in the jpayne@69: * range [0..ubidi_countParagraphs(pBiDi)-1]. jpayne@69: * jpayne@69: * @param pParaStart will receive the index of the first character of the jpayne@69: * paragraph in the text. jpayne@69: * This pointer can be NULL if this jpayne@69: * value is not necessary. jpayne@69: * jpayne@69: * @param pParaLimit will receive the limit of the paragraph. jpayne@69: * This pointer can be NULL if this jpayne@69: * value is not necessary. jpayne@69: * jpayne@69: * @param pParaLevel will receive the level of the paragraph. jpayne@69: * This pointer can be NULL if this jpayne@69: * value is not necessary. jpayne@69: * jpayne@69: * @param pErrorCode must be a valid pointer to an error code value. jpayne@69: * jpayne@69: * @stable ICU 3.4 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ubidi_getParagraphByIndex(const UBiDi *pBiDi, int32_t paraIndex, jpayne@69: int32_t *pParaStart, int32_t *pParaLimit, jpayne@69: UBiDiLevel *pParaLevel, UErrorCode *pErrorCode); jpayne@69: jpayne@69: /** jpayne@69: * Get the level for one character. jpayne@69: * jpayne@69: * @param pBiDi is the paragraph or line UBiDi object. jpayne@69: * jpayne@69: * @param charIndex the index of a character. It must be in the range jpayne@69: * [0..ubidi_getProcessedLength(pBiDi)]. jpayne@69: * jpayne@69: * @return The level for the character at charIndex (0 if charIndex is not jpayne@69: * in the valid range). jpayne@69: * jpayne@69: * @see UBiDiLevel jpayne@69: * @see ubidi_getProcessedLength jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE UBiDiLevel U_EXPORT2 jpayne@69: ubidi_getLevelAt(const UBiDi *pBiDi, int32_t charIndex); jpayne@69: jpayne@69: /** jpayne@69: * Get an array of levels for each character.

jpayne@69: * jpayne@69: * Note that this function may allocate memory under some jpayne@69: * circumstances, unlike ubidi_getLevelAt(). jpayne@69: * jpayne@69: * @param pBiDi is the paragraph or line UBiDi object, whose jpayne@69: * text length must be strictly positive. jpayne@69: * jpayne@69: * @param pErrorCode must be a valid pointer to an error code value. jpayne@69: * jpayne@69: * @return The levels array for the text, jpayne@69: * or NULL if an error occurs. jpayne@69: * jpayne@69: * @see UBiDiLevel jpayne@69: * @see ubidi_getProcessedLength jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE const UBiDiLevel * U_EXPORT2 jpayne@69: ubidi_getLevels(UBiDi *pBiDi, UErrorCode *pErrorCode); jpayne@69: jpayne@69: /** jpayne@69: * Get a logical run. jpayne@69: * This function returns information about a run and is used jpayne@69: * to retrieve runs in logical order.

jpayne@69: * This is especially useful for line-breaking on a paragraph. jpayne@69: * jpayne@69: * @param pBiDi is the paragraph or line UBiDi object. jpayne@69: * jpayne@69: * @param logicalPosition is a logical position within the source text. jpayne@69: * jpayne@69: * @param pLogicalLimit will receive the limit of the corresponding run. jpayne@69: * The l-value that you point to here may be the jpayne@69: * same expression (variable) as the one for jpayne@69: * logicalPosition. jpayne@69: * This pointer can be NULL if this jpayne@69: * value is not necessary. jpayne@69: * jpayne@69: * @param pLevel will receive the level of the corresponding run. jpayne@69: * This pointer can be NULL if this jpayne@69: * value is not necessary. jpayne@69: * jpayne@69: * @see ubidi_getProcessedLength jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ubidi_getLogicalRun(const UBiDi *pBiDi, int32_t logicalPosition, jpayne@69: int32_t *pLogicalLimit, UBiDiLevel *pLevel); jpayne@69: jpayne@69: /** jpayne@69: * Get the number of runs. jpayne@69: * This function may invoke the actual reordering on the jpayne@69: * UBiDi object, after ubidi_setPara() jpayne@69: * may have resolved only the levels of the text. Therefore, jpayne@69: * ubidi_countRuns() may have to allocate memory, jpayne@69: * and may fail doing so. jpayne@69: * jpayne@69: * @param pBiDi is the paragraph or line UBiDi object. jpayne@69: * jpayne@69: * @param pErrorCode must be a valid pointer to an error code value. jpayne@69: * jpayne@69: * @return The number of runs. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: ubidi_countRuns(UBiDi *pBiDi, UErrorCode *pErrorCode); jpayne@69: jpayne@69: /** jpayne@69: * Get one run's logical start, length, and directionality, jpayne@69: * which can be 0 for LTR or 1 for RTL. jpayne@69: * In an RTL run, the character at the logical start is jpayne@69: * visually on the right of the displayed run. jpayne@69: * The length is the number of characters in the run.

jpayne@69: * ubidi_countRuns() should be called jpayne@69: * before the runs are retrieved. jpayne@69: * jpayne@69: * @param pBiDi is the paragraph or line UBiDi object. jpayne@69: * jpayne@69: * @param runIndex is the number of the run in visual order, in the jpayne@69: * range [0..ubidi_countRuns(pBiDi)-1]. jpayne@69: * jpayne@69: * @param pLogicalStart is the first logical character index in the text. jpayne@69: * The pointer may be NULL if this index is not needed. jpayne@69: * jpayne@69: * @param pLength is the number of characters (at least one) in the run. jpayne@69: * The pointer may be NULL if this is not needed. jpayne@69: * jpayne@69: * @return the directionality of the run, jpayne@69: * UBIDI_LTR==0 or UBIDI_RTL==1, jpayne@69: * never UBIDI_MIXED, jpayne@69: * never UBIDI_NEUTRAL. jpayne@69: * jpayne@69: * @see ubidi_countRuns jpayne@69: * jpayne@69: * Example: jpayne@69: *

jpayne@69:  * \code
jpayne@69:  * int32_t i, count=ubidi_countRuns(pBiDi),
jpayne@69:  *         logicalStart, visualIndex=0, length;
jpayne@69:  * for(i=0; i0);
jpayne@69:  *     } else {
jpayne@69:  *         logicalStart+=length;  // logicalLimit
jpayne@69:  *         do { // RTL
jpayne@69:  *             show_char(text[--logicalStart], visualIndex++);
jpayne@69:  *         } while(--length>0);
jpayne@69:  *     }
jpayne@69:  * }
jpayne@69:  *\endcode
jpayne@69:  *


jpayne@69:  *
jpayne@69:  * Note that in right-to-left runs, code like this places
jpayne@69:  * second surrogates before first ones (which is generally a bad idea)
jpayne@69:  * and combining characters before base characters.
jpayne@69:  * 
jpayne@69:  * Use of ubidi_writeReordered(), optionally with the
jpayne@69:  * #UBIDI_KEEP_BASE_COMBINING option, can be considered in order
jpayne@69:  * to avoid these issues.
jpayne@69:  * @stable ICU 2.0
jpayne@69:  */
jpayne@69: U_STABLE UBiDiDirection U_EXPORT2
jpayne@69: ubidi_getVisualRun(UBiDi *pBiDi, int32_t runIndex,
jpayne@69:                    int32_t *pLogicalStart, int32_t *pLength);
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Get the visual position from a logical text position.
jpayne@69:  * If such a mapping is used many times on the same
jpayne@69:  * UBiDi object, then calling
jpayne@69:  * ubidi_getLogicalMap() is more efficient.

jpayne@69:  *
jpayne@69:  * The value returned may be #UBIDI_MAP_NOWHERE if there is no
jpayne@69:  * visual position because the corresponding text character is a Bidi control
jpayne@69:  * removed from output by the option #UBIDI_OPTION_REMOVE_CONTROLS.
jpayne@69:  * 

jpayne@69:  * When the visual output is altered by using options of
jpayne@69:  * ubidi_writeReordered() such as UBIDI_INSERT_LRM_FOR_NUMERIC,
jpayne@69:  * UBIDI_KEEP_BASE_COMBINING, UBIDI_OUTPUT_REVERSE,
jpayne@69:  * UBIDI_REMOVE_BIDI_CONTROLS, the visual position returned may not
jpayne@69:  * be correct. It is advised to use, when possible, reordering options
jpayne@69:  * such as UBIDI_OPTION_INSERT_MARKS and UBIDI_OPTION_REMOVE_CONTROLS.
jpayne@69:  * 

jpayne@69:  * Note that in right-to-left runs, this mapping places
jpayne@69:  * second surrogates before first ones (which is generally a bad idea)
jpayne@69:  * and combining characters before base characters.
jpayne@69:  * Use of ubidi_writeReordered(), optionally with the
jpayne@69:  * #UBIDI_KEEP_BASE_COMBINING option can be considered instead
jpayne@69:  * of using the mapping, in order to avoid these issues.
jpayne@69:  *
jpayne@69:  * @param pBiDi is the paragraph or line UBiDi object.
jpayne@69:  *
jpayne@69:  * @param logicalIndex is the index of a character in the text.
jpayne@69:  *
jpayne@69:  * @param pErrorCode must be a valid pointer to an error code value.
jpayne@69:  *
jpayne@69:  * @return The visual position of this character.
jpayne@69:  *
jpayne@69:  * @see ubidi_getLogicalMap
jpayne@69:  * @see ubidi_getLogicalIndex
jpayne@69:  * @see ubidi_getProcessedLength
jpayne@69:  * @stable ICU 2.0
jpayne@69:  */
jpayne@69: U_STABLE int32_t U_EXPORT2
jpayne@69: ubidi_getVisualIndex(UBiDi *pBiDi, int32_t logicalIndex, UErrorCode *pErrorCode);
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Get the logical text position from a visual position.
jpayne@69:  * If such a mapping is used many times on the same
jpayne@69:  * UBiDi object, then calling
jpayne@69:  * ubidi_getVisualMap() is more efficient.

jpayne@69:  *
jpayne@69:  * The value returned may be #UBIDI_MAP_NOWHERE if there is no
jpayne@69:  * logical position because the corresponding text character is a Bidi mark
jpayne@69:  * inserted in the output by option #UBIDI_OPTION_INSERT_MARKS.
jpayne@69:  * 

jpayne@69:  * This is the inverse function to ubidi_getVisualIndex().
jpayne@69:  * 

jpayne@69:  * When the visual output is altered by using options of
jpayne@69:  * ubidi_writeReordered() such as UBIDI_INSERT_LRM_FOR_NUMERIC,
jpayne@69:  * UBIDI_KEEP_BASE_COMBINING, UBIDI_OUTPUT_REVERSE,
jpayne@69:  * UBIDI_REMOVE_BIDI_CONTROLS, the logical position returned may not
jpayne@69:  * be correct. It is advised to use, when possible, reordering options
jpayne@69:  * such as UBIDI_OPTION_INSERT_MARKS and UBIDI_OPTION_REMOVE_CONTROLS.
jpayne@69:  *
jpayne@69:  * @param pBiDi is the paragraph or line UBiDi object.
jpayne@69:  *
jpayne@69:  * @param visualIndex is the visual position of a character.
jpayne@69:  *
jpayne@69:  * @param pErrorCode must be a valid pointer to an error code value.
jpayne@69:  *
jpayne@69:  * @return The index of this character in the text.
jpayne@69:  *
jpayne@69:  * @see ubidi_getVisualMap
jpayne@69:  * @see ubidi_getVisualIndex
jpayne@69:  * @see ubidi_getResultLength
jpayne@69:  * @stable ICU 2.0
jpayne@69:  */
jpayne@69: U_STABLE int32_t U_EXPORT2
jpayne@69: ubidi_getLogicalIndex(UBiDi *pBiDi, int32_t visualIndex, UErrorCode *pErrorCode);
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Get a logical-to-visual index map (array) for the characters in the UBiDi
jpayne@69:  * (paragraph or line) object.
jpayne@69:  * 

jpayne@69:  * Some values in the map may be #UBIDI_MAP_NOWHERE if the
jpayne@69:  * corresponding text characters are Bidi controls removed from the visual
jpayne@69:  * output by the option #UBIDI_OPTION_REMOVE_CONTROLS.
jpayne@69:  * 

jpayne@69:  * When the visual output is altered by using options of
jpayne@69:  * ubidi_writeReordered() such as UBIDI_INSERT_LRM_FOR_NUMERIC,
jpayne@69:  * UBIDI_KEEP_BASE_COMBINING, UBIDI_OUTPUT_REVERSE,
jpayne@69:  * UBIDI_REMOVE_BIDI_CONTROLS, the visual positions returned may not
jpayne@69:  * be correct. It is advised to use, when possible, reordering options
jpayne@69:  * such as UBIDI_OPTION_INSERT_MARKS and UBIDI_OPTION_REMOVE_CONTROLS.
jpayne@69:  * 

jpayne@69:  * Note that in right-to-left runs, this mapping places
jpayne@69:  * second surrogates before first ones (which is generally a bad idea)
jpayne@69:  * and combining characters before base characters.
jpayne@69:  * Use of ubidi_writeReordered(), optionally with the
jpayne@69:  * #UBIDI_KEEP_BASE_COMBINING option can be considered instead
jpayne@69:  * of using the mapping, in order to avoid these issues.
jpayne@69:  *
jpayne@69:  * @param pBiDi is the paragraph or line UBiDi object.
jpayne@69:  *
jpayne@69:  * @param indexMap is a pointer to an array of ubidi_getProcessedLength()
jpayne@69:  *        indexes which will reflect the reordering of the characters.
jpayne@69:  *        If option #UBIDI_OPTION_INSERT_MARKS is set, the number
jpayne@69:  *        of elements allocated in indexMap must be no less than
jpayne@69:  *        ubidi_getResultLength().
jpayne@69:  *        The array does not need to be initialized.


jpayne@69:  *        The index map will result in indexMap[logicalIndex]==visualIndex.
jpayne@69:  *
jpayne@69:  * @param pErrorCode must be a valid pointer to an error code value.
jpayne@69:  *
jpayne@69:  * @see ubidi_getVisualMap
jpayne@69:  * @see ubidi_getVisualIndex
jpayne@69:  * @see ubidi_getProcessedLength
jpayne@69:  * @see ubidi_getResultLength
jpayne@69:  * @stable ICU 2.0
jpayne@69:  */
jpayne@69: U_STABLE void U_EXPORT2
jpayne@69: ubidi_getLogicalMap(UBiDi *pBiDi, int32_t *indexMap, UErrorCode *pErrorCode);
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Get a visual-to-logical index map (array) for the characters in the UBiDi
jpayne@69:  * (paragraph or line) object.
jpayne@69:  * 

jpayne@69:  * Some values in the map may be #UBIDI_MAP_NOWHERE if the
jpayne@69:  * corresponding text characters are Bidi marks inserted in the visual output
jpayne@69:  * by the option #UBIDI_OPTION_INSERT_MARKS.
jpayne@69:  * 

jpayne@69:  * When the visual output is altered by using options of
jpayne@69:  * ubidi_writeReordered() such as UBIDI_INSERT_LRM_FOR_NUMERIC,
jpayne@69:  * UBIDI_KEEP_BASE_COMBINING, UBIDI_OUTPUT_REVERSE,
jpayne@69:  * UBIDI_REMOVE_BIDI_CONTROLS, the logical positions returned may not
jpayne@69:  * be correct. It is advised to use, when possible, reordering options
jpayne@69:  * such as UBIDI_OPTION_INSERT_MARKS and UBIDI_OPTION_REMOVE_CONTROLS.
jpayne@69:  *
jpayne@69:  * @param pBiDi is the paragraph or line UBiDi object.
jpayne@69:  *
jpayne@69:  * @param indexMap is a pointer to an array of ubidi_getResultLength()
jpayne@69:  *        indexes which will reflect the reordering of the characters.
jpayne@69:  *        If option #UBIDI_OPTION_REMOVE_CONTROLS is set, the number
jpayne@69:  *        of elements allocated in indexMap must be no less than
jpayne@69:  *        ubidi_getProcessedLength().
jpayne@69:  *        The array does not need to be initialized.


jpayne@69:  *        The index map will result in indexMap[visualIndex]==logicalIndex.
jpayne@69:  *
jpayne@69:  * @param pErrorCode must be a valid pointer to an error code value.
jpayne@69:  *
jpayne@69:  * @see ubidi_getLogicalMap
jpayne@69:  * @see ubidi_getLogicalIndex
jpayne@69:  * @see ubidi_getProcessedLength
jpayne@69:  * @see ubidi_getResultLength
jpayne@69:  * @stable ICU 2.0
jpayne@69:  */
jpayne@69: U_STABLE void U_EXPORT2
jpayne@69: ubidi_getVisualMap(UBiDi *pBiDi, int32_t *indexMap, UErrorCode *pErrorCode);
jpayne@69: 
jpayne@69: /**
jpayne@69:  * This is a convenience function that does not use a UBiDi object.
jpayne@69:  * It is intended to be used for when an application has determined the levels
jpayne@69:  * of objects (character sequences) and just needs to have them reordered (L2).
jpayne@69:  * This is equivalent to using ubidi_getLogicalMap() on a
jpayne@69:  * UBiDi object.
jpayne@69:  *
jpayne@69:  * @param levels is an array with length levels that have been determined by
jpayne@69:  *        the application.
jpayne@69:  *
jpayne@69:  * @param length is the number of levels in the array, or, semantically,
jpayne@69:  *        the number of objects to be reordered.
jpayne@69:  *        It must be length>0.
jpayne@69:  *
jpayne@69:  * @param indexMap is a pointer to an array of length
jpayne@69:  *        indexes which will reflect the reordering of the characters.
jpayne@69:  *        The array does not need to be initialized.

jpayne@69:  *        The index map will result in indexMap[logicalIndex]==visualIndex.
jpayne@69:  * @stable ICU 2.0
jpayne@69:  */
jpayne@69: U_STABLE void U_EXPORT2
jpayne@69: ubidi_reorderLogical(const UBiDiLevel *levels, int32_t length, int32_t *indexMap);
jpayne@69: 
jpayne@69: /**
jpayne@69:  * This is a convenience function that does not use a UBiDi object.
jpayne@69:  * It is intended to be used for when an application has determined the levels
jpayne@69:  * of objects (character sequences) and just needs to have them reordered (L2).
jpayne@69:  * This is equivalent to using ubidi_getVisualMap() on a
jpayne@69:  * UBiDi object.
jpayne@69:  *
jpayne@69:  * @param levels is an array with length levels that have been determined by
jpayne@69:  *        the application.
jpayne@69:  *
jpayne@69:  * @param length is the number of levels in the array, or, semantically,
jpayne@69:  *        the number of objects to be reordered.
jpayne@69:  *        It must be length>0.
jpayne@69:  *
jpayne@69:  * @param indexMap is a pointer to an array of length
jpayne@69:  *        indexes which will reflect the reordering of the characters.
jpayne@69:  *        The array does not need to be initialized.

jpayne@69:  *        The index map will result in indexMap[visualIndex]==logicalIndex.
jpayne@69:  * @stable ICU 2.0
jpayne@69:  */
jpayne@69: U_STABLE void U_EXPORT2
jpayne@69: ubidi_reorderVisual(const UBiDiLevel *levels, int32_t length, int32_t *indexMap);
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Invert an index map.
jpayne@69:  * The index mapping of the first map is inverted and written to
jpayne@69:  * the second one.
jpayne@69:  *
jpayne@69:  * @param srcMap is an array with length elements
jpayne@69:  *        which defines the original mapping from a source array containing
jpayne@69:  *        length elements to a destination array.
jpayne@69:  *        Some elements of the source array may have no mapping in the
jpayne@69:  *        destination array. In that case, their value will be
jpayne@69:  *        the special value UBIDI_MAP_NOWHERE.
jpayne@69:  *        All elements must be >=0 or equal to UBIDI_MAP_NOWHERE.
jpayne@69:  *        Some elements may have a value >= length, if the
jpayne@69:  *        destination array has more elements than the source array.
jpayne@69:  *        There must be no duplicate indexes (two or more elements with the
jpayne@69:  *        same value except UBIDI_MAP_NOWHERE).
jpayne@69:  *
jpayne@69:  * @param destMap is an array with a number of elements equal to 1 + the highest
jpayne@69:  *        value in srcMap.
jpayne@69:  *        destMap will be filled with the inverse mapping.
jpayne@69:  *        If element with index i in srcMap has a value k different
jpayne@69:  *        from UBIDI_MAP_NOWHERE, this means that element i of
jpayne@69:  *        the source array maps to element k in the destination array.
jpayne@69:  *        The inverse map will have value i in its k-th element.
jpayne@69:  *        For all elements of the destination array which do not map to
jpayne@69:  *        an element in the source array, the corresponding element in the
jpayne@69:  *        inverse map will have a value equal to UBIDI_MAP_NOWHERE.
jpayne@69:  *
jpayne@69:  * @param length is the length of each array.
jpayne@69:  * @see UBIDI_MAP_NOWHERE
jpayne@69:  * @stable ICU 2.0
jpayne@69:  */
jpayne@69: U_STABLE void U_EXPORT2
jpayne@69: ubidi_invertMap(const int32_t *srcMap, int32_t *destMap, int32_t length);
jpayne@69: 
jpayne@69: /** option flags for ubidi_writeReordered() */
jpayne@69: 
jpayne@69: /**
jpayne@69:  * option bit for ubidi_writeReordered():
jpayne@69:  * keep combining characters after their base characters in RTL runs
jpayne@69:  *
jpayne@69:  * @see ubidi_writeReordered
jpayne@69:  * @stable ICU 2.0
jpayne@69:  */
jpayne@69: #define UBIDI_KEEP_BASE_COMBINING       1
jpayne@69: 
jpayne@69: /**
jpayne@69:  * option bit for ubidi_writeReordered():
jpayne@69:  * replace characters with the "mirrored" property in RTL runs
jpayne@69:  * by their mirror-image mappings
jpayne@69:  *
jpayne@69:  * @see ubidi_writeReordered
jpayne@69:  * @stable ICU 2.0
jpayne@69:  */
jpayne@69: #define UBIDI_DO_MIRRORING              2
jpayne@69: 
jpayne@69: /**
jpayne@69:  * option bit for ubidi_writeReordered():
jpayne@69:  * surround the run with LRMs if necessary;
jpayne@69:  * this is part of the approximate "inverse Bidi" algorithm
jpayne@69:  *
jpayne@69:  * 
This option does not imply corresponding adjustment of the index
jpayne@69:  * mappings.
jpayne@69:  *
jpayne@69:  * @see ubidi_setInverse
jpayne@69:  * @see ubidi_writeReordered
jpayne@69:  * @stable ICU 2.0
jpayne@69:  */
jpayne@69: #define UBIDI_INSERT_LRM_FOR_NUMERIC    4
jpayne@69: 
jpayne@69: /**
jpayne@69:  * option bit for ubidi_writeReordered():
jpayne@69:  * remove Bidi control characters
jpayne@69:  * (this does not affect #UBIDI_INSERT_LRM_FOR_NUMERIC)
jpayne@69:  *
jpayne@69:  * This option does not imply corresponding adjustment of the index
jpayne@69:  * mappings.
jpayne@69:  *
jpayne@69:  * @see ubidi_writeReordered
jpayne@69:  * @stable ICU 2.0
jpayne@69:  */
jpayne@69: #define UBIDI_REMOVE_BIDI_CONTROLS      8
jpayne@69: 
jpayne@69: /**
jpayne@69:  * option bit for ubidi_writeReordered():
jpayne@69:  * write the output in reverse order
jpayne@69:  *
jpayne@69:  * This has the same effect as calling ubidi_writeReordered()
jpayne@69:  * first without this option, and then calling
jpayne@69:  * ubidi_writeReverse() without mirroring.
jpayne@69:  * Doing this in the same step is faster and avoids a temporary buffer.
jpayne@69:  * An example for using this option is output to a character terminal that
jpayne@69:  * is designed for RTL scripts and stores text in reverse order.
jpayne@69:  *
jpayne@69:  * @see ubidi_writeReordered
jpayne@69:  * @stable ICU 2.0
jpayne@69:  */
jpayne@69: #define UBIDI_OUTPUT_REVERSE            16
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Get the length of the source text processed by the last call to
jpayne@69:  * ubidi_setPara(). This length may be different from the length
jpayne@69:  * of the source text if option #UBIDI_OPTION_STREAMING
jpayne@69:  * has been set.
jpayne@69:  * 

jpayne@69:  * Note that whenever the length of the text affects the execution or the
jpayne@69:  * result of a function, it is the processed length which must be considered,
jpayne@69:  * except for ubidi_setPara (which receives unprocessed source
jpayne@69:  * text) and ubidi_getLength (which returns the original length
jpayne@69:  * of the source text).

jpayne@69:  * In particular, the processed length is the one to consider in the following
jpayne@69:  * cases:
jpayne@69:  * 
jpayne@69:  * maximum value of the limit argument of
jpayne@69:  * ubidi_setLine
jpayne@69:  * maximum value of the charIndex argument of
jpayne@69:  * ubidi_getParagraph
jpayne@69:  * maximum value of the charIndex argument of
jpayne@69:  * ubidi_getLevelAt
jpayne@69:  * number of elements in the array returned by ubidi_getLevels
jpayne@69:  * maximum value of the logicalStart argument of
jpayne@69:  * ubidi_getLogicalRun
jpayne@69:  * maximum value of the logicalIndex argument of
jpayne@69:  * ubidi_getVisualIndex
jpayne@69:  * number of elements filled in the *indexMap argument of
jpayne@69:  * ubidi_getLogicalMap
jpayne@69:  * length of text processed by ubidi_writeReordered
jpayne@69:  * 
jpayne@69:  *
jpayne@69:  * @param pBiDi is the paragraph UBiDi object.
jpayne@69:  *
jpayne@69:  * @return The length of the part of the source text processed by
jpayne@69:  *         the last call to ubidi_setPara.
jpayne@69:  * @see ubidi_setPara
jpayne@69:  * @see UBIDI_OPTION_STREAMING
jpayne@69:  * @stable ICU 3.6
jpayne@69:  */
jpayne@69: U_STABLE int32_t U_EXPORT2
jpayne@69: ubidi_getProcessedLength(const UBiDi *pBiDi);
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Get the length of the reordered text resulting from the last call to
jpayne@69:  * ubidi_setPara(). This length may be different from the length
jpayne@69:  * of the source text if option #UBIDI_OPTION_INSERT_MARKS
jpayne@69:  * or option #UBIDI_OPTION_REMOVE_CONTROLS has been set.
jpayne@69:  * 

jpayne@69:  * This resulting length is the one to consider in the following cases:
jpayne@69:  * 
jpayne@69:  * maximum value of the visualIndex argument of
jpayne@69:  * ubidi_getLogicalIndex
jpayne@69:  * number of elements of the *indexMap argument of
jpayne@69:  * ubidi_getVisualMap
jpayne@69:  * 
jpayne@69:  * Note that this length stays identical to the source text length if
jpayne@69:  * Bidi marks are inserted or removed using option bits of
jpayne@69:  * ubidi_writeReordered, or if option
jpayne@69:  * #UBIDI_REORDER_INVERSE_NUMBERS_AS_L has been set.
jpayne@69:  *
jpayne@69:  * @param pBiDi is the paragraph UBiDi object.
jpayne@69:  *
jpayne@69:  * @return The length of the reordered text resulting from
jpayne@69:  *         the last call to ubidi_setPara.
jpayne@69:  * @see ubidi_setPara
jpayne@69:  * @see UBIDI_OPTION_INSERT_MARKS
jpayne@69:  * @see UBIDI_OPTION_REMOVE_CONTROLS
jpayne@69:  * @stable ICU 3.6
jpayne@69:  */
jpayne@69: U_STABLE int32_t U_EXPORT2
jpayne@69: ubidi_getResultLength(const UBiDi *pBiDi);
jpayne@69: 
jpayne@69: U_CDECL_BEGIN
jpayne@69: 
jpayne@69: #ifndef U_HIDE_DEPRECATED_API
jpayne@69: /**
jpayne@69:  * Value returned by UBiDiClassCallback callbacks when
jpayne@69:  * there is no need to override the standard Bidi class for a given code point.
jpayne@69:  *
jpayne@69:  * This constant is deprecated; use u_getIntPropertyMaxValue(UCHAR_BIDI_CLASS)+1 instead.
jpayne@69:  *
jpayne@69:  * @see UBiDiClassCallback
jpayne@69:  * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
jpayne@69:  */
jpayne@69: #define U_BIDI_CLASS_DEFAULT  U_CHAR_DIRECTION_COUNT
jpayne@69: #endif  // U_HIDE_DEPRECATED_API
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Callback type declaration for overriding default Bidi class values with
jpayne@69:  * custom ones.
jpayne@69:  * Usually, the function pointer will be propagated to a UBiDi
jpayne@69:  * object by calling the ubidi_setClassCallback() function;
jpayne@69:  * then the callback will be invoked by the UBA implementation any time the
jpayne@69:  * class of a character is to be determined.
jpayne@69:  *
jpayne@69:  * @param context is a pointer to the callback private data.
jpayne@69:  *
jpayne@69:  * @param c       is the code point to get a Bidi class for.
jpayne@69:  *
jpayne@69:  * @return The directional property / Bidi class for the given code point
jpayne@69:  *         c if the default class has been overridden, or
jpayne@69:  *         u_getIntPropertyMaxValue(UCHAR_BIDI_CLASS)+1
jpayne@69:  *         if the standard Bidi class value for c is to be used.
jpayne@69:  * @see ubidi_setClassCallback
jpayne@69:  * @see ubidi_getClassCallback
jpayne@69:  * @stable ICU 3.6
jpayne@69:  */
jpayne@69: typedef UCharDirection U_CALLCONV
jpayne@69: UBiDiClassCallback(const void *context, UChar32 c);
jpayne@69: 
jpayne@69: U_CDECL_END
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Retrieve the Bidi class for a given code point.
jpayne@69:  * If a #UBiDiClassCallback callback is defined and returns a
jpayne@69:  * value other than u_getIntPropertyMaxValue(UCHAR_BIDI_CLASS)+1,
jpayne@69:  * that value is used; otherwise the default class determination mechanism is invoked.
jpayne@69:  *
jpayne@69:  * @param pBiDi is the paragraph UBiDi object.
jpayne@69:  *
jpayne@69:  * @param c     is the code point whose Bidi class must be retrieved.
jpayne@69:  *
jpayne@69:  * @return The Bidi class for character c based
jpayne@69:  *         on the given pBiDi instance.
jpayne@69:  * @see UBiDiClassCallback
jpayne@69:  * @stable ICU 3.6
jpayne@69:  */
jpayne@69: U_STABLE UCharDirection U_EXPORT2
jpayne@69: ubidi_getCustomizedClass(UBiDi *pBiDi, UChar32 c);
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Set the callback function and callback data used by the UBA
jpayne@69:  * implementation for Bidi class determination.
jpayne@69:  * This may be useful for assigning Bidi classes to PUA characters, or
jpayne@69:  * for special application needs. For instance, an application may want to
jpayne@69:  * handle all spaces like L or R characters (according to the base direction)
jpayne@69:  * when creating the visual ordering of logical lines which are part of a report
jpayne@69:  * organized in columns: there should not be interaction between adjacent
jpayne@69:  * cells.

jpayne@69:  *
jpayne@69:  * @param pBiDi is the paragraph UBiDi object.
jpayne@69:  *
jpayne@69:  * @param newFn is the new callback function pointer.
jpayne@69:  *
jpayne@69:  * @param newContext is the new callback context pointer. This can be NULL.
jpayne@69:  *
jpayne@69:  * @param oldFn fillin: Returns the old callback function pointer. This can be
jpayne@69:  *                      NULL.
jpayne@69:  *
jpayne@69:  * @param oldContext fillin: Returns the old callback's context. This can be
jpayne@69:  *                           NULL.
jpayne@69:  *
jpayne@69:  * @param pErrorCode must be a valid pointer to an error code value.
jpayne@69:  *
jpayne@69:  * @see ubidi_getClassCallback
jpayne@69:  * @stable ICU 3.6
jpayne@69:  */
jpayne@69: U_STABLE void U_EXPORT2
jpayne@69: ubidi_setClassCallback(UBiDi *pBiDi, UBiDiClassCallback *newFn,
jpayne@69:                        const void *newContext, UBiDiClassCallback **oldFn,
jpayne@69:                        const void **oldContext, UErrorCode *pErrorCode);
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Get the current callback function used for Bidi class determination.
jpayne@69:  *
jpayne@69:  * @param pBiDi is the paragraph UBiDi object.
jpayne@69:  *
jpayne@69:  * @param fn fillin: Returns the callback function pointer.
jpayne@69:  *
jpayne@69:  * @param context fillin: Returns the callback's private context.
jpayne@69:  *
jpayne@69:  * @see ubidi_setClassCallback
jpayne@69:  * @stable ICU 3.6
jpayne@69:  */
jpayne@69: U_STABLE void U_EXPORT2
jpayne@69: ubidi_getClassCallback(UBiDi *pBiDi, UBiDiClassCallback **fn, const void **context);
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Take a UBiDi object containing the reordering
jpayne@69:  * information for a piece of text (one or more paragraphs) set by
jpayne@69:  * ubidi_setPara() or for a line of text set by
jpayne@69:  * ubidi_setLine() and write a reordered string to the
jpayne@69:  * destination buffer.
jpayne@69:  *
jpayne@69:  * This function preserves the integrity of characters with multiple
jpayne@69:  * code units and (optionally) combining characters.
jpayne@69:  * Characters in RTL runs can be replaced by mirror-image characters
jpayne@69:  * in the destination buffer. Note that "real" mirroring has
jpayne@69:  * to be done in a rendering engine by glyph selection
jpayne@69:  * and that for many "mirrored" characters there are no
jpayne@69:  * Unicode characters as mirror-image equivalents.
jpayne@69:  * There are also options to insert or remove Bidi control
jpayne@69:  * characters; see the description of the destSize
jpayne@69:  * and options parameters and of the option bit flags.
jpayne@69:  *
jpayne@69:  * @param pBiDi A pointer to a UBiDi object that
jpayne@69:  *              is set by ubidi_setPara() or
jpayne@69:  *              ubidi_setLine() and contains the reordering
jpayne@69:  *              information for the text that it was defined for,
jpayne@69:  *              as well as a pointer to that text.


jpayne@69:  *              The text was aliased (only the pointer was stored
jpayne@69:  *              without copying the contents) and must not have been modified
jpayne@69:  *              since the ubidi_setPara() call.
jpayne@69:  *
jpayne@69:  * @param dest A pointer to where the reordered text is to be copied.
jpayne@69:  *             The source text and dest[destSize]
jpayne@69:  *             must not overlap.
jpayne@69:  *
jpayne@69:  * @param destSize The size of the dest buffer,
jpayne@69:  *                 in number of UChars.
jpayne@69:  *                 If the UBIDI_INSERT_LRM_FOR_NUMERIC
jpayne@69:  *                 option is set, then the destination length could be
jpayne@69:  *                 as large as
jpayne@69:  *                 ubidi_getLength(pBiDi)+2*ubidi_countRuns(pBiDi).
jpayne@69:  *                 If the UBIDI_REMOVE_BIDI_CONTROLS option
jpayne@69:  *                 is set, then the destination length may be less than
jpayne@69:  *                 ubidi_getLength(pBiDi).
jpayne@69:  *                 If none of these options is set, then the destination length
jpayne@69:  *                 will be exactly ubidi_getProcessedLength(pBiDi).
jpayne@69:  *
jpayne@69:  * @param options A bit set of options for the reordering that control
jpayne@69:  *                how the reordered text is written.
jpayne@69:  *                The options include mirroring the characters on a code
jpayne@69:  *                point basis and inserting LRM characters, which is used
jpayne@69:  *                especially for transforming visually stored text
jpayne@69:  *                to logically stored text (although this is still an
jpayne@69:  *                imperfect implementation of an "inverse Bidi" algorithm
jpayne@69:  *                because it uses the "forward Bidi" algorithm at its core).
jpayne@69:  *                The available options are:
jpayne@69:  *                #UBIDI_DO_MIRRORING,
jpayne@69:  *                #UBIDI_INSERT_LRM_FOR_NUMERIC,
jpayne@69:  *                #UBIDI_KEEP_BASE_COMBINING,
jpayne@69:  *                #UBIDI_OUTPUT_REVERSE,
jpayne@69:  *                #UBIDI_REMOVE_BIDI_CONTROLS
jpayne@69:  *
jpayne@69:  * @param pErrorCode must be a valid pointer to an error code value.
jpayne@69:  *
jpayne@69:  * @return The length of the output string.
jpayne@69:  *
jpayne@69:  * @see ubidi_getProcessedLength
jpayne@69:  * @stable ICU 2.0
jpayne@69:  */
jpayne@69: U_STABLE int32_t U_EXPORT2
jpayne@69: ubidi_writeReordered(UBiDi *pBiDi,
jpayne@69:                      UChar *dest, int32_t destSize,
jpayne@69:                      uint16_t options,
jpayne@69:                      UErrorCode *pErrorCode);
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Reverse a Right-To-Left run of Unicode text.
jpayne@69:  *
jpayne@69:  * This function preserves the integrity of characters with multiple
jpayne@69:  * code units and (optionally) combining characters.
jpayne@69:  * Characters can be replaced by mirror-image characters
jpayne@69:  * in the destination buffer. Note that "real" mirroring has
jpayne@69:  * to be done in a rendering engine by glyph selection
jpayne@69:  * and that for many "mirrored" characters there are no
jpayne@69:  * Unicode characters as mirror-image equivalents.
jpayne@69:  * There are also options to insert or remove Bidi control
jpayne@69:  * characters.
jpayne@69:  *
jpayne@69:  * This function is the implementation for reversing RTL runs as part
jpayne@69:  * of ubidi_writeReordered(). For detailed descriptions
jpayne@69:  * of the parameters, see there.
jpayne@69:  * Since no Bidi controls are inserted here, the output string length
jpayne@69:  * will never exceed srcLength.
jpayne@69:  *
jpayne@69:  * @see ubidi_writeReordered
jpayne@69:  *
jpayne@69:  * @param src A pointer to the RTL run text.
jpayne@69:  *
jpayne@69:  * @param srcLength The length of the RTL run.
jpayne@69:  *
jpayne@69:  * @param dest A pointer to where the reordered text is to be copied.
jpayne@69:  *             src[srcLength] and dest[destSize]
jpayne@69:  *             must not overlap.
jpayne@69:  *
jpayne@69:  * @param destSize The size of the dest buffer,
jpayne@69:  *                 in number of UChars.
jpayne@69:  *                 If the UBIDI_REMOVE_BIDI_CONTROLS option
jpayne@69:  *                 is set, then the destination length may be less than
jpayne@69:  *                 srcLength.
jpayne@69:  *                 If this option is not set, then the destination length
jpayne@69:  *                 will be exactly srcLength.
jpayne@69:  *
jpayne@69:  * @param options A bit set of options for the reordering that control
jpayne@69:  *                how the reordered text is written.
jpayne@69:  *                See the options parameter in ubidi_writeReordered().
jpayne@69:  *
jpayne@69:  * @param pErrorCode must be a valid pointer to an error code value.
jpayne@69:  *
jpayne@69:  * @return The length of the output string.
jpayne@69:  * @stable ICU 2.0
jpayne@69:  */
jpayne@69: U_STABLE int32_t U_EXPORT2
jpayne@69: ubidi_writeReverse(const UChar *src, int32_t srcLength,
jpayne@69:                    UChar *dest, int32_t destSize,
jpayne@69:                    uint16_t options,
jpayne@69:                    UErrorCode *pErrorCode);
jpayne@69: 
jpayne@69: /*#define BIDI_SAMPLE_CODE*/
jpayne@69: /*@}*/
jpayne@69: 
jpayne@69: #endif