Debian Codegraph @

include/deal.II/base/mutable_bind.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2019 - 2023 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_base_mutable_bind_h
16 #define dealii_base_mutable_bind_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/patterns.h>
21
22 #include <tuple>
23 #include <utility>
24
25 DEAL_II_NAMESPACE_OPEN
26
27 namespace Utilities
28 {
29 /**
30 * A mutable version of std::bind, that binds all arguments of a function
31 * pointer to a stored tuple, and allows you to update the tuple between
32 * calls.
33 *
34 * An example usage of this class is through the helper function
35 * mutable_bind() that creates a MutableBind object on the fly, based on its
36 * arguments:
37 *
38 * @code
39 * void my_function(const int &a, const double &b);
40 *
41 * auto bound = mutable_bind(my_function, 1, 2.0);
42 *
43 * bound(); // will execute my_function(1, 2.0);
44 *
45 * bound.set_arguments(2, 3.0);
46 * bound(); // will execute my_function(2, 3.0);
47 *
48 * bound.parse_arguments("3: 4.0");
49 * bound(); // will execute my_function(3, 4.0);
50 * @endcode
51 *
52 * The arguments are copied to the tuple, with their reference and const
53 * attributes removed. Only copy constructible objects are allowed as
54 * function arguments. If you need to keep some references around, you may
55 * wrap your function into a lambda function:
56 *
57 * @code
58 * void
59 * example_function(const Point<2> &p,
60 * const double &d,
61 * const unsigned int i = 3) {
62 * ...
63 * };
64 *
65 * const Point<2> p(1, 2);
66 *
67 * Utilities::MutableBind<void, double, unsigned int> exp = {
68 * [&p](const double &d,
69 * const unsigned int i)
70 * {
71 * example_function(p, d, i);
72 * },
73 * {}};
74 *
75 * exp.parse_arguments("3.0 : 4");
76 * exp(); // calls example_function(p, 3.0, 4);
77 * @endcode
78 */
79 template <typename ReturnType, class... FunctionArgs>
80 class MutableBind
81 {
82 public:
83 /**
84 * An alias to the stored std::tuple type. Only copy constructible
85 * objects are allowed as tuple members.
86 */
87 using TupleType =
88 std::tuple<std::remove_cv_t<std::remove_reference_t<FunctionArgs>>...>;
89
90 /**
91 * Construct a MutableBind object specifying the function, and
92 * each arguments separately.
93 */
94 template <typename FunctionType>
95 MutableBind(FunctionType function, FunctionArgs &&...arguments);
96
97 /**
98 * Construct a MutableBind object specifying the function, and
99 * the arguments as a tuple.
100 */
101 template <typename FunctionType>
102 MutableBind(FunctionType function, TupleType &&arguments);
103
104 /**
105 * Construct a MutableBind object specifying only the function. By default,
106 * the arguments are left to their default constructor values.
107 */
108 template <typename FunctionType>
109 MutableBind(FunctionType function);
110
111 /**
112 * Call the original function, passing as arguments the elements of the
113 * tuple of bound arguments.
114 */
115 ReturnType
116 operator()() const;
117
118 /**
119 * Set the arguments to use in @p function, for next time
120 * operator()() is called, using move semantic.
121 */
122 void
123 set_arguments(TupleType &&arguments);
124
125 /**
126 * Set the arguments to use in @p function, for next time
127 * operator()() is called, using move semantic.
128 */
129 void
130 set_arguments(FunctionArgs &&...arguments);
131
132 /**
133 * Parse the arguments to use in @p function from a string, for next time
134 * operator()() is called.
135 *
136 * The conversion is performed using a user supplied Patterns::PatternBase
137 * object. By default, Patterns::Tools::Convert<TupleType>::to_pattern() is
138 * used to determine how to convert from @p value_string to a TupleType
139 * object.
140 *
141 * @param value_string The string to convert from
142 * @param pattern A unique pointer to the pattern to use when performing
143 * the conversion
144 */
145 void
146 parse_arguments(const std::string &value_string,
147 const Patterns::PatternBase &pattern =
148 *Patterns::Tools::Convert<TupleType>::to_pattern());
149
150 private:
151 /**
152 * An std::function that stores the original function.
153 */
154 const std::function<ReturnType(FunctionArgs...)> function;
155
156 /**
157 * Currently stored arguments. These are forwarded to the function object
158 * above, when calling operator()().
159 */
160 TupleType arguments;
161 };
162
163
164
165 /**
166 * Create a MutableBind object from a function pointer and a list of
167 * arguments.
168 *
169 * An example usage is given by:
170 * @code
171 * void my_function(const int &a, const double &b);
172 *
173 * auto bound = mutable_bind(my_function, 1, 2.0);
174 *
175 * bound(); // will execute my_function(1, 2.0);
176 *
177 * bound.set_arguments(2, 3.0);
178 * bound(); // will execute my_function(2, 3.0);
179 *
180 * bound.parse_arguments("3: 4.0");
181 * bound(); // will execute my_function(3, 4.0);
182 * @endcode
183 */
184 template <typename ReturnType, class... FunctionArgs>
185 MutableBind<ReturnType, FunctionArgs...>
186 mutable_bind(ReturnType (*function)(FunctionArgs...),
187 std_cxx20::type_identity_t<FunctionArgs> &&...arguments);
188
189 /**
190 * Same as above, using a std::function object.
191 */
192 template <typename ReturnType, class... FunctionArgs>
193 MutableBind<ReturnType, FunctionArgs...>
194 mutable_bind(std::function<ReturnType(FunctionArgs...)>,
195 std_cxx20::type_identity_t<FunctionArgs> &&...arguments);
196
197 /**
198 * Create a MutableBind object from a function pointer, with uninitialized
199 * arguments.
200 *
201 * Notice that if you do not call one of the MutableBind::set_arguments()
202 * methods, or the MutableBind::parse_arguments() function on the returned
203 * object, then the arguments passed to the function object will be
204 * initialized with the values coming from each of the arguments' default
205 * constructors.
206 */
207 template <typename ReturnType, class... FunctionArgs>
208 MutableBind<ReturnType, FunctionArgs...>
209 mutable_bind(ReturnType (*function)(FunctionArgs...));
210
211 /**
212 * Same as above, using a std::function object.
213 */
214 template <typename ReturnType, class... FunctionArgs>
215 MutableBind<ReturnType, FunctionArgs...>
216 mutable_bind(std::function<ReturnType(FunctionArgs...)>);
217
218
219
220 #ifndef DOXYGEN
221 template <typename ReturnType, class... FunctionArgs>
222 template <typename FunctionType>
223 MutableBind<ReturnType, FunctionArgs...>::MutableBind(
224 FunctionType function,
225 FunctionArgs &&...arguments)
226 : function(function)
227 , arguments(std::make_tuple(std::move(arguments)...))
228 {}
229
230
231
232 template <typename ReturnType, class... FunctionArgs>
233 template <typename FunctionType>
234 MutableBind<ReturnType, FunctionArgs...>::MutableBind(FunctionType function,
235 TupleType &&arguments)
236 : function(function)
237 , arguments(std::move(arguments))
238 {}
239
240
241
242 template <typename ReturnType, class... FunctionArgs>
243 template <typename FunctionType>
244 MutableBind<ReturnType, FunctionArgs...>::MutableBind(FunctionType function)
245 : function(function)
246 {}
247
248
249
250 template <typename ReturnType, class... FunctionArgs>
251 ReturnType
252 MutableBind<ReturnType, FunctionArgs...>::operator()() const
253 {
254 return std::apply(function, arguments);
255 }
256
257
258
259 template <typename ReturnType, class... FunctionArgs>
260 void
261 MutableBind<ReturnType, FunctionArgs...>::set_arguments(
262 FunctionArgs &&...args)
263 {
264 arguments = std::make_tuple(std::move(args)...);
265 }
266
267
268
269 template <typename ReturnType, class... FunctionArgs>
270 void
271 MutableBind<ReturnType, FunctionArgs...>::set_arguments(TupleType &&args)
272 {
273 arguments = std::move(args);
274 }
275
276
277
278 template <typename ReturnType, class... FunctionArgs>
279 void
280 MutableBind<ReturnType, FunctionArgs...>::parse_arguments(
281 const std::string &value_string,
282 const Patterns::PatternBase &pattern)
283 {
284 arguments =
285 Patterns::Tools::Convert<TupleType>::to_value(value_string, pattern);
286 }
287
288
289
290 template <typename ReturnType, class... FunctionArgs>
291 MutableBind<ReturnType, FunctionArgs...>
292 mutable_bind(ReturnType (*function)(FunctionArgs...),
293 std_cxx20::type_identity_t<FunctionArgs> &&...arguments)
294 {
295 return MutableBind<ReturnType, FunctionArgs...>(function,
296 std::move(arguments)...);
297 }
298
299
300
301 template <typename ReturnType, class... FunctionArgs>
302 MutableBind<ReturnType, FunctionArgs...>
303 mutable_bind(ReturnType (*function)(FunctionArgs...))
304 {
305 return MutableBind<ReturnType, FunctionArgs...>(function);
306 }
307
308
309
310 template <typename ReturnType, class... FunctionArgs>
311 MutableBind<ReturnType, FunctionArgs...>
312 mutable_bind(std::function<ReturnType(FunctionArgs...)> function,
313 std_cxx20::type_identity_t<FunctionArgs> &&...arguments)
314 {
315 return MutableBind<ReturnType, FunctionArgs...>(function,
316 std::move(arguments)...);
317 }
318
319
320
321 template <typename ReturnType, class... FunctionArgs>
322 MutableBind<ReturnType, FunctionArgs...>
323 mutable_bind(std::function<ReturnType(FunctionArgs...)> function)
324 {
325 return MutableBind<ReturnType, FunctionArgs...>(function);
326 }
327 #endif
328 } // namespace Utilities
329
330 DEAL_II_NAMESPACE_CLOSE
331
332 #endif