sl@0: /* sl@0: ****************************************************************************** sl@0: * sl@0: * Copyright (C) 1999-2005, International Business Machines sl@0: * Corporation and others. All Rights Reserved. sl@0: * sl@0: ****************************************************************************** sl@0: * file name: ubidi.h sl@0: * encoding: US-ASCII sl@0: * tab size: 8 (not used) sl@0: * indentation:4 sl@0: * sl@0: * created on: 1999jul27 sl@0: * created by: Markus W. Scherer sl@0: */ sl@0: sl@0: #ifndef UBIDI_H sl@0: #define UBIDI_H sl@0: sl@0: #include "unicode/utypes.h" sl@0: #include "unicode/uchar.h" sl@0: sl@0: /* sl@0: * javadoc-style comments are intended to be transformed into HTML sl@0: * using DOC++ - see sl@0: * http://www.zib.de/Visual/software/doc++/index.html . sl@0: * sl@0: * The HTML documentation is created with sl@0: * doc++ -H ubidi.h sl@0: * sl@0: * The following #define trick allows us to do it all in one file sl@0: * and still be able to compile it. sl@0: */ sl@0: /*#define DOCXX_TAG*/ sl@0: /*#define BIDI_SAMPLE_CODE*/ sl@0: sl@0: /** sl@0: *\file sl@0: * \brief C API: BIDI algorithm sl@0: * sl@0: *

BIDI algorithm for ICU

sl@0: * sl@0: * This is an implementation of the Unicode Bidirectional algorithm. sl@0: * The algorithm is defined in the sl@0: * Unicode Standard Annex #9, sl@0: * version 13, also described in The Unicode Standard, Version 4.0 .

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

General remarks about the API:

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

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

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

sl@0: * sl@0: * @author Markus W. Scherer sl@0: * @version 1.0 sl@0: * sl@0: * sl@0: *

Sample code for the ICU BIDI API

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

The basic assumptions are:

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

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

sl@0: * sl@0: * @see ubidi_setPara sl@0: * sl@0: *

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

sl@0: * sl@0: * Note that the value for UBIDI_DEFAULT_LTR is even sl@0: * and the one for UBIDI_DEFAULT_RTL is odd, sl@0: * just like with normal LTR and RTL level values - sl@0: * these special values are designed that way. Also, the implementation sl@0: * assumes that UBIDI_MAX_EXPLICIT_LEVEL is odd. sl@0: * sl@0: * @see UBIDI_DEFAULT_LTR sl@0: * @see UBIDI_DEFAULT_RTL sl@0: * @see UBIDI_LEVEL_OVERRIDE sl@0: * @see UBIDI_MAX_EXPLICIT_LEVEL sl@0: * @stable ICU 2.0 sl@0: */ sl@0: typedef uint8_t UBiDiLevel; sl@0: sl@0: /** Paragraph level setting. sl@0: * If there is no strong character, then set the paragraph level to 0 (left-to-right). sl@0: * @stable ICU 2.0 sl@0: */ sl@0: #define UBIDI_DEFAULT_LTR 0xfe sl@0: sl@0: /** Paragraph level setting. sl@0: * If there is no strong character, then set the paragraph level to 1 (right-to-left). sl@0: * @stable ICU 2.0 sl@0: */ sl@0: #define UBIDI_DEFAULT_RTL 0xff sl@0: sl@0: /** sl@0: * Maximum explicit embedding level. sl@0: * (The maximum resolved level can be up to UBIDI_MAX_EXPLICIT_LEVEL+1). sl@0: * @stable ICU 2.0 sl@0: */ sl@0: #define UBIDI_MAX_EXPLICIT_LEVEL 61 sl@0: sl@0: /** Bit flag for level input. sl@0: * Overrides directional properties. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: #define UBIDI_LEVEL_OVERRIDE 0x80 sl@0: sl@0: /** sl@0: * UBiDiDirection values indicate the text direction. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: enum UBiDiDirection { sl@0: /** All left-to-right text. This is a 0 value. @stable ICU 2.0 */ sl@0: UBIDI_LTR, sl@0: /** All right-to-left text. This is a 1 value. @stable ICU 2.0 */ sl@0: UBIDI_RTL, sl@0: /** Mixed-directional text. @stable ICU 2.0 */ sl@0: UBIDI_MIXED sl@0: }; sl@0: sl@0: /** @stable ICU 2.0 */ sl@0: typedef enum UBiDiDirection UBiDiDirection; sl@0: sl@0: /** sl@0: * Forward declaration of the UBiDi structure for the declaration of sl@0: * the API functions. Its fields are implementation-specific.

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

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

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

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

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

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

