com.ibm.icu.text

Class BidiTransform

java.lang.Object

com.ibm.icu.text.BidiTransform

public class BidiTransform
extends Object

Bidi Layout Transformation Engine.

Author:

Lina Kemmel

Status:

Stable ICU 58.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	BidiTransform.Mirroring BidiTransform.Mirroring indicates whether or not characters with the "mirrored" property in RTL runs should be replaced with their mirror-image counterparts.
static class	BidiTransform.Order BidiTransform.Order indicates the order of text.

Constructor Summary

Constructors

Constructor and Description
BidiTransform() BidiTransform default constructor.

Method Summary

Modifier and Type	Method and Description
String	transform(CharSequence text, byte inParaLevel, BidiTransform.Order inOrder, byte outParaLevel, BidiTransform.Order outOrder, BidiTransform.Mirroring doMirroring, int shapingOptions) 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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BidiTransform

public BidiTransform()

BidiTransform default constructor.

Status:

Stable ICU 58.

Method Detail

transform

public String transform(CharSequence text,
                        byte inParaLevel,
                        BidiTransform.Order inOrder,
                        byte outParaLevel,
                        BidiTransform.Order outOrder,
                        BidiTransform.Mirroring doMirroring,
                        int shapingOptions)

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(int) as needed (when the reordering mode is other than normal),
• calling Bidi.setInverse(boolean) 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(java.lang.String, byte, byte[]),
• 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(int),
• performing Arabic digit and letter shaping on the output text by calling ArabicShaping.shape(char[], int, int, char[], int, int).

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(java.lang.String, byte, byte[]) with paraLevel == Bidi.LTR,
• {Logical RTL, Visual LTR}: this is equivalent to calling Bidi.setPara(java.lang.String, byte, byte[]) with paraLevel == Bidi.RTL,
• {Logical Default ("Auto") LTR, Visual LTR}: this is equivalent to calling Bidi.setPara(java.lang.String, byte, byte[]) with paraLevel == Bidi.LEVEL_DEFAULT_LTR,
• {Logical Default ("Auto") RTL, Visual LTR}: this is equivalent to calling Bidi.setPara(java.lang.String, byte, byte[]) with paraLevel == Bidi.LEVEL_DEFAULT_RTL,
• {Visual LTR, Logical LTR}: this is equivalent to calling Bidi.setInverse(boolean)(true) and then Bidi.setPara(java.lang.String, byte, byte[]) with paraLevel == Bidi.LTR,
• {Visual LTR, Logical RTL}: this is equivalent to calling Bidi.setInverse(boolean)(true) and then Bidi.setPara(java.lang.String, byte, byte[]) 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 - An input character sequence that the Bidi layout transformations will be performed on.

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

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

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

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

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

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

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

Throws:

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

Status:

Stable ICU 58.