From 883b84589e5a6108dacb9f3df9f7a41369940ca5 Mon Sep 17 00:00:00 2001 From: Dimitri van Heesch Date: Sun, 21 Oct 2001 18:02:53 +0000 Subject: Release-1.2.11-20011021 --- INSTALL | 4 +- README | 4 +- VERSION | 2 +- doc/install.doc | 2 +- doc/maintainers.txt | 1 + doc/translator.pl | 6 + packages/rpm/doxygen.spec | 2 +- qtools/Doxyfile | 19 +- qtools/qarray.doc | 486 +++++++++++++++++++++ qtools/qdict.doc | 492 +++++++++++++++++++++ qtools/qintdict.doc | 475 ++++++++++++++++++++ qtools/qlist.doc | 1048 +++++++++++++++++++++++++++++++++++++++++++++ qtools/qptrdict.doc | 486 +++++++++++++++++++++ qtools/qsortedlist.doc | 94 ++++ qtools/qstack.doc | 135 ++++++ qtools/qstrlist.doc | 5 + qtools/qtl.doc | 249 +++++++++++ qtools/qvaluelist.doc | 772 +++++++++++++++++++++++++++++++++ qtools/qvector.doc | 344 +++++++++++++++ src/classdef.cpp | 53 +-- src/code.l | 2 - src/doc.l | 2 +- src/doxygen.cpp | 39 +- src/doxytag.l | 1 + src/latexgen.cpp | 7 +- src/scanner.l | 2 +- src/translator_cn.h | 961 ++++++++++++++++++++++++++++++++--------- src/translator_ru.h | 14 +- src/translator_si.h | 442 ++++++++++++++++--- src/util.cpp | 21 +- src/util.h | 2 +- 31 files changed, 5833 insertions(+), 339 deletions(-) create mode 100644 qtools/qarray.doc create mode 100644 qtools/qdict.doc create mode 100644 qtools/qintdict.doc create mode 100644 qtools/qlist.doc create mode 100644 qtools/qptrdict.doc create mode 100644 qtools/qsortedlist.doc create mode 100644 qtools/qstack.doc create mode 100644 qtools/qstrlist.doc create mode 100644 qtools/qtl.doc create mode 100644 qtools/qvaluelist.doc create mode 100644 qtools/qvector.doc diff --git a/INSTALL b/INSTALL index e1eba20..f7c83c5 100644 --- a/INSTALL +++ b/INSTALL @@ -1,6 +1,6 @@ -DOXYGEN Version 1.2.11-20011014 +DOXYGEN Version 1.2.11-20011021 Please read the installation section of the manual for instructions. -------- -Dimitri van Heesch (14 October 2001) +Dimitri van Heesch (21 October 2001) diff --git a/README b/README index 90f939f..bf7785f 100644 --- a/README +++ b/README @@ -1,4 +1,4 @@ -DOXYGEN Version 1.2.11_20011014 +DOXYGEN Version 1.2.11_20011021 Please read INSTALL for compilation instructions. @@ -17,4 +17,4 @@ to subscribe to the lists or to visit the archives. Enjoy, -Dimitri van Heesch (dimitri@stack.nl) (14 October 2001) +Dimitri van Heesch (dimitri@stack.nl) (21 October 2001) diff --git a/VERSION b/VERSION index 431edf0..2ed0956 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.2.11-20011014 +1.2.11-20011021 diff --git a/doc/install.doc b/doc/install.doc index d32e762..1025961 100644 --- a/doc/install.doc +++ b/doc/install.doc @@ -520,7 +520,7 @@ the bin directory of the distribution to the path. For running doxywizard you need to install the non-commercial version of the Qt library first. This library can be downloaded from -http://www.trolltech.com/products/download/freelicense/noncommercial-dl.html +http://www.trolltech.com/products/download/qt-win-noncomm.html \subsection build_tools Tools used to develop doxygen diff --git a/doc/maintainers.txt b/doc/maintainers.txt index 646f6c1..d0a7188 100644 --- a/doc/maintainers.txt +++ b/doc/maintainers.txt @@ -5,6 +5,7 @@ Brazilian Fabio "FJTC" Jun Takada Chino: chino@grad.icmc.sc.usp.br Chinese +Wei Liu: liuwei@asiainfo.com Wang Weihan: wangweihan@capinfo.com.cn Croatian diff --git a/doc/translator.pl b/doc/translator.pl index e031674..a3021fa 100644 --- a/doc/translator.pl +++ b/doc/translator.pl @@ -77,6 +77,11 @@ # the simplified language.doc from the template was moved to # the separate function CopyTemplateToLanguageDoc(). # +# 2001/10/17 +# - Minor update of GetInfoFrom() to ignore spaces between the +# method identifier and the opening parenthesis to match better +# the method prototype with the one in the translator.h. +# ################################################################ use 5.005; @@ -316,6 +321,7 @@ sub GetInfoFrom ##{{{ $cont =~ s{^\s+}{}s; $cont =~ s{\s+$}{}s; + $cont =~ s{\s+\(}{(}g; $cont =~ s{\)\s*}{)\n}g; # Split the string and add it to the ouptut list. diff --git a/packages/rpm/doxygen.spec b/packages/rpm/doxygen.spec index 18b7384..a901d09 100644 --- a/packages/rpm/doxygen.spec +++ b/packages/rpm/doxygen.spec @@ -1,5 +1,5 @@ Name: doxygen -Version: 1.2.11_20011014 +Version: 1.2.11_20011021 Summary: documentation system for C, C++ and IDL Release: 4 Source: doxygen-%{version}.src.tar.gz diff --git a/qtools/Doxyfile b/qtools/Doxyfile index 8a54cc9..838a299 100644 --- a/qtools/Doxyfile +++ b/qtools/Doxyfile @@ -51,21 +51,10 @@ WARN_LOGFILE = #--------------------------------------------------------------------------- # configuration options related to the input files #--------------------------------------------------------------------------- -INPUT = . \ - $(QTDIR)/src/doc/qarray.doc \ - $(QTDIR)/src/doc/qdict.doc \ - $(QTDIR)/src/doc/qintdict.doc \ - $(QTDIR)/src/doc/qlist.doc \ - $(QTDIR)/src/doc/qptrdict.doc \ - $(QTDIR)/src/doc/qsortedlist.doc \ - $(QTDIR)/src/doc/qstack.doc \ - $(QTDIR)/src/doc/qstrlist.doc \ - $(QTDIR)/src/doc/qvector.doc \ - $(QTDIR)/src/doc/qvaluelist.doc \ - $(QTDIR)/src/doc/qtl.doc +INPUT = . FILE_PATTERNS = *.h \ *.cpp \ - q*.doc + *.doc RECURSIVE = NO EXCLUDE_PATTERNS = EXAMPLE_PATH = @@ -77,8 +66,8 @@ FILTER_SOURCE_FILES = NO # configuration options related to the alphabetical class index #--------------------------------------------------------------------------- ALPHABETICAL_INDEX = YES -COLS_IN_ALPHA_INDEX = 5 -IGNORE_PREFIX = +COLS_IN_ALPHA_INDEX = 4 +IGNORE_PREFIX = Q #--------------------------------------------------------------------------- # configuration options related to the HTML output #--------------------------------------------------------------------------- diff --git a/qtools/qarray.doc b/qtools/qarray.doc new file mode 100644 index 0000000..d5a606e --- /dev/null +++ b/qtools/qarray.doc @@ -0,0 +1,486 @@ +/**************************************************************************** +** $Id$ +** +** QArray class documentation +** +** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be distributed under the terms of the Q Public License +** as defined by Trolltech AS of Norway and appearing in the file +** LICENSE.QPL included in the packaging of this file. +** +** This file may be distributed and/or modified under the terms of the +** GNU General Public License version 2 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. +** +** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition +** 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 +** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +** +** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for +** information about Qt Commercial License Agreements. +** See http://www.trolltech.com/qpl/ for QPL licensing information. +** See http://www.trolltech.com/gpl/ for GPL licensing information. +** +** Contact info@trolltech.com if any conditions of this licensing are +** not clear to you. +** +**********************************************************************/ + + +/***************************************************************************** + QArray documentation + *****************************************************************************/ + +/*! + \class QArray qarray.h + \brief The QArray class is a template class that provides arrays of simple types. + + \ingroup tools + + QArray is implemented as a template class. Define a template + instance QArray\ to create an array that contains X items. + + QArray 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. QArray uses + bitwise operations to copy and compare array elements. + + The QVector collection class is also a kind of array. Like most + \link collection.html collection classes\endlink, it has pointers to the + contained items. + + QArray uses explicit \link shclass.html sharing\endlink with a reference + count. If more than one array share common data, and one array is + modified, all arrays will be modified. + + The benefit of sharing is that a program does not need to duplicate + data when it is not required, which results in less memory usage and + less copying of data. + + Example: + \code + #include + #include + + QArray fib( int num ) // returns fibonacci array + { + ASSERT( num > 2 ); + QArray f( num ); // array of ints + + f[0] = f[1] = 1; // initialize first two numbers + for ( int i=2; i a = fib( 6 ); // get 6 first fibonaccis + int i; + + for ( i=0; i 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 workaround 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. + + \sa \link shclass.html Shared Classes\endlink +*/ + + +/*! + \fn QArray::QArray() + Constructs a null array. + \sa isNull() +*/ + +/*! + \fn QArray::QArray( int size ) + Constructs an array with room for \e size elements. + Makes a null array if \e size == 0. + + Note that the elements are not initialized. + + \sa resize(), isNull() +*/ + +/*! + \fn QArray::QArray( const QArray &a ) + Constructs a shallow copy of \e a. + \sa assign() +*/ + +/*! + \fn QArray::QArray( int, int ) + Constructs an array without allocating array space. + The arguments should be (0, 0). Use at own risk. +*/ + +/*! + \fn QArray::~QArray() + Dereferences the array data and deletes it if this was the last + reference. +*/ + +/*! + \fn QArray &QArray::operator=( const QArray &a ) + Assigns a shallow copy of \e a to this array and returns a reference + to this array. + + Equivalent to assign( a ). +*/ + +/*! + \fn type *QArray::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 QArray::nrefs() const + Returns the reference count for the shared array data. This reference count + is always greater than zero. +*/ + +/*! + \fn uint QArray::size() const + Returns the size of the array (max number of elements). + + The array is a null array if size() == 0. + + \sa isNull(), resize() +*/ + +/*! + \fn uint QArray::count() const + Returns the same as size(). + + \sa size() +*/ + +/*! + \fn bool QArray::isEmpty() const + Returns TRUE if the array is empty, i.e. size() == 0, otherwise FALSE. + + isEmpty() is equivalent with isNull() for QArray. Note that this is not + the case for QCString::isEmpty(). +*/ + +/*! + \fn bool QArray::isNull() const + Returns TRUE if the array is null, otherwise FALSE. + + A null array has size() == 0 and data() == 0. +*/ + +/*! + \fn bool QArray::resize( uint size ) + Resizes (expands or shrinks) the array to \e size elements. The array + becomes a null array if \e size == 0. + + Returns TRUE if successful, or FALSE if the memory cannot be allocated. + + New elements will not be initialized. + + \sa size() +*/ + +/*! + \fn bool QArray::truncate( uint pos ) + Truncates the array at position \e pos. + + Returns TRUE if successful, or FALSE if the memory cannot be allocated. + + Equivalent to resize(\e pos). + + \sa resize() +*/ + +/*! + \fn bool QArray::fill( const type &v, int size ) + Fills the array with the value \e v. If \e size is specified as different + from -1, then the array will be resized before filled. + + Returns TRUE if successful, or FALSE if the memory cannot be allocated + (only when \e size != -1). + + \sa resize() +*/ + +/*! + \fn void QArray::detach() + Detaches this array from shared array data, i.e. makes a private, deep + copy of the data. + + Copying will only be performed if the + \link nrefs() reference count\endlink is greater than one. + + \sa copy() +*/ + +/*! + \fn QArray QArray::copy() const + Returns a deep copy of this array. + \sa detach(), duplicate() +*/ + +/*! + \fn QArray &QArray::assign( const QArray &a ) + Shallow copy. Dereferences the current array and references the data + contained in \e a instead. Returns a reference to this array. + \sa operator=() +*/ + +/*! + \fn QArray &QArray::assign( const type *data, uint size ) + Shallow copy. Dereferences the current array and references the + array data \e data, which contains \e size elements. + Returns a reference to this array. + + Do not delete \e data later, QArray takes care of that. +*/ + +/*! + \fn QArray &QArray::duplicate( const QArray &a ) + Deep copy. Dereferences the current array and obtains a copy of the data + contained in \e a instead. Returns a reference to this array. + \sa copy() +*/ + +/*! + \fn QArray &QArray::duplicate( const type *data, uint size ) + Deep copy. Dereferences the current array and obtains a copy of the + array data \e data instead. Returns a reference to this array. + \sa copy() +*/ + +/*! + \fn QArray &QArray::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 \e data and + the new array size to \e size. Do not attempt to resize or re-assign the + array data when raw data has been set. + Call resetRawData(d,len) to reset the array. + + Setting raw data is useful because it sets QArray 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 >> ; // 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(), QArray will attempt to + deallocate or reallocate the raw data, which might not be too good. + Be careful. + + \sa resetRawData() +*/ + +/*! + \fn void QArray::resetRawData( const type *data, uint size ) + Resets raw data that was set using setRawData(). + + The arguments must be the data and length that were passed to + setRawData(). This is for consistency checking. + + \sa setRawData() +*/ + +/*! + \fn int QArray::find( const type &v, uint index ) const + Finds the first occurrence of \e v, starting at position \e index. + + Returns the position of \e v, or -1 if \e v could not be found. + + \sa contains() +*/ + +/*! + \fn int QArray::contains( const type &v ) const + Returns the number of times \e v occurs in the array. + \sa find() +*/ + +/*! + \fn void QArray::sort() + Sorts the array elements in ascending order, using bitwise + comparison (memcmp()). + + \sa bsearch() +*/ + +/*! + \fn int QArray::bsearch( const type &v ) const + In a sorted array, finds the first occurrence of \e v using binary + search. For a sorted array, this is generally much faster than + find(), which does a linear search. + + Returns the position of \e v, or -1 if \e v could not be found. + + \sa sort(), find() +*/ + +/*! + \fn type &QArray::operator[]( int index ) const + Returns a reference to the element at position \e index in the array. + + This can be used to both read and set an element. Equivalent to at(). + + \sa at() +*/ + +/*! + \fn type &QArray::at( uint index ) const + Returns a reference to the element at position \e index in the array. + + This can be used to both read and set an element. + + \sa operator[]() +*/ + +/*! + \fn QArray::operator const type *() const + Cast operator. Returns a pointer to the array. + \sa data() +*/ + +/*! + \fn bool QArray::operator==( const QArray &a ) const + Returns TRUE if this array is equal to \e a, otherwise FALSE. + + The two arrays are bitwise compared. + + \sa operator!=() +*/ + +/*! + \fn bool QArray::operator!=( const QArray &a ) const + Returns TRUE if this array is different from \e a, otherwise FALSE. + + The two arrays are bitwise compared. + + \sa operator==() +*/ + +/*! + \fn Iterator QArray::begin() + Returns an iterator pointing at the beginning of this array. + This iterator can be used as the iterators of QValueList and QMap + for example. In fact it does not only behave like a usual pointer: + It is a pointer. +*/ + +/*! + \fn Iterator QArray::end() + Returns an iterator pointing behind the last element of this array. + This iterator can be used as the iterators of QValueList and QMap + for example. In fact it does not only behave like a usual pointer: + It is a pointer. +*/ + +/*! + \fn ConstIterator QArray::begin() const + Returns a const iterator pointing at the beginning of this array. + This iterator can be used as the iterators of QValueList and QMap + for example. In fact it does not only behave like a usual pointer: + It is a pointer. +*/ + +/*! + \fn ConstIterator QArray::end() const + Returns a const iterator pointing behind the last element of this array. + This iterator can be used as the iterators of QValueList and QMap + for example. In fact it does not only behave like a usual pointer: + It is a pointer. +*/ + + +/***************************************************************************** + QByteArray documentation + *****************************************************************************/ + +/*! + \class QByteArray qcstring.h + \brief The QByteArray class provides an array of bytes. + + \inherit QArray + + \ingroup tools + + The QByteArray class provides an explicitly shared array of + bytes. It is useful for manipulating memory areas with custom + data. QByteArray is implemented as QArray. See the QArray + documentation for further information. +*/ diff --git a/qtools/qdict.doc b/qtools/qdict.doc new file mode 100644 index 0000000..4472a3c --- /dev/null +++ b/qtools/qdict.doc @@ -0,0 +1,492 @@ +/**************************************************************************** +** $Id$ +** +** QDict and QDictIterator class documentation +** +** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be distributed under the terms of the Q Public License +** as defined by Trolltech AS of Norway and appearing in the file +** LICENSE.QPL included in the packaging of this file. +** +** This file may be distributed and/or modified under the terms of the +** GNU General Public License version 2 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. +** +** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition +** 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 +** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +** +** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for +** information about Qt Commercial License Agreements. +** See http://www.trolltech.com/qpl/ for QPL licensing information. +** See http://www.trolltech.com/gpl/ for GPL licensing information. +** +** Contact info@trolltech.com if any conditions of this licensing are +** not clear to you. +** +**********************************************************************/ + + +/***************************************************************************** + QDict documentation + *****************************************************************************/ + +/*! + \class QDict qdict.h + \brief The QDict class is a template class that provides a dictionary based on \c QString keys. + + \ingroup collection + \ingroup tools + + QDict is implemented as a template class. Define a template instance + QDict\ to create a dictionary that operates on pointers to X, or X*. + + A dictionary is a collection that associates an item with a key. + The key is used for inserting and looking up an item. QDict has + \l QString keys, which are Unicode strings. If you want to use + non-Unicode, plain 8-bit \c char* keys, use the QAsciiDict template. + A QDict has the same performace as a QAsciiDict. + + The dictionary has very fast insertion and lookup. + + Example: + \code + #include + #include + + void main() + { + // Creates a dictionary that maps QString ==> char* (case insensitive) + QDict dict( 17, FALSE ); + + dict.insert( "France", "Paris" ); + dict.insert( "Russia", "Moscow" ); + dict.insert( "Norway", "Oslo" ); + + printf( "%s\n", dict["Norway"] ); + printf( "%s\n", dict["FRANCE"] ); + printf( "%s\n", dict["russia"] ); + + if ( !dict["Italy"] ) + printf( "Italy not defined\n" ); + } + \endcode + + Program output: + \code + Oslo + Paris + Moscow + Italy not defined + \endcode + + The dictionary in our example maps \c QString keys to \c char* items. + Note that the mapping is case insensitive (specified in the + \link QDict::QDict() constructor\endlink). + QDict implements the \link operator[] [] operator\endlink to lookup an item. + + QDict is implemented by QGDict as a hash array with a fixed number of + entries. Each array entry points to a singly linked list of buckets, in + which the dictionary items are stored. + + When an item is inserted with a key, the key is converted (hashed) to + an integer index into the hash array. The item is inserted before the + first bucket in the list of buckets. + + Looking up an item is normally very fast. The key is again hashed to an + array index. Then QDict scans the list of buckets and returns the item + found or null if the item was not found. You cannot insert null pointers + into a dictionary. + + The size of the hash array is very important. In order to get good + performance, you should use a suitably large \link primes.html prime + number\endlink. Suitable means equal to or larger than the maximum + expected number of dictionary items. + + Items with equal keys are allowed. When inserting two items with the + same key, only the last inserted item will be visible (last in, first out) + until it is removed. + + Example: + \code + #include + #include + + void main() + { + // Creates a dictionary that maps QString ==> char* (case sensitive) + QDict dict; + + dict.insert( "Germany", "Berlin" ); + dict.insert( "Germany", "Bonn" ); + + printf( "%s\n", dict["Germany"] ); + dict.remove( "Germany" ); // Oct 3rd 1990 + printf( "%s\n", dict["Germany"] ); + } + \endcode + + Program output: + \code + Bonn + Berlin + \endcode + + The QDictIterator class can traverse the dictionary contents, but only + in an arbitrary order. Multiple iterators may independently traverse the + same dictionary. + + Calling setAutoDelete(TRUE) for a dictionary tells it to delete items + that are removed . The default is to not delete items when they are + removed. + + When inserting an item into a dictionary, only the pointer is copied, not + the item itself. This is called a shallow copy. It is possible to make the + dictionary copy all of the item's data (known as a deep copy) when an + item is inserted. insert() calls the virtual function + QCollection::newItem() for the item to be inserted. + Inherit a dictionary and reimplement it if you want deep copies. + + When removing a dictionary item, the virtual function + QCollection::deleteItem() is called. QDict's default implementation + is to delete the item if auto-deletion is enabled. + + \sa QDictIterator, QAsciiDict, QIntDict, QPtrDict, + \link collection.html Collection Classes\endlink +*/ + + +/*! + \fn QDict::QDict( int size, bool caseSensitive ) + Constructs a dictionary with the following properties: + \arg \e size is the size of the internal hash array. + \arg \e caseSensitive specifies whether to use case sensitive lookup or not. + + Setting \e size to a suitably large \link primes.html prime + number\endlink (equal to or greater than the expected number of entries) + makes the hash distribution better and hence the loopup faster. + + Setting \e caseSensitive to TRUE will treat "abc" and "Abc" as different + keys. Setting it to FALSE will make the dictionary ignore case. + Case insensitive comparison includes the whole Unicode alphabeth. +*/ + +/*! + \fn QDict::QDict( const QDict &dict ) + Constructs a copy of \e dict. + + Each item in \e dict are inserted into this dictionary. + Only the pointers are copied (shallow copy). +*/ + +/*! + \fn QDict::~QDict() + Removes all items from the dictionary and destroys it. + All iterators that access this dictionary will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn QDict &QDict::operator=(const QDict &dict) + Assigns \e dict to this dictionary and returns a reference to this + dictionary. + + This dictionary is first cleared, then each item in \e dict is inserted + into this dictionary. + Only the pointers are copied (shallow copy), unless newItem() has been + reimplemented(). +*/ + +/*! + \fn uint QDict::count() const + Returns the number of items in the dictionary. + \sa isEmpty() +*/ + +/*! + \fn uint QDict::size() const + Returns the size of the internal hash array (as specified in the + constructor). + \sa count() +*/ + +/*! + \fn void QDict::resize( uint newsize ) + Changes the size of the hashtable the \a newsize. + The contents of the dictionary are preserved, + but all iterators on the dictionary become invalid. +*/ + +/*! + \fn bool QDict::isEmpty() const + Returns TRUE if the dictionary is empty, i.e. count() == 0. Returns FALSE + otherwise. + \sa count() +*/ + +/*! + \fn void QDict::insert( const QString &key, const type *item ) + + Inserts the \e key with the \e item into the dictionary. + + The key does not have to be a unique dictionary key. If multiple items + are inserted with the same key, only the last item will be visible. + + Null items are not allowed. + + \sa replace() +*/ + +/*! + \fn void QDict::replace( const QString &key, const type *item ) + + Replaces an item which has a key equal to \e key with \e item. + + If the item does not already exist, it will be inserted. + + Null items are not allowed. + + Equivalent to: + \code + QDict dict; + ... + if ( dict.find(key) ) + dict.remove( key ); + dict.insert( key, item ); + \endcode + + If there are two or more items with equal keys, then the last inserted + of these will be replaced. + + \sa insert() +*/ + +/*! + \fn bool QDict::remove( const QString &key ) + + Removes the item associated with \e key from the dictionary. + Returns TRUE if successful, or FALSE if the key does not exist in the + dictionary. + + If there are two or more items with equal keys, then the last inserted + of these will be removed. + + The removed item is deleted if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled. + + All dictionary iterators that refer to the removed item will be set to + point to the next item in the dictionary traversing order. + + \sa take(), clear(), setAutoDelete() +*/ + +/*! + \fn type *QDict::take( const QString &key ) + + Takes the item associated with \e key out of the dictionary without + deleting it (even if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled). + + If there are two or more items with equal keys, then the last inserted + of these will be taken. + + Returns a pointer to the item taken out, or null if the key does not + exist in the dictionary. + + All dictionary iterators that refer to the taken item will be set to + point to the next item in the dictionary traversal order. + + \sa remove(), clear(), setAutoDelete() +*/ + +/*! + \fn void QDict::clear() + + Removes all items from the dictionary. + + The removed items are deleted if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled. + + All dictionary iterators that operate on dictionary are reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn type *QDict::find( const QString &key ) const + + Returns the item associated with \e key, or null if the key does not + exist in the dictionary. + + This function uses an internal hashing algorithm to optimize lookup. + + If there are two or more items with equal keys, then the last inserted + of these will be found. + + Equivalent to the [] operator. + + \sa operator[]() +*/ + +/*! + \fn type *QDict::operator[]( const QString &key ) const + + Returns the item associated with \e key, or null if the key does not + exist in the dictionary. + + This function uses an internal hashing algorithm to optimize lookup. + + If there are two or more items with equal keys, then the last inserted + of these will be found. + + Equivalent to the find() function. + + \sa find() +*/ + +/*! + \fn void QDict::statistics() const + Debugging-only function that prints out the dictionary distribution + using qDebug(). +*/ + + +/***************************************************************************** + QDictIterator documentation + *****************************************************************************/ + +/*! + \class QDictIterator qdict.h + \brief The QDictIterator class provides an iterator for QDict collections. + + \ingroup collection + \ingroup tools + + QDictIterator is implemented as a template class. + Define a template instance QDictIterator\ to create a + dictionary iterator that operates on QDict\ (dictionary of X*). + + Example: + \code + #include + #include + + void main() + { + // Creates a dictionary that maps QString ==> char* (case insensitive) + QDict dict( 17, FALSE ); + + dict.insert( "France", "Paris" ); + dict.insert( "Russia", "Moscow" ); + dict.insert( "Norway", "Oslo" ); + + QDictIterator it( dict ); // iterator for dict + + while ( it.current() ) { + printf( "%s -> %s\n", it.currentKey().latin1(), it.current() ); + ++it; + } + } + \endcode + + Program output: + \code + Russia -> Moscow + Norway -> Oslo + France -> Paris + \endcode + + Note that the traversal order is arbitrary, you are not guaranteed the + order above. + + Multiple iterators may independently traverse the same dictionary. + A QDict knows about all iterators that are operating on the dictionary. + When an item is removed from the dictionary, QDict update all iterators + that are referring the removed item to point to the next item in the + traversing order. + + \sa QDict, \link collection.html Collection Classes\endlink +*/ + +/*! + \fn QDictIterator::QDictIterator( const QDict &dict ) + Constructs an iterator for \e dict. The current iterator item is + set to point on the first item in the \e dict. +*/ + +/*! + \fn QDictIterator::~QDictIterator() + Destroys the iterator. +*/ + +/*! + \fn uint QDictIterator::count() const + Returns the number of items in the dictionary this iterator operates on. + \sa isEmpty() +*/ + +/*! + \fn bool QDictIterator::isEmpty() const + Returns TRUE if the dictionary is empty, i.e. count() == 0, otherwise FALSE. + \sa count() +*/ + +/*! + \fn type *QDictIterator::toFirst() + Sets the current iterator item to point to the first item in the + dictionary and returns a pointer to the item. + If the dictionary is empty it sets the current item to null and + returns null. +*/ + +/*! + \fn QDictIterator::operator type *() const + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *QDictIterator::current() const + Returns a pointer to the current iterator item. +*/ + +/*! + \fn QString QDictIterator::currentKey() const + Returns a pointer to the key for the current iterator item. +*/ + +/*! + \fn type *QDictIterator::operator()() + Makes the succeeding item current and returns the original current item. + + If the current iterator item was the last item in the dictionary or if it + was null, null is returned. +*/ + +/*! + \fn type *QDictIterator::operator++() + Prefix ++ makes the succeeding item current and returns the new current + item. + + If the current iterator item was the last item in the dictionary or if it + was null, null is returned. +*/ + +/*! + \fn type *QDictIterator::operator+=( uint jump ) + Sets the current item to the item \e jump positions after the current item, + and returns a pointer to that item. + + If that item is beyond the last item or if the dictionary is empty, + it sets the current item to null and returns null. +*/ + + diff --git a/qtools/qintdict.doc b/qtools/qintdict.doc new file mode 100644 index 0000000..0a77398 --- /dev/null +++ b/qtools/qintdict.doc @@ -0,0 +1,475 @@ +/**************************************************************************** +** $Id$ +** +** QIntDict and QIntDictIterator class documentation +** +** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be distributed under the terms of the Q Public License +** as defined by Trolltech AS of Norway and appearing in the file +** LICENSE.QPL included in the packaging of this file. +** +** This file may be distributed and/or modified under the terms of the +** GNU General Public License version 2 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. +** +** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition +** 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 +** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +** +** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for +** information about Qt Commercial License Agreements. +** See http://www.trolltech.com/qpl/ for QPL licensing information. +** See http://www.trolltech.com/gpl/ for GPL licensing information. +** +** Contact info@trolltech.com if any conditions of this licensing are +** not clear to you. +** +**********************************************************************/ + + +/***************************************************************************** + QIntDict documentation + *****************************************************************************/ + +/*! + \class QIntDict qintdict.h + \brief The QIntDict class is a template class that provides a dictionary based on \c long keys. + + \ingroup collection + \ingroup tools + + QIntDict is implemented as a template class. Define a + template instance QIntDict\ to create a dictionary that operates on + pointers to X, or X*. + + A dictionary is a collection that associates an item with a key. + The key is used for inserting and looking up an item. QIntDict has + \c long keys. + + The dictionary has very fast insertion and lookup. + + Example: + \code + #include + #include + + void main() + { + QIntDict dict; // maps long ==> char* + + dict.insert( 33, "France" ); + dict.insert( 7, "Russia" ); + dict.insert( 49, "Norway" ); + + printf( "%s\n", dict[49] ); + printf( "%s\n", dict[33] ); + printf( "%s\n", dict[7] ); + + if ( !dict[39] ) + printf( "39 not defined\n" ); + } + \endcode + + Program output: + \code + Norway + France + Russia + 39 not defined + \endcode + + The dictionary in our example maps \c long keys to \c char* items. + QIntDict implements the \link operator[] [] operator\endlink to lookup + an item. + + QIntDict is implemented by QGDict as a hash array with a fixed number of + entries. Each array entry points to a singly linked list of buckets, in + which the dictionary items are stored. + + When an item is inserted with a key, the key is converted (hashed) to + an integer index into the hash array using the \c mod operation. The + item is inserted before the first bucket in the list of buckets. + + Looking up an item is normally very fast. The key is again hashed to an + array index. Then QIntDict scans the list of buckets and returns the item + found or null if the item was not found. You cannot insert null pointers + into a dictionary. + + The size of the hash array is very important. In order to get good + performance, you should use a suitably large \link primes.html prime + number\endlink. Suitable means equal to or larger than the maximum + expected number of dictionary items. + + Items with equal keys are allowed. When inserting two items with the + same key, only the last inserted item will be visible (last in, first out) + until it is removed. + + Example: + \code + #include + #include + + void main() + { + QIntDict dict; // maps long ==> char* + + dict.insert( 7, "Russia" ); + dict.insert( 7, "USSR" ); + + printf( "%s\n", dict[7] ); + dict.remove( 7 ); // Gorbie was here + printf( "%s\n", dict[7] ); + } + \endcode + + Program output: + \code + USSR + Russia + \endcode + + The QIntDictIterator class can traverse the dictionary contents, but only + in an arbitrary order. Multiple iterators may independently traverse the + same dictionary. + + Calling setAutoDelete(TRUE) for a dictionary tells it to delete items + that are removed . The default is to not delete items when they are + removed. + + When inserting an item into a dictionary, only the pointer is copied, not + the item itself. This is called a shallow copy. It is possible to make the + dictionary copy all of the item's data (known as a deep copy) when an + item is inserted. insert() calls the virtual function + QCollection::newItem() for the item to be inserted. + Inherit a dictionary and reimplement it if you want deep copies. + + When removing a dictionary item, the virtual function + QCollection::deleteItem() is called. QIntDict's default implementation + is to delete the item if auto-deletion is enabled. + + \sa QIntDictIterator, QDict, QAsciiDict, QPtrDict, + \link collection.html Collection Classes\endlink +*/ + + +/*! + \fn QIntDict::QIntDict( int size ) + Constructs a dictionary using an internal hash array with the size + \e size. + + Setting \e size to a suitably large \link primes.html prime number\endlink + (equal to or greater than the expected number of entries) makes the hash + distribution better and hence the loopup faster. +*/ + +/*! + \fn QIntDict::QIntDict( const QIntDict &dict ) + Constructs a copy of \e dict. + + Each item in \e dict are inserted into this dictionary. + Only the pointers are copied (shallow copy). +*/ + +/*! + \fn QIntDict::~QIntDict() + Removes all items from the dictionary and destroys it. + + All iterators that access this dictionary will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn QIntDict &QIntDict::operator=(const QIntDict &dict) + Assigns \e dict to this dictionary and returns a reference to this + dictionary. + + This dictionary is first cleared, then each item in \e dict is inserted + into this dictionary. + Only the pointers are copied (shallow copy), unless newItem() has been + reimplemented. +*/ + +/*! + \fn uint QIntDict::count() const + Returns the number of items in the dictionary. + \sa isEmpty() +*/ + +/*! + \fn uint QIntDict::size() const + Returns the size of the internal hash array (as specified in the + constructor). + \sa count() +*/ + +/*! + \fn void QIntDict::resize( uint newsize ) + Changes the size of the hashtable the \a newsize. + The contents of the dictionary are preserved, + but all iterators on the dictionary become invalid. +*/ + +/*! + \fn bool QIntDict::isEmpty() const + Returns TRUE if the dictionary is empty, i.e. count() == 0. Returns FALSE + otherwise. + \sa count() +*/ + +/*! + \fn void QIntDict::insert( long key, const type *item ) + Inserts the \e key with the \e item into the dictionary. + + The key does not have to be a unique dictionary key. If multiple items + are inserted with the same key, only the last item will be visible. + + Null items are not allowed. + + \sa replace() +*/ + +/*! + \fn void QIntDict::replace( long key, const type *item ) + Replaces an item which has a key equal to \e key with \e item. + + If the item does not already exist, it will be inserted. + + Null items are not allowed. + + Equivalent to: + \code + QIntDict dict; + ... + if ( dict.find(key) ) + dict.remove( key ); + dict.insert( key, item ); + \endcode + + If there are two or more items with equal keys, then the last inserted + of these will be replaced. + + \sa insert() +*/ + +/*! + \fn bool QIntDict::remove( long key ) + Removes the item associated with \e key from the dictionary. + Returns TRUE if successful, or FALSE if the key does not exist in the + dictionary. + + If there are two or more items with equal keys, then the last inserted + of these will be removed. + + The removed item is deleted if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled. + + All dictionary iterators that refer to the removed item will be set to + point to the next item in the dictionary traversing order. + + \sa take(), clear(), setAutoDelete() +*/ + +/*! + \fn type *QIntDict::take( long key ) + Takes the item associated with \e key out of the dictionary without + deleting it (even if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled). + + If there are two or more items with equal keys, then the last inserted + of these will be taken. + + Returns a pointer to the item taken out, or null if the key does not + exist in the dictionary. + + All dictionary iterators that refer to the taken item will be set to + point to the next item in the dictionary traversing order. + + \sa remove(), clear(), setAutoDelete() +*/ + +/*! + \fn void QIntDict::clear() + Removes all items from the dictionary. + + The removed items are deleted if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled. + + All dictionary iterators that access this dictionary will be reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn type *QIntDict::find( long key ) const + Returns the item associated with \e key, or null if the key does not + exist in the dictionary. + + This function uses an internal hashing algorithm to optimize lookup. + + If there are two or more items with equal keys, then the last inserted + of these will be found. + + Equivalent to the [] operator. + + \sa operator[]() +*/ + +/*! + \fn type *QIntDict::operator[]( long key ) const + Returns the item associated with \e key, or null if the key does not + exist in the dictionary. + + This function uses an internal hashing algorithm to optimize lookup. + + If there are two or more items with equal keys, then the last inserted + of these will be found. + + Equivalent to the find() function. + + \sa find() +*/ + +/*! + \fn void QIntDict::statistics() const + Debugging-only function that prints out the dictionary distribution + using qDebug(). +*/ + + +/***************************************************************************** + QIntDictIterator documentation + *****************************************************************************/ + +/*! + \class QIntDictIterator qintdict.h + \brief The QIntDictIterator class provides an iterator for QIntDict collections. + + \ingroup collection + \ingroup tools + + QIntDictIterator is implemented as a template class. + Define a template instance QIntDictIterator\ to create a + dictionary iterator that operates on QIntDict\ (dictionary of X*). + + Example: + \code + #include + #include + + void main() + { + QIntDict dict; // maps long ==> char* + + dict.insert( 33, "France" ); + dict.insert( 7, "Russia" ); + dict.insert( 49, "Norway" ); + + QIntDictIterator it( dict ); // iterator for dict + + while ( it.current() ) { + printf( "%d -> %s\n", it.currentKey(), it.current() ); + ++it; + } + } + \endcode + + Program output: + \code + 7 -> Russia + 49 -> Norway + 33 -> France + \endcode + + Note that the traversal order is arbitrary, you are not guaranteed the + order above. + + Multiple iterators may independently traverse the same dictionary. + A QIntDict knows about all iterators that are operating on the dictionary. + When an item is removed from the dictionary, QIntDict update all + iterators that are referring the removed item to point to the next item + in the traversing order. + + \sa QIntDict, \link collection.html Collection Classes\endlink +*/ + +/*! + \fn QIntDictIterator::QIntDictIterator( const QIntDict &dict ) + Constructs an iterator for \e dict. The current iterator item is + set to point on the first item in the \e dict. +*/ + +/*! + \fn QIntDictIterator::~QIntDictIterator() + Destroys the iterator. +*/ + +/*! + \fn uint QIntDictIterator::count() const + Returns the number of items in the dictionary this iterator operates on. + \sa isEmpty() +*/ + +/*! + \fn bool QIntDictIterator::isEmpty() const + Returns TRUE if the dictionary is empty, i.e. count() == 0. Returns FALSE + otherwise. + \sa count() +*/ + +/*! + \fn type *QIntDictIterator::toFirst() + Sets the current iterator item to point to the first item in the + dictionary and returns a pointer to the item. + If the dictionary is empty it sets the current item to null and + returns null. +*/ + +/*! + \fn QIntDictIterator::operator type *() const + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *QIntDictIterator::current() const + Returns a pointer to the current iterator item. +*/ + +/*! + \fn long QIntDictIterator::currentKey() const + Returns the key for the current iterator item. +*/ + +/*! + \fn type *QIntDictIterator::operator()() + Makes the succeeding item current and returns the original current item. + + If the current iterator item was the last item in the dictionary or if it + was null, null is returned. +*/ + +/*! + \fn type *QIntDictIterator::operator++() + Prefix ++ makes the succeeding item current and returns the new current + item. + + If the current iterator item was the last item in the dictionary or if it + was null, null is returned. +*/ + +/*! + \fn type *QIntDictIterator::operator+=( uint jump ) + Sets the current item to the item \e jump positions after the current item, + and returns a pointer to that item. + + If that item is beyond the last item or if the dictionary is empty, + it sets the current item to null and returns null. +*/ diff --git a/qtools/qlist.doc b/qtools/qlist.doc new file mode 100644 index 0000000..85dbf5b --- /dev/null +++ b/qtools/qlist.doc @@ -0,0 +1,1048 @@ +/**************************************************************************** +** $Id$ +** +** QList and QListIterator class documentation +** +** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be distributed under the terms of the Q Public License +** as defined by Trolltech AS of Norway and appearing in the file +** LICENSE.QPL included in the packaging of this file. +** +** This file may be distributed and/or modified under the terms of the +** GNU General Public License version 2 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. +** +** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition +** 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 +** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +** +** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for +** information about Qt Commercial License Agreements. +** See http://www.trolltech.com/qpl/ for QPL licensing information. +** See http://www.trolltech.com/gpl/ for GPL licensing information. +** +** Contact info@trolltech.com if any conditions of this licensing are +** not clear to you. +** +**********************************************************************/ + + +/***************************************************************************** + QList documentation + *****************************************************************************/ + +/*! + \class QList qlist.h + \brief The QList class is a template class that provides doubly linked lists. + + \ingroup collection + \ingroup tools + + In Qt 2.0 QList is only implemented as a template class. Define a + template instance QList\ to create a list that operates on pointers + to X, or X*. + + Example: + \code + #include + #include + #include + + class Employee + { + public: + Employee( const QString& name, int salary ) { n=name; s=salary; } + QString name() const { return n; } + int salary() const { return s; } + private: + QString n; + int s; + }; + + void main() + { + QList list; // list of pointers to Employee + list.setAutoDelete( TRUE ); // delete items when they are removed + + list.append( new Employee("Bill", 50000) ); + list.append( new Employee("Steve",80000) ); + list.append( new Employee("Ron", 60000) ); + + Employee *emp; + for ( emp=list.first(); emp != 0; emp=list.next() ) + printf( "%s earns %d\n", emp->name().latin1(), emp->salary() ); + } + \endcode + + Program output: + \code + Bill earns 50000 + Steve earns 80000 + Ron earns 60000 + \endcode + + The list class is indexable and has a \link at() current index\endlink + and a \link current() current item\endlink. The first item corresponds + to index 0. The current index is -1 if the current item is null. + + QList has several member functions for traversing the list, but using + a QListIterator can be more practical. Multiple list iterators may + traverse the same list, independent of each other and independent of + the current list item. + + In the example above, we make the call setAutoDelete(TRUE). + Enabling auto-deletion tells the list to delete items that are removed + from the list. The default is to not delete items when they are + removed, but that would cause a memory leak in our example since we have + no other references to the list items. + + List items are stored as \c void* in an internal QLNode, which also + holds pointers to the next and previous list items. The functions + currentNode(), removeNode() and takeNode() operate directly on the + QLNode, but they should be used with care. + + When inserting an item into a list, only the pointer is copied, not the + item itself. This is called a shallow copy. It is possible to make the + list copy all of the item's data (known as a deep copy) when an item is + inserted. insert(), inSort() and append() call the virtual function + QCollection::newItem() for the item to be inserted. + Inherit a list and reimplement it if you want deep copies. + + When removing an item from a list, the virtual function + QCollection::deleteItem() is called. QList's default implementation + is to delete the item if auto-deletion is enabled. + + The virtual function QGList::compareItems() can be reimplemented to + compare two list items. This function is called from all list functions + that need to compare list items, for instance remove(const type*). + If you only want to deal with pointers, there are functions that + compare pointers instead, for instance removeRef(const type*). + These functions are somewhat faster than those that call compareItems(). + + The QStrList class in qstrlist.h is a list of \c char*. QStrList is + a good example of a list that reimplements newItem(), deleteItem() and + compareItems() + + \sa QListIterator, \link collection.html Collection Classes\endlink +*/ + + +/*! + \fn QList::QList() + Constructs an empty list. +*/ + +/*! + \fn QList::QList( const QList &list ) + Constructs a copy of \e list. + + Each item in \e list is \link append() appended\endlink to this list. + Only the pointers are copied (shallow copy). +*/ + +/*! + \fn QList::~QList() + Removes all items from the list and destroys the list. + + All list iterators that access this list will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn QList &QList::operator=(const QList &list) + Assigns \e list to this list and returns a reference to this list. + + This list is first cleared, then each item in \e list is + \link append() appended\endlink to this list. Only the pointers are copied + (shallow copy), unless newItem() has been reimplemented(). +*/ + +/*! + \fn bool QList::operator==(const QList &list ) const + + Compares this list with \a list. Retruns TRUE if the lists + contain the same data, else FALSE. +*/ + +/*! + \fn uint QList::count() const + Returns the number of items in the list. + \sa isEmpty() +*/ + +/*! + \fn void QList::sort() + + Sorts the list by the result of the virtual compareItems() function. + + The Heap-Sort algorithm is used for sorting. It sorts n items with + O(n*log n) compares. This is the asymptotic optimal solution of the + sorting problem. + + If the items in your list support operator< and operator== then you + might be better off with QSortedList since it implements the + compareItems() function for you using these two operators. + + \sa inSort() +*/ + +/*! + \fn bool QList::isEmpty() const + Returns TRUE if the list is empty, i.e. count() == 0. Returns FALSE + otherwise. + \sa count() +*/ + +/*! + \fn bool QList::insert( uint index, const type *item ) + Inserts the \e item at the position \e index in the list. + + Returns TRUE if successful, or FALSE if \e index is out of range. + The valid range is 0 .. count() inclusive. + The item is appended if \e index == count(). + + The inserted item becomes the current list item. + + The \e item must not be a null pointer. + + \sa append(), current() +*/ + +/*! + \fn void QList::inSort( const type *item ) + Inserts the \e item at its sorted position in the list. + + The sort order depends on the virtual QGList::compareItems() function. + All items must be inserted with inSort() to maintain the sorting order. + + The inserted item becomes the current list item. + + The \e item must not be a null pointer. + + Please note that inSort is slow. If you want to insert lots of items + in a list and sort after inserting then you should use sort(). + inSort() takes up to O(n) compares. That means inserting n items in + your list will need O(n^2) compares while sort() only needs O(n*logn) + for the same task. So you inSort() only if you already have a pre-sorted + list and want to insert only few additional items. + + \sa insert(), QGList::compareItems(), current(), sort() +*/ + +/*! + \fn void QList::append( const type *item ) + Inserts the \e item at the end of the list. + + The inserted item becomes the current list item. + This is equivalent to \c insert(count(),item). + + + The \e item must not be a null pointer. + + \sa insert(), current(), prepend() +*/ + +/*! + \fn void QList::prepend( const type *item ) + + Inserts the \e item at the start of the list. + + The inserted item becomes the current list item. + This is equivalent to \c insert(0,item). + + The \e item must not be a null pointer. + + \sa append(), insert(), current() +*/ + +/*! + \fn bool QList::remove( uint index ) + Removes the item at position \e index in the list. + + Returns TRUE if successful, or FALSE if \e index is out of range. + The valid range is 0 .. (count() - 1) inclusive. + + The removed item is deleted if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled. + + The item after the removed item becomes the new current list item if + the removed item is not the last item in the list. If the last item + is removed, the new last item becomes the current item in Qt 2.x. + In 3.0, the current item will be set to null. The current item is + set to null if the list becomes empty. + + All list iterators that refer to the removed item will be set to point + to the new current item. + + \sa take(), clear(), setAutoDelete(), current() removeRef() +*/ + +/*! + \fn bool QList::remove() + Removes the current list item. + + Returns TRUE if successful, or FALSE if the current item is null. + + The removed item is deleted if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled. + + The item after the removed item becomes the new current list item if + the removed item is not the last item in the list. If the last item + is removed, the new last item becomes the current item in Qt 2.x. + In 3.0, the current item will be set to null. The current item is + set to null if the list becomes empty. + + All list iterators that refer to the removed item will be set to point + to the new current item. + + \sa take(), clear(), setAutoDelete(), current() removeRef() +*/ + +/*! + \fn bool QList::remove( const type *item ) + Removes the first occurrence of \e item from the list. + + Returns TRUE if successful, or FALSE if the item could not be found in the + list. + + The removed item is deleted if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled. + + The compareItems() function is called when searching for the item + in the list. If compareItems() is not reimplemented, it is more + efficient to call removeRef(). + + The item after the removed item becomes the new current list item if + the removed item is not the last item in the list. If the last item + is removed, the new last item becomes the current item in Qt 2.x. + In 3.0, the current item will be set to null. The current item is + set to null if the list becomes empty. + + All list iterators that refer to the removed item will be set to point + to the new current item. + + \sa removeRef(), take(), clear(), setAutoDelete(), compareItems(), current() +*/ + +/*! + \fn bool QList::removeRef( const type *item ) + Removes the first occurrence of \e item from the list. + + Returns TRUE if successful, or FALSE if the item cannot be found in the + list. + + The removed item is deleted if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled. + + The list is scanned until the pointer \e item is found. It is removed + if it is found. + + Equivalent to: + \code + if ( list.findRef(item) != -1 ) + list.remove(); + \endcode + + The item after the removed item becomes the new current list item if + the removed item is not the last item in the list. If the last item + is removed, the new last item becomes the current item in Qt 2.x. + In 3.0, the current item will be set to null. The current item is + set to null if the list becomes empty. + + All list iterators that refer to the removed item will be set to point + to the new current item. + + \sa remove(), clear(), setAutoDelete(), current() +*/ + +/*! + \fn void QList::removeNode( QLNode *node ) + Removes the \e node from the list. + + This node must exist in the list, otherwise the program may crash. + + The removed item is deleted if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled. + + The first item in the list will become the new current list item. + The current item is set to null if the list becomes empty. + + All list iterators that refer to the removed item will be set to point to + the item succeeding this item, or the preceding item if the removed item + was the last item. + + \warning Do not call this function unless you are an expert. + + \sa takeNode(), currentNode() remove() removeRef() +*/ + +/*! + \fn bool QList::removeFirst() + Removes the first item from the list. + Returns TRUE if successful, or FALSE if the list is empty. + + The removed item is deleted if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled. + + The first item in the list becomes the new current list item. + The current item is set to null if the list becomes empty. + + All list iterators that refer to the removed item will be set to point + to the new current item. + + \sa removeLast(), setAutoDelete(), current() remove() +*/ + +/*! + \fn bool QList::removeLast() + Removes the last item from the list. + Returns TRUE if successful, or FALSE if the list is empty. + + The removed item is deleted if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled. + + The last item in the list becomes the new current list item. + The current item is set to null if the list becomes empty. + + All list iterators that refer to the removed item will be set to point + to the new current item. + + \sa removeFirst(), setAutoDelete(), current() +*/ + +/*! + \fn type *QList::take( uint index ) + Takes the item at position \e index out of the list without + deleting it (even if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled). + + Returns a pointer to the item taken out of the list, or null if + the index is out of range. + The valid range is 0 .. (count() - 1) inclusive. + + The item after the taken item becomes the new current list item if + the taken item is not the last item in the list. If the last item + is taken, the new last item becomes the current item in Qt 2.x. In + 3.0, the current item will be set to null. The current item is set + to null if the list becomes empty. + + All list iterators that refer to the taken item will be set to point to + the new current item. + + \sa remove(), clear(), current() +*/ + +/*! + \fn type *QList::take() + Takes the current item out of the list without deleting it (even if + \link QCollection::setAutoDelete() auto-deletion\endlink is enabled). + Returns a pointer to the item taken out of the list, or null if + the current item is null. + + The item after the taken item becomes the new current list item if + the taken item is not the last item in the list. If the last item + is taken, the new last item becomes the current item in Qt 2.x. In + 3.0, the current item will be set to null. The current item is set + to null if the list becomes empty. + + All list iterators that refer to the taken item will be set to point to + the new current item. + + \sa remove(), clear(), current() +*/ + +/*! + \fn type *QList::takeNode( QLNode *node ) + Takes the \e node out of the list without deleting its item (even if + \link QCollection::setAutoDelete() auto-deletion\endlink is enabled). + Returns a pointer to the item taken out of the list. + + This node must exist in the list, otherwise the program may crash. + + The first item in the list becomes the new current list item. + + All list iterators that refer to the taken item will be set to point to + the item succeeding this item, or the preceding item if the taken item + was the last item. + + \warning Do not call this function unless you are an expert. + + \sa removeNode(), currentNode() +*/ + +/*! + \fn void QList::clear() + Removes all items from the list. + + The removed items are deleted if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled. + + All list iterators that access this list will be reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn int QList::find( const type *item ) + Finds the first occurrence of \e item in the list. + + If the item is found, the list sets the current item to point to + the found item and returns the index of this item. + If the item is not found, the list sets the current item to null, + the current index to -1 and returns -1. + + The compareItems() function is called when searching for the item + in the list. If compareItems() is not reimplemented, it is more + efficient to call findRef(). + + \sa findNext(), findRef(), compareItems(), current() +*/ + +/*! + \fn int QList::findNext( const type *item ) + Finds the next occurrence of \e item in the list, starting from + the current list item. + + If the item is found, the list sets the current item to point to + the found item and returns the index of this item. + If the item is not found, the list sets the current item to null, + the current index to -1 and returns -1. + + The compareItems() function is called when searching for the item + in the list. If compareItems() is not reimplemented, it is more + efficient to call findNextRef(). + + \sa find(), findNextRef(), compareItems(), current() +*/ + +/*! + \fn int QList::findRef( const type *item ) + Finds the first occurrence of \e item in the list. + + If the item is found, the list sets the current item to point to + the found item and returns the index of this item. + If the item is not found, the list sets the current item to null, + the current index to -1 and returns -1. + + Calling this function is must faster than find(), because find() + compares \e item with each list item using compareItems(). + This function only compares the pointers. + + \sa findNextRef(), find(), current() +*/ + +/*! + \fn int QList::findNextRef( const type *item ) + Finds the next occurrence of \e item in the list, starting from the + current list item. + + If the item is found, the list sets the current item to point to + the found item and returns the index of this item. + If the item is not found, the list sets the current item to null, + the current index to -1 and returns -1. + + Calling this function is must faster than findNext(), because findNext() + compares \e item with each list item using compareItems(). + This function only compares the pointers. + + \sa findRef(), findNext(), current() +*/ + +/*! + \fn uint QList::contains( const type *item ) const + Counts and returns the number of occurrences of \e item in the list. + + The compareItems() function is called when looking for the \e item + in the list. If compareItems() is not reimplemented, it is more + efficient to call containsRef(). + + Does not affect the current list item. + + \sa containsRef(), compareItems() +*/ + +/*! + \fn uint QList::containsRef( const type *item ) const + Counts and returns the number of occurrences of \e item in the list. + + Calling this function is must faster than contains(), because contains() + compares \e item with each list item using compareItems(). + This function only compares the pointers. + + Does not affect the current list item. + + \sa contains() +*/ + +/*! + \fn type *QList::at( uint index ) + Returns a pointer to the item at position \e index in the list, or + null if the index is out of range. + + Sets the current list item to this item if \e index is valid. + The valid range is 0 .. (count() - 1) inclusive. + + This function is very efficient. It starts scanning from the first + item, last item or current item, whichever is closest to \e index. + + \sa current() +*/ + +/*! + \fn int QList::at() const + Returns the index of the current list item. The returned value is -1 + if the current item is null. + \sa current() +*/ + +/*! + \fn type *QList::current() const + Returns a pointer to the current list item. The current item may be + null (implies that the current index is -1). + \sa at() +*/ + +/*! + \fn QLNode *QList::currentNode() const + Returns a pointer to the current list node. + + The node can be kept and removed later using removeNode(). + The advantage is that the item can be removed directly without + searching the list. + + \warning Do not call this function unless you are an expert. + + \sa removeNode(), takeNode(), current() +*/ + +/*! + \fn type *QList::getFirst() const + Returns a pointer to the first item in the list, or null if the + list is empty. + + Does not affect the current list item. + + \sa first(), getLast() +*/ + +/*! + \fn type *QList::getLast() const + Returns a pointer to the last item in the list, or null if the + list is empty. + + Does not affect the current list item. + + \sa last(), getFirst() +*/ + +/*! + \fn type *QList::first() + Returns a pointer to the first item in the list and makes this the + current list item, or null if the list is empty. + \sa getFirst(), last(), next(), prev(), current() +*/ + +/*! + \fn type *QList::last() + Returns a pointer to the last item in the list and makes this the + current list item, or null if the list is empty. + \sa getLast(), first(), next(), prev(), current() +*/ + +/*! + \fn type *QList::next() + Returns a pointer to the item succeeding the current item. + Returns null if the current item is null or equal to the last item. + + Makes the succeeding item current. If the current item before this + function call was the last item, the current item will be set to null. + If the current item was null, this function does nothing. + + \sa first(), last(), prev(), current() +*/ + +/*! + \fn type *QList::prev() + Returns a pointer to the item preceding the current item. + Returns null if the current item is null or equal to the first item. + + Makes the preceding item current. If the current item before this + function call was the first item, the current item will be set to null. + If the current item was null, this function does nothing. + + \sa first(), last(), next(), current() +*/ + +/*! + \fn void QList::toVector( QGVector *vec ) const + Stores all list items in the vector \e vec. + + The vector must be have the same item type, otherwise the result + will be undefined. +*/ + + +/***************************************************************************** + QListIterator documentation + *****************************************************************************/ + +/*! + \class QListIterator qlist.h + \brief The QListIterator class provides an iterator for QList collections. + + \ingroup collection + \ingroup tools + + Define a template instance QListIterator\ to create a list iterator + that operates on QList\ (list of X*). + + Example: + \code + #include + #include + #include + + class Employee + { + public: + Employee( const char *name, int salary ) { n=name; s=salary; } + const char *name() const { return n; } + int salary() const { return s; } + private: + QString n; + int s; + }; + + void main() + { + QList list; // list of pointers to Employee + list.setAutoDelete( TRUE ); // delete items when they are removed + + list.append( new Employee("Bill", 50000) ); + list.append( new Employee("Steve",80000) ); + list.append( new Employee("Ron", 60000) ); + + QListIterator it(list); // iterator for employee list + for ( ; it.current(); ++it ) { + Employee *emp = it.current(); + printf( "%s earns %d\n", emp->name().latin1(), emp->salary() ); + } + } + \endcode + + Program output: + \code + Bill earns 50000 + Steve earns 80000 + Ron earns 60000 + \endcode + + Although QList has member functions to traverse the doubly linked list + structure, using a list iterator is a much more robust way of traversing + the list, because multiple list iterators can operate on the same list, + independent of each other and independent of the QList's current item. + An iterator has its own current list item and can get the next and + previous list items. It can only traverse the list, never modify it. + + A QList knows about all list iterators that are operating on the list. + When an item is removed from the list, the list update all iterators + that are pointing the removed item to point to the new current list item. + + Example: + \code + #include + #include + #include + + class Employee + { + ... // same as above + }; + + void main() + { + QList list; // list of pointers to Employee + list.setAutoDelete( TRUE ); // delete items when they are removed + + list.append( new Employee("Bill", 50000) ); + list.append( new Employee("Steve",80000) ); + list.append( new Employee("Ron", 60000) ); + + QListIterator it(list); + + list.at( 1 ); // current list item: "Steve" + it.toLast(); // it: "Ron" + --it; // it: "Steve" + + // Now, both the list and the iterator are referring the same item + + list.remove(); + printf( "%s\n", it.current()->name().latin1() ); + } + \endcode + + Program output: + \code + Ron + \endcode + + \sa QList, \link collection.html collection classes\endlink +*/ + +/*! + \fn QListIterator::QListIterator( const QList &list ) + Constructs an iterator for \e list. The current iterator item is + set to point on the first item in the \e list. +*/ + +/*! + \fn QListIterator::~QListIterator() + Destroys the iterator. +*/ + +/*! + \fn uint QListIterator::count() const + Returns the number of items in the list this iterator operates on. + \sa isEmpty() +*/ + +/*! + \fn bool QListIterator::isEmpty() const + Returns TRUE if the list is empty, i.e. count() == 0, otherwise FALSE. + \sa count() +*/ + +/*! + \fn bool QListIterator::atFirst() const + Returns TRUE if the current iterator item is the first list item, otherwise + FALSE. + \sa toFirst(), atLast() +*/ + +/*! + \fn bool QListIterator::atLast() const + Returns TRUE if the current iterator item is the last list item, otherwise + FALSE. + \sa toLast(), atFirst() +*/ + +/*! + \fn type *QListIterator::toFirst() + Sets the current iterator item to point to the first list item and returns + a pointer to the item. Sets the current item to null and returns null + if the list is empty. + \sa toLast(), atFirst() +*/ + +/*! + \fn type *QListIterator::toLast() + Sets the current iterator item to point to the last list item and returns + a pointer to the item. Sets the current item to null and returns null + if the list is empty. + \sa toFirst(), atLast() +*/ + +/*! + \fn QListIterator::operator type *() const + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *QListIterator::operator*() + Asterix operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *QListIterator::current() const + Returns a pointer to the current iterator item. +*/ + +/*! + \fn type *QListIterator::operator()() + Makes the succeeding item current and returns the original current item. + + If the current iterator item was the last item in the list or if it was + null, null is returned. +*/ + +/*! + \fn char *QStrListIterator::operator()() + Makes the succeeding item current and returns the original current item. + + If the current iterator item was the last item in the list or if it was + null, null is returned. +*/ + +/*! + \fn type *QListIterator::operator++() + Prefix ++ makes the succeeding item current and returns the new current + item. + + If the current iterator item was the last item in the list or if it was + null, null is returned. +*/ + +/*! + \fn type *QListIterator::operator+=( uint jump ) + Sets the current item to the item \e jump positions after the current item, + and returns a pointer to that item. + + If that item is beyond the last item or if the dictionary is empty, + it sets the current item to null and returns null +*/ + +/*! + \fn type *QListIterator::operator--() + Prefix -- makes the preceding item current and returns the new current + item. + + If the current iterator item was the first item in the list or if it was + null, null is returned. +*/ + +/*! + \fn type *QListIterator::operator-=( uint jump ) + Returns the item \e jump positions before the current item, or null if + it is beyond the first item. Makes this the current item. +*/ + +/*! + \fn QListIterator& QListIterator::operator=( const QListIterator &it ) + Assignment. Makes a copy of the iterator \a it and returns a reference + to this iterator. +*/ + + +/***************************************************************************** + QStrList documentation + *****************************************************************************/ + +typedef QList QStrList + +/*! + \class QStrList qstrlist.h + \brief The QStrList class provides a doubly linked list of \c char*. + + \inherit QList + + \ingroup collection + \ingroup tools + + This class is a QList\ instance (a list of char*). + + QStrList can make deep or shallow copies of the strings that are inserted. + + A deep copy means to allocate space for the string and then copy the string + data into it. A shallow copy is just a copy of the pointer value and not + the string data. + + The disadvantage with shallow copies is that since a pointer can only + be deleted once, the program must put all strings in a central place and + know when it is safe to delete them (i.e. when the strings are no longer + referenced by other parts of the program). This can make the program + more complex. The advantage of shallow copies is that shallow copies + consume far less memory than deep copies. It is also much faster + to copy a pointer (typically 4 or 8 bytes) than to copy string data. + + A QStrList that operates on deep copies will by default turn on + auto-deletion (see setAutoDelete()). Thus, by default, QStrList will + deallocate any string copies it allocates. + + The virtual compareItems() function is reimplemented and does a case + sensitive string comparison. The inSort() function will insert + strings in a sorted order. + + The QStrListIterator class is an iterator for QStrList. +*/ + +/*! + \fn QStrList::QStrList( bool deepCopies ) + Constructs an empty list of strings. Will make deep copies of all inserted + strings if \e deepCopies is TRUE, or uses shallow copies if \e deepCopies + is FALSE. +*/ + +/*! + \fn QStrList::QStrList( const QStrList &list ) + Constructs a copy of \e list. + + If \e list has deep copies, this list will also get deep copies. + Only the pointers are copied (shallow copy) if the other list does not + use deep copies. +*/ + +/*! + \fn QStrList::~QStrList() + Destroys the list. All strings are removed. +*/ + +/*! + \fn QStrList& QStrList::operator=( const QStrList& list ) + Assigns \e list to this list and returns a reference to this list. + + If \e list has deep copies, this list will also get deep copies. + Only the pointers are copied (shallow copy) if the other list does not + use deep copies. +*/ + + +/***************************************************************************** + QStrIList documentation + *****************************************************************************/ + +/*! + \class QStrIList qstrlist.h + \brief The QStrIList class provides a doubly linked list of \c char* with +case insensitive compare. + + \ingroup collection + \ingroup tools + + This class is a QList\ instance (a list of char*). + + QStrIList is similar to QStrList except that it is case insensitive. + The virtual compareItems() function is reimplemented and does a + case insensitive string comparison. + The inSort() function will insert strings in a sorted order. + + The QStrListIterator class is an iterator for QStrList. +*/ + +/*! + \fn QStrIList::QStrIList( bool deepCopies ) + Constructs a list of strings. Will make deep copies of all inserted + strings if \e deepCopies is TRUE, or uses shallow copies if \e deepCopies + is FALSE. +*/ + +/*! + \fn QStrIList::~QStrIList() + Destroys the list. All strings are removed. +*/ + + +/***************************************************************************** + QStrListIterator documentation + *****************************************************************************/ + +/*! + \class QStrListIterator qstrlist.h + \brief The QStrListIterator class is an iterator for the QStrList and QStrIList classes. + + \inherit QListIterator + + \ingroup tools + + This class is a QListIterator\ instance. + It can traverse the strings in the QStrList and QStrIList classes. +*/ diff --git a/qtools/qptrdict.doc b/qtools/qptrdict.doc new file mode 100644 index 0000000..5a652d0 --- /dev/null +++ b/qtools/qptrdict.doc @@ -0,0 +1,486 @@ +/**************************************************************************** +** $Id$ +** +** QPtrDict and QPtrDictIterator class documentation +** +** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be distributed under the terms of the Q Public License +** as defined by Trolltech AS of Norway and appearing in the file +** LICENSE.QPL included in the packaging of this file. +** +** This file may be distributed and/or modified under the terms of the +** GNU General Public License version 2 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. +** +** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition +** 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 +** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +** +** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for +** information about Qt Commercial License Agreements. +** See http://www.trolltech.com/qpl/ for QPL licensing information. +** See http://www.trolltech.com/gpl/ for GPL licensing information. +** +** Contact info@trolltech.com if any conditions of this licensing are +** not clear to you. +** +**********************************************************************/ + + +/***************************************************************************** + QPtrDict documentation + *****************************************************************************/ + +/*! + \class QPtrDict qptrdict.h + \brief The QPtrDict class is a template class that provides a dictionary based on \c void* keys. + + \ingroup collection + \ingroup tools + + QPtrDict is implemented as a template class. Define a + template instance QPtrDict\ to create a dictionary that operates on + pointers to X, or X*. + + A dictionary is a collection that associates an item with a key. + The key is used for inserting and looking up an item. QPtrDict has + \c void* keys. + + The dictionary has very fast insertion and lookup. + + Example: + \code + #include + #include + + void main() + { + int *a = new int[12]; + int *b = new int[10]; + int *c = new int[18]; + int *d = new int[13]; + + QPtrDict dict; // maps void* -> char* + + dict.insert( a, "a is int[12]" ); // describe pointers + dict.insert( b, "b is int[10]" ); + dict.insert( c, "c is int[18]" ); + + printf( "%s\n", dict[a] ); // print descriptions + printf( "%s\n", dict[b] ); + printf( "%s\n", dict[c] ); + + if ( !dict[d] ) + printf( "d not in dictionary\n" ); + } + \endcode + + Program output: + \code + a is int[12] + b is int[10] + c is int[18] + d not in dictionary + \endcode + + The dictionary in our example maps \c int* keys to \c char* items. + QPtrDict implements the \link operator[] [] operator\endlink to lookup + an item. + + QPtrDict is implemented by QGDict as a hash array with a fixed number of + entries. Each array entry points to a singly linked list of buckets, in + which the dictionary items are stored. + + When an item is inserted with a key, the key is converted (hashed) to + an integer index into the hash array using the \c mod operation. The + item is inserted before the first bucket in the list of buckets. + + Looking up an item is normally very fast. The key is again hashed to an + array index. Then QPtrDict scans the list of buckets and returns the item + found or null if the item was not found. You cannot insert null pointers + into a dictionary. + + The size of the hash array is very important. In order to get good + performance, you should use a suitably large \link primes.html prime + number\endlink. Suitable means equal to or larger than the maximum + expected number of dictionary items. + + Items with equal keys are allowed. When inserting two items with the + same key, only the last inserted item will be visible (last in, first out) + until it is removed. + + Example: + \code + #include + #include + + void main() + { + QPtrDict dict; // maps char* ==> char* + + double *ptr = new double[28]; + dict.insert( ptr, "first" ); + dict.insert( ptr, "second" ); + + printf( "%s\n", dict[ptr] ); + dict.remove( ptr ); + printf( "%s\n", dict[ptr] ); + } + \endcode + + Program output: + \code + second + first + \endcode + + The QPtrDictIterator class can traverse the dictionary contents, but only + in an arbitrary order. Multiple iterators may independently traverse the + same dictionary. + + Calling setAutoDelete(TRUE) for a dictionary tells it to delete items + that are removed . The default is to not delete items when they are + removed. + + When inserting an item into a dictionary, only the pointer is copied, not + the item itself. This is called a shallow copy. It is possible to make the + dictionary copy all of the item's data (known as a deep copy) when an + item is inserted. insert() calls the virtual function + QCollection::newItem() for the item to be inserted. + Inherit a dictionary and reimplement it if you want deep copies. + + When removing a dictionary item, the virtual function + QCollection::deleteItem() is called. QPtrDict's default implementation + is to delete the item if auto-deletion is enabled. + + \sa QPtrDictIterator, QDict, QAsciiDict, QIntDict, + \link collection.html Collection Classes\endlink +*/ + + +/*! + \fn QPtrDict::QPtrDict( int size ) + Constructs a dictionary using an internal hash array with the size + \e size. + + Setting \e size to a suitably large \link primes.html prime number\endlink + (equal to or greater than the expected number of entries) makes the hash + distribution better and hence the loopup faster. +*/ + +/*! + \fn QPtrDict::QPtrDict( const QPtrDict &dict ) + Constructs a copy of \e dict. + + Each item in \e dict are inserted into this dictionary. + Only the pointers are copied (shallow copy). +*/ + +/*! + \fn QPtrDict::~QPtrDict() + Removes all items from the dictionary and destroys it. + + All iterators that access this dictionary will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn QPtrDict &QPtrDict::operator=(const QPtrDict &dict) + Assigns \e dict to this dictionary and returns a reference to this + dictionary. + + This dictionary is first cleared, then each item in \e dict is inserted + into this dictionary. + Only the pointers are copied (shallow copy), unless newItem() has been + reimplemented(). +*/ + +/*! + \fn uint QPtrDict::count() const + Returns the number of items in the dictionary. + \sa isEmpty() +*/ + +/*! + \fn uint QPtrDict::size() const + Returns the size of the internal hash array (as specified in the + constructor). + \sa count() +*/ + +/*! + \fn void QPtrDict::resize( uint newsize ) + Changes the size of the hashtable the \a newsize. + The contents of the dictionary are preserved, + but all iterators on the dictionary become invalid. +*/ + +/*! + \fn bool QPtrDict::isEmpty() const + Returns TRUE if the dictionary is empty, i.e. count() == 0. Returns FALSE + otherwise. + \sa count() +*/ + +/*! + \fn void QPtrDict::insert( void *key, const type *item ) + Inserts the \e key with the \e item into the dictionary. + + The key does not have to be a unique dictionary key. If multiple items + are inserted with the same key, only the last item will be visible. + + Null items are not allowed. + + \sa replace() +*/ + +/*! + \fn void QPtrDict::replace( void *key, const type *item ) + Replaces an item which has a key equal to \e key with \e item. + + If the item does not already exist, it will be inserted. + + Null items are not allowed. + + Equivalent to: + \code + QPtrDict dict; + ... + if ( dict.find(key) ) + dict.remove( key ); + dict.insert( key, item ); + \endcode + + If there are two or more items with equal keys, then the last inserted + of these will be replaced. + + \sa insert() +*/ + +/*! + \fn bool QPtrDict::remove( void *key ) + Removes the item associated with \e key from the dictionary. + Returns TRUE if successful, or FALSE if the key does not exist in the + dictionary. + + If there are two or more items with equal keys, then the last inserted + of these will be removed. + + The removed item is deleted if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled. + + All dictionary iterators that refer to the removed item will be set to + point to the next item in the dictionary traversing order. + + \sa take(), clear(), setAutoDelete() +*/ + +/*! + \fn type *QPtrDict::take( void *key ) + Takes the item associated with \e key out of the dictionary without + deleting it (even if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled). + + If there are two or more items with equal keys, then the last inserted + of these will be taken. + + Returns a pointer to the item taken out, or null if the key does not + exist in the dictionary. + + All dictionary iterators that refer to the taken item will be set to + point to the next item in the dictionary traversing order. + + \sa remove(), clear(), setAutoDelete() +*/ + +/*! + \fn void QPtrDict::clear() + Removes all items from the dictionary. + + The removed items are deleted if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled. + + All dictionary iterators that access this dictionary will be reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn type *QPtrDict::find( void *key ) const + Returns the item associated with \e key, or null if the key does not + exist in the dictionary. + + This function uses an internal hashing algorithm to optimize lookup. + + If there are two or more items with equal keys, then the last inserted + of these will be found. + + Equivalent to the [] operator. + + \sa operator[]() +*/ + +/*! + \fn type *QPtrDict::operator[]( void *key ) const + Returns the item associated with \e key, or null if the key does not + exist in the dictionary. + + This function uses an internal hashing algorithm to optimize lookup. + + If there are two or more items with equal keys, then the last inserted + of these will be found. + + Equivalent to the find() function. + + \sa find() +*/ + +/*! + \fn void QPtrDict::statistics() const + Debugging-only function that prints out the dictionary distribution + using qDebug(). +*/ + + +/***************************************************************************** + QPtrDictIterator documentation + *****************************************************************************/ + +/*! + \class QPtrDictIterator qptrdict.h + \brief The QPtrDictIterator class provides an iterator for QPtrDict collections. + + \ingroup collection + \ingroup tools + + QPtrDictIterator is implemented as a template class. + Define a template instance QPtrDictIterator\ to create a + dictionary iterator that operates on QPtrDict\ (dictionary of X*). + + Example: + \code + #include + #include + + void main() + { + int *a = new int[12]; + int *b = new int[10]; + int *c = new int[18]; + int *d = new int[13]; + + QPtrDict dict; // maps void* -> char* + + dict.insert( a, "a is int[12]" ); // describe pointers + dict.insert( b, "b is int[10]" ); + dict.insert( c, "c is int[18]" ); + + QPtrDictIterator it( dict ); // iterator for dict + + while ( it.current() ) { + printf( "%x -> %s\n", it.currentKey(), it.current() ); + ++it; + } + } + \endcode + + Program output: + \code + 804a788 -> a is int[12] + 804a7f0 -> c is int[18] + 804a7c0 -> b is int[10] + \endcode + + Note that the traversal order is arbitrary, you are not guaranteed the + order above. + + Multiple iterators may independently traverse the same dictionary. + A QPtrDict knows about all iterators that are operating on the dictionary. + When an item is removed from the dictionary, QPtrDict update all + iterators that are referring the removed item to point to the next item + in the traversing order. + + \sa QPtrDict, \link collection.html Collection Classes\endlink +*/ + +/*! + \fn QPtrDictIterator::QPtrDictIterator( const QPtrDict &dict ) + Constructs an iterator for \e dict. The current iterator item is + set to point on the first item in the \e dict. +*/ + +/*! + \fn QPtrDictIterator::~QPtrDictIterator() + Destroys the iterator. +*/ + +/*! + \fn uint QPtrDictIterator::count() const + Returns the number of items in the dictionary this iterator operates on. + \sa isEmpty() +*/ + +/*! + \fn bool QPtrDictIterator::isEmpty() const + Returns TRUE if the dictionary is empty, i.e. count() == 0. Returns FALSE + otherwise. + \sa count() +*/ + +/*! + \fn type *QPtrDictIterator::toFirst() + Sets the current iterator item to point to the first item in the + dictionary and returns a pointer to the item. + If the dictionary is empty it sets the current item to null and + returns null. +*/ + +/*! + \fn QPtrDictIterator::operator type *() const + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *QPtrDictIterator::current() const + Returns a pointer to the current iterator item. +*/ + +/*! + \fn void *QPtrDictIterator::currentKey() const + Returns the key for the current iterator item. +*/ + +/*! + \fn type *QPtrDictIterator::operator()() + Makes the succeeding item current and returns the original current item. + + If the current iterator item was the last item in the dictionary or if it + was null, null is returned. +*/ + +/*! + \fn type *QPtrDictIterator::operator++() + Prefix ++ makes the succeeding item current and returns the new current + item. + + If the current iterator item was the last item in the dictionary or if it + was null, null is returned. +*/ + +/*! + \fn type *QPtrDictIterator::operator+=( uint jump ) + Sets the current item to the item \e jump positions after the current item, + and returns a pointer to that item. + + If that item is beyond the last item or if the dictionary is empty, + it sets the current item to null and returns null. +*/ diff --git a/qtools/qsortedlist.doc b/qtools/qsortedlist.doc new file mode 100644 index 0000000..12d3f02 --- /dev/null +++ b/qtools/qsortedlist.doc @@ -0,0 +1,94 @@ +/**************************************************************************** +** $Id$ +** +** QSortedList documentation +** +** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be distributed under the terms of the Q Public License +** as defined by Trolltech AS of Norway and appearing in the file +** LICENSE.QPL included in the packaging of this file. +** +** This file may be distributed and/or modified under the terms of the +** GNU General Public License version 2 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. +** +** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition +** 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 +** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +** +** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for +** information about Qt Commercial License Agreements. +** See http://www.trolltech.com/qpl/ for QPL licensing information. +** See http://www.trolltech.com/gpl/ for GPL licensing information. +** +** Contact info@trolltech.com if any conditions of this licensing are +** not clear to you. +** +**********************************************************************/ + + +/***************************************************************************** + QSortedList documentation + *****************************************************************************/ + +/*! + \class QSortedList qsortedlist.h + \brief The QSortedList class provides a list sorted by operator< and operator== + + \ingroup collection + \ingroup tools + + If you want to sort a QList you have to reimplement the + QGList::compareItems() method. If the elements of your list support + operator<() and operator==() then you can use QSortedList instead. + Its compareItems() calls operator<() and operator==() and returns an + appropriate result. + + Otherwise, this is as QList. + + \sa QList, \link collection.html Collection Classes\endlink +*/ + + +/*! + \fn QSortedList::QSortedList() + Constructs an empty list. +*/ + +/*! + \fn QSortedList::QSortedList( const QSortedList &list ) + Constructs a copy of \e list. + + Each item in \e list is copied to this new list. +*/ + +/*! + \fn QSortedList::~QSortedList() + Removes all items from the list and destroys the list. + + All list iterators that access this list will be reset. +*/ + +/*! + \fn QSortedList& QSortedList::operator=(const QSortedList& list) + Assigns \e list to this list and returns a reference to this list. + + This list is first cleared, then each item in \e list is + appended to this list. Only the pointers are copied + (shallow copy), unless newItem() has been reimplemented(). +*/ + +/*! + \fn int QSortedList::compareItems( QCollection::Item s1, QCollection::Item s2 ) + + \reimp + + This reimplementation uses operator< and operator== to compare. +*/ diff --git a/qtools/qstack.doc b/qtools/qstack.doc new file mode 100644 index 0000000..b51e7c0 --- /dev/null +++ b/qtools/qstack.doc @@ -0,0 +1,135 @@ +/**************************************************************************** +** $Id$ +** +** QStack class documentation +** +** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be distributed under the terms of the Q Public License +** as defined by Trolltech AS of Norway and appearing in the file +** LICENSE.QPL included in the packaging of this file. +** +** This file may be distributed and/or modified under the terms of the +** GNU General Public License version 2 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. +** +** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition +** 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 +** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +** +** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for +** information about Qt Commercial License Agreements. +** See http://www.trolltech.com/qpl/ for QPL licensing information. +** See http://www.trolltech.com/gpl/ for GPL licensing information. +** +** Contact info@trolltech.com if any conditions of this licensing are +** not clear to you. +** +**********************************************************************/ + + +/***************************************************************************** + QStack documentation + *****************************************************************************/ + +/*! + \class QStack qstack.h + \brief The QStack class is a template class that provides a stack. + + \ingroup collection + \ingroup tools + + QStack is implemented as a template class. Define a template + instance QStack\ to create a stack that operates on pointers to + X, or X*. + + A stack is a Last In, First Out (LIFO) structure. Items are added to + the top of the stack with push() and retrieved from the top + with pop(). + + \sa \link collection.html Collection Classes\endlink +*/ + +/*! \fn QStack::QStack () + Creates and empty stack. +*/ + +/*! \fn QStack::QStack (const QStack& s) + Creates a stack by making a shallow copy of another stack. +*/ + +/*! \fn QStack::~QStack () + Destroys the stack. All items will be deleted if autoDelete() is TRUE. +*/ + +/*! \fn QStack& QStack::operator= (const QStack& s) + Sets the contents of this stack by making a shallow copy of another stack. + Elements currently in this stack will be deleted if autoDelete() is TRUE. +*/ + +/*! \fn bool QStack::isEmpty () const + Returns TRUE is the stack contains no elements to be \link pop() popped\endlink. +*/ + +/*! \fn void QStack::push (const type* d) + Adds an element to the top of the stack. Last in, first out. +*/ + +/*! \fn type* QStack::pop () + Removes the top item from the stack and returns it. +*/ + +/*! \fn bool QStack::remove () + Removes the top item from the stack and deletes it if + autoDelete() is TRUE. Returns TRUE if there was an item to pop. + + \sa clear() +*/ + +/*! \fn void QStack::clear() + Removes all items from the stack, deleting them if + autoDelete() is TRUE. + + \sa remove() +*/ + +/*! \fn uint QStack::count() const + Returns the number of items in the stack. + + \sa isEmpty() +*/ + +/*! \fn type* QStack::top () const + Returns a reference to the top item on the stack (most recently pushed). + The stack is not changed. +*/ + +/*! \fn QStack::operator type* ()const + Returns a reference to the top item on the stack (most recently pushed). + The stack is not changed. +*/ + +/*! \fn type* QStack::current () const + Returns a reference to the top item on the stack (most recently pushed). + The stack is not changed. +*/ + +/*! \fn bool QStack::autoDelete() const + + The same as QCollection::autoDelete(). + + \sa setAutoDelete() +*/ + +/*! \fn void QStack::setAutoDelete( bool enable ) + + The same as QCollection::setAutoDelete(). + + \sa autoDelete() +*/ diff --git a/qtools/qstrlist.doc b/qtools/qstrlist.doc new file mode 100644 index 0000000..81e4e46 --- /dev/null +++ b/qtools/qstrlist.doc @@ -0,0 +1,5 @@ +/**************************************************************************** +** $Id$ +*****************************************************************************/ + +//typedef QListIterator QStrListIterator; diff --git a/qtools/qtl.doc b/qtools/qtl.doc new file mode 100644 index 0000000..e4ce0d0 --- /dev/null +++ b/qtools/qtl.doc @@ -0,0 +1,249 @@ +/**************************************************************************** +** $Id$ +** +** Qt template library classes documentation +** +** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be distributed under the terms of the Q Public License +** as defined by Trolltech AS of Norway and appearing in the file +** LICENSE.QPL included in the packaging of this file. +** +** This file may be distributed and/or modified under the terms of the +** GNU General Public License version 2 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. +** +** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition +** 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 +** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +** +** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for +** information about Qt Commercial License Agreements. +** See http://www.trolltech.com/qpl/ for QPL licensing information. +** See http://www.trolltech.com/gpl/ for GPL licensing information. +** +** Contact info@trolltech.com if any conditions of this licensing are +** not clear to you. +** +**********************************************************************/ + +/*! +\page qtl.html + +\title Qt Template library + +Thq Qt Template Library is a set of templates within Qt dealing with +containers of objects. It provides a list of objects, a stack of +objects, a map (or dictionary) from one type to another, and +associated iterators and algorithms. + +Qt also contains similar classes that deal with pointers to objects; +\l QValueList vs. \l QList, etc. Compared to the pointer-based +templates, the QTL offers easy copying of the container, real support +for classes that e.g. require constructors, expand to much more object +code, can often be a bit faster, require that the objects stored can +be copied, and finally, have a worse record of compiler problems. + +Compared to the STL, the QTL contains only the most important features +of the STL, has more regular function naming, has no platform +differences, is often a little slower and often expands to less object +code. + + +If you can not make copies of the objects you want to store you are +better off with QCollection and friends. They were designed to handle +exactly that kind of pointer semantics. This applies for example to +all classes derived from \l QObject. A QObject does not have a copy +constructor, so using it as value is impossible. You may choose be +store pointers to QObjects in a QValueList, but using QList directly +seems to be the better choice for this kind of application +domain. QList, like all other QCollection based containers, provides +far more sanity checking than a speed-optimized value +based container. + +If you have objects that implement value semantics, use the Qt +template library. Value semantics require at least +
    +
  • a copy constructor, +
  • an assignment operator and +
  • a default constructor, i.e. a constructor that does not take +any arguments. +
