Commit Graph

66 Commits

Author SHA1 Message Date
Marc Mutz 9efcf14572 Mark string view classes as security-critical
QString and QByteArray are critical, too, and not because of their
ownership semantics, but because of the algorithms operating on
them. The views have largely the same algorithms, so the same
rationale applies here.

Unlike the owning containers, the views are mostly inline, so mark the
headers. The implementation files, OTOH, are not critical, because
they contain only trivial implementation:

- QDebug op<< (qanystringview.cpp)
- none (qstringview.cpp)

The qdoc files, some of which have in the past moved from qdoc to cpp
and/or back, are insignificant reason:docs.

Task-number: QTBUG-135195
Pick-to: 6.10.0 6.10 6.9 6.8
Change-Id: Ic7874d5d28a966be52813ada36e65f488e6fb653
Reviewed-by: Ivan Solovev <ivan.solovev@qt.io>
2025-09-19 19:37:45 +02:00
Olivier De Cannière 44e0210b6e Doc: Fix inconsistent QChar arg naming in some QStringView functions
Rename char arguments to align with the other overloads and with the
utf16-or-latin1-or-ch snippet.

Pick-to: 6.10 6.9 6.8 6.5
Change-Id: I88b070d792406d5f3c88149030733bbbea6848f5
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
2025-08-26 17:16:56 +02:00
Ivan Solovev fab2c58f6e Hide docs for operator""_sv
Hide the docs until we can provide a consistent experience, i.e. add
UDLs for other views.

Found in API review. The original comment suggested to revert this
change, but it's a bit problematic, because we already have several
usages in qtdeclarative.

Task-number: QTBUG-134136
Pick-to: 6.10
Change-Id: I54e6e2470ff592ddd9d3d1c3ce14818a550b5e5e
Reviewed-by: Marc Mutz <marc.mutz@qt.io>
2025-08-18 20:15:11 +02:00
Kai Köhne 98ff325a75 Doc: Fix links to deprecated QSV::mid()
mid() got deprecated already in Qt 6.0 . Use sliced() instead.

This also fixes warnings like

     qt5/qtbase/src/corelib/text/qstringview.cpp:730: (qdoc) warning: Can't link to 'mid()'
     qt5/qtbase/src/corelib/text/qstringview.cpp:705: (qdoc) warning: Can't link to 'mid()'
     qt5/qtbase/src/corelib/text/qstringview.cpp:718: (qdoc) warning: Can't link to 'mid()'

Pick-to: 6.5 6.8 6.9 6.10
Change-Id: I5fced4082195aacc2c3e54ab6ca4419e7aeec180
Reviewed-by: Marc Mutz <marc.mutz@qt.io>
2025-07-23 15:31:34 +02:00
Mitch Curtis 441a4ac1bc Doc: link to "Which string class to use?" on all string pages
This section has very useful flowcharts. The question "Which string
class to use?" is exactly what most users will want the answer to when
faced with all of the different string types we provide.

Task-number: QTBUG-135947
Change-Id: I2ae79803e205693d6c7ee8f50cad5d057c4d24ea
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
2025-05-09 03:40:03 +00:00
Marc Mutz b7a67b46e6 Long live \constraints!
We have divergence in the way we document function, operator and
constructor constraints. About half use \note, while the other
doesn't. Some say "if and only if" while others say just "participates
only if".

So add a qdoc macro, \constraints, to semantically mark up these
constraints. It expands to a section titled `Constraints`, and
uses a predefined sentence (prefix) for constraints.

Documentation for constraints is moved to the end of the comment
blocks to separate them from the rest of the text.

Apply them to all the standard-ish constraint documentation blocks
(grepped for "participate"). I didn't look for other, one-off, ways
documentation authors may have documented constraints, but I'm also
not aware of any.

Re-wrap lines only if the result fits into a single line.

As a drive-by, drop additional "if"s, as in "only if X and -if- Y" to
make the texts work with the `Constraints` section.

