QStringConverter Class
QStringConverter 클래스는 텍스트 인코딩 및 디코딩을 위한 기본 클래스를 제공합니다. 더 보기...
| Header: | #include <QStringConverter> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
| 상속됨: |
참고: 이 클래스의 모든 함수는 재인용됩니다.
공용 유형
| enum | Encoding { Utf8, Utf16, Utf16BE, Utf16LE, Utf32, …, System } |
| enum class | Flag { Default, ConvertInvalidToNull, WriteBom, ConvertInitialBom, Stateless } |
| flags | Flags |
공용 함수
| bool | hasError() const |
| bool | isValid() const |
| const char * | name() const |
| void | resetState() |
정적 공용 멤버
| QStringList | availableCodecs() |
| std::optional<QStringConverter::Encoding> | encodingForData(QByteArrayView data, char16_t expectedFirstCharacter = 0) |
| std::optional<QStringConverter::Encoding> | encodingForHtml(QByteArrayView data) |
| std::optional<QStringConverter::Encoding> | encodingForName(QAnyStringView name) |
| const char * | nameForEncoding(QStringConverter::Encoding e) |
상세 설명
Qt는 UTF-16을 사용하여 문자열을 저장, 그리기 및 조작합니다. 많은 상황에서 다른 인코딩을 사용하는 데이터를 처리하고 싶을 수 있습니다. 파일과 네트워크 연결을 통해 전송되는 대부분의 텍스트 데이터는 UTF-8로 인코딩됩니다.
QStringConverter 클래스는 서로 다른 텍스트 인코딩 간의 변환을 도와주는 QStringEncoder 및 QStringDecoder 클래스의 베이스 클래스입니다. QStringDecoder 는 인코딩된 표현의 문자열을 Qt 내부에서 사용하는 형식인 UTF-16으로 디코딩할 수 있습니다. QStringEncoder 는 반대 작업을 수행하여 UTF-16 인코딩된 데이터(일반적으로 QString 의 형태)를 요청된 인코딩으로 인코딩합니다.
항상 지원되는 인코딩은 다음과 같습니다:
- UTF-8
- UTF-16
- UTF-16BE
- UTF-16LE
- UTF-32
- UTF-32BE
- UTF-32LE
- ISO-8859-1(라틴-1)
- 시스템 인코딩
QStringConverter는 Qt 컴파일 방식에 따라 더 많은 인코딩을 지원할 수 있습니다. 더 많은 코덱이 지원되는 경우 availableCodecs()를 사용하여 나열할 수 있습니다.
QStringConverter를 다음과 같이 사용하여 일부 인코딩된 문자열을 UTF-16으로 변환할 수 있습니다.
UTF-8로 인코딩된 문자열이 있는데 이를 QString 로 변환하고 싶다고 가정해 보겠습니다. 간단한 방법은 QStringDecoder 을 다음과 같이 사용하는 것입니다:
QByteArray encodedString = "..."; auto toUtf16 = QStringDecoder(QStringDecoder::Utf8); QString string = toUtf16(encodedString);
이 후 string 은 디코딩된 형태의 텍스트를 보유합니다. QStringEncoder 클래스를 사용하여 문자열을 유니코드에서 로컬 인코딩으로 변환하는 것도 마찬가지로 쉽습니다:
QString string = "..."; auto fromUtf16 = QStringEncoder(QStringEncoder::Utf8); QByteArray encodedString = fromUtf16(string);
다양한 인코딩으로 텍스트 파일을 읽거나 쓰려면 QTextStream 및 setEncoding() 함수를 사용합니다.
예를 들어 네트워크를 통해 데이터를 수신할 때와 같이 청크 단위로 데이터를 변환하려고 할 때는 약간의 주의를 기울여야 합니다. 이러한 경우 멀티바이트 문자가 두 개의 청크로 분할될 수 있습니다. 이로 인해 문자가 손실될 수 있으며 최악의 경우 전체 변환이 실패할 수도 있습니다.
QStringEncoder 와 QStringDecoder 에서는 내부 상태에서 이를 추적하여 이를 쉽게 해결할 수 있습니다. 따라서 다음 데이터 청크로 인코더 또는 디코더를 다시 호출하기만 하면 자동으로 데이터를 올바르게 인코딩 또는 디코딩할 수 있습니다:
auto toUtf16 = QStringDecoder(QStringDecoder::Utf8); QString string; while (new_data_available()) { QByteArray chunk = get_new_data(); string += toUtf16(chunk); }
QStringDecoder 객체는 청크 사이의 상태를 유지하므로 멀티바이트 문자가 청크 사이에 분할되어 있어도 올바르게 작동합니다.
QStringConverter 객체는 내부 상태 때문에 복사할 수 없지만 이동할 수는 있습니다.
QTextStream, QStringDecoder, QStringEncoder 를참조하세요 .
멤버 유형 문서
enum QStringConverter::Encoding
| 상수 | 값 | 설명 |
|---|---|---|
QStringConverter::Utf8 | 0 | UTF-8로 변환하거나 UTF-16으로 변환하는 변환기 만들기 |
QStringConverter::Utf16 | 1 | UTF-16으로 변환하거나 UTF-8로 변환하는 변환기를 생성합니다. 디코딩할 때 바이트 순서는 선행 바이트 순서 표시를 통해 자동으로 감지됩니다. 없는 경우 또는 인코딩 시에는 시스템 바이트 순서가 사용됩니다. |
QStringConverter::Utf16BE | 3 | 빅엔디안 UTF-16으로 변환하거나 빅엔디안 UTF-16으로 변환하는 변환기를 만듭니다. |
QStringConverter::Utf16LE | 2 | 리틀 엔디안 UTF-16으로 변환하거나 리틀 엔디안 UTF-16으로 변환하는 변환기를 만듭니다. |
QStringConverter::Utf32 | 4 | UTF-32로 변환하거나 UTF-32로 변환하는 변환기를 만듭니다. 디코딩할 때 선행 바이트 순서 표시를 통해 바이트 순서가 자동으로 감지됩니다. 선행 바이트 순서가 없거나 인코딩 시에는 시스템 바이트 순서가 사용됩니다. |
QStringConverter::Utf32BE | 6 | 빅엔디안 UTF-32로 변환하거나 빅엔디안 UTF-32로 변환하는 변환기를 만듭니다. |
QStringConverter::Utf32LE | 5 | 리틀 엔디안 UTF-32로 변환하거나 리틀 엔디안 UTF-32로 변환하는 변환기를 만듭니다. |
QStringConverter::Latin1 | 7 | ISO-8859-1(Latin1)로 변환하거나 변환하는 변환기를 만듭니다. |
QStringConverter::System | 8 | 운영 체제 로캘의 기본 인코딩을 변환하거나 변환하는 변환기를 만듭니다. 이것은 항상 유닉스 기반 시스템의 경우 UTF-8로 가정합니다. Windows에서는 로캘 코드 페이지에서 변환합니다. |
열거형 클래스 QStringConverter::Flag
플래그 QStringConverter::Flags
| Constant | 값 | 설명 |
|---|---|---|
QStringConverter::Flag::Default | 0 | 기본 변환 규칙이 적용됩니다. |
QStringConverter::Flag::ConvertInvalidToNull | 0x2 | 이 플래그가 설정되어 있으면 유효하지 않은 각 입력 문자는 null 문자로 출력됩니다. 설정하지 않으면 잘못된 입력 문자는 출력 인코딩이 해당 문자를 표현할 수 있는 경우 QChar::ReplacementCharacter, 그렇지 않은 경우 물음표로 표시됩니다. |
QStringConverter::Flag::WriteBom | 0x4 | QString 에서 출력 인코딩으로 변환할 때 출력 인코딩이 이를 지원하는 경우 첫 번째 문자로 QChar::ByteOrderMark 을 작성합니다. UTF-8, UTF-16 및 UTF-32 인코딩이 이에 해당합니다. |
QStringConverter::Flag::ConvertInitialBom | 0x8 | 입력 인코딩에서 QString 로 변환할 때 QStringDecoder 은 일반적으로 선행 QChar::ByteOrderMark 을 건너뜁니다. 이 플래그를 설정하면 바이트 순서 표시를 건너뛰지 않고 utf-16으로 변환하여 생성된 QString 의 시작 부분에 삽입합니다. |
QStringConverter::Flag::Stateless | 0x1 | 문자열 인코딩 또는 디코딩을 위해 서로 다른 함수 호출 간에 발생할 수 있는 변환기 상태를 무시합니다. 또한 불완전한 데이터 시퀀스가 발생하면 QStringConverter 에 오류가 발생합니다. |
Flags 유형은 QFlags<Flag>에 대한 typedef입니다. 플래그 값의 OR 조합을 저장합니다.
멤버 함수 문서
[static] QStringList QStringConverter::availableCodecs()
지원되는 코덱의 이름 목록을 반환합니다. 이 함수가 반환한 이름은 QStringEncoder 및 QStringDecoder 의 생성자에 전달하여 지정된 코덱에 대한 en 또는 디코더를 생성할 수 있습니다.
이 함수는 표준 코덱 외에 추가 코덱 목록을 가져오는 데 사용할 수 있습니다. 추가 코덱을 지원하려면 ICU 라이브러리를 지원하여 Qt를 컴파일해야 합니다.
참고: 코덱의 순서는 내부 구현 세부 사항이며 안정성을 보장하지 않습니다.
[static noexcept] std::optional<QStringConverter::Encoding> QStringConverter::encodingForData(QByteArrayView data, char16_t expectedFirstCharacter = 0)
data 콘텐츠의 인코딩을 확인할 수 있는 경우 인코딩을 반환합니다. expectedFirstCharacter 인코딩을 확인하는 데 도움이 되는 추가 힌트로 전달할 수 있습니다.
인코딩이 불분명하면 반환되는 옵션은 비어 있습니다.
[static] std::optional<QStringConverter::Encoding> QStringConverter::encodingForHtml(QByteArrayView data)
HTML 메타 태그의 선행 바이트 순서 표시 또는 문자 집합 지정자를 확인하여 data 에서 HTML의 인코딩을 결정하려고 시도합니다. 옵션이 비어 있으면 지정된 인코딩이 QStringConverter 에서 지원되지 않습니다. 인코딩이 감지되지 않으면 이 메서드는 Utf8을 반환합니다.
QStringDecoder::decoderForHtml()도 참조하세요 .
[static noexcept] std::optional<QStringConverter::Encoding> QStringConverter::encodingForName(QAnyStringView name)
name 을 해당 Encoding 멤버가 있는 경우 해당 멤버로 변환합니다.
name 가 인코딩 열거에 나열된 코덱의 이름이 아닌 경우 std::nullopt 이 반환됩니다. ICU가 주어진 이름을 가진 변환기를 제공한다면, ICU로 Qt를 빌드할 때 QStringConverter 생성자가 그러한 이름을 받아들일 수 있습니다.
참고: 6.8 이전 Qt 버전에서는 이 함수가 UTF-8로 인코딩된 것으로 예상되는 const char * 만 받습니다.
[noexcept] bool QStringConverter::hasError() const
변환이 문자를 올바르게 변환할 수 없는 경우 true를 반환합니다. 예를 들어 잘못된 UTF-8 시퀀스 또는 대상 인코딩의 제한으로 인해 문자를 변환할 수 없을 때 트리거될 수 있습니다.
[noexcept] bool QStringConverter::isValid() const
텍스트를 인코딩 또는 디코딩하는 데 사용할 수 있는 유효한 문자열 변환기인 경우 true를 반환합니다.
기본으로 구성된 문자열 변환기나 지원되지 않는 이름으로 구성된 변환기는 유효하지 않습니다.
[noexcept] const char *QStringConverter::name() const
QStringConverter 이 인코딩 또는 디코딩할 수 있는 인코딩의 표준 이름을 반환합니다. 변환기가 유효하지 않으면 nullptr을 반환합니다. 반환된 이름은 UTF-8로 인코딩됩니다.
isValid()도 참조하세요 .
[static] const char *QStringConverter::nameForEncoding(QStringConverter::Encoding e)
인코딩을 위한 표준 이름을 반환합니다 e.
[noexcept] void QStringConverter::resetState()
변환기의 내부 상태를 초기화하여 잠재적인 오류 또는 부분 변환을 지웁니다.
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
