OpenJDK 27 · jdk.internal.util.Preconditions · APIdia, the JavaDoc alternative

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

Access	Constructor and Description
public	Preconditions()

Method Summary

Modifier and Type	Method and Description
public static < the type of runtime exception to throw if the arguments are out of bounds X extends RuntimeException> int	Returns: `fromIndex` if the sub-range within bounds of the range checkFromIndexSize(int the lower-bound (inclusive) of the sub-interval fromIndex, int the size of the sub-range size, int the upper-bound (exclusive) of the range length, BiFunction<String, List<Number>, X> 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. 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).
public static < the type of runtime exception to throw if the arguments are out of bounds X extends RuntimeException> long	Returns: `fromIndex` if the sub-range within bounds of the range checkFromIndexSize(long the lower-bound (inclusive) of the sub-interval fromIndex, long the size of the sub-range size, long the upper-bound (exclusive) of the range length, BiFunction<String, List<Number>, X> 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. 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).
public static < the type of runtime exception to throw if the arguments are out of bounds X extends RuntimeException> int	Returns: `fromIndex` if the sub-range within bounds of the range checkFromToIndex(int the lower-bound (inclusive) of the sub-range fromIndex, int the upper-bound (exclusive) of the sub-range toIndex, int the upper-bound (exclusive) the range length, BiFunction<String, List<Number>, X> 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. oobef) Checks if the sub-range from `fromIndex` (inclusive) to `toIndex` (exclusive) is within the bounds of range from `0` (inclusive) to `length` (exclusive).
public static < the type of runtime exception to throw if the arguments are out of bounds X extends RuntimeException> long	Returns: `fromIndex` if the sub-range within bounds of the range checkFromToIndex(long the lower-bound (inclusive) of the sub-range fromIndex, long the upper-bound (exclusive) of the sub-range toIndex, long the upper-bound (exclusive) the range length, BiFunction<String, List<Number>, X> 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. oobef) Checks if the sub-range from `fromIndex` (inclusive) to `toIndex` (exclusive) is within the bounds of range from `0` (inclusive) to `length` (exclusive).
public static < the type of runtime exception to throw if the arguments are out of bounds X extends RuntimeException> int	Returns: `index` if it is within bounds of the range checkIndex(int the index index, int the upper-bound (exclusive) of the range length, BiFunction<String, List<Number>, X> 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. oobef) Checks if the `index` is within the bounds of the range from `0` (inclusive) to `length` (exclusive).
public static < the type of runtime exception to throw if the arguments are out of bounds X extends RuntimeException> long	Returns: `index` if it is within bounds of the range checkIndex(long the index index, long the upper-bound (exclusive) of the range length, BiFunction<String, List<Number>, X> 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. oobef) Checks if the `index` is within the bounds of the range from `0` (inclusive) to `length` (exclusive).
private static RuntimeException	Returns: the runtime exception outOfBounds(BiFunction<String, List<Number>, ? extends RuntimeException> the exception formatter that when applied with a checkKind and a list out-of-bounds arguments returns a runtime exception. If `null` then, it is as if an exception formatter was supplied that returns `IndexOutOfBoundsException` for any given arguments. oobef, String the kind of bounds check, whose name may correspond to the name of one of the range check methods, checkIndex, checkFromToIndex, checkFromIndexSize checkKind, Number... the out-of-bounds arguments that failed the range check. If the checkKind corresponds to the name of a range check method then the bounds arguments are those that can be passed in order to the method. args) Maps out-of-bounds values to a runtime exception.
private static RuntimeException	outOfBoundsCheckFromIndexSize(BiFunction<String, List<Number>, ? extends RuntimeException> oobe, int fromIndex, int size, int length)
private static RuntimeException	outOfBoundsCheckFromIndexSize(BiFunction<String, List<Number>, ? extends RuntimeException> oobe, long fromIndex, long size, long length)
private static RuntimeException	outOfBoundsCheckFromToIndex(BiFunction<String, List<Number>, ? extends RuntimeException> oobe, int fromIndex, int toIndex, int length)
private static RuntimeException	outOfBoundsCheckFromToIndex(BiFunction<String, List<Number>, ? extends RuntimeException> oobe, long fromIndex, long toIndex, long length)
private static RuntimeException	outOfBoundsCheckIndex(BiFunction<String, List<Number>, ? extends RuntimeException> oobe, int index, int length)
private static RuntimeException	outOfBoundsCheckIndex(BiFunction<String, List<Number>, ? extends RuntimeException> oobe, long index, long length)
public static < the type of runtime exception to be returned by the given exception factory and relayed by the exception formatter X extends RuntimeException> BiFunction<String, List<Number>, X>	Returns: the out-of-bounds exception formatter outOfBoundsExceptionFormatter(Function<String, X> 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. f) Returns an out-of-bounds exception formatter from an given exception factory.
private static String	outOfBoundsMessage(String checkKind, List<? extends Number> args)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

