Module terminal.text.width
Module to check and validate character display widths.
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 a cache of character widths as they have been measured.
To populate the cache with tested widths use test and test_write.
To check width, using the cached widths, use utf8cwidth and utf8swidth. Any
character not in the cache will be passed to system.utf8cwidth to determine the width.
Functions
| utf8cwidth (char) | Returns the width of a character in columns, matches system.utf8cwidth signature. |
| utf8swidth (str) | Returns the width of a string in columns, matches system.utf8swidth signature. |
Testing
| test (str) | Returns the width of the string, by test writing. |
| test_write (str) | Returns the width of the string, and writes it to the terminal. |
Functions
- utf8cwidth (char)
-
Returns the width of a character in columns, matches
system.utf8cwidthsignature. This will check the cache of recorded widths first, and if not found, usesystem.utf8cwidthto determine the width. It will not test the width.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, matches
system.utf8swidthsignature. It will use the cached widths, if no cached width is available it falls back onsystem.utf8cwidth. It will not test the width.Parameters:
- str string the string to check
Returns:
-
number
the width of the string in columns
Testing
- test (str)
-
Returns the width of the string, by test writing. Characters will be written 'invisible', so it does not show on the terminal, but it does need room to print them. The cursor is returned to its original position. It will read many character-widths at once, and hence is a lot faster than checking each character individually. The width of each character measured is recorded in the cache.
- the text stack is used to set the brightness to 0 before, and restore colors/attributes after the test.
- the test will be done at the current cursor position, and hence content there might be overwritten. Since a character is either 1 or 2 columns wide. The content of those 2 columns might have to be restored.
Parameters:
- str string the string of characters to test
Returns:
-
number
width in columns of the string
Or
- nil
- string error message
- test_write (str)
-
Returns the width of the string, and writes it to the terminal.
Writes the string to the terminal, visible, whilst at the same time injecting cursor-position queries
to detect the width of the unknown characters in the string.
It will read many character-widths at once, and hence is a lot faster than checking
each character individually.
The width of each character measured is recorded in the cache.
Parameters:
- str string the string of characters to write and test
Returns:
-
number
the width of the string in columns