Platform::Collections::Map Class
Represents a map, which is a collection of key-value pairs. Implements Windows::Foundation::Collections::IObservableMap to help with XAML data binding.
Syntax
template <
typename K,
typename V,
typename C = std::less<K>>
ref class Map sealed;
Parameters
K
The type of the key in the key-value pair.
V
The type of the value in the key-value pair.
C
A type that provides a function object that can compare two element values as sort keys to determine their relative order in the Map. By default, std::less<K>.
__is_valid_winrt_type() A compiler-generated function that validates the type of K and V and provides a friendly error message if the type cannot be stored in the Map.
Remarks
Allowed types are:
integers
interface class^
public ref class^
value struct
public enum class
Map is basically a wrapper for std::map. It is a C++ concrete implementation of the Windows::Foundation::Collections::IMap<Windows::Foundation::Collections::IKeyValuePair<K,V>> and IObservableMap types that are passed across public Windows Runtime interfaces. If you try to use a Platform::Collections::Map type in a public return value or parameter, compiler error C3986 is raised. You can fix the error by changing the type of the parameter or return value to Windows::Foundation::Collections::IMap<K,V>.
For more information, see Collections.
Members
Public Constructors
| Name | Description |
|---|---|
| Map::Map | Initializes a new instance of the Map class. |
Public Methods
| Name | Description |
|---|---|
| Map::Clear | Removes all key-value pairs from the current Map object. |
| Map::First | Returns an iterator that specifies the first element in the map. |
| Map::GetView | Returns a read-only view of the current Map; that is, a Platform::Collections::MapView Class. |
| Map::HasKey | Determines whether the current Map contains the specified key. |
| Map::Insert | Adds the specified key-value pair to the current Map object. |
| Map::Lookup | Retrieves the element at the specified key in the current Map object. |
| Map::Remove | Deletes the specified key-value pair from the current Map object. |
| Map::Size | Returns the number of elements in the current Map object. |
Events
| Name | Description |
|---|---|
| Map::MapChanged event | Occurs when the Map changes. |
Inheritance Hierarchy
Map
Requirements
Header: collection.h
Namespace: Platform::Collections
Map::Clear Method
Removes all key-value pairs from the current Map object.
Syntax
virtual void Clear();
Map::First Method
Returns an iterator that specifies the first element in the map, or nullptr if the map is empty.
Syntax
virtual Windows::Foundation::Collections::IIterator<
Windows::Foundation::Collections::IKeyValuePair<K, V>^>^ First();
Return Value
An iterator that specifies the first element in the map.
Remarks
A convenient way to hold the iterator returned by First() is to assign the return value to a variable that is declared with the auto type deduction keyword. For example, auto x = myMap->First();.
Map::GetView Method
Returns a read-only view of the current Map; that is, a Platform::Collections::MapView Class, which implements the Windows::Foundation::Collections::IMapView<K,V> interface.
Syntax
Windows::Foundation::Collections::IMapView<K, V>^ GetView();
Return Value
A MapView object.
Map::HasKey Method
Determines whether the current Map contains the specified key.
Syntax
bool HasKey(K key);
Parameters
key
The key used to locate the Map element. The type of key is typename K.
Return Value
true if the key is found; otherwise, false.
Map::Insert Method
Adds the specified key-value pair to the current Map object.
Syntax
virtual bool Insert(K key, V value);
Parameters
key
The key portion of the key-value pair. The type of key is typename K.
value
The value portion of the key-value pair. The type of value is typename V.
Return Value
true if the key of an existing element in the current Map matches key and the value portion of that element is set to value. false if no existing element in the current Map matches key and the key and value parameters are made into a key-value pair and then added to the current Map.
Map::Lookup Method
Retrieves the value of type V that is associated with the specified key of type K, if the key exists.
Syntax
V Lookup(K key);
Parameters
key
The key used to locate an element in the Map. The type of key is typename K.
Return Value
The value that is paired with the key. The type of the return value is typename V.
Remarks
If the key does not exist, then a Platform::OutOfBoundsException is thrown.
Map::Map Constructor
Initializes a new instance of the Map class.
Syntax
explicit Map(const C& comp = C());
explicit Map(const StdMap& m);
explicit Map(StdMap&& m ;
template <typename InIt>
Map(
InItfirst,
InItlast,
const C& comp = C());
Parameters
InIt
The typename of the current Map.
comp
A type that provides a function object that can compare two element values as sort keys to determine their relative order in the Map.
m
A reference or rvalue to a map Class that is used to initialize the current Map.
first
The input iterator of the first element in a range of elements used to initialize the current Map.
last
The input iterator of the first element after a range of elements used to initialize the current Map.
Map::MapChanged Event
Raised when an item is inserted into or removed from the map.
Syntax
event Windows::Foundation::Collections::MapChangedEventHandler<K,V>^ MapChanged;
Property Value/Return Value
A MapChangedEventHandler<K,V> that contains information about the object that raised the event, and the kind of change that occurred. See also IMapChangedEventArgs<K> and CollectionChange Enumeration.
.NET Framework Equivalent
Windows Runtime apps that use C# or Visual Basic project IMap<K,V> as IDictionary<K,V>.
Map::Remove Method
Deletes the specified key-value pair from the current Map object.
Syntax
virtual void Remove(K key);
Parameters
key
The key portion of the key-value pair. The type of key is typename K.
Map::Size Method
Returns the number of Windows::Foundation::Collections::IKeyValuePair<K,V> elements in the Map.
Syntax
virtual property unsigned int Size;
Return Value
The number of elements in the Map.
See also
Collections (C++/CX)
Platform Namespace
Creating Windows Runtime Components in C++