\inmodule QtCore More...

#include <qstringconverter.h>

Inheritance diagram for QStringDecoder:

Collaboration diagram for QStringDecoder:

Classes
struct	EncodedData

Public Types
using	FinalizeResult = FinalizeResultChar<char16_t>
	\variable QStringConverter::FinalizeResultChar::error Relays errors discovered during finalization.
using	FinalizeResultQChar = FinalizeResultChar<QChar>
	This is an alias for QStringConverter::FinalizeResultChar<QChar>.
Public Types inherited from QStringConverter
enum class	Flag { Default = 0 , Stateless = 0x1 , ConvertInvalidToNull = 0x2 , WriteBom = 0x4 , ConvertInitialBom = 0x8 , UsesIcu = 0x10 }
	\value Default Default conversion rules apply. More...
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 Member Functions
constexpr	QStringDecoder (Encoding encoding, Flags flags=Flag::Default)
	Creates an decoder object using encoding and flags.
constexpr	QStringDecoder () noexcept
	Default constructs an decoder.
	QStringDecoder (QAnyStringView name, Flags f=Flag::Default)
	Creates an decoder object using name and flags.
Q_WEAK_OVERLOAD EncodedData< const QByteArray & >	operator() (const QByteArray &ba)
EncodedData< QByteArrayView >	operator() (QByteArrayView ba)
Q_WEAK_OVERLOAD EncodedData< const QByteArray & >	decode (const QByteArray &ba)
EncodedData< QByteArrayView >	decode (QByteArrayView ba)
	Converts ba and returns a struct that is implicitly convertible to QString.
qsizetype	requiredSpace (qsizetype inputLength) const
	Returns the maximum amount of UTF-16 code units required to be able to process inputLength encoded data.
QChar *	appendToBuffer (QChar *out, QByteArrayView ba)
	Decodes the sequence of bytes viewed by in and writes the decoded result into the buffer starting at out.
char16_t *	appendToBuffer (char16_t *out, QByteArrayView ba)
FinalizeResultQChar	finalize (QChar *out, qsizetype maxlen)
Q_REQUIRED_RESULT Q_CORE_EXPORT FinalizeResult	finalize (char16_t *out, qsizetype maxlen)
Q_REQUIRED_RESULT FinalizeResult	finalize ()
	Signals to the decoder that no further data will arrive.
