com.tencent.kona.jdk.internal.util

Class Preconditions

java.lang.Object

com.tencent.kona.jdk.internal.util.Preconditions

public class Preconditions
extends java.lang.Object

Utility methods to check if state or arguments are correct.

Field Summary

Fields

Modifier and Type	Field and Description
static java.util.function.BiFunction<java.lang.String,java.util.List<java.lang.Number>,java.lang.ArrayIndexOutOfBoundsException>	AIOOBE_FORMATTER
static java.util.function.BiFunction<java.lang.String,java.util.List<java.lang.Number>,java.lang.IndexOutOfBoundsException>	IOOBE_FORMATTER
static java.util.function.BiFunction<java.lang.String,java.util.List<java.lang.Number>,java.lang.StringIndexOutOfBoundsException>	SIOOBE_FORMATTER Utility exception formatters which can be used in Preconditions check functions below.

Constructor Summary

Constructors

Constructor and Description
Preconditions()

Method Summary

Modifier and Type	Method and Description
static <X extends java.lang.RuntimeException> int	checkFromIndexSize(int fromIndex, int size, int length, java.util.function.BiFunction<java.lang.String,java.util.List<java.lang.Number>,X> oobef) Checks if the sub-range from fromIndex (inclusive) to fromIndex + size (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).
static <X extends java.lang.RuntimeException> long	checkFromIndexSize(long fromIndex, long size, long length, java.util.function.BiFunction<java.lang.String,java.util.List<java.lang.Number>,X> oobef) Checks if the sub-range from fromIndex (inclusive) to fromIndex + size (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).
static <X extends java.lang.RuntimeException> int	checkFromToIndex(int fromIndex, int toIndex, int length, java.util.function.BiFunction<java.lang.String,java.util.List<java.lang.Number>,X> oobef) Checks if the sub-range from fromIndex (inclusive) to toIndex (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).
static <X extends java.lang.RuntimeException> long	checkFromToIndex(long fromIndex, long toIndex, long length, java.util.function.BiFunction<java.lang.String,java.util.List<java.lang.Number>,X> oobef) Checks if the sub-range from fromIndex (inclusive) to toIndex (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).
static <X extends java.lang.RuntimeException> int	checkIndex(int index, int length, java.util.function.BiFunction<java.lang.String,java.util.List<java.lang.Number>,X> oobef) Checks if the index is within the bounds of the range from 0 (inclusive) to length (exclusive).
static <X extends java.lang.RuntimeException> long	checkIndex(long index, long length, java.util.function.BiFunction<java.lang.String,java.util.List<java.lang.Number>,X> oobef) Checks if the index is within the bounds of the range from 0 (inclusive) to length (exclusive).
static <X extends java.lang.RuntimeException> java.util.function.BiFunction<java.lang.String,java.util.List<java.lang.Number>,X>	outOfBoundsExceptionFormatter(java.util.function.Function<java.lang.String,X> f) Returns an out-of-bounds exception formatter from an given exception factory.

Methods inherited from class java.lang.Object

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

Field Detail

SIOOBE_FORMATTER

public static final java.util.function.BiFunction<java.lang.String,java.util.List<java.lang.Number>,java.lang.StringIndexOutOfBoundsException> SIOOBE_FORMATTER

Utility exception formatters which can be used in Preconditions check functions below. These anonymous inner classes can be syntactically replaced by lambda expression or method reference, but it's not feasible in practices, because Preconditions is used in many fundamental classes such as java.lang.String, lambda expressions or method references exercise many other code at VM startup, this could lead a recursive calls when fundamental classes is used in lambda expressions or method references.

AIOOBE_FORMATTER

public static final java.util.function.BiFunction<java.lang.String,java.util.List<java.lang.Number>,java.lang.ArrayIndexOutOfBoundsException> AIOOBE_FORMATTER

IOOBE_FORMATTER

public static final java.util.function.BiFunction<java.lang.String,java.util.List<java.lang.Number>,java.lang.IndexOutOfBoundsException> IOOBE_FORMATTER

Constructor Detail

Preconditions

public Preconditions()

Method Detail

outOfBoundsExceptionFormatter

public static <X extends java.lang.RuntimeException> java.util.function.BiFunction<java.lang.String,java.util.List<java.lang.Number>,X> outOfBoundsExceptionFormatter(java.util.function.Function<java.lang.String,X> f)

Returns an out-of-bounds exception formatter from an given exception factory. The exception formatter is a function that formats an out-of-bounds message from its arguments and applies that message to the given exception factory to produce and relay an exception.

The exception formatter accepts two arguments: a String describing the out-of-bounds range check that failed, referred to as the check kind; and a List<Number> containing the out-of-bound integral values that failed the check. The list of out-of-bound values is not modified.

Three check kinds are supported checkIndex, checkFromToIndex and checkFromIndexSize corresponding respectively to the specified application of an exception formatter as an argument to the out-of-bounds range check methods checkIndex, checkFromToIndex, and checkFromIndexSize. Thus a supported check kind corresponds to a method name and the out-of-bound integral values correspond to method argument values, in order, preceding the exception formatter argument (similar in many respects to the form of arguments required for a reflective invocation of such a range check method).