+Note that a fast copy constructor is absolutely crucial for a good +overall performance of the container, since many copy operations are +going to happen. + +Examples for value based classes are QRect, QPoint, QSize and all +simple C++ types like int, bool or double. + +The Qt template library is designed for speed. Especially iterators +are extremely fast. On the drawback side, less error checking is done +than in the QCollection based containers. A template library container +for example does not track associated iterators. This makes certain +validity checks, like on removing items, impossible to perform +automatically. + +

Iterators

+ +The Qt template library deals with value objects, not with pointers. +For that reason, there is no other way of iterating over containers +than using iterators. This is no disadvantage as the size of an +iterator matches the size of a normal pointer - 32 or 64 bits +depending on your CPU architecture. + +To iterate over a container, use a loop like this: + +\code + typedef QValueList List; + List l; + for( List::Iterator it = l.begin(); it != l.end(); ++it ) + printf("Number is %i\n",*it); +\endcode + +begin() returns the iterator pointing at the first element, while +end() returns an iterator that points \e after the last +element. end() marks an invalid position, it can never be +dereferenced. It's the break condition in any iteration, may it be +from begin() or fromLast(). For maximum speed, use increment or +decrement iterators with the prefix operator (++it, --it) instead of the the +postfix one (it++, it--), since the former is slightly faster. + +The same concept applies to the other container classes: + +\code + typedef QMap Map; + Map map; + for( Map::Iterator it = map.begin(); it != map.end(); ++it ) + printf("Key=%s Data=%s\n", it.key().ascii(), it.data().ascii() ); + + typedef QArray Array; + Array array; + for( Array::Iterator it = array.begin(); it != array.end(); ++it ) + printf("Data=%i\n", *it ); +\endcode + +There are two kind of iterators, the volatile iterator shown in the +examples above and a version that returns a const reference to its +current object, the ConstIterator. Const iterators are required +whenever the container itself is const, such as a member variable +inside a const function. Assigning a ConstIterator to a normal +Iterator is not allowed as it would violate const semantics. + +

