InternalFormat.Formatter (jython-slim 2.7.3 API)

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.

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`bytes` Signals the client's intention to make a PyString (or other byte-like) interpretation of `result`, rather than a PyUnicode one.
`protected int`	`lenSign` If it contains no sign, this length is zero, and >0 otherwise.
`protected int`	`lenWhole` The length of the whole part (to left of the decimal point or exponent)
`protected int`	`mark` The start of the formatted data for padding purposes, <=`start`
`protected java.lang.StringBuilder`	`result` The (partial) result.
`protected InternalFormat.Spec`	`spec` The specification according to which we format any number supplied to the method.
`protected int`	`start` The latest number we are working on floats at the end of the result, and starts here.

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`.
`protected void`	`groupDigits(int groupSize, char comma)` Insert grouping characters (conventionally commas) into the whole part of the number.
`boolean`	`isBytes()` Whether initialised for a byte-like interpretation.
`protected void`	`makeSpaceAt(int pos, int size)` Make a space in `result` of a certain size and position.
`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`.
`protected void`	`pad(int leftIndex, int n)` Pad the last result (defined as the contents of `result` from argument `leftIndex` to the end) using the alignment, by `n` repetitions of the fill character defined in `spec`, and distributed according to `spec.align`.
`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:
`protected void`	`reset()` Clear the instance variables describing the latest object in `result`, ready to receive a new one.
`protected int[]`	`sectionLengths()` Supports `toString()` by returning the lengths of the successive sections in the result buffer, used for navigation relative to `start`.
`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()`
`static PyException`	`unknownFormat(char code, java.lang.String forType)` Convenience method returning a `Py.ValueError` reporting:
`protected void`	`uppercase()` Convert letters in the representation of the current number (in `result`) to upper case.
`protected void`	`zeroPadAfterSignWithGroupingFixup(int groupSize, char comma)` Fix-up the zero-padding of the last formatted number in `result` in the special case where a sign-aware padding (`spec.align='='`) was requested, the fill character is `'0'`, and the digits are to be grouped.
`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
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail
- spec
```
protected final InternalFormat.Spec spec
```
  The specification according to which we format any number supplied to the method.
- result
```
protected java.lang.StringBuilder result
```
  The (partial) result.
- bytes
```
protected boolean bytes
```
  Signals the client's intention to make a PyString (or other byte-like) interpretation of result, rather than a PyUnicode one.
- mark
```
protected int mark
```
  The start of the formatted data for padding purposes, <=start
- start
```
protected int start
```
  The latest number we are working on floats at the end of the result, and starts here.
- lenSign
```
protected int lenSign
```
  If it contains no sign, this length is zero, and >0 otherwise.
- lenWhole
```
protected int lenWhole
```
  The length of the whole part (to left of the decimal point or exponent)

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.

reset
```
protected void reset()
```
Clear the instance variables describing the latest object in result, ready to receive a new one. This is called from setStart(). Subclasses override this method and call setStart() at the start of their format method.

sectionLengths
```
protected int[] sectionLengths()
```
Supports toString() by returning the lengths of the successive sections in the result buffer, used for navigation relative to start. The toString method shows a '|' character between each section when it prints out the buffer. Override this when you define more lengths in the subclass.

Returns:

the lengths of the successive sections

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

groupDigits
```
protected void groupDigits(int groupSize,
                           char comma)
```
Insert grouping characters (conventionally commas) into the whole part of the number. lenWhole will increase correspondingly.

Parameters:

groupSize - normally 3.

comma - or some other character to use as a separator.

makeSpaceAt
```
protected void makeSpaceAt(int pos,
                           int size)
```
Make a space in result of a certain size and position. On return, the segment lengths are likely to be invalid until the caller adjusts them corresponding to the insertion. There is no guarantee what the opened space contains.

Parameters:

pos - at which to make the space

size - of the space

uppercase
```
protected void uppercase()
```
Convert letters in the representation of the current number (in result) to upper case.

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

pad
```
protected void pad(int leftIndex,
                   int n)
```
Pad the last result (defined as the contents of result from argument leftIndex to the end) using the alignment, by n repetitions of the fill character defined in spec, and distributed according to spec.align. The value of leftIndex is only used if the alignment is '>' (left) or '^' (both). The value of the critical lengths (lenWhole, lenSign, etc.) are not affected, because we assume that leftIndex <= start.

Parameters:

leftIndex - the index in result at which to insert left-fill characters.

n - number of fill characters to insert.

zeroPadAfterSignWithGroupingFixup
```
protected void zeroPadAfterSignWithGroupingFixup(int groupSize,
                                                 char comma)
```
Fix-up the zero-padding of the last formatted number in result in the special case where a sign-aware padding (spec.align='=') was requested, the fill character is '0', and the digits are to be grouped. In these exact circumstances, the grouping, which must already have been applied to the (whole part) number itself, has to be extended into the zero-padding.
```
 >>> format(-12e8, " =30,.3f")
 '-            1,200,000,000.000'
 >>> format(-12e8, "*=30,.3f")
 '-************1,200,000,000.000'
 >>> format(-12e8, "*>30,.3f")
 '************-1,200,000,000.000'
 >>> format(-12e8, "0>30,.3f")
 '000000000000-1,200,000,000.000'
 >>> format(-12e8, "0=30,.3f")
 '-0,000,000,001,200,000,000.000'
 
```
The padding has increased the overall length of the result to the target width. About one in three calls to this method adds one to the width, because the whole part cannot start with a comma.
```
 >>> format(-12e8, " =30,.4f")
 '-           1,200,000,000.0000'
 >>> format(-12e8, "0=30,.4f")
 '-0,000,000,001,200,000,000.0000'
 
```
Parameters:

groupSize - normally 3.

comma - or some other character to use as a separator.

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

Class InternalFormat.Formatter

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

spec

result

bytes

mark

start

lenSign

lenWhole

Constructor Detail

Formatter

Formatter

Method Detail

setBytes

isBytes

getResult

getPyResult

append

append

append

setStart

reset

sectionLengths

toString

groupDigits

makeSpaceAt

uppercase

pad

pad

zeroPadAfterSignWithGroupingFixup

unknownFormat

alternateFormNotAllowed

alternateFormNotAllowed

alignmentNotAllowed

signNotAllowed

precisionNotAllowed

zeroPaddingNotAllowed

notAllowed

notAllowed

precisionTooLarge