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.