1[/
2 / Copyright (c) 2008 Howard Hinnant
3 / Copyright (c) 2009-2012 Vicente J. Botet Escriba
4 /
5 / Distributed under the Boost Software License, Version 1.0. (See accompanying
6 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7 /]
8
9[article Declval
10    [quickbook 1.5]
11    [authors [Hinnant, Howard]]
12    [authors [Botet Escriba, Vicente J.]]
13    [copyright 2008 Howard Hinnant]
14    [copyright 2009-2012 Vicente J. Botet Escriba]
15    [license
16        Distributed under the Boost Software License, Version 1.0.
17        (See accompanying file LICENSE_1_0.txt or copy at
18        [@http://www.boost.org/LICENSE_1_0.txt])
19    ]
20]
21
22[/===============]
23[section Overview]
24[/===============]
25
26The motivation for `declval` was introduced in [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2958.html#Value N2958:
27Moving Swap Forward]. Here follows a rewording of this chapter.
28
29With the provision of decltype, late-specified return types, and default template-arguments for function templates a
30new generation of SFINAE patterns will emerge to at least partially compensate the lack of concepts on the C++0x timescale.
31Using this technique, it is sometimes necessary to obtain an object of a known type in a non-using context, e.g. given the declaration
32
33  template<class T>
34  T&& declval(); // not used
35
36as part of the function template declaration
37
38  template<class To, class From>
39  decltype(static_cast<To>(declval<From>())) convert(From&&);
40
41or as part of a class template definition
42
43  template<class> class result_of;
44
45  template<class Fn, class... ArgTypes>
46  struct result_of<Fn(ArgTypes...)>
47  {
48    typedef decltype(declval<Fn>()(declval<ArgTypes>()...)) type;
49  };
50
51The role of the function template declval() is a transformation of a type T into a value without using or evaluating this function.
52The name is supposed to direct the reader's attention to the fact that the expression `declval<T>()` is an lvalue if and only if
53T is an lvalue-reference, otherwise an rvalue. To extend the domain of this function we can do a bit better by changing its declaration to
54
55  template<class T>
56  typename std::add_rvalue_reference<T>::type declval(); // not used
57
58which ensures that we can also use cv void as template parameter. The careful reader might have noticed that `declval()`
59already exists under the name create() as part of the definition of the semantics of the type trait is_convertible in the C++0x standard.
60
61The provision of a new library component that allows the production of values in unevaluated expressions is considered
62important to realize constrained templates in C++0x where concepts are not available.
63This extremely light-weight function is expected to be part of the daily tool-box of the C++0x programmer.
64
65[endsect]
66
67
68[/=================]
69[section:reference Reference ]
70[/=================]
71
72`#include <boost/utility/declval.hpp>`
73
74    namespace boost {
75
76        template <typename T>
77        typename add_rvalue_reference<T>::type declval() noexcept; // as unevaluated operand
78
79    }  // namespace boost
80
81
82The library provides the function template declval to simplify the definition of expressions which occur as unevaluated operands.
83
84        template <typename T>
85        typename add_rvalue_reference<T>::type declval();
86
87[*Remarks:] If this function is used, the program is ill-formed.
88
89[*Remarks:] The template parameter T of declval may be an incomplete type.
90
91[*Example:]
92
93    template <class To, class From>
94    decltype(static_cast<To>(declval<From>())) convert(From&&);
95
96Declares a function template convert which only participates in overloading if the type From can be explicitly converted to type To.
97
98[endsect]
99
100[/===============]
101[section History]
102[/===============]
103
104[heading boost 1.50]
105
106Fixes:
107
108* [@http://svn.boost.org/trac/boost/ticket/6570 #6570] Adding noexcept to boost::declval.
109
110[endsect]
111
112
113
114
115