Standard library · Text

bidi

The Unicode bidirectional algorithm: the right display order when right to left and left to right text are mixed.

import bidi

Text is stored in memory in the order it was typed, but when right to left and left to right scripts are mixed, the order seen on screen is not that order. Browsers and editors do the rearranging with the Unicode bidirectional algorithm.

If you are drawing text yourself somewhere that does not do this for you, onto an image, in a terminal or on a simple display, the bidi package runs the same algorithm and tells you where every character goes.

Each function takes a paragraph direction: DirAuto infers it from the first strong character in the text, and the other two set it in advance. The "level" of each character is a number: even means left to right and odd means right to left.

The package only decides the order. Choosing a direction for a single character is unicode.BidiClass, and in a web page the browser does all of this for you with dir="auto".

What the package does not do, so your drawing code has to:

  • It does not mirror. In right to left text a ( must be drawn as ); Reorder leaves the characters as they are. The last section below shows the fix.
  • It does not shape Arabic letters. The reordered string still holds the plain letters, so a surface that cannot join them shows them unjoined.
  • It does not break lines. Pass one line at a time; for a wrapped paragraph, wrap first and reorder each line.
  • Explicit direction controls such as U+202B (RLE) get the level -1 from Levels and are left out of VisualOrder and Reorder, so those can be shorter than the input.

Which way does a line run?

Before you can draw a line you need to know which edge it starts from. ParagraphLevel with DirAuto answers that: it looks for the first strong character, a letter with a direction of its own, and returns one for right to left and zero for left to right. Digits and punctuation are weak, so a line that starts with a year still takes its direction from the first word after it. A line with no strong character at all counts as left to right.

bidi-guide-direction.salam
import bidi

func main:
    lines := ["Hello, world", "سلام دنیا", "2026 سال خوبی بود", "Salam یعنی سلام", "123 456"]
    each line in lines:
        mut align := "left"
        if bidi.ParagraphLevel(line, bidi.DirAuto) == 1:
            align = "right"
        end
        println align, "|", line
    end
end
Outputleft | Hello, world right | سلام دنیا right | 2026 سال خوبی بود left | Salam یعنی سلام left | 123 456

This is the same rule dir="auto" follows in HTML. Use it to align each line of a chat log or a table cell to the right edge or the left one.

Splitting text into direction runs

Levels returns one number per character, not per byte, so it lines up with str.Chars from the str package. Consecutive characters with the same level form a run. In a right to left paragraph the Persian runs are at level one and the embedded English words at level two; the spaces between them belong to the paragraph's own direction.

bidi-guide-runs.salam
import bidi
import str

func main:
    text := "Salam به معنی peace است"
    chars := str.Chars(text)
    levels := bidi.Levels(text, bidi.DirRTL)
    mut run := ""
    mut level := levels.Get(0)
    repeat chars.Len() in i:
        if levels.Get(i) != level:
            println level, "[" + run + "]"
            run = ""
            level = levels.Get(i)
        end
        run += chars.Get(i)
    end
    println level, "[" + run + "]"
end
Output2 [Salam] 1 [ به معنی ] 2 [peace] 1 [ است]

Runs are what a text renderer works with: each run is shaped and drawn as one piece, often with a different font for each script.

Drawing characters in display order

VisualOrder tells you, for each column on the screen from left to right, which character goes there. Walking it and appending the characters builds exactly the string that Reorder returns. Use the index form when you draw character by character or need to map a click on the screen back to a position in the text, and Reorder when you only want the finished string.

bidi-guide-visual.salam
import bidi
import str

func main:
    text := "ab سلام"
    chars := str.Chars(text)
    order := bidi.VisualOrder(text, bidi.DirLTR)
    mut drawn := ""
    each column, index in order:
        println column, "<-", index, "[" + chars.Get(index) + "]"
        drawn += chars.Get(index)
    end
    println drawn == bidi.Reorder(text, bidi.DirLTR)
end
Output0 <- 0 [a] 1 <- 1 [b] 2 <- 2 [ ] 3 <- 6 [م] 4 <- 5 [ا] 5 <- 4 [ل] 6 <- 3 [س] true

The reordered string is meant for a surface that does no bidi of its own, such as an image or a plain terminal. Do not send it to a browser or a modern editor: they apply the algorithm again and the text comes out backwards. That is also why the outputs on this page may look scrambled to you, because your browser is reordering them a second time.

Mirroring brackets in right to left runs

