1 方法解释和原理

C++ 标准化的创新步伐使得实现的长期稳定性不太可能。功能被添加到语言中是因为程序员希望使用这些功能。功能被添加到标准（工作草案）中，因为这些功能变得明确。在许多情况下，一个功能在标准正式引入它之前或之后很久就被添加到实现中。

这个过程使得想要使用某个功能的程序员很难知道它在任何给定实现中是否可用。实现很少直接从一个正式的标准修订版跳到下一个；实现过程通常以较小的步骤进行。因此，测试特定标准修订版（例如，通过检查 __cplusplus 宏的值）通常会给出错误的答案。实现者通常不希望在所有功能都实现之前就声称完全符合某个标准修订版。这使得程序员没有可移植的方法来确定哪些功能实际上对他们可用。

程序通常可以以特定于单个实现的方式确定该实现支持哪些功能；但其方法通常文档不全、随意，有时甚至复杂——尤其是当功能的可用性由调用选项控制时。在单个源代码库中为各种实现进行此确定是复杂且容易出错的。

1.1 功能测试宏之前的现状

以下代码试图确定当前实现中是否支持右值引用

#ifndef __USE_RVALUE_REFERENCES
  #if (__GNUC__ > 4 || __GNUC__ == 4 && __GNUC_MINOR__ >= 3) || \
      _MSC_VER >= 1600
    #if __EDG_VERSION__ > 0
      #define __USE_RVALUE_REFERENCES (__EDG_VERSION__ >= 410)
    #else
      #define __USE_RVALUE_REFERENCES 1
    #endif
  #elif __clang__
    #define __USE_RVALUE_REFERENCES __has_feature(cxx_rvalue_references)
  #else
    #define __USE_RVALUE_REFERENCES 0
  #endif
#endif

首先，检查 GNU 和 Microsoft 的版本号是否足够高。但随后检查 EDG 的版本号，因为该前端也兼容这两种编译器，并定义了宏来指示（声称的）兼容性。如果该功能未在指定的 EDG 版本中实现，则假定该功能不可用——即使 EDG 的客户有可能在 EDG 之前实现该功能。

幸运的是，Clang 有办法专门测试特定功能是否存在。但不幸的是，用于此类测试的函数调用式语法不适用于标准预处理器，因此这个出色的新功能最终为混合增加了自己的复杂性。

另请注意，此代码只是实际解决方案的开始。一个完整的解决方案需要考虑更多的编译器，以及特定于各种编译器的命令行选项设置。

1.2 建议解决方案的特点

为了保留实现者按照对自身及其客户最有意义的顺序添加功能的自由，实现者应通过添加与该功能对应的宏定义来指示每个单独功能的可用性。

重要说明：通过建议使用这些宏，WG21 并非使任何功能成为可选；相关功能测试宏的定义缺失并不意味着缺少某个功能的实现符合要求该功能的标准。但是，如果实现者和程序员遵循这些建议，则代码在实际实现之间的可移植性应该会得到改善。

首先，一个功能由WG21文件中指定它并将其引入标准工作草案的论文来标识。并非每篇论文都引入了值得功能测试宏的新功能，但每篇不仅仅是问题解决方案集合的论文都被视为候选；例外情况需要明确说明理由。

对于 C++14，功能测试宏名称通常由论文标题中的某些单词组合而成。未来，希望每篇论文都包含自己关于功能测试宏名称的建议。

为功能测试宏指定的值基于该功能被投票进入工作草案的年份和月份。如果某个功能随后发生重大变化，但仍可认为是相同的功能，则宏的值会更改以指示该功能的规范“修订级别”。然而，在大多数情况下，预期可以通过任何非零宏值的存在来确定功能的存在；例如

template<typename T>
struct use_empty_base_opt :
    std::integral_constant<bool,
        std::is_empty<T>::value
#if __cpp_lib_is_final
        && !std::is_final<T>::value
#endif
    >
{ };

为了避免用户命名空间，语言功能宏的名称前缀为 __cpp_；对于库功能，前缀为 __cpp_lib_。不引入新头文件的库功能预计由实现该功能的头文件定义。

1.3 示例

根据功能可用性选择更高效的编译时实现

#if __cpp_variadic_using
// can use the compile-time efficient, flat inheritance
template<typename ...T> struct Callable : T... {
  using T::operator() ...;
};
#else
// fall-back to linear recursion for older compilers
template<typename ...T> struct Callable;
template<typename T, typename ...U>
struct Callable<T, U...> : T, Callable<U...> {
  using T::operator();
  using Callable<U...>::operator();
};
template<typename T> struct Callable<T> : T {
  using T::operator();
};
template<> struct Callable<> {};
#endif

同理

#if __cpp_fold_expressions
template<typename... T>
  auto sum(T... args)  { return (args + ...); }
#else
auto sum() { return 0; }
template<typename T>
  auto sum(T t) { return t; }
template(typename T, typename... Ts)
  auto sum(T t, Ts... ts) { return t + sum(ts...); }
#endif

根据功能可用性选择更高效的运行时实现

