w32tex
About: TeX Live provides a comprehensive TeX system including all the major TeX-related programs, macro packages, and fonts that are free software. Windows sources.
  Fossies Dox: w32tex-src.tar.xz  ("unofficial" and yet experimental doxygen-generated source code documentation)  

ubidi.h File Reference

C API: Bidi algorithm. More...

#include "unicode/utypes.h"
#include "unicode/uchar.h"
Include dependency graph for ubidi.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define UBIDI_DEFAULT_LTR   0xfe
 
#define UBIDI_DEFAULT_RTL   0xff
 
#define UBIDI_MAX_EXPLICIT_LEVEL   125
 
#define UBIDI_LEVEL_OVERRIDE   0x80
 
#define UBIDI_MAP_NOWHERE   (-1)
 
#define UBIDI_KEEP_BASE_COMBINING   1
 
#define UBIDI_DO_MIRRORING   2
 
#define UBIDI_INSERT_LRM_FOR_NUMERIC   4
 
#define UBIDI_REMOVE_BIDI_CONTROLS   8
 
#define UBIDI_OUTPUT_REVERSE   16
 
#define U_BIDI_CLASS_DEFAULT   U_CHAR_DIRECTION_COUNT
 

Typedefs

typedef uint8_t UBiDiLevel
 
typedef enum UBiDiDirection UBiDiDirection
 
typedef struct UBiDi UBiDi
 
typedef enum UBiDiReorderingMode UBiDiReorderingMode
 
typedef enum UBiDiReorderingOption UBiDiReorderingOption
 
typedef UCharDirection UBiDiClassCallback(const void *context, UChar32 c)
 

Enumerations

enum  UBiDiDirection { UBIDI_LTR , UBIDI_RTL , UBIDI_MIXED , UBIDI_NEUTRAL }
 
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
}
 
enum  UBiDiReorderingOption { UBIDI_OPTION_DEFAULT = 0 , UBIDI_OPTION_INSERT_MARKS = 1 , UBIDI_OPTION_REMOVE_CONTROLS = 2 , UBIDI_OPTION_STREAMING = 4 }
 

Functions

UBiDiubidi_open_68 (void)
 
UBiDiubidi_openSized_68 (int32_t maxLength, int32_t maxRunCount, UErrorCode *pErrorCode)
 
void ubidi_close_68 (UBiDi *pBiDi)
 
void ubidi_setInverse_68 (UBiDi *pBiDi, UBool isInverse)
 
UBool ubidi_isInverse_68 (UBiDi *pBiDi)
 
void ubidi_orderParagraphsLTR_68 (UBiDi *pBiDi, UBool orderParagraphsLTR)
 
UBool ubidi_isOrderParagraphsLTR_68 (UBiDi *pBiDi)
 
void ubidi_setReorderingMode_68 (UBiDi *pBiDi, UBiDiReorderingMode reorderingMode)
 
UBiDiReorderingMode ubidi_getReorderingMode_68 (UBiDi *pBiDi)
 
void ubidi_setReorderingOptions_68 (UBiDi *pBiDi, uint32_t reorderingOptions)
 
uint32_t ubidi_getReorderingOptions_68 (UBiDi *pBiDi)
 
void ubidi_setContext_68 (UBiDi *pBiDi, const UChar *prologue, int32_t proLength, const UChar *epilogue, int32_t epiLength, UErrorCode *pErrorCode)
 
void ubidi_setPara_68 (UBiDi *pBiDi, const UChar *text, int32_t length, UBiDiLevel paraLevel, UBiDiLevel *embeddingLevels, UErrorCode *pErrorCode)
 
void ubidi_setLine_68 (const UBiDi *pParaBiDi, int32_t start, int32_t limit, UBiDi *pLineBiDi, UErrorCode *pErrorCode)
 
UBiDiDirection ubidi_getDirection_68 (const UBiDi *pBiDi)
 
UBiDiDirection ubidi_getBaseDirection_68 (const UChar *text, int32_t length)
 
const UCharubidi_getText_68 (const UBiDi *pBiDi)
 
int32_t ubidi_getLength_68 (const UBiDi *pBiDi)
 
UBiDiLevel ubidi_getParaLevel_68 (const UBiDi *pBiDi)
 
int32_t ubidi_countParagraphs_68 (UBiDi *pBiDi)
 
int32_t ubidi_getParagraph_68 (const UBiDi *pBiDi, int32_t charIndex, int32_t *pParaStart, int32_t *pParaLimit, UBiDiLevel *pParaLevel, UErrorCode *pErrorCode)
 
void ubidi_getParagraphByIndex_68 (const UBiDi *pBiDi, int32_t paraIndex, int32_t *pParaStart, int32_t *pParaLimit, UBiDiLevel *pParaLevel, UErrorCode *pErrorCode)
 
UBiDiLevel ubidi_getLevelAt_68 (const UBiDi *pBiDi, int32_t charIndex)
 
const UBiDiLevelubidi_getLevels_68 (UBiDi *pBiDi, UErrorCode *pErrorCode)
 
void ubidi_getLogicalRun_68 (const UBiDi *pBiDi, int32_t logicalPosition, int32_t *pLogicalLimit, UBiDiLevel *pLevel)
 
int32_t ubidi_countRuns_68 (UBiDi *pBiDi, UErrorCode *pErrorCode)
 
UBiDiDirection ubidi_getVisualRun_68 (UBiDi *pBiDi, int32_t runIndex, int32_t *pLogicalStart, int32_t *pLength)
 
int32_t ubidi_getVisualIndex_68 (UBiDi *pBiDi, int32_t logicalIndex, UErrorCode *pErrorCode)
 
int32_t ubidi_getLogicalIndex_68 (UBiDi *pBiDi, int32_t visualIndex, UErrorCode *pErrorCode)
 
void ubidi_getLogicalMap_68 (UBiDi *pBiDi, int32_t *indexMap, UErrorCode *pErrorCode)
 
void ubidi_getVisualMap_68 (UBiDi *pBiDi, int32_t *indexMap, UErrorCode *pErrorCode)
 
void ubidi_reorderLogical_68 (const UBiDiLevel *levels, int32_t length, int32_t *indexMap)
 
void ubidi_reorderVisual_68 (const UBiDiLevel *levels, int32_t length, int32_t *indexMap)
 
void ubidi_invertMap_68 (const int32_t *srcMap, int32_t *destMap, int32_t length)
 
int32_t ubidi_getProcessedLength_68 (const UBiDi *pBiDi)
 
int32_t ubidi_getResultLength_68 (const UBiDi *pBiDi)
 
UCharDirection ubidi_getCustomizedClass_68 (UBiDi *pBiDi, UChar32 c)
 
void ubidi_setClassCallback_68 (UBiDi *pBiDi, UBiDiClassCallback *newFn, const void *newContext, UBiDiClassCallback **oldFn, const void **oldContext, UErrorCode *pErrorCode)
 
void ubidi_getClassCallback_68 (UBiDi *pBiDi, UBiDiClassCallback **fn, const void **context)
 
int32_t ubidi_writeReordered_68 (UBiDi *pBiDi, UChar *dest, int32_t destSize, uint16_t options, UErrorCode *pErrorCode)
 
