illumos: manual page: wcswidth

WCSWIDTH(3C) Standard C Library Functions WCSWIDTH(3C)

NAME

wcswidth, wcswidth_l - determine number of columns for wide-character
string

SYNOPSIS

#include <wchar.h>

int
wcswidth(const wchar_t *str, size_t len);

#include <wchar.h>
#include <xlocale.h>

int
wcswidth_l(const wchar_t *str, size_t len, locale_t loc);

DESCRIPTION

The wcswidth() and wcswidth_l() functions count the total number of columns
that are required to display the contents of the wide-character string str.
For each wide-character in the string str, the equivalent of wcwidth(3C) is
called and the result summed to a running total which is returned.

Up to len wide-characters from str will be evaluated; however, the
functions will stop iterating if they encounter the null wide-character
(L'\0').

The wide-characters in str must be valid characters in the current locale
or in the case of the wcswidth_l() function, the locale specified by loc.
The functions will fail if any of the wide-characters in str are valid in
the current locale, but considered non-printable (as in iswprint(3C) would
fail for the character) or the wide-character does not represent a valid
character in the locale.

RETURN VALUES

Upon successful completion, the wcswidth() and wcswidth_l() functions
return the total number of columns that are required to display the wide-
character string. Otherwise, -1 is returned to indicate that an invalid or
non-printable wide-character was encountered.

EXAMPLES

Example 1 Using the wcswidth() function to count characters in a string.

#include <wchar.h>
#include <stdio.h>

int
main(void)
{
wchar_t *str = L"Hello world";
int ret = wcswidth(str, wcslen(str));
(void) printf("wcswidth returned: %d0, ret);
return (0);
}

When compiled and run, this program outputs:

$ gcc -Wall -Wextra example.c
$ ./a.out
wcswidth returned: 11

MT-LEVEL
The wcswidth() function is MT-Safe as long as the thread-specific or global
locale is not changed while it is running.

The wcswidth_l() function is MT-Safe as long as the locale loc is not freed
while the function is running.

INTERFACE STABILITY