Formatter arguments conforming to such supported check kinds will produce specific exception messages describing failed out-of-bounds checks. Otherwise, more generic exception messages will be produced in any of the following cases: the check kind is supported but fewer or more out-of-bounds values are supplied, the check kind is not supported, the check kind is null, or the list of out-of-bound values is null.

Type Parameters:

X - the type of runtime exception to be returned by the given exception factory and relayed by the exception formatter

Parameters:

f - the exception factory, that produces an exception from a message where the message is produced and formatted by the returned exception formatter. If this factory is stateless and side-effect free then so is the returned formatter. Exceptions thrown by the factory are relayed to the caller of the returned formatter.

Returns:

the out-of-bounds exception formatter

checkIndex

public static <X extends java.lang.RuntimeException> int checkIndex(int index,
                                                                    int length,
                                                                    java.util.function.BiFunction<java.lang.String,java.util.List<java.lang.Number>,X> oobef)

Checks if the index is within the bounds of the range from 0 (inclusive) to length (exclusive).

The index is defined to be out of bounds if any of the following inequalities is true:

• index < 0
• index >= length
• length < 0, which is implied from the former inequalities

If the index is out of bounds, then a runtime exception is thrown that is the result of applying the following arguments to the exception formatter: the name of this method, checkIndex; and an unmodifiable list of integers whose values are, in order, the out-of-bounds arguments index and length.

Type Parameters:

X - the type of runtime exception to throw if the arguments are out of bounds

Parameters:

index - the index

length - the upper-bound (exclusive) of the range

oobef - the exception formatter that when applied with this method name and out-of-bounds arguments returns a runtime exception. If null or returns null then, it is as if an exception formatter produced from an invocation of outOfBoundsExceptionFormatter(IndexOutOfBounds::new) is used instead (though it may be more efficient). Exceptions thrown by the formatter are relayed to the caller.

Returns:

index if it is within bounds of the range

Throws:

X - if the index is out of bounds and the exception formatter is non-null

java.lang.IndexOutOfBoundsException - if the index is out of bounds and the exception formatter is null

Since:

9

checkFromToIndex

public static <X extends java.lang.RuntimeException> int checkFromToIndex(int fromIndex,
                                                                          int toIndex,
                                                                          int length,
                                                                          java.util.function.BiFunction<java.lang.String,java.util.List<java.lang.Number>,X> oobef)

Checks if the sub-range from fromIndex (inclusive) to toIndex (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).

The sub-range is defined to be out of bounds if any of the following inequalities is true:

• fromIndex < 0
• fromIndex > toIndex
• toIndex > length
• length < 0, which is implied from the former inequalities

If the sub-range is out of bounds, then a runtime exception is thrown that is the result of applying the following arguments to the exception formatter: the name of this method, checkFromToIndex; and an unmodifiable list of integers whose values are, in order, the out-of-bounds arguments fromIndex, toIndex, and length.

Type Parameters:

X - the type of runtime exception to throw if the arguments are out of bounds

Parameters:

fromIndex - the lower-bound (inclusive) of the sub-range

toIndex - the upper-bound (exclusive) of the sub-range

length - the upper-bound (exclusive) the range

oobef - the exception formatter that when applied with this method name and out-of-bounds arguments returns a runtime exception. If null or returns null then, it is as if an exception formatter produced from an invocation of outOfBoundsExceptionFormatter(IndexOutOfBounds::new) is used instead (though it may be more efficient). Exceptions thrown by the formatter are relayed to the caller.

Returns:

fromIndex if the sub-range within bounds of the range

Throws:

X - if the sub-range is out of bounds and the exception factory function is non-null

java.lang.IndexOutOfBoundsException - if the sub-range is out of bounds and the exception factory function is null

Since:

9

checkFromIndexSize

public static <X extends java.lang.RuntimeException> int checkFromIndexSize(int fromIndex,
                                                                            int size,
                                                                            int length,
                                                                            java.util.function.BiFunction<java.lang.String,java.util.List<java.lang.Number>,X> oobef)

Checks if the sub-range from fromIndex (inclusive) to fromIndex + size (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).

The sub-range is defined to be out of bounds if any of the following inequalities is true:

• fromIndex < 0
• size < 0
• fromIndex + size > length, taking into account integer overflow
• length < 0, which is implied from the former inequalities

If the sub-range is out of bounds, then a runtime exception is thrown that is the result of applying the following arguments to the exception formatter: the name of this method, checkFromIndexSize; and an unmodifiable list of integers whose values are, in order, the out-of-bounds arguments fromIndex, size, and length.

Type Parameters:

X - the type of runtime exception to throw if the arguments are out of bounds

Parameters:

fromIndex - the lower-bound (inclusive) of the sub-interval

size - the size of the sub-range

length - the upper-bound (exclusive) of the range

oobef - the exception formatter that when applied with this method name and out-of-bounds arguments returns a runtime exception. If null or returns null then, it is as if an exception formatter produced from an invocation of outOfBoundsExceptionFormatter(IndexOutOfBounds::new) is used instead (though it may be more efficient). Exceptions thrown by the formatter are relayed to the caller.

