Float16

class Float16 : Comparable<Float16>
kotlin.Any
   ↳ androidx.ui.util.Float16

The Float16 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. To distinguish short values holding half-precision floats from regular short values, it is recommended to use the @HalfFloat annotation.

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.

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

Summary

Constants

const Int

Maximum exponent a finite half-precision float may have.

const Int

Minimum exponent a normalized half-precision float may have.

const Int

The number of bits used to represent a half-precision float value.

Public constructors

<init>(value: Float)

Constructs a newly allocated Float16 object that represents the argument converted to a half-precision float.

<init>(value: Double)

Constructs a newly allocated Float16 object that represents the argument converted to a half-precision float.

<init>(halfValue: Short)

The Float16 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).

Public methods

Float16

Returns the absolute value of the half-precision float.

Float16

Returns the smallest half-precision float value toward negative infinity greater than or equal to this half-precision float value.

operator Int

Compares to another half-precision float value.

Boolean
equals(@Nullable other: Any?)

Compares this object against the specified object.

Float16

Returns the largest half-precision float value toward positive infinity less than or equal to this half-precision float value.

Int

Returns a hash code for this Float16 object.

Boolean

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

Boolean

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

Boolean

Returns true if this Float16 value represents a Not-a-Number, false otherwise.

Boolean

Returns true if the half-precision float value is normalized (does not have a subnormal representation).

Float16

Returns the closest integral half-precision float value to the this half-precision float value.

Int

Returns a representation of the half-precision float value according to the bit layout described in Float16.

Byte

Returns the value of this Float16 as a Byte after a narrowing primitive conversion.

Double

Returns the value of this Float16 as a Double after a widening primitive conversion.

Float

Returns the value of this Float16 as a Float after a widening primitive conversion.

String

Returns a hexadecimal string representation of the half-precision float value.

Int

Returns the value of this Float16 as a Int after a narrowing primitive conversion.

Long

Returns the value of this Float16 as a Long after a narrowing primitive conversion.

Int

Returns a representation of the half-precision float value according to the bit layout described in Float16.

Short

Returns the value of this Float16 as a Short after a narrowing primitive conversion.

String

Returns a string representation of the specified half-precision float value.

Float16

Returns the truncated half-precision float value of this half-precision float value.

Float16

Returns a Float16 with the magnitude of this and the sign of sign

Properties

Int

The unbiased exponent used in the representation of the specified half-precision float value.

Short

Float16

Returns the sign of this half-precision float value.

Int

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

Companion properties

Float16

Epsilon is the difference between 1.

Float16

Smallest negative value a half-precision float may have.

Float16

Maximum positive finite value a half-precision float may have.

Float16

Smallest positive normal value a half-precision float may have.

Float16

Smallest positive non-zero value a half-precision float may have.

Float16

A Not-a-Number representation of a half-precision float.

Float16

Negative infinity of type half-precision float.

Float16

Negative 0 of type half-precision float.

Float16

Positive infinity of type half-precision float.

Float16

Positive 0 of type half-precision float.

Constants

MaxExponent

const val MaxExponent: Int

Maximum exponent a finite half-precision float may have.

Value: 15

MinExponent

const val MinExponent: Int

Minimum exponent a normalized half-precision float may have.

Value: -14

Size

const val Size: Int

The number of bits used to represent a half-precision float value.

Value: 16

Public constructors

<init>

Float16(value: Float)

Constructs a newly allocated Float16 object that represents the argument converted to a half-precision float.

Parameters
value: Float The value to be represented by the Float16

<init>

Float16(value: Double)

Constructs a newly allocated Float16 object that represents the argument converted to a half-precision float.

Parameters
value: Double The value to be represented by the Float16

<init>

Float16(halfValue: Short)

The Float16 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. To distinguish short values holding half-precision floats from regular short values, it is recommended to use the @HalfFloat annotation.

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.

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

Public methods

absoluteValue

