C/C++ mbrtoc32() 함수 완벽 가이드 – 문법, 매개변수, 반환 값과 예제

이 글에서는 C++ STL의 std::mbrtoc32() 함수가 어떻게 동작하는지, 그 문법과 실제 사용 예제를 자세히 살펴보겠습니다.

std::mbrtoc32()란 무엇인가?

std::mbrtoc32()는 C++ 표준 라이브러리에 내장된 함수로, <cuchar> 헤더 파일에 정의되어 있습니다. 이 함수는 좁은(narrow) 멀티바이트 문자를 UTF-32 문자 표현으로 변환하는 데 사용됩니다.

연관된 문자 포인터가 null이 아니고 나머지 매개변수들도 모두 유효하다면, 해당 문자를 32비트 문자로 변환합니다.

문법

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

매개변수

이 함수는 다음과 같은 매개변수를 받습니다.

pc32 − 변환 결과를 저장하고자 하는 위치를 가리키는 포인터입니다.
str − 입력으로 사용되는 문자열입니다.
n − 검사할 바이트 수입니다.
ps − 멀티바이트 문자열을 해석할 때 사용되는 상태 객체(mbstate_t)에 대한 포인터입니다.

반환 값

이 함수는 조건에 따라 다음과 같은 값을 반환합니다.

0 − 변환 대상인 str의 문자가 널(NULL) 문자일 때 0을 반환합니다.
1~n − 문자열 *str에서 변환된 멀티바이트 문자의 바이트 수입니다.
-3 − 서러게이트 쌍(surrogate pair)이 존재하는 경우, 즉 char32_t 값이 여러 개의 char32_t 시퀀스로 구성된 경우 반환됩니다. 이때 입력으로부터 소비되는 바이트는 없습니다.
-2 − 다음 n바이트가 불완전하지만 지금까지 읽은 부분은 유효한 멀티바이트 문자인 경우 반환됩니다.
-1 − 인코딩 오류가 발생한 경우 반환되며, 이때 *pc32에는 아무것도 기록되지 않습니다.

예제 1

#include <cstdio>
#include <cstdlib>
#include <iostream>
#include <uchar.h>
#include <wchar.h>
using namespace std;

int main(void) {
    char32_t hold;
    char str[] = "I";
    mbstate_t arr{};
    int len;

    // 함수 초기화 및 호출
    len = mbrtoc32(&hold, str, MB_CUR_MAX, &arr);
    if (len < 0) {
       perror("conversion failed");
       exit(-1);
    }
    cout << "String is: " << str << endl;
    cout << "Length is: " << len << endl;
    printf("32-bit character = 0g%02hd\n", hold);
}

출력

String is: I
Length is: 1
32-bit character = 0g73

예제 2

#include <cstdio>
#include <cstdlib>
#include <iostream>
#include <uchar.h>
#include <wchar.h>
using namespace std;

int main(void) {
    char32_t hold;
    char str[] = "I";
    mbstate_t arr{};
    int len;

    // 함수 초기화 및 호출
    len = mbrtoc32(&hold, str, MB_CUR_MAX, &arr);
    if (len < 0) {
       perror("conversion failed");
       exit(-1);
    }
    cout << "String is: " << str << endl;
    cout << "Length is: " << len << endl;
    printf("32-bit character = 0x%08hx\n", hold);
}

출력

String is: I
Length is: 1
32-bit character = 0x00000049

위 예제들은 문자 'I'를 멀티바이트 문자열에서 UTF-32 문자로 변환하는 과정을 보여줍니다. mbrtoc32()는 성공적으로 변환된 바이트 수를 반환하며, 변환된 값은 char32_t 변수에 저장됩니다. 두 번째 예제에서는 16진수 형식 지정자(%08hx)를 사용하여 문자 'I'의 유니코드 코드 포인트인 0x49를 확인할 수 있습니다.