X-Git-Url: https://git.saurik.com/apple/icu.git/blobdiff_plain/b75a7d8f3b4adbae880cab104ce2c6a50eee4db2..fd0068a84e9996f225edba706498f6ed413d0673:/icuSources/common/unicode/ubidi.h diff --git a/icuSources/common/unicode/ubidi.h b/icuSources/common/unicode/ubidi.h index 7e29ff8e..71d181ca 100644 --- a/icuSources/common/unicode/ubidi.h +++ b/icuSources/common/unicode/ubidi.h @@ -1,7 +1,7 @@ /* ****************************************************************************** * -* Copyright (C) 1999-2001, International Business Machines +* Copyright (C) 1999-2006, International Business Machines * Corporation and others. All Rights Reserved. * ****************************************************************************** @@ -20,30 +20,16 @@ #include "unicode/utypes.h" #include "unicode/uchar.h" -/* - * javadoc-style comments are intended to be transformed into HTML - * using DOC++ - see - * http://www.zib.de/Visual/software/doc++/index.html . - * - * The HTML documentation is created with - * doc++ -H ubidi.h - * - * The following #define trick allows us to do it all in one file - * and still be able to compile it. - */ -/*#define DOCXX_TAG*/ -/*#define BIDI_SAMPLE_CODE*/ - /** *\file - * \brief C API: BIDI algorithm + * \brief C API: BIDI algorithm * *

BIDI algorithm for ICU

* * This is an implementation of the Unicode Bidirectional algorithm. * The algorithm is defined in the - * Unicode Technical Report 9, - * version 5, also described in The Unicode Standard, Version 3.0 .

+ * Unicode Standard Annex #9, + * version 13, also described in The Unicode Standard, Version 4.0 .

