QStringDecoder Class | Qt Core | Qt 6.11.1
Description: The QStringDecoder class provides a state-based decoder for text.

- Qt 6.11
- Qt Core
- C++ Classes
- QStringDecoder
- Qt 6.11.1 Reference Documentation

# QStringDecoder Class

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

Header: | `#include <QStringDecoder>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS Core)` `target_link_libraries(mytarget PRIVATE Qt6::Core)`
qmake: | `QT += core`
Inherits: | QStringConverter

- List of all members, including inherited members
- QStringDecoder is part of Classes for string data.

Note: All functions in this class are reentrant.

## Public Types

| FinalizeResult
| FinalizeResultQChar

## Public Functions

| QStringDecoder()
| QStringDecoder(QAnyStringView name, QStringConverter::Flags flags = Flag::Default)
| QStringDecoder(QStringConverter::Encoding encoding, QStringConverter::Flags flags = Flag::Default)
QChar * | appendToBuffer(QChar *out, QByteArrayView in)
`(since 6.6)` char16_t * | appendToBuffer(char16_t *out, QByteArrayView in)
QStringDecoder::EncodedData<QByteArrayView> | decode(QByteArrayView ba)
QStringDecoder::EncodedData<const QByteArray &> | decode(const QByteArray &ba)
`(since 6.11)` QStringDecoder::FinalizeResult | finalize()
`(since 6.11)` QStringDecoder::FinalizeResultQChar | finalize(QChar *out, qsizetype maxlen)
`(since 6.11)` QStringDecoder::FinalizeResult | finalize(char16_t *out, qsizetype maxlen)
qsizetype | requiredSpace(qsizetype inputLength) const
QStringDecoder::EncodedData<QByteArrayView> | operator()(QByteArrayView ba)
QStringDecoder::EncodedData<const QByteArray &> | operator()(const QByteArray &ba)

## Static Public Members

QStringDecoder | decoderForHtml(QByteArrayView data)

## Detailed Description

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::Error::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 and QStringEncoder.

## Member Type Documentation

### `[alias]` QStringDecoder::FinalizeResult

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

### `[alias]` QStringDecoder::FinalizeResultQChar

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

## Member Function Documentation

### `[constexpr noexcept]` QStringDecoder::QStringDecoder()

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

### `[explicit]` QStringDecoder::QStringDecoder(QAnyStringView name, QStringConverter::Flags flags = Flag::Default)

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().

### `[explicit constexpr]` QStringDecoder::QStringDecoder(QStringConverter::Encoding encoding, QStringConverter::Flags flags = Flag::Default)

Creates an decoder object using encoding and flags.

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

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

### `[since 6.6]` char16_t *QStringDecoder::appendToBuffer(char16_t *out, QByteArrayView in)

This is an overloaded function.

This function was introduced in Qt 6.6.

### `[static]` QStringDecoder 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. 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().

### `[since 6.11]` QStringDecoder::FinalizeResultQChar QStringDecoder::finalize(QChar *out, qsizetype maxlen)

### `[since 6.11]` QStringDecoder::FinalizeResult QStringDecoder::finalize(char16_t *out, qsizetype maxlen)

### `[since 6.11]` QStringDecoder::FinalizeResult QStringDecoder::finalize()

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 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().

These functions were introduced in Qt 6.11.

See also hasError() and appendToBuffer().

### qsizetype QStringDecoder::requiredSpace(qsizetype inputLength) const

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

See also appendToBuffer.

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

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

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

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

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; };