blob: 03d22bbd9ce19c1724ecc5f1d9c72043806eb6fb [file] [log] [blame]
.. _module-pw_preprocessor:
---------------
pw_preprocessor
---------------
The preprocessor module provides various helpful preprocessor macros.
Compatibility
=============
C and C++
Headers
=======
The preprocessor module provides several headers.
pw_preprocessor/arguments.h
---------------------------------
Defines macros for handling variadic arguments to function-like macros. Macros
include the following:
.. c:macro:: PW_DELEGATE_BY_ARG_COUNT(name, ...)
Selects and invokes a macro based on the number of arguments provided. Expands
to ``<name><arg_count>(...)``. For example,
``PW_DELEGATE_BY_ARG_COUNT(foo_, 1, 2, 3)`` expands to ``foo_3(1, 2, 3)``.
This example shows how ``PW_DELEGATE_BY_ARG_COUNT`` could be used to log a
customized message based on the number of arguments provided.
.. code-block:: cpp
#define ARG_PRINT(...) PW_DELEGATE_BY_ARG_COUNT(_ARG_PRINT, __VA_ARGS__)
#define _ARG_PRINT0(a) LOG_INFO("nothing!")
#define _ARG_PRINT1(a) LOG_INFO("1 arg: %s", a)
#define _ARG_PRINT2(a, b) LOG_INFO("2 args: %s, %s", a, b)
#define _ARG_PRINT3(a, b, c) LOG_INFO("3 args: %s, %s, %s", a, b, c)
When used, ``ARG_PRINT`` expands to the ``_ARG_PRINT#`` macro corresponding
to the number of arguments.
.. code-block:: cpp
ARG_PRINT(); // Outputs: nothing!
ARG_PRINT("a"); // Outputs: 1 arg: a
ARG_PRINT("a", "b"); // Outputs: 2 args: a, b
ARG_PRINT("a", "b", "c"); // Outputs: 3 args: a, b, c
.. c:macro:: PW_COMMA_ARGS(...)
Expands to a comma followed by the arguments if any arguments are provided.
Otherwise, expands to nothing. If the final argument is empty, it is omitted.
This is useful when passing ``__VA_ARGS__`` to a variadic function or template
parameter list, since it removes the extra comma when no arguments are
provided. ``PW_COMMA_ARGS`` must NOT be used when invoking a macro from
another macro.
For example. ``PW_COMMA_ARGS(1, 2, 3)``, expands to ``, 1, 2, 3``, while
``PW_COMMA_ARGS()`` expands to nothing. ``PW_COMMA_ARGS(1, 2, )`` expands to
``, 1, 2``.
pw_preprocessor/boolean.h
-------------------------
Defines macros for boolean logic on literal 1s and 0s. This is useful for
situations when a literal is needed to build the name of a function or macro.
pw_preprocessor/compiler.h
--------------------------
Macros for compiler-specific features, such as attributes or builtins.
Modifying compiler diagnostics
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
``pw_preprocessor/compiler.h`` provides macros for enabling or disabling
compiler diagnostics (warnings or errors).
.. c:macro:: PW_MODIFY_DIAGNOSTICS_PUSH()
Starts a new group of :c:macro:`PW_MODIFY_DIAGNOSTIC` statements. A
:c:macro:`PW_MODIFY_DIAGNOSTICS_POP` statement must follow.
.. c:macro:: PW_MODIFY_DIAGNOSTICS_POP()
:c:macro:`PW_MODIFY_DIAGNOSTIC` statements since the most recent
:c:macro:`PW_MODIFY_DIAGNOSTICS_PUSH` no longer apply after this statement.
.. c:macro:: PW_MODIFY_DIAGNOSTIC(kind, option)
Changes how a diagnostic (warning or error) is handled. Most commonly used to
disable warnings. ``PW_MODIFY_DIAGNOSTIC`` should be used between
:c:macro:`PW_MODIFY_DIAGNOSTICS_PUSH` and :c:macro:`PW_MODIFY_DIAGNOSTICS_POP`
statements to avoid applying the modifications too broadly.
``kind`` may be ``warning``, ``error``, or ``ignored``.
These macros can be used to disable warnings for precise sections of code, even
a single line if necessary.
.. code-block:: c
PW_MODIFY_DIAGNOSTICS_PUSH();
PW_MODIFY_DIAGNOSTIC(ignored, "-Wunused-variable");
static int this_variable_is_never_used;
PW_MODIFY_DIAGNOSTICS_POP();
.. tip::
:c:macro:`PW_MODIFY_DIAGNOSTIC` and related macros should rarely be used.
Whenever possible, fix the underlying issues about which the compiler is
warning, rather than silencing the diagnostics.
pw_preprocessor/concat.h
------------------------
Defines the ``PW_CONCAT(...)`` macro, which expands its arguments if they are
macros and token pastes the results. This can be used for building names of
classes, variables, macros, etc.
pw_preprocessor/util.h
----------------------
General purpose, useful macros.
* ``PW_ARRAY_SIZE(array)`` -- calculates the size of a C array
* ``PW_STRINGIFY(...)`` -- expands its arguments as macros and converts them to
a string literal
* ``PW_EXTERN_C`` -- declares a name to be ``extern "C"`` in C++; expands to
nothing in C
* ``PW_EXTERN_C_START`` / ``PW_EXTERN_C_END`` -- declares an ``extern "C" { }``
block in C++; expands to nothing in C