diff options
Diffstat (limited to 'qtools/qarray.doc')
| -rw-r--r-- | qtools/qarray.doc | 486 |
1 files changed, 486 insertions, 0 deletions
diff --git a/qtools/qarray.doc b/qtools/qarray.doc new file mode 100644 index 0000000..d5a606e --- /dev/null +++ b/qtools/qarray.doc @@ -0,0 +1,486 @@ +/**************************************************************************** +** $Id$ +** +** QArray class documentation +** +** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be distributed under the terms of the Q Public License +** as defined by Trolltech AS of Norway and appearing in the file +** LICENSE.QPL included in the packaging of this file. +** +** This file may be distributed and/or modified under the terms of the +** GNU General Public License version 2 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. +** +** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition +** 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 +** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +** +** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for +** information about Qt Commercial License Agreements. +** See http://www.trolltech.com/qpl/ for QPL licensing information. +** See http://www.trolltech.com/gpl/ for GPL licensing information. +** +** Contact info@trolltech.com if any conditions of this licensing are +** not clear to you. +** +**********************************************************************/ + + +/***************************************************************************** + QArray documentation + *****************************************************************************/ + +/*! + \class QArray qarray.h + \brief The QArray class is a template class that provides arrays of simple types. + + \ingroup tools + + QArray is implemented as a template class. Define a template + instance QArray\<X\> to create an array that contains X items. + + QArray 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. QArray uses + bitwise operations to copy and compare array elements. + + The QVector collection class is also a kind of array. Like most + \link collection.html collection classes\endlink, it has pointers to the + contained items. + + QArray uses explicit \link shclass.html sharing\endlink with a reference + count. If more than one array share common data, and one array is + modified, all arrays will be modified. + + The benefit of sharing is that a program does not need to duplicate + data when it is not required, which results in less memory usage and + less copying of data. + + Example: + \code + #include <qarray.h> + #include <stdio.h> + + QArray<int> fib( int num ) // returns fibonacci array + { + ASSERT( num > 2 ); + QArray<int> f( num ); // array of ints + + f[0] = f[1] = 1; // initialize first two numbers + for ( int i=2; i<num; i++ ) + f[i] = f[i-1] + f[i-2]; + + return f; + } + + void main() + { + QArray<int> a = fib( 6 ); // get 6 first fibonaccis + int i; + + for ( i=0; i<a.size(); i++ ) // print them + prinf( "%d: %d\n", i, a[i] ); + + printf( "1 is found %d time(s)\n", a.contains(1) ); + printf( "5 is found at index %d\n", a.find(5) ); + } + \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 about using QArray 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 QArray will use + for its bitwise element comparisons. Since the remaining bytes will + typically be uninitialized, this can cause find() etc. to fail to + find the element. Example: + + \code + struct MyStruct + { + short i; // 2 bytes + char c; // 1 byte + }; // sizeof(MyStruct) may be padded to 4 bytes + + QArray<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 workaround 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. + + \sa \link shclass.html Shared Classes\endlink +*/ + + +/*! + \fn QArray::QArray() + Constructs a null array. + \sa isNull() +*/ + +/*! + \fn QArray::QArray( int size ) + Constructs an array with room for \e size elements. + Makes a null array if \e size == 0. + + Note that the elements are not initialized. + + \sa resize(), isNull() +*/ + +/*! + \fn QArray::QArray( const QArray<type> &a ) + Constructs a shallow copy of \e a. + \sa assign() +*/ + +/*! + \fn QArray::QArray( int, int ) + Constructs an array <em>without allocating</em> array space. + The arguments should be (0, 0). Use at own risk. +*/ + +/*! + \fn QArray::~QArray() + Dereferences the array data and deletes it if this was the last + reference. +*/ + +/*! + \fn QArray<type> &QArray::operator=( const QArray<type> &a ) + Assigns a shallow copy of \e a to this array and returns a reference + to this array. + + Equivalent to assign( a ). +*/ + +/*! + \fn type *QArray::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 QArray::nrefs() const + Returns the reference count for the shared array data. This reference count + is always greater than zero. +*/ + +/*! + \fn uint QArray::size() const + Returns the size of the array (max number of elements). + + The array is a null array if size() == 0. + + \sa isNull(), resize() +*/ + +/*! + \fn uint QArray::count() const + Returns the same as size(). + + \sa size() +*/ + +/*! + \fn bool QArray::isEmpty() const + Returns TRUE if the array is empty, i.e. size() == 0, otherwise FALSE. + + isEmpty() is equivalent with isNull() for QArray. Note that this is not + the case for QCString::isEmpty(). +*/ + +/*! + \fn bool QArray::isNull() const + Returns TRUE if the array is null, otherwise FALSE. + + A null array has size() == 0 and data() == 0. +*/ + +/*! + \fn bool QArray::resize( uint size ) + Resizes (expands or shrinks) the array to \e size elements. The array + becomes a null array if \e size == 0. + + Returns TRUE if successful, or FALSE if the memory cannot be allocated. + + New elements will not be initialized. + + \sa size() +*/ + +/*! + \fn bool QArray::truncate( uint pos ) + Truncates the array at position \e pos. + + Returns TRUE if successful, or FALSE if the memory cannot be allocated. + + Equivalent to resize(\e pos). + + \sa resize() +*/ + +/*! + \fn bool QArray::fill( const type &v, int size ) + Fills the array with the value \e v. If \e size is specified as different + from -1, then the array will be resized before filled. + + Returns TRUE if successful, or FALSE if the memory cannot be allocated + (only when \e size != -1). + + \sa resize() +*/ + +/*! + \fn void QArray::detach() + Detaches this array from shared array data, i.e. makes a private, deep + copy of the data. + + Copying will only be performed if the + \link nrefs() reference count\endlink is greater than one. + + \sa copy() +*/ + +/*! + \fn QArray<type> QArray::copy() const + Returns a deep copy of this array. + \sa detach(), duplicate() +*/ + +/*! + \fn QArray<type> &QArray::assign( const QArray<type> &a ) + Shallow copy. Dereferences the current array and references the data + contained in \e a instead. Returns a reference to this array. + \sa operator=() +*/ + +/*! + \fn QArray<type> &QArray::assign( const type *data, uint size ) + Shallow copy. Dereferences the current array and references the + array data \e data, which contains \e size elements. + Returns a reference to this array. + + Do not delete \e data later, QArray takes care of that. +*/ + +/*! + \fn QArray<type> &QArray::duplicate( const QArray<type> &a ) + Deep copy. Dereferences the current array and obtains a copy of the data + contained in \e a instead. Returns a reference to this array. + \sa copy() +*/ + +/*! + \fn QArray<type> &QArray::duplicate( const type *data, uint size ) + Deep copy. Dereferences the current array and obtains a copy of the + array data \e data instead. Returns a reference to this array. + \sa copy() +*/ + +/*! + \fn QArray<type> &QArray::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 \e data and + the new array size to \e size. Do not attempt to resize or re-assign the + array data when raw data has been set. + Call resetRawData(d,len) to reset the array. + + Setting raw data is useful because it sets QArray 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(), QArray will attempt to + deallocate or reallocate the raw data, which might not be too good. + Be careful. + + \sa resetRawData() +*/ + +/*! + \fn void QArray::resetRawData( const type *data, uint size ) + Resets raw data that was set using setRawData(). + + The arguments must be the data and length that were passed to + setRawData(). This is for consistency checking. + + \sa setRawData() +*/ + +/*! + \fn int QArray::find( const type &v, uint index ) const + Finds the first occurrence of \e v, starting at position \e index. + + Returns the position of \e v, or -1 if \e v could not be found. + + \sa contains() +*/ + +/*! + \fn int QArray::contains( const type &v ) const + Returns the number of times \e v occurs in the array. + \sa find() +*/ + +/*! + \fn void QArray::sort() + Sorts the array elements in ascending order, using bitwise + comparison (memcmp()). + + \sa bsearch() +*/ + +/*! + \fn int QArray::bsearch( const type &v ) const + In a sorted array, finds the first occurrence of \e v using binary + search. For a sorted array, this is generally much faster than + find(), which does a linear search. + + Returns the position of \e v, or -1 if \e v could not be found. + + \sa sort(), find() +*/ + +/*! + \fn type &QArray::operator[]( int index ) const + Returns a reference to the element at position \e index in the array. + + This can be used to both read and set an element. Equivalent to at(). + + \sa at() +*/ + +/*! + \fn type &QArray::at( uint index ) const + Returns a reference to the element at position \e index in the array. + + This can be used to both read and set an element. + + \sa operator[]() +*/ + +/*! + \fn QArray::operator const type *() const + Cast operator. Returns a pointer to the array. + \sa data() +*/ + +/*! + \fn bool QArray::operator==( const QArray<type> &a ) const + Returns TRUE if this array is equal to \e a, otherwise FALSE. + + The two arrays are bitwise compared. + + \sa operator!=() +*/ + +/*! + \fn bool QArray::operator!=( const QArray<type> &a ) const + Returns TRUE if this array is different from \e a, otherwise FALSE. + + The two arrays are bitwise compared. + + \sa operator==() +*/ + +/*! + \fn Iterator QArray::begin() + Returns an iterator pointing at the beginning of this array. + This iterator can be used as the iterators of QValueList and QMap + for example. In fact it does not only behave like a usual pointer: + It is a pointer. +*/ + +/*! + \fn Iterator QArray::end() + Returns an iterator pointing behind the last element of this array. + This iterator can be used as the iterators of QValueList and QMap + for example. In fact it does not only behave like a usual pointer: + It is a pointer. +*/ + +/*! + \fn ConstIterator QArray::begin() const + Returns a const iterator pointing at the beginning of this array. + This iterator can be used as the iterators of QValueList and QMap + for example. In fact it does not only behave like a usual pointer: + It is a pointer. +*/ + +/*! + \fn ConstIterator QArray::end() const + Returns a const iterator pointing behind the last element of this array. + This iterator can be used as the iterators of QValueList and QMap + for example. In fact it does not only behave like a usual pointer: + It is a pointer. +*/ + + +/***************************************************************************** + QByteArray documentation + *****************************************************************************/ + +/*! + \class QByteArray qcstring.h + \brief The QByteArray class provides an array of bytes. + + \inherit QArray + + \ingroup tools + + The QByteArray class provides an explicitly shared array of + bytes. It is useful for manipulating memory areas with custom + data. QByteArray is implemented as QArray<char>. See the QArray + documentation for further information. +*/ |