void update(std::set<X>& set, const X& elem, int val)
{
    auto pos = set.find(elem);
    if (pos == set.end())
        return;
#if __cpp_lib_node_extract
    auto next = std::next(pos);
    auto x = set.extract(pos);
    x.value().update(val);
    set.insert(next, std::move(x));
#else
    X tmp = *pos;
    pos = set.erase(pos);
    tmp.update(val);
    set.insert(pos, std::move(tmp));
#endif
}

在某些情况下，功能测试宏的值可能会随着底层功能的变化而改变。为了更容易地跟踪每个功能的演变，本文档中的表格按宏名称分组——每行包含每个可能的值及其相关的提案。

根据__cpp_static_assert有条件地实现某个功能。

#if __cpp_static_assert
#  if __cpp_static_assert > 201400
#    define Static_Assert(cond) static_assert(cond)
#  else
#    define Static_Assert(cond) static_assert(cond, #cond)
#  endif
#  define Static_Assert_Msg(cond, msg) static_assert(cond, msg)
#else
#  define Static_Assert(cond)
#  define Static_Assert_Msg(cond, msg)
#endif

属性也可能随时间改变语义，这就是为什么下面描述的__has_cpp_attribute工具评估为一个值而不是简单的1或0。这允许用户根据__has_cpp_attribute(nodiscard)有条件地提供nodiscard版本

#if __has_cpp_attribute(nodiscard) >= 201907
   // nodiscard has a reason and can
   // be applied to constructors
#  define NODISCARD(msg)      [[nodiscard(msg)]]
#  define NODISCARD_CTOR(msg) [[nodiscard(msg)]]
#elif __has_cpp_attribute(nodiscard) >= 201603
   // nodiscard doesn't have a reason, nor can
#  define NODISCARD(msg)      [[nodiscard]]
#  define NODISCARD_CTOR(msg)
#else
   // nodiscard doesn't exist at all yet
#  define NODISCARD(msg)
#  define NODISCARD_CTOR(msg)
#endif

2 建议

2.1 引言

为了提高各种C++标准部分实现之间的可移植性，WG21（ISO C++编程语言技术委员会）建议实现者和程序员遵循本文档中关于功能测试宏的指导方针。

提供新标准功能的实现者应在功能可用的相同情况下（例如，考虑相关命令行选项）定义具有推荐名称和值的宏，以指示对该功能的支持。

希望确定某个功能在实现中是否可用的程序员应根据具有推荐名称的宏的状态进行判断。（缺少经过测试的功能可能导致程序功能减少，或者相关功能可能以不同方式提供。严格依赖某个功能支持的程序可以尝试无条件使用该功能；据推测，在缺少必要支持的实现上，翻译将失败。因此，如果功能测试宏最有用的目的是在功能不可用时控制 #error 指令的包含，则认为这不足以成为该宏的理由。请注意，测试宏对某个功能的有用性与该功能本身的有用性完全无关。）

2.2 测试头文件是否存在：__has_include

C++ 程序无法直接、可靠和可移植地确定库头文件是否可用于包含。有条件地包含头文件需要使用配置宏，其设置可以通过构建时的配置测试过程（可靠，但可移植性较差）或通过其他方式（通常不可靠或不可移植）确定。

为了解决这个普遍问题，WG21 建议程序员使用 __has_include 功能。

2.2.1 语法

h-预处理-标记:
    除 > 之外的任何 预处理-标记

h-pp-标记:
    h-预处理-标记
    h-pp-标记 h-预处理-标记

has-include-表达式:
    __has_include ( 头文件名 )
    __has_include ( 字符串字面量 )
    __has_include ( < h-pp-标记 > )

2.2.2 语义

在 has-include-expression 的第一种形式中，括号中的 header-name 标记不受宏展开的影响。只有在第一种形式不匹配时才考虑第二种和第三种形式，并且预处理标记的处理方式与正常文本中相同。

has-include-expression 只能出现在 #if 或 #elif 指令的控制常量表达式中 ([cpp.cond] 16.1)。在评估此类表达式之前，会搜索由其中包含的每个 has-include-expression 中的括号括起来的预处理标记序列标识的源文件，就像该预处理标记序列是 #include 指令中的 pp-tokens 一样，除了不执行进一步的宏展开。如果此类指令不满足 #include 指令的语法要求，则程序格式错误。如果源文件搜索成功，has-include-expression 将被 pp-number 1 替换；如果搜索失败，则替换为 pp-number 0。

#ifdef 和 #ifndef 指令，以及定义的条件包含运算符，应将 __has_include 视为已定义宏的名称。标识符 __has_include 不应出现在本节未提及的任何上下文中。

2.2.3 示例

这演示了一种仅在可用时使用库可选功能的方法。请注意，__has_include(<optional>) 成功是不够的，因为在许多工具链上，头文件可能存在于安装中，但其内容会根据编译标志进行保护。例如，以下代码

#ifdef __has_include
#if __has_include(<optional>)
#include <optional>
std::optional<int> o;
#endif
#endif
int main(){ }

