TextFormatter (Jython API documentation)
Date: 2022-09-10

org.python.core.stringlib

## Class TextFormatter

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

- All Implemented Interfaces:
    java.lang.Appendable

      public class TextFormatter
      extends InternalFormat.Formatter

  A class that provides the implementation of `str` and `unicode` formatting. In a limited way, it acts like a StringBuilder to which text, 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
    `TextFormatter(InternalFormat.Spec spec)` Construct the formatter from a specification, allocating a buffer internally for the result.
    `TextFormatter(java.lang.StringBuilder result, InternalFormat.Spec spec)` Construct the formatter from a client-supplied buffer, to which the result will be appended, and a specification.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `TextFormatter` | `append(char c)`
    `TextFormatter` | `append(java.lang.CharSequence csq)`
    `TextFormatter` | `append(java.lang.CharSequence csq, int start, int end)`
    `TextFormatter` | `format(java.lang.String value)` Format the given `String` into the `result` buffer.
    `TextFormatter` | `pad()` Pad the result so far (defined as the contents of `InternalFormat.Formatter.result` from `InternalFormat.Formatter.mark` to the end) using the alignment, target width and fill character defined in `InternalFormat.Formatter.spec`.

    - ### Methods inherited from class org.python.core.stringlib.InternalFormat.Formatter

      `alignmentNotAllowed, alternateFormNotAllowed, alternateFormNotAllowed, getPyResult, getResult, isBytes, notAllowed, notAllowed, precisionNotAllowed, precisionTooLarge, setBytes, setStart, signNotAllowed, toString, unknownFormat, zeroPaddingNotAllowed`

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

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

- - ### Constructor Detail

    - #### TextFormatter

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

      Construct the formatter from a client-supplied buffer, to which the result will be appended, and a specification. Sets `InternalFormat.Formatter.mark` to the end of the buffer.
      Parameters:
        `result` - destination buffer
        `spec` - parsed conversion specification

    - #### TextFormatter

          public TextFormatter(InternalFormat.Spec spec)

      Construct the formatter from a specification, allocating a buffer internally for the result.
      Parameters:
        `spec` - parsed conversion specification

  - ### Method Detail

    - #### append

          public TextFormatter append(char c)

      Specified by:
        `append` in interface `java.lang.Appendable`
      Overrides:
        `append` in class `InternalFormat.Formatter`

    - #### append

          public TextFormatter append(java.lang.CharSequence csq)

      Specified by:
        `append` in interface `java.lang.Appendable`
      Overrides:
        `append` in class `InternalFormat.Formatter`

    - #### append

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

      Specified by:
        `append` in interface `java.lang.Appendable`
      Overrides:
        `append` in class `InternalFormat.Formatter`
      Throws:
        `java.lang.IndexOutOfBoundsException`

    - #### format

          public TextFormatter format(java.lang.String value)

      Format the given `String` into the `result` buffer. Largely, this is a matter of copying the value of the argument, but a subtlety arises when the string contains supplementary (non-BMP) Unicode characters, which are represented as surrogate pairs. The precision specified in the format relates to a count of Unicode characters (code points), not Java `char`s. The method deals with this correctly, essentially by not counting the high-surrogates in the allowance. The final value of `InternalFormat.Formatter.lenWhole` counts the UTF-16 units added.
      Parameters:
        `value` - to format
      Returns:
        this `TextFormatter` object

    - #### pad

          public TextFormatter pad()

      Description copied from class: `InternalFormat.Formatter`
      Pad the result so far (defined as the contents of `InternalFormat.Formatter.result` from `InternalFormat.Formatter.mark` to the end) using the alignment, target width and fill character defined in `InternalFormat.Formatter.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 `InternalFormat.Formatter.start` or `InternalFormat.Formatter.lenWhole` as follows.

      Effect of padding on `InternalFormat.Formatter.start` or `InternalFormat.Formatter.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).
      Overrides:
        `pad` in class `InternalFormat.Formatter`
      Returns:
        this Formatter object

Jython homepage