cxx/stdlib/half_wrapper.txt

// Copyright 2017-2020 The Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

[[half-wrapper-library]]
=== Half Wrapper Library

The OpenCL {cpp} programming language implements a wrapper class for the built-in half data type (see the <<builtin-half-data-type, _Built-in Half Data Type_>> section).
The class methods perform implicit `vload_half` and `vstore_half` operations from the <<vector-data-load-and-store-functions, _Vector Data Load and Store Functions_>> section.

[[header-opencl_half-synopsis]]
==== Header <opencl_half> Synopsis

[source]
----
namespace cl {
struct fp16
{
    fp16() = default;
    fp16(const fp16 &) = default;
    fp16(fp16 &&) = default;
    fp16 &operator=(const fp16 &) = default;
    fp16 &operator=(fp16 &&) = default;

    explicit operator bool() const noexcept;

#ifdef cl_khr_fp16
    fp16(half r) noexcept;
    fp16 &operator=(half r) noexcept;
    operator half() const noexcept;
#endif

    fp16(float r) noexcept;
    fp16 &operator=(float r) noexcept;
    operator float() const noexcept;

#ifdef cl_khr_fp64
    fp16(double r) noexcept;
    fp16 &operator=(double r) noexcept;
    operator double() const noexcept;
#endif

    fp16 &operator++() noexcept;
    fp16 operator++(int) noexcept;
    fp16 &operator--() noexcept;
    fp16 operator--(int) noexcept;
    fp16 &operator+=(const fp16 &r) noexcept;
    fp16 &operator-=(const fp16 &r) noexcept;
    fp16 &operator*=(const fp16 &r) noexcept;
    fp16 &operator/=(const fp16 &r) noexcept;
};

bool operator==(const fp16& lhs, const fp16& rhs) noexcept;
bool operator!=(const fp16& lhs, const fp16& rhs) noexcept;
bool operator< (const fp16& lhs, const fp16& rhs) noexcept;
bool operator> (const fp16& lhs, const fp16& rhs) noexcept;
bool operator<=(const fp16& lhs, const fp16& rhs) noexcept;
bool operator>=(const fp16& lhs, const fp16& rhs) noexcept;
fp16 operator+(const fp16& lhs, const fp16& rhs) noexcept;
fp16 operator-(const fp16& lhs, const fp16& rhs) noexcept;
fp16 operator*(const fp16& lhs, const fp16& rhs) noexcept;
fp16 operator/(const fp16& lhs, const fp16& rhs) noexcept;

}
----

[[constructors-1]]
==== Constructors

[source]
----
fp16(const half &r) noexcept;
----

Constructs an object with a half built-in type.

[source]
----
fp16(const float &r) noexcept;
----

Constructs an object with a float built-in type.
If the *cl_khr_fp16* extension is not supported, `vstore_half` built-in function is called with the default rounding mode.

[source]
----
fp16(const double &r) noexcept;
----

Constructs an object with a double built-in type.
If the *cl_khr_fp16* extension is not supported, `vstore_half` built-in function is called with the default rounding mode.
The constructor is only present if the double precision support is enabled.

[[assignment-operators-1]]
==== Assignment operators

[source]
----
fp16 &operator=(const half &r) noexcept;
----

Assigns r to the stored half type.

[source]
----
fp16 &operator=(const float &r) noexcept;
----

Assigns r to the stored half type.
If the *cl_khr_fp16* extension is not supported, `vstore_half` built-in function is called with the default rounding mode.

[source]
----
fp16 &operator=(const double &r) noexcept;
----

Assigns r to the stored half type.
If the *cl_khr_fp16* extension is not supported, `vstore_half` built-in function is called with the default rounding mode.
The operator is only present if the double precision support is enabled.

[[conversion-operators]]
==== Conversion operators
[source]
----
explicit operator bool() const noexcept;
----

Returns `m != 0.0h`.
If the *cl_khr_fp16* extension is not supported, `vload_half` built-in function is called.

[source]
----
operator half() const noexcept;
----

Conversion operator to the built-in half type.

[source]
----
operator float() const noexcept;
----

