Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
Loading...
Searching...
No Matches
Classes | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
QStringDecoder Class Reference

\inmodule QtCore More...

#include <qstringconverter.h>

+ Inheritance diagram for QStringDecoder:
+ Collaboration diagram for QStringDecoder:

Classes

struct  EncodedData
 

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 (const char *name, Flags f=Flag::Default)
 Creates an decoder object using name and flags.
 
Q_WEAK_OVERLOAD QStringDecoder (const QString &name, Flags f=Flag::Default)
 
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)
 
- 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 (const char *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 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 (const char *name, Flags f)
 
 ~QStringConverter ()=default
 
- Protected Member Functions inherited from QStringConverterBase
 ~QStringConverterBase ()=default
 

Additional Inherited Members

- Public Types inherited from QStringConverter
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
}
 
- 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()) {
QByteArray chunk = get_new_data();
string += toUtf16(chunk);
}

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

Constructor & Destructor Documentation

◆ QStringDecoder() [1/5]

constexpr QStringDecoder::QStringDecoder ( const Interface * i)
inlineexplicitconstexprprotectednoexcept

Definition at line 88 of file qstringconverter.h.

◆ QStringDecoder() [2/5]

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

Creates an decoder object using encoding and flags.

Definition at line 92 of file qstringconverter.h.

◆ QStringDecoder() [3/5]

constexpr QStringDecoder::QStringDecoder ( )
inlineconstexprnoexcept

Default constructs an decoder.

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

Definition at line 95 of file qstringconverter.h.

Referenced by decoderForHtml().

+ Here is the caller graph for this function:

◆ QStringDecoder() [4/5]

constexpr QStringDecoder::QStringDecoder ( const char * 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.

See also
isValid()

Definition at line 98 of file qstringconverter.h.

◆ QStringDecoder() [5/5]

constexpr QStringDecoder::QStringDecoder ( const QString & name,
Flags flags = Flag::Default )
inlineexplicit
Since
6.8

Creates an decoder object using name and flags. If name is not the name of a known encoding an invalid converter will get created.

See also
isValid()

Definition at line 101 of file qstringconverter.h.

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

References appendToBuffer(), ba, and out.

+ Here is the call graph for this function:

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

See also
requiredSpace

Definition at line 125 of file qstringconverter.h.

References ba, QStringConverter::iface, QStringConverterBase::State::invalidChars, out, QStringConverter::state, and QStringConverter::Interface::toUtf16.

Referenced by QFileSystemIterator::advance(), and appendToBuffer().

+ Here is the caller graph for this function:

◆ decode() [1/2]

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

Definition at line 118 of file qstringconverter.h.

References ba.

Referenced by QClipboard::text().

+ Here is the caller graph for this function:

◆ decode() [2/2]

QStringDecoder::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 120 of file qstringconverter.h.

References ba.

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

References QStringDecoder(), QStringConverter::encodingForData(), parseHtmlMetaForEncoding(), and QStringConverter::Utf8.

Referenced by QMimeDataPrivate::retrieveTypedData(), and QTextBrowserPrivate::setSource().

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

◆ operator()() [1/2]

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

Definition at line 113 of file qstringconverter.h.

References ba.

◆ operator()() [2/2]

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

Definition at line 115 of file qstringconverter.h.

References ba.

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

References QStringConverter::iface, and QStringConverter::Interface::toUtf16Len.

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