You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
591 lines
15 KiB
591 lines
15 KiB
/****************************************************************************
|
|
**
|
|
** 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 requirements 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 required, 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 requires 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.
|
|
*/
|