Package com.apple.foundationdb.half

Class Half

java.lang.Object
java.lang.Number
com.apple.foundationdb.half.Half
All Implemented Interfaces:
Serializable, Comparable<Half>
public final class Half extends Number implements Comparable<Half>
The Half class implements half precision (FP16) float-point number according to IEEE 754 standard.

In addition, this class provides several methods for converting a Half to a String and a String to a Half, as well as other constants and methods useful when dealing with a Half.

Half is implemented to provide, as much as possible, the same interface as Float and Double.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    BYTES
    The number of bytes used to represent a Half value.
    static final int
    MAX_EXPONENT
    Maximum exponent a finite Half variable may have.
    static final Half
    MAX_VALUE
    A constant holding the largest positive finite value of type Half, (2-2-10)·215.
    static final int
    MIN_EXPONENT
    Minimum exponent a normalized Half variable may have.
    static final Half
    MIN_NORMAL
    A constant holding the smallest positive normal value of type Half, 2-14.
    static final Half
    MIN_VALUE
    A constant holding the smallest positive nonzero value of type Half, 2-24.
    static final Half
    NaN
    A constant holding a Not-a-Number (NaN) value of type Half.
    static final Half
    NEGATIVE_INFINITY
    A constant holding the negative infinity of type Half.
    static final Half
    NEGATIVE_MAX_VALUE
    A constant holding the largest positive finite value of type Half, (2-2-10)·215.
    static final Half
    NEGATIVE_ZERO
    A constant holding the negative zero of type Half.
    static final Half
    POSITIVE_INFINITY
    A constant holding the positive infinity of type Half.
    static final Half
    POSITIVE_ZERO
    A constant holding the positive zero of type Half.
    static final int
    SIZE
    The number of bits used to represent a Half value.

  • Method Summary

    Modifier and Type
    Method
    Description
    byte
    byteValue()
    Returns the value of the specified number as a byte.
    static int
    compare(Half half1, Half half2)
    Compares the two specified Half objects.
    int
    compareTo(Half anotherHalf)
     
    double
    doubleValue()
     
    boolean
    equals(Object obj)
     
    static short
    floatToHalfShortBits(float floatValue)
     
    static short
    floatToShortBitsCollapseNaN(float floatRepresentation)
    Returns a representation of the specified floating-point value according to the IEEE 754 floating-point "single format" bit layout.
    float
    floatValue()
     
    static float
    halfShortToFloat(short shortBits)
     
    static short
    halfToRawShortBits(Half half)
    Returns a representation of the specified floating-point value according to the IEEE 754 floating-point "single format" bit layout, preserving Not-a-Number (NaN) values.
    static short
    halfToShortBits(Half half)
    Returns a representation of the specified floating-point value according to the IEEE 754 floating-point "single format" bit layout.
    int
    hashCode()
    Returns a hash code for this Half object.
    static int
    hashCode(Half half)
    Returns a hash code for a Half; compatible with Half.hashCode().
    int
    intValue()
     
    boolean
    isFinite()
    Returns true if the argument is a finite floating-point value; returns false otherwise (for NaN and infinity arguments).
    static boolean
    isFinite(Half half)
    Returns true if the argument is a finite floating-point value; returns false otherwise (for NaN and infinity arguments).
    boolean
    isInfinite()
    Returns true if this Half value is infinitely large in magnitude, false otherwise.
    static boolean
    isInfinite(Half half)
    Returns true if the specified Half is infinitely large in magnitude, false otherwise.
    boolean
    isNaN()
    Returns true if this Half value is a Not-a-Number (NaN), false otherwise.
    static boolean
    isNaN(Half half)
    Returns true if the specified number is a Not-a-Number (NaN) value, false otherwise.
    long
    longValue()
     
    static Half
    max(Half a, Half b)
    Returns the greater of two Half objects.
    Determined using aFloatValue = a.floatValue() and bFloatValue = b.floatValue() then calling Float.max(aFloatValue, bFloatValue).
    static Half
    min(Half a, Half b)
    Returns the smaller of two Half objects.
    Determined using aFloatValue = a.floatValue() and bFloatValue = b.floatValue() then calling Float.min(aFloatValue, bFloatValue).
    static float
    quantizeFloat(float floatValue)
     
    static Half
    shortBitsToHalf(short shortBits)
    Returns the Half object corresponding to a given bit representation.
    short
    shortValue()
    Returns the value of the specified number as a short.
    static Half
    sum(Half a, Half b)
    Adds two Half values together as per the + operator.
    static String
    toHexString(Half half)
    Returns a hexadecimal string representation of the half argument.
    String
    toString()
     
    static String
    toString(Half half)
    Returns a string representation of the half argument.
    static Half
    valueOf(double doubleValue)
    Returns a Half instance representing the specified double value.
    static Half
    valueOf(float floatValue)
    Returns a Half instance representing the specified float value.
    static Half
    valueOf(Half half)
    Returns a new Half instance identical to the specified half.
    static Half
    valueOf(Double doubleValue)
    Returns a Half instance representing the specified Double value.
    static Half
    valueOf(Float floatValue)
    Returns a Half instance representing the specified Float value.
    static Half
    valueOf(String s)
    Returns a Half object represented by the argument string s.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • POSITIVE_INFINITY

      public static final Half POSITIVE_INFINITY
      A constant holding the positive infinity of type Half.

      It is equal to the value returned by shortBitsToHalf((short)0x7c00).

    • NEGATIVE_INFINITY

      public static final Half NEGATIVE_INFINITY
      A constant holding the negative infinity of type Half.

      It is equal to the value returned by shortBitsToHalf((short)0xfc00).

    • NaN

      public static final Half NaN
      A constant holding a Not-a-Number (NaN) value of type Half.

      It is equivalent to the value returned by shortBitsToHalf((short)0x7e00).

    • MAX_VALUE

      public static final Half MAX_VALUE
      A constant holding the largest positive finite value of type Half, (2-2-10)·215.

      It is equal to shortBitsToHalf((short)0x7bff).

    • NEGATIVE_MAX_VALUE

      public static final Half NEGATIVE_MAX_VALUE
      A constant holding the largest positive finite value of type Half, (2-2-10)·215.

      It is equal to shortBitsToHalf((short)0xfbff).

    • MIN_NORMAL

      public static final Half MIN_NORMAL
      A constant holding the smallest positive normal value of type Half, 2-14.

      It is equal to shortBitsToHalf((short)0x0400).

    • MIN_VALUE

      public static final Half MIN_VALUE
      A constant holding the smallest positive nonzero value of type Half, 2-24.

      It is equal to shortBitsToHalf((short)0x1).

    • MAX_EXPONENT

      public static final int MAX_EXPONENT
      Maximum exponent a finite Half variable may have.

      It is equal to the value returned by HalfMath.getExponent(Half.MAX_VALUE).

      See Also:

    • MIN_EXPONENT

      public static final int MIN_EXPONENT
      Minimum exponent a normalized Half variable may have.

      It is equal to the value returned by HalfMath.getExponent(Half.MIN_NORMAL).

      See Also:

    • SIZE

      public static final int SIZE
      The number of bits used to represent a Half value.
      See Also:

    • BYTES

      public static final int BYTES
      The number of bytes used to represent a Half value.
      See Also:

    • POSITIVE_ZERO

      public static final Half POSITIVE_ZERO
      A constant holding the positive zero of type Half.

      It is equal to the value returned by shortBitsToHalf((short)0x0).

    • NEGATIVE_ZERO

      public static final Half NEGATIVE_ZERO
      A constant holding the negative zero of type Half.

      It is equal to the value returned by shortBitsToHalf((short)0x8000).

  • Method Details

    • shortBitsToHalf

      public static Half shortBitsToHalf(short shortBits)
      Returns the Half object corresponding to a given bit representation. The argument is considered to be a representation of a floating-point value according to the IEEE 754 floating-point "half format" bit layout.

      If the argument is 0x7c00, the result is positive infinity.

      If the argument is 0xfc00, the result is negative infinity.

      If the argument is any value in the range {0x7c01} through 0x7fff or in the range 0xfc01 through 0xffff, the result is a NaN. No IEEE 754 floating-point operation provided by Java can distinguish between two NaN values of the same type with different bit patterns. Distinct values of NaN are only distinguishable by use of the Half.halfToRawShortBits method.

      In all other cases, let s, e, and m be three values that can be computed from the argument: 

       {
     @code
     int s = ((bits >> 16) == 0) ? 1 : -1;
     int e = ((bits >> 10) & 0x1f);
     int m = (e == 0) ? (bits & 0x3ff) << 1 : (bits & 0x3ff) | 0x200;
 }
      Then the float-point result equals the value of the mathematical expression s·m·2e-25.

      Note that this method may not be able to return a Half NaN with exactly same bit pattern as the short argument. IEEE 754 distinguishes between two kinds of NaNs, quiet NaNs and signaling NaNs. The differences between the two kinds of NaN are generally not visible in Java. Arithmetic operations on signaling NaNs turn them into quiet NaNs with a different, but often similar, bit pattern. However, on some processors merely copying a signaling NaN also performs that conversion. In particular, copying a signaling NaN to return it to the calling method may perform this conversion. So shortBitsToHalf may not be able to return a Half with a signaling NaN bit pattern. Consequently, for some short values, halfToRawShortBits(shortBitsToHalf(start)) may not equal start. Moreover, which particular bit patterns represent signaling NaNs is platform dependent; although all NaN bit patterns, quiet or signaling, must be in the NaN range identified above.

      Parameters:
      shortBits - a short.
      Returns:
      the Half float-point object with the same bit pattern.

    • halfShortToFloat

      public static float halfShortToFloat(short shortBits)

    • halfToShortBits

      public static short halfToShortBits(Half half)
      Returns a representation of the specified floating-point value according to the IEEE 754 floating-point "single format" bit layout.

      Bit 15 (the bit that is selected by the mask 0x8000) represents the sign of the floating-point number. Bits 14-10 (the bits that are selected by the mask 0x7c00) represent the exponent. Bits 9-0 (the bits that are selected by the mask 0x03ff) represent the significand (sometimes called the mantissa) of the floating-point number.

      If the argument is positive infinity, the result is 0x7c00.

      If the argument is negative infinity, the result is 0xfc00.

      If the argument is NaN, the result is 0x7e00.

      In all cases, the result is a short that, when given to the shortBitsToHalf(short) method, will produce a floating-point value the same as the argument to halfToShortBits (except all NaN values are collapsed to a single "canonical" NaN value).

      Parameters:
      half - a Half object.
      Returns:
      the bits that represent the floating-point number.

    • floatToShortBitsCollapseNaN

      public static short floatToShortBitsCollapseNaN(float floatRepresentation)
      Returns a representation of the specified floating-point value according to the IEEE 754 floating-point "single format" bit layout.

      Bit 15 (the bit that is selected by the mask 0x8000) represents the sign of the floating-point number. Bits 14-10 (the bits that are selected by the mask 0x7c00) represent the exponent. Bits 9-0 (the bits that are selected by the mask 0x03ff) represent the significand (sometimes called the mantissa) of the floating-point number.

      If the argument is positive infinity, the result is 0x7c00.

      If the argument is negative infinity, the result is 0xfc00.

      If the argument is NaN, the result is 0x7e00.

      In all cases, the result is a short that, when given to the shortBitsToHalf(short) method, will produce a floating-point value the same as the argument to halfToShortBits (except all NaN values are collapsed to a single "canonical" NaN value).

      Parameters:
      floatRepresentation - a float representation as used within a Half object.
      Returns:
      the bits that represent the floating-point number.

    • halfToRawShortBits

      public static short halfToRawShortBits(Half half)
      Returns a representation of the specified floating-point value according to the IEEE 754 floating-point "single format" bit layout, preserving Not-a-Number (NaN) values.

      Bit 15 (the bit that is selected by the mask 0x8000) represents the sign of the floating-point number. Bits 14-10 (the bits that are selected by the mask 0x7c00) represent the exponent. Bits 9-0 (the bits that are selected by the mask 0x03ff) represent the significand (sometimes called the mantissa) of the floating-point number.

      If the argument is positive infinity, the result is 0x7c00.

      If the argument is negative infinity, the result is 0xfc00.

      If the argument is NaN, the result is the integer representing the actual NaN value. Unlike the halfToShortBits method, halfToRawShortBits does not collapse all the bit patterns encoding a NaN to a single "canonical" NaN value.

      In all cases, the result is a short that, when given to the shortBitsToHalf(short) method, will produce a floating-point value the same as the argument to halfToRawShortBits.

      Parameters:
      half - a Half object.
      Returns:
      the bits that represent the half-point number.

    • floatToHalfShortBits

      public static short floatToHalfShortBits(float floatValue)

    • shortValue

      public short shortValue()
      Returns the value of the specified number as a short.
      Overrides:
      shortValue in class Number
      Returns:
      the numeric value represented by this object after conversion to type short.

    • intValue

      public int intValue()
      Specified by:
      intValue in class Number

    • longValue

      public long longValue()
      Specified by:
      longValue in class Number

    • floatValue

      public float floatValue()
      Specified by:
      floatValue in class Number

    • doubleValue

      public double doubleValue()
      Specified by:
      doubleValue in class Number

    • byteValue

      public byte byteValue()
      Returns the value of the specified number as a byte.
      Overrides:
      byteValue in class Number
      Returns:
      the numeric value represented by this object after conversion to type byte.

    • valueOf

      public static Half valueOf(String s) throws NumberFormatException
      Returns a Half object represented by the argument string s.

      If s is null, then a NullPointerException is thrown.

      Leading and trailing whitespace characters in s are ignored. Whitespace is removed as if by the String.trim() method; that is, both ASCII space and control characters are removed. The rest of s should constitute a FloatValue as described by the lexical syntax rules:

      FloatValue:
      Signopt NaN
      Signopt Infinity
      Signopt FloatingPointLiteral
      Signopt HexFloatingPointLiteral
      SignedInteger
      HexFloatingPointLiteral:
      HexSignificand BinaryExponent FloatTypeSuffixopt
      HexSignificand:
      HexNumeral
      HexNumeral .
      0x HexDigitsopt . HexDigits
      0X HexDigitsopt . HexDigits
      BinaryExponent:
      BinaryExponentIndicator SignedInteger
      BinaryExponentIndicator:
      p
      P
      where Sign, FloatingPointLiteral, HexNumeral, HexDigits, SignedInteger and FloatTypeSuffix are as defined in the lexical structure sections of The Java Language Specification, except that underscores are not accepted between digits. If s does not have the form of a FloatValue, then a NumberFormatException is thrown. Otherwise, s is regarded as representing an exact decimal value in the usual "computerized scientific notation" or as an exact hexadecimal value; this exact numerical value is then conceptually converted to an "infinitely precise" binary value that is then rounded to type half by the usual round-to-nearest rule of IEEE 754 floating-point arithmetic, which includes preserving the sign of a zero value. Note that the round-to-nearest rule also implies overflow and underflow behaviour; if the exact value of s is large enough in magnitude (greater than or equal to (MAX_VALUE + HalfMath.ulp(MAX_VALUE)/2), rounding to float will result in an infinity and if the exact value of s is small enough in magnitude (less than or equal to MIN_VALUE/2), rounding to float will result in a zero. Finally, after rounding a Half object is returned.

      To interpret localized string representations of a floating-point value, use subclasses of NumberFormat.

      To avoid calling this method on an invalid string and having a NumberFormatException be thrown, the documentation for Double.valueOf lists a regular expression which can be used to screen the input.

      Parameters:
      s - the string to be parsed.
      Returns:
      a Half object holding the value represented by the String argument.
      Throws:
      NumberFormatException - if the string does not contain a parsable number.

    • valueOf

      public static Half valueOf(double doubleValue)
      Returns a Half instance representing the specified double value.
      Parameters:
      doubleValue - a double value.
      Returns:
      a Half instance representing doubleValue.

    • valueOf

      public static Half valueOf(Double doubleValue)
      Returns a Half instance representing the specified Double value.
      Parameters:
      doubleValue - a double value.
      Returns:
      a Half instance representing doubleValue.

    • valueOf

      public static Half valueOf(float floatValue)
      Returns a Half instance representing the specified float value.
      Parameters:
      floatValue - a float value.
      Returns:
      a Half instance representing floatValue.

    • quantizeFloat

      public static float quantizeFloat(float floatValue)

    • valueOf

      public static Half valueOf(Float floatValue)
      Returns a Half instance representing the specified Float value.
      Parameters:
      floatValue - a float value.
      Returns:
      a Half instance representing floatValue.

    • valueOf

      public static Half valueOf(Half half)
      Returns a new Half instance identical to the specified half.
      Parameters:
      half - a half instance.
      Returns:
      a Half instance representing doubleValue.

    • isNaN

      public static boolean isNaN(Half half)
      Returns true if the specified number is a Not-a-Number (NaN) value, false otherwise.
      Parameters:
      half - the Half to be tested.
      Returns:
      true if the argument is NaN; false otherwise.

    • isNaN

      public boolean isNaN()
      Returns true if this Half value is a Not-a-Number (NaN), false otherwise.
      Returns:
      true if the value represented by this object is NaN; false otherwise.

    • isInfinite

      public static boolean isInfinite(Half half)
      Returns true if the specified Half is infinitely large in magnitude, false otherwise.
      Parameters:
      half - the Half to be tested.
      Returns:
      true if the argument is positive infinity or negative infinity; false otherwise.

    • isInfinite

      public boolean isInfinite()
      Returns true if this Half value is infinitely large in magnitude, false otherwise.
      Returns:
      true if the value represented by this object is positive infinity or negative infinity; false otherwise.

    • isFinite

      public static boolean isFinite(Half half)
      Returns true if the argument is a finite floating-point value; returns false otherwise (for NaN and infinity arguments).
      Parameters:
      half - the Half to be tested
      Returns:
      true if the argument is a finite floating-point value, false otherwise.

    • isFinite

      public boolean isFinite()
      Returns true if the argument is a finite floating-point value; returns false otherwise (for NaN and infinity arguments).
      Returns:
      true if the argument is a finite floating-point value, false otherwise.

    • toString

      public static String toString(Half half)
      Returns a string representation of the half argument. All characters mentioned below are ASCII characters.
      • If the argument is NaN, the result is the string "NaN".
      • Otherwise, the result is a string that represents the sign and magnitude (absolute value) of the argument. If the sign is negative, the first character of the result is '-' ('\u002D'); if the sign is positive, no sign character appears in the result. As for the magnitude m:
        • If m is infinity, it is represented by the characters "Infinity"; thus, positive infinity produces the result "Infinity" and negative infinity produces the result "-Infinity".
        • If m is zero, it is represented by the characters "0.0"; thus, negative zero produces the result "-0.0" and positive zero produces the result "0.0".
        • If m is greater than or equal to 10-3 but less than 107, then it is represented as the integer part of m, in decimal form with no leading zeroes, followed by '.' ('\u002E'), followed by one or more decimal digits representing the fractional part of m.
        • If m is less than 10-3 or greater than or equal to 107, then it is represented in so-called "computerized scientific notation." Let n be the unique integer such that 10n ≤ m < 10n+1; then let a be the mathematically exact quotient of m and 10n so that 1 ≤ a < 10. The magnitude is then represented as the integer part of a, as a single decimal digit, followed by '.' ('\u002E'), followed by decimal digits representing the fractional part of a, followed by the letter 'E' ('\u0045'), followed by a representation of n as a decimal integer, as produced by the method Integer.toString(int).
      Handled as a float and number of significant digits is determined by Float.toString(floatValue) using results of floatValue() call using half instance.

      To create localized string representations of a floating-point value, use subclasses of NumberFormat.

      Parameters:
      half - the Half to be converted.
      Returns:
      a string representation of the argument.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • toHexString

      public static String toHexString(Half half)
      Returns a hexadecimal string representation of the half argument. All characters mentioned below are ASCII characters.
      • If the argument is NaN, the result is the string "NaN".
      • Otherwise, the result is a string that represents the sign and magnitude (absolute value) of the argument. If the sign is negative, the first character of the result is '-' ('\u002D'); if the sign is positive, no sign character appears in the result. As for the magnitude m:
        • If m is infinity, it is represented by the string "Infinity"; thus, positive infinity produces the result "Infinity" and negative infinity produces the result "-Infinity".
        • If m is zero, it is represented by the string "0x0.0p0"; thus, negative zero produces the result "-0x0.0p0" and positive zero produces the result "0x0.0p0".
        • If m is a half with a normalized representation, substrings are used to represent the significand and exponent fields. The significand is represented by the characters "0x1." followed by a lowercase hexadecimal representation of the rest of the significand as a fraction. Trailing zeros in the hexadecimal representation are removed unless all the digits are zero, in which case a single zero is used. Next, the exponent is represented by "p" followed by a decimal string of the unbiased exponent as if produced by a call to Integer.toString on the exponent value.
        • If m is a half with a subnormal representation, the significand is represented by the characters "0x0." followed by a hexadecimal representation of the rest of the significand as a fraction. Trailing zeros in the hexadecimal representation are removed. Next, the exponent is represented by "p-14". Note that there must be at least one nonzero digit in a subnormal significand.
      Examples
      Floating-point Value Hexadecimal String
      1.0 0x1.0p0
      -1.0 -0x1.0p0
      2.0 0x1.0p1
      3.0 0x1.8p1
      0.5 0x1.0p-1
      0.25 0x1.0p-2
      Float.MAX_VALUE 0x1.ffcp15
      Minimum Normal Value 0x1.0p-14
      Maximum Subnormal Value 0x0.ffcp-14
      Float.MIN_VALUE 0x0.004p-14
      Parameters:
      half - the Half to be converted.
      Returns:
      a hex string representation of the argument.

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public static int hashCode(Half half)
      Returns a hash code for a Half; compatible with Half.hashCode().
      Parameters:
      half - the Half to hash
      Returns:
      a hash code value for a Half value.

    • hashCode

      public int hashCode()
      Returns a hash code for this Half object. The result is the short bit representation, exactly as produced by the method halfToShortBits(Half) represented by this Half object.
      Overrides:
      hashCode in class Object
      Returns:
      a hash code value for this object.

    • compare

      public static int compare(Half half1, Half half2)
      Compares the two specified Half objects. The sign of the integer value returned is the same as that of the integer that would be returned by the call: 
       half1.compareTo(half2)
      Parameters:
      half1 - the first Half to compare.
      half2 - the second Half to compare.
      Returns:
      the value 0 if half1 is numerically equal to half2; a value less than 0 if half1 is numerically less than half2; and a value greater than 0 if half1 is numerically greater than half2.

    • compareTo

      public int compareTo(Half anotherHalf)
      Specified by:
      compareTo in interface Comparable<Half>

    • sum

      public static Half sum(Half a, Half b)
      Adds two Half values together as per the + operator.
      Parameters:
      a - the first operand
      b - the second operand
      Returns:
      the sum of a and b
      See Also:

    • max

      public static Half max(Half a, Half b)
      Returns the greater of two Half objects.
      Determined using aFloatValue = a.floatValue() and bFloatValue = b.floatValue() then calling Float.max(aFloatValue, bFloatValue).
      Parameters:
      a - the first operand
      b - the second operand
      Returns:
      the greater of a and b
      See Also:

    • min

      public static Half min(Half a, Half b)
      Returns the smaller of two Half objects.
      Determined using aFloatValue = a.floatValue() and bFloatValue = b.floatValue() then calling Float.min(aFloatValue, bFloatValue).
      Parameters:
      a - the first operand
      b - the second operand
      Returns:
      the smaller of a and b
      See Also: