QStringEncoder Class | Qt Core | Qt 6.11.0
Description: The QStringEncoder class provides a state-based encoder for text.

- Qt 6.11
- Qt Core
- C++ Classes
- QStringEncoder
- Qt 6.11.0 Reference Documentation

# QStringEncoder Class

The QStringEncoder class provides a state-based encoder for text. More...

Header: | `#include <QStringEncoder>`
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
- QStringEncoder is part of Classes for string data.

Note: All functions in this class are reentrant.

## Public Types

| FinalizeResult

## Public Functions

| QStringEncoder()
| QStringEncoder(QAnyStringView name, QStringConverter::Flags flags = Flag::Default)
| QStringEncoder(QStringConverter::Encoding encoding, QStringConverter::Flags flags = Flag::Default)
char * | appendToBuffer(char *out, QStringView in)
QStringEncoder::DecodedData<QStringView> | encode(QStringView in)
QStringEncoder::DecodedData<const QString &> | encode(const QString &in)
`(since 6.11)` QStringEncoder::FinalizeResult | finalize()
`(since 6.11)` QStringEncoder::FinalizeResult | finalize(char *out, qsizetype maxlen)
qsizetype | requiredSpace(qsizetype inputLength) const
QStringEncoder::DecodedData<QStringView> | operator()(QStringView in)
QStringEncoder::DecodedData<const QString &> | operator()(const QString &in)

## Detailed Description

A text encoder converts text from Qt's internal representation into an encoded text format using a specific encoding.

Converting a string from Unicode to the local encoding can be achieved using the following code:

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

The encoder 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 encoder whenever new data is available:

     auto fromUtf16 = QStringEncoder(QStringEncoder::Utf8);

     QByteArray encoded;
     while (new_data_available() && !fromUtf16.hasError()) {
         QString chunk = get_new_data();
         encoded += fromUtf16(chunk);
     }
     auto result = fromUtf16.finalize();
     if (result.error != QStringEncoder::FinalizeResult::Error::NoError) {
         // Handle error
     }

The QStringEncoder object maintains state between chunks and therefore works correctly even if a UTF-16 surrogate character is split between chunks.

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

See also QStringConverter and QStringDecoder.

## Member Type Documentation

### `[alias]` QStringEncoder::FinalizeResult

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

## Member Function Documentation

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

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

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

Creates an encoder 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]` QStringEncoder::QStringEncoder(QStringConverter::Encoding encoding, QStringConverter::Flags flags = Flag::Default)

Creates an encoder object using encoding and flags.

### char *QStringEncoder::appendToBuffer(char *out, QStringView in)

Encodes in and writes the encoded result into the buffer starting at out. Returns a pointer to the end of the data written.

Note: out must be large enough to be able to hold all the decoded data. Use requiredSpace() to determine the maximum size requirement to be able to encode in. This function may write to any bytes between out and `out + requiredSpace()`, including those past the returned end pointer.

See also requiredSpace().

### QStringEncoder::DecodedData<const QString &> QStringEncoder::encode(const QString &in)

### QStringEncoder::DecodedData<QStringView> QStringEncoder::encode(QStringView in)

### QStringEncoder::DecodedData<const QString &> QStringEncoder::operator()(const QString &in)

### QStringEncoder::DecodedData<QStringView> QStringEncoder::operator()(QStringView in)

Converts in and returns a struct that is implicitly convertible to QByteArray.

     QString string = "...";
     auto fromUtf16 = QStringEncoder(QStringEncoder::Utf8);
     auto data = fromUtf16(string); // data's type is QStringEncoder::DecodedData<const QString &>
     QByteArray encodedString = fromUtf16(string); // Implicit conversion to QByteArray

     // Here you have to cast "data" to QByteArray
     auto func = [&]() { return !fromUtf16.hasError() ? QByteArray(data) : "foo"_ba; };

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

### `[since 6.11]` QStringEncoder::FinalizeResult QStringEncoder::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. When using a stateful encoding, such as ISO-2022-JP, this may also write bytes to restore, or end, the current state in the character stream.

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 QStringEncoder::requiredSpace(qsizetype inputLength) const

Returns the maximum amount of characters required to be able to process inputLength decoded data.

See also appendToBuffer().