QAnyStringView Class
The QAnyStringView class provides a unified view on Latin-1, UTF-8, or UTF-16 strings with a read-only subset of the QString API. More...
Header: | #include <QAnyStringView> |
CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
qmake: | QT += core |
Since: | Qt 6.0 |
Note: All functions in this class are reentrant.
Public Types
Public Functions
QAnyStringView(const QString &str) | |
QAnyStringView(const QByteArray &str) | |
QAnyStringView(const Char *str) | |
QAnyStringView() | |
QChar | back() const |
const void * | data() const |
bool | empty() const |
QChar | front() const |
bool | isEmpty() const |
bool | isNull() const |
int | length() const |
int | size() const |
int | size_bytes() const |
QString | toString() const |
Static Public Members
int | compare(QAnyStringView lhs, QAnyStringView rhs, Qt::CaseSensitivity cs = Qt::CaseSensitive) |
Related Non-Members
bool | operator!=(QAnyStringView lhs, QAnyStringView rhs) |
bool | operator<(QAnyStringView lhs, QAnyStringView rhs) |
bool | operator<=(QAnyStringView lhs, QAnyStringView rhs) |
bool | operator==(QAnyStringView lhs, QAnyStringView rhs) |
bool | operator>(QAnyStringView lhs, QAnyStringView rhs) |
bool | operator>=(QAnyStringView lhs, QAnyStringView rhs) |
Detailed Description
A QAnyStringView references a contiguous portion of a string it does not own. It acts as an interface type to all kinds of strings, without the need to construct a QString first.
Unlike QStringView and QUtf8StringView, QAnyStringView can hold strings of any of the following encodings: UTF-8, UTF-16, and Latin-1. The latter is supported because Latin-1, unlike UTF-8, can be efficiently compared to UTF-16 data: a length mismatch already means the strings cannot be equal. This is not true for UTF-8/UTF-16 comparisons, because UTF-8 is a variable-length encoding.
The string may be represented as an array (or an array-compatible data-structure such as QString, std::basic_string, etc.) of char
, char8_t
, QChar, ushort
, char16_t
or (on platforms, such as Windows, where it is a 16-bit type) wchar_t
.
QAnyStringView is designed as an interface type; its main use-case is as a function parameter type. When QAnyStringViews are used as automatic variables or data members, care must be taken to ensure that the referenced string data (for example, owned by a QString) outlives the QAnyStringView on all code paths, lest the string view ends up referencing deleted data.
When used as an interface type, QAnyStringView allows a single function to accept a wide variety of string data sources. One function accepting QAnyStringView thus replaces five function overloads (taking QString, (const QChar*, qsizetype)
, QUtf8StringView, QLatin1StringView (but see above), and QChar), while at the same time enabling even more string data sources to be passed to the function, such as u8"Hello World"
, a char8_t
string literal.
Like elsewhere in Qt, QAnyStringView assumes char
data is encoded in UTF-8, unless it is presented as a QLatin1StringView.
Since Qt 6.4, however, UTF-8 string literals that are pure US-ASCII are automatically stored as Latin-1. This is a compile-time check with no runtime overhead. The feature requires compiling in C++20, or with a recent GCC.
QAnyStringViews should be passed by value, not by reference-to-const:
void myfun1(QAnyStringView sv); // preferred void myfun2(const QAnyStringView &sv); // compiles and works, but slower
QAnyStringView can also be used as the return value of a function, but this is not recommended. QUtf8StringView or QStringView are better suited as function return values. If you call a function returning QAnyStringView, take extra care to not keep the QAnyStringView around longer than the function promises to keep the referenced string data alive. If in doubt, obtain a strong reference to the data by calling toString() to convert the QAnyStringView into a QString.
QAnyStringView is a Literal Type.
Compatible Character Types
QAnyStringView accepts strings over a variety of character types:
char
(both signed and unsigned)char8_t
(C++20 only)char16_t
wchar_t
(where it's a 16-bit type, e.g. Windows)ushort
QChar
The 8-bit character types are interpreted as UTF-8 data (except when presented as a QLatin1StringView) while the 16-bit character types are interpreted as UTF-16 data in host byte order (the same as QString).
Sizes and Sub-Strings
All sizes and positions in QAnyStringView functions are in the encoding's code units (that is, UTF-16 surrogate pairs count as two for the purposes of these functions, the same as in QString, and UTF-8 multibyte sequences count as two, three or four, depending on their length).
See also QUtf8StringView and QStringView.
Member Type Documentation
QAnyStringView::difference_type
Alias for std::ptrdiff_t
. Provided for compatibility with the STL.
QAnyStringView::size_type
Alias for qsizetype. Provided for compatibility with the STL.
Member Function Documentation
QAnyStringView::QAnyStringView(const QString &str)
Constructs a string view on str.
str.data()
must remain valid for the lifetime of this string view object.
The string view will be null if and only if str.isNull()
.
QAnyStringView::QAnyStringView(const QByteArray &str)
Constructs a string view on str. The data in str is interpreted as UTF-8.
str.data()
must remain valid for the lifetime of this string view object.
The string view will be null if and only if str.isNull()
.
template <typename Char> QAnyStringView::QAnyStringView(const Char *str)
Constructs a string view on str. The length is determined by scanning for the first Char(0)
.
str must remain valid for the lifetime of this string view object.
Passing nullptr
as str is safe and results in a null string view.
This constructor only participates in overload resolution if str is not an array and if Char
is a compatible character type.
See also isNull() and Compatible Character Types.
QAnyStringView::QAnyStringView()
Constructs a null string view.
See also isNull().
QChar QAnyStringView::back() const
Returns the last character in the string view.
This function is provided for STL compatibility.
Warning: Calling this function on an empty string view constitutes undefined behavior.
See also front() and Sizes and Sub-Strings.
[static]
int QAnyStringView::compare(QAnyStringView lhs, QAnyStringView rhs, Qt::CaseSensitivity cs = Qt::CaseSensitive)
Returns an integer that compares to zero as lhs compares to rhs.
If cs is Qt::CaseSensitive (the default), the comparison is case sensitive; otherwise the comparison is case-insensitive.
See also operator==(), operator<(), and operator>().
const void *QAnyStringView::data() const
Returns a const pointer to the first character in the string view.
Note: The character array represented by the return value is not null-terminated.
See also size_bytes().
bool QAnyStringView::empty() const
Returns whether this string view is empty - that is, whether size() == 0
.
This function is provided for STL compatibility.
See also isEmpty(), isNull(), and size().
QChar QAnyStringView::front() const
Returns the first character in the string view.
This function is provided for STL compatibility.
Warning: Calling this function on an empty string view constitutes undefined behavior.
See also back() and Sizes and Sub-Strings.
bool QAnyStringView::isEmpty() const
Returns whether this string view is empty - that is, whether size() == 0
.
This function is provided for compatibility with other Qt containers.
See also empty(), isNull(), and size().
bool QAnyStringView::isNull() const
Returns whether this string view is null - that is, whether data() == nullptr
.
This functions is provided for compatibility with other Qt containers.
See also empty(), isEmpty(), and size().
int QAnyStringView::length() const
Same as size().
This function is provided for compatibility with other Qt containers.
See also size().
int QAnyStringView::size() const
Returns the size of this string view, in the encoding's code points.
See also empty(), isEmpty(), isNull(), size_bytes(), and Sizes and Sub-Strings.
int QAnyStringView::size_bytes() const
Returns the size of this string view, but in bytes, not code-points.
You can use this function together with data() for hashing or serialization.
This function is provided for STL compatibility.
QString QAnyStringView::toString() const
Returns a deep copy of this string view's data as a QString.
The return value will be a null QString if and only if this string view is null.
Related Non-Members
bool operator!=(QAnyStringView lhs, QAnyStringView rhs)
bool operator<(QAnyStringView lhs, QAnyStringView rhs)
bool operator<=(QAnyStringView lhs, QAnyStringView rhs)
bool operator==(QAnyStringView lhs, QAnyStringView rhs)
bool operator>(QAnyStringView lhs, QAnyStringView rhs)
bool operator>=(QAnyStringView lhs, QAnyStringView rhs)
Operators that compare lhs to rhs.
See also compare().