Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members  

ubidi.h File Reference

C API: BIDI algorithm. More...

#include "unicode/utypes.h"
#include "unicode/uchar.h"

Go to the source code of this file.

Defines

#define UBIDI_DEFAULT_LTR   0xfe
 Paragraph level setting. More...

#define UBIDI_DEFAULT_RTL   0xff
 Paragraph level setting. More...

#define UBIDI_MAX_EXPLICIT_LEVEL   61
 Maximum explicit embedding level. More...

#define UBIDI_LEVEL_OVERRIDE   0x80
 Bit flag for level input. More...

#define UBIDI_KEEP_BASE_COMBINING   1
 option bit for ubidi_writeReordered(): keep combining characters after their base characters in RTL runs. More...

#define UBIDI_DO_MIRRORING   2
 option bit for ubidi_writeReordered(): replace characters with the "mirrored" property in RTL runs by their mirror-image mappings. More...

#define UBIDI_INSERT_LRM_FOR_NUMERIC   4
 option bit for ubidi_writeReordered(): surround the run with LRMs if necessary; this is part of the approximate "inverse BiDi" algorithm. More...

#define UBIDI_REMOVE_BIDI_CONTROLS   8
 option bit for ubidi_writeReordered(): remove BiDi control characters (this does not affect UBIDI_INSERT_LRM_FOR_NUMERIC). More...

#define UBIDI_OUTPUT_REVERSE   16
 option bit for ubidi_writeReordered(): write the output in reverse order. More...


Typedefs

typedef uint8_t UBiDiLevel
 UBiDiLevel is the type of the level values in this BiDi implementation. More...

typedef enum UBiDiDirection UBiDiDirection
typedef struct UBiDi UBiDi

Enumerations

enum  UBiDiDirection { UBIDI_LTR, UBIDI_RTL, UBIDI_MIXED }
 UBiDiDirection values indicate the text direction. More...


Functions

U_CAPI UBiDi* U_EXPORT2 ubidi_open (void)
 Allocate a UBiDi structure. More...

U_CAPI UBiDi* U_EXPORT2 ubidi_openSized (UTextOffset maxLength, UTextOffset maxRunCount, UErrorCode *pErrorCode)
 Allocate a UBiDi structure with preallocated memory for internal structures. More...

U_CAPI void U_EXPORT2 ubidi_close (UBiDi *pBiDi)
 ubidi_close() must be called to free the memory associated with a UBiDi object.

. More...

U_CAPI void U_EXPORT2 ubidi_setInverse (UBiDi *pBiDi, UBool isInverse)
 Modify the operation of the BiDi algorithm such that it approximates an "inverse BiDi" algorithm. More...

U_CAPI UBool U_EXPORT2 ubidi_isInverse (UBiDi *pBiDi)
 Is this BiDi object set to perform the inverse BiDi algorithm? More...

U_CAPI void U_EXPORT2 ubidi_setPara (UBiDi *pBiDi, const UChar *text, UTextOffset length, UBiDiLevel paraLevel, UBiDiLevel *embeddingLevels, UErrorCode *pErrorCode)
 Perform the Unicode BiDi algorithm. More...

U_CAPI void U_EXPORT2 ubidi_setLine (const UBiDi *pParaBiDi, UTextOffset start, UTextOffset limit, UBiDi *pLineBiDi, UErrorCode *pErrorCode)
 ubidi_setLine() sets a UBiDi to contain the reordering information, especially the resolved levels, for all the characters in a line of text. More...

U_CAPI UBiDiDirection U_EXPORT2 ubidi_getDirection (const UBiDi *pBiDi)
 Get the directionality of the text. More...

U_CAPI const UChar* U_EXPORT2 ubidi_getText (const UBiDi *pBiDi)
 Get the pointer to the text. More...

U_CAPI UTextOffset U_EXPORT2 ubidi_getLength (const UBiDi *pBiDi)
 Get the length of the text. More...

U_CAPI UBiDiLevel U_EXPORT2 ubidi_getParaLevel (const UBiDi *pBiDi)
 Get the paragraph level of the text. More...

U_CAPI UBiDiLevel U_EXPORT2 ubidi_getLevelAt (const UBiDi *pBiDi, UTextOffset charIndex)
 Get the level for one character. More...

U_CAPI const UBiDiLevel* U_EXPORT2 ubidi_getLevels (UBiDi *pBiDi, UErrorCode *pErrorCode)
 Get an array of levels for each character.

. More...

