org.checkerframework.checker.index.qual

Annotation Type SubstringIndexFor

@SubtypeOf(value=SubstringIndexUnknown.class)
 @Retention(value=RUNTIME)
 @Target(value={TYPE_USE,TYPE_PARAMETER})
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 and 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 Detail

value

public abstract 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

public abstract 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").