Map - SeqAn API Documentation

# Class Map
Set/dictionary container.

All Subcl's | Skiplist, VectorSet
Defined in | <seqan/map.h>
Signature | `template <typename TValue, typename TSpec> class Map;`

## Template Parameters

`TSpec` | The specializing type. Default: Skiplist
`TValue` | Type of values that are stored in the map. Use a Pair<Key, Cargo> to implement a dictionary mapping from `Key` to `Cargo`.

## Interface Function Overview

- `void add(map, value);, void add(map, key, cargo);`
  Insert another value into a multi map.
- `TCargo find(map, key);`
  Returns a cargo given a key.
- `void erase(map, key);, void erase(map, iterator);`
  Removes a value from a map.
- `void eraseAll(map, key);`
  Removes a value from a map.
- `TIterator find(map, key);`
  Find a value in a map.
- `bool hasKey(map, key);`
  Determines whether a map contains a value given key.
- `void insert(map, value);, void insert(map, key, cargo);`
  Insert new value into map.
- `TSize length(map);`
  Return number of elements in map.
- `TMapValue mapValue(map, key);`
  Subscript `operator[]` of maps.
- `TReference value(map, key);`
  Returns a value given a key.

## Interface Metafunction Overview

- `MapValue<T>::Type`
  Type of the map value type.

## Interface Functions Detail

### `void add(map, value); void add(map, key, cargo);`

Insert another value into a multi map.

#### Parameters

`map` | A map. Types: Skiplist
`value` | A value that is added to `map`.
`cargo` | A cargo.
`key` | A key.

If `key` and `cargo` are specified, a new value of that key and value is added.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TCargo find(map, key);`

Returns a cargo given a key.

#### Parameters

`map` | A map.
`key` | A key.

#### Returns

`TReturn` | The cargo of the first value in `map` of the given key, if there is any. Otherwise, the cargo of a new value that is inserted to `map`.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `void erase(map, key); void erase(map, iterator);`

Removes a value from a map.

#### Parameters

`map` | A map. Types: Map
`key` | The key of a value in `map`.
`iterator` | An iterator to a value in `map`.

Removes the first value in `map` of the given key, if there is any.

Use eraseAll to remove all values of the given key in a multi map.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `void eraseAll(map, key);`

Removes a value from a map.

#### Parameters

`map` | A map. Types: Skiplist
`key` | The key of a value in `map`.

Removes all values in `map` of the given key, if there is any.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TIterator find(map, key);`

Find a value in a map.

#### Parameters

`map` | A map. Types: Map
`key` | A key.

#### Returns

`TIterator` | An iterator to the first value in `map` of the given key, if there is any. An iterator to the fist value in `map` with key > `key`, otherwise.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

#### See Also

- cargo
- value

### `bool hasKey(map, key);`

Determines whether a map contains a value given key.

#### Parameters

`map` | A map. Types: Map
`key` | A key.

#### Returns

`bool` | `true`, if there is a value in `map` of that key, `false` otherwise.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `void insert(map, value); void insert(map, key, cargo);`

Insert new value into map.

#### Parameters

`map` | A map.
`value` | A value that is added to `map`.
`key` | A key.
`cargo` | A cargo.

If `key` and `cargo` are specified, a new value of that key and value is added. If there is already a value of that key in `map`, the value of this element is changed to `cargo`.

If `value` 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.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TSize length(map);`

Return number of elements in map.

#### Parameters

`map` | The Map to query for its size.

#### Returns

`TSize` | The number of elements in the map.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TMapValue mapValue(map, key);`

Subscript `operator[]` of maps.

#### Parameters

`map` | A map. Types: Map
`key` | A key.

#### Returns

`TMapValue` | If `map` is a set: The same as Map#hasKey. If `map` is a dictionary: The same as Map#value.

#### Remarks

Usually, Map#value implements the subscript operator `[ ]`, but for maps, this operator is implemented in `mapValue`. The semantic of this operator depends on the kind of map: If the map has a Cargo.cargo, than `mapValue(map, key)` 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 `true`, if `key` is in `map`, or `false` otherwise.

#### 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.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TReference value(map, key);`

Note.

Do not change the key of a value in the map.

Returns a value given a key.

#### Parameters

`map` | A map.
`key` | A key.

#### Returns

`TReference` | The first value in `map` of the given key, if there is any. Otherwise, a new value that is inserted to `map`.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

## Interface Metafunctions Detail

### `MapValue<T>::Type`

Type of the map value type.

#### Template Parameters

`T` | A map type. Types: Map

#### Returns

`Type` | the map value type.

#### Dox Sources

    /*!
     * @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>.
     *
     * @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 &gt; <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.
     *
     * @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.
     *
     * @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.
     */