[part implicit_cast
    [version 1]
    [copyright 2005-2006 ]
    [id implicit_cast]
    [category implicit_cast]
    [authors  [Abrahams,David]]
     [license
        Distributed under the Boost Software License, Version 1.0.
        (See accompanying file LICENSE_1_0.txt or copy at
        <ulink url="http://www.boost.org/LICENSE_1_0.txt">
            http://www.boost.org/LICENSE_1_0.txt
        </ulink>)
    ]
]

[section:index Boost.Implicit_cast]

* [link synopsis Synopsis]
* [link summary Summary]
* [link example Example]

[#synopsis]

[h3 Synopsis]
	
header [@../../../../boost/implicit_cast.hpp "boost/implicit_cast.hpp"]

	template <typename T> T implicit_cast( T1 x);

   Requires: T1 is implicitly convertible to T.
   Returns: An object of type T whose value is the result of implicit conversion of x from type T1 to T.

[#summary]

[h3 Summary]
implicit_cast is used when the source type is implicitly
convertible to the target type, to force the implicit conversion.
It's less liberal than static_cast, which will convert in the opposite direction.


implicit_cast<t>(S) will usually [link note1 '''<superscript>1</superscript>'''] succeed if [@../../../../doc/html/boost_typetraits/reference.html#boost_typetraits.is_convertible boost::is_convertible<S,T>]::value is true, but will always cause a compile_time error if 
[@../../../../doc/html/boost_typetraits/reference.html#boost_typetraits.is_convertible boost::is_convertible<S,T>]::value is false.

[#example]

[h3 Example]
As an example application lets take initialisation of a user defined type (UDT) where its usual to require explicit initialisation (or value initialisation) by making the constructor explicit to prevent implicit initialisation. In udtA the explicit constructor means that udtA can be initialised with types T, but only using the explicit or value initialisation syntax.
  
    #include <boost/implicit_cast.hpp>

    template <typename T>
    struct udtA{
        typedef T value_type;
        T val;
        template <typename T1>
        explicit udtA( T1 const & t) : val(t){}
    };

The problem is that udtA can be value initialised by an unexpectedly wide range of types as shown in the first example below. The initialisation of a udtA<double> object is safe because it can only be value initialised by inbuilt types. The nested udtA<udtA<double> > allows initialisation by its value_type, a udtA<double>, as shown in the initialisation of vA1, but it also allows initialisation by an int as shown in vA2. This may be, but is probably not, what the author of udtA intended.

    udtA<double> vA0(1);
    udtA<udtA<double> >vA1(vA0);
    udtA<udtA<double> >vA2(1);

This problem can be prevented by adding `boost::implicit_cast` in the initialiser for val as shown in udtB.

    template <typename T>
    struct udtB{
    typedef T value_type;
    T val;
    template <typename T1>
    explicit udtB( T1 const & t) : val(boost::implicit_cast<T>(t)){}
};

Attempting to initialise a udtB by a type not implicitly convertible to its value_type will be prevented, as in the attempted initialisation of vB2 by an int shown below.

    udtB<double> vB0(1);
    udtB<udtB<double> >vB1(vB0);
    udtB<udtB<double> >vB2(1); // Error!

[#note1]
Note1\n
The following is one situation where is_convertible<foo,int> will return true but where implicit_cast wont succeed.

       struct foo{
          operator int() { throw "fooled ya"; }
       };

[endsect]