Algorithms

+ +The template library defines a number of algorithms that operate on +its containers: qHeapSort(), qBubbleSort(), qSwap() and +qCopy(). These algorithms are implemented as template functions. + +qHeapSort() and qBubbleSort() provide the well known sorting +algorithms. You can use them like this: + +\code + typedef QValueList List; + List l; + l << 42 << 100 << 1234 << 12 << 8; + qHeapSort( l ); + + List l2; + l2 << 42 << 100 << 1234 << 12 << 8; + List::Iterator b = l2.find( 100 ); + List::Iterator e = l2.find( 8 ); + qHeapSort( b, e ); + + double arr[] = { 3.2, 5.6, 8.9 }; + qHeapSort( arr, arr + 3 ); +\endcode + +The first example sorts the entire list. The second one sorts all +elements enclosed in the two iterators, namely 100, 1234 and 12. The +third example shows that iterators act like pointers and can be +treated as such. + +Naturally, the sorting templates won't work with const iterators. + +Another utility is qSwap(). It exchanges the values of two variables: + +\code + QString second( "Einstein" ); + QString name( "Albert" ); + qSwap( second, name ); +\endcode + +Another template function is qCopy(). It copies a container or a slice +of it to an OutputIterator, in this case a QTextOStreamIterator: + +\code + typedef QValueList List; + List l; + l << 100 << 200 << 300; + QTextOStream str( stdout ); + qCopy( l, QTextOStreamIterator( str ) ); +\endcode + +In addition, you can use any Qt template library iterator as the +OutputIterator. Just make sure that the right hand of the iterator has +as many elements present as you want to insert. The following example +illustrates this: + +\code + QStringList l1, l2; + l1 << "Weis" << "Ettrich" << "Arnt" << "Sue"; + l2 << "Torben" << "Matthias"; + qCopy( l2, l1.begin(); +\endcode + +At the end of this code fragment, the List l1 contains "Torben", +"Matthias", "Arnt" and "Sue", with the prior contents being +overwritten. Another flavor of qCopy() takes three arguments to make +it possible to copy a slice of a container: + +\code + typedef QValueList List; + List l; + l << 42 << 100 << 1234 << 12 << 8; + List::Iterator b = l.find( 100 ); + List::Iterator e = l.find( 8 ); + QTextOStream str( stdout ); + qCopy( b, e, QTextOStreamIterator( str ) ); +\endcode + +If you write new algorithms, consider writing them as template +functions in order to make them usable with as many containers +possible. In the above example, you could just as easily print out a +standard C++ array with qCopy(): + +\code + int arr[] = { 100, 200, 300 }; + QTextOStream str( stdout ); + qCopy( arr, arr + 3, QTextOStreamIterator( str ) ); +\endcode + + +

