cxx/stdlib/limits.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/

[[limits-library]]
=== Limits Library

OpenCL {cpp} standard library implements modified version of the numeric limits library described in chapter _18.3 [support.limits]_ of {cpp14} standard.

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

[source]
----
namespace cl
{

template<class T> class numeric_limits;

enum float_round_style;
enum float_denorm_style;

#define CHAR_BIT    8
#define CHAR_MAX    SCHAR_MAX
#define CHAR_MIN    SCHAR_MIN
#define INT_MAX     2147483647
#define INT_MIN     (-2147483647 - 1)
#define LONG_MAX    0x7fffffffffffffffL
#define LONG_MIN    (-0x7fffffffffffffffL - 1)
#define SCHAR_MAX   127
#define SCHAR_MIN   (-127 - 1)
#define SHRT_MAX    32767
#define SHRT_MIN    (-32767 - 1)
#define UCHAR_MAX   255
#define USHRT_MAX   65535
#define UINT_MAX    0xffffffff
#define ULONG_MAX   0xffffffffffffffffUL

template<> class numeric_limits<bool>;
template<> class numeric_limits<bool2>;
template<> class numeric_limits<bool3>;
template<> class numeric_limits<bool4>;
template<> class numeric_limits<bool8>;
template<> class numeric_limits<bool16>;
template<> class numeric_limits<char>;
template<> class numeric_limits<char2>;
template<> class numeric_limits<char3>;
template<> class numeric_limits<char4>;
template<> class numeric_limits<char8>;
template<> class numeric_limits<char16>;
template<> class numeric_limits<uchar>;
template<> class numeric_limits<uchar2>;
template<> class numeric_limits<uchar3>;
template<> class numeric_limits<uchar4>;
template<> class numeric_limits<uchar8>;
template<> class numeric_limits<uchar16>;
template<> class numeric_limits<short>;
template<> class numeric_limits<short2>;
template<> class numeric_limits<short3>;
template<> class numeric_limits<short4>;
template<> class numeric_limits<short8>;
template<> class numeric_limits<short16>;
template<> class numeric_limits<ushort>;
template<> class numeric_limits<ushort2>;
template<> class numeric_limits<ushort3>;
template<> class numeric_limits<ushort4>;
template<> class numeric_limits<ushort8>;
template<> class numeric_limits<ushort16>;
template<> class numeric_limits<int>;
template<> class numeric_limits<int2>;
template<> class numeric_limits<int3>;
template<> class numeric_limits<int4>;
template<> class numeric_limits<int8>;
template<> class numeric_limits<int16>;
template<> class numeric_limits<uint>;
template<> class numeric_limits<uint2>;
template<> class numeric_limits<uint3>;
template<> class numeric_limits<uint4>;
template<> class numeric_limits<uint8>;
template<> class numeric_limits<uint16>;
template<> class numeric_limits<long>;
template<> class numeric_limits<long2>;
template<> class numeric_limits<long3>;
template<> class numeric_limits<long4>;
template<> class numeric_limits<long8>;
template<> class numeric_limits<long16>;
template<> class numeric_limits<ulong>;
template<> class numeric_limits<ulong2>;
template<> class numeric_limits<ulong3>;
template<> class numeric_limits<ulong4>;
template<> class numeric_limits<ulong8>;
template<> class numeric_limits<ulong16>;

#ifdef cl_khr_fp16
#define HALF_DIG        3
#define HALF_MANT_DIG   11
#define HALF_MAX_10_EXP +4
#define HALF_MAX_EXP    +16
#define HALF_MIN_10_EXP -4
#define HALF_MIN_EXP    -13
#define HALF_RADIX      2
#define HALF_MAX        0x1.ffcp15h
#define HALF_MIN        0x1.0p-14h
#define HALF_EPSILON    0x1.0p-10h

template<> class numeric_limits<half>;
#endif

#define FLT_DIG         6
#define FLT_MANT_DIG    24
#define FLT_MAX_10_EXP  +38
#define FLT_MAX_EXP     +128
#define FLT_MIN_10_EXP  -37
#define FLT_MIN_EXP     -125
#define FLT_RADIX       2
#define FLT_MAX         0x1.fffffep127f
#define FLT_MIN         0x1.0p-126f
#define FLT_EPSILON     0x1.0p-23f
template<> class numeric_limits<float>;

#ifdef cl_khr_fp64
#define DBL_DIG         15
#define DBL_MANT_DIG    53
#define DBL_MAX_10_EXP  +308
#define DBL_MAX_EXP     +1024
#define DBL_MIN_10_EXP  -307
#define DBL_MIN_EXP     -1021
#define DBL_MAX         0x1.fffffffffffffp1023
#define DBL_MIN         0x1.0p-1022
#define DBL_EPSILON     0x1.0p-52

template<> class numeric_limits<double>;
#endif

}
----

