Teach PyString_FromFormat, PyErr_Format, and PyString_FromFormatV

about "%u", "%lu" and "%zu" formats.

Since PyString_FromFormat and PyErr_Format have exactly the same rules
(both inherited from PyString_FromFormatV), it would be good if someone
with more LaTeX Fu changed one of them to just point to the other.
Their docs were way out of synch before this patch, and I just did a
mass copy+paste to repair that.

Not a backport candidate (this is a new feature).

1 files changed, 29 insertions, 10 deletions

diff --git a/Doc/api/exceptions.tex b/Doc/api/exceptions.tex
index c4727f2..7942812 100644
--- a/Doc/api/exceptions.tex
+++ b/Doc/api/exceptions.tex
@@ -135,13 +135,32 @@ for each thread.
   codes, similar to \cfunction{printf()}. The \code{width.precision}
   before a format code is parsed, but the width part is ignored.
 
-  \begin{tableii}{c|l}{character}{Character}{Meaning}
-    \lineii{c}{Character, as an \ctype{int} parameter}
-    \lineii{d}{Number in decimal, as an \ctype{int} parameter}
-    \lineii{x}{Number in hexadecimal, as an \ctype{int} parameter}
-    \lineii{s}{A string, as a \ctype{char *} parameter}
-    \lineii{p}{A hex pointer, as a \ctype{void *} parameter}
-  \end{tableii}
+  % This should be exactly the same as the table in PyString_FromFormat.
+  % One should just refer to the other.
+
+  % The descriptions for %zd and %zu are wrong, but the truth is complicated
+  % because not all compilers support the %z width modifier -- we fake it
+  % when necessary via interpolating PY_FORMAT_SIZE_T.
+
+  % %u, %lu, %zu should have "new in Python 2.5" blurbs.
+
+  \begin{tableiii}{l|l|l}{member}{Format Characters}{Type}{Comment}
+    \lineiii{\%\%}{\emph{n/a}}{The literal \% character.}
+    \lineiii{\%c}{int}{A single character, represented as an C int.}
+    \lineiii{\%d}{int}{Exactly equivalent to \code{printf("\%d")}.}
+    \lineiii{\%u}{unsigned int}{Exactly equivalent to \code{printf("\%u")}.}
+    \lineiii{\%ld}{long}{Exactly equivalent to \code{printf("\%ld")}.}
+    \lineiii{\%lu}{unsigned long}{Exactly equivalent to \code{printf("\%lu")}.}
+    \lineiii{\%zd}{Py_ssize_t}{Exactly equivalent to \code{printf("\%zd")}.}
+    \lineiii{\%zu}{ssize_t}{Exactly equivalent to \code{printf("\%zu")}.}
+    \lineiii{\%i}{int}{Exactly equivalent to \code{printf("\%i")}.}
+    \lineiii{\%x}{int}{Exactly equivalent to \code{printf("\%x")}.}
+    \lineiii{\%s}{char*}{A null-terminated C character array.}
+    \lineiii{\%p}{void*}{The hex representation of a C pointer.
+	Mostly equivalent to \code{printf("\%p")} except that it is
+	guaranteed to start with the literal \code{0x} regardless of
+	what the platform's \code{printf} yields.}
+  \end{tableiii}
 
   An unrecognized format character causes all the rest of the format
   string to be copied as-is to the result string, and any extra
@@ -275,8 +294,8 @@ for each thread.
   command line documentation.  There is no C API for warning control.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject *category, 
-                const char *message, const char *filename, int lineno, 
+\begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject *category,
+                const char *message, const char *filename, int lineno,
                 const char *module, PyObject *registry}
   Issue a warning message with explicit control over all warning
   attributes.  This is a straightforward wrapper around the Python
@@ -402,5 +421,5 @@ are derived from \exception{BaseException}.
 \withsubitem{(built-in exception)}{\ttindex{BaseException}}
 
 String exceptions are still supported in the interpreter to allow
-existing code to run unmodified, but this will also change in a future 
+existing code to run unmodified, but this will also change in a future
 release.