Package org.checkerframework.checker.index.qual

Annotation Interface SubstringIndexFor

@Documented @Retention(RUNTIME) @Target({TYPE_USE,TYPE_PARAMETER}) @SubtypeOf(SubstringIndexUnknown.class) public @interface SubstringIndexFor
The annotated expression evaluates to either -1 or a non-negative integer less than the lengths of all the given sequences. The annotation @SubstringIndexFor(args) is like @NonNegative @LTLengthOf(args), except that @SubstringIndexFor(args) additionally permits the value -1.

When multiple values or offsets are given, they are considered pairwise. For example, @SubstringIndexFor(value={"a", "b"}, offset={"c", "d"}) is equivalent to writing both @SubstringIndexFor(value="a", offset="c") and @SubstringIndexFor(value="b", offset="d").

The return types of JDK methods String.indexOf and String.lastIndexOf are annotated @SubstringIndexFor(value="this",offset="#1.length()-1"). This means that the returned value is either -1 or it is less than or equal to the length of the receiver sequence minus the length of the sequence passed as the first argument.

The name of this annotation, "substring index for", is intended to mean that the annotated expression is a index of a substring (returned by indexOf or similar methods) for the specified sequence.

See the Checker Framework Manual:
Index Checker

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String[]
    offset
    This expression plus the annotated expression is less than the length of the corresponding sequence in the value array.
    String[]
    value
    Sequences, each of which is longer than the annotated expression plus the corresponding offset.

  • Element Details

    • value

      @JavaExpression String[] value
      Sequences, each of which is longer than the annotated expression plus the corresponding offset. (Exception: the annotated expression is also allowed to have the value -1.)

    • offset

      @JavaExpression String[] offset
      This expression plus the annotated expression is less than the length of the corresponding sequence in the value array. (Exception: the annotated expression is also allowed to have the value -1.)

      The offset array must either be empty or the same length as value.

      The expressions in offset may be addition/subtraction of any number of Java expressions. For example, @SubstringIndexFor(value = "a", offset = "b.length() - 1").