C Library Functions -mbtowc()

C Standard Library - <stdlib.h>

mbtowc()It is a function in the C standard library that converts a multibyte character to a wide character.

mbtowc()The declaration is located in<wchar.h>In the header file, it is mainly used to support conversion between multibyte character sets (such as UTF-8) and wide character sets (such as Unicode).

mbtowc()Used to convert a multibyte character (mbstr) into a wide character (wc). This function is based on the currentLC_CTYPEThe locale (environment settings) determines how multibyte characters are interpreted. If the multibyte character is valid, it is converted into a wide character. If the character is invalid, it returns-1。

Declaration

Below is the declaration of the mbtowc() function.

#include <wchar.h>

int mbtowc(wchar_t *wc, const char *mbstr, size_t n);

Parameters:

  • wc: points towchar_tA pointer to a variable of the type. This variable will receive the converted wide character.
  • mbstr: A pointer to the multibyte string, which is the sequence of multibyte characters to be converted.
  • n: indicatesmbstrThe maximum number of bytes in the string. Usually you can set it to the length of the string.

Return Value

  • If successful,mbtowc()Returns the number of bytes occupied by the converted character (i.e.,mbstrnumber of bytes of the multibyte character). Ifwcis notNULL, then the value is greater than 0.
  • If an error is encountered (such as an invalid multibyte character), the function returns-1。
  • If the end of the character sequence is reached (for example, encountering the string terminator\0), then return0。

Example

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

Example

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

int main()
{
    // Set the program's locale information
    setlocale(LC_CTYPE, "");

    // Multibyte string
    const char *str = "Here is example.com";

    // Wide character array to store the converted result
    wchar_t mb[100];
   
    // Current character index and converted wide-character length
    int i = 0;
    int len;
   
    // Convert each character to a wide character
    while (*str) {
        len = mbtowc(&mb[i], str, MB_CUR_MAX);  // Convert the current multibyte character
        if (len > 0) {
            str += len;  // Move to the start of the next character
            i++;  // Store into the wide character array
        } else if (len == 0) {
            break;  // Encountered the string terminator
        } else {
            // Error handling for invalid character
            printf("Invalid character\n");
            break;
        }
    }

    // Output the converted wide character string
    wprintf(L"%ls \n", mb);
   
    return 0;
}

Let us compile and run the above program, which will produce the following result, because it needs to output the result in multibyte form, which is a binary output.

这里是 example.com

Example

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

int main() {
    // Set the program's locale information
    setlocale(LC_CTYPE, "");

    const char *mbstr = Hello;
    wchar_t wc;

    // Convert character by character
    for (size_t i = 0; mbstr[i] != '\0'; i++) {
        int len = mbtowc(&wc, &mbstr[i], 1);
        if (len > 0) {
            wprintf(L"Converted wide character: %lc\n", wc);
            i += len - 1;  // Skip the number of bytes of the current multibyte character
        } else if (len == 0) {
            break;
        } else {
            printf("Invalid character\n");
        }
    }

    return 0;
}

Description:

  1. Multibyte Character Set: In a multibyte character set (such as UTF-8), a character may consist of multiple bytes, while a character in a wide character set (such as Unicode) is usually represented by a singlewchar_tvalue of the type (2 or 4 bytes on some platforms).

  2. Locale：mbtowc()The behavior of it depends on the current program's locale, especiallyLC_CTYPEsetting, which determines how the multibyte character set is interpreted. Therefore, when using this function, you usually need to usesetlocale()Set the appropriate locale.

  3. Error Handling: If the input multibyte string is not in a valid format, or cannot be converted to a wide character,mbtowc()will return-1. You need to check the return value to ensure the conversion is successful.

C Standard Library - <stdlib.h>

other extensions