Doc. No.: | N4030
Date: | 2014-05-22
Reply to: | Clark Nelson
Title: | Feature-testing recommendations for C++

# Feature-testing recommendations for C++

## Preface

The new `__has_cpp_attribute` feature should be reviewed by EWG and WG21.

I have added indications of changes relative to the published SD-6. The preface is informative; changes are not marked.

This revision of this document contains STUBS for sections expected to be filled in later.

## Contents

1. Introduction
2. Explanation and rationale for the approach
   1. Problem statement
   2. Status quo
   3. Characteristics of the proposed solution
3. Recommendations
   1. Introduction
   2. Testing for the presence of a header: `__has_include`
   3. Testing for the presence of an attribute: `__has_cpp_attribute`
   4. C++14 features
   5. C++11 features (STUB)
   6. Conditionally-supported constructs (STUB)
   7. C++98 features (STUB)
4. Detailed explanation and rationale
   1. C++14 features
5. Revision history

## Introduction

At the September 2013 (Chicago) meeting of WG21, there was a five-way poll of all of the C++ experts in attendance – approximately 80 – concerning their support for the approach described herein for feature-testing in C++. The results of the poll:

Strongly favor | Favor | Neutral | Oppose | Strongly oppose
--- | --- | --- | --- | ---
lots | lots | 1 | 0 | 0

This document was subsequently designated WG21's SD-6 (sixth standing document), which will continue to be maintained by SG10.

## Explanation and rationale for the approach

### Problem statement

The pace of innovation in the standardization of C++ makes long-term stability of implementations unlikely. Features are added to the language because programmers want to use those features. Features are added to (the working draft of) the standard as the features become well-specified. In many cases a feature is added to an implementation well before or well after the standard officially introducing it is approved.

This process makes it difficult for programmers who want to use a feature to know whether it is available in any given implementation. Implementations rarely leap from one formal revision of the standard directly to the next; the implementation process generally proceeds by smaller steps. As a result, testing for a specific revision of the standard (e.g. by examining the value of the `__cplusplus` macro) often gives the wrong answer. Implementers generally don't want to appear to be claiming full conformance to a standard revision until all of its features are implemented. That leaves programmers with no portable way to determine which features are actually available to them.

It is often possible for a program to determine, in a manner specific to a single implementation, what features are supported by that implementation; but the means are often poorly documented and ad hoc, and sometimes complex – especially when the availability of a feature is controlled by an invocation option. To make this determination for a variety of implementations in a single source base is complex and error-prone.

### Status quo

Here is some code that attempts to determine whether rvalue references are available in the implementation in use:

    #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

First, the GNU and Microsoft version numbers are checked to see if they are high enough. But then a check is made of the EDG version number, since that front end also has compatibility modes for both those compilers, and defines macros indicating (claimed) compatibility with them. If the feature wasn't implemented in the indicated EDG version, it is assumed that the feature is not available – even though it is possible for a customer of EDG to implement a feature before EDG does.

Fortunately Clang has ways to test specifically for the presence of specific features. But unfortunately, the function-call-like syntax used for such tests won't work with a standard preprocessor, so this fine new feature winds up adding its own flavor of complexity to the mix.

Also note that this code is only the beginning of a real-world solution. A complete solution would need to take into account more compilers, and also command-line option settings specific to various compilers.

### Characteristics of the proposed solution

To preserve implementers' freedom to add features in the order that makes the most sense for themselves and their customers, implementers should indicate the availability of each separate feature by adding a definition of a macro with the name corresponding to that feature.

Important note: By recommending the use of these macros, WG21 is not making any feature optional; the absence of a definition for the relevant feature-test macro does not make an implementation that lacks a feature conform to a standard that requires the feature. However, if implementers and programmers follow these recommendations, portability of code between real-world implementations should be improved.

To a first approximation, a feature is identified by the WG21 paper in which it is specified, and by which it is introduced into the working draft of the standard. Not every paper introduces a new feature worth a feature-test macro, but every paper that is not just a collection of issue resolutions is considered a candidate; exceptions are explicitly justified.

