Класс QUtf8StringView

Класс QUtf8StringView предоставляет единый вид на строки UTF-8 с подмножеством чтений-только методов API класса QString. Подробнее...

• Список всех членов, включая унаследованные
• Устаревшие члены

Примечание: Все функции в этом классе являются реентерабельными.

Открытые типы

Открытые функции

Статические публичные члены

Подробное описание

QUtf8StringView ссылается на непрерывный фрагмент строки UTF-8, не являясь её владельцем. Она выступает в качестве интерфейсного типа для всех видов строк UTF-8, без необходимости предварительного создания QString или QByteArray.

Строка UTF-8 может быть представлена в виде массива (или совместимой с массивом структуры данных, такой как std::basic_string и т.д.) char8_t, char, signed char или unsigned char.

QUtf8StringView разработана как интерфейсный тип; её основное применение — в качестве типа параметра функции. При использовании QUtf8StringView в качестве автоматических переменных или членов данных необходимо позаботиться о том, чтобы данные строки, на которую ссылается строковый вью (например, принадлежащие std::u8string), сохранялись дольше, чем QUtf8StringView, на всех путях кода, чтобы строковый вью не ссылался на удалённые данные.

При использовании в качестве интерфейсного типа QUtf8StringView позволяет одной функции принимать множество источников данных строк UTF-8. Таким образом, одна функция, принимающая QUtf8StringView, заменяет несколько перегруженных функций (принимающих, например, QByteArray), и одновременно позволяет передавать в функцию ещё больше источников данных строк, такие как u8"Hello World", char8_t (C++20) или char (C++17) строковый литерал. Несовместимость char8_t между C++17 и C++20 исчезает при использовании QUtf8StringView.

Как и все представления, QUtf8StringViews должны передаваться по значению, а не по ссылке-to-const:

    void myfun1(QUtf8StringView sv);        // preferred
    void myfun2(const QUtf8StringView &sv); // compiles and works, but slower

Если вы хотите предоставить своим пользователям максимальную свободу в том, какие строки они могут передавать вашей функции, рассмотрите использование QAnyStringView вместо этого.

QUtf8StringView также может использоваться в качестве значения возврата функции. Если вы вызываете функцию, возвращающую QUtf8StringView, обратите особое внимание, чтобы не хранить QUtf8StringView дольше, чем функция обещает сохранить данные ссылаемой строки живыми. В случае сомнений получите сильную ссылку на данные, вызвав toString(), чтобы преобразовать QUtf8StringView в QString.

QUtf8StringView — это литеральный тип.

Совместимые типы символов

QUtf8StringView принимает строки различных типов символов:

• char (как со знаком, так и без)
• char8_t (только C++20)

Размеры и подстроки

Все размеры и позиции в функциях QUtf8StringView указаны в кодовых точках UTF-8 (то есть многобайтовые последовательности UTF-8 учитываются как две, три или четыре в зависимости от их длины). QUtf8StringView не пытается обнаружить или предотвратить обрезку прямо через многобайтовые последовательности UTF-8. Это аналогично ситуации с QStringView и парами суррогатов.

C++20, char8_t и QUtf8StringView

В C++20 u8"" строковые литералы изменили свой тип с const char[] на const char8_t[]. Если бы Qt 6 мог полагаться на C++20, QUtf8StringView хранил бы char8_t напрямую, и следующие функции и псевдонимы использовали бы (указатели на) char8_t:

• storage_type, value_type и т. д.
• begin(), end(), data() и т. д.
• front(), back(), at(), operator[]()

Ожидается, что QUtf8StringView будет выглядеть так в Qt 7, но в Qt 6 это было невозможно. Вместо того, чтобы привязывать пользователей к интерфейсу эпохи C++17 на ближайшее десятилетие, Qt предоставляет два класса QUtf8StringView в разных (встроенных) именованных пространствах. Первый, в пространстве имён q_no_char8_t, имеет value_type типа const char и доступен универсально. Второй, в пространстве имён q_has_char8_t, имеет value_type типа const char8_t и доступен только при компиляции в режиме C++20.