A plain surface draws every character exactly as it gets it, so after reordering, the brackets of a Persian line point the wrong way. The rule is simple: a character on an odd level is drawn as its mirror image. Walk VisualOrder, look up each character's level in Levels, and swap a bracket for its partner from unicode.PairedBracket when the level is odd.

bidi-guide-mirror.salam
import bidi
import str
import unicode

func draw(line: str): str:
    cps := str.CodePoints(line)
    defer cps.Free()
    levels := bidi.Levels(line, bidi.DirAuto)
    defer levels.Free()
    order := bidi.VisualOrder(line, bidi.DirAuto)
    defer order.Free()
    mut b := str.NewBuilder()
    defer str.BufFree(b)
    each i in order:
        mut cp := cps.Get(i)
        if levels.Get(i) % 2 == 1:
            cp = unicode.PairedBracket(cp)
        end
        str.BufAppendCp(b, cp)
    end
    ret str.BufStr(b)
end

func brackets(s: str): str:
    mut out := ""
    chars := str.Chars(s)
    defer chars.Free()
    each ch in chars:
        if ch == "(" or ch == ")" or ch == "[" or ch == "]":
            out += ch
        end
    end
    ret out
end

func main:
    each line in ["قیمت (با مالیات)", "فصل [۲] و فصل [۳]"]:
        println "Reorder:", brackets(bidi.Reorder(line, bidi.DirAuto)), "mirrored:", brackets(draw(line))
    end
end
OutputReorder: )( mirrored: () Reorder: ][][ mirrored: [][]

The example prints only the brackets, so the result reads the same in your browser. Reorder gives )(, so on a terminal or an image the brackets face away from the words they enclose; the mirrored version gives (), which is correct. PairedBracket covers the bracket pairs. Signs such as < and > mirror as well, so add them by hand if your text uses them.

Which function for which job

JobFunction
Align a line left or rightParagraphLevel with DirAuto
Find the right to left and left to right piecesLevels
Map screen columns to charactersVisualOrder
Get the whole line in drawing orderReorder
Draw brackets the right way roundVisualOrder, Levels and unicode.PairedBracket

Constants and variables

DirAuto

const DirAuto: i32 = 0
Take the paragraph direction from the first strong character in the text: right to left when it is an Arabic or Hebrew letter, left to right for Latin and the other left to right scripts. Text with no strong character is left to right.
bidi-Reorder.salam
import bidi

func main:
    s := "abc سلام"
    println bidi.ParagraphLevel(s, bidi.DirAuto), bidi.ParagraphLevel("سلام abc", bidi.DirAuto)
    println bidi.ParagraphLevel(s, bidi.DirRTL), bidi.ParagraphLevel("سلام", bidi.DirLTR)
    println bidi.Levels(s, bidi.DirLTR)
    println bidi.VisualOrder(s, bidi.DirLTR)
    println bidi.Reorder(s, bidi.DirLTR)
end
Output0 1 1 0 [0, 0, 0, 0, 1, 1, 1, 1] [0, 1, 2, 3, 7, 6, 5, 4] abc مالس

DirLTR

const DirLTR: i32 = 1
The paragraph is left to right, as on an English page.

The example for this item is shown with the ones above: bidi-Reorder.salam

DirRTL

const DirRTL: i32 = 2
The paragraph is right to left, as on a Persian page.

The example for this item is shown with the ones above: bidi-Reorder.salam

Functions

ParagraphLevel

func ParagraphLevel(s: str, dir: int): int
Returns the base level of the paragraph: zero for left to right and one for right to left.

The example for this item is shown with the ones above: bidi-Reorder.salam

Levels

func Levels(s: str, dir: int): Vector<int>
Returns the level of every character in a vector, one entry per code point; odd levels are displayed right to left. Explicit direction controls, which are not displayed, get -1. Free the vector when you are done.

The example for this item is shown with the ones above: bidi-Reorder.salam

VisualOrder

func VisualOrder(s: str, dir: int): Vector<int>
Says which characters are seen, in which order, reading the screen from left to right. Element i is the index of the character that appears in position i. Characters with level -1 are left out.

The example for this item is shown with the ones above: bidi-Reorder.salam

Reorder

func Reorder(s: str, dir: int): str
Rearranges the text into the order it should be drawn in from left to right: the same characters, in display order, without mirroring or letter shaping.

The example for this item is shown with the ones above: bidi-Reorder.salam