Conversion operator.
If the *cl_khr_fp16* extension is not supported, `vload_half` built-in function is called.

[source]
----
operator double() const noexcept;
----

Conversion operator.
If the *cl_khr_fp16* extension is not supported, `vload_half` built-in function is called.
The operator is only present if the double precision support is enabled.

[[arithmetic-operations]]
==== Arithmetic operations

[source]
----
fp16 &operator++() noexcept;
----

Pre-increment operator.
If the *cl_khr_fp16* extension is not supported, `vload_half` and `vstore_half` built-in functions are called.

[source]
----
fp16 operator++(int) noexcept;
----

Post-increment operator.
If the *cl_khr_fp16* extension is not supported, `vload_half` and `vstore_half` built-in functions are called.

[source]
----
fp16 &operator--() noexcept;
----

Pre-decrement operator.
If the *cl_khr_fp16* extension is not supported, `vload_half` and `vstore_half` built-in functions are called.

[source]
----
fp16 operator--(int) noexcept;
----

Pre-decrement operator.
If the *cl_khr_fp16* extension is not supported, `vload_half` and `vstore_half` built-in functions are called.

[source]
----
fp16 &operator+=(const fp16 &r) noexcept;
----

Addition operator.
If the *cl_khr_fp16* extension is not supported, `vload_half` and `vstore_half` built-in functions are called.

[source]
----
fp16 &operator-=(const fp16 &r) noexcept;
----

Subtract operator.
If the *cl_khr_fp16* extension is not supported, `vload_half` and `vstore_half` built-in functions are called.

[source]
----
fp16 &operator*=(const fp16 &r) noexcept;
----

Multiplication operator.
If the *cl_khr_fp16* extension is not supported, `vload_half` and `vstore_half` built-in functions are called.

[source]
----
fp16 &operator/=(const fp16 &r) noexcept;
----

Division operator.
If the *cl_khr_fp16* extension is not supported, `vload_half` and `vstore_half` built-in functions are called.

[[non-member-functions-1]]
==== Non-member functions

[source]
----
bool operator==(const fp16& lhs, const fp16& rhs) noexcept;
----

Comparison operator ==.
If the *cl_khr_fp16* extension is not supported, `vload_half` built-in function is called.

[source]
----
bool operator!=(const fp16& lhs, const fp16& rhs) noexcept;
----

Comparison operator !=.
If the *cl_khr_fp16* extension is not supported, `vload_half` built-in function is called.

[source]
----
bool operator< (const fp16& lhs, const fp16& rhs) noexcept;
----

Comparison operator <.
If the *cl_khr_fp16* extension is not supported, `vload_half` built-in function is called.

[source]
----
bool operator> (const fp16& lhs, const fp16& rhs) noexcept;
----

Comparison operator >.
If the *cl_khr_fp16* extension is not supported, `vload_half` built-in function is called.

[source]
----
bool operator<=(const fp16& lhs, const fp16& rhs) noexcept;
----

Comparison operator <=.
If the *cl_khr_fp16* extension is not supported, `vload_half` built-in function is called.

[source]
----
bool operator>=(const fp16& lhs, const fp16& rhs) noexcept;
----

Comparison operator >=.
If the *cl_khr_fp16* extension is not supported, `vload_half` built-in function is called.

[source]
----
fp16 operator+(const fp16& lhs, const fp16& rhs) noexcept;
----

Addition operator.
If the *cl_khr_fp16* extension is not supported, `vload_half` and `vstore_half` built-in functions are called.

[source]
----
fp16 operator-(const fp16& lhs, const fp16& rhs) noexcept;
----

Subtract operator.
If the *cl_khr_fp16* extension is not supported, `vload_half` and `vstore_half` built-in functions are called.

[source]
----
fp16 operator*(const fp16& lhs, const fp16& rhs) noexcept;
----

Multiplication operator.
If the *cl_khr_fp16* extension is not supported, `vload_half` and `vstore_half` built-in functions are called.

[source]
----
fp16 operator/(const fp16& lhs, const fp16& rhs) noexcept;
----

Division operator.
If the *cl_khr_fp16* extension is not supported, `vload_half` and `vstore_half` built-in functions are called.