Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
QStringConverter Class Reference

\inmodule QtCore More...

#include <qstringconverter_base.h>

+ Inheritance diagram for QStringConverter:
+ Collaboration diagram for QStringConverter:

Classes

struct  Interface
 

Public Types

enum  Encoding {
  Utf8 , Utf16 , Utf16LE , Utf16BE ,
  Utf32 , Utf32LE , Utf32BE , Latin1 ,
  System , LastEncoding = System
}
 \value Utf8 Create a converter to or from UTF-8 \value Utf16 Create a converter to or from UTF-16. More...
 
- Public Types inherited from QStringConverterBase
enum class  Flag {
  Default = 0 , Stateless = 0x1 , ConvertInvalidToNull = 0x2 , WriteBom = 0x4 ,
  ConvertInitialBom = 0x8 , UsesIcu = 0x10
}
 

Public Member Functions

 QStringConverter (QStringConverter &&)=default
 
QStringConverter & operator= (QStringConverter &&)=default
 
bool isValid () const noexcept
 Returns true if this is a valid string converter that can be used for encoding or decoding text.
 
void resetState () noexcept
 Resets the internal state of the converter, clearing potential errors or partial conversions.
 
bool hasError () const noexcept
 Returns true if a conversion could not correctly convert a character.
 
Q_CORE_EXPORT const char * name () const noexcept
 Returns the canonical name of the encoding this QStringConverter can encode or decode.
 

Static Public Member Functions

static Q_CORE_EXPORT std::optional< Encoding > encodingForName (QAnyStringView name) noexcept
 Convert name to the corresponding \l Encoding member, if there is one.
 
static Q_CORE_EXPORT const char * nameForEncoding (Encoding e)
 Returns the canonical name for encoding e.
 
static Q_CORE_EXPORT std::optional< Encoding > encodingForData (QByteArrayView data, char16_t expectedFirstCharacter=0) noexcept
 Returns the encoding for the content of data if it can be determined.
 
static Q_CORE_EXPORT std::optional< Encoding > encodingForHtml (QByteArrayView data)
 Tries to determine the encoding of the HTML in data by looking at leading byte order marks or a charset specifier in the HTML meta tag.
 
static Q_CORE_EXPORT QStringList availableCodecs ()
 Returns a list of names of supported codecs.
 

Protected Member Functions

constexpr QStringConverter () noexcept
 
constexpr QStringConverter (Encoding encoding, Flags f)
 
constexpr QStringConverter (const Interface *i) noexcept
 
Q_CORE_EXPORT QStringConverter (QAnyStringView name, Flags f)
 
 ~QStringConverter ()=default
 
- Protected Member Functions inherited from QStringConverterBase
 ~QStringConverterBase ()=default
 

Protected Attributes

const Interface * iface
 
State state
 

Detailed Description

\inmodule QtCore

The QStringConverter class provides a base class for encoding and decoding text. \reentrant

Qt uses UTF-16 to store, draw and manipulate strings. In many situations you may wish to deal with data that uses a different encoding. Most text data transferred over files and network connections is encoded in UTF-8.

The QStringConverter class is a base class for the \l {QStringEncoder} and \l {QStringDecoder} classes that help with converting between different text encodings. QStringDecoder can decode a string from an encoded representation into UTF-16, the format Qt uses internally. QStringEncoder does the opposite operation, encoding UTF-16 encoded data (usually in the form of a QString) to the requested encoding.

The following encodings are always supported:

\list

  • UTF-8
  • UTF-16
  • UTF-16BE
  • UTF-16LE
  • UTF-32
  • UTF-32BE
  • UTF-32LE
  • ISO-8859-1 (Latin-1)
  • The system encoding \endlist

QStringConverter may support more encodings depending on how Qt was compiled. If more codecs are supported, they can be listed using availableCodecs().

\l {QStringConverter}s can be used as follows to convert some encoded string to and from UTF-16.

