Package org.python.core.stringlib

Class 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 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​(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.

        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