21 Metaprogramming library [meta]

21.3 Metaprogramming and type traits [type.traits]

21.3.8 Transformations between types [meta.trans]

21.3.8.1 General [meta.trans.general]

Subclause [meta.trans] contains templates that may be used to transform one type to another following some predefined rule.

Each of the templates in [meta.trans] shall be a Cpp17TransformationTrait ([meta.rqmts]).

21.3.8.2 Const-volatile modifications [meta.trans.cv]

The templates specified in Table 54 add or remove cv-qualifications ([basic.type.qualifier]).

Table 54: Const-volatile modifications [tab:meta.trans.cv]

🔗	Template	Comments
🔗	template<class T> struct remove_const;	The member typedef type denotes the type formed by removing any top-level const-qualifier from T. [Example 1: remove_const_t<const volatile int> evaluates to volatile int, whereas remove_const_t<const int> evaluates to const int. — end example]
🔗	template<class T> struct remove_volatile;	The member typedef type denotes the type formed by removing any top-level volatile-qualifier from T. [Example 2: remove_volatile_t<const volatile int> evaluates to const int, whereas remove_volatile_t<volatile int> evaluates to volatile int. — end example]
🔗	template<class T> struct remove_cv;	The member typedef type denotes the type formed by removing any top-level cv-qualifiers from T. [Example 3: remove_cv_t<const volatile int> evaluates to int, whereas remove_cv_t<const volatile int> evaluates to const volatile int. — end example]
🔗	template<class T> struct add_const;	If T is a reference, function, or top-level const-qualified type, then type denotes T, otherwise T const.
🔗	template<class T> struct add_volatile;	If T is a reference, function, or top-level volatile-qualified type, then type denotes T, otherwise T volatile.
🔗	template<class T> struct add_cv;	The member typedef type denotes add_const_t<add_volatile_t<T>>.

21.3.8.3 Reference modifications [meta.trans.ref]

The templates specified in Table 55 add or remove references.

Table 55: Reference modifications [tab:meta.trans.ref]

🔗	Template	Comments
🔗	template<class T> struct remove_reference;	If T has type “reference to T1” then the member typedef type denotes T1; otherwise, type denotes T.
🔗	template<class T> struct add_lvalue_reference;	If T is a referenceable type ([defns.referenceable]) then the member typedef type denotes T&; otherwise, type denotes T. [Note 1: This rule reflects the semantics of reference collapsing ([dcl.ref]). — end note]
🔗	template<class T> struct add_rvalue_reference;	If T is a referenceable type then the member typedef type denotes T&&; otherwise, type denotes T. [Note 2: This rule reflects the semantics of reference collapsing ([dcl.ref]). For example, when a type T is a reference type T1&, the type add_rvalue_reference_t<T> is not an rvalue reference. — end note]

21.3.8.4 Sign modifications [meta.trans.sign]

The templates specified in Table 56 convert an integer type to its corresponding signed or unsigned type.

Table 56: Sign modifications [tab:meta.trans.sign]

🔗	Template	Comments
🔗	template<class T> struct make_signed;	If T is a (possibly cv-qualified) signed integer type ([basic.fundamental]) then the member typedef type denotes T; otherwise, if T is a (possibly cv-qualified) unsigned integer type then type denotes the corresponding signed integer type, with the same cv-qualifiers as T; otherwise, type denotes the signed integer type with smallest rank ([conv.rank]) for which sizeof(T) == sizeof(type), with the same cv-qualifiers as T. Mandates: T is an integral or enumeration type other than cv bool.
🔗	template<class T> struct make_unsigned;	If T is a (possibly cv-qualified) unsigned integer type ([basic.fundamental]) then the member typedef type denotes T; otherwise, if T is a (possibly cv-qualified) signed integer type then type denotes the corresponding unsigned integer type, with the same cv-qualifiers as T; otherwise, type denotes the unsigned integer type with smallest rank ([conv.rank]) for which sizeof(T) == sizeof(type), with the same cv-qualifiers as T. Mandates: T is an integral or enumeration type other than cv bool.

21.3.8.5 Array modifications [meta.trans.arr]

The templates specified in Table 57 modify array types.

Table 57: Array modifications [tab:meta.trans.arr]

