qtools/qarray.doc

   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 */