ImathTypeTraits.h

Go to the documentation of this file.

//
// SPDX-License-Identifier: BSD-3-Clause
// Copyright Contributors to the OpenEXR Project.
//

//
// This file contains type traits related to or used by the Imath library.
//

#ifndef INCLUDED_IMATHTYPETRAITS_H
#define INCLUDED_IMATHTYPETRAITS_H

#include <type_traits>

#include "ImathPlatform.h"

IMATH_INTERNAL_NAMESPACE_HEADER_ENTER


/// Define Imath::enable_if_t to be std for C++14, equivalent for C++11.
#if (IMATH_CPLUSPLUS_VERSION >= 14)
    using std::enable_if_t;    // Use C++14 std::enable_if_t
#else
    // Define enable_if_t for C++11
    template <bool B, class T = void>
    using enable_if_t = typename std::enable_if<B, T>::type;
#endif


/// An enable_if helper to be used in template parameters which results in
/// much shorter symbols.
#define IMATH_ENABLE_IF(...) IMATH_INTERNAL_NAMESPACE::enable_if_t<(__VA_ARGS__), int> = 0


#if IMATH_FOREIGN_VECTOR_INTEROP

/// @{
/// @name Detecting interoperable types.
///
/// In order to construct or assign from external "compatible" types without
/// prior knowledge of their definitions, we have a few helper type traits.
/// The intent of these is to allow custom linear algebra types in an
/// application that have seamless conversion to and from Imath types.
///
/// `has_xy<T,Base>`, `has_xyz<T,Base>`, `has_xyzw<T,Base>` detect if class
/// `T` has elements `.x`, `.y`, and `.z` all of type `Base` and seems to be
/// the right size to hold exactly those members and nothing more.
///
/// `has_subscript<T,Base,N>` detects if class `T` can perform `T[int]`
/// to yield a `Base`, and that it seems to be exactly the right size to
/// hold `N` of those elements.
///
/// This is not exact. It's possible that for a particular user-defined
/// type, this may yield a false negative or false positive. For example:
///   * A class for a 3-vector that contains an extra element of padding
///     so that it will have the right size and alignment to use 4-wide
///     SIMD math ops will appear to be the wrong size.
///   * A `std::vector<T>` is subscriptable and might have N elements at
///     runtime, but the size is dynamic and so would fail this test.
///   * A foreign type may have .x, .y, .z that are not matching our base
///     type but we still want it to work (with appropriate conversions).
///
/// In these cases, user code may declare an exception -- for example,
/// stating that `mytype` should be considered implicitly convertible to
/// an Imath::V3f by subscripting:
///
///     template<>
///     struct Imath::has_subscript<mytype, float, 3> : public std::true_type { };
///
/// And similarly, user code may correct a potential false positive (that
/// is, a `mytype` looks like it should be convertible to a V3f, but you
/// don't want it to ever happen):
///
///     template<typename B, int N>
///     struct Imath::has_subscript<mytype, B, N> : public std::false_type { };
///


/// `has_xy<T,Base>::value` will be true if type `T` has member variables
/// `.x` and `.y`, all of type `Base`, and the size of a `T` is exactly big
/// enough to hold 2 Base values.
template <typename T, typename Base>
struct has_xy {
private:
    typedef char Yes[1];
    typedef char No[2];

    // Valid only if .x, .y exist and are the right type: return a Yes.
    template<typename C,
             IMATH_ENABLE_IF(std::is_same<decltype(C().x), Base>::value),
             IMATH_ENABLE_IF(std::is_same<decltype(C().y), Base>::value)>
    static Yes& test(int);

    // Fallback, default to returning a No.
    template<typename C> static No& test(...);
public:
    enum { value = (sizeof(test<T>(0)) == sizeof(Yes)
                    && sizeof(T) == 2*sizeof(Base))
      };
};


/// `has_xyz<T,Base>::value` will be true if type `T` has member variables
/// `.x`, `.y`, and `.z`, all of type `Base`, and the size of a `T` is
/// exactly big enough to hold 3 Base values.
template <typename T, typename Base>
struct has_xyz {
private:
    typedef char Yes[1];
    typedef char No[2];

