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

#include <qstringconverter.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 }

Public Types inherited from QStringConverterBase
enum class	Flag { Default = 0 , Stateless = 0x1 , ConvertInvalidToNull = 0x2 , WriteBom = 0x4 , ConvertInitialBom = 0x8 }

Public Member Functions
bool	isValid () const

void	resetState ()

bool	hasError () const

const char *	name () const

Static Public Member Functions
static Q_CORE_EXPORT std::optional< Encoding >	encodingForName (const char *name)

static Q_CORE_EXPORT const char *	nameForEncoding (Encoding e)

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

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

Protected Member Functions
QSTRINGCONVERTER_CONSTEXPR	QStringConverter ()

QSTRINGCONVERTER_CONSTEXPR	QStringConverter (Encoding encoding, Flags f)

QSTRINGCONVERTER_CONSTEXPR	QStringConverter (const Interface *i)

Q_CORE_EXPORT	QStringConverter (const char *name, Flags f)

Protected Attributes
const Interface *	iface

State	state

Detailed Description

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

\inmodule QtCore

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 supported encodings are:

\list

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

\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:

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:

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:

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 115 of file qstringconverter.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 119 of file qstringconverter.h.

Constructor & Destructor Documentation

◆ QStringConverter() [1/4]

constexpr QStringConverter::QStringConverter ( )

inlineprotected

Definition at line 157 of file qstringconverter.h.

◆ QStringConverter() [2/4]

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

inlineprotected

Definition at line 160 of file qstringconverter.h.

◆ QStringConverter() [3/4]

QSTRINGCONVERTER_CONSTEXPR QStringConverter::QStringConverter ( const Interface * i )

inlineprotected

Definition at line 163 of file qstringconverter.h.

◆ QStringConverter() [4/4]

QStringConverter::QStringConverter	(	const char *	name,
		Flags	f
	)

protected

Definition at line 1697 of file qstringconverter.cpp.

Here is the call graph for this function:

Member Function Documentation

◆ encodingForData()

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

static

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 1761 of file qstringconverter.cpp.

Here is the call graph for this function:

◆ 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.

Definition at line 1808 of file qstringconverter.cpp.

◆ encodingForName()

std::optional< QStringConverter::Encoding > QStringConverter::encodingForName ( const char * name )

static

Returns an optional encoding for name. The optional is empty if the name could not get converted to a valid encoding.

Definition at line 1743 of file qstringconverter.cpp.

Here is the caller graph for this function:

◆ hasError()

bool QStringConverter::hasError ( ) const

inline

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 176 of file qstringconverter.h.

Here is the caller graph for this function:

◆ isValid()

bool QStringConverter::isValid ( ) const

inline

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 170 of file qstringconverter.h.

Here is the caller graph for this function:

◆ name()

const char * QStringConverter::name ( ) const

inline

Returns the canonical name of the encoding this QStringConverter can encode or decode. Returns a nullptr if the converter is not valid.

See also: isValid()

Definition at line 178 of file qstringconverter.h.

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 1853 of file qstringconverter.cpp.

◆ resetState()

void QStringConverter::resetState ( )

inline

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

Definition at line 172 of file qstringconverter.h.

Here is the caller graph for this function:

Member Data Documentation

◆ iface

const Interface* QStringConverter::iface

protected

Definition at line 187 of file qstringconverter.h.

◆ state

State QStringConverter::state

protected

Definition at line 188 of file qstringconverter.h.

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

src/corelib/text/qstringconverter.h
src/corelib/text/qstringconverter.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ Encoding

Constructor & Destructor Documentation

◆ QStringConverter() [1/4]

◆ QStringConverter() [2/4]

◆ QStringConverter() [3/4]

◆ QStringConverter() [4/4]

Member Function Documentation

◆ encodingForData()

◆ encodingForHtml()

◆ encodingForName()

◆ hasError()

◆ isValid()

◆ name()

◆ nameForEncoding()

◆ resetState()

Member Data Documentation

◆ iface

◆ state