org.apache.arrow.memory.util

Class Float16

java.lang.Object

org.apache.arrow.memory.util.Float16

public class Float16
extends Object

Lifted from Apache Parquet MR project: https://github.com/apache/parquet-mr/blob/e87b80308869b77f914fcfd04364686e11158950/parquet-column/src/main/java/org/apache/parquet/schema/Float16.java

Changes made:
• Modify the data type input from Parquet-MR Binary (toFloat(Binary b)) to Arrow Java short (toFloat(short b))
• Expose NAN and POSITIVE_INFINITY variables

The class is 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 float16 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 (float32). Ref: https://android.googlesource.com/platform/libcore/+/master/luni/src/main/java/libcore/util/FP16.java

Field Summary

Fields

Modifier and Type	Field and Description
static short	NaN
static short	POSITIVE_INFINITY

Constructor Summary

Constructors

Constructor and Description
Float16()

Method Summary

Modifier and Type	Method and Description
static int	compare(short x, short y) Compares the two specified half-precision float values.
static boolean	isNaN(short h) Returns true if the specified half-precision float value represents a Not-a-Number, false otherwise.
static float	toFloat(short b) Converts the specified half-precision float value into a single-precision float value.
static short	toFloat16(float f) Converts the specified single-precision float value into a half-precision float value.
static String	toFloatString(short h) Returns a string representation of the specified half-precision float value.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

POSITIVE_INFINITY

public static final short POSITIVE_INFINITY

See Also:

Constant Field Values

NaN

public static final short NaN

See Also:

Constant Field Values

Constructor Detail

Float16

public Float16()

Method Detail

isNaN

public static boolean isNaN(short h)

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

Parameters:

h - A half-precision float value

Returns:

True if the value is a NaN, false otherwise

compare

public static int compare(short x,
                          short y)

Compares the two specified half-precision float values. 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 #POSITIVE_INFINITY)
• POSITIVE_ZERO is considered by this method to be greater than NEGATIVE_ZERO.

Parameters:

x - The first half-precision float value to compare.

y - The second half-precision float value to compare

Returns:

The value 0 if x is numerically equal to y, a value less than 0 if x is numerically less than y, and a value greater than 0 if x is numerically greater than y

toFloat

public static float toFloat(short b)

Converts the specified half-precision float value into a single-precision float value. The following special cases are handled: If the input is NaN, the returned value is Float NaN. If the input is POSITIVE_INFINITY or NEGATIVE_INFINITY, the returned value is respectively Float POSITIVE_INFINITY or Float NEGATIVE_INFINITY. If the input is 0 (positive or negative), the returned value is +/-0.0f. Otherwise, the returned value is a normalized single-precision float value.

Parameters:

b - The half-precision float value to convert to single-precision

Returns:

A normalized single-precision float value

toFloat16

public static short toFloat16(float f)

Converts the specified single-precision float value into a half-precision float value. The following special cases are handled: If the input is NaN, the returned value is NaN. If the input is Float POSITIVE_INFINITY or Float NEGATIVE_INFINITY, the returned value is respectively POSITIVE_INFINITY or NEGATIVE_INFINITY. If the input is 0 (positive or negative), the returned value is POSITIVE_ZERO or NEGATIVE_ZERO. If the input is a less than MIN_VALUE, the returned value is flushed to POSITIVE_ZERO or NEGATIVE_ZERO. If the input is a less than MIN_NORMAL, the returned value is a denorm half-precision float. Otherwise, the returned value is rounded to the nearest representable half-precision float value.

Parameters:

f - The single-precision float value to convert to half-precision

Returns:

A half-precision float value

toFloatString

public static String toFloatString(short h)

Returns a string representation of the specified half-precision float value. Calling this method is equivalent to calling Float.toString(toFloat(h)). See Float.toString(float) for more information on the format of the string representation.

Parameters:

h - A half-precision float value in binary little-endian format

Returns:

A string representation of the specified value