xtensor-stack · tdegeus · Nov 9, 2019
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -0,0 +1,52 @@
+
+********
+Examples
+********
+
+.. seealso::
+
+    `Medium post by Johan Mabille <https://medium.com/@johan.mabille/designing-language-bindings-with-xtensor-f32aa0f20db>`__
+
+Option 4: type restriction with SFINAE
+======================================
+
+In this example we will design a module with a function that accepts an ``xt::xtensor`` as argument, but in such a way that an ``xt::pyxtensor`` can be accepted in the Python module. We will achieve this with the principle of SFINAE (Substitution Failure Is Not An Error).
+
+Our example has the following file-structure.
+
+.. code-block:: none
+
+    examples/sfinae
+       |- src
+       |   |- foobar.hpp
+       |   |- python.cpp
+       |- CMakeLists.txt
+       |- main.cpp
+
+The module has one function that accepts an ``xt::xtensor`` as argument:
+
+:download:`src/foobar.hpp <examples/sfinae/src/foobar.hpp>`
+
+.. literalinclude:: examples/sfinae/src/foobar.hpp
+   :language: cpp
+
+Consequently from C++, the interaction with the module's function is trivial
+
+:download:`main.cpp <examples/sfinae/main.cpp>`
+
+.. literalinclude:: examples/sfinae/main.cpp
+   :language: cpp
+
+From the Python module, we will add an additional overload to the template
+
+:download:`src/python.cpp <examples/sfinae/src/python.cpp>`
+
+.. literalinclude:: examples/sfinae/src/python.cpp
+   :language: cpp
+
+There are several options to build the module. Using cmake we can use the following ``CMakeLists.txt``:
+
+:download:`CMakeLists.txt <examples/sfinae/CMakeLists.txt>`
+
+.. literalinclude:: examples/sfinae/CMakeLists.txt
+   :language: cmake
diff --git a/docs/source/examples/sfinae/CMakeLists.txt b/docs/source/examples/sfinae/CMakeLists.txt
@@ -0,0 +1,32 @@
+cmake_minimum_required(VERSION 3.1)
+
+project(foobar)
+
+find_package(xtl REQUIRED)
+find_package(xtensor REQUIRED)
+find_package(pybind11 REQUIRED)
+find_package(xtensor-python REQUIRED)
+
+add_library(foobar src/python.cpp)
+
+if(MSVC)
+    target_compile_options(foobar PRIVATE /EHsc /MP /bigobj)
+    set(CMAKE_EXE_LINKER_FLAGS /MANIFEST:NO)
+endif()
+
+if (CMAKE_CXX_COMPILER_ID MATCHES "Clang" OR
+    CMAKE_CXX_COMPILER_ID MATCHES "GNU" OR
+    (CMAKE_CXX_COMPILER_ID MATCHES "Intel" AND NOT WIN32))
+    target_compile_options(foobar PRIVATE -march=native -std=c++14)
+endif()
+
+target_link_libraries(foobar
+    PRIVATE
+    pybind11::pybind11
+    xtensor
+    xtensor-python)
+
+set_target_properties(foobar
+    PROPERTIES
+    PREFIX "${PYTHON_MODULE_PREFIX}"
+    SUFFIX "${PYTHON_MODULE_EXTENSION}")
diff --git a/docs/source/examples/sfinae/main.cpp b/docs/source/examples/sfinae/main.cpp
@@ -0,0 +1,9 @@
+#include "src/foobar.hpp"
+
+int main()
+{
+  xt::xtensor<size_t,2> a = xt::arange<size_t>(2 * 3).reshape({2, 3});
+  foobar::compute(a);
+  std::cout << a << std::endl;
+  return 0;
+}
diff --git a/docs/source/examples/sfinae/src/foobar.hpp b/docs/source/examples/sfinae/src/foobar.hpp
@@ -0,0 +1,27 @@
+#include <xtensor/xtensor.hpp>
+#include <xtensor/xio.hpp>
+
+namespace foobar {
+
+template <class C>
+struct is_tensor : std::false_type
+{
+};
+
+template <class T, std::size_t N, xt::layout_type L, class Tag>
+struct is_tensor<xt::xtensor<T, N, L, Tag>> : std::true_type
+{
+};
+
+template <template<class> class C, class T>
+using check_constraints = std::enable_if_t<C<T>::value, bool>;
+
+template <class T, template <class> class C = is_tensor,
+          check_constraints<C, T> = true>
+void compute(T& t)
+{
+  using value_type = typename T::value_type;
+  t *= (value_type)(2);
+}
+
+}
diff --git a/docs/source/examples/sfinae/src/python.cpp b/docs/source/examples/sfinae/src/python.cpp
@@ -0,0 +1,19 @@
+#include <pybind11/pybind11.h>
+#define FORCE_IMPORT_ARRAY
+#include <xtensor-python/pytensor.hpp>
+
+namespace foobar {
+
+template <class T, std::size_t N, xt::layout_type L>
+struct is_tensor<xt::pytensor<T, N, L>> : std::true_type
+{
+};
+
+}
+
+PYBIND11_MODULE(foobar, m)
+{
+    xt::import_numpy();
+
+    m.def("compute", &foobar::compute<xt::pytensor<double, 2>>);
+}
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -16,7 +16,7 @@ What are ``xtensor`` and ``xtensor-python``?
  - ``xtensor`` is a C++ library for multi-dimensional arrays enabling numpy-style broadcasting and lazy computing.
  - ``xtensor-python`` enables inplace use of numpy arrays with all the benefits from ``xtensor``
 
-     - C++ universal functions and broadcasting 
+     - C++ universal functions and broadcasting
      - STL - compliant APIs.
 
 
@@ -54,7 +54,6 @@ This software is licensed under the BSD-3-Clause license. See the LICENSE file f
 
    installation
 
-
 .. toctree::
    :caption: USAGE
    :maxdepth: 2
@@ -63,6 +62,7 @@ This software is licensed under the BSD-3-Clause license. See the LICENSE file f
    array_tensor
    numpy_capi
    cookiecutter
+   examples
 
 .. toctree::
    :caption: API REFERENCE
@@ -78,7 +78,7 @@ This software is licensed under the BSD-3-Clause license. See the LICENSE file f
 
 .. _NumPy: http://www.numpy.org
 .. _`Buffer Protocol`: https://docs.python.org/3/c-api/buffer.html
-.. _`numpy to xtensor cheat sheet`: http://xtensor.readthedocs.io/en/latest/numpy.html 
+.. _`numpy to xtensor cheat sheet`: http://xtensor.readthedocs.io/en/latest/numpy.html
 .. _xtensor: https://github.com/QuantStack/xtensor
-.. _pybind11: https://github.com/pybind/pybind11 
-.. _xtensor-python-cookiecutter: https://github.com/QuantStack/xtensor-python-cookiecutter 
+.. _pybind11: https://github.com/pybind/pybind11
+.. _xtensor-python-cookiecutter: https://github.com/QuantStack/xtensor-python-cookiecutter