C++ mbrtoc32()

The mbrtoc32() function is defined in <cuchar> header file.

mbrtoc32() prototype

size_t mbrtoc32( char32_t* pc32, const char* s, size_t n, mbstate_t* ps);

The mbrtoc32() function converts at most n multibyte character represented by s to its equivalent utf-32 character and stores it in the memory location pointed to by pc32.

If s represents a null pointer, the values of n and pc32 are ignored and the call to is equivalent to mbrtoc32(NULL, "", 1, ps).

If the resulting character produced is null, the conversion state *ps represents the initial shift state.

mbrtoc32() Parameters

• pc32: Pointer to the memory location to store the resulting 32 bit character.
• s: Pointer to the multibyte character to convert.
• n: Maximum number of bytes in s to convert.
• ps: A pointer to an mbstate_t object used when interpreting the multibyte string.

mbrtoc32() Return value

The mbrtoc32() function returns the first of the following value that matches the cases below:

• 0 if the converted character is a null character.
• the number of bytes (at most n) of the multibyte character that was successfully converted to 32 bit character.
• -3 if the next char32_t from a multi-char32_t character (e.g. a surrogate pair) has now been written to *pc32. No bytes are processed from the input in this case.
• -2 if the next n bytes constitute an incomplete, but so far valid, multibyte character. In this case nothing is written to *pc32.
• -1 if encoding error occurs. In this case nothing is written to *pc32, errno is set to EILSEQ and the value of *ps is unspecified.

Example: How mbrtoc32() function works?

#include <cstdio>
#include <cstdlib>
#include <cuchar>
#include <iostream>
using namespace std;

int main(void)
{
	char32_t pc32;
	char s[] = "x" ;
	mbstate_t ps;
	int length;

	length = mbrtoc32(&pc32, s, MB_CUR_MAX, &ps);
	if (length < 0)
	{
		perror("mbrtoc32() fails to convert");
		exit(-1);
	}

	cout << "Multibyte string = " << s << endl;
	cout << "Length = " << length << endl;
	printf ("32-bit character = 0x%08hx\n", pc32);

	return 0;
}

When you run the program, the output will be:

Multibyte string = x
Length = 1
32-bit character = 0x00000078