What is std mbrtoc 32 in C++?
The std::mbrtoc32 method converts a character that is narrow and multibyte to its UTF-32 representation.
The number of bytes required to finish the next multibyte character (including any shift sequences) is determined by inspecting at most n bytes of the multibyte character string, starting with the byte that s points to. This process is carried out if s is not a null pointer. The function translates the next multibyte character in s to the appropriate 32-bit character and stores it in *pc32 (assuming pc32 is not null) if it finds that the character is complete and valid. Once *ps is updated following the initial call to this method, if the multibyte character in *s corresponds to a multi-char32_t sequence (which is not feasible with UTF-32), then the further calls to mbrtoc32 will write out the additional char32_t without taking *s into account.
In the event that s is a null pointer, the call is equal to std::mbrtoc32(nullptr, ", 1, ps), and the values of n and pc32 are ignored. The conversion state *ps denotes the first shift state if the wide-character generated is the null character. The active C locale determines the multibyte encoding that this function uses.
![What is std::mbrtoc32 in C++?](https://static.tutorialandexample.com/cpp/what-is-std-mbrtoc32-in-cpp1.png)
Parameters:
- s - pointer to the multibyte character string used as input;
- n - limit on the number of bytes in s that can be examined;
- PC32 - pointer to the location where the resulting 32-bit character will be written.
- Ps - a pointer to the conversion state object that is utilized to understand the multibyte string
Return value:
The first applicable of the following
- If the invalid character was the character that was changed over from s (and, if it wasn't invalid, put away in *pc32).
- The number of bytes [1...n] that were successfully transformed from s to the multibyte character.
- -3 in the event that *pc32 has now received the subsequent char32_t from a multi-char32_t character. In this instance, no bytes are processed from the input.
- -2 in the event that the subsequent n bytes make up an unfinished, but as of yet valid, multibyte character. *pc32 has nothing written to it.
- -1 Suppose there is an encoding problem. The value of *ps is unknown, nothing is written to *pc32, and the value of EILSEQ is kept in errno.
Usage notes:
- In order to use the mbrtoc32() function, compile the source code with the LANGLVL(EXTC1X) option.
- The CCSIDs offered by Unicode Services are the only ones that the mbrtoc32() function supports.
- When numerous mbstate_t objects—including the internal one—are used to convert multiple strings alternatively in a single thread, the outcome is undefinable.
- The mbrtoc32() method, assuming s is not a null pointer, examines up to n bytes starting from the byte that s points to calculate the number of bytes required to finish the subsequent multibyte character (including any shift sequences). The function first determines the values of the matching wide characters if it finds that the next multibyte character is complete and legal. If pc32 is not a null pointer, it stores the value of the first (or only) such character in the object that pc32 points to. Until all of the characters have been stored, further calls will store consecutive wide characters without requiring any additional input. The initial conversion state is the resultant state stated if the associated wide character is the null wide character.
- The mbrtoc32() function is the same as calling mbrtoc32(NULL,",1, ps) if s is a null pointer. In this instance, the values of the parameters pc32 and n are disregarded.
- In the event that ps is a null pointer, mbrtoc32() tracks the shift status using an internal object of its own. If not, *ps needs to be a legitimate mbstate_t object.
Example-1:
Let us take an example to illustrate the std::mbrtoc32 in C++
#include <cstdio>
#include <cstdlib>
#include <iostream>
#include <uchar.h>
#include <wchar.h>
using namespace std;
int main(void)
{
char32_t pc32;
char s[] = "S";
mbstate_t ps{};
int length;
// initializing the function
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%04hx\n", pc32);
return 0;
}
Output:
Multibyte string = S
Length = 1
32-bit character = 0x0053