U_CAPI void U_EXPORT2 ubidi_getLogicalRun (const UBiDi *pBiDi, UTextOffset logicalStart, UTextOffset *pLogicalLimit, UBiDiLevel *pLevel)
 Get a logical run. More...

U_CAPI UTextOffset U_EXPORT2 ubidi_countRuns (UBiDi *pBiDi, UErrorCode *pErrorCode)
 Get the number of runs. More...

U_CAPI UBiDiDirection U_EXPORT2 ubidi_getVisualRun (UBiDi *pBiDi, UTextOffset runIndex, UTextOffset *pLogicalStart, UTextOffset *pLength)
 Get one run's logical start, length, and directionality, which can be 0 for LTR or 1 for RTL. More...

U_CAPI UTextOffset U_EXPORT2 ubidi_getVisualIndex (UBiDi *pBiDi, UTextOffset logicalIndex, UErrorCode *pErrorCode)
 Get the visual position from a logical text position. More...

U_CAPI UTextOffset U_EXPORT2 ubidi_getLogicalIndex (UBiDi *pBiDi, UTextOffset visualIndex, UErrorCode *pErrorCode)
 Get the logical text position from a visual position. More...

U_CAPI void U_EXPORT2 ubidi_getLogicalMap (UBiDi *pBiDi, UTextOffset *indexMap, UErrorCode *pErrorCode)
 Get a logical-to-visual index map (array) for the characters in the UBiDi (paragraph or line) object. More...

U_CAPI void U_EXPORT2 ubidi_getVisualMap (UBiDi *pBiDi, UTextOffset *indexMap, UErrorCode *pErrorCode)
 Get a visual-to-logical index map (array) for the characters in the UBiDi (paragraph or line) object. More...

U_CAPI void U_EXPORT2 ubidi_reorderLogical (const UBiDiLevel *levels, UTextOffset length, UTextOffset *indexMap)
 This is a convenience function that does not use a UBiDi object. More...

U_CAPI void U_EXPORT2 ubidi_reorderVisual (const UBiDiLevel *levels, UTextOffset length, UTextOffset *indexMap)
 This is a convenience function that does not use a UBiDi object. More...

U_CAPI void U_EXPORT2 ubidi_invertMap (const UTextOffset *srcMap, UTextOffset *destMap, UTextOffset length)
 Invert an index map. More...

U_CAPI UTextOffset U_EXPORT2 ubidi_writeReordered (UBiDi *pBiDi, UChar *dest, int32_t destSize, uint16_t options, UErrorCode *pErrorCode)
 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. More...

U_CAPI UTextOffset U_EXPORT2 ubidi_writeReverse (const UChar *src, int32_t srcLength, UChar *dest, int32_t destSize, uint16_t options, UErrorCode *pErrorCode)
 Reverse a Right-To-Left run of Unicode text. More...


Detailed Description

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 .

General remarks about the API:

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

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

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

Author(s):
Markus W. Scherer
Version:
1.0

Sample code for the ICU BIDI API

Rendering a paragraph with the ICU BiDi API

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

The basic assumptions are:

 
#include "unicode/ubidi.h"

typedef enum {
     styleNormal=0, styleSelected=1,
     styleBold=2, styleItalics=4,
     styleSuper=8, styleSub=16
} Style;

typedef struct { UTextOffset limit; Style style; } StyleRun;

int getTextWidth(const UChar *text, UTextOffset start, UTextOffset limit,
                  const StyleRun *styleRuns, int styleRunCount);

 // set *pLimit and *pStyleRunLimit for a line
 // from text[start] and from styleRuns[styleRunStart]
 // using ubidi_getLogicalRun(para, ...)
void getLineBreak(const UChar *text, UTextOffset start, UTextOffset *pLimit,
                  UBiDi *para,
                  const StyleRun *styleRuns, int styleRunStart, int *pStyleRunLimit,
                  int *pLineWidth);

 // render runs on a line sequentially, always from left to right

 // prepare rendering a new line
void startLine(UBiDiDirection textDirection, int lineWidth);

 // render a run of text and advance to the right by the run width
 // the text[start..limit-1] is always in logical order
void renderRun(const UChar *text, UTextOffset start, UTextOffset limit,
               UBiDiDirection textDirection, Style style);

 // We could compute a cross-product
 // from the style runs with the directional runs
 // and then reorder it.
 // Instead, here we iterate over each run type
 // and render the intersections -
 // with shortcuts in simple (and common) cases.
 // renderParagraph() is the main function.

 // render a directional run with
 // (possibly) multiple style runs intersecting with it