int32_t ubidi_writeReverse_68 (const UChar *src, int32_t srcLength, UChar *dest, int32_t destSize, uint16_t options, UErrorCode *pErrorCode)
 

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 Standard Annex #9.

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

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

  • Rendering is done from left to right on a horizontal line.
  • A run of single-style, unidirectional text can be rendered at once.
  • Such a run of text is passed to the graphics system with characters (code units) in logical order.
  • The line-breaking algorithm is very complicated and Locale-dependent - and therefore its implementation omitted from this sample code.
*#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,
const StyleRun *styleRuns, int styleRunCount) {
int i;
// iterate over style runs
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,
const StyleRun *styleRuns, int styleRunCount) {
// unidirectional
if(styleRunCount<=1) {
renderRun(text, start, limit, direction, styleRuns[0].style);
} else {
renderDirectionalRun(text, start, limit,
direction, styleRuns, styleRunCount);
}
} else {
// mixed-directional
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) {
}
} else {
// iterate over both directional and style runs
for(i=0; i<count; ++i) {
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; }
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 {
// we need to render several lines
line=ubidi_openSized(length, 0, pErrorCode);
if(line!=NULL) {
int styleRunStart=0, styleRunLimit;
for(;;) {
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; }
styleRunStart=styleRunLimit-1;
if(start>=styleRuns[styleRunStart].limit) {
++styleRunStart;
}
}
}
}
}
ubidi_close(para);
*}
*
int level
Definition: afm2pl.c:1694
#define width(a)
Definition: aptex-macros.h:198
#define count(a)
Definition: aptex-macros.h:781
integer include[40][2]
Definition: dvidvi.c:170
unsigned char UChar
Definition: bzip2.c:163
#define NULL
Definition: ftobjs.h:61
small capitals from c petite p scientific i
Definition: afcover.h:80
Arabic default style
Definition: afstyles.h:94
signed int int32_t
Definition: stdint.h:77
#define length(c)
Definition: ctangleboot.c:65
char line[1024]
Definition: process_score.c:29
#define direction(p, c)
Definition: sh12.c:109
Definition: bdf.c:133
int j
Definition: t4ht.c:1589
#define UBIDI_DEFAULT_RTL
Definition: ubidi.h:392
#define UBIDI_DEFAULT_LTR
Definition: ubidi.h:365
UBiDiDirection
Definition: ubidi.h:428
@ UBIDI_LTR
Definition: ubidi.h:440
@ UBIDI_MIXED
Definition: ubidi.h:459
uint8_t UBiDiLevel
Definition: ubidi.h:339
#define ubidi_setPara
Definition: urename.h:476
#define ubidi_close
Definition: urename.h:427
#define ubidi_setLine
Definition: urename.h:475
#define ubidi_getDirection
Definition: urename.h:434
#define ubidi_getVisualRun
Definition: urename.h:460
#define ubidi_countRuns
Definition: urename.h:429
#define ubidi_getParaLevel
Definition: urename.h:448
#define ubidi_openSized
Definition: urename.h:468
@ start
Definition: preamble.c:52
UErrorCode
Definition: utypes.h:431
#define U_FAILURE(x)
Definition: utypes.h:735
#define U_SUCCESS(x)
Definition: utypes.h:730
#define limit(x)
Definition: yuvsplittoppm.c:26

Definition in file ubidi.h.

Macro Definition Documentation

◆ U_BIDI_CLASS_DEFAULT

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

This constant is deprecated; use u_getIntPropertyMaxValue(UCHAR_BIDI_CLASS)+1 instead.

See also
UBiDiClassCallback
Deprecated:
ICU 58 The numeric value may change over time, see ICU ticket #12420.

Definition at line 1991 of file ubidi.h.

◆ UBIDI_DEFAULT_LTR

#define UBIDI_DEFAULT_LTR   0xfe

Paragraph level setting.

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

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

If reordering option UBIDI_OPTION_INSERT_MARKS is set, an RLM may be added at the beginning of the result string to ensure round trip (that the result string, when reordered back to visual, will produce the original source text).

See also
UBIDI_REORDER_INVERSE_LIKE_DIRECT
UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL @stable ICU 2.0

Definition at line 365 of file ubidi.h.

◆ UBIDI_DEFAULT_RTL

#define UBIDI_DEFAULT_RTL   0xff

Paragraph level setting.

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

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

If reordering option UBIDI_OPTION_INSERT_MARKS is set, an RLM may be added at the beginning of the result string to ensure round trip (that the result string, when reordered back to visual, will produce the original source text).

See also
UBIDI_REORDER_INVERSE_LIKE_DIRECT
UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL @stable ICU 2.0

Definition at line 392 of file ubidi.h.

◆ UBIDI_DO_MIRRORING

#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 @stable ICU 2.0

Definition at line 1863 of file ubidi.h.

◆ UBIDI_INSERT_LRM_FOR_NUMERIC

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

See also
ubidi_setInverse
ubidi_writeReordered @stable ICU 2.0

Definition at line 1877 of file ubidi.h.

◆ UBIDI_KEEP_BASE_COMBINING

#define UBIDI_KEEP_BASE_COMBINING   1

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

See also
ubidi_writeReordered @stable ICU 2.0

Definition at line 1853 of file ubidi.h.

◆ UBIDI_LEVEL_OVERRIDE

#define UBIDI_LEVEL_OVERRIDE   0x80

Bit flag for level input. Overrides directional properties. @stable ICU 2.0

Definition at line 407 of file ubidi.h.

◆ UBIDI_MAP_NOWHERE

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

See also
ubidi_getVisualIndex
ubidi_getVisualMap
ubidi_getLogicalIndex
ubidi_getLogicalMap @stable ICU 3.6

Definition at line 422 of file ubidi.h.

◆ UBIDI_MAX_EXPLICIT_LEVEL

#define UBIDI_MAX_EXPLICIT_LEVEL   125

Maximum explicit embedding level. Same as the max_depth value in the Unicode Bidirectional Algorithm. (The maximum resolved level can be up to UBIDI_MAX_EXPLICIT_LEVEL+1). @stable ICU 2.0

Definition at line 401 of file ubidi.h.

◆ UBIDI_OUTPUT_REVERSE

#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 @stable ICU 2.0

Definition at line 1906 of file ubidi.h.

◆ UBIDI_REMOVE_BIDI_CONTROLS

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

See also
ubidi_writeReordered @stable ICU 2.0

Definition at line 1890 of file ubidi.h.

Typedef Documentation

◆ UBiDi

typedef struct UBiDi UBiDi

@stable ICU 2.0

Definition at line 339 of file ubidi.h.

◆ UBiDiClassCallback

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

Parameters
contextis a pointer to the callback private data.
cis the code point to get a Bidi class for.
Returns
The directional property / Bidi class for the given code point c if the default class has been overridden, or u_getIntPropertyMaxValue(UCHAR_BIDI_CLASS)+1 if the standard Bidi class value for c is to be used.
See also
ubidi_setClassCallback
ubidi_getClassCallback @stable ICU 3.6

Definition at line 2015 of file ubidi.h.

◆ UBiDiDirection

@stable ICU 2.0

Definition at line 339 of file ubidi.h.

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

Note: The numeric values of the related constants will not change: They are tied to the use of 7-bit byte values (plus the override bit) and of the UBiDiLevel=uint8_t data type in this API.

See also
UBIDI_DEFAULT_LTR
UBIDI_DEFAULT_RTL
UBIDI_LEVEL_OVERRIDE
UBIDI_MAX_EXPLICIT_LEVEL @stable ICU 2.0

Definition at line 339 of file ubidi.h.

◆ UBiDiReorderingMode

