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