mbtowc()
convert multibyte character to wide character
Function
SYNOPSIS DESCRIPTION PARAMETERS RETURN VALUES CONFORMANCE MULTITHREAD SAFETY LEVEL PORTING ISSUES AVAILABILITY SEE ALSO
pwc
Is the address of a wide character, type wchar_t, to receive the UNICODE equivalent of s.
s
Points to the multibyte character to be converted to UNICODE.
n
Is the maximum width, in bytes, for which to scan s for a valid multibyte sequence. Regardless of the value of n, no more than MB_CUR_MAX bytes are examined.
RETURN VALUES
If successful, mbtowc() returns the length, in bytes, of the multibyte character for which it found a UNICODE equivalent. If s is null or points to a null character, mbtowc() returns zero. If no valid multibyte sequence is found at s, mbtowc() returns -1.
Parameters
wchar
Address of a wide character (type wchar_t).
mbchar
Address of a sequence of bytes (a multibyte character).
count
Number of bytes to check.
locale
The locale to use.
Return Value
If mbchar is not NULL and if the object that mbchar points to forms a valid multibyte character, mbtowc returns the length in bytes of the multibyte character. If mbchar is NULL or the object that it points to is a wide-character null character (L'\0'), the function returns 0. If the object that mbchar points to does not form a valid multibyte character within the first count characters, it returns –1.
Remarks
The mbtowc function converts count or fewer bytes pointed to by mbchar, if mbchar is not NULL, to a corresponding wide character. mbtowc stores the resulting wide character at wchar, if wchar is not NULL. mbtowc does not examine more than MB_CUR_MAX bytes. mbtowc uses the current locale for locale-dependent behavior; _mbtowc_l is identical except that it uses the locale passed in instead.
Requirements
Routine Required header Compatibility
mbtowc
<stdlib.h>
ANSI, Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003
_mbtowc_l
<stdlib.h>
ANSI, Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003
For additional compatibility information, see Compatibility in the Introduction.
Libraries
All versions of the C run-time libraries.
Example
Copy Code
// crt_mbtowc.c
/* Illustrates the behavior of the mbtowc function
*/
printf( "Convert multibyte character back to a wide "
"character:\n" );
i = mbtowc( pwc, pmbc, MB_CUR_MAX );
printf( " Bytes converted: %u\n", i );
printf( " Wide character: %x\n\n", *pwc );
printf( "Attempt to convert when target is NULL\n" );
printf( " returns the length of the multibyte character:\n" );
i = mbtowc( pwcnull, pmbc, MB_CUR_MAX );
printf( " Length of multibyte character: %u\n\n", i );
printf( "Attempt to convert a NULL pointer to a" );
printf( " wide character:\n" );
pmbc = NULL;
i = mbtowc( pwc, pmbc, MB_CUR_MAX );
printf( " Bytes converted: %u\n", i );
}
Output
Convert a wide character to multibyte character:
Characters converted: 1
Multibyte character: 61
Convert multibyte character back to a wide character:
Bytes converted: 1
Wide character: 61
Attempt to convert when target is NULL
returns the length of the multibyte character:
Length of multibyte character: 1
Attempt to convert a NULL pointer to a wide character:
Bytes converted: 0