q_no_char8_t является встроенным именным пространством независимо от версии C++, чтобы избежать случайных двоичных несовместимостей. Чтобы использовать версию char8_t, вам необходимо явно назвать её q_has_char8_t::QUtf8StringView.

Внутри оба являются экземплярами одного и того же шаблона класса QBasicUtf8StringView. Не используйте имя шаблона класса в своём исходном коде.

См. также QAnyStringView, QUtf8StringView и QString.

Документация по типам членов

QUtf8StringView::const_iterator

Этот typedef предоставляет итератор типа const STL для QUtf8StringView.

См. также iterator и const_reverse_iterator.

QUtf8StringView::const_pointer

Псевдоним для value_type *. Предоставлен для совместимости со STL.

QUtf8StringView::const_reference

Псевдоним для value_type &. Предоставлен для совместимости со STL.

QUtf8StringView::const_reverse_iterator

Этот typedef предоставляет обратный итератор типа const STL для QUtf8StringView.

См. также reverse_iterator и const_iterator.

QUtf8StringView::difference_type

Псевдоним для std::ptrdiff_t. Предоставлен для совместимости со STL.

QUtf8StringView::iterator

Этот typedef предоставляет итератор типа const STL для QUtf8StringView.

QUtf8StringView не поддерживает изменяемые итераторы, поэтому это то же самое, что и const_iterator.

См. также const_iterator и reverse_iterator.

QUtf8StringView::pointer

Псевдоним для value_type *. Предоставлен для совместимости со STL.

QUtf8StringView не поддерживает изменяемые указатели, поэтому это то же самое, что и const_pointer.

QUtf8StringView::reference

Псевдоним для value_type &. Предоставлен для совместимости со STL.

QUtf8StringView не поддерживает изменяемые ссылки, поэтому это то же самое, что и const_reference.

QUtf8StringView::reverse_iterator

Этот typedef предоставляет обратный итератор типа const STL для QUtf8StringView.

QUtf8StringView не поддерживает изменяемые обратные итераторы, поэтому это то же самое, что и const_reverse_iterator.

См. также const_reverse_iterator и iterator.

QUtf8StringView::size_type

Псевдоним для qsizetype. Предоставлен для совместимости со STL.

[alias] QUtf8StringView::storage_type

Псевдоним для char.

QUtf8StringView::value_type

Псевдоним для const char. Предоставлен для совместимости со STL.

Документация по функциям членов

template <typename Container, if_compatible_container<Container>> QUtf8StringView::QUtf8StringView(const Container &str)

Создаёт представление строки str. Длина берётся из str.size().

str.data() должно оставаться допустимым для всего срока существования этого объекта представления строки.

Этот конструктор участвует в разрешении перегрузки только в том случае, если Container является экземпляром std::basic_string с совместимым типом символов. Совместимые типы символов: char8_t, char, signed char и unsigned char.

Представление строки будет пустым только тогда, когда str.empty(). Неопределено, может ли этот конструктор привести к представлению пустой строки (str.data() должно возвращать nullptr для этого).

См. также isNull() и isEmpty().

template <typename Char> QUtf8StringView::QUtf8StringView(const Char *str)

Создаёт представление строки str. Длина определяется по первому Char(0).

str должно оставаться допустимым для всего срока существования этого объекта представления строки.

Передача nullptr в качестве str безопасна и приводит к представлению пустой строки.

Этот конструктор участвует в разрешении перегрузки только в том случае, если str не является массивом и если Char является совместимым типом символов. Совместимые типы символов: char8_t, char, signed char и unsigned char.

template <typename Char, size_t N> QUtf8StringView::QUtf8StringView(const Char (&)[N] string = N)

Создаёт представление строки символьного литерала string. Представление охватывает массив до первой Char(0) или N, что наступит раньше. Если вам нужно всё содержимое массива, используйте fromArray() вместо этого.

string должно оставаться допустимым для всего срока существования этого объекта представления строки.

Этот конструктор участвует в разрешении перегрузки только в том случае, если string является фактическим массивом и если Char является совместимым типом символов. Совместимые типы символов: char8_t, char, signed char и unsigned char.

См. также fromArray().