UBiDiReorderingMode values indicate which variant of the Bidi algorithm to use.

See also
ubidi_setReorderingMode @stable ICU 3.6

◆ UBiDiReorderingOption

UBiDiReorderingOption values indicate which options are specified to affect the Bidi algorithm.

See also
ubidi_setReorderingOptions @stable ICU 3.6

Enumeration Type Documentation

◆ UBiDiDirection

UBiDiDirection values indicate the text direction. @stable ICU 2.0

Enumerator
UBIDI_LTR 

Left-to-right text. This is a 0 value.

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

@stable ICU 2.0

UBIDI_RTL 

Right-to-left text. This is a 1 value.

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

@stable ICU 2.0

UBIDI_MIXED 

Mixed-directional text.

As return value for ubidi_getDirection(), it means that the source string contains both left-to-right and right-to-left characters. @stable ICU 2.0

UBIDI_NEUTRAL 

No strongly directional text.

As return value for ubidi_getBaseDirection(), it means that the source string is missing or empty, or contains neither left-to-right nor right-to-left characters. @stable ICU 4.6

Definition at line 428 of file ubidi.h.

◆ UBiDiReorderingMode

UBiDiReorderingMode values indicate which variant of the Bidi algorithm to use.

See also
ubidi_setReorderingMode @stable ICU 3.6
Enumerator
UBIDI_REORDER_DEFAULT 

Regular Logical to Visual Bidi algorithm according to Unicode. This is a 0 value. @stable ICU 3.6

UBIDI_REORDER_NUMBERS_SPECIAL 

Logical to Visual algorithm which handles numbers in a way which mimics the behavior of Windows XP. @stable ICU 3.6

UBIDI_REORDER_GROUP_NUMBERS_WITH_R 

Logical to Visual algorithm grouping numbers with adjacent R characters (reversible algorithm). @stable ICU 3.6

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.
If this mode is set together with option UBIDI_OPTION_INSERT_MARKS, some Bidi controls in the source text may be removed and other controls may be added to produce the minimum combination which has the required display. @stable ICU 3.6

UBIDI_REORDER_INVERSE_NUMBERS_AS_L 

