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
`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