QAnyStringView Class | Qt Core 6.4.1

- Qt 6.4
- Qt Core
- C++ Classes
- QAnyStringView
- Qt 6.4.1 Reference Documentation

# 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

- List of all members, including inherited members

Note: All functions in this class are reentrant.

## Public Types

| difference_type
| size_type

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

See also size() and data().

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