AIOOBE_FORMATTER	back to summary
public static final BiFunction<String, List<Number>, ArrayIndexOutOfBoundsException> AIOOBE_FORMATTER

IOOBE_FORMATTER	back to summary
public static final BiFunction<String, List<Number>, IndexOutOfBoundsException> IOOBE_FORMATTER

SIOOBE_FORMATTER	back to summary
public static final BiFunction<String, List<Number>, 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.

Preconditions	back to summary
public Preconditions()

Method Detail

checkFromIndexSize back to summary

checkFromIndexSize	back to summary
public static <X extends RuntimeException> int checkFromIndexSize(int fromIndex, int size, int length, BiFunction<String, List<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`. Parameters <X> the type of runtime exception to throw if the arguments are out of bounds fromIndex:int the lower-bound (inclusive) of the sub-interval size:int the size of the sub-range length:int the upper-bound (exclusive) of the range oobef:BiFunction<String, List<Number>, X> 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:int `fromIndex` if the sub-range within bounds of the range Exceptions BiFunction-: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

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

Parameters

<X>: the type of runtime exception to throw if the arguments are out of bounds
fromIndex:int: the lower-bound (inclusive) of the sub-interval
size:int: the size of the sub-range
length:int: the upper-bound (exclusive) of the range
oobef:BiFunction<String, List<Number>, X>: 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:int

fromIndex if the sub-range within bounds of the range

Exceptions

BiFunction-: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

checkFromIndexSize back to summary

checkFromIndexSize	back to summary
public static <X extends RuntimeException> long checkFromIndexSize(long fromIndex, long size, long length, BiFunction<String, List<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`. Parameters <X> the type of runtime exception to throw if the arguments are out of bounds fromIndex:long the lower-bound (inclusive) of the sub-interval size:long the size of the sub-range length:long the upper-bound (exclusive) of the range oobef:BiFunction<String, List<Number>, X> 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:long `fromIndex` if the sub-range within bounds of the range Exceptions BiFunction-: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 16

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

Parameters

<X>: the type of runtime exception to throw if the arguments are out of bounds
fromIndex:long: the lower-bound (inclusive) of the sub-interval
size:long: the size of the sub-range
length:long: the upper-bound (exclusive) of the range
oobef:BiFunction<String, List<Number>, X>: 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:long

fromIndex if the sub-range within bounds of the range

Exceptions

BiFunction-: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

checkFromToIndex back to summary

checkFromToIndex	back to summary
public static <X extends RuntimeException> int checkFromToIndex(int fromIndex, int toIndex, int length, BiFunction<String, List<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`. Parameters <X> the type of runtime exception to throw if the arguments are out of bounds fromIndex:int the lower-bound (inclusive) of the sub-range toIndex:int the upper-bound (exclusive) of the sub-range length:int the upper-bound (exclusive) the range oobef:BiFunction<String, List<Number>, X> 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:int `fromIndex` if the sub-range within bounds of the range Exceptions BiFunction-: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

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

Parameters

<X>: the type of runtime exception to throw if the arguments are out of bounds
fromIndex:int: the lower-bound (inclusive) of the sub-range
toIndex:int: the upper-bound (exclusive) of the sub-range
length:int: the upper-bound (exclusive) the range
oobef:BiFunction<String, List<Number>, X>: 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:int

fromIndex if the sub-range within bounds of the range

Exceptions

BiFunction-: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

checkFromToIndex back to summary

checkFromToIndex	back to summary
public static <X extends RuntimeException> long checkFromToIndex(long fromIndex, long toIndex, long length, BiFunction<String, List<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`. Parameters <X> the type of runtime exception to throw if the arguments are out of bounds fromIndex:long the lower-bound (inclusive) of the sub-range toIndex:long the upper-bound (exclusive) of the sub-range length:long the upper-bound (exclusive) the range oobef:BiFunction<String, List<Number>, X> 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:long `fromIndex` if the sub-range within bounds of the range Exceptions BiFunction-: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 16

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

Parameters

<X>: the type of runtime exception to throw if the arguments are out of bounds
fromIndex:long: the lower-bound (inclusive) of the sub-range
toIndex:long: the upper-bound (exclusive) of the sub-range
length:long: the upper-bound (exclusive) the range
oobef:BiFunction<String, List<Number>, X>: 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:long

fromIndex if the sub-range within bounds of the range

Exceptions

BiFunction-: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

checkIndex back to summary

checkIndex	back to summary
public static <X extends RuntimeException> int checkIndex(int index, int length, BiFunction<String, List<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`. Implementation Note This method is made intrinsic in optimizing compilers to guide them to perform unsigned comparisons of the index and length when it is known the length is a non-negative value (such as that of an array length or from the upper bound of a loop) Parameters <X> the type of runtime exception to throw if the arguments are out of bounds index:int the index length:int the upper-bound (exclusive) of the range oobef:BiFunction<String, List<Number>, X> 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:int `index` if it is within bounds of the range Annotations @IntrinsicCandidate Exceptions BiFunction-: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

public static <X extends RuntimeException> int checkIndex(int index, int length, BiFunction<String, List<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.

Implementation Note

This method is made intrinsic in optimizing compilers to guide them to perform unsigned comparisons of the index and length when it is known the length is a non-negative value (such as that of an array length or from the upper bound of a loop)

Parameters

<X>: the type of runtime exception to throw if the arguments are out of bounds
index:int: the index
length:int: the upper-bound (exclusive) of the range
oobef:BiFunction<String, List<Number>, X>: 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:int

index if it is within bounds of the range

Annotations

@IntrinsicCandidate

Exceptions

BiFunction-: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

checkIndex back to summary

checkIndex	back to summary
public static <X extends RuntimeException> long checkIndex(long index, long length, BiFunction<String, List<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`. Implementation Note This method is made intrinsic in optimizing compilers to guide them to perform unsigned comparisons of the index and length when it is known the length is a non-negative value (such as that of an array length or from the upper bound of a loop) Parameters <X> the type of runtime exception to throw if the arguments are out of bounds index:long the index length:long the upper-bound (exclusive) of the range oobef:BiFunction<String, List<Number>, X> 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:long `index` if it is within bounds of the range Annotations @IntrinsicCandidate Exceptions BiFunction-: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 16

public static <X extends RuntimeException> long checkIndex(long index, long length, BiFunction<String, List<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.

Implementation Note

Parameters

<X>: the type of runtime exception to throw if the arguments are out of bounds
index:long: the index
length:long: the upper-bound (exclusive) of the range
oobef:BiFunction<String, List<Number>, X>: 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:long

index if it is within bounds of the range

Annotations

@IntrinsicCandidate

Exceptions

BiFunction-: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

outOfBounds back to summary

outOfBounds	back to summary
private static RuntimeException outOfBounds(BiFunction<String, List<Number>, ? extends RuntimeException> oobef, String checkKind, Number... args) Maps out-of-bounds values to a runtime exception. Parameters oobef:BiFunction<String, List<Number>, ? extends RuntimeException> the exception formatter that when applied with a checkKind and a list out-of-bounds arguments returns a runtime exception. If `null` then, it is as if an exception formatter was supplied that returns `IndexOutOfBoundsException` for any given arguments. checkKind:String the kind of bounds check, whose name may correspond to the name of one of the range check methods, checkIndex, checkFromToIndex, checkFromIndexSize args:Number[] the out-of-bounds arguments that failed the range check. If the checkKind corresponds to the name of a range check method then the bounds arguments are those that can be passed in order to the method. Returns:RuntimeException the runtime exception

private static RuntimeException outOfBounds(BiFunction<String, List<Number>, ? extends RuntimeException> oobef, String checkKind, Number... args)

Maps out-of-bounds values to a runtime exception.

Parameters

oobef:BiFunction<String, List<Number>, ? extends RuntimeException>: the exception formatter that when applied with a checkKind and a list out-of-bounds arguments returns a runtime exception. If null then, it is as if an exception formatter was supplied that returns IndexOutOfBoundsException for any given arguments.
checkKind:String: the kind of bounds check, whose name may correspond to the name of one of the range check methods, checkIndex, checkFromToIndex, checkFromIndexSize
args:Number[]: the out-of-bounds arguments that failed the range check. If the checkKind corresponds to the name of a range check method then the bounds arguments are those that can be passed in order to the method.

Returns:RuntimeException

the runtime exception

outOfBoundsCheckFromIndexSize	back to summary
private static RuntimeException outOfBoundsCheckFromIndexSize(BiFunction<String, List<Number>, ? extends RuntimeException> oobe, int fromIndex, int size, int length)

outOfBoundsCheckFromIndexSize	back to summary
private static RuntimeException outOfBoundsCheckFromIndexSize(BiFunction<String, List<Number>, ? extends RuntimeException> oobe, long fromIndex, long size, long length)

outOfBoundsCheckFromToIndex	back to summary
private static RuntimeException outOfBoundsCheckFromToIndex(BiFunction<String, List<Number>, ? extends RuntimeException> oobe, int fromIndex, int toIndex, int length)

outOfBoundsCheckFromToIndex	back to summary
private static RuntimeException outOfBoundsCheckFromToIndex(BiFunction<String, List<Number>, ? extends RuntimeException> oobe, long fromIndex, long toIndex, long length)

outOfBoundsCheckIndex	back to summary
private static RuntimeException outOfBoundsCheckIndex(BiFunction<String, List<Number>, ? extends RuntimeException> oobe, int index, int length)

outOfBoundsCheckIndex	back to summary
private static RuntimeException outOfBoundsCheckIndex(BiFunction<String, List<Number>, ? extends RuntimeException> oobe, long index, long length)

outOfBoundsExceptionFormatter back to summary

outOfBoundsExceptionFormatter	back to summary
public static <X extends RuntimeException> BiFunction<String, List<Number>, 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<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`. API Note This method produces an out-of-bounds exception formatter that can be passed as an argument to any of the supported out-of-bounds range check methods declared by `Objects`. For example, a formatter producing an `ArrayIndexOutOfBoundsException` may be produced and stored on a `static final` field as follows: `static final BiFunction<String, List<Number>, ArrayIndexOutOfBoundsException> AIOOBEF = outOfBoundsExceptionFormatter(ArrayIndexOutOfBoundsException::new);` The formatter instance `AIOOBEF` may be passed as an argument to an out-of-bounds range check method, such as checking if an `index` is within the bounds of a `limit`: `checkIndex(index, limit, AIOOBEF);` If the bounds check fails then the range check method will throw an `ArrayIndexOutOfBoundsException` with an appropriate exception message that is a produced from `AIOOBEF` as follows: `AIOOBEF.apply("checkIndex", List.of(index, limit));` Parameters <X> the type of runtime exception to be returned by the given exception factory and relayed by the exception formatter f:Function<String, X> 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:BiFunction<String, List<Number>, X> the out-of-bounds exception formatter

public static <X extends RuntimeException> BiFunction<String, List<Number>, 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<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.

API Note

This method produces an out-of-bounds exception formatter that can be passed as an argument to any of the supported out-of-bounds range check methods declared by Objects. For example, a formatter producing an ArrayIndexOutOfBoundsException may be produced and stored on a static final field as follows:

static final
BiFunction<String, List<Number>, ArrayIndexOutOfBoundsException> AIOOBEF =
    outOfBoundsExceptionFormatter(ArrayIndexOutOfBoundsException::new);

The formatter instance AIOOBEF may be passed as an argument to an out-of-bounds range check method, such as checking if an index is within the bounds of a limit:

checkIndex(index, limit, AIOOBEF);

If the bounds check fails then the range check method will throw an ArrayIndexOutOfBoundsException with an appropriate exception message that is a produced from AIOOBEF as follows:

AIOOBEF.apply("checkIndex", List.of(index, limit));

Parameters

<X>: the type of runtime exception to be returned by the given exception factory and relayed by the exception formatter
f:Function<String, X>: 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:BiFunction<String, List<Number>, X>

the out-of-bounds exception formatter

outOfBoundsMessage	back to summary
private static String outOfBoundsMessage(String checkKind, List<? extends Number> args)

public Class Preconditions

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail