From cec3d03d11ddf2190595c8ed193ecb084a398c9c Mon Sep 17 00:00:00 2001 From: Marc Mutz Date: Wed, 20 Sep 2023 22:12:35 +0200 Subject: [PATCH] Un-deprecate qSwap() It seems to have fallen prey to the mass-deprecation of in Qt 5.2. Since it didn't actually duplicate STL functionality, that was uncalled-for: Unlike std::swap(), it's ADL-enabled, so the docs were wrong to suggest replacing it with std::swap instead. In fact, the tony-table that 5957f245c6c77c98d7e90d614c9fe2cdbfe7e8e6 added to qalgorithms.qdoc didn't include qSwap(), yet, qSwap() was marked as deprecated. Un-deprecate and expand the discussion to more faithfully represent its value, without going into the depths of teaching how to swap correctly in C++ (link to boost.org and cppreference.com for that instead). Remove the example that used qSwap() on doubles, which is precisely _not_ how you should use it. Amends 5957f245c6c77c98d7e90d614c9fe2cdbfe7e8e6(!). [ChangeLog][QtCore] Un-deprecated qSwap(). Pick-to: 6.5 6.2 5.15 Change-Id: I4981005ba71b0d1824f2a46897145255fa66a7ea Reviewed-by: Fabian Kosmale Reviewed-by: Leena Miettinen (cherry picked from commit aa19704bbc35d5310b33a9fbe2added77470a836) Reviewed-by: Qt Cherry-pick Bot --- .../doc/snippets/code/doc_src_qalgorithms.cpp | 9 ----- src/corelib/global/qswap.qdoc | 36 +++++++++++++++---- 2 files changed, 30 insertions(+), 15 deletions(-) diff --git a/src/corelib/doc/snippets/code/doc_src_qalgorithms.cpp b/src/corelib/doc/snippets/code/doc_src_qalgorithms.cpp index 201517aa2a0..f2b94a74165 100644 --- a/src/corelib/doc/snippets/code/doc_src_qalgorithms.cpp +++ b/src/corelib/doc/snippets/code/doc_src_qalgorithms.cpp @@ -1,15 +1,6 @@ // Copyright (C) 2016 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause -//! [0] -double pi = 3.14; -double e = 2.71; - -qSwap(pi, e); -// pi == 2.71, e == 3.14 -//! [0] - - //! [1] QList list; list.append(new Employee("Blackpool", "Stephen")); diff --git a/src/corelib/global/qswap.qdoc b/src/corelib/global/qswap.qdoc index 2d9d56b694b..bffad903f95 100644 --- a/src/corelib/global/qswap.qdoc +++ b/src/corelib/global/qswap.qdoc @@ -1,14 +1,38 @@ // Copyright (C) 2022 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only -/*! \fn template void qSwap(T &var1, T &var2) +/*! + \fn template void qSwap(T &lhs, T &rhs) \relates - \deprecated - Use \c std::swap instead. + Exchanges the values of variables \a lhs and \a rhs, + taking type-specific \c{swap()} overloads into account. - Exchanges the values of variables \a var1 and \a var2. + This function is Qt's version of + \l{https://www.boost.org/doc/libs/release/libs/core/doc/html/core/swap.html}{\c{boost::swap()}}, + and is equivalent to + \code + using std::swap; // bring std::swap into scope (for built-in types) + swap(lhs, rhs); // unqualified call (picks up type-specific overloads + // via Argument-Dependent Lookup, or falls back to std::swap) + \endcode - Example: - \snippet code/doc_src_qalgorithms.cpp 0 + Use this function primarily in generic code, where you would traditionally + have written the above two lines, because you don't know anything about \c{T}. + + If you already know what \c{T} is, then use one of the following options, in + order of preference: + + \list + \li \c{lhs.swap(rhs);} if such a member-swap exists + \li \c{std::swap(lhs, rhs);} if no type-specific \c{swap()} exists + \endlist + + See + \l{https://www.boost.org/doc/libs/release/libs/core/doc/html/core/swap.html}{\c{boost::swap()} on boost.org} + for more details. + + See also + \l{https://en.cppreference.com/w/cpp/algorithm/swap}{\c{std::swap} on cppreference.com}, + \l{https://en.cppreference.com/w/cpp/named_req/Swappable}{\c{Swappable} on cppreference.com}. */