ceph/src/boost/libs/type_traits/doc/has_right_shift.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_right_shift has_right_shift]
   9    template <class Lhs, class Rhs=Lhs, class Ret=dont_care>
  10    struct has_right_shift : public __tof {};
  11
  12 __inherit
  13 If (i) `lhs` of type `Lhs` and `rhs` of type `Rhs` can be used in expression `lhs>>rhs`,
  14 and (ii) `Ret=dont_care` or the result of expression `lhs>>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 binary `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 Lhs lhs;
  24 Rhs rhs;
  25 f(lhs>>rhs); // is valid if has_right_shift<Lhs, Rhs, Ret>::value==true
  26 ``
  27 If `Ret=void`, the return type is checked to be exactly `void`.
  28
  29 __header `#include <boost/type_traits/has_right_shift.hpp>` or `#include <boost/type_traits/has_operator.hpp>` or `#include <boost/type_traits.hpp>`
  30
  31 [has_binary_operator_compat]
  32
  33 __examples
  34
  35 [:`has_right_shift<Lhs, Rhs, Ret>::value_type` is the type `bool`.]
  36 [:`has_right_shift<Lhs, Rhs, Ret>::value` is a `bool` integral constant expression.]
  37 [:`has_right_shift<int>::value` is a `bool` integral constant expression that evaluates to `true`.]
  38 [:`has_right_shift<long>` inherits from `__true_type`.]
  39
  40 [:`has_right_shift<int, int, int>` inherits from `__true_type`.]
  41 [:`has_right_shift<const int, int>` inherits from `__true_type`.]
  42 [:`has_right_shift<std::istream, int&>` inherits from `__true_type`.]
  43 [:`has_right_shift<std::istream, char*, std::ostream>` inherits from `__true_type`.]
  44 [:`has_right_shift<std::istream, std::string&>` inherits from `__true_type`.]
  45
  46 [:`has_right_shift<int, double, bool>` inherits from `__false_type`.]
  47 [:`has_right_shift<int, int, std::string>` inherits from `__false_type`.]
  48
  49
  50 [*See also:] [link boost_typetraits.category.value_traits.operators Operator Type Traits]
  51
  52 [*Known issues:]
  53
  54 * This trait cannot detect whether binary `operator>>` is public or not:
  55 if `operator>>` is defined as a private member of `Lhs` then
  56 instantiating `has_right_shift<Lhs>` will produce a compiler error.
  57 For this reason `has_right_shift` cannot be used to determine whether a type has a public `operator>>` or not.
  58 ``
  59 struct A { private: void operator>>(const A&); };
  60 boost::has_right_shift<A>::value; // error: A::operator>>(const A&) is private
  61 ``
  62
  63 * There is an issue if the operator exists only for type `A` and `B` is
  64 convertible to `A`. In this case, the compiler will report an ambiguous overload.
  65 ``
  66 struct A { };
  67 void operator>>(const A&, const A&);
  68 struct B { operator A(); };
  69 boost::has_right_shift<A>::value; // this is fine
  70 boost::has_right_shift<B>::value; // error: ambiguous overload
  71 ``
  72
  73 * There is an issue when applying this trait to template classes.
  74 If `operator>>` is defined but does not bind for a given template type,
  75 it is still detected by the trait which returns `true` instead of `false`.
  76 Example:
  77 ``
  78 #include <boost/type_traits/has_right_shift.hpp>
  79 #include <iostream>
  80
  81 template <class T>
  82 struct contains { T data; };
  83
  84 template <class T>
  85 bool operator>>(const contains<T> &lhs, const contains<T> &rhs) {
  86         return f(lhs.data, rhs.data);
  87 }
  88
  89 class bad { };
  90 class good { };
  91 bool f(const good&, const good&) { }
  92
  93 int main() {
  94         std::cout<<std::boolalpha;
  95         // works fine for contains<good>
  96         std::cout<<boost::has_right_shift< contains< good > >::value<<'\n'; // true
  97         contains<good> g;
  98         g>>g; // ok
  99         // does not work for contains<bad>
 100         std::cout<<boost::has_right_shift< contains< bad > >::value<<'\n'; // true, should be false
 101         contains<bad> b;
 102         b>>b; // compile time error
 103         return 0;
 104 }
 105 ``
 106
 107 * `volatile` qualifier is not properly handled and would lead to undefined behavior
 108
 109 [endsect]
 110