[[class-numeric_limits]]
==== Class numeric_limits
[source]
----
namespace cl
{
template<class T>
class numeric_limits
{
public:
  static constexpr bool is_specialized = false;
  static constexpr T min() noexcept { return T(); }
  static constexpr T max() noexcept { return T(); }
  static constexpr T lowest() noexcept { return T(); }
  static constexpr int digits = 0;
  static constexpr int digits10 = 0;
  static constexpr int max_digits10 = 0;
  static constexpr bool is_signed = false;
  static constexpr bool is_integer = false;
  static constexpr bool is_exact = false;
  static constexpr int radix = 0;
  static constexpr T epsilon() noexcept { return T(); }
  static constexpr T round_error() noexcept { return T(); }
  static constexpr int min_exponent = 0;
  static constexpr int min_exponent10 = 0;
  static constexpr int max_exponent = 0;
  static constexpr int max_exponent10 = 0;
  static constexpr bool has_infinity = false;
  static constexpr bool has_quiet_NaN = false;
  static constexpr bool has_signaling_NaN = false;
  static constexpr float_denorm_style has_denorm = denorm_absent;
  static constexpr bool has_denorm_loss = false;
  static constexpr T infinity() noexcept { return T(); }
  static constexpr T quiet_NaN() noexcept { return T(); }
  static constexpr T signaling_NaN() noexcept { return T(); }
  static constexpr T denorm_min() noexcept { return T(); }
  static constexpr bool is_iec559 = false;
  static constexpr bool is_bounded = false;
  static constexpr bool is_modulo = false;
  static constexpr bool traps = false;
  static constexpr bool tinyness_before = false;
  static constexpr float_round_style round_style = round_toward_zero;
  static constexpr bool is_scalar = false;
  static constexpr bool is_vector = false;
};

template<class T> class numeric_limits<const T>;
template<class T> class numeric_limits<volatile T>;
template<class T> class numeric_limits<const volatile T>;

}
----

[[has_denorm-numeric_limits-class-member]]
==== has_denorm numeric_limits class member

`has_denorm` class member value depends on a macro:

  * `HAS_SINGLE_FP_DENORM` for type `float`.
  * `HAS_HALF_FP_DENORM` for type `half`.
  * `HAS_DOUBLE_FP_DENORM` for type `double`.

If a macro is defined, `has_denorm` is set to `denorm_present`.
Otherwise it is `denorm_absent`.

[[floating-point-macros-and-limits]]
==== Floating-point macros and limits

The macro names given in the following list must use the values specified.
These constant expressions are suitable for use in `#if` preprocessing directives.

[source]
----
#define FLT_DIG         6
#define FLT_MANT_DIG    24
#define FLT_MAX_10_EXP  +38
#define FLT_MAX_EXP     +128
#define FLT_MIN_10_EXP  -37
#define FLT_MIN_EXP     -125
#define FLT_RADIX       2
#define FLT_MAX         0x1.fffffep127f
#define FLT_MIN         0x1.0p-126f
#define FLT_EPSILON     0x1.0p-23f
----