sl@0: * The number of runs depends on the actual text and maybe anywhere between sl@0: * 1 and maxLength. It is typically small.

sl@0: * sl@0: * @param pErrorCode must be a valid pointer to an error code value. sl@0: * sl@0: * @return An empty UBiDi object with preallocated memory. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE UBiDi * U_EXPORT2 sl@0: ubidi_openSized(int32_t maxLength, int32_t maxRunCount, UErrorCode *pErrorCode); sl@0: sl@0: /** sl@0: * ubidi_close() must be called to free the memory sl@0: * associated with a UBiDi object.

sl@0: * sl@0: * Important: sl@0: * A parent UBiDi object must not be destroyed or reused if sl@0: * it still has children. sl@0: * If a UBiDi object is the child sl@0: * of another one (its parent), after calling sl@0: * ubidi_setLine(), then the child object must sl@0: * be destroyed (closed) or reused (by calling sl@0: * ubidi_setPara() or ubidi_setLine()) sl@0: * before the parent object. sl@0: * sl@0: * @param pBiDi is a UBiDi object. sl@0: * sl@0: * @see ubidi_setPara sl@0: * @see ubidi_setLine sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE void U_EXPORT2 sl@0: ubidi_close(UBiDi *pBiDi); sl@0: sl@0: /** sl@0: * Modify the operation of the BiDi algorithm such that it sl@0: * approximates an "inverse BiDi" algorithm. This function sl@0: * must be called before ubidi_setPara(). sl@0: * sl@0: *

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

sl@0: * sl@0: *

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

sl@0: * sl@0: *

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

sl@0: * sl@0: * @param pBiDi is a UBiDi object. sl@0: * sl@0: * @param isInverse specifies "forward" or "inverse" BiDi operation sl@0: * sl@0: * @see ubidi_setPara sl@0: * @see ubidi_writeReordered sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE void U_EXPORT2 sl@0: ubidi_setInverse(UBiDi *pBiDi, UBool isInverse); sl@0: sl@0: /** sl@0: * Is this BiDi object set to perform the inverse BiDi algorithm? sl@0: * sl@0: * @param pBiDi is a UBiDi object. sl@0: * @return TRUE if the BiDi object is set to perform the inverse BiDi algorithm sl@0: * sl@0: * @see ubidi_setInverse sl@0: * @stable ICU 2.0 sl@0: */ sl@0: sl@0: U_STABLE UBool U_EXPORT2 sl@0: ubidi_isInverse(UBiDi *pBiDi); sl@0: sl@0: /** sl@0: * Specify whether block separators must be allocated level zero, sl@0: * so that successive paragraphs will progress from left to right. sl@0: * This function must be called before ubidi_setPara(). sl@0: * Paragraph separators (B) may appear in the text. Setting them to level zero sl@0: * means that all paragraph separators (including one possibly appearing sl@0: * in the last text position) are kept in the reordered text after the text sl@0: * that they follow in the source text. sl@0: * When this feature is not enabled, a paragraph separator at the last sl@0: * position of the text before reordering will go to the first position sl@0: * of the reordered text when the paragraph level is odd. sl@0: * sl@0: * @param pBiDi is a UBiDi object. sl@0: * sl@0: * @param orderParagraphsLTR specifies whether paragraph separators (B) must sl@0: * receive level 0, so that successive paragraphs progress from left to right. sl@0: * sl@0: * @see ubidi_setPara sl@0: * @stable ICU 3.4 sl@0: */ sl@0: U_STABLE void U_EXPORT2 sl@0: ubidi_orderParagraphsLTR(UBiDi *pBiDi, UBool orderParagraphsLTR); sl@0: sl@0: /** sl@0: * Is this BiDi object set to allocate level 0 to block separators so that sl@0: * successive paragraphs progress from left to right? sl@0: * sl@0: * @param pBiDi is a UBiDi object. sl@0: * @return TRUE if the BiDi object is set to allocate level 0 to block sl@0: * separators. sl@0: * sl@0: * @see ubidi_orderParagraphsLTR sl@0: * @stable ICU 3.4 sl@0: */ sl@0: U_STABLE UBool U_EXPORT2 sl@0: ubidi_isOrderParagraphsLTR(UBiDi *pBiDi); sl@0: sl@0: /** sl@0: * Perform the Unicode BiDi algorithm. It is defined in the sl@0: * Unicode Standard Anned #9, sl@0: * version 13, sl@0: * also described in The Unicode Standard, Version 4.0 .

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

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

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

sl@0: * Except for that bit, it must be sl@0: * paraLevel<=embeddingLevels[]<=UBIDI_MAX_EXPLICIT_LEVEL, sl@0: * with one exception: a level of zero may be specified for a paragraph sl@0: * separator even if paraLevel>0 when multiple paragraphs sl@0: * are submitted in the same call to ubidi_setPara().

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

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

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

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

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

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

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

sl@0: * sl@0: * The text pointer that was stored in pParaBiDi is also copied, sl@0: * and start is added to it so that it points to the beginning of the sl@0: * line for this object. sl@0: * sl@0: * @param pParaBiDi is the parent paragraph object. It must have been set sl@0: * by a successful call to ubidi_setPara. sl@0: * sl@0: * @param start is the line's first index into the text. sl@0: * sl@0: * @param limit is just behind the line's last index into the text sl@0: * (its last index +1).
sl@0: * It must be 0<=start<=limit<=containing paragraph limit. sl@0: * If the specified line crosses a paragraph boundary, the function sl@0: * will terminate with error code U_ILLEGAL_ARGUMENT_ERROR. sl@0: * sl@0: * @param pLineBiDi is the object that will now represent a line of the text. sl@0: * sl@0: * @param pErrorCode must be a valid pointer to an error code value. sl@0: * sl@0: * @see ubidi_setPara sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE void U_EXPORT2 sl@0: ubidi_setLine(const UBiDi *pParaBiDi, sl@0: int32_t start, int32_t limit, sl@0: UBiDi *pLineBiDi, sl@0: UErrorCode *pErrorCode); sl@0: sl@0: /** sl@0: * Get the directionality of the text. sl@0: * sl@0: * @param pBiDi is the paragraph or line UBiDi object. sl@0: * sl@0: * @return A UBIDI_XXX value that indicates if the entire text sl@0: * represented by this object is unidirectional, sl@0: * and which direction, or if it is mixed-directional. sl@0: * sl@0: * @see UBiDiDirection sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE UBiDiDirection U_EXPORT2 sl@0: ubidi_getDirection(const UBiDi *pBiDi); sl@0: sl@0: /** sl@0: * Get the pointer to the text. sl@0: * sl@0: * @param pBiDi is the paragraph or line UBiDi object. sl@0: * sl@0: * @return The pointer to the text that the UBiDi object was created for. sl@0: * sl@0: * @see ubidi_setPara sl@0: * @see ubidi_setLine sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE const UChar * U_EXPORT2 sl@0: ubidi_getText(const UBiDi *pBiDi); sl@0: sl@0: /** sl@0: * Get the length of the text. sl@0: * sl@0: * @param pBiDi is the paragraph or line UBiDi object. sl@0: * sl@0: * @return The length of the text that the UBiDi object was created for. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: ubidi_getLength(const UBiDi *pBiDi); sl@0: sl@0: /** sl@0: * Get the paragraph level of the text. sl@0: * sl@0: * @param pBiDi is the paragraph or line UBiDi object. sl@0: * sl@0: * @return The paragraph level. If there are multiple paragraphs, their sl@0: * level may vary if the required paraLevel is UBIDI_DEFAULT_LTR or sl@0: * UBIDI_DEFAULT_RTL. In that case, the level of the first paragraph sl@0: * is returned. sl@0: * sl@0: * @see UBiDiLevel sl@0: * @see ubidi_getParagraph sl@0: * @see ubidi_getParagraphByIndex sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE UBiDiLevel U_EXPORT2 sl@0: ubidi_getParaLevel(const UBiDi *pBiDi); sl@0: sl@0: /** sl@0: * Get the number of paragraphs. sl@0: * sl@0: * @param pBiDi is the paragraph or line UBiDi object. sl@0: * sl@0: * @return The number of paragraphs. sl@0: * @stable ICU 3.4 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: ubidi_countParagraphs(UBiDi *pBiDi); sl@0: sl@0: /** sl@0: * Get a paragraph, given a position within the text. sl@0: * This function returns information about a paragraph.

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

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

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

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

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

sl@0:  * \code
sl@0:  * int32_t i, count=ubidi_countRuns(pBiDi),
sl@0:  *         logicalStart, visualIndex=0, length;
sl@0:  * for(i=0; i0);
sl@0:  *     } else {
sl@0:  *         logicalStart+=length;  // logicalLimit
sl@0:  *         do { // RTL
sl@0:  *             show_char(text[--logicalStart], visualIndex++);
sl@0:  *         } while(--length>0);
sl@0:  *     }
sl@0:  * }
sl@0:  *\endcode
sl@0:  *
sl@0: * sl@0: * Note that in right-to-left runs, code like this places sl@0: * modifier letters before base characters and second surrogates sl@0: * before first ones. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE UBiDiDirection U_EXPORT2 sl@0: ubidi_getVisualRun(UBiDi *pBiDi, int32_t runIndex, sl@0: int32_t *pLogicalStart, int32_t *pLength); sl@0: sl@0: /** sl@0: * Get the visual position from a logical text position. sl@0: * If such a mapping is used many times on the same sl@0: * UBiDi object, then calling sl@0: * ubidi_getLogicalMap() is more efficient.

sl@0: * sl@0: * Note that in right-to-left runs, this mapping places sl@0: * modifier letters before base characters and second surrogates sl@0: * before first ones. sl@0: * sl@0: * @param pBiDi is the paragraph or line UBiDi object. sl@0: * sl@0: * @param logicalIndex is the index of a character in the text. sl@0: * sl@0: * @param pErrorCode must be a valid pointer to an error code value. sl@0: * sl@0: * @return The visual position of this character. sl@0: * sl@0: * @see ubidi_getLogicalMap sl@0: * @see ubidi_getLogicalIndex sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: ubidi_getVisualIndex(UBiDi *pBiDi, int32_t logicalIndex, UErrorCode *pErrorCode); sl@0: sl@0: /** sl@0: * Get the logical text position from a visual position. sl@0: * If such a mapping is used many times on the same sl@0: * UBiDi object, then calling sl@0: * ubidi_getVisualMap() is more efficient.

sl@0: * sl@0: * This is the inverse function to ubidi_getVisualIndex(). sl@0: * sl@0: * @param pBiDi is the paragraph or line UBiDi object. sl@0: * sl@0: * @param visualIndex is the visual position of a character. sl@0: * sl@0: * @param pErrorCode must be a valid pointer to an error code value. sl@0: * sl@0: * @return The index of this character in the text. sl@0: * sl@0: * @see ubidi_getVisualMap sl@0: * @see ubidi_getVisualIndex sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: ubidi_getLogicalIndex(UBiDi *pBiDi, int32_t visualIndex, UErrorCode *pErrorCode); sl@0: sl@0: /** sl@0: * Get a logical-to-visual index map (array) for the characters in the UBiDi sl@0: * (paragraph or line) object. sl@0: * sl@0: * @param pBiDi is the paragraph or line UBiDi object. sl@0: * sl@0: * @param indexMap is a pointer to an array of ubidi_getLength() sl@0: * indexes which will reflect the reordering of the characters. sl@0: * The array does not need to be initialized.

sl@0: * The index map will result in indexMap[logicalIndex]==visualIndex.

sl@0: * sl@0: * @param pErrorCode must be a valid pointer to an error code value. sl@0: * sl@0: * @see ubidi_getVisualMap sl@0: * @see ubidi_getVisualIndex sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE void U_EXPORT2 sl@0: ubidi_getLogicalMap(UBiDi *pBiDi, int32_t *indexMap, UErrorCode *pErrorCode); sl@0: sl@0: /** sl@0: * Get a visual-to-logical index map (array) for the characters in the UBiDi sl@0: * (paragraph or line) object. sl@0: * sl@0: * @param pBiDi is the paragraph or line UBiDi object. sl@0: * sl@0: * @param indexMap is a pointer to an array of ubidi_getLength() sl@0: * indexes which will reflect the reordering of the characters. sl@0: * The array does not need to be initialized.

sl@0: * The index map will result in indexMap[visualIndex]==logicalIndex.

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

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

sl@0: * The index map will result in indexMap[visualIndex]==logicalIndex. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE void U_EXPORT2 sl@0: ubidi_reorderVisual(const UBiDiLevel *levels, int32_t length, int32_t *indexMap); sl@0: sl@0: /** sl@0: * Invert an index map. sl@0: * The one-to-one index mapping of the first map is inverted and written to sl@0: * the second one. sl@0: * sl@0: * @param srcMap is an array with length indexes sl@0: * which define the original mapping. sl@0: * sl@0: * @param destMap is an array with length indexes sl@0: * which will be filled with the inverse mapping. sl@0: * sl@0: * @param length is the length of each array. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE void U_EXPORT2 sl@0: ubidi_invertMap(const int32_t *srcMap, int32_t *destMap, int32_t length); sl@0: sl@0: /** option flags for ubidi_writeReordered() */ sl@0: sl@0: /** sl@0: * option bit for ubidi_writeReordered(): sl@0: * keep combining characters after their base characters in RTL runs sl@0: * sl@0: * @see ubidi_writeReordered sl@0: * @stable ICU 2.0 sl@0: */ sl@0: #define UBIDI_KEEP_BASE_COMBINING 1 sl@0: sl@0: /** sl@0: * option bit for ubidi_writeReordered(): sl@0: * replace characters with the "mirrored" property in RTL runs sl@0: * by their mirror-image mappings sl@0: * sl@0: * @see ubidi_writeReordered sl@0: * @stable ICU 2.0 sl@0: */ sl@0: #define UBIDI_DO_MIRRORING 2 sl@0: sl@0: /** sl@0: * option bit for ubidi_writeReordered(): sl@0: * surround the run with LRMs if necessary; sl@0: * this is part of the approximate "inverse BiDi" algorithm sl@0: * sl@0: * @see ubidi_setInverse sl@0: * @see ubidi_writeReordered sl@0: * @stable ICU 2.0 sl@0: */ sl@0: #define UBIDI_INSERT_LRM_FOR_NUMERIC 4 sl@0: sl@0: /** sl@0: * option bit for ubidi_writeReordered(): sl@0: * remove BiDi control characters sl@0: * (this does not affect UBIDI_INSERT_LRM_FOR_NUMERIC) sl@0: * sl@0: * @see ubidi_writeReordered sl@0: * @stable ICU 2.0 sl@0: */ sl@0: #define UBIDI_REMOVE_BIDI_CONTROLS 8 sl@0: sl@0: /** sl@0: * option bit for ubidi_writeReordered(): sl@0: * write the output in reverse order sl@0: * sl@0: *

