Scope and limitations

Where cl-icu fits

cl-icu covers the Unicode text processing that comes before shaping in a layout pipeline, plus the text services every program needs:

Step	Who does it
splitting text into paragraphs, resolving bidi levels, reordering lines (UAX #9)	cl-icu
splitting runs by script (UAX #24)	cl-icu
finding line break opportunities (UAX #14), graphemes, words, sentences (UAX #29)	cl-icu
normalization, case mapping, character properties	cl-icu
choosing line breaks by width, justification, font fallback	your code, or cl-textrender
shaping each run into glyphs, mirroring in RTL runs	cl-harfbuzz
rasterizing glyphs	cl-ft2, or a GPU renderer

Not covered

These ICU services have no wrapper. Most live in libicui18n, which cl-icu does not load; you can bind them yourself with deficu after loading that library (see FFI layer).

• Collation (locale-aware sorting) and string search.
• Transliteration, spoof checking, IDNA.
• Formatting: dates, times, numbers, currencies, plural rules, messages.
• Regular expressions, UnicodeSet, charset conversion.
• Locale data: display names, delimiters, measurement systems.
• Custom break rules and iterating over boundaries incrementally: each boundary function runs over the whole text at once.
• Bidi options: reordering modes (inverse bidi, numbers special) and inserting or removing bidi marks. (Visual and logical maps are bidi-visual-order and bidi-visual-positions.)
• Numeric, string and mask properties in char-property (Numeric_Value, Age, case mappings as properties, General_Category_Mask), and the emoji properties of strings (RGI_Emoji and its relatives). char-unicode-name covers the Name property.
• Case mapping options (title-casing without lower-casing the rest, and similar).

Design limits

• Each call starts from scratch. A call converts its text to UTF-16, opens the ICU object it needs and frees it again. That is fast (see Core concepts), but call each function once per paragraph and keep the results, rather than once per character or per candidate line.
• script-runs follows the Script property, not Script_Extensions. A Common character with extensions (ー, 、) joins the run around it, whatever its extensions say. This matches ICU's own script run iterator.
• Word kinds: ICU's Chinese and Japanese dictionary reports its words as :ideographic, katakana included, so :kana does not occur in practice with ICU 78.
• Locales fall back silently. A misspelt locale gives the root rules without an error.
• Results follow the system's ICU. Different machines may have different Unicode versions; Windows' ICU is often older than a current Linux distribution's. Check unicode-version when exact behaviour matters.

Known issues

• macOS is untested. cl-icu should load a Homebrew ICU once its directory is on DYLD_FALLBACK_LIBRARY_PATH (see Installation), but CI does not run on macOS.