For C++14, it is preferred for the feature-test macro to be named using name generally consists of some combination of words from the title of the paper. In the future, it is hoped that every paper will include its own recommendations concerning feature-test macro names.

The value specified for a feature-test macro is based on the year and month in which the feature is voted into the working draft. In a case where a feature is subsequently changed in a significant way, but arguably remains the same feature, the value of the macro can be is changed to indicate the “revision level” of the specification of the feature. However, in most cases it is expected that the presence of a feature can be determined by the presence of any non-zero macro value; for example:

    #if __cpp_binary_literals
    int const packed_zero_to_three = 0b00011011;
    #else
    int const packed_zero_to_three = 0x1B;
    #endif

To avoid the user's namespace, names of macros for language features are prefixed by “`__cpp_`”; for library features, by “`__cpp_lib_`”. A library feature that doesn't introduce a new header is expected to be defined by the header(s) that implement the feature.

## Recommendations

### Introduction

For the sake of improved portability between partial implementations of various C++ standards, WG21 (the ISO technical committee for the C++ programming language) recommends that implementers and programmers follow the guidelines in this document concerning feature-test macros.

Implementers who provide a new standard feature should define a macro with the recommended name and value, in the same circumstances under which the feature is available (for example, taking into account relevant command-line options), to indicate the presence of support for that feature.

Programmers who wish to determine whether a feature is available in an implementation should base that determination on the state of the macro with the recommended name. (The absence of a tested feature may result in a program with decreased functionality, or the relevant functionality may be provided in a different way. A program that strictly depends on support for a feature can just try to use the feature unconditionally; presumably, on an implementation lacking necessary support, translation will fail.)

### Testing for the presence of a header: `__has_include`

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).

To solve this general problem, WG21 recommends that implementers provide, and programmers use, the `__has_include` feature.

#### Syntax

h-preprocessing-token:
  any preprocessing-token other than `>`

h-pp-tokens:
  h-preprocessing-token
  h-pp-tokens h-preprocessing-token

has-include-expression:
  `__has_include (` header-name `)`
  `__has_include (` string-literal `)`
  `__has_include ( <` h-pp-tokens `> )`

#### Semantics

In the first form of the has-include-expression, the parenthesized header-name 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.

A has-include-expression shall appear only in the controlling constant expression of a `#if` or `#elif` 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 has-include-expression is searched for as if that preprocessing token sequence were the pp-tokens in a `#include` directive, except that no further macro expansion is performed. If such a directive would not satisfy the syntactic requirements of a `#include` directive, the program is ill-formed. The has-include-expression is replaced by the pp-number `1` if the search for the source file succeeds, and by the pp-number `0` if the search fails.

The `#ifdef` and `#ifndef` directives, and the `defined` conditional inclusion operator, shall treat `__has_include` as if it were the name of a defined macro. The identifier `__has_include` shall not appear in any context not mentioned in this section.

#### Example

This demonstrates a way to include the header `<optional>` only if it is available.

    #ifdef __has_include
    #  if __has_include(<optional>)
    #    include <optional>
    #    define have_optional
    #  endif
    #endif

### Testing for the presence of an attribute: `__has_cpp_attribute`

Insert introductory text here.

#### Syntax

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

#### Semantics

A has-attribute-expression shall appear only in the controlling constant expression of a `#if` or `#elif` directive ([cpp.cond] 16.1). The has-attribute-expression is replaced by the pp-number 1 if the implementation supports an attribute with the specified name, and by the pp-number 0 otherwise.

The `#ifdef` and `#ifndef` directives, and the `defined` conditional inclusion operator, shall treat `__has_cpp_attribute` as if it were the name of a defined macro. The identifier `__has_cpp_attribute` shall not appear in any context not mentioned in this section.

#### Example

This demonstrates a way to use the attribute `[[deprecated]]` only if it is available.

    #ifdef __has_cpp_attribute
    #  if __has_cpp_attribute(deprecated)
    #    define ATTR_DEPRECATED(msg) [[deprecated(msg)]]
    #  else
    #    define ATTR_DEPRECATED(msg)
    #  endif
    #endif

