// ------------------------------------------------------------------------ // // SPDX-License-Identifier: LGPL-2.1-or-later // Copyright (C) 2019 - 2023 by the deal.II authors // // This file is part of the deal.II library. // // Part of the source code is dual licensed under Apache-2.0 WITH // LLVM-exception OR LGPL-2.1-or-later. Detailed license information // governing the source code and code contributions can be found in // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II. // // ------------------------------------------------------------------------ #ifndef dealii_base_mutable_bind_h #define dealii_base_mutable_bind_h #include #include #include #include DEAL_II_NAMESPACE_OPEN namespace Utilities { /** * A mutable version of std::bind, that binds all arguments of a function * pointer to a stored tuple, and allows you to update the tuple between * calls. * * An example usage of this class is through the helper function * mutable_bind() that creates a MutableBind object on the fly, based on its * arguments: * * @code * void my_function(const int &a, const double &b); * * auto bound = mutable_bind(my_function, 1, 2.0); * * bound(); // will execute my_function(1, 2.0); * * bound.set_arguments(2, 3.0); * bound(); // will execute my_function(2, 3.0); * * bound.parse_arguments("3: 4.0"); * bound(); // will execute my_function(3, 4.0); * @endcode * * The arguments are copied to the tuple, with their reference and const * attributes removed. Only copy constructible objects are allowed as * function arguments. If you need to keep some references around, you may * wrap your function into a lambda function: * * @code * void * example_function(const Point<2> &p, * const double &d, * const unsigned int i = 3) { * ... * }; * * const Point<2> p(1, 2); * * Utilities::MutableBind exp = { * [&p](const double &d, * const unsigned int i) * { * example_function(p, d, i); * }, * {}}; * * exp.parse_arguments("3.0 : 4"); * exp(); // calls example_function(p, 3.0, 4); * @endcode */ template class MutableBind { public: /** * An alias to the stored std::tuple type. Only copy constructible * objects are allowed as tuple members. */ using TupleType = std::tuple>...>; /** * Construct a MutableBind object specifying the function, and * each arguments separately. */ template MutableBind(FunctionType function, FunctionArgs &&...arguments); /** * Construct a MutableBind object specifying the function, and * the arguments as a tuple. */ template MutableBind(FunctionType function, TupleType &&arguments); /** * Construct a MutableBind object specifying only the function. By default, * the arguments are left to their default constructor values. */ template MutableBind(FunctionType function); /** * Call the original function, passing as arguments the elements of the * tuple of bound arguments. */ ReturnType operator()() const; /** * Set the arguments to use in @p function, for next time * operator()() is called, using move semantic. */ void set_arguments(TupleType &&arguments); /** * Set the arguments to use in @p function, for next time * operator()() is called, using move semantic. */ void set_arguments(FunctionArgs &&...arguments); /** * Parse the arguments to use in @p function from a string, for next time * operator()() is called. * * The conversion is performed using a user supplied Patterns::PatternBase * object. By default, Patterns::Tools::Convert::to_pattern() is * used to determine how to convert from @p value_string to a TupleType * object. * * @param value_string The string to convert from * @param pattern A unique pointer to the pattern to use when performing * the conversion */ void parse_arguments(const std::string &value_string, const Patterns::PatternBase &pattern = *Patterns::Tools::Convert::to_pattern()); private: /** * An std::function that stores the original function. */ const std::function function; /** * Currently stored arguments. These are forwarded to the function object * above, when calling operator()(). */ TupleType arguments; }; /** * Create a MutableBind object from a function pointer and a list of * arguments. * * An example usage is given by: * @code * void my_function(const int &a, const double &b); * * auto bound = mutable_bind(my_function, 1, 2.0); * * bound(); // will execute my_function(1, 2.0); * * bound.set_arguments(2, 3.0); * bound(); // will execute my_function(2, 3.0); * * bound.parse_arguments("3: 4.0"); * bound(); // will execute my_function(3, 4.0); * @endcode */ template MutableBind mutable_bind(ReturnType (*function)(FunctionArgs...), std_cxx20::type_identity_t &&...arguments); /** * Same as above, using a std::function object. */ template MutableBind mutable_bind(std::function, std_cxx20::type_identity_t &&...arguments); /** * Create a MutableBind object from a function pointer, with uninitialized * arguments. * * Notice that if you do not call one of the MutableBind::set_arguments() * methods, or the MutableBind::parse_arguments() function on the returned * object, then the arguments passed to the function object will be * initialized with the values coming from each of the arguments' default * constructors. */ template MutableBind mutable_bind(ReturnType (*function)(FunctionArgs...)); /** * Same as above, using a std::function object. */ template MutableBind mutable_bind(std::function); #ifndef DOXYGEN template template MutableBind::MutableBind( FunctionType function, FunctionArgs &&...arguments) : function(function) , arguments(std::make_tuple(std::move(arguments)...)) {} template template MutableBind::MutableBind(FunctionType function, TupleType &&arguments) : function(function) , arguments(std::move(arguments)) {} template template MutableBind::MutableBind(FunctionType function) : function(function) {} template ReturnType MutableBind::operator()() const { return std::apply(function, arguments); } template void MutableBind::set_arguments( FunctionArgs &&...args) { arguments = std::make_tuple(std::move(args)...); } template void MutableBind::set_arguments(TupleType &&args) { arguments = std::move(args); } template void MutableBind::parse_arguments( const std::string &value_string, const Patterns::PatternBase &pattern) { arguments = Patterns::Tools::Convert::to_value(value_string, pattern); } template MutableBind mutable_bind(ReturnType (*function)(FunctionArgs...), std_cxx20::type_identity_t &&...arguments) { return MutableBind(function, std::move(arguments)...); } template MutableBind mutable_bind(ReturnType (*function)(FunctionArgs...)) { return MutableBind(function); } template MutableBind mutable_bind(std::function function, std_cxx20::type_identity_t &&...arguments) { return MutableBind(function, std::move(arguments)...); } template MutableBind mutable_bind(std::function function) { return MutableBind(function); } #endif } // namespace Utilities DEAL_II_NAMESPACE_CLOSE #endif