diff options
Diffstat (limited to 'doc/qmemarray.doc')
| -rw-r--r-- | doc/qmemarray.doc | 590 |
1 files changed, 590 insertions, 0 deletions
diff --git a/doc/qmemarray.doc b/doc/qmemarray.doc new file mode 100644 index 000000000..f849222eb --- /dev/null +++ b/doc/qmemarray.doc @@ -0,0 +1,590 @@ +/**************************************************************************** +** +** QMemArray class documentation +** +** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be used under the terms of the GNU General +** Public License versions 2.0 or 3.0 as published by the Free +** Software Foundation and appearing in the files LICENSE.GPL2 +** and LICENSE.GPL3 included in the packaging of this file. +** Alternatively you may (at your option) use any later version +** of the GNU General Public License if such license has been +** publicly approved by Trolltech ASA (or its successors, if any) +** and the KDE Free Qt Foundation. +** +** Please review the following information to ensure GNU General +** Public Licensing retquirements will be met: +** http://trolltech.com/products/qt/licenses/licensing/opensource/. +** If you are unsure which license is appropriate for your use, please +** review the following information: +** http://trolltech.com/products/qt/licenses/licensing/licensingoverview +** or contact the sales department at [email protected]. +** +** This file may be used under the terms of the Q Public License as +** defined by Trolltech ASA and appearing in the file LICENSE.QPL +** included in the packaging of this file. Licensees holding valid Qt +** Commercial licenses may use this file in accordance with the Qt +** Commercial License Agreement provided with the Software. +** +** This file is provided "AS IS" with NO WARRANTY OF ANY KIND, +** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted +** herein. +** +**********************************************************************/ + + +/***************************************************************************** + QMemArray documentation + *****************************************************************************/ + +/*! + \class QMemArray qmemarray.h + \reentrant + \brief The QMemArray class is a template class that provides arrays of simple types. + + \ingroup tools + + QMemArray is implemented as a template class. Define a template + instance QMemArray\<X\> to create an array that contains X items. + + QMemArray 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). + QMemArray uses bitwise operations to copy and compare array + elements. + + The QPtrVector collection class is also a kind of array. Like most + \link collection.html collection classes\endlink, it uses pointers + to the contained items. + + QMemArray uses \link shclass.html explicit sharing\endlink 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 retquired, which results in lower memory use + and less copying of data. + + An alternative to QMemArray is QValueVector. The QValueVector class + also provides an array of objects, but can deal with objects that + have constructors (specifically a copy constructor and a default + constructor). QValueVector provides an STL-compatible syntax and is + \link shclass.html implicitly shared\endlink. + + Example: + \code + #include <qmemarray.h> + #include <stdio.h> + + QMemArray<int> fib( int num ) // returns fibonacci array + { + Q_ASSERT( num > 2 ); + QMemArray<int> f( num ); // array of ints + + f[0] = f[1] = 1; + for ( int i = 2; i < num; i++ ) + f[i] = f[i-1] + f[i-2]; + + return f; + } + + int main() + { + QMemArray<int> a = fib( 6 ); // get first 6 fibonaccis + for ( int i = 0; i < a.size(); i++ ) + qDebug( "%d: %d", i, a[i] ); + + qDebug( "1 is found %d times", a.contains(1) ); + qDebug( "5 is found at index %d", a.find(5) ); + + return 0; + } + \endcode + + Program output: + \code + 0: 1 + 1: 1 + 2: 2 + 3: 3 + 4: 5 + 5: 8 + 1 is found 2 times + 5 is found at index 4 + \endcode + + Note concerning the use of QMemArray 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 + QMemArray 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: + + \code + // MyStruct may be padded to 4 or 8 bytes + struct MyStruct + { + short i; // 2 bytes + char c; // 1 byte + }; + + QMemArray<MyStruct> a(1); + a[0].i = 5; + a[0].c = 't'; + + MyStruct x; + x.i = '5'; + x.c = 't'; + int i = a.find( x ); // may return -1 if the pad bytes differ + \endcode + + 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. + + QMemArray 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 retquires care. + + \sa \link shclass.html Shared Classes\endlink +*/ + +/*! \enum QMemArray::Iterator + A QMemArray iterator. + \sa begin() end() +*/ +/*! \enum QMemArray::ConstIterator + A const QMemArray iterator. + \sa begin() end() +*/ +/*! \enum QMemArray::ValueType + \internal +*/ + +/*! + \fn QMemArray::QMemArray() + + Constructs a null array. + + \sa isNull() +*/ + +/*! + \fn QMemArray::QMemArray( 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 QMemArray::QMemArray( const QMemArray<type> &a ) + + Constructs a shallow copy of \a a. + + \sa assign() +*/ + +/*! + \fn QMemArray::QMemArray( int, int ) + + Constructs an array \e{without allocating} array space. The + arguments should be (0, 0). Use at your own risk. +*/ + +/*! + \fn QMemArray::~QMemArray() + + Dereferences the array data and deletes it if this was the last + reference. +*/ + +/*! + \fn QMemArray<type> &QMemArray::operator=( const QMemArray<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 *QMemArray::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 QMemArray::nrefs() const + + Returns the reference count for the shared array data. This + reference count is always greater than zero. +*/ + +/*! + \fn uint QMemArray::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 QMemArray::count() const + + Returns the same as size(). + + \sa size() +*/ + +/*! + \fn bool QMemArray::isEmpty() const + + Returns TRUE if the array is empty; otherwise returns FALSE. + + isEmpty() is equivalent to isNull() for QMemArray (unlike + QString). +*/ + +/*! + \fn bool QMemArray::isNull() const + + Returns TRUE if the array is null; otherwise returns FALSE. + + A null array has size() == 0 and data() == 0. +*/ + +/*! + \fn bool QMemArray::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 \c QGArray::MemOptim (the default) or + \c QGArray::SpeedOptim. + + <b>Note:</b> By default, \c SpeedOptim is not available for general + use since it is only available if Qt is built in a particular + configuration. + + \sa size() +*/ + +/*! + \fn bool QMemArray::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 QMemArray::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 QMemArray::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 QMemArray::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 QMemArray<type> QMemArray::copy() const + + Returns a deep copy of this array. + + \sa detach(), duplicate() +*/ + +/*! + \fn QMemArray<type> &QMemArray::assign( const QMemArray<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 QMemArray<type> &QMemArray::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; QMemArray will call free() on it + at the right time. +*/ + +/*! + \fn QMemArray<type> &QMemArray::duplicate( const QMemArray<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 QMemArray<type> &QMemArray::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 QMemArray<type> &QMemArray::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 QMemArray data without + allocating memory or copying data. + + Example I (intended use): + \code + static char bindata[] = { 231, 1, 44, ... }; + QByteArray a; + a.setRawData( bindata, sizeof(bindata) ); // a points to bindata + QDataStream s( a, IO_ReadOnly ); // open on a's data + s >> <something>; // read raw bindata + a.resetRawData( bindata, sizeof(bindata) ); // finished + \endcode + + Example II (you don't want to do this): + \code + static char bindata[] = { 231, 1, 44, ... }; + QByteArray a, b; + a.setRawData( bindata, sizeof(bindata) ); // a points to bindata + a.resize( 8 ); // will crash + b = a; // will crash + a[2] = 123; // might crash + // forget to resetRawData: will crash + \endcode + + \warning If you do not call resetRawData(), QMemArray will attempt + to deallocate or reallocate the raw data, which might not be too + good. Be careful. + + \sa resetRawData() +*/ + +/*! + \fn void QMemArray::resetRawData( const type *data, uint size ) + + Removes internal references to the raw data that was set using + setRawData(). This means that QMemArray no longer has access to + the \a data, so you are free to manipulate \a data as you wish. + You can now use the QMemArray 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 QMemArray::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 QMemArray::contains( const type &v ) const + + Returns the number of times \a v occurs in the array. + + \sa find() +*/ + +/*! + \fn void QMemArray::sort() + + Sorts the array elements in ascending order, using bitwise + comparison (memcmp()). + + \sa bsearch() +*/ + +/*! + \fn int QMemArray::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 &QMemArray::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 &QMemArray::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 QMemArray::operator const type *() const + + Cast operator. Returns a pointer to the array. + + \sa data() +*/ + +/*! + \fn bool QMemArray::operator==( const QMemArray<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 QMemArray::operator!=( const QMemArray<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 QMemArray::begin() + + Returns an iterator pointing at the beginning of this array. This + iterator can be used in the same way as the iterators of + QValueList and QMap, for example. +*/ + +/*! + \fn Iterator QMemArray::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 QValueList and QMap, for example. +*/ + +/*! + \fn ConstIterator QMemArray::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 + QValueList and QMap, for example. +*/ + +/*! + \fn ConstIterator QMemArray::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 QValueList and QMap, for example. +*/ |