org.checkerframework.checker.formatter.qual.Format Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of checker Show documentation

The Checker Framework enhances Java's type system to make it more powerful and useful. This lets software developers detect and prevent errors in their Java programs. The Checker Framework includes compiler plug-ins ("checkers") that find bugs or verify their absence. It also permits you to write your own compiler plug-ins.

There is a newer version: 3.43.0

Show newest version

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.
 *
 * The annotation's value represents the valid arguments that may be passed to the format method.
 * For example:
 *
 * 

 *
 *  * {@literal @}Format({GENERAL, INT}) String f = "String '%s' has length %d";
 *
 *  String.format(f, "Example", 7);
 * 
 *
 * 
 *
 * 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();
}