.. _onemkl_blas_swap:

swap
====

Swaps a vector with another vector.

Description
***********

Given two vectors of ``n`` elements, ``x`` and ``y``, the ``swap``
routines return vectors ``y`` and ``x`` swapped, each replacing the
other. The operation is defined as:

.. math::

   \left[\begin{array}{c}
      y\\x
   \end{array}\right]
   \leftarrow
   \left[\begin{array}{c}
      x\\y
   \end{array}\right]

``swap`` supports the following precisions:

.. list-table::
   :header-rows: 1

   * -  T
   * -  ``float``
   * -  ``double``
   * -  ``std::complex<float>``
   * -  ``std::complex<double>``


swap (Buffer Version)
*********************

Syntax
------

.. code-block:: cpp

   namespace oneapi::mkl::blas::column_major {
       void swap(sycl::queue &queue,
                 std::int64_t n,
                 sycl::buffer<T,1> &x,
                 std::int64_t incx,
                 sycl::buffer<T,1> &y,
                 std::int64_t incy)
   }

.. code-block:: cpp

   namespace oneapi::mkl::blas::row_major {
       void swap(sycl::queue &queue,
                 std::int64_t n,
                 sycl::buffer<T,1> &x,
                 std::int64_t incx,
                 sycl::buffer<T,1> &y,
                 std::int64_t incy)
   }

Input Parameters
----------------

queue
   The queue where the routine should be executed.

n
   Number of elements in vectors ``x`` and ``y``.

x
   Buffer holding input vector ``x``. Size of the buffer must be at
   least (1 + (``n`` - 1)*abs(``incx``)). See ref:`matrix-storage` for more details.

incx
   Stride of vector ``x``.

y
   Buffer holding input vector ``y``. Size of the buffer must be at
   least (1 + (``n`` - 1)*abs(``incy``)). See ref:`matrix-storage` for more details.

incy
   Stride of vector ``y``.

Output Parameters
-----------------

x
   Buffer holding updated buffer ``x``, that is, the input vector
   ``y``.

y
   Buffer holding updated buffer ``y``, that is, the input vector
   ``x``.


swap (USM Version)
*********************

Syntax
------

.. code-block:: cpp

   namespace oneapi::mkl::blas::column_major {
       sycl::event swap(sycl::queue &queue,
                        std::int64_t n,
                        T *x,
                        std::int64_t incx,
                        T *y,
                        std::int64_t incy,
                        const std::vector<sycl::event> &dependencies = {})
   }

.. code-block:: cpp

   namespace oneapi::mkl::blas::row_major {
       sycl::event swap(sycl::queue &queue,
                        std::int64_t n,
                        T *x,
                        std::int64_t incx,
                        T *y,
                        std::int64_t incy,
                        const std::vector<sycl::event> &dependencies = {})
   }

Input Parameters
----------------

queue
   The queue where the routine should be executed.

n
   Number of elements in vectors ``x`` and ``y``.

x
   Pointer to input vector ``x``. Size of the array must be at
   least (1 + (``n`` - 1)*abs(``incx``)). See ref:`matrix-storage` for more details. 

incx
   Stride of vector ``x``.

y
   Pointer to input vector ``y``. Size of the array must be at
   least (1 + (``n`` - 1)*abs(``incy``)). See ref:`matrix-storage` for more details.

incy
   Stride of vector ``y``.

dependencies
   List of events to wait for before starting computation, if any. If
   omitted, defaults to no dependencies.

Output Parameters
-----------------

x
   Pointer to updated array ``x``, that is, the input vector
   ``y``.

y
   Pointer to updated array ``y``, that is, the input vector
   ``x``.

Return Values
-------------

Output event to wait on to ensure computation is complete.