Promotions.H

Go to the documentation of this file.

/*! @file
    @author Randolph Voorhies
    @copyright GNU Public License (GPL v3)
    @section License
    @verbatim
    // ////////////////////////////////////////////////////////////////////////
    //              The iLab Neuromorphic Robotics Toolkit (NRT)             //
    // Copyright 2010-2012 by the University of Southern California (USC)    //
    //                          and the iLab at USC.                         //
    //                                                                       //
    //                iLab - University of Southern California               //
    //                Hedco Neurociences Building, Room HNB-10               //
    //                    Los Angeles, Ca 90089-2520 - USA                   //
    //                                                                       //
    //      See http://ilab.usc.edu for information about this project.      //
    // ////////////////////////////////////////////////////////////////////////
    // This file is part of The iLab Neuromorphic Robotics Toolkit.          //
    //                                                                       //
    // The iLab Neuromorphic Robotics Toolkit is free software: you can      //
    // redistribute it and/or modify it under the terms of the GNU General   //
    // Public License as published by the Free Software Foundation, either   //
    // version 3 of the License, or (at your option) any later version.      //
    //                                                                       //
    // The iLab Neuromorphic Robotics Toolkit is distributed in the hope     //
    // that it will be useful, but WITHOUT ANY WARRANTY; without even the    //
    // implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR       //
    // PURPOSE.  See the GNU General Public License for more details.        //
    //                                                                       //
    // You should have received a copy of the GNU General Public License     //
    // along with The iLab Neuromorphic Robotics Toolkit.  If not, see       //
    // <http://www.gnu.org/licenses/>.                                       //
    // ////////////////////////////////////////////////////////////////////////
    @endverbatim */


#ifndef INCLUDE_NRT_CORE_TYPING_PROMOTIONS_H
#define INCLUDE_NRT_CORE_TYPING_PROMOTIONS_H

#include <nrt/Core/Typing/ErrorType.H>
#include <nrt/Core/Typing/IntegerTypes.H>
#include <nrt/Core/Typing/details/TypeTraitsHelpers.H>
#include <type_traits>

namespace nrt
{
  /*! \defgroup promotions Automatic type promotion for operations

      When building generic functions it is often necessary to determine the return type of a generic method which takes
      two templated types as input.  For example, what should be the return type of the following method?

      @code
      template<class T1, class T2>
      Dims<SOME_TYPE> operator+(Dims<T1> x, Dims<T2> y);
      @endcode

      A good solution is to use this nrt::promote class which determines the return type by asking the compiler in which
      type the result of T1*T2 (which is the largest data type returned by most operations) should be stored. The
      resulting code looks like this:

      @code
      template<class T1, class T2>
      Dims<nrt::promote<T1,T2>::type> operator+(Dims<T1> x, Dims<T2> y);
      @endcode

      Keep in mind that when trying to find an operator* the compiler will first try to match for the exact type, then
      for any implicit conversions, before getting eaten up by our fail mechanism. So, if you don't indend two types to
      be promotable but have constructors for one type that takes as an argument the other, make sure you make use of
      the explicit keyword in your constructors so the compiler can't implicitly convert it. See
      \link test-Traits.C \endlink

      \ingroup typing */

  /*! @{ */ // **********************************************************************

  //! Specialization of nrt::promote for when we can't promote
  template <class T1, class T2, bool B = nrt::is_promotable<T1,T2>::value>
  struct promote
  {
      typedef NotATypeError type;
      static bool const will_promote = false;
  };

  //! Specialization of nrt::promote for when a promotion will occur  
  template <class T1, class T2>
  struct promote<T1,T2,true>
  {
    private:
      static T1 const & x;
      static T2 const & y;

    public:
      //! The nrt::promote::type typedef is used to access the resulting type of the promotion
      typedef decltype(x*y) type;

      //! Will the resulting type be a different type than the two original types?
      static bool const will_promote = !(std::is_same<type, T1>::value && std::is_same<type, T2>::value);
  };

  //! Specialization of nrt::promote when first type is void, promoted type is the second type
  template <class T2>
  struct promote<void, T2, false>
  {
      typedef T2 type;
      static bool const will_promote = false;
  };

  //! Specialization of nrt::promote when second type is void, promoted type is the first type
  /*! This is useful if you want to not promote, for example:
      @code
      nrt::Image<nrt::PixGray<nrt::byte> > src;
      nrt::Image<nrt::PixGray<nrt::byte> > dest = nrt::lowPass3<void>(src);
      // by default, lowPass3() would return Image<PixGray<double>> as its default promo parameter is double
      @endcode */
  template <class T1>
  struct promote<T1, void, false>
  {
      typedef T1 type;
      static bool const will_promote = false;
  };

  //! Specialization of nrt::promote when both types are void
  /*! This is just to avoid compilation ambiguities in the less-specialized cases. */
  template <>
  struct promote<void, void, false>
  {
      typedef void type;
      static bool const will_promote = false;
  };

  /*! @} */ // **********************************************************************
}

#endif // INCLUDE_NRT_CORE_TYPING_PROMOTIONS_H