Merged revisions 78440 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r78440 | eric.smith | 2010-02-25 09:14:35 -0500 (Thu, 25 Feb 2010) | 1 line

  Issue #5965: Add documentation for parts of format specification language.
........

diff --git a/Doc/library/string.rst b/Doc/library/string.rst
index 5e6aa92c1d451bae5954718ec0ae4f7d7a2ef196..68f78ff9bd332ea3ad3c8e101a521ae3302ea6fb 100644 (file)
--- a/Doc/library/string.rst
+++ b/Doc/library/string.rst
@@ -312,8 +312,9 @@ specification is to be interpreted.
 Most built-in types implement the following options for format specifications,
 although some of the formatting options are only supported by the numeric types.
 
-A general convention is that an empty format string (``""``) produces the same
-result as if you had called :func:`str` on the value.
+A general convention is that an empty format string (``""``) produces
+the same result as if you had called :func:`str` on the value. A
+non-empty format string typically modifies the result.
 
 The general form of a *standard format specifier* is:
 
@@ -324,7 +325,7 @@ The general form of a *standard format specifier* is:
    sign: "+" | "-" | " "
    width: `integer`
    precision: `integer`
-   type: "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "x" | "X" | "%"
+   type: "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"
 
 The *fill* character can be any character other than '}' (which signifies the
 end of the field).  The presence of a fill character is signaled by the *next*
@@ -392,6 +393,17 @@ used from the field content. The *precision* is not allowed for integer values.
 
 Finally, the *type* determines how the data should be presented.
 
+The available string presentation types are:
+
+   +---------+----------------------------------------------------------+
+   | Type    | Meaning                                                  |
+   +=========+==========================================================+
+   | ``'s'`` | String format. This is the default type for strings and  |
+   |         | may be omitted.                                          |
+   +---------+----------------------------------------------------------+
+   | None    | The same as ``'s'``.                                     |
+   +---------+----------------------------------------------------------+
+
 The available integer presentation types are:
 
    +---------+----------------------------------------------------------+
@@ -419,6 +431,11 @@ The available integer presentation types are:
    | None    | The same as ``'d'``.                                     |
    +---------+----------------------------------------------------------+
 
+In addition to the above presentation types, integers can be formatted
+with the floating point presentation types listed below (except
+``'n'`` and None). When doing so, :func:`float` is used to convert the
+integer to a floating point number before formatting.
+
 The available presentation types for floating point and decimal values are:
 
    +---------+----------------------------------------------------------+