class ICU::BiDi

• ICU::BiDi
• Reference
• Object

Overview

Bidirectional Algorithm

This class provides a wrapper around ICU's Bidirectional Algorithm (BiDi) implementation. It is used to reorder text that contains a mix of left-to-right (LTR) and right-to-left (RTL) characters according to the Unicode Bidirectional Algorithm.

Disclaimer: this binding wrapper has been automatically generated via GenAI

Usage

# Example with mixed LTR and RTL text
text = "hello \u0627\u0644\u0639\u0631\u0628\u064A\u0629 world" # "hello العربية world"

# Create a BiDi object and set the text
bidi = ICU::BiDi.new
bidi.set_text(text)

# Get the visual reordering
reordered_text = bidi.write_reordered
puts reordered_text # Output depends on terminal/environment BiDi support

# Get the base direction (static method)
puts ICU::BiDi.base_direction(text) # => ICU::BiDi::Direction::Mixed

# Get the number of runs (segments of consistent direction)
puts bidi.run_count # => e.g., 3 (LTR, RTL, LTR)

# Iterate through visual runs
runs = bidi.visual_runs
runs.each_with_index do |run, i|
  puts "Run #{i}: Logical Start=#{run.logical_start}, Length=#{run.length}, Direction=#{run.direction}"
end

# Get logical index from visual index
logical_idx = bidi.logical_index(visual_idx: 10)
puts "Logical index for visual index 10: #{logical_idx}"

See also

• Reference C API
• ICU User Guide
• Unit tests

Defined in:

Constant Summary

DEFAULT_LTR = 254.to_u8

Constants for paragraph level setting used in #set_text. DEFAULT_LTR: Use LTR if no strong character, otherwise auto-detect.

DEFAULT_RTL = 255.to_u8

DEFAULT_RTL: Use RTL if no strong character, otherwise auto-detect.

LEVEL_OVERRIDE = 128.to_u8

Bit flag used with embedding_levels in #set_text to override default directional properties.

MAP_NOWHERE = -1.to_i32

Special value returned by #logical_index or #visual_index when a mapping doesn't exist (e.g., for removed controls or inserted marks).

MAX_EXPLICIT_LEVEL = 125.to_u8

Maximum explicit embedding level allowed (125).

Constructors

• .new(text : String, para_level : Level = DEFAULT_LTR)

  Creates a new BiDi object and immediately processes the given text.

• .new

  Creates a new, empty BiDi object.

Class Method Summary

• .base_direction(text : String) : Direction

  Static method to get the base direction of a plain text string according to the first strong character (L, R, or AL) per the Unicode Bidirectional Algorithm.

• .write_reverse(src : String, options : WriteOption = WriteOption::None) : String

  Static method to reverse a string character by character.

Instance Method Summary

• #direction : Direction

  Gets the overall direction of the processed text.

• #finalize

  Releases resources associated with the BiDi object.

• #inverse=(is_inverse : Bool) : Nil

  Sets whether to use an approximation of the "inverse" BiDi algorithm (transforming visual order to logical order).

• #inverse? : Bool

  Checks if the inverse BiDi algorithm mode (ReorderingMode::InverseNumbersAsL) is active.

• #length : Int32

  Gets the original length of the text set by #set_text.

• #logical_index(visual_index : Int32) : Int32

  Maps a visual index to its corresponding logical index in the original text.

• #order_paragraphs_ltr=(order_ltr : Bool) : Nil

  Sets whether paragraph separators (like U+2029) should always be treated as LTR (level 0).

• #order_paragraphs_ltr? : Bool

  Checks if paragraph separators are forced to level 0 for LTR progression.

• #para_level : Level

  Gets the base paragraph level of the text.

• #paragraph(char_index : Int32) : ParagraphInfo

  Gets information about the paragraph containing the character at char_index.

• #paragraph_by_index(para_index : Int32) : ParagraphInfo

  Gets information about the paragraph at the specified para_index.

• #paragraph_count : Int32

  Gets the number of paragraphs detected in the text (separated by block separators like U+2029).

• #reordering_mode : ReorderingMode

  Gets the currently active reordering mode.

• #reordering_mode=(mode : ReorderingMode) : Nil

  Sets the specific BiDi algorithm variant or reordering mode to use.

• #reordering_options : UInt32

  Gets the currently active reordering options as a bitmask.

• #reordering_options=(options : ReorderingOption) : Nil

  Sets options that modify the behavior of the selected reordering mode (e.g., inserting marks, removing controls, streaming).

• #result_length : Int32

  Gets the length of the reordered text that would be generated by #write_reordered.

• #run_count : Int32

  Gets the number of directional runs in the visually reordered text.

• #set_context(prologue : String, epilogue : String) : Nil

  Sets context text that surrounds the main text processed by #set_text.

• #set_text(text : String, para_level : Level = 0.to_u8, embedding_levels : Array(Level) | Nil = nil) : Nil

  Sets the text to be processed by the BiDi algorithm.

• #visual_index(logical_index : Int32) : Int32

  Maps a logical index from the original text to its corresponding visual index.

• #visual_run(run_index : Int32) : VisualRunInfo

  Gets information about a specific visual run.

• #visual_runs : Array(VisualRunInfo)

  Gets an array containing information about all visual runs.

• #write_reordered(options : WriteOption = WriteOption::None) : String

  Generates the visually reordered string based on the processed text.

Constructor Detail

bidi = ICU::BiDi.new("hello العربية world")
puts bidi.direction # => ICU::BiDi::Direction::Mixed

Class Method Detail

Instance Method Detail

runs = bidi.visual_runs
runs.each { |run| puts run }