Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731

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 sales@trolltech.com.
+**
+** 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. 
+*/