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

Public Methods

Events

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++