diff options
Diffstat (limited to 'Doc/api')
| -rw-r--r-- | Doc/api/abstract.tex | 6 | ||||
| -rw-r--r-- | Doc/api/concrete.tex | 40 | ||||
| -rw-r--r-- | Doc/api/init.tex | 2 | ||||
| -rw-r--r-- | Doc/api/memory.tex | 7 | ||||
| -rw-r--r-- | Doc/api/newtypes.tex | 2 | ||||
| -rw-r--r-- | Doc/api/utilities.tex | 91 |
6 files changed, 138 insertions, 10 deletions
diff --git a/Doc/api/abstract.tex b/Doc/api/abstract.tex index f292972..c5b53d7 100644 --- a/Doc/api/abstract.tex +++ b/Doc/api/abstract.tex @@ -790,7 +790,7 @@ determination. the Python statement \samp{del \var{o}[\var{i1}:\var{i2}]}. \end{cfuncdesc} -\begin{cfuncdesc}{int}{PySequence_Count}{PyObject *o, PyObject *value} +\begin{cfuncdesc}{Py_ssize_t}{PySequence_Count}{PyObject *o, PyObject *value} Return the number of occurrences of \var{value} in \var{o}, that is, return the number of keys for which \code{\var{o}[\var{key}] == \var{value}}. On failure, return \code{-1}. This is equivalent to @@ -804,7 +804,7 @@ determination. expression \samp{\var{value} in \var{o}}. \end{cfuncdesc} -\begin{cfuncdesc}{int}{PySequence_Index}{PyObject *o, PyObject *value} +\begin{cfuncdesc}{Py_ssize_t}{PySequence_Index}{PyObject *o, PyObject *value} Return the first index \var{i} for which \code{\var{o}[\var{i}] == \var{value}}. On error, return \code{-1}. This is equivalent to the Python expression \samp{\var{o}.index(\var{value})}. @@ -854,7 +854,7 @@ determination. \versionadded{2.3} \end{cfuncdesc} -\begin{cfuncdesc}{int}{PySequence_Fast_GET_SIZE}{PyObject *o} +\begin{cfuncdesc}{Py_ssize_t}{PySequence_Fast_GET_SIZE}{PyObject *o} Returns the length of \var{o}, assuming that \var{o} was returned by \cfunction{PySequence_Fast()} and that \var{o} is not \NULL. The size can also be gotten by calling diff --git a/Doc/api/concrete.tex b/Doc/api/concrete.tex index 630a726..cdf6856 100644 --- a/Doc/api/concrete.tex +++ b/Doc/api/concrete.tex @@ -442,7 +442,9 @@ booleans. The following macros are available, however. \begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *pyfloat} Return a C \ctype{double} representation of the contents of - \var{pyfloat}. + \var{pyfloat}. If \var{pyfloat} is not a Python floating point + object but has a \method{__float__} method, this method will first + be called to convert \var{pyfloat} into a float. \end{cfuncdesc} \begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyObject *pyfloat} @@ -557,8 +559,11 @@ typedef struct { \end{cfuncdesc} \begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op} - Return the \ctype{Py_complex} value of the complex number - \var{op}. + Return the \ctype{Py_complex} value of the complex number \var{op}. + \versionchanged[If \var{op} is not a Python complex number object + but has a \method{__complex__} method, this method + will first be called to convert \var{op} to a Python + complex number object]{2.6} \end{cfuncdesc} @@ -2156,6 +2161,35 @@ def PyDict_MergeFromSeq2(a, seq2, override): \section{Other Objects \label{otherObjects}} +\subsection{Class Objects \label{classObjects}} + +\obindex{class} +Note that the class objects described here represent old-style classes, +which will go away in Python 3. When creating new types for extension +modules, you will want to work with type objects (section +\ref{typeObjects}). + +\begin{ctypedesc}{PyClassObject} + The C structure of the objects used to describe built-in classes. +\end{ctypedesc} + +\begin{cvardesc}{PyObject*}{PyClass_Type} + This is the type object for class objects; it is the same object as + \code{types.ClassType} in the Python layer. + \withsubitem{(in module types)}{\ttindex{ClassType}} +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyClass_Check}{PyObject *o} + Return true if the object \var{o} is a class object, including + instances of types derived from the standard class object. Return + false in all other cases. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyClass_IsSubclass}{PyObject *klass, PyObject *base} + Return true if \var{klass} is a subclass of \var{base}. Return false in + all other cases. +\end{cfuncdesc} + \subsection{File Objects \label{fileObjects}} \obindex{file} diff --git a/Doc/api/init.tex b/Doc/api/init.tex index e380bdb..76fcf61 100644 --- a/Doc/api/init.tex +++ b/Doc/api/init.tex @@ -245,7 +245,7 @@ program name (set by \cfunction{Py_SetProgramName()} above) and some environment variables. The returned string consists of a series of directory names separated by a platform dependent delimiter - character. The delimiter character is \character{:} on \UNIX and Mac OS X, + character. The delimiter character is \character{:} on \UNIX{} and Mac OS X, \character{;} on Windows. The returned string points into static storage; the caller should not modify its value. The value is available to Python code as the list diff --git a/Doc/api/memory.tex b/Doc/api/memory.tex index 4bc2c7a..18abe98 100644 --- a/Doc/api/memory.tex +++ b/Doc/api/memory.tex @@ -100,7 +100,9 @@ are available for allocating and releasing memory from the Python heap: memory block is resized but is not freed, and the returned pointer is non-\NULL. Unless \var{p} is \NULL, it must have been returned by a previous call to \cfunction{PyMem_Malloc()} or - \cfunction{PyMem_Realloc()}. + \cfunction{PyMem_Realloc()}. If the request fails, + \cfunction{PyMem_Realloc()} returns \NULL{} and \var{p} remains a + valid pointer to the previous memory area. \end{cfuncdesc} \begin{cfuncdesc}{void}{PyMem_Free}{void *p} @@ -124,7 +126,8 @@ that \var{TYPE} refers to any C type. \begin{cfuncdesc}{\var{TYPE}*}{PyMem_Resize}{void *p, TYPE, size_t n} Same as \cfunction{PyMem_Realloc()}, but the memory block is resized to \code{(\var{n} * sizeof(\var{TYPE}))} bytes. Returns a pointer - cast to \ctype{\var{TYPE}*}. + cast to \ctype{\var{TYPE}*}. On return, \var{p} will be a pointer to + the new memory area, or \NULL{} in the event of failure. \end{cfuncdesc} \begin{cfuncdesc}{void}{PyMem_Del}{void *p} diff --git a/Doc/api/newtypes.tex b/Doc/api/newtypes.tex index af1aed3..77ad7a5 100644 --- a/Doc/api/newtypes.tex +++ b/Doc/api/newtypes.tex @@ -1316,7 +1316,7 @@ PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems) This field is inherited by static subtypes, but not by dynamic subtypes (subtypes created by a class statement); in the latter, - this field is always set to \cfunction{PyType_GenericAlloc()}, to + this field is always set to \cfunction{PyType_GenericAlloc}, to force a standard heap allocation strategy. That is also the recommended value for statically defined types. \end{cmemberdesc} 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} |