void renderDirectionalRun(const UChar *text,
                           UTextOffset start, UTextOffset limit,
                           UBiDiDirection direction,
                           const StyleRun *styleRuns, int styleRunCount) {
     int i;

     // iterate over style runs
     if(direction==UBIDI_LTR) {
         int styleLimit;

         for(i=0; i<styleRunCount; ++i) {
             styleLimit=styleRun[i].limit;
             if(start<styleLimit) {
                 if(styleLimit>limit) { styleLimit=limit; }
                 renderRun(text, start, styleLimit,
                           direction, styleRun[i].style);
                 if(styleLimit==limit) { break; }
                 start=styleLimit;
             }
         }
     } else {
         int styleStart;

         for(i=styleRunCount-1; i>=0; --i) {
             if(i>0) {
                 styleStart=styleRun[i-1].limit;
             } else {
                 styleStart=0;
             }
             if(limit>=styleStart) {
                 if(styleStart<start) { styleStart=start; }
                 renderRun(text, styleStart, limit,
                           direction, styleRun[i].style);
                 if(styleStart==start) { break; }
                 limit=styleStart;
             }
         }
     }
 }

 // the line object represents text[start..limit-1]
 void renderLine(UBiDi *line, const UChar *text,
                 UTextOffset start, UTextOffset limit,
                 const StyleRun *styleRuns, int styleRunCount) {
     UBiDiDirection direction=ubidi_getDirection(line);
     if(direction!=UBIDI_MIXED) {
         // unidirectional
         if(styleRunCount<=1) {
             renderRun(text, start, limit, direction, styleRuns[0].style);
         } else {
             renderDirectionalRun(text, start, limit,
                                  direction, styleRuns, styleRunCount);
         }
     } else {
         // mixed-directional
         UTextOffset count, i, length;
         UBiDiLevel level;

         count=ubidi_countRuns(para, pErrorCode);
         if(U_SUCCESS(*pErrorCode)) {
             if(styleRunCount<=1) {
                 Style style=styleRuns[0].style;

                 // iterate over directional runs
                for(i=0; i<count; ++i) {
                    direction=ubidi_getVisualRun(para, i, &start, &length);
                     renderRun(text, start, start+length, direction, style);
                }
             } else {
                 UTextOffset j;

                 // iterate over both directional and style runs
                 for(i=0; i<count; ++i) {
                     direction=ubidi_getVisualRun(line, i, &start, &length);
                     renderDirectionalRun(text, start, start+length,
                                          direction, styleRuns, styleRunCount);
                 }
             }
         }
     }
 }

void renderParagraph(const UChar *text, UTextOffset length,
                     UBiDiDirection textDirection,
                      const StyleRun *styleRuns, int styleRunCount,
                      int lineWidth,
                      UErrorCode *pErrorCode) {
     UBiDi *para;

     if(pErrorCode==NULL || U_FAILURE(*pErrorCode) || length<=0) {
         return;
     }

     para=ubidi_openSized(length, 0, pErrorCode);
     if(para==NULL) { return; }

     ubidi_setPara(para, text, length,
                   textDirection ? UBIDI_DEFAULT_RTL : UBIDI_DEFAULT_LTR,
                   NULL, pErrorCode);
     if(U_SUCCESS(*pErrorCode)) {
         UBiDiLevel paraLevel=1&ubidi_getParaLevel(para);
         StyleRun styleRun={ length, styleNormal };
         int width;

         if(styleRuns==NULL || styleRunCount<=0) {
            styleRunCount=1;
             styleRuns=&styleRun;
         }

        // assume styleRuns[styleRunCount-1].limit>=length

         width=getTextWidth(text, 0, length, styleRuns, styleRunCount);
         if(width<=lineWidth) {
             // everything fits onto one line

            // prepare rendering a new line from either left or right
             startLine(paraLevel, width);

             renderLine(para, text, 0, length,
                        styleRuns, styleRunCount);
         } else {
             UBiDi *line;

             // we need to render several lines
             line=ubidi_openSized(length, 0, pErrorCode);
             if(line!=NULL) {
                 UTextOffset start=0, limit;
                 int styleRunStart=0, styleRunLimit;

                 for(;;) {
                     limit=length;
                     styleRunLimit=styleRunCount;
                     getLineBreak(text, start, &limit, para,
                                  styleRuns, styleRunStart, &styleRunLimit,
                                 &width);
                     ubidi_setLine(para, start, limit, line, pErrorCode);
                     if(U_SUCCESS(*pErrorCode)) {
                         // prepare rendering a new line
                         // from either left or right
                         startLine(paraLevel, width);

                         renderLine(line, text, start, limit,
                                    styleRuns+styleRunStart,
                                    styleRunLimit-styleRunStart);
                     }
                     if(limit==length) { break; }
                     start=limit;
                     styleRunStart=styleRunLimit-1;
                     if(start>=styleRuns[styleRunStart].limit) {
                         ++styleRunStart;
                     }
                 }

                 ubidi_close(line);
             }
        }
    }

     ubidi_close(para);
}

