qmap.3qt

tmark1.11:用于生成QT/EMBEDDED应用工程的Markfile文件

.TH QMap 3qt "6 July 1999" "Troll Tech AS" \" -*- nroff -*-
.\" Copyright 1992-1999 Troll Tech AS.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QMap \- Value based template class that provides a dictionary
.SH SYNOPSIS
.br
.PP
\fC#include <qmap.h>\fR
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "\fBQMap\fR ()"
.br
.ti -1c
.BI "\fBQMap\fR ( const QMap<Key,T> & m )"
.br
.ti -1c
.BI "\fB~QMap\fR ()"
.br
.ti -1c
.BI "QMap<Key, T>& \fBoperator=\fR ( const QMap<Key, T> & m )"
.br
.ti -1c
.BI "Iterator \fBbegin\fR ()"
.br
.ti -1c
.BI "Iterator \fBend\fR ()"
.br
.ti -1c
.BI "ConstIterator \fBbegin\fR () const"
.br
.ti -1c
.BI "ConstIterator \fBend\fR () const"
.br
.ti -1c
.BI "Iterator \fBfind\fR ( const Key & k )"
.br
.ti -1c
.BI "ConstIterator \fBfind\fR ( const Key & k ) const"
.br
.ti -1c
.BI "T& \fBoperator[]\fR ( const Key & k )"
.br
.ti -1c
.BI "const T& \fBoperator[]\fR ( const Key & k ) const"
.br
.ti -1c
.BI "bool \fBcontains\fR ( const Key & k ) const"
.br
.ti -1c
.BI "uint \fBcount\fR () const"
.br
.ti -1c
.BI "bool \fBisEmpty\fR () const"
.br
.ti -1c
.BI "Iterator \fBinsert\fR ( const Key & " "key" ", const T & value )"
.br
.ti -1c
.BI "void \fBremove\fR ( Iterator it )"
.br
.ti -1c
.BI "void \fBremove\fR ( const Key & k )"
.br
.ti -1c
.BI "Iterator \fBreplace\fR ( const Key & " "k" ", const T & v )"
.br
.ti -1c
.BI "void \fBclear\fR ()"
.br
.in -1c
.SS "Protected Members"
.in +1c
.ti -1c
.BI "void \fBdetach\fR ()"
.br
.in -1c
.SH RELATED FUNCTION DOCUMENTATION
(Note that these are not member functions.)
.in +1c
.ti -1c
.BI "QDataStream& \fBoperator>>\fR (QDataStream & " "s" ", QMap<Key,T> & " "m" ")"
.br
.ti -1c
.BI "QDataStream& \fBoperator<<\fR (QDataStream & " "s" ", const QMap<Key,T> & " "m" ")"
.br
.in -1c
.SH DESCRIPTION
The QMap class is a value based template class that provides a dictionary
.PP
Define a template instance QMap<Key,Data> to create a dictionary with keys of type X and values of type Y. Please notice that QMap does not store pointers to the members of the map. 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".
.PP
Some classes can not be used within a QMap. For example everything derived from QObject and as a reason of this that extends to all classes which implement widgets. You can only put stuff in a QMap which can be easily copied. That means that the class X and Y must implement a copy constructor.
.PP
Example:
.PP
.nf
.br
    #include <qmap.h>
.br
    #include <qstring.h>
.br
    #include <stdio.h>
.br
.br
    class Employee
.br
    {
.br
    public:
.br
        Employee( const QString& name, int salary ) { n=name; s=salary; }
.br
        Employee( const Employee& _e ) { n = _e.name; s = _e.s; }
.br
.br
        QString     name()   const               { return n; }
.br
        int         salary() const               { return s; }
.br
        void        setSalary( int _s ) const    { s = _s; }
.br
    private:
.br
        QString     n;
.br
        int         s;
.br
    };
.br
.br
    void main()