Public Member Functions inherited from QStringConverter
	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 QStringDecoder	decoderForHtml (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 and returns a QStringDecoder matching the encoding.
Static Public Member Functions inherited from QStringConverter
static Q_CORE_EXPORT std::optional< Encoding >	encodingForName (QAnyStringView name) noexcept
	Convert name to the corresponding \l Encoding member, if there is one.
Q_DECL_PURE_FUNCTION static Q_CORE_EXPORT const char *	nameForEncoding (Encoding e) noexcept
	Returns the canonical name for encoding e or \nullptr if e is an invalid value.
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	QStringDecoder (const Interface *i) noexcept
Protected Member Functions inherited from QStringConverter
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

Additional Inherited Members
Protected Attributes inherited from QStringConverter
const Interface *	iface
State	state

Detailed Description

\inmodule QtCore

The QStringDecoder class provides a state-based decoder for text. \reentrant

A text decoder converts text an encoded text format that uses a specific encoding into Qt's internal representation.

Converting encoded data into a QString can be achieved using the following code:

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

The decoder remembers any state that is required between calls, so converting data received in chunks, for example, when receiving it over a network, is just as easy, by calling the decoder whenever new data is available:

        auto toUtf16 = QStringDecoder(QStringDecoder::Utf8);
 
        QString string;
        while (new_data_available() && !toUtf16.hasError()) {
            QByteArray chunk = get_new_data();
            string += toUtf16(chunk);
        }
        auto result = toUtf16.finalize();
        if (result.error != QStringDecoder::FinalizeResult::NoError) {
            // Handle error
        }

The QStringDecoder object maintains state between chunks and therefore works correctly even if chunks are split in the middle of a multi-byte character sequence.

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

See also: QStringConverter, QStringEncoder

Definition at line 93 of file qstringconverter.h.

Member Typedef Documentation

◆ FinalizeResult

using QStringDecoder::FinalizeResult = FinalizeResultChar<char16_t>

\variable QStringConverter::FinalizeResultChar::error Relays errors discovered during finalization.

\variable QStringConverter::FinalizeResultChar::next Points to the character position {following} the last-written character.

\variable QStringConverter::FinalizeResultChar::invalidChars The number of invalid characters that were previously counted in the state as well as any that were encountered during the call to finalize().

This is an alias for QStringConverter::FinalizeResultChar<char16_t>.

Definition at line 142 of file qstringconverter.h.

◆ FinalizeResultQChar

using QStringDecoder::FinalizeResultQChar = FinalizeResultChar<QChar>

This is an alias for QStringConverter::FinalizeResultChar<QChar>.

Definition at line 143 of file qstringconverter.h.

Constructor & Destructor Documentation

◆ QStringDecoder() [1/4]

QStringDecoder::QStringDecoder ( const Interface * i )

inlineexplicitconstexprprotectednoexcept

Definition at line 96 of file qstringconverter.h.

References QStringDecoder().

Referenced by QStringDecoder().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ QStringDecoder() [2/4]

QStringDecoder::QStringDecoder	(	Encoding	encoding,
		Flags	flags = Flag::Default )

inlineexplicitconstexpr

Creates an decoder object using encoding and flags.

Definition at line 100 of file qstringconverter.h.

References QStringDecoder().

Referenced by QStringDecoder(), and QStringDecoder().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ QStringDecoder() [3/4]

QStringDecoder::QStringDecoder ( )

inlineconstexprnoexcept

Default constructs an decoder.

The default decoder is not valid, and can't be used for converting text.

Definition at line 103 of file qstringconverter.h.

References QStringDecoder().

Referenced by QStringDecoder().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ QStringDecoder() [4/4]

QStringDecoder::QStringDecoder	(	QAnyStringView	name,
		Flags	flags = Flag::Default )

inlineexplicit

Creates an decoder object using name and flags.

If name is not the name of a known encoding an invalid converter will get created.

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

See also: isValid()

Definition at line 106 of file qstringconverter.h.

References QStringDecoder().

Here is the call graph for this function:

Member Function Documentation

◆ appendToBuffer() [1/2]

char16_t * QStringDecoder::appendToBuffer	(	char16_t *	out,
		QByteArrayView	in )

inline

Since: 6.6 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 138 of file qstringconverter.h.

◆ appendToBuffer() [2/2]

QChar * QStringDecoder::appendToBuffer	(	QChar *	out,
		QByteArrayView	in )

inline

Decodes the sequence of bytes viewed by in and writes the decoded result into the buffer starting at out.

Returns a pointer to the end of data written.

out needs to be large enough to be able to hold all the decoded data. Use \l{requiredSpace} to determine the maximum size requirements to decode an encoded data buffer of in.size() bytes. This function may write to any bytes between out and {out + requiredSpace()}, including those past the returned end pointer.

See also: requiredSpace

Definition at line 130 of file qstringconverter.h.

◆ decode() [1/2]

Q_WEAK_OVERLOAD EncodedData< const QByteArray & > QStringDecoder::decode ( const QByteArray & ba )

inline

Definition at line 123 of file qstringconverter.h.

◆ decode() [2/2]

EncodedData< QByteArrayView > QStringDecoder::decode ( QByteArrayView ba )

inline

Converts ba and returns a struct that is implicitly convertible to QString.

        QByteArray encodedString = "...";
        auto toUtf16 = QStringDecoder(QStringDecoder::Utf8);
        auto data = toUtf16(encodedString); // data's type is QStringDecoder::EncodedData<const QByteArray &>
        QString string = toUtf16(encodedString); // Implicit conversion to QString
 
        // Here you have to cast "data" to QString
        auto func = [&]() { return !toUtf16.hasError() ? QString(data) : u"foo"_s; };

Definition at line 125 of file qstringconverter.h.

◆ decoderForHtml()

QStringDecoder QStringDecoder::decoderForHtml ( 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 and returns a QStringDecoder matching the encoding.

If the returned decoder is not valid, the encoding specified is not supported by QStringConverter. If no encoding is detected, the method returns a decoder for Utf8.

See also: isValid()

Definition at line 2891 of file qstringconverter.cpp.

◆ finalize() [1/3]

Q_REQUIRED_RESULT FinalizeResult QStringDecoder::finalize ( )

inline

Signals to the decoder that no further data will arrive.

May also provide data from residual content that was pending decoding. When there is no residual data to account for, the return's error field will be set to \l {QCharConverter::FinalizeResult::Error::} {NoError}.

If out is supplied and non-null, it must have space in which up to maxlen characters may be written. Up to this many characters of residual output are written to this space, with the end indicated by the return-value's next field. Typically this residual data shall consist of one replacement character per remaining unconverted input character.

If all residual content has been delivered via out, if out is \nullptr, or if there is no residual data, the decoder is reset on return from finalize(). Otherwise, the remaining data can be retrieved or discarded by a further call to finalize().

Since: 6.11

See also: hasError(), appendToBuffer()

Definition at line 152 of file qstringconverter.h.

◆ finalize() [2/3]

auto QStringDecoder::finalize	(	char16_t *	out,
		qsizetype	maxlen )

Definition at line 2760 of file qstringconverter.cpp.

◆ finalize() [3/3]

FinalizeResultQChar QStringDecoder::finalize	(	QChar *	out,
		qsizetype	maxlen )

inline

Definition at line 144 of file qstringconverter.h.

◆ operator()() [1/2]

Q_WEAK_OVERLOAD EncodedData< const QByteArray & > QStringDecoder::operator() ( const QByteArray & ba )

inline

Definition at line 118 of file qstringconverter.h.

◆ operator()() [2/2]

EncodedData< QByteArrayView > QStringDecoder::operator() ( QByteArrayView ba )

inline

Definition at line 120 of file qstringconverter.h.

◆ requiredSpace()

qsizetype QStringDecoder::requiredSpace ( qsizetype inputLength ) const

inline

Returns the maximum amount of UTF-16 code units required to be able to process inputLength encoded data.

See also: appendToBuffer

Definition at line 128 of file qstringconverter.h.

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

qtbase/src/corelib/text/qstringconverter.h (e2d19b9b8f4f7b87a0a4bfe5b6afd1395685ba20)
qtbase/src/corelib/text/qstringconverter.cpp (23ec36d1b23a866771ada3a6f2cd47217fecad2c)

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ FinalizeResult

◆ FinalizeResultQChar

Constructor & Destructor Documentation

◆ QStringDecoder() [1/4]

◆ QStringDecoder() [2/4]

◆ QStringDecoder() [3/4]

◆ QStringDecoder() [4/4]

Member Function Documentation

◆ appendToBuffer() [1/2]

◆ appendToBuffer() [2/2]

◆ decode() [1/2]

◆ decode() [2/2]

◆ decoderForHtml()

◆ finalize() [1/3]

◆ finalize() [2/3]

◆ finalize() [3/3]

◆ operator()() [1/2]

◆ operator()() [2/2]

◆ requiredSpace()