Definition in file ubidi.h.


Define Documentation

#define UBIDI_DEFAULT_LTR   0xfe
 

Paragraph level setting.

If there is no strong character, then set the paragraph level to 0 (left-to-right).

Definition at line 342 of file ubidi.h.

#define UBIDI_DEFAULT_RTL   0xff
 

Paragraph level setting.

If there is no strong character, then set the paragraph level to 1 (right-to-left).

Definition at line 347 of file ubidi.h.

#define UBIDI_DO_MIRRORING   2
 

option bit for ubidi_writeReordered(): replace characters with the "mirrored" property in RTL runs by their mirror-image mappings.

See also:
ubidi_writeReordered

Definition at line 976 of file ubidi.h.

#define UBIDI_INSERT_LRM_FOR_NUMERIC   4
 

option bit for ubidi_writeReordered(): surround the run with LRMs if necessary; this is part of the approximate "inverse BiDi" algorithm.

See also:
ubidi_setInverse , ubidi_writeReordered

Definition at line 986 of file ubidi.h.

#define UBIDI_KEEP_BASE_COMBINING   1
 

option bit for ubidi_writeReordered(): keep combining characters after their base characters in RTL runs.

See also:
ubidi_writeReordered

Definition at line 967 of file ubidi.h.

#define UBIDI_LEVEL_OVERRIDE   0x80
 

Bit flag for level input.

Overrides directional properties.

Definition at line 359 of file ubidi.h.

#define UBIDI_MAX_EXPLICIT_LEVEL   61
 

Maximum explicit embedding level.

(The maximum resolved level can be up to UBIDI_MAX_EXPLICIT_LEVEL+1).

Definition at line 354 of file ubidi.h.

#define UBIDI_OUTPUT_REVERSE   16
 

option bit for ubidi_writeReordered(): write the output in reverse order.

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

See also:
ubidi_writeReordered

Definition at line 1010 of file ubidi.h.

#define UBIDI_REMOVE_BIDI_CONTROLS   8
 

option bit for ubidi_writeReordered(): remove BiDi control characters (this does not affect UBIDI_INSERT_LRM_FOR_NUMERIC).

See also:
ubidi_writeReordered

Definition at line 995 of file ubidi.h.


Typedef Documentation

typedef struct UBiDi UBiDi
 

Definition at line 386 of file ubidi.h.

typedef enum UBiDiDirection UBiDiDirection
 

Definition at line 373 of file ubidi.h.

typedef uint8_t UBiDiLevel
 

UBiDiLevel is the type of the level values in this BiDi implementation.

It holds an embedding level and indicates the visual direction by its bit 0 (even/odd value).

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

  • bit 7 of an embeddingLevels[] value indicates whether the using application is 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 and UBIDI_DEFAULT_RTL.

    See also:
    ubidi_setPara

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

    Note that the value for UBIDI_DEFAULT_LTR is even and the one for UBIDI_DEFAULT_RTL is odd, just like with normal LTR and RTL level values - these special values are designed that way. Also, the implementation assumes that UBIDI_MAX_EXPLICIT_LEVEL is odd.

    See also:
    UBIDI_DEFAULT_LTR , UBIDI_DEFAULT_RTL , UBIDI_LEVEL_OVERRIDE , UBIDI_MAX_EXPLICIT_LEVEL

    Definition at line 337 of file ubidi.h.


Enumeration Type Documentation

enum UBiDiDirection
 

UBiDiDirection values indicate the text direction.

Enumeration values:
UBIDI_LTR   All left-to-right text. This is a 0 value.
UBIDI_RTL   All right-to-left text. This is a 1 value.
UBIDI_MIXED   Mixed-directional text.

Definition at line 364 of file ubidi.h.


Function Documentation