template <typename Char, if_compatible_char<Char>> QUtf8StringView::QUtf8StringView(const Char *first, const Char *last)

Создаёт представление строки first длиной (last - first).

Диапазон [first,last) должен оставаться допустимым для всего срока существования этого объекта представления строки.

Передача \nullptr в качестве first безопасна, если last также nullptr, и приводит к представлению пустой строки.

Поведение не определено, если last предшествует first или first является nullptr и last не является.

Этот конструктор участвует в разрешении перегрузки только в том случае, если Char является совместимым типом символов. Совместимые типы символов: char8_t, char, signed char и unsigned char.

template <typename Char, if_compatible_char<Char>> QUtf8StringView::QUtf8StringView(const Char *str, qsizetype len)

Создаёт представление строки str длиной len.

Передача [str,len) в качестве str безопасна, если len равно 0, и приводит к представлению пустой строки.

Поведение не определено, если len отрицательно или, если положительно, если str является nullptr.

Этот конструктор участвует в разрешении перегрузки только в том случае, если Char — это совместимый тип символов. Совместимые типы символов: char8_t, char, signed char и unsigned char.

QUtf8StringView::QUtf8StringView(std::nullptr_t)

Создаёт строку-просмотр null.

См. также isNull().

QUtf8StringView::QUtf8StringView()

Создаёт строку-просмотр null.

См. также isNull().

QUtf8StringView::storage_type QUtf8StringView::at(qsizetype n) const

Возвращает код символа в позиции n в этой строке-просмотре.

Поведение не определено, если n отрицательно или не меньше size().

См. также operator[](), front() и back().

QUtf8StringView::storage_type QUtf8StringView::back() const

Возвращает последний код символа в строке. То же, что и last().

Эта функция предоставляется для совместимости со STL.

См. также front().

QUtf8StringView::const_iterator QUtf8StringView::begin() const

Возвращает постоянный итератор STL, указывающий на первый код символа в строке.

Эта функция предоставляется для совместимости со STL.

См. также end(), cbegin(), rbegin() и data().

QUtf8StringView::const_iterator QUtf8StringView::cbegin() const

То же, что и begin().

Эта функция предоставляется для совместимости со STL.

См. также cend(), begin(), crbegin() и data().

QUtf8StringView::const_iterator QUtf8StringView::cend() const

То же, что и end().

Эта функция предоставляется для совместимости со STL.

См. также cbegin(), end() и crend().

void QUtf8StringView::chop(qsizetype n)

Усекает эту строку-просмотр на n кодовых точек.

То же, что и *this = first(size() - n).

См. также sliced(), first(), last(), chopped() и truncate().

QUtf8StringView QUtf8StringView::chopped(qsizetype n) const

Возвращает подстроку длиной size() - n, начиная с начала этого объекта.

То же, что и first(size() - n).

См. также sliced(), first(), last(), chop() и truncate().

QUtf8StringView::const_reverse_iterator QUtf8StringView::crbegin() const

То же, что и rbegin().

Эта функция предоставляется для совместимости со STL.

См. также crend(), rbegin() и cbegin().

QUtf8StringView::const_reverse_iterator QUtf8StringView::crend() const

То же, что и rend().

Эта функция предоставляется для совместимости со STL.

См. также crbegin(), rend() и cend().

QUtf8StringView::const_pointer QUtf8StringView::data() const

Возвращает указатель на первый код символа в строке.

См. также begin(), end() и utf8().

bool QUtf8StringView::empty() const

Возвращает значение true, если эта строка-просмотр пустая, т.е. size() == 0.

Эта функция предоставляется для совместимости со STL.

См. также isEmpty(), isNull(), size() и length().

QUtf8StringView::const_iterator QUtf8StringView::end() const

Возвращает постоянный итератор STL, указывающий на воображаемую кодовую точку после последней кодовой точки в списке.

Эта функция предоставляется для совместимости со STL.

См. также begin(), cend() и rend().

QUtf8StringView QUtf8StringView::first(qsizetype n) const

Возвращает строку-просмотр, содержащую первые n кодовых точек этой строки.

См. также last(), sliced(), chopped(), chop() и truncate().

