Patch #1684834: document some utility C API functions.

 (backport from rev. 54483)

1 files changed, 91 insertions, 0 deletions

diff --git a/Doc/api/utilities.tex b/Doc/api/utilities.tex
index 5a6f0b0..93e3796 100644
--- a/Doc/api/utilities.tex
+++ b/Doc/api/utilities.tex
@@ -930,3 +930,94 @@ PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
   If there is an error in the format string, the
   \exception{SystemError} exception is set and \NULL{} returned.
 \end{cfuncdesc}
+
+\section{String conversion and formatting \label{string-formatting}}
+
+Functions for number conversion and formatted string output.
+
+\begin{cfuncdesc}{int}{PyOS_snprintf}{char *str, size_t size, 
+                                      const char *format, \moreargs}
+Output not more than \var{size} bytes to \var{str} according to the format
+string \var{format} and the extra arguments. See the \UNIX{} man
+page \manpage{snprintf}{2}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyOS_vsnprintf}{char *str, size_t size,
+                                       const char *format, va_list va}
+Output not more than \var{size} bytes to \var{str} according to the format
+string \var{format} and the variable argument list \var{va}. \UNIX{}
+man page \manpage{vsnprintf}{2}.
+\end{cfuncdesc}
+
+\cfunction{PyOS_snprintf} and \cfunction{PyOS_vsnprintf} wrap the
+Standard C library functions \cfunction{snprintf()} and
+\cfunction{vsnprintf()}. Their purpose is to guarantee consistent
+behavior in corner cases, which the Standard C functions do not.
+
+The wrappers ensure that \var{str}[\var{size}-1] is always
+\character{\textbackslash0} upon return. They never write more than
+\var{size} bytes (including the trailing \character{\textbackslash0}
+into str. Both functions require that \code{\var{str} != NULL},
+\code{\var{size} > 0} and \code{\var{format} != NULL}.
+
+If the platform doesn't have \cfunction{vsnprintf()} and the buffer
+size needed to avoid truncation exceeds \var{size} by more than 512
+bytes, Python aborts with a \var{Py_FatalError}.
+
+The return value (\var{rv}) for these functions should be interpreted
+as follows:
+
+\begin{itemize}
+
+\item When \code{0 <= \var{rv} < \var{size}}, the output conversion
+  was successful and \var{rv} characters were written to \var{str}
+  (excluding the trailing \character{\textbackslash0} byte at
+  \var{str}[\var{rv}]).
+
+\item When \code{\var{rv} >= \var{size}}, the output conversion was
+  truncated and a buffer with \code{\var{rv} + 1} bytes would have
+  been needed to succeed. \var{str}[\var{size}-1] is
+  \character{\textbackslash0} in this case.
+
+\item When \code{\var{rv} < 0}, ``something bad happened.''
+  \var{str}[\var{size}-1] is \character{\textbackslash0} in this case
+  too, but the rest of \var{str} is undefined. The exact cause of the
+  error depends on the underlying platform.
+
+\end{itemize}
+
+The following functions provide locale-independent string to number
+conversions.
+
+\begin{cfuncdesc}{double}{PyOS_ascii_strtod}{const char *nptr, char **endptr}
+Convert a string to a \ctype{double}. This function behaves like the
+Standard C function \cfunction{strtod()} does in the C locale. It does
+this without changing the current locale, since that would not be
+thread-safe.
+
+\cfunction{PyOS_ascii_strtod} should typically be used for reading
+configuration files or other non-user input that should be locale
+independent. \versionadded{2.4}
+
+See the \UNIX{} man page \manpage{strtod}{2} for details.
+
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char *}{PyOS_ascii_formatd}{char *buffer, size_t buf_len,
+                                              const char *format, double d}
+Convert a \ctype{double} to a string using the \character{.} as the
+decimal separator. \var{format} is a \cfunction{printf()}-style format
+string specifying the number format. Allowed conversion characters are
+\character{e}, \character{E}, \character{f}, \character{F},
+\character{g} and \character{G}.
+
+The return value is a pointer to \var{buffer} with the converted
+string or NULL if the conversion failed. \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{double}{PyOS_ascii_atof}{const char *nptr}
+Convert a string to a \ctype{double} in a locale-independent
+way. \versionadded{2.4}
+
+See the \UNIX{} man page \manpage{atof}{2} for details.
+\end{cfuncdesc}