Class NullnessUtil
To avoid the need to write the NullnessUtil class name, do:
import static org.checkerframework.checker.nullness.util.NullnessUtil.castNonNull;or
import static org.checkerframework.checker.nullness.util.NullnessUtil.*;
Runtime Dependency: If you use this class, you must distribute (or link to)
checker-qual.jar
, along with your binaries. Or, you can copy this class into your own project.
-
Method Summary
Modifier and TypeMethodDescriptioncastNonNull
(@Nullable T ref) A method that suppresses warnings from the Nullness Checker.castNonNull
(@Nullable T ref, String message) Suppress warnings from the Nullness Checker, with a custom error message.castNonNullDeep
(T @Nullable [] arr) Like castNonNull, but whereas that method only checks and casts the reference itself, this traverses all levels of the argument array.castNonNullDeep
(T @Nullable [] @Nullable [] arr) Like castNonNull, but whereas that method only checks and casts the reference itself, this traverses all levels of the argument array.castNonNullDeep
(T @Nullable [] @Nullable [] @Nullable [] arr) Like castNonNull, but whereas that method only checks and casts the reference itself, this traverses all levels of the argument array.castNonNullDeep
(T @Nullable [] @Nullable [] @Nullable [] @Nullable [] arr) Like castNonNull, but whereas that method only checks and casts the reference itself, this traverses all levels of the argument array.Like castNonNull, but whereas that method only checks and casts the reference itself, this traverses all levels of the argument array.castNonNullDeep
(T @Nullable [] @Nullable [] @Nullable [] @Nullable [] @Nullable [] arr, String message) Like castNonNull, but whereas that method only checks and casts the reference itself, this traverses all levels of the argument array.Like castNonNull, but whereas that method only checks and casts the reference itself, this traverses all levels of the argument array.castNonNullDeep
(T @Nullable [] @Nullable [] @Nullable [] arr, String message) Like castNonNull, but whereas that method only checks and casts the reference itself, this traverses all levels of the argument array.castNonNullDeep
(T @Nullable [] @Nullable [] arr, String message) Like castNonNull, but whereas that method only checks and casts the reference itself, this traverses all levels of the argument array.castNonNullDeep
(T @Nullable [] arr, String message) Like castNonNull, but whereas that method only checks and casts the reference itself, this traverses all levels of the argument array.
-
Method Details
-
castNonNull
@EnsuresNonNull("#1") public static <T extends @Nullable Object> @NonNull T castNonNull(@Nullable T ref) A method that suppresses warnings from the Nullness Checker.The method takes a possibly-null reference, unsafely casts it to have the @NonNull type qualifier, and returns it. The Nullness Checker considers both the return value, and also the argument, to be non-null after the method call. Therefore, the
castNonNull
method can be used either as a cast expression or as a statement. The Nullness Checker issues no warnings in any of the following code:
The// one way to use as a cast: @NonNull String s = castNonNull(possiblyNull1); // another way to use as a cast: castNonNull(possiblyNull2).toString(); // one way to use as a statement: castNonNull(possiblyNull3); possiblyNull3.toString();`
castNonNull
method is intended to be used in situations where the programmer definitively knows that a given reference is not null, but the type system is unable to make this deduction. It is not intended for defensive programming, in which a programmer cannot prove that the value is not null but wishes to have an earlier indication if it is. See the Checker Framework Manual for further discussion.The method throws
AssertionError
if Java assertions are enabled and the argument isnull
. If the exception is ever thrown, then that indicates that the programmer misused the method by using it in a circumstance where its argument can be null.- Type Parameters:
T
- the type of the reference- Parameters:
ref
- a reference of @Nullable type, that is non-null at run time- Returns:
- the argument, casted to have the type qualifier @NonNull
-
castNonNull
@EnsuresNonNull("#1") public static <T extends @Nullable Object> @NonNull T castNonNull(@Nullable T ref, String message) Suppress warnings from the Nullness Checker, with a custom error message. SeecastNonNull(Object)
for documentation.- Type Parameters:
T
- the type of the reference- Parameters:
ref
- a reference of @Nullable type, that is non-null at run timemessage
- text to include if this method is misused- Returns:
- the argument, casted to have the type qualifier @NonNull
- See Also:
-
castNonNullDeep
@EnsuresNonNull("#1") public static <T extends @Nullable Object> @NonNull T @NonNull [] castNonNullDeep(T @Nullable [] arr) Like castNonNull, but whereas that method only checks and casts the reference itself, this traverses all levels of the argument array. The array is recursively checked to ensure that all elements at every array level are non-null.- Type Parameters:
T
- the component type of the array- Parameters:
arr
- an array all of whose elements, and their elements recursively, are non-null at run time- Returns:
- the argument, casted to have the type qualifier @NonNull at all levels
- See Also:
-
castNonNullDeep
@EnsuresNonNull("#1") public static <T extends @Nullable Object> @NonNull T @NonNull [] castNonNullDeep(T @Nullable [] arr, String message) Like castNonNull, but whereas that method only checks and casts the reference itself, this traverses all levels of the argument array. The array is recursively checked to ensure that all elements at every array level are non-null.- Type Parameters:
T
- the component type of the array- Parameters:
arr
- an array all of whose elements, and their elements recursively, are non-null at run timemessage
- text to include if this method is misused- Returns:
- the argument, casted to have the type qualifier @NonNull at all levels
- See Also:
-
castNonNullDeep
@EnsuresNonNull("#1") public static <T extends @Nullable Object> @NonNull T[] @NonNull [] castNonNullDeep(T @Nullable [] @Nullable [] arr) Like castNonNull, but whereas that method only checks and casts the reference itself, this traverses all levels of the argument array. The array is recursively checked to ensure that all elements at every array level are non-null.- Type Parameters:
T
- the component type of the component type of the array- Parameters:
arr
- an array all of whose elements, and their elements recursively, are non-null at run time- Returns:
- the argument, casted to have the type qualifier @NonNull at all levels
- See Also:
-
castNonNullDeep
@EnsuresNonNull("#1") public static <T extends @Nullable Object> @NonNull T[] @NonNull [] castNonNullDeep(T @Nullable [] @Nullable [] arr, String message) Like castNonNull, but whereas that method only checks and casts the reference itself, this traverses all levels of the argument array. The array is recursively checked to ensure that all elements at every array level are non-null.- Type Parameters:
T
- the component type of the component type of the array- Parameters:
arr
- an array all of whose elements, and their elements recursively, are non-null at run timemessage
- text to include if this method is misused- Returns:
- the argument, casted to have the type qualifier @NonNull at all levels
- See Also:
-
castNonNullDeep
@EnsuresNonNull("#1") public static <T extends @Nullable Object> @NonNull T[][] @NonNull [] castNonNullDeep(T @Nullable [] @Nullable [] @Nullable [] arr) Like castNonNull, but whereas that method only checks and casts the reference itself, this traverses all levels of the argument array. The array is recursively checked to ensure that all elements at every array level are non-null.- Type Parameters:
T
- the component type (three levels in) of the array- Parameters:
arr
- an array all of whose elements, and their elements recursively, are non-null at run time- Returns:
- the argument, casted to have the type qualifier @NonNull at all levels
- See Also:
-
castNonNullDeep
@EnsuresNonNull("#1") public static <T extends @Nullable Object> @NonNull T[][] @NonNull [] castNonNullDeep(T @Nullable [] @Nullable [] @Nullable [] arr, String message) Like castNonNull, but whereas that method only checks and casts the reference itself, this traverses all levels of the argument array. The array is recursively checked to ensure that all elements at every array level are non-null.- Type Parameters:
T
- the component type (three levels in) of the array- Parameters:
arr
- an array all of whose elements, and their elements recursively, are non-null at run timemessage
- text to include if this method is misused- Returns:
- the argument, casted to have the type qualifier @NonNull at all levels
- See Also:
-
castNonNullDeep
@EnsuresNonNull("#1") public static <T extends @Nullable Object> @NonNull T[][][] @NonNull [] castNonNullDeep(T @Nullable [] @Nullable [] @Nullable [] @Nullable [] arr) Like castNonNull, but whereas that method only checks and casts the reference itself, this traverses all levels of the argument array. The array is recursively checked to ensure that all elements at every array level are non-null.- Type Parameters:
T
- the component type of the array- Parameters:
arr
- an array all of whose elements, and their elements recursively, are non-null at run time- Returns:
- the argument, casted to have the type qualifier @NonNull at all levels
- See Also:
-
castNonNullDeep
@EnsuresNonNull("#1") public static <T extends @Nullable Object> @NonNull T[][][] @NonNull [] castNonNullDeep(T @Nullable [] @Nullable [] @Nullable [] @Nullable [] arr, String message) Like castNonNull, but whereas that method only checks and casts the reference itself, this traverses all levels of the argument array. The array is recursively checked to ensure that all elements at every array level are non-null.- Type Parameters:
T
- the component type (four levels in) of the array- Parameters:
arr
- an array all of whose elements, and their elements recursively, are non-null at run timemessage
- text to include if this method is misused- Returns:
- the argument, casted to have the type qualifier @NonNull at all levels
- See Also:
-
castNonNullDeep
@EnsuresNonNull("#1") public static <T extends @Nullable Object> @NonNull T[][][][] @NonNull [] castNonNullDeep(T @Nullable [] @Nullable [] @Nullable [] @Nullable [] @Nullable [] arr) Like castNonNull, but whereas that method only checks and casts the reference itself, this traverses all levels of the argument array. The array is recursively checked to ensure that all elements at every array level are non-null.- Type Parameters:
T
- the component type (four levels in) of the array- Parameters:
arr
- an array all of whose elements, and their elements recursively, are non-null at run time- Returns:
- the argument, casted to have the type qualifier @NonNull at all levels
- See Also:
-
castNonNullDeep
@EnsuresNonNull("#1") public static <T extends @Nullable Object> @NonNull T[][][][] @NonNull [] castNonNullDeep(T @Nullable [] @Nullable [] @Nullable [] @Nullable [] @Nullable [] arr, String message) Like castNonNull, but whereas that method only checks and casts the reference itself, this traverses all levels of the argument array. The array is recursively checked to ensure that all elements at every array level are non-null.- Type Parameters:
T
- the component type (five levels in) of the array- Parameters:
arr
- an array all of whose elements, and their elements recursively, are non-null at run timemessage
- text to include if this method is misused- Returns:
- the argument, casted to have the type qualifier @NonNull at all levels
- See Also:
-