Fixes: QTBUG-106871
Pick-to: 6.9 6.8 6.5
Change-Id: I18c2f9f734474017264e49165389f8c9c7f34030
Reviewed-by: Kai Köhne <kai.koehne@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
2025-02-28 13:51:18 +00:00
Giuseppe D'Angelo 874be50e7b QStringView: introduce a user-defined literal operator
Although char16_t string literals implicitly convert to QStringView,
there are corner-cases where one may want to explicitly create a
QStringView out of them.

A couple of examples I've found is where these string literals decay
into pointers:

  // range is a std::initializer_list<const char16_t *>
  for (QStringView v : { u"foo", u"bar" }) { ... }

  // ternary will decay arguments
  void print(QStringView);
  print(check ? u"hi" : u"there");

When this happens the resulting code gets pessimized and polluted by
runtime calls to qustrlen in order to build the QStringView objects [1].

We can restore optimal codegen by directly dealing with QStringView
objects instead. Adding explicit conversions may make the code
cumbersome to read, so I'm introducing a UDL for QStringView, matching
the one for QString (and std::string_view).

[1] for instance: https://gcc.godbolt.org/z/eY7xvEje3

Apply the new operator to a couple of places.

[ChangeLog][QtCore][QStringView] Is it now possible to create
QStringView objects by using the u""_sv user-defined literal.

Fixes: QTBUG-123851
Change-Id: I8af7d2e211b356d284de160a222eab9e91d09500
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
2025-02-26 15:27:32 +01:00
Marc Mutz f7e8e54d7e QString: toward UTF-8 arg() support [4/4]: accept QAnyStringViews (incl. UTF-8 ones)
This is the public API for the functionality already implemented in
pt.1 of this patch series (except the replacement of the remaining
Q_UNREACHABLE).

I opted to do the minimal change to enable this important
functionality: the ArgBase hierarchy stays and gets extended a bit
differently than originally envisioned. ArgBase, of course, is just
yet another QAnyStringView re-implementation, so eventually, this will
go. But the churn to do this in a binary-compatible way would just be
too big. Instead of the U8 tag representing UTF-8 arguments, repurpose
this up-to-now unused tag to mean QAnyStringView. This allows to get
rid of the qStringLikeToArg() overloads, leaving only one accepting
QAnyStringView. This is the only one that new code will ever call. But
we still need to support L1 and U16 ArgBases for old code.

[ChangeLog][QtCore][QString/QStringView/QAnyStringView] Added
(multi-)arg() support for UTF-8 (QUtf8StringView) and QAnyStringView
arguments. Passing C string literals or QByteArrays to arg() now no
longer implicitly converts to QString first.

Fixes: QTBUG-124365
Change-Id: I0d710365a45d2c62af26184e8a857c3f4cdeeae2
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
2024-12-03 22:44:54 +01:00
Marc Mutz 906aa1533f Create qdoc macros for C++ class docs 2.1: qHash()
Add a family of qdoc macros to document the various qHash() overloads
we have.

This patch does not change the \relates of the qHash() functions, they
remain as inconsistent as they have been. Created QTBUG-129815 to
clean things up. Since this author expects the \relates to change in
the future, there are different \qhash commands, and all except
\qhashbuiltin take the class name as an argument, for use in a
centrally-choreographed fix for QTBUG-129815.

As drive-by's, fix:
- missing documentation about Key having to support qHash() in the
  associative Qt containers
- drop noexcept and default arguments from \fn lines that needed to
  have their argument names changed
- move the QStringView overload from qhash.cpp to qstringview.cpp
  (as it \relates to the former)

Fixes: QTBUG-129574
Pick-to: 6.8 6.5
Change-Id: I8e8c2edc27422cbe5823f56baf3a24d7f7050836
Reviewed-by: Ivan Solovev <ivan.solovev@qt.io>
Reviewed-by: Jaishree Vyas <jaishree.vyas@qt.io>
2024-11-27 12:39:55 +01:00
Marc Mutz b8500f3efc QString: toward UTF-8 arg() support [3/4]: add Q{Any,Utf8}StringView::arg()
This is the public API for the functionality already implemented in
pt.2 of this patch series.

We can now use UTF-8 format strings, but there's still no way to
interpolate UTF-8 strings into them.