### C++14 features

The following table itemizes all the changes that were made to the working draft for C++14 as specified in a WG21 technical document. (Changes that were made as specified in a core or library issue are not included.)

The table is sorted by the section of the standard primarily affected. The “Doc. No.” column links to the paper itself on the committee web site. The “Macro Name” column links to the relevant portion of the “Detailed explanation and rationale” section of this document.

For library features, the “Header“ column identifies the header that is expected to define the macro, although the macro may also be predefined. For language features, the macro must be predefined.

Significant changes to C++14
Doc. No. | Title | Primary Section | Macro Name | Value | Header
--- | --- | --- | --- | --- | ---
N3910 | What can signal handlers do? (CWG 1441) | 1.9-1.10 | none
N3927 | Definition of Lock-Free | 1.10 | none
N3472 | Binary Literals in the C++ Core Language | 2.14 | `__cpp_binary_literals` | 201304 | predefined
N3781 | Single-Quotation-Mark as a Digit Separator | 2.14 | `__cpp_digit_separators` | 201309 | predefined
N3323 | A Proposal to Tweak Certain C++ Contextual Conversions | 4 | none
N3648 | Wording Changes for Generalized Lambda-capture | 5.1 | `__cpp_init_captures` | 201304 | predefined
N3649 | Generic (Polymorphic) Lambda Expressions | 5.1 | `__cpp_generic_lambdas` | 201304 | predefined
N3664 | Clarifying Memory Allocation | 5.3 | none
N3778 | C++ Sized Deallocation | 5.3, 18.6 | `__cpp_sized_deallocation` | 201309 | predefined
N3624 | Core Issue 1512: Pointer comparison vs qualification conversions | 5.9, 5.10 | none
N3652 | Relaxing constraints on constexpr functions / constexpr member functions and implicit const | 5.19, 7.1 | `__cpp_constexpr` | 201304 | predefined
N3638 | Return type deduction for normal functions | 7.1 | `__cpp_decltype_auto` | 201304 | predefined
`__cpp_return_type_deduction` | 201304 | predefined
N3760 | [[deprecated]] attribute | 7.6 | `__has_cpp_attribute(deprecated)` | 1 | predefined
N3639 | Runtime-sized arrays with automatic storage duration | 8.3 | `__cpp_runtime_arrays` | 201304 | predefined
N3653 | Member initializers and aggregates | 8.5 | `__cpp_aggregate_nsdmi` | 201304 | predefined
N3667 | Drafting for Core 1402 | 12.8 | none
N3651 | Variable Templates | 14, 14.7 | `__cpp_variable_templates` | 201304 | predefined
N3669 | Fixing constexpr member functions without const | various | none
N3673 | C++ Library Working Group Ready Issues Bristol 2013 | various | none
N3658 | Compile-time integer sequences | 20 | `__cpp_lib_integer_sequence` | 201304 | `<utility>`
N3668 | exchange() utility function | 20 | `__cpp_lib_exchange_function` | 201304 | `<utility>`
N3471 | Constexpr Library Additions: utilities | 20.2-20.4 | none
N3670 | Wording for Addressing Tuples by Type | 20.2-20.4 | `__cpp_lib_tuples_by_type` | 201304 | `<utility>`
N3887 | Consistent Metafunction Aliases | 20.3-20.4 | `__cpp_lib_tuple_element_t` | 201402 | `<utility>`
N3672 | A proposal to add a utility class to represent optional objects | 20.5 | `__has_include(<optional>)` | 1 | predefined
N3656 | make_unique | 20.7 | `__cpp_lib_make_unique` | 201304 | `<memory>`
N3421 | Making Operator Functors greater<> | 20.8 | `__cpp_lib_transparent_operators` | 201210 | `<functional>`
N3462 | std::result_of and SFINAE | 20.9 | `__cpp_lib_result_of_sfinae` | 201210 | `<functional>`
N3545 | An Incremental Improvement to integral_constant | 20.9 | `__cpp_lib_integral_constant_callable` | 201304 | `<type_traits>`
N3655 | TransformationTraits Redux | 20.9 | `__cpp_lib_transformation_trait_aliases` | 201304 | `<type_traits>`
N3789 | Constexpr Library Additions: functional | 20.10 | none
LWG 2112 | User-defined classes that cannot be derived from | 20.10 | `__cpp_lib_has_is_final` ? | 201402 | `<type_traits>`
LWG 2247 | Type traits and std::nullptr_t | 20.10 | `__cpp_lib_has_is_null_pointer` ?? | 201309 | `<type_traits>`
N3469 | Constexpr Library Additions: chrono | 20.11 | none
N3642 | User-defined Literals for Standard Library Types | 20.11 | `__cpp_lib_chrono_udls` | 201304 | `<chrono>`
21.7 | `__cpp_lib_string_udls` | 201304 | `<string>`
N3662 | C++ Dynamic Arrays | 23.2, 23.3 | `__has_include(<dynarray>)` | 1 | predefined
N3470 | Constexpr Library Additions: containers | 23.3 | none
N3657 | Adding heterogeneous comparison lookup to associative containers | 23.4 | `__cpp_lib_generic_associative_lookup` | 201304 | `<map>` `<set>`
N3644 | Null Forward Iterators | 24.2 | `__cpp_lib_null_iterators` | 201304 | `<iterator>`
LWG 2285 | make_reverse_iterator | 24.5 | `__cpp_lib_has_make_reverse_iterator` ?? | 201402 | `<iterator>`
N3671 | Making non-modifying sequence operations more robust | 25.2 | `__cpp_lib_robust_nonmodifying_seq_ops` | 201304 | `<algorithm>`
N3779 | User-defined Literals for std::complex | 26.4 | `__cpp_lib_complex_udls` | 201309 | `<complex>`
N3924 | Discouraging rand() in C++14 | 26.8 | none
N3654 | Quoted Strings Library Proposal | 27.7 | `__cpp_lib_quoted_string_io` | 201304 | `<iomanip>`
LWG 2249 | Remove gets from <cstdio> | 27.9 | none ?
N3786 | Prohibiting "out of thin air" results in C++14 | 29.3 | none
N3659 | Shared locking in C++ | 30.4 | `__cpp_lib_shared_mutex` Shall we keep this definition, for stability, or remove it, since it kind of misses the point? | 201304 | `<mutex>`
`__has_include(<shared_mutex>)` | 1 | predefined
N3891 | A proposal to rename shared_mutex to shared_timed_mutex | 30.4 | `__cpp_lib_shared_mutex` | 201402 | `<shared_mutex>`
N3776 | Wording for ~future | 30.6 | none

