<!DOCTYPE html>
<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<title></title>
<style type="text/css">
tr {
page-break-inside: avoid;
}
</style>
</head>
<body>
<table border="1" summary="This table provides identifying information for this document.">
        <tbody>
         <tr>
                <th>Doc. No.:</th>
                <td></td>
         </tr>
         <tr>
                <th>Date:</th>
                <td>2014-05-06</td>
         </tr>
         <tr>
                <th rowspan="2">Reply to:</th>
                <td>Clark Nelson</td>
         </tr>
         <tr>
                <td>Richard Smith</td>
         </tr>
        </tbody>
</table>
<h1>Feature-testing preprocessor predicates for C++17</h1>
<h2>Introduction</h2>
<p>SD-6 recommends, in addition to defining feature-test macros,
        that implementations support
        two new predicates for use in preprocessor conditional inclusion
        (like the existing <code>defined</code> predicate).</p>
<p>The first of these, <code>__has_include</code>,
        is actually a general-purpose extension to the preprocessor,
        and would be useful to improve portability
        between a very wide range of implementations.
        (The other, <code>__has_cpp_attribute</code>,
        has considerably narrower utility.)
</p>
<p>SG10 would like EWG and WG21 to consider
        whether these predicates would be worth adding to the C++17 standard.</p>
<h2>Descriptions (verbatim from SD-6)</h2>
<h3 id="recs.hasinc">Testing for the presence of a header: <code>__has_include</code></h3>
<p>It is impossible for a C++ program to directly, reliably and portably determine whether
                or not a library header is available for inclusion. Conditionally including a header
                requires the use of a configuration macro, whose setting can be determined by a
                configuration-test process at build time (reliable, but less portable), or by some
                other means (often not reliable or portable).</p>
<p>To solve this general problem, WG21 recommends that implementers provide, and programmers
                use, the <code>__has_include</code> feature.</p>
<h4>Syntax</h4>
<dl>
        <dt><dfn>h-preprocessing-token</dfn>:</dt>
        <dd>any <var>preprocessing-token</var> other than <code>></code></dd>
</dl>
<dl>
        <dt><dfn>h-pp-tokens</dfn>:</dt>
        <dd><var>h-preprocessing-token</var></dd>
        <dd><var>h-pp-tokens h-preprocessing-token</var></dd>
</dl>
<dl>
        <dt><dfn>has-include-expression</dfn>:</dt>
        <dd><code>__has_include (</code> <var>header-name</var> <code>)</code></dd>
        <dd><code>__has_include (</code> <var>string-literal</var> <code>)</code></dd>
        <dd><code>__has_include ( <</code> <var>h-pp-tokens</var> <code>> )</code></dd>
</dl>
<h4>Semantics</h4>
<p>In the first form of the <var>has-include-expression</var>, the parenthesized <var>header-name</var> token is not subject to macro expansion. The second and third
                forms are considered only if the first form does not match, and the preprocessing
                tokens are processed just as in normal text.</p>
<p>A <var>has-include-expression</var> shall appear only in the controlling constant
                expression of a <code>#if</code> or <code>#elif</code> directive ([cpp.cond] 16.1).
                Prior to the evaluation of such an expression, the source file identified by the
                parenthesized preprocessing token sequence in each contained <var>has-include-expression</var>
        is searched for as if that preprocessing token sequence were the <var>pp-tokens</var>
        in a <code>#include</code> directive, except that no further macro expansion is
                performed. If such a directive would not satisfy the syntactic requirements of a
                <code>#include</code> directive, the program is ill-formed. The <var>has-include-expression</var>
        is replaced by the <var>pp-number</var> <code>1</code> if the search for the source
                file succeeds, and by the <var>pp-number</var> <code>0</code> if the search fails.</p>
<p>The <code>#ifdef</code> and <code>#ifndef</code> directives, and the <code>defined</code>
        conditional inclusion operator, shall treat <code>__has_include</code> as if it
                were the name of a defined macro. The identifier <code>__has_include</code> shall
                not appear in any context not mentioned in this section.</p>
<h4>Example</h4>
<p>This demonstrates a way to
        use a library <code>optional</code> facility only if it is available.</p>
<pre>
#ifdef __has_include
# if __has_include(<optional>)
# include <optional>
# define have_optional 1
# elif __has_include(<experimental/optional>)
# include <experimental/optional>
# define have_optional 1
# define experimental_optional
# else
# define have_optional 0
# endif
#endif
</pre>
<h3 id="recs.hasattr">Testing for the presence of an attribute: <code>__has_cpp_attribute</code></h3>
<p>A C++ program cannot directly, reliably, and portably determine whether or not
                a standard or vendor-specific attribute is available for use. Testing for attribute
                support generally requires complex macro logic, as illustrated above for language
                features in general.</p>
<p>To solve this general problem, WG21 recommends that implementers provide, and
                programmers use, the <code>__has_cpp_attribute</code> feature.</p>
<h4>Syntax</h4>
<dl>
        <dt><dfn>has-attribute-expression</dfn>:</dt>
        <dd><code>__has_cpp_attribute (</code> <var>attribute-token</var> <code>)</code></dd>
</dl>
<h4>Semantics</h4>
<p>A <var>has-attribute-expression</var> shall appear only in the controlling constant
                expression of a <code>#if</code> or <code>#elif</code> directive ([cpp.cond] 16.1).
                The <var>has-attribute-expression</var> is replaced by a non-zero pp-number if the
                implementation supports an attribute with the specified name, and by the pp-number
                0 otherwise.</p>
<p>For a standard attribute, the value of the <code>__has_cpp_attribute</code>
        macro is based on the year and month in which the attribute was voted into the working
                draft. In the case where the attribute is vendor-specific, the value is implementation-defined.
                However, in most cases it is expected that the availability of an attribute can
                be detected by any non-zero result.</p>
<p>The <code>#ifdef</code> and <code>#ifndef</code> directives, and the <code>defined</code>
        conditional inclusion operator, shall treat <code>__has_cpp_attribute</code> as
                if it were the name of a defined macro. The identifier <code>__has_cpp_attribute</code>
        shall not appear in any context not mentioned in this section.</p>
<h4>Example</h4>
<p>This demonstrates a way to use the attribute <code>[[deprecated]]</code> only
                if it is available.</p>
<pre>#ifdef __has_cpp_attribute
# if __has_cpp_attribute(deprecated)
# define ATTR_DEPRECATED(msg) [[deprecated(msg)]]
# else
# define ATTR_DEPRECATED(msg)
# endif
#endif</pre>
</body>
</html>