| .. _module-pw_polyfill: |
| |
| =========== |
| pw_polyfill |
| =========== |
| The ``pw_polyfill`` module supports compiling code against different C++ |
| standards. |
| |
| ---------------------------------------------------- |
| Adapt code to compile with different versions of C++ |
| ---------------------------------------------------- |
| |
| C++ standard macro |
| ================== |
| ``pw_polyfill/standard.h`` provides a macro for checking if a C++ standard is |
| supported. |
| |
| .. c:macro:: PW_CXX_STANDARD_IS_SUPPORTED(standard) |
| |
| Evaluates true if the provided C++ standard (98, 11, 14, 17, 20) is supported |
| by the compiler. This is a simpler, cleaner alternative to checking the value |
| of the ``__cplusplus`` macro. |
| |
| Language feature macros |
| ======================= |
| ``pw_polyfill/language_feature_macros.h`` provides macros for adapting code to |
| work with or without C++ language features. |
| |
| .. list-table:: |
| :header-rows: 1 |
| |
| * - Macro |
| - Feature |
| - Description |
| - Feature test macro |
| * - ``PW_INLINE_VARIABLE`` |
| - inline variables |
| - inline if supported by the compiler |
| - ``__cpp_inline_variables`` |
| * - ``PW_CONSTEXPR_CPP20`` |
| - ``constexpr`` |
| - ``constexpr`` if compiling for C++20 |
| - ``__cplusplus >= 202002L`` |
| * - ``PW_CONSTEVAL`` |
| - ``consteval`` |
| - ``consteval`` if supported by the compiler |
| - ``__cpp_consteval`` |
| * - ``PW_CONSTINIT`` |
| - ``constinit`` |
| - ``constinit`` in clang and GCC 10+ |
| - ``__cpp_constinit`` |
| |
| In GN, Bazel, or CMake, depend on ``$dir_pw_polyfill``, ``//pw_polyfill``, |
| or ``pw_polyfill``, respectively, to access these features. In other build |
| systems, add ``pw_polyfill/public`` as an include path. |
| |
| ------------------------------------------------ |
| Backport new C++ features to older C++ standards |
| ------------------------------------------------ |
| Pigweed backports a few C++ features to older C++ standards. These features |
| are provided in the ``pw`` namespace. If the features are provided by the |
| toolchain, the ``pw`` versions are aliases of the ``std`` versions. |
| |
| These features are documented here, but are not implemented in ``pw_polyfill``. |
| |
| Backported features |
| =================== |
| .. list-table:: |
| :header-rows: 1 |
| |
| * - Header |
| - Feature |
| - Feature test macro |
| - Module |
| - Polyfill header |
| - Polyfill name |
| * - ``<array>`` |
| - ``std::to_array`` |
| - ``__cpp_lib_to_array`` |
| - :ref:`module-pw_containers` |
| - ``pw_containers/to_array.h`` |
| - ``pw::containers::to_array`` |
| * - ``<bit>`` |
| - ``std::endian`` |
| - ``__cpp_lib_endian`` |
| - :ref:`module-pw_bytes` |
| - ``pw_bytes/bit.h`` |
| - ``pw::endian`` |
| * - ``<expected>`` |
| - ``std::expected`` |
| - ``__cpp_lib_expected`` |
| - :ref:`module-pw_result` |
| - ``pw_result/expected.h`` |
| - ``pw::expected`` |
| * - ``<span>`` |
| - ``std::span`` |
| - ``__cpp_lib_span`` |
| - :ref:`module-pw_span` |
| - ``pw_span/span.h`` |
| - ``pw::span`` |
| |
| ------ |
| Zephyr |
| ------ |
| To enable ``pw_polyfill`` for Zephyr add ``CONFIG_PIGWEED_POLYFILL=y`` to the |
| project's configuration. |