This has the same effect as calling ubidi_writeReordered() sl@0: * first without this option, and then calling sl@0: * ubidi_writeReverse() without mirroring. sl@0: * Doing this in the same step is faster and avoids a temporary buffer. sl@0: * An example for using this option is output to a character terminal that sl@0: * is designed for RTL scripts and stores text in reverse order.

sl@0: * sl@0: * @see ubidi_writeReordered sl@0: * @stable ICU 2.0 sl@0: */ sl@0: #define UBIDI_OUTPUT_REVERSE 16 sl@0: sl@0: /** sl@0: * Take a UBiDi object containing the reordering sl@0: * information for a piece of text (one or more paragraphs) set by sl@0: * ubidi_setPara() or for a line of text set by ubidi_setLine() sl@0: * and write a reordered string to the destination buffer. sl@0: * sl@0: * This function preserves the integrity of characters with multiple sl@0: * code units and (optionally) modifier letters. sl@0: * Characters in RTL runs can be replaced by mirror-image characters sl@0: * in the destination buffer. Note that "real" mirroring has sl@0: * to be done in a rendering engine by glyph selection sl@0: * and that for many "mirrored" characters there are no sl@0: * Unicode characters as mirror-image equivalents. sl@0: * There are also options to insert or remove BiDi control sl@0: * characters; see the description of the destSize sl@0: * and options parameters and of the option bit flags. sl@0: * sl@0: * @see UBIDI_DO_MIRRORING sl@0: * @see UBIDI_INSERT_LRM_FOR_NUMERIC sl@0: * @see UBIDI_KEEP_BASE_COMBINING sl@0: * @see UBIDI_OUTPUT_REVERSE sl@0: * @see UBIDI_REMOVE_BIDI_CONTROLS sl@0: * sl@0: * @param pBiDi A pointer to a UBiDi object that sl@0: * is set by ubidi_setPara() or sl@0: * ubidi_setLine() and contains the reordering sl@0: * information for the text that it was defined for, sl@0: * as well as a pointer to that text. sl@0: *

The text was aliased (only the pointer was stored sl@0: * without copying the contents) and must not have been modified sl@0: * since the ubidi_setPara() call.

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