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