Класс QStringView

Класс QStringView предоставляет унифицированный вид на UTF-16 строки с подмножеством функций класса 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 разработана как интерфейсный тип; её основное использование — в качестве типа параметра функции. При использовании QStringViews в качестве автоматических переменных или данных-членов необходимо следить за тем, чтобы данные строки, на которые ссылается QStringView (например, принадлежащие QString), существовали дольше, чем QStringView, на всех путях кода, чтобы избежать ситуации, когда строковый вид ссылается на удалённые данные.

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

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

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

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

• 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 функциях). Вместо этого можно использовать цикл с индексами и/или utf16() в constexpr контекстах.

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

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

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

typedef QStringView::const_iterator

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

См. также итератор и const_обратный_итератор.

typedef QStringView::const_pointer

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

typedef QStringView::const_reference

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

typedef QStringView::const_reverse_iterator

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

См. также обратный итератор и итератор.

typedef QStringView::difference_type

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

typedef QStringView::iterator

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

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

См. также const_итератор и обратный итератор.

typedef QStringView::pointer

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

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

typedef QStringView::reference

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

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

typedef QStringView::reverse_iterator

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

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

См. также const_обратный итератор и итератор.

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, латинской-1 строки 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().

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

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

QStringView::QStringView(const QString &str)

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

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

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

QStringView::QStringView(const Char *str)

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

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

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

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

QStringView::QStringView(const Char (&)[N] string = ...)

Создаёт представление строки-литерала 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.

QStringView::QStringView(const Char *first, const Char *last)

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

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

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

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

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

QStringView::QStringView(const Char *str, qsizetype len)

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

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

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

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

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

QStringView::QStringView(std::nullptr_t)

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

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

QStringView::QStringView()

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

См. также 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 other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const

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

Если 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

Возвращает, является ли эта строка-представление пустой — то есть, является ли 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

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

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

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

bool QStringView::isNull() const

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

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

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

bool QStringView::isRightToLeft() const

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

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

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

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.

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

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

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

QString QStringView::toString() const

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

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

Предупреждение: 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

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

storage_type — это char16_t.

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

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

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

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

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

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