Class Floats
- java.lang.Object
-
- com.google.common.primitives.Floats
-
@GwtCompatible(emulated=true) public final class Floats extends java.lang.Object
Static utility methods pertaining tofloat
primitives, that are not already found in eitherFloat
orArrays
.See the Guava User Guide article on primitive utilities.
- Since:
- 1.0
- Author:
- Kevin Bourrillion
-
-
Field Summary
Fields Modifier and Type Field Description static int
BYTES
The number of bytes required to represent a primitivefloat
value.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static java.util.List<java.lang.Float>
asList(float... backingArray)
Returns a fixed-size list backed by the specified array, similar toArrays.asList(Object[])
.static int
compare(float a, float b)
Compares the two specifiedfloat
values usingFloat.compare(float, float)
.static float[]
concat(float[]... arrays)
Returns the values from each provided array combined into a single array.static float
constrainToRange(float value, float min, float max)
Returns the value nearest tovalue
which is within the closed range[min..max]
.static boolean
contains(float[] array, float target)
Returnstrue
iftarget
is present as an element anywhere inarray
.static float[]
ensureCapacity(float[] array, int minLength, int padding)
Returns an array containing the same values asarray
, but guaranteed to be of a specified minimum length.static int
hashCode(float value)
Returns a hash code forvalue
; equal to the result of invoking((Float) value).hashCode()
.static int
indexOf(float[] array, float target)
Returns the index of the first appearance of the valuetarget
inarray
.static int
indexOf(float[] array, float[] target)
Returns the start position of the first occurrence of the specifiedtarget
withinarray
, or-1
if there is no such occurrence.static boolean
isFinite(float value)
Returnstrue
ifvalue
represents a real number.static java.lang.String
join(java.lang.String separator, float... array)
Returns a string containing the suppliedfloat
values, converted to strings as specified byFloat.toString(float)
, and separated byseparator
.static int
lastIndexOf(float[] array, float target)
Returns the index of the last appearance of the valuetarget
inarray
.static java.util.Comparator<float[]>
lexicographicalComparator()
Returns a comparator that compares twofloat
arrays lexicographically.static float
max(float... array)
Returns the greatest value present inarray
, using the same rules of comparison asMath.max(float, float)
.static float
min(float... array)
Returns the least value present inarray
, using the same rules of comparison asMath.min(float, float)
.static void
reverse(float[] array)
Reverses the elements ofarray
.static void
reverse(float[] array, int fromIndex, int toIndex)
Reverses the elements ofarray
betweenfromIndex
inclusive andtoIndex
exclusive.static void
rotate(float[] array, int distance)
Performs a right rotation ofarray
of "distance" places, so that the first element is moved to index "distance", and the element at indexi
ends up at index(distance + i) mod array.length
.static void
rotate(float[] array, int distance, int fromIndex, int toIndex)
Performs a right rotation ofarray
betweenfromIndex
inclusive andtoIndex
exclusive.static void
sortDescending(float[] array)
Sorts the elements ofarray
in descending order.static void
sortDescending(float[] array, int fromIndex, int toIndex)
Sorts the elements ofarray
betweenfromIndex
inclusive andtoIndex
exclusive in descending order.static Converter<java.lang.String,java.lang.Float>
stringConverter()
Returns a serializable converter object that converts between strings and floats usingFloat.valueOf(java.lang.String)
andFloat.toString()
.static float[]
toArray(java.util.Collection<? extends java.lang.Number> collection)
Returns an array containing each value ofcollection
, converted to afloat
value in the manner ofNumber.floatValue()
.static java.lang.Float
tryParse(java.lang.String string)
Parses the specified string as a single-precision floating point value.
-
-
-
Field Detail
-
BYTES
public static final int BYTES
The number of bytes required to represent a primitivefloat
value.Java 8+ users: use
Float.BYTES
instead.- Since:
- 10.0
- See Also:
- Constant Field Values
-
-
Method Detail
-
hashCode
public static int hashCode(float value)
Returns a hash code forvalue
; equal to the result of invoking((Float) value).hashCode()
.Java 8+ users: use
Float.hashCode(float)
instead.- Parameters:
value
- a primitivefloat
value- Returns:
- a hash code for the value
-
compare
public static int compare(float a, float b)
Compares the two specifiedfloat
values usingFloat.compare(float, float)
. You may prefer to invoke that method directly; this method exists only for consistency with the other utilities in this package.Note: this method simply delegates to the JDK method
Float.compare(float, float)
. It is provided for consistency with the other primitive types, whose compare methods were not added to the JDK until JDK 7.- Parameters:
a
- the firstfloat
to compareb
- the secondfloat
to compare- Returns:
- the result of invoking
Float.compare(float, float)
-
isFinite
public static boolean isFinite(float value)
Returnstrue
ifvalue
represents a real number. This is equivalent to, but not necessarily implemented as,!(Float.isInfinite(value) || Float.isNaN(value))
.Java 8+ users: use
Float.isFinite(float)
instead.- Since:
- 10.0
-
contains
public static boolean contains(float[] array, float target)
Returnstrue
iftarget
is present as an element anywhere inarray
. Note that this always returnsfalse
whentarget
isNaN
.- Parameters:
array
- an array offloat
values, possibly emptytarget
- a primitivefloat
value- Returns:
true
ifarray[i] == target
for some value ofi
-
indexOf
public static int indexOf(float[] array, float target)
Returns the index of the first appearance of the valuetarget
inarray
. Note that this always returns-1
whentarget
isNaN
.- Parameters:
array
- an array offloat
values, possibly emptytarget
- a primitivefloat
value- Returns:
- the least index
i
for whicharray[i] == target
, or-1
if no such index exists.
-
indexOf
public static int indexOf(float[] array, float[] target)
Returns the start position of the first occurrence of the specifiedtarget
withinarray
, or-1
if there is no such occurrence.More formally, returns the lowest index
i
such thatArrays.copyOfRange(array, i, i + target.length)
contains exactly the same elements astarget
.Note that this always returns
-1
whentarget
containsNaN
.- Parameters:
array
- the array to search for the sequencetarget
target
- the array to search for as a sub-sequence ofarray
-
lastIndexOf
public static int lastIndexOf(float[] array, float target)
Returns the index of the last appearance of the valuetarget
inarray
. Note that this always returns-1
whentarget
isNaN
.- Parameters:
array
- an array offloat
values, possibly emptytarget
- a primitivefloat
value- Returns:
- the greatest index
i
for whicharray[i] == target
, or-1
if no such index exists.
-
min
@GwtIncompatible("Available in GWT! Annotation is to avoid conflict with GWT specialization of base class.") public static float min(float... array)
Returns the least value present inarray
, using the same rules of comparison asMath.min(float, float)
.- Parameters:
array
- a nonempty array offloat
values- Returns:
- the value present in
array
that is less than or equal to every other value in the array - Throws:
java.lang.IllegalArgumentException
- ifarray
is empty
-
max
@GwtIncompatible("Available in GWT! Annotation is to avoid conflict with GWT specialization of base class.") public static float max(float... array)
Returns the greatest value present inarray
, using the same rules of comparison asMath.max(float, float)
.- Parameters:
array
- a nonempty array offloat
values- Returns:
- the value present in
array
that is greater than or equal to every other value in the array - Throws:
java.lang.IllegalArgumentException
- ifarray
is empty
-
constrainToRange
public static float constrainToRange(float value, float min, float max)
Returns the value nearest tovalue
which is within the closed range[min..max]
.If
value
is within the range[min..max]
,value
is returned unchanged. Ifvalue
is less thanmin
,min
is returned, and ifvalue
is greater thanmax
,max
is returned.- Parameters:
value
- thefloat
value to constrainmin
- the lower bound (inclusive) of the range to constrainvalue
tomax
- the upper bound (inclusive) of the range to constrainvalue
to- Throws:
java.lang.IllegalArgumentException
- ifmin > max
- Since:
- 21.0
-
concat
public static float[] concat(float[]... arrays)
Returns the values from each provided array combined into a single array. For example,concat(new float[] {a, b}, new float[] {}, new float[] {c}
returns the array{a, b, c}
.- Parameters:
arrays
- zero or morefloat
arrays- Returns:
- a single array containing all the values from the source arrays, in order
-
stringConverter
public static Converter<java.lang.String,java.lang.Float> stringConverter()
Returns a serializable converter object that converts between strings and floats usingFloat.valueOf(java.lang.String)
andFloat.toString()
.- Since:
- 16.0
-
ensureCapacity
public static float[] ensureCapacity(float[] array, int minLength, int padding)
Returns an array containing the same values asarray
, but guaranteed to be of a specified minimum length. Ifarray
already has a length of at leastminLength
, it is returned directly. Otherwise, a new array of sizeminLength + padding
is returned, containing the values ofarray
, and zeroes in the remaining places.- Parameters:
array
- the source arrayminLength
- the minimum length the returned array must guaranteepadding
- an extra amount to "grow" the array by if growth is necessary- Returns:
- an array containing the values of
array
, with guaranteed minimum lengthminLength
- Throws:
java.lang.IllegalArgumentException
- ifminLength
orpadding
is negative
-
join
public static java.lang.String join(java.lang.String separator, float... array)
Returns a string containing the suppliedfloat
values, converted to strings as specified byFloat.toString(float)
, and separated byseparator
. For example,join("-", 1.0f, 2.0f, 3.0f)
returns the string"1.0-2.0-3.0"
.Note that
Float.toString(float)
formatsfloat
differently in GWT. In the previous example, it returns the string"1-2-3"
.- Parameters:
separator
- the text that should appear between consecutive values in the resulting string (but not at the start or end)array
- an array offloat
values, possibly empty
-
lexicographicalComparator
public static java.util.Comparator<float[]> lexicographicalComparator()
Returns a comparator that compares twofloat
arrays lexicographically. That is, it compares, usingcompare(float, float)
), the first pair of values that follow any common prefix, or when one array is a prefix of the other, treats the shorter array as the lesser. For example,[] < [1.0f] < [1.0f, 2.0f] < [2.0f]
.The returned comparator is inconsistent with
Object.equals(Object)
(since arrays support only identity equality), but it is consistent withArrays.equals(float[], float[])
.- Since:
- 2.0
-
sortDescending
public static void sortDescending(float[] array)
Sorts the elements ofarray
in descending order.Note that this method uses the total order imposed by
Float.compare(float, float)
, which treats all NaN values as equal and 0.0 as greater than -0.0.- Since:
- 23.1
-
sortDescending
public static void sortDescending(float[] array, int fromIndex, int toIndex)
Sorts the elements ofarray
betweenfromIndex
inclusive andtoIndex
exclusive in descending order.Note that this method uses the total order imposed by
Float.compare(float, float)
, which treats all NaN values as equal and 0.0 as greater than -0.0.- Since:
- 23.1
-
reverse
public static void reverse(float[] array)
Reverses the elements ofarray
. This is equivalent toCollections.reverse(Floats.asList(array))
, but is likely to be more efficient.- Since:
- 23.1
-
reverse
public static void reverse(float[] array, int fromIndex, int toIndex)
Reverses the elements ofarray
betweenfromIndex
inclusive andtoIndex
exclusive. This is equivalent toCollections.reverse(Floats.asList(array).subList(fromIndex, toIndex))
, but is likely to be more efficient.- Throws:
java.lang.IndexOutOfBoundsException
- iffromIndex < 0
,toIndex > array.length
, ortoIndex > fromIndex
- Since:
- 23.1
-
rotate
public static void rotate(float[] array, int distance)
Performs a right rotation ofarray
of "distance" places, so that the first element is moved to index "distance", and the element at indexi
ends up at index(distance + i) mod array.length
. This is equivalent toCollections.rotate(Floats.asList(array), distance)
, but is considerably faster and avoids allocation and garbage collection.The provided "distance" may be negative, which will rotate left.
- Since:
- 32.0.0
-
rotate
public static void rotate(float[] array, int distance, int fromIndex, int toIndex)
Performs a right rotation ofarray
betweenfromIndex
inclusive andtoIndex
exclusive. This is equivalent toCollections.rotate(Floats.asList(array).subList(fromIndex, toIndex), distance)
, but is considerably faster and avoids allocations and garbage collection.The provided "distance" may be negative, which will rotate left.
- Throws:
java.lang.IndexOutOfBoundsException
- iffromIndex < 0
,toIndex > array.length
, ortoIndex > fromIndex
- Since:
- 32.0.0
-
toArray
public static float[] toArray(java.util.Collection<? extends java.lang.Number> collection)
Returns an array containing each value ofcollection
, converted to afloat
value in the manner ofNumber.floatValue()
.Elements are copied from the argument collection as if by
collection.toArray()
. Calling this method is as thread-safe as calling that method.- Parameters:
collection
- a collection ofNumber
instances- Returns:
- an array containing the same values as
collection
, in the same order, converted to primitives - Throws:
java.lang.NullPointerException
- ifcollection
or any of its elements is null- Since:
- 1.0 (parameter was
Collection<Float>
before 12.0)
-
asList
public static java.util.List<java.lang.Float> asList(float... backingArray)
Returns a fixed-size list backed by the specified array, similar toArrays.asList(Object[])
. The list supportsList.set(int, Object)
, but any attempt to set a value tonull
will result in aNullPointerException
.The returned list maintains the values, but not the identities, of
Float
objects written to or read from it. For example, whetherlist.get(0) == list.get(0)
is true for the returned list is unspecified.The returned list may have unexpected behavior if it contains
NaN
, or ifNaN
is used as a parameter to any of its methods.The returned list is serializable.
- Parameters:
backingArray
- the array to back the list- Returns:
- a list view of the array
-
tryParse
@GwtIncompatible @CheckForNull public static java.lang.Float tryParse(java.lang.String string)
Parses the specified string as a single-precision floating point value. The ASCII character'-'
('\u002D'
) is recognized as the minus sign.Unlike
Float.parseFloat(String)
, this method returnsnull
instead of throwing an exception if parsing fails. Valid inputs are exactly those accepted byFloat.valueOf(String)
, except that leading and trailing whitespace is not permitted.This implementation is likely to be faster than
Float.parseFloat
if many failures are expected.- Parameters:
string
- the string representation of afloat
value- Returns:
- the floating point value represented by
string
, ornull
ifstring
has a length of zero or cannot be parsed as afloat
value - Throws:
java.lang.NullPointerException
- ifstring
isnull
- Since:
- 14.0
-
-