1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[docs] QVector: don't scare people away from reserve()

Browse Source 
reserve() is a good thing, and key to getting top performance out
of any data structure that provides them, yet the existing docs
scared people away by claiming that "you will rarely ever need to
call this function".

Change-Id: I88e30d96960443c0ed759a79c6fa9ee6af0d1e07
Reviewed-by: Mitch Curtis <mitch.curtis@theqtcompany.com>
This commit is contained in:
Marc Mutz 2015-10-13 10:35:01 +02:00
parent 18bd4453ce
commit 01284f3886
1 changed files with 17 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
src/corelib/tools/qvector.cpp
View File

@ -403,15 +403,24 @@
/*! \fn void QVector::reserve(int size) /*! \fn void QVector::reserve(int size)
Attempts to allocate memory for at least \a size elements. If you Attempts to allocate memory for at least \a size elements. If you
know in advance how large the vector will be, you can call this know in advance how large the vector will be, you should call this
function, and if you call resize() often you are likely to get function to prevent reallocations and memory fragmentation.
better performance. If \a size is an underestimate, the worst
that will happen is that the QVector will be a bit slower.
The sole purpose of this function is to provide a means of fine If \a size is an underestimate, the worst that will happen is that
tuning QVector's memory usage. In general, you will rarely ever the QVector will be a bit slower. If \a size is an overestimate, you
need to call this function. If you want to change the size of the may have used more memory than the normal QVector growth strategy
vector, call resize(). would have allocated—or you may have used less.
An alternative to reserve() is calling resize(). Whether or not that is
faster than reserve() depends on the element type, because resize()
default-constructs all elements, and requires assignment to existing
entries rather than calling append(), which copy- or move-constructs.
For simple types, like \c int or \c double, resize() is typically faster,
but for anything more complex, you should prefer reserve().
\warning If the size passed to resize() was underestimated, you run out
of allocated space and into undefined behavior. This problem does not
exist with reserve(), because it treats the size as just a hint.
\sa squeeze(), capacity() \sa squeeze(), capacity()
*/ */