Класс QStringView

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

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

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

Публичные типы

Публичные функции

Связанные нечленные функции

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

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

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

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

QStringView разработан как тип интерфейса; его основное использование — в качестве типа параметра функции. При использовании 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

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

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

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

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

typedef QStringView::const_iterator

Этот typedef предоставляет итератор по умолчанию для QStringView.

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

typedef QStringView::const_pointer

Псевдоним для value_type *. Предоставлен для совместимости со стандартной библиотекой шаблонов.

typedef QStringView::const_reference

Псевдоним для value_type &. Предоставлен для совместимости со стандартной библиотекой шаблонов.

typedef QStringView::const_reverse_iterator

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

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

typedef QStringView::difference_type

Псевдоним для std::ptrdiff_t. Предоставлен для совместимости со стандартной библиотекой шаблонов.

typedef QStringView::iterator

Этот typedef предоставляет итератор по умолчанию для QStringView.

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

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

typedef QStringView::pointer

Псевдоним для value_type *. Предоставлен для совместимости со стандартной библиотекой шаблонов.

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

typedef QStringView::reference

Псевдоним для value_type &. Предоставлен для совместимости со стандартной библиотекой шаблонов.

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

typedef QStringView::reverse_iterator

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

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

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

typedef QStringView::size_type

Псевдоним для qsizetype. Предоставлен для совместимости со стандартной библиотекой шаблонов.

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

typedef QStringView::storage_type

Псевдоним для char16_t для не-Windows платформ или если определен Q_COMPILER_UNICODE_STRINGS. В противном случае псевдоним для wchar_t.

typedef QStringView::value_type

Псевдоним для const QChar. Предоставлен для совместимости со стандартной библиотекой шаблонов.

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

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

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

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

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

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

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

QStringView::QStringView()

Конструирует пустую строку-представление.

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

QStringView::QStringView(std::nullptr_t)

Конструирует пустую строку-представление.

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

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

Конструирует строку-представление на str с длиной len.

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

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

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

Этот конструктор участвует только в разрешении перегрузки, если 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, и приводит к представлению пустой строки.

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

Этот конструктор участвует в разрешении перегрузки только если 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 *str)

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

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

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

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

QStringView::QStringView(const QString &str)

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

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

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

QStringView::QStringView(const QStringRef &str)

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

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

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

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().

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 и возвращает целое число, меньшее, равное или больше нуля, если это представление строки меньше, равно или больше, чем представление строки 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

Возвращает значение 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, если эта строковая область равна null, т.е. 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.

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().