kotlin-math/dev.romainguy.kotlin.math/Half

Half

value class Half(v: UShort) : Comparable<Half> (source)

The Half class is a wrapper and a utility class to manipulate half-precision 16-bit IEEE 754 floating point data types (also called fp16 or binary16). A half-precision float can be created from or converted to single-precision floats, and is stored in a short data type.

The IEEE 754 standard specifies an fp16 as having the following format:

Sign bit: 1 bit
Exponent width: 5 bits
Significand: 10 bits

The format is laid out as follows:

1   11111   1111111111
^   --^--   -----^----
sign  |          |_______ significand
      |
      -- exponent

Half-precision floating points can be useful to save memory and/or bandwidth at the expense of range and precision when compared to single-precision floating points (fp32).

To help you decide whether fp16 is the right storage type for you need, please refer to the table below that shows the available precision throughout the range of possible values. The precision column indicates the step size between two consecutive numbers in a specific part of the range.

Range start	Precision
0	1 ⁄ 16,777,216
1 ⁄ 16,384	1 ⁄ 16,777,216
1 ⁄ 8,192	1 ⁄ 8,388,608
1 ⁄ 4,096	1 ⁄ 4,194,304
1 ⁄ 2,048	1 ⁄ 2,097,152
1 ⁄ 1,024	1 ⁄ 1,048,576
1 ⁄ 512	1 ⁄ 524,288
1 ⁄ 256	1 ⁄ 262,144
1 ⁄ 128	1 ⁄ 131,072
1 ⁄ 64	1 ⁄ 65,536
1 ⁄ 32	1 ⁄ 32,768
1 ⁄ 16	1 ⁄ 16,384
1 ⁄ 8	1 ⁄ 8,192
1 ⁄ 4	1 ⁄ 4,096
1 ⁄ 2	1 ⁄ 2,048
1	1 ⁄ 1,024
2	1 ⁄ 512
4	1 ⁄ 256
8	1 ⁄ 128
16	1 ⁄ 64
32	1 ⁄ 32
64	1 ⁄ 16
128	1 ⁄ 8
256	1 ⁄ 4
512	1 ⁄ 2
1,024	1
2,048	2
4,096	4
8,192	8
16,384	16
32,768	32

This table shows that numbers higher than 1024 lose all fractional precision.

Constructors

Half

fun Half(v: UShort)

Types

Companion

object Companion

Functions

compareTo

open operator override fun compareTo(other: Half): Int

dec

operator fun dec(): Half

div

operator fun div(other: Half): Half

inc

operator fun inc(): Half

isFinite

fun isFinite(): Boolean

Returns true if this half-precision float value does not represent infinity nor NaN, false otherwise.

isInfinite

fun isInfinite(): Boolean

Returns true if this half-precision float value represents infinity, false otherwise.

isNaN

fun isNaN(): Boolean

Returns true if this half-precision float value represents a Not-a-Number, false otherwise.

isNormalized

fun isNormalized(): Boolean

Returns true if this half-precision float value is normalized (does not have a subnormal representation). If this value is Half.POSITIVE_INFINITY, Half.NEGATIVE_INFINITY, Half.POSITIVE_ZERO, Half.NEGATIVE_ZERO, NaN or any subnormal number, this method returns false.

isZero

fun isZero(): Boolean

Returns true if this half-precision float value represents zero, false otherwise.

minus

operator fun minus(other: Half): Half

nextDown

fun nextDown(): Half

Returns the Half value nearest to this value in direction of negative infinity.

nextTowards

fun nextTowards(to: Half): Half

Returns the Half value nearest to this value in direction from this value towards the value to.

nextUp

fun nextUp(): Half

Returns the Half value nearest to this value in direction of positive infinity.

plus

operator fun plus(other: Half): Half

roundToInt

fun roundToInt(): Int

Rounds this Half value to the nearest integer and converts the result to Int. Ties are rounded towards positive infinity.

roundToLong

fun roundToLong(): Long

Rounds this Half value to the nearest integer and converts the result to Long. Ties are rounded towards positive infinity.

times

operator fun times(other: Half): Half

toBits

fun toBits(): Int

Returns a bit representation of this half-precision floating point value as Int according to the IEEE 754 floating-point half-precision bit layout.

toByte

fun toByte(): Byte

Returns the value of this Half as a byte after a narrowing primitive conversion.

toDouble

fun toDouble(): Double

Returns the value of this Half as a double after a widening primitive conversion.

toFloat

fun toFloat(): Float

Returns the value of this Half as a float after a widening primitive conversion.

toHexString

fun toHexString(): String

Returns a hexadecimal string representation of the specified half-precision float value. If the value is a NaN, the result is "NaN", otherwise the result follows this format:

toInt

fun toInt(): Int

Returns the value of this Half as a int after a narrowing primitive conversion.

toLong

fun toLong(): Long

Returns the value of this Half as a long after a narrowing primitive conversion.

toShort

fun toShort(): Short

Returns the value of this Half as a short after a narrowing primitive conversion.

toString

open override fun toString(): String

unaryMinus

operator fun unaryMinus(): Half

unaryPlus

operator fun unaryPlus(): Half

withSign

fun withSign(sign: Half): Half

Returns this value with the sign bit same as of the sign value. If sign is NaN the sign of the result is undefined.

Properties

absoluteValue

val absoluteValue: Half

Returns the absolute value of this half-precision float. Special values are handled in the following ways:

exponent

val exponent: Int

Returns the unbiased exponent used in the representation of this half-precision float value. if the value is NaN or infinite, this method returns MAX_EXPONENT + 1. If the argument is 0 or a subnormal representation, this method returns MIN_EXPONENT - 1.

sign

val sign: Half

Returns the sign of this half-precision float value:

significand

val significand: Int

Returns the significand, or mantissa, used in the representation of this half-precision float value.

ulp

val ulp: Half

Returns the ulp of this value. An ulp is a positive distance between this value and the next nearest Half value larger in magnitude.