public final class Half extends Number implements Comparable<Half>
The Half
class wraps the bits of an IEEE 754-2008 half-precision
floating point value in an object. An object of type Half
contains
a single field whose type is short
(the bits of the actual floating
point value.)
In addition, this class provides several methods for converting a
Half
to a float
, a float
to a Half
, a
Half
to a String
and a String
to a Half
;
as well as other constants and methods useful when dealing with a
Half
.
It also provides methods for conversions between a short
containing the bit pattern of a half-precision floating point value and the
native float
type.
Modifier and Type | Field and Description |
---|---|
static float |
EPSILON
A constant holding the smallest positive
e for which
half(1.0 + e) != half(1.0) . |
static int |
MAX_EXPONENT
Maximum exponent a finite
half variable may have. |
static float |
MAX_VALUE
A constant holding the largest positive finite value of type
half , (2-2-10)·215. |
static int |
MIN_EXPONENT
Minimum exponent a normalized
half variable may have. |
static float |
MIN_NORMAL
A constant holding the smallest positive normal value of type
half , 2-14. |
static float |
MIN_VALUE
A constant holding the smallest positive nonzero value of type
half , 2-24. |
static Half |
NaN
A constant holding the value of Not-a-Number (NaN) of type
half . |
static short |
NaN_BITS
A constant holding the bit pattern of a
Not-a-Number (NaN) value of type
half . |
static Half |
NEGATIVE_INFINITY
A constant holding the value of the negative infinity
of type
half . |
static short |
NEGATIVE_INFINITY_BITS
A constant holding the bit pattern of the negative infinity
of type
half |
static Half |
POSITIVE_INFINITY
A constant holding the value of the positive infinity
of type
half . |
static short |
POSITIVE_INFINITY_BITS
A constant holding the bit pattern of the positive infinity
of type
half |
static int |
SIZE
The number of bits used to represent a
half value. |
Constructor and Description |
---|
Half(double value)
Constructs a newly allocated
Half object that
represents the argument converted to type half . |
Half(float value)
Constructs a newly allocated
Half object that
represents the argument converted to type half . |
Half(short bits)
Constructs a newly allocated
Half object with the bit pattern
of the argument. |
Half(String s)
Constructs a newly allocated
Half object that
represents the half-precision floating-point value
represented by the string. |
Modifier and Type | Method and Description |
---|---|
byte |
byteValue()
Returns the value of this
Half as a
byte (by casting its float value to a byte ). |
static int |
compare(short bitsH1,
short bitsH2)
Compares the two specified
short bit patterns each representing
a half-precision floating-point value. |
int |
compareTo(Half anotherHalf)
Compares two
Half objects numerically. |
double |
doubleValue()
Returns the exact value of this
Half as a
double (by casting its float value to an double ). |
boolean |
equals(Object obj)
Compares this object against the specified object.
|
static short |
floatToShortBits(float value)
Returns a representation of the specified floating-point value
according to the IEEE 754-2008 "half format" bit layout.
|
float |
floatValue()
Returns the exact value of this
Half as a
double by converting its bit pattern as per the
shortBitsToFloat(short) method. |
short |
halfToRawShortBits()
Returns a representation of the calling object
according to the IEEE 754-2008 floating-point "half format" bit
layout, preserving Not-a-Number (NaN) values.
|
short |
halfToShortBits()
Returns a representation of the calling object
according to the IEEE 754-2008 floating-point "half format" bit
layout.
|
static short |
halfToShortBits(short halfBits)
Returns a representation of the given bit pattern adhering to
the IEEE 754-2008 floating-point "half format" layout.
|
int |
hashCode()
Returns a hash code for this
Half object. |
int |
intValue()
Returns the value of this
Half as an
int (by casting its float value to an int ). |
boolean |
isInfinite()
Returns
true if this Half value is
infinitely large in magnitude, false otherwise. |
static boolean |
isInfinite(short bits)
Returns
true if the specified bit pattern corresponding to a
half-precision floating point number 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(short bits)
Returns
true if the specified bit pattern corresponding to a
half-precision floating point number is a
Not-a-Number (NaN) value, false otherwise. |
long |
longValue()
Returns the value of this
Half as a
long (by casting its float value to a long ). |
static float |
shortBitsToFloat(short bits)
Returns the
float value equivalent to a given half-precision
bit representation. |
short |
shortValue()
Returns the value of this
Half as a
short (by casting its float value to a short ). |
String |
toHexString() |
String |
toString() |
public static final float MIN_NORMAL
half
, 2-14.public static final float MIN_VALUE
half
, 2-24.public static final float MAX_VALUE
half
, (2-2-10)·215.public static final int MIN_EXPONENT
half
variable may have.public static final int MAX_EXPONENT
half
variable may have.public static final float EPSILON
e
for which
half(1.0 + e) != half(1.0)
.public static final short NaN_BITS
half
.public static final Half NaN
half
.public static final short NEGATIVE_INFINITY_BITS
half
public static final Half NEGATIVE_INFINITY
half
.public static final short POSITIVE_INFINITY_BITS
half
public static final Half POSITIVE_INFINITY
half
.public static final int SIZE
half
value.public Half(short bits)
Half
object with the bit pattern
of the argument.bits
- the bit pattern which represents the Half
public Half(float value)
Half
object that
represents the argument converted to type half
.value
- the value to be represented by the Half
.floatToShortBits(float)
public Half(double value)
Half
object that
represents the argument converted to type half
.value
- the value to be represented by the Half
.floatToShortBits(float)
public Half(String s) throws NumberFormatException
Half
object that
represents the half-precision floating-point value
represented by the string. The string is converted to a
float
value as if by the valueOf
method.s
- a string to be converted to a Half
.NumberFormatException
- if the string does not contain a
parsable number.Float.valueOf(java.lang.String)
,
floatToShortBits(float)
public static short floatToShortBits(float value)
Returns a representation of the specified floating-point value according to the IEEE 754-2008 "half 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
represents the
exponent. Bits 9-0 (the bits that are selected by the mask
0x3ff
) 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 an integer that, when given to the
shortBitsToFloat(short)
method, will produce a floating-point
value the same as the argument to floatToShortBits
(except
all NaN values are collapsed to a single "canonical"
NaN value).
value
- a floating-point number.public static float shortBitsToFloat(short bits)
float
value equivalent to a given half-precision
bit representation.
The argument is considered to be a representation of a
floating-point value according to the IEEE 754-2008 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 Float.floatToRawIntBits
method.
In all other cases, let s, e, and m be three values that can be computed from the argument:
Then the floating-point result equals the value of the mathematical expression s·m·2e-25.int s = ((bits >> 15) == 0) ? 1 : -1; int e = ((bits >> 10) & 0x1f); int m = (e == 0) ? (bits & 0x3ff) << 1 : (bits & 0x3ff) | 0x400;
Note that this method may not be able to return a
float
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 shortBitsToFloat
may
not be able to return a float
with a signaling NaN
bit pattern. Consequently, for some short
values,
floatToShortBits(shortBitsToFloat(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.
bits
- a short.float
floating-point value with the equivalent bit
pattern.public static boolean isNaN(short bits)
true
if the specified bit pattern corresponding to a
half-precision floating point number is a
Not-a-Number (NaN) value, false
otherwise.bits
- the bit pattern to be tested.true
if the argument is NaN;
false
otherwise.public static boolean isInfinite(short bits)
true
if the specified bit pattern corresponding to a
half-precision floating point number is infinitely
large in magnitude, false
otherwise.bits
- the bit pattern to be tested.true
if the argument is positive infinity or
negative infinity; false
otherwise.public short halfToRawShortBits()
Returns a representation of the calling object according to the IEEE 754-2008 floating-point "half 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
represents the
exponent. Bits 9-0 (the bits that are selected by the mask
0x3ff
) 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 short 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
shortBitsToFloat(short)
method, will produce a
floating-point value the same as invoking object.
public short halfToShortBits()
Returns a representation of the calling object according to the IEEE 754-2008 floating-point "half 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
represents the
exponent. Bits 9-0 (the bits that are selected by the mask
0x3ff
) 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
shortBitsToFloat(short)
method, will produce a
floating-point value the same as invoking object.
public static short halfToShortBits(short halfBits)
Returns a representation of the given bit pattern adhering to the IEEE 754-2008 floating-point "half format" 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
represents the
exponent. Bits 9-0 (the bits that are selected by the mask
0x3ff
) 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
shortBitsToFloat(short)
method, will produce a
floating-point value the same as invoking object.
halfBits
- the bit pattern of a half
floating-point number.public boolean isNaN()
true
if this Half
value is a
Not-a-Number (NaN), false
otherwise.true
if the value represented by this object is
NaN; false
otherwise.public boolean isInfinite()
true
if this Half
value is
infinitely large in magnitude, false
otherwise.true
if the value represented by this object is
positive infinity or negative infinity;
false
otherwise.public byte byteValue()
Half
as a
byte
(by casting its float
value to a byte
).byteValue
in class Number
float
value represented by this object
converted to type byte
floatValue()
public short shortValue()
Half
as a
short
(by casting its float
value to a short
).shortValue
in class Number
float
value represented by this object
converted to type short
floatValue()
public int intValue()
Half
as an
int
(by casting its float
value to an int
).intValue
in class Number
float
value represented by this object
converted to type int
floatValue()
public long longValue()
Half
as a
long
(by casting its float
value to a long
).longValue
in class Number
float
value represented by this object
converted to type long
floatValue()
public float floatValue()
Half
as a
double
by converting its bit pattern as per the
shortBitsToFloat(short)
method.floatValue
in class Number
float
value represented by this object.shortBitsToFloat(short)
public double doubleValue()
Half
as a
double
(by casting its float
value to an double
).doubleValue
in class Number
float
value represented by this object
converted to type double
floatValue()
public boolean equals(Object obj)
true
if and only if the argument is not
null
and is a Half
object that
represents a half
with the same value as the
half
represented by this object. For this
purpose, two half
values are considered to be the
same if and only if the method halfToShortBits()
returns the identical short
value when applied to each.
Note that in most cases, for two instances of class
Half
, h1
and h2
, the value
of h1.equals(h2)
is true
if and only if
h1.floatValue() == h2.floatValue()
also has the value true
. However, there are two exceptions:
h1
and h2
both represent
Half.NaN
, then the equals
method returns
true
, even though the operator ==
applied to the
numerical values has the value false
.
h1
represents +0.0f
while
h2
represents -0.0f
, or vice
versa, the equal
test has the value
false
, even though 0.0f==-0.0f
has the value true
.
equals
in class Object
obj
- the object to be comparedtrue
if the objects are the same;
false
otherwise.halfToShortBits()
public int hashCode()
Half
object. The
result is the integer bit representation, exactly as produced
by the method halfToRawShortBits()
.public String toHexString()
public int compareTo(Half anotherHalf)
Half
objects numerically. There are
two ways in which comparisons performed by this method differ
from those performed by the Java language numerical comparison
operators (<, <=, ==, >= >
) when
applied to primitive float
values:
Half.NaN
is considered by this method to
be equal to itself and greater than all other
float
values
(including Half.POSITIVE_INFINITY
).
0.0f
is considered by this method to be greater
than -0.0f
.
equals
.compareTo
in interface Comparable<Half>
anotherHalf
- the Half
to be compared.0
if anotherHalf
is
numerically equal to this Half
; a value
less than 0
if this Half
is numerically less than anotherHalf
;
and a value greater than 0
if this
Half
is numerically greater than
anotherHalf
.Comparable.compareTo(Object)
public static int compare(short bitsH1, short bitsH2)
short
bit patterns each representing
a half-precision floating-point value. The sign
of the integer value returned is the same as that of the
integer that would be returned by the call:
<pre>
new Half(bitsH1).compareTo(new Half(bitsH2))
</pre>
bitsH1
- the bit pattern of the first half
to compare.bitsH2
- the bit pattern of the first half
to compare.0
if the half
represented by
bitsH1
is numerically equal to the half
represented by bitsH2
; a value less than 0
if the half
represented by bitsH1
is numerically
less than half
represented by bitsH2
; and a
value greater than 0
if the half
represented by
bitsH1
is numerically greater than the half
represented by bitsH2
.