Boost.Hana: boost::hana::map< implementation_defined > Struct Template Reference

| Boost.Hana 1.0.0 Your standard library for metaprogramming |

Synopsis of associated functions | Friends | Public Member Functions | List of all members
boost::hana::map< implementation_defined > Struct Template Reference
Data types

## Description

### template<typename implementation_defined>
struct boost::hana::map< implementation_defined >

Basic associative container requiring unique, `Comparable` and `Hashable` keys.

The order of the elements of the map is unspecified. Also, all the keys must be `Hashable`, and any two keys with equal hashes must be `Comparable` with each other at compile-time.

Note
  The actual representation of a `hana::map` is implementation-defined. In particular, one should not take for granted the order of the template parameters and the presence of any additional constructors or assignment operators than what is documented. The canonical way of creating a `hana::map` is through `hana::make_map`.

## Modeled concepts

1. `Comparable`
   Two maps are equal iff all their keys are equal and are associated to equal values.
   // Copyright Louis Dionne 2013-2016
   // Distributed under the Boost Software License, Version 1.0.
   // (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
   #include <boost/hana/assert.hpp>
   #include <boost/hana/integral_constant.hpp>
   #include <boost/hana/map.hpp>
   #include <boost/hana/pair.hpp>
   #include <boost/hana/type.hpp>
   #include <string>
   namespace hana = boost::hana;
   using namespace std::literals;
   int main() {
   BOOST_HANA_RUNTIME_CHECK(
   hana::make_map(
   hana::make_pair(hana::char_c<'a'>, "foobar"s),
   hana::make_pair(hana::type_c<int&&>, nullptr)
   )
   ==
   hana::make_map(
   hana::make_pair(hana::type_c<int&&>, (void*)0),
   hana::make_pair(hana::char_c<'a'>, "foobar"s)
   )
   );
   }
2. `Searchable`
   A map can be searched by its keys with a predicate yielding a compile-time `Logical`. Also note that `operator[]` can be used instead of `at_key`.
   // Copyright Louis Dionne 2013-2016
   // Distributed under the Boost Software License, Version 1.0.
   // (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
   #include <boost/hana/assert.hpp>
   #include <boost/hana/at_key.hpp>
   #include <boost/hana/equal.hpp>
   #include <boost/hana/find.hpp>
   #include <boost/hana/integral_constant.hpp>
   #include <boost/hana/map.hpp>
   #include <boost/hana/optional.hpp>
   #include <boost/hana/pair.hpp>
   #include <boost/hana/type.hpp>
   namespace hana = boost::hana;
   constexpr auto m = hana::make_map(
   hana::make_pair(hana::type_c<int>, 'i'),
   hana::make_pair(hana::type_c<float>, 'f')
   );
   static_assert(hana::find(m, hana::type_c<int>) == hana::just('i'), "");
   static_assert(hana::find(m, hana::type_c<float>) == hana::just('f'), "");
   BOOST_HANA_CONSTANT_CHECK(hana::find(m, hana::type_c<void>) == hana::nothing);
   BOOST_HANA_CONSTANT_CHECK(hana::find(m, hana::int_c<3>) == hana::nothing);
   // operator[] is equivalent to at_key
   static_assert(m[hana::type_c<int>] == 'i', "");
   static_assert(m[hana::type_c<float>] == 'f', "");
   int main() { }