* * Note: Libraries that perform a bidirectional algorithm and * reorder strings accordingly are sometimes called "Storage Layout Engines". @@ -297,7 +283,7 @@ *\endcode * */ - + /*DOCXX_TAG*/ /*@{*/ @@ -316,7 +302,7 @@ * specifying the level of a character to override whatever the * BiDi implementation would resolve it to. *

  • paraLevel can be set to the - * pesudo-level values UBIDI_DEFAULT_LTR + * pseudo-level values UBIDI_DEFAULT_LTR * and UBIDI_DEFAULT_RTL.
    • * * @@ -362,22 +348,37 @@ typedef uint8_t UBiDiLevel; */ #define UBIDI_MAX_EXPLICIT_LEVEL 61 -/** Bit flag for level input. - * Overrides directional properties. +/** Bit flag for level input. + * Overrides directional properties. * @stable ICU 2.0 */ #define UBIDI_LEVEL_OVERRIDE 0x80 /** - * @memo UBiDiDirection values indicate the text direction. + * Special value which can be returned by the mapping functions when a logical + * index has no corresponding visual index or vice-versa. This may happen + * for the logical-to-visual mapping of a BiDi control when option + * #UBIDI_OPTION_REMOVE_CONTROLS is specified. This can also happen + * for the visual-to-logical mapping of a BiDi mark (LRM or RLM) inserted + * by option #UBIDI_OPTION_INSERT_MARKS. + * @see ubidi_getVisualIndex + * @see ubidi_getVisualMap + * @see ubidi_getLogicalIndex + * @see ubidi_getLogicalMap + * @draft ICU 3.6 + */ +#define UBIDI_MAP_NOWHERE (-1) + +/** + * UBiDiDirection values indicate the text direction. * @stable ICU 2.0 */ enum UBiDiDirection { - /** @memo All left-to-right text. This is a 0 value. @stable ICU 2.0 */ + /** All left-to-right text. This is a 0 value. @stable ICU 2.0 */ UBIDI_LTR, - /** @memo All right-to-left text. This is a 1 value. @stable ICU 2.0 */ + /** All right-to-left text. This is a 1 value. @stable ICU 2.0 */ UBIDI_RTL, - /** @memo Mixed-directional text. @stable ICU 2.0 */ + /** Mixed-directional text. @stable ICU 2.0 */ UBIDI_MIXED }; @@ -387,11 +388,11 @@ typedef enum UBiDiDirection UBiDiDirection; /** * Forward declaration of the UBiDi structure for the declaration of * the API functions. Its fields are implementation-specific.

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

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

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

    - * ubidi_set() will allocate additional memory for - * internal structures as necessary. + * ubidi_setPara() and ubidi_setLine() will allocate + * additional memory for internal structures as necessary. * * @return An empty UBiDi object. * @stable ICU 2.0 */ -U_CAPI UBiDi * U_EXPORT2 +U_STABLE UBiDi * U_EXPORT2 ubidi_open(void); /** @@ -432,7 +434,7 @@ ubidi_open(void); * and the internal structures that are associated with it will be allocated * on demand, just like with ubidi_open(). * - * @param maxLength is the maximum paragraph or line length that internal memory + * @param maxLength is the maximum text or line length that internal memory * will be preallocated for. An attempt to associate this object with a * longer text will fail, unless this value is 0, which leaves the allocation * up to the implementation. @@ -441,17 +443,16 @@ ubidi_open(void); * that internal memory will be preallocated for. An attempt to access * visual runs on an object that was not preallocated for as many runs * as the text was actually resolved to will fail, - * unless this value is 0, which leaves the allocation up to the implementation.

    + * unless this value is 0, which leaves the allocation up to the implementation.

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

    + * 1 and maxLength. It is typically small. * - * @param pErrorCode must be a valid pointer to an error code value, - * which must not indicate a failure before the function call. + * @param pErrorCode must be a valid pointer to an error code value. * * @return An empty UBiDi object with preallocated memory. * @stable ICU 2.0 */ -U_CAPI UBiDi * U_EXPORT2 +U_STABLE UBiDi * U_EXPORT2 ubidi_openSized(int32_t maxLength, int32_t maxRunCount, UErrorCode *pErrorCode); /** @@ -459,8 +460,10 @@ ubidi_openSized(int32_t maxLength, int32_t maxRunCount, UErrorCode *pErrorCode); * associated with a UBiDi object.

    * * Important: - * If a UBiDi object is the child - * of another one (its parent), after calling + * A parent UBiDi object must not be destroyed or reused if + * it still has children. + * If a UBiDi object has become the child + * of another one (its parent) by calling * ubidi_setLine(), then the child object must * be destroyed (closed) or reused (by calling * ubidi_setPara() or ubidi_setLine()) @@ -472,7 +475,7 @@ ubidi_openSized(int32_t maxLength, int32_t maxRunCount, UErrorCode *pErrorCode); * @see ubidi_setLine * @stable ICU 2.0 */ -U_CAPI void U_EXPORT2 +U_STABLE void U_EXPORT2 ubidi_close(UBiDi *pBiDi); /** @@ -484,13 +487,13 @@ ubidi_close(UBiDi *pBiDi); * in the Unicode Technical Report is to take text stored in logical * (keyboard, typing) order and to determine the reordering of it for visual * rendering. - * Some legacy codepages store text in visual order, and for operations + * Some legacy systems store text in visual order, and for operations * with standard, Unicode-based algorithms, the text needs to be transformed * to logical order. This is effectively the inverse algorithm of the * described BiDi algorithm. Note that there is no standard algorithm for * this "inverse BiDi" and that the current implementation provides only an * approximation of "inverse BiDi".

    - * + * *

    With isInverse set to TRUE, * this function changes the behavior of some of the subsequent functions * in a way that they can be used for the inverse BiDi algorithm. @@ -503,40 +506,463 @@ ubidi_close(UBiDi *pBiDi); * ubidi_getVisualRun() gets the reordered runs, these are actually * the runs of the logically ordered output.

    * + *

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

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

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

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

    + * + *

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

    + * + *

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

    + * + *

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

    + * + * + * + *

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

    + * + *

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

    This option must be set or reset before calling + * ubidi_setPara.

    + * + *

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

    + * + * + *

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

    + * + *

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

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

    + * + * @see ubidi_setReorderingMode + * @see ubidi_setReorderingOptions + * @draft ICU 3.6 + */ + UBIDI_OPTION_INSERT_MARKS = 1, + + /** + * option bit for ubidi_setReorderingOptions: + * remove BiDi control characters + * + *

    This option must be set or reset before calling + * ubidi_setPara.

    + * + *

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

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

    This option must be set or reset before calling + * ubidi_setPara.

    + * + *

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

    + * + *

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

    + * In all cases, this option should be turned off before processing the last + * part of the text.

    + * + *

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

    + * + * @see ubidi_setReorderingMode + * @see ubidi_setReorderingOptions + * @see ubidi_getProcessedLength + * @see ubidi_orderParagraphsLTR + * @draft ICU 3.6 + */ + UBIDI_OPTION_STREAMING = 4 +} UBiDiReorderingOption; + +/** + * Specify which of the reordering options + * should be applied during BiDi transformations. + * + * @param pBiDi is a UBiDi object. + * @param reorderingOptions is a combination of zero or more of the following + * options: + * #UBIDI_OPTION_DEFAULT, #UBIDI_OPTION_INSERT_MARKS, + * #UBIDI_OPTION_REMOVE_CONTROLS, #UBIDI_OPTION_STREAMING. + * + * @see ubidi_getReorderingOptions + * @draft ICU 3.6 + */ +U_DRAFT void U_EXPORT2 +ubidi_setReorderingOptions(UBiDi *pBiDi, uint32_t reorderingOptions); + +/** + * What are the reordering options applied to a given BiDi object? + * + * @param pBiDi is a UBiDi object. + * @return the current reordering options of the BiDi object + * @see ubidi_setReorderingOptions + * @draft ICU 3.6 + */ +U_DRAFT uint32_t U_EXPORT2 +ubidi_getReorderingOptions(UBiDi *pBiDi); + /** * Perform the Unicode BiDi algorithm. It is defined in the - * Unicode Technical Report 9, - * version 5, - * also described in The Unicode Standard, Version 3.0 .

    + * Unicode Standard Anned #9, + * version 13, + * also described in The Unicode Standard, Version 4.0 .

    * - * This function takes a single plain text paragraph with or without - * externally specified embedding levels from styled text - * and computes the left-right-directionality of each character.

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

    * - * If the entire paragraph consists of text of only one direction, then + * If the entire text is all of the same directionality, then * the function may not perform all the steps described by the algorithm, * i.e., some levels may not be the same as if all steps were performed. * This is not relevant for unidirectional text.
    @@ -545,41 +971,48 @@ ubidi_isInverse(UBiDi *pBiDi); * the algorithm. This implementation may set all resolved levels to * the same value in such a case.

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

    + * #UBIDI_LEVEL_OVERRIDE bit set.

    * Except for that bit, it must be - * paraLevel<=embeddingLevels[]<=UBIDI_MAX_EXPLICIT_LEVEL.

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

    * Caution: A copy of this pointer, not of the levels, * will be stored in the UBiDi object; * the embeddingLevels array must not be @@ -587,17 +1020,16 @@ ubidi_isInverse(UBiDi *pBiDi); * and the embeddingLevels * should not be modified to avoid unexpected results on subsequent BiDi operations. * However, the ubidi_setPara() and - * ubidi_setLine() functions may modify some or all of the levels.

    + * ubidi_setLine() functions may modify some or all of the levels.

    * After the UBiDi object is reused or destroyed, the caller - * must take care of the deallocation of the embeddingLevels array.

    - * The embeddingLevels array must be - * at least length long. + * must take care of the deallocation of the embeddingLevels array.

    + * Note: the embeddingLevels array must be + * at least length long. * - * @param pErrorCode must be a valid pointer to an error code value, - * which must not indicate a failure before the function call. + * @param pErrorCode must be a valid pointer to an error code value. * @stable ICU 2.0 */ -U_CAPI void U_EXPORT2 +U_STABLE void U_EXPORT2 ubidi_setPara(UBiDi *pBiDi, const UChar *text, int32_t length, UBiDiLevel paraLevel, UBiDiLevel *embeddingLevels, UErrorCode *pErrorCode); @@ -607,13 +1039,13 @@ ubidi_setPara(UBiDi *pBiDi, const UChar *text, int32_t length, * contain the reordering information, especially the resolved levels, * for all the characters in a line of text. This line of text is * specified by referring to a UBiDi object representing - * this information for a paragraph of text, and by specifying - * a range of indexes in this paragraph.

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

    + * this information for a piece of text containing one or more paragraphs, + * and by specifying a range of indexes in this text.

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

    * * This is used after calling ubidi_setPara() - * for a paragraph, and after line-breaking on that paragraph. - * It is not necessary if the paragraph is treated as a single line.

    + * for a piece of text, and after line-breaking on that text. + * It is not necessary if each paragraph is treated as a single line.

    * * After line-breaking, rules (L1) and (L2) for the treatment of * trailing WS and for reordering are performed on @@ -629,23 +1061,26 @@ ubidi_setPara(UBiDi *pBiDi, const UChar *text, int32_t length, * and start is added to it so that it points to the beginning of the * line for this object. * - * @param pParaBiDi is the parent paragraph object. + * @param pParaBiDi is the parent paragraph object. It must have been set + * by a successful call to ubidi_setPara. * - * @param start is the line's first index into the paragraph text. + * @param start is the line's first index into the text. * - * @param limit is just behind the line's last index into the paragraph text + * @param limit is just behind the line's last index into the text * (its last index +1).
    - * It must be 0<=start<=limit<=paragraph length. + * It must be 0<=start<=limit<=containing paragraph limit. + * If the specified line crosses a paragraph boundary, the function + * will terminate with error code U_ILLEGAL_ARGUMENT_ERROR. * - * @param pLineBiDi is the object that will now represent a line of the paragraph. + * @param pLineBiDi is the object that will now represent a line of the text. * - * @param pErrorCode must be a valid pointer to an error code value, - * which must not indicate a failure before the function call. + * @param pErrorCode must be a valid pointer to an error code value. * * @see ubidi_setPara + * @see ubidi_getProcessedLength * @stable ICU 2.0 */ -U_CAPI void U_EXPORT2 +U_STABLE void U_EXPORT2 ubidi_setLine(const UBiDi *pParaBiDi, int32_t start, int32_t limit, UBiDi *pLineBiDi, @@ -663,7 +1098,7 @@ ubidi_setLine(const UBiDi *pParaBiDi, * @see UBiDiDirection * @stable ICU 2.0 */ -U_CAPI UBiDiDirection U_EXPORT2 +U_STABLE UBiDiDirection U_EXPORT2 ubidi_getDirection(const UBiDi *pBiDi); /** @@ -677,7 +1112,7 @@ ubidi_getDirection(const UBiDi *pBiDi); * @see ubidi_setLine * @stable ICU 2.0 */ -U_CAPI const UChar * U_EXPORT2 +U_STABLE const UChar * U_EXPORT2 ubidi_getText(const UBiDi *pBiDi); /** @@ -688,7 +1123,7 @@ ubidi_getText(const UBiDi *pBiDi); * @return The length of the text that the UBiDi object was created for. * @stable ICU 2.0 */ -U_CAPI int32_t U_EXPORT2 +U_STABLE int32_t U_EXPORT2 ubidi_getLength(const UBiDi *pBiDi); /** @@ -696,14 +1131,99 @@ ubidi_getLength(const UBiDi *pBiDi); * * @param pBiDi is the paragraph or line UBiDi object. * - * @return The paragraph level. + * @return The paragraph level. If there are multiple paragraphs, their + * level may vary if the required paraLevel is UBIDI_DEFAULT_LTR or + * UBIDI_DEFAULT_RTL. In that case, the level of the first paragraph + * is returned. * * @see UBiDiLevel + * @see ubidi_getParagraph + * @see ubidi_getParagraphByIndex * @stable ICU 2.0 */ -U_CAPI UBiDiLevel U_EXPORT2 +U_STABLE UBiDiLevel U_EXPORT2 ubidi_getParaLevel(const UBiDi *pBiDi); +/** + * Get the number of paragraphs. + * + * @param pBiDi is the paragraph or line UBiDi object. + * + * @return The number of paragraphs. + * @stable ICU 3.4 + */ +U_STABLE int32_t U_EXPORT2 +ubidi_countParagraphs(UBiDi *pBiDi); + +/** + * Get a paragraph, given a position within the text. + * This function returns information about a paragraph.

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

    + * + * @param pBiDi is the paragraph UBiDi object. + * + * @param paraIndex is the number of the paragraph, in the + * range [0..ubidi_countParagraphs(pBiDi)-1]. + * + * @param pParaStart will receive the index of the first character of the + * paragraph in the text. + * This pointer can be NULL if this + * value is not necessary. + * + * @param pParaLimit will receive the limit of the paragraph. + * This pointer can be NULL if this + * value is not necessary. + * + * @param pParaLevel will receive the level of the paragraph. + * This pointer can be NULL if this + * value is not necessary. + * + * @param pErrorCode must be a valid pointer to an error code value. + * + * @stable ICU 3.4 + */ +U_STABLE void U_EXPORT2 +ubidi_getParagraphByIndex(const UBiDi *pBiDi, int32_t paraIndex, + int32_t *pParaStart, int32_t *pParaLimit, + UBiDiLevel *pParaLevel, UErrorCode *pErrorCode); + /** * Get the level for one character. * @@ -714,9 +1234,10 @@ ubidi_getParaLevel(const UBiDi *pBiDi); * @return The level for the character at charIndex. * * @see UBiDiLevel + * @see ubidi_getProcessedLength * @stable ICU 2.0 */ -U_CAPI UBiDiLevel U_EXPORT2 +U_STABLE UBiDiLevel U_EXPORT2 ubidi_getLevelAt(const UBiDi *pBiDi, int32_t charIndex); /** @@ -725,18 +1246,19 @@ ubidi_getLevelAt(const UBiDi *pBiDi, int32_t charIndex); * Note that this function may allocate memory under some * circumstances, unlike ubidi_getLevelAt(). * - * @param pBiDi is the paragraph or line UBiDi object. + * @param pBiDi is the paragraph or line UBiDi object, whose + * text length must be strictly positive. * - * @param pErrorCode must be a valid pointer to an error code value, - * which must not indicate a failure before the function call. + * @param pErrorCode must be a valid pointer to an error code value. * * @return The levels array for the text, * or NULL if an error occurs. * * @see UBiDiLevel + * @see ubidi_getProcessedLength * @stable ICU 2.0 */ -U_CAPI const UBiDiLevel * U_EXPORT2 +U_STABLE const UBiDiLevel * U_EXPORT2 ubidi_getLevels(UBiDi *pBiDi, UErrorCode *pErrorCode); /** @@ -759,9 +1281,11 @@ ubidi_getLevels(UBiDi *pBiDi, UErrorCode *pErrorCode); * @param pLevel will receive the level of the run. * This pointer can be NULL if this * value is not necessary. + * + * @see ubidi_getProcessedLength * @stable ICU 2.0 */ -U_CAPI void U_EXPORT2 +U_STABLE void U_EXPORT2 ubidi_getLogicalRun(const UBiDi *pBiDi, int32_t logicalStart, int32_t *pLogicalLimit, UBiDiLevel *pLevel); @@ -775,13 +1299,12 @@ ubidi_getLogicalRun(const UBiDi *pBiDi, int32_t logicalStart, * * @param pBiDi is the paragraph or line UBiDi object. * - * @param pErrorCode must be a valid pointer to an error code value, - * which must not indicate a failure before the function call. + * @param pErrorCode must be a valid pointer to an error code value. * * @return The number of runs. * @stable ICU 2.0 */ -U_CAPI int32_t U_EXPORT2 +U_STABLE int32_t U_EXPORT2 ubidi_countRuns(UBiDi *pBiDi, UErrorCode *pErrorCode); /** @@ -835,7 +1358,7 @@ ubidi_countRuns(UBiDi *pBiDi, UErrorCode *pErrorCode); * before first ones. * @stable ICU 2.0 */ -U_CAPI UBiDiDirection U_EXPORT2 +U_STABLE UBiDiDirection U_EXPORT2 ubidi_getVisualRun(UBiDi *pBiDi, int32_t runIndex, int32_t *pLogicalStart, int32_t *pLength); @@ -845,6 +1368,10 @@ ubidi_getVisualRun(UBiDi *pBiDi, int32_t runIndex, * UBiDi object, then calling * ubidi_getLogicalMap() is more efficient.

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

    * Note that in right-to-left runs, this mapping places * modifier letters before base characters and second surrogates * before first ones. @@ -853,16 +1380,16 @@ ubidi_getVisualRun(UBiDi *pBiDi, int32_t runIndex, * * @param logicalIndex is the index of a character in the text. * - * @param pErrorCode must be a valid pointer to an error code value, - * which must not indicate a failure before the function call. + * @param pErrorCode must be a valid pointer to an error code value. * * @return The visual position of this character. * * @see ubidi_getLogicalMap * @see ubidi_getLogicalIndex + * @see ubidi_getProcessedLength * @stable ICU 2.0 */ -U_CAPI int32_t U_EXPORT2 +U_STABLE int32_t U_EXPORT2 ubidi_getVisualIndex(UBiDi *pBiDi, int32_t logicalIndex, UErrorCode *pErrorCode); /** @@ -871,71 +1398,91 @@ ubidi_getVisualIndex(UBiDi *pBiDi, int32_t logicalIndex, UErrorCode *pErrorCode) * UBiDi object, then calling * ubidi_getVisualMap() is more efficient.

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

    * This is the inverse function to ubidi_getVisualIndex(). * * @param pBiDi is the paragraph or line UBiDi object. * * @param visualIndex is the visual position of a character. * - * @param pErrorCode must be a valid pointer to an error code value, - * which must not indicate a failure before the function call. + * @param pErrorCode must be a valid pointer to an error code value. * * @return The index of this character in the text. * * @see ubidi_getVisualMap * @see ubidi_getVisualIndex + * @see ubidi_getResultLength * @stable ICU 2.0 */ -U_CAPI int32_t U_EXPORT2 +U_STABLE int32_t U_EXPORT2 ubidi_getLogicalIndex(UBiDi *pBiDi, int32_t visualIndex, UErrorCode *pErrorCode); /** * Get a logical-to-visual index map (array) for the characters in the UBiDi * (paragraph or line) object. + *

    + * Some values in the map may be #UBIDI_MAP_NOWHERE if the + * corresponding text characters are BiDi controls removed from the visual + * output by the option #UBIDI_OPTION_REMOVE_CONTROLS. * * @param pBiDi is the paragraph or line UBiDi object. * - * @param indexMap is a pointer to an array of ubidi_getLength() + * @param indexMap is a pointer to an array of ubidi_getProcessedLength() * indexes which will reflect the reordering of the characters. - * The array does not need to be initialized.

    - * The index map will result in indexMap[logicalIndex]==visualIndex.

    + * If option #UBIDI_OPTION_INSERT_MARKS is set, the number + * of elements allocated in indexMap must be no less than + * ubidi_getResultLength(). + * The array does not need to be initialized.

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

    + * Some values in the map may be #UBIDI_MAP_NOWHERE if the + * corresponding text characters are BiDi marks inserted in the visual output + * by the option #UBIDI_OPTION_INSERT_MARKS. * * @param pBiDi is the paragraph or line UBiDi object. * - * @param indexMap is a pointer to an array of ubidi_getLength() + * @param indexMap is a pointer to an array of ubidi_getResultLength() * indexes which will reflect the reordering of the characters. - * The array does not need to be initialized.

    - * The index map will result in indexMap[visualIndex]==logicalIndex.

    + * If option #UBIDI_OPTION_REMOVE_CONTROLS is set, the number + * of elements allocated in indexMap must be no less than + * ubidi_getProcessedLength(). + * The array does not need to be initialized.

    + * The index map will result in indexMap[visualIndex]==logicalIndex. * - * @param pErrorCode must be a valid pointer to an error code value, - * which must not indicate a failure before the function call. + * @param pErrorCode must be a valid pointer to an error code value. * * @see ubidi_getLogicalMap * @see ubidi_getLogicalIndex + * @see ubidi_getProcessedLength + * @see ubidi_getResultLength * @stable ICU 2.0 */ -U_CAPI void U_EXPORT2 +U_STABLE void U_EXPORT2 ubidi_getVisualMap(UBiDi *pBiDi, int32_t *indexMap, UErrorCode *pErrorCode); /** * This is a convenience function that does not use a UBiDi object. * It is intended to be used for when an application has determined the levels * of objects (character sequences) and just needs to have them reordered (L2). - * This is equivalent to using ubidi_getLogicalMap on a + * This is equivalent to using ubidi_getLogicalMap() on a * UBiDi object. * * @param levels is an array with length levels that have been determined by @@ -951,14 +1498,14 @@ ubidi_getVisualMap(UBiDi *pBiDi, int32_t *indexMap, UErrorCode *pErrorCode); * The index map will result in indexMap[logicalIndex]==visualIndex. * @stable ICU 2.0 */ -U_CAPI void U_EXPORT2 +U_STABLE void U_EXPORT2 ubidi_reorderLogical(const UBiDiLevel *levels, int32_t length, int32_t *indexMap); /** * This is a convenience function that does not use a UBiDi object. * It is intended to be used for when an application has determined the levels * of objects (character sequences) and just needs to have them reordered (L2). - * This is equivalent to using ubidi_getVisualMap on a + * This is equivalent to using ubidi_getVisualMap() on a * UBiDi object. * * @param levels is an array with length levels that have been determined by @@ -974,24 +1521,37 @@ ubidi_reorderLogical(const UBiDiLevel *levels, int32_t length, int32_t *indexMap * The index map will result in indexMap[visualIndex]==logicalIndex. * @stable ICU 2.0 */ -U_CAPI void U_EXPORT2 +U_STABLE void U_EXPORT2 ubidi_reorderVisual(const UBiDiLevel *levels, int32_t length, int32_t *indexMap); /** * Invert an index map. - * The one-to-one index mapping of the first map is inverted and written to + * The index mapping of the first map is inverted and written to * the second one. * * @param srcMap is an array with length indexes - * which define the original mapping. - * - * @param destMap is an array with length indexes - * which will be filled with the inverse mapping. + * which defines the original mapping from a source array containing + * length elements to a destination array. + * All indexes must be >=0 or equal to UBIDI_MAP_NOWHERE. + * This special value means that the corresponding elements in the source + * array have no matching element in the destination array. + * Some indexes may have a value >= length, if the + * destination array has more elements than the source array. + * There must be no duplicate indexes (two or more indexes with the + * same value except UBIDI_MAP_NOWHERE). + * + * @param destMap is an array with a number of indexes equal to 1 + the highest + * value in srcMap. + * destMap will be filled with the inverse mapping. + * Elements of destMap which have no matching elements in + * srcMap will receive an index equal to + * UBIDI_MAP_NOWHERE * * @param length is the length of each array. + * @See UBIDI_MAP_NOWHERE * @stable ICU 2.0 */ -U_CAPI void U_EXPORT2 +U_STABLE void U_EXPORT2 ubidi_invertMap(const int32_t *srcMap, int32_t *destMap, int32_t length); /** option flags for ubidi_writeReordered() */ @@ -1020,6 +1580,9 @@ ubidi_invertMap(const int32_t *srcMap, int32_t *destMap, int32_t length); * surround the run with LRMs if necessary; * this is part of the approximate "inverse BiDi" algorithm * + *

    This option does not imply corresponding adjustment of the index + * mappings.

    + * * @see ubidi_setInverse * @see ubidi_writeReordered * @stable ICU 2.0 @@ -1029,7 +1592,10 @@ ubidi_invertMap(const int32_t *srcMap, int32_t *destMap, int32_t length); /** * option bit for ubidi_writeReordered(): * remove BiDi control characters - * (this does not affect UBIDI_INSERT_LRM_FOR_NUMERIC) + * (this does not affect #UBIDI_INSERT_LRM_FOR_NUMERIC) + * + *

    This option does not imply corresponding adjustment of the index + * mappings.

    * * @see ubidi_writeReordered * @stable ICU 2.0 @@ -1052,11 +1618,182 @@ ubidi_invertMap(const int32_t *srcMap, int32_t *destMap, int32_t length); */ #define UBIDI_OUTPUT_REVERSE 16 +/** + * Get the length of the source text processed by the last call to + * ubidi_setPara(). This length may be different from the length + * of the source text if option #UBIDI_OPTION_STREAMING + * has been set. + *
    + * Note that whenever the length of the text affects the execution or the + * result of a function, it is the processed length which must be considered, + * except for ubidi_setPara (which receives unprocessed source + * text) and ubidi_getLength (which returns the original length + * of the source text).
    + * In particular, the processed length is the one to consider in the following + * cases: + * + * + * @param pBiDi is the paragraph UBiDi object. + * + * @return The length of the part of the source text processed by + * the last call to ubidi_setPara. + * @see ubidi_setPara + * @see UBIDI_OPTION_STREAMING + * @draft ICU 3.6 + */ +U_DRAFT int32_t U_EXPORT2 +ubidi_getProcessedLength(const UBiDi *pBiDi); + +/** + * Get the length of the reordered text resulting from the last call to + * ubidi_setPara(). This length may be different from the length + * of the source text if option #UBIDI_OPTION_INSERT_MARKS + * or option #UBIDI_OPTION_REMOVE_CONTROLS has been set. + *
    + * This resulting length is the one to consider in the following cases: + * + * Note that this length stays identical to the source text length if + * BiDi marks are inserted or removed using option bits of + * ubidi_writeReordered, or if option + * #UBIDI_REORDER_INVERSE_NUMBERS_AS_L has been set. + * + * @param pBiDi is the paragraph UBiDi object. + * + * @return The length of the reordered text resulting from + * the last call to ubidi_setPara. + * @see ubidi_setPara + * @see UBIDI_OPTION_INSERT_MARKS + * @see UBIDI_OPTION_REMOVE_CONTROLS + * @draft ICU 3.6 + */ +U_DRAFT int32_t U_EXPORT2 +ubidi_getResultLength(const UBiDi *pBiDi); + +U_CDECL_BEGIN +/** + * value returned by UBiDiClassCallback callbacks when + * there is no need to override the standard BiDi class for a given code point. + * @see UBiDiClassCallback + * @draft ICU 3.6 + */ +#define U_BIDI_CLASS_DEFAULT U_CHAR_DIRECTION_COUNT + +/** + * Callback type declaration for overriding default BiDi class values with + * custom ones. + *

    Usually, the function pointer will be propagated to a UBiDi + * object by calling the ubidi_setClassCallback() function; + * then the callback will be invoked by the UBA implementation any time the + * class of a character is to be determined.

    + * + * @param context is a pointer to the callback private data. + * + * @param c is the code point to get a BiDi class for. + * + * @return The directional property / BiDi class for the given code point + * c if the default class has been overridden, or + * #U_BIDI_CLASS_DEFAULT if the standard BiDi class value + * for c is to be used. + * @see ubidi_setClassCallback + * @see ubidi_getClassCallback + * @draft ICU 3.6 + */ +typedef UCharDirection U_CALLCONV +UBiDiClassCallback(const void *context, UChar32 c); + +U_CDECL_END + +/** + * Retrieve the BiDi class for a given code point. + *

    If a #UBiDiClassCallback callback is defined and returns a + * value other than #U_BIDI_CLASS_DEFAULT, that value is used; + * otherwise the default class determination mechanism is invoked.

    + * + * @param pBiDi is the paragraph UBiDi object. + * + * @param c is the code point whose BiDi class must be retrieved. + * + * @return The BiDi class for character c based + * on the given pBiDi instance. + * @see UBiDiClassCallback + * @draft ICU 3.6 + */ +U_DRAFT UCharDirection U_EXPORT2 +ubidi_getCustomizedClass(UBiDi *pBiDi, UChar32 c); + +/** + * Set the callback function and callback data used by the UBA + * implementation for BiDi class determination. + *

    This may be useful for assigning BiDi classes to PUA characters, or + * for special application needs. For instance, an application may want to + * handle all spaces like L or R characters (according to the base direction) + * when creating the visual ordering of logical lines which are part of a report + * organized in columns: there should not be interaction between adjacent + * cells.

    + * + * @param pBiDi is the paragraph UBiDi object. + * + * @param newFn is the new callback function pointer. + * + * @param newContext is the new callback context pointer. This can be NULL. + * + * @param oldFn fillin: Returns the old callback function pointer. This can be + * NULL. + * + * @param oldContext fillin: Returns the old callback's context. This can be + * NULL. + * + * @param pErrorCode must be a valid pointer to an error code value. + * + * @see ubidi_getClassCallback + * @draft ICU 3.6 + */ +U_DRAFT void U_EXPORT2 +ubidi_setClassCallback(UBiDi *pBiDi, UBiDiClassCallback *newFn, + const void *newContext, UBiDiClassCallback **oldFn, + const void **oldContext, UErrorCode *pErrorCode); + +/** + * Get the current callback function used for BiDi class determination. + * + * @param pBiDi is the paragraph UBiDi object. + * + * @param fn fillin: Returns the callback function pointer. + * + * @param context fillin: Returns the callback's private context. + * + * @see ubidi_setClassCallback + * @draft ICU 3.6 + */ +U_DRAFT void U_EXPORT2 +ubidi_getClassCallback(UBiDi *pBiDi, UBiDiClassCallback **fn, const void **context); + /** * Take a UBiDi object containing the reordering - * information for one paragraph or line of text as set by - * ubidi_setPara() or ubidi_setLine() and - * write a reordered string to the destination buffer. + * information for a piece of text (one or more paragraphs) set by + * ubidi_setPara() or for a line of text set by + * ubidi_setLine() and write a reordered string to the + * destination buffer. * * This function preserves the integrity of characters with multiple * code units and (optionally) modifier letters. @@ -1073,10 +1810,10 @@ ubidi_invertMap(const int32_t *srcMap, int32_t *destMap, int32_t length); * is set by ubidi_setPara() or * ubidi_setLine() and contains the reordering * information for the text that it was defined for, - * as well as a pointer to that text. - *

    The text was aliased (only the pointer was stored + * as well as a pointer to that text.

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

    + * since the ubidi_setPara() call. * * @param dest A pointer to where the reordered text is to be copied. * The source text and dest[destSize] @@ -1102,14 +1839,21 @@ ubidi_invertMap(const int32_t *srcMap, int32_t *destMap, int32_t length); * to logically stored text (although this is still an * imperfect implementation of an "inverse BiDi" algorithm * because it uses the "forward BiDi" algorithm at its core). + * The available options are: + * #UBIDI_DO_MIRRORING, + * #UBIDI_INSERT_LRM_FOR_NUMERIC, + * #UBIDI_KEEP_BASE_COMBINING, + * #UBIDI_OUTPUT_REVERSE, + * #UBIDI_REMOVE_BIDI_CONTROLS * - * @param pErrorCode must be a valid pointer to an error code value, - * which must not indicate a failure before the function call. + * @param pErrorCode must be a valid pointer to an error code value. * * @return The length of the output string. + * + * @see ubidi_getProcessedLength * @stable ICU 2.0 */ -U_CAPI int32_t U_EXPORT2 +U_STABLE int32_t U_EXPORT2 ubidi_writeReordered(UBiDi *pBiDi, UChar *dest, int32_t destSize, uint16_t options, @@ -1154,15 +1898,14 @@ ubidi_writeReordered(UBiDi *pBiDi, * * @param options A bit set of options for the reordering that control * how the reordered text is written. - * See ubidi_writeReordered(). + * See the options parameter in ubidi_writeReordered(). * - * @param pErrorCode must be a valid pointer to an error code value, - * which must not indicate a failure before the function call. + * @param pErrorCode must be a valid pointer to an error code value. * * @return The length of the output string. * @stable ICU 2.0 */ -U_CAPI int32_t U_EXPORT2 +U_STABLE int32_t U_EXPORT2 ubidi_writeReverse(const UChar *src, int32_t srcLength, UChar *dest, int32_t destSize, uint16_t options,