fun absoluteValue(): Float16

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

  • If the specified half-precision float is NaN, the result is NaN
  • If the specified half-precision float is zero (negative or positive), the result is positive zero (see PositiveZero)
  • If the specified half-precision float is infinity (negative or positive), the result is positive infinity (see PositiveInfinity)

ceil

fun ceil(): Float16

Returns the smallest half-precision float value toward negative infinity greater than or equal to this half-precision float value. Special values are handled in the following ways:

  • If the specified half-precision float is NaN, the result is NaN
  • If the specified half-precision float is infinity (negative or positive), the result is infinity (with the same sign)
  • If the specified half-precision float is zero (negative or positive), the result is zero (with the same sign)
Return
The smallest half-precision float value toward negative infinity greater than or equal to the half-precision float value

compareTo

operator fun compareTo(other: Float16): Int

Compares to another half-precision float value. The following conditions apply during the comparison:

  • NaN is considered by this method to be equal to itself and greater than all other half-precision float values (including #PositiveInfinity)
  • PositiveZero is considered by this method to be greater than NegativeZero.
Parameters
other: Float16 The half-precision float value to compare to the half-precision value represented by this Float16 object
Return
The value 0 if this is numerically equal to h; a value less than 0 if this is numerically less than h; and a value greater than 0 if this is numerically greater than h

equals

fun equals(@Nullable other: Any?): Boolean

Compares this object against the specified object. The result is true if and only if the argument is not null and is a Float16 object that represents the same half-precision value as the this object. Two half-precision values are considered to be the same if and only if the method toBits returns an identical int value for both.

Parameters
other: Any? The object to compare
Return
True if the objects are the same, false otherwise

See Also

floor

fun floor(): Float16

Returns the largest half-precision float value toward positive infinity less than or equal to this half-precision float value. Special values are handled in the following ways:

  • If the specified half-precision float is NaN, the result is NaN
  • If the specified half-precision float is infinity (negative or positive), the result is infinity (with the same sign)
  • If the specified half-precision float is zero (negative or positive), the result is zero (with the same sign)
Return
The largest half-precision float value toward positive infinity less than or equal to the half-precision float value

hashCode

fun hashCode(): Int

Returns a hash code for this Float16 object. The result is the integer bit representation, exactly as produced by the method toBits, of the primitive half-precision float value represented by this Float16 object.

Return
A hash code value for this object

isFinite

fun isFinite(): Boolean

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

Return
False if the value is positive infinity or negative infinity, true otherwise

isInfinite

fun isInfinite(): Boolean

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

Return
True if the value is positive infinity or negative infinity, false otherwise

isNaN

fun isNaN(): Boolean

Returns true if this Float16 value represents a Not-a-Number, false otherwise.

Return
True if the value is a NaN, false otherwise

isNormalized

fun isNormalized(): Boolean

Returns true if the half-precision float value is normalized (does not have a subnormal representation). If the specified value is PositiveInfinity, NegativeInfinity, PositiveZero, NegativeZero, NaN or any subnormal number, this method returns false.

Return
True if the value is normalized, false otherwise

round

fun round(): Float16

Returns the closest integral half-precision float value to the this half-precision float value. Special values are handled in the following ways:

  • If the specified half-precision float is NaN, the result is NaN
  • If the specified half-precision float is infinity (negative or positive), the result is infinity (with the same sign)
  • If the specified half-precision float is zero (negative or positive), the result is zero (with the same sign)
Return
The value of the specified half-precision float rounded to the nearest half-precision float value

toBits

fun toBits(): Int

Returns a representation of the half-precision float value according to the bit layout described in Float16.

Unlike toRawBits, this method collapses all possible Not-a-Number values to a single canonical Not-a-Number value defined by NaN.

Return
The bits that represent the half-precision float value

toByte

fun toByte(): Byte

Returns the value of this Float16 as a Byte after a narrowing primitive conversion.

Return
The half-precision float value represented by this object converted to type Byte

toDouble

fun toDouble(): Double

Returns the value of this Float16 as a Double after a widening primitive conversion.

Return
The half-precision float value represented by this object converted to type Double

toFloat

fun toFloat(): Float

Returns the value of this Float16 as a Float after a widening primitive conversion.

Return
The half-precision float value represented by this object converted to type Float

toHexString

@NonNull fun toHexString(): String

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

  • If the sign is positive, no sign character appears in the result
  • If the sign is negative, the first character is '-'
  • If the value is inifinity, the string is "Infinity"
  • If the value is 0, the string is "0x0.0p0"
  • If the value has a normalized representation, the exponent and significand are represented in the string in two fields. The significand starts with "0x1." followed by its lowercase hexadecimal representation. Trailing zeroes are removed unless all digits are 0, then a single zero is used. The significand representation is followed by the exponent, represented by "p", itself followed by a decimal string of the unbiased exponent
  • If the value has a subnormal representation, the significand starts with "0x0." followed by its lowercase hexadecimal representation. Trailing zeroes are removed unless all digits are 0, then a single zero is used. The significand representation is followed by the exponent, represented by "p-14"
Return
A hexadecimal string representation of the specified value

toInt

fun toInt(): Int

Returns the value of this Float16 as a Int after a narrowing primitive conversion.

Return
The half-precision float value represented by this object converted to type Int

toLong

fun toLong(): Long

Returns the value of this Float16 as a Long after a narrowing primitive conversion.

Return
The half-precision float value represented by this object converted to type Long

toRawBits

fun toRawBits(): Int

Returns a representation of the half-precision float value according to the bit layout described in Float16.

Return
The bits that represent the half-precision float value

toShort

fun toShort(): Short

Returns the value of this Float16 as a Short after a narrowing primitive conversion.

Return
The half-precision float value represented by this object converted to type Short

toString

fun toString(): String

Returns a string representation of the specified half-precision float value. See toString for more information.

Return
A string representation of this Float16 object

trunc

fun trunc(): Float16

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

  • If the specified half-precision float is NaN, the result is NaN
  • If the specified half-precision float is infinity (negative or positive), the result is infinity (with the same sign)
  • If the specified half-precision float is zero (negative or positive), the result is zero (with the same sign)
Return
The truncated half-precision float value of the half-precision float value

withSign

fun withSign(sign: Float16): Float16

Returns a Float16 with the magnitude of this and the sign of sign

Properties

exponent

val exponent: Int

The unbiased exponent used in the representation of the specified half-precision float value. if the value is NaN or infinite, this* method returns MaxExponent + 1. If the argument is 0 or a subnormal representation, this method returns MinExponent - 1.

halfValue

val halfValue: Short

sign

val sign: Float16

Returns the sign of this half-precision float value.

  • -1.0 if the value is negative,
  • zero if the value is zero,
  • 1.0 if the value is positive

Special case:

  • NaN.sign is NaN

significand

val significand: Int

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

Companion properties

Epsilon

val Epsilon: Float16

Epsilon is the difference between 1.0 and the next value representable by a half-precision floating-point.

LowestValue

val LowestValue: Float16

Smallest negative value a half-precision float may have.

MaxValue

val MaxValue: Float16

Maximum positive finite value a half-precision float may have.

MinNormal

val MinNormal: Float16

Smallest positive normal value a half-precision float may have.

MinValue

val MinValue: Float16

Smallest positive non-zero value a half-precision float may have.

NaN

val NaN: Float16

A Not-a-Number representation of a half-precision float.

NegativeInfinity

val NegativeInfinity: Float16

Negative infinity of type half-precision float.

NegativeZero

val NegativeZero: Float16

Negative 0 of type half-precision float.

PositiveInfinity

val PositiveInfinity: Float16

Positive infinity of type half-precision float.

PositiveZero

val PositiveZero: Float16

Positive 0 of type half-precision float.