仍将无法使用 g++ -std=c++14（使用 libstdc++）编译。

因此，我们需要这样做

#ifdef __has_include
#  if __has_include(<optional>)
#    include <optional>
#    if __cpp_lib_optional >= 201606
#      define have_optional 1
#    endif
#  elif __has_include(<experimental/optional>)
#    include <experimental/optional>
#    if __cpp_lib_experimental_optional >= 201400
#      define have_optional 1
#      define experimental_optional 1
#    endif
#endif

#ifndef have_optional
#    define have_optional 0
#endif

此外，<version> 头文件 [P0754R2] 是一个轻量级头文件，它定义了所有标准库功能测试宏。另一种实现可以是

#ifndef __has_include
#  define __has_include(x) 0
#endif

#if __has_include(<version>)
#  include <version>
#elif __has_include(<optional>)
#  include <optional>
#endif
#if __cpp_lib_optional >= 201606
#  define have_optional 1
#else
#  define have_optional 0
#endif

2.3 测试属性是否存在：__has_cpp_attribute

C++ 程序无法直接、可靠且可移植地确定标准或特定于供应商的属性是否可用。测试属性支持通常需要复杂的宏逻辑，如上文针对一般语言功能所说明的那样。

为了解决这个普遍问题，WG21 建议程序员使用 __has_cpp_attribute 功能。

2.3.1 语法

has-attribute-expression:
    __has_cpp_attribute ( attribute-token )

2.3.2 语义

一个 has-attribute-expression 只能出现在 #if 或 #elif 指令的控制常量表达式中 ([cpp.cond] 16.1)。如果实现支持具有指定名称的属性，has-attribute-expression 将被替换为非零的 pp-number，否则替换为 pp-number 0。

对于标准属性，__has_cpp_attribute 宏的值基于该属性被投票进入工作草案的年份和月份。如果属性是供应商特定的，则该值是实现定义的。然而，在大多数情况下，预期可以通过任何非零结果检测到属性的可用性。

#ifdef 和 #ifndef 指令，以及定义的条件包含运算符，应将 __has_cpp_attribute 视为已定义宏的名称。标识符 __has_cpp_attribute 不应出现在本节未提及的任何上下文中。

2.3.3 示例

这演示了仅在可用时使用属性 [[deprecated]] 的方法。

#ifndef __has_cpp_attribute
# define __has_cpp_attribute(x) 0
#endif
#if __has_cpp_attribute(deprecated)
# define ATTR_DEPRECATED(msg) [[deprecated(msg)]]
#else
# define ATTR_DEPRECATED(msg)
#endif

3 策略

SG-10 已采纳多项与我们确定和命名宏的标准实践相关的策略。

3.1 constexpr

对于语言，我们将有一个单独的 __cpp_constexpr 宏。每次我们在语言中扩展 constexpr 时，它都会被提升。对于库，我们将为重要的特殊功能添加特定的功能测试宏。否则，对于那些我们只是将 constexpr 添加到库中更多事物的情况，我们将为每个头文件提供一个专用的测试宏，并且每次更改时只提升该头文件特定的宏。该宏将命名为 __cpp_lib_constexpr_HEADER（除了少数现有的数组和算法宏，它们的名称略有不同）。

摘自 [P1902R1]。

3.2 带有库组件的语言功能

在某些情况下，一个功能需要两个宏，一个用于语言，一个用于库。例如，除非编译器支持该功能，否则库不会定义其三向比较操作。

对于最终用户，建议他们只测试库宏，因为只有当语言宏也为真时，库宏才为真。因此，语言宏包含“impl”以将其与预计由库设置的更通用版本区分开来。

请注意，最初 SG10 建议库版本的宏不包含通常的 _lib 部分，但 LWG 对库宏（在使用前需要头文件）不包含 _lib 的不一致性感到不适。

另请注意，SG10 最初建议核心功能测试包含 _lang，但 LWG 希望有更清晰地暗示该宏是用于核心功能而非供最终用户使用的内容。他们建议改用 _impl。

摘自 [P1353R0]。

4 功能测试宏表

以下是标准中的所有功能测试宏，按语言宏、属性宏和库宏划分，然后按名称排序。每个宏将包含其可能的取值列表以及在实现定义该宏为特定取值之前需要实现的论文。

请注意，同一篇论文可能会引入或更新多个功能测试宏。给定值可能需要多篇论文。论文也可能*移除*某个功能测试宏，在这种情况下，其值将被指定为 已删除。

4.1 语言功能测试宏

所有语言宏都是预定义的（即在进行检查之前无需包含任何头文件）。

在某些情况下，一个功能需要两个宏：一个用于语言，一个用于库。例如，除非编译器支持该功能，否则库不会定义其三向比较运算符。在这些情况下，建议最终用户只测试库宏。那些旨在由库检查的核心语言功能测试宏被拼写为 __cpp_impl_*。

4.2 属性功能测试宏

以下所有宏都是预定义的。

4.3 库功能测试宏

以下所有宏在包含头文件 <version> 或下面指定的相应头文件后定义。

5 参考文献