Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
Classes | Public Member Functions | Protected Member Functions | List of all members
QStringEncoder Class Reference

\inmodule QtCore More...

#include <qstringconverter.h>

+ Inheritance diagram for QStringEncoder:
+ Collaboration diagram for QStringEncoder:

Classes

struct  DecodedData
 

Public Member Functions

constexpr QStringEncoder () noexcept
 Default constructs an encoder.
 
constexpr QStringEncoder (Encoding encoding, Flags flags=Flag::Default)
 Creates an encoder object using encoding and flags.
 
 QStringEncoder (QAnyStringView name, Flags flags=Flag::Default)
 Creates an encoder object using name and flags.
 
Q_WEAK_OVERLOAD DecodedData< const QString & > operator() (const QString &str)
 
DecodedData< QStringView > operator() (QStringView in)
 Converts in and returns a struct that is implicitly convertible to QByteArray.
 
Q_WEAK_OVERLOAD DecodedData< const QString & > encode (const QString &str)
 
DecodedData< QStringView > encode (QStringView in)
 
qsizetype requiredSpace (qsizetype inputLength) const
 Returns the maximum amount of characters required to be able to process inputLength decoded data.
 
char * appendToBuffer (char *out, QStringView in)
 Encodes in and writes the encoded result into the buffer starting at out.
 
- 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.
 

Protected Member Functions

constexpr QStringEncoder (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
 
- 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
}
 
- 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.
 
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 Attributes inherited from QStringConverter
const Interface * iface
 
State state
 

Detailed Description

\inmodule QtCore

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

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()) {
QString chunk = get_new_data();
encoded += fromUtf16(chunk);
}

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, QStringDecoder

Definition at line 20 of file qstringconverter.h.

Constructor & Destructor Documentation

◆ QStringEncoder() [1/4]

QStringEncoder::QStringEncoder ( const Interface * i)
inlineexplicitconstexprprotectednoexcept

Definition at line 23 of file qstringconverter.h.

◆ QStringEncoder() [2/4]

QStringEncoder::QStringEncoder ( )
inlineconstexprnoexcept

Default constructs an encoder.

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

Definition at line 27 of file qstringconverter.h.

◆ QStringEncoder() [3/4]

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

Creates an encoder object using encoding and flags.

Definition at line 30 of file qstringconverter.h.

◆ QStringEncoder() [4/4]

QStringEncoder::QStringEncoder ( QAnyStringView name,
Flags flags = Flag::Default )
inlineexplicit

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

Definition at line 33 of file qstringconverter.h.

Member Function Documentation

◆ appendToBuffer()

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

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.
See also
requiredSpace()

Definition at line 57 of file qstringconverter.h.

◆ encode() [1/2]

Q_WEAK_OVERLOAD DecodedData< const QString & > QStringEncoder::encode ( const QString & str)
inline

Definition at line 50 of file qstringconverter.h.

◆ encode() [2/2]

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

Definition at line 52 of file qstringconverter.h.

◆ operator()() [1/2]

Q_WEAK_OVERLOAD DecodedData< const QString & > QStringEncoder::operator() ( const QString & str)
inline

Definition at line 45 of file qstringconverter.h.

◆ operator()() [2/2]

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

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

Definition at line 47 of file qstringconverter.h.

◆ requiredSpace()

qsizetype QStringEncoder::requiredSpace ( qsizetype inputLength) const
inline

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

See also
appendToBuffer()

Definition at line 55 of file qstringconverter.h.

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