diff options
Diffstat (limited to 'doc/src/classes/q3memarray.qdoc')
| -rw-r--r-- | doc/src/classes/q3memarray.qdoc | 523 |
1 files changed, 523 insertions, 0 deletions
diff --git a/doc/src/classes/q3memarray.qdoc b/doc/src/classes/q3memarray.qdoc new file mode 100644 index 000000000..b9c1f73e3 --- /dev/null +++ b/doc/src/classes/q3memarray.qdoc @@ -0,0 +1,523 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3MemArray + \brief The Q3MemArray class is a template class that provides arrays of simple types. + \compat + + Q3MemArray is implemented as a template class. Define a template + instance Q3MemArray\<X\> to create an array that contains X items. + + Q3MemArray stores the array elements directly in the array. It can + only deal with simple types (i.e. C++ types, structs, and classes + that have no constructors, destructors, or virtual functions). + Q3MemArray uses bitwise operations to copy and compare array + elements. + + The Q3PtrVector collection class is also a kind of array. Like most + old Qt collection classes, it uses pointers to the contained items. + + Q3MemArray uses explicit sharing with a + reference count. If more than one array shares common data and one + of the arrays is modified, all the arrays are modified. + + The benefit of sharing is that a program does not need to duplicate + data when it is not required, which results in lower memory use + and less copying of data. + + Example: + \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 0 + + Program output: + \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 1 + + Note concerning the use of Q3MemArray for manipulating structs or + classes: Compilers will often pad the size of structs of odd sizes + up to the nearest word boundary. This will then be the size + Q3MemArray will use for its bitwise element comparisons. Because + the remaining bytes will typically be uninitialized, this can + cause find() etc. to fail to find the element. Example: + + \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 2 + + To work around this, make sure that you use a struct where + sizeof() returns the same as the sum of the sizes of the members + either by changing the types of the struct members or by adding + dummy members. + + Q3MemArray data can be traversed by iterators (see begin() and + end()). The number of items is returned by count(). The array can + be resized with resize() and filled using fill(). + + You can make a shallow copy of the array with assign() (or + operator=()) and a deep copy with duplicate(). + + Search for values in the array with find() and contains(). For + sorted arrays (see sort()) you can search using bsearch(). + + You can set the data directly using setRawData() and + resetRawData(), although this requires care. +*/ + +/*! \fn Q3MemArray::operator QVector<type>() const + + Automatically converts the Q3MemArray<type> into a QVector<type>. +*/ + +/*! \typedef Q3MemArray::Iterator + A Q3MemArray iterator. + \sa begin() end() +*/ +/*! \typedef Q3MemArray::ConstIterator + A const Q3MemArray iterator. + \sa begin() end() +*/ +/*! \typedef Q3MemArray::ValueType + \internal +*/ + +/*! + \fn Q3MemArray::Q3MemArray() + + Constructs a null array. + + \sa isNull() +*/ + +/*! + \fn Q3MemArray::Q3MemArray( int size ) + + Constructs an array with room for \a size elements. Makes a null + array if \a size == 0. + + The elements are left uninitialized. + + \sa resize(), isNull() +*/ + +/*! + \fn Q3MemArray::Q3MemArray( const Q3MemArray<type> &a ) + + Constructs a shallow copy of \a a. + + \sa assign() +*/ + +/*! + \fn Q3MemArray::Q3MemArray(const QVector<type> &vector) + + Constructs a copy of \a vector. +*/ + +/*! + \fn Q3MemArray::Q3MemArray(int arg1, int arg2) + + Constructs an array \e{without allocating} array space. The + arguments \a arg1 and \a arg2 should be zero. Use at your own + risk. +*/ + +/*! + \fn Q3MemArray::~Q3MemArray() + + Dereferences the array data and deletes it if this was the last + reference. +*/ + +/*! + \fn Q3MemArray<type> &Q3MemArray::operator=( const Q3MemArray<type> &a ) + + Assigns a shallow copy of \a a to this array and returns a + reference to this array. + + Equivalent to assign( a ). +*/ + +/*! + \fn type *Q3MemArray::data() const + + Returns a pointer to the actual array data. + + The array is a null array if data() == 0 (null pointer). + + \sa isNull() +*/ + +/*! + \fn uint Q3MemArray::nrefs() const + + Returns the reference count for the shared array data. This + reference count is always greater than zero. +*/ + +/*! + \fn uint Q3MemArray::size() const + + Returns the size of the array (maximum number of elements). + + The array is a null array if size() == 0. + + \sa isNull(), resize() +*/ + +/*! + \fn uint Q3MemArray::count() const + + Returns the same as size(). + + \sa size() +*/ + +/*! + \fn bool Q3MemArray::isEmpty() const + + Returns TRUE if the array is empty; otherwise returns FALSE. + + isEmpty() is equivalent to isNull() for Q3MemArray (unlike + QString). +*/ + +/*! + \fn bool Q3MemArray::isNull() const + + Returns TRUE if the array is null; otherwise returns FALSE. + + A null array has size() == 0 and data() == 0. +*/ + +/*! + \fn bool Q3MemArray::resize( uint size, Optimization optim ) + + Resizes (expands or shrinks) the array to \a size elements. The + array becomes a null array if \a size == 0. + + Returns TRUE if successful, or FALSE if the memory cannot be + allocated. + + New elements are not initialized. + + \a optim is either Q3GArray::MemOptim (the default) or + Q3GArray::SpeedOptim. When optimizing for speed rather than memory + consumption, the array uses a smart grow and shrink algorithm that + might allocate more memory than is actually needed for \a size + elements. This speeds up subsequent resize operations, for example + when appending many elements to an array, since the space has + already been allocated. + + \sa size() +*/ + +/*! + \fn bool Q3MemArray::resize( uint size ) + + \overload + + Resizes (expands or shrinks) the array to \a size elements. The + array becomes a null array if \a size == 0. + + Returns TRUE if successful, i.e. if the memory can be allocated; + otherwise returns FALSE. + + New elements are not initialized. + + \sa size() +*/ + +/*! + \fn bool Q3MemArray::truncate( uint pos ) + + Truncates the array at position \a pos. + + Returns TRUE if successful, i.e. if the memory can be allocated; + otherwise returns FALSE. + + Equivalent to resize(\a pos). + + \sa resize() +*/ + +/*! + \fn bool Q3MemArray::fill( const type &v, int size ) + + Fills the array with the value \a v. If \a size is specified as + different from -1, then the array will be resized before being + filled. + + Returns TRUE if successful, i.e. if \a size is -1, or \a size is + != -1 and the memory can be allocated; otherwise returns FALSE. + + \sa resize() +*/ + +/*! + \fn void Q3MemArray::detach() + + Detaches this array from shared array data; i.e. it makes a + private, deep copy of the data. + + Copying will be performed only if the \link nrefs() reference + count\endlink is greater than one. + + \sa copy() +*/ + +/*! + \fn Q3MemArray<type> Q3MemArray::copy() const + + Returns a deep copy of this array. + + \sa detach(), duplicate() +*/ + +/*! + \fn Q3MemArray<type> &Q3MemArray::assign( const Q3MemArray<type> &a ) + + Shallow copy. Dereferences the current array and references the + data contained in \a a instead. Returns a reference to this array. + + \sa operator=() +*/ + +/*! + \fn Q3MemArray<type> &Q3MemArray::assign( const type *data, uint size ) + + \overload + + Shallow copy. Dereferences the current array and references the + array data \a data, which contains \a size elements. Returns a + reference to this array. + + Do not delete \a data later; Q3MemArray will call free() on it + at the right time. +*/ + +/*! + \fn Q3MemArray<type> &Q3MemArray::duplicate( const Q3MemArray<type> &a ) + + Deep copy. Dereferences the current array and obtains a copy of + the data contained in \a a instead. Returns a reference to this + array. + + \sa copy() +*/ + +/*! + \fn Q3MemArray<type> &Q3MemArray::duplicate( const type *data, uint size ) + + \overload + + Deep copy. Dereferences the current array and obtains a copy of + the array data \a data instead. Returns a reference to this array. + The size of the array is given by \a size. + + \sa copy() +*/ + +/*! + \fn Q3MemArray<type> &Q3MemArray::setRawData( const type *data, uint size ) + + Sets raw data and returns a reference to the array. + + Dereferences the current array and sets the new array data to \a + data and the new array size to \a size. Do not attempt to resize + or re-assign the array data when raw data has been set. Call + resetRawData(\a data, \a size) to reset the array. + + Setting raw data is useful because it sets Q3MemArray data without + allocating memory or copying data. + + Example I (intended use): + \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 3 + + Example II (you don't want to do this): + \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 4 + + \warning If you do not call resetRawData(), Q3MemArray will attempt + to deallocate or reallocate the raw data, which might not be too + good. Be careful. + + \sa resetRawData() +*/ + +/*! + \fn void Q3MemArray::resetRawData( const type *data, uint size ) + + Removes internal references to the raw data that was set using + setRawData(). This means that Q3MemArray no longer has access to + the \a data, so you are free to manipulate \a data as you wish. + You can now use the Q3MemArray without affecting the original \a + data, for example by calling setRawData() with a pointer to some + other data. + + The arguments must be the \a data and length, \a size, that were + passed to setRawData(). This is for consistency checking. + + \sa setRawData() +*/ + +/*! + \fn int Q3MemArray::find( const type &v, uint index ) const + + Finds the first occurrence of \a v, starting at position \a index. + + Returns the position of \a v, or -1 if \a v could not be found. + + \sa contains() +*/ + +/*! + \fn int Q3MemArray::contains( const type &v ) const + + Returns the number of times \a v occurs in the array. + + \sa find() +*/ + +/*! + \fn void Q3MemArray::sort() + + Sorts the array elements in ascending order, using bitwise + comparison (memcmp()). + + \sa bsearch() +*/ + +/*! + \fn int Q3MemArray::bsearch( const type &v ) const + + In a sorted array (as sorted by sort()), finds the first + occurrence of \a v by using a binary search. For a sorted + array this is generally much faster than find(), which does + a linear search. + + Returns the position of \a v, or -1 if \a v could not be found. + + \sa sort(), find() +*/ + +/*! + \fn type &Q3MemArray::operator[]( int index ) const + + Returns a reference to the element at position \a index in the + array. + + This can be used to both read and set an element. Equivalent to + at(). + + \sa at() +*/ + +/*! + \fn type &Q3MemArray::at( uint index ) const + + Returns a reference to the element at position \a index in the array. + + This can be used to both read and set an element. + + \sa operator[]() +*/ + +/*! + \fn Q3MemArray::operator const type *() const + + Cast operator. Returns a pointer to the array. + + \sa data() +*/ + +/*! + \fn bool Q3MemArray::operator==( const Q3MemArray<type> &a ) const + + Returns TRUE if this array is equal to \a a; otherwise returns + FALSE. + + The two arrays are compared bitwise. + + \sa operator!=() +*/ + +/*! + \fn bool Q3MemArray::operator!=( const Q3MemArray<type> &a ) const + + Returns TRUE if this array is different from \a a; otherwise + returns FALSE. + + The two arrays are compared bitwise. + + \sa operator==() +*/ + +/*! + \fn Iterator Q3MemArray::begin() + + Returns an iterator pointing at the beginning of this array. This + iterator can be used in the same way as the iterators of + Q3ValueList and QMap, for example. +*/ + +/*! + \fn Iterator Q3MemArray::end() + + Returns an iterator pointing behind the last element of this + array. This iterator can be used in the same way as the iterators + of Q3ValueList and QMap, for example. +*/ + +/*! + \fn ConstIterator Q3MemArray::begin() const + + \overload + + Returns a const iterator pointing at the beginning of this array. + This iterator can be used in the same way as the iterators of + Q3ValueList and QMap, for example. +*/ + +/*! + \fn ConstIterator Q3MemArray::end() const + + \overload + + Returns a const iterator pointing behind the last element of this + array. This iterator can be used in the same way as the iterators + of Q3ValueList and QMap, for example. +*/ |