mbstowcs
Converts a sequence of multibyte characters to a corresponding sequence of wide characters.
size_tmbstowcs(wchar_t*wcstr,constchar*mbstr,size_tcount**);**
| Routine | Required Header | Compatibility |
| mbstowcs | <stdlib.h> | ANSI, Win 95, Win NT |
For additional compatibility information, see Compatibility in the Introduction.
Libraries
| LIBC.LIB | Single thread static library, retail version |
| LIBCMT.LIB | Multithread static library, retail version |
| MSVCRT.LIB | Import library for MSVCRT.DLL, retail version |
Return Value
If mbstowcs successfully converts the source string, it returns the number of converted multibyte characters. If the wcstr argument is NULL, the function returns the required size of the destination string. If mbstowcs encounters an invalid multibyte character, it returns –1. If the return value is count, the wide-character string is not null-terminated.
Parameters
wcstr
The address of a sequence of wide characters
mbstr
The address of a sequence of multibyte characters
count
The number of multibyte characters to convert
Remarks
The mbstowcs function converts count or fewer multibyte characters pointed to by mbstr to a string of corresponding wide characters that are determined by the current locale. It stores the resulting wide-character string at the address represented by wcstr. The result is similiar to a series of calls to mbtowc. If mbstowcs encounters the single-byte null character ('\0') either before or when count occurs, it converts the null character to a wide-character null character (L'\0') and stops. Thus the wide-character string at wcstr is null-terminated only if a null character is encountered during conversion. If the sequences pointed to by wcstr and mbstr overlap, the behavior is undefined.
If the wcstr argument is NULL, mbstowcs returns the required size of the destination string.
Example
/* MBSTOWCS.CPP illustrates the behavior of the mbstowcs function
*/
#include <stdlib.h>
#include <stdio.h>
void main( void )
{
int i;
char *pmbnull = NULL;
char *pmbhello = (char *)malloc( MB_CUR_MAX );
wchar_t *pwchello = L"Hi";
wchar_t *pwc = (wchar_t *)malloc( sizeof( wchar_t ));
printf( "Convert to multibyte string:\n" );
i = wcstombs( pmbhello, pwchello, MB_CUR_MAX );
printf( "\tCharacters converted: %u\n", i );
printf( "\tHex value of first" );
printf( " multibyte character: %#.4x\n\n", pmbhello );
printf( "Convert back to wide-character string:\n" );
i = mbstowcs( pwc, pmbhello, MB_CUR_MAX );
printf( "\tCharacters converted: %u\n", i );
printf( "\tHex value of first" );
printf( " wide character: %#.4x\n\n", pwc );
}
Output
Convert to multibyte string:
Characters converted: 1
Hex value of first multibyte character: 0x0e1a
Convert back to wide-character string:
Characters converted: 1
Hex value of first wide character: 0x0e1e
Data Conversion Routines | Locale Routines | Interpretation of Multibyte-Character Sequences