The following table describes the built-in macro names given above in the OpenCL {cpp} library and the corresponding macro names available to the application.

.Float Built-in Macros
[width="100%",cols="50%,50%",options="header"]
|====
| *Macro in OpenCL {cpp}*
| *Macro for application*

| `FLT_DIG`
| `CL_FLT_DIG`

| `FLT_MANT_DIG`
| `CL_FLT_MANT_DIG`

| `FLT_MAX_10_EXP`
| `CL_FLT_MAX_10_EXP`

| `FLT_MAX_EXP`
| `CL_FLT_MAX_EXP`

| `FLT_MIN_10_EXP`
| `CL_FLT_MIN_10_EXP`

| `FLT_MIN_EXP`
| `CL_FLT_MIN_EXP`

| `FLT_RADIX`
| `CL_FLT_RADIX`

| `FLT_MAX`
| `CL_FLT_MAX`

| `FLT_MIN`
| `CL_FLT_MIN`

| `FLT_EPSILSON`
| `CL_FLT_EPSILON`
|====


The following macros shall expand to integer constant expressions whose values are returned by `ilogb(x)` if `x` is zero or NaN, respectively.
The value of `FP_ILOGB0` shall be either `INT_MIN` or `INT_MAX`. The value of `FP_ILOGBNAN` shall be either `INT_MAX` or `INT_MIN`.

If double precision is supported by the device, the following macros and constants are available:

[source]
----
#define DBL_DIG         15
#define DBL_MANT_DIG    53
#define DBL_MAX_10_EXP  +308
#define DBL_MAX_EXP     +1024
#define DBL_MIN_10_EXP  -307
#define DBL_MIN_EXP     -1021
#define DBL_MAX         0x1.fffffffffffffp1023
#define DBL_MIN         0x1.0p-1022
#define DBL_EPSILON     0x1.0p-52
----

The macro names given in the following list must use the values specified.
These constant expressions are suitable for use in `#if` preprocessing directives.

The following table describes the built-in macro names given above in the OpenCL {cpp} library and the corresponding macro names available to the application.

.Double Built-in Macros
[width="100%",cols="50%,50%",options="header"]
|====
| *Macro in OpenCL cpp*
| *Macro for application*

| `DBL_DIG`
| `CL_DBL_DIG`

| `DBL_MANT_DIG`
| `CL_DBL_MANT_DIG`

| `DBL_MAX_10_EXP`
| `CL_DBL_MAX_10_EXP`

| `DBL_MAX_EXP`
| `CL_DBL_MAX_EXP`

| `DBL_MIN_10_EXP`
| `CL_DBL_MIN_10_EXP`

| `DBL_MIN_EXP`
| `CL_DBL_MIN_EXP`

| `DBL_MAX`
| `CL_DBL_MAX`

| `DBL_MIN`
| `CL_DBL_MIN`

| `DBL_EPSILSON`
| `CL_DBL_EPSILON`
|====


If half precision arithmetic operations are supported, the following macros and constants for half precision floating-point are available:

[source]
----
#define HALF_DIG        3
#define HALF_MANT_DIG   11
#define HALF_MAX_10_EXP +4
#define HALF_MAX_EXP    +16
#define HALF_MIN_10_EXP -4
#define HALF_MIN_EXP    -13
#define HALF_RADIX      2
#define HALF_MAX        0x1.ffcp15h
#define HALF_MIN        0x1.0p-14h
#define HALF_EPSILON    0x1.0p-10h
----

The macro names given in the following list must use the values specified.
These constant expressions are suitable for use in `#if` preprocessing directives.

The following table describes the built-in macro names given above in the OpenCL {cpp} library and the corresponding macro names available to the application.

.Half Built-in Macros
[width="100%",cols="50%,50%",options="header"]
|====
| *Macro in OpenCL cpp*
| *Macro for application*

