Класс QStringView

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

Этот класс был представлен в Qt 5.10.

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

Примечание: Все функции в этом классе являются повторно входящими.

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

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

Связанные нечлены

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

QStringView ссылается на непрерывную часть строки UTF-16, она не является владельцем этой строки. Она действует как интерфейсный тип для всех типов строк UTF-16, без необходимости предварительно создавать QString.

Строка UTF-16 может быть представлена как массив (или совместимая с массивом структура данных, такая как QString, std::basic_string и т. д.) объектов QChar, ushort, char16_t или (на платформах, таких как Windows, где это 16-битный тип) wchar_t.

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

При использовании в качестве интерфейсного типа QStringView позволяет одной функции принимать широкий спектр источников данных строк UTF-16. Одна функция, принимающая QStringView, таким образом, заменяет три перегрузки функции (принимающие QString, QStringRef и (const QChar*, int)), одновременно позволяя передавать в функцию ещё больше источников данных строк, таких как u"Hello World", char16_t строковый литерал.

QStringView следует передавать по значению, а не по ссылке-константе:

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

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

• QChar: эта перегрузка может делегировать вызов функции для QStringView:

      void fun(QChar ch) { fun(QStringView(&ch, 1)); }

  хотя по техническим причинам QStringView не может сам предоставить конструктор QChar.

• QString: если вы храните немодифицированную копию строки и хотите воспользоваться неявным совместным использованием QString.
• QLatin1String: если вы можете реализовать функцию без предварительного преобразования QLatin1String в UTF-16; пользователи ожидают, что функция, перегруженная на QLatin1String, будет выполнять существенно меньше операций выделения памяти, чем семантически эквивалентный вызов версии QStringView, включающий создание QString из QLatin1String.

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

QStringView — литеральный тип, но поскольку он хранит данные в формате char16_t, итерация не constexpr (преобразования из const char16_t* в const QChar*, что запрещено в constexpr функциях). В constexpr контекстах вы можете использовать цикл с индексом и/или utf16().

Примечание: Мы настоятельно не рекомендуем использовать QList<QStringView>, потому что QList — очень неэффективный контейнер для QStringView (он будет выделять каждый элемент в куче). Используйте QVector (или std::vector) для хранения QStringView вместо этого.

См. также QString и QStringRef.

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

typedef QStringView::const_iterator

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

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

typedef QStringView::const_pointer

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

typedef QStringView::const_reference

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

typedef QStringView::const_reverse_iterator

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

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

typedef QStringView::difference_type

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

typedef QStringView::iterator

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

QStringView не поддерживает изменяемые итераторы, поэтому он такой же, как const_iterator.

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

typedef QStringView::pointer

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

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

typedef QStringView::reference

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

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

typedef QStringView::reverse_iterator

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

QStringView не поддерживает изменяемые обратные итераторы, поэтому он такой же, как const_reverse_iterator.

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

typedef QStringView::size_type

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

В отличие от других классов Qt, QStringView использует qsizetype в качестве своего size_type, чтобы позволить принимать данные из std::basic_string без усечения. Функции API Qt, например, length(), возвращают int, а функции, совместимые со STL, например, size(), возвращают size_type.

typedef QStringView::storage_type

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

typedef QStringView::value_type

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

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

Возвращает индекс последнего вхождения строки str, латинской строки l1 или символа ch соответственно в этой строке, идя назад с индекса from. Если from равно -1 (по умолчанию), поиск начинается с последнего символа; если from равно -2, то с предпоследнего символа и так далее. Возвращает -1, если str не найдено.

Если cs равно Qt::CaseSensitive (по умолчанию), поиск выполняется с учётом регистра; в противном случае поиск выполняется без учёта регистра.

Эта функция была добавлена в Qt 5.14.

См. также QString::lastIndexOf().

Возвращает true, если в этой строке-представлении содержится вхождение строки-представления str, строки Latin-1 l1 или символа ch; в противном случае возвращает false.

Если cs имеет значение Qt::CaseSensitive (по умолчанию), поиск регистрозависимый; в противном случае поиск регистронезависимый.

Эта функция была добавлена в Qt 5.14.

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

Возвращает индекс первого вхождения строки-представления str, строки Latin-1 l1 или символа ch соответственно в этой строке-представлении, выполняя поиск вперёд с индекса from. Возвращает -1, если str не найдено.

Если cs имеет значение Qt::CaseSensitive (по умолчанию), поиск регистрозависимый; в противном случае поиск регистронезависимый.

Если from равно -1, поиск начинается с последнего символа; если -2, со второго с конца и так далее.

Эта функция была добавлена в Qt 5.14.

См. также QString::indexOf().

Возвращает true, если эта строка-представление заканчивается строкой-представлением str, строкой Latin-1 l1 или символом ch соответственно; в противном случае возвращает false.

Если cs имеет значение Qt::CaseSensitive (по умолчанию), поиск регистрозависимый; в противном случае поиск регистронезависимый.

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

Возвращает true, если эта строка-представление начинается со строки-представления str, строки Latin-1 l1 или символа ch соответственно; в противном случае возвращает false.

