QStringView Class
The QStringView class provides a unified view on UTF-16 strings with a read-only subset of the QString API. More...
Header: | #include <QStringView> |
qmake: | QT += core |
Since: | Qt 5.10 |
Note: All functions in this class are reentrant.
Public Types
typedef | const_iterator |
typedef | const_pointer |
typedef | const_reference |
typedef | const_reverse_iterator |
typedef | difference_type |
typedef | iterator |
typedef | pointer |
typedef | reference |
typedef | reverse_iterator |
typedef | size_type |
typedef | storage_type |
typedef | value_type |
Detailed Description
The QStringView class provides a unified view on UTF-16 strings with a read-only subset of the QString API.
A QStringView references a contiguous portion of a UTF-16 string it does not own. It acts as an interface type to all kinds of UTF-16 string, without the need to construct a QString first.
The UTF-16 string may be represented as an array (or an array-compatible data-structure such as QString, std::basic_string, etc.) of QChar, ushort
, char16_t
(on compilers that support C++11 Unicode strings) or (on platforms, such as Windows, where it is a 16-bit type) wchar_t
.
QStringView is designed as an interface type; its main use-case is as a function parameter type. When QStringViews 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 QStringView on all code paths, lest the string view ends up referencing deleted data.
When used as an interface type, QStringView allows a single function to accept a wide variety of UTF-16 string data sources. One function accepting QStringView thus replaces three function overloads (taking QString, QStringRef, and (const QChar*, int)
), while at the same time enabling even more string data sources to be passed to the function, such as u"Hello World"
, a char16_t
string literal.
QStringViews should be passed by value, not by reference-to-const:
void myfun1(QStringView sv); // preferred void myfun2(const QStringView &sv); // compiles and works, but slower
If you want to give your users maximum freedom in what strings they can pass to your function, accompany the QStringView overload with overloads for
- QChar: this overload can delegate to the QStringView version:
void fun(QChar ch) { fun(QStringView(&ch, 1)); }
even though, for technical reasons, QStringView cannot provide a QChar constructor by itself.
- QString: if you store an unmodified copy of the string and thus would like to take advantage of QString's implicit sharing.
- QLatin1String: if you can implement the function without converting the QLatin1String to UTF-16 first; users expect a function overloaded on QLatin1String to perform strictly less memory allocations than the semantically equivalent call of the QStringView version, involving construction of a QString from the QLatin1String.
QStringView can also be used as the return value of a function. If you call a function returning QStringView, take extra care to not keep the QStringView 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 QStringView into a QString.
QStringView is a Literal Type, but since it stores data as char16_t
, iteration is not constexpr
(casts from const char16_t*
to const QChar*
, which is not allowed in constexpr
functions). You can use an indexed loop and/or utf16() in constexpr
contexts instead.
Note: We strongly discourage the use of QList<QStringView>, because QList is a very inefficient container for QStringViews (it would heap-allocate every element). Use QVector (or std::vector) to hold QStringViews instead.
See also QString and QStringRef.
Member Type Documentation
typedef QStringView::const_iterator
This typedef provides an STL-style const iterator for QStringView.
See also iterator and const_reverse_iterator.
typedef QStringView::const_pointer
Alias for value_type *
. Provided for compatibility with the STL.
typedef QStringView::const_reference
Alias for value_type &
. Provided for compatibility with the STL.
typedef QStringView::const_reverse_iterator
This typedef provides an STL-style const reverse iterator for QStringView.
See also reverse_iterator and const_iterator.
typedef QStringView::difference_type
Alias for std::ptrdiff_t
. Provided for compatibility with the STL.
typedef QStringView::iterator
This typedef provides an STL-style const iterator for QStringView.
QStringView does not support mutable iterators, so this is the same as const_iterator.
See also const_iterator and reverse_iterator.
typedef QStringView::pointer
Alias for value_type *
. Provided for compatibility with the STL.
QStringView does not support mutable pointers, so this is the same as const_pointer.
typedef QStringView::reference
Alias for value_type &
. Provided for compatibility with the STL.
QStringView does not support mutable references, so this is the same as const_reference.
typedef QStringView::reverse_iterator
This typedef provides an STL-style const reverse iterator for QStringView.
QStringView does not support mutable reverse iterators, so this is the same as const_reverse_iterator.
See also const_reverse_iterator and iterator.
typedef QStringView::size_type
Alias for qsizetype. Provided for compatibility with the STL.
Unlike other Qt classes, QStringView uses qsizetype as its size_type
, to allow accepting data from std::basic_string
without truncation. The Qt API functions, for example length(), return int
, while the STL-compatible functions, for example size(), return size_type
.
typedef QStringView::storage_type
Alias for char16_t
for non-Windows or if Q_COMPILER_UNICODE_STRINGS is defined. Otherwise, alias for wchar_t
.
typedef QStringView::value_type
Alias for const QChar
. Provided for compatibility with the STL.