U_CAPI void U_EXPORT2 ubidi_close ( UBiDi * pBiDi )
 

ubidi_close() must be called to free the memory associated with a UBiDi object.

.

Important: If a UBiDi object is the <quote>child</quote> of another one (its <quote>parent</quote>), after calling ubidi_setLine(), then the child object must be destroyed (closed) or reused (by calling ubidi_setPara() or ubidi_setLine()) before the parent object.

Parameters:
pBiDi   is a UBiDi object.

See also:
ubidi_setPara , ubidi_setLine

Referenced by BiDi::~BiDi().

U_CAPI UTextOffset U_EXPORT2 ubidi_countRuns ( UBiDi * pBiDi,
UErrorCode * pErrorCode )
 

Get the number of runs.

This function may invoke the actual reordering on the UBiDi object, after ubidi_setPara() may have resolved only the levels of the text. Therefore, ubidi_countRuns() may have to allocate memory, and may fail doing so.

Parameters:
pBiDi   is the paragraph or line UBiDi object.
pErrorCode   must be a valid pointer to an error code value, which must not indicate a failure before the function call.

Returns:
The number of runs.

Referenced by BiDi::countRuns().

U_CAPI UBiDiDirection U_EXPORT2 ubidi_getDirection ( const UBiDi * pBiDi )
 

Get the directionality of the text.

Parameters:
pBiDi   is the paragraph or line UBiDi object.

Returns:
A UBIDI_XXX value that indicates if the entire text represented by this object is unidirectional, and which direction, or if it is mixed-directional.

See also:
UBiDiDirection

Referenced by BiDi::getDirection().

U_CAPI UTextOffset U_EXPORT2 ubidi_getLength ( const UBiDi * pBiDi )
 

Get the length of the text.

Parameters:
pBiDi   is the paragraph or line UBiDi object.

Returns:
The length of the text that the UBiDi object was created for.

Referenced by BiDi::getLength().

U_CAPI UBiDiLevel U_EXPORT2 ubidi_getLevelAt ( const UBiDi * pBiDi,
UTextOffset charIndex )
 

Get the level for one character.

Parameters:
pBiDi   is the paragraph or line UBiDi object.
charIndex   the index of a character.

Returns:
The level for the character at charIndex.

See also:
UBiDiLevel

Referenced by BiDi::getLevelAt().

U_CAPI const UBiDiLevel *U_EXPORT2 ubidi_getLevels ( UBiDi * pBiDi,
UErrorCode * pErrorCode )
 

Get an array of levels for each character.

.

Note that this function may allocate memory under some circumstances, unlike ubidi_getLevelAt().

Parameters:
pBiDi   is the paragraph or line UBiDi object.
pErrorCode   must be a valid pointer to an error code value, which must not indicate a failure before the function call.

Returns:
The levels array for the text, or NULL if an error occurs.

See also:
UBiDiLevel

Referenced by BiDi::getLevels().

U_CAPI UTextOffset U_EXPORT2 ubidi_getLogicalIndex ( UBiDi * pBiDi,
UTextOffset visualIndex,
UErrorCode * pErrorCode )
 

Get the logical text position from a visual position.

If such a mapping is used many times on the same UBiDi object, then calling ubidi_getVisualMap() is more efficient.

This is the inverse function to ubidi_getVisualIndex().

Parameters:
pBiDi   is the paragraph or line UBiDi object.
visualIndex   is the visual position of a character.
pErrorCode   must be a valid pointer to an error code value, which must not indicate a failure before the function call.

Returns:
The index of this character in the text.

See also:
ubidi_getVisualMap , ubidi_getVisualIndex

Referenced by BiDi::getLogicalIndex().

U_CAPI void U_EXPORT2 ubidi_getLogicalMap ( UBiDi * pBiDi,
UTextOffset * indexMap,
UErrorCode * pErrorCode )
 

Get a logical-to-visual index map (array) for the characters in the UBiDi (paragraph or line) object.

Parameters:
pBiDi   is the paragraph or line UBiDi object.
indexMap   is a pointer to an array of ubidi_getLength() 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.

Parameters:
pErrorCode   must be a valid pointer to an error code value, which must not indicate a failure before the function call.

See also:
ubidi_getVisualMap , ubidi_getVisualIndex

Referenced by BiDi::getLogicalMap().

U_CAPI void U_EXPORT2 ubidi_getLogicalRun ( const UBiDi * pBiDi,
UTextOffset logicalStart,
UTextOffset * pLogicalLimit,
UBiDiLevel * pLevel )
 

