1 /****************************************************************************

     2 ** 

     3 **

     4 ** QArray class documentation

     5 **

     6 ** Copyright (C) 1992-2000 Trolltech AS.  All rights reserved.

     7 **

     8 ** This file is part of the Qt GUI Toolkit.

     9 **

    10 ** This file may be distributed under the terms of the Q Public License

    11 ** as defined by Trolltech AS of Norway and appearing in the file

    12 ** LICENSE.QPL included in the packaging of this file.

    13 **

    14 ** This file may be distributed and/or modified under the terms of the

    15 ** GNU General Public License version 2 as published by the Free Software

    16 ** Foundation and appearing in the file LICENSE.GPL included in the

    17 ** packaging of this file.

    18 **

    19 ** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition

    20 ** licenses may use this file in accordance with the Qt Commercial License

    21 ** Agreement provided with the Software.

    22 **

    23 ** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE

    24 ** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

    25 **

    26 ** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for

    27 **   information about Qt Commercial License Agreements.

    28 ** See http://www.trolltech.com/qpl/ for QPL licensing information.

    29 ** See http://www.trolltech.com/gpl/ for GPL licensing information.

    30 **

    31 ** Contact info@trolltech.com if any conditions of this licensing are

    32 ** not clear to you.

    33 **

    34 **********************************************************************/

    35 

    36 

    37 /*****************************************************************************

    38   QArray documentation

    39  *****************************************************************************/

    40 

    41 /*!

    42   \class QArray qarray.h

    43   \brief The QArray class is a template class that provides arrays of simple types.

    44 

    45   \ingroup tools

    46 

    47   QArray is implemented as a template class. Define a template

    48   instance QArray\<X\> to create an array that contains X items.

    49 

    50   QArray stores the array elements directly in the array. It can only

    51   deal with simple types, i.e. C++ types, structs and classes that have

    52   no constructors, destructors or virtual functions.  QArray uses

    53   bitwise operations to copy and compare array elements.

    54 

    55   The QVector collection class is also a kind of array.  Like most

    56   \link collection.html collection classes\endlink, it has pointers to the

    57   contained items.

    58 

    59   QArray uses explicit \link shclass.html sharing\endlink with a reference

    60   count.  If more than one array share common data, and one array is

    61   modified, all arrays will be modified.

    62 

    63   The benefit of sharing is that a program does not need to duplicate

    64   data when it is not required, which results in less memory usage and

    65   less copying of data.

    66 

    67   Example:

    68   \code

    69     #include <qarray.h>

    70     #include <stdio.h>

    71 

    72     QArray<int> fib( int num )			// returns fibonacci array

    73     {

    74 	ASSERT( num > 2 );

    75 	QArray<int> f( num );			// array of ints

    76 

    77         f[0] = f[1] = 1;			// initialize first two numbers

    78 	for ( int i=2; i<num; i++ )

    79 	    f[i] = f[i-1] + f[i-2];	

    80 

    81 	return f;

    82     }

    83 

    84     void main()

    85     {

    86 	QArray<int> a = fib( 6 );		// get 6 first fibonaccis

    87 	int i;

    88 

    89 	for ( i=0; i<a.size(); i++ )		// print them

    90 	    prinf( "%d: %d\n", i, a[i] );

    91 

    92 	printf( "1 is found %d time(s)\n", a.contains(1) );

    93 	printf( "5 is found at index %d\n", a.find(5) );

    94     }

    95   \endcode

    96 

    97   Program output:

    98   \code

    99 	0: 1

   100 	1: 1

   101 	2: 2

   102 	3: 3

   103 	4: 5

   104 	5: 8

   105 	1 is found 2 times

   106 	5 is found at index 4

   107   \endcode

   108 

   109   Note about using QArray for manipulating structs or classes:

   110   Compilers will often pad the size of structs of odd sizes up to the

   111   nearest word boundary. This will then be the size QArray will use

   112   for its bitwise element comparisons. Since the remaining bytes will

   113   typically be uninitialized, this can cause find() etc. to fail to

   114   find the element. Example:

   115 

   116   \code

   117     struct MyStruct

   118     {

   119       short i;                    // 2 bytes

   120       char c;                     // 1 byte

   121     };                            // sizeof(MyStruct) may be padded to 4 bytes

   122 

   123     QArray<MyStruct> a(1);

   124     a[0].i = 5;

   125     a[0].c = 't';

   126 

   127     MyStruct x;

   128     x.i = '5';

   129     x.c = 't';

   130     int i = a.find( x );          // May return -1 if the pad bytes differ

   131   \endcode

   132 

   133   To workaround this, make sure that you use a struct where sizeof()

   134   returns the same as the sum of the sizes of the members, either by

   135   changing the types of the struct members or by adding dummy members.

   136 

   137   \sa \link shclass.html Shared Classes\endlink

   138 */

   139 

   140 

   141 /*!

   142   \fn QArray::QArray()

   143   Constructs a null array.

   144   \sa isNull()

   145 */

   146 

   147 /*!

   148   \fn QArray::QArray( int size )

   149   Constructs an array with room for \e size elements.

   150   Makes a null array if \e size == 0.

   151 

   152   Note that the elements are not initialized.

   153 

   154   \sa resize(), isNull()

   155 */

   156 

   157 /*!

   158   \fn QArray::QArray( const QArray<type> &a )

   159   Constructs a shallow copy of \e a.

   160   \sa assign()

   161 */

   162 

   163 /*!

   164   \fn QArray::QArray( int, int )

   165   Constructs an array <em>without allocating</em> array space.

   166   The arguments should be (0, 0). Use at own risk.

   167 */

   168 

   169 /*!

   170   \fn QArray::~QArray()

   171   Dereferences the array data and deletes it if this was the last

   172   reference.

   173 */

   174 

   175 /*!

   176   \fn QArray<type> &QArray::operator=( const QArray<type> &a )

   177   Assigns a shallow copy of \e a to this array and returns a reference

   178   to this array.

   179 

   180   Equivalent to assign( a ).

   181 */

   182 

   183 /*!

   184   \fn type *QArray::data() const

   185   Returns a pointer to the actual array data.

   186 

   187   The array is a null array if data() == 0 (null pointer).

   188 

   189   \sa isNull()

   190 */

   191 

   192 /*!

   193   \fn uint QArray::nrefs() const

   194   Returns the reference count for the shared array data. This reference count

   195   is always greater than zero.

   196 */

   197 

   198 /*!

   199   \fn uint QArray::size() const

   200   Returns the size of the array (max number of elements).

   201 

   202   The array is a null array if size() == 0.

   203 

   204   \sa isNull(), resize()

   205 */

   206 

   207 /*!

   208   \fn uint QArray::count() const

   209   Returns the same as size().

   210 

   211   \sa size()

   212 */

   213 

   214 /*!

   215   \fn bool QArray::isEmpty() const

   216   Returns TRUE if the array is empty, i.e. size() == 0, otherwise FALSE.

   217 

   218   isEmpty() is equivalent with isNull() for QArray.  Note that this is not

   219   the case for QCString::isEmpty().

   220 */

   221 

   222 /*!

   223   \fn bool QArray::isNull() const

   224   Returns TRUE if the array is null, otherwise FALSE.

   225 

   226   A null array has size() == 0 and data() == 0.

   227 */

   228 

   229 /*!

   230   \fn bool QArray::resize( uint size )

   231   Resizes (expands or shrinks) the array to \e size elements. The array

   232   becomes a null array if \e size == 0.

   233 

   234   Returns TRUE if successful, or FALSE if the memory cannot be allocated.

   235 

   236   New elements will not be initialized.

   237 

   238   \sa size()

   239 */

   240 

   241 /*!

   242   \fn bool QArray::truncate( uint pos )

   243   Truncates the array at position \e pos.

   244 

   245   Returns TRUE if successful, or FALSE if the memory cannot be allocated.

   246 

   247   Equivalent to resize(\e pos).

   248 

   249   \sa resize()

   250 */

   251 

   252 /*!

   253   \fn bool QArray::fill( const type &v, int size )

   254   Fills the array with the value \e v. If \e size is specified as different

   255   from -1, then the array will be resized before filled.

   256 

   257   Returns TRUE if successful, or FALSE if the memory cannot be allocated

   258   (only when \e size != -1).

   259 

   260   \sa resize()

   261 */

   262 

   263 /*!

   264   \fn void QArray::detach()

   265   Detaches this array from shared array data, i.e. makes a private, deep

   266   copy of the data.

   267 

   268   Copying will only be performed if the

   269   \link nrefs() reference count\endlink is greater than one.

   270 

   271   \sa copy()

   272 */

   273 

   274 /*!

   275   \fn QArray<type> QArray::copy() const

   276   Returns a deep copy of this array.

   277   \sa detach(), duplicate()

   278 */

   279 

   280 /*!

   281   \fn QArray<type> &QArray::assign( const QArray<type> &a )

   282   Shallow copy. Dereferences the current array and references the data

   283   contained in \e a instead. Returns a reference to this array.

   284   \sa operator=()

   285 */

   286 

   287 /*!

   288   \fn QArray<type> &QArray::assign( const type *data, uint size )

   289   Shallow copy. Dereferences the current array and references the

   290   array data \e data, which contains \e size elements.

   291   Returns a reference to this array.

   292 

   293   Do not delete \e data later, QArray takes care of that.

   294 */

   295 

   296 /*!

   297   \fn QArray<type> &QArray::duplicate( const QArray<type> &a )

   298   Deep copy. Dereferences the current array and obtains a copy of the data

   299   contained in \e a instead. Returns a reference to this array.

   300   \sa copy()

   301 */

   302 

   303 /*!

   304   \fn QArray<type> &QArray::duplicate( const type *data, uint size )

   305   Deep copy. Dereferences the current array and obtains a copy of the

   306   array data \e data instead.  Returns a reference to this array.

   307   \sa copy()

   308 */

   309 

   310 /*!

   311   \fn QArray<type> &QArray::setRawData( const type *data, uint size )

   312 

   313   Sets raw data and returns a reference to the array.

   314 

   315   Dereferences the current array and sets the new array data to \e data and

   316   the new array size to \e size.  Do not attempt to resize or re-assign the

   317   array data when raw data has been set.

   318   Call resetRawData(d,len) to reset the array.

   319 

   320   Setting raw data is useful because it sets QArray data without allocating

   321   memory or copying data.

   322 

   323   Example I (intended use):

   324   \code

   325     static char bindata[] = { 231, 1, 44, ... };

   326     QByteArray	a;

   327     a.setRawData( bindata, sizeof(bindata) );	// a points to bindata

   328     QDataStream s( a, IO_ReadOnly );		// open on a's data

   329     s >> <something>;				// read raw bindata

   330     a.resetRawData( bindata, sizeof(bindata) ); // finished

   331   \endcode

   332 

   333   Example II (you don't want to do this):

   334   \code

   335     static char bindata[] = { 231, 1, 44, ... };

   336     QByteArray	a, b;

   337     a.setRawData( bindata, sizeof(bindata) );	// a points to bindata

   338     a.resize( 8 );				// will crash

   339     b = a;					// will crash

   340     a[2] = 123;					// might crash

   341       // forget to resetRawData - will crash

   342   \endcode

   343 

   344   \warning If you do not call resetRawData(), QArray will attempt to

   345   deallocate or reallocate the raw data, which might not be too good.

   346   Be careful.

   347 

   348   \sa resetRawData()

   349 */

   350 

   351 /*!

   352   \fn void QArray::resetRawData( const type *data, uint size )

   353   Resets raw data that was set using setRawData().

   354 

   355   The arguments must be the data and length that were passed to

   356   setRawData().	 This is for consistency checking.

   357 

   358   \sa setRawData()

   359 */

   360 

   361 /*!

   362   \fn int QArray::find( const type &v, uint index ) const

   363   Finds the first occurrence of \e v, starting at position \e index.

   364 

   365   Returns the position of \e v, or -1 if \e v could not be found.

   366 

   367   \sa contains()

   368 */

   369 

   370 /*!

   371   \fn int QArray::contains( const type &v ) const

   372   Returns the number of times \e v occurs in the array.

   373   \sa find()

   374 */

   375 

   376 /*!

   377   \fn void QArray::sort()

   378   Sorts the array elements in ascending order, using bitwise

   379   comparison (memcmp()).

   380 

   381   \sa bsearch()

   382 */

   383 

   384 /*!

   385   \fn int QArray::bsearch( const type &v ) const

   386   In a sorted array, finds the first occurrence of \e v using binary

   387   search. For a sorted array, this is generally much faster than

   388   find(), which does a linear search.

   389 

   390   Returns the position of \e v, or -1 if \e v could not be found.

   391 

   392   \sa sort(), find()

   393 */

   394 

   395 /*!

   396   \fn type &QArray::operator[]( int index ) const

   397   Returns a reference to the element at position \e index in the array.

   398 

   399   This can be used to both read and set an element.  Equivalent to at().

   400 

   401   \sa at()

   402 */

   403 

   404 /*!

   405   \fn type &QArray::at( uint index ) const

   406   Returns a reference to the element at position \e index in the array.

   407 

   408   This can be used to both read and set an element.

   409 

   410   \sa operator[]()

   411 */

   412 

   413 /*!

   414   \fn QArray::operator const type *() const

   415   Cast operator.  Returns a pointer to the array.

   416   \sa data()

   417 */

   418 

   419 /*!

   420   \fn bool QArray::operator==( const QArray<type> &a ) const

   421   Returns TRUE if this array is equal to \e a, otherwise FALSE.

   422 

   423   The two arrays are bitwise compared.

   424 

   425   \sa operator!=()

   426 */

   427 

   428 /*!

   429   \fn bool QArray::operator!=( const QArray<type> &a ) const

   430   Returns TRUE if this array is different from \e a, otherwise FALSE.

   431 

   432   The two arrays are bitwise compared.

   433 

   434   \sa operator==()

   435 */

   436 

   437 /*!

   438   \fn Iterator QArray::begin()

   439   Returns an iterator pointing at the beginning of this array.

   440   This iterator can be used as the iterators of QValueList and QMap

   441   for example. In fact it does not only behave like a usual pointer:

   442   It is a pointer.

   443 */

   444 

   445 /*!

   446   \fn Iterator QArray::end()

   447   Returns an iterator pointing behind the last element of this array.

   448   This iterator can be used as the iterators of QValueList and QMap

   449   for example. In fact it does not only behave like a usual pointer:

   450   It is a pointer.

   451 */

   452 

   453 /*!

   454   \fn ConstIterator QArray::begin() const

   455   Returns a const iterator pointing at the beginning of this array.

   456   This iterator can be used as the iterators of QValueList and QMap

   457   for example. In fact it does not only behave like a usual pointer:

   458   It is a pointer.

   459 */

   460 

   461 /*!

   462   \fn ConstIterator QArray::end() const

   463   Returns a const iterator pointing behind the last element of this array.

   464   This iterator can be used as the iterators of QValueList and QMap

   465   for example. In fact it does not only behave like a usual pointer:

   466   It is a pointer.

   467 */

   468 

   469 

   470 /*****************************************************************************

   471   QByteArray documentation

   472  *****************************************************************************/

   473 

   474 /*!

   475   \class QByteArray qcstring.h

   476   \brief The QByteArray class provides an array of bytes.

   477 

   478   \inherit QArray

   479 

   480   \ingroup tools

   481 

   482   The QByteArray class provides an explicitly shared array of

   483   bytes. It is useful for manipulating memory areas with custom

   484   data. QByteArray is implemented as QArray<char>. See the QArray

   485   documentation for further information.

   486 */