diff options
Diffstat (limited to 'src/corelib/text/qanystringview.qdoc')
| -rw-r--r-- | src/corelib/text/qanystringview.qdoc | 397 |
1 files changed, 0 insertions, 397 deletions
diff --git a/src/corelib/text/qanystringview.qdoc b/src/corelib/text/qanystringview.qdoc deleted file mode 100644 index ec4f1c5a42..0000000000 --- a/src/corelib/text/qanystringview.qdoc +++ /dev/null @@ -1,397 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2020 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Marc Mutz <marc.mutz@kdab.com> -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QAnyStringView - \inmodule QtCore - \since 6.0 - \brief The QAnyStringView class provides a unified view on Latin-1, UTF-8, - or UTF-16 strings with a read-only subset of the QString API. - \reentrant - \ingroup tools - \ingroup string-processing - - A QAnyStringView references a contiguous portion of a string it does - not own. It acts as an interface type to all kinds of strings, - without the need to construct a QString first. - - Unlike QStringView and QUtf8StringView, QAnyStringView can hold - strings of any of the following encodings: UTF-8, UTF-16, and - Latin-1. The latter is supported to keep old source working - efficiently. It is expected that by Qt 7, the Latin-1 support will - be removed. - - The string may be represented as an array (or an array-compatible - data-structure such as QString, std::basic_string, etc.) of \c - char, \c char8_t, QChar, \c ushort, \c char16_t or (on platforms, - such as Windows, where it is a 16-bit type) \c wchar_t. - - QAnyStringView is designed as an interface type; its main use-case - is as a function parameter type. When QAnyStringViews are used as - automatic variables or data members, care must be taken to ensure - that the referenced string data (for example, owned by a QString) - outlives the QAnyStringView on all code paths, lest the string - view ends up referencing deleted data. - - When used as an interface type, QAnyStringView allows a single - function to accept a wide variety of string data sources. One - function accepting QAnyStringView thus replaces five function - overloads (taking QString, \c{(const QChar*, int)}, - QUtf8StringView, QLatin1String (but see above), and QChar), while - at the same time enabling even more string data sources to be - passed to the function, such as \c{u8"Hello World"}, a \c char8_t - string literal. - - Like elsewhere in Qt, QAnyStringView assumes \c char data is encoded - in UTF-8, unless it is presented as a QLatin1String. - - QAnyStringViews should be passed by value, not by reference-to-const: - \snippet code/src_corelib_text_qanystringview.cpp 0 - - QAnyStringView can also be used as the return value of a function, - but this is not recommended. QUtf8StringView or QStringView are - better suited as function return values. If you call a function - returning QAnyStringView, take extra care to not keep the - QAnyStringView around longer than the function promises to keep - the referenced string data alive. If in doubt, obtain a strong - reference to the data by calling toString() to convert the - QAnyStringView into a QString. - - QAnyStringView is a \e{Literal Type}. - - \section2 Compatible Character Types - - QAnyStringView accepts strings over a variety of character types: - - \list - \li \c char (both signed and unsigned) - \li \c char8_t (C++20 only) - \li \c char16_t - \li \c wchar_t (where it's a 16-bit type, e.g. Windows) - \li \c ushort - \li \c QChar - \endlist - - The 8-bit character types are interpreted as UTF-8 data (except when - presented as a QLatin1String) while the 16-bit character types are - interpreted as UTF-16 data in host byte order (the same as QString). - - \section2 Sizes and Sub-Strings - - All sizes and positions in QAnyStringView functions are in the - encoding's code points (that is, UTF-16 surrogate pairs count as - two for the purposes of these functions, the same as in QString, - and UTF-8 multibyte sequences count as two, three or four, - depending on their length). - - \sa QUtf8StringView, QStringView -*/ - -/*! - \typedef QAnyStringView::difference_type - - Alias for \c{std::ptrdiff_t}. Provided for compatibility with the STL. -*/ - -/*! - \typedef QAnyStringView::size_type - - Alias for qsizetype. Provided for compatibility with the STL. -*/ - -/*! - \fn QAnyStringView::QAnyStringView() - - Constructs a null string view. - - \sa isNull() -*/ - -/*! - \fn QAnyStringView::QAnyStringView(std::nullptr_t) - - Constructs a null string view. - - \sa isNull() -*/ - -/*! - \fn template <typename Char> QAnyStringView::QAnyStringView(const Char *str, qsizetype len) - - Constructs a string view on \a str with length \a len. - - The range \c{[str,len)} must remain valid for the lifetime of this string view object. - - Passing \nullptr as \a str is safe if \a len is 0, too, and results in a null string view. - - The behavior is undefined if \a len is negative or, when positive, if \a str is \nullptr. - - This constructor only participates in overload resolution if \c Char is a compatible - character type. - - \sa isNull(), {Compatible Character Types} -*/ - -/*! - \fn template <typename Char> QAnyStringView::QAnyStringView(const Char *first, const Char *last) - - Constructs a string view on \a first with length (\a last - \a first). - - The range \c{[first,last)} must remain valid for the lifetime of - this string view object. - - Passing \nullptr as \a first is safe if \a last is \nullptr, too, - and results in a null string view. - - The behavior is undefined if \a last precedes \a first, or \a first - is \nullptr and \a last is not. - - This constructor only participates in overload resolution if \c Char - is a compatible character type. - - \sa isNull(), {Compatible Character Types} -*/ - -/*! - \fn template <typename Char> QAnyStringView::QAnyStringView(const Char *str) - - Constructs a string view on \a str. The length is determined - by scanning for the first \c{Char(0)}. - - \a str must remain valid for the lifetime of this string view object. - - Passing \nullptr as \a str is safe and results in a null string view. - - This constructor only participates in overload resolution if \a - str is not an array and if \c Char is a compatible character - type. - - \sa isNull(), {Compatible Character Types} -*/ - -/*! - \fn template <typename Char, size_t N> QAnyStringView::QAnyStringView(const Char (&string)[N]) - - Constructs a string view on the character string literal \a string. - The view covers the array until the first \c{Char(0)} is encountered, - or \c N, whichever comes first. - If you need the full array, use fromArray() instead. - - \a string must remain valid for the lifetime of this string view - object. - - This constructor only participates in overload resolution if \a - string is an actual array and \c Char is a compatible character - type. - - \sa {Compatible Character Types} -*/ - -/*! - \fn QAnyStringView::QAnyStringView(const QString &str) - - Constructs a string view on \a str. - - \c{str.data()} must remain valid for the lifetime of this string view object. - - The string view will be null if and only if \c{str.isNull()}. -*/ - -/*! - \fn QAnyStringView::QAnyStringView(const QByteArray &str) - - Constructs a string view on \a str. The data in \a str is interpreted as UTF-8. - - \c{str.data()} must remain valid for the lifetime of this string view object. - - The string view will be null if and only if \c{str.isNull()}. -*/ - -/*! - \fn template <typename Char, size_t Size> static QAnyStringView fromArray(const Char (&string)[Size]) noexcept - - Constructs a string view on the full character string literal \a string, - including any trailing \c{Char(0)}. If you don't want the - null-terminator included in the view then you can use the constructor - overload taking a pointer and a size: - - \snippet code/src_corelib_text_qanystringview.cpp 2 - - Alternatively you can use the constructor overload taking an - array literal which will create a view up to, but not including, - the first null-terminator in the data. - - \a string must remain valid for the lifetime of this string view - object. - - This function will work with any array literal if \c Char is a - compatible character type. -*/ - -/*! - \fn QString QAnyStringView::toString() const - - Returns a deep copy of this string view's data as a QString. - - The return value will be a null QString if and only if this string view is null. -*/ - -/*! - \fn const void *QAnyStringView::data() const - - Returns a const pointer to the first character in the string view. - - \note The character array represented by the return value is \e not null-terminated. - - \sa size_bytes() -*/ - -/*! - \fn bool QAnyStringView::empty() const - - Returns whether this string view is empty - that is, whether \c{size() == 0}. - - This function is provided for STL compatibility. - - \sa isEmpty(), isNull(), size() -*/ - -/*! - \fn bool QAnyStringView::isEmpty() const - - Returns whether this string view is empty - that is, whether \c{size() == 0}. - - This function is provided for compatibility with other Qt containers. - - \sa empty(), isNull(), size() -*/ - -/*! - \fn bool QAnyStringView::isNull() const - - Returns whether this string view is null - that is, whether \c{data() == nullptr}. - - This functions is provided for compatibility with other Qt containers. - - \sa empty(), isEmpty(), size() -*/ - -/*! - \fn qsizetype QAnyStringView::size() const - - Returns the size of this string view, in the encoding's code points. - - \sa empty(), isEmpty(), isNull(), size_bytes(), {Sizes and Sub-Strings} -*/ - -/*! - \fn QAnyStringView::size_bytes() const - - Returns the size of this string view, but in bytes, not code-points. - - You can use this function together with data() for hashing or serialization. - - This function is provided for STL compatibility. - - \sa size(), data() -*/ - -/*! - \fn int QAnyStringView::length() const - - Same as size(). - - This function is provided for compatibility with other Qt containers. - - \sa size() -*/ - -/*! - \fn QChar QAnyStringView::front() const - - Returns the first character in the string view. - - This function is provided for STL compatibility. - - \warning Calling this function on an empty string view constitutes - undefined behavior. - - \sa back(), {Sizes and Sub-Strings} -*/ - -/*! - \fn QChar QAnyStringView::back() const - - Returns the last character in the string view. - - This function is provided for STL compatibility. - - \warning Calling this function on an empty string view constitutes - undefined behavior. - - \sa front(), {Sizes and Sub-Strings} -*/ - -/*! - \fn QAnyStringView::compare(QAnyStringView lhs, QAnyStringView rhs, Qt::CaseSensitivity cs) - - Returns an integer that compares to zero as \a lhs compares to \a rhs. - - If \a cs is Qt::CaseSensitive (the default), the comparison is case sensitive; - otherwise the comparison is case-insensitive. - - \sa operator==(), operator<(), operator>() -*/ - -/*! - \fn bool QAnyStringView::operator==(QAnyStringView lhs, QAnyStringView rhs) - \fn bool QAnyStringView::operator!=(QAnyStringView lhs, QAnyStringView rhs) - \fn bool QAnyStringView::operator<=(QAnyStringView lhs, QAnyStringView rhs) - \fn bool QAnyStringView::operator>=(QAnyStringView lhs, QAnyStringView rhs) - \fn bool QAnyStringView::operator<(QAnyStringView lhs, QAnyStringView rhs) - \fn bool QAnyStringView::operator>(QAnyStringView lhs, QAnyStringView rhs) - - Operators that compare \a lhs to \a rhs. - - \sa compare() -*/ - -/*! - \fn template <typename QStringLike> qToAnyStringViewIgnoringNull(const QStringLike &s); - \since 6.0 - \internal - - Convert \a s to a QAnyStringView ignoring \c{s.isNull()}. - - Returns a string view that references \a{s}'s data, but is never null. - - This is a faster way to convert a QString or QByteArray to a QAnyStringView, - if null QStrings or QByteArrays can legitimately be treated as empty ones. - - \sa QString::isNull(), QAnyStringView -*/ - |