[ChangeLog][QtCore][QUtf8StringView/QAnyStringView] Added
(multi-)arg() support a la QStringView/QLatin1StringView.

Task-number: QTBUG-124365
Change-Id: Ie887e3e89eee6cb997b41e381f143befaad1e08f
Reviewed-by: Ahmad Samir <a.samirh78@gmail.com>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
2024-11-11 14:57:43 +01:00
Ahmad Samir 0130ba3cbd QStringView: de-duplicate some API docs
Pick-to: 6.8
Change-Id: I736874037780147c2ec0d657689fa4f3066ebe7d
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
2024-10-23 01:56:17 +03:00
Ivan Solovev 2382bfb5b0 Add max_size() and maxSize() to view types
That requires including qcontainerfwd.h to the headers, so that
we could get access to QtPrivate::MaxAllocSize.

The max_size() methods are added for compatibility with stl.
The logic for most of the views is similar. The only exception is
QAnyStringView, because its character size may vary, depending on the
contained data.

The maxSize() methods are the static equivalents of max_size().
QASV does not have it for the reasons mentioned above.

[ChangeLog][QtCore] Added max_size() to all string-view types.

Amends 7ce6920aac.

Found in 6.8 API review.

Pick-to: 6.8
Change-Id: I467c7d64ec3d92eb424eb5b94a39ec3d45d63d1f
Reviewed-by: Marc Mutz <marc.mutz@qt.io>
2024-08-30 14:50:45 +00:00
Ahmad Samir 8f68bd9e63 String Views: add slice() methods
Methods with preconditions can't be noexcept (from Marc in code
review).

[ChangeLog][QtCore][String Views] Added slice() methods to
Q{String,ByteArray,Latin1String,Utf8String,AnyString}View which work
like sliced() but modify the view they are called on.

Found in API review.

Pick-to: 6.8
Task-number: QTBUG-99218
Change-Id: Ic8ef3085f7cfac86b8404fb28d491ca38ad121eb
Reviewed-by: Marc Mutz <marc.mutz@qt.io>
2024-08-28 15:32:19 +00:00
Ivan Solovev 7500577a92 QStringView: use new comparison helper macros
Replace the friend relational operators for QSV vs QSV and QSV vs QChar
comparison.

Task-number: QTBUG-117661
Change-Id: I547f69dac67c27b04864e56b383e75e213a17bfe
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
2024-02-20 01:04:34 +01:00
Luca Di Sera 60c2d72d96 Doc: Fix \fn template arguments for Qt Core
Upcoming changes to QDoc require accurate definition for
template arguments in \fn commands.

Task-number: QTBUG-118080
Change-Id: I64d50919bc6ffab61ef5ead553d1da99d63a9f21
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
2023-11-30 11:26:20 +01:00
Jaishree Vyas 19b17667da Improve the documentation of compare() overloads for string-like types
Also update the QCollator::compare() docs for consistency.

Task-number: QTBUG-114822
Change-Id: I5fca896cacedd93ce5a4a1a8aead1986a21f6993
Reviewed-by: Ivan Solovev <ivan.solovev@qt.io>
2023-11-20 16:46:15 +00:00
Luca Di Sera 482d11fdbe Doc: Fix template information for QStringView members
When QDoc parses a project, it parses the source code to extract the
user-provided documentation and perform sanity checkings based on the
code itself on it.

When QDoc parses an "\fn" command as part of this process, it tries to
understand, based on its intermediate representation built on the
information extracted from the code-base, which "documentable element"
the "\fn" refers to.

When QDoc performs this "matching" process, it takes into consideration
only a certain amount of information.
For example, no checking is performed over the template declaration of a
callable.

Due to some upcoming documentation, where two callables are
indistinguishable to the current process, as they differ only in their
template declaration, QDoc will start to take into consideration the
template declaration of a callable when matching.

This implies that an "\fn" command should now provide information
parity, with regards to template declaration for callables, with the
code-base so that QDoc can perform the match correctly.

The documentation for of the members of `QStringView` is not in sync
with the intended target template declaration.

Hence, add the missing information to the relevant "\fn" commands.

