summaryrefslogtreecommitdiffstats
path: root/doc/qmemarray.doc
diff options
context:
space:
mode:
authorMichele Calgaro <michele.calgaro@yahoo.it>2024-07-07 14:56:09 +0900
committerMichele Calgaro <michele.calgaro@yahoo.it>2024-07-07 14:56:09 +0900
commit87d29563e3ccdeb7fea0197e262e667ef323ff9c (patch)
tree2d674f204c5205ca577a782e1b50583afd563972 /doc/qmemarray.doc
parent628b0bb74c3fc327efff8add9c73ada04b1cbea2 (diff)
downloadtqt3-87d29563e3ccdeb7fea0197e262e667ef323ff9c.tar.gz
tqt3-87d29563e3ccdeb7fea0197e262e667ef323ff9c.zip
Rename utility class nt* related files to equivalent tq*
Signed-off-by: Michele Calgaro <michele.calgaro@yahoo.it>
Diffstat (limited to 'doc/qmemarray.doc')
-rw-r--r--doc/qmemarray.doc590
1 files changed, 0 insertions, 590 deletions
diff --git a/doc/qmemarray.doc b/doc/qmemarray.doc
deleted file mode 100644
index 20e2f68b8..000000000
--- a/doc/qmemarray.doc
+++ /dev/null
@@ -1,590 +0,0 @@
-/****************************************************************************
-**
-** QMemArray class documentation
-**
-** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved.
-**
-** This file is part of the TQt 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 TQt 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 ntqmemarray.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 TQPtrVector 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 TQValueVector. The TQValueVector class
- also provides an array of objects, but can deal with objects that
- have constructors (specifically a copy constructor and a default
- constructor). TQValueVector provides an STL-compatible syntax and is
- \link shclass.html implicitly shared\endlink.
-
- Example:
- \code
- #include <ntqmemarray.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++ )
- tqDebug( "%d: %d", i, a[i] );
-
- tqDebug( "1 is found %d times", a.contains(1) );
- tqDebug( "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
- TQString).
-*/
-
-/*!
- \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 TQt 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
- TQValueList and TQMap, 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 TQValueList and TQMap, 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
- TQValueList and TQMap, 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 TQValueList and TQMap, for example.
-*/