Alexei Frolov | c10c812 | 2019-11-01 16:31:19 -0700 | [diff] [blame^] | 1 | .. _chapter-preprocessor: |
| 2 | |
| 3 | .. default-domain:: cpp |
| 4 | |
| 5 | .. highlight:: sh |
| 6 | |
| 7 | ------------ |
| 8 | Preprocessor |
| 9 | ------------ |
| 10 | The preprocessor module provides various helpful preprocessor macros. |
| 11 | |
| 12 | Compatibility |
| 13 | ============= |
| 14 | C and C++ |
| 15 | |
| 16 | Dependencies |
| 17 | ============ |
| 18 | This module has no dependencies. |
| 19 | |
| 20 | Headers |
| 21 | ======= |
| 22 | The preprocessor module provides several headers. |
| 23 | |
| 24 | pw_preprocessor/boolean.h |
| 25 | ------------------------- |
| 26 | Defines macros for boolean logic on literal 1s and 0s. This is useful for |
| 27 | situations when a literal is needed to build the name of a function or macro. |
| 28 | |
| 29 | pw_preprocessor/compiler.h |
| 30 | -------------------------- |
| 31 | Macros for compiler-specific features, such as attributes or builtins. |
| 32 | |
| 33 | pw_preprocessor/concat.h |
| 34 | ------------------------ |
| 35 | Defines the ``PW_CONCAT(...)`` macro, which expands its arguments if they are |
| 36 | macros and token pastes the results. This can be used for building names of |
| 37 | classes, variables, macros, etc. |
| 38 | |
| 39 | pw_preprocessor/macro_arg_count.h |
| 40 | --------------------------------- |
| 41 | Defines the ``PW_ARG_COUNT(...)`` macro, which counts the number of arguments it |
| 42 | was passed. It can be invoked directly or with ``__VA_ARGS__`` in another macro. |
| 43 | ``PW_ARG_COUNT(...)`` evaluates to a literal of the number of arguments which |
| 44 | can be used directly or concatenated to build other names. Unlike many common |
| 45 | implementations, this macro correctly evaluates to ``0`` when it is invoked |
| 46 | without arguments. |
| 47 | |
| 48 | This header also defines ``PW_HAS_ARGS(...)`` and ``PW_HAS_NO_ARGS(...)``, |
| 49 | which evaluate to ``1`` or ``0`` depending on whether they are invoked with |
| 50 | arguments. |
| 51 | |
| 52 | pw_preprocessor/util.h |
| 53 | ---------------------- |
| 54 | General purpose, useful macros. |
| 55 | |
| 56 | * ``PW_ARRAY_SIZE(array)`` -- calculates the size of a C array |
| 57 | * ``PW_UNUSED(value)`` -- silences "unused variable" compiler warnings |
| 58 | * ``PW_STRINGIFY(...)`` -- expands its arguments as macros and converts them to |
| 59 | a string literal |
| 60 | * ``PW_EXTERN_C`` -- declares a name to be ``extern "C"`` in C++; expands to |
| 61 | nothing in C |
| 62 | * ``PW_EXTERN_C_START`` / ``PW_EXTERN_C_END`` -- declares an ``extern "C" { }`` |
| 63 | block in C++; expands to nothing in C |