Streaming

+ +All mentioned containers can be serialized with the respective +streaming operators. Here is an example. + +\code + QDataStream str(...); + QValueList l; + // ... fill the list here + str << l; +\endcode + +The container can be read in again with: + +\code + QValueList l; + str >> l; +\endcode + +The same applies to QStringList, QValueStack and QMap. + +*/ diff --git a/qtools/qvaluelist.doc b/qtools/qvaluelist.doc new file mode 100644 index 0000000..6aa95d8 --- /dev/null +++ b/qtools/qvaluelist.doc @@ -0,0 +1,772 @@ +/**************************************************************************** +** $Id$ +** +** QValueList and QValueListIterator class documentation +** +** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be distributed under the terms of the Q Public License +** as defined by Trolltech AS of Norway and appearing in the file +** LICENSE.QPL included in the packaging of this file. +** +** This file may be distributed and/or modified under the terms of the +** GNU General Public License version 2 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. +** +** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition +** 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 +** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +** +** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for +** information about Qt Commercial License Agreements. +** See http://www.trolltech.com/qpl/ for QPL licensing information. +** See http://www.trolltech.com/gpl/ for GPL licensing information. +** +** Contact info@trolltech.com if any conditions of this licensing are +** not clear to you. +** +**********************************************************************/ + + +/***************************************************************************** + QValueList documentation + *****************************************************************************/ + +/*! + \class QValueList qvaluelist.h + \brief The QValueList class is a value based template class that provides doubly linked lists. + + \ingroup qtl + \ingroup tools + \ingroup shared + + Define a template instance QValueList\ to create a list of values which all + have the class X. Please notice that QValueList does not store pointers to the + members of the list. It holds a copy of every member. That is the reason why this + kind of classes are called "value based" while QList and QDict are "reference based". + + Some classes can not be used within a QValueList, for example everything + derived from QObject and thus all classes that implement widgets. + Only values can be used in a QValueList. To qualify as a value, the class + must provide +
    +
  • a copy constructor, +
  • an assignment operator and +
  • a default constructor, i.e. a constructor that does not take any arguments. +
