diff --git a/docs/source/API/core/numerics/complex.rst b/docs/source/API/core/numerics/complex.rst index 8065cb05b..b8b6628a6 100644 --- a/docs/source/API/core/numerics/complex.rst +++ b/docs/source/API/core/numerics/complex.rst @@ -13,6 +13,9 @@ Description * This is intended as a replacement for ``std::complex``. * Note: If ``z`` has type ``Kokkos::complex``, casting such as ``reinterpret_cast(z)`` leads to undefined behavior (this differs from ``std::complex``). +* Note: operations involving ``std::complex``, ``std::istream`` or ``std::ostream`` are not available on the device. +* Note: while operators may be listed as public member functions or non-member functions, they may be implemented as member functions, free functions or hidden friends. + Interface --------- @@ -111,25 +114,33 @@ Interface Assigns ``i`` to the imaginary component. .. cpp:function:: constexpr complex& operator+=(complex v) noexcept + .. cpp:function:: constexpr complex& operator+=(std::complex v) .. cpp:function:: constexpr complex& operator+=(T v) noexcept Adds the complex value ``complex(v)`` to the complex value ``*this`` and stores the sum in ``*this``. .. cpp:function:: constexpr complex& operator-=(complex v) noexcept + .. cpp:function:: constexpr complex& operator-=(std::complex v) .. cpp:function:: constexpr complex& operator-=(T v) noexcept Subtracts the complex value ``complex(v)`` from the complex value ``*this`` and stores the difference in ``*this``. .. cpp:function:: constexpr complex& operator*=(complex v) noexcept + .. cpp:function:: constexpr complex& operator*=(std::complex v) .. cpp:function:: constexpr complex& operator*=(T v) noexcept Multiplies the complex value ``complex(v)`` by the complex value ``*this`` and stores the product in ``*this``. .. cpp:function:: constexpr complex& operator/=(complex v) noexcept + .. cpp:function:: constexpr complex& operator/=(std::complex v) noexcept .. cpp:function:: constexpr complex& operator/=(T v) noexcept Divides the complex value ``complex(v)`` into the complex value ``*this`` and stores the quotient in ``*this``. + .. note:: + + The Kokkos implementation of division uses a scaled method, and the result does not necessarily match a similar operation using ``std::complex``, nor are they ``constexpr`` until C++23. + .. cpp:function:: volatile T& real() volatile noexcept .. deprecated:: 4.0.0 @@ -181,54 +192,157 @@ Interface .. rubric:: Non-Member Functions: + .. cpp:function:: constexpr bool operator==(complex x, complex y) + .. cpp:function:: constexpr bool operator==(complex x, T y) + .. cpp:function:: constexpr bool operator==(T x, complex y) + .. cpp:function:: constexpr bool operator==(complex x, std::complex y) + .. cpp:function:: constexpr bool operator==(std::complex x, complex y) + + :return: ``true`` if and only if the real component of ``complex(x)`` equals the real component of ``complex(y)`` and the imaginary component of ``complex(x)`` equals the imaginary component of ``complex(y)``. + .. cpp:function:: template bool operator==(complex x, complex y) noexcept + + .. deprecated:: 5.0.2 + .. cpp:function:: template bool operator==(complex x, T2 y) noexcept + + .. deprecated:: 5.0.2 + .. cpp:function:: template bool operator==(T1 x, complex y) noexcept + + .. deprecated:: 5.0.2 + .. cpp:function:: template bool operator==(complex x, std::complex y) noexcept + + .. deprecated:: 5.0.2 + .. cpp:function:: template bool operator==(std::complex x, complex y) noexcept - :return: ``true`` if and only if the real component of ``complex(x)`` equals the real component of ``complex(y)`` and the imaginary component of ``complex(x)`` equals the imaginary component of ``complex(y)``. + .. deprecated:: 5.0.2 + + .. cpp:function:: constexpr bool operator!=(complex x, complex y) + .. cpp:function:: constexpr bool operator!=(complex x, T y) + .. cpp:function:: constexpr bool operator!=(T x, complex y) + .. cpp:function:: constexpr bool operator!=(complex x, std::complex y) + .. cpp:function:: constexpr bool operator!=(std::complex x, complex y) + + :return: ``!(x == y)`` .. cpp:function:: template bool operator!=(complex x, complex y) noexcept + + .. deprecated:: 5.0.2 + .. cpp:function:: template bool operator!=(complex x, T2 y) noexcept + + .. deprecated:: 5.0.2 + .. cpp:function:: template bool operator!=(T1 x, complex y) noexcept + + .. deprecated:: 5.0.2 + .. cpp:function:: template bool operator!=(complex x, std::complex y) noexcept + + .. deprecated:: 5.0.2 + .. cpp:function:: template bool operator!=(std::complex x, complex y) noexcept - :return: ``!(x == y)`` + .. deprecated:: 5.0.2 - .. cpp:function:: template complex operator+(complex x) noexcept + .. cpp:function:: constexpr complex operator+(complex x) noexcept :return: ``x`` + .. cpp:function:: constexpr complex operator+(complex x, complex y) + .. cpp:function:: constexpr complex operator+(complex x, T y) + .. cpp:function:: constexpr complex operator+(T x, complex y) + .. cpp:function:: constexpr complex operator+(complex x, std::complex y) + .. cpp:function:: constexpr complex operator+(std::complex x, complex y) + + :return: The complex value ``complex(x)`` added to the complex value ``complex(y)``. + .. cpp:function:: template complex> operator+(complex x, complex y) noexcept + + .. deprecated:: 5.0.2 + .. cpp:function:: template complex> operator+(complex x, T2 y) noexcept + + .. deprecated:: 5.0.2 + .. cpp:function:: template complex> operator+(T1 x, complex y) noexcept - :return: The complex value ``complex(x)`` added to the complex value ``complex(y)``. + .. deprecated:: 5.0.2 - .. cpp:function:: template complex operator-(complex x) noexcept + .. cpp:function:: constexpr complex operator-(complex x) noexcept :return: ``complex(-x.real(), -x.imag())`` + .. cpp:function:: constexpr complex operator-(complex x, complex y) + .. cpp:function:: constexpr complex operator-(complex x, T y) + .. cpp:function:: constexpr complex operator-(T x, complex y) + .. cpp:function:: constexpr complex operator-(complex x, std::complex y) + .. cpp:function:: constexpr complex operator-(std::complex x, complex y) + + :return: The complex value ``complex(y)`` subtracted from the complex value ``complex(x)``. + .. cpp:function:: template complex> operator-(complex x, complex y) noexcept + + .. deprecated:: 5.0.2 + .. cpp:function:: template complex> operator-(complex x, T2 y) noexcept + + .. deprecated:: 5.0.2 + .. cpp:function:: template complex> operator-(T1 x, complex y) noexcept - :return: The complex value ``complex(y)`` subtracted from the complex value ``complex(x)``. + .. deprecated:: 5.0.2 + + .. cpp:function:: constexpr complex operator*(complex x, complex y) + .. cpp:function:: constexpr complex operator*(complex x, T y) + .. cpp:function:: constexpr complex operator*(T x, complex y) + .. cpp:function:: constexpr complex operator*(complex x, std::complex y) + .. cpp:function:: constexpr complex operator*(std::complex x, complex y) + + :return: The complex value ``complex(x)`` multiplied by the complex value ``complex(y)``. .. cpp:function:: template complex> operator*(complex x, complex y) noexcept + + .. deprecated:: 5.0.2 + .. cpp:function:: template complex> operator*(complex x, T2 y) noexcept + + .. deprecated:: 5.0.2 + .. cpp:function:: template complex> operator*(T1 x, complex y) noexcept + + .. deprecated:: 5.0.2 + .. cpp:function:: template complex> operator*(std::complex x, complex y) noexcept - :return: The complex value ``complex(x)`` multiplied by the complex value ``complex(y)``. + .. deprecated:: 5.0.2 + + .. cpp:function:: constexpr complex operator/(complex x, complex y) + .. cpp:function:: constexpr complex operator/(complex x, T y) + .. cpp:function:: constexpr complex operator/(T x, complex y) + .. cpp:function:: constexpr complex operator/(complex x, std::complex y) + .. cpp:function:: constexpr complex operator/(std::complex x, complex y) + + :return: The complex value ``complex(y)`` divided into the complex value ``complex(x)``. + + .. note:: + + The Kokkos implementation of division uses a scaled method, and the result does not necessarily match a similar operation using ``std::complex``, nor are they ``constexpr`` until C++23. .. cpp:function:: template complex> operator/(complex x, complex y) noexcept + + .. deprecated:: 5.0.2 + .. cpp:function:: template complex> operator/(complex x, T2 y) noexcept + + .. deprecated:: 5.0.2 + .. cpp:function:: template complex> operator/(T1 x, complex y) noexcept - :return: The complex value ``complex(y)`` divided into the complex value ``complex(x)``. + .. deprecated:: 5.0.2 .. cpp:function:: template std::istream& operator>>(std::ostream& i, complex& x)