1 files changed, 58 insertions, 12 deletions

diff --git a/src/corelib/tools/qvector.qdoc b/src/corelib/tools/qvector.qdoc
index 116d962411..daa6ff95e9 100644
--- a/src/corelib/tools/qvector.qdoc
+++ b/src/corelib/tools/qvector.qdoc
@@ -39,7 +39,7 @@
     stores its items in adjacent memory locations and provides fast
     index-based access.
 
-    QList\<T\>, QLinkedList\<T\>, QVector\<T\>, and QVarLengthArray\<T\>
+    QList\<T\>, QVector\<T\>, and QVarLengthArray\<T\>
     provide similar APIs and functionality. They are often interchangeable,
     but there are performance consequences. Here is an overview of use cases:
 
@@ -57,18 +57,13 @@
         those APIs.
     \li If you need a real linked list, which guarantees
         \l{Algorithmic Complexity}{constant time} insertions mid-list and
-        uses iterators to items rather than indexes, use QLinkedList.
+        uses iterators to items rather than indexes, use std::list.
     \endlist
 
     \note QVector and QVarLengthArray both guarantee C-compatible
     array layout. QList does not. This might be important if your
     application must interface with a C API.
 
-    \note Iterators into a QLinkedList and references into
-    heap-allocating QLists remain valid as long as the referenced items
-    remain in the container. This is not true for iterators and
-    references into a QVector and non-heap-allocating QLists.
-
     Here's an example of a QVector that stores integers and a QVector
     that stores QString values:
 
@@ -129,7 +124,7 @@
     (\l{linear time}) for large vectors, because they require moving many
     items in the vector by one position in memory. If you want a container
     class that provides fast insertion/removal in the middle, use
-    QList or QLinkedList instead.
+    std::list instead.
 
     Unlike plain C++ arrays, QVectors can be resized at any time by
     calling resize(). If the new size is larger than the old size,
@@ -190,8 +185,6 @@
     holding a lot of allocated memory, especially large, contiguous blocks.
     Such considerations, the configuration of such behavior or any mitigation
     are outside the scope of the Qt API.
-
-    \sa QVectorIterator, QMutableVectorIterator, QList, QLinkedList
 */
 
 /*!
@@ -640,12 +633,34 @@
     For large vectors, this operation can be slow (\l{linear time}),
     because it requires moving all the items in the vector by one
     position further in memory. If you want a container class that
-    provides a fast prepend() function, use QList or QLinkedList
+    provides a fast prepend operation, use std::list
     instead.
 
     \sa append(), insert()
 */
 
+/*!
+    \fn template <typename T> template <typename ...Args> T &QVector<T>::emplaceBack(Args&&... args)
+    \fn template <typename T> template <typename ...Args> T &QVector<T>::emplace_back(Args&&... args)
+
+    Adds a new element to the end for the container. This new element
+    is constructed in-place using \a args as the arguments for its
+    construction.
+
+    Returns a reference to the new element.
+
+    Example:
+    \snippet code/src_corelib_tools_qvector.cpp emplace-back
+
+    It is also possible to access a newly created object by using
+    returned reference:
+    \snippet code/src_corelib_tools_qvector.cpp emplace-back-ref
+
+    This is the same as vector.emplace(vector.size(), \a args).
+
+    \sa emplace
+*/
+
 /*! \fn template <typename T> void QVector<T>::insert(int i, const T &value)
     \fn template <typename T> void QVector<T>::insert(int i, T &&value)
 
@@ -659,7 +674,7 @@
     For large vectors, this operation can be slow (\l{linear time}),
     because it requires moving all the items at indexes \a i and
     above by one position further in memory. If you want a container
-    class that provides a fast insert() function, use QLinkedList
+    class that provides a fast insert() function, use std::list
     instead.
 
     \sa append(), prepend(), remove()
@@ -693,6 +708,26 @@
     first of the inserted items.
 */
 
+/*!
+    \fn template <typename T> template <typename ...Args> QVector<T>::iterator QVector<T>::emplace(int i, Args&&... args)
+
+    Extends the container by inserting a new element at position \a i.
+    This new element is constructed in-place using \a args as the
+    arguments for its construction.
+
+    Returns an iterator to the new element.
+
+    Example:
+    \snippet code/src_corelib_tools_qvector.cpp emplace
+
+    \note It is garanteed that the element will be created in place
+          at the beginning, but after that it might be copied or
+          moved to the right position.
+
+    \sa emplaceBack
+*/
+
+
 /*! \fn template <typename T> void QVector<T>::replace(int i, const T &value)
 
     Replaces the item at index position \a i with \a value.
@@ -838,6 +873,17 @@
     \sa takeFirst(), removeLast()
 */
 
+/*!
+    \fn template <typename T> template <typename ...Args> QVector<T>::iterator QVector<T>::emplace(QVector<T>::iterator before, Args&&... args)
+
+    \overload
+
+    Creates a new element in front of the item pointed to by the
+    iterator \a before. This new element is constructed in-place
+    using \a args as the arguments for its construction.
+
+    Returns an iterator to the new element.
+*/
 
 /*! \fn template <typename T> QVector<T> &QVector<T>::fill(const T &value, int size = -1)