Suppose you have some string encoded in UTF-8, and want to convert it to a QString. The simple way to do it is to use a \l {QStringDecoder} like this:

QByteArray encodedString = "...";
auto toUtf16 = QStringDecoder(QStringDecoder::Utf8);
QString string = toUtf16(encodedString);

After this, string holds the text in decoded form. Converting a string from Unicode to the local encoding is just as easy using the \l {QStringEncoder} class:

QString string = "...";
auto fromUtf16 = QStringEncoder(QStringEncoder::Utf8);
QByteArray encodedString = fromUtf16(string);

To read or write text files in various encodings, use QTextStream and its \l{QTextStream::setEncoding()}{setEncoding()} function.

Some care must be taken when trying to convert the data in chunks, for example, when receiving it over a network. In such cases it is possible that a multi-byte character will be split over two chunks. At best this might result in the loss of a character and at worst cause the entire conversion to fail.

Both QStringEncoder and QStringDecoder make this easy, by tracking this in an internal state. So simply calling the encoder or decoder again with the next chunk of data will automatically continue encoding or decoding the data correctly:

auto toUtf16 = QStringDecoder(QStringDecoder::Utf8);
QString string;
while (new_data_available()) {
QByteArray chunk = get_new_data();
string += toUtf16(chunk);
}

The QStringDecoder object maintains state between chunks and therefore works correctly even if a multi-byte character is split between chunks.

QStringConverter objects can't be copied because of their internal state, but can be moved.

See also
QTextStream, QStringDecoder, QStringEncoder

Definition at line 87 of file qstringconverter_base.h.

Member Enumeration Documentation

◆ Encoding

enum QStringConverter::Encoding

\value Utf8 Create a converter to or from UTF-8 \value Utf16 Create a converter to or from UTF-16.

When decoding, the byte order will get automatically detected by a leading byte order mark. If none exists or when encoding, the system byte order will be assumed. \value Utf16BE Create a converter to or from big-endian UTF-16. \value Utf16LE Create a converter to or from little-endian UTF-16. \value Utf32 Create a converter to or from UTF-32. When decoding, the byte order will get automatically detected by a leading byte order mark. If none exists or when encoding, the system byte order will be assumed. \value Utf32BE Create a converter to or from big-endian UTF-32. \value Utf32LE Create a converter to or from little-endian UTF-32. \value Latin1 Create a converter to or from ISO-8859-1 (Latin1). \value System Create a converter to or from the underlying encoding of the operating systems locale. This is always assumed to be UTF-8 for Unix based systems. On Windows, this converts to and from the locale code page. \omitvalue LastEncoding

Enumerator
Utf8 
Utf16 
Utf16LE 
Utf16BE 
Utf32 
Utf32LE 
Utf32BE 
Latin1 
System 
LastEncoding 

Definition at line 91 of file qstringconverter_base.h.

Constructor & Destructor Documentation

◆ QStringConverter() [1/5]

QStringConverter::QStringConverter ( )
inlineconstexprprotectednoexcept

Definition at line 132 of file qstringconverter_base.h.

References iface.

◆ QStringConverter() [2/5]

QStringConverter::QStringConverter ( Encoding encoding,
Flags f )
inlineexplicitconstexprprotected

Definition at line 135 of file qstringconverter_base.h.

References QStringConverter().

Referenced by QStringConverter().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ QStringConverter() [3/5]

QStringConverter::QStringConverter ( const Interface * i)
inlineexplicitconstexprprotectednoexcept

Definition at line 138 of file qstringconverter_base.h.

References iface.

◆ QStringConverter() [4/5]

QStringConverter::QStringConverter ( QAnyStringView name,
Flags f )
explicitprotected

Definition at line 2416 of file qstringconverter.cpp.

◆ ~QStringConverter()

QStringConverter::~QStringConverter ( )
protecteddefault

◆ QStringConverter() [5/5]

QStringConverter::QStringConverter ( QStringConverter && )
default

Member Function Documentation