Task-number: QTBUG-118080
Change-Id: Ia5c6f99d38b0080b150cbfca83ae605cc07d9b72
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
2023-11-13 16:35:54 +01:00
Anton Kudryavtsev 4fad57e750 QStringView: add isLower and isUpper
[ChangeLog][QtCore][QStringView] Added isLower() and isUpper()

Change-Id: Ie6cd20bd375d42cbdfb17953b2307d025c31ec77
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
2023-11-02 13:50:42 +03:00
Ahmad Samir 42c4d6c249 String views: de-duplicate API docs
Will be reused in later commits.

Change-Id: I078ad7eb0aac6eb389453d8bc32c414c840bc22e
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
2023-10-02 23:28:13 +03:00
Giuseppe D'Angelo 96d67da420 String-like containers: add implicit conversions towards std:: string views
In C++20 std::basic_string_view has gained a range constructor (like
QStringView always had), but that range constructor has been made
explicit. This means we can't just pass a QString(View) to a function
taking a u16string_view. The consensus seems to be that that types that
should implictly convert towards stdlib's string views should do that
via implicit conversion operators. This patch adds them for

* QByteArrayView => std::string_view
* QString(View) => std::u16string_view
* QUtf8StringView => std::string_view or std::u8string_view, depending
  on the storage_type

QLatin1StringView doesn't have a matching std:: view so I'm not enabling
its conversion.

QByteArray poses a challenge, in that it already defines a conversion
towards const char *. (One can disable that conversion with a macro.)
That conversion makes it impossible to support:

  QByteArray ba;
  std::string_view sv1(ba);  // 1
  std::string_view sv2 = ba; // 2

because:

* if only operator const char *() is defined, then (2) doesn't work
  (situation right now);

* if both conversions to const char * and string_view are defined, then
  (1) is ambiguous on certain compilers (MSVC, QCC). Interestingly
  enough, not on GCC/Clang, but only in C++17 and later modes.

I can't kill the conversion towards const char * (API break, and we use
it *everywhere* in Qt), hence, QByteArray does not get the implicit
conversion, at least not in this patch.

[ChangeLog][QtCore][QByteArrayView] Added an implicit conversion
operator towards std::string_view.

[ChangeLog][QtCore][QString] Added an implicit conversion operator
towards std::u16string_view.

[ChangeLog][QtCore][QStringView] Added an implicit conversion operator
towards std::u16string_view.

[ChangeLog][QtCore][QUtf8StringView] Added an implicit conversion
operator towards std::string_view (QUtf8StringView is using char
as its storage type in Qt 6). Note that QUtf8StringView is planned to
use char8_t in Qt 7, therefore it is expected that the conversion will
change towards std::u8string_view in Qt 7.

Change-Id: I6d3b64d211a386241ae157765cd1b03f531f909a
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
2023-07-13 16:19:06 +02:00
Mårten Nordheim 054a64ce67 QStringView: size is encoded with code units not code points
Code points is what you get when surrogate pairs have been joined

Pick-to: 6.6 6.5 6.2
Change-Id: I86c4131de5782ce1e6342217947a603ca16bb521
Reviewed-by: Giuseppe D'Angelo <giuseppe.dangelo@kdab.com>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
2023-06-20 22:04:04 +00:00
Marc Mutz fd6ecd8561 Q{Any,Utf8,}StringView: fix docs of generic Container ctor
For QAnyStringView, the docs were missing completely.

For QUtf8StringView and QStringView, they weren't updated following
the rewrite of the std::basic_string ctors into generic Container
ones.

Amends 9e1dc1e8a9 and
2c9529e158.

Pick-to: 6.5 6.2
Task-number: QTBUG-112746
Change-Id: I6eef2294db01e35f1a085df7fc76c25c6003530d
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
2023-05-04 07:07:08 +02:00
Marc Mutz bbb9cf225f Make compare(QU8SV) a non-template, document it
Templates have different overload characteristics from normal
functions, and treating q_no_char8_t and q_has_char8_t::QUtf8StingView
separately is never necessary, as one implicitly converts into the
other.

Add docs for the new UTF-8 compare() functions.

Amends b977ae371a.

Found in API review.

