Класс 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) строковые литералы. Несовместимость между C++17 и C++20 при использовании QUtf8StringView исчезает.

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

    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 строковые литералы изменили свой тип с 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.

В режиме C++17 q_no_char8_t — это встроенное именованное пространство, в C++20 — q_has_char8_t. Это означает, что имя «QUtf8StringView» (без явного указания именованного пространства) будет обозначать разные типы в режимах C++17 и C++20.

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

Все API Qt используют q_no_char8_t::QUtf8StringView из-за двоичной совместимости, но эти API также принимают q_has_char8_t::QUtf8StringView, поскольку последний неявно преобразуется в первый и наоборот.

В своём собственном коде используйте только QUtf8StringView и/или q_no_char8_t::QUtf8StringView:

• Если вы ориентируетесь только на C++20, используйте «QUtf8StringView». Это будет алиас для q_has_char8_t::QUtf8StringView, и вы больше никогда не вернётесь назад.
• Если вы ориентируетесь только на C++17, используйте «QUtf8StringView». Это будет алиас для q_no_char8_t::QUtf8StringView, и пока всё в порядке.
• Если вы ориентируетесь как на C++17, так и на C++20, вам придётся сделать выбор:
  • Если вас не беспокоит несовместимость исходного кода значений, возвращаемых QUtf8StringView::data() и т.д., при компиляции в C++17 или C++20, используйте «QUtf8StringView». Вам нужно будет написать свой код таким образом, чтобы он адаптировался к различиям в API QUtf8StringView в разных версиях C++.
  • Если вы не хотите иметь дело с указанными выше проблемами несовместимости исходного кода или вам нужна двоичная совместимость между сборками C++20 и C++17, явно используйте «q_no_char8_t::QUtf8StringView». Имейте в виду, что версия q_no_char8_t исчезнет в Qt 7.

В итоге: просто используйте QUtf8StringView, если вы не знаете, что делаете.

См. также 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) должен оставаться валидным в течение всего времени существования объекта представления строки.

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

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

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

QUtf8StringView::QUtf8StringView(std::nullptr_t)

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

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

QUtf8StringView::QUtf8StringView()

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

См. также 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

Возвращает указатель типа 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).

Примечание: Поведение не определено, когда n < 0 или n > size().

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

QUtf8StringView QUtf8StringView::chopped(qsizetype n) const

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

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

Примечание: Поведение не определено, когда n < 0 или n > size().

См. также 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

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

Примечание: Массив символов, представленный возвращаемым значением, не завершается нулём.

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

bool QUtf8StringView::empty() const

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

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

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

QUtf8StringView::const_iterator QUtf8StringView::end() const

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

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

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

QUtf8StringView QUtf8StringView::first(qsizetype n) const

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

Примечание: Поведение не определено, когда n < 0 или n > size().

См. также 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 кодов символов этой строки.

Примечание: Поведение не определено, когда n < 0 или n > size().

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

QUtf8StringView::const_reverse_iterator QUtf8StringView::rbegin() const

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

Эта функция предоставлена для совместимости со 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 в этом объекте и продолжающуюся до его конца.

Примечание: Поведение не определено, когда pos < 0 или pos > size().

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

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

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

Примечание: Поведение не определено, когда pos < 0, n < 0 или pos + n > size().

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

QString QUtf8StringView::toString() const

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

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

void QUtf8StringView::truncate(qsizetype n)

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

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

Примечание: Поведение не определено, когда n < 0 или n > size().

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

const char8_t *QUtf8StringView::utf8() const

Возвращает указатель const на первую кодовую точку в строке.

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

Примечание: Массив символов, представленный возвращаемым значением, не является нуль-терминированным.

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

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

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

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

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