ocrm.bsky.social
the game where you go into mines and start crafting! but for consoles (forked directly from smartcmd's github)
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
71functions, 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
77This macro must be used within a declarative context, it must follow the local
78function result type, it must be followed by the local function body code, and
79then by the @RefMacro{BOOST_LOCAL_FUNCTION_NAME} macro (see the
80@RefSect{tutorial, Tutorial} and @RefSect{advanced_topics, Advanced Topics}
81sections):
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
92As usual, exceptions specifications can be optionally programmed just after the
93macro and before the body code block <c>{ ... }</c> (but the exception
94specifications will only apply to the body code and not to the library code
95automatically generated by the macro expansion, see the
96@RefSect{advanced_topics, Advanced Topics} section).
97
98Within templates, the special macros @RefMacro{BOOST_LOCAL_FUNCTION_TPL}
99and @RefMacro{BOOST_LOCAL_FUNCTION_NAME_TPL} must be used.
100
101@Params
102@Param{declarations,
103On compilers that support variadic macros\, the parameter declarations are
104defined 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
123On compilers that do not support variadic macros\, <c>declaration_tuple</c>
124cannot 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
136Note that on compilers that support variadic macros, commas can be used to
137separate the declarations resembling more closely the usual C++ function
138declaration syntax (this is the preferred syntax).
139However, for portability, on all C++ compilers (with and without variadic
140macros) the same library macros also accept parameter declarations specified as
141a Boost.Preprocessor sequence separated by round parenthesis <c>()</c>.
142
143When binding the object <c>this</c>, the special symbol <c>this_</c> needs to
144be used instead of <c>this</c> as the name of the variable to bind and also
145within 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
148The result type must either be specified just before the macro or within the
149macro declarations prefixed by <c>return</c> (but not in both places).
150
151Within 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.
152The bound variable types can be accessed using @RefMacro{BOOST_LOCAL_FUNCTION_TYPEOF}.
153
154This macro cannot be portably expanded multiple times on the same line.
155In these cases, use the @RefMacro{BOOST_LOCAL_FUNCTION_ID} macro instead.
156
157The maximum number of local function parameters (excluding bound variables) is
158specified by the configuration macro
159@RefMacro{BOOST_LOCAL_FUNCTION_CONFIG_ARITY_MAX}.
160The maximum number of bound variables is specified by the configuration macro
161@RefMacro{BOOST_LOCAL_FUNCTION_CONFIG_BIND_MAX}.
162The configuration macro
163@RefMacro{BOOST_LOCAL_FUNCTION_CONFIG_LOCALS_AS_TPARAMS} can be used to force
164optimizations that reduce the local function call run-time overhead.
165
166@Note Local functions are functors so they can be assigned to other functors
167like <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
182templates.
183
184This macro must be used instead of @RefMacro{BOOST_LOCAL_FUNCTION} when
185declaring a local function within a template.
186A part from that, this macro has the exact same syntax a
187@RefMacro{BOOST_LOCAL_FUNCTION} (see @RefMacro{BOOST_LOCAL_FUNCTION} for more
188information):
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
199Note that @RefMacro{BOOST_LOCAL_FUNCTION_NAME_TPL} must be used with this
200macro instead of @RefMacro{BOOST_LOCAL_FUNCTION_NAME}.
201
202This macro cannot be portably expanded multiple times on the same line.
203In 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.
206This library internally manipulates types, these operations require
207<c>typename</c> but only within templates.
208This macro is used to indicate to the library when the enclosing scope is a
209template 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
220This macro is equivalent to @RefMacro{BOOST_LOCAL_FUNCTION} but it can be
221expanded multiple times on the same line if different identifiers <c>id</c> are
222provided for each expansion (see the
223@RefSect{advanced_topics, Advanced Topics} section).
224
225@Params
226@Param{id,
227A 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,
231Same as the <c>declarations</c> parameter of the
232@RefMacro{BOOST_LOCAL_FUNCTION} macro.
233}
234@EndParams
235
236The @RefMacro{BOOST_LOCAL_FUNCTION_NAME} macro should be used to end each one
237of the multiple local function declarations as usual (and it will specify a
238unique name for each local function).
239
240Within templates, the special macros @RefMacro{BOOST_LOCAL_FUNCTION_ID_TPL}
241must be used.
242
243@Note This macro can be useful when the local function macros are expanded
244within user-defined macros (because macros all expand on the same line).
245On 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
247the use of this macro when expanding multiple local function macros on the same
248line is always necessary to ensure portability (this is because this library
249can only portably use <c>__LINE__</c> to internally generate unique
250identifiers).
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
260within templates.
261
262This macro must be used instead of @RefMacro{BOOST_LOCAL_FUNCTION_TPL} when
263declaring multiple local functions on the same line within a template.
264A part from that, this macro has the exact same syntax as
265@RefMacro{BOOST_LOCAL_FUNCTION_TPL} (see @RefMacro{BOOST_LOCAL_FUNCTION_TPL}
266for more information).
267
268@Params
269@Param{id,
270A 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,
274Same as the <c>declarations</c> parameter of the
275@RefMacro{BOOST_LOCAL_FUNCTION_TPL} macro.
276}
277@EndParams
278
279The @RefMacro{BOOST_LOCAL_FUNCTION_NAME} macro should be used to end each one
280of the multiple local function declarations as usual (and it will specify a
281unique name for each local function).
282
283Outside template, the macro @RefMacro{BOOST_LOCAL_FUNCTION_ID} should be used
284to declare multiple local functions on the same line.
285
286@Note This macro can be useful when the local function macros are expanded
287within user-defined macros (because macros all expand on the same line).
288On 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
290the use of this macro when expanding multiple local function macros on the same
291line is always necessary to ensure portability (this is because this library
292can only portably use <c>__LINE__</c> to internally generate unique
293identifiers).
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
303name.
304
305This 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
316Within 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,
321The 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
332The 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
337This increases the chances that the compiler will be able to inline the local
338function calls (thus reducing run-time).
339However, 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>).
341That is true on C++03 compilers but inline local functions can instead be
342passed as template parameters on C++11 compilers.
343On C++11 compilers, there is no need to declare a local function lined because
344this library will automatically use C++11 specific features to inline the local
345function while always allowing to pass it as a template parameter.
346This 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
348forced using @RefMacro{BOOST_LOCAL_FUNCTION_CONFIG_LOCALS_AS_TPARAMS}.
349
350The 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
356This allows the local function to recursively call itself from its body (as
357usual in C++).
358However, recursive local functions should only be called within their
359declaration scope (otherwise the result is undefined behaviour).
360Finally, compilers have not been observed to be able to inline recursive local
361function calls, not even when the recursive local function is also declared
362inline:
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
369declared within the same enclosing scope (but <c>boost::overloaded_function</c>
370can be used to overload local functions, see
371Boost.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
383name within templates.
384
385This macro must be used instead of @RefMacro{BOOST_LOCAL_FUNCTION_NAME} when
386declaring a local function within a template.
387A part from that, this macro has the exact same syntax a
388@RefMacro{BOOST_LOCAL_FUNCTION_NAME} (see @RefMacro{BOOST_LOCAL_FUNCTION_NAME}
389for 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
400Note that @RefMacro{BOOST_LOCAL_FUNCTION_TPL} must be used with this macro
401instead of @RefMacro{BOOST_LOCAL_FUNCTION}.
402
403@Note C++03 does not allow to use <c>typename</c> outside templates.
404This library internally manipulates types, these operations require
405<c>typename</c> but only within templates.
406This macro is used to indicate to the library when the enclosing scope is a
407template 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
417This macro can be used within the local functions body to refer to the bound
418variable types so to declare local variables, check concepts (using
419Boost.ConceptCheck), etc (see the @RefSect{advanced_topics, Advanced Topics}
420section).
421This way the local function can be programmed entirely without explicitly
422specifying the bound variable types thus facilitating maintenance (e.g., if
423the type of a bound variable changes in the enclosing scope, the local function
424code does not have to change).
425
426@Params
427@Param{bound_variable_name,
428The name of one of the local function's bound variables.
429}
430@EndParams
431
432The type returned by the macro is fully qualified in that it contains the extra
433constant and reference qualifiers when the specified variable is bound by
434constant and by reference.
435For 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
445This 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
448number 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