Pick-to: 6.5 6.5.0
Change-Id: I58b4b28a3eccde1976d71cfa3412b734d46f314d
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
2023-03-09 11:36:42 +00:00
Ahmad Samir a608744c90 Docs: adjust docs after the QLatin1String to QLatin1StringView rename
Unify wording as "{Latin-1,UTF-16} string viewed by \a str".

Drive-by change: Fix a grammatical error, it's "a US-ASCII", not an
(because it's pronounced by the letter name "U" which is pronounced
like "you", so "a" not "an").

Task-number: QTBUG-108711
Pick-to: 6.5
Change-Id: Iff763f4008341c35317bb3d7a2a228767ff6a648
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
2023-01-05 14:46:38 +02:00
Ahmad Samir 5d76c49e9c Use more documentation snippets for QString and its siblings
Pick-to: 6.5
Change-Id: Ia569806b586923473f68b9fe1d98a3628ba46a58
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
2023-01-01 14:13:50 +02:00
Marc Mutz 334c27dad1 [docs] Fix ints that should be qsizetype [src/corelib/text]
For the constructors, replace int with qsizetype. For the incorrect
return type in \fn of length(), drop the return type, the presence of
which violated DRY, stressing the importance of that SOLID principle.

Fixes: QTBUG-103531
Pick-to: 6.4 6.3 6.2
Change-Id: Ic7a8e1953333c28a2722fd7f753a0b5af6777395
Reviewed-by: Sona Kurazyan <sona.kurazyan@qt.io>
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
2022-09-01 15:51:48 +02:00
Ivan Solovev 593b0a01c5 Remove QStringView metatype declaration
It was required back in Qt 5 times, so that we could use
qvariant_cast<> or QVariant.value() on it. Not required in Qt 6
anymore.

As a drive-by: cleanup some unneeded includes in qstringview.cpp

Task-number: QTBUG-102350
Pick-to: 6.4
Change-Id: Idbcdc5cfe62cf4a55b86e227106d7a997997e0ba
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
2022-07-13 12:52:00 +02:00
Lucie Gérard 05fc3aef53 Use SPDX license identifiers
Replace the current license disclaimer in files by
a SPDX-License-Identifier.
Files that have to be modified by hand are modified.
License files are organized under LICENSES directory.

Task-number: QTBUG-67283
Change-Id: Id880c92784c40f3bbde861c0d93f58151c18b9f1
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Lars Knoll <lars.knoll@qt.io>
Reviewed-by: Jörg Bornemann <joerg.bornemann@qt.io>
2022-05-16 16:37:38 +02:00
Giuseppe D'Angelo d063b2b131 QBAV/QSV: remove a historical note
Both QByteArray and QString can contain more than 2^32 elements on 64
bits platforms, so the warning does not apply any more.

Change-Id: I4604c1fe225922a0df7e78135eeb5a1e2b84fea3
Pick-to: 6.2 6.3
Reviewed-by: Marc Mutz <marc.mutz@qt.io>
2022-04-01 23:03:58 +02:00
Sona Kurazyan b625195893 QtCore: Replace remaining uses of QLatin1String with QLatin1StringView
Task-number: QTBUG-98434
Change-Id: Ib7c5fc0aaca6ef33b93c7486e99502c555bf20bc
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Reviewed-by: Marc Mutz <marc.mutz@qt.io>
2022-03-26 01:44:05 +01:00
Sona Kurazyan 76db8a0b1b Use QLatin1StringView in QString/QLatin1String APIs and docs
- Replaced QLatin1String with QLatin1StringView in QString/QLatin1String
  APIs and docs (except for QLatin1String class declaration and ctor
  names).

- Made the docs look like QLatin1StringView is "The Real Thing".

[ChangeLog][QtCore] Made QLatin1StringView the recommended name for
referring to a Latin-1 string view (instead of QLatin1String).

Task-number: QTBUG-98434
Change-Id: I6d9a85cc956c6da0c910ad7d23be7956e4bd94ac
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
2022-03-23 18:06:51 +01:00
Sona Kurazyan 893dd5d7be Add QStringView::localeAwareCompare()
QString already has a localeAwareCompare(QStringView, QStringView)
static method. Use it in QStringView::localeAwareCompare(QStringView).

