wcswidth

wcswidth is a function in the C standard library used to determine the display width of a wide-character string when rendered in a terminal. It returns the number of column positions needed to display the first up to n wide characters from pwcs, according to the widths reported by wcwidth for each character. The function stops early if it encounters a null terminator within the first n characters.

Prototype and header: int wcswidth(const wchar_t *pwcs, size_t n); It is declared in the header <wchar.h>. The function analyzes the wide-character sequence pwcs and computes a width value suitable for alignment and text layout in terminal output.

Behavior: For each character in the range up to n or until the string terminator, wcswidth sums the value returned by wcwidth for that character. If any character has a negative width (wcwidth returns a negative value), the function returns -1 to indicate an error. Characters with width zero, such as certain combining marks, contribute zero to the total width, while characters with width one or two contribute 1 or 2, respectively. The result reflects how many columns the text would occupy on a typical terminal display.

Locale and portability: The width calculation depends on the current locale because wcwidth uses locale-specific rules. Consequently, wcswidth results can vary between locales and implementations. Programs should set an appropriate locale with setlocale when consistent results are required across environments. The function is defined in POSIX and widely available on Unix-like systems with wchar.h; behavior may differ on non-POSIX platforms or with nonconforming libraries.

See also: wcwidth, setlocale, wcslen.