]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | /*! |
2 | @file | |
3 | Forward declares `boost::hana::set`. | |
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_SET_HPP | |
11 | #define BOOST_HANA_FWD_SET_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 | ||
18 | ||
19 | BOOST_HANA_NAMESPACE_BEGIN | |
20 | //! @ingroup group-datatypes | |
21 | //! Basic unordered container requiring unique, `Comparable` and | |
22 | //! `Hashable` keys. | |
23 | //! | |
24 | //! A set is an unordered container that can hold heterogeneous keys. | |
25 | //! A set requires (and ensures) that no duplicates are present when | |
26 | //! inserting new keys. | |
27 | //! | |
28 | //! @note | |
29 | //! The actual representation of a `hana::set` is implementation-defined. | |
30 | //! In particular, one should not take for granted the order of the | |
31 | //! template parameters and the presence of any additional constructors | |
32 | //! or assignment operators than what is documented. The canonical way of | |
33 | //! creating a `hana::set` is through `hana::make_set`. | |
34 | //! | |
35 | //! | |
36 | //! Modeled concepts | |
37 | //! ---------------- | |
38 | //! 1. `Comparable`\n | |
39 | //! Two sets are equal iff they contain the same elements, regardless of | |
40 | //! the order. | |
41 | //! @include example/set/comparable.cpp | |
42 | //! | |
43 | //! 2. Foldable\n | |
44 | //! Folding a set is equivalent to folding the sequence of its values. | |
45 | //! However, note that the values are not required to be in any specific | |
46 | //! order, so using the folds provided here with an operation that is not | |
47 | //! both commutative and associative will yield non-deterministic behavior. | |
48 | //! @include example/set/foldable.cpp | |
49 | //! | |
50 | //! 3. Searchable\n | |
51 | //! The elements in a set act as both its keys and its values. Since the | |
52 | //! elements of a set are unique, searching for an element will return | |
53 | //! either the only element which is equal to the searched value, or | |
54 | //! `nothing`. Also note that `operator[]` can be used instead of the | |
55 | //! `at_key` function. | |
56 | //! @include example/set/searchable.cpp | |
57 | //! | |
58 | //! | |
59 | //! Conversion from any `Foldable` | |
60 | //! ------------------------------ | |
61 | //! Any `Foldable` structure can be converted into a `hana::set` with | |
62 | //! `to<set_tag>`. The elements of the structure must all be compile-time | |
63 | //! `Comparable`. If the structure contains duplicate elements, only | |
64 | //! the first occurence will appear in the resulting set. More | |
65 | //! specifically, conversion from a `Foldable` is equivalent to | |
66 | //! @code | |
67 | //! to<set_tag>(xs) == fold_left(xs, make_set(), insert) | |
68 | //! @endcode | |
69 | //! | |
70 | //! __Example__ | |
71 | //! @include example/set/to.cpp | |
72 | #ifdef BOOST_HANA_DOXYGEN_INVOKED | |
73 | template <typename implementation_defined> | |
74 | struct set { | |
75 | //! Copy-construct a set from another set. This constructor only | |
76 | //! exists when all the elements of the set are copy-constructible. | |
77 | constexpr set(set const& other) = default; | |
78 | ||
79 | //! Move-construct a set from another set. This constructor only | |
80 | //! exists when all the elements of the set are move-constructible. | |
81 | constexpr set(set&& other) = default; | |
82 | ||
83 | //! Equivalent to `hana::equal` | |
84 | template <typename X, typename Y> | |
85 | friend constexpr auto operator==(X&& x, Y&& y); | |
86 | ||
87 | //! Equivalent to `hana::not_equal` | |
88 | template <typename X, typename Y> | |
89 | friend constexpr auto operator!=(X&& x, Y&& y); | |
90 | ||
91 | //! Equivalent to `hana::at_key` | |
92 | template <typename Key> | |
93 | constexpr decltype(auto) operator[](Key&& key); | |
94 | }; | |
95 | #else | |
96 | template <typename ...Xs> | |
97 | struct set; | |
98 | #endif | |
99 | ||
100 | //! Tag representing the `hana::set` container. | |
101 | //! @relates hana::set | |
102 | struct set_tag { }; | |
103 | ||
104 | //! Function object for creating a `hana::set`. | |
105 | //! @relates hana::set | |
106 | //! | |
107 | //! Given zero or more values `xs...`, `make<set_tag>` returns a `set` | |
108 | //! containing those values. The values must all be compile-time | |
109 | //! `Comparable`, and no duplicate values may be provided. To create | |
110 | //! a `set` from a sequence with possible duplicates, use `to<set_tag>` | |
111 | //! instead. | |
112 | //! | |
113 | //! | |
114 | //! Example | |
115 | //! ------- | |
116 | //! @include example/set/make.cpp | |
117 | #ifdef BOOST_HANA_DOXYGEN_INVOKED | |
118 | template <> | |
119 | constexpr auto make<set_tag> = [](auto&& ...xs) { | |
120 | return set<implementation_defined>{forwarded(xs)...}; | |
121 | }; | |
122 | #endif | |
123 | ||
124 | //! Equivalent to `make<set_tag>`; provided for convenience. | |
125 | //! @relates hana::set | |
126 | //! | |
127 | //! | |
128 | //! Example | |
129 | //! ------- | |
130 | //! @include example/set/make.cpp | |
131 | constexpr auto make_set = make<set_tag>; | |
132 | ||
133 | //! Insert an element in a `hana::set`. | |
134 | //! @relates hana::set | |
135 | //! | |
136 | //! If the set already contains an element that compares equal, then | |
137 | //! nothing is done and the set is returned as is. | |
138 | //! | |
139 | //! | |
140 | //! @param set | |
141 | //! The set in which to insert a value. | |
142 | //! | |
143 | //! @param element | |
144 | //! The value to insert. It must be compile-time `Comparable`. | |
145 | //! | |
146 | //! | |
147 | //! Example | |
148 | //! ------- | |
149 | //! @include example/set/insert.cpp | |
150 | #ifdef BOOST_HANA_DOXYGEN_INVOKED | |
151 | constexpr auto insert = [](auto&& set, auto&& element) { | |
152 | return tag-dispatched; | |
153 | }; | |
154 | #endif | |
155 | ||
156 | //! Remove an element from a `hana::set`. | |
157 | //! @relates hana::set | |
158 | //! | |
159 | //! Returns a new set containing all the elements of the original, | |
160 | //! except the one comparing `equal` to the given element. If the set | |
161 | //! does not contain such an element, a new set equal to the original | |
162 | //! set is returned. | |
163 | //! | |
164 | //! | |
165 | //! @param set | |
166 | //! The set in which to remove a value. | |
167 | //! | |
168 | //! @param element | |
169 | //! The value to remove. It must be compile-time `Comparable`. | |
170 | //! | |
171 | //! | |
172 | //! Example | |
173 | //! ------- | |
174 | //! @include example/set/erase_key.cpp | |
175 | #ifdef BOOST_HANA_DOXYGEN_INVOKED | |
176 | constexpr auto erase_key = [](auto&& set, auto&& element) { | |
177 | return tag-dispatched; | |
178 | }; | |
179 | #endif | |
180 | ||
181 | //! Equivalent to `to<set_tag>`; provided for convenience. | |
182 | //! @relates hana::set | |
183 | constexpr auto to_set = to<set_tag>; | |
184 | BOOST_HANA_NAMESPACE_END | |
185 | ||
186 | #endif // !BOOST_HANA_FWD_SET_HPP |