[ChangeLog][QtCore][QStringView] Added
QStringView::localeAwareCompare().

Task-number: QTBUG-98431
Change-Id: Iec3865a5439d9fb653cc1150da21042186bdee98
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Reviewed-by: Marc Mutz <marc.mutz@qt.io>
2022-03-17 14:27:45 +01:00
Sona Kurazyan 82e12c79b2 Add an overload of QStringView::count() for QLatin1String
Required for the API symmetry between QStringView and QLatin1String.

[ChangeLog][QtCore][QStringView] Added an overload of
QStringView::count() for QLatin1String.

Change-Id: Ic49a4b31e8f6f0969eff0f792654d23a60e06c49
Task-numer: QTBUG-98431
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
2022-03-09 15:58:47 +01:00
Marc Mutz ecc307ff41 QString et al: fix lastIndexOf() API asymmetry
Commit 6cee204d56 introduced overloads
of lastIndexOf() which drop the 'from' argument, inadvertently fixing
QTBUG-80694, but failed to provide the new overloads for all existing
lastIndexOf() overloads, making the fix for QTBUG-80694 incomplete.

This patch completes the fix, by adding the missing overloads (for
char-likes) and also adds the missing (non-regex) tests to
tst_qstringapisymmetry.

Also amends 1c164ec7f2.

Fixes: QTBUG-80694
Change-Id: Ib4b3d597d658ce2edf01a2bce0d711ecea593d6e
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
2021-12-02 16:05:33 +00:00
Volker Hilsheimer 62fc486a77 Doc: fix a bunch of qdoc warnings from wrong prototypes
* name method parameters consistently with their declaration
* don't document parameters that are not there

Pick-to: 6.2
Change-Id: I06ae9fdca357ed29eb7a72802f149eb4914181f4
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
2021-09-03 21:40:08 +02:00
Giuseppe D'Angelo 6cee204d56 QS(V)/QBA(V)/QL1S::lastIndexOf: fix the offset calculations
When trying to fix 0-length matches at the end of a QString,
be83ff65c4 actually introduced a
regression due to how lastIndexOf interprets its `from` parameter.

The "established" (=legacy) interpretation of a negative `from` is that
it is supposed to indicate that we want the last match at offset `from +
size()`. With the default from of -1, that means we want a match
starting at most at position `size() - 1` inclusive, i.e. *at* the last
position in the string. The aforementioned commit changed that, by
allowing a match at position `size()` instead, and this behavioral
change broke code.

The problem the commit tried to fix was that empty matches *are* allowed
to happen at position size(): the last match of regexp // inside the
string "test" is indeed at position 4 (the regexp matches 5 times).