3. `Foldable`
   Folding a map is equivalent to folding a list of the key/value pairs it contains. In particular, since that list is not guaranteed to be in any specific order, folding a map with an operation that is not both commutative and associative will yield non-deterministic behavior.
   // Copyright Louis Dionne 2013-2016
   // Distributed under the Boost Software License, Version 1.0.
   // (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
   #include <boost/hana/assert.hpp>
   #include <boost/hana/first.hpp>
   #include <boost/hana/fold_left.hpp>
   #include <boost/hana/insert.hpp>
   #include <boost/hana/integral_constant.hpp>
   #include <boost/hana/map.hpp>
   #include <boost/hana/pair.hpp>
   #include <boost/hana/second.hpp>
   #include <boost/hana/type.hpp>
   namespace hana = boost::hana;
   int main() {
   // Given a map of (key, value) pairs, returns a map of (value, key) pairs.
   // This requires both the keys and the values to be compile-time Comparable.
   auto invert = [](auto map) {
   return hana::fold_left(map, hana::make_map(), [](auto map, auto pair) {
   return hana::insert(map, hana::make_pair(hana::second(pair), hana::first(pair)));
   });
   };
   auto m = hana::make_map(
   hana::make_pair(hana::type_c<int>, hana::int_c<1>),
   hana::make_pair(hana::type_c<float>, hana::int_c<2>),
   hana::make_pair(hana::int_c<3>, hana::type_c<void>)
   );
   BOOST_HANA_CONSTANT_CHECK(invert(m) ==
   hana::make_map(
   hana::make_pair(hana::int_c<1>, hana::type_c<int>),
   hana::make_pair(hana::int_c<2>, hana::type_c<float>),
   hana::make_pair(hana::type_c<void>, hana::int_c<3>)
   )
   );
   }

## Conversion from any `Foldable`

Any `Foldable` of `Product`s can be converted to a `hana::map` with `hana::to<hana::map_tag>` or, equivalently, `hana::to_map`. If the `Foldable` contains duplicate keys, only the value associated to the first occurence of each key is kept.

// Copyright Louis Dionne 2013-2016
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
#include <boost/hana/assert.hpp>
#include <boost/hana/core/to.hpp>
#include <boost/hana/map.hpp>
#include <boost/hana/pair.hpp>
#include <boost/hana/tuple.hpp>
#include <boost/hana/type.hpp>
#include <string>
namespace hana = boost::hana;
using namespace std::literals;
int main() {
auto xs = hana::make_tuple(
hana::make_pair(hana::type_c<int>, "abcd"s),
hana::make_pair(hana::type_c<void>, 1234),
hana::make_pair(hana::type_c<int>, nullptr)
);
BOOST_HANA_RUNTIME_CHECK(
hana::to<hana::map_tag>(xs) == hana::make_map(
hana::make_pair(hana::type_c<int>, "abcd"s),
hana::make_pair(hana::type_c<void>, 1234)
)
);
}

## Synopsis of associated functions
template<>
constexpr auto | make< map_tag >
| Function object for creating a `hana::map`. More...
constexpr auto | make_map = make<map_tag>
| Alias to `make<map_tag>`; provided for convenience. More...
constexpr auto | to_map = to<map_tag>
| Equivalent to `to<map_tag>`; provided for convenience. More...
constexpr auto | keys
| Returns a `Sequence` of the keys of the map, in unspecified order. More...
constexpr auto | values
| Returns a `Sequence` of the values of the map, in unspecified order. More...
constexpr auto | insert
| Inserts a new key/value pair in a map. More...
constexpr auto | erase_key
| Removes a key/value pair from a map. More...

## Friends
template<typename X , typename Y >
constexpr auto | operator== (X &&x, Y &&y)
| Equivalent to `hana::equal`
template<typename X , typename Y >
constexpr auto | operator!= (X &&x, Y &&y)
| Equivalent to `hana::not_equal`

## Public Member Functions
constexpr | map ()=default
| Default-construct a map. This constructor only exists when all the elements of the map are default-constructible.
constexpr | map (map const &other)=default
| Copy-construct a map from another map. This constructor only exists when all the elements of the map are copy-constructible.
constexpr | map (map &&other)=default
| Move-construct a map from another map. This constructor only exists when all the elements of the map are move-constructible.
template<typename Key >
decltype(auto) constexpr | operator[] (Key &&key)
| Equivalent to `hana::at_key`

## Associated functions

template<typename implementation_defined >
template<>

constexpr auto make< map_tag >
| related

