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).
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 @@
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 @@
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 @@
\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.