Features in the first CD of C++14, subsequently removed to a Technical Specification
Doc. No. | Title | Primary Section | Macro Name | Value | Header
--- | --- | --- | --- | --- | ---
N3639 | Runtime-sized arrays with automatic storage duration | 8.3 | `__cpp_runtime_arrays` | 201304 | predefined
N3672 | A proposal to add a utility class to represent optional objects | 20.5 | `__has_include(<optional>)` | 1 | predefined
N3662 | C++ Dynamic Arrays | 23.2, 23.3 | `__has_include(<dynarray>)` | 1 | predefined

### C++11 features

STUB: this table should be considered a very rough, preliminary, incomplete draft

Significant features of C++11
Doc. No. | Title | Primary Section | Macro name | Value | Header
--- | --- | --- | --- | --- | ---
N2249 | New Character Types in C++ | 2.13 | `__cpp_unicode_characters` | 200704 | predefined
N2442 | Raw and Unicode String Literals Unified Proposal | 2.13 | `__cpp_raw_strings` | 200710 | predefined
`__cpp_unicode_literals` | 200710 | predefined
N2765 | User-defined Literals | 2.13, 13.5 | `__cpp_user_defined_literals` | 200809 | predefined
N2927 | New wording for C++0x lambdas | 5.1 | `__cpp_lambdas` | 200907 | predefined
N2235 | Generalized Constant Expressions | 5.19, 7.1 | `__cpp_constexpr` | 200704 | predefined
N1720 | Proposal to Add Static Assertions to the Core Language | 7 | `__cpp_static_assert` | 200410 | predefined
N2343 | Decltype | 7.1 | `__cpp_decltype` | 200707 | predefined
N2761 | Towards support for attributes in C++ | 7.6 | `__cpp_attributes` | 200809 | predefined
N2118 | A Proposal to Add an Rvalue Reference to the C++ Language | 8.3 | `__cpp_rvalue_references` | 200610 | predefined
N2242 | Proposed Wording for Variadic Templates | 8.3, 14 | `__cpp_variadic_templates` | 200704 | predefined
N2258 | Template Aliases | 14.5 | `__cpp_alias_templates` | 200704 | predefined