Get a logical run.

This function returns information about a run and is used to retrieve runs in logical order.

This is especially useful for line-breaking on a paragraph.

Parameters:
pBiDi   is the paragraph or line UBiDi object.
logicalStart   is the first character of the run.
pLogicalLimit   will receive the limit of the run. The l-value that you point to here may be the same expression (variable) as the one for logicalStart. This pointer can be NULL if this value is not necessary.
pLevel   will receive the level of the run. This pointer can be NULL if this value is not necessary.

Referenced by BiDi::getLogicalRun().

U_CAPI UBiDiLevel U_EXPORT2 ubidi_getParaLevel ( const UBiDi * pBiDi )
 

Get the paragraph level of the text.

Parameters:
pBiDi   is the paragraph or line UBiDi object.

Returns:
The paragraph level.

See also:
UBiDiLevel

Referenced by BiDi::getParaLevel().

U_CAPI const UChar *U_EXPORT2 ubidi_getText ( const UBiDi * pBiDi )
 

Get the pointer to the text.

Parameters:
pBiDi   is the paragraph or line UBiDi object.

Returns:
The pointer to the text that the UBiDi object was created for.

See also:
ubidi_setPara , ubidi_setLine

Referenced by BiDi::getText().

U_CAPI UTextOffset U_EXPORT2 ubidi_getVisualIndex ( UBiDi * pBiDi,
UTextOffset logicalIndex,
UErrorCode * pErrorCode )
 

Get the visual position from a logical text position.

If such a mapping is used many times on the same UBiDi object, then calling ubidi_getLogicalMap() is more efficient.

Note that in right-to-left runs, this mapping places modifier letters before base characters and second surrogates before first ones.

Parameters:
pBiDi   is the paragraph or line UBiDi object.
logicalIndex   is the index of a character in the text.
pErrorCode   must be a valid pointer to an error code value, which must not indicate a failure before the function call.

Returns:
The visual position of this character.

See also:
ubidi_getLogicalMap , ubidi_getLogicalIndex

Referenced by BiDi::getVisualIndex().

U_CAPI void U_EXPORT2 ubidi_getVisualMap ( UBiDi * pBiDi,
UTextOffset * indexMap,
UErrorCode * pErrorCode )
 

Get a visual-to-logical index map (array) for the characters in the UBiDi (paragraph or line) object.

Parameters:
pBiDi   is the paragraph or line UBiDi object.
indexMap   is a pointer to an array of ubidi_getLength() 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.

Parameters:
pErrorCode   must be a valid pointer to an error code value, which must not indicate a failure before the function call.

See also:
ubidi_getLogicalMap , ubidi_getLogicalIndex

Referenced by BiDi::getVisualMap().

U_CAPI UBiDiDirection U_EXPORT2 ubidi_getVisualRun ( UBiDi * pBiDi,
UTextOffset runIndex,
UTextOffset * pLogicalStart,
UTextOffset * pLength )
 

Get one run's logical start, length, and directionality, which can be 0 for LTR or 1 for RTL.

In an RTL run, the character at the logical start is visually on the right of the displayed run. The length is the number of characters in the run.

ubidi_countRuns() should be called before the runs are retrieved.

Parameters:
pBiDi   is the paragraph or line UBiDi object.
runIndex   is the number of the run in visual order, in the range [0..ubidi_countRuns(pBiDi)-1].
pLogicalStart   is the first logical character index in the text. The pointer may be NULL if this index is not needed.
pLength   is the number of characters (at least one) in the run. The pointer may be NULL if this is not needed.

Returns:
the directionality of the run, UBIDI_LTR==0 or UBIDI_RTL==1, never UBIDI_MIXED.

See also:
ubidi_countRuns

Example:
 
 UTextOffset i, count=ubidi_countRuns(pBiDi),
         logicalStart, visualIndex=0, length;
 for(i=0; i<count; ++i) {
    if(UBIDI_LTR==ubidi_getVisualRun(pBiDi, i, &logicalStart, &length)) {
         do { // LTR
             show_char(text[logicalStart++], visualIndex++);
         } while(--length>0);
     } else {
         logicalStart+=length;  // logicalLimit
         do { // RTL
             show_char(text[--logicalStart], visualIndex++);
         } while(--length>0);
     }
 }

Note that in right-to-left runs, code like this places modifier letters before base characters and second surrogates before first ones.

Referenced by BiDi::getVisualRun().

