feat: Add batch::raw (#1363)

Author: AntoinePrv

docs/source/vectorized_code.rst

@@ -81,3 +81,40 @@ architecture and pass the appropriate flag to the compiler. For instance:
 
 This can be useful to implement runtime dispatching, based on the instruction set detected at runtime. `xsimd` provides a generic machinery :cpp:func:`xsimd::dispatch()` to implement
 this pattern. Based on the above example, instead of calling ``mean{}(arch, a, b, res, tag)``, one can use ``xsimd::dispatch(mean{})(a, b, res, tag)``. More about this can be found in the :ref:`Arch Dispatching` section.
+
+Breaking out of xsimd
+---------------------
+
+Sometimes ``xsimd`` may not give you the whole availability of the instruction set you
+are targeting. This is not specific to this library but to all libraries that
+abstract something.
+
+``xsimd`` give you the possibility to break out of its :cpp:class:`~xsimd::batch` class
+and getting the underlying intrinsic register type.
+This is useful when an instruction set expose some intrinsicts for applications (*e.g.* video
+processing, cryptography...) that are too specific to include in ``xsimd``, or when some
+instructions are currently missing.
+
+There are many ways a user could add a special cases in their arch-independent SIMD code.
+One that is simple and compiles on all platforms is using C++17 ``if constexpr``.
+
+.. code:: cpp
+
+    template<typename Arch>
+    auto sign_i8(
+        xsimd::batch<int8_t, Arch> const& x,
+        xsimd::batch<int8_t, Arch> const& y
+    ) -> xsimd::batch<uint8_t, Arch> {
+         // Dedicated instruction dispatch at compile time
+         if constexpr(std::is_same_v<Arch, xsimd::avx2>){
+             // Automatic conversion back and forth between xsimd::batch and native types
+             return _mm256_sign_epi8(x, y);
+             // When compiler complains we can be more explicit
+             return xsimd::batch<int8_t, Arch>(_mm256_sign_epi8(x.to_native(), y.to_native()));
+         }
+
+         // General xsimd implementation
+         auto const zero = xsimd::batch<uint8_t, Arch>(0);
+         auto const c = xsimd::select(b < 0, -a, a);
+         return xsimd::select(b == zero, zero, c);
+    }

include/xsimd/types/xsimd_batch.hpp

@@ -151,6 +151,8 @@ namespace xsimd
             return this->data;
         }
 
+        XSIMD_INLINE register_type to_native() const noexcept;
+
         template <class U>
         XSIMD_NO_DISCARD static XSIMD_INLINE batch broadcast(U val) noexcept;
 
@@ -343,6 +345,8 @@ namespace xsimd
         template <class Tp>
         XSIMD_INLINE batch_bool(Tp const*) = delete;
 
+        XSIMD_INLINE register_type to_native() const noexcept;
+
         // memory operators
         XSIMD_INLINE void store_aligned(bool* mem) const noexcept;
         XSIMD_INLINE void store_unaligned(bool* mem) const noexcept;
@@ -836,6 +840,15 @@ namespace xsimd
         return kernel::first(*this, A {});
     }
 
+    /**
+     * Cast to the underlying native intrinsic register type.
+     */
+    template <class T, class A>
+    XSIMD_INLINE auto batch<T, A>::to_native() const noexcept -> register_type
+    {
+        return static_cast<register_type>(*this);
+    }
+
     /******************************
      * batch comparison operators *
      ******************************/
@@ -1167,6 +1180,15 @@ namespace xsimd
         return kernel::first(*this, A {});
     }
 
+    /**
+     * Cast to the underlying native intrinsic register type.
+     */
+    template <class T, class A>
+    XSIMD_INLINE auto batch_bool<T, A>::to_native() const noexcept -> register_type
+    {
+        return static_cast<register_type>(*this);
+    }
+
     /***********************************
      * batch_bool comparison operators *
      ***********************************/

test/test_batch.cpp

@@ -100,6 +100,19 @@ struct batch_test
         CHECK_EQ(res_dump.str(), b_dump.str());
     }
 
+    void test_register_conversion() const
+    {
+        batch_type b1 = batch_type::load_unaligned(lhs.data());
+
+        auto b_converted = static_cast<typename batch_type::register_type>(b1);
+        auto b_native = b1.to_native();
+        // Check via decltype as register_type raises warning for ignored attributes
+        CHECK(std::is_same<decltype(b_native), decltype(b_converted)>::value);
+
+        batch_type b2 = b_native; // Converting ctor
+        CHECK_BATCH_EQ(b1, b2);
+    }
+
     void test_load_store() const
     {
         array_type res;
@@ -1161,6 +1174,11 @@ TEST_CASE_TEMPLATE("[batch]", B, BATCH_TYPES)
         Test.test_stream_dump();
     }
 
+    SUBCASE("register_conversion")
+    {
+        Test.test_register_conversion();
+    }
+
     SUBCASE("load_store")
     {
         Test.test_load_store();