Module terminal.text.width
Module for character and string display width in terminal columns.
Not all characters are displayed with the same width on the terminal. The Unicode standard defines the width of many characters, but not all. Especially the 'ambiguous width' characters can be displayed with different widths especially when used with East Asian languages. The only way to truly know their display width is to write them to the terminal and measure the cursor position change.
This module implements ambiguous-width configuration and detection (default 1). Preferably, ambiguous width is detected once during terminal initialization.
The functions utf8cwidth and utf8swidth can be used to get the display width of characters and strings, respectively.
Functions
| detect_ambiguous_width () | Detects and sets the width of the abiguous width characters. |
| get_ambiguous_width () | Returns the current width used for ambiguous-width characters. |
| set_ambiguous_width (n) | Sets the width used for ambiguous-width characters. |
| utf8cwidth (char) | Returns the width of a character in columns. |
| utf8swidth (str) | Returns the width of a string in columns. |
Text
| truncate_ellipsis (width[, text=""[, trunc_type="right"[, ellipsis="…"]]]) | Truncates text to fit within a given width, adding ellipsis as needed. |
Functions
- detect_ambiguous_width ()
-
Detects and sets the width of the abiguous width characters.
Writes a test character and queries the cursor position. Returns (and sets) the default value 1 if detection fails.
The preferred way to call this function is during terminal initialization, see terminal.initialize.
Returns:
-
number
1 or 2
- get_ambiguous_width ()
-
Returns the current width used for ambiguous-width characters.
Returns:
-
number
1 or 2
- set_ambiguous_width (n)
-
Sets the width used for ambiguous-width characters.
Parameters:
- n number 1 or 2
- utf8cwidth (char)
-
Returns the width of a character in columns.
Calculates character width, using the configured ambiguous width for ambiguous characters.
Parameters:
- char string or number the character (string or codepoint) to check
Returns:
-
number
the width of the first character in columns
- utf8swidth (str)
-
Returns the width of a string in columns.
Calculates string width, using the configured ambiguous width for ambiguous characters.
Parameters:
- str string the string to check
Returns:
-
number
the width of the string in columns
Text
- truncate_ellipsis (width[, text=""[, trunc_type="right"[, ellipsis="…"]]])
-
Truncates text to fit within a given width, adding ellipsis as needed.
Shortens text if necessary, adds ellipsis when truncated. Respects UTF-8
character boundaries and handles double-width characters correctly.
Parameters:
- width number The available width for the text in columns.
- text string The text to truncate. (default "")
- trunc_type string The type of truncation to apply: - "right": Truncate from the right, show beginning of text with ellipsis on the right - "left": Truncate from the left, show end of text with ellipsis on the left - "drop": Drop the entire text if it doesn't fit (return empty string). (default "right")
- ellipsis string The ellipsis string to use. Defaults to Unicode ellipsis character "…". Can be a multi-character string or empty string. (default "…")
Returns:
- string The truncated text (may be empty string).
- number The size of the returned text in columns.
Usage:
-- Truncate from right (default) truncate_ellipsis(10, "Very long text") -- "Very long…" -- Truncate from left truncate_ellipsis(10, "Very long text", "left") -- "…long text" -- Drop if too small truncate_ellipsis(3, "Very long text", "drop") -- "" -- Custom ellipsis truncate_ellipsis(10, "Very long text", "right", "..") -- "Very lon.." -- Empty string as ellipsis just truncates the text truncate_ellipsis(10, "Very long text", "left", "") -- " long text"