Release-1.2.11-20011021

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.
+*/