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: %d\n", 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

Committed