◆ availableCodecs()

QStringList QStringConverter::availableCodecs ( )
static

Returns a list of names of supported codecs.

The names returned by this function can be passed to QStringEncoder's and QStringDecoder's constructor to create a en- or decoder for the given codec.

This function may be used to obtain a listing of additional codecs beyond the standard ones. Support for additional codecs requires Qt be compiled with support for the ICU library.

Note
The order of codecs is an internal implementation detail and not guaranteed to be stable.

Definition at line 2637 of file qstringconverter.cpp.

◆ encodingForData()

std::optional< QStringConverter::Encoding > QStringConverter::encodingForData ( QByteArrayView data,
char16_t expectedFirstCharacter = 0 )
staticnoexcept

Returns the encoding for the content of data if it can be determined.

expectedFirstCharacter can be passed as an additional hint to help determine the encoding.

The returned optional is empty, if the encoding is unclear.

Definition at line 2512 of file qstringconverter.cpp.

◆ encodingForHtml()

std::optional< QStringConverter::Encoding > QStringConverter::encodingForHtml ( QByteArrayView data)
static

Tries to determine the encoding of the HTML in data by looking at leading byte order marks or a charset specifier in the HTML meta tag.

If the optional is empty, the encoding specified is not supported by QStringConverter. If no encoding is detected, the method returns Utf8.

See also
QStringDecoder::decoderForHtml()

Definition at line 2597 of file qstringconverter.cpp.

◆ encodingForName()

std::optional< QStringConverter::Encoding > QStringConverter::encodingForName ( QAnyStringView name)
staticnoexcept

Convert name to the corresponding \l Encoding member, if there is one.

If the name is not the name of a codec listed in the Encoding enumeration, {std::nullopt} is returned. Such a name may, none the less, be accepted by the QStringConverter constructor when Qt is built with ICU, if ICU provides a converter with the given name.

Note
In Qt versions prior to 6.8, this function took only a {const char *}, which was expected to be UTF-8-encoded.

Definition at line 2490 of file qstringconverter.cpp.

◆ hasError()

bool QStringConverter::hasError ( ) const
inlinenoexcept

Returns true if a conversion could not correctly convert a character.

This could for example get triggered by an invalid UTF-8 sequence or when a character can't get converted due to limitations in the target encoding.

Definition at line 159 of file qstringconverter_base.h.

◆ isValid()

bool QStringConverter::isValid ( ) const
inlinenoexcept

Returns true if this is a valid string converter that can be used for encoding or decoding text.

Default constructed string converters or converters constructed with an unsupported name are not valid.

Definition at line 153 of file qstringconverter_base.h.

References iface.

◆ name()

const char * QStringConverter::name ( ) const
noexcept

Returns the canonical name of the encoding this QStringConverter can encode or decode.

Returns a nullptr if the converter is not valid. The returned name is UTF-8 encoded.

See also
isValid()

Definition at line 2429 of file qstringconverter.cpp.

Referenced by testing.tools.encode_pdf_filter._PdfStream::RegisterByName().

+ Here is the caller graph for this function:

◆ nameForEncoding()

const char * QStringConverter::nameForEncoding ( QStringConverter::Encoding e)
static

Returns the canonical name for encoding e.

Definition at line 2697 of file qstringconverter.cpp.

◆ operator=()

QStringConverter & QStringConverter::operator= ( QStringConverter && )
default

◆ resetState()

void QStringConverter::resetState ( )
inlinenoexcept

Resets the internal state of the converter, clearing potential errors or partial conversions.

Definition at line 155 of file qstringconverter_base.h.

Member Data Documentation

◆ iface

const Interface* QStringConverter::iface
protected

Definition at line 175 of file qstringconverter_base.h.

Referenced by QStringConverter(), QStringConverter(), and isValid().

◆ state

State QStringConverter::state
protected

Definition at line 176 of file qstringconverter_base.h.

The documentation for this class was generated from the following files: