wcswidth() — Determine the display width of a wide-character string

Standards

Standards / Extensions	C or C++	Dependencies
XPG4 XPG4.2 Single UNIX Specification, Version 3	both

Format

#include <wchar.h>

int wcswidth(const wchar_t *wcs, size_t n);

General description

Determines the number of printing positions that a graphic representation of n wide characters (or fewer than n wide characters, if a NULL wide character is encountered before n wide characters have been exhausted), in the wide-character string pointed to by wcs, occupies on a display device. The number of printing positions is independent of its location on the device.

Returned value

If successful, wcswidth() returns the number of printing positions occupied by the wide-character string pointed to by wcs.

If wcs points to a NULL wide character, wcswidth() returns 0.

If any wide character in the wide-character string pointed to by wcs is not a printing wide character, wcswidth() returns -1.

The behavior of wcswidth() is affected by the LC_CTYPE category.

Note: Under z/OS® XL C/C++ applications, the width returned will be 1 for each single-byte character and 2 for each double-byte character.

Example

CELEBW27

⁄* CELEBW27 *⁄                                   
#include <stdio.h>                                                              
#include <wchar.h>                                                              
                                                                                
int main(void)                                                                  
{                                                                               
   wchar_t *wcs = L"ABC";                                                       
                                                                                
   printf("wcs has a width of: %d\n", wcswidth(wcs,3));                         
}

Output:

wcs has a width of: 3

Related information

wchar.h