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