Package 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
    Description
    static final short
    NaN
     
    static final short
    POSITIVE_INFINITY
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    Float16()
     

  • Method Summary

    Modifier and Type
    Method
    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 Details

  • Constructor Details

    • Float16

      public Float16()

  • Method Details

    • 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