🔗	Template	Comments
🔗	template<class T> struct remove_extent;	If T is a type “array of U”, the member typedef type denotes U, otherwise T. [Note 1: For multidimensional arrays, only the first array dimension is removed. For a type “array of const U”, the resulting type is const U. — end note]
🔗	template<class T> struct remove_all_extents;	If T is “multidimensional array of U”, the resulting member typedef type denotes U, otherwise T.

[Example 1: // the following assertions hold: static_assert(is_same_v<remove_extent_t<int>, int>); static_assert(is_same_v<remove_extent_t<int[2]>, int>); static_assert(is_same_v<remove_extent_t<int[2][3]>, int[3]>); static_assert(is_same_v<remove_extent_t<int[][3]>, int[3]>); — end example]

[Example 2: // the following assertions hold: static_assert(is_same_v<remove_all_extents_t<int>, int>); static_assert(is_same_v<remove_all_extents_t<int[2]>, int>); static_assert(is_same_v<remove_all_extents_t<int[2][3]>, int>); static_assert(is_same_v<remove_all_extents_t<int[][3]>, int>); — end example]

21.3.8.6 Pointer modifications [meta.trans.ptr]

The templates specified in Table 58 add or remove pointers.

Table 58: Pointer modifications [tab:meta.trans.ptr]

🔗	Template	Comments
🔗	template<class T> struct remove_pointer;	If T has type “(possibly cv-qualified) pointer to T1” then the member typedef type denotes T1; otherwise, it denotes T.
🔗	template<class T> struct add_pointer;	If T is a referenceable type ([defns.referenceable]) or a cv void type then the member typedef type denotes remove_reference_t<T>*; otherwise, type denotes T.

21.3.8.7 Other transformations [meta.trans.other]

The templates specified in Table 59 perform other modifications of a type.

Table 59: Other transformations [tab:meta.trans.other]

🔗	Template	Comments
🔗	template<class T> struct type_identity;	The member typedef type denotes T.
🔗	template<class T> struct remove_cvref;	The member typedef type denotes remove_cv_t<remove_reference_t<T>>.
🔗	template<class T> struct decay;	Let U be remove_reference_t<T>. If is_array_v<U> is true, the member typedef type denotes remove_extent_t<U>. If is_function_v<U> is true, the member typedef type denotes add_pointer_t<U>. Otherwise the member typedef type denotes remove_cv_t<U>. [Note 1: This behavior is similar to the lvalue-to-rvalue ([conv.lval]), array-to-pointer ([conv.array]), and function-to-pointer ([conv.func]) conversions applied when an lvalue is used as an rvalue, but also strips cv-qualifiers from class types in order to more closely model by-value argument passing. — end note*]
🔗	template<bool B, class T = void> struct enable_if;	If B is true, the member typedef type denotes T; otherwise, there shall be no member type.
🔗	template<bool B, class T, class F> struct conditional;	If B is true, the member typedef type denotes T. If B is false, the member typedef type denotes F.
🔗	template<class... T> struct common_type;	Unless this trait is specialized, the member type is defined or omitted as specified below. If it is omitted, there shall be no member type. Each type in the template parameter pack T shall be complete, cv void, or an array of unknown bound.
🔗	template<class, class, template<class> class, template<class> class> struct basic_common_reference;	Unless this trait is specialized, there shall be no member type.
🔗	template<class... T> struct common_reference;	The member typedef-name type is defined or omitted as specified below. Each type in the parameter pack T shall be complete or cv void.
🔗	template<class T> struct underlying_type;	If T is an enumeration type, the member typedef type denotes the underlying type of T ([dcl.enum]); otherwise, there is no member type. Mandates: T is not an incomplete enumeration type.
🔗	template<class Fn, class... ArgTypes> struct invoke_result;	If the expression INVOKE(declval<Fn>(), declval<ArgTypes>()...) ([func.require]) is well-formed when treated as an unevaluated operand ([expr.context]), the member typedef type denotes the type decltype(INVOKE(declval<Fn>(), declval<ArgTypes>()...)); otherwise, there shall be no member type. Access checking is performed as if in a context unrelated to Fn and ArgTypes. Only the validity of the immediate context of the expression is considered. [Note 2: The compilation of the expression can result in side effects such as the instantiation of class template specializations and function template specializations, the generation of implicitly-defined functions, and so on. Such side effects are not in the “immediate context” and can result in the program being ill-formed. — end note] Preconditions: Fn and all types in the template parameter pack ArgTypes are complete types, cv void, or arrays of unknown bound.
🔗	template<class T> struct unwrap_reference;	If T is a specialization reference_wrapper<X> for some type X, the member typedef type of unwrap_reference<T> denotes X&, otherwise type denotes T.
🔗	template<class T> unwrap_ref_decay;	The member typedef type of unwrap_ref_decay<T> denotes the type unwrap_reference_t<decay_t<T>>.

In addition to being available via inclusion of the <type_traits> header, the templates unwrap_reference, unwrap_ref_decay, unwrap_reference_t, and unwrap_ref_decay_t are available when the header <functional> ([functional.syn]) is included.

Let:

(3.1)
CREF(A) be add_lvalue_reference_t<const remove_reference_t<A>>,
(3.2)
XREF(A) denote a unary alias template T such that T<U> denotes the same type as U with the addition of A's cv and reference qualifiers, for a non-reference cv-unqualified type U,
(3.3)
COPYCV(FROM, TO) be an alias for type TO with the addition of FROM's top-level cv-qualifiers,
[Example 1:
COPYCV(const int, volatile short) is an alias for const volatile short.
— end example]
(3.4)
COND-RES(X, Y) be decltype(false ? declval<X(&)()>()() : declval<Y(&)()>()()).

Given types A and B, let X be remove_reference_t<A>, let Y be remove_reference_t<B>, and let COMMON-REF(A, B) be:

(3.5)
If A and B are both lvalue reference types, COMMON-REF(A, B) is COND-RES(COPYCV(X, Y) &, COPYCV(Y, X) &) if that type exists and is a reference type.
(3.6)
Otherwise, let C be remove_reference_t<COMMON-REF(X&, Y&)>&&.

If A and B are both rvalue reference types, C is well-formed, and is_convertible_v<A, C> && is_convertible_v<B, C> is true, then COMMON-REF(A, B) is C.
(3.7)
Otherwise, let D be COMMON-REF(const X&, Y&).

If A is an rvalue reference and B is an lvalue reference and D is well-formed and is_convertible_v<A, D> is true, then COMMON-REF(A, B) is D.
(3.8)
Otherwise, if A is an lvalue reference and B is an rvalue reference, then COMMON-REF(A, B) is COMMON-REF(B, A).
(3.9)
Otherwise, COMMON-REF(A, B) is ill-formed.

If any of the types computed above is ill-formed, then COMMON-REF(A, B) is ill-formed.

For the common_type trait applied to a template parameter pack T of types, the member type shall be either defined or not present as follows:

(4.1)
If sizeof...(T) is zero, there shall be no member type.
(4.2)
If sizeof...(T) is one, let T0 denote the sole type constituting the pack T.

The member typedef-name type shall denote the same type, if any, as common_type_t<T0, T0>; otherwise there shall be no member type.
(4.3)
If sizeof...(T) is two, let the first and second types constituting T be denoted by T1 and T2, respectively, and let D1 and D2 denote the same types as decay_t<T1> and decay_t<T2>, respectively.
- (4.3.1)
  If is_same_v<T1, D1> is false or is_same_v<T2, D2> is false, let C denote the same type, if any, as common_type_t<D1, D2>.
- (4.3.2)
  [Note 3:
  None of the following will apply if there is a specialization common_type<D1, D2>.
  — end note]
- (4.3.3)
  Otherwise, if decay_t<decltype(false ? declval<D1>() : declval<D2>())> denotes a valid type, let C denote that type.
- (4.3.4)
  Otherwise, if COND-RES(CREF(D1), CREF(D2)) denotes a type, let C denote the type decay_t<COND-RES(CREF(D1), CREF(D2))>.
In either case, the member typedef-name type shall denote the same type, if any, as C.

Otherwise, there shall be no member type.
(4.4)
If sizeof...(T) is greater than two, let T1, T2, and R, respectively, denote the first, second, and (pack of) remaining types constituting T.

Let C denote the same type, if any, as common_type_t<T1, T2>.

If there is such a type C, the member typedef-name type shall denote the same type, if any, as common_type_t<C, R...>.

Otherwise, there shall be no member type.

Notwithstanding the provisions of [meta.type.synop], and pursuant to [namespace.std], a program may specialize common_type<T1, T2> for types T1 and T2 such that is_same_v<T1, decay_t<T1>> and is_same_v<T2, decay_t<T2>> are each true.

[Note 4:

Such specializations are needed when only explicit conversions are desired between the template arguments.

— end note]

Such a specialization need not have a member named type, but if it does, the qualified-id common_type<T1, T2>::type shall denote a cv-unqualified non-reference type to which each of the types T1 and T2 is explicitly convertible.

Moreover, common_type_t<T1, T2> shall denote the same type, if any, as does common_type_t<T2, T1>.

No diagnostic is required for a violation of this Note's rules.

For the common_reference trait applied to a parameter pack T of types, the member type shall be either defined or not present as follows:

(6.1)
If sizeof...(T) is zero, there shall be no member type.
(6.2)
Otherwise, if sizeof...(T) is one, let T0 denote the sole type in the pack T.

The member typedef type shall denote the same type as T0.
(6.3)
Otherwise, if sizeof...(T) is two, let T1 and T2 denote the two types in the pack T.
Then
- (6.3.1)
  Let R be COMMON-REF(T1, T2).
  
  If T1 and T2 are reference types, R is well-formed, and is_convertible_v<add_pointer_t<T1>, add_pointer_t<R>> && is_convertible_v<add_pointer_t<T2>, add_pointer_t<R>> is true, then the member typedef type denotes R.
- (6.3.2)
  Otherwise, if basic_common_reference<remove_cvref_t<T1>, remove_cvref_t<T2>, XREF(T1), XREF(T2)>::type is well-formed, then the member typedef type denotes that type.
- (6.3.3)
  Otherwise, if COND-RES(T1, T2) is well-formed, then the member typedef type denotes that type.
- (6.3.4)
  Otherwise, if common_type_t<T1, T2> is well-formed, then the member typedef type denotes that type.
- (6.3.5)
  Otherwise, there shall be no member type.
(6.4)
Otherwise, if sizeof...(T) is greater than two, let T1, T2, and Rest, respectively, denote the first, second, and (pack of) remaining types comprising T.

Let C be the type common_reference_t<T1, T2>.
Then:
- (6.4.1)
  If there is such a type C, the member typedef type shall denote the same type, if any, as common_reference_t<C, Rest...>.
- (6.4.2)
  Otherwise, there shall be no member type.

Notwithstanding the provisions of [meta.type.synop], and pursuant to [namespace.std], a program may partially specialize basic_common_reference<T, U, TQual, UQual> for types T and U such that is_same_v<T, decay_t<T>> and is_same_v<U, decay_t<U>> are each true.

[Note 5:

Such specializations can be used to influence the result of common_reference, and are needed when only explicit conversions are desired between the template arguments.

— end note]

Such a specialization need not have a member named type, but if it does, the qualified-id basic_common_reference<T, U, TQual, UQual>::type shall denote a type to which each of the types TQual<T> and UQual<U> is convertible.

Moreover, basic_common_reference<T, U, TQual, UQual>::type shall denote the same type, if any, as does basic_common_reference<U, T, UQual, TQual>::type.

No diagnostic is required for a violation of these rules.

[Example 2:

Given these definitions: using PF1 = bool (&)(); using PF2 = short (*)(long); struct S { operator PF2() const; double operator()(char, int&); void fn(long) const; char data; }; using PMF = void (S::*)(long) const; using PMD = char S::*; the following assertions will hold: static_assert(is_same_v<invoke_result_t<S, int>, short>); static_assert(is_same_v<invoke_result_t<S&, unsigned char, int&>, double>); static_assert(is_same_v<invoke_result_t<PF1>, bool>); static_assert(is_same_v<invoke_result_t<PMF, unique_ptr<S>, int>, void>); static_assert(is_same_v<invoke_result_t<PMD, S>, char&&>); static_assert(is_same_v<invoke_result_t<PMD, const S*>, const char&>);

— end example]