Modifier and Type	Class and Description
public static class	InternalFormat.Formatter A class that provides the base for implementations of type-specific formatting.
private static class	InternalFormat.Parser Parser for PEP-3101 field format specifications.
public static class	InternalFormat.Spec Parsed PEP-3101 format specification of a single field, encapsulating the format for use by formatting methods.

Access	Constructor and Description
public	InternalFormat()

Modifier and Type	Method and Description
public static InternalFormat.Spec	Returns: parsed equivalent to text fromText(String to parse text) Create a `Spec` object by parsing a format specification.
public static InternalFormat.Spec	Returns: parsed equivalent to text fromText(PyObject to parse text, String method) Create a `Spec` object by parsing a format specification, supplied as an object.

InternalFormat	back to summary
public InternalFormat()

fromText	back to summary
public static InternalFormat.Spec fromText(String text) Create a `Spec` object by parsing a format specification. Parameters text:String to parse Returns:InternalFormat.Spec parsed equivalent to text

fromText	back to summary
public static InternalFormat.Spec fromText(PyObject text, String method) Create a `Spec` object by parsing a format specification, supplied as an object. Parameters text:PyObject to parse Returns:InternalFormat.Spec parsed equivalent to text

org.python.core.stringlib back to summary

public Class InternalFormat.Formatter

Class Inheritance

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

All Implemented Interfaces

java.lang.Appendable

Known Direct Subclasses

org.python.core.stringlib.TextFormatter, org.python.core.stringlib.FloatFormatter, org.python.core.stringlib.IntegerFormatter

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

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 StringBuilder	result The (partial) result.
protected final 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

Access	Constructor and Description
public	Formatter(StringBuilder destination buffer result, InternalFormat.Spec parsed conversion specification spec) Construct the formatter from a client-supplied buffer and a specification.
public	Formatter(InternalFormat.Spec parsed conversion specification spec, int of buffer initially width) Construct the formatter from a specification and initial buffer capacity.

Method Summary

