\n\n

C Library Function – mbstowcs()

\n\n

Description

\n

The C library function mbstowcs is used to convert a multibyte string to a wide character string.

\n

The mbstowcs function is defined in the <stdlib.h> header file.

\n\n

Declaration

\n

Below is the declaration for the mbstowcs() function.

\n

size_t mbstowcs(wchar_t *pwcs, const char *mbs, size_t n);

\n\n

Parameters

\n

\n
• pwcs: A pointer to a buffer where the converted wide character string will be stored. If pwcs is NULL, the function returns the required buffer length without performing the actual conversion.
\n
• mbs: A pointer to the multibyte string.
\n
• n: The maximum number of characters to convert. If n characters have been converted before encountering the null terminator, the conversion stops early.
\n

\n\n

Return Value

\n

\n
• On success, it returns the number of wide characters converted, excluding the terminating null character.
\n
• If an invalid multibyte sequence is encountered, it returns (size_t)-1 and sets errno.
\n

\n\n

Example

\n

The following example demonstrates the usage of the mbstowcs() function.

\n\n

Example 1

\n

#include<stdio.h>\n#include<stdlib.h>\n#include<string.h>\n\nint main()\n{\n    int len;\n    char *pmbnull = NULL;\n    char *pmb = (char *)malloc(MB_CUR_MAX);\n    wchar_t *pwc = L"Hi";\n    wchar_t *pwcs = (wchar_t *)malloc(sizeof(wchar_t));\n\n    printf("Converting to multibyte stringn");\n    len = wcstombs(pmb, pwc, MB_CUR_MAX);\n    printf("Characters converted %dn", len);\n    printf("Hexadecimal value of first multibyte char: %#.4xn", pmb);\n\n    printf("Converting back to wide character stringn");\n    len = mbstowcs(pwcs, pmb, MB_CUR_MAX);\n    printf("Characters converted %dn", len);\n    printf("Hexadecimal value of first wide char: %#.4xnn", pwcs);\n\n    return(0);\n}

\n

Let us compile and run the above program, this will produce the following result:

\n

Converting to multibyte string\nCharacters converted 1\nHexadecimal value of first multibyte char: 0x19a60010\nConverting back to wide character string\nCharacters converted 1\nHexadecimal value of first wide char: 0x19a60030

\n\n

Example 2

\n

#include <stdio.h>\n#include <stdlib.h>\n#include <wchar.h>\n#include <locale.h>\n\nint main() {\n    // Set the current locale to the user's environment variable locale\n    setlocale(LC_ALL, "");\n\n    // Define a multibyte string\n    const char* mbstr = "Hello, World!";\n\n    // Calculate the required buffer size\n    size_t wcs_len = mbstowcs(NULL, mbstr, 0) + 1;\n\n    // Allocate wide character buffer\n    wchar_t* wcs = (wchar_t*)malloc(wcs_len * sizeof(wchar_t));\n    if (wcs == NULL) {\n        perror("malloc");\n        return 1;\n    }\n\n    // Perform the conversion\n    mbstowcs(wcs, mbstr, wcs_len);\n\n    // Print the wide character string\n    wprintf(L"%lsn", wcs);\n\n    // Free the allocated memory\n    free(wcs);\n\n    return 0;\n}

\n

Let us compile and run the above program, this will produce the following result:

\n

Hello, World!

\n\n

Notes

\n

\n
1. Locale: The function's behavior is affected by the current locale setting. Typically, you need to call setlocale before calling mbstowcs to set an appropriate locale.
\n
2. Error Handling: If the input multibyte string contains an invalid multibyte sequence, the function returns (size_t)-1 and sets errno. The caller needs to check the return value and handle potential errors.
\n
3. Memory Allocation: The caller must ensure that pwcs has enough space to store the converted wide character string. You can calculate the required buffer size by calling mbstowcs once with pwcs set to NULL.
\n