### Conditionally-supported constructs

STUB

### C++98 features

STUB: especially for exception handling and RTTI

## Detailed explanation and rationale

### C++14 features

Many of the examples here have been shamelessly and almost brainlessly plagiarized from the cited paper. Assistance with improving examples is solicited.

#### N3323: A Proposal to Tweak Certain C++ Contextual Conversions

This paper specifies a small change that is considered to be more of a bug fix than a new feature, so no macro is considered necessary.

#### N3421: Making Operator Functors greater<>

Example:

    #if __cpp_lib_transparent_operators
    	sort(v.begin(), v.end(), greater<>());
    #else
    	sort(v.begin(), v.end(), greater<valueType>());
    #endif

#### N3462: std::result_of and SFINAE

Example:

    template<typename A>
    #if __cpp_lib_result_of_sfinae
      typename std::result_of<inc(A)>::type
    #else
      decltype(std::declval<inc>()(std::declval<A>()))
    #endif
    try_inc(A a);

#### N3469: Constexpr Library Additions: chrono
N3470: Constexpr Library Additions: containers
N3471: Constexpr Library Additions: utilities

These papers just add `constexpr` to the declarations of several dozen library functions in various headers. It is not clear that a macro to test for the presence of these changes would be sufficiently useful to be worthwhile.

#### N3472: Binary Literals in the C++ Core Language

Example:

    int const packed_zero_to_three =
    #if __cpp_binary_literals
    	0b00011011;
    #else
    	0x1B;
    #endif

#### N3545: An Incremental Improvement to integral_constant

Example:

    constexpr bool arithmetic =
    #if __cpp_lib_integral_constant_callable
    	std::is_arithmetic<T>{}();
    #else
    	static_cast<bool>(std::is_arithmetic<T>{});
    #endif

#### N3624: Core Issue 1512: Pointer comparison vs qualification conversions

This paper contained the wording changes to resolve a core issue. It did not introduce a new feature, so no macro is considered necessary.

#### N3638: Return type deduction for normal functions

This paper describes two separate features: the ability to deduce the return type of a function from the return statements contained in its body, and the ability to use `decltype(auto)`. These features can be implemented independently, so a macro is recommended for each.

Examples:

    template<typename T>
    auto abs(T x)
    #ifndef __cpp_return_type_deduction
    	-> decltype(x < 0 ? -x : x)
    #endif
    {
    	return x < 0 ? -x : x;
    }

#### N3639: Runtime-sized arrays with automatic storage duration

This was removed from C++14 to TS 19569.

Example:

    #if __cpp_runtime_arrays
    	T local_buffer[n];	// more efficient than vector
    #else
    	std::vector<T> local_buffer(n);
    #endif

#### N3642: User-defined Literals for Standard Library Types

This paper specifies user-defined literal operators for two different standard library types, which could be implemented independently. Furthermore, user-defined literal operators are expected to be added later for at least one other library type. So for consistency and flexibility, each type is given its own macro.

Examples:

#### N3644: Null Forward Iterators

Example:

#### N3648: Wording Changes for Generalized Lambda-capture

Example:

#### N3649: Generic (Polymorphic) Lambda Expressions

Example:

#### N3651: Variable Templates

Example:

#### N3652: Relaxing constraints on constexpr functions / constexpr member functions and implicit const

