jdk.internal.util

Class Preconditions

java.lang.Object

jdk.internal.util.Preconditions

public class Preconditions
extends Object

Utility methods to check if state or arguments are correct.

Constructor Summary

Constructors

Constructor and Description
Preconditions()

Method Summary

Modifier and Type	Method and Description
static <X extends RuntimeException> int	checkFromIndexSize(int fromIndex, int size, int length, BiFunction<String,List<Integer>,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 RuntimeException> int	checkFromToIndex(int fromIndex, int toIndex, int length, BiFunction<String,List<Integer>,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 RuntimeException> int	checkIndex(int index, int length, BiFunction<String,List<Integer>,X> oobef) Checks if the index is within the bounds of the range from 0 (inclusive) to length (exclusive).
static <X extends RuntimeException> BiFunction<String,List<Integer>,X>	outOfBoundsExceptionFormatter(Function<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

Constructor Detail

Preconditions

public Preconditions()

Method Detail

outOfBoundsExceptionFormatter

public static <X extends RuntimeException> BiFunction<String,List<Integer>,X> outOfBoundsExceptionFormatter(Function<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<Integer> containing the out-of-bound integer 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 integer 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 RuntimeException> int checkIndex(int index,
                                                          int length,
                                                          BiFunction<String,List<Integer>,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 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

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

Since:

9

checkFromToIndex

public static <X extends RuntimeException> int checkFromToIndex(int fromIndex,
                                                                int toIndex,
                                                                int length,
                                                                BiFunction<String,List<Integer>,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 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

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

Since:

9

checkFromIndexSize

public static <X extends RuntimeException> int checkFromIndexSize(int fromIndex,
                                                                  int size,
                                                                  int length,
                                                                  BiFunction<String,List<Integer>,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 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

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

Since:

9