[Python-3000] String formatting: Conversion specifiers

[Nick Coghlan]

Talin wrote:
> So I decided to sit down and rethink the whole conversion specifier 
> system. I looked at the docs for the '%' operator, and some other 
> languages, and here is what I came up with (this is an excerpt from the 
> revised PEP.)

Generally nice, but I'd format the writeup a bit differently (see below) and 
reorder the elements so that an arbitrary character can be supplied as the 
fill character and the old ' ' sign flag behaviour remains available.

I'd also design it so that the standard conversion specifiers are available 
'for free' (i.e., they work for any class, unless the class author 
deliberately replaces them with something else).

Cheers,
Nick.

--------------------------------

Standard Conversion Specifiers

      If an object does not define its own conversion specifiers, a standard
      set of conversion specifiers are used. These are similar in concept to
      the conversion specifiers used by the existing '%' operator, however
      there are also a number of significant differences. The standard
      conversion specifiers fall into three major categories: string
      conversions, integer conversions and floating point conversions.

      The general form of a string conversion specifier is:

          [[fill][align]width][type]

      The brackets ([]) indicate an optional field.

      'width' is a decimal integer defining the minimum field width.
      If not specified, then the field width will be determined by
      the content.

      If the minimum field width is defined, then the optional align
      flag can be one of the following:

          '<' - Forces the field to be left-aligned within the available
                space (This is the default.)
          '>' - Forces the field to be right-aligned within the
                available space.

      The optional 'fill' character defines the character to be used to
      pad the field to the minimum width. The alignment flag must be
      supplied if the character is a number other than 0 (otherwise the
      character would be interpreted as part of the field width specifier).

      Finally, the 'type' determines how the data should be presented.

      The available string conversion types are:

          's' - String format. Invokes str() on the object.
                This is the default conversion specifier type.
          'r' - Repr format. Invokes repr() on the object.


      The general form of an integer conversion specifier is:

          [[fill][align]width][sign]type

      The 'fill', 'align' and 'width' fields are as for string conversion
      specifiers.

      The 'sign' field can be one of the following:

          '+'  - indicates that a sign should be used for both
                 positive as well as negative numbers
          '-'  - indicates that a sign should be used only for negative
                 numbers (this is the default behaviour)
          ' '  - indicates that a leading space should be used on
                 positive numbers
          '()' - indicates that negative numbers should be surrounded
                 by parentheses

      There are several integer conversion types. All invoke int() on the
      object before attempting to format it.

      The available integer conversion types are:

          'b' - Binary. Outputs the number in base 2.
          'c' - Character. Converts the integer to the corresponding
                unicode character before printing.
          'd' - Decimal Integer. Outputs the number in base 10.
          'o' - Octal format. Outputs the number in base 8.
          'x' - Hex format. Outputs the number in base 16, using lower-
                case letters for the digits above 9.
          'X' - Hex format. Outputs the number in base 16, using upper-
                case letters for the digits above 9.

      The general form of a floating point conversion specifier is:

          [[fill][align]width][.precision][sign]type

      The 'fill', 'align', 'width' and 'sign' fields are as for
      integer conversion specifiers.

      The 'precision' field is a decimal number indicating how many digits
      should be displayed after the decimal point.

      There are several floating point conversion types. All invoke float() on
      the object before attempting to format it.

      The available floating point conversion types are:

          'e' - Exponent notation. Prints the number in scientific
                notation using the letter 'e' to indicate the exponent.
          'E' - Exponent notation. Same as 'e' except it uses an upper
                case 'E' as the separator character.
          'f' - Fixed point. Displays the number as a fixed-point
                number.
          'F' - Fixed point. Same as 'f'.
          'g' - General format. This prints the number as a fixed-point
                number, unless the number is too large, in which case
                it switches to 'e' exponent notation.
          'G' - General format. Same as 'g' except switches to 'E'
                if the number gets to large.
          'n' - Number. This is the same as 'g', except that it uses the
                current locale setting to insert the appropriate
                number separator characters.
          '%' - Percentage. Multiplies the number by 100 and displays
                in fixed ('f') format, followed by a percent sign.

      Objects are able to define their own conversion specifiers to replace
      the standard ones.  An example is the 'datetime' class, whose
      conversion specifiers might look something like the arguments
      to the strftime() function:

          "Today is: {0:a b d H:M:S Y}".format(datetime.now())



-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia
---------------------------------------------------------------
             http://www.boredomandlaziness.org