Initial value:
= [](auto&& ...pairs) {
return map<implementation_defined>{forwarded(pairs)...};
}

Function object for creating a `hana::map`.

Given zero or more `Product`s representing key/value associations, `make<map_tag>` returns a `hana::map` associating these keys to these values.

`make<map_tag>` requires all the keys to be unique and to have different hashes. If you need to create a map with duplicate keys or with keys whose hashes might collide, use `hana::to_map` or insert `(key, value)` pairs to an empty map successively. However, be aware that doing so will be much more compile-time intensive than using `make<map_tag>`, because the uniqueness of keys will have to be enforced.

## Example

// Copyright Louis Dionne 2013-2016
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
#include <boost/hana/assert.hpp>
#include <boost/hana/core/make.hpp>
#include <boost/hana/integral_constant.hpp>
#include <boost/hana/map.hpp>
#include <boost/hana/pair.hpp>
#include <boost/hana/type.hpp>
#include <string>
namespace hana = boost::hana;
using namespace std::literals;
int main() {
BOOST_HANA_RUNTIME_CHECK(
hana::make_map(
hana::make_pair(hana::int_c<1>, "foobar"s),
hana::make_pair(hana::type_c<void>, 1234)
)
==
hana::make<hana::map_tag>(
hana::make_pair(hana::int_c<1>, "foobar"s),
hana::make_pair(hana::type_c<void>, 1234)
)
);
}
template<typename implementation_defined >

constexpr auto make_map = make<map_tag>
| related

Alias to `make<map_tag>`; provided for convenience.

## Example

// Copyright Louis Dionne 2013-2016
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
#include <boost/hana/assert.hpp>
#include <boost/hana/core/make.hpp>
#include <boost/hana/integral_constant.hpp>
#include <boost/hana/map.hpp>
#include <boost/hana/pair.hpp>
#include <boost/hana/type.hpp>
#include <string>
namespace hana = boost::hana;
using namespace std::literals;
int main() {
BOOST_HANA_RUNTIME_CHECK(
hana::make_map(
hana::make_pair(hana::int_c<1>, "foobar"s),
hana::make_pair(hana::type_c<void>, 1234)
)
==
hana::make<hana::map_tag>(
hana::make_pair(hana::int_c<1>, "foobar"s),
hana::make_pair(hana::type_c<void>, 1234)
)
);
}
template<typename implementation_defined >

constexpr auto to_map = to<map_tag>
| related

Equivalent to `to<map_tag>`; provided for convenience.

template<typename implementation_defined >

constexpr auto keys
| related

Initial value:
= [](auto&& map) {
return implementation_defined;
}

Returns a `Sequence` of the keys of the map, in unspecified order.

## Example

// Copyright Louis Dionne 2013-2016
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
#include <boost/hana/assert.hpp>
#include <boost/hana/contains.hpp>
#include <boost/hana/integral_constant.hpp>
#include <boost/hana/keys.hpp>
#include <boost/hana/map.hpp>
#include <boost/hana/pair.hpp>
#include <boost/hana/permutations.hpp>
#include <boost/hana/tuple.hpp>
#include <boost/hana/type.hpp>
#include <string>
namespace hana = boost::hana;
using namespace std::literals;
int main() {
auto m = hana::make_map(
hana::make_pair(hana::int_c<1>, "foobar"s),
hana::make_pair(hana::type_c<void>, 1234)
);
// The order of the keys is unspecified.
BOOST_HANA_CONSTANT_CHECK(
hana::keys(m) ^hana::in^ hana::permutations(hana::make_tuple(hana::int_c<1>, hana::type_c<void>))
);
}
template<typename implementation_defined >

constexpr auto values
| related

Initial value:
= [](auto&& map) -> decltype(auto) {
return implementation_defined;
}

Returns a `Sequence` of the values of the map, in unspecified order.

## Example

