qvaluevector.3qt

Linux下的基于X11的图形开发环境。

'\" t
.TH QValueVector 3qt "9 December 2002" "Trolltech AS" \" -*- nroff -*-
.\" Copyright 1992-2001 Trolltech AS.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QValueVector \- Value-based template class that provides a dynamic array
.SH SYNOPSIS
All the functions in this class are reentrant when Qt is built with thread support.</p>
.PP
\fC#include <qvaluevector.h>\fR
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "typedef T \fBvalue_type\fR"
.br
.ti -1c
.BI "typedef value_type * \fBpointer\fR"
.br
.ti -1c
.BI "typedef const value_type * \fBconst_pointer\fR"
.br
.ti -1c
.BI "typedef value_type * \fBiterator\fR"
.br
.ti -1c
.BI "typedef const value_type * \fBconst_iterator\fR"
.br
.ti -1c
.BI "typedef value_type & \fBreference\fR"
.br
.ti -1c
.BI "typedef const value_type & \fBconst_reference\fR"
.br
.ti -1c
.BI "typedef size_t \fBsize_type\fR"
.br
.ti -1c
.BI "typedef ptrdiff_t \fBdifference_type\fR"
.br
.ti -1c
.BI "\fBQValueVector\fR ()"
.br
.ti -1c
.BI "\fBQValueVector\fR ( const QValueVector<T> & v )"
.br
.ti -1c
.BI "\fBQValueVector\fR ( size_type n, const T & val = T ( ) )"
.br
.ti -1c
.BI "\fBQValueVector\fR ( std::vector<T> & v )"
.br
.ti -1c
.BI "\fBQValueVector\fR ( const std::vector<T> & v )"
.br
.ti -1c
.BI "\fB~QValueVector\fR ()"
.br
.ti -1c
.BI "QValueVector<T> & \fBoperator=\fR ( const QValueVector<T> & v )"
.br
.ti -1c
.BI "QValueVector<T> & \fBoperator=\fR ( const std::vector<T> & v )"
.br
.ti -1c
.BI "size_type \fBsize\fR () const"
.br
.ti -1c
.BI "bool \fBempty\fR () const"
.br
.ti -1c
.BI "size_type \fBcapacity\fR () const"
.br
.ti -1c
.BI "iterator \fBbegin\fR ()"
.br
.ti -1c
.BI "const_iterator \fBbegin\fR () const"
.br
.ti -1c
.BI "iterator \fBend\fR ()"
.br
.ti -1c
.BI "const_iterator \fBend\fR () const"
.br
.ti -1c
.BI "reference \fBat\fR ( size_type i, bool * ok = 0 )"
.br
.ti -1c
.BI "const_reference \fBat\fR ( size_type i, bool * ok = 0 ) const"
.br
.ti -1c
.BI "reference \fBoperator[]\fR ( size_type i )"
.br
.ti -1c
.BI "const_reference \fBoperator[]\fR ( size_type i ) const"
.br
.ti -1c
.BI "reference \fBfront\fR ()"
.br
.ti -1c
.BI "const_reference \fBfront\fR () const"
.br
.ti -1c
.BI "reference \fBback\fR ()"
.br
.ti -1c
.BI "const_reference \fBback\fR () const"
.br
.ti -1c
.BI "void \fBpush_back\fR ( const T & x )"
.br
.ti -1c
.BI "void \fBpop_back\fR ()"
.br
.ti -1c
.BI "iterator \fBinsert\fR ( iterator pos, const T & x )"
.br
.ti -1c
.BI "iterator \fBinsert\fR ( iterator pos, size_type n, const T & x )"
.br
.ti -1c
.BI "void \fBreserve\fR ( size_type n )"
.br
.ti -1c
.BI "void \fBresize\fR ( size_type n, const T & val = T ( ) )"
.br
.ti -1c
.BI "void \fBclear\fR ()"
.br
.ti -1c
.BI "iterator \fBerase\fR ( iterator pos )"
.br
.ti -1c
.BI "iterator \fBerase\fR ( iterator first, iterator last )"
.br
.ti -1c
.BI "bool \fBoperator==\fR ( const QValueVector<T> & x )"
.br
.ti -1c
.BI "bool \fBoperator==\fR ( const QValueVector<T> & x ) const"
.br
.ti -1c
.BI "typedef T \fBValueType\fR"
.br
.ti -1c
.BI "typedef ValueType * \fBIterator\fR"
.br
.ti -1c
.BI "typedef const ValueType * \fBConstIterator\fR"
.br
.ti -1c
.BI "size_type \fBcount\fR () const"
.br
.ti -1c
.BI "bool \fBisEmpty\fR () const"
.br
.ti -1c
.BI "reference \fBfirst\fR ()"
.br
.ti -1c
.BI "const_reference \fBfirst\fR () const"
.br
.ti -1c
.BI "reference \fBlast\fR ()"
.br
.ti -1c
.BI "const_reference \fBlast\fR () const"
.br
.ti -1c
.BI "void \fBappend\fR ( const T & x )"
.br
.in -1c
.SH DESCRIPTION
The QValueVector class is a value-based template class that provides a dynamic array.
.PP
QValueVector is a Qt implementation of an STL-like vector container. It can be used in your application if the standard \fCvector\fR is not available for your target platforms. QValueVector is part of the Qt Template Library.
.PP
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.
.PP
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.
.PP
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.
.PP
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:
.TP
a copy constructor;
.TP
an assignment operator;
.TP
a default constructor, i.e., a constructor that does not take any arguments.
.PP
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.
.PP
QValueVector uses an STL-like syntax to manipulate and address the objects it contains. See this document for more information.
.PP
Example:
.PP
.nf
.br
    #include <qvaluevector.h>
