mbstowcs() Function

The mbstowcs() function is declared in the header file <stdlib.h>.

The mbstowcs() function converts a multibyte string into its equivalent wide-character string. It processes the input sequence until it either reaches a specified maximum number of wide characters or encounters a null character in the source string, converting the characters based on the current locale’s LC_CTYPE settings.

Syntax of mbstowcs()

</>
Copy
size_t mbstowcs(wchar_t *dest, const char *src, size_t max);

Parameters

ParameterDescription
destPointer to an array of wchar_t elements where the converted wide characters will be stored. The array should be large enough to hold at most max characters.
srcC-string containing the multibyte characters to be converted. The multibyte sequence must begin in the initial shift state.
maxMaximum number of wchar_t characters to be written to dest.

The conversion behavior of mbstowcs() is dependent on the LC_CTYPE category of the current C locale. If the function processes exactly max characters, the resulting wide-character string in dest is not null-terminated.

Return Value

The function returns the number of wide characters written to dest, not including the terminating null character. If an invalid multibyte character is encountered during conversion, the function returns (size_t)-1.

Examples for mbstowcs()

Example 1: Converting a Basic Multibyte String

This example demonstrates how to convert a simple multibyte string to a wide-character string using mbstowcs().

Program

</>
Copy
#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>

int main() {
    const char *src = "Hello, World!";
    wchar_t dest[50];
    size_t ret;

    ret = mbstowcs(dest, src, 50);
    if (ret != (size_t)-1) {
        dest[ret] = L'\0'; // Ensure null-termination
        wprintf(L"Converted wide string: %ls\n", dest);
    } else {
        printf("Conversion error encountered.\n");
    }
    return 0;
}

Explanation:

  1. A multibyte string "Hello, World!" is defined.
  2. A wide-character array dest is allocated to store the converted string.
  3. mbstowcs() converts the multibyte string to wide characters, storing the result in dest.
  4. The return value, representing the number of wide characters converted, is used to add a null terminator.
  5. The converted wide-character string is printed using wprintf().

Program Output:

Converted wide string: Hello, World!

Example 2: Conversion with a Limited Buffer Size

This example shows how to convert a multibyte string when the destination buffer can only hold a limited number of wide characters. Note that if the limit is reached, the result may not be null-terminated.

Program

</>
Copy
#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>

int main() {
    const char *src = "This is a longer multibyte string.";
    wchar_t dest[10];
    size_t ret;

    ret = mbstowcs(dest, src, 9); // Leave space for manual null-termination
    if (ret != (size_t)-1) {
        dest[ret] = L'\0'; // Manual null-termination if possible
        wprintf(L"Partially converted wide string: %ls\n", dest);
    } else {
        printf("Conversion error encountered.\n");
    }
    return 0;
}

Explanation:

  1. The multibyte string src is longer than the destination buffer size.
  2. A destination array dest of limited size is allocated.
  3. mbstowcs() is called with a maximum conversion limit, so only a portion of the string is converted.
  4. A manual null terminator is added to ensure the wide-character string is properly terminated.
  5. The partially converted wide string is printed.

Program Output:

Partially converted wide string: This is a

Example 3: Handling an Invalid Multibyte Sequence

This example demonstrates how mbstowcs() handles an invalid multibyte sequence by checking the return value for an error indicator.

Program

</>
Copy
#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>

int main() {
    /* Assuming the source string contains an invalid multibyte sequence.
       This might not be easily reproducible on all systems, but serves as an example. */
    const char *src = "\xFF\xFFInvalid";
    wchar_t dest[50];
    size_t ret;

    ret = mbstowcs(dest, src, 50);
    if (ret == (size_t)-1) {
        printf("Conversion error: Invalid multibyte sequence encountered.\n");
    } else {
        dest[ret] = L'\0';
        wprintf(L"Converted wide string: %ls\n", dest);
    }
    return 0;
}

Explanation:

  1. An invalid multibyte sequence is provided in the source string.
  2. The mbstowcs() function attempts to convert the string.
  3. If an invalid sequence is encountered, the function returns (size_t)-1.
  4. The program checks the return value and prints an error message accordingly.

Program Output:

Conversion error: Invalid multibyte sequence encountered.