Changing the meaning of negative from to include that last position (in
general: to include position `from+size()+1` as the last valid matching
position, in case of a negative `from`) has unfortunately broken client
code. Therefore, we need to revert it. This patch does that, adapting
the tests as necessary (drive-by: a broken #undef is removed).

Reverting the patch however is not sufficient. What we are facing here
is an historical API mistake that forces the default `from` (-1) to
*skip* the truly last possible match; the mistake is that thre is simply
no way to pass a negative `from` and obtain that match. This means that
the revert will now cause code like this:

  str.lastIndexOf(QRE("")); // `from` defaulted to -1

NOT to return str.size(), which is counter-intuitive and wrong. Other
APIs expose this inconsistency: for instance, using
QRegularExpressionIterator would actually yield a last match at position
str.size(). Similarly, using QString::count would return `str.size()+1`.
Note that, in general, it's still possible for clients to call

  str.lastIndexOf(~~~, str.size())

to get the "truly last" match.

This patch also tries to fix this case ("have our cake and eat it").

First and foremost, a couple of bugs in QByteArray and QString code are
fixed (when dealing with 0-length needles).

Second, a lastIndexOf overload is added. One overload is the "legacy"
one, that will honor the pre-existing semantics of negative `from`. The
new overload does NOT take a `from` parameter at all, and will actually
match from the truly end (by simply calling `lastIndexOf(~~~, size())`
internally).

These overloads are offered for all the existing lastIndexOf()
overloads, not only the ones taking QRE.

This means that code simply using `lastIndexOf` without any `from`
parameter get the "correct" behavior for 0-length matches, and code that
specifies one gets the legacy behavior. Matches of length > 0 are not
affected anyways, as they can't match at position size().

[ChangeLog][Important Behavior Changes] A regression in the behavior of
the lastIndexOf() function on text-related containers and views
(QString, QStringView, QByteArray, QByteArrayView, QLatin1String) has
been fixed, and the behavior made consistent and more in line with
user expectations. When lastIndexOf() is invoked with a negative `from`
position, the last match has now to start at the last character in the
container/view (before, it was at the position *past* the last
character). This makes a difference when using lastIndexOf() with a
needle that has 0 length (for instance an empty string, a regular
expression that can match 0 characters, and so on); any other case is
unaffected. To retrieve the "truly last" match, one can pass a
positive `from` offset to lastIndexOf() (basically, pass `size()` as the
`from` parameter). To make calls such as `text.lastIndexOf(~~~);`, that
do not pass any `from` parameter, behave properly, a new lastIndexOf()
overload has been added to all the text containers/views. This overload
does not take a `from` parameter at all, and will search starting from
one character past the end of the text, therefore returning a correct
result when used with needles that may yield 0-length matches. Client
code may need to be recompiled in order to use this new overload.
Conversely, client code that needs to skip the "truly last" match now
needs to pass -1 as the `from` parameter instead of relying on the
default.

Change-Id: I5e92bdcf1a57c2c3cca97b6adccf0883d00a92e5
Fixes: QTBUG-94215
Pick-to: 6.2
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
2021-08-19 01:55:01 +02:00
Sona Kurazyan 9009a36c01 Fix some errors in docs of string-related classes
- Fixed various texts in docs for QStringView, QUtf8StringView and
QAnyStringView copied from QString, that are still talking about string
or string reference instead of string view.

- Replaced 'string-view' with 'string view', which is the more commonly
used form.

- Fixed the wrong usage of uppercase 'If' in some places.

- Did minor adjusments, to make the docs consistent with docs of
QByteArray/QByteArrayView.

Change-Id: Ifb905e00957e869a8befad5a36d6b00b6e621a04
Reviewed-by: Ivan Solovev <ivan.solovev@qt.io>
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
2021-08-16 18:53:56 +02:00
Paul Wicking a1dfe27955 Doc: Use \deprecated instead of \obsolete
Task-number: QTBUG-93990
Change-Id: I4e512354a49dde6678ca89cabc56bc76ba666bb3
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
2021-05-26 13:06:56 +02:00
Giuseppe D'Angelo 86ad338aa4 Q{*String,ByteArray}View::length(): use qsizetype, not int
Looks like these ones have been forgotten in the Qt 5 -> 6 upgrade
to qsizetype. Change them to return qsizetype as well,
and fix the docs. Being entirely inline, non-exported classes, we
should be able to get away with it without affecting binary
compatibility. Moreover, there's no reason for keeping them
deprecated.

Requires some minor adjustments, just like the ones done for
size()'s changes.

[ChangeLog][QtCore][QStringView] The length() function
now returns `qsizetype`, not `int`, for consistency with the
other string and container classes in Qt. Following this
change, it has been un-deprecated.

[ChangeLog][QtCore][QAnyStringView] The length() function
now returns `qsizetype`, not `int`, for consistency with the
other string and container classes in Qt. Following this
change, it has been un-deprecated.

[ChangeLog][QtCore][QUtf8StringView] The length() function
now returns `qsizetype`, not `int`, for consistency with the
other string and container classes in Qt. Following this
change, it has been un-deprecated.

[ChangeLog][QtCore][QByteArrayView] The length() function
now returns `qsizetype`, not `int`, for consistency with the
other string and container classes in Qt. Following this
change, it has been un-deprecated.

Fixes: QTBUG-92496
Change-Id: Ie0f4939d1083884e95d4725f891b6c6764532cb8
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
2021-04-15 01:09:44 +02:00
Thiago Macieira 4974091699 QStringView: add constBegin and constEnd
Change-Id: I55083c2909f64a1f8868fffd164f21118a9d3ec5
Reviewed-by: Allan Sandfeld Jensen <allan.jensen@qt.io>
Reviewed-by: Lars Knoll <lars.knoll@qt.io>
2020-12-12 12:17:18 -08:00
Giuseppe D'Angelo ce0b767310 QStringView: add some QRegularExpression-related overloads
[ChangeLog][QtCore][QStringView] Added the indexOf(), contains(),
lastIndexOf() and count() methods taking a QRegularExpression.

Fixes: QTBUG-89050
Change-Id: Ic726754f67e06b3764302d2fad252e0378a77afc
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
2020-12-10 02:15:18 +01:00
Anton Kudryavtsev e8662d2d80 Doc: fix QStringView::compare since section
Change-Id: Ia469236f9cf669e11bcaec5fa8e4837bbbe911c7
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
2020-11-16 10:50:52 +03:00
Topi Reinio ecd86b1894 Doc: Fix documentation warnings for string classes
Task-number: QTBUG-86295
Change-Id: I13033635eecd495b32c98c7ec9318a0102b6f23e
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
2020-10-29 18:29:22 +01:00
Volker Hilsheimer 0ebe1708e2 Fix qdoc warnings in QStringView
Fix prototype of template member function, and fix see-also reference.

Change-Id: Ibb39925063dfeb3fd511f47a1606a0b243d4c2ef
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
2020-09-26 14:35:48 +02:00
Volker Hilsheimer 756104d5e1 Fix some qdoc warnings for QString/View/Tokenizer
Use correct member function prototype, which requires the template declaration.
Remove see-alsos that don't exist.
Document parameters for qTokenize.

Still lots of warnings from QStringTokenizer, due to the inheritance structure
of that template class and the declarations of nested types in undocumented
base classes.

Also, qdoc doesn't seem to recognize training this-lvalue/this-rvalue
declarations for overloads, and considers the second toContainer documentations
to override the first.

Change-Id: Iadf967d3328ddda52b6f66786836853bddeda79b
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
2020-09-26 14:35:29 +02:00
Mårten Nordheim 107ff4c1d6 Q(Any|Utf8)StringView: move array size deduction feature to fromArray
The constructor taking an array literal will now stop at the first
null-terminator encountered.

And fromArray is introduced which only supports array literals.
Constructs a view of the full size. Explicit so it shouldn't be
surprising.

Change-Id: I1497c33a5c12453a95e87c990abe6335b2817081
Reviewed-by: Andrei Golubev <andrei.golubev@qt.io>
Reviewed-by: Lars Knoll <lars.knoll@qt.io>
2020-09-18 23:34:52 +02:00
Karsten Heimrich 2766322de3 Move QStringRef and remains to Qt5Compat
Export some private functions from QUtf8 to resolve
undefined symbols in Qt5Compat after moving QStringRef.

Task-number: QTBUG-84437
Change-Id: I9046dcb14ed520d8868a511d79da6e721e26f72b
Reviewed-by: Lars Knoll <lars.knoll@qt.io>
2020-08-20 00:58:13 +02:00
Linus Jahn 1ecc884bfd QStringView: Remove outdated note about usage with QList
Change-Id: Id1cef09642ccde701e57e8f0a3a3d0e5fcf47e5c
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
2020-07-12 21:07:05 +02:00
Lars Knoll 9117e3850b Rename from() to sliced()
After API discussions, agreement was that from(n) is a bad name
for the method. Let's go with sliced(n) instead.

Change-Id: I0338cc150148a5008c3ee72bd8fda96fb93e9c35
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
2020-07-06 21:31:35 +02:00
Jarek Kobus b0f9c06a9b Use QList instead of QVector in corelib implementation
Omitting state machine and docs for now.

Task-number: QTBUG-84469
Change-Id: Ibfa5e7035515773461f6cdbff35299315ef65737
Reviewed-by: Sona Kurazyan <sona.kurazyan@qt.io>
2020-06-29 12:35:09 +02:00