+ + Note that C++ defaults to field-by-field assignment operators and + copy constructors if no explicit version is supplied. In many cases, + this is sufficient. + + Example: + \code + #include + #include + #include + + class Employee + { + public: + Employee(): s(0) {} + Employee( const QString& name, int salary ) + : n(name), s(salary) + {} + + QString name() const { return n; } + int salary() const { return s; } + void setSalary( int salary ) { s = salary; } + private: + QString n; + int s; + }; + + void main() + { + typedef QValueList EmployeeList; + EmployeeList list; // list of Employee + + list.append( Employee("Bill", 50000) ); + list.append( Employee("Steve",80000) ); + list.append( Employee("Ron", 60000) ); + + Employee joe( "Joe", 50000 ); + list.append( joe ); + joe.setSalary( 4000 ); + + EmployeeList::Iterator it; + for( it = list.begin(); it != list.end(); ++it ) + printf( "%s earns %d\n", (*it).name().latin1(), (*it).salary().latin1() ); + } + \endcode + + Program output: + \code + Bill earns 50000 + Steve earns 80000 + Ron earns 60000 + Joe earns 50000 + \endcode + + As you can see, the latest changes to Joes salary did not affect the value + in the list because the list created a copy of Joes entry. + + There are three ways of finding items in the list. The first one is by using + the at() function. It returns an iterator. The advantages of + getting an iterator is that you can now move forward or backward from this + position by incrementing/decrementing the iterator. To get the amount of + items in the list call count(). Valid indices are 0..count(). + + The second way of accessing a list is with operator[]. That means you can address + it like an array. The return value is a reference to the value stored in the list. + There exist two versions of this operator. The first one is const and returns a + const reference to the value. The second on is non const and returns a non const + reference to the value. It is up to your compiler to choose the correct one. + + The third method is to use the functions begin() and end(). + With a simple for loop as shown in the example you can iterate over the complete list. + It is save to have multiple iterators at the same time. If some member of the list is + removed then only iterators pointing to the removed member become invalid. Inserting in + the list does not invalidate any iterator. For convenience the function last() returns + an iterator for the last and first() for the first element in the list. + + In addition you can search items in the list with the find() function. It exists in a const + and a non const version. It starts searching from the beginning of the list, but another + flavor of the find() function allows you to specify where searching should start. + If you just want to know wether a certain item is at least once in the list, then you + can use the contains() function. + + Since QValueList is value based there is no need to care about deleting elements in the + list. The list holds its own copies and will free them if the corresponding member or + the list itself is deleted. You can force the list to free all of its item with clear(). + + QValueList is implicitly shared. That means you can just make copies of the list + in time O(1). If multiple QValueList instances share the same data and one + is doing a modification of the lists data then this modifying instance makes a copy + and modifies its private copy. So it does not affect the other instances. + From a developers point of view you can think that a QValueList and a copy of this + list have nothing to do with each other. Developers may only notice that copying is + very fast. People known to a CPUs MMU architecture will know this pattern as "copy on write". + + There exist three functions to insert items in the list. append() + inserts an item at the end, prepend() inserts at the beginning + and insert() inserts in front of the position given by an iterator. + + Items can be removed from the list in two ways. The first is to pass an iterator to + the remove(). The other possibility is to pass a value to remove() which will + delete all members which match this value. + + Lists can be sorted with the algorithms provided by the Qt Template Library, for example with + qHeapSort(): + + Example: + \code + QValueList l; + l.append( 5 ); + l.append( 8 ); + l.append( 3 ); + l.append( 4 ); + qHeapSort( l ); + \endcode + + \sa QValueListIterator +*/ + + +/*! + \fn QValueList::QValueList() + Constructs an empty list. +*/ + +/*! + \fn QValueList::QValueList( const QValueList& l ) + Constructs a copy of \e l. + + This operation costs O(1) time since QValueList is implicit shared. + The first instance applying modifications to a shared list will create + a copy which takes in turn O(n) time. However returning a QValueList from + a function is very fast. +*/ + +/*! + \fn QValueList::~QValueList() + Destroys the list. References to the values in the list and all iterators + of this list become invalidated. Since QValueList is highly tuned for performance + you wont see warnings if you use invalid iterators, + because it is impossible for + an iterator to check wether it is valid or not. +*/ + +/*! + \fn QValueList& QValueList::operator= ( const QValueList& l ) + Assigns \e l to this list and returns a reference to this list. + + All iterators of the current list become invalidated by this operation. + The cost of such an assignment is O(1) since QValueList is implicitly shared. +*/ + +/*! + \fn QValueList QValueList::operator+ ( const QValueList& l ) const + Creates a new list and fills it with the elements of this list. Then the + elements of \e l are appended. + + Returns the new list. +*/ + +/*! + \fn QValueList& QValueList::operator+= ( const QValueList& l ) + Adds \e list to this list. + + Returns a reference to this list. +*/ + +/*! + \fn bool QValueList::operator== ( const QValueList& l ) const + Compares both lists. + + Returns TRUE if both list are equal. +*/ + +/*! + \fn bool QValueList::operator!= ( const QValueList& l ) const + Compares both lists. + + Returns TRUE if both list are unequal. +*/ + +/*! + \fn QValueList& QValueList::operator+= ( const T& x ) + Adds the value \e x to the end of the list. + + Returns a reference to the list. +*/ + +/*! + \fn QValueList& QValueList::operator<< ( const T& x ) + Adds the value \e x to the end of the list. + + Returns a reference to the list. +*/ + +/*! + \fn const T& QValueList::operator[] ( uint i ) const + Returns a const reference to the item with index \e i in the list. + It is up to you to check wether this item really exists. You can do that easily + with the count() function. However this operator does not check wether \e i + is in range and will deliver undefined results if it does not exist. +*/ + +/*! + \fn T& QValueList::operator[] ( uint i ) + Returns a reference to the item with index \e i in the list. + It is up to you to check wether this item really exists. You can do that easily + with the count() function. However this operator does not check wether \e i + is in range and will deliver undefined results if it does not exist. + In contrast to the const operator[] you may manipulate the value returned by this + operator. +*/ + +/*! + \fn uint QValueList::count() const + Returns the number of items in the list. + \sa isEmpty() +*/ + +/*! + \fn bool QValueList::isEmpty() const + Returns TRUE if the list is empty, i.e. count() == 0. Returns FALSE + otherwise. + \sa count() +*/ + +/*! + \fn Iterator QValueList::insert( Iterator it, const T& x ) + Inserts the value \e x in front of the iterator \e it. + + Returns an iterator pointing at the inserted item. + + \sa append(), prepend() +*/ + +/*! + \fn Iterator QValueList::append( const T& x ) + Inserts the value \e x at the end of the list. + + Returns an iterator pointing at the inserted item. + + \sa insert(), prepend() +*/ + +/*! + \fn Iterator QValueList::prepend( const T& x ) + Inserts the value \e x at the beginning of the list. + + Returns an iterator pointing at the inserted item. + + \sa insert(), append() +*/ + +/*! + \fn Iterator QValueList::remove( Iterator it ) + Removes the item at position \e it in the list. + + Returns an iterator pointing to the item following the + removed on or end() if the last item was deleted. + + \sa clear() +*/ + +/*! + \fn void QValueList::remove( const T& x ) + Removes all items which have the value \e x. + + \sa clear() +*/ + +/*! + \fn void QValueList::clear() + Removes all items from the list. + + \sa remove() +*/ + +/*! + \fn Iterator QValueList::find( const T& x ) + Finds the first occurrence of \e x in the list. + + Returns end() if no item did match. +*/ + +/*! + \fn ConstIterator QValueList::find( const T& x ) const + Finds the first occurrence of \e x in the list. + + Returns end() if no item did match. +*/ + +/*! + \fn Iterator QValueList::find( Iterator it, const T& x ) + Finds the first occurrence of \e x in the list starting at + the position given by \e it. + + Returns end() if no item did match. +*/ + +/*! + \fn ConstIterator QValueList::find( ConstIterator it, const T& x ) const + Finds the first occurrence of \e x in the list starting at + the position given by \e it. + + Returns end() if no item did match. +*/ + +/*! + \fn uint QValueList::contains( const T& x ) const + Counts and returns the number of occurrences of the value \e x in the list. +*/ + +/*! + \fn int QValueList::findIndex( const T& x ) const + Returns the first index of the value \e x in the list or -1 if no such value + can be found in the list. +*/ + +/*! + \fn Iterator QValueList::at( uint i ) + Returns an iterator pointing to the item at position \e i in the list, or + end() if the index is out of range. +*/ + +/*! + \fn ConstIterator QValueList::at( uint i ) const + Returns an iterator pointing to the item at position \e i in the list, or + end() if the index is out of range. +*/ + +/*! + \fn T& QValueList::first() + Returns a reference to the first item in the list or the item + referenced by end() + if no such items exists. Please note that you may not change + the value the end() Iterator is pointing to. + + \sa begin(), last() +*/ + +/*! + \fn const T& QValueList::first() const + Returns a reference to the first item in the list or the item + referenced by end() if + no such items exists. + + \sa begin(), last() +*/ + +/*! + \fn Iterator QValueList::fromLast() + Returns an iterator pointing to the last element in the list or + end() if no such item exists. + + \sa last() +*/ + +/*! + \fn ConstIterator QValueList::fromLast() const + Returns an iterator pointing to the last element in the list or + end() if no such item exists. + + \sa last() +*/ + +/*! + \fn T& QValueList::last() + Returns a reference to the last item in the list or the item + referenced by end() if no + such item exists. Please note that you may not change + the value the end() Iterator is pointing to. + + \sa end(), first(), fromLast() +*/ + +/*! + \fn const T& QValueList::last() const + Returns a reference to the last item in the list or the item + referenced by end() if no such item exists. + + \sa end(), first(), fromLast() +*/ + +/*! + \fn Iterator QValueList::begin() + Returns an iterator pointing to the first element in the list. This + iterator equals end() if the list is empty; + \sa first(), end() +*/ + +/*! + \fn ConstIterator QValueList::begin() const + Returns an iterator pointing to the first element in the list. This + iterator equals end() if the list is empty; + \sa first(), end() +*/ + +/*! + \fn Iterator QValueList::end() + Returns an iterator pointing behind the last element in the list. This + iterator equals begin() if the list is empty. + + \sa last(), begin() +*/ + +/*! + \fn ConstIterator QValueList::end() const + Returns an iterator pointing behind the last element in the list. This + iterator equals begin() if the list is empty. + + \sa last(), begin() +*/ + +/*! + \fn void QValueList::detach() + If the list does not share its data with another QValueList instance, then nothing + happens, otherwise the function creates a new copy of this data and detaches + from the shared one. This function is called whenever the list is modified. + The implicit sharing mechanism is implemented this way. +*/ + +/*! + \fn QDataStream& operator>>( QDataStream& s, QValueList& l ) + \relates QValueList + Reads a list from the stream. The type \e T stored in the list must implement + the streaming operator, too. +*/ + +/*! + \fn QDataStream& operator<<( QDataStream& s, const QValueList& l ) + \relates QValueList + Writes a list to the stream. The type \e T stored in the list must implement + the streaming operator, too. +*/ + +/***************************************************************************** + QValueListIterator documentation + *****************************************************************************/ + +/*! + \class QValueListIterator qvaluelist.h + \brief The QValueListIterator class provides an iterator for QValueList. + + \ingroup qtl + \ingroup tools + + You can not create an iterator by yourself. Instead you have to + ask a list to give you one. An iterator has only the size of a pointer. + On 32 bit machines that means 4 bytes otherwise 8 bytes. That makes them + very fast. In fact they resemble the semantics of pointers as good as possible + and they are almost as fast as usual pointers. + + Example: + \code + #include + #include + #include + + class Employee + { + public: + Employee(): s(0) {} + Employee( const QString& name, int salary ) + : n(name), s(salary) + {} + + QString name() const { return n; } + int salary() const { return s; } + void setSalary( int salary ) { s = salary; } + private: + QString n; + int s; + }; + + void main() + { + typedef QValueList EmployeeList; + EmployeeList list; // list of Employee + + list.append( Employee("Bill", 50000) ); + list.append( Employee("Steve",80000) ); + list.append( Employee("Ron", 60000) ); + + Employee joe( "Joe", 50000 ); + list.append( joe ); + joe.setSalary( 4000 ); + + EmployeeList::Iterator it; + for( it = list.begin(); it != list.end(); ++it ) + printf( "%s earns %d\n", (*it).name().latin1(), (*it).salary() ); + } + \endcode + + Program output: + \code + Bill earns 50000 + Steve earns 80000 + Ron earns 60000 + Joe earns 50000 + \endcode + + In contrast to QList there are no built in functions in QValueList to + traverse the list. The only way to do this is to use iterators. + QValueList is highly optimized for performance and memory usage. + On the other hand that means that you have to be a bit more careful + by what you are doing. QValueList does not know about all its iterators + and the iterators dont even know to which list they belong. That makes + things fast and slim but a bit dangerous because it is up to you to make + sure that iterators you are using are still valid. QListIterator will be able + to give warnings while QValueListIterator may end up in an undefined state. + + For every Iterator there is a ConstIterator. When accessing a QValueList + in a const environment or if the reference or pointer to the list is itself + const, then you have to use the ConstIterator. Its semantics are the same, + but it returns only const references to the item it points to. + + \sa QValueList, QValueListConstIterator +*/ + +/*! + \fn QValueListIterator::QValueListIterator() + Creates un uninitialized iterator. +*/ + +/*! + \fn QValueListIterator::QValueListIterator( NodePtr p ) + Internal function. +*/ + +/*! + \fn QValueListIterator::QValueListIterator( const QValueListIterator& it ) + Constructs a copy of the iterator \e it. +*/ + +/*! + \fn QValueListIterator::~QValueListIterator() + Destroys the iterator. +*/ + +/* Unfortunately not with MSVC + \fn T *QValueListIterator::operator->() + Pointer operator. Returns a pointer to the current iterator item. + The great advantage of this operator is that you can treat the + iterator like a pointer. + + Example: + \code + QValueList::Iterator it = list.begin(); + for( ; it != end(); ++it ) + it->show(); + \endcode +*/ + +/*! + \fn T& QValueListIterator::operator*() + Asterix operator. Returns a reference to the current iterator item. +*/ + +/*! + \fn const T& QValueListIterator::operator*() const + Asterix operator. Returns a reference to the current iterator item. +*/ + +/*! + \fn QValueListIterator& QValueListIterator::operator++() + Prefix ++ makes the succeeding item current and returns + an iterator pointing to the new current item. + The iterator can not check wether it reached the end of the list. Incrementing + the iterator as returned by end() causes undefined results. +*/ + +/*! + \fn QValueListIterator QValueListIterator::operator++(int) + Postfix ++ makes the succeeding item current and returns + an iterator pointing to the new current item. + The iterator can not check wether it reached the end of the list. Incrementing + the iterator as returned by end() causes undefined results. +*/ + +/*! + \fn QValueListIterator& QValueListIterator::operator--() + Prefix -- makes the previous item current and returns + an iterator pointing to the new current item. + The iterator can not check wether it reached the beginning of the list. Decrementing + the iterator as returned by begin() causes undefined results. +*/ + +/*! + \fn QValueListIterator QValueListIterator::operator--(int) + Postfix -- makes the previous item current and returns + an iterator pointing to the new current item. + The iterator can not check wether it reached the beginning of the list. Decrementing + the iterator as returned by begin() causes undefined results. +*/ + +/*! + \fn bool QValueListIterator::operator==( const QValueListIterator& it ) const + Compares both iterators and returns TRUE if they point to the same item. +*/ + +/*! + \fn bool QValueListIterator::operator!=( const QValueListIterator& it ) const + Compares both iterators and returns TRUE if they point to different items. +*/ + +/***************************************************************************** + QValueListConstIterator documentation + *****************************************************************************/ + +/*! + \class QValueListConstIterator qvaluelist.h + \brief The QValueListConstIterator class provides an iterator for QValueList. + + \ingroup qtl + \ingroup tools + + In contrast to QValueListIterator this class is used to iterate over a const + list. It does not allow to modify the values of the list since this would + break the const semantics. + + For more informations on QValueList iterators see QValueListIterator. + + \sa QValueListIterator, QValueList +*/ + +/*! + \fn QValueListConstIterator::QValueListConstIterator() + Creates un uninitialized iterator. +*/ + +/*! + \fn QValueListConstIterator::QValueListConstIterator( NodePtr p ) + Internal function. +*/ + +/*! + \fn QValueListConstIterator::QValueListConstIterator( const QValueListConstIterator& it ) + Constructs a copy of the iterator \e it. +*/ + +/*! + \fn QValueListConstIterator::QValueListConstIterator( const QValueListIterator& it ) + Constructs a copy of the iterator \e it. +*/ + +/*! + \fn QValueListConstIterator::~QValueListConstIterator() + Destroys the iterator. +*/ + +/* Unfortunately not with MSVC + \fn const T *QValueListConstIterator::operator->() + Pointer operator. Returns a pointer to the current iterator item. + The great advantage of this operator is that you can treat the + iterator like a pointer. + + Example: + \code + QValueList::Iterator it = list.begin(); + for( ; it != end(); ++it ) + it->show(); + \endcode +*/ + +/*! + \fn const T& QValueListConstIterator::operator*() const + Asterix operator. Returns a reference to the current iterator item. +*/ + +/*! + \fn QValueListConstIterator& QValueListConstIterator::operator++() + Prefix ++ makes the succeeding item current and returns + an iterator pointing to the new current item. + The iterator can not check wether it reached the end of the list. Incrementing + the iterator as returned by end() causes undefined results. +*/ + +/*! + \fn QValueListConstIterator QValueListConstIterator::operator++(int) + Postfix ++ makes the succeeding item current and returns + an iterator pointing to the new current item. + The iterator can not check wether it reached the end of the list. Incrementing + the iterator as returned by end() causes undefined results. +*/ + +/*! + \fn QValueListConstIterator& QValueListConstIterator::operator--() + Prefix -- makes the previous item current and returns + an iterator pointing to the new current item. + The iterator can not check wether it reached the beginning of the list. Decrementing + the iterator as returned by begin() causes undefined results. +*/ + +/*! + \fn QValueListConstIterator QValueListConstIterator::operator--(int) + Postfix -- makes the previous item current and returns + an iterator pointing to the new current item. + The iterator can not check wether it reached the beginning of the list. Decrementing + the iterator as returned by begin() causes undefined results. +*/ + +/*! + \fn bool QValueListConstIterator::operator==( const QValueListConstIterator& it ) const + Compares both iterators and returns TRUE if they point to the same item. +*/ + +/*! + \fn bool QValueListConstIterator::operator!=( const QValueListConstIterator& it ) const + Compares both iterators and returns TRUE if they point to different items. +*/ diff --git a/qtools/qvector.doc b/qtools/qvector.doc new file mode 100644 index 0000000..24309e3 --- /dev/null +++ b/qtools/qvector.doc @@ -0,0 +1,344 @@ +/**************************************************************************** +** $Id$ +** +** QVector class documentation +** +** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be distributed under the terms of the Q Public License +** as defined by Trolltech AS of Norway and appearing in the file +** LICENSE.QPL included in the packaging of this file. +** +** This file may be distributed and/or modified under the terms of the +** GNU General Public License version 2 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. +** +** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition +** 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 +** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +** +** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for +** information about Qt Commercial License Agreements. +** See http://www.trolltech.com/qpl/ for QPL licensing information. +** See http://www.trolltech.com/gpl/ for GPL licensing information. +** +** Contact info@trolltech.com if any conditions of this licensing are +** not clear to you. +** +**********************************************************************/ + + +/***************************************************************************** + QVector documentation + *****************************************************************************/ + +// BEING REVISED: ettrich +/*! + \class QVector qvector.h + + \brief The QVector class is a template collection class that + provides a vector (array). + + \ingroup tools + + QVector is implemented as a template class. Define a template + instance QVector\ to create a vector that contains pointers to + X, or X*. + + A vector is the same as an array. The main difference between + QVector and QArray is that QVector stores pointers to the elements, + while QArray stores the elements themselves (i.e. QArray is + value-based). + + Unless where otherwise stated, all functions that remove items from + the vector will also delete the element pointed to if auto-deletion + is enabled - see setAutoDelete(). By default, auto-deletion is + disabled. This behaviour can be changed in a subclass by + reimplementing the virtual method deleteItem(). + + Functions that compares items, e.g. find() and sort(), will do so + using the virtual function compareItems(). The default + implementation of this function will only compare the absolute + pointer values. Reimplement compareItems() in a subclass to get + searching and sorting based on the item contents. + + \sa \link collection.html Collection Classes\endlink, QArray +*/ + +/*! + \fn QVector::QVector() + + Constructs a null vector. + + \sa isNull() +*/ + +/*! + \fn QVector::QVector( uint size ) + + Constructs an vector with room for \a size items. Makes a null + vector if \a size == 0. + + All \a size positions in the vector are initialized to 0. + + \sa size(), resize(), isNull() +*/ + +/*! + \fn QVector::QVector( const QVector &v ) + + Constructs a copy of \a v. Only the pointers are copied (i.e. shallow copy). +*/ + +/*! + \fn QVector::~QVector() + + Removes all items from the vector, and destroys the vector itself. + + \sa clear() +*/ + +/*! + \fn QVector &QVector::operator=( const QVector &v ) + + Assigns \a v to this vector and returns a reference to this vector. + + This vector is first cleared, then all the items from \a v is copied + into this vector. Only the pointers are copied (i.e. shallow copy). + + \sa clear() +*/ + +/*! + \fn type **QVector::data() const + Returns a pointer to the actual vector data, which is an array of type*. + + The vector is a null vector if data() == 0 (null pointer). + + \sa isNull() +*/ + +/*! + \fn uint QVector::size() const + + Returns the size of the vector, i.e. the number of vector + positions. This is also the maximum number of items the vector can + hold. + + The vector is a null vector if size() == 0. + + \sa isNull(), resize(), count() +*/ + +/*! + \fn uint QVector::count() const + + Returns the number of items in the vector. The vector is empty if + count() == 0. + + \sa isEmpty(), size() +*/ + +/*! + \fn bool QVector::isEmpty() const + + Returns TRUE if the vector is empty, i.e. count() == 0, otherwise FALSE. + + \sa count() +*/ + +/*! + \fn bool QVector::isNull() const + + Returns TRUE if the vector is null, otherwise FALSE. + + A null vector has size() == 0 and data() == 0. + + \sa size() +*/ + +/*! + \fn bool QVector::resize( uint size ) + Resizes (expands or shrinks) the vector to \a size elements. The array + becomes a null array if \a size == 0. + + Any items in position \a size or beyond in the vector are removed. + New positions are initialized 0. + + Returns TRUE if successful, or FALSE if the memory cannot be allocated. + + \sa size(), isNull() +*/ + +/*! + \fn bool QVector::insert( uint i, const type *d ) + + Sets position \a i in the vector to contain the item \a d. \a i must + be less than size(). Any previous element in position \a i is removed. + + \sa at() +*/ + +/*! + \fn bool QVector::remove( uint i ) + + Removes the item at position \a i in the vector, if there is one. + \a i must be less than size(). + + Returns TRUE unless \a i is out of range. + + \sa take(), at() +*/ + +/*! + \fn type* QVector::take( uint i ) + + Returns the item at position \a i in the vector, and removes that + item from the vector. \a i must be less than size(). If there is no + item at position \a i, 0 is returned. + + In contrast to remove(), this function does \e not call deleteItem() + for the removed item. + + \sa remove(), at() +*/ + +/*! + \fn void QVector::clear() + + Removes all items from the vector, and destroys the vector + itself. + + The vector becomes a null vector. + + \sa isNull() +*/ + +/*! + \fn bool QVector::fill( const type *d, int size ) + + Inserts item \a d in all positions in the vector. Any existing items + are removed. If \a d is 0, the vector becomes empty. + + If \a size >= 0, the vector is first resized to \a size. By default, + \a size is -1. + + Returns TRUE if successful, or FALSE if the memory cannot be allocated + (only if a resize has been requested). + + \sa resize(), insert(), isEmpty() +*/ + +/*! + \fn void QVector::sort() + + Sorts the items in ascending order. Any empty positions will be put + last. + + Compares items using the virtual function compareItems(). + + \sa bsearch() +*/ + +/*! + \fn int QVector::bsearch( const type* d ) const + + In a sorted array, finds the first occurrence of \a d using binary + search. For a sorted array, this is generally much faster than + find(), which does a linear search. + + Returns the position of \a d, or -1 if \a d could not be found. \a d + may not be 0. + + Compares items using the virtual function compareItems(). + + \sa sort(), find() +*/ + + +/*! + \fn int QVector::findRef( const type *d, uint i ) const + + Finds the first occurrence of the item pointer \a d in the vector, + using linear search. The search starts at position \a i, which must + be less than size(). \a i is by default 0; i.e. the search starts at + the start of the vector. + + Returns the position of \a d, or -1 if \a d could not be found. + + This function does \e not use compareItems() to compare items. + + \sa find(), bsearch() +*/ + +/*! + \fn int QVector::find( const type *d, uint i ) const + + Finds the first occurrence of item \a d in the vector, using linear + search. The search starts at position \a i, which must be less than + size(). \a i is by default 0; i.e. the search starts at the start of + the vector. + + Returns the position of \e v, or -1 if \e v could not be found. + + Compares items using the virtual function compareItems(). + + \sa findRef(), bsearch() +*/ + + +/*! + \fn uint QVector::containsRef( const type *d ) const + + Returns the number of occurrences of the item pointer \a d in the + vector. + + This function does \e not use compareItems() to compare items. + + \sa findRef() +*/ + +/*! + \fn uint QVector::contains( const type *d ) const + + Returns the number of occurrences of item \a d in the vector. + + Compares items using the virtual function compareItems(). + + \sa containsRef() +*/ + +/*! + \fn type *QVector::operator[]( int i ) const + + Returns the item at position \a i, or 0 if there is no item at + that position. \a i must be less than size(). + + Equivalent to at( \a i ). + + \sa at() +*/ + +/*! + \fn type *QVector::at( uint i ) const + + Returns the item at position \a i, or 0 if there is no item at + that position. \a i must be less than size(). +*/ + + +/*! + \fn void QVector::toList( QGList *list ) const + + Copies all items in this vector to the list \a list. First, \a list + is cleared, then all items are appended to \a list. + + \sa QList, QStack, QQueue +*/ + diff --git a/src/classdef.cpp b/src/classdef.cpp index 8111928..24ca56f 100644 --- a/src/classdef.cpp +++ b/src/classdef.cpp @@ -1232,7 +1232,8 @@ void ClassDef::writeMemberList(OutputList &ol) ol.writeObjectLink(getReference(),getOutputFileBase(),0,name()); parseText(ol,theTranslator->trIncludingInheritedMembers()); - ol.startItemList(); + //ol.startItemList(); + ol.writeString("\n"); //MemberNameInfo *mni=m_allMemberNameInfoList->first(); MemberNameInfoSDict::Iterator mnii(*m_allMemberNameInfoSDict); @@ -1244,17 +1245,6 @@ void ClassDef::writeMemberList(OutputList &ol) { MemberDef *md=mi->memberDef; ClassDef *cd=md->getClassDef(); - - // compute the protection level for this member - //Protection prot=md->protection(); - //if (mi->prot==Protected) // inherited protection: Protected - //{ - // if (prot==Public) prot=Protected; - //} - //else if (mi->prot==Private) // inherited protection: Private - //{ - // prot=Private; - //} Protection prot = mi->prot; //printf("%s: Member %s of class %s md->protection()=%d mi->prot=%d prot=%d inherited=%d\n", @@ -1268,23 +1258,15 @@ void ClassDef::writeMemberList(OutputList &ol) rmd = rmd->reimplements(); } - if (cd && !md->name().isEmpty() && md->name()[0]!='@' - // && - //( - // md->isFriend() - // || - //(/*mi->prot!=Private &&*/ - // (prot!=Private || Config_getBool("EXTRACT_PRIVATE")) - //) - //) - ) + if (cd && !md->name().isEmpty() && md->name()[0]!='@') { bool memberWritten=FALSE; if (cd->isLinkable() && md->isLinkable()) // create a link to the documentation { QCString name=mi->ambiguityResolutionScope+md->name(); - ol.writeListItem(); + //ol.writeListItem(); + ol.writeString(" "); memberWritten=TRUE; } else if (!Config_getBool("HIDE_UNDOC_MEMBERS")) // no documentation, // generate link to the class instead. { - ol.writeListItem(); + //ol.writeListItem(); + ol.writeString(" "); memberWritten=TRUE; } + if (memberWritten) + { + ol.writeString(""); + ol.writeString(""); + ol.writeString("\n"); + } } mi=mni->next(); } } - ol.endItemList(); + //ol.endItemList(); + + ol.writeString("
"); ol.writeObjectLink(cd->getReference(),cd->getOutputFileBase(), md->anchor(),name); if ( md->isFunction() || md->isSignal() || md->isSlot() || @@ -1298,13 +1280,15 @@ void ClassDef::writeMemberList(OutputList &ol) ol.docify(" typedef"); else if (md->isFriend() && !strcmp(md->typeString(),"friend class")) ol.docify(" class"); - ol.writeString("\n"); + //ol.writeString("\n"); + ol.writeString("
"); ol.startBold(); ol.docify(md->name()); ol.endBold(); @@ -1329,8 +1313,17 @@ void ClassDef::writeMemberList(OutputList &ol) ol.endBold(); } ol.writeString(")"); + ol.writeString(""); + ol.writeObjectLink(cd->getReference(),cd->getOutputFileBase(), + 0,cd->name()); + ol.writeString(""); + } if ((prot!=Public || virt!=Normal || md->isFriend() || md->isRelated() || md->isExplicit() || md->isMutable() || (md->isInline() && Config_getBool("INLINE_INFO")) || @@ -1368,11 +1361,19 @@ void ClassDef::writeMemberList(OutputList &ol) ol.docify("]"); ol.endTypewriter(); } + if (memberWritten) + { + ol.writeString("
"); + endFile(ol); ol.popGeneratorState(); } diff --git a/src/code.l b/src/code.l index 1a662af..d55da72 100644 --- a/src/code.l +++ b/src/code.l @@ -77,7 +77,6 @@ class CodeVarDef QCString classScope; }; -typedef QList CodeClassList; typedef QDict CodeClassDict; typedef QList CodeVarList; @@ -86,7 +85,6 @@ typedef QList CodeVarList; */ static OutputDocInterface * g_code; -//static CodeClassList g_codeClassList; static CodeClassDict g_codeClassDict(1009); static CodeVarList g_codeVarList; static CodeVarList g_codeParmList; diff --git a/src/doc.l b/src/doc.l index 3b06654..d0397f1 100644 --- a/src/doc.l +++ b/src/doc.l @@ -864,7 +864,7 @@ FILE ({FILESCHAR}*{FILEECHAR}+("."{FILESCHAR}*{FILEECHAR}+)*)|("\""[^\n\"]+ ID [a-z_A-Z][a-z_A-Z0-9]* SCOPENAME (({ID}?{BN}*"::"{BN}*)*)((~{BN}*)?{ID}) SCOPEMASK {ID}?(("::"|"#")?(~)?{ID})+ -URLMASK [a-z_A-Z0-9\~\:\?\@\&\%\#\.\-\+\/\=]+ +URLMASK ([^\>\"\n]+)|([a-z_A-Z0-9\~\:\?\@\&\%\#\.\-\+\/\=]+) NONTERM [\{\}\[\]\`\~\@\|\-\+\#\$\/\\\!\%\^\&\*()a-z_A-Z<>0-9\x80-\xff] WORD ({NONTERM}+([^\n\t ]*{NONTERM}+)?)|("\""[^\n\"]"\"") ATTR ({B}+[^>\n]*)? diff --git a/src/doxygen.cpp b/src/doxygen.cpp index 1605da3..9d3788f 100644 --- a/src/doxygen.cpp +++ b/src/doxygen.cpp @@ -2421,6 +2421,10 @@ static void findUsedClassesForClass(Entry *root, ClassDef *usedCd = Doxygen::hiddenClasses.find(type); if (usedCd==0 && !Config_getBool("HIDE_UNDOC_RELATIONS")) { + if (type.right(2)=="(*") // type is a function pointer + { + type+=md->argsString(); + } Debug::print(Debug::Classes,0," New undocumented used class `%s'\n", type.data()); usedCd = new ClassDef( masterCd->getDefFileName(),masterCd->getDefLine(), @@ -5012,19 +5016,23 @@ static void generateClassDocs() for ( ; cli.current() ; ++cli ) { ClassDef *cd=cli.current(); - if ( cd->isLinkableInProject() && cd->templateMaster()==0 && - (cd->getOuterScope()==0 || // <-- should not happen - cd->getOuterScope()==Doxygen::globalScope - ) - ) // skip external references, anonymous compounds and - // template instances and nested classes + + if (cd->getOuterScope()==0 || // <-- should not happen, but can if we read an old tag file + cd->getOuterScope()==Doxygen::globalScope // only look at global classes + ) { - msg("Generating docs for compound %s...\n",cd->name().data()); - - cd->writeDocumentation(*outputList); - cd->writeMemberList(*outputList); + // skip external references, anonymous compounds and + // template instances + if ( cd->isLinkableInProject() && cd->templateMaster()==0) + { + msg("Generating docs for compound %s...\n",cd->name().data()); + + cd->writeDocumentation(*outputList); + cd->writeMemberList(*outputList); + } + // even for undocumented classes, the inner classes can be documented. + cd->writeDocumentationForInnerClasses(*outputList); } - cd->writeDocumentationForInnerClasses(*outputList); } } @@ -5607,6 +5615,7 @@ static void generateNamespaceDocs() NamespaceSDict::Iterator nli(Doxygen::namespaceSDict); NamespaceDef *nd; + // for each namespace... for (;(nd=nli.current());++nli) { if (nd->isLinkableInProject()) @@ -5614,12 +5623,12 @@ static void generateNamespaceDocs() msg("Generating docs for namespace %s\n",nd->name().data()); nd->writeDocumentation(*outputList); } - ClassSDict::Iterator cli(Doxygen::classSDict); + // for each class in the namespace... + ClassSDict::Iterator cli(*nd->classSDict); for ( ; cli.current() ; ++cli ) { ClassDef *cd=cli.current(); - if ( cd->getOuterScope()==nd && - cd->isLinkableInProject() && + if ( cd->isLinkableInProject() && cd->templateMaster()==0 ) // skip external references, anonymous compounds and // template instances and nested classes @@ -6965,7 +6974,7 @@ void parseInput() msg("Building page list...\n"); buildPageList(root); - msg("Buidling package list...\n"); + msg("Building package list...\n"); buildPackageList(root); msg("Search for main page...\n"); diff --git a/src/doxytag.l b/src/doxytag.l index b8f1279..1afe949 100644 --- a/src/doxytag.l +++ b/src/doxytag.l @@ -391,6 +391,7 @@ QCString unhtmlify(const char *str) "&" { memberArgs+="&"; } "<" { memberArgs+="<"; } ">" { memberArgs+=">"; } +" " { memberArgs+=" "; } /* [{}] { // handle enums memberArgs.resize(0); diff --git a/src/latexgen.cpp b/src/latexgen.cpp index 1e42ee8..7b2b2bb 100644 --- a/src/latexgen.cpp +++ b/src/latexgen.cpp @@ -1265,6 +1265,7 @@ void LatexGenerator::docify(const char *str) static bool isKorean = theTranslator->idLanguage()=="korean"; static bool isRussian = theTranslator->idLanguage()=="russian"; static bool isUkrainian = theTranslator->idLanguage()=="ukrainian"; + static bool isChinese = theTranslator->idLanguage()=="chinese"; if (str) { const unsigned char *p=(const unsigned char *)str; @@ -1329,9 +1330,9 @@ void LatexGenerator::docify(const char *str) break; default: - - if (isJapanese || isKorean) - { // Japanese language uses wide characters + // Some languages uses wide characters + if (isJapanese || isKorean || isChinese) + { if (c>=128) { t << (char)c; diff --git a/src/scanner.l b/src/scanner.l index 43ed58f..5873d2e 100644 --- a/src/scanner.l +++ b/src/scanner.l @@ -3051,7 +3051,7 @@ CHARLIT (("'"\\[0-7]{1,3}"'")|("'"\\."'")|("'"[^'\\\n]{1,4}"'")) ); yyLineNr++; } -{SCOPENAME} { +{ID}("."{ID})* { current->name = yytext; newDocState(); } diff --git a/src/translator_cn.h b/src/translator_cn.h index b85aad2..30375d7 100644 --- a/src/translator_cn.h +++ b/src/translator_cn.h @@ -26,245 +26,489 @@ */ #define CN_SPC -class TranslatorChinese : public TranslatorAdapter_1_2_1 +class TranslatorChinese : public Translator { public: - QCString idLanguage() + /*! Used for identification of the language. The identification + * should not be translated. It should be replaced by the name + * of the language in English using lower-case characters only + * (e.g. "czech", "japanese", "russian", etc.). It sould be equal to + * the identification used in the language.cpp. + */ + virtual QCString idLanguage() { return "chinese"; } - QCString idLanguageCharset() + + /*! Used to get the LaTeX command(s) for the language support. + * This method should return string with commands that switch + * LaTeX to the desired language. For example + * 
"\\usepackage[german]{babel}\n"
+		 *
+ * or + * 
"\\usepackage{polski}\n"
+		 * "\\usepackage[latin2]{inputenc}\n"
+		 * "\\usepackage[T1]{fontenc}\n"
+		 *
+ * + * The English LaTeX does not use such commands. Because of this + * the empty string is returned in this implementation. + */ + virtual QCString latexLanguageSupportCommand() + { + QCString result(latexBabelPackage()); + if (!result.isEmpty()) + { + result = "\\usepackage{" + result; + result += "}\n"; + } + return result; + } + + virtual QCString latexBabelPackage() + { return "CJK"; } + + /*! return the language charset. This will be used for the HTML output */ + virtual QCString idLanguageCharset() { return "gb2312"; } - QCString latexBabelPackage() - { return "chinese"; } - QCString trRelatedFunctions() + + /*! used in the compound documentation before a list of related functions. + */ + virtual QCString trRelatedFunctions() { return "Ïà¹Øº¯Êý"; } - QCString trRelatedSubscript() - { return "£¨×¢Ò⣺ÕâЩ²»ÊdzÉÔ±º¯Êý£©"; } - QCString trDetailedDescription() - { return "ÏêϤÃèÊö"; } - QCString trMemberTypedefDocumentation() + + /*! subscript for the related functions. */ + virtual QCString trRelatedSubscript() + { return "£¨×¢Ò⣺ÕâЩ²»ÊdzÉÔ±º¯Êý¡££©"; } + + /*! header that is put before the detailed description of files, + * classes and namespaces. + */ + virtual QCString trDetailedDescription() + { return "ÏêϸÃèÊö"; } + + /*! header that is put before the list of typedefs. */ + virtual QCString trMemberTypedefDocumentation() { return "³ÉÔ±ÀàÐͶ¨ÒåÎĵµ"; } - QCString trMemberEnumerationDocumentation() + + /*! header that is put before the list of enumerations. */ + virtual QCString trMemberEnumerationDocumentation() { return "³ÉԱö¾ÙÀàÐÍÎĵµ"; } - QCString trEnumerationValueDocumentation() + + virtual QCString trEnumerationValueDocumentation() { return "³ÉԱö¾ÙÖµÎĵµ"; } - QCString trMemberFunctionDocumentation() + + /*! header that is put before the list of member function. */ + virtual QCString trMemberFunctionDocumentation() { return "³ÉÔ±º¯ÊýÎĵµ"; } - QCString trMemberDataDocumentation() - { return "³ÉÔ±Êý¾ÝÎĵµ"; } - QCString trMore() + + /*! header that is put before the list of member attributes. */ + virtual QCString trMemberDataDocumentation() + { + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) + { + return "×Ö¶ÎÎĵµ"; + } + else { + return "³ÉÔ±Êý¾ÝÎĵµ"; + } + } + + /*! this is the text of a link put after brief descriptions. */ + virtual QCString trMore() { return "¸ü¶à..."; } - QCString trListOfAllMembers() + + /*! put in the class documention */ + virtual QCString trListOfAllMembers() { return "ËùÓгÉÔ±µÄÁÐ±í¡£"; } - QCString trMemberList() + + /*! used as the title of the "list of all members" page of a class */ + virtual QCString trMemberList() { return "³ÉÔ±Áбí"; } - QCString trThisIsTheListOfAllMembers() + + /*! this is the first part of a sentence that is followed by a class name */ + virtual QCString trThisIsTheListOfAllMembers() { return "³ÉÔ±µÄÍêÕûÁÐ±í£¬ÕâЩ³ÉÔ±ÊôÓÚ"CN_SPC; } - QCString trIncludingInheritedMembers() + + /*! this is the remainder of the sentence after the class name */ + virtual QCString trIncludingInheritedMembers() { return "£¬°üÀ¨ËùÓм̳жøÀ´µÄ³ÉÔ±"; } - QCString trGeneratedAutomatically(const char *s) - { QCString result; + + /*! this is put at the author sections at the bottom of man pages. + * parameter s is name of the project name. + */ + virtual QCString trGeneratedAutomatically(const char *s) + { + QCString result; if (s) result=(QCString)"Ϊ"CN_SPC+s+"£¬"; result+="ÓÉ"CN_SPC"Doyxgen"CN_SPC"ͨ¹ý·ÖÎöÔ´´úÂë×Ô¶¯Éú³É¡£"; return result; } - QCString trEnumName() + + /*! put after an enum name in the list of all members */ + virtual QCString trEnumName() { return "ö¾ÙÃû³Æ"; } - QCString trEnumValue() + + /*! put after an enum value in the list of all members */ + virtual QCString trEnumValue() { return "ö¾ÙÖµ"; } - QCString trDefinedIn() + + /*! put after an undocumented member in the list of all members */ + virtual QCString trDefinedIn() { return "¶¨ÒåÓÚ"CN_SPC; } - QCString trVerbatimText(const char *f) + + // quick reference sections + + + virtual QCString trVerbatimText(const char *f) { return (QCString)"ÕâÊÇÍ·Îļþ"CN_SPC+f+CN_SPC"µÄÔ´´úÂë¡£"; } - QCString trModules() + + /*! This is put above each page as a link to the list of all groups of + * compounds or files (see the \\group command). + */ + virtual QCString trModules() { return "Ä£¿é"; } - QCString trClassHierarchy() + + /*! This is put above each page as a link to the class hierarchy */ + virtual QCString trClassHierarchy() { return "Àà¼Ì³Ð¹Øϵ"; } - QCString trCompoundList() - { return "×éºÏÀàÐÍÁбí"; } - QCString trFileList() + + /*! This is put above each page as a link to the list of annotated class */ + virtual QCString trCompoundList() + { + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) { + return "Êý¾Ý½á¹¹"; + } + else { + return "×éºÏÀàÐÍÁбí"; + } + } + + /*! This is put above each page as a link to the list of documented files */ + virtual QCString trFileList() { return "ÎļþÁбí"; } - QCString trHeaderFiles() + + + /*! This is put above each page as a link to the list of all verbatim headers */ + virtual QCString trHeaderFiles() { return "Í·Îļþ"; } - QCString trCompoundMembers() - { return "×éºÏÀàÐͳÉÔ±"; } - QCString trFileMembers() - { return "Îļþ³ÉÔ±"; } - QCString trRelatedPages() + + /*! This is put above each page as a link to all members of compounds. */ + virtual QCString trCompoundMembers() + { + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) { + return "Êý¾Ý×Ö¶Î"; + } + else { + return "×éºÏÀàÐͳÉÔ±"; + } + } + + /*! This is put above each page as a link to all member of files. */ + virtual QCString trFileMembers() + { + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) { + return "È«¾Ö¶¨Òå"; + } else { + return "Îļþ³ÉÔ±"; + } + } + + /*! This is put above each page as a link to all related pages. */ + virtual QCString trRelatedPages() { return "Ïà¹ØÒ³Ãæ"; } - QCString trExamples() + + /*! This is put above each page as a link to all examples. */ + virtual QCString trExamples() { return "ʾÀý"; } - QCString trSearch() + + virtual QCString trSearch() { return "ËÑË÷"; } - QCString trClassHierarchyDescription() + + virtual QCString trClassHierarchyDescription() { return "´ËÁбí»ù±¾°´×Öµä˳ÐòÅÅÐò£º"; } - QCString trFileListDescription(bool extractAll) + + virtual QCString trFileListDescription(bool extractAll) { - QCString result="ÕâÀïÁгöËùÓÐ"; + QCString result="ÕâÀïÁгöËùÓÐ"; if (!extractAll) result+="Îĵµ»¯µÄ"; result+="Îļþ£¬¸½´ø¼òҪ˵Ã÷£º"; return result; } - QCString trCompoundListDescription() - { return "ÕâÀïÁгöËùÓÐÀà¡¢½á¹¹¡¢ÁªºÏÒÔ¼°½Ó¿Ú¶¨Ò壬¸½´ø¼òҪ˵Ã÷£º"; + + virtual QCString trCompoundListDescription() + { + + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) + { + return "ÕâÀïÁгöËùÓÐÊý¾Ý½á¹¹£¬¸½´ø¼òҪ˵Ã÷£º"; + } + else + { + return "ÕâÀïÁгöËùÓÐÀà¡¢½á¹¹¡¢ÁªºÏÒÔ¼°½Ó¿Ú¶¨Ò壬¸½´ø¼òҪ˵Ã÷£º"; + } } - QCString trCompoundMembersDescription(bool extractAll) + + virtual QCString trCompoundMembersDescription(bool extractAll) { - QCString result="ÕâÀïÁгöËùÓÐ"; - if (!extractAll) result+="Îĵµ»¯µÄ"; - result+="Àà³ÉÔ±£¬¸½´ø"; - if (extractAll) result+="ËùÔÚÀàµÄÎĵµµÄÁ´½Ó£º"; - else result+="ËùÔÚÀàµÄÁ´½Ó£º"; + QCString result="ÕâÀïÁгöËùÓÐ"; + if (!extractAll) { + result+="Îĵµ»¯µÄ"; + } + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) { + result+="½á¹¹ºÍÁªºÏµÄ³ÉÔ±£¬¸½´ø"; + } + else { + result+="Àà³ÉÔ±£¬¸½´ø"; + } + + if (extractAll) { + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) { + result+="ËùÔڽṹ£¯ÁªºÏµÄÎĵµµÄÁ´½Ó£º"; + } + else { + result+="ËùÔÚÀàµÄÎĵµµÄÁ´½Ó£º"; + } + } + else { + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) { + result+="ËùÊô½á¹¹£¯ÁªºÏµÄÁ´½Ó£º"; + } + else { + result+="ËùÊôÀàµÄÁ´½Ó£º"; + } + } return result; } - QCString trFileMembersDescription(bool extractAll) + + virtual QCString trFileMembersDescription(bool extractAll) { - QCString result="ÕâÀïÁгöËùÓÐ"; - if (!extractAll) result+="Îĵµ»¯µÄ"; - result+="Îļþ³ÉÔ±£¬¸½´ø"; - if (extractAll) result+="ËùÔÚÎļþµÄÎĵµµÄÁ´½Ó£º"; - else result+="ËùÔÚÎļþµÄÁ´½Ó£º"; + QCString result="ÕâÀïÁгöËùÓÐ"; + if (!extractAll) + result +="Îĵµ»¯µÄ"; + + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) { + result +="º¯Êý£¬±äÁ¿£¬ºê£¬Ã¶¾ÙºÍÀàÐͶ¨Ò壬¸½´ø"; + } + else { + result +="Îļþ³ÉÔ±£¬¸½´ø"; + } + + if (extractAll) + result+="ËùÔÚÎļþµÄÎĵµµÄÁ´½Ó£º"; + else + result+="ËùÔÚÎļþµÄÁ´½Ó£º"; return result; } - QCString trHeaderFilesDescription() + + virtual QCString trHeaderFilesDescription() { return "ÕâÀïÁгö×é³ÉAPIµÄÍ·Îļþ£º"; } - QCString trExamplesDescription() + + virtual QCString trExamplesDescription() { return "ÕâÀïÁгöËùÓÐʾÀý£º"; } - QCString trRelatedPagesDescription() + + virtual QCString trRelatedPagesDescription() { return "ÕâÀïÁгöËùÓÐÏà¹ØµÄÒ³Ã棺"; } - QCString trModulesDescription() + + virtual QCString trModulesDescription() { return "ÕâÀïÁгöËùÓÐÄ£¿é"; } - QCString trNoDescriptionAvailable() + + virtual QCString trNoDescriptionAvailable() { return "ÎÞ¿ÉÓÃÎĵµ"; } - QCString trDocumentation() + virtual QCString trDocumentation() { return "Îĵµ"; } - QCString trModuleIndex() + + virtual QCString trModuleIndex() { return "Ä£¿éË÷Òý"; } - QCString trHierarchicalIndex() + + virtual QCString trHierarchicalIndex() { return "¼Ì³Ð¹ØϵË÷Òý"; } - QCString trCompoundIndex() - { return "×éºÏÀàÐÍË÷Òý"; } - QCString trFileIndex() + + virtual QCString trCompoundIndex() + { + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) + { + return "Êý¾Ý½á¹¹Ë÷Òý"; + } + else { + return "×éºÏÀàÐÍË÷Òý"; + } + } + + virtual QCString trFileIndex() { return "ÎļþË÷Òý"; } - QCString trModuleDocumentation() + + virtual QCString trModuleDocumentation() { return "Ä£¿éÎĵµ"; } - QCString trClassDocumentation() - { return "ÀàÎĵµ"; } - QCString trFileDocumentation() + + virtual QCString trClassDocumentation() + { + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) + { + return "Êý¾Ý½á¹¹Îĵµ"; + } + else { + return "ÀàÎĵµ"; + } + } + + virtual QCString trFileDocumentation() { return "ÎļþÎĵµ"; } - QCString trExampleDocumentation() + + virtual QCString trExampleDocumentation() { return "ʾÀýÎĵµ"; } - QCString trPageDocumentation() + + virtual QCString trPageDocumentation() { return "Ò³ÃæÎĵµ"; } - QCString trReferenceManual() + + virtual QCString trReferenceManual() { return "²Î¿¼ÊÖ²á"; } - QCString trDefines() + virtual QCString trDefines() { return "ºê¶¨Òå"; } - QCString trFuncProtos() + + virtual QCString trFuncProtos() { return "º¯ÊýÔ­ÐÍ"; } - QCString trTypedefs() + + virtual QCString trTypedefs() { return "ÀàÐͶ¨Òå"; } - QCString trEnumerations() + + virtual QCString trEnumerations() { return "ö¾Ù"; } - QCString trFunctions() + + virtual QCString trFunctions() { return "º¯Êý"; } - QCString trVariables() + + virtual QCString trVariables() { return "±äÁ¿"; } - QCString trEnumerationValues() + + virtual QCString trEnumerationValues() { return "ö¾ÙÖµ"; } - QCString trAuthor() + + virtual QCString trAuthor() { return "×÷Õß"; } - QCString trDefineDocumentation() + + virtual QCString trDefineDocumentation() { return "ºê¶¨ÒåÎĵµ"; } - QCString trFunctionPrototypeDocumentation() + + virtual QCString trFunctionPrototypeDocumentation() { return "º¯ÊýÔ­ÐÍÎĵµ"; } - QCString trTypedefDocumentation() + + virtual QCString trTypedefDocumentation() { return "ÀàÐͶ¨ÒåÎĵµ"; } - QCString trEnumerationTypeDocumentation() + + virtual QCString trEnumerationTypeDocumentation() { return "ö¾ÙÀàÐÍÎĵµ"; } - QCString trFunctionDocumentation() + + virtual QCString trFunctionDocumentation() { return "º¯ÊýÎĵµ"; } - QCString trVariableDocumentation() + + virtual QCString trVariableDocumentation() { return "±äÁ¿Îĵµ"; } - QCString trCompounds() - { return "×éºÏÀàÐÍ"; } - QCString trFiles() + + virtual QCString trCompounds() + { + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) + { + return "Êý¾Ý½á¹¹"; + } + else { + return "×éºÏÀàÐÍ"; + } + } + + virtual QCString trFiles() { return "Îļþ"; } - QCString trGeneratedAt(const char *date,const char *projName) + + virtual QCString trGeneratedAt(const char *date,const char *projName) { - QCString result=(QCString)"Generated at "+date; + QCString result=(QCString)"Generated at "+date; if (projName) result+=(QCString)" for "+projName; result+=(QCString)" by"; return result; } - QCString trWrittenBy() + + virtual QCString trWrittenBy() { return "written by"; } - QCString trClassDiagram(const char *clName) + + virtual QCString trClassDiagram(const char *clName) { return (QCString)"¼Ì³Ðͼ£¬Àà"CN_SPC+clName; } - QCString trForInternalUseOnly() + + virtual QCString trForInternalUseOnly() { return "½öÏÞÄÚ²¿Ê¹Óá£"; } - QCString trReimplementedForInternalReasons() + + virtual QCString trReimplementedForInternalReasons() { return "ÓÉÓÚÄÚ²¿Ô­Òò±»ÖØÔØ£»µ«²»Ó°ÏìAPI"; } - QCString trWarning() + + virtual QCString trWarning() { return "¾¯¸æ"; } - QCString trBugsAndLimitations() + + virtual QCString trBugsAndLimitations() { return "BUG"CN_SPC"Óë¾ÖÏÞ"; } - QCString trVersion() + + virtual QCString trVersion() { return "°æ±¾"; } - QCString trDate() + + virtual QCString trDate() { return "ÈÕÆÚ"; } - QCString trAuthors() + + virtual QCString trAuthors() { return "×÷Õß"; } - QCString trReturns() + + virtual QCString trReturns() { return "·µ»Ø"; } - QCString trSeeAlso() + + virtual QCString trSeeAlso() { return "²Î¼û"; } - QCString trParameters() + + virtual QCString trParameters() { return "²ÎÊý"; } - QCString trExceptions() + + virtual QCString trExceptions() { return "Òì³£"; } - QCString trGeneratedBy() + + virtual QCString trGeneratedBy() { return "ÖÆ×÷Õß"; } ////////////////////////////////////////////////////////////////////////// // new since 0.49-990307 ////////////////////////////////////////////////////////////////////////// - QCString trNamespaceList() - { return "ÃüÃû¿Õ¼äÁбí"; } - QCString trNamespaceListDescription(bool extractAll) + virtual QCString trNamespaceList() + { return "Ãû×Ö¿Õ¼äÁбí"; } + + virtual QCString trNamespaceListDescription(bool extractAll) { - QCString result="ÕâÀïÁгöËùÓÐ"; + QCString result="ÕâÀïÁгöËùÓÐ"; if (!extractAll) result+="Îĵµ»¯µÄ"; - result+="ÃüÃû¿Õ¼ä¶¨Ò壬¸½´ø¼òҪ˵Ã÷£º"; + result+="Ãû×ֿռ䶨Ò壬¸½´ø¼òҪ˵Ã÷£º"; return result; } - QCString trFriends() + + virtual QCString trFriends() { return "ÓÑÔª"; } ////////////////////////////////////////////////////////////////////////// // new since 0.49-990405 ////////////////////////////////////////////////////////////////////////// - QCString trRelatedFunctionDocumentation() + virtual QCString trRelatedFunctionDocumentation() { return "ÓÑÔª¼°Ïà¹Øº¯ÊýÎĵµ"; } ////////////////////////////////////////////////////////////////////////// // new since 0.49-990425 ////////////////////////////////////////////////////////////////////////// - QCString trCompoundReference(const char *clName, + virtual QCString trCompoundReference(const char *clName, ClassDef::CompoundType compType, bool isTemplate) // used as the title of the HTML page of a class/struct/union { - QCString result=(QCString)clName; + QCString result=(QCString)clName; if (isTemplate) result+=CN_SPC"Ä£°å"; switch(compType) { @@ -277,49 +521,61 @@ class TranslatorChinese : public TranslatorAdapter_1_2_1 result+="²Î¿¼"; return result; } - QCString trFileReference(const char *fileName) + + virtual QCString trFileReference(const char *fileName) // used as the title of the HTML page of a file { - QCString result=fileName; + QCString result=fileName; result+=CN_SPC"Îļþ²Î¿¼"; return result; } - QCString trNamespaceReference(const char *namespaceName) + + virtual QCString trNamespaceReference(const char *namespaceName) // used as the title of the HTML page of a namespace { - QCString result=namespaceName; - result+=CN_SPC"ÃüÃû¿Õ¼ä²Î¿¼"; + QCString result=namespaceName; + result+=CN_SPC"Ãû×Ö¿Õ¼ä²Î¿¼"; return result; } // these are for the member sections of a class, struct or union - QCString trPublicMembers() + virtual QCString trPublicMembers() { return "¹«ÓгÉÔ±"; } - QCString trPublicSlots() + + virtual QCString trPublicSlots() { return "¹«ÓвÛ"; } - QCString trSignals() + + virtual QCString trSignals() { return "ÐźÅ"; } - QCString trStaticPublicMembers() + + virtual QCString trStaticPublicMembers() { return "¾²Ì¬¹«ÓгÉÔ±"; } - QCString trProtectedMembers() + + virtual QCString trProtectedMembers() { return "±£»¤³ÉÔ±"; } - QCString trProtectedSlots() + + virtual QCString trProtectedSlots() { return "±£»¤²Û"; } - QCString trStaticProtectedMembers() + + virtual QCString trStaticProtectedMembers() { return "¾²Ì¬±£»¤³ÉÔ±"; } - QCString trPrivateMembers() + + virtual QCString trPrivateMembers() { return "˽ÓгÉÔ±"; } - QCString trPrivateSlots() + + virtual QCString trPrivateSlots() { return "˽ÓвÛ"; } - QCString trStaticPrivateMembers() + + virtual QCString trStaticPrivateMembers() { return "¾²Ì¬Ë½ÓгÉÔ±"; } + // end of member sections - QCString trWriteList(int numEntries) + virtual QCString trWriteList(int numEntries) { // this function is used to produce a comma-separated list of items. // use generateMarker(i) to indicate where item i should be put. - QCString result; + QCString result; int i; // the inherits list contain `numEntries' classes for (i=0;i