TermUI.Renderer.DisplayWidth (TermUI v0.2.0)

Calculates display width of Unicode characters and strings.

Display width determines how many terminal columns a character occupies:

Most characters are single-width (1 column)
East Asian characters (CJK) are double-width (2 columns)
Combining characters are zero-width (0 columns)

This module uses Unicode properties to determine width, essential for correct cursor positioning and layout calculations.

Summary

Functions

double_width?(grapheme)

Checks if a character is double-width (East Asian Wide/Fullwidth).

pad(string, target_width, opts \\ [])

Pads a string to the given display width.

string_width(string)

Returns the total display width of a string.

truncate(string, max_width)

Truncates a string to fit within the given display width.

width(grapheme)

Returns the display width of a grapheme cluster.

zero_width?(grapheme)

Checks if a character is zero-width (combining character).

Functions

double_width?(grapheme)

@spec double_width?(String.t()) :: boolean()

Checks if a character is double-width (East Asian Wide/Fullwidth).

Examples

iex> DisplayWidth.double_width?("日")
true

iex> DisplayWidth.double_width?("A")
false

pad(string, target_width, opts \\ [])

@spec pad(String.t(), non_neg_integer(), keyword()) :: String.t()

Pads a string to the given display width.

Options

:direction - :left, :right, or :center (default: :right)
:char - Padding character (default: " ")

Examples

iex> DisplayWidth.pad("Hi", 5)
"Hi   "

iex> DisplayWidth.pad("Hi", 5, direction: :left)
"   Hi"

iex> DisplayWidth.pad("日", 4)
"日  "

string_width(string)

@spec string_width(String.t()) :: non_neg_integer()

Returns the total display width of a string.

Examples

iex> DisplayWidth.string_width("Hello")
5

iex> DisplayWidth.string_width("日本語")
6

iex> DisplayWidth.string_width("Café")
4

truncate(string, max_width)

@spec truncate(String.t(), non_neg_integer()) :: {String.t(), non_neg_integer()}

Truncates a string to fit within the given display width.

Returns the truncated string and its actual display width.

Examples

iex> DisplayWidth.truncate("Hello World", 5)
{"Hello", 5}

iex> DisplayWidth.truncate("日本語", 4)
{"日本", 4}

width(grapheme)

@spec width(String.t()) :: non_neg_integer()

Returns the display width of a grapheme cluster.

Examples

iex> DisplayWidth.width("A")
1

iex> DisplayWidth.width("日")
2

iex> DisplayWidth.width("é")  # e + combining acute
1

zero_width?(grapheme)

@spec zero_width?(String.t()) :: boolean()

Checks if a character is zero-width (combining character).

Examples

iex> DisplayWidth.zero_width?("\u0301")  # combining acute
true

iex> DisplayWidth.zero_width?("A")
false