Performs transformation of text from the bidi layout defined by the input ordering scheme to the bidi layout defined by the output ordering scheme, and applies character mirroring and Arabic shaping operations.

In terms of Bidi class, such a transformation implies:

• calling Bidi#setReorderingMode as needed (when the reordering mode is other than normal),
• calling Bidi#setInverse as needed (when text should be transformed from a visual to a logical form),
• resolving embedding levels of each character in the input text by calling Bidi#setPara,
• reordering the characters based on the computed embedding levels, also performing character mirroring as needed, and streaming the result to the output, by calling Bidi#writeReordered,
• performing Arabic digit and letter shaping on the output text by calling ArabicShaping#shape.

An "ordering scheme" encompasses the base direction and the order of text, and these characteristics must be defined by the caller for both input and output explicitly .

There are 36 possible combinations of {input, output} ordering schemes, which are partially supported by Bidi already. Examples of the currently supported combinations:

• {Logical LTR, Visual LTR}: this is equivalent to calling Bidi#setPara with paraLevel == Bidi#LTR,
• {Logical RTL, Visual LTR}: this is equivalent to calling Bidi#setPara with paraLevel == Bidi#RTL,
• {Logical Default ("Auto") LTR, Visual LTR}: this is equivalent to calling Bidi#setPara with paraLevel == Bidi#LEVEL_DEFAULT_LTR,
• {Logical Default ("Auto") RTL, Visual LTR}: this is equivalent to calling Bidi#setPara with paraLevel == Bidi#LEVEL_DEFAULT_RTL,
• {Visual LTR, Logical LTR}: this is equivalent to calling Bidi#setInverse(true) and then Bidi#setPara with paraLevel == Bidi#LTR,
• {Visual LTR, Logical RTL}: this is equivalent to calling Bidi#setInverse(true) and then Bidi#setPara with paraLevel == Bidi#RTL.

All combinations that involve the Visual RTL scheme are unsupported by Bidi, for instance:

• {Logical LTR, Visual RTL},
• {Visual RTL, Logical RTL}.

Example of usage of the transformation engine:

BidiTransform bidiTransform = new BidiTransform();
String in = "abc ۰123"; // "abc \\u06f0123"
// Run a transformation.
String out = bidiTransform.transform(in,
         Bidi.LTR, Order.VISUAL,
         Bidi.RTL, Order.LOGICAL,
         Mirroring.OFF,
         ArabicShaping.DIGITS_AN2EN | ArabicShaping.DIGIT_TYPE_AN_EXTENDED);
// Result: "0123 abc".
// Do something with out.
out = out.replace('0', '4');
// Result: "4123 abc".
// Run a reverse transformation.
String inNew = bidiTransform.transform(out,
         Bidi.RTL, Order.LOGICAL,
         Bidi.LTR, Order.VISUAL,
         Mirroring.OFF,
         ArabicShaping.DIGITS_EN2AN | ArabicShaping.DIGIT_TYPE_AN_EXTENDED);
// Result: "abc \\u06f4\\u06f1\\u06f2\\u06f3"

Parameters

text:CharSequence

An input character sequence that the Bidi layout transformations will be performed on.

inParaLevel:byte

A base embedding level of the input as defined in Bidi#setPara(String, byte, byte[]) documentation for the paraLevel parameter.

inOrder:BidiTransform.Order

An order of the input, which can be one of the Order values.

outParaLevel:byte

A base embedding level of the output as defined in Bidi#setPara(String, byte, byte[]) documentation for the paraLevel parameter.

outOrder:BidiTransform.Order

An order of the output, which can be one of the Order values.

doMirroring:BidiTransform.Mirroring

Indicates whether or not to perform character mirroring, and can accept one of the Mirroring values.

shapingOptions:int

Arabic digit and letter shaping options defined in the ArabicShaping documentation.

Note

Direction indicator options are computed by the transformation engine based on the effective ordering schemes, so user-defined direction indicators will be ignored.

Returns:String

The output string, which is the result of the layout transformation.

Exceptions

IllegalArgumentException:

if text, inOrder, outOrder, or doMirroring parameter is null.

ICU Status

Stable since ICU 58.