From 987b01b28ca1d07992e836d10d9c0d78c9d2e587 Mon Sep 17 00:00:00 2001 From: Peter Dimov Date: Mon, 8 Jun 2015 00:22:03 +0300 Subject: [PATCH] Add documentation for declval. --- doc/declval.qbk | 120 +++++--------------------------------------- doc/type_traits.qbk | 2 + 2 files changed, 15 insertions(+), 107 deletions(-) diff --git a/doc/declval.qbk b/doc/declval.qbk index 7bf5cb5..7b151ae 100644 --- a/doc/declval.qbk +++ b/doc/declval.qbk @@ -1,115 +1,21 @@ -[/ - / Copyright (c) 2008 Howard Hinnant - / Copyright (c) 2009-20012 Vicente J. Botet Escriba - / - / Distributed under the Boost Software License, Version 1.0. (See accompanying - / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) - /] - -[article Declval - [quickbook 1.5] - [authors [Hinnant, Howard]] - [authors [Botet Escriba, Vicente J.]] - [copyright 2008 Howard Hinnant] - [copyright 2009-2012 Vicente J. Botet Escriba] - [license - Distributed under the Boost Software License, Version 1.0. - (See accompanying file LICENSE_1_0.txt or copy at - [@http://www.boost.org/LICENSE_1_0.txt]) - ] +[/ + Copyright 2015 Peter Dimov. + Distributed under the Boost Software License, Version 1.0. + (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt). ] -[/===============] -[section Overview] -[/===============] +[section:declval declval] -The motivation for `declval` was introduced in [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2958.html#Value N2958: -Moving Swap Forward]. Here follows a rewording of this chapter. + template + typename add_rvalue_reference::type declval() noexcept; // as unevaluated operand -With the provision of decltype, late-specified return types, and default template-arguments for function templates a -new generation of SFINAE patterns will emerge to at least partially compensate the lack of concepts on the C++0x timescale. -Using this technique, it is sometimes necessary to obtain an object of a known type in a non-using context, e.g. given the declaration +__std_ref C++11 20.2.4 [declval]. - template - T&& declval(); // not used - -as part of the function template declaration +__header ` #include ` or ` #include ` - template - decltype(static_cast(declval())) convert(From&&); - -or as part of a class template definition - - template class result_of; - - template - struct result_of - { - typedef decltype(declval()(declval()...)) type; - }; - -The role of the function template declval() is a transformation of a type T into a value without using or evaluating this function. -The name is supposed to direct the reader's attention to the fact that the expression `declval()` is an lvalue if and only if -T 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 - - template - typename std::add_rvalue_reference::type declval(); // not used - -which ensures that we can also use cv void as template parameter. The careful reader might have noticed that `declval()` -already exists under the name create() as part of the definition of the semantics of the type trait is_convertible in the C++0x standard. - -The provision of a new library component that allows the production of values in unevaluated expressions is considered -important to realize constrained templates in C++0x where concepts are not available. -This extremely light-weight function is expected to be part of the daily tool-box of the C++0x programmer. +The function template `declval` is used when a value of a certain type is required in +a type computation context. For example, the type of the result of adding an `int` and +a `float` can be obtained with the expression `decltype( declval() + declval() )`. [endsect] - - -[/=================] -[section:reference Reference ] -[/=================] - -`#include ` - - namespace boost { - - template - typename add_rvalue_reference::type declval() noexcept; // as unevaluated operand - - } // namespace boost - - -The library provides the function template declval to simplify the definition of expressions which occur as unevaluated operands. - - template - typename add_rvalue_reference::type declval(); - -[*Remarks:] If this function is used, the program is ill-formed. - -[*Remarks:] The template parameter T of declval may be an incomplete type. - -[*Example:] - - template - decltype(static_cast(declval())) convert(From&&); - -Declares a function template convert which only participates in overloading if the type From can be explicitly converted to type To. - -[endsect] - -[/===============] -[section History] -[/===============] - -[heading boost 1.50] - -Fixes: - -* [@http://svn.boost.org/trac/boost/ticket/6570 #6570] Adding noexcept to boost::declval. - - -[endsect] - - - - diff --git a/doc/type_traits.qbk b/doc/type_traits.qbk index 4e43921..c0046a1 100644 --- a/doc/type_traits.qbk +++ b/doc/type_traits.qbk @@ -134,6 +134,7 @@ [def __copy_cv [link boost_typetraits.reference.copy_cv copy_cv]] [def __type_identity [link boost_typetraits.reference.type_identity type_identity]] +[def __declval [link boost_typetraits.reference.declval declval]] A printer-friendly [@http://sourceforge.net/projects/boost/files/boost-docs/ PDF version of this manual is also available]. @@ -188,6 +189,7 @@ that is the result of the transformation. [include common_type.qbk] [include copy_cv.qbk] [include decay.qbk] +[include declval.qbk] [include extent.qbk] [include floating_point_promotion.qbk] [include function_traits.qbk]