U_CAPI void U_EXPORT2 ubidi_invertMap ( const UTextOffset * srcMap,
UTextOffset * destMap,
UTextOffset length )
 

Invert an index map.

The one-to-one index mapping of the first map is inverted and written to the second one.

Parameters:
srcMap   is an array with length indexes which define the original mapping.
destMap   is an array with length indexes which will be filled with the inverse mapping.
length   is the length of each array.

Referenced by BiDi::invertMap().

U_CAPI UBool U_EXPORT2 ubidi_isInverse ( UBiDi * pBiDi )
 

Is this BiDi object set to perform the inverse BiDi algorithm?

Parameters:
pBiDi   is a UBiDi object.

See also:
ubidi_setInverse

Referenced by BiDi::isInverse().

U_CAPI UBiDi *U_EXPORT2 ubidi_open ( void )
 

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 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.

Returns:
An empty UBiDi object.

Referenced by BiDi::BiDi().

U_CAPI UBiDi *U_EXPORT2 ubidi_openSized ( UTextOffset maxLength,
UTextOffset maxRunCount,
UErrorCode * pErrorCode )
 

Allocate a UBiDi structure with preallocated memory for internal structures.

This function provides a UBiDi object like ubidi_open() with no arguments, but it also preallocates memory for internal structures according to the sizings supplied by the caller.

Subsequent functions will not allocate any more memory, and are thus guaranteed not to fail because of lack of memory.

The preallocation can be limited to some of the internal memory by setting some values to 0 here. That means that if, e.g., maxRunCount cannot be reasonably predetermined and should not be set to maxLength (the only failproof value) to avoid wasting memory, then maxRunCount could be set to 0 here and the internal structures that are associated with it will be allocated on demand, just like with ubidi_open().

Parameters:
maxLength   is the maximum paragraph 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.
maxRunCount   is the maximum anticipated number of same-level runs 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.

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

Parameters:
pErrorCode   must be a valid pointer to an error code value, which must not indicate a failure before the function call.

Returns:
An empty UBiDi object with preallocated memory.

Referenced by BiDi::BiDi().

