QMap 类是提供关联数组的模板类。 更多...
| 头： | #include <QMap> |
| CMake: |
find_package(Qt6 COMPONENTS Core REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
注意： 此类的所有函数 可重入 .
| class | const_iterator |
| class | iterator |
| class | key_iterator |
| ConstIterator | |
| Iterator | |
| const_key_value_iterator | |
| difference_type | |
| key_type | |
| key_value_iterator | |
| mapped_type | |
| size_type |
| QMap (QMap<Key, T> && other ) | |
| QMap (const QMap<Key, T> & other ) | |
| QMap (std::map<Key, T> && other ) | |
| QMap (const std::map<Key, T> & other ) | |
| QMap (std::initializer_list<std::pair<Key, T> > list ) | |
| QMap () | |
| QMap<Key, T> & | operator= (QMap<Key, T> && other ) |
| QMap<Key, T> & | operator= (const QMap<Key, T> & other ) |
| ~QMap () | |
| QMap::iterator | begin () |
| QMap::const_iterator | begin () const |
| QMap::const_iterator | cbegin () const |
| QMap::const_iterator | cend () const |
| void | clear () |
| QMap::const_iterator | constBegin () const |
| QMap::const_iterator | constEnd () const |
| QMap::const_iterator | constFind (const Key & key ) const |
| QMap::const_key_value_iterator | constKeyValueBegin () const |
| QMap::const_key_value_iterator | constKeyValueEnd () const |
| bool | contains (const Key & key ) const |
| QMap::size_type | count (const Key & key ) const |
| QMap::size_type | count () const |
| bool | empty () const |
| QMap::iterator | end () |
| QMap::const_iterator | end () const |
| QPair<QMap::iterator, QMap::iterator> | equal_range (const Key & key ) |
| QPair<QMap::const_iterator, QMap::const_iterator> | equal_range (const Key & key ) const |
| QMap::iterator | erase (QMap::const_iterator pos ) |
| QMap::iterator | erase (QMap::const_iterator first , QMap::const_iterator last ) |
| QMap::iterator | find (const Key & key ) |
| QMap::const_iterator | find (const Key & key ) const |
| T & | first () |
| const T & | first () const |
| const Key & | firstKey () const |
| QMap::iterator | insert (const Key & key , const T & value ) |
| QMap::iterator | insert (QMap::const_iterator pos , const Key & key , const T & value ) |
| void | insert (const QMap<Key, T> & map ) |
| void | insert (QMap<Key, T> && map ) |
| bool | isEmpty () const |
| Key | key (const T & value , const Key & defaultKey = Key()) const |
| QMap::key_iterator | keyBegin () const |
| QMap::key_iterator | keyEnd () const |
| QMap::key_value_iterator | keyValueBegin () |
| QMap::const_key_value_iterator | keyValueBegin () const |
| QMap::key_value_iterator | keyValueEnd () |
| QMap::const_key_value_iterator | keyValueEnd () const |
| QList<Key> | keys () const |
| QList<Key> | keys (const T & value ) const |
| T & | last () |
| const T & | last () const |
| const Key & | lastKey () const |
| QMap::iterator | lowerBound (const Key & key ) |
| QMap::const_iterator | lowerBound (const Key & key ) const |
| QMap::size_type | remove (const Key & key ) |
| QMap::size_type | removeIf (Predicate pred ) |
| QMap::size_type | size () const |
| void | swap (QMap<Key, T> & other ) |
| T | take (const Key & key ) |
| std::map<Key, T> | toStdMap () const & |
| QMap::iterator | upperBound (const Key & key ) |
| QMap::const_iterator | upperBound (const Key & key ) const |
| T | value (const Key & key , const T & defaultValue = T()) const |
| QList<T> | values () const |
| T & | operator[] (const Key & key ) |
| T | operator[] (const Key & key ) const |
| qsizetype | erase_if (QMap<Key, T> & map , Predicate pred ) |
| bool | operator!= (const QMap<Key, T> & lhs , const QMap<Key, T> & rhs ) |
| QDataStream & | operator<< (QDataStream & out , const QMap<Key, T> & map ) |
| bool | operator== (const QMap<Key, T> & lhs , const QMap<Key, T> & rhs ) |
| QDataStream & | operator>> (QDataStream & in , QMap<Key, T> & map ) |
QMap<Key, T> 是一种 Qt 一般 容器类 。它存储 (key, value) 对，并提供按 Key 的快速查找。
QMap 和 QHash 提供非常类似的功能。差异是：
这里是 QMap 范例具有
QString
键和
int
值：
QMap<QString, int> map;
要将 (key, value) 对插入映射，可以使用 operator[]()：
map["one"] = 1; map["three"] = 3; map["seven"] = 7;
This inserts the following three (key, value) pairs into the QMap: ("one", 1), ("three", 3), and ("seven", 7). Another way to insert items into the map is to use insert ():
map.insert("twelve", 12);
要查找值，使用 operator[]() 或 value ():
int num1 = map["thirteen"]; int num2 = map.value("thirteen");
If there is no item with the specified key in the map, these functions return a 默认构造值 .
If you want to check whether the map contains a certain key, use contains ():
int timeout = 30; if (map.contains("TIMEOUT")) timeout = map.value("TIMEOUT");
There is also a value () overload that uses its second argument as a default value if there is no item with the specified key:
int timeout = map.value("TIMEOUT", 30);
In general, we recommend that you use contains () 和 value () rather than operator[]() for looking up a key in a map. The reason is that operator[]() silently inserts an item into the map if no item exists with the same key (unless the map is const). For example, the following code snippet will create 1000 items in memory:
// WRONG QMap<int, QWidget *> map; ... for (int i = 0; i < 1000; ++i) { if (map[i] == okButton) cout << "Found button at index " << i << Qt::endl; }
要避免此问题，替换
map[i]
with
map.value(i)
在以上代码中。
If you want to navigate through all the (key, value) pairs stored in a QMap, you can use an iterator. QMap provides both Java 风格迭代器 ( QMapIterator and QMutableMapIterator ) 和 STL 样式迭代器 ( QMap::const_iterator and QMap::iterator ). Here's how to iterate over a QMap< QString , int> using a Java-style iterator:
QMapIterator<QString, int> i(map); while (i.hasNext()) { i.next(); cout << i.key() << ": " << i.value() << Qt::endl; }
Here's the same code, but using an STL-style iterator this time:
QMap<QString, int>::const_iterator i = map.constBegin(); while (i != map.constEnd()) { cout << i.key() << ": " << i.value() << Qt::endl; ++i; }
The items are traversed in ascending key order.
Normally, a QMap allows only one value per key. If you call insert () with a key that already exists in the QMap, the previous value will be erased. For example:
map.insert("plenty", 100); map.insert("plenty", 2000); // map.value("plenty") == 2000
However, you can store multiple values per key by using QMultiMap . If you want to retrieve all the values for a single key, you can use values(const Key &key), which returns a QList <T>:
QList<int> values = map.values("plenty"); for (int i = 0; i < values.size(); ++i) cout << values.at(i) << Qt::endl;
Another approach is to call find () to get the STL-style iterator for the first item with a key and iterate from there:
QMap<QString, int>::iterator i = map.find("plenty"); while (i != map.end() && i.key() == "plenty") { cout << i.value() << Qt::endl; ++i; }
If you only need to extract the values from a map (not the keys), you can also use foreach :
QMap<QString, int> map; ... foreach (int value, map) cout << value << Qt::endl;
Items can be removed from the map in several ways. One way is to call remove (); this will remove any item with the given key. Another way is to use QMutableMapIterator::remove (). In addition, you can clear the entire map using clear ().
QMap's key and value data types must be
可赋值数据类型
. This covers most data types you are likely to encounter, but the compiler won't let you, for example, store a
QWidget
作为值；取而代之，存储
QWidget
*. In addition, QMap's key type must provide operator<(). QMap uses it to keep its items sorted, and assumes that two keys
x
and
y
are equivalent if neither
x < y
nor
y < x
为 true。
范例：
#ifndef EMPLOYEE_H #define EMPLOYEE_H class Employee { public: Employee() {} Employee(const QString &name, QDate dateOfBirth); ... private: QString myName; QDate myDateOfBirth; }; inline bool operator<(const Employee &e1, const Employee &e2) { if (e1.name() != e2.name()) return e1.name() < e2.name(); return e1.dateOfBirth() < e2.dateOfBirth(); } #endif // EMPLOYEE_H
In the example, we start by comparing the employees' names. If they're equal, we compare their dates of birth to break the tie.
另请参阅 QMapIterator , QMutableMapIterator , QHash ，和 QSet .
Qt 样式同义词 QMap <Key, T>::const_iterator.
Qt 样式同义词 QMap <Key, T>::iterator.
[since 5.10]
QMap::
const_key_value_iterator
The QMap::const_key_value_iterator typedef provides an STL-style iterator for QMap .
QMap::const_key_value_iterator is essentially the same as QMap::const_iterator with the difference that operator*() returns a key/value pair instead of a value.
该 typedef 在 Qt 5.10 引入。
另请参阅 QKeyValueIterator .
[alias]
QMap::
difference_type
typedef 对于 ptrdiff_t。为兼容 STL 提供。
[alias]
QMap::
key_type
typedef 对于 Key。为兼容 STL 提供。
[since 5.10]
QMap::
key_value_iterator
The QMap::key_value_iterator typedef provides an STL-style iterator for QMap .
QMap::key_value_iterator is essentially the same as QMap::iterator with the difference that operator*() returns a key/value pair instead of a value.
该 typedef 在 Qt 5.10 引入。
另请参阅 QKeyValueIterator .
[alias]
QMap::
mapped_type
typedef 对于 T。为兼容 STL 提供。
[alias]
QMap::
size_type
typedef 对于 int。为兼容 STL 提供。
[default, since 5.2]
QMap::
QMap
(
QMap
<
Key
,
T
> &&
other
)
Move-constructs a QMap instance.
该函数在 Qt 5.2 引入。
[default]
QMap::
QMap
(const
QMap
<
Key
,
T
> &
other
)
构造副本为 other .
This operation occurs in 常量时间 , because QMap is 隐式共享 . This makes returning a QMap from a function very fast. If a shared instance is modified, it will be copied (copy-on-write), and this takes 线性时间 .
另请参阅 operator= .
Constructs a map by moving from other .
另请参阅 toStdMap ().
构造副本为 other .
另请参阅 toStdMap ().
[since 5.1]
QMap::
QMap
(
std::initializer_list
<
std::pair
<
Key
,
T
> >
list
)
Constructs a map with a copy of each of the elements in the initializer list list .
该函数在 Qt 5.1 引入。
Constructs an empty map.
另请参阅 clear ().
[default, since 5.2]
QMap
<
Key
,
T
> &QMap::
operator=
(
QMap
<
Key
,
T
> &&
other
)
移动赋值 other 到此 QMap 实例。
该函数在 Qt 5.2 引入。
[default]
QMap
<
Key
,
T
> &QMap::
operator=
(const
QMap
<
Key
,
T
> &
other
)
赋值 other to this map and returns a reference to this map.
[default]
QMap::
~QMap
()
Destroys the map. References to the values in the map, and all iterators over this map, become invalid.
返回 STL 样式迭代器 pointing to the first item in the map.
另请参阅 constBegin () 和 end ().
这是重载函数。
[since 5.0]
QMap::const_iterator
QMap::
cbegin
() const
返回常量 STL 样式迭代器 pointing to the first item in the map.
该函数在 Qt 5.0 引入。
[since 5.0]
QMap::const_iterator
QMap::
cend
() const
返回常量 STL 样式迭代器 pointing to the imaginary item after the last item in the map.
该函数在 Qt 5.0 引入。
Removes all items from the map.
另请参阅 remove ().
返回常量 STL 样式迭代器 pointing to the first item in the map.
返回常量 STL 样式迭代器 pointing to the imaginary item after the last item in the map.
另请参阅 constBegin () 和 end ().
Returns an const iterator pointing to the item with key key in the map.
If the map contains no item with key key ，函数返回 constEnd ().
另请参阅 find ().
[since 5.10]
QMap::const_key_value_iterator
QMap::
constKeyValueBegin
() const
返回常量 STL 样式迭代器 pointing to the first entry in the map.
该函数在 Qt 5.10 引入。
另请参阅 keyValueBegin ().
[since 5.10]
QMap::const_key_value_iterator
QMap::
constKeyValueEnd
() const
返回常量 STL 样式迭代器 pointing to the imaginary entry after the last entry in the map.
该函数在 Qt 5.10 引入。
另请参阅 constKeyValueBegin ().
返回
true
if the map contains an item with key
key
；否则返回
false
.
另请参阅 count ().
Returns the number of items associated with key key .
另请参阅 contains ().
这是重载函数。
如同 size ().
此函数为兼容 STL (标准模板库) 提供。它相当于 isEmpty (), returning true if the map is empty; otherwise returning false.
返回 STL 样式迭代器 pointing to the imaginary item after the last item in the map.
这是重载函数。
Returns a pair of iterators delimiting the range of values
[first, second)
, that are stored under
key
.
[since 5.6]
QPair
<
QMap::const_iterator
,
QMap::const_iterator
> QMap::
equal_range
(const
Key
&
key
) const
这是重载函数。
该函数在 Qt 5.6 引入。
Removes the (key, value) pair pointed to by the iterator pos from the map, and returns an iterator to the next item in the map.
注意： The iterator pos must be valid and dereferenceable.
另请参阅 remove ().
[since 6.0]
QMap::iterator
QMap::
erase
(
QMap::const_iterator
first
,
QMap::const_iterator
last
)
Removes the (key, value) pairs pointed to by the iterator range [ first , last ) from the map. Returns an iterator to the item in the map following the last removed element.
注意：
范围
[first, last)
must
be a valid range in
*this
.
该函数在 Qt 6.0 引入。
另请参阅 remove ().
Returns an iterator pointing to the item with key key in the map.
If the map contains no item with key key ，函数返回 end ().
另请参阅 constFind (), value (), values (), lowerBound ()，和 upperBound ().
这是重载函数。
[since 5.2]
T
&QMap::
first
()
Returns a reference to the first value in the map, that is the value mapped to the smallest key. This function assumes that the map is not empty.
When unshared (or const version is called), this executes in 常量时间 .
该函数在 Qt 5.2 引入。
另请参阅 last (), firstKey ()，和 isEmpty ().
[since 5.2]
const
T
&QMap::
first
() const
这是重载函数。
该函数在 Qt 5.2 引入。
[since 5.2]
const
Key
&QMap::
firstKey
() const
Returns a reference to the smallest key in the map. This function assumes that the map is not empty.
This executes in 常量时间 .
该函数在 Qt 5.2 引入。
另请参阅 lastKey (), first (), keyBegin ()，和 isEmpty ().
Inserts a new item with the key key 和值 value .
If there is already an item with the key key , that item's value is replaced with value .
另请参阅 QMultiMap::insert ().
[since 5.1]
QMap::iterator
QMap::
insert
(
QMap::const_iterator
pos
, const
Key
&
key
, const
T
&
value
)
这是重载函数。
Inserts a new item with the key key and value value and with hint pos suggesting where to do the insert.
若 constBegin () is used as hint it indicates that the key is less than any key in the map while constEnd () suggests that the key is (strictly) larger than any key in the map. Otherwise the hint should meet the condition ( pos - 1). key () < key <= pos. key (). If the hint pos is wrong it is ignored and a regular insert is done.
If there is already an item with the key key , that item's value is replaced with value .
If the hint is correct and the map is unshared, the insert executes in amortized 常量时间 .
When creating a map from sorted data inserting the largest key first with constBegin () is faster than inserting in sorted order with constEnd (), since constEnd () - 1 (which is needed to check if the hint is valid) needs logarithmic time .
注意： Be careful with the hint. Providing an iterator from an older shared instance might crash but there is also a risk that it will silently corrupt both the map and the pos map.
该函数在 Qt 5.1 引入。
另请参阅 QMultiMap::insert ().
[since 5.15]
void
QMap::
insert
(const
QMap
<
Key
,
T
> &
map
)
插入所有项在 map 进此映射。
If a key is common to both maps, its value will be replaced with the value stored in map .
注意： 若 map contains multiple entries with the same key then the final value of the key is undefined.
该函数在 Qt 5.15 引入。
另请参阅 QMultiMap::insert ().
[since 5.15]
void
QMap::
insert
(
QMap
<
Key
,
T
> &&
map
)
Moves all the items from map 进此映射。
If a key is common to both maps, its value will be replaced with the value stored in map .
若 map is shared, then the items will be copied instead.
该函数在 Qt 5.15 引入。
返回
true
若映射不包含项；否则返回 false。
另请参阅 size ().
这是重载函数。
返回第一个键具有值 value ，或 defaultKey if the map contains no item with value value . If no defaultKey is provided the function returns a default-constructed key .
此函数可能很慢 ( 线性时间 )，因为 QMap 's internal data structure is optimized for fast lookup by key, not by value.
[since 5.6]
QMap::key_iterator
QMap::
keyBegin
() const
返回常量 STL 样式迭代器 pointing to the first key in the map.
该函数在 Qt 5.6 引入。
[since 5.6]
QMap::key_iterator
QMap::
keyEnd
() const
返回常量 STL 样式迭代器 pointing to the imaginary item after the last key in the map.
该函数在 Qt 5.6 引入。
另请参阅 keyBegin () 和 lastKey ().
[since 5.10]
QMap::key_value_iterator
QMap::
keyValueBegin
()
返回 STL 样式迭代器 pointing to the first entry in the map.
该函数在 Qt 5.10 引入。
另请参阅 keyValueEnd ().
[since 5.10]
QMap::const_key_value_iterator
QMap::
keyValueBegin
() const
返回常量 STL 样式迭代器 pointing to the first entry in the map.
该函数在 Qt 5.10 引入。
另请参阅 keyValueEnd ().
[since 5.10]
QMap::key_value_iterator
QMap::
keyValueEnd
()
返回 STL 样式迭代器 pointing to the imaginary entry after the last entry in the map.
该函数在 Qt 5.10 引入。
另请参阅 keyValueBegin ().
[since 5.10]
QMap::const_key_value_iterator
QMap::
keyValueEnd
() const
返回常量 STL 样式迭代器 pointing to the imaginary entry after the last entry in the map.
该函数在 Qt 5.10 引入。
另请参阅 keyValueBegin ().
Returns a list containing all the keys in the map in ascending order.
The order is guaranteed to be the same as that used by values ().
此函数创建新列表，按 线性时间 . The time and memory use that entails can be avoided by iterating from keyBegin () 到 keyEnd ().
另请参阅 QMultiMap::uniqueKeys (), values ()，和 key ().
这是重载函数。
Returns a list containing all the keys associated with value value in ascending order.
此函数可能很慢 ( 线性时间 )，因为 QMap 's internal data structure is optimized for fast lookup by key, not by value.
[since 5.2]
T
&QMap::
last
()
Returns a reference to the last value in the map, that is the value mapped to the largest key. This function assumes that the map is not empty.
When unshared (or const version is called), this executes in logarithmic time .
该函数在 Qt 5.2 引入。
另请参阅 first (), lastKey ()，和 isEmpty ().
[since 5.2]
const
T
&QMap::
last
() const
这是重载函数。
该函数在 Qt 5.2 引入。
[since 5.2]
const
Key
&QMap::
lastKey
() const
Returns a reference to the largest key in the map. This function assumes that the map is not empty.
This executes in logarithmic time .
该函数在 Qt 5.2 引入。
另请参阅 firstKey (), last (), keyEnd ()，和 isEmpty ().
Returns an iterator pointing to the first item with key key in the map. If the map contains no item with key key , the function returns an iterator to the nearest item with a greater key.
另请参阅 upperBound () 和 find ().
这是重载函数。
Removes all the items that have the key key from the map. Returns the number of items removed which will be 1 if the key exists in the map, and 0 otherwise.
[since 6.1]
template <typename Predicate>
QMap::size_type
QMap::
removeIf
(
Predicate
pred
)
Removes all elements for which the predicate pred returns true from the map.
The function supports predicates which take either an argument of type
QMap<Key, T>::iterator
, or an argument of type
std::pair<const Key &, T &>
.
Returns the number of elements removed, if any.
该函数在 Qt 6.1 引入。
Returns the number of (key, value) pairs in the map.
Swaps map other with this map. This operation is very fast and never fails.
Removes the item with the key key from the map and returns the value associated with it.
If the item does not exist in the map, the function simply returns a 默认构造值 . If there are multiple items for key in the map, only the most recently inserted one is removed and returned.
若不使用返回值， remove () 效率更高。
另请参阅 remove ().
Returns an STL map equivalent to this QMap .
Returns an iterator pointing to the item that immediately follows the last item with key key in the map. If the map contains no item with key key , the function returns an iterator to the nearest item with a greater key.
范例：
QMap<int, QString> map; map.insert(1, "one"); map.insert(5, "five"); map.insert(10, "ten"); map.upperBound(0); // returns iterator to (1, "one") map.upperBound(1); // returns iterator to (5, "five") map.upperBound(2); // returns iterator to (5, "five") map.upperBound(10); // returns end() map.upperBound(999); // returns end()
另请参阅 lowerBound () 和 find ().
这是重载函数。
Returns the value associated with the key key .
If the map contains no item with key key ，函数返回 defaultValue . If no defaultValue is specified, the function returns a 默认构造值 .
另请参阅 key (), values (), contains ()，和 operator[] ().
Returns a list containing all the values in the map, in ascending order of their keys. If a key is associated with multiple values, all of its values will be in the list, and not just the most recently inserted one.
此函数创建新列表，按 线性时间 . The time and memory use that entails can be avoided by iterating from keyValueBegin () 到 keyValueEnd ().
Returns the value associated with the key key 作为可修改引用。
If the map contains no item with key key , the function inserts a 默认构造值 into the map with key key , and returns a reference to it. If the map contains multiple items with key key , this function returns a reference to the most recently inserted value.
这是重载函数。
如同 value ().
[since 6.1]
template <typename Key, typename T, typename Predicate>
qsizetype
erase_if
(
QMap
<
Key
,
T
> &
map
,
Predicate
pred
)
Removes all elements for which the predicate pred returns true from the map map .
The function supports predicates which take either an argument of type
QMap<Key, T>::iterator
, or an argument of type
std::pair<const Key &, T &>
.
Returns the number of elements removed, if any.
该函数在 Qt 6.1 引入。
返回
true
if
lhs
不等于
rhs
；否则返回 false。
Two maps are considered equal if they contain the same (key, value) pairs.
This function requires the key and the value types to implement
operator==()
.
另请参阅 operator== ().
写入映射 map 到流 out .
This function requires the key and value types to implement
operator<<()
.
另请参阅 QDataStream 运算符格式 .
返回
true
if
lhs
等于
rhs
；否则返回 false。
Two maps are considered equal if they contain the same (key, value) pairs.
This function requires the key and the value types to implement
operator==()
.
另请参阅 operator!= ().
读取映射从流 in into map .
This function requires the key and value types to implement
operator>>()
.
另请参阅 QDataStream 运算符格式 .