#include "unicode/utypes.h"
#include "unicode/uchar.h"
Go to the source code of this file.
#define | UBIDI_DEFAULT_LTR 0xfe |
Paragraph level setting. | |
#define | UBIDI_DEFAULT_RTL 0xff |
Paragraph level setting. | |
#define | UBIDI_MAX_EXPLICIT_LEVEL 61 |
Maximum explicit embedding level. | |
#define | UBIDI_LEVEL_OVERRIDE 0x80 |
Bit flag for level input. | |
#define | UBIDI_MAP_NOWHERE (-1) |
Special value which can be returned by the mapping functions when a logical index has no corresponding visual index or vice-versa. | |
#define | UBIDI_KEEP_BASE_COMBINING 1 |
option bit for ubidi_writeReordered(): keep combining characters after their base characters in RTL runs | |
#define | UBIDI_DO_MIRRORING 2 |
option bit for ubidi_writeReordered(): replace characters with the "mirrored" property in RTL runs by their mirror-image mappings | |
#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 | |
#define | UBIDI_REMOVE_BIDI_CONTROLS 8 |
option bit for ubidi_writeReordered(): remove BiDi control characters (this does not affect UBIDI_INSERT_LRM_FOR_NUMERIC) | |
#define | UBIDI_OUTPUT_REVERSE 16 |
option bit for ubidi_writeReordered(): write the output in reverse order | |
#define | U_BIDI_CLASS_DEFAULT U_CHAR_DIRECTION_COUNT |
value returned by UBiDiClassCallback callbacks when there is no need to override the standard BiDi class for a given code point. | |
enum | UBiDiDirection { UBIDI_LTR, UBIDI_RTL, UBIDI_MIXED } |
UBiDiDirection values indicate the text direction. More... | |
enum | UBiDiReorderingMode { UBIDI_REORDER_DEFAULT = 0, UBIDI_REORDER_NUMBERS_SPECIAL, UBIDI_REORDER_GROUP_NUMBERS_WITH_R, UBIDI_REORDER_RUNS_ONLY, UBIDI_REORDER_INVERSE_NUMBERS_AS_L, UBIDI_REORDER_INVERSE_LIKE_DIRECT, UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL, UBIDI_REORDER_COUNT } |
UBiDiReorderingMode values indicate which variant of the BiDi algorithm to use. More... | |
enum | UBiDiReorderingOption { UBIDI_OPTION_DEFAULT = 0, UBIDI_OPTION_INSERT_MARKS = 1, UBIDI_OPTION_REMOVE_CONTROLS = 2, UBIDI_OPTION_STREAMING = 4 } |
UBiDiReorderingOption values indicate which options are specified to affect the BiDi algorithm. More... | |
typedef uint8_t | UBiDiLevel |
UBiDiLevel is the type of the level values in this BiDi implementation. | |
typedef enum UBiDiDirection | UBiDiDirection |
typedef UBiDi | UBiDi |
typedef UCharDirection U_CALLCONV | UBiDiClassCallback (const void *context, UChar32 c) |
Callback type declaration for overriding default BiDi class values with custom ones. | |
UBiDi * | ubidi_open (void) |
Allocate a UBiDi structure. | |
UBiDi * | ubidi_openSized (int32_t maxLength, int32_t maxRunCount, UErrorCode *pErrorCode) |
Allocate a UBiDi structure with preallocated memory for internal structures. | |
void | ubidi_close (UBiDi *pBiDi) |
ubidi_close() must be called to free the memory associated with a UBiDi object. | |
void | ubidi_setInverse (UBiDi *pBiDi, UBool isInverse) |
Modify the operation of the BiDi algorithm such that it approximates an "inverse BiDi" algorithm. | |
UBool | ubidi_isInverse (UBiDi *pBiDi) |
Is this BiDi object set to perform the inverse BiDi algorithm? | |
void | ubidi_orderParagraphsLTR (UBiDi *pBiDi, UBool orderParagraphsLTR) |
Specify whether block separators must be allocated level zero, so that successive paragraphs will progress from left to right. | |
UBool | ubidi_isOrderParagraphsLTR (UBiDi *pBiDi) |
Is this BiDi object set to allocate level 0 to block separators so that successive paragraphs progress from left to right? | |
void | ubidi_setReorderingMode (UBiDi *pBiDi, UBiDiReorderingMode reorderingMode) |
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". | |
UBiDiReorderingMode | ubidi_getReorderingMode (UBiDi *pBiDi) |
What is the requested reordering mode for a given BiDi object? | |
void | ubidi_setReorderingOptions (UBiDi *pBiDi, uint32_t reorderingOptions) |
Specify which of the reordering options should be applied during BiDi transformations. | |
uint32_t | ubidi_getReorderingOptions (UBiDi *pBiDi) |
What are the reordering options applied to a given BiDi object? | |
void | ubidi_setPara (UBiDi *pBiDi, const UChar *text, int32_t length, UBiDiLevel paraLevel, UBiDiLevel *embeddingLevels, UErrorCode *pErrorCode) |
Perform the Unicode BiDi algorithm. | |
void | ubidi_setLine (const UBiDi *pParaBiDi, int32_t start, int32_t 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. | |
UBiDiDirection | ubidi_getDirection (const UBiDi *pBiDi) |
Get the directionality of the text. | |
const UChar * | ubidi_getText (const UBiDi *pBiDi) |
Get the pointer to the text. | |
int32_t | ubidi_getLength (const UBiDi *pBiDi) |
Get the length of the text. | |
UBiDiLevel | ubidi_getParaLevel (const UBiDi *pBiDi) |
Get the paragraph level of the text. | |
int32_t | ubidi_countParagraphs (UBiDi *pBiDi) |
Get the number of paragraphs. | |
int32_t | ubidi_getParagraph (const UBiDi *pBiDi, int32_t charIndex, int32_t *pParaStart, int32_t *pParaLimit, UBiDiLevel *pParaLevel, UErrorCode *pErrorCode) |
Get a paragraph, given a position within the text. | |
void | ubidi_getParagraphByIndex (const UBiDi *pBiDi, int32_t paraIndex, int32_t *pParaStart, int32_t *pParaLimit, UBiDiLevel *pParaLevel, UErrorCode *pErrorCode) |
Get a paragraph, given the index of this paragraph. | |
UBiDiLevel | ubidi_getLevelAt (const UBiDi *pBiDi, int32_t charIndex) |
Get the level for one character. | |
const UBiDiLevel * | ubidi_getLevels (UBiDi *pBiDi, UErrorCode *pErrorCode) |
Get an array of levels for each character. | |
void | ubidi_getLogicalRun (const UBiDi *pBiDi, int32_t logicalStart, int32_t *pLogicalLimit, UBiDiLevel *pLevel) |
Get a logical run. | |
int32_t | ubidi_countRuns (UBiDi *pBiDi, UErrorCode *pErrorCode) |
Get the number of runs. | |
UBiDiDirection | ubidi_getVisualRun (UBiDi *pBiDi, int32_t runIndex, int32_t *pLogicalStart, int32_t *pLength) |
Get one run's logical start, length, and directionality, which can be 0 for LTR or 1 for RTL. | |
int32_t | ubidi_getVisualIndex (UBiDi *pBiDi, int32_t logicalIndex, UErrorCode *pErrorCode) |
Get the visual position from a logical text position. | |
int32_t | ubidi_getLogicalIndex (UBiDi *pBiDi, int32_t visualIndex, UErrorCode *pErrorCode) |
Get the logical text position from a visual position. | |
void | ubidi_getLogicalMap (UBiDi *pBiDi, int32_t *indexMap, UErrorCode *pErrorCode) |
Get a logical-to-visual index map (array) for the characters in the UBiDi (paragraph or line) object. | |
void | ubidi_getVisualMap (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. | |
void | ubidi_reorderLogical (const UBiDiLevel *levels, int32_t length, int32_t *indexMap) |
This is a convenience function that does not use a UBiDi object. | |
void | ubidi_reorderVisual (const UBiDiLevel *levels, int32_t length, int32_t *indexMap) |
This is a convenience function that does not use a UBiDi object. | |
void | ubidi_invertMap (const int32_t *srcMap, int32_t *destMap, int32_t length) |
Invert an index map. | |
int32_t | ubidi_getProcessedLength (const UBiDi *pBiDi) |
Get the length of the source text processed by the last call to ubidi_setPara() . | |
int32_t | ubidi_getResultLength (const UBiDi *pBiDi) |
Get the length of the reordered text resulting from the last call to ubidi_setPara() . | |
U_CDECL_END UCharDirection | ubidi_getCustomizedClass (UBiDi *pBiDi, UChar32 c) |
Retrieve the BiDi class for a given code point. | |
void | ubidi_setClassCallback (UBiDi *pBiDi, UBiDiClassCallback *newFn, const void *newContext, UBiDiClassCallback **oldFn, const void **oldContext, UErrorCode *pErrorCode) |
Set the callback function and callback data used by the UBA implementation for BiDi class determination. | |
void | ubidi_getClassCallback (UBiDi *pBiDi, UBiDiClassCallback **fn, const void **context) |
Get the current callback function used for BiDi class determination. | |
int32_t | ubidi_writeReordered (UBiDi *pBiDi, UChar *dest, int32_t destSize, uint16_t options, UErrorCode *pErrorCode) |
Take a UBiDi object containing the reordering 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. | |
int32_t | 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 is an implementation of the Unicode Bidirectional algorithm. The algorithm is defined in the 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". ICU's BiDi and shaping (u_shapeArabic()) APIs can be used at the core of such "Storage Layout Engines".
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.
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 { int32_t limit; Style style; } StyleRun; *int getTextWidth(const UChar *text, int32_t start, int32_t 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, int32_t start, int32_t *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, int32_t start, int32_t 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, int32_t start, int32_t 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, int32_t start, int32_t 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 int32_t 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 { int32_t 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, int32_t 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) { int32_t 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 U_BIDI_CLASS_DEFAULT U_CHAR_DIRECTION_COUNT |
value returned by UBiDiClassCallback
callbacks when there is no need to override the standard BiDi class for a given code point.
#define UBIDI_DEFAULT_LTR 0xfe |
#define UBIDI_DEFAULT_RTL 0xff |
#define UBIDI_DO_MIRRORING 2 |
option bit for ubidi_writeReordered(): replace characters with the "mirrored" property in RTL runs by their mirror-image mappings
#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
This option does not imply corresponding adjustment of the index mappings.
#define UBIDI_KEEP_BASE_COMBINING 1 |
option bit for ubidi_writeReordered(): keep combining characters after their base characters in RTL runs
#define UBIDI_LEVEL_OVERRIDE 0x80 |
#define UBIDI_MAP_NOWHERE (-1) |
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
.
#define UBIDI_MAX_EXPLICIT_LEVEL 61 |
#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.
#define UBIDI_REMOVE_BIDI_CONTROLS 8 |
option bit for ubidi_writeReordered(): remove BiDi control characters (this does not affect UBIDI_INSERT_LRM_FOR_NUMERIC)
This option does not imply corresponding adjustment of the index mappings.
typedef UCharDirection U_CALLCONV UBiDiClassCallback(const void *context, UChar32 c) |
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.
context | is a pointer to the callback private data. | |
c | is the code point to get a BiDi class for. |
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. typedef enum UBiDiDirection UBiDiDirection |
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:
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 pseudo-level values UBIDI_DEFAULT_LTR
and UBIDI_DEFAULT_RTL
.
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.
enum UBiDiDirection |
enum UBiDiReorderingMode |
UBiDiReorderingMode
values indicate which variant of the BiDi algorithm to use.
UBIDI_REORDER_DEFAULT |
Regular Logical to Visual BiDi algorithm according to Unicode.
This is a 0 value.
|
UBIDI_REORDER_NUMBERS_SPECIAL |
Logical to Visual algorithm which handles numbers in a way which mimicks the behavior of Windows XP.
|
UBIDI_REORDER_GROUP_NUMBERS_WITH_R |
Logical to Visual algorithm grouping numbers with adjacent R characters (reversible algorithm).
|
UBIDI_REORDER_RUNS_ONLY |
Reorder runs only to transform a Logical LTR string to the Logical RTL string with the same display, or vice-versa.
|
UBIDI_REORDER_INVERSE_NUMBERS_AS_L |
Visual to Logical algorithm which handles numbers like L (same algorithm as selected by ubidi_setInverse(TRUE) .
|
UBIDI_REORDER_INVERSE_LIKE_DIRECT |
Visual to Logical algorithm equivalent to the regular Logical to Visual algorithm.
|
UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL |
Inverse BiDi (Visual to Logical) algorithm for the UBIDI_REORDER_NUMBERS_SPECIAL BiDi algorithm.
|
UBIDI_REORDER_COUNT |
Number of values for reordering mode.
|
UBiDiReorderingOption
values indicate which options are specified to affect the BiDi algorithm.
UBIDI_OPTION_DEFAULT |
option value for ubidi_setReorderingOptions : disable all the options which can be set with this function
|
UBIDI_OPTION_INSERT_MARKS |
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 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
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
This option will be ignored if specified together with option
|
UBIDI_OPTION_REMOVE_CONTROLS |
option bit for ubidi_setReorderingOptions : remove BiDi control characters
This option must be set or reset before calling
This option nullifies option
|
UBIDI_OPTION_STREAMING |
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 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,
When the
|
void ubidi_close | ( | UBiDi * | pBiDi | ) |
ubidi_close()
must be called to free the memory associated with a UBiDi object.
Important: 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()
) before the parent object.
pBiDi | is a UBiDi object. |
Get the number of paragraphs.
pBiDi | is the paragraph or line UBiDi object. |
int32_t 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.
pBiDi | is the paragraph or line UBiDi object. | |
pErrorCode | must be a valid pointer to an error code value. |
void ubidi_getClassCallback | ( | UBiDi * | pBiDi, | |
UBiDiClassCallback ** | fn, | |||
const void ** | context | |||
) |
Get the current callback function used for BiDi class determination.
pBiDi | is the paragraph UBiDi object. | |
fn | fillin: Returns the callback function pointer. | |
context | fillin: Returns the callback's private context. |
U_CDECL_END UCharDirection ubidi_getCustomizedClass | ( | UBiDi * | pBiDi, | |
UChar32 | c | |||
) |
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.
pBiDi | is the paragraph UBiDi object. | |
c | is the code point whose BiDi class must be retrieved. |
c
based on the given pBiDi
instance. UBiDiDirection ubidi_getDirection | ( | const UBiDi * | pBiDi | ) |
Get the directionality of the text.
pBiDi | is the paragraph or line UBiDi object. |
UBIDI_XXX
value that indicates if the entire text represented by this object is unidirectional, and which direction, or if it is mixed-directional.Referenced by ParagraphLayout::getTextDirection().
Get the length of the text.
pBiDi | is the paragraph or line UBiDi object. |
UBiDiLevel ubidi_getLevelAt | ( | const UBiDi * | pBiDi, | |
int32_t | charIndex | |||
) |
Get the level for one character.
pBiDi | is the paragraph or line UBiDi object. | |
charIndex | the index of a character. |
const UBiDiLevel* 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()
.
pBiDi | is the paragraph or line UBiDi object, whose text length must be strictly positive. | |
pErrorCode | must be a valid pointer to an error code value. |
NULL
if an error occurs.int32_t ubidi_getLogicalIndex | ( | UBiDi * | pBiDi, | |
int32_t | 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.
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()
.
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. |
void ubidi_getLogicalMap | ( | UBiDi * | pBiDi, | |
int32_t * | indexMap, | |||
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
.
pBiDi | is the paragraph or line UBiDi object. | |
indexMap | is a pointer to an array of ubidi_getProcessedLength() indexes which will reflect the reordering of the characters. 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 . | |
pErrorCode | must be a valid pointer to an error code value. |
void ubidi_getLogicalRun | ( | const UBiDi * | pBiDi, | |
int32_t | logicalStart, | |||
int32_t * | 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.
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. |
int32_t ubidi_getParagraph | ( | const UBiDi * | pBiDi, | |
int32_t | charIndex, | |||
int32_t * | pParaStart, | |||
int32_t * | pParaLimit, | |||
UBiDiLevel * | pParaLevel, | |||
UErrorCode * | pErrorCode | |||
) |
Get a paragraph, given a position within the text.
This function returns information about a paragraph.
pBiDi | is the paragraph or line UBiDi object. | |
charIndex | is the index of a character within the text, in the range [0..ubidi_getProcessedLength(pBiDi)-1] . | |
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. | |
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. | |
pParaLevel | will receive the level of the paragraph. This pointer can be NULL if this value is not necessary. | |
pErrorCode | must be a valid pointer to an error code value. |
void ubidi_getParagraphByIndex | ( | const UBiDi * | pBiDi, | |
int32_t | paraIndex, | |||
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.
pBiDi | is the paragraph UBiDi object. | |
paraIndex | is the number of the paragraph, in the range [0..ubidi_countParagraphs(pBiDi)-1] . | |
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. | |
pParaLimit | will receive the limit of the paragraph. This pointer can be NULL if this value is not necessary. | |
pParaLevel | will receive the level of the paragraph. This pointer can be NULL if this value is not necessary. | |
pErrorCode | must be a valid pointer to an error code value. |
UBiDiLevel ubidi_getParaLevel | ( | const UBiDi * | pBiDi | ) |
Get the paragraph level of the text.
pBiDi | is the paragraph or line UBiDi object. |
Referenced by ParagraphLayout::getParagraphLevel().
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:
limit
argument of ubidi_setLine
charIndex
argument of ubidi_getParagraph
charIndex
argument of ubidi_getLevelAt
ubidi_getLevels
logicalStart
argument of ubidi_getLogicalRun
logicalIndex
argument of ubidi_getVisualIndex
*indexMap
argument of ubidi_getLogicalMap
ubidi_writeReordered
pBiDi | is the paragraph UBiDi object. |
ubidi_setPara
. UBiDiReorderingMode ubidi_getReorderingMode | ( | UBiDi * | pBiDi | ) |
What is the requested reordering mode for a given BiDi object?
pBiDi | is a UBiDi object. |
What are the reordering options applied to a given BiDi object?
pBiDi | is a UBiDi object. |
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:
visualIndex
argument of ubidi_getLogicalIndex
*indexMap
argument of ubidi_getVisualMap
ubidi_writeReordered
, or if option UBIDI_REORDER_INVERSE_NUMBERS_AS_L
has been set.
pBiDi | is the paragraph UBiDi object. |
ubidi_setPara
. const UChar* ubidi_getText | ( | const UBiDi * | pBiDi | ) |
Get the pointer to the text.
pBiDi | is the paragraph or line UBiDi object. |
int32_t ubidi_getVisualIndex | ( | UBiDi * | pBiDi, | |
int32_t | 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.
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.
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. |
void ubidi_getVisualMap | ( | 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
.
pBiDi | is the paragraph or line UBiDi object. | |
indexMap | is a pointer to an array of ubidi_getResultLength() indexes which will reflect the reordering of the characters. 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 . | |
pErrorCode | must be a valid pointer to an error code value. |
UBiDiDirection ubidi_getVisualRun | ( | UBiDi * | pBiDi, | |
int32_t | runIndex, | |||
int32_t * | pLogicalStart, | |||
int32_t * | 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.
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. |
UBIDI_LTR==0
or UBIDI_RTL==1
, never UBIDI_MIXED
.int32_t 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.
Invert an index map.
The index mapping of the first map is inverted and written to the second one.
srcMap | is an array with length indexes 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 ). | |
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 | |
length | is the length of each array. |
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.
pBiDi | is a UBiDi object. |
Is this BiDi object set to allocate level 0 to block separators so that successive paragraphs progress from left to right?
pBiDi | is a UBiDi object. |
UBiDi* ubidi_open | ( | void | ) |
Allocate a UBiDi
structure.
Such an object is initially empty. It is assigned 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_setPara()
and ubidi_setLine()
will allocate additional memory for internal structures as necessary.
UBiDi
object. UBiDi* ubidi_openSized | ( | int32_t | maxLength, | |
int32_t | 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()
.
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. | |
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. | |
pErrorCode | must be a valid pointer to an error code value. |
UBiDi
object with preallocated memory. 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.
pBiDi | is a UBiDi object. | |
orderParagraphsLTR | specifies whether paragraph separators (B) must receive level 0, so that successive paragraphs progress from left to right. |
void 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_getLogicalMap()
on a UBiDi
object.
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. |
indexMap[logicalIndex]==visualIndex
. void ubidi_reorderVisual | ( | 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 UBiDi
object.
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. |
indexMap[visualIndex]==logicalIndex
. void ubidi_setClassCallback | ( | UBiDi * | pBiDi, | |
UBiDiClassCallback * | newFn, | |||
const void * | newContext, | |||
UBiDiClassCallback ** | oldFn, | |||
const void ** | oldContext, | |||
UErrorCode * | pErrorCode | |||
) |
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.
pBiDi | is the paragraph UBiDi object. | |
newFn | is the new callback function pointer. | |
newContext | is the new callback context pointer. This can be NULL. | |
oldFn | fillin: Returns the old callback function pointer. This can be NULL. | |
oldContext | fillin: Returns the old callback's context. This can be NULL. | |
pErrorCode | must be a valid pointer to an error code value. |
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 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. 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.
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
.
pBiDi | is a UBiDi object. | |
isInverse | specifies "forward" or "inverse" BiDi operation. |
void ubidi_setLine | ( | const UBiDi * | pParaBiDi, | |
int32_t | start, | |||
int32_t | 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 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 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 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.
pParaBiDi | is the parent paragraph object. It must have been set by a successful call to ubidi_setPara. | |
start | is the line's first index into the text. | |
limit | is just behind the line's last index into the text (its last index +1). 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. | |
pLineBiDi | is the object that will now represent a line of the text. | |
pErrorCode | must be a valid pointer to an error code value. |
void ubidi_setPara | ( | UBiDi * | pBiDi, | |
const UChar * | text, | |||
int32_t | length, | |||
UBiDiLevel | paraLevel, | |||
UBiDiLevel * | embeddingLevels, | |||
UErrorCode * | pErrorCode | |||
) |
Perform the Unicode BiDi algorithm.
It is defined in the Unicode Standard Anned #9, version 13, also described in The Unicode Standard, Version 4.0 .
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 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.
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 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.
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 text that the BiDi algorithm will be performed on. This pointer is stored in the UBiDi object and can be retrieved with ubidi_getText() .Note: the text must be (at least) length long. | |
length | is the length of the text; if length==-1 then the text must be zero-terminated. | |
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 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. | |
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 , 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 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.Note: the embeddingLevels array must be at least length long. | |
pErrorCode | must be a valid pointer to an error code value. |
void ubidi_setReorderingMode | ( | UBiDi * | pBiDi, | |
UBiDiReorderingMode | reorderingMode | |||
) |
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.
UBIDI_REORDER_DEFAULT
, the standard BiDi Logical to Visual algorithm is applied.
UBIDI_REORDER_NUMBERS_SPECIAL
, the algorithm used to perform BiDi transformations when calling ubidi_setPara
should approximate the algorithm used in Microsoft Windows XP rather than strictly conform to the Unicode BiDi algorithm.
UBIDI_REORDER_GROUP_NUMBERS_WITH_R
, numbers located between LTR text and RTL text are associated with the RTL text. For instance, an LTR paragraph with content "abc 123 DEF" (where upper case letters represent RTL characters) will be transformed to "abc FED 123" (and not "abc 123 FED"), "DEF 123 abc" will be transformed to "123 FED abc" and "123 FED abc" will be transformed to "DEF 123 abc". This makes the algorithm reversible and makes it useful when round trip (from visual to logical and back to visual) must be achieved without adding LRM characters. However, this is a variation from the standard Unicode Bidi algorithm.
UBIDI_REORDER_RUNS_ONLY
, a "Logical to Logical" transformation must be performed: paraLevel
in ubidi_setPara
) is even, the source text will be handled as LTR logical text and will be transformed to the RTL logical text which has the same LTR visual display.
UBIDI_REORDER_INVERSE_NUMBERS_AS_L
, an "inverse BiDi" algorithm is applied. Runs of text with numeric characters will be treated like LTR letters and may need to be surrounded with LRM characters when they are written in reordered sequence (the option UBIDI_INSERT_LRM_FOR_NUMERIC
can be used with function ubidi_writeReordered
to this end. This mode is equivalent to calling ubidi_setInverse()
with argument isInverse
set to TRUE
.
UBIDI_REORDER_INVERSE_LIKE_DIRECT
, the "direct" Logical to Visual BiDi algorithm is used as an approximation of an "inverse BiDi" algorithm. This mode is similar to mode UBIDI_REORDER_INVERSE_NUMBERS_AS_L
but is closer to the regular BiDi algorithm. UBIDI_REORDER_INVERSE_NUMBERS_AS_L
.UBIDI_OPTION_INSERT_MARKS
, this mode generally adds BiDi marks to the output significantly more sparingly than mode UBIDI_REORDER_INVERSE_NUMBERS_AS_L
with option UBIDI_INSERT_LRM_FOR_NUMERIC
in calls to ubidi_writeReordered
.
UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL
, the Logical to Visual BiDi algorithm used in Windows XP is used as an approximation of an "inverse BiDi" algorithm.
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
.
pBiDi | is a UBiDi object. | |
reorderingMode | specifies the required variant of the BiDi algorithm. |
Specify which of the reordering options should be applied during BiDi transformations.
pBiDi | is a UBiDi object. | |
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 . |
int32_t ubidi_writeReordered | ( | UBiDi * | pBiDi, | |
UChar * | dest, | |||
int32_t | destSize, | |||
uint16_t | options, | |||
UErrorCode * | pErrorCode | |||
) |
Take a UBiDi
object containing the reordering 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. 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.
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. | |
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). The available options are: UBIDI_DO_MIRRORING , UBIDI_INSERT_LRM_FOR_NUMERIC , UBIDI_KEEP_BASE_COMBINING , UBIDI_OUTPUT_REVERSE , UBIDI_REMOVE_BIDI_CONTROLS | |
pErrorCode | must be a valid pointer to an error code value. |
int32_t 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, the output string length will never exceed srcLength
.
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 the options parameter in ubidi_writeReordered() . | |
pErrorCode | must be a valid pointer to an error code value. |