Класс 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 разработан как интерфейсный тип; его основное использование — в качестве типа параметра функции. Когда QUtf8StringViews используются в качестве автоматических переменных или членов данных, необходимо убедиться, что ссылаемые данные строки (например, принадлежащие 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 следует передавать по значению, а не по константной ссылке:

    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(), оператор[]()

Ожидается, что 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

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

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

QUtf8StringView::const_pointer

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

QUtf8StringView::const_reference

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

QUtf8StringView::const_reverse_iterator

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

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

QUtf8StringView::difference_type

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

QUtf8StringView::iterator

Этот псевдоним типа предоставляет итератор типа 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

Этот псевдоним типа предоставляет обратный итератор типа 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.

Передача nullptr в качестве 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).

Примечание: Поведение неопределено, когда 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

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

Примечание: Символьный массив, возвращаемый функцией, не завершается нулём.

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

Примечание: Поведение неопределено, когда 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, указывающий на первый код символа в строке в обратном порядке.

Эта функция предоставляется для совместимости со 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 char8_t*, поэтому эта функция доступна только при компиляции в режиме C++20.

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

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

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

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

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

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