/*!
* @class Map
*
* @headerfile <seqan/map.h>
*
* @brief Set/dictionary container.
*
* @signature template <typename TValue, typename TSpec> class Map;
*
* @tparam TSpec The specializing type. Default: @link Skiplist @endlink
* @tparam TValue Type of values that are stored in the map. Use a Pair<Key,
* Cargo> to implement a dictionary mapping from <tt>Key</tt> to
* <tt>Cargo</tt>.
*
* @mfn Map#MapValue
*
* @brief Type of the map value type.
*
* @signature MapValue<T>::Type
*
* @tparam T A map type. Types: Map
*
* @return Type the map value type.
*
* @fn Map#length
*
* @headerfile <seqan/map.h>
*
* @brief Return number of elements in map.
*
* @signature TSize length(map);
*
* @param[in] map The Map to query for its size.
*
* @return TSize The number of elements in the map.
*
* @fn Map#mapValue
*
* @brief Subscript <tt>operator[]</tt> of maps.
*
* @signature TMapValue mapValue(map, key);
*
* @param[in,out] map A map. Types: Map
* @param[in] key A key.
*
* @return TMapValue If <tt>map</tt> is a set: The same as Map#hasKey. If
* <tt>map</tt> is a dictionary: The same as Map#value.
*
* @section Remarks
*
* Usually, Map#value implements the subscript operator <tt>[ ]</tt>, but for
* maps, this operator is implemented in <tt>mapValue</tt>. The semantic of this
* operator depends on the kind of map: If the map has a Cargo.cargo, than
* <tt>mapValue(map, key)</tt> returns the cargo of the (first) value in the map
* of the given key. If the map has no Cargo.cargo, than the function returns a
* <tt>true</tt>, if <tt>key</tt> is in <tt>map</tt>, or <tt>false</tt>
* otherwise.
*
* @section Remarks
*
* There is no way to create a set of Pair, since it is always interpreted as a
* key/value pair. If you need a key type that holds two members, define your
* own key type.
*
* You may overload Key and Cargo for your own value type in order to define,
* what part of your value type is used as key and what as cargo.
*
* @fn Map#find
*
* @headerfile <seqan/map.h>
*
* @brief Find a value in a map.
*
* @signature TIterator find(map, key);
*
* @param[in] map A map. Types: Map
* @param[in] key A key.
*
* @return TIterator An iterator to the first value in <tt>map</tt> of the given
* key, if there is any. An iterator to the fist value in
* <tt>map</tt> with key > <tt>key</tt>, otherwise.
*
* @see Map#value
* @see Map#cargo
*
* @fn Map#value
*
* @brief Returns a value given a key.
*
* @note Do not change the key of a value in the map.
*
* @signature TReference value(map, key);
*
* @param[in] map A map.
* @param[in] key A key.
*
* @return TReference The first value in <tt>map</tt> of the given key, if there
* is any. Otherwise, a new value that is inserted to
* <tt>map</tt>.
*
* @fn Map#cargo
*
* @brief Returns a cargo given a key.
*
* @signature TCargo find(map, key);
*
* @param[in,out] map A map.
* @param[in] key A key.
*
* @return TReturn The cargo of the first value in <tt>map</tt> of the given
* key, if there is any. Otherwise, the cargo of a new value
* that is inserted to <tt>map</tt>.
*
* @fn Map#insert
*
* @brief Insert new value into map.
*
* @signature void insert(map, value);
* @signature void insert(map, key, cargo);
*
* @param[in,out] map A map.
* @param[in] value A value that is added to <tt>map</tt>.
* @param[in] key A key.
* @param[in] cargo A cargo.
*
* If <tt>key</tt> and <tt>cargo</tt> are specified, a new value of that key and
* value is added. If there is already a value of that key in <tt>map</tt>, the
* value of this element is changed to <tt>cargo</tt>.
*
* If <tt>value</tt> is specified, and there is already a value in map of that
* key, than the cargo of this value is changed to cargo.cargo(value).
*
* Use Map#add instead to insert multiple values of the same key.
*
* @fn Map#add
*
* @brief Insert another value into a multi map.
*
* @signature void add(map, value);
* @signature void add(map, key, cargo);
*
* @param[in,out] map A map. Types: Skiplist
* @param[in] value A value that is added to <tt>map</tt>.
* @param[in] cargo A cargo.
* @param[in] key A key.
*
* If <tt>key</tt> and <tt>cargo</tt> are specified, a new value of that key and
* value is added.
*
* @fn Map#erase
*
* @brief Removes a value from a map.
*
* @signature void erase(map, key);
* @signature void erase(map, iterator);
*
* @param[in] map A map. Types: Map
* @param[in] key The key of a value in <tt>map</tt>.
* @param[in] iterator An iterator to a value in <tt>map</tt>.
*
* Removes the first value in <tt>map</tt> of the given key, if there is any.
*
* Use @link Map#eraseAll @endlink to remove all values of the given key in a
* multi map.
*
* @fn Map#eraseAll
*
* @brief Removes a value from a map.
*
* @signature void eraseAll(map, key);
*
* @param[in,out] map A map. Types: Skiplist
* @param[in] key The key of a value in <tt>map</tt>.
*
* Removes all values in <tt>map</tt> of the given key, if there is any.
*
* @fn Map#hasKey
*
* @brief Determines whether a map contains a value given key.
*
* @signature bool hasKey(map, key);
*
* @param[in] map A map. Types: Map
* @param[in] key A key.
*
* @return bool <tt>true</tt>, if there is a value in <tt>map</tt> of that key,
* <tt>false</tt> otherwise.
*/