Package org.checkerframework.checker.formatter.qual

Enum Class ConversionCategory

java.lang.Object
java.lang.Enum<ConversionCategory>
org.checkerframework.checker.formatter.qual.ConversionCategory
All Implemented Interfaces:
Serializable, Comparable<ConversionCategory>, Constable
@AnnotatedFor("nullness") public enum ConversionCategory extends Enum<ConversionCategory>
Elements of this enumeration are used in a Format annotation to indicate the valid types that may be passed as a format parameter. For example: 
@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 (GENERAL) and an integer as the second parameter (INT).
See Also:
See the Checker Framework Manual:
Format String Checker

  • Enum Constant Details

    • GENERAL

      public static final ConversionCategory GENERAL
      Use if the parameter can be of any type. Applicable for conversions b, B, h, H, s, S.

    • CHAR

      public static final ConversionCategory CHAR
      Use if the parameter is of a basic types which represent Unicode characters: char, Character, byte, Byte, short, and Short. This conversion may also be applied to the types int and Integer when Character.isValidCodePoint(int) returns true. Applicable for conversions c, C.

    • INT

      public static final ConversionCategory INT
      Use if the parameter is an integral type: byte, Byte, short, Short, int and Integer, long, Long, and BigInteger. Applicable for conversions d, o, x, X.

    • FLOAT

      public static final ConversionCategory FLOAT
      Use if the parameter is a floating-point type: float, Float, double, Double, and BigDecimal. Applicable for conversions e, E, f, g, G, a, A.

    • TIME

      public static final ConversionCategory TIME
      Use if the parameter is a type which is capable of encoding a date or time: long, Long, Calendar, and Date. Applicable for conversions t, T.

    • CHAR_AND_INT

      public static final ConversionCategory CHAR_AND_INT
      Use if the parameter is both a char and an int.

      In a format string, multiple conversions may be applied to the same parameter. This is seldom needed, but the following is an example of such use: 

         format("Test %1$c %1$d", (int)42);
      In this example, the first parameter is interpreted as both a character and an int, therefore the parameter must be compatible with both conversion, and can therefore neither be char nor long. This intersection of conversions is called CHAR_AND_INT.

      One other conversion intersection is interesting, namely the intersection of INT and TIME, resulting in INT_AND_TIME.

      All other intersection either lead to an already existing type, or NULL, in which case it is illegal to pass object's of any type as parameter.

    • INT_AND_TIME

      public static final ConversionCategory INT_AND_TIME
      Use if the parameter is both an int and a time.
      See Also:

    • NULL

      public static final ConversionCategory NULL
      Use if no object of any type can be passed as parameter. In this case, the only legal value is null. This is seldomly needed, and indicates an error in most cases. For example: 
         format("Test %1$f %1$d", null);
      Only null can be legally passed, passing a value such as 4 or 4.2 would lead to an exception.

    • UNUSED

      public static final ConversionCategory UNUSED
      Use if a parameter is not used by the formatter. This is seldomly needed, and indicates an error in most cases. For example: 
         format("Test %1$s %3$s", "a","unused","b");
      Only the first "a" and third "b" parameters are used, the second "unused" parameter is ignored.

  • Field Details

    • types

      public final Class<?> @Nullable [] types
      The argument types. Null means every type.

    • chars

      public final @Nullable String chars
      The format specifier characters. Null means users cannot specify it directly.

  • Method Details

    • values

      public static ConversionCategory[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static ConversionCategory valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null

    • fromConversionChar

      public static ConversionCategory fromConversionChar(char c)
      Converts a conversion character to a category. For example: 
      
 ConversionCategory.fromConversionChar('d') == ConversionCategory.INT
      Parameters:
      c - a conversion character
      Returns:
      the category for the given conversion character

    • isSubsetOf

      public static boolean isSubsetOf(ConversionCategory a, ConversionCategory b)

    • intersect

      public static ConversionCategory intersect(ConversionCategory a, ConversionCategory b)
      Returns the intersection of two categories. This is seldomly needed. 
       ConversionCategory.intersect(INT, TIME) == INT_AND_TIME;
      Parameters:
      a - a category
      b - a category
      Returns:
      the intersection of the two categories (their greatest lower bound)

    • union

      public static ConversionCategory union(ConversionCategory a, ConversionCategory b)
      Returns the union of two categories. This is seldomly needed. 
       ConversionCategory.union(INT, TIME) == GENERAL;
      Parameters:
      a - a category
      b - a category
      Returns:
      the union of the two categories (their least upper bound)

    • isAssignableFrom

      public boolean isAssignableFrom(Class<?> argType)
      Returns true if argType can be an argument used by this format specifier.
      Parameters:
      argType - an argument type
      Returns:
      true if argType can be an argument used by this format specifier

    • toString

      @Pure public String toString()
      Returns a pretty printed ConversionCategory.
      Overrides:
      toString in class Enum<ConversionCategory>