Namespaces
Variants

std:: codecvt_utf8

From cppreference.net
C++
Text processing library
Localization library
헤더 파일에 정의됨 <codecvt>
template <

class Elem,
unsigned long Maxcode = 0x10ffff ,
std:: codecvt_mode Mode = ( std:: codecvt_mode ) 0 >
class codecvt_utf8

: public std:: codecvt < Elem, char , std:: mbstate_t > ;
(C++11부터 사용 가능)
(C++17부터 사용 중지됨)
(C++26에서 제거됨)

std::codecvt_utf8 는 UTF-8로 인코딩된 바이트 문자열과 UCS-2 또는 UTF-32 문자 문자열( Elem 의 타입에 따라) 간의 변환을 캡슐화하는 std::codecvt 패싯입니다. 이 std::codecvt 패싯은 텍스트 및 바이너리 UTF-8 파일을 읽고 쓰는 데 사용할 수 있습니다.

UCS-2는 UTF-16의 하위 집합인 구식 인코딩으로, U+0000-U+FFFF(기본 다국어 평면) 범위의 스칼라 값만 인코딩합니다.

목차

템플릿 매개변수

Elem - char16_t , char32_t , 또는 wchar_t 중 하나
Maxcode - 이 패싯이 오류 없이 읽거나 쓸 수 있는 Elem 의 최대값
Mode - std::codecvt_mode 타입의 상수

멤버 함수

(constructor)
새로운 codecvt_utf8 패싯을 생성함
(public member function)
(destructor)
codecvt_utf8 패싯을 파괴함
(public member function)

std::codecvt_utf8:: codecvt_utf8

explicit codecvt_utf8 ( std:: size_t refs = 0 ) ;

새로운 std::codecvt_utf8 패싯을 생성하며, 초기 참조 카운터 refs 를 기본 클래스에 전달합니다.

매개변수

refs - 패싯에 연결되는 참조 횟수

std::codecvt_utf8:: ~codecvt_utf8

~codecvt_utf8 ( ) ;

패싯을 파괴합니다. 로캘에 의해 관리되는 패싯들과 달리, 이 패싯의 소멸자는 공개되어 있습니다.

std:: codecvt 로부터 상속됨

중첩 타입

유형 정의
intern_type internT
extern_type externT
state_type stateT

데이터 멤버

멤버 설명
std::locale::id id [static] 패싯 의 식별자

멤버 함수

do_out 을 호출합니다
( std::codecvt<InternT,ExternT,StateT> 의 public member function)
do_in 을 호출합니다
( std::codecvt<InternT,ExternT,StateT> 의 public member function)
do_unshift 을 호출합니다
( std::codecvt<InternT,ExternT,StateT> 의 public member function)
do_encoding 을 호출합니다
( std::codecvt<InternT,ExternT,StateT> 의 public member function)
do_always_noconv 을 호출합니다
( std::codecvt<InternT,ExternT,StateT> 의 public member function)
do_length 을 호출합니다
( std::codecvt<InternT,ExternT,StateT> 의 public member function)
do_max_length 을 호출합니다
( std::codecvt<InternT,ExternT,StateT> 의 public member function)

보호된 멤버 함수

[virtual]
InternT 에서 ExternT 로 문자열을 변환합니다(예: 파일에 쓸 때)
( std::codecvt<InternT,ExternT,StateT> 의 virtual protected 멤버 함수)
[virtual]
ExternT 에서 InternT 로 문자열을 변환합니다(예: 파일에서 읽을 때)
( std::codecvt<InternT,ExternT,StateT> 의 virtual protected 멤버 함수)
[virtual]
불완전한 변환을 위한 ExternT 문자들의 종료 문자 시퀀스를 생성합니다
( std::codecvt<InternT,ExternT,StateT> 의 virtual protected 멤버 함수)
[virtual]
하나의 InternT 문자를 생성하는 데 필요한 ExternT 문자 수를 반환합니다(상수일 경우)
( std::codecvt<InternT,ExternT,StateT> 의 virtual protected 멤버 함수)
[virtual]
모든 유효한 인수 값에 대해 항등 변환을 인코딩하는지 테스트합니다
( std::codecvt<InternT,ExternT,StateT> 의 virtual protected 멤버 함수)
[virtual]
주어진 InternT 버퍼로 변환될 때 소비될 ExternT 문자열의 길이를 계산합니다
( std::codecvt<InternT,ExternT,StateT> 의 virtual protected 멤버 함수)
[virtual]
단일 InternT 문자로 변환될 수 있는 최대 ExternT 문자 수를 반환합니다
( std::codecvt<InternT,ExternT,StateT> 의 virtual protected 멤버 함수)

