C mbtowc() Function – stdlib.h

mbtowc() Function

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

The mbtowc() function converts a multibyte sequence to its wide character equivalent, facilitating internationalization and character encoding conversion. It handles an internal shift state, making it useful for processing multibyte character encodings based on the current locale settings.

---

Syntax of mbtowc()

int mbtowc(wchar_t *pwc, const char *pmb, size_t max);

Parameters

Parameter	Description
pwc	A pointer to an object of type wchar_t where the converted wide character will be stored. This argument can be NULL if storage is not required.
pmb	A pointer to the first byte of the multibyte character to be converted. When this is NULL, the function resets its internal shift state.
max	The maximum number of bytes to consider from pmb. No more than MB_CUR_MAX bytes are examined.

The function behavior depends on the LC_CTYPE category of the current locale, and it maintains an internal shift state that can be reset by passing a NULL pointer as the multibyte character.

---

Return Value

If pmb is not NULL and the multibyte character forms a valid wide character, the function returns the number of bytes processed. If the multibyte character is the terminating null character, it returns zero. On failure, it returns -1. When pmb is NULL, it returns a nonzero value if the encoding is state-dependent, and zero otherwise.

---

Examples for mbtowc()

Example 1: Converting a Simple Multibyte Character

This example demonstrates how to convert a single multibyte character to its wide character equivalent.

Program

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

int main() {
    char mbStr[] = "A";  // Multibyte character
    wchar_t wc;
    int bytes;

    bytes = mbtowc(&wc, mbStr, sizeof(mbStr));
    if (bytes > 0) {
        printf("Converted wide character: %lc\n", wc);
        printf("Bytes processed: %d\n", bytes);
    } else {
        printf("Conversion failed.\n");
    }

    return 0;
}

Explanation:

1. A multibyte string "A" is defined.
2. The mbtowc() function converts the multibyte character to a wide character and stores it in wc.
3. The function returns the number of bytes processed which is printed along with the wide character.

Program Output:

Converted wide character: A
Bytes processed: 1

Example 2: Resetting the Internal Shift State

This example shows how to reset the internal shift state of mbtowc() by passing a NULL pointer as the multibyte sequence.

Program

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

int main() {
    int result;

    // Reset the internal shift state
    result = mbtowc(NULL, NULL, 0);
    if (result == 0) {
        printf("Encoding is not state-dependent or reset was successful.\n");
    } else {
        printf("Encoding is state-dependent.\n");
    }

    return 0;
}

Explanation:

1. The function is called with NULL for both the wide character pointer and the multibyte character pointer.
2. This resets the internal shift state of the conversion function.
3. The return value indicates whether the encoding is state-dependent (nonzero) or not (zero).

Program Output:

Encoding is not state-dependent or reset was successful.

Example 3: Converting a Multibyte String with a Null Character

This example demonstrates the behavior of mbtowc() when the multibyte character represents the terminating null character.

Program

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

int main() {
    char nullChar[] = "\0";
    wchar_t wc;
    int bytes;

    bytes = mbtowc(&wc, nullChar, sizeof(nullChar));
    if (bytes == 0) {
        printf("Null character encountered; conversion returned 0.\n");
    } else if (bytes == -1) {
        printf("Conversion failed.\n");
    } else {
        printf("Converted wide character: %lc\n", wc);
        printf("Bytes processed: %d\n", bytes);
    }

    return 0;
}

Explanation:

1. A multibyte string containing only a terminating null character is defined.
2. The mbtowc() function processes the null character and returns 0, indicating the termination.
3. The program checks the return value and prints the appropriate message.

Program Output:

Null character encountered; conversion returned 0.