ceph/src/boost/libs/hana/include/boost/hana/fwd/map.hpp

   1 /*!
   2 @file
   3 Forward declares `boost::hana::map`.
   4
   5 @copyright Louis Dionne 2013-2016
   6 Distributed under the Boost Software License, Version 1.0.
   7 (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
   8  */
   9
  10 #ifndef BOOST_HANA_FWD_MAP_HPP
  11 #define BOOST_HANA_FWD_MAP_HPP
  12
  13 #include <boost/hana/config.hpp>
  14 #include <boost/hana/fwd/core/to.hpp>
  15 #include <boost/hana/fwd/core/make.hpp>
  16 #include <boost/hana/fwd/erase_key.hpp>
  17 #include <boost/hana/fwd/insert.hpp>
  18 #include <boost/hana/fwd/keys.hpp>
  19
  20
  21 BOOST_HANA_NAMESPACE_BEGIN
  22     //! @ingroup group-datatypes
  23     //! Basic associative container requiring unique, `Comparable` and
  24     //! `Hashable` keys.
  25     //!
  26     //! The order of the elements of the map is unspecified. Also, all the
  27     //! keys must be `Hashable`, and any two keys with equal hashes must be
  28     //! `Comparable` with each other at compile-time.
  29     //!
  30     //! @note
  31     //! The actual representation of a `hana::map` is implementation-defined.
  32     //! In particular, one should not take for granted the order of the
  33     //! template parameters and the presence of any additional constructors
  34     //! or assignment operators than what is documented. The canonical way of
  35     //! creating a `hana::map` is through `hana::make_map`.
  36     //!
  37     //!
  38     //! Modeled concepts
  39     //! ----------------
  40     //! 1. `Comparable`\n
  41     //! Two maps are equal iff all their keys are equal and are associated
  42     //! to equal values.
  43     //! @include example/map/comparable.cpp
  44     //!
  45     //! 2. `Searchable`\n
  46     //! A map can be searched by its keys with a predicate yielding a
  47     //! compile-time `Logical`. Also note that `operator[]` can be used
  48     //! instead of `at_key`.
  49     //! @include example/map/searchable.cpp
  50     //!
  51     //! 3. `Foldable`\n
  52     //! Folding a map is equivalent to folding a list of the key/value pairs
  53     //! it contains. In particular, since that list is not guaranteed to be
  54     //! in any specific order, folding a map with an operation that is not
  55     //! both commutative and associative will yield non-deterministic behavior.
  56     //! @include example/map/foldable.cpp
  57     //!
  58     //!
  59     //! Conversion from any `Foldable`
  60     //! ------------------------------
  61     //! Any `Foldable` of `Product`s can be converted to a `hana::map` with
  62     //! `hana::to<hana::map_tag>` or, equivalently, `hana::to_map`. If the
  63     //! `Foldable` contains duplicate keys, only the value associated to the
  64     //! first occurence of each key is kept.
  65     //! @include example/map/to.cpp
  66 #ifdef BOOST_HANA_DOXYGEN_INVOKED
  67     template <typename implementation_defined>
  68     struct map {
  69         //! Default-construct a map. This constructor only exists when all the
  70         //! elements of the map are default-constructible.
  71         constexpr map() = default;
  72
  73         //! Copy-construct a map from another map. This constructor only
  74         //! exists when all the elements of the map are copy-constructible.
  75         constexpr map(map const& other) = default;
  76
  77         //! Move-construct a map from another map. This constructor only
  78         //! exists when all the elements of the map are move-constructible.
  79         constexpr map(map&& other) = default;
  80
  81         //! Equivalent to `hana::equal`
  82         template <typename X, typename Y>
  83         friend constexpr auto operator==(X&& x, Y&& y);
  84
  85         //! Equivalent to `hana::not_equal`
  86         template <typename X, typename Y>
  87         friend constexpr auto operator!=(X&& x, Y&& y);
  88
  89         //! Equivalent to `hana::at_key`
  90         template <typename Key>
  91         constexpr decltype(auto) operator[](Key&& key);
  92     };
  93 #else
  94     template <typename HashTable, typename Storage>
  95     struct map;
  96 #endif
  97
  98     //! Tag representing `hana::map`s.
  99     //! @relates hana::map
 100     struct map_tag { };
 101
 102     //! Function object for creating a `hana::map`.
 103     //! @relates hana::map
 104     //!
 105     //! Given zero or more `Product`s representing key/value associations,
 106     //! `make<map_tag>` returns a `hana::map` associating these keys to these
 107     //! values.
 108     //!
 109     //! `make<map_tag>` requires all the keys to be unique and to have
 110     //! different hashes. If you need to create a map with duplicate keys
 111     //! or with keys whose hashes might collide, use `hana::to_map` or
 112     //! insert `(key, value)` pairs to an empty map successively. However,
 113     //! be aware that doing so will be much more compile-time intensive than
 114     //! using `make<map_tag>`, because the uniqueness of keys will have to be
 115     //! enforced.
 116     //!
 117     //!
 118     //! Example
 119     //! -------
 120     //! @include example/map/make.cpp
 121 #ifdef BOOST_HANA_DOXYGEN_INVOKED
 122     template <>
 123     constexpr auto make<map_tag> = [](auto&& ...pairs) {
 124         return map<implementation_defined>{forwarded(pairs)...};
 125     };
 126 #endif
 127
 128     //! Alias to `make<map_tag>`; provided for convenience.
 129     //! @relates hana::map
 130     //!
 131     //!
 132     //! Example
 133     //! -------
 134     //! @include example/map/make.cpp
 135     constexpr auto make_map = make<map_tag>;
 136
 137     //! Equivalent to `to<map_tag>`; provided for convenience.
 138     //! @relates hana::map
 139     constexpr auto to_map = to<map_tag>;
 140
 141     //! Returns a `Sequence` of the keys of the map, in unspecified order.
 142     //! @relates hana::map
 143     //!
 144     //!
 145     //! Example
 146     //! -------
 147     //! @include example/map/keys.cpp
 148 #ifdef BOOST_HANA_DOXYGEN_INVOKED
 149     constexpr auto keys = [](auto&& map) {
 150         return implementation_defined;
 151     };
 152 #endif
 153
 154     //! Returns a `Sequence` of the values of the map, in unspecified order.
 155     //! @relates hana::map
 156     //!
 157     //!
 158     //! Example
 159     //! -------
 160     //! @include example/map/values.cpp
 161 #ifdef BOOST_HANA_DOXYGEN_INVOKED
 162     constexpr auto values = [](auto&& map) -> decltype(auto) {
 163         return implementation_defined;
 164     };
 165 #else
 166     struct values_t {
 167         template <typename Map>
 168         constexpr decltype(auto) operator()(Map&& map) const;
 169     };
 170
 171     constexpr values_t values{};
 172 #endif
 173
 174     //! Inserts a new key/value pair in a map.
 175     //! @relates hana::map
 176     //!
 177     //! Given a `(key, value)` pair, `insert` inserts this new pair into a
 178     //! map. If the map already contains this key, nothing is done and the
 179     //! map is returned as-is.
 180     //!
 181     //!
 182     //! @param map
 183     //! The map in which to insert a `(key,value)` pair.
 184     //!
 185     //! @param pair
 186     //! An arbitrary `Product` representing a `(key, value)` pair to insert
 187     //! in the map. The `key` must be compile-time `Comparable`.
 188     //!
 189     //!
 190     //! Example
 191     //! -------
 192     //! @include example/map/insert.cpp
 193 #ifdef BOOST_HANA_DOXYGEN_INVOKED
 194     constexpr auto insert = [](auto&& map, auto&& pair) {
 195         return tag-dispatched;
 196     };
 197 #endif
 198
 199     //! Removes a key/value pair from a map.
 200     //! @relates hana::map
 201     //!
 202     //! Returns a new `hana::map` containing all the elements of the original,
 203     //! except for the `(key, value)` pair whose `key` compares `equal`
 204     //! to the given key. If the map does not contain such an element,
 205     //! a new map equal to the original is returned.
 206     //!
 207     //!
 208     //! @param map
 209     //! The map in which to erase a `key`.
 210     //!
 211     //! @param key
 212     //! A key to remove from the map. It must be compile-time `Comparable`.
 213     //!
 214     //!
 215     //! Example
 216     //! -------
 217     //! @include example/map/erase_key.cpp
 218 #ifdef BOOST_HANA_DOXYGEN_INVOKED
 219     constexpr auto erase_key = [](auto&& map, auto&& key) {
 220         return tag-dispatched;
 221     };
 222 #endif
 223 BOOST_HANA_NAMESPACE_END
 224
 225 #endif // !BOOST_HANA_FWD_MAP_HPP