[Python-checkins] CVS: python/dist/src/Doc/api api.tex,1.147,1.148 refcounts.dat,1.30,1.31
Fred L. Drake
fdrake@users.sourceforge.net
Thu, 20 Sep 2001 12:18:54 -0700
Update of /cvsroot/python/python/dist/src/Doc/api
In directory usw-pr-cvs1:/tmp/cvs-serv5089
Modified Files:
api.tex refcounts.dat
Log Message:
Document all the Py*_CheckExact() functions.
Document many more of the PyLong_{As,From}*() functions.
Index: api.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/api.tex,v
retrieving revision 1.147
retrieving revision 1.148
diff -C2 -d -r1.147 -r1.148
*** api.tex 2001/09/06 17:12:44 1.147
--- api.tex 2001/09/20 19:18:52 1.148
***************
*** 1681,1690 ****
\begin{cfuncdesc}{PyObject*}{PyObject_Type}{PyObject *o}
! On success, returns a type object corresponding to the object
! type of object \var{o}. On failure, returns \NULL{}. This is
! equivalent to the Python expression \samp{type(\var{o})}.
\bifuncindex{type}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o}
Return the length of object \var{o}. If the object \var{o} provides
--- 1681,1696 ----
\begin{cfuncdesc}{PyObject*}{PyObject_Type}{PyObject *o}
! When \var{o} is non-\NULL, returns a type object corresponding to the
! object type of object \var{o}. On failure, raises
! \exception{SystemError} and returns \NULL. This is equivalent to the
! Python expression \code{type(\var{o})}.
\bifuncindex{type}
\end{cfuncdesc}
+ \begin{cfuncdesc}{int}{PyObject_TypeCheck}{PyObject *o, PyTypeObject *type}
+ Return true if the object \var{o} is of type \var{type} or a subtype
+ of \var{type}. Both parameters must be non-\NULL.
+ \end{cfuncdesc}
+
\begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o}
Return the length of object \var{o}. If the object \var{o} provides
***************
*** 2366,2370 ****
\begin{cfuncdesc}{int}{PyInt_Check}{PyObject* o}
! Returns true if \var{o} is of type \cdata{PyInt_Type}.
\end{cfuncdesc}
--- 2372,2384 ----
\begin{cfuncdesc}{int}{PyInt_Check}{PyObject* o}
! Returns true if \var{o} is of type \cdata{PyInt_Type} or a subtype of
! \cdata{PyInt_Type}.
! \versionchanged[Allowed subtypes to be accepted]{2.2}
! \end{cfuncdesc}
!
! \begin{cfuncdesc}{int}{PyInt_CheckExact}{PyObject* o}
! Returns true if \var{o} is of type \cdata{PyInt_Type}, but not a
! subtype of \cdata{PyInt_Type}.
! \versionadded{2.2}
\end{cfuncdesc}
***************
*** 2411,2415 ****
\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
! Returns true if its argument is a \ctype{PyLongObject}.
\end{cfuncdesc}
--- 2425,2437 ----
\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
! Returns true if its argument is a \ctype{PyLongObject} or a subtype of
! \ctype{PyLongObject}.
! \versionchanged[Allowed subtypes to be accepted]{2.2}
! \end{cfuncdesc}
!
! \begin{cfuncdesc}{int}{PyLong_CheckExact}{PyObject *p}
! Returns true if its argument is a \ctype{PyLongObject}, but not a
! subtype of \ctype{PyLongObject}.
! \versionadded{2.2}
\end{cfuncdesc}
***************
*** 2424,2427 ****
--- 2446,2459 ----
\end{cfuncdesc}
+ \begin{cfuncdesc}{PyObject*}{PyLong_FromLongLong}{long long v}
+ Returns a new \ctype{PyLongObject} object from a C \ctype{long long},
+ or \NULL{} on failure.
+ \end{cfuncdesc}
+
+ \begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLongLong}{unsigned long long v}
+ Returns a new \ctype{PyLongObject} object from a C \ctype{unsigned
+ long long}, or \NULL{} on failure.
+ \end{cfuncdesc}
+
\begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v}
Returns a new \ctype{PyLongObject} object from the integer part of
***************
*** 2429,2432 ****
--- 2461,2497 ----
\end{cfuncdesc}
+ \begin{cfuncdesc}{PyObject*}{PyLong_FromString}{char *str, char **pend,
+ int base}
+ Return a new \ctype{PyLongObject} based on the string value in
+ \var{str}, which is interpreted according to the radix in \var{base}.
+ If \var{pend} is non-\NULL, \code{*\var{pend}} will point to the first
+ character in \var{str} which follows the representation of the
+ number. If \var{base} is \code{0}, the radix will be determined base
+ on the leading characters of \var{str}: if \var{str} starts with
+ \code{'0x'} or \code{'0X'}, radix 16 will be used; if \var{str} starts
+ with \code{'0'}, radix 8 will be used; otherwise radix 10 will be
+ used. If \var{base} is not \code{0}, it must be between \code{2} and
+ \code{36}, inclusive. Leading spaces are ignored. If there are no
+ digits, \exception{ValueError} will be raised.
+ \end{cfuncdesc}
+
+ \begin{cfuncdesc}{PyObject*}{PyLong_FromUnicode}{Py_UNICODE *u,
+ int length, int base}
+ Convert a sequence of Unicode digits to a Python long integer value.
+ The first parameter, \var{u}, points to the first character of the
+ Unicode string, \var{length} gives the number of characters, and
+ \var{base} is the radix for the conversion. The radix must be in the
+ range [2, 36]; if it is out of range, \exception{ValueError} will be
+ raised.
+ \versionadded{1.6}
+ \end{cfuncdesc}
+
+ \begin{cfuncdesc}{PyObject*}{PyLong_FromVoidPtr}{void *p}
+ Create a Python integer or long integer from the pointer \var{p}. The
+ pointer value can be retrieved from the resulting value using
+ \cfunction{PyLong_AsVoidPtr()}.
+ \versionadded{1.5.2}
+ \end{cfuncdesc}
+
\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong}
Returns a C \ctype{long} representation of the contents of
***************
*** 2443,2463 ****
\end{cfuncdesc}
\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong}
! Returns a C \ctype{double} representation of the contents of \var{pylong}.
\end{cfuncdesc}
! \begin{cfuncdesc}{PyObject*}{PyLong_FromString}{char *str, char **pend,
! int base}
! Return a new \ctype{PyLongObject} based on the string value in
! \var{str}, which is interpreted according to the radix in \var{base}.
! If \var{pend} is non-\NULL, \code{*\var{pend}} will point to the first
! character in \var{str} which follows the representation of the
! number. If \var{base} is \code{0}, the radix will be determined base
! on the leading characters of \var{str}: if \var{str} starts with
! \code{'0x'} or \code{'0X'}, radix 16 will be used; if \var{str} starts
! with \code{'0'}, radix 8 will be used; otherwise radix 10 will be
! used. If \var{base} is not \code{0}, it must be between \code{2} and
! \code{36}, inclusive. Leading spaces are ignored. If there are no
! digits, \exception{ValueError} will be raised.
\end{cfuncdesc}
--- 2508,2541 ----
\end{cfuncdesc}
+ \begin{cfuncdesc}{long long}{PyLong_AsLongLong}{PyObject *pylong}
+ Return a C \ctype{long long} from a Python long integer. If
+ \var{pylong} cannot be represented as a \ctype{long long}, an
+ \exception{OverflowError} will be raised.
+ \versionadded{2.2}
+ \end{cfuncdesc}
+
+ \begin{cfuncdesc}{unsigned long long}{PyLong_AsUnsignedLongLong}{PyObject
+ *pylong}
+ Return a C \ctype{unsigned long long} from a Python long integer. If
+ \var{pylong} cannot be represented as an \ctype{unsigned long long},
+ an \exception{OverflowError} will be raised if the value is positive,
+ or a \exception{TypeError} will be raised if the value is negative.
+ \versionadded{2.2}
+ \end{cfuncdesc}
+
\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong}
! Returns a C \ctype{double} representation of the contents of
! \var{pylong}. If \var{pylong} cannot be approximately represented as
! a \ctype{double}, an \exception{OverflowError} exception is raised and
! \code{-1.0} will be returned.
\end{cfuncdesc}
! \begin{cfuncdesc}{void*}{PyLong_AsVoidPtr}{PyObject *pylong}
! Convert a Python integer or long integer \var{pylong} to a C
! \ctype{void} pointer. If \var{pylong} cannot be converted, an
! \exception{OverflowError} will be raised. This is only assured to
! produce a usable \ctype{void} pointer for values created with
! \cfunction{PyLong_FromVoidPtr()}.
! \versionadded{1.5.2}
\end{cfuncdesc}
***************
*** 2478,2482 ****
\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
! Returns true if its argument is a \ctype{PyFloatObject}.
\end{cfuncdesc}
--- 2556,2568 ----
\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
! Returns true if its argument is a \ctype{PyFloatObject} or a subtype
! of \ctype{PyFloatObject}.
! \versionchanged[Allowed subtypes to be accepted]{2.2}
! \end{cfuncdesc}
!
! \begin{cfuncdesc}{int}{PyFloat_CheckExact}{PyObject *p}
! Returns true if its argument is a \ctype{PyFloatObject}, but not a
! subtype of \ctype{PyFloatObject}.
! \versionadded{2.2}
\end{cfuncdesc}
***************
*** 2570,2576 ****
\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
! Returns true if its argument is a \ctype{PyComplexObject}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyComplex_FromCComplex}{Py_complex v}
Create a new Python complex number object from a C
--- 2656,2670 ----
\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
! Returns true if its argument is a \ctype{PyComplexObject} or a subtype
! of \ctype{PyComplexObject}.
! \versionchanged[Allowed subtypes to be accepted]{2.2}
\end{cfuncdesc}
+ \begin{cfuncdesc}{int}{PyComplex_CheckExact}{PyObject *p}
+ Returns true if its argument is a \ctype{PyComplexObject}, but not a
+ subtype of \ctype{PyComplexObject}.
+ \versionadded{2.2}
+ \end{cfuncdesc}
+
\begin{cfuncdesc}{PyObject*}{PyComplex_FromCComplex}{Py_complex v}
Create a new Python complex number object from a C
***************
*** 2621,2627 ****
\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
! Returns true if the object \var{o} is a string object.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyString_FromString}{const char *v}
Returns a new string object with the value \var{v} on success, and
--- 2715,2729 ----
\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
! Returns true if the object \var{o} is a string object or an instance
! of a subtype of the string type.
! \versionchanged[Allowed subtypes to be accepted]{2.2}
\end{cfuncdesc}
+ \begin{cfuncdesc}{int}{PyString_CheckExact}{PyObject *o}
+ Returns true if the object \var{o} is a string object, but not an
+ instance of a subtype of the string type.
+ \versionadded{2.2}
+ \end{cfuncdesc}
+
\begin{cfuncdesc}{PyObject*}{PyString_FromString}{const char *v}
Returns a new string object with the value \var{v} on success, and
***************
*** 2836,2842 ****
\begin{cfuncdesc}{int}{PyUnicode_Check}{PyObject *o}
! Returns true if the object \var{o} is a Unicode object.
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyUnicode_GET_SIZE}{PyObject *o}
Returns the size of the object. o has to be a
--- 2938,2952 ----
\begin{cfuncdesc}{int}{PyUnicode_Check}{PyObject *o}
! Returns true if the object \var{o} is a Unicode object or an instance
! of a Unicode subtype.
! \versionchanged[Allowed subtypes to be accepted]{2.2}
\end{cfuncdesc}
+ \begin{cfuncdesc}{int}{PyUnicode_CheckExact}{PyObject *o}
+ Returns true if the object \var{o} is a Unicode object, but not an
+ instance of a subtype.
+ \versionadded{2.2}
+ \end{cfuncdesc}
+
\begin{cfuncdesc}{int}{PyUnicode_GET_SIZE}{PyObject *o}
Returns the size of the object. o has to be a
***************
*** 3624,3628 ****
\begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
! Return true if the argument is a tuple object.
\end{cfuncdesc}
--- 3734,3746 ----
\begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
! Return true if \var{p} is a tuple object or an instance of a subtype
! of the tuple type.
! \versionchanged[Allowed subtypes to be accepted]{2.2}
! \end{cfuncdesc}
!
! \begin{cfuncdesc}{int}{PyTuple_CheckExact}{PyObject *p}
! Return true if \var{p} is a tuple object, but not an instance of
! a subtype of the tuple type.
! \versionadded{2.2}
\end{cfuncdesc}
***************
*** 3984,3990 ****
\begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p}
! Returns true if its argument is a \ctype{PyFileObject}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyFile_FromString}{char *filename, char *mode}
On success, returns a new file object that is opened on the
--- 4102,4116 ----
\begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p}
! Returns true if its argument is a \ctype{PyFileObject} or a subtype of
! \ctype{PyFileObject}.
! \versionchanged[Allowed subtypes to be accepted]{2.2}
\end{cfuncdesc}
+ \begin{cfuncdesc}{int}{PyFile_CheckExact}{PyObject *p}
+ Returns true if its argument is a \ctype{PyFileObject}, but not a
+ subtype of \ctype{PyFileObject}.
+ \versionadded{2.2}
+ \end{cfuncdesc}
+
\begin{cfuncdesc}{PyObject*}{PyFile_FromString}{char *filename, char *mode}
On success, returns a new file object that is opened on the
***************
*** 4160,4164 ****
\begin{cfuncdesc}{int}{PyModule_Check}{PyObject *p}
! Returns true if its argument is a module object.
\end{cfuncdesc}
--- 4286,4298 ----
\begin{cfuncdesc}{int}{PyModule_Check}{PyObject *p}
! Returns true if \var{p} is a module object, or a subtype of a
! module object.
! \versionchanged[Allowed subtypes to be accepted]{2.2}
! \end{cfuncdesc}
!
! \begin{cfuncdesc}{int}{PyModule_CheckExact}{PyObject *p}
! Returns true if \var{p} is a module object, but not a subtype of
! \cdata{PyModule_Type}.
! \versionadded{2.2}
\end{cfuncdesc}
Index: refcounts.dat
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/refcounts.dat,v
retrieving revision 1.30
retrieving revision 1.31
diff -C2 -d -r1.30 -r1.31
*** refcounts.dat 2001/09/06 18:06:46 1.30
--- refcounts.dat 2001/09/20 19:18:52 1.31
***************
*** 450,453 ****
--- 450,459 ----
PyLong_FromLong:long:v::
+ PyLong_FromLongLong:PyObject*::+1:
+ PyLong_FromLongLong:long long:v::
+
+ PyLong_FromUnsignedLongLong:PyObject*::+1:
+ PyLong_FromUnsignedLongLong:unsigned long long:v::
+
PyLong_FromString:PyObject*::+1:
PyLong_FromString:char*:str::
***************
*** 455,460 ****
--- 461,474 ----
PyLong_FromString:int:base::
+ PyLong_FromUnicode:PyObject*::+1:
+ PyLong_FromUnicode:Py_UNICODE:u::
+ PyLong_FromUnicode:int:length::
+ PyLong_FromUnicode:int:base::
+
PyLong_FromUnsignedLong:PyObject*::+1:
PyLong_FromUnsignedLong:unsignedlong:v::
+
+ PyLong_FromVoidPtr:PyObject*::+1:
+ PyLong_FromVoidPtr:void*:p::
PyMapping_Check:int:::