[static] template <typename Char, size_t Size, if_compatible_char<Char>> QUtf8StringView QUtf8StringView::fromArray(const Char (&)[Size] string = Size)

Создаёт строку-просмотр на полном символьном строковом литерале string, включая любой завершающий Char(0). Если вы не хотите включать завершающий нуль в просмотр, вы можете chop() его, когда уверены, что он находится в конце. В качестве альтернативы вы можете использовать перегрузку конструктора, принимающую литерал массива, который создаст просмотр до, но не включая, первого завершающего нуля в данных.

string должен оставаться допустимым в течение всего срока службы этого объекта строки-просмотра.

Эта функция будет работать с любым литералом массива, если Char — совместимый тип символов. Совместимые типы символов: char8_t, char, signed char и unsigned char.

QUtf8StringView::storage_type QUtf8StringView::front() const

Возвращает первый код символа в строке. То же, что и first().

Эта функция предоставляется для совместимости со STL.

См. также back().

bool QUtf8StringView::isEmpty() const

Возвращает значение true, если эта строка-просмотр пустая, т.е. size() == 0.

Эта функция предоставляется для совместимости с другими контейнерами Qt.

См. также empty(), isNull(), size() и length().

bool QUtf8StringView::isNull() const

Возвращает значение true, если эта строка-просмотр null, т.е. data() == nullptr.

Эта функция предоставляется для совместимости с другими контейнерами Qt.

См. также empty(), isEmpty(), size() и length().

QUtf8StringView QUtf8StringView::last(qsizetype n) const

Возвращает строку-просмотр, содержащую последние n кодовые точки этой строки.

См. также first(), sliced(), chopped(), chop() и truncate().

qsizetype QUtf8StringView::length() const

То же, что и size().

Эта функция предоставляется для совместимости с другими контейнерами Qt.

См. также empty(), isEmpty(), isNull(), и size().

QUtf8StringView::const_reverse_iterator QUtf8StringView::rbegin() const

Возвращает константный итератор обратного порядка STL, указывающий на первый код символа в строке в обратном порядке.

Эта функция предоставляется для совместимости со STL.

См. также rend(), crbegin(), и begin().

QUtf8StringView::const_reverse_iterator QUtf8StringView::rend() const

Возвращает итератор обратного порядка STL, указывающий на позицию после последнего кода символа в строке в обратном порядке.

Эта функция предоставляется для совместимости со STL.

См. также rbegin(), crend(), и end().

qsizetype QUtf8StringView::size() const

Возвращает размер этой строковой области, в точках кода UTF-8 (то есть многобайтовые последовательности считаются более чем одной для целей этой функции, так же, как пары суррогатов в QString и QStringView).

См. также empty(), isEmpty(), isNull(), и length().

QUtf8StringView QUtf8StringView::sliced(qsizetype pos) const

Возвращает строковую область, начинающуюся с позиции pos в этом объекте и продолжающуюся до его конца.

См. также first(), last(), chopped(), chop(), и truncate().

QUtf8StringView QUtf8StringView::sliced(qsizetype pos, qsizetype n) const

Возвращает строковую область, содержащую n точек кода этой строковой области, начиная с позиции pos.

См. также first(), last(), chopped(), chop(), и truncate().

QString QUtf8StringView::toString() const

Возвращает глубокую копию данных этой строковой области в виде QString.

Возвращаемое значение будет пустым QString только в том случае, если эта строковая область является нулевой.

void QUtf8StringView::truncate(qsizetype n)

Усекает эту строковую область до n точек кода.

То же, что и *this = first(n).

См. также sliced(), first(), last(), chopped(), и chop().

const char8_t *QUtf8StringView::utf8() const

Возвращает указатель на первый код символа в строке.

Результат возвращается в виде const char8_t*, поэтому эта функция доступна только при компиляции в режиме C++20.

См. также begin(), end(), и data().

QUtf8StringView::storage_type QUtf8StringView::operator[](qsizetype n) const

Возвращает точку кода в позиции n в этой строковой области.

Поведение не определено, если n отрицательное или не меньше size().

См. также at(), front(), и back().