diff options
Diffstat (limited to 'src/corelib/tools/qvector.cpp')
| -rw-r--r-- | src/corelib/tools/qvector.cpp | 27 |
1 files changed, 18 insertions, 9 deletions
diff --git a/src/corelib/tools/qvector.cpp b/src/corelib/tools/qvector.cpp index 9afd2c624a..0fcba3c0c4 100644 --- a/src/corelib/tools/qvector.cpp +++ b/src/corelib/tools/qvector.cpp @@ -403,15 +403,24 @@ /*! \fn void QVector::reserve(int size) 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 - function, and if you call resize() often you are likely to get - 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 - tuning QVector's memory usage. In general, you will rarely ever - need to call this function. If you want to change the size of the - vector, call resize(). + know in advance how large the vector will be, you should call this + function to prevent reallocations and memory fragmentation. + + If \a size is an underestimate, the worst that will happen is that + the QVector will be a bit slower. If \a size is an overestimate, you + may have used more memory than the normal QVector growth strategy + 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() */ |