Modifier and Type	Method and Description
public static PyException	Returns: exception to throw alignmentNotAllowed(char type of alignment align, String the type it was found applied to forType) Convenience method returning a `Py#ValueError` reporting that the given alignment flag is not allowed in a format specifier for the named type.
public static PyException	Returns: exception to throw alternateFormNotAllowed(String the type it was found applied to forType) Convenience method returning a `Py#ValueError` reporting that alternate form is not allowed in a format specifier for the named type.
public static PyException	Returns: exception to throw alternateFormNotAllowed(String the type it was found applied to forType, char the formatting code (or '\0' not to mention one) 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.
public InternalFormat.Formatter	append(char The character to append c) Implements java.lang.Appendable.append. Appends the specified character to this `Appendable`.
public InternalFormat.Formatter	append(CharSequence The character sequence to append. If `csq` is `null`, then the four characters `"null"` are appended to this Appendable. csq) Implements java.lang.Appendable.append. Appends the specified character sequence to this `Appendable`.
public InternalFormat.Formatter	append(CharSequence The character sequence from which a subsequence will be appended. If `csq` is `null`, then characters will be appended as if `csq` contained the four characters `"null"`. csq, int The index of the first character in the subsequence start, int The index of the character following the last character in the subsequence end) Implements java.lang.Appendable.append. Appends a subsequence of the specified character sequence to this `Appendable`.
public PyString	Returns: formatted result getPyResult() Convenience method to return the current result of the formatting, as a `PyObject`, either `PyString` or `PyUnicode` according to `bytes`.
public String	Returns: formatted result getResult() Current (possibly final) result of the formatting, as a `String`.
protected void	groupDigits(int normally 3. groupSize, char or some other character to use as a separator. comma) Insert grouping characters (conventionally commas) into the whole part of the number.
public boolean	Returns: bytes attribute isBytes() Whether initialised for a byte-like interpretation.
protected void	makeSpaceAt(int at which to make the space pos, int of the space size) Make a space in `result` of a certain size and position.
public static PyException	Returns: exception to throw notAllowed(String committed in the present case outrage, String the data type (e.g. "integer") it where it is an outrage forType) Convenience method returning a `Py#ValueError` reporting that some format specifier feature is not allowed for the named data type.
public static PyException	Returns: exception to throw notAllowed(String committed in the present case outrage, String the data type (e.g. "integer") it where it is an outrage forType, char the formatting code for which it is an outrage (or '\0' not to mention one) code) Convenience method returning a `Py#ValueError` reporting that some format specifier feature is not allowed for the named format code and data type.
public InternalFormat.Formatter	Returns: this Formatter object 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 the index in result at which to insert left-fill characters. leftIndex, int number of fill characters to insert. 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`.
public static PyException	Returns: exception to throw precisionNotAllowed(String the type it was found applied to forType) Convenience method returning a `Py#ValueError` reporting that specifying a precision is not allowed in a format specifier for the named type.
public static PyException	Returns: exception to throw precisionTooLarge(String of formatting ("integer", "float") type) Convenience method returning a `Py#OverflowError` reporting: `"formatted "+type+" is too long (precision too large?)"`
protected void	reset() Clear the instance variables describing the latest object in `result`, ready to receive a new one.
protected int[]	Returns: the lengths of the successive sections sectionLengths() Supports `toString()` by returning the lengths of the successive sections in the result buffer, used for navigation relative to `start`.
public void	setBytes(boolean true to signal the intention to make a byte-like interpretation bytes) Signals the client's intention to make a PyString (or other byte-like) interpretation of `result`, rather than a PyUnicode one.
public void	setStart() Clear the instance variables describing the latest object in `result`, ready to receive a new one: sets `start` and calls `reset()`.
public static PyException	Returns: exception to throw signNotAllowed(String the type it was found applied to forType, char the formatting code (or '\0' not to mention one) code) Convenience method returning a `Py#ValueError` reporting that specifying a sign is not allowed in a format specifier for the named type.
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.
public static PyException	Returns: exception to throw unknownFormat(char the presentation type code, String the type it was found applied to forType) Convenience method returning a `Py#ValueError` reporting: `"Unknown format code '"+code+"' for object of type '"+forType+"'"`
protected void	uppercase() Convert letters in the representation of the current number (in `result`) to upper case.
protected void	zeroPadAfterSignWithGroupingFixup(int normally 3. groupSize, char or some other character to use as a separator. 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.
public static PyException	Returns: exception to throw zeroPaddingNotAllowed(String the type it was found applied to forType) Convenience method returning a `Py#ValueError` reporting that zero padding is not allowed in a format specifier for the named type.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

bytes	back to summary
protected boolean bytes Signals the client's intention to make a PyString (or other byte-like) interpretation of `result`, rather than a PyUnicode one.

lenSign	back to summary
protected int lenSign If it contains no sign, this length is zero, and >0 otherwise.

lenWhole	back to summary
protected int lenWhole The length of the whole part (to left of the decimal point or exponent)

mark	back to summary
protected int mark The start of the formatted data for padding purposes, <=`start`

result	back to summary
protected StringBuilder result The (partial) result.

spec	back to summary
protected final InternalFormat.Spec spec The specification according to which we format any number supplied to the method.

start	back to summary
protected int start The latest number we are working on floats at the end of the result, and starts here.

Constructor Detail

Formatter back to summary

Formatter	back to summary
public Formatter(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:StringBuilder destination buffer spec:InternalFormat.Spec parsed conversion specification

public Formatter(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:StringBuilder: destination buffer
spec:InternalFormat.Spec: parsed conversion specification

Formatter back to summary

Formatter	back to summary
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:InternalFormat.Spec parsed conversion specification width:int of buffer initially

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:InternalFormat.Spec: parsed conversion specification
width:int: of buffer initially

Method Detail

alignmentNotAllowed back to summary

alignmentNotAllowed	back to summary
public static PyException alignmentNotAllowed(char align, 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:char type of alignment forType:String the type it was found applied to Returns:PyException exception to throw

public static PyException alignmentNotAllowed(char align, 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:char: type of alignment
forType:String: the type it was found applied to

Returns:PyException

exception to throw

alternateFormNotAllowed back to summary

alternateFormNotAllowed	back to summary
public static PyException alternateFormNotAllowed(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:String the type it was found applied to Returns:PyException exception to throw

public static PyException alternateFormNotAllowed(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:String: the type it was found applied to

Returns:PyException

exception to throw

alternateFormNotAllowed back to summary

alternateFormNotAllowed	back to summary
public static PyException alternateFormNotAllowed(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:String the type it was found applied to code:char the formatting code (or '\0' not to mention one) Returns:PyException exception to throw

public static PyException alternateFormNotAllowed(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:String: the type it was found applied to
code:char: the formatting code (or '\0' not to mention one)

Returns:PyException

exception to throw

append back to summary

append	back to summary
public InternalFormat.Formatter append(char c) Implements java.lang.Appendable.append. Doc from java.lang.Appendable.append. Appends the specified character to this `Appendable`. Parameters c:char The character to append Returns:InternalFormat.Formatter A reference to this `Appendable` Annotations @Override

public InternalFormat.Formatter append(char c)

Implements java.lang.Appendable.append.

Doc from java.lang.Appendable.append.

Appends the specified character to this Appendable.

Parameters

c:char: The character to append

Returns:InternalFormat.Formatter

A reference to this Appendable

Annotations

@Override

append back to summary

append	back to summary
public InternalFormat.Formatter append(CharSequence csq) Implements java.lang.Appendable.append. Doc from java.lang.Appendable.append. Appends the specified character sequence to this `Appendable`. Depending on which class implements the character sequence `csq`, the entire sequence may not be appended. For instance, if `csq` is a `java.nio.CharBuffer` then the subsequence to append is defined by the buffer's position and limit. The contents of this `Appendable` are unspecified if the `CharSequence` is modified during the method call or an exception is thrown when accessing the `CharSequence`. Parameters csq:CharSequence The character sequence to append. If `csq` is `null`, then the four characters `"null"` are appended to this Appendable. Returns:InternalFormat.Formatter A reference to this `Appendable` Annotations @Override

public InternalFormat.Formatter append(CharSequence csq)

Implements java.lang.Appendable.append.

Doc from java.lang.Appendable.append.

Appends the specified character sequence to this Appendable.

Depending on which class implements the character sequence csq, the entire sequence may not be appended. For instance, if csq is a java.nio.CharBuffer then the subsequence to append is defined by the buffer's position and limit.

The contents of this Appendable are unspecified if the CharSequence is modified during the method call or an exception is thrown when accessing the CharSequence.

Parameters

csq:CharSequence: The character sequence to append. If csq is null, then the four characters "null" are appended to this Appendable.

Returns:InternalFormat.Formatter

A reference to this Appendable

Annotations

@Override

append back to summary

append	back to summary
public InternalFormat.Formatter append(CharSequence csq, int start, int end) throws IndexOutOfBoundsException Implements java.lang.Appendable.append. Doc from java.lang.Appendable.append. Appends a subsequence of the specified character sequence to this `Appendable`. An invocation of this method of the form `out.append(csq, start, end)` when `csq` is not `null`, behaves in exactly the same way as the invocation out.append(csq.subSequence(start, end)) The contents of this `Appendable` are unspecified if the `CharSequence` is modified during the method call or an exception is thrown when accessing the `CharSequence`. Parameters csq:CharSequence The character sequence from which a subsequence will be appended. If `csq` is `null`, then characters will be appended as if `csq` contained the four characters `"null"`. start:int The index of the first character in the subsequence end:int The index of the character following the last character in the subsequence Returns:InternalFormat.Formatter A reference to this `Appendable` Annotations @Override Exceptions IndexOutOfBoundsException: If `start` or `end` are negative, `start` is greater than `end`, or `end` is greater than `csq.length()`

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

Implements java.lang.Appendable.append.

Doc from java.lang.Appendable.append.

Appends a subsequence of the specified character sequence to this Appendable.

An invocation of this method of the form out.append(csq, start, end) when csq is not null, behaves in exactly the same way as the invocation

    out.append(csq.subSequence(start, end))

The contents of this Appendable are unspecified if the CharSequence is modified during the method call or an exception is thrown when accessing the CharSequence.

Parameters

csq:CharSequence: The character sequence from which a subsequence will be appended. If csq is null, then characters will be appended as if csq contained the four characters "null".
start:int: The index of the first character in the subsequence
end:int: The index of the character following the last character in the subsequence

Returns:InternalFormat.Formatter

A reference to this Appendable

Annotations

@Override

Exceptions

IndexOutOfBoundsException:: If start or end are negative, start is greater than end, or end is greater than csq.length()

getPyResult back to summary

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

public PyString getPyResult()

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

Returns:PyString: formatted result

getResult back to summary

getResult	back to summary
public String getResult() Current (possibly final) result of the formatting, as a `String`. Returns:String formatted result

public String getResult()

Current (possibly final) result of the formatting, as a String.

Returns:String: formatted result

groupDigits back to summary

groupDigits	back to summary
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:int normally 3. comma:char or some other character to use as a separator.

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:int: normally 3.
comma:char: or some other character to use as a separator.

isBytes	back to summary
public boolean isBytes() Whether initialised for a byte-like interpretation. Returns:boolean bytes attribute

isBytes

back to summary

public boolean isBytes()

Whether initialised for a byte-like interpretation.

Returns:boolean: bytes attribute

makeSpaceAt back to summary

makeSpaceAt	back to summary
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:int at which to make the space size:int of the space

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:int: at which to make the space
size:int: of the space

notAllowed back to summary

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

public static PyException notAllowed(String outrage, String forType)

Convenience method returning a Py#ValueError reporting that some format specifier feature is not allowed for the named data type.

Parameters

outrage:String: committed in the present case
forType:String: the data type (e.g. "integer") it where it is an outrage

Returns:PyException

exception to throw

notAllowed back to summary

notAllowed	back to summary
public static PyException notAllowed(String outrage, 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:String committed in the present case forType:String the data type (e.g. "integer") it where it is an outrage code:char the formatting code for which it is an outrage (or '\0' not to mention one) Returns:PyException exception to throw

public static PyException notAllowed(String outrage, 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:String: committed in the present case
forType:String: the data type (e.g. "integer") it where it is an outrage
code:char: the formatting code for which it is an outrage (or '\0' not to mention one)

Returns:PyException

exception to throw

pad back to summary

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:InternalFormat.Formatter: this Formatter object

pad back to summary

pad	back to summary
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:int the index in result at which to insert left-fill characters. n:int number of fill characters to insert.

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:int: the index in result at which to insert left-fill characters.
n:int: number of fill characters to insert.

precisionNotAllowed back to summary

precisionNotAllowed	back to summary
public static PyException precisionNotAllowed(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:String the type it was found applied to Returns:PyException exception to throw

public static PyException precisionNotAllowed(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:String: the type it was found applied to

Returns:PyException

exception to throw

precisionTooLarge back to summary

precisionTooLarge	back to summary
public static PyException precisionTooLarge(String type) Convenience method returning a `Py#OverflowError` reporting: `"formatted "+type+" is too long (precision too large?)"` Parameters type:String of formatting ("integer", "float") Returns:PyException exception to throw

public static PyException precisionTooLarge(String type)

Convenience method returning a Py#OverflowError reporting:

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

Parameters

type:String: of formatting ("integer", "float")

Returns:PyException

exception to throw

reset	back to summary
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 back to summary

sectionLengths	back to summary
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:int[] the lengths of the successive sections

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:int[]: the lengths of the successive sections

setBytes back to summary

setBytes	back to summary
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:boolean true to signal the intention to make a byte-like interpretation

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:boolean: true to signal the intention to make a byte-like interpretation

setStart	back to summary
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.

signNotAllowed back to summary

signNotAllowed	back to summary
public static PyException signNotAllowed(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:String the type it was found applied to code:char the formatting code (or '\0' not to mention one) Returns:PyException exception to throw

public static PyException signNotAllowed(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:String: the type it was found applied to
code:char: the formatting code (or '\0' not to mention one)

Returns:PyException

exception to throw

toString back to summary

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Doc from java.lang.Object.toString. Returns a string representation of the object. 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. Returns:String a string representation of the object Annotations @Override

public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

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.

Returns:String

a string representation of the object

Annotations

@Override

unknownFormat back to summary

unknownFormat	back to summary
public static PyException unknownFormat(char code, String forType) Convenience method returning a `Py#ValueError` reporting: `"Unknown format code '"+code+"' for object of type '"+forType+"'"` Parameters code:char the presentation type forType:String the type it was found applied to Returns:PyException exception to throw

public static PyException unknownFormat(char code, String forType)

Convenience method returning a Py#ValueError reporting:

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

Parameters

code:char: the presentation type
forType:String: the type it was found applied to

Returns:PyException

exception to throw

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

zeroPadAfterSignWithGroupingFixup back to summary

zeroPadAfterSignWithGroupingFixup	back to summary
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:int normally 3. comma:char or some other character to use as a separator.

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:int: normally 3.
comma:char: or some other character to use as a separator.

zeroPaddingNotAllowed back to summary

zeroPaddingNotAllowed	back to summary
public static PyException zeroPaddingNotAllowed(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:String the type it was found applied to Returns:PyException exception to throw

public static PyException zeroPaddingNotAllowed(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:String: the type it was found applied to

Returns:PyException

exception to throw

Modifier and Type	Field and Description
private int	ptr
private String	spec

Access	Constructor and Description
pack-priv	Parser(String format specifier to parse (e.g. "<+12.3f") spec) Constructor simply holds the specification string ahead of the `parse()` operation.

Modifier and Type	Method and Description
private boolean	isAlign() Test that the next character is one of the alignment characters.
private boolean	isAt(String chars) Test that the next character is one of a specified set.
private boolean	isDigit() Test that the next character is a digit.
pack-priv InternalFormat.Spec	Returns: the `Spec` equivalent to the string given. parse() Parse the specification with which this object was initialised into an `Spec`, which is an object encapsulating the format for use by formatting methods.
private int	scanInteger() The current character is a digit (maybe a sign).
private boolean	scanPast(char c) Test that the next character is exactly the one specified, and advance past it if it is.

ptr	back to summary
private int ptr

org.python.core.stringlib back to summary

public Class InternalFormat.Spec

Class Inheritance

extends Object

java.lang.Object
org.python.core.stringlib.InternalFormat.Spec

Parsed PEP-3101 format specification of a single field, encapsulating the format for use by formatting methods. This class holds the several attributes that might be decoded from a format specifier. Each attribute has a reserved value used to indicate "unspecified". Spec objects may be merged such that one Spec provides values, during the construction of a new Spec, for attributes that are unspecified in a primary source.

This structure is returned by factory method fromText(String), and having public final members is freely accessed by formatters such as FloatFormatter, and the __format__ methods of client object types.

The fields correspond to the elements of a format specification. The grammar of a format specification is:

[[fill]align][sign][#][0][width][,][.precision][type]

A typical idiom is:

private static final InternalFormatSpec FLOAT_DEFAULTS = InternalFormatSpec.from(">");
    ...
        InternalFormat.Spec spec = InternalFormat.fromText(specString);
        spec = spec.withDefaults(FLOAT_DEFAULTS);
        ... // Validation of spec.type, and other attributes, for this type.
        FloatFormatter f = new FloatFormatter(spec);
        String result = f.format(value).getResult();

Field Summary

Modifier and Type	Field and Description
public final char	align Alignment indicator is one of {'<', '^', '>', '=', or U+FFFF if unspecified.
public final boolean	alternate The alternative format flag '#' was given.
public final char	fill The fill character specified, or U+FFFF if unspecified.
public final boolean	grouping Insert the grouping separator (which in Python always indicates a group-size of 3).
public static final char	NONE Non-character code point used to represent "no value" in `char` attributes.
public static final InternalFormat.Spec	NUMERIC Defaults applicable to most numeric types.
public final int	precision Precision decoded from the format, or -1 if unspecified.
public final char	sign Sign-handling flag, one of `'+'`, `'-'`, or `' '`, or U+FFFF if unspecified.
public static final InternalFormat.Spec	STRING Defaults applicable to string types.
public final char	type Type key from the format, or U+FFFF if unspecified.
public static final int	UNSPECIFIED Negative value used to represent "no value" in `int` attributes.
public final int	width Width to which to pad the result, or -1 if unspecified.

Constructor Summary

Access Constructor and Description

public

Spec(char

fill character (or NONE

fill, char

alignment indicator, one of {'<', '^', '>', '='}

align, char

policy, one of '+', '-', or ' '.

sign, boolean

true to request alternate formatting mode ('#' flag).

alternate, int

of field after padding or -1 to default

width, boolean

true to request comma-separated groups

grouping, int

(e.g. decimal places) or -1 to default

precision, char

indicator character

type)

Constructor to set all the fields in the format specifier.

public

Spec(int

(e.g. decimal places)

precision, char

indicator character

type)

Constructor offering just precision and type.

Method Summary

Modifier and Type	Method and Description
public char	getAlign(char defaultAlign) The alignment from the parsed format specification, or default.
public char	getFill(char defaultFill) The alignment from the parsed format specification, or default.
public int	getPrecision(int defaultPrecision) The precision from the parsed format specification, or default.
public char	getType(char defaultType) The type code from the parsed format specification, or default supplied.
public static final boolean	Returns: true only if the attribute is not equal to `NONE` specified(char attribute c) Test to see if an attribute has been specified.
public static final boolean	Returns: true only if the attribute is ≥0 (meaning that it has been specified). specified(int of attribute value) Test to see if an attribute has been specified.
public String	toString() Overrides java.lang.Object.toString. Return a format specifier (text) equivalent to the value of this Spec.
public InternalFormat.Spec	Returns: a new Spec object. withDefaults(InternalFormat.Spec defaults to merge where this object does not specify the attribute. other) Return a merged `Spec` object, in which any attribute of this object that is specified (or `true`), has the same value in the result, and any attribute of this object that is unspecified (or `false`), has the value that attribute takes in the other object.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

align	back to summary
public final char align Alignment indicator is one of {'<', '^', '>', '=', or U+FFFF if unspecified.

alternate	back to summary
public final boolean alternate The alternative format flag '#' was given.

fill	back to summary
public final char fill The fill character specified, or U+FFFF if unspecified.

grouping	back to summary
public final boolean grouping Insert the grouping separator (which in Python always indicates a group-size of 3).

NONE	back to summary
public static final char NONE Non-character code point used to represent "no value" in `char` attributes.

NUMERIC	back to summary
public static final InternalFormat.Spec NUMERIC Defaults applicable to most numeric types. Equivalent to " >"

precision	back to summary
public final int precision Precision decoded from the format, or -1 if unspecified.

sign	back to summary
public final char sign Sign-handling flag, one of `'+'`, `'-'`, or `' '`, or U+FFFF if unspecified.

STRING	back to summary
public static final InternalFormat.Spec STRING Defaults applicable to string types. Equivalent to " <"

type	back to summary
public final char type Type key from the format, or U+FFFF if unspecified.

UNSPECIFIED	back to summary
public static final int UNSPECIFIED Negative value used to represent "no value" in `int` attributes.

width	back to summary
public final int width Width to which to pad the result, or -1 if unspecified.

Constructor Detail

Spec back to summary

public Spec(char fill, char align, char sign, boolean alternate, int width, boolean grouping, int precision, char type)

Constructor to set all the fields in the format specifier.

[[fill]align][sign][#][0][width][,][.precision][type]

Parameters

fill:char: fill character (or NONE
align:char: alignment indicator, one of {'<', '^', '>', '='}
sign:char: policy, one of '+', '-', or ' '.
alternate:boolean: true to request alternate formatting mode ('#' flag).
width:int: of field after padding or -1 to default
grouping:boolean: true to request comma-separated groups
precision:int: (e.g. decimal places) or -1 to default
type:char: indicator character

Spec

back to summary

public Spec(int precision, char type)

Constructor offering just precision and type.

[.precision][type]

Parameters

precision:int: (e.g. decimal places)
type:char: indicator character

Method Detail

getAlign	back to summary
public char getAlign(char defaultAlign) The alignment from the parsed format specification, or default.

getFill	back to summary
public char getFill(char defaultFill) The alignment from the parsed format specification, or default.

getPrecision	back to summary
public int getPrecision(int defaultPrecision) The precision from the parsed format specification, or default.

getType	back to summary
public char getType(char defaultType) The type code from the parsed format specification, or default supplied.

specified back to summary

public static final boolean specified(char c)

Test to see if an attribute has been specified.

Parameters

c:char: attribute

Returns:boolean

true only if the attribute is not equal to NONE

specified

back to summary

public static final boolean specified(int value)

Test to see if an attribute has been specified.

Parameters

value:int: of attribute

Returns:boolean

true only if the attribute is ≥0 (meaning that it has been specified).

toString

back to summary

public String toString()

Overrides java.lang.Object.toString.

Return a format specifier (text) equivalent to the value of this Spec.

Returns:String

Doc from java.lang.Object.toString.

a string representation of the object

Annotations

@Override

withDefaults back to summary

public InternalFormat.Spec withDefaults(InternalFormat.Spec other)

Return a merged Spec object, in which any attribute of this object that is specified (or true), has the same value in the result, and any attribute of this object that is unspecified (or false), has the value that attribute takes in the other object. Thus the second object supplies default values. (These defaults may also be unspecified.) The use of this method is to allow a Spec constructed from text to record exactly, and only, what was in the textual specification, while the __format__ method of a client object supplies its type-specific defaults. Thus "20" means "<20s" to a str, ">20.12" to a float and ">20.12g" to a complex.

Parameters

other:InternalFormat.Spec: defaults to merge where this object does not specify the attribute.

Returns:InternalFormat.Spec

a new Spec object.

public Class InternalFormat

Nested and Inner Type Summary

Constructor Summary

Method Summary

Constructor Detail

Method Detail

public Class InternalFormat.Formatter

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class InternalFormat.Parser

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public Class InternalFormat.Spec

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail