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