1 2 // Copyright (C) 2009-2012 Lorenzo Caminiti 3 // Distributed under the Boost Software License, Version 1.0 4 // (see accompanying file LICENSE_1_0.txt or a copy at 5 // http://www.boost.org/LICENSE_1_0.txt) 6 // Home at http://www.boost.org/libs/local_function 7 8 #ifndef BOOST_LOCAL_FUNCTION_HPP_ 9 #define BOOST_LOCAL_FUNCTION_HPP_ 10 11 #ifndef DOXYGEN 12 13 #include <boost/local_function/aux_/macro/decl.hpp> 14 #include <boost/local_function/aux_/macro/name.hpp> 15 #include <boost/local_function/aux_/macro/typeof.hpp> 16 #include <boost/local_function/aux_/preprocessor/traits/decl.hpp> 17 #include <boost/local_function/detail/preprocessor/line_counter.hpp> 18 #include <boost/local_function/detail/preprocessor/void_list.hpp> 19 #include <boost/config.hpp> 20 21 // PUBLIC // 22 23 #ifdef BOOST_NO_CXX11_VARIADIC_MACROS 24 # define BOOST_LOCAL_FUNCTION_ID(id, declarations) \ 25 BOOST_LOCAL_FUNCTION_AUX_DECL(id, 0 /* not within template */, \ 26 BOOST_LOCAL_FUNCTION_AUX_PP_DECL_TRAITS( \ 27 BOOST_LOCAL_FUNCTION_DETAIL_PP_VOID_LIST( \ 28 declarations))) 29 # define BOOST_LOCAL_FUNCTION(declarations) \ 30 BOOST_LOCAL_FUNCTION_ID( \ 31 BOOST_LOCAL_FUNCTION_DETAIL_PP_LINE_COUNTER, declarations) 32 # define BOOST_LOCAL_FUNCTION_ID_TPL(id, declarations) \ 33 BOOST_LOCAL_FUNCTION_AUX_DECL(id, 1 /* within template */, \ 34 BOOST_LOCAL_FUNCTION_AUX_PP_DECL_TRAITS( \ 35 BOOST_LOCAL_FUNCTION_DETAIL_PP_VOID_LIST( \ 36 declarations))) 37 # define BOOST_LOCAL_FUNCTION_TPL(declarations) \ 38 BOOST_LOCAL_FUNCTION_ID_TPL( \ 39 BOOST_LOCAL_FUNCTION_DETAIL_PP_LINE_COUNTER, declarations) 40 #else // VARIADIC 41 # define BOOST_LOCAL_FUNCTION_ID(id, ...) \ 42 BOOST_LOCAL_FUNCTION_AUX_DECL(id, 0 /* not within template */, \ 43 BOOST_LOCAL_FUNCTION_AUX_PP_DECL_TRAITS( \ 44 BOOST_LOCAL_FUNCTION_DETAIL_PP_VOID_LIST(__VA_ARGS__))) 45 # define BOOST_LOCAL_FUNCTION(...) \ 46 BOOST_LOCAL_FUNCTION_ID( \ 47 BOOST_LOCAL_FUNCTION_DETAIL_PP_LINE_COUNTER, __VA_ARGS__) 48 # define BOOST_LOCAL_FUNCTION_ID_TPL(id, ...) \ 49 BOOST_LOCAL_FUNCTION_AUX_DECL(id, 1 /* within template */, \ 50 BOOST_LOCAL_FUNCTION_AUX_PP_DECL_TRAITS( \ 51 BOOST_LOCAL_FUNCTION_DETAIL_PP_VOID_LIST(__VA_ARGS__))) 52 # define BOOST_LOCAL_FUNCTION_TPL(...) \ 53 BOOST_LOCAL_FUNCTION_ID_TPL( \ 54 BOOST_LOCAL_FUNCTION_DETAIL_PP_LINE_COUNTER, __VA_ARGS__) 55 #endif // VARIADIC 56 57 #define BOOST_LOCAL_FUNCTION_NAME(qualified_name) \ 58 BOOST_LOCAL_FUNCTION_AUX_NAME(0 /* not within template */, qualified_name) 59 #define BOOST_LOCAL_FUNCTION_NAME_TPL(qualified_name) \ 60 BOOST_LOCAL_FUNCTION_AUX_NAME(1 /* within template */, qualified_name) 61 62 #define BOOST_LOCAL_FUNCTION_TYPEOF(bound_variable_name) \ 63 BOOST_LOCAL_FUNCTION_AUX_TYPEOF_TYPE(bound_variable_name) 64 65 // DOCUMENTATION // 66 67 #else // DOXYGEN 68 69 /** @file 70 @brief Local functions allow to program functions locally, within other 71 functions, and directly within the scope where they are needed. 72 */ 73 74 /** 75 @brief This macro is used to start a local function declaration. 76 77 This macro must be used within a declarative context, it must follow the local 78 function result type, it must be followed by the local function body code, and 79 then by the @RefMacro{BOOST_LOCAL_FUNCTION_NAME} macro (see the 80 @RefSect{tutorial, Tutorial} and @RefSect{advanced_topics, Advanced Topics} 81 sections): 82 @code 83 { // Some declarative context. 84 ... 85 result_type BOOST_LOCAL_FUNCTION(declarations) { 86 ... // Body code. 87 } BOOST_LOCAL_FUNCTION_NAME(qualified_name) 88 ... 89 } 90 @endcode 91 92 As usual, exceptions specifications can be optionally programmed just after the 93 macro and before the body code block <c>{ ... }</c> (but the exception 94 specifications will only apply to the body code and not to the library code 95 automatically generated by the macro expansion, see the 96 @RefSect{advanced_topics, Advanced Topics} section). 97 98 Within templates, the special macros @RefMacro{BOOST_LOCAL_FUNCTION_TPL} 99 and @RefMacro{BOOST_LOCAL_FUNCTION_NAME_TPL} must be used. 100 101 @Params 102 @Param{declarations, 103 On compilers that support variadic macros\, the parameter declarations are 104 defined by the following grammar: 105 @code 106 declarations: 107 void | declaration_tuple | declaration_sequence 108 declaration_tuple: 109 declaration\, declaration\, ... 110 declaration_sequence: 111 (declaration) (declaration) ... 112 declaration: 113 bound_variable | parameter | default_value | result_type 114 bound_variable: 115 [const] bind [(variable_type)] [&] variable_name 116 parameter: 117 [auto | register] parameter_type parameter_name 118 default_value: 119 default parameter_default_value 120 result_type: 121 return function_result_type 122 @endcode 123 On compilers that do not support variadic macros\, <c>declaration_tuple</c> 124 cannot be used: 125 @code 126 declarations: 127 void | declaration_sequence 128 @endcode 129 130 (Lexical conventions: <c>token1 | token2</c> means either <c>token1</c> or 131 <c>token2</c>; <c>[token]</c> means either <c>token</c> or nothing; 132 <c>{expression}</c> means the token resulting from the expression.) 133 } 134 @EndParams 135 136 Note that on compilers that support variadic macros, commas can be used to 137 separate the declarations resembling more closely the usual C++ function 138 declaration syntax (this is the preferred syntax). 139 However, for portability, on all C++ compilers (with and without variadic 140 macros) the same library macros also accept parameter declarations specified as 141 a Boost.Preprocessor sequence separated by round parenthesis <c>()</c>. 142 143 When binding the object <c>this</c>, the special symbol <c>this_</c> needs to 144 be used instead of <c>this</c> as the name of the variable to bind and also 145 within the local function body to access the object. 146 (Mistakenly using <c>this</c> instead of <c>this_</c> might not always result in a compiler error and will in general result in undefined behaviour.) 147 148 The result type must either be specified just before the macro or within the 149 macro declarations prefixed by <c>return</c> (but not in both places). 150 151 Within the local function body it possible to access the result type using <c>result_type</c>, the type of the first parameter using <c>arg1_type</c>, the type of the second parameter using <c>arg2_type</c>, etc. 152 The bound variable types can be accessed using @RefMacro{BOOST_LOCAL_FUNCTION_TYPEOF}. 153 154 This macro cannot be portably expanded multiple times on the same line. 155 In these cases, use the @RefMacro{BOOST_LOCAL_FUNCTION_ID} macro instead. 156 157 The maximum number of local function parameters (excluding bound variables) is 158 specified by the configuration macro 159 @RefMacro{BOOST_LOCAL_FUNCTION_CONFIG_ARITY_MAX}. 160 The maximum number of bound variables is specified by the configuration macro 161 @RefMacro{BOOST_LOCAL_FUNCTION_CONFIG_BIND_MAX}. 162 The configuration macro 163 @RefMacro{BOOST_LOCAL_FUNCTION_CONFIG_LOCALS_AS_TPARAMS} can be used to force 164 optimizations that reduce the local function call run-time overhead. 165 166 @Note Local functions are functors so they can be assigned to other functors 167 like <c>boost::function</c> (see Boost.Function). 168 169 @See @RefSect{tutorial, Tutorial} section, 170 @RefSect{advanced_topics, Advanced Topics} section, 171 @RefMacro{BOOST_LOCAL_FUNCTION_NAME}, @RefMacro{BOOST_LOCAL_FUNCTION_TPL}, 172 @RefMacro{BOOST_LOCAL_FUNCTION_NAME_TPL}, 173 @RefMacro{BOOST_LOCAL_FUNCTION_TYPEOF}, @RefMacro{BOOST_LOCAL_FUNCTION_ID}, 174 @RefMacro{BOOST_LOCAL_FUNCTION_CONFIG_ARITY_MAX}, 175 @RefMacro{BOOST_LOCAL_FUNCTION_CONFIG_BIND_MAX}, 176 @RefMacro{BOOST_LOCAL_FUNCTION_CONFIG_LOCALS_AS_TPARAMS}. 177 */ 178 #define BOOST_LOCAL_FUNCTION(declarations) 179 180 /** 181 @brief This macro is used to start a local function declaration within 182 templates. 183 184 This macro must be used instead of @RefMacro{BOOST_LOCAL_FUNCTION} when 185 declaring a local function within a template. 186 A part from that, this macro has the exact same syntax a 187 @RefMacro{BOOST_LOCAL_FUNCTION} (see @RefMacro{BOOST_LOCAL_FUNCTION} for more 188 information): 189 @code 190 { // Some declarative context within a template. 191 ... 192 result_type BOOST_LOCAL_FUNCTION_TPL(declarations) { 193 ... // Body code. 194 } BOOST_LOCAL_FUNCTION_NAME_TPL(qualified_name) 195 ... 196 } 197 @endcode 198 199 Note that @RefMacro{BOOST_LOCAL_FUNCTION_NAME_TPL} must be used with this 200 macro instead of @RefMacro{BOOST_LOCAL_FUNCTION_NAME}. 201 202 This macro cannot be portably expanded multiple times on the same line. 203 In these cases, use the @RefMacro{BOOST_LOCAL_FUNCTION_ID_TPL} macro instead. 204 205 @Note C++03 does not allow to use <c>typename</c> outside templates. 206 This library internally manipulates types, these operations require 207 <c>typename</c> but only within templates. 208 This macro is used to indicate to the library when the enclosing scope is a 209 template so the library can correctly use <c>typename</c>. 210 211 @See @RefSect{tutorial, Tutorial} section, @RefMacro{BOOST_LOCAL_FUNCTION}, 212 @RefMacro{BOOST_LOCAL_FUNCTION_ID_TPL}, 213 @RefMacro{BOOST_LOCAL_FUNCTION_NAME_TPL}. 214 */ 215 #define BOOST_LOCAL_FUNCTION_TPL(declarations) 216 217 /** 218 @brief This macro allows to declare multiple local functions on the same line. 219 220 This macro is equivalent to @RefMacro{BOOST_LOCAL_FUNCTION} but it can be 221 expanded multiple times on the same line if different identifiers <c>id</c> are 222 provided for each expansion (see the 223 @RefSect{advanced_topics, Advanced Topics} section). 224 225 @Params 226 @Param{id, 227 A unique identifier token which can be concatenated by the preprocessor 228 (<c>__LINE__</c>\, <c>local_function_number_1_on_line_123</c>\, etc). 229 } 230 @Param{declarations, 231 Same as the <c>declarations</c> parameter of the 232 @RefMacro{BOOST_LOCAL_FUNCTION} macro. 233 } 234 @EndParams 235 236 The @RefMacro{BOOST_LOCAL_FUNCTION_NAME} macro should be used to end each one 237 of the multiple local function declarations as usual (and it will specify a 238 unique name for each local function). 239 240 Within templates, the special macros @RefMacro{BOOST_LOCAL_FUNCTION_ID_TPL} 241 must be used. 242 243 @Note This macro can be useful when the local function macros are expanded 244 within user-defined macros (because macros all expand on the same line). 245 On some compilers (e.g., MSVC which supports the non-standard 246 <c>__COUNTER__</c> macro) it might not be necessary to use this macro but 247 the use of this macro when expanding multiple local function macros on the same 248 line is always necessary to ensure portability (this is because this library 249 can only portably use <c>__LINE__</c> to internally generate unique 250 identifiers). 251 252 @See @RefSect{advanced_topics, Advanced Topics} section, 253 @RefMacro{BOOST_LOCAL_FUNCTION}, @RefMacro{BOOST_LOCAL_FUNCTION_NAME}, 254 @RefMacro{BOOST_LOCAL_FUNCTION_ID_TPL}. 255 */ 256 #define BOOST_LOCAL_FUNCTION_ID(id, declarations) 257 258 /** 259 @brief This macro allows to declare multiple local functions on the same line 260 within templates. 261 262 This macro must be used instead of @RefMacro{BOOST_LOCAL_FUNCTION_TPL} when 263 declaring multiple local functions on the same line within a template. 264 A part from that, this macro has the exact same syntax as 265 @RefMacro{BOOST_LOCAL_FUNCTION_TPL} (see @RefMacro{BOOST_LOCAL_FUNCTION_TPL} 266 for more information). 267 268 @Params 269 @Param{id, 270 A unique identifier token which can be concatenated by the preprocessor 271 (<c>__LINE__</c>\, <c>local_function_number_1_on_line_123</c>\, etc). 272 } 273 @Param{declarations, 274 Same as the <c>declarations</c> parameter of the 275 @RefMacro{BOOST_LOCAL_FUNCTION_TPL} macro. 276 } 277 @EndParams 278 279 The @RefMacro{BOOST_LOCAL_FUNCTION_NAME} macro should be used to end each one 280 of the multiple local function declarations as usual (and it will specify a 281 unique name for each local function). 282 283 Outside template, the macro @RefMacro{BOOST_LOCAL_FUNCTION_ID} should be used 284 to declare multiple local functions on the same line. 285 286 @Note This macro can be useful when the local function macros are expanded 287 within user-defined macros (because macros all expand on the same line). 288 On some compilers (e.g., MSVC which supports the non-standard 289 <c>__COUNTER__</c> macro) it might not be necessary to use this macro but 290 the use of this macro when expanding multiple local function macros on the same 291 line is always necessary to ensure portability (this is because this library 292 can only portably use <c>__LINE__</c> to internally generate unique 293 identifiers). 294 295 @See @RefSect{advanced_topics, Advanced Topics} section, 296 @RefMacro{BOOST_LOCAL_FUNCTION_TPL}, @RefMacro{BOOST_LOCAL_FUNCTION_NAME}, 297 @RefMacro{BOOST_LOCAL_FUNCTION_ID}. 298 */ 299 #define BOOST_LOCAL_FUNCTION_ID_TPL(id, declarations) 300 301 /** 302 @brief This macro is used to end a local function declaration specifying its 303 name. 304 305 This macro must follow the local function body code block <c>{ ... }</c>: 306 @code 307 { // Some declarative context. 308 ... 309 result_type BOOST_LOCAL_FUNCTION(declarations) { 310 ... // Body code. 311 } BOOST_LOCAL_FUNCTION_NAME(qualified_name) 312 ... 313 } 314 @endcode 315 316 Within templates, the special macros @RefMacro{BOOST_LOCAL_FUNCTION_TPL} and 317 @RefMacro{BOOST_LOCAL_FUNCTION_NAME_TPL} must be used. 318 319 @Params 320 @Param{qualified_name, 321 The name of the local function optionally qualified as follow: 322 @code 323 name: 324 [inline] [recursive] local_function_name 325 @endcode 326 (Lexical conventions: <c>token1 | token2</c> means either <c>token1</c> or 327 <c>token2</c>; <c>[token]</c> means either <c>token</c> or nothing; 328 <c>{expression}</c> means the token resulting from the expression.) 329 } 330 @EndParams 331 332 The local function name can be qualified by prefixing it with the keyword 333 <c>inline</c> (see the @RefSect{advanced_topics, Advanced Topics} section): 334 @code 335 BOOST_LOCAL_FUNCTION_NAME(inline local_function_name) 336 @endcode 337 This increases the chances that the compiler will be able to inline the local 338 function calls (thus reducing run-time). 339 However, inline local functions cannot be passed as template parameters (e.g., to <c>std::for_each</c>) or assigned to other functors (e.g., to 340 <c>boost::function</c>). 341 That is true on C++03 compilers but inline local functions can instead be 342 passed as template parameters on C++11 compilers. 343 On C++11 compilers, there is no need to declare a local function lined because 344 this library will automatically use C++11 specific features to inline the local 345 function while always allowing to pass it as a template parameter. 346 This optimization is automatically enabled when the Boost.Config macro 347 <c>BOOST_NO_CXX11_LOCAL_CLASS_TEMPLATE_PARAMETERS</c> is not defined but it also be 348 forced using @RefMacro{BOOST_LOCAL_FUNCTION_CONFIG_LOCALS_AS_TPARAMS}. 349 350 The local function name can also be qualified by prefixing it with the 351 "keyword" <c>recursive</c> (see the 352 @RefSect{advanced_topics, Advanced Topics} section): 353 @code 354 BOOST_LOCAL_FUNCTION_NAME(recursive local_function_name) 355 @endcode 356 This allows the local function to recursively call itself from its body (as 357 usual in C++). 358 However, recursive local functions should only be called within their 359 declaration scope (otherwise the result is undefined behaviour). 360 Finally, compilers have not been observed to be able to inline recursive local 361 function calls, not even when the recursive local function is also declared 362 inline: 363 @code 364 BOOST_LOCAL_FUNCTION(inline recursive local_function_name) 365 @endcode 366 367 @Note The local function name cannot be the name of an operator 368 <c>operator...</c> and it cannot be the same name of another local function 369 declared within the same enclosing scope (but <c>boost::overloaded_function</c> 370 can be used to overload local functions, see 371 Boost.Functional/OverloadedFunction and the 372 @RefSect{advanced_topics, Advanced Topics} section). 373 374 @See @RefSect{tutorial, Tutorial} section, 375 @RefSect{advanced_topics, Advanced Topics} section, 376 @RefMacro{BOOST_LOCAL_FUNCTION}, 377 @RefMacro{BOOST_LOCAL_FUNCTION_NAME_TPL}. 378 */ 379 #define BOOST_LOCAL_FUNCTION_NAME(qualified_name) 380 381 /** 382 @brief This macro is used to end a local function declaration specifying its 383 name within templates. 384 385 This macro must be used instead of @RefMacro{BOOST_LOCAL_FUNCTION_NAME} when 386 declaring a local function within a template. 387 A part from that, this macro has the exact same syntax a 388 @RefMacro{BOOST_LOCAL_FUNCTION_NAME} (see @RefMacro{BOOST_LOCAL_FUNCTION_NAME} 389 for more information): 390 @code 391 { // Some declarative context within a template. 392 ... 393 result_type BOOST_LOCAL_FUNCTION_TPL(declarations) { 394 ... // Body code. 395 } BOOST_LOCAL_FUNCTION_NAME_TPL(qualified_name) 396 ... 397 } 398 @endcode 399 400 Note that @RefMacro{BOOST_LOCAL_FUNCTION_TPL} must be used with this macro 401 instead of @RefMacro{BOOST_LOCAL_FUNCTION}. 402 403 @Note C++03 does not allow to use <c>typename</c> outside templates. 404 This library internally manipulates types, these operations require 405 <c>typename</c> but only within templates. 406 This macro is used to indicate to the library when the enclosing scope is a 407 template so the library can correctly use <c>typename</c>. 408 409 @See @RefSect{tutorial, Tutorial} section, 410 @RefMacro{BOOST_LOCAL_FUNCTION_NAME}, @RefMacro{BOOST_LOCAL_FUNCTION_TPL}. 411 */ 412 #define BOOST_LOCAL_FUNCTION_NAME_TPL(name) 413 414 /** 415 @brief This macro expands to the type of the specified bound variable. 416 417 This macro can be used within the local functions body to refer to the bound 418 variable types so to declare local variables, check concepts (using 419 Boost.ConceptCheck), etc (see the @RefSect{advanced_topics, Advanced Topics} 420 section). 421 This way the local function can be programmed entirely without explicitly 422 specifying the bound variable types thus facilitating maintenance (e.g., if 423 the type of a bound variable changes in the enclosing scope, the local function 424 code does not have to change). 425 426 @Params 427 @Param{bound_variable_name, 428 The name of one of the local function's bound variables. 429 } 430 @EndParams 431 432 The type returned by the macro is fully qualified in that it contains the extra 433 constant and reference qualifiers when the specified variable is bound by 434 constant and by reference. 435 For example, if a variable named <c>t</c> of type <c>T</c> is: 436 @li Bound by value using <c>bind t</c> then 437 <c>BOOST_LOCAL_FUNCTION_TYPEOF(t)</c> is <c>T</c>. 438 @li Bound by constant value using <c>const bind t</c> then 439 <c>BOOST_LOCAL_FUNCTION_TYPEOF(t)</c> is <c>const T</c>. 440 @li Bound by reference using <c>bind& t</c> then 441 <c>BOOST_LOCAL_FUNCTION_TYPEOF(t)</c> is <c>T&</c>. 442 @li Bound by constant reference using <c>const bind& t</c> then 443 <c>BOOST_LOCAL_FUNCTION_TYPEOF(t)</c> is <c>const T&</c>. 444 445 This macro must be prefixed by <c>typename</c> when used within templates. 446 447 @Note It is best to use this macro instead of Boost.Typeof so to reduce the 448 number of times Boost.Typeof is used to deduce types (see the 449 @RefSect{advanced_topics, Advanced Topics} section). 450 451 @See @RefSect{advanced_topics, Advanced Topics} section, 452 @RefMacro{BOOST_LOCAL_FUNCTION}. 453 */ 454 #define BOOST_LOCAL_FUNCTION_TYPEOF(bound_variable_name) 455 456 #endif // DOXYGEN 457 458 #endif // #include guard 459 460