diff options
author | Marc Mutz <marc.mutz@kdab.com> | 2019-05-15 11:52:14 +0200 |
---|---|---|
committer | Marc Mutz <marc.mutz@kdab.com> | 2019-05-16 13:18:06 +0000 |
commit | 5497183c71de352324cab05f3c0a768be75a236a (patch) | |
tree | 3119ca7df32828f91300b76aa9db34ef41eddca4 /src/corelib/global | |
parent | 0e71db3c8eb7f98bccbe0fae48ba324b3ebfd301 (diff) |
Add some examples to qExchange() docs
Change-Id: I758782f6566ab94006aedacc9988ec4eb09a14c6
Reviewed-by: MÃ¥rten Nordheim <marten.nordheim@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Diffstat (limited to 'src/corelib/global')
-rw-r--r-- | src/corelib/global/qglobal.cpp | 39 |
1 files changed, 39 insertions, 0 deletions
diff --git a/src/corelib/global/qglobal.cpp b/src/corelib/global/qglobal.cpp index 3436a19881..be01e5a605 100644 --- a/src/corelib/global/qglobal.cpp +++ b/src/corelib/global/qglobal.cpp @@ -3815,7 +3815,46 @@ bool qunsetenv(const char *varName) This is Qt's implementation of std::exchange(). It differs from std::exchange() only in that it is \c constexpr already in C++14, and available on all supported compilers. + + Here is how to use qExchange() to implement move constructors: + \code + MyClass(MyClass &&other) + : m_pointer{qExchange(other.m_pointer, nullptr)}, + m_int{qExchange(other.m_int, 0)}, + m_vector{std::move(other.m_vector)}, + ... + \endcode + + For members of class type, we can use std::move(), as their move-constructor will + do the right thing. But for scalar types such as raw pointers or integer type, move + is the same as copy, which, particularly for pointers, is not what we expect. So, we + cannot use std::move() for such types, but we can use std::exchange()/qExchange() to + make sure the source object's member is already reset by the time we get to the + initialization of our next data member, which might come in handy if the constructor + exits with an exception. + + Here is how to use qExchange() to write a loop that consumes the collection it + iterates over: + \code + for (auto &e : qExchange(collection, {}) + doSomethingWith(e); + \endcode + + Which is equivalent to the following, much more verbose code: + \code + { + auto tmp = std::move(collection); + collection = {}; // or collection.clear() + for (auto &e : tmp) + doSomethingWith(e); + } // destroys 'tmp' + \endcode + + This is perfectly safe, as the for-loop keeps the result of qExchange() alive for as + long as the loop runs, saving the declaration of a temporary variable. Be aware, though, + that qExchange() returns a non-const object, so Qt containers may detach. */ + /*! \macro QT_TR_NOOP(sourceText) \relates <QtGlobal> |