HALF-PRECISION FLOATING-POINT LIBRARY (Version 2.1.0)
-----------------------------------------------------
This is a C++ header-only library to provide an IEEE 754 conformant 16-bit
half-precision floating-point type along with corresponding arithmetic
operators, type conversions and common mathematical functions. It aims for both
efficiency and ease of use, trying to accurately mimic the behaviour of the
built-in floating-point types at the best performance possible.
INSTALLATION AND REQUIREMENTS
-----------------------------
Conveniently, the library consists of just a single header file containing all
the functionality, which can be directly included by your projects, without the
neccessity to build anything or link to anything.
Whereas this library is fully C++98-compatible, it can profit from certain
C++11 features. Support for those features is checked automatically at compile
(or rather preprocessing) time, but can be explicitly enabled or disabled by
predefining the corresponding preprocessor symbols to either 1 or 0 yourself
before including half.hpp. This is useful when the automatic detection fails
(for more exotic implementations) or when a feature should be explicitly
disabled:
- 'long long' integer type for mathematical functions returning 'long long'
results (enabled for VC++ 2003 and icc 11.1 and newer, gcc and clang,
overridable with 'HALF_ENABLE_CPP11_LONG_LONG').
- Static assertions for extended compile-time checks (enabled for VC++ 2010,
gcc 4.3, clang 2.9, icc 11.1 and newer, overridable with
'HALF_ENABLE_CPP11_STATIC_ASSERT').
- Generalized constant expressions (enabled for VC++ 2015, gcc 4.6, clang 3.1,
icc 14.0 and newer, overridable with 'HALF_ENABLE_CPP11_CONSTEXPR').
- noexcept exception specifications (enabled for VC++ 2015, gcc 4.6,
clang 3.0, icc 14.0 and newer, overridable with 'HALF_ENABLE_CPP11_NOEXCEPT').
- User-defined literals for half-precision literals to work (enabled for
VC++ 2015, gcc 4.7, clang 3.1, icc 15.0 and newer, overridable with
'HALF_ENABLE_CPP11_USER_LITERALS').
- Thread-local storage for per-thread floating-point exception flags (enabled
for VC++ 2015, gcc 4.8, clang 3.3, icc 15.0 and newer, overridable with
'HALF_ENABLE_CPP11_THREAD_LOCAL').
- Type traits and template meta-programming features from <type_traits>
(enabled for VC++ 2010, libstdc++ 4.3, libc++ and newer, overridable with
'HALF_ENABLE_CPP11_TYPE_TRAITS').
- Special integer types from <cstdint> (enabled for VC++ 2010, libstdc++ 4.3,
libc++ and newer, overridable with 'HALF_ENABLE_CPP11_CSTDINT').
- Certain C++11 single-precision mathematical functions from <cmath> for
floating-point classification during conversions from higher precision types
(enabled for VC++ 2013, libstdc++ 4.3, libc++ and newer, overridable with
'HALF_ENABLE_CPP11_CMATH').
- Floating-point environment control from <cfenv> for possible exception
propagation to the built-in floating-point platform (enabled for VC++ 2013,
libstdc++ 4.3, libc++ and newer, overridable with 'HALF_ENABLE_CPP11_CFENV').
- Hash functor 'std::hash' from <functional> (enabled for VC++ 2010,
libstdc++ 4.3, libc++ and newer, overridable with 'HALF_ENABLE_CPP11_HASH').
The library has been tested successfully with Visual C++ 2005-2015, gcc 4-8
and clang 3-8 on 32- and 64-bit x86 systems. Please contact me if you have any
problems, suggestions or even just success testing it on other platforms.
DOCUMENTATION
-------------
What follows are some general words about the usage of the library and its
implementation. For a complete documentation of its interface consult the
corresponding website http://half.sourceforge.net. You may also generate the
complete developer documentation from the library's only include file's doxygen
comments, but this is more relevant to developers rather than mere users.
BASIC USAGE
To make use of the library just include its only header file half.hpp, which
defines all half-precision functionality inside the 'half_float' namespace. The
actual 16-bit half-precision data type is represented by the 'half' type, which
uses the standard IEEE representation with 1 sign bit, 5 exponent bits and 11
mantissa bits (including the hidden bit) and supports all types of special
values, like subnormal values, infinity and NaNs. This type behaves like the
built-in floating-point types as much as possible, supporting the usual
arithmetic, comparison and streaming operators, which makes its use pretty
straight-forward:
using half_float::half;
half a(3.4), b(5);
half c = a * b;
c += 3;
if(c > a)
std::cout << c << std::endl;
Additionally the 'half_float' namespace also defines half-precision versions
for all mathematical functions of the C++ standard library, which can be used
directly through ADL:
half a(-3.14159);
half s = sin(abs(a));
long l = lround(s);
You may also specify explicit half-precision literals, since the library
provides a user-defined literal inside the 'half_float::literal' namespace,
which you just need to import (assuming support for C++11 user-defined literals):
using namespace half_float::literal;
half x = 1.0_h;
Furthermore the library provides proper specializations for
'std::numeric_limits', defining various implementation properties, and
'std::hash' for hashing half-precision numbers (assuming support for C++11
'std::hash'). Similar to the corresponding preprocessor symbols from <cmath>
the library also defines the 'HUGE_VALH' constant and maybe the 'FP_FAST_FMAH'
symbol.
CONVERSIONS AND ROUNDING
The half is explicitly constructible/convertible from a single-precision float
argument. Thus it is also explicitly constructible/convertible from any type
implicitly convertible to float, but constructing it from types like double or
int will involve the usual warnings arising when implicitly converting those to
float because of the lost precision. On the one hand those warnings are
intentional, because converting those types to half neccessarily also reduces
precision. But on the other hand they are raised for explicit conversions from
those types, when the user knows what he is doing. So if those warnings keep
bugging you, then you won't get around first explicitly converting to float
before converting to half, or use the 'half_cast' described below. In addition
you can also directly assign float values to halfs.
In contrast to the float-to-half conversion, which reduces precision, the
conversion from half to float (and thus to any other type implicitly
convertible from float) is implicit, because all values represetable with
half-precision are also representable with single-precision. This way the
half-to-float conversion behaves similar to the builtin float-to-double
conversion and all arithmetic expressions involving both half-precision and
single-precision arguments will be of single-precision type. This way you can
also directly use the mathematical functions of the C++ standard library,
though in this case you will invoke the single-precision versions which will
also return single-precision values, which is (even if maybe performing the
exact same computation, see below) not as conceptually clean when working in a
half-precision environment.
The default rounding mode for conversions between half and more precise types
as well as for rounding results of arithmetic operations and mathematical
functions rounds to the nearest representable value. But by predefining the
'HALF_ROUND_STYLE' preprocessor symbol this default can be overridden with one
of the other standard rounding modes using their respective constants or the
equivalent values of 'std::float_round_sty