.br
    #include <qstring.h>
.br
    #include <stdio.h>
.br
.br
    class Employee
.br
    {
.br
    public:
.br
        Employee(): s(0) {}
.br
        Employee( const QString& name, int salary )
.br
            : n( name ), s( salary )
.br
        { }
.br
.br
        QString name() const { return n; }
.br
        int salary() const { return s; }
.br
        void setSalary( int salary ) { s = salary; }
.br
.br
        QString name()   const          { return n; }
.br
        int     salary() const          { return s; }
.br
        void    setSalary( int salary ) { s = salary; }
.br
    private:
.br
        QString n;
.br
        int     s;
.br
    };
.br
.br
    int main()
.br
    {
.br
        typedef QValueVector<Employee> EmployeeVector;
.br
        EmployeeVector vec( 3 );  // vector of 3 Employees
.br
.br
        vec[0] = Employee( "Bill", 50000 );
.br
        vec[1] = Employee( "Steve", 80000 );
.br
        vec[2] = Employee( "Ron", 60000 );
.br
.br
        Employee joe( "Joe", 50000 );
.br
        vec.push_back( joe );  // vector expands to accommodate 4 Employees
.br
        joe.setSalary( 70000 );
.br
.br
.br
        EmployeeVector::iterator it;
.br
        for( it = vec.begin(); it != vec.end(); ++it )
.br
            printf( "%s earns %d\\n", (*it).name().latin1(), (*it).salary() );
.br
.br
        return 0;
.br
    }
.br
.fi
.PP
Program output:
.PP
.nf
.br
        Bill earns 50000
.br
        Steve earns 80000
.br
        Ron earns 60000
.br
        Joe earns 50000
.br
.fi
.PP
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.
.PP
Many Qt functions return const value vectors; to iterate over these you should make a copy and iterate over the copy.
.PP
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 \fInot\fR 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().
.PP
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:
.PP
.nf
.br
    QValueVector<int> vec1;  // an empty vector
.br
    vec1[10] = 4;  // WARNING: undefined, probably a crash
.br
.br
    QValueVector<QString> vec2(25); // initialize with 25 elements