    // Valid only if .x, .y, .z exist and are the right type: return a Yes.
    template<typename C,
             IMATH_ENABLE_IF(std::is_same<decltype(C().x), Base>::value),
             IMATH_ENABLE_IF(std::is_same<decltype(C().y), Base>::value),
             IMATH_ENABLE_IF(std::is_same<decltype(C().z), Base>::value)>
    static Yes& test(int);

    // Fallback, default to returning a No.
    template<typename C> static No& test(...);
public:
    enum { value = (sizeof(test<T>(0)) == sizeof(Yes)
                    && sizeof(T) == 3*sizeof(Base))
      };
};


/// `has_xyzw<T,Base>::value` will be true if type `T` has member variables
/// `.x`, `.y`, `.z`, and `.w`, all of type `Base`, and the size of a `T` is
/// exactly big enough to hold 4 Base values.
template <typename T, typename Base>
struct has_xyzw {
private:
    typedef char Yes[1];
    typedef char No[2];

    // Valid only if .x, .y, .z, .w exist and are the right type: return a Yes.
    template<typename C,
             IMATH_ENABLE_IF(std::is_same<decltype(C().x), Base>::value),
             IMATH_ENABLE_IF(std::is_same<decltype(C().y), Base>::value),
             IMATH_ENABLE_IF(std::is_same<decltype(C().z), Base>::value),
             IMATH_ENABLE_IF(std::is_same<decltype(C().w), Base>::value)>
    static Yes& test(int);

    // Fallback, default to returning a No.
    template<typename C> static No& test(...);
public:
    enum { value = (sizeof(test<T>(0)) == sizeof(Yes)
                    && sizeof(T) == 4*sizeof(Base))
      };
};



/// `has_subscript<T,Base,Nelem>::value` will be true if type `T` has
/// subscripting syntax, a `T[int]` returns a `Base`, and the size of a `T`
/// is exactly big enough to hold `Nelem` `Base` values.
template <typename T, typename Base, int Nelem>
struct has_subscript {
private:
    typedef char Yes[1];
    typedef char No[2];

    // Valid only if T[] is possible and is the right type: return a Yes.
    template<typename C,
             IMATH_ENABLE_IF(std::is_same<typename std::decay<decltype(C()[0])>::type, Base>::value)>
    static Yes& test(int);

    // Fallback, default to returning a No.
    template<typename C> static No& test(...);
public:
    enum { value = (sizeof(test<T>(0)) == sizeof(Yes)
                    && sizeof(T) == Nelem*sizeof(Base))
      };
};


/// C arrays of just the right length also are qualified for has_subscript.
template<typename Base, int Nelem>
struct has_subscript<Base[Nelem], Base, Nelem> : public std::true_type { };



/// `has_double_subscript<T,Base,Rows,Cols>::value` will be true if type `T`
/// has 2-level subscripting syntax, a `T[int][int]` returns a `Base`, and
/// the size of a `T` is exactly big enough to hold `R*C` `Base` values.
template <typename T, typename Base, int Rows, int Cols>
struct has_double_subscript {
private:
    typedef char Yes[1];
    typedef char No[2];

    // Valid only if T[][] is possible and is the right type: return a Yes.
    template<typename C,
             IMATH_ENABLE_IF(std::is_same<typename std::decay<decltype(C()[0][0])>::type, Base>::value)>
    static Yes& test(int);

    // Fallback, default to returning a No.
    template<typename C> static No& test(...);
public:
    enum { value = (sizeof(test<T>(0)) == sizeof(Yes)
                    && sizeof(T) == (Rows*Cols)*sizeof(Base))
      };
};


/// C arrays of just the right length also are qualified for has_double_subscript.
template<typename Base, int Rows, int Cols>
struct has_double_subscript<Base[Rows][Cols], Base, Rows, Cols> : public std::true_type { };

/// @}

#endif

IMATH_INTERNAL_NAMESPACE_HEADER_EXIT

#endif // INCLUDED_IMATHTYPETRAITS_H