1.. _module-pw_preprocessor: 2 3--------------- 4pw_preprocessor 5--------------- 6The preprocessor module provides various helpful preprocessor macros. 7 8Compatibility 9============= 10C and C++ 11 12Headers 13======= 14The preprocessor module provides several headers. 15 16pw_preprocessor/arguments.h 17--------------------------------- 18Defines macros for handling variadic arguments to function-like macros. Macros 19include the following: 20 21.. c:macro:: PW_DELEGATE_BY_ARG_COUNT(name, ...) 22 23 Selects and invokes a macro based on the number of arguments provided. Expands 24 to ``<name><arg_count>(...)``. For example, 25 ``PW_DELEGATE_BY_ARG_COUNT(foo_, 1, 2, 3)`` expands to ``foo_3(1, 2, 3)``. 26 27 This example shows how ``PW_DELEGATE_BY_ARG_COUNT`` could be used to log a 28 customized message based on the number of arguments provided. 29 30 .. code-block:: cpp 31 32 #define ARG_PRINT(...) PW_DELEGATE_BY_ARG_COUNT(_ARG_PRINT, __VA_ARGS__) 33 #define _ARG_PRINT0(a) LOG_INFO("nothing!") 34 #define _ARG_PRINT1(a) LOG_INFO("1 arg: %s", a) 35 #define _ARG_PRINT2(a, b) LOG_INFO("2 args: %s, %s", a, b) 36 #define _ARG_PRINT3(a, b, c) LOG_INFO("3 args: %s, %s, %s", a, b, c) 37 38 When used, ``ARG_PRINT`` expands to the ``_ARG_PRINT#`` macro corresponding 39 to the number of arguments. 40 41 .. code-block:: cpp 42 43 ARG_PRINT(); // Outputs: nothing! 44 ARG_PRINT("a"); // Outputs: 1 arg: a 45 ARG_PRINT("a", "b"); // Outputs: 2 args: a, b 46 ARG_PRINT("a", "b", "c"); // Outputs: 3 args: a, b, c 47 48.. c:macro:: PW_COMMA_ARGS(...) 49 50 Expands to a comma followed by the arguments if any arguments are provided. 51 Otherwise, expands to nothing. If the final argument is empty, it is omitted. 52 This is useful when passing ``__VA_ARGS__`` to a variadic function or template 53 parameter list, since it removes the extra comma when no arguments are 54 provided. ``PW_COMMA_ARGS`` must NOT be used when invoking a macro from 55 another macro. 56 57 For example. ``PW_COMMA_ARGS(1, 2, 3)``, expands to ``, 1, 2, 3``, while 58 ``PW_COMMA_ARGS()`` expands to nothing. ``PW_COMMA_ARGS(1, 2, )`` expands to 59 ``, 1, 2``. 60 61pw_preprocessor/boolean.h 62------------------------- 63Defines macros for boolean logic on literal 1s and 0s. This is useful for 64situations when a literal is needed to build the name of a function or macro. 65 66pw_preprocessor/compiler.h 67-------------------------- 68Macros for compiler-specific features, such as attributes or builtins. 69 70Modifying compiler diagnostics 71^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 72``pw_preprocessor/compiler.h`` provides macros for enabling or disabling 73compiler diagnostics (warnings or errors) for sections of code. 74 75:c:macro:`PW_MODIFY_DIAGNOSTICS_PUSH` and :c:macro:`PW_MODIFY_DIAGNOSTICS_POP` 76are used to turn off or on diagnostics (warnings or errors) for a section of 77code. Use :c:macro:`PW_MODIFY_DIAGNOSTICS_PUSH`, use 78:c:macro:`PW_MODIFY_DIAGNOSTIC` as many times as needed, then use 79:c:macro:`PW_MODIFY_DIAGNOSTICS_POP` to restore the previous settings. 80 81.. code-block:: c 82 83 PW_MODIFY_DIAGNOSTICS_PUSH(); 84 PW_MODIFY_DIAGNOSTIC(ignored, "-Wunused-variable"); 85 86 static int this_variable_is_never_used; 87 88 PW_MODIFY_DIAGNOSTICS_POP(); 89 90.. tip:: 91 92 :c:macro:`PW_MODIFY_DIAGNOSTIC` and related macros should rarely be used. 93 Whenever possible, fix the underlying issues about which the compiler is 94 warning, rather than silencing the diagnostics. 95 96.. _module-pw_preprocessor-integer-overflow: 97 98Integer with Overflow Checking 99^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 100``pw_preprocessor/compiler.h`` provides macros for performing arithmetic 101operations and checking whether it overflowed. 102 103- :c:macro:`PW_ADD_OVERFLOW` 104- :c:macro:`PW_SUB_OVERFLOW` 105- :c:macro:`PW_MUL_OVERFLOW` 106 107API Reference 108^^^^^^^^^^^^^ 109.. doxygengroup:: pw_preprocessor_compiler 110 :content-only: 111 112pw_preprocessor/concat.h 113------------------------ 114Defines the ``PW_CONCAT(...)`` macro, which expands its arguments if they are 115macros and token pastes the results. This can be used for building names of 116classes, variables, macros, etc. 117 118pw_preprocessor/util.h 119---------------------- 120General purpose, useful macros. 121 122* ``PW_ARRAY_SIZE(array)`` -- calculates the size of a C array 123* ``PW_STRINGIFY(...)`` -- expands its arguments as macros and converts them to 124 a string literal 125* ``PW_EXTERN_C`` -- declares a name to be ``extern "C"`` in C++; expands to 126 nothing in C 127* ``PW_EXTERN_C_START`` / ``PW_EXTERN_C_END`` -- declares an ``extern "C" { }`` 128 block in C++; expands to nothing in C 129 130Zephyr 131====== 132To enable ``pw_preprocessor`` for Zephyr add ``CONFIG_PIGWEED_PREPROCESSOR=y`` 133to the project's configuration. 134