Returns:

fromIndex if the sub-range within bounds of the range

Throws:

X - if the sub-range is out of bounds and the exception factory function is non-null

java.lang.IndexOutOfBoundsException - if the sub-range is out of bounds and the exception factory function is null

Since:

9

checkIndex

public static <X extends java.lang.RuntimeException> long checkIndex(long index,
                                                                     long length,
                                                                     java.util.function.BiFunction<java.lang.String,java.util.List<java.lang.Number>,X> oobef)

Checks if the index is within the bounds of the range from 0 (inclusive) to length (exclusive).

The index is defined to be out of bounds if any of the following inequalities is true:

• index < 0
• index >= length
• length < 0, which is implied from the former inequalities

If the index is out of bounds, then a runtime exception is thrown that is the result of applying the following arguments to the exception formatter: the name of this method, checkIndex; and an unmodifiable list of longs whose values are, in order, the out-of-bounds arguments index and length.

Type Parameters:

X - the type of runtime exception to throw if the arguments are out of bounds

Parameters:

index - the index

length - the upper-bound (exclusive) of the range

oobef - the exception formatter that when applied with this method name and out-of-bounds arguments returns a runtime exception. If null or returns null then, it is as if an exception formatter produced from an invocation of outOfBoundsExceptionFormatter(IndexOutOfBounds::new) is used instead (though it may be more efficient). Exceptions thrown by the formatter are relayed to the caller.

Returns:

index if it is within bounds of the range

Throws:

X - if the index is out of bounds and the exception formatter is non-null

java.lang.IndexOutOfBoundsException - if the index is out of bounds and the exception formatter is null

Since:

16

checkFromToIndex

public static <X extends java.lang.RuntimeException> long checkFromToIndex(long fromIndex,
                                                                           long toIndex,
                                                                           long length,
                                                                           java.util.function.BiFunction<java.lang.String,java.util.List<java.lang.Number>,X> oobef)

Checks if the sub-range from fromIndex (inclusive) to toIndex (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).

The sub-range is defined to be out of bounds if any of the following inequalities is true:

• fromIndex < 0
• fromIndex > toIndex
• toIndex > length
• length < 0, which is implied from the former inequalities

If the sub-range is out of bounds, then a runtime exception is thrown that is the result of applying the following arguments to the exception formatter: the name of this method, checkFromToIndex; and an unmodifiable list of longs whose values are, in order, the out-of-bounds arguments fromIndex, toIndex, and length.

Type Parameters:

X - the type of runtime exception to throw if the arguments are out of bounds

Parameters:

fromIndex - the lower-bound (inclusive) of the sub-range

toIndex - the upper-bound (exclusive) of the sub-range

length - the upper-bound (exclusive) the range

oobef - the exception formatter that when applied with this method name and out-of-bounds arguments returns a runtime exception. If null or returns null then, it is as if an exception formatter produced from an invocation of outOfBoundsExceptionFormatter(IndexOutOfBounds::new) is used instead (though it may be more efficient). Exceptions thrown by the formatter are relayed to the caller.

Returns:

fromIndex if the sub-range within bounds of the range

Throws:

X - if the sub-range is out of bounds and the exception factory function is non-null

java.lang.IndexOutOfBoundsException - if the sub-range is out of bounds and the exception factory function is null

Since:

16

checkFromIndexSize

public static <X extends java.lang.RuntimeException> long checkFromIndexSize(long fromIndex,
                                                                             long size,
                                                                             long length,
                                                                             java.util.function.BiFunction<java.lang.String,java.util.List<java.lang.Number>,X> oobef)

Checks if the sub-range from fromIndex (inclusive) to fromIndex + size (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).

The sub-range is defined to be out of bounds if any of the following inequalities is true:

• fromIndex < 0
• size < 0
• fromIndex + size > length, taking into account integer overflow
• length < 0, which is implied from the former inequalities

If the sub-range is out of bounds, then a runtime exception is thrown that is the result of applying the following arguments to the exception formatter: the name of this method, checkFromIndexSize; and an unmodifiable list of longs whose values are, in order, the out-of-bounds arguments fromIndex, size, and length.

Type Parameters:

X - the type of runtime exception to throw if the arguments are out of bounds

Parameters:

fromIndex - the lower-bound (inclusive) of the sub-interval

size - the size of the sub-range

length - the upper-bound (exclusive) of the range

oobef - the exception formatter that when applied with this method name and out-of-bounds arguments returns a runtime exception. If null or returns null then, it is as if an exception formatter produced from an invocation of outOfBoundsExceptionFormatter(IndexOutOfBounds::new) is used instead (though it may be more efficient). Exceptions thrown by the formatter are relayed to the caller.

Returns:

fromIndex if the sub-range within bounds of the range

Throws:

X - if the sub-range is out of bounds and the exception factory function is non-null

java.lang.IndexOutOfBoundsException - if the sub-range is out of bounds and the exception factory function is null

Since:

16