| `HALF_DIG`
| `CL_HALF_DIG`

| `HALF_MANT_DIG`
| `CL_HALF_MANT_DIG`

| `HALF_MAX_10_EXP`
| `CL_HALF_MAX_10_EXP`

| `HALF_MAX_EXP`
| `CL_HALF_MAX_EXP`

| `HALF_MIN_10_EXP`
| `CL_HALF_MIN_10_EXP`

| `HALF_MIN_EXP`
| `CL_HALF_MIN_EXP`

| `HALF_RADIX`
| `CL_HALF_RADIX`

| `HALF_MAX`
| `CL_HALF_MAX`

| `HALF_MIN`
| `CL_HALF_MIN`

| `HALF_EPSILSON`
| `CL_HALF_EPSILON`
|====

The following symbolic constants are available.
Their values are of type float and are accurate within the precision of a single precision floating-point number.

.Float Symbolic Constants
[width="100%",cols="50%,50%",options="header"]
|====
| *Constant Name*
| *Description*

| `MAXFLOAT`
| Value of maximum non-infinite single-precision floating-point number.

| `HUGE_VALF`
| A positive float constant expression. `HUGE_VALF` evaluates to +infinity.
  Used as an error value returned by the built-in math functions.

| `INFINITY`
| A constant expression of type float representing positive or unsigned infinity.

| `NAN`
| A constant expression of type float representing a quiet NaN.
|====

If double precision is supported by the device, the following symbolic constant will also be available:

.Double Symbolic Constants
[width="100%",cols="50%,50%",options="header"]
|====
| *Constant Name*
| *Description*

| `HUGE_VAL`
| A positive double constant expression.
  `HUGE_VAL` evaluates to +infinity.
  Used as an error value returned by the built-in math functions.
|====

[[integer-macros-and-limits]]
==== Integer macros and limits

The macro names given in the following list must use the values specified.
The values shall all be constant expressions suitable for use in `#if` preprocessing directives.

[source]
----
#define CHAR_BIT    8
#define CHAR_MAX    SCHAR_MAX
#define CHAR_MIN    SCHAR_MIN
#define INT_MAX     2147483647
#define INT_MIN     (-2147483647 - 1)
#define LONG_MAX    0x7fffffffffffffffL
#define LONG_MIN    (-0x7fffffffffffffffL - 1)
#define SCHAR_MAX   127
#define SCHAR_MIN   (-127 - 1)
#define SHRT_MAX    32767
#define SHRT_MIN    (-32767 - 1)
#define UCHAR_MAX   255
#define USHRT_MAX   65535
#define UINT_MAX    0xffffffff
#define ULONG_MAX   0xffffffffffffffffUL
----

The following table describes the built-in macro names given above in the OpenCL {cpp} library and the corresponding macro names available to the application.

.Integer built-in macros
[width="100%",cols="50%,50%",options="header"]
|====
| *Macro in OpenCL cpp*
| *Macro for application*

| `CHAR_BIT`
| `CL_CHAR_BIT`

| `CHAR_MAX`
| `CL_CHAR_MAX`

| `CHAR_MIN`
| `CL_CHAR_MIN`

| `INT_MAX`
| `CL_INT_MAX`

| `INT_MIN`
| `CL_INT_MIN`

| `LONG_MAX`
| `CL_LONG_MAX`

| `LONG_MIN`
| `CL_LONG_MIN`

| `SCHAR_MAX`
| `CL_SCHAR_MAX`

| `SCHAR_MIN`
| `CL_SCHAR_MIN`

| `SHRT_MAX`
| `CL_SHRT_MAX`

| `SHRT_MIN`
| `CL_SHRT_MIN`

| `UCHAR_MAX`
| `CL_UCHAR_MAX`

| `USHRT_MAX`
| `CL_USHRT_MAX`

| `UINT_MAX`
| `CL_UINT_MAX`

| `ULONG_MAX`
| `CL_ULONG_MAX`
|====