The major change proposed by this paper is considered to be strictly a further development of the `constexpr` feature of C++11. Consequently, the recommendation here is to give an increased value to the macro indicating C++11 support for `constexpr`.

Example:

#### N3653: Member initializers and aggregates

Example:

#### N3654: Quoted Strings Library Proposal

Example:

#### N3655: TransformationTraits Redux

Example:

#### N3656: make_unique

Example:

#### N3657: Adding heterogeneous comparison lookup to associative containers

Example:

#### N3658: Compile-time integer sequences

Example:

#### N3659: Shared locking in C++

Example:

#### N3662: C++ Dynamic Arrays

This was removed from C++14 to TS 19569.

For new headers, we have a long-term solution that uses `__has_include`. There was not sufficient support and a number of objections against adding macros to existing library header files, as there was not consensus on a place to put them.

There is also a simple workaround for users that are not using libraries that define the header file: supplying their own header that is further down the search path than the library headers.

Example:

    #if __has_include(<dynarray>)
    #include <dynarray>

    // code that uses std::dynarray
    #endif

#### N3664: Clarifying Memory Allocation

The substantive change in this paper just relaxes a restriction on implementations. There is no new feature for a programmer to use, so no macro is considered necessary.

#### N3667: Drafting for Core 1402

This paper contained the wording changes to resolve a core issue. It did not introduce a new feature, so no macro is considered necessary.

#### N3668: exchange() utility function

Example:

#### N3669: Fixing constexpr member functions without const

This paper contained the wording changes to ensure that a minor change proposed by N3652 did not impact the standard library. It did not introduce a new feature, so no macro is considered necessary.

#### N3670: Wording for Addressing Tuples by Type

Example:

#### N3671: Making non-modifying sequence operations more robust

Example:

#### N3672: A proposal to add a utility class to represent optional objects

This was removed from C++14 to TS 19568.

See N3662 for rationale.

Example:

    #if __has_include(<optional>)
    #include <optional>

    // code that uses std::optional
    #endif

#### N3673: C++ Library Working Group Ready Issues Bristol 2013

This paper was just a collection of library issues. It did not introduce a new feature, so no macro is considered necessary.

#### N3760: [[deprecated]] attribute

Rationale needed.

Example:

#### N3776: Wording for ~future

The change made by this paper is a bug fix, and no macro is considered necessary.

#### N3778: C++ Sized Deallocation

Example:

#### N3779: User-defined Literals for std::complex

Example:

#### N3781: Single-Quotation-Mark as a Digit Separator

Example:

#### N3786: Prohibiting "out of thin air" results in C++14

The change made by this paper is a bug fix, and no macro is considered necessary.

#### N3789: Constexpr Library Additions: functional

See N3471 for rationale.

#### N3887: Consistent Metafunction Aliases

Example:

#### N3891: A proposal to rename shared_mutex to shared_timed_mutex

Example:

#### N3910: What can signal handlers do? (CWG 1441)

The change made by this paper is a bug fix, and no macro is considered necessary.

#### N3924: Discouraging rand() in C++14

The change made by this paper is not normative; no macro is necessary.

#### N3927: Definition of Lock-Free

The change made by this paper is a bug fix, and no macro is considered necessary.

#### LWG issue 2112: User-defined classes that cannot be derived from

This is a quote from Richard:

Libraries that want to do EBO could reasonably want to use `is_final && is_empty` if `is_final` exists, and fall back to just using `is_empty` otherwise.

#### LWG issue 2247: Type traits and std::nullptr_t

Added by default.

Example:

#### LWG issue 2249: Remove gets from <cstdio>

Since portable, well-written code does not use the `gets` function at all, there is no need for a macro to indicate whether it is available.

#### LWG issue 2285: make_reverse_iterator

Added by default.

Example:

## Revision history

Date | Document | Description
--- | --- | ---
2014-05-22 | N4030 | Updated for changes from Chicago and Issaquah meetings Added `__has_cpp_attribute` test
2013-11-27 | SD-6 | Initial publication No substantive changes from N3745
2013-08-28 | N3745 | Endorsed by WG21 membership
2013-06-27 | N3694 | Initial draft