Visual to Logical algorithm which handles numbers like L (same algorithm as selected by ubidi_setInverse(true).

See also
ubidi_setInverse @stable ICU 3.6
UBIDI_REORDER_INVERSE_LIKE_DIRECT 

Visual to Logical algorithm equivalent to the regular Logical to Visual algorithm. @stable ICU 3.6

UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL 

Inverse Bidi (Visual to Logical) algorithm for the UBIDI_REORDER_NUMBERS_SPECIAL Bidi algorithm. @stable ICU 3.6

UBIDI_REORDER_COUNT 

Number of values for reordering mode.

Deprecated:
ICU 58 The numeric value may change over time, see ICU ticket #12420.

Definition at line 698 of file ubidi.h.

◆ UBiDiReorderingOption

UBiDiReorderingOption values indicate which options are specified to affect the Bidi algorithm.

See also
ubidi_setReorderingOptions @stable ICU 3.6
Enumerator
UBIDI_OPTION_DEFAULT 

option value for ubidi_setReorderingOptions: disable all the options which can be set with this function

See also
ubidi_setReorderingOptions @stable ICU 3.6
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 ubidi_setPara.

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

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

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

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

See also
ubidi_setReorderingMode
ubidi_setReorderingOptions @stable ICU 3.6
UBIDI_OPTION_REMOVE_CONTROLS 

option bit for ubidi_setReorderingOptions: remove Bidi control characters

This option must be set or reset before calling ubidi_setPara.

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

See also
ubidi_setReorderingMode
ubidi_setReorderingOptions @stable ICU 3.6
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 ubidi_setPara.

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

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

  • submit a larger amount of text with a better chance to include a reasonable boundary.
  • resubmit the same text after turning off option UBIDI_OPTION_STREAMING.

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

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

See also
ubidi_setReorderingMode
ubidi_setReorderingOptions
ubidi_getProcessedLength
ubidi_orderParagraphsLTR @stable ICU 3.6

Definition at line 913 of file ubidi.h.

Function Documentation

◆ ubidi_close_68()

void ubidi_close_68 ( 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.

Parameters
pBiDiis a UBiDi object.
See also
ubidi_setPara
ubidi_setLine @stable ICU 2.0

Definition at line 238 of file ubidi.cpp.

References UBiDi::dirPropsMemory, UBiDi::insertPoints, UBiDi::isolatesMemory, UBiDi::levelsMemory, NULL, UBiDi::openingsMemory, UBiDi::parasMemory, InsertPoints::points, UBiDi::pParaBiDi, UBiDi::runsMemory, and uprv_free.

◆ ubidi_countParagraphs_68()

int32_t ubidi_countParagraphs_68 ( UBiDi pBiDi)

Get the number of paragraphs.

Parameters
pBiDiis the paragraph or line UBiDi object.
Returns
The number of paragraphs. @stable ICU 3.4

Definition at line 2930 of file ubidi.cpp.

References IS_VALID_PARA_OR_LINE, and UBiDi::paraCount.

◆ ubidi_countRuns_68()

int32_t ubidi_countRuns_68 ( 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
pBiDiis the paragraph or line UBiDi object.
pErrorCodemust be a valid pointer to an error code value.
Returns
The number of runs. @stable ICU 2.0

Definition at line 352 of file ubidiln.cpp.

References RETURN_IF_NOT_VALID_PARA_OR_LINE, RETURN_IF_NULL_OR_FAILING_ERRCODE, UBiDi::runCount, U_FAILURE, and ubidi_getRuns.

◆ ubidi_getBaseDirection_68()

UBiDiDirection ubidi_getBaseDirection_68 ( const UChar text,
int32_t  length 
)

Gets the base direction of the text provided according to the Unicode Bidirectional Algorithm. The base direction is derived from the first character in the string with bidirectional character type L, R, or AL. If the first such character has type L, UBIDI_LTR is returned. If the first such character has type R or AL, UBIDI_RTL is returned. If the string does not contain any character of these types, then UBIDI_NEUTRAL is returned.

This is a lightweight function for use when only the base direction is needed and no further bidi processing of the text is needed.

Parameters
textis a pointer to the text whose base direction is needed. Note: the text must be (at least) length long.
lengthis the length of the text; if length==-1 then the text must be zero-terminated.
Returns
UBIDI_LTR, UBIDI_RTL, UBIDI_NEUTRAL
See also
UBiDiDirection @stable ICU 4.6

Definition at line 340 of file ubidi.cpp.

References dir, i, length, NULL, U16_NEXT, u_charDirection, U_LEFT_TO_RIGHT, U_RIGHT_TO_LEFT, U_RIGHT_TO_LEFT_ARABIC, u_strlen, UBIDI_LTR, UBIDI_NEUTRAL, UBIDI_RTL, and uchar.

◆ ubidi_getClassCallback_68()

void ubidi_getClassCallback_68 ( UBiDi pBiDi,
UBiDiClassCallback **  fn,
const void **  context 
)

Get the current callback function used for Bidi class determination.

Parameters
pBiDiis the paragraph UBiDi object.
fnfillin: Returns the callback function pointer.
contextfillin: Returns the callback's private context.
See also
ubidi_setClassCallback @stable ICU 3.6

Definition at line 3007 of file ubidi.cpp.

References UBiDi::coClassCallback, fc-lang::fn, UBiDi::fnClassCallback, and NULL.

◆ ubidi_getCustomizedClass_68()

UCharDirection ubidi_getCustomizedClass_68 ( 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_getIntPropertyMaxValue(UCHAR_BIDI_CLASS)+1, that value is used; otherwise the default class determination mechanism is invoked.

Parameters
pBiDiis the paragraph UBiDi object.
cis the code point whose Bidi class must be retrieved.
Returns
The Bidi class for character c based on the given pBiDi instance.
See also
UBiDiClassCallback @stable ICU 3.6

Definition at line 3023 of file ubidi.cpp.

References c, UBiDi::coClassCallback, dir, UBiDi::fnClassCallback, NULL, ON, U_BIDI_CLASS_DEFAULT, U_CHAR_DIRECTION_COUNT, and ubidi_getClass.

◆ ubidi_getDirection_68()

UBiDiDirection ubidi_getDirection_68 ( const UBiDi pBiDi)

Get the directionality of the text.

Parameters
pBiDiis the paragraph or line UBiDi object.
Returns
a value of UBIDI_LTR, UBIDI_RTL or UBIDI_MIXED that indicates if the entire text represented by this object is unidirectional, and which direction, or if it is mixed-directional. Note - The value UBIDI_NEUTRAL is never returned from this method.
See also
UBiDiDirection @stable ICU 2.0

Definition at line 2874 of file ubidi.cpp.

References UBiDi::direction, IS_VALID_PARA_OR_LINE, and UBIDI_LTR.

◆ ubidi_getLength_68()

int32_t ubidi_getLength_68 ( const UBiDi pBiDi)

Get the length of the text.

Parameters
pBiDiis the paragraph or line UBiDi object.
Returns
The length of the text that the UBiDi object was created for. @stable ICU 2.0

Definition at line 2892 of file ubidi.cpp.

References IS_VALID_PARA_OR_LINE, and UBiDi::originalLength.

◆ ubidi_getLevelAt_68()

UBiDiLevel ubidi_getLevelAt_68 ( const UBiDi pBiDi,
int32_t  charIndex 
)

Get the level for one character.

Parameters
pBiDiis the paragraph or line UBiDi object.
charIndexthe index of a character. It must be in the range [0..ubidi_getProcessedLength(pBiDi)].
Returns
The level for the character at charIndex (0 if charIndex is not in the valid range).
See also
UBiDiLevel
ubidi_getProcessedLength @stable ICU 2.0

Definition at line 251 of file ubidiln.cpp.

References UBiDi::direction, GET_PARALEVEL, IS_VALID_PARA_OR_LINE, length, UBiDi::levels, UBiDi::trailingWSStart, and UBIDI_MIXED.

◆ ubidi_getLevels_68()

const UBiDiLevel* ubidi_getLevels_68 ( 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
pBiDiis the paragraph or line UBiDi object, whose text length must be strictly positive.
pErrorCodemust be a valid pointer to an error code value.
Returns
The levels array for the text, or NULL if an error occurs.
See also
UBiDiLevel
ubidi_getProcessedLength @stable ICU 2.0

Definition at line 263 of file ubidiln.cpp.

References getLevelsMemory, length, UBiDi::length, UBiDi::levels, UBiDi::levelsMemory, NULL, UBiDi::paraLevel, RETURN_IF_NOT_VALID_PARA_OR_LINE, RETURN_IF_NULL_OR_FAILING_ERRCODE, start, UBiDi::trailingWSStart, U_ILLEGAL_ARGUMENT_ERROR, U_MEMORY_ALLOCATION_ERROR, uprv_memcpy, and uprv_memset.

◆ ubidi_getLogicalIndex_68()

int32_t ubidi_getLogicalIndex_68 ( 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().

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

Parameters
pBiDiis the paragraph or line UBiDi object.
visualIndexis the visual position of a character.
pErrorCodemust be a valid pointer to an error code value.
Returns
The index of this character in the text.
See also
ubidi_getVisualMap
ubidi_getVisualIndex
ubidi_getResultLength @stable ICU 2.0

Definition at line 985 of file ubidiln.cpp.

References begin, UBiDi::controlCount, UBiDi::direction, GET_INDEX, i, UBiDi::insertPoints, Run::insertRemove, IS_BIDI_CONTROL_CHAR, IS_EVEN_RUN, j, k, length, UBiDi::length, limit, Run::logicalStart, LRM_AFTER, LRM_BEFORE, REMOVE_ODD_BIT, UBiDi::resultLength, RETURN_IF_BAD_RANGE, RETURN_IF_NOT_VALID_PARA_OR_LINE, RETURN_IF_NULL_OR_FAILING_ERRCODE, RLM_AFTER, RLM_BEFORE, UBiDi::runCount, UBiDi::runs, InsertPoints::size, start, UBiDi::text, U_MEMORY_ALLOCATION_ERROR, ubidi_getRuns, UBIDI_LTR, UBIDI_MAP_NOWHERE, UBIDI_RTL, uchar, and Run::visualLimit.

◆ ubidi_getLogicalMap_68()

void ubidi_getLogicalMap_68 ( 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.

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

Note that in right-to-left runs, this mapping places second surrogates before first ones (which is generally a bad idea) and combining characters before base characters. Use of ubidi_writeReordered(), optionally with the UBIDI_KEEP_BASE_COMBINING option can be considered instead of using the mapping, in order to avoid these issues.

Parameters
pBiDiis the paragraph or line UBiDi object.
indexMapis 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.
pErrorCodemust be a valid pointer to an error code value.
See also
ubidi_getVisualMap
ubidi_getVisualIndex
ubidi_getProcessedLength
ubidi_getResultLength @stable ICU 2.0

Definition at line 1110 of file ubidiln.cpp.

References UBiDi::controlCount, GET_INDEX, i, UBiDi::insertPoints, Run::insertRemove, IS_BIDI_CONTROL_CHAR, IS_EVEN_RUN, j, k, length, UBiDi::length, Run::logicalStart, LRM_AFTER, LRM_BEFORE, NULL, REMOVE_ODD_BIT, UBiDi::resultLength, RETURN_VOID_IF_NULL_OR_FAILING_ERRCODE, RLM_AFTER, RLM_BEFORE, UBiDi::runCount, UBiDi::runs, InsertPoints::size, UBiDi::text, U_FAILURE, U_ILLEGAL_ARGUMENT_ERROR, ubidi_countRuns, UBIDI_MAP_NOWHERE, uchar, uprv_memset, and Run::visualLimit.

◆ ubidi_getLogicalRun_68()

void ubidi_getLogicalRun_68 ( const UBiDi pBiDi,
int32_t  logicalPosition,
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.

Parameters
pBiDiis the paragraph or line UBiDi object.
logicalPositionis a logical position within the source text.
pLogicalLimitwill receive the limit of the corresponding run. The l-value that you point to here may be the same expression (variable) as the one for logicalPosition. This pointer can be NULL if this value is not necessary.
pLevelwill receive the level of the corresponding run. This pointer can be NULL if this value is not necessary.
See also
ubidi_getProcessedLength @stable ICU 2.0

Definition at line 305 of file ubidiln.cpp.

References UBiDi::direction, errorCode, GET_INDEX, GET_ODD_BIT, GET_PARALEVEL, i, UBiDi::length, UBiDi::levels, Run::logicalStart, UBiDi::reorderingMode, RETURN_VOID_IF_BAD_RANGE, UBiDi::runs, UBiDi::trailingWSStart, U_FAILURE, U_ZERO_ERROR, ubidi_countRuns, UBIDI_MIXED, UBIDI_REORDER_RUNS_ONLY, and Run::visualLimit.

◆ ubidi_getParagraph_68()

int32_t ubidi_getParagraph_68 ( 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.
Note: if the paragraph index is known, it is more efficient to retrieve the paragraph information using ubidi_getParagraphByIndex().

Parameters
pBiDiis the paragraph or line UBiDi object.
charIndexis the index of a character within the text, in the range [0..ubidi_getProcessedLength(pBiDi)-1].
pParaStartwill receive the index of the first character of the paragraph in the text. This pointer can be NULL if this value is not necessary.
pParaLimitwill 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.
pParaLevelwill receive the level of the paragraph. This pointer can be NULL if this value is not necessary.
pErrorCodemust be a valid pointer to an error code value.
Returns
The index of the paragraph containing the specified position.
See also
ubidi_getProcessedLength @stable ICU 3.4

Definition at line 2967 of file ubidi.cpp.

References UBiDi::length, Para::limit, UBiDi::paras, UBiDi::pParaBiDi, RETURN_IF_BAD_RANGE, RETURN_IF_NOT_VALID_PARA_OR_LINE, RETURN_IF_NULL_OR_FAILING_ERRCODE, and ubidi_getParagraphByIndex.

◆ ubidi_getParagraphByIndex_68()

void ubidi_getParagraphByIndex_68 ( 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.

Parameters
pBiDiis the paragraph UBiDi object.
paraIndexis the number of the paragraph, in the range [0..ubidi_countParagraphs(pBiDi)-1].
pParaStartwill receive the index of the first character of the paragraph in the text. This pointer can be NULL if this value is not necessary.
pParaLimitwill receive the limit of the paragraph. This pointer can be NULL if this value is not necessary.
pParaLevelwill receive the level of the paragraph. This pointer can be NULL if this value is not necessary.
pErrorCodemust be a valid pointer to an error code value.

@stable ICU 3.4

Definition at line 2939 of file ubidi.cpp.

References GET_PARALEVEL, Para::limit, NULL, UBiDi::paraCount, UBiDi::paras, UBiDi::pParaBiDi, RETURN_VOID_IF_BAD_RANGE, RETURN_VOID_IF_NOT_VALID_PARA_OR_LINE, and RETURN_VOID_IF_NULL_OR_FAILING_ERRCODE.

◆ ubidi_getParaLevel_68()

UBiDiLevel ubidi_getParaLevel_68 ( const UBiDi pBiDi)

Get the paragraph level of the text.

Parameters
pBiDiis the paragraph or line UBiDi object.
Returns
The paragraph level. If there are multiple paragraphs, their level may vary if the required paraLevel is UBIDI_DEFAULT_LTR or UBIDI_DEFAULT_RTL. In that case, the level of the first paragraph is returned.
See also
UBiDiLevel
ubidi_getParagraph
ubidi_getParagraphByIndex @stable ICU 2.0

Definition at line 2921 of file ubidi.cpp.

References IS_VALID_PARA_OR_LINE, and UBiDi::paraLevel.

◆ ubidi_getProcessedLength_68()

int32_t ubidi_getProcessedLength_68 ( const UBiDi pBiDi)

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:

  • maximum value of the limit argument of ubidi_setLine
  • maximum value of the charIndex argument of ubidi_getParagraph
  • maximum value of the charIndex argument of ubidi_getLevelAt
  • number of elements in the array returned by ubidi_getLevels
  • maximum value of the logicalStart argument of ubidi_getLogicalRun
  • maximum value of the logicalIndex argument of ubidi_getVisualIndex
  • number of elements filled in the *indexMap argument of ubidi_getLogicalMap
  • length of text processed by ubidi_writeReordered
Parameters
pBiDiis the paragraph UBiDi object.
Returns
The length of the part of the source text processed by the last call to ubidi_setPara.
See also
ubidi_setPara
UBIDI_OPTION_STREAMING @stable ICU 3.6

Definition at line 2901 of file ubidi.cpp.

References IS_VALID_PARA_OR_LINE, and UBiDi::length.

◆ ubidi_getReorderingMode_68()

UBiDiReorderingMode ubidi_getReorderingMode_68 ( UBiDi pBiDi)

What is the requested reordering mode for a given Bidi object?

Parameters
pBiDiis a UBiDi object.
Returns
the current reordering mode of the Bidi object
See also
ubidi_setReorderingMode @stable ICU 3.6

Definition at line 312 of file ubidi.cpp.

References NULL, UBiDi::reorderingMode, and UBIDI_REORDER_DEFAULT.

◆ ubidi_getReorderingOptions_68()

uint32_t ubidi_getReorderingOptions_68 ( UBiDi pBiDi)

What are the reordering options applied to a given Bidi object?

Parameters
pBiDiis a UBiDi object.
Returns
the current reordering options of the Bidi object
See also
ubidi_setReorderingOptions @stable ICU 3.6

Definition at line 331 of file ubidi.cpp.

References NULL, and UBiDi::reorderingOptions.

◆ ubidi_getResultLength_68()

int32_t ubidi_getResultLength_68 ( const UBiDi pBiDi)

Get the length of the reordered text resulting from the last call to ubidi_setPara(). This length may be different from the length of the source text if option UBIDI_OPTION_INSERT_MARKS or option UBIDI_OPTION_REMOVE_CONTROLS has been set.
This resulting length is the one to consider in the following cases:

  • maximum value of the visualIndex argument of ubidi_getLogicalIndex
  • number of elements of the *indexMap argument of ubidi_getVisualMap

Note that this length stays identical to the source text length if Bidi marks are inserted or removed using option bits of ubidi_writeReordered, or if option UBIDI_REORDER_INVERSE_NUMBERS_AS_L has been set.

Parameters
pBiDiis the paragraph UBiDi object.
Returns
The length of the reordered text resulting from the last call to ubidi_setPara.
See also
ubidi_setPara
UBIDI_OPTION_INSERT_MARKS
UBIDI_OPTION_REMOVE_CONTROLS @stable ICU 3.6

Definition at line 2910 of file ubidi.cpp.

References IS_VALID_PARA_OR_LINE, and UBiDi::resultLength.

◆ ubidi_getText_68()

const UChar* ubidi_getText_68 ( const UBiDi pBiDi)

Get the pointer to the text.

Parameters
pBiDiis 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 @stable ICU 2.0

Definition at line 2883 of file ubidi.cpp.

References IS_VALID_PARA_OR_LINE, NULL, and UBiDi::text.

◆ ubidi_getVisualIndex_68()

int32_t ubidi_getVisualIndex_68 ( 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.

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

Note that in right-to-left runs, this mapping places second surrogates before first ones (which is generally a bad idea) and combining characters before base characters. Use of ubidi_writeReordered(), optionally with the UBIDI_KEEP_BASE_COMBINING option can be considered instead of using the mapping, in order to avoid these issues.

Parameters
pBiDiis the paragraph or line UBiDi object.
logicalIndexis the index of a character in the text.
pErrorCodemust be a valid pointer to an error code value.
Returns
The visual position of this character.
See also
ubidi_getLogicalMap
ubidi_getLogicalIndex
ubidi_getProcessedLength @stable ICU 2.0

Definition at line 875 of file ubidiln.cpp.

References UBiDi::controlCount, UBiDi::direction, GET_INDEX, i, UBiDi::insertPoints, Run::insertRemove, IS_BIDI_CONTROL_CHAR, IS_EVEN_RUN, j, length, UBiDi::length, limit, Run::logicalStart, LRM_AFTER, LRM_BEFORE, offset, RETURN_IF_BAD_RANGE, RETURN_IF_NOT_VALID_PARA_OR_LINE, RETURN_IF_NULL_OR_FAILING_ERRCODE, RLM_AFTER, RLM_BEFORE, UBiDi::runCount, UBiDi::runs, InsertPoints::size, start, UBiDi::text, U_MEMORY_ALLOCATION_ERROR, ubidi_getRuns, UBIDI_LTR, UBIDI_MAP_NOWHERE, UBIDI_RTL, and Run::visualLimit.

◆ ubidi_getVisualMap_68()

void ubidi_getVisualMap_68 ( 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.

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

Parameters
pBiDiis the paragraph or line UBiDi object.
indexMapis 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.
pErrorCodemust be a valid pointer to an error code value.
See also
ubidi_getLogicalMap
ubidi_getLogicalIndex
ubidi_getProcessedLength
ubidi_getResultLength @stable ICU 2.0

Definition at line 1211 of file ubidiln.cpp.

References UBiDi::controlCount, i, UBiDi::insertPoints, Run::insertRemove, IS_BIDI_CONTROL_CHAR, IS_EVEN_RUN, j, k, length, Run::logicalStart, LRM_AFTER, LRM_BEFORE, m, NULL, ClipperLib::pi, REMOVE_ODD_BIT, UBiDi::resultLength, RETURN_VOID_IF_NULL_OR_FAILING_ERRCODE, RLM_AFTER, RLM_BEFORE, UBiDi::runCount, UBiDi::runs, InsertPoints::size, UBiDi::text, U_ILLEGAL_ARGUMENT_ERROR, U_SUCCESS, ubidi_countRuns, UBIDI_MAP_NOWHERE, uchar, and Run::visualLimit.

◆ ubidi_getVisualRun_68()

UBiDiDirection ubidi_getVisualRun_68 ( 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.

Parameters
pBiDiis the paragraph or line UBiDi object.
runIndexis the number of the run in visual order, in the range [0..ubidi_countRuns(pBiDi)-1].
pLogicalStartis the first logical character index in the text. The pointer may be NULL if this index is not needed.
pLengthis 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, never UBIDI_NEUTRAL.
See also
ubidi_countRuns

Example:

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 second surrogates before first ones (which is generally a bad idea) and combining characters before base characters.

Use of ubidi_writeReordered(), optionally with the UBIDI_KEEP_BASE_COMBINING option, can be considered in order to avoid these issues. @stable ICU 2.0

Definition at line 363 of file ubidiln.cpp.

References errorCode, GET_INDEX, GET_ODD_BIT, Run::logicalStart, NULL, RETURN_IF_BAD_RANGE, RETURN_IF_NOT_VALID_PARA_OR_LINE, UBiDi::runCount, UBiDi::runs, start, U_FAILURE, U_ZERO_ERROR, ubidi_getRuns, UBIDI_LTR, and Run::visualLimit.

◆ ubidi_invertMap_68()

void ubidi_invertMap_68 ( const int32_t srcMap,
int32_t destMap,
int32_t  length 
)

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

Parameters
srcMapis an array with length elements which defines the original mapping from a source array containing length elements to a destination array. Some elements of the source array may have no mapping in the destination array. In that case, their value will be the special value UBIDI_MAP_NOWHERE. All elements must be >=0 or equal to UBIDI_MAP_NOWHERE. Some elements 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 elements with the same value except UBIDI_MAP_NOWHERE).
destMapis an array with a number of elements equal to 1 + the highest value in srcMap. destMap will be filled with the inverse mapping. If element with index i in srcMap has a value k different from UBIDI_MAP_NOWHERE, this means that element i of the source array maps to element k in the destination array. The inverse map will have value i in its k-th element. For all elements of the destination array which do not map to an element in the source array, the corresponding element in the inverse map will have a value equal to UBIDI_MAP_NOWHERE.
lengthis the length of each array.
See also
UBIDI_MAP_NOWHERE @stable ICU 2.0

Definition at line 1319 of file ubidiln.cpp.

References count, length, NULL, ClipperLib::pi, and uprv_memset.

◆ ubidi_isInverse_68()

UBool ubidi_isInverse_68 ( UBiDi pBiDi)

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.

Parameters
pBiDiis a UBiDi object.
Returns
true if the Bidi object is set to perform the inverse Bidi algorithm by handling numbers as L.
See also
ubidi_setInverse
ubidi_setReorderingMode @stable ICU 2.0

Definition at line 279 of file ubidi.cpp.

References FALSE, UBiDi::isInverse, and NULL.

◆ ubidi_isOrderParagraphsLTR_68()

UBool ubidi_isOrderParagraphsLTR_68 ( UBiDi pBiDi)

Is this Bidi object set to allocate level 0 to block separators so that successive paragraphs progress from left to right?

Parameters
pBiDiis a UBiDi object.
Returns
true if the Bidi object is set to allocate level 0 to block separators.
See also
ubidi_orderParagraphsLTR @stable ICU 3.4

Definition at line 2865 of file ubidi.cpp.

References FALSE, NULL, and UBiDi::orderParagraphsLTR.

◆ ubidi_open_68()

UBiDi* ubidi_open_68 ( 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.

Returns
An empty UBiDi object. @stable ICU 2.0

Definition at line 127 of file ubidi.cpp.

References errorCode, U_ZERO_ERROR, and ubidi_openSized.

◆ ubidi_openSized_68()

UBiDi* ubidi_openSized_68 ( 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().

Parameters
maxLengthis 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.
maxRunCountis 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.
pErrorCodemust be a valid pointer to an error code value.
Returns
An empty UBiDi object with preallocated memory. @stable ICU 2.0

Definition at line 134 of file ubidi.cpp.

References getInitialDirPropsMemory, getInitialLevelsMemory, getInitialRunsMemory, maxLength(), UBiDi::mayAllocateRuns, UBiDi::mayAllocateText, NULL, UBiDi::runsSize, TRUE, U_FAILURE, U_ILLEGAL_ARGUMENT_ERROR, U_MEMORY_ALLOCATION_ERROR, U_SUCCESS, ubidi_close, uprv_malloc, and uprv_memset.

◆ ubidi_orderParagraphsLTR_68()

void ubidi_orderParagraphsLTR_68 ( UBiDi pBiDi,
UBool  orderParagraphsLTR 
)

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.

Parameters
pBiDiis a UBiDi object.
orderParagraphsLTRspecifies whether paragraph separators (B) must receive level 0, so that successive paragraphs progress from left to right.
See also
ubidi_setPara @stable ICU 3.4

Definition at line 2858 of file ubidi.cpp.

References NULL, and UBiDi::orderParagraphsLTR.

◆ ubidi_reorderLogical_68()

void ubidi_reorderLogical_68 ( 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.

Parameters
levelsis an array with length levels that have been determined by the application.
lengthis the number of levels in the array, or, semantically, the number of objects to be reordered. It must be length>0.
indexMapis 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. @stable ICU 2.0

Definition at line 750 of file ubidiln.cpp.

References length, limit, NULL, prepareReorder(), and start.

◆ ubidi_reorderVisual_68()

void ubidi_reorderVisual_68 ( 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.

Parameters
levelsis an array with length levels that have been determined by the application.
lengthis the number of levels in the array, or, semantically, the number of objects to be reordered. It must be length>0.
indexMapis 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. @stable ICU 2.0

Definition at line 813 of file ubidiln.cpp.

References end, length, limit, NULL, prepareReorder(), start, and temp.

◆ ubidi_setClassCallback_68()

void ubidi_setClassCallback_68 ( 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.

Parameters
pBiDiis the paragraph UBiDi object.
newFnis the new callback function pointer.
newContextis the new callback context pointer. This can be NULL.
oldFnfillin: Returns the old callback function pointer. This can be NULL.
oldContextfillin: Returns the old callback's context. This can be NULL.
pErrorCodemust be a valid pointer to an error code value.
See also
ubidi_getClassCallback @stable ICU 3.6

Definition at line 2985 of file ubidi.cpp.

References UBiDi::coClassCallback, UBiDi::fnClassCallback, NULL, RETURN_VOID_IF_NULL_OR_FAILING_ERRCODE, and U_ILLEGAL_ARGUMENT_ERROR.

◆ ubidi_setContext_68()

void ubidi_setContext_68 ( UBiDi pBiDi,
const UChar prologue,
int32_t  proLength,
const UChar epilogue,
int32_t  epiLength,
UErrorCode pErrorCode 
)

Set the context before a call to ubidi_setPara().

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

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

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

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

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

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

Note 3: users must be aware that even after setting the context before a call to ubidi_setPara() to perform e.g. a logical to visual transformation, the resulting string may not be identical to what it would have been if all the text, including prologue and epilogue, had been processed together.
Example (upper case letters represent RTL characters):
  prologue = "<code>abc DE</code>"
  epilogue = none
  main text = "<code>FGH xyz</code>"
  paraLevel = UBIDI_LTR
  display without prologue = "<code>HGF xyz</code>" ("HGF" is adjacent to "xyz")
  display with prologue = "<code>abc HGFED xyz</code>" ("HGF" is not adjacent to "xyz")

Parameters
pBiDiis a paragraph UBiDi object.
prologueis a pointer to the text which precedes the text that will be specified in a coming call to ubidi_setPara(). If there is no prologue to consider, then proLength must be zero and this pointer can be NULL.
proLengthis the length of the prologue; if proLength==-1 then the prologue must be zero-terminated. Otherwise proLength must be >= 0. If proLength==0, it means that there is no prologue to consider.
epilogueis a pointer to the text which follows the text that will be specified in a coming call to ubidi_setPara(). If there is no epilogue to consider, then epiLength must be zero and this pointer can be NULL.
epiLengthis the length of the epilogue; if epiLength==-1 then the epilogue must be zero-terminated. Otherwise epiLength must be >= 0. If epiLength==0, it means that there is no epilogue to consider.
pErrorCodemust be a valid pointer to an error code value.
See also
ubidi_setPara @stable ICU 4.8

Definition at line 2328 of file ubidi.cpp.

References UBiDi::epiLength, UBiDi::epilogue, NULL, UBiDi::proLength, prologue, UBiDi::prologue, RETURN_VOID_IF_NULL_OR_FAILING_ERRCODE, U_ILLEGAL_ARGUMENT_ERROR, and u_strlen.

◆ ubidi_setInverse_68()

void ubidi_setInverse_68 ( 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 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.

Parameters
pBiDiis a UBiDi object.
isInversespecifies "forward" or "inverse" Bidi operation.
See also
ubidi_setPara
ubidi_writeReordered
ubidi_setReorderingMode @stable ICU 2.0

Definition at line 270 of file ubidi.cpp.

References UBiDi::isInverse, NULL, UBiDi::reorderingMode, UBIDI_REORDER_DEFAULT, and UBIDI_REORDER_INVERSE_NUMBERS_AS_L.

◆ ubidi_setLine_68()

void ubidi_setLine_68 ( 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.

Parameters
pParaBiDiis the parent paragraph object. It must have been set by a successful call to ubidi_setPara.
startis the line's first index into the text.
limitis 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.
pLineBiDiis the object that will now represent a line of the text.
pErrorCodemust be a valid pointer to an error code value.
See also
ubidi_setPara
ubidi_getProcessedLength @stable ICU 2.0

Definition at line 126 of file ubidiln.cpp.

References UBiDi::controlCount, UBiDi::direction, UBiDi::dirProps, UBiDi::flags, GET_PARALEVEL, i, IS_BIDI_CONTROL_CHAR, j, length, UBiDi::length, level, UBiDi::levels, limit, NULL, UBiDi::originalLength, UBiDi::paraCount, UBiDi::paraLevel, UBiDi::pParaBiDi, UBiDi::reorderingMode, UBiDi::reorderingOptions, UBiDi::resultLength, RETURN_VOID_IF_BAD_RANGE, RETURN_VOID_IF_NOT_VALID_PARA, RETURN_VOID_IF_NULL_OR_FAILING_ERRCODE, UBiDi::runCount, UBiDi::runs, setTrailingWSStart(), start, UBiDi::text, UBiDi::trailingWSStart, U_ILLEGAL_ARGUMENT_ERROR, ubidi_getParagraph, UBIDI_LTR, UBIDI_MIXED, and UBIDI_RTL.

◆ ubidi_setPara_68()

void ubidi_setPara_68 ( 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 Annex #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.

Parameters
pBiDiA 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.
textis 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.
lengthis the length of the text; if length==-1 then the text must be zero-terminated.
paraLevelspecifies 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.

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

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. This pointer can be NULL if this value is not necessary.
pErrorCodemust be a valid pointer to an error code value. @stable ICU 2.0

Definition at line 2554 of file ubidi.cpp.

References addPoint(), adjustWSLevels(), B, checkExplicitLevels(), InsertPoints::confirmed, UBiDi::controlCount, UBiDi::defaultParaLevel, direction, UBiDi::direction, DIRPROP_FLAG, DIRPROP_FLAG_LR, DIRPROP_FLAG_MULTI_RUNS, UBiDi::dirProps, UBiDi::dirPropsMemory, InsertPoints::errorCode, UBiDi::flags, GET_LR_FROM_LEVEL, GET_PARALEVEL, getDirProps(), getDirPropsMemory, getInitialIsolatesMemory, getLevelsMemory, i, impTab_DEFAULT, impTab_GROUP_NUMBERS_WITH_R, impTab_INVERSE_FOR_NUMBERS_SPECIAL, impTab_INVERSE_FOR_NUMBERS_SPECIAL_WITH_MARKS, impTab_INVERSE_LIKE_DIRECT, impTab_INVERSE_LIKE_DIRECT_WITH_MARKS, impTab_INVERSE_NUMBERS_AS_L, impTab_NUMBERS_SPECIAL, UBiDi::insertPoints, IS_DEFAULT_LEVEL, UBiDi::isolateCount, UBiDi::isolates, UBiDi::isolatesMemory, UBiDi::isolatesSize, j, L, last, length, UBiDi::length, level, Para::level, UBiDi::levels, UBiDi::levelsMemory, limit, Para::limit, MASK_BN_EXPLICIT, MASK_R_AL, NO_OVERRIDE, NULL, UBiDi::originalLength, UBiDi::paraCount, UBiDi::paraLevel, UBiDi::paras, UBiDi::parasMemory, UBiDi::pImpTabPair, UBiDi::pParaBiDi, UBiDi::reorderingMode, UBiDi::reorderingOptions, resolveExplicitLevels(), resolveImplicitLevels(), UBiDi::resultLength, RETURN_VOID_IF_NULL_OR_FAILING_ERRCODE, RLM_BEFORE, UBiDi::runCount, UBiDi::runs, setParaRunsOnly(), setParaSuccess(), SIMPLE_ISOLATES_COUNT, UBiDi::simpleIsolates, UBiDi::simpleParas, InsertPoints::size, start, UBiDi::text, text, UBiDi::trailingWSStart, U_FAILURE, U_ILLEGAL_ARGUMENT_ERROR, U_MEMORY_ALLOCATION_ERROR, u_strlen, UBIDI_DEFAULT_LTR, UBIDI_LEVEL_OVERRIDE, UBIDI_LTR, UBIDI_MAX_EXPLICIT_LEVEL, UBIDI_OPTION_INSERT_MARKS, UBIDI_OPTION_REMOVE_CONTROLS, UBIDI_REORDER_DEFAULT, UBIDI_REORDER_GROUP_NUMBERS_WITH_R, UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL, UBIDI_REORDER_INVERSE_LIKE_DIRECT, UBIDI_REORDER_INVERSE_NUMBERS_AS_L, UBIDI_REORDER_NUMBERS_SPECIAL, UBIDI_REORDER_RUNS_ONLY, UBIDI_RTL, and UPRV_UNREACHABLE.

◆ ubidi_setReorderingMode_68()

void ubidi_setReorderingMode_68 ( 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.

  • When the reordering mode is set to UBIDI_REORDER_DEFAULT, the standard Bidi Logical to Visual algorithm is applied.

  • When the reordering mode is set to 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.
    The differences between the basic algorithm and the algorithm addressed by this option are as follows:

    • Within text at an even embedding level, the sequence "123AB" (where AB represent R or AL letters) is transformed to "123BA" by the Unicode algorithm and to "BA123" by the Windows algorithm.
    • Arabic-Indic numbers (AN) are handled by the Windows algorithm just like regular numbers (EN).

  • When the reordering mode is set to 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.
    The source text should not contain Bidi control characters other than LRM or RLM.

  • When the reordering mode is set to UBIDI_REORDER_RUNS_ONLY, a "Logical to Logical" transformation must be performed:

    • If the default text level of the source text (argument 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.
    • If the default level of the source text is odd, the source text will be handled as RTL logical text and will be transformed to the LTR logical text which has the same LTR visual display.

    This mode may be needed when logical text which is basically Arabic or Hebrew, with possible included numbers or phrases in English, has to be displayed as if it had an even embedding level (this can happen if the displaying application treats all text as if it was basically LTR).
    This mode may also be needed in the reverse case, when logical text which is basically English, with possible included phrases in Arabic or Hebrew, has to be displayed as if it had an odd embedding level.
    Both cases could be handled by adding LRE or RLE at the head of the text, if the display subsystem supports these formatting controls. If it does not, the problem may be handled by transforming the source text in this mode before displaying it, so that it will be displayed properly.
    The source text should not contain Bidi control characters other than LRM or RLM.

  • When the reordering mode is set to 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.

  • When the reordering mode is set to 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.
    For example, an LTR paragraph with the content "FED 123 456 CBA" (where upper case represents RTL characters) will be transformed to "ABC 456 123 DEF", as opposed to "DEF 123 456 ABC" with mode UBIDI_REORDER_INVERSE_NUMBERS_AS_L.
    When used in conjunction with option 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.

  • When the reordering mode is set to 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.
    For example, an LTR paragraph with the content "abc FED123" (where upper case represents RTL characters) will be transformed to "abc 123DEF."

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.

Parameters
pBiDiis a UBiDi object.
reorderingModespecifies the required variant of the Bidi algorithm.
See also
UBiDiReorderingMode
ubidi_setInverse
ubidi_setPara
ubidi_writeReordered @stable ICU 3.6

Definition at line 303 of file ubidi.cpp.

References UBiDi::isInverse, NULL, UBiDi::reorderingMode, UBIDI_REORDER_COUNT, UBIDI_REORDER_DEFAULT, and UBIDI_REORDER_INVERSE_NUMBERS_AS_L.

◆ ubidi_setReorderingOptions_68()

void ubidi_setReorderingOptions_68 ( UBiDi pBiDi,
uint32_t  reorderingOptions 
)

Specify which of the reordering options should be applied during Bidi transformations.

Parameters
pBiDiis a UBiDi object.
reorderingOptionsis a combination of zero or more of the following options: UBIDI_OPTION_DEFAULT, UBIDI_OPTION_INSERT_MARKS, UBIDI_OPTION_REMOVE_CONTROLS, UBIDI_OPTION_STREAMING.
See also
ubidi_getReorderingOptions @stable ICU 3.6

Definition at line 321 of file ubidi.cpp.

References NULL, UBiDi::reorderingOptions, and UBIDI_OPTION_REMOVE_CONTROLS.

◆ ubidi_writeReordered_68()

int32_t ubidi_writeReordered_68 ( 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) combining characters. 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
pBiDiA 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.
destA pointer to where the reordered text is to be copied. The source text and dest[destSize] must not overlap.
destSizeThe 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_getProcessedLength(pBiDi).
optionsA 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
pErrorCodemust be a valid pointer to an error code value.
Returns
The length of the output string.
See also
ubidi_getProcessedLength @stable ICU 2.0

Definition at line 357 of file ubidiwrt.cpp.

References dest, dir, DIRPROP_FLAG, UBiDi::dirProps, doWriteForward(), doWriteReverse(), Run::insertRemove, UBiDi::isInverse, L, length, UBiDi::length, LRM_AFTER, LRM_BEFORE, LRM_CHAR, MASK_R_AL, NULL, UBiDi::reorderingMode, UBiDi::reorderingOptions, RLM_AFTER, RLM_BEFORE, RLM_CHAR, run(), UBiDi::runs, link_confs::src, UBiDi::text, text, U_FAILURE, U_ILLEGAL_ARGUMENT_ERROR, u_terminateUChars, ubidi_countRuns, UBIDI_DO_MIRRORING, ubidi_getVisualRun, UBIDI_INSERT_LRM_FOR_NUMERIC, UBIDI_LTR, UBIDI_OPTION_INSERT_MARKS, UBIDI_OPTION_REMOVE_CONTROLS, UBIDI_OUTPUT_REVERSE, UBIDI_REMOVE_BIDI_CONTROLS, UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL, UBIDI_REORDER_INVERSE_LIKE_DIRECT, UBIDI_REORDER_INVERSE_NUMBERS_AS_L, and UBIDI_REORDER_RUNS_ONLY.

◆ ubidi_writeReverse_68()

int32_t ubidi_writeReverse_68 ( 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) combining characters. 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.

See also
ubidi_writeReordered
Parameters
srcA pointer to the RTL run text.
srcLengthThe length of the RTL run.
destA pointer to where the reordered text is to be copied. src[srcLength] and dest[destSize] must not overlap.
destSizeThe 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.
optionsA bit set of options for the reordering that control how the reordered text is written. See the options parameter in ubidi_writeReordered().
pErrorCodemust be a valid pointer to an error code value.
Returns
The length of the output string. @stable ICU 2.0

Definition at line 309 of file ubidiwrt.cpp.

References dest, doWriteReverse(), NULL, link_confs::src, U_FAILURE, U_ILLEGAL_ARGUMENT_ERROR, u_strlen, and u_terminateUChars.