third_party/pigweed/repo/pw_preprocessor/docs.rst

   1 .. _module-pw_preprocessor:
   2
   3 ---------------
   4 pw_preprocessor
   5 ---------------
   6 The preprocessor module provides various helpful preprocessor macros.
   7
   8 Compatibility
   9 =============
  10 C and C++
  11
  12 Headers
  13 =======
  14 The preprocessor module provides several headers.
  15
  16 pw_preprocessor/arguments.h
  17 ---------------------------------
  18 Defines macros for handling variadic arguments to function-like macros. Macros
  19 include the following:
  20
  21 .. c:function:: 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_PRINT_0(a)        LOG_INFO("nothing!")
  34       #define _ARG_PRINT_1(a)        LOG_INFO("1 arg: %s", a)
  35       #define _ARG_PRINT_2(a, b)     LOG_INFO("2 args: %s, %s", a, b)
  36       #define _ARG_PRINT_3(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:function:: 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
  61 pw_preprocessor/boolean.h
  62 -------------------------
  63 Defines macros for boolean logic on literal 1s and 0s. This is useful for
  64 situations when a literal is needed to build the name of a function or macro.
  65
  66 pw_preprocessor/compiler.h
  67 --------------------------
  68 Macros for compiler-specific features, such as attributes or builtins.
  69
  70 pw_preprocessor/concat.h
  71 ------------------------
  72 Defines the ``PW_CONCAT(...)`` macro, which expands its arguments if they are
  73 macros and token pastes the results. This can be used for building names of
  74 classes, variables, macros, etc.
  75
  76 pw_preprocessor/util.h
  77 ----------------------
  78 General purpose, useful macros.
  79
  80 * ``PW_ARRAY_SIZE(array)`` -- calculates the size of a C array
  81 * ``PW_UNUSED(value)`` -- silences "unused variable" compiler warnings
  82 * ``PW_STRINGIFY(...)`` -- expands its arguments as macros and converts them to
  83   a string literal
  84 * ``PW_EXTERN_C`` -- declares a name to be ``extern "C"`` in C++; expands to
  85   nothing in C
  86 * ``PW_EXTERN_C_START`` / ``PW_EXTERN_C_END`` -- declares an ``extern "C" { }``
  87   block in C++; expands to nothing in C