﻿<!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>N4535</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>&gt;</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 ( &lt;</code> <var>h-pp-tokens</var> <code>&gt; )</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(&lt;optional&gt;)
#    include &lt;optional&gt;
#    define have_optional 1
#  elif __has_include(&lt;experimental/optional&gt;)
#    include &lt;experimental/optional&gt;
#    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>
