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);Reorderleaves 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
Levelsand are left out ofVisualOrderandReorder, 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.
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
endThis 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.
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 + "]"
endRuns 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.
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)
endThe 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.
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
endThe 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
| Job | Function |
|---|---|
| Align a line left or right | ParagraphLevel with DirAuto |
| Find the right to left and left to right pieces | Levels |
| Map screen columns to characters | VisualOrder |
| Get the whole line in drawing order | Reorder |
| Draw brackets the right way round | VisualOrder, Levels and unicode.PairedBracket |
Constants and variables
DirAuto
const DirAuto: i32 = 0import 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)
endDirLTR
const DirLTR: i32 = 1The example for this item is shown with the ones above: bidi-Reorder.salam
DirRTL
const DirRTL: i32 = 2The example for this item is shown with the ones above: bidi-Reorder.salam
Functions
ParagraphLevel
func ParagraphLevel(s: str, dir: int): intThe example for this item is shown with the ones above: bidi-Reorder.salam
Levels
func Levels(s: str, dir: int): Vector<int>The example for this item is shown with the ones above: bidi-Reorder.salam
VisualOrder
func VisualOrder(s: str, dir: int): Vector<int>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): strThe example for this item is shown with the ones above: bidi-Reorder.salam