Если cs имеет значение Qt::CaseSensitive (по умолчанию), поиск регистрозависимый; в противном случае поиск регистронезависимый.

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

Возвращает целое число, которое сравнивается с нулём, как эта строка-представление сравнивается со строкой Latin-1 l1 или символом ch соответственно.

Если cs имеет значение Qt::CaseSensitive (по умолчанию), сравнение регистрозависимое; в противном случае сравнение регистронезависимое.

См. также operator==(), operator<() и operator>().

template <typename Args> QString QStringView::arg(Args &&... args) const

Заменяет вхождения %N в этой строке соответствующим аргументом из args. Аргументы не позиционные: первый из args заменяет %N с наименьшим N (все из них), второй из args — %N с следующим по величине N и т.д.

Args может содержать что угодно, что неявно преобразуется в QString, QStringView или QLatin1String.

Кроме того, поддерживаются следующие типы: QChar, QLatin1Char.

Эта функция была добавлена в Qt 5.14.

См. также QString::arg().

template <typename StdBasicString, if_compatible_string<StdBasicString>> QStringView::QStringView(const StdBasicString &str)

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

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

Этот конструктор участвует в разрешении перегрузки только если StdBasicString является экземпляром std::basic_string с совместимым типом символа. Совместимые типы символов: QChar, ushort, char16_t и (на платформах, таких как Windows, где это 16-битный тип) wchar_t.

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

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

QStringView::QStringView(const QStringRef &str)

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

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

Представление строки будет пустым тогда и только тогда, когда str.isNull().

QStringView::QStringView(const QString &str)

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

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

Представление строки будет пустым тогда и только тогда, когда str.isNull().

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

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

str должен оставаться валидным в течение всего жизненного цикла объекта представления строки.

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

Этот конструктор участвует в разрешении перегрузки только если str не является массивом и если Char является совместимым типом символа. Совместимые типы символов: QChar, ushort, char16_t и (на платформах, таких как Windows, где это 16-битный тип) wchar_t.

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

Создаёт представление строки на строковой литерал символов string. Длина установлена в N-1, исключая заключительный {Char(0)}. Если вам нужна вся строка, используйте конструктор из указателя и размера вместо этого:

    auto sv = QStringView(array, std::size(array)); // using C++17 std::size()

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

Этот конструктор участвует в разрешении перегрузки только если string является фактическим массивом и Char является совместимым типом символов. Совместимые типы символов: QChar, ushort, char16_t и (на платформах, таких как Windows, где это 16-битный тип) wchar_t.

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

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

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

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

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

Этот конструктор участвует в разрешении перегрузки только если Char является совместимым типом символов. Совместимые типы символов: QChar, ushort, char16_t и (на платформах, таких как Windows, где это 16-битный тип) wchar_t.

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

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

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

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

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

Этот конструктор участвует в разрешении перегрузки только если Char является совместимым типом символов. Совместимые типы символов: QChar, ushort, char16_t и (на платформах, таких как Windows, где это 16-битный тип) wchar_t.

QStringView::QStringView(std::nullptr_t)

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

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

QStringView::QStringView()

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

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

QChar QStringView::at(qsizetype n) const

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

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

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

QChar QStringView::back() const

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

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

Предупреждение: Вызов этой функции для пустого представления строки приводит к неопределённому поведению.

См. также front(), first() и last().

QStringView::const_iterator QStringView::begin() const

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

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

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

QStringView::const_iterator QStringView::cbegin() const

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

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

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

QStringView::const_iterator QStringView::cend() const

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

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

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

void QStringView::chop(qsizetype length)

Усекает это представление строки на length символов.

То же самое, что и *this = left(size() - length).

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

См. также mid(), left(), right(), chopped() и truncate().

QStringView QStringView::chopped(qsizetype length) const

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

То же самое, что и left(size() - length).

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

См. также mid(), left(), right(), chop() и truncate().

