InternalFormat.Formatter (Jython API documentation)
Date: 2022-09-10

org.python.core.stringlib

## Class InternalFormat.Formatter

- java.lang.Object
- - org.python.core.stringlib.InternalFormat.Formatter

- All Implemented Interfaces:
    java.lang.Appendable
  Direct Known Subclasses:
    FloatFormatter, IntegerFormatter, TextFormatter
  Enclosing class:
    InternalFormat

      public static class InternalFormat.Formatter
      extends java.lang.Object
      implements java.lang.Appendable

  A class that provides the base for implementations of type-specific formatting. In a limited way, it acts like a StringBuilder to which text and one or more numbers may be appended, formatted according to the format specifier supplied at construction. These are ephemeral objects that are not, on their own, thread safe.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Formatter(InternalFormat.Spec spec, int width)` Construct the formatter from a specification and initial buffer capacity.
    `Formatter(java.lang.StringBuilder result, InternalFormat.Spec spec)` Construct the formatter from a client-supplied buffer and a specification.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static PyException` | `alignmentNotAllowed(char align, java.lang.String forType)` Convenience method returning a `Py.ValueError` reporting that the given alignment flag is not allowed in a format specifier for the named type.
    `static PyException` | `alternateFormNotAllowed(java.lang.String forType)` Convenience method returning a `Py.ValueError` reporting that alternate form is not allowed in a format specifier for the named type.
    `static PyException` | `alternateFormNotAllowed(java.lang.String forType, char code)` Convenience method returning a `Py.ValueError` reporting that alternate form is not allowed in a format specifier for the named type and specified typoe code.
    `InternalFormat.Formatter` | `append(char c)`
    `InternalFormat.Formatter` | `append(java.lang.CharSequence csq)`
    `InternalFormat.Formatter` | `append(java.lang.CharSequence csq, int start, int end)`
    `PyString` | `getPyResult()` Convenience method to return the current result of the formatting, as a `PyObject`, either `PyString` or `PyUnicode` according to `bytes`.
    `java.lang.String` | `getResult()` Current (possibly final) result of the formatting, as a `String`.
    `boolean` | `isBytes()` Whether initialised for a byte-like interpretation.
    `static PyException` | `notAllowed(java.lang.String outrage, java.lang.String forType)` Convenience method returning a `Py.ValueError` reporting that some format specifier feature is not allowed for the named data type.
    `static PyException` | `notAllowed(java.lang.String outrage, java.lang.String forType, char code)` Convenience method returning a `Py.ValueError` reporting that some format specifier feature is not allowed for the named format code and data type.
    `InternalFormat.Formatter` | `pad()` Pad the result so far (defined as the contents of `result` from `mark` to the end) using the alignment, target width and fill character defined in `spec`.
    `static PyException` | `precisionNotAllowed(java.lang.String forType)` Convenience method returning a `Py.ValueError` reporting that specifying a precision is not allowed in a format specifier for the named type.
    `static PyException` | `precisionTooLarge(java.lang.String type)` Convenience method returning a `Py.OverflowError` reporting: `"formatted "+type+" is too long (precision too large?)"`
    `void` | `setBytes(boolean bytes)` Signals the client's intention to make a PyString (or other byte-like) interpretation of `result`, rather than a PyUnicode one.
    `void` | `setStart()` Clear the instance variables describing the latest object in `result`, ready to receive a new one: sets `start` and calls `reset()`.
    `static PyException` | `signNotAllowed(java.lang.String forType, char code)` Convenience method returning a `Py.ValueError` reporting that specifying a sign is not allowed in a format specifier for the named type.
    `java.lang.String` | `toString()` Overridden to provide a debugging view in which the actual text is shown divided up by the `len*` member variables.
    `static PyException` | `unknownFormat(char code, java.lang.String forType)` Convenience method returning a `Py.ValueError` reporting: `"Unknown format code '"+code+"' for object of type '"+forType+"'"`
    `static PyException` | `zeroPaddingNotAllowed(java.lang.String forType)` Convenience method returning a `Py.ValueError` reporting that zero padding is not allowed in a format specifier for the named type.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Formatter

          public Formatter(java.lang.StringBuilder result,
                           InternalFormat.Spec spec)

      Construct the formatter from a client-supplied buffer and a specification. Sets `mark` and `start` to the end of the buffer. The new formatted object will therefore be appended there and, when the time comes, padding will be applied to (just) the new text.
      Parameters:
        `result` - destination buffer
        `spec` - parsed conversion specification

    - #### Formatter

          public Formatter(InternalFormat.Spec spec,
                           int width)

      Construct the formatter from a specification and initial buffer capacity. Sets `mark` to the end of the buffer.
      Parameters:
        `spec` - parsed conversion specification
        `width` - of buffer initially

  - ### Method Detail

    - #### setBytes

          public void setBytes(boolean bytes)

      Signals the client's intention to make a PyString (or other byte-like) interpretation of `result`, rather than a PyUnicode one. Only formatters that could produce characters >255 are affected by this (e.g. c-format). Idiom:

           MyFormatter f = new MyFormatter( InternalFormatter.fromText(formatSpec) );
           f.setBytes(!(formatSpec instanceof PyUnicode));
           // ... formatting work
           return f.getPyResult();

      Parameters:
        `bytes` - true to signal the intention to make a byte-like interpretation

    - #### isBytes

          public boolean isBytes()

      Whether initialised for a byte-like interpretation.
      Returns:
        bytes attribute

    - #### getResult

          public java.lang.String getResult()

      Current (possibly final) result of the formatting, as a `String`.
      Returns:
        formatted result

    - #### getPyResult

          public PyString getPyResult()

      Convenience method to return the current result of the formatting, as a `PyObject`, either `PyString` or `PyUnicode` according to `bytes`.
      Returns:
        formatted result

    - #### append

          public InternalFormat.Formatter append(char c)

      Specified by:
        `append` in interface `java.lang.Appendable`

    - #### append

          public InternalFormat.Formatter append(java.lang.CharSequence csq)

      Specified by:
        `append` in interface `java.lang.Appendable`

    - #### append

          public InternalFormat.Formatter append(java.lang.CharSequence csq,
                                                 int start,
                                                 int end)
                                          throws java.lang.IndexOutOfBoundsException

      Specified by:
        `append` in interface `java.lang.Appendable`
      Throws:
        `java.lang.IndexOutOfBoundsException`

    - #### setStart

          public void setStart()

      Clear the instance variables describing the latest object in `result`, ready to receive a new one: sets `start` and calls `reset()`. This is necessary when a `Formatter` is to be re-used. Note that this leaves `mark` where it is. In the core, we need this to support `complex`: two floats in the same format, but padded as a unit.

    - #### toString

          public java.lang.String toString()

      Overridden to provide a debugging view in which the actual text is shown divided up by the `len*` member variables. If the dividers don't look right, those variables have not remained consistent with the text.

      Overrides:
        `toString` in class `java.lang.Object`

    - #### pad

          public InternalFormat.Formatter pad()

      Pad the result so far (defined as the contents of `result` from `mark` to the end) using the alignment, target width and fill character defined in `spec`. The action of padding will increase the length of this segment to the target width, if that is greater than the current length.

      When the padding method has decided that that it needs to add n padding characters, it will affect `start` or `lenWhole` as follows.

      Effect of padding on `start` or `lenWhole`
      align | meaning | start | lenWhole | result.length()
      --- | --- | --- | --- | ---
      `<` | left-aligned | +0 | +0 | +n
      `>` | right-aligned | +n | +0 | +n
      `^` | centred | +(n/2) | +0 | +n
      `=` | pad after sign | +0 | +n | +n

      Note that in the "pad after sign" mode, only the last number into the buffer receives the padding. This padding gets incorporated into the whole part of the number. (In other modes, the padding is around `result[mark:]`.) When this would not be appropriate, it is up to the client to disallow this (which `complex` does).
      Returns:
        this Formatter object

    - #### unknownFormat

          public static PyException unknownFormat(char code,
                                                  java.lang.String forType)

      Convenience method returning a `Py.ValueError` reporting:

      `"Unknown format code '"+code+"' for object of type '"+forType+"'"`

      Parameters:
        `code` - the presentation type
        `forType` - the type it was found applied to
      Returns:
        exception to throw

    - #### alternateFormNotAllowed

          public static PyException alternateFormNotAllowed(java.lang.String forType)

      Convenience method returning a `Py.ValueError` reporting that alternate form is not allowed in a format specifier for the named type.
      Parameters:
        `forType` - the type it was found applied to
      Returns:
        exception to throw

    - #### alternateFormNotAllowed

          public static PyException alternateFormNotAllowed(java.lang.String forType,
                                                            char code)

      Convenience method returning a `Py.ValueError` reporting that alternate form is not allowed in a format specifier for the named type and specified typoe code.
      Parameters:
        `forType` - the type it was found applied to
        `code` - the formatting code (or '\0' not to mention one)
      Returns:
        exception to throw

    - #### alignmentNotAllowed

          public static PyException alignmentNotAllowed(char align,
                                                        java.lang.String forType)

      Convenience method returning a `Py.ValueError` reporting that the given alignment flag is not allowed in a format specifier for the named type.
      Parameters:
        `align` - type of alignment
        `forType` - the type it was found applied to
      Returns:
        exception to throw

    - #### signNotAllowed

          public static PyException signNotAllowed(java.lang.String forType,
                                                   char code)

      Convenience method returning a `Py.ValueError` reporting that specifying a sign is not allowed in a format specifier for the named type.
      Parameters:
        `forType` - the type it was found applied to
        `code` - the formatting code (or '\0' not to mention one)
      Returns:
        exception to throw

    - #### precisionNotAllowed

          public static PyException precisionNotAllowed(java.lang.String forType)

      Convenience method returning a `Py.ValueError` reporting that specifying a precision is not allowed in a format specifier for the named type.
      Parameters:
        `forType` - the type it was found applied to
      Returns:
        exception to throw

    - #### zeroPaddingNotAllowed

          public static PyException zeroPaddingNotAllowed(java.lang.String forType)

      Convenience method returning a `Py.ValueError` reporting that zero padding is not allowed in a format specifier for the named type.
      Parameters:
        `forType` - the type it was found applied to
      Returns:
        exception to throw

    - #### notAllowed

          public static PyException notAllowed(java.lang.String outrage,
                                               java.lang.String forType)

      Convenience method returning a `Py.ValueError` reporting that some format specifier feature is not allowed for the named data type.
      Parameters:
        `outrage` - committed in the present case
        `forType` - the data type (e.g. "integer") it where it is an outrage
      Returns:
        exception to throw

    - #### notAllowed

          public static PyException notAllowed(java.lang.String outrage,
                                               java.lang.String forType,
                                               char code)

      Convenience method returning a `Py.ValueError` reporting that some format specifier feature is not allowed for the named format code and data type. Produces a message like:

      `outrage+" not allowed with "+forType+" format specifier '"+code+"'"`

      `outrage+" not allowed in "+forType+" format specifier"`

      Parameters:
        `outrage` - committed in the present case
        `forType` - the data type (e.g. "integer") it where it is an outrage
        `code` - the formatting code for which it is an outrage (or '\0' not to mention one)
      Returns:
        exception to throw

    - #### precisionTooLarge

          public static PyException precisionTooLarge(java.lang.String type)

      Convenience method returning a `Py.OverflowError` reporting:

      `"formatted "+type+" is too long (precision too large?)"`

      Parameters:
        `type` - of formatting ("integer", "float")
      Returns:
        exception to throw

Jython homepage