summaryrefslogtreecommitdiffstats
path: root/Doc/api
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/api')
-rw-r--r--Doc/api/concrete.tex49
1 files changed, 49 insertions, 0 deletions
diff --git a/Doc/api/concrete.tex b/Doc/api/concrete.tex
index e0664b5..d60dcff 100644
--- a/Doc/api/concrete.tex
+++ b/Doc/api/concrete.tex
@@ -1006,6 +1006,55 @@ use these APIs:
when \var{u} is \NULL{}.
\end{cfuncdesc}
+\begin{cfuncdesc}{PyObject*}{PyUnicode_FromFormat}{const char *format, ...}
+ Take a C \cfunction{printf()}-style \var{format} string and a
+ variable number of arguments, calculate the size of the resulting
+ Python unicode string and return a string with the values formatted into
+ it. The variable arguments must be C types and must correspond
+ exactly to the format characters in the \var{format} string. The
+ following format characters are allowed:
+
+ % 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}{size_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.}
+ \lineiii{\%U}{PyObject*}{A unicode object.}
+ \lineiii{\%V}{PyObject*, char *}{A unicode object (which may be \NULL{})
+ and a null-terminated C character array as a second parameter (which
+ will be used, if the first parameter is \NULL{}).}
+ \lineiii{\%S}{PyObject*}{The result of calling \function{PyObject_Unicode()}.}
+ \lineiii{\%R}{PyObject*}{The result of calling \function{PyObject_Repr()}.}
+ \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
+ arguments discarded.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_FromFormatV}{const char *format,
+ va_list vargs}
+ Identical to \function{PyUnicode_FromFormat()} except that it takes
+ exactly two arguments.
+\end{cfuncdesc}
+
\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AsUnicode}{PyObject *unicode}
Return a read-only pointer to the Unicode object's internal
\ctype{Py_UNICODE} buffer, \NULL{} if \var{unicode} is not a Unicode