ceph/src/boost/libs/type_traits/doc/has_dereference.qbk

   1 [/
   2   (C) Copyright 2009-2011  Frederic Bron.
   3   Distributed under the Boost Software License, Version 1.0.
   4   (See accompanying file LICENSE_1_0.txt or copy at
   5   http://www.boost.org/LICENSE_1_0.txt).
   6 ]
   7
   8 [section:has_dereference has_dereference]
   9    template <class Rhs, class Ret=dont_care>
  10    struct has_dereference : public __tof {};
  11
  12 __inherit
  13 If (i) `rhs` of type `Rhs` can be used in expression `*rhs`,
  14 and (ii) `Ret=dont_care` or the result of expression `*rhs` is convertible to `Ret`
  15 then inherits from __true_type,
  16 otherwise inherits from __false_type.
  17
  18 The default behaviour (`Ret=dont_care`) is to not check for the return value of prefix `operator*`.
  19 If `Ret` is different from the default `dont_care` type, the return value is checked to be convertible to `Ret`.
  20 Convertible to `Ret` means that the return value of the operator can be used as argument to a function expecting `Ret`:
  21 ``
  22 void f(Ret);
  23 Rhs rhs;
  24 f(*rhs); // is valid if has_dereference<Rhs, Ret>::value==true
  25 ``
  26 If `Ret=void`, the return type is checked to be exactly `void`.
  27
  28 __header `#include <boost/type_traits/has_dereference.hpp>` or `#include <boost/type_traits/has_operator.hpp>` or `#include <boost/type_traits.hpp>`
  29
  30 [has_binary_operator_compat]
  31
  32 __examples
  33
  34 [:`has_dereference<Rhs, Ret>::value_type` is the type `bool`.]
  35 [:`has_dereference<Rhs, Ret>::value` is a `bool` integral constant expression.]
  36 [:`has_dereference<int*>::value` is a `bool` integral constant expression that evaluates to `true`.]
  37 [:`has_dereference<long*>` inherits from `__true_type`.]
  38
  39
  40 [:`has_dereference<int*, int>` inherits from `__true_type`.]
  41 [:`has_dereference<int*, const int>` inherits from `__true_type`.]
  42 [:`has_dereference<int const *>` inherits from `__true_type`.]
  43 [:`has_dereference<int * const>` inherits from `__true_type`.]
  44 [:`has_dereference<int const * const>` inherits from `__true_type`.]
  45
  46 [:`has_dereference<int>` inherits from `__false_type`.]
  47 [:`has_dereference<double>` inherits from `__false_type`.]
  48 [:`has_dereference<void*>` inherits from `__false_type`.]
  49 [:`has_dereference<const int*, int&>` inherits from `__false_type`.]
  50
  51
  52 [*See also:] [link boost_typetraits.category.value_traits.operators Operator Type Traits]
  53
  54 [*Known issues:]
  55
  56 * This trait cannot detect whether prefix `operator*` is public or not:
  57 if `operator*` is defined as a private member of `Rhs` then
  58 instantiating `has_dereference<Rhs>` will produce a compiler error.
  59 For this reason `has_dereference` cannot be used to determine whether a type has a public `operator*` or not.
  60 ``
  61 struct A { private: void operator*(); };
  62 boost::has_dereference<A>::value; // error: A::operator*() is private
  63 ``
  64
  65 * There is an issue if the operator exists only for type `A` and `B` is
  66 convertible to `A`. In this case, the compiler will report an ambiguous overload.
  67 ``
  68 struct A { };
  69 void operator*(const A&);
  70 struct B { operator A(); };
  71 boost::has_dereference<A>::value; // this is fine
  72 boost::has_dereference<B>::value; // error: ambiguous overload
  73 ``
  74
  75 * There is an issue when applying this trait to template classes.
  76 If `operator*` is defined but does not bind for a given template type,
  77 it is still detected by the trait which returns `true` instead of `false`.
  78 Example:
  79 ``
  80 #include <boost/type_traits/has_dereference.hpp>
  81 #include <iostream>
  82
  83 template <class T>
  84 struct contains { T data; };
  85
  86 template <class T>
  87 bool operator*(const contains<T> &rhs) {
  88         return f(rhs.data);
  89 }
  90
  91 class bad { };
  92 class good { };
  93 bool f(const good&) { }
  94
  95 int main() {
  96         std::cout<<std::boolalpha;
  97         // works fine for contains<good>
  98         std::cout<<boost::has_dereference< contains< good > >::value<<'\n'; // true
  99         contains<good> g;
 100         *g; // ok
 101         // does not work for contains<bad>
 102         std::cout<<boost::has_dereference< contains< bad > >::value<<'\n'; // true, should be false
 103         contains<bad> b;
 104         *b; // compile time error
 105         return 0;
 106 }
 107 ``
 108
 109 * `volatile` qualifier is not properly handled and would lead to undefined behavior
 110
 111 [endsect]
 112