std:: codecvt_base 로부터 상속됨

중첩 타입 정의
enum result { ok, partial, error, noconv } ; 범위 없는 열거형 타입
열거형 상수 정의
ok 오류 없이 변환이 완료됨
partial 모든 소스 문자가 변환되지 않음
error 유효하지 않은 문자를 만남
noconv 변환이 필요 없음, 입력과 출력 타입이 동일함

참고 사항

표준에서는 Elem 의 크기가 16비트일 때 이 패싯이 UCS-2와 함께 작동하도록 요구하지만, 일부 구현에서는 대신 UTF-16을 사용합니다. "UCS-2"라는 용어는 더 이상 사용되지 않으며 ISO 10646에서 제거되었습니다.

예제

다음 예제는 UCS-2/UTF-8과 UTF-16/UTF-8 변환 간의 차이를 보여줍니다: 문자열의 세 번째 문자는 유효한 UCS-2 문자가 아닙니다.

이 코드 실행 
#include <codecvt>
#include <cstdint>
#include <iostream>
#include <locale>
#include <string>
int main()
{
    // UTF-8 data. The character U+1d10b, musical sign segno, does not fit in UCS-2
    std::string utf8 = "z\u6c34\U0001d10b";
    // the UTF-8 / UTF-16 standard conversion facet
    std::wstring_convert<std::codecvt_utf8_utf16<char16_t>, char16_t> utf16conv;
    std::u16string utf16 = utf16conv.from_bytes(utf8);
    std::cout << "UTF-16 conversion produced " << utf16.size() << " code units:\n"
              << std::showbase << std::hex;
    for (char16_t c : utf16)
        std::cout << static_cast<std::uint16_t>(c) << ' ';
    // the UTF-8 / UCS-2 standard conversion facet
    std::wstring_convert<std::codecvt_utf8<char16_t>, char16_t> ucs2conv;
    try
    {
        std::u16string ucs2 = ucs2conv.from_bytes(utf8);
    }
    catch(const std::range_error& e)
    {
        std::u16string ucs2 = ucs2conv.from_bytes(utf8.substr(0, ucs2conv.converted()));
        std::cout << "\nUCS-2 failed after producing " << std::dec << ucs2.size()
                  << " characters:\n" << std::showbase << std::hex;
        for (char16_t c : ucs2)
            std::cout << static_cast<std::uint16_t>(c) << ' ';
        std::cout << '\n';
    }
}

출력: 

UTF-16 conversion produced 4 code units:
0x7a 0x6c34 0xd834 0xdd0b
UCS-2 failed after producing 2 characters:
0x7a 0x6c34

결함 보고서

다음의 동작 변경 결함 보고서들은 이전에 발표된 C++ 표준에 소급 적용되었습니다.

DR 적용 대상 게시된 동작 올바른 동작
LWG 2229 C++98 생성자와 소멸자가 명시되지 않았음 명시함

참고 항목

문자
변환 		로케일 정의 멀티바이트
(UTF-8, GB18030) 		UTF-8
UTF-16
UTF-16 mbrtoc16 / c16rtomb (C11의 DR488 포함)

codecvt < char16_t , char ,mbstate_t >
codecvt_utf8_utf16 < char16_t >
codecvt_utf8_utf16 < char32_t >
codecvt_utf8_utf16 < wchar_t >

해당 없음
UCS-2 c16rtomb (C11의 DR488 없이) codecvt_utf8 < char16_t > codecvt_utf16 < char16_t >
UTF-32

mbrtoc32 / c32rtomb

codecvt < char32_t , char ,mbstate_t >
codecvt_utf8 < char32_t >

codecvt_utf16 < char32_t >

시스템 wchar_t :

UTF-32 (비윈도우)
UCS-2 (윈도우)

mbsrtowcs / wcsrtombs
use_facet < codecvt
< wchar_t , char ,mbstate_t >> ( locale )

codecvt_utf8 < wchar_t > codecvt_utf16 < wchar_t >
문자 인코딩 간 변환 (UTF-8, UTF-16, UTF-32 포함)
(클래스 템플릿)
(C++11) (C++17에서 사용 중단됨) (C++26에서 제거됨)
표준 codecvt 패싯의 동작을 변경하는 태그
(열거형)
(C++11) (C++17에서 사용 중단됨) (C++26에서 제거됨)
UTF-16과 UCS-2/UCS-4 간 변환
(클래스 템플릿)
(C++11) (C++17에서 사용 중단됨) (C++26에서 제거됨)
UTF-8과 UTF-16 간 변환
(클래스 템플릿)