| package org.checkerframework.checker.formatter.qual; |
| |
| import java.lang.annotation.Documented; |
| import java.lang.annotation.ElementType; |
| import java.lang.annotation.Retention; |
| import java.lang.annotation.RetentionPolicy; |
| import java.lang.annotation.Target; |
| import org.checkerframework.framework.qual.SubtypeOf; |
| |
| /** |
| * This annotation, attached to a String type, indicates that the String may be passed to {@link |
| * java.util.Formatter#format(String, Object...) Formatter.format} and similar methods. |
| * |
| * <p>The annotation's value represents the valid arguments that may be passed to the format method. |
| * For example: |
| * |
| * <blockquote> |
| * |
| * <pre> |
| * {@literal @}Format({GENERAL, INT}) String f = "String '%s' has length %d"; |
| * |
| * String.format(f, "Example", 7); |
| * </pre> |
| * |
| * </blockquote> |
| * |
| * The annotation indicates that the format string requires any Object as the first parameter |
| * ({@link ConversionCategory#GENERAL}) and an integer as the second parameter ({@link |
| * ConversionCategory#INT}). The format string accepts any values as additional parameters (because |
| * it ignores them). |
| * |
| * @see ConversionCategory |
| * @checker_framework.manual #formatter-checker Format String Checker |
| */ |
| @Documented |
| @Retention(RetentionPolicy.RUNTIME) |
| @Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER}) |
| @SubtypeOf(UnknownFormat.class) |
| public @interface Format { |
| /** |
| * An array of {@link ConversionCategory}, indicating the types of legal remaining arguments when |
| * a value of the annotated type is used as the first argument to {@link |
| * java.util.Formatter#format(String, Object...) Formatter.format} and similar methods. |
| * |
| * @return types that can be used as values when a value of this type is the format string |
| */ |
| ConversionCategory[] value(); |
| } |