Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731

1 files changed, 724 insertions, 0 deletions

diff --git a/doc/qvaluevector.doc b/doc/qvaluevector.doc
new file mode 100644
index 000000000..1b7360e35
--- /dev/null
+++ b/doc/qvaluevector.doc
@@ -0,0 +1,724 @@
+/****************************************************************************
+**
+** QValueVector class documentation
+**
+** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
+**
+** This file is part of the Qt GUI Toolkit.
+**
+** This file may be used under the terms of the GNU General
+** Public License versions 2.0 or 3.0 as published by the Free
+** Software Foundation and appearing in the files LICENSE.GPL2
+** and LICENSE.GPL3 included in the packaging of this file.
+** Alternatively you may (at your option) use any later version
+** of the GNU General Public License if such license has been
+** publicly approved by Trolltech ASA (or its successors, if any)
+** and the KDE Free Qt Foundation.
+**
+** Please review the following information to ensure GNU General
+** Public Licensing retquirements will be met:
+** http://trolltech.com/products/qt/licenses/licensing/opensource/.
+** If you are unsure which license is appropriate for your use, please
+** review the following information:
+** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
+** or contact the sales department at sales@trolltech.com.
+**
+** This file may be used under the terms of the Q Public License as
+** defined by Trolltech ASA and appearing in the file LICENSE.QPL
+** included in the packaging of this file.  Licensees holding valid Qt
+** Commercial licenses may use this file in accordance with the Qt
+** Commercial License Agreement provided with the Software.
+**
+** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
+** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
+** herein.
+**
+**********************************************************************/
+
+
+/*****************************************************************************
+  QValueVector documentation
+ *****************************************************************************/
+
+/*!
+    \class QValueVector qvaluevector.h
+    \brief The QValueVector class is a value-based template class that provides a dynamic array.
+
+    \ingroup qtl
+    \ingroup tools
+    \ingroup shared
+    \mainclass
+    \reentrant
+
+    QValueVector is a Qt implementation of an STL-like vector
+    container. It can be used in your application if the standard \c
+    vector is not available for your target platforms. QValueVector is
+    part of the \link qtl.html Qt Template Library\endlink.
+
+    QValueVector\<T\> defines a template instance to create a vector
+    of values that all have the class T. QValueVector does not store
+    pointers to the members of the vector; it holds a copy of every
+    member. QValueVector is said to be value based; in contrast,
+    QPtrList and QDict are pointer based.
+
+    QValueVector contains and manages a collection of objects of type
+    T and provides random access iterators that allow the contained
+    objects to be addressed. QValueVector owns the contained
+    elements. For more relaxed ownership semantics, see QPtrCollection
+    and friends, which are pointer-based containers.
+
+    QValueVector provides good performance if you append or remove
+    elements from the end of the vector. If you insert or remove
+    elements from anywhere but the end, performance is very bad. The
+    reason for this is that elements must to be copied into new
+    positions.
+
+    Some classes cannot be used within a QValueVector: for example,
+    all classes derived from QObject and thus all classes that
+    implement widgets. Only values can be used in a QValueVector. To
+    qualify as a value the class must provide:
+    \list
+    \i a copy constructor;
+    \i an assignment operator;
+    \i a default constructor, i.e., a constructor that does not take any arguments.
+    \endlist
+
+    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.
+
+    QValueVector uses an STL-like syntax to manipulate and address the
+    objects it contains. See \link qtl.html this document\endlink for
+    more information.
+
+    Example:
+    \code
+    #include <qvaluevector.h>
+    #include <qstring.h>
+    #include <stdio.h>
+
+    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;
+    };
+
+    int main()
+    {
+	typedef QValueVector<Employee> EmployeeVector;
+	EmployeeVector vec( 3 );  // vector of 3 Employees
+
+	vec[0] = Employee( "Bill", 50000 );
+	vec[1] = Employee( "Steve", 80000 );
+	vec[2] = Employee( "Ron", 60000 );
+
+	Employee joe( "Joe", 50000 );
+	vec.push_back( joe );  // vector expands to accommodate 4 Employees
+	joe.setSalary( 70000 );
+	
+	EmployeeVector::iterator it;
+	for( it = vec.begin(); it != vec.end(); ++it )
+	    printf( "%s earns %d\n", (*it).name().latin1(), (*it).salary() );
+
+	return 0;
+    }
+    \endcode
+
+    Program output:
+    \code
+	Bill earns 50000
+	Steve earns 80000
+	Ron earns 60000
+	Joe earns 50000
+    \endcode
+
+    As you can see, the most recent change to Joe's salary did not
+    affect the value in the vector because the vector created a copy
+    of Joe's entry.
+
+    Many Qt functions return const value vectors; to iterate over
+    these you should make a copy and iterate over the copy.
+
+    There are several ways to find items in the vector. The begin()
+    and end() functions return iterators to the beginning and end of
+    the vector. The advantage of getting an iterator is that you can
+    move forward or backward from this position by
+    incrementing/decrementing the iterator. The iterator returned by
+    end() points to the element which is one past the last element in
+    the container. The past-the-end iterator is still associated with
+    the vector it belongs to, however it is \e not dereferenceable;
+    operator*() will not return a well-defined value. If the vector is
+    empty(), the iterator returned by begin() will equal the iterator
+    returned by end().
+
+    The fastest way to access an element of a vector is by using
+    operator[]. This function provides random access and will return
+    a reference to the element located at the specified index. Thus,
+    you can access every element directly, in constant time, providing
+    you know the location of the element. It is undefined to access
+    an element that does not exist (your application will probably
+    crash). For example:
+
+    \code
+    QValueVector<int> vec1;  // an empty vector
+    vec1[10] = 4;  // WARNING: undefined, probably a crash
+
+    QValueVector<QString> vec2(25); // initialize with 25 elements
+    vec2[10] = "Dave";  // OK
+    \endcode
+
+    Whenever inserting, removing or referencing elements in a vector,
+    always make sure you are referring to valid positions. For
+    example:
+
+    \code
+    void func( QValueVector<int>& vec )
+    {
+	if ( vec.size() > 10 ) {
+	    vec[9] = 99; // OK
+	}
+    };
+    \endcode
+
+    The iterators provided by vector are random access iterators,
+    therefore you can use them with many generic algorithms, for
+    example, algorithms provided by the STL or the \link qtl.html
+    QTL\endlink. 
+
+    Another way to find an element in the vector is by using the
+    std::find() or \link qtl.html#qFind qFind()\endlink algorithms.
+    For example:
+
+    \code
+    QValueVector<int> vec;
+    ...
+    QValueVector<int>::const_iterator it = qFind( vec.begin(), vec.end(), 3 );
+    if ( it != vector.end() )
+	// 'it' points to the found element
+    \endcode
+
+    It is safe to have multiple iterators on the vector at the same
+    time. Since QValueVector manages memory dynamically, all iterators
+    can become invalid if a memory reallocation occurs. For example,
+    if some member of the vector is removed, iterators that point to
+    the removed element and to all following elements become
+    invalidated. Inserting into the middle of the vector will
+    invalidate all iterators. For convenience, the function back()
+    returns a reference to the last element in the vector, and front()
+    returns a reference to the first element. If the vector is
+    empty(), both back() and front() have undefined behavior (your
+    application will crash or do unpredictable things). Use back() and
+    front() with caution, for example:
+
+    \code
+    QValueVector<int> vec( 3 );
+    vec.push_back( 1 );
+    vec.push_back( 2 );
+    vec.push_back( 3 );
+    ...
+    if ( !vec.empty() ) {
+	// OK: modify the first element
+	int& i = vec.front();
+	i = 18;
+    }
+    ...
+    QValueVector<double> dvec;
+    double d = dvec.back(); // undefined behavior
+    \endcode
+
+    Because QValueVector manages memory dynamically, it is recommended
+    that you contruct a vector with an initial size. Inserting and
+    removing elements happens fastest when:
+    \list
+    \i Inserting or removing elements happens at the end() of the
+    vector;
+    \i The vector does not need to allocate additional memory.
+    \endlist
+
+    By creating a QValueVector with a sufficiently large initial size,
+    there will be less memory allocations. Do not use an initial size
+    that is too big, since it will still take time to construct all
+    the empty entries, and the extra space will be wasted if it is
+    never used.
+
+    Because QValueVector is value-based there is no need to be careful
+    about deleting elements in the vector. The vector holds its own
+    copies and will free them if the corresponding member or the
+    vector itself is deleted. You can force the vector to free all of
+    its items with clear().
+
+    QValueVector is shared implicitly, which means it can be copied in
+    constant time. If multiple QValueVector instances share the same
+    data and one needs to modify its contents, this modifying instance
+    makes a copy and modifies its private copy; it thus does not
+    affect the other instances. This is often called "copy on write".
+    If a QValueVector is being used in a multi-threaded program, you
+    must protect all access to the vector. See QMutex.
+
+    There are several ways to insert elements into the vector. The
+    push_back() function insert elements into the end of the vector,
+    and is usually fastest. The insert() function can be used to add
+    elements at specific positions within the vector.
+
+    Items can be also be removed from the vector in several ways.
+    There are several variants of the erase() function which removes a
+    specific element, or range of elements, from the vector.
+
+    Vectors can be also sorted with various STL algorithms , or it can
+    be sorted using the \link qtl.html Qt Template Library\endlink.
+    For example with qHeapSort():
+
+    Example:
+    \code
+    QValueVector<int> v( 4 );
+    v.push_back( 5 );
+    v.push_back( 8 );
+    v.push_back( 3 );
+    v.push_back( 4 );
+    qHeapSort( v );
+    \endcode
+
+    QValueVector stores its elements in contiguous memory. This means
+    that you can use a QValueVector in any situation that retquires an
+    array. 
+*/
+
+/*! \enum QValueVector::value_type
+	The type of the object stored in the vector. */
+/*! \enum QValueVector::ValueType
+	The type of the object stored in the vector. */
+/*! \enum QValueVector::pointer
+	The pointer to T type. */
+/*! \enum QValueVector::const_pointer
+	The const pointer to T type. */
+/*! \enum QValueVector::iterator
+	The vector's iterator type. */
+/*! \enum QValueVector::const_iterator
+	The vector's const iterator type. */
+/*! \enum QValueVector::Iterator
+	The vector's iterator type. */
+/*! \enum QValueVector::ConstIterator
+	The vector's const iterator type. */
+/*! \enum QValueVector::reference
+	The reference to T type. */
+/*! \enum QValueVector::const_reference
+	The const reference to T type. */
+/*! \enum QValueVector::size_type
+	An unsigned integral type, used to represent various sizes. */
+/*! \enum QValueVector::difference_type
+	A signed integral type used to represent the distance between two iterators. */
+
+
+/*!
+    \fn QValueVector::QValueVector()
+
+    Constructs an empty vector without any elements. To create a
+    vector which reserves an initial amount of space for elements, use
+    \c QValueVector(size_type n). 
+*/
+
+/*!
+    \fn QValueVector::QValueVector( const QValueVector<T>& v )
+
+    Constructs a copy of \a v.
+
+    This operation costs O(1) time because QValueVector is implicitly
+    shared.
+
+    The first modification to the vector does takes O(n) time, because
+    the elements must be copied.
+*/
+
+/*!
+    \fn QValueVector::QValueVector( std::vector<T>& v )
+
+    Constructs a copy of \a v.
+*/
+
+/*!
+    \fn QValueVector::QValueVector( const std::vector<T>& v )
+
+    This operation costs O(n) time because \a v is copied.
+*/
+
+/*!
+    \fn QValueVector::QValueVector( size_type n, const T& val )
+
+    Constructs a vector with an initial size of \a n elements. Each
+    element is initialized with the value of \a val.
+*/
+
+/*!
+    \fn QValueVector::~QValueVector()
+
+    Destroys the vector, destroying all elements and freeing the
+    allocated memory. References to the values in the vector and all
+    iterators of this vector become invalidated. Note that it is
+    impossible for an iterator to check whether or not it is valid:
+    QValueVector is tuned for performance, not for error checking.
+*/
+
+/*!
+    \fn QValueVector<T>& QValueVector::operator=( const QValueVector<T>& v )
+
+    Assigns \a v to this vector and returns a reference to this vector.
+
+    All iterators of the current vector become invalidated by this
+    operation. The cost of such an assignment is O(1) since
+    QValueVector is implicitly shared.
+*/
+
+/*!
+    \fn QValueVector<T>& QValueVector::operator=( const std::vector<T>& v )
+
+    \overload
+
+    Assigns \a v to this vector and returns a reference to this vector.
+
+    All iterators of the current vector become invalidated by this
+    operation. The cost of this assignment is O(n) since \a v is
+    copied.
+*/
+
+/*!
+    \fn size_type QValueVector::size() const
+
+    Returns the number of elements in the vector.
+
+    This function is provided for STL compatibility. It is equivalent
+    to count().
+
+  \sa empty()
+*/
+
+/*!
+    \fn size_type QValueVector::count() const
+
+    Returns the number of items in the vector.
+
+    \sa isEmpty()
+*/
+
+/*!
+    \fn bool QValueVector::empty() const
+
+    Returns TRUE if the vector is empty; otherwise returns FALSE.
+    Equivalent to size()==0, only faster.
+
+    This function is provided for STL compatibility. It is equivalent
+    to isEmpty().
+
+    \sa size()
+*/
+
+/*!
+    \fn bool QValueVector::isEmpty() const
+
+    Returns TRUE if the vector is empty; returns FALSE otherwise.
+
+    \sa count()
+*/
+
+/*!
+    \fn size_type QValueVector::capacity() const
+
+    Returns the maximum number of elements that can be stored in the
+    vector without forcing memory reallocation. If memory reallocation
+    takes place, some or all iterators may become invalidated.
+*/
+
+/*!
+    \fn iterator QValueVector::begin()
+
+    Returns an iterator pointing to the beginning of the vector. If
+    the vector is empty(), the returned iterator will equal end().
+*/
+
+/*!
+    \fn const_iterator QValueVector::begin() const
+
+    \overload
+
+    Returns a const iterator pointing to the beginning of the vector.
+    If the vector is empty(), the returned iterator will equal end().
+*/
+
+/*!
+    \fn const_iterator QValueVector::constBegin() const
+
+    Returns a const iterator pointing to the beginning of the vector.
+    If the vector is empty(), the returned iterator will equal end().
+
+    \sa constEnd();
+*/
+
+/*!
+    \fn iterator QValueVector::end()
+
+    Returns an iterator pointing behind the last element of the
+    vector.
+*/
+
+/*!
+    \fn const_iterator QValueVector::end() const
+
+    \overload
+
+    Returns a const iterator pointing behind the last element of the
+    vector.
+*/
+
+/*!
+    \fn const_iterator QValueVector::constEnd() const
+
+    Returns a const iterator pointing behind the last element of the
+    vector.
+
+    \sa constBegin()
+*/
+
+/*!
+    \fn reference QValueVector::at( size_type i , bool* ok )
+
+    Returns a reference to the element with index \a i. If \a ok is
+    non-null, and the index \a i is out of range, *\a ok is set to
+    FALSE and the returned reference is undefined. If the index \a i
+    is within the range of the vector, and \a ok is non-null, *\a ok
+    is set to TRUE and the returned reference is well defined.
+*/
+
+/*!
+    \fn const_reference QValueVector::at( size_type i , bool* ok ) const
+
+    \overload
+
+    Returns a const reference to the element with index \a i. If \a ok
+    is non-null, and the index \a i is out of range, *\a ok is set to
+    FALSE and the returned reference is undefined. If the index \a i
+    is within the range of the vector, and \a ok is non-null, *\a ok
+    is set to TRUE and the returned reference is well defined.
+*/
+
+/*!
+    \fn reference QValueVector::operator[]( size_type i )
+
+    Returns a reference to the element at index \a i. If \a i is out
+    of range, this function has undefined behavior.
+
+    \sa at()
+*/
+
+/*!
+    \fn const_reference QValueVector::operator[]( size_type i ) const
+
+    \overload
+
+    Returns a const reference to the element at index \a i. If \a i is
+    out of range, this function has undefined behavior.
+
+    \sa at()
+*/
+
+/*!
+    \fn reference QValueVector::front()
+
+    Returns a reference to the first element in the vector. If there
+    is no first element, this function has undefined behavior. 
+
+    \sa empty() back()
+*/
+
+/*!
+    \fn const_reference QValueVector::front() const
+
+    \overload
+
+    Returns a const reference to the first element in the vector. If
+    there is no first element, this function has undefined behavior. 
+
+    \sa empty() back()
+*/
+
+/*!
+    \fn reference QValueVector::first()
+
+    Returns a reference to the first item in the vector. If there is
+    no first item, this function has undefined behavior.
+
+    \sa empty() last()
+*/
+
+/*!
+    \fn const_reference QValueVector::first() const
+
+    \overload
+*/
+
+/*!
+    \fn reference QValueVector::back()
+
+    Returns a reference to the last element in the vector. If there is
+    no last element, this function has undefined behavior. 
+
+    \sa empty() front()
+*/
+
+/*!
+    \fn const_reference QValueVector::back() const
+
+    \overload
+
+    Returns a const reference to the last element in the vector. If
+    there is no last element, this function has undefined behavior. 
+
+    \sa empty() front()
+*/
+
+/*!
+    \fn reference QValueVector::last()
+
+    Returns a reference to the last item in the vector. If there is no
+    last item, this function has undefined behavior.
+
+    \sa empty() first()
+*/
+
+/*!
+    \fn const_reference QValueVector::last() const
+
+    \overload
+*/
+
+/*!
+    \fn void QValueVector::push_back( const T& x )
+
+    Appends a copy of \a x to the end of the vector. This is the
+    fastest way to add new elements.
+
+    This function is provided for STL compatibility. It is equivalent
+    to append().
+
+    \sa insert()
+*/
+
+/*!
+    \fn void QValueVector::append( const T& x )
+
+    Appends a copy of \a x to the end of the vector.
+
+    \sa push_back() insert()
+*/
+
+/*!
+    \fn void QValueVector::pop_back()
+
+    Removes the last item from the vector.
+
+    This function is provided for STL compatibility.
+*/
+
+/*!
+    \fn iterator QValueVector::insert( iterator pos, const T& x )
+
+    Inserts a copy of \a x at the position immediately before \a pos.
+
+    \sa push_back()
+*/
+
+/*! \fn void QValueVector::detachInternal()
+    
+    \internal
+*/
+
+/*!
+    \fn iterator QValueVector::insert( iterator pos, size_type n, const T& x )
+
+    \overload
+
+    Inserts \a n copies of \a x immediately before position x.
+
+    \sa push_back()
+*/
+
+/*!
+    \fn void QValueVector::reserve( size_type n )
+
+    Increases the vector's capacity. If \a n is less than or equal to
+    capacity(), nothing happens. Otherwise, additional memory is
+    allocated so that capacity() will be increased to a value greater
+    than or equal to \a n. All iterators will then become invalidated.
+    Note that the vector's size() and the values of existing elements
+    remain unchanged.
+*/
+
+/*!
+    \fn void QValueVector::resize( size_type n, const T& val = T() )
+
+    Changes the size of the vector to \a n. If \a n is greater than
+    the current size(), elements are added to the end and initialized
+    with the value of \a val. If \a n is less than size(), elements
+    are removed from the end. If \a n is equal to size() nothing
+    happens.
+*/
+
+/*!
+    \fn void QValueVector::clear()
+
+    Removes all the elements from the vector.
+*/
+
+/*!
+    \fn iterator QValueVector::erase( iterator pos )
+
+    Removes the element at position \a pos and returns the position of
+    the next element.
+*/
+
+/*!
+    \fn iterator QValueVector::erase( iterator first, iterator last )
+
+    \overload
+
+    Removes all elements from \a first up to but not including \a last
+    and returns the position of the next element.
+*/
+
+/*!
+    \fn bool QValueVector::operator==( const QValueVector<T>& x ) const
+    
+    Returns TRUE if each element in this vector equals each
+    corresponding element in \a x; otherwise returns FALSE.
+*/
+
+/*!
+    \fn bool QValueVector::operator==( const QValueVector<T>& x ) 
+
+    \overload
+
+    Returns TRUE if each element in this vector equals each
+    corresponding element in \a x; otherwise returns FALSE.
+*/
+
+
+/*!
+    \fn void QValueVector::detach()
+
+    \internal
+
+    If the vector does not share its data with another QValueVector
+    instance, nothing happens. Otherwise the function creates a new
+    copy of this data and detaches from the shared one. This function
+    is called whenever the vector is modified. The implicit sharing
+    mechanism is implemented this way.
+*/