InternalFormat.Spec (Jython API documentation)
Date: 2024-08-18

org.python.core.stringlib

## Class InternalFormat.Spec

- java.lang.Object
- - org.python.core.stringlib.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 and 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 and 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 and 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.

Jython homepage