diff options
Diffstat (limited to 'doc/src/classes/q3memarray.qdoc')
| -rw-r--r-- | doc/src/classes/q3memarray.qdoc | 523 |
1 files changed, 0 insertions, 523 deletions
diff --git a/doc/src/classes/q3memarray.qdoc b/doc/src/classes/q3memarray.qdoc deleted file mode 100644 index eb0648c..0000000 --- a/doc/src/classes/q3memarray.qdoc +++ /dev/null @@ -1,523 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3MemArray - \brief The Q3MemArray class is a template class that provides arrays of simple types. - \compat - - Q3MemArray is implemented as a template class. Define a template - instance Q3MemArray\<X\> to create an array that contains X items. - - Q3MemArray 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). - Q3MemArray uses bitwise operations to copy and compare array - elements. - - The Q3PtrVector collection class is also a kind of array. Like most - old Qt collection classes, it uses pointers to the contained items. - - Q3MemArray uses explicit sharing 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. - - Example: - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 0 - - Program output: - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 1 - - Note concerning the use of Q3MemArray 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 - Q3MemArray 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: - - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 2 - - 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. - - Q3MemArray 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. -*/ - -/*! \fn Q3MemArray::operator QVector<type>() const - - Automatically converts the Q3MemArray<type> into a QVector<type>. -*/ - -/*! \typedef Q3MemArray::Iterator - A Q3MemArray iterator. - \sa begin() end() -*/ -/*! \typedef Q3MemArray::ConstIterator - A const Q3MemArray iterator. - \sa begin() end() -*/ -/*! \typedef Q3MemArray::ValueType - \internal -*/ - -/*! - \fn Q3MemArray::Q3MemArray() - - Constructs a null array. - - \sa isNull() -*/ - -/*! - \fn Q3MemArray::Q3MemArray( 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 Q3MemArray::Q3MemArray( const Q3MemArray<type> &a ) - - Constructs a shallow copy of \a a. - - \sa assign() -*/ - -/*! - \fn Q3MemArray::Q3MemArray(const QVector<type> &vector) - - Constructs a copy of \a vector. -*/ - -/*! - \fn Q3MemArray::Q3MemArray(int arg1, int arg2) - - Constructs an array \e{without allocating} array space. The - arguments \a arg1 and \a arg2 should be zero. Use at your own - risk. -*/ - -/*! - \fn Q3MemArray::~Q3MemArray() - - Dereferences the array data and deletes it if this was the last - reference. -*/ - -/*! - \fn Q3MemArray<type> &Q3MemArray::operator=( const Q3MemArray<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 *Q3MemArray::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 Q3MemArray::nrefs() const - - Returns the reference count for the shared array data. This - reference count is always greater than zero. -*/ - -/*! - \fn uint Q3MemArray::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 Q3MemArray::count() const - - Returns the same as size(). - - \sa size() -*/ - -/*! - \fn bool Q3MemArray::isEmpty() const - - Returns TRUE if the array is empty; otherwise returns FALSE. - - isEmpty() is equivalent to isNull() for Q3MemArray (unlike - QString). -*/ - -/*! - \fn bool Q3MemArray::isNull() const - - Returns TRUE if the array is null; otherwise returns FALSE. - - A null array has size() == 0 and data() == 0. -*/ - -/*! - \fn bool Q3MemArray::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 Q3GArray::MemOptim (the default) or - Q3GArray::SpeedOptim. When optimizing for speed rather than memory - consumption, the array uses a smart grow and shrink algorithm that - might allocate more memory than is actually needed for \a size - elements. This speeds up subsequent resize operations, for example - when appending many elements to an array, since the space has - already been allocated. - - \sa size() -*/ - -/*! - \fn bool Q3MemArray::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 Q3MemArray::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 Q3MemArray::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 Q3MemArray::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 Q3MemArray<type> Q3MemArray::copy() const - - Returns a deep copy of this array. - - \sa detach(), duplicate() -*/ - -/*! - \fn Q3MemArray<type> &Q3MemArray::assign( const Q3MemArray<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 Q3MemArray<type> &Q3MemArray::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; Q3MemArray will call free() on it - at the right time. -*/ - -/*! - \fn Q3MemArray<type> &Q3MemArray::duplicate( const Q3MemArray<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 Q3MemArray<type> &Q3MemArray::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 Q3MemArray<type> &Q3MemArray::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 Q3MemArray data without - allocating memory or copying data. - - Example I (intended use): - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 3 - - Example II (you don't want to do this): - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 4 - - \warning If you do not call resetRawData(), Q3MemArray will attempt - to deallocate or reallocate the raw data, which might not be too - good. Be careful. - - \sa resetRawData() -*/ - -/*! - \fn void Q3MemArray::resetRawData( const type *data, uint size ) - - Removes internal references to the raw data that was set using - setRawData(). This means that Q3MemArray no longer has access to - the \a data, so you are free to manipulate \a data as you wish. - You can now use the Q3MemArray 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 Q3MemArray::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 Q3MemArray::contains( const type &v ) const - - Returns the number of times \a v occurs in the array. - - \sa find() -*/ - -/*! - \fn void Q3MemArray::sort() - - Sorts the array elements in ascending order, using bitwise - comparison (memcmp()). - - \sa bsearch() -*/ - -/*! - \fn int Q3MemArray::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 &Q3MemArray::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 &Q3MemArray::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 Q3MemArray::operator const type *() const - - Cast operator. Returns a pointer to the array. - - \sa data() -*/ - -/*! - \fn bool Q3MemArray::operator==( const Q3MemArray<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 Q3MemArray::operator!=( const Q3MemArray<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 Q3MemArray::begin() - - Returns an iterator pointing at the beginning of this array. This - iterator can be used in the same way as the iterators of - Q3ValueList and QMap, for example. -*/ - -/*! - \fn Iterator Q3MemArray::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 Q3ValueList and QMap, for example. -*/ - -/*! - \fn ConstIterator Q3MemArray::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 - Q3ValueList and QMap, for example. -*/ - -/*! - \fn ConstIterator Q3MemArray::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 Q3ValueList and QMap, for example. -*/ |