int QStringView::compare(QStringView str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Возвращает целое число, которое сравнивается с нулём как это представление строки со строкой str.

Если cs равен Qt::CaseSensitive (по умолчанию), сравнение чувствительно к регистру; в противном случае сравнение нечувствительно к регистру.

Эта функция была представлена в Qt 5.12.

См. также operator==(), operator<() и operator>().

QStringView::const_reverse_iterator QStringView::crbegin() const

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

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

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

QStringView::const_reverse_iterator QStringView::crend() const

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

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

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

QStringView::const_pointer QStringView::data() const

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

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

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

bool QStringView::empty() const

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

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

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

QStringView::const_iterator QStringView::end() const

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

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

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

QChar QStringView::first() const

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

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

Предупреждение: Вызов этой функции для пустого представления строки приводит к неопределённому поведению.

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

QChar QStringView::front() const

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

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

Предупреждение: Вызов этой функции для пустого представления строки приводит к неопределённому поведению.

См. также back(), first() и last().

bool QStringView::isEmpty() const

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

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

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

bool QStringView::isNull() const

Возвращает значение true, если данная строка-представление является пустой — то есть, если data() == nullptr.

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

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

bool QStringView::isRightToLeft() const

Возвращает значение true, если строка читается справа налево.

Эта функция была добавлена в Qt 5.11.

См. также QString::isRightToLeft().

bool QStringView::isValidUtf16() const

Возвращает значение true, если строка содержит данные, закодированные в формате UTF-16, или false в противном случае.

Обратите внимание, что эта функция не выполняет специальной проверки данных; она лишь проверяет, может ли она быть успешно декодирована из UTF-16. Предполагается, что данные находятся в порядке байтов хоста; наличие BOM не имеет значения.

Эта функция была добавлена в Qt 5.15.

См. также QString::isValidUtf16().

QChar QStringView::last() const

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

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

Предупреждение: Вызов этой функции для пустой строки-представления приводит к неопределённому поведению.

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

QStringView QStringView::left(qsizetype length) const

Возвращает подстроку длиной length, начиная с позиции 0 в этом объекте.

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

См. также mid(), right(), chopped(), chop() и truncate().

int QStringView::length() const

То же самое, что size(), за исключением того, что результат возвращается как int.

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

Предупреждение: QStringView может представлять строки с более чем 2³¹ символами. Вызов этой функции для строки-представления, для которой size() возвращает значение большее, чем INT_MAX приводит к неопределённому поведению.

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

QStringView QStringView::mid(qsizetype start) const

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

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

См. также left(), right(), chopped(), chop() и truncate().

QStringView QStringView::mid(qsizetype start, qsizetype length) const

Это перегруженная функция.

Возвращает подстроку длиной length, начиная с позиции start в этом объекте.

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

См. также left(), right(), chopped(), chop() и truncate().

QStringView::const_reverse_iterator QStringView::rbegin() const

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

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

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

QStringView::const_reverse_iterator QStringView::rend() const

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

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

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

QStringView QStringView::right(qsizetype length) const

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

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

См. также mid(), left(), chopped(), chop() и truncate().

qsizetype QStringView::size() const

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

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

QByteArray QStringView::toLatin1() const

Возвращает представление строки в кодировке Latin-1 в виде QByteArray.

Поведение неопределённо, если строка содержит символы, не поддерживаемые Latin-1.

См. также toUtf8(), toLocal8Bit() и QTextCodec.

QByteArray QStringView::toLocal8Bit() const

Возвращает представление строки в локальной 8-битной кодировке в виде QByteArray.

Для преобразования из Unicode используется QTextCodec::codecForLocale(). Если кодировка локали не может быть определена, эта функция делает то же самое, что и toLatin1().

Поведение неопределённо, если строка содержит символы, не поддерживаемые локальной 8-битной кодировкой.

См. также toLatin1(), toUtf8() и QTextCodec.

QString QStringView::toString() const

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

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

Предупреждение: QStringView может хранить строки с более чем 2³⁰ символами, в то время как QString не может. Вызов этой функции для строки-представления, для которой size() возвращает значение большее, чем INT_MAX / 2 приводит к неопределённому поведению.

QVector<uint> QStringView::toUcs4() const

Возвращает представление строки в кодировке UCS-4/UTF-32 в виде QVector<uint>.

UCS-4 — это кодировка Unicode, поэтому она не приводит к потерям. Все символы из этой строки будут закодированы в UCS-4. Любая недопустимая последовательность кодовых единиц в этой строке заменяется символом замены Unicode (QChar::ReplacementCharacter, что соответствует U+FFFD).

Возвращаемый вектор не имеет нулевого терминатора.

См. также toUtf8(), toLatin1(), toLocal8Bit() и QTextCodec.

QByteArray QStringView::toUtf8() const

Возвращает представление строки в кодировке UTF-8 в виде QByteArray.

UTF-8 — это кодировка Unicode и может представлять все символы в строке Unicode, как в QString.

См. также toLatin1(), toLocal8Bit() и QTextCodec.

int QStringView::toWCharArray(wchar_t *array) const

Преобразует эту строку в заданный массив array.

Вызывающая сторона отвечает за обеспечение того, что array достаточно велик для хранения wchar_t кодировки этой строки (выделение массива с той же длиной, что и у строки, всегда достаточно). Массив закодирован в UTF-16 на платформах, где wchar_t имеет ширину 2 байта (например, Windows); в противном случае (системы Unix) wchar_t предполагается иметь ширину 4 байта, и данные записываются в UCS-4.

Примечание: Эта функция не записывает нулевой терминатор в конец array.

Возвращает количество wchar_t элементов, записанных в array.

Эта функция была добавлена в Qt 5.14.

См. также QString::toWCharArray().

QStringView QStringView::trimmed() const

Удаляет начальные и конечные пробелы и возвращает результат.

Пробелы означают любой символ, для которого QChar::isSpace() возвращает true. Это включает в себя ASCII-символы '\t', '\n', '\v', '\f', '\r' и ' '.

void QStringView::truncate(qsizetype length)

Усекает данное представление строки до длины length.

То же, что и *this = left(length).

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

См. также mid(), left(), right(), chopped() и chop().

const QStringView::storage_type *QStringView::utf16() const

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

storage_type равен char16_t.

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

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

QChar QStringView::operator[](qsizetype n) const

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

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

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