QUtf8StringView 类

QUtf8StringView 类提供了对 UTF-8 字符串的统一视图,包含 QString API 的只读子集。 更多...

头文件 #include <QUtf8StringView>
CMakefind_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmakeQT += core
自从Qt 6.0

注意: 该类中所有函数均为 可重入

公共类型

公共函数

QUtf8StringView()
QUtf8StringView(std::nullptr_t)
QUtf8StringView(const Char *str, qsizetype len)
QUtf8StringView(const Char *first, const Char *last)
QUtf8StringView(const Char (&)[N] string)
QUtf8StringView(const Char *str)
QUtf8StringView(const Container &str)
QUtf8StringView::storage_typeat(qsizetype n) const
QUtf8StringView::storage_typeback() const
QUtf8StringView::const_iteratorbegin() const
QUtf8StringView::const_iteratorcbegin() const
QUtf8StringView::const_iteratorcend() const
voidchop(qsizetype n)
QUtf8StringViewchopped(qsizetype n) const
(since 6.5) intcompare(QUtf8StringView str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
(since 6.5) intcompare(QStringView str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
(since 6.5) intcompare(QLatin1StringView str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
QUtf8StringView::const_reverse_iteratorcrbegin() const
QUtf8StringView::const_reverse_iteratorcrend() const
QUtf8StringView::const_pointerdata() const
boolempty() const
QUtf8StringView::const_iteratorend() const
QUtf8StringViewfirst(qsizetype n) const
QUtf8StringView::storage_typefront() const
boolisEmpty() const
boolisNull() const
(since 6.3) boolisValidUtf8() const
QUtf8StringViewlast(qsizetype n) const
qsizetypelength() const
QUtf8StringView::const_reverse_iteratorrbegin() const
QUtf8StringView::const_reverse_iteratorrend() const
qsizetypesize() const
QUtf8StringViewsliced(qsizetype pos) const
QUtf8StringViewsliced(qsizetype pos, qsizetype n) const
QStringtoString() const
voidtruncate(qsizetype n)
const char8_t *utf8() const
(since 6.7) std::basic_string_view<QUtf8StringView::storage_type>operator std::basic_string_view<QUtf8StringView::storage_type>() const
QUtf8StringView::storage_typeoperator[](qsizetype n) const

静态公共成员

QUtf8StringViewfromArray(const Char (&)[Size] string)

详细描述

A QUtf8StringView引用了UTF-8字符串的连续部分,它不拥有该字符串。它作为所有种类的UTF-8字符串的接口类型,无需首先创建QStringQByteArray

UTF-8字符串可以表示为一个char8_tcharsigned charunsigned char数组(或与数组兼容的数据结构,如std::basic_string等)。

QUtf8StringView被设计为一个接口类型;其主要用例是作为函数参数类型。当QUtf8StringView用作自动变量或数据成员时,必须注意确保引用的字符串数据(例如,由std::u8string拥有的)在所有代码路径上都比QUtf8StringView持久,否则 字符串视图最终会引用已被删除的数据。

当用作接口类型时,QUtf8StringView允许单个函数接受各种UTF-8字符串数据源。因此,接受QUtf8StringView的一个函数可以替代几个函数重载(例如,接受QByteArray),同时还可以将更多的字符串数据源传递给函数,例如u8"Hello World"、一个char8_t(C++20)或char(C++17)字符串字面量。使用QUtf8StringView时,C++17和C++20之间的char8_t不兼容性消失了。

像所有视图一样,QUtf8StringView应按值传递,而不是按引用传递到const

    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

这是Qt 7中期待QUtf8StringView的样子,但出于Qt 6的原因,当时不能这么做。Qt选择提供两个不同的(内联)命名空间中的QUtf8StringView类,而不是将用户锁定在C++17时代的接口上十年。第一个,在命名空间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的实例化,请勿在源代码中使用该模板类的名称。

也请参阅QAnyStringViewQUtf8StringViewQString

成员类型文档

QUtf8StringView::const_iterator

此typedef提供了适用于QUtf8StringView的STL风格的const迭代器。

也请参阅iteratorconst_reverse_iterator

QUtf8StringView::const_pointer

value_type *的别名。为了与STL兼容提供。

QUtf8StringView::const_reference

value_type &的别名。为了与STL兼容提供。

QUtf8StringView::const_reverse_iterator

此typedef为QUtf8StringView提供了STL风格的const反向迭代器。

也请参阅reverse_iteratorconst_iterator

QUtf8StringView::difference_type

std::ptrdiff_t的别名。为了与STL兼容提供。

QUtf8StringView::迭代器

此typedef提供了适用于QUtf8StringView的STL风格的const迭代器。

QUtf8StringView 不支持可变迭代器,因此这与 const_iterator 相同。

另请参阅const_iteratorreverse_iterator

QUtf8StringView::指针

value_type *的别名。为了与STL兼容提供。

QUtf8StringView 不支持可变指针,因此这与 const_pointer 相同。

QUtf8StringView::引用

value_type &的别名。为了与STL兼容提供。

QUtf8StringView 不支持可变引用,因此这与 const_reference 相同。

QUtf8StringView::反向迭代器

此typedef为QUtf8StringView提供了STL风格的const反向迭代器。

QUtf8StringView 不支持可变反向迭代器,因此这与 const_reverse_iterator 相同。

另请参阅const_reverse_iteratoriterator

QUtf8StringView::size_type

代表 qsizetype,以便与 STL 兼容。

[别称] QUtf8StringView::storage_type

代表 char

QUtf8StringView::value_type

代表 const char,以便与 STL 兼容。

成员函数文档

[noexcept, 自 6.5 版起] int QUtf8StringView::compare(QLatin1StringView str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const

[noexcept, 自 6.5 版起] int QUtf8StringView::compare(QStringView str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const

[noexcept, 自 6.5 版起] int QUtf8StringView::compare(QUtf8StringView str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const

比较此字符串视图与 str,如果此字符串视图小于 str,则返回负整数,如果大于 str,则返回正整数,如果它们相等,则返回零。

如果 csQt::CaseSensitive(默认值),比较区分大小写;否则比较不区分大小写。

此功能自 Qt 6.5 版引入。

[constexpr noexcept] QUtf8StringView::QUtf8StringView()

构建一个空字符串视图。

另请参阅isNull()[

[constexpr noexcept] QUtf8StringView::QUtf8StringView(std::nullptr_t)

构建一个空字符串视图。

另请参阅isNull()[

[constexpr] 模板 <typename Char, QUtf8StringView::if_compatible_char<Char> = true> QUtf8StringView::QUtf8StringView(const Char *str, qsizetype len)

str 上构造具有长度 len 的字符串视图。

此字符串视图对象的生存期内,范围 [str,len) 必须保持有效。

如果 len 也是0,则将 nullptr 作为 str 传递是安全的,并将生成空字符串视图。

如果 len 为负数,或者当为正数时,如果 strnullptr,行为是未定义的。

如果 Char 是兼容字符类型,则此构造函数才参与重载解析。兼容的字符类型包括: char8_tcharsigned charunsigned char

[constexpr] 模板 <typename Char, QUtf8StringView::if_compatible_char<Char> = true> QUtf8StringView::QUtf8StringView(const Char *first, const Char *last)

根据长度 (last - first) 在 first 上构造一个字符串视图。

此字符串视图对象的生存期内,范围 [first,last) 必须保持有效。

如果 last 也是 nullptr,则将 \nullptr 作为 first 传递是安全的,并将生成空字符串视图。

如果 last 先于 first,或者 firstnullptr 而非 last,行为是未定义的。

如果 Char 是兼容字符类型,则此构造函数才参与重载解析。兼容的字符类型包括: char8_tcharsigned charunsigned char

[constexpr noexcept] 模板 <typename Char, size_t N> QUtf8StringView::QUtf8StringView(const Char (&)[N] string)

在字符字符串文字 string 上构造字符串视图。视图覆盖数组直到遇到第一个 Char(0)N,以先到者为准。如果需要完整的数组,请使用 fromArray()。

string 必须保持在此字符串视图对象的生存期内有效。

如果 string 是实际数组且如果 Char 是兼容字符类型,则此构造函数才参与重载解析。兼容的字符类型包括: char8_tcharsigned charunsigned char

另请参阅 fromArray().

[constexpr noexcept] 模板 <typename Char> QUtf8StringView::QUtf8StringView(const Char *str)

str 上构造字符串视图。长度通过搜索第一个 Char(0) 来确定。

str 必须保持在此字符串视图对象的生存期内有效。

nullptr 作为 str 传递是安全的,并将生成空字符串视图。

如果 str 不是数组且如果 Char 是兼容字符类型,则此构造函数才参与重载解析。兼容的字符类型包括: char8_tcharsigned charunsigned char

[constexpr noexcept] 模板 <typename Container, QUtf8StringView::if_compatible_container<Container> = true> QUtf8StringView::QUtf8StringView(const Container &str)

str 上构造字符串视图。长度从 std::size(str) 取得。

std::data(str) 必须在此字符串视图对象的整个生命周期内保持有效。

此构造函数仅在 Container 是与 value_type 兼容字符类型的容器时参与重载解析。兼容的字符类型有:char8_tcharsigned charunsigned char

如果且仅当 std::size(str) == 0,字符串视图将为空。此构造函数能否产生空字符串视图(在此情况下,std::data(str) 必须返回 nullptr)是不确定的。

另请参阅 isNull() 和 isEmpty

[constexpr] QUtf8StringView::storage_type QUtf8StringView::at(qsizetype n) const

返回在字符串视图中位置 n 的代码点。

如果 n 为负数或大于等于 size(),行为未定义。

另请参阅 operator[]()、front() 和 back

[constexpr] QUtf8StringView::storage_type QUtf8StringView::back() const

返回字符串视图中最后一个代码点。与 last 相同。

此函数提供以适应 STL 兼容性。

警告: 在空字符串视图中调用此函数会导致未定义行为。

另请参阅 front

[noexcept] QUtf8StringView::const_iterator QUtf8StringView::begin() const

返回一个指向字符串视图中第一个代码点的不变 STL 样式迭代器

此函数提供以适应 STL 兼容性。

另请参阅 end()、cbegin()、rbegin() 和 data()。

[noexcept] QUtf8StringView::const_iterator QUtf8StringView::cbegin() const

begin 相同。

此函数提供以适应 STL 兼容性。

另请参阅 cend()、begin()、crbegin() 和 data()。

[noexcept] QUtf8StringView::const_iterator QUtf8StringView::cend() const

end 相同。

此函数提供以适应 STL 兼容性。

另请参阅 cbegin()、endcrend()。

[constexpr] void QUtf8StringView::chop(qsizetype n)

通过 n 个代码点截断此字符串视图。

*this = first(size() - n) 相同。

注意: n 小于 0 或大于 size() 时,行为未定义。

另请参阅 sliced(),first(),last(),chopped() 和 truncate()。

[constexpr] QUtf8StringView QUtf8StringView::chopped(qsizetype n) const

返回从该对象开头开始的长度为 size() - n 的子字符串。

等效于 first(size() - n)

注意: n 小于 0 或大于 size() 时,行为未定义。

另请参阅 sliced(),first(),last(),chop() 和 truncate()。

[noexcept] QUtf8StringView::const_reverse_iterator QUtf8StringView::crbegin() const

rbegin 相同。

此函数提供以适应 STL 兼容性。

另请参阅 crendrbegincbegin

[noexcept] QUtf8StringView::const_reverse_iterator QUtf8StringView::crend() const

rend 相同。

此函数提供以适应 STL 兼容性。

另请参阅 crbeginrendcend

[constexpr noexcept] QUtf8StringView::const_pointer QUtf8StringView::data() const

返回指向字符串视图中第一个码点的 const 指针。

注意: 由返回值表示的字符数组不是 null 结尾的。

另请参阅 beginendutf8

[constexpr noexcept] bool QUtf8StringView::empty() const

返回该字符串视图是否为空 - 即 size() == 0

此函数提供以适应 STL 兼容性。

另请参阅 isEmptyisNullsizelength

[noexcept] QUtf8StringView::const_iterator QUtf8StringView::end() const

返回一个指向字符串视图中最后一个码点后虚码点的 const 迭代器。

此函数提供以适应 STL 兼容性。

另请参阅 begincendrend

[constexpr] QUtf8StringView QUtf8StringView::first(qsizetype n) const

返回一个字符串视图,它包含该字符串视图中前 n 个码点。

注意: n 小于 0 或大于 size() 时,行为未定义。

另请参阅 lastslicedchoppedchoptruncate

[静态常量表达式 noexcept] 模板 <typename Char, size_t Size, QUtf8StringView::if_compatible_char<Char> = true> QUtf8StringView QUtf8StringView::fromArray(const Char (&)[Size] string)

构造一个字符串视图,包括任何尾随的 Char(0) 字符串字面量。如果您不希望在视图中包含空终止符,则可以在确定它是末尾时使用 chop()。或者,您可以使用带有数组字面量的构造函数重载,该构造函数将在数据中创建一个不包括第一个空终止符的视图。

string 必须保持在此字符串视图对象的生存期内有效。

如果 Char 是兼容字符类型,则此函数可以与任何数组字面量一起工作。兼容字符类型包括:char8_tcharsigned charunsigned char

[常量表达式] QUtf8StringView::storage_type QUtf8StringView::front() const

返回字符串视图中的第一个码点。与 first 相同。

此函数提供以适应 STL 兼容性。

警告: 在空字符串视图中调用此函数会导致未定义行为。

另请参阅back

[常量表达式 noexcept] bool QUtf8StringView::isEmpty() const

返回该字符串视图是否为空 - 即 size() == 0

此函数提供与其他 Qt 容器兼容。

另请参阅empty(),isNull(),size()和 length()。

[常量表达式 noexcept] bool QUtf8StringView::isNull() const

返回此字符串视图是否为空 - 即 data() == nullptr

该函数提供与其他 Qt 容器兼容。

另请参阅empty(),isEmpty(),size()和 length()。

[noexcept, since 6.3] bool QUtf8StringView::isValidUtf8() const

如果此字符串包含有效的 UTF-8 编码数据,则返回 true,否则返回 false

此函数是在 Qt 6.3 中引入的。

[常量表达式] QUtf8StringView QUtf8StringView::last(qsizetype n) const

返回包含此字符串视图最后 n 个码点的字符串视图。

注意: n 小于 0 或大于 size() 时,行为未定义。

另请参阅first(),sliced(),chopped(),chop()和 truncate()。

[常量表达式 noexcept] qsizetype QUtf8StringView::length() const

size 相同。

此函数提供与其他 Qt 容器兼容。

另请参阅empty(),isEmpty(),isNull()和 size()。

[noexcept] QUtf8StringView::const_reverse_iterator QUtf8StringView::rbegin() const

返回一个指向字符串视图第一个代码点并将其逆转的STL风格迭代器

此函数提供以适应 STL 兼容性。

另请参阅rend(),crbegin(),和begin()。

[noexcept] QUtf8StringView::const_reverse_iterator QUtf8StringView::rend() const

返回一个指向字符串视图最后一个代码点之后,并以倒序排列的STL风格迭代器

此函数提供以适应 STL 兼容性。

另请参阅rbegin(),crend(),和end()。

[constexpr noexcept] qsizetype QUtf8StringView::size() const

返回此字符串视图的大小,以UTF-8代码点数计算(即,对于本函数,多字节序列计为一个以上的代码点,与QStringQStringView中的代理对相同)。

另请参阅empty(),isEmpty(),isNull(),和length()。

[constexpr] QUtf8StringView QUtf8StringView::sliced(qsizetype pos) const

返回一个从对象中的位置pos开始到其末尾的字符串视图。

注意:当pos < 0或pos > size()时,行为未定义。

另请参阅first(),last(),chopped(),chop(),和truncate()。

[constexpr] QUtf8StringView QUtf8StringView::sliced(qsizetype pos, qsizetype n) const

返回一个包含从位置pos开始此字符串视图的n个代码点的字符串视图。

注意:当pos < 0,n < 0,或pos + n > size()时,行为未定义。

另请参阅first(),last(),chopped(),chop(),和truncate()。

QString QUtf8StringView::toString() const

返回此字符串视图数据的深层副本,作为一个QString

如果且仅当此字符串视图为空时,返回值将为空QString

[constexpr] void QUtf8StringView::truncate(qsizetype n)

将此字符串视图截断至n个代码点。

等同于*this = first(n)

注意: n 小于 0 或大于 size() 时,行为未定义。

另请参阅sliced(),first(),last(),chopped(),和chop()。

[noexcept] const char8_t *QUtf8StringView::utf8() const

返回指向字符串视图中第一个码点的 const 指针。

结果以 const char8_t* 的形式返回,因此此函数仅在 C++20 模式下编译时可用。

注意: 由返回值表示的字符数组不是 null 结尾的。

另请参阅begin()、end() 和 data()。

[noexcept, since 6.7] std::basic_string_view<QUtf8StringView::storage_type> QUtf8StringView::operator std::basic_string_view<QUtf8StringView::storage_type>() const

将此 QUtf8StringView 对象转换为 std::basic_string_view 对象。返回的视图具有与视图相同的数据指针和长度。返回视图的字符类型将为 storage_type

该函数自 Qt 6.7 起引入。

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

返回在字符串视图中位置 n 的代码点。

如果 n 为负数或大于等于 size(),行为未定义。

另请参阅at()、front() 和 back()。

© 2024 The Qt Company Ltd. 本文档中的贡献均为其各自所有者的版权。本文档依据自由软件基金会发布的 GNU 自由文档许可证第 1.3 版 的条款许可以许可。Qt 及其相关标志是 The Qt Company Ltd. 在芬兰和其他国家/地区的商标。所有其他商标均为其各自所有者的财产。