Class InternalFormat.Spec

  • Enclosing class:
    InternalFormat

    public static class InternalFormat.Spec
    extends java.lang.Object
    Parsed PEP-3101 format specification of a single field, encapsulating the format for use by formatting methods. This class holds the several attributes that might be decoded from a format specifier. Each attribute has a reserved value used to indicate "unspecified". Spec objects may be merged such that one Spec provides values, during the construction of a new Spec, for attributes that are unspecified in a primary source.

    This structure is returned by factory method InternalFormat.fromText(String), and having public final members is freely accessed by formatters such as FloatFormatter, and the __format__ methods of client object types.

    The fields correspond to the elements of a format specification. The grammar of a format specification is:

     [[fill]align][sign][#][0][width][,][.precision][type]
     
    A typical idiom is:
         private static final InternalFormatSpec FLOAT_DEFAULTS = InternalFormatSpec.from(">");
         ...
             InternalFormat.Spec spec = InternalFormat.fromText(specString);
             spec = spec.withDefaults(FLOAT_DEFAULTS);
             ... // Validation of spec.type, and other attributes, for this type.
             FloatFormatter f = new FloatFormatter(spec);
             String result = f.format(value).getResult();
    
     
    • Field Summary

      Fields 
      Modifier and Type Field Description
      char align
      Alignment indicator is one of {'<', '^', '>', '=', or U+FFFF if unspecified.
      boolean alternate
      The alternative format flag '#' was given.
      char fill
      The fill character specified, or U+FFFF if unspecified.
      boolean grouping
      Insert the grouping separator (which in Python always indicates a group-size of 3).
      static char NONE
      Non-character code point used to represent "no value" in char attributes.
      static InternalFormat.Spec NUMERIC
      Defaults applicable to most numeric types.
      int precision
      Precision decoded from the format, or -1 if unspecified.
      char sign
      Sign-handling flag, one of '+', '-', or ' ', or U+FFFF if unspecified.
      static InternalFormat.Spec STRING
      Defaults applicable to string types.
      char type
      Type key from the format, or U+FFFF if unspecified.
      static int UNSPECIFIED
      Negative value used to represent "no value" in int attributes.
      int width
      Width to which to pad the result, or -1 if unspecified.
    • Constructor Summary

      Constructors 
      Constructor Description
      Spec​(char fill, char align, char sign, boolean alternate, int width, boolean grouping, int precision, char type)
      Constructor to set all the fields in the format specifier.
      Spec​(int precision, char type)
      Constructor offering just precision and type.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      char getAlign​(char defaultAlign)
      The alignment from the parsed format specification, or default.
      char getFill​(char defaultFill)
      The alignment from the parsed format specification, or default.
      int getPrecision​(int defaultPrecision)
      The precision from the parsed format specification, or default.
      char getType​(char defaultType)
      The type code from the parsed format specification, or default supplied.
      static boolean specified​(char c)
      Test to see if an attribute has been specified.
      static boolean specified​(int value)
      Test to see if an attribute has been specified.
      java.lang.String toString()
      Return a format specifier (text) equivalent to the value of this Spec.
      InternalFormat.Spec withDefaults​(InternalFormat.Spec other)
      Return a merged Spec object, in which any attribute of this object that is specified (or true), has the same value in the result, and any attribute of this object that is unspecified (or false), has the value that attribute takes in the other object.
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • fill

        public final char fill
        The fill character specified, or U+FFFF if unspecified.
      • align

        public final char align
        Alignment indicator is one of {'<', '^', '>', '=', or U+FFFF if unspecified.
      • sign

        public final char sign
        Sign-handling flag, one of '+', '-', or ' ', or U+FFFF if unspecified.
      • alternate

        public final boolean alternate
        The alternative format flag '#' was given.
      • width

        public final int width
        Width to which to pad the result, or -1 if unspecified.
      • grouping

        public final boolean grouping
        Insert the grouping separator (which in Python always indicates a group-size of 3).
      • precision

        public final int precision
        Precision decoded from the format, or -1 if unspecified.
      • type

        public final char type
        Type key from the format, or U+FFFF if unspecified.
      • NONE

        public static final char NONE
        Non-character code point used to represent "no value" in char attributes.
        See Also:
        Constant Field Values
      • UNSPECIFIED

        public static final int UNSPECIFIED
        Negative value used to represent "no value" in int attributes.
        See Also:
        Constant Field Values
      • NUMERIC

        public static final InternalFormat.Spec NUMERIC
        Defaults applicable to most numeric types. Equivalent to " >"
      • STRING

        public static final InternalFormat.Spec STRING
        Defaults applicable to string types. Equivalent to " <"
    • Constructor Detail

      • Spec

        public Spec​(char fill,
                    char align,
                    char sign,
                    boolean alternate,
                    int width,
                    boolean grouping,
                    int precision,
                    char type)
        Constructor to set all the fields in the format specifier.
         [[fill]align][sign][#][0][width][,][.precision][type]
         
        Parameters:
        fill - fill character (or NONE
        align - alignment indicator, one of {'<', '^', '>', '='
        sign - policy, one of '+', '-', or ' '.
        alternate - true to request alternate formatting mode ('#' flag).
        width - of field after padding or -1 to default
        grouping - true to request comma-separated groups
        precision - (e.g. decimal places) or -1 to default
        type - indicator character
      • Spec

        public Spec​(int precision,
                    char type)
        Constructor offering just precision and type.
         [.precision][type]
         
        Parameters:
        precision - (e.g. decimal places)
        type - indicator character
    • Method Detail

      • specified

        public static final boolean specified​(char c)
        Test to see if an attribute has been specified.
        Parameters:
        c - attribute
        Returns:
        true only if the attribute is not equal to NONE
      • specified

        public static final boolean specified​(int value)
        Test to see if an attribute has been specified.
        Parameters:
        value - of attribute
        Returns:
        true only if the attribute is >=0 (meaning that it has been specified).
      • toString

        public java.lang.String toString()
        Return a format specifier (text) equivalent to the value of this Spec.
        Overrides:
        toString in class java.lang.Object
      • withDefaults

        public InternalFormat.Spec withDefaults​(InternalFormat.Spec other)
        Return a merged Spec object, in which any attribute of this object that is specified (or true), has the same value in the result, and any attribute of this object that is unspecified (or false), has the value that attribute takes in the other object. Thus the second object supplies default values. (These defaults may also be unspecified.) The use of this method is to allow a Spec constructed from text to record exactly, and only, what was in the textual specification, while the __format__ method of a client object supplies its type-specific defaults. Thus "20" means "<20s" to a str, ">20.12" to a float and ">20.12g" to a complex.
        Parameters:
        other - defaults to merge where this object does not specify the attribute.
        Returns:
        a new Spec object.
      • getFill

        public char getFill​(char defaultFill)
        The alignment from the parsed format specification, or default.
      • getAlign

        public char getAlign​(char defaultAlign)
        The alignment from the parsed format specification, or default.
      • getPrecision

        public int getPrecision​(int defaultPrecision)
        The precision from the parsed format specification, or default.
      • getType

        public char getType​(char defaultType)
        The type code from the parsed format specification, or default supplied.