.br
    {
.br
        typedef QMap<QString,Employee> EmployeeMap;
.br
        EmployeeMap map;                // map of Employee
.br
.br
        map.insert( "Gates", Employee("Bill", 50000) );
.br
        map.insert( "Ballmer", ( Employee("Steve",80000) );
.br
        map.insert( "Sommer," ( Employee("Ron",  60000) );
.br
.br
        Employee joe( "Joe", 50000 );
.br
        map.insert( "Doe", joe );
.br
        joe.setSalary( 4000 );
.br
.br
        EmployeeMap::Iterator it;
.br
        for( it = map.begin(); it != map.end(); ++it )
.br
            printf( "%s, %s earns %d\\n", it.key(), it.data().name(), it.data().salary() );
.br
    }
.fi
.PP
Program output:
.PP
.nf
.br
        Ballmer, Steve earns 80000
.br
        Doe, Joe earns 50000
.br
        Gates, Bill earns 50000
.br
        Sommer, Ron earns 60000
.fi
.PP
As you can see, the latest changes to Joes salary did not affect the value in the list because the map created a copy of Joes entry. In addition you should notice that the items are alphabetically sorted when iterating over the map.
.PP
There are two ways to find values in the list. The first one is to use the find() function. It returns an iterator pointing to the desired item or the end() iterator it no such element exists.
.PP
The scond approach uses the operator[]. But be warned: If you dont know that the element you are searching for is really in the list, then you should not use operator[]. The following example illustrated that.
.PP
.nf
.br
        QMap<QString,QString> map;
.br
        map.insert( "Weis", "Torben" );
.br
        str << map["Weis"] << map["Ettrich"] << endl;
.br
.br
        const QMap<QString,QString>& map2 = map;
.br
        str << map["Weis"] << map["Reggie"] << endl;
.fi
.PP
The code fragment will print out "Weis", "" and the second part will print "Weis", "". In addition the first fragment inserted an empty entry with they "Ettrich". The second one did not insert an empty entry with key "Reggie" because the const operator[] was used which can not do insertion. So if you are not shure wether a certain element is in the map you should use find() and iterators.
.PP
If you just want to know wether a certain key is contained in the map, the the contains() function is what you are looking for. In addition count() tells you how many keys there are currently in the map.
.PP
Another method for traversing a map is to use the functions begin() and end(). With a simple for loop as shown in the example you can iterate over the complete map. It is save to have multiple iterators at the same time. If some member of the map is removed then only iterators pointing to the removed member become invalid. Inserting in the map does not invalidate any iterator.
.PP
Since QMap 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().
.PP
QMap is implict shared. That means you can just make copies of the map in time O(1). If multiple QMap instances share the same data and one is doing a modification of the maps 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 QMap and a copy of this map 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".
.PP
There are two ways of inerting new elements in a list. One uses the insert() method while the other one uses operator[] like this:
.PP
.nf
.br
        QMap<QString,QString> map;
.br
        map["Weis"] = "Torben";
.fi
;
.PP
Items can be removed from the map in two ways. The first is to pass an iterator to the remove(). The other possibility is to pass a key value to remove() which will delete the entry with the requested key. In addition you can clear the entire map using the clear() method.
.PP
See also: QMapIterator.
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QMap::QMap ()"
Constructs an empty map.
.SH "QMap::QMap ( const QMap<Key,T> & m )"
Constructs a copy of \fIm.\fR
.PP
This operation costs O(1) time since QMap 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 QMap from a function is very fast.
.SH "QMap::~QMap ()"
Destroys the map. References to the values in the map and all iterators of this map become invalidated. Since QMap 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.
.SH "ConstIterator QMap::begin () const"
Returns an iterator pointing to the first element in the map. This iterator equals end() if the map is empty;
.PP
See also: end(), \\sa and QMapConstIterator.
.SH "Iterator QMap::begin ()"
Returns an iterator pointing to the first element in the map. This iterator equals end() if the map is empty;
.PP
See also: end(), \\sa and QMapIterator.
.SH "void QMap::clear ()"
Removes all items from the map.
.PP
See also: remove().
.SH "bool QMap::contains ( const Key & k ) const"
Returns TRUE if the key \\k is contained in the map.
.SH "uint QMap::count () const"
Returns the number of items in the ap.
.PP
See also: isEmpty().
.SH "void QMap::detach () \fC[protected]\fR"
If the map does not share its data with another QMap 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 map is modified. The implicit sharing mechanism is implemented this way.
.SH "ConstIterator QMap::end () const"
Returns an iterator pointing behind the last element in the map. This iterator equals begin() if the map is empty.
.PP
See also: begin(), \\sa and QMapConstIterator.
.SH "Iterator QMap::end ()"
Returns an iterator pointing behind the last element in the map. This iterator equals begin() if the map is empty.
.PP
See also: begin(), \\sa and QMapIterator.
.SH "ConstIterator QMap::find ( const Key & k ) const"
Finds the key \fIk\fR in the map.
.PP
Returns end() if no key did match.
.PP
See also: QMapConstIterator.
.SH "Iterator QMap::find ( const Key & k )"
Finds the key \fIk\fR in the map.
.PP
Returns end() if no key did match.
.PP
See also: QMapIterator.
.SH "Iterator QMap::insert ( const Key & key, const T & value )"
Inserts the \fIvalue\fR with key \fIk.\fR
.PP
Returns an iterator pointing at the inserted value.
.PP
See also: QMapIterator.
.SH "bool QMap::isEmpty () const"
Returns TRUE if the list is empty, i.e. count() == 0. Returns FALSE otherwise.
.PP
See also: count().
.SH "T& QMap::operator[] ( const Key & k )"
Returns the value associated with the key \fIk.\fR If no such key is present then en empty item is inserted with this key and a reference to the item is returned.
.PP
You can use this operator in two directions: For reading and for writing:
.PP
.nf
.br
        QMap<QString,QString> map;
.br
        map[ "Weis" ] = "Torben";
.br
        stream << map[ "Weis" ];
.fi
.SH "const T& QMap::operator[] ( const Key & k ) const"
Returns the value associated with the key \fIk.\fR If no such key is present then a reference to an empty item is returned.
.SH "void QMap::remove ( Iterator it )"
Removes the item at position \fIit\fR in the map.
.PP
See also: clear(), \\sa and QMapIterator.
.SH "void QMap::remove ( const Key & k )"
Removes the item with the key \fIk.\fR
.PP
See also: clear().
.SH "Iterator QMap::replace ( const Key & k, const T & v )"
Replaces the value with key \fIk\fR from the map if possible and inserts the new value \fIv\fR with key \\k in the map.
.PP
See also: insert(), \\sa, remove(), \\sa and QMapIterator.
.SH RELATED FUNCTION DOCUMENTATION
.SH "QDataStream& operator>> (QDataStream & s, QMap<Key,T> & m)"
Reads a map from the stream. The types \fIKey\fR and \fIT\fR must implement the streaming operator, too.
.SH "QDataStream& operator<< (QDataStream & s, const QMap<Key,T> & m)"
Writes a map to the stream. The types \fIKey\fR and \fIT\fR must implement
the streaming operator, too.
.SH "SEE ALSO"
.BR http://www.troll.no/qt/qmap.html
.SH COPYRIGHT
Copyright 1992-1999 Troll Tech AS.  See the license file included in
the distribution for a complete license statement.
.SH AUTHOR
Generated automatically from the source code.