U_CAPI void U_EXPORT2 ubidi_reorderLogical ( const UBiDiLevel * levels,
UTextOffset length,
UTextOffset * 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_getLogicalMap on a UBiDi object.

Parameters:
levels   is an array with length levels that have been determined by the application.
length   is the number of levels in the array, or, semantically, the number of objects to be reordered. It must be length>0.
indexMap   is a pointer to an array of length 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.

Referenced by BiDi::reorderLogical().

U_CAPI void U_EXPORT2 ubidi_reorderVisual ( const UBiDiLevel * levels,
UTextOffset length,
UTextOffset * 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 UBiDi object.

Parameters:
levels   is an array with length levels that have been determined by the application.
length   is the number of levels in the array, or, semantically, the number of objects to be reordered. It must be length>0.
indexMap   is a pointer to an array of length 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.

Referenced by BiDi::reorderVisual().

U_CAPI void U_EXPORT2 ubidi_setInverse ( UBiDi * pBiDi,
UBool isInverse )
 

Modify the operation of the BiDi algorithm such that it approximates an "inverse BiDi" algorithm.

This function must be called before ubidi_setPara().

The normal operation of the BiDi algorithm as described 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 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. Specifically, runs of text with numeric characters will be treated in a special way and may need to be surrounded with LRM characters when they are written in reordered sequence.

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

Parameters:
pBiDi   is a UBiDi object.
isInverse   specifies "forward" or "inverse" BiDi operation

See also:
ubidi_setPara , ubidi_writeReordered

Referenced by BiDi::setInverse().

U_CAPI void U_EXPORT2 ubidi_setLine ( const UBiDi * pParaBiDi,
UTextOffset start,
UTextOffset limit,
UBiDi * pLineBiDi,
UErrorCode * pErrorCode )
 

ubidi_setLine() sets a UBiDi to 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 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.

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

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

The text pointer that was stored in pParaBiDi is also copied, and start is added to it so that it points to the beginning of the line for this object.

Parameters:
pParaBiDi   is the parent paragraph object.
start   is the line's first index into the paragraph text.
limit   is just behind the line's last index into the paragraph text (its last index +1).
It must be 0<=start<=limit<=paragraph length.
pLineBiDi   is the object that will now represent a line of the paragraph.
pErrorCode   must be a valid pointer to an error code value, which must not indicate a failure before the function call.

See also:
ubidi_setPara

Referenced by BiDi::setLine().

U_CAPI void U_EXPORT2 ubidi_setPara ( UBiDi * pBiDi,
const UChar * text,
UTextOffset length,
UBiDiLevel paraLevel,
UBiDiLevel * embeddingLevels,
UErrorCode * pErrorCode )
 

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 .

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

If the entire paragraph consists of text of only one direction, 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.
For example, in pure LTR text with numbers the numbers would get a resolved level of 2 higher than the surrounding text according to 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.

Parameters:
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.
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. This pointer is stored in the UBiDi object and can be retrieved with ubidi_getText().
length   is the length of the text; if length==-1 then the text must be zero-terminated.
paraLevel   specifies the default level for the paragraph; 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.
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.

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

Caution: A copy of this pointer, not of the levels, will be stored in the UBiDi object; the embeddingLevels array must not be deallocated before the UBiDi structure is destroyed or reused, 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.

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.

Parameters:
pErrorCode   must be a valid pointer to an error code value, which must not indicate a failure before the function call.

Referenced by BiDi::setPara().

U_CAPI UTextOffset U_EXPORT2 ubidi_writeReordered ( UBiDi * pBiDi,
UChar * dest,
int32_t destSize,
uint16_t options,
UErrorCode * pErrorCode )
 

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.

This function preserves the integrity of characters with multiple code units and (optionally) modifier letters. Characters in RTL runs can be replaced by mirror-image characters in the destination buffer. Note that "real" mirroring has to be done in a rendering engine by glyph selection and that for many "mirrored" characters there are no Unicode characters as mirror-image equivalents. There are also options to insert or remove BiDi control characters; see the description of the destSize and options parameters and of the option bit flags.

Parameters:
pBiDi   A pointer to a UBiDi object that 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 without copying the contents) and must not have been modified since the ubidi_setPara() call.

Parameters:
dest   A pointer to where the reordered text is to be copied. The source text and dest[destSize] must not overlap.
destSize   The size of the dest buffer, in number of UChars. If the UBIDI_INSERT_LRM_FOR_NUMERIC option is set, then the destination length could be as large as ubidi_getLength(pBiDi)+2*ubidi_countRuns(pBiDi). If the UBIDI_REMOVE_BIDI_CONTROLS option is set, then the destination length may be less than ubidi_getLength(pBiDi). If none of these options is set, then the destination length will be exactly ubidi_getLength(pBiDi).
options   A bit set of options for the reordering that control how the reordered text is written. The options include mirroring the characters on a code point basis and inserting LRM characters, which is used especially for transforming visually stored text 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).
pErrorCode   must be a valid pointer to an error code value, which must not indicate a failure before the function call.

Returns:
The number of characters that were written to dest.

Referenced by BiDi::writeReordered().

U_CAPI UTextOffset U_EXPORT2 ubidi_writeReverse ( const UChar * src,
int32_t srcLength,
UChar * dest,
int32_t destSize,
uint16_t options,
UErrorCode * pErrorCode )
 

Reverse a Right-To-Left run of Unicode text.

This function preserves the integrity of characters with multiple code units and (optionally) modifier letters. Characters can be replaced by mirror-image characters in the destination buffer. Note that "real" mirroring has to be done in a rendering engine by glyph selection and that for many "mirrored" characters there are no Unicode characters as mirror-image equivalents. There are also options to insert or remove BiDi control characters.

This function is the implementation for reversing RTL runs as part of ubidi_writeReordered(). For detailed descriptions of the parameters, see there. Since no BiDi controls are inserted here, this function will never write more than srcLength characters to dest.

See also:
ubidi_writeReordered
Parameters:
src   A pointer to the RTL run text.
srcLength   The length of the RTL run.
dest   A pointer to where the reordered text is to be copied. src[srcLength] and dest[destSize] must not overlap.
destSize   The size of the dest buffer, in number of UChars. If the UBIDI_REMOVE_BIDI_CONTROLS option is set, then the destination length may be less than srcLength. If this option is not set, then the destination length will be exactly srcLength.
options   A bit set of options for the reordering that control how the reordered text is written. See ubidi_writeReordered().
pErrorCode   must be a valid pointer to an error code value, which must not indicate a failure before the function call.

Returns:
The number of characters that were written to dest.

Referenced by BiDi::writeReverse().


Generated at Tue Jun 12 14:04:06 2001 for ICU 1.8.1 by doxygen1.2.3 written by Dimitri van Heesch, © 1997-2000