diff options
Diffstat (limited to 'src/corelib/text/qlatin1stringview.qdoc')
| -rw-r--r-- | src/corelib/text/qlatin1stringview.qdoc | 1295 |
1 files changed, 1295 insertions, 0 deletions
diff --git a/src/corelib/text/qlatin1stringview.qdoc b/src/corelib/text/qlatin1stringview.qdoc new file mode 100644 index 0000000000..711057767b --- /dev/null +++ b/src/corelib/text/qlatin1stringview.qdoc @@ -0,0 +1,1295 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2022 Intel Corporation. +// Copyright (C) 2019 Mail.ru Group. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! \class QLatin1StringView + \inmodule QtCore + \brief The QLatin1StringView class provides a thin wrapper around + a US-ASCII/Latin-1 encoded string literal. + + \ingroup string-processing + \reentrant + + \compares strong + \compareswith strong char16_t QChar QStringView QUtf8StringView QString \ + {const char16_t *} + \endcompareswith + \compareswith strong {const char *} QByteArray QByteArrayView + The byte array data is interpreted as utf-8. + \endcompareswith + + Many of QString's member functions are overloaded to accept + \c{const char *} instead of QString. This includes the copy + constructor, the assignment operator, the comparison operators, + and various other functions such as \l{QString::insert()}{insert()}, + \l{QString::append()}{append()}, and \l{QString::prepend()}{prepend()}. + Some of these functions are optimized to avoid constructing a + QString object for the \c{const char *} data. For example, + assuming \c str is a QString, + + \snippet code/src_corelib_text_qstring.cpp 3 + + is much faster than + + \snippet code/src_corelib_text_qstring.cpp 4 + + because it doesn't construct four temporary QString objects and + make a deep copy of the character data. + + However, that is not true for all QString member functions that take + \c{const char *} and therefore applications should assume a temporary will + be created, such as in + + \snippet code/src_corelib_text_qstring.cpp 4bis + + Applications that define \l QT_NO_CAST_FROM_ASCII (as explained + in the QString documentation) don't have access to QString's + \c{const char *} API. To provide an efficient way of specifying + constant Latin-1 strings, Qt provides the QLatin1StringView, which is + just a very thin wrapper around a \c{const char *}. Using + QLatin1StringView, the example code above becomes + + \snippet code/src_corelib_text_qstring.cpp 5 + + This is a bit longer to type, but it provides exactly the same + benefits as the first version of the code, and is faster than + converting the Latin-1 strings using QString::fromLatin1(). + + Thanks to the QString(QLatin1StringView) constructor, + QLatin1StringView can be used everywhere a QString is expected. For + example: + + \snippet code/src_corelib_text_qstring.cpp 6 + + \note If the function you're calling with a QLatin1StringView + argument isn't actually overloaded to take QLatin1StringView, the + implicit conversion to QString will trigger a memory allocation, + which is usually what you want to avoid by using QLatin1StringView + in the first place. In those cases, using QStringLiteral may be + the better option. + + \sa QString, QLatin1Char, {QStringLiteral()}{QStringLiteral}, + QT_NO_CAST_FROM_ASCII +*/ + +/*! + \class QLatin1String + \inmodule QtCore + \brief QLatin1String is the same as QLatin1StringView. + + QLatin1String is a view to a Latin-1 string. It's the same as + QLatin1StringView and is kept for compatibility reasons. It is + recommended to use QLatin1StringView instead. + + Please see the QLatin1StringView documentation for details. +*/ + +/*! + \typedef QLatin1StringView::value_type + \since 5.10 + + Alias for \c{const char}. Provided for compatibility with the STL. +*/ + +/*! + \typedef QLatin1StringView::difference_type + \since 5.10 + + Alias for \c{qsizetype}. Provided for compatibility with the STL. +*/ + +/*! + \typedef QLatin1StringView::size_type + \since 5.10 + + Alias for \c{qsizetype}. Provided for compatibility with the STL. + + \note In version prior to Qt 6, this was an alias for \c{int}, + restricting the amount of data that could be held in a QLatin1StringView + on 64-bit architectures. +*/ + +/*! + \typedef QLatin1StringView::pointer + \typedef QLatin1StringView::const_pointer + \since 6.7 + + Alias for \c{value_type *}. Provided for compatibility with the STL. +*/ + +/*! + \typedef QLatin1StringView::reference + \since 5.10 + + Alias for \c{value_type &}. Provided for compatibility with the STL. +*/ + +/*! + \typedef QLatin1StringView::const_reference + \since 5.11 + + Alias for \c{reference}. Provided for compatibility with the STL. +*/ + +/*! + \typedef QLatin1StringView::iterator + \since 5.10 + + QLatin1StringView does not support mutable iterators, so this is the same + as const_iterator. + + \sa const_iterator, reverse_iterator +*/ + +/*! + \typedef QLatin1StringView::const_iterator + \since 5.10 + + \sa iterator, const_reverse_iterator +*/ + +/*! + \typedef QLatin1StringView::reverse_iterator + \since 5.10 + + QLatin1StringView does not support mutable reverse iterators, so this is the + same as const_reverse_iterator. + + \sa const_reverse_iterator, iterator +*/ + +/*! + \typedef QLatin1StringView::const_reverse_iterator + \since 5.10 + + \sa reverse_iterator, const_iterator +*/ + +/*! \fn QLatin1StringView::QLatin1StringView() + \since 5.6 + + Constructs a QLatin1StringView object that stores a \nullptr. + + \sa data(), isEmpty(), isNull(), {Distinction Between Null and Empty Strings} +*/ + +/*! \fn QLatin1StringView::QLatin1StringView(std::nullptr_t) + \since 6.4 + + Constructs a QLatin1StringView object that stores a \nullptr. + + \sa data(), isEmpty(), isNull(), {Distinction Between Null and Empty Strings} +*/ + +/*! \fn QLatin1StringView::QLatin1StringView(const char *str) + + Constructs a QLatin1StringView object that stores \a str. + + The string data is \e not copied. The caller must be able to + guarantee that \a str will not be deleted or modified as long as + the QLatin1StringView object exists. + + \sa latin1() +*/ + +/*! \fn QLatin1StringView::QLatin1StringView(const char *str, qsizetype size) + + Constructs a QLatin1StringView object that stores \a str with \a size. + + The string data is \e not copied. The caller must be able to + guarantee that \a str will not be deleted or modified as long as + the QLatin1StringView object exists. + + \note: any null ('\\0') bytes in the byte array will be included in this + string, which will be converted to Unicode null characters (U+0000) if this + string is used by QString. This behavior is different from Qt 5.x. + + \sa latin1() +*/ + +/*! + \fn QLatin1StringView::QLatin1StringView(const char *first, const char *last) + \since 5.10 + + Constructs a QLatin1StringView object that stores \a first with length + (\a last - \a first). + + The range \c{[first,last)} must remain valid for the lifetime of + this Latin-1 string object. + + Passing \nullptr as \a first is safe if \a last is \nullptr, + too, and results in a null Latin-1 string. + + The behavior is undefined if \a last precedes \a first, \a first + is \nullptr and \a last is not, or if \c{last - first > + INT_MAX}. +*/ + +/*! \fn QLatin1StringView::QLatin1StringView(const QByteArray &str) + + Constructs a QLatin1StringView object as a view on \a str. + + The string data is \e not copied. The caller must be able to + guarantee that \a str will not be deleted or modified as long as + the QLatin1StringView object exists. + + \sa latin1() +*/ + +/*! \fn QLatin1StringView::QLatin1StringView(QByteArrayView str) + \since 6.3 + + Constructs a QLatin1StringView object as a view on \a str. + + The string data is \e not copied. The caller must be able to + guarantee that the data which \a str is pointing to will not + be deleted or modified as long as the QLatin1StringView object + exists. The size is obtained from \a str as-is, without checking + for a null-terminator. + + \note: any null ('\\0') bytes in the byte array will be included in this + string, which will be converted to Unicode null characters (U+0000) if this + string is used by QString. + + \sa latin1() +*/ + +/*! + \fn QString QLatin1StringView::toString() const + \since 6.0 + + Converts this Latin-1 string into a QString. Equivalent to + \code + return QString(*this); + \endcode +*/ + +/*! \fn const char *QLatin1StringView::latin1() const + + Returns the start of the Latin-1 string referenced by this object. +*/ + +/*! \fn const char *QLatin1StringView::data() const + + Returns the start of the Latin-1 string referenced by this object. +*/ + +/*! \fn const char *QLatin1StringView::constData() const + \since 6.4 + + Returns the start of the Latin-1 string referenced by this object. + + This function is provided for compatibility with other Qt containers. + + \sa data() +*/ + +/*! \fn qsizetype QLatin1StringView::size() const + + Returns the size of the Latin-1 string referenced by this object. + + \note In version prior to Qt 6, this function returned \c{int}, + restricting the amount of data that could be held in a QLatin1StringView + on 64-bit architectures. +*/ + +/*! \fn qsizetype QLatin1StringView::length() const + \since 6.4 + + Same as size(). + + This function is provided for compatibility with other Qt containers. +*/ + +/*! \fn bool QLatin1StringView::isNull() const + \since 5.10 + + Returns whether the Latin-1 string referenced by this object is null + (\c{data() == nullptr}) or not. + + \sa isEmpty(), data() +*/ + +/*! \fn bool QLatin1StringView::isEmpty() const + \since 5.10 + + Returns whether the Latin-1 string referenced by this object is empty + (\c{size() == 0}) or not. + + \sa isNull(), size() +*/ + +/*! \fn bool QLatin1StringView::empty() const + \since 6.4 + + Returns whether the Latin-1 string referenced by this object is empty + (\c{size() == 0}) or not. + + This function is provided for STL compatibility. + + \sa isEmpty(), isNull(), size() +*/ + +/*! \fn QLatin1Char QLatin1StringView::at(qsizetype pos) const + \since 5.8 + + Returns the character at position \a pos in this object. + + \note This function performs no error checking. + The behavior is undefined when \a pos < 0 or \a pos >= size(). + + \sa operator[]() +*/ + +/*! \fn QLatin1Char QLatin1StringView::operator[](qsizetype pos) const + \since 5.8 + + Returns the character at position \a pos in this object. + + \note This function performs no error checking. + The behavior is undefined when \a pos < 0 or \a pos >= size(). + + \sa at() +*/ + +/*! + \fn QLatin1Char QLatin1StringView::front() const + \since 5.10 + + Returns the first character in the string. + Same as \c{at(0)}. + + This function is provided for STL compatibility. + + \warning Calling this function on an empty string constitutes + undefined behavior. + + \sa back(), at(), operator[]() +*/ + +/*! + \fn QLatin1Char QLatin1StringView::first() const + \since 6.4 + + Returns the first character in the string. + Same as \c{at(0)} or front(). + + This function is provided for compatibility with other Qt containers. + + \warning Calling this function on an empty string constitutes + undefined behavior. + + \sa last(), front(), back() +*/ + +/*! + \fn QLatin1Char QLatin1StringView::back() const + \since 5.10 + + Returns the last character in the string. + Same as \c{at(size() - 1)}. + + This function is provided for STL compatibility. + + \warning Calling this function on an empty string constitutes + undefined behavior. + + \sa front(), at(), operator[]() +*/ + +/*! + \fn QLatin1Char QLatin1StringView::last() const + \since 6.4 + + Returns the last character in the string. + Same as \c{at(size() - 1)} or back(). + + This function is provided for compatibility with other Qt containers. + + \warning Calling this function on an empty string constitutes + undefined behavior. + + \sa first(), back(), front() +*/ + +/*! + \fn int QLatin1StringView::compare(QStringView str, Qt::CaseSensitivity cs) const + \fn int QLatin1StringView::compare(QLatin1StringView l1, Qt::CaseSensitivity cs) const + \fn int QLatin1StringView::compare(QChar ch) const + \fn int QLatin1StringView::compare(QChar ch, Qt::CaseSensitivity cs) const + \since 5.14 + + Compares this string view with UTF-16 string view \a str, Latin-1 string view \a l1, + or the character \a ch, respectively. Returns a negative integer if this + string is less than \a str, \a l1 or \a ch, returns a positive integer if it + is greater than \a str, \a l1 or \a ch, and zero if they are equal. + + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} + + \sa operator==(), operator<(), operator>() +*/ + +/*! + \fn int QLatin1StringView::compare(QUtf8StringView str, Qt::CaseSensitivity cs) const + \since 6.5 + + Compares this string view with \a str and returns a negative integer if + this string view is less than \a str, a positive integer if it is greater than + \a str, and zero if they are equal. + + \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison} + + \sa operator==(), operator<(), operator>() +*/ + + +/*! + \fn bool QLatin1StringView::startsWith(QStringView str, Qt::CaseSensitivity cs) const + \since 5.10 + \fn bool QLatin1StringView::startsWith(QLatin1StringView l1, Qt::CaseSensitivity cs) const + \since 5.10 + \fn bool QLatin1StringView::startsWith(QChar ch) const + \since 5.10 + \fn bool QLatin1StringView::startsWith(QChar ch, Qt::CaseSensitivity cs) const + \since 5.10 + + Returns \c true if this Latin-1 string view starts with the UTF-16 + string viewed by \a str, the Latin-1 string viewed by \a l1, or the + character \a ch, respectively; otherwise returns \c false. + + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} + + \sa endsWith() +*/ + +/*! + \fn bool QLatin1StringView::endsWith(QStringView str, Qt::CaseSensitivity cs) const + \since 5.10 + \fn bool QLatin1StringView::endsWith(QLatin1StringView l1, Qt::CaseSensitivity cs) const + \since 5.10 + \fn bool QLatin1StringView::endsWith(QChar ch) const + \since 5.10 + \fn bool QLatin1StringView::endsWith(QChar ch, Qt::CaseSensitivity cs) const + \since 5.10 + + Returns \c true if this Latin-1 string view ends with the UTF-16 string + viewed \a str, the Latin-1 string viewed by \a l1, or the character \a ch, + respectively; otherwise returns \c false. + + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} + + \sa startsWith() +*/ + +/*! + \fn qsizetype QLatin1StringView::indexOf(QStringView str, qsizetype from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const + \fn qsizetype QLatin1StringView::indexOf(QLatin1StringView l1, qsizetype from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const + \fn qsizetype QLatin1StringView::indexOf(QChar c, qsizetype from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const + \since 5.14 + + Returns the index position in this Latin-1 string view of the first + occurrence of the UTF-16 string viewed by \a str, the Latin-1 string + viewed by \a l1, or the character \a ch, respectively, searching forward + from index position \a from. Returns -1 if \a str, \a l1 or \a c is not + found, respectively. + + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} + + \include qstring.qdocinc negative-index-start-search-from-end + + \sa QString::indexOf() +*/ + +/*! + \fn bool QLatin1StringView::contains(QStringView str, Qt::CaseSensitivity cs) const + \fn bool QLatin1StringView::contains(QLatin1StringView l1, Qt::CaseSensitivity cs) const + \fn bool QLatin1StringView::contains(QChar c, Qt::CaseSensitivity cs) const + \since 5.14 + + Returns \c true if this Latin-1 string view contains an occurrence of the + UTF-16 string viewed by \a str, the Latin-1 string viewed by \a l1, or the + character \a ch, respectively; otherwise returns \c false. + + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} + + \sa indexOf(), QStringView::contains(), QStringView::indexOf(), + QString::indexOf() +*/ + +/*! + \fn qsizetype QLatin1StringView::lastIndexOf(QStringView str, qsizetype from, Qt::CaseSensitivity cs) const + \fn qsizetype QLatin1StringView::lastIndexOf(QLatin1StringView l1, qsizetype from, Qt::CaseSensitivity cs) const + \fn qsizetype QLatin1StringView::lastIndexOf(QChar c, qsizetype from, Qt::CaseSensitivity cs) const + \since 5.14 + + Returns the index position in this Latin-1 string view of the last + occurrence of the UTF-16 string viewed by \a str, the Latin-1 string + viewed by \a l1, or the character \a ch, respectively, searching backward + from index position \a from; returns -1 if \a str, \a l1 or \a ch is not + found, respectively. + + \include qstring.qdocinc negative-index-start-search-from-end + + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} + + \note When searching for a 0-length \a str or \a l1, the match at + the end of the data is excluded from the search by a negative \a + from, even though \c{-1} is normally thought of as searching from + the end of the string: the match at the end is \e after the last + character, so it is excluded. To include such a final empty match, + either give a positive value for \a from or omit the \a from + parameter entirely. + + \sa indexOf(), QStringView::lastIndexOf(), QStringView::indexOf(), + QString::indexOf() +*/ + +/*! + \fn qsizetype QLatin1StringView::lastIndexOf(QStringView str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const + \fn qsizetype QLatin1StringView::lastIndexOf(QLatin1StringView l1, Qt::CaseSensitivity cs = Qt::CaseSensitive) const + \since 6.2 + \overload lastIndexOf() + + Returns the index position in this Latin-1 string view of the last + occurrence of the UTF-16 string viewed by \a str or the Latin-1 string + viewed by \a l1, respectively. Returns -1 if \a str or \a l1 is not found, + respectively. + + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} +*/ + +/*! + \fn qsizetype QLatin1StringView::lastIndexOf(QChar ch, Qt::CaseSensitivity cs) const + \since 6.3 + \overload +*/ + +/*! + \fn qsizetype QLatin1StringView::count(QStringView str, Qt::CaseSensitivity cs) const + \fn qsizetype QLatin1StringView::count(QLatin1StringView l1, Qt::CaseSensitivity cs) const + \fn qsizetype QLatin1StringView::count(QChar ch, Qt::CaseSensitivity cs) const + \since 6.4 + + Returns the number of (potentially overlapping) occurrences of the + UTF-16 string viewed by \a str, the Latin-1 string viewed by \a l1, + or the character \a ch, respectively, in this string view. + + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} + + \sa contains(), indexOf() +*/ + +/*! + \fn QLatin1StringView::const_iterator QLatin1StringView::begin() const + \since 5.10 + + Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the + first character in the string. + + This function is provided for STL compatibility. + + \sa end(), cbegin(), rbegin(), data() +*/ + +/*! + \fn QLatin1StringView::const_iterator QLatin1StringView::cbegin() const + \since 5.10 + + Same as begin(). + + This function is provided for STL compatibility. + + \sa cend(), begin(), crbegin(), data() +*/ + +/*! + \fn QLatin1StringView::const_iterator QLatin1StringView::constBegin() const + \since 6.4 + + Same as begin(). + + This function is provided for compatibility with other Qt containers. + + \sa constEnd(), begin(), cbegin(), data() +*/ + +/*! + \fn QLatin1StringView::const_iterator QLatin1StringView::end() const + \since 5.10 + + Returns a const \l{STL-style iterators}{STL-style iterator} pointing just + after the last character in the string. + + This function is provided for STL compatibility. + + \sa begin(), cend(), rend() +*/ + +/*! \fn QLatin1StringView::const_iterator QLatin1StringView::cend() const + \since 5.10 + + Same as end(). + + This function is provided for STL compatibility. + + \sa cbegin(), end(), crend() +*/ + +/*! \fn QLatin1StringView::const_iterator QLatin1StringView::constEnd() const + \since 6.4 + + Same as end(). + + This function is provided for compatibility with other Qt containers. + + \sa constBegin(), end(), cend(), crend() +*/ + +/*! + \fn QLatin1StringView::const_reverse_iterator QLatin1StringView::rbegin() const + \since 5.10 + + Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing + to the first character in the string, in reverse order. + + This function is provided for STL compatibility. + + \sa rend(), crbegin(), begin() +*/ + +/*! + \fn QLatin1StringView::const_reverse_iterator QLatin1StringView::crbegin() const + \since 5.10 + + Same as rbegin(). + + This function is provided for STL compatibility. + + \sa crend(), rbegin(), cbegin() +*/ + +/*! + \fn QLatin1StringView::const_reverse_iterator QLatin1StringView::rend() const + \since 5.10 + + Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing just + after the last character in the string, in reverse order. + + This function is provided for STL compatibility. + + \sa rbegin(), crend(), end() +*/ + +/*! + \fn QLatin1StringView::const_reverse_iterator QLatin1StringView::crend() const + \since 5.10 + + Same as rend(). + + This function is provided for STL compatibility. + + \sa crbegin(), rend(), cend() +*/ + +/*! + \fn QLatin1StringView QLatin1StringView::mid(qsizetype start, qsizetype length) const + \since 5.8 + + Returns the substring of length \a length starting at position + \a start in this Latin-1 string view. + + If you know that \a start and \a length cannot be out of bounds, use + sliced() instead in new code, because it is faster. + + Returns an empty Latin-1 string view if \a start exceeds the length + of this string view. If there are less than \a length characters available + in this string view starting at \a start, or if \a length is negative + (default), the function returns all characters that are available from + \a start. + + \sa first(), last(), sliced(), chopped(), chop(), truncate() +*/ + +/*! + \fn QLatin1StringView QLatin1StringView::left(qsizetype length) const + \since 5.8 + + If you know that \a length cannot be out of bounds, use first() instead in + new code, because it is faster. + + Returns the substring of length \a length starting at position + 0 in this Latin-1 string view. + + The entire Latin-1 string view is returned if \a length is greater + than or equal to size(), or less than zero. + + \sa first(), last(), sliced(), startsWith(), chopped(), chop(), truncate() +*/ + +/*! + \fn QLatin1StringView QLatin1StringView::right(qsizetype length) const + \since 5.8 + + If you know that \a length cannot be out of bounds, use last() instead in + new code, because it is faster. + + Returns the substring of length \a length starting at position + size() - \a length in this Latin-1 string view. + + The entire Latin-1 string view is returned if \a length is greater + than or equal to size(), or less than zero. + + \sa first(), last(), sliced(), endsWith(), chopped(), chop(), truncate() +*/ + +/*! + \fn QLatin1StringView QLatin1StringView::first(qsizetype n) const + \since 6.0 + + Returns a Latin-1 string view that contains the first \a n characters + of this string view. + + \note The behavior is undefined when \a n < 0 or \a n > size(). + + \sa last(), startsWith(), chopped(), chop(), truncate() +*/ + +/*! + \fn QLatin1StringView QLatin1StringView::last(qsizetype n) const + \since 6.0 + + Returns a Latin-1 string view that contains the last \a n characters + of this string view. + + \note The behavior is undefined when \a n < 0 or \a n > size(). + + \sa first(), endsWith(), chopped(), chop(), truncate() +*/ + +/*! + \fn QLatin1StringView QLatin1StringView::sliced(qsizetype pos, qsizetype n) const + \since 6.0 + + Returns a Latin-1 string view that points to \a n characters of this + string view, starting at position \a pos. + +//! [UB-sliced-index-length] + \note The behavior is undefined when \a pos < 0, \a n < 0, + or \c{pos + n > size()}. +//! [UB-sliced-index-length] + + \sa first(), last(), chopped(), chop(), truncate() +*/ + +/*! + \fn QLatin1StringView QLatin1StringView::sliced(qsizetype pos) const + \since 6.0 + + Returns a Latin-1 string view starting at position \a pos in this + string view, and extending to its end. + +//! [UB-sliced-index-only] + \note The behavior is undefined when \a pos < 0 or \a pos > size(). +//! [UB-sliced-index-only] + + \sa first(), last(), chopped(), chop(), truncate() +*/ + +/*! + \fn QLatin1StringView QLatin1StringView::chopped(qsizetype length) const + \since 5.10 + + Returns the substring of length size() - \a length starting at the + beginning of this object. + + Same as \c{left(size() - length)}. + + \note The behavior is undefined when \a length < 0 or \a length > size(). + + \sa sliced(), first(), last(), chop(), truncate() +*/ + +/*! + \fn void QLatin1StringView::truncate(qsizetype length) + \since 5.10 + + Truncates this string to length \a length. + + Same as \c{*this = left(length)}. + + \note The behavior is undefined when \a length < 0 or \a length > size(). + + \sa sliced(), first(), last(), chopped(), chop() +*/ + +/*! + \fn void QLatin1StringView::chop(qsizetype length) + \since 5.10 + + Truncates this string by \a length characters. + + Same as \c{*this = left(size() - length)}. + + \note The behavior is undefined when \a length < 0 or \a length > size(). + + \sa sliced(), first(), last(), chopped(), truncate() +*/ + +/*! + \fn QLatin1StringView QLatin1StringView::trimmed() const + \since 5.10 + + Strips leading and trailing whitespace and returns the result. + + Whitespace means any character for which QChar::isSpace() returns + \c true. This includes the ASCII characters '\\t', '\\n', '\\v', + '\\f', '\\r', and ' '. +*/ + +/*! + \fn bool QLatin1StringView::operator==(const QLatin1StringView &lhs, const char * const &rhs) + \since 4.3 + + Returns \c true if the string \a lhs is equal to const char pointer \a rhs; + otherwise returns \c false. + + The \a rhs const char pointer is converted to a QUtf8StringView. + + You can disable this operator by defining + \l QT_NO_CAST_FROM_ASCII when you compile your applications. This + can be useful if you want to ensure that all user-visible strings + go through QObject::tr(), for example. + + \sa {Comparing Strings} +*/ + +/*! + \fn bool QLatin1StringView::operator==(const QLatin1StringView &lhs, const QByteArray &rhs) + \since 5.0 + \overload + + The \a rhs byte array is converted to a QUtf8StringView. + + You can disable this operator by defining + \l QT_NO_CAST_FROM_ASCII when you compile your applications. This + can be useful if you want to ensure that all user-visible strings + go through QObject::tr(), for example. +*/ + +/*! + \fn bool QLatin1StringView::operator!=(const QLatin1StringView &lhs, const char * const &rhs) + \since 4.3 + + Returns \c true if the string \a lhs is not equal to const char pointer \a rhs; + otherwise returns \c false. + + The \a rhs const char pointer is converted to a QUtf8StringView. + + You can disable this operator by defining + \l QT_NO_CAST_FROM_ASCII when you compile your applications. This + can be useful if you want to ensure that all user-visible strings + go through QObject::tr(), for example. + + \sa {Comparing Strings} +*/ + +/*! + \fn bool QLatin1StringView::operator!=(const QLatin1StringView &lhs, const QByteArray &rhs) + \since 5.0 + \overload operator!=() + + The \a rhs byte array is converted to a QUtf8StringView. + + You can disable this operator by defining + \l QT_NO_CAST_FROM_ASCII when you compile your applications. This + can be useful if you want to ensure that all user-visible strings + go through QObject::tr(), for example. +*/ + +/*! + \fn bool QLatin1StringView::operator>(const QLatin1StringView &lhs, const char * const &rhs) + \since 4.3 + + Returns \c true if the string \a lhs is lexically greater than const char pointer + \a rhs; otherwise returns \c false. + + The \a rhs const char pointer is converted to a QUtf8StringView. + + You can disable this operator by defining \l QT_NO_CAST_FROM_ASCII + when you compile your applications. This can be useful if you want + to ensure that all user-visible strings go through QObject::tr(), + for example. + + \sa {Comparing Strings} +*/ + +/*! + \fn bool QLatin1StringView::operator>(const QLatin1StringView &lhs, const QByteArray &rhs) + \since 5.0 + \overload + + The \a rhs byte array is converted to a QUtf8StringView. + + You can disable this operator by defining \l QT_NO_CAST_FROM_ASCII + when you compile your applications. This can be useful if you want + to ensure that all user-visible strings go through QObject::tr(), + for example. +*/ + +/*! + \fn bool QLatin1StringView::operator<(const QLatin1StringView &lhs, const char * const &rhs) + \since 4.3 + + Returns \c true if the string \a lhs is lexically less than const char pointer + \a rhs; otherwise returns \c false. + + The \a rhs const char pointer is converted to a QUtf8StringView. + + You can disable this operator by defining + \l QT_NO_CAST_FROM_ASCII when you compile your applications. This + can be useful if you want to ensure that all user-visible strings + go through QObject::tr(), for example. + + \sa {Comparing Strings} +*/ + +/*! + \fn bool QLatin1StringView::operator<(const QLatin1StringView &lhs, const QByteArray &rhs) + \since 5.0 + \overload + + The \a rhs byte array is converted to a QUtf8StringView. + + You can disable this operator by defining + \l QT_NO_CAST_FROM_ASCII when you compile your applications. This + can be useful if you want to ensure that all user-visible strings + go through QObject::tr(), for example. +*/ + +/*! + \fn bool QLatin1StringView::operator>=(const QLatin1StringView &lhs, const char * const &rhs) + \since 4.3 + + Returns \c true if the string \a lhs is lexically greater than or equal to + const char pointer \a rhs; otherwise returns \c false. + + The \a rhs const char pointer is converted to a QUtf8StringView. + + You can disable this operator by defining + \l QT_NO_CAST_FROM_ASCII when you compile your applications. This + can be useful if you want to ensure that all user-visible strings + go through QObject::tr(), for example. + + \sa {Comparing Strings} +*/ + +/*! + \fn bool QLatin1StringView::operator>=(const QLatin1StringView &lhs, const QByteArray &rhs) + \since 5.0 + \overload + + The \a rhs byte array is converted to a QUtf8StringView. + + You can disable this operator by defining + \l QT_NO_CAST_FROM_ASCII when you compile your applications. This + can be useful if you want to ensure that all user-visible strings + go through QObject::tr(), for example. +*/ + +/*! + \fn bool QLatin1StringView::operator<=(const QLatin1StringView &lhs, const char * const &rhs) + \since 4.3 + + Returns \c true if the string \a lhs is lexically less than or equal to + const char pointer \a rhs; otherwise returns \c false. + + The \a rhs const char pointer is converted to a QUtf8StringView. + + You can disable this operator by defining + \l QT_NO_CAST_FROM_ASCII when you compile your applications. This + can be useful if you want to ensure that all user-visible strings + go through QObject::tr(), for example. + + \sa {Comparing Strings} +*/ + +/*! + \fn bool QLatin1StringView::operator<=(const QLatin1StringView &lhs, const QByteArray &rhs) + \since 5.0 + \overload + + The \a rhs byte array is converted to a QUtf8StringView. + + You can disable this operator by defining + \l QT_NO_CAST_FROM_ASCII when you compile your applications. This + can be useful if you want to ensure that all user-visible strings + go through QObject::tr(), for example. +*/ + +/*! \fn bool QLatin1StringView::operator==(const QLatin1StringView &lhs, const QLatin1StringView &rhs) + + Returns \c true if string \a lhs is lexically equal to string \a rhs; + otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator!=(const QLatin1StringView &lhs, const QLatin1StringView &rhs) + + Returns \c true if string \a lhs is lexically not equal to string \a rhs; + otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator<(const QLatin1StringView &lhs, const QLatin1StringView &rhs) + + Returns \c true if string \a lhs is lexically less than string \a rhs; + otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator<=(const QLatin1StringView &lhs, const QLatin1StringView &rhs) + + Returns \c true if string \a lhs is lexically less than or equal to + string \a rhs; otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator>(const QLatin1StringView &lhs, const QLatin1StringView &rhs) + + Returns \c true if string \a lhs is lexically greater than string \a rhs; + otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator>=(const QLatin1StringView &lhs, const QLatin1StringView &rhs) + + Returns \c true if string \a lhs is lexically greater than or equal + to string \a rhs; otherwise returns \c false. +*/ + +/*! \fn bool QLatin1StringView::operator==(const QChar &lhs, const QLatin1StringView &rhs) + + Returns \c true if char \a lhs is lexically equal to string \a rhs; + otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator<(const QChar &lhs, const QLatin1StringView &rhs) + + Returns \c true if char \a lhs is lexically less than string \a rhs; + otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator>(const QChar &lhs, const QLatin1StringView &rhs) + Returns \c true if char \a lhs is lexically greater than string \a rhs; + otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator!=(const QChar &lhs, const QLatin1StringView &rhs) + + Returns \c true if char \a lhs is lexically not equal to string \a rhs; + otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator<=(const QChar &lhs, const QLatin1StringView &rhs) + + Returns \c true if char \a lhs is lexically less than or equal to + string \a rhs; otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator>=(const QChar &lhs, const QLatin1StringView &rhs) + + Returns \c true if char \a lhs is lexically greater than or equal to + string \a rhs; otherwise returns \c false. +*/ + +/*! \fn bool QLatin1StringView::operator==(const QLatin1StringView &lhs, const QChar &rhs) + + Returns \c true if string \a lhs is lexically equal to char \a rhs; + otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator<(const QLatin1StringView &lhs, const QChar &rhs) + + Returns \c true if string \a lhs is lexically less than char \a rhs; + otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator>(const QLatin1StringView &lhs, const QChar &rhs) + + Returns \c true if string \a lhs is lexically greater than char \a rhs; + otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator!=(const QLatin1StringView &lhs, const QChar &rhs) + + Returns \c true if string \a lhs is lexically not equal to char \a rhs; + otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator<=(const QLatin1StringView &lhs, const QChar &rhs) + + Returns \c true if string \a lhs is lexically less than or equal to + char \a rhs; otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator>=(const QLatin1StringView &lhs, const QChar &rhs) + + Returns \c true if string \a lhs is lexically greater than or equal to + char \a rhs; otherwise returns \c false. +*/ + +/*! \fn bool QLatin1StringView::operator==(const QStringView &lhs, const QLatin1StringView &rhs) + + Returns \c true if string view \a lhs is lexically equal to string \a rhs; + otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator<(const QStringView &lhs, const QLatin1StringView &rhs) + + Returns \c true if string view \a lhs is lexically less than string \a rhs; + otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator>(const QStringView &lhs, const QLatin1StringView &rhs) + + Returns \c true if string view \a lhs is lexically greater than string \a rhs; + otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator!=(const QStringView &lhs, const QLatin1StringView &rhs) + + Returns \c true if string view \a lhs is lexically not equal to string \a rhs; + otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator<=(const QStringView &lhs, const QLatin1StringView &rhs) + + Returns \c true if string view \a lhs is lexically less than or equal to + string \a rhs; otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator>=(const QStringView &lhs, const QLatin1StringView &rhs) + + Returns \c true if string view \a lhs is lexically greater than or equal to + string \a rhs; otherwise returns \c false. +*/ + +/*! \fn bool QLatin1StringView::operator==(const QLatin1StringView &lhs, const QStringView &rhs) + + Returns \c true if string \a lhs is lexically equal to string view \a rhs; + otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator<(const QLatin1StringView &lhs, const QStringView &rhs) + + Returns \c true if string \a lhs is lexically less than string view \a rhs; + otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator>(const QLatin1StringView &lhs, const QStringView &rhs) + + Returns \c true if string \a lhs is lexically greater than string view \a rhs; + otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator!=(const QLatin1StringView &lhs, const QStringView &rhs) + + Returns \c true if string \a lhs is lexically not equal to string view \a rhs; + otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator<=(const QLatin1StringView &lhs, const QStringView &rhs) + + Returns \c true if string \a lhs is lexically less than or equal to + string view \a rhs; otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator>=(const QLatin1StringView &lhs, const QStringView &rhs) + + Returns \c true if string \a lhs is lexically greater than or equal to + string view \a rhs; otherwise returns \c false. +*/ + +/*! \fn bool QLatin1StringView::operator==(const char * const &lhs, const QLatin1StringView &rhs) + + Returns \c true if const char pointer \a lhs is lexically equal to + string \a rhs; otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator<(const char * const &lhs, const QLatin1StringView &rhs) + + Returns \c true if const char pointer \a lhs is lexically less than + string \a rhs; otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator>(const char * const &lhs, const QLatin1StringView &rhs) + + Returns \c true if const char pointer \a lhs is lexically greater than + string \a rhs; otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator!=(const char * const &lhs, const QLatin1StringView &rhs) + + Returns \c true if const char pointer \a lhs is lexically not equal to + string \a rhs; otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator<=(const char * const &lhs, const QLatin1StringView &rhs) + + Returns \c true if const char pointer \a lhs is lexically less than or + equal to string \a rhs; otherwise returns \c false. +*/ +/*! \fn bool QLatin1StringView::operator>=(const char * const &lhs, const QLatin1StringView &rhs) + + Returns \c true if const char pointer \a lhs is lexically greater than or + equal to string \a rhs; otherwise returns \c false. +*/ + +/*! + \fn qlonglong QLatin1StringView::toLongLong(bool *ok, int base) const + \fn qulonglong QLatin1StringView::toULongLong(bool *ok, int base) const + \fn int QLatin1StringView::toInt(bool *ok, int base) const + \fn uint QLatin1StringView::toUInt(bool *ok, int base) const + \fn long QLatin1StringView::toLong(bool *ok, int base) const + \fn ulong QLatin1StringView::toULong(bool *ok, int base) const + \fn short QLatin1StringView::toShort(bool *ok, int base) const + \fn ushort QLatin1StringView::toUShort(bool *ok, int base) const + + \since 6.4 + + Returns this QLatin1StringView converted to a corresponding numeric value using + base \a base, which is ten by default. Bases 0 and 2 through 36 are supported, + using letters for digits beyond 9; A is ten, B is eleven and so on. + + If \a base is 0, the base is determined automatically using the following + rules (in this order), if the Latin-1 string view begins with: + + \list + \li \c "0x", the rest of it is read as hexadecimal (base 16) + \li \c "0b", the rest of it is read as binary (base 2) + \li \c "0", the rest of it is read as octal (base 8) + \li otherwise it is read as decimal + \endlist + + Returns 0 if the conversion fails. + + If \a ok is not \nullptr, failure is reported by setting *\a{ok} + to \c false, and success by setting *\a{ok} to \c true. + +//! [latin1-numeric-conversion-note] + \note The conversion of the number is performed in the default C locale, + regardless of the user's locale. Use QLocale to perform locale-aware + conversions between numbers and strings. + + This function ignores leading and trailing spacing characters. +//! [latin1-numeric-conversion-note] + + \note Support for the "0b" prefix was added in Qt 6.4. +*/ + +/*! + \fn double QLatin1StringView::toDouble(bool *ok) const + \fn float QLatin1StringView::toFloat(bool *ok) const + \since 6.4 + + Returns this QLatin1StringView converted to a corresponding floating-point value. + + Returns an infinity if the conversion overflows or 0.0 if the + conversion fails for other reasons (e.g. underflow). + + If \a ok is not \nullptr, failure is reported by setting *\a{ok} + to \c false, and success by setting *\a{ok} to \c true. + + \warning The QLatin1StringView content may only contain valid numerical + characters which includes the plus/minus sign, the character e used in + scientific notation, and the decimal point. Including the unit or additional + characters leads to a conversion error. + + \include qlatin1stringview.qdoc latin1-numeric-conversion-note +*/ + +/*! + \fn Qt::Literals::StringLiterals::operator""_L1(const char *str, size_t size) + + \relates QLatin1StringView + \since 6.4 + + Literal operator that creates a QLatin1StringView out of the first \a size + characters in the char string literal \a str. + + The following code creates a QLatin1StringView: + \code + using namespace Qt::Literals::StringLiterals; + + auto str = "hello"_L1; + \endcode + + \sa Qt::Literals::StringLiterals +*/ |