The half Class

#include <Imath/half.h>

half is a 16-bit floating point number. See `The half Type`_ for an explanation of the representation.

Also, see `C-language half Conversion`_ for C-language support for conversion between half and float.

Example:

#include <Imath/half.h>
#include <math.h>

void
half_example()
{
    half a (3.5);
    float b (a + sqrt (a));
    a += b;
    b += a;
    b = a + 7;
}
class Imath::half

class half 16-bit floating point number

Type half can represent positive and negative numbers whose magnitude is between roughly 6.1e-5 and 6.5e+4 with a relative error of 9.8e-4; numbers smaller than 6.1e-5 can be represented with an absolute error of 6.0e-8. All integers from -2048 to +2048 can be represented exactly.

Type half behaves (almost) like the built-in C++ floating point types. In arithmetic expressions, half, float and double can be mixed freely. Here are a few examples:

half a (3.5);
float b (a + sqrt (a));
a += b;
b += a;
b = a + 7;

Conversions from half to float are lossless; all half numbers are exactly representable as floats.

Conversions from float to half may not preserve a float’s value exactly. If a float is not representable as a half, then the float value is rounded to the nearest representable half. If a float value is exactly in the middle between the two closest representable half values, then the float value is rounded to the closest half whose least significant bit is zero.

Overflows during float-to-half conversions cause arithmetic exceptions. An overflow occurs when the float value to be converted is too large to be represented as a half, or if the float value is an infinity or a NAN.

The implementation of type half makes the following assumptions about the implementation of the built-in C++ types:

  • float is an IEEE 754 single-precision number

  • sizeof (float) == 4

  • sizeof (unsigned int) == sizeof (float)

  • alignof (unsigned int) == alignof (float)

  • sizeof (uint16_t) == 2

Constructors

half() noexcept = default

Default construction provides no initialization (hence it is not constexpr).

inline half(float f) noexcept

Construct from float.

inline constexpr half(FromBitsTag, uint16_t bits) noexcept

Construct from bit-vector.

constexpr half(const half&) noexcept = default

Copy constructor.

constexpr half(half&&) noexcept = default

Move constructor.

~half() noexcept = default

Destructor.

Basic Algebra

inline constexpr half operator-() const noexcept

Unary minus.

half &operator=(const half &h) noexcept = default

Assignment.

half &operator=(half &&h) noexcept = default

Move assignment.

inline half &operator=(float f) noexcept

Assignment from float.

inline half &operator+=(half h) noexcept

Addition assignment.

inline half &operator+=(float f) noexcept

Addition assignment from float.

inline half &operator-=(half h) noexcept

Subtraction assignment.

inline half &operator-=(float f) noexcept

Subtraction assignment from float.

inline half &operator*=(half h) noexcept

Multiplication assignment.

inline half &operator*=(float f) noexcept

Multiplication assignment from float.

inline half &operator/=(half h) noexcept

Division assignment.

inline half &operator/=(float f) noexcept

Division assignment from float.

Classification

inline constexpr bool isFinite() const noexcept

Return true if a normalized number, a denormalized number, or zero.

inline constexpr bool isNormalized() const noexcept

Return true if a normalized number.

inline constexpr bool isDenormalized() const noexcept

Return true if a denormalized number.

inline constexpr bool isZero() const noexcept

Return true if zero.

inline constexpr bool isNan() const noexcept

Return true if NAN.

inline constexpr bool isInfinity() const noexcept

Return true if a positive or a negative infinity.

inline constexpr bool isNegative() const noexcept

Return true if the sign bit is set (negative)

Special values

static inline constexpr half posInf() noexcept

Return +infinity.

static inline constexpr half negInf() noexcept

Return -infinity.

static inline constexpr half qNan() noexcept

Returns a NAN with the bit pattern 0111111111111111.

static inline constexpr half sNan() noexcept

Return a NAN with the bit pattern 0111110111111111.

Access to the internal representation

inline constexpr uint16_t bits() const noexcept

Return the bit pattern.

inline constexpr void setBits(uint16_t bits) noexcept

Set the bit pattern.

Public Types

enum FromBitsTag

A special tag that lets us initialize a half from the raw bits.

Values:

enumerator FromBits
using uif = imath_half_uif

Public Functions

inline operator float() const noexcept

Conversion to float.

inline constexpr half round(unsigned int n) const noexcept

Round to n-bit precision (n should be between 0 and 10).

After rounding, the significand’s 10-n least significant bits will be zero.

std::ostream &operator<<(std::ostream &os, Imath::half h)

Output h to os, formatted as a float.

Warning

doxygenfunction: Unable to resolve function “operator>>” with arguments (std::ostream&, Imath::half&) in doxygen xml output for project “Imath” from directory: doxyxml/. Potential matches:

- std::istream &operator>>(std::istream &is, Imath::half &h)