Enum ConversionCategory

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<ConversionCategory>

    @AnnotatedFor("nullness")
    public enum ConversionCategory
    extends java.lang.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:
    Format
    • Enum Constant Summary

      Enum Constants 
      Enum Constant Description
      CHAR
      Use if the parameter is of a basic types which represent Unicode characters: char, Character, byte, Byte, short, and Short.
      CHAR_AND_INT
      Use if the parameter is both a char and an int.
      FLOAT
      Use if the parameter is a floating-point type: float, Float, double, Double, and BigDecimal.
      GENERAL
      Use if the parameter can be of any type.
      INT
      Use if the parameter is an integral type: byte, Byte, short, Short, int and Integer, long, Long, and BigInteger.
      INT_AND_TIME
      Use if the parameter is both an int and a time.
      NULL
      Use if no object of any type can be passed as parameter.
      TIME
      Use if the parameter is a type which is capable of encoding a date or time: long, Long, Calendar, and Date.
      UNUSED
      Use if a parameter is not used by the formatter.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      @Nullable java.lang.String chars
      The format specifier characters.
      java.lang.Class<?> @Nullable [] types
      The argument types.
    • Enum Constant Detail

      • 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.

      • 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 Detail

      • types

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

        public final @Nullable java.lang.String chars
        The format specifier characters. Null means users cannot specify it directly.
    • Method Detail

      • values

        public static ConversionCategory[] values()
        Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
        for (ConversionCategory c : ConversionCategory.values())
            System.out.println(c);
        
        Returns:
        an array containing the constants of this enum type, in the order they are declared
      • valueOf

        public static ConversionCategory valueOf​(java.lang.String name)
        Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (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:
        java.lang.IllegalArgumentException - if this enum type has no constant with the specified name
        java.lang.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
      • 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​(java.lang.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