// Copyright Louis Dionne 2013-2016
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
#include <boost/hana/assert.hpp>
#include <boost/hana/contains.hpp>
#include <boost/hana/integral_constant.hpp>
#include <boost/hana/map.hpp>
#include <boost/hana/pair.hpp>
#include <boost/hana/permutations.hpp>
#include <boost/hana/tuple.hpp>
#include <boost/hana/type.hpp>
#include <string>
namespace hana = boost::hana;
using namespace std::literals;
int main() {
auto m = hana::make_map(
hana::make_pair(hana::int_c<1>, "foobar"s),
hana::make_pair(hana::type_c<void>, 1234)
);
// The order of the values is unspecified.
BOOST_HANA_RUNTIME_CHECK(
hana::values(m) ^hana::in^ hana::permutations(hana::make_tuple("foobar"s, 1234))
);
}
template<typename implementation_defined >

constexpr auto insert
| related

Initial value:
= [](auto&& map, auto&& pair) {
return tag-dispatched;
}

Inserts a new key/value pair in a map.

Given a `(key, value)` pair, `insert` inserts this new pair into a map. If the map already contains this key, nothing is done and the map is returned as-is.

Parameters

  map | The map in which to insert a `(key,value)` pair.
  pair | An arbitrary `Product` representing a `(key, value)` pair to insert in the map. The `key` must be compile-time `Comparable`.

## Example

// Copyright Louis Dionne 2013-2016
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
#include <boost/hana/assert.hpp>
#include <boost/hana/insert.hpp>
#include <boost/hana/map.hpp>
#include <boost/hana/pair.hpp>
#include <boost/hana/type.hpp>
#include <string>
namespace hana = boost::hana;
using namespace std::literals;
int main() {
auto m = hana::make_map(
hana::make_pair(hana::type_c<int>, "abcd"s),
hana::make_pair(hana::type_c<void>, 1234)
);
BOOST_HANA_RUNTIME_CHECK(
hana::insert(m, hana::make_pair(hana::type_c<float>, 'x')) ==
hana::make_map(
hana::make_pair(hana::type_c<int>, "abcd"s),
hana::make_pair(hana::type_c<void>, 1234),
hana::make_pair(hana::type_c<float>, 'x')
)
);
BOOST_HANA_RUNTIME_CHECK(hana::insert(m, hana::make_pair(hana::type_c<void>, 'x')) == m);
}

## Benchmarks

template<typename implementation_defined >

constexpr auto erase_key
| related

Initial value:
= [](auto&& map, auto&& key) {
return tag-dispatched;
}

Removes a key/value pair from a map.

Returns a new `hana::map` containing all the elements of the original, except for the `(key, value)` pair whose `key` compares `equal` to the given key. If the map does not contain such an element, a new map equal to the original is returned.

Parameters

  map | The map in which to erase a `key`.
  key | A key to remove from the map. It must be compile-time `Comparable`.

## Example

// Copyright Louis Dionne 2013-2016
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
#include <boost/hana/assert.hpp>
#include <boost/hana/erase_key.hpp>
#include <boost/hana/map.hpp>
#include <boost/hana/pair.hpp>
#include <boost/hana/string.hpp>
#include <boost/hana/type.hpp>
#include <string>
namespace hana = boost::hana;
using namespace std::literals;
int main() {
auto m = hana::make_map(
hana::make_pair(hana::type_c<int>, "abcd"s),
hana::make_pair(hana::type_c<void>, 1234),
hana::make_pair(BOOST_HANA_STRING("foobar!"), hana::type_c<char>)
);
BOOST_HANA_RUNTIME_CHECK(
hana::erase_key(m, BOOST_HANA_STRING("foobar!")) ==
hana::make_map(
hana::make_pair(hana::type_c<int>, "abcd"s),
hana::make_pair(hana::type_c<void>, 1234)
)
);
BOOST_HANA_RUNTIME_CHECK(hana::erase_key(m, hana::type_c<char>) == m);
}