Package daikon.tools.nullness

Class NullnessUtil

  • public final class NullnessUtil
extends Object
    Utility class for the Nullness Checker.

    To avoid the need to write the NullnessUtil class name, do: 

    import static daikon.tools.nullness.NullnessUtil.castNonNull;
    or 
    import static daikon.tools.nullness.NullnessUtil.*;

    Run-time Dependency

    Please note that using this class introduces a run-time dependency. This means that you need to distribute (or link to) Daikon, along with your binaries.

    To eliminate this dependency, you can simply copy this class into your own project.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static <T extends @Nullable Object>
      @NonNull T      		 castNonNull​(T ref)
      A method that suppresses warnings from the Nullness Checker.
      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.
      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.
      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.
      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.
      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.

    • Method Detail

      • castNonNull

        @EnsuresNonNull("#1")
public static <T extends @Nullable Object> @NonNull T castNonNull​(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: 

        
   // 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();`
 }
        The 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 is null. 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.

        Parameters:
        ref - a reference of @Nullable type
        Returns:
        the argument, casted to have the type qualifier @NonNull

      • 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 type of array elements
        Parameters:
        arr - an array that contains no null elements at any level
        Returns:
        the argument, with each array level casted to @NonNull
        See Also:
        castNonNull(Object)

      • castNonNullDeep

        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 type of array elements
        Parameters:
        arr - an array that contains no null elements at any level
        Returns:
        the argument, with each array level casted to @NonNull
        See Also:
        castNonNull(Object)

      • castNonNullDeep

        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 type of array elements
        Parameters:
        arr - an array that contains no null elements at any level
        Returns:
        the argument, with each array level casted to @NonNull
        See Also:
        castNonNull(Object)

      • 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 type of array elements
        Parameters:
        arr - an array that contains no null elements at any level
        Returns:
        the argument, with each array level casted to @NonNull
        See Also:
        castNonNull(Object)

      • 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 type of array elements
        Parameters:
        arr - an array that contains no null elements at any level
        Returns:
        the argument, with each array level casted to @NonNull
        See Also:
        castNonNull(Object)