1 // Copyright 2018 The Abseil Authors. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 // 15 // ----------------------------------------------------------------------------- 16 // File: bind_front.h 17 // ----------------------------------------------------------------------------- 18 // 19 // `absl::bind_front()` returns a functor by binding a number of arguments to 20 // the front of a provided (usually more generic) functor. Unlike `std::bind`, 21 // it does not require the use of argument placeholders. The simpler syntax of 22 // `absl::bind_front()` allows you to avoid known misuses with `std::bind()`. 23 // 24 // `absl::bind_front()` is meant as a drop-in replacement for C++20's upcoming 25 // `std::bind_front()`, which similarly resolves these issues with 26 // `std::bind()`. Both `bind_front()` alternatives, unlike `std::bind()`, allow 27 // partial function application. (See 28 // https://en.wikipedia.org/wiki/Partial_application). 29 30 #ifndef ABSL_FUNCTIONAL_BIND_FRONT_H_ 31 #define ABSL_FUNCTIONAL_BIND_FRONT_H_ 32 33 #if defined(__cpp_lib_bind_front) && __cpp_lib_bind_front >= 201907L 34 #include <functional> // For std::bind_front. 35 #endif // defined(__cpp_lib_bind_front) && __cpp_lib_bind_front >= 201907L 36 37 #include "absl/functional/internal/front_binder.h" 38 #include "absl/utility/utility.h" 39 40 namespace absl { 41 ABSL_NAMESPACE_BEGIN 42 43 // bind_front() 44 // 45 // Binds the first N arguments of an invocable object and stores them by value. 46 // 47 // Like `std::bind()`, `absl::bind_front()` is implicitly convertible to 48 // `std::function`. In particular, it may be used as a simpler replacement for 49 // `std::bind()` in most cases, as it does not require placeholders to be 50 // specified. More importantly, it provides more reliable correctness guarantees 51 // than `std::bind()`; while `std::bind()` will silently ignore passing more 52 // parameters than expected, for example, `absl::bind_front()` will report such 53 // mis-uses as errors. In C++20, `absl::bind_front` is replaced by 54 // `std::bind_front`. 55 // 56 // absl::bind_front(a...) can be seen as storing the results of 57 // std::make_tuple(a...). 58 // 59 // Example: Binding a free function. 60 // 61 // int Minus(int a, int b) { return a - b; } 62 // 63 // assert(absl::bind_front(Minus)(3, 2) == 3 - 2); 64 // assert(absl::bind_front(Minus, 3)(2) == 3 - 2); 65 // assert(absl::bind_front(Minus, 3, 2)() == 3 - 2); 66 // 67 // Example: Binding a member function. 68 // 69 // struct Math { 70 // int Double(int a) const { return 2 * a; } 71 // }; 72 // 73 // Math math; 74 // 75 // assert(absl::bind_front(&Math::Double)(&math, 3) == 2 * 3); 76 // // Stores a pointer to math inside the functor. 77 // assert(absl::bind_front(&Math::Double, &math)(3) == 2 * 3); 78 // // Stores a copy of math inside the functor. 79 // assert(absl::bind_front(&Math::Double, math)(3) == 2 * 3); 80 // // Stores std::unique_ptr<Math> inside the functor. 81 // assert(absl::bind_front(&Math::Double, 82 // std::unique_ptr<Math>(new Math))(3) == 2 * 3); 83 // 84 // Example: Using `absl::bind_front()`, instead of `std::bind()`, with 85 // `std::function`. 86 // 87 // class FileReader { 88 // public: 89 // void ReadFileAsync(const std::string& filename, std::string* content, 90 // const std::function<void()>& done) { 91 // // Calls Executor::Schedule(std::function<void()>). 92 // Executor::DefaultExecutor()->Schedule( 93 // absl::bind_front(&FileReader::BlockingRead, this, 94 // filename, content, done)); 95 // } 96 // 97 // private: 98 // void BlockingRead(const std::string& filename, std::string* content, 99 // const std::function<void()>& done) { 100 // CHECK_OK(file::GetContents(filename, content, {})); 101 // done(); 102 // } 103 // }; 104 // 105 // `absl::bind_front()` stores bound arguments explicitly using the type passed 106 // rather than implicitly based on the type accepted by its functor. 107 // 108 // Example: Binding arguments explicitly. 109 // 110 // void LogStringView(absl::string_view sv) { 111 // LOG(INFO) << sv; 112 // } 113 // 114 // Executor* e = Executor::DefaultExecutor(); 115 // std::string s = "hello"; 116 // absl::string_view sv = s; 117 // 118 // // absl::bind_front(LogStringView, arg) makes a copy of arg and stores it. 119 // e->Schedule(absl::bind_front(LogStringView, sv)); // ERROR: dangling 120 // // string_view. 121 // 122 // e->Schedule(absl::bind_front(LogStringView, s)); // OK: stores a copy of 123 // // s. 124 // 125 // To store some of the arguments passed to `absl::bind_front()` by reference, 126 // use std::ref()` and `std::cref()`. 127 // 128 // Example: Storing some of the bound arguments by reference. 129 // 130 // class Service { 131 // public: 132 // void Serve(const Request& req, std::function<void()>* done) { 133 // // The request protocol buffer won't be deleted until done is called. 134 // // It's safe to store a reference to it inside the functor. 135 // Executor::DefaultExecutor()->Schedule( 136 // absl::bind_front(&Service::BlockingServe, this, std::cref(req), 137 // done)); 138 // } 139 // 140 // private: 141 // void BlockingServe(const Request& req, std::function<void()>* done); 142 // }; 143 // 144 // Example: Storing bound arguments by reference. 145 // 146 // void Print(const std::string& a, const std::string& b) { 147 // std::cerr << a << b; 148 // } 149 // 150 // std::string hi = "Hello, "; 151 // std::vector<std::string> names = {"Chuk", "Gek"}; 152 // // Doesn't copy hi. 153 // for_each(names.begin(), names.end(), 154 // absl::bind_front(Print, std::ref(hi))); 155 // 156 // // DO NOT DO THIS: the functor may outlive "hi", resulting in 157 // // dangling references. 158 // foo->DoInFuture(absl::bind_front(Print, std::ref(hi), "Guest")); // BAD! 159 // auto f = absl::bind_front(Print, std::ref(hi), "Guest"); // BAD! 160 // 161 // Example: Storing reference-like types. 162 // 163 // void Print(absl::string_view a, const std::string& b) { 164 // std::cerr << a << b; 165 // } 166 // 167 // std::string hi = "Hello, "; 168 // // Copies "hi". 169 // absl::bind_front(Print, hi)("Chuk"); 170 // 171 // // Compile error: std::reference_wrapper<const string> is not implicitly 172 // // convertible to string_view. 173 // // absl::bind_front(Print, std::cref(hi))("Chuk"); 174 // 175 // // Doesn't copy "hi". 176 // absl::bind_front(Print, absl::string_view(hi))("Chuk"); 177 // 178 #if defined(__cpp_lib_bind_front) && __cpp_lib_bind_front >= 201907L 179 using std::bind_front; 180 #else // defined(__cpp_lib_bind_front) && __cpp_lib_bind_front >= 201907L 181 template <class F, class... BoundArgs> 182 constexpr functional_internal::bind_front_t<F, BoundArgs...> bind_front( 183 F&& func, BoundArgs&&... args) { 184 return functional_internal::bind_front_t<F, BoundArgs...>( 185 absl::in_place, absl::forward<F>(func), 186 absl::forward<BoundArgs>(args)...); 187 } 188 #endif // defined(__cpp_lib_bind_front) && __cpp_lib_bind_front >= 201907L 189 190 ABSL_NAMESPACE_END 191 } // namespace absl 192 193 #endif // ABSL_FUNCTIONAL_BIND_FRONT_H_ 194