[Python-checkins] r42722 - python/trunk/Doc/api/concrete.tex python/trunk/Doc/api/utilities.tex

[martin.v.loewis]

Author: martin.v.loewis
Date: Wed Mar  1 06:47:11 2006
New Revision: 42722

Modified:
   python/trunk/Doc/api/concrete.tex
   python/trunk/Doc/api/utilities.tex
Log:
Document new Py_ssize_t API.


Modified: python/trunk/Doc/api/concrete.tex
==============================================================================
--- python/trunk/Doc/api/concrete.tex	(original)
+++ python/trunk/Doc/api/concrete.tex	Wed Mar  1 06:47:11 2006
@@ -162,9 +162,20 @@
   suspect the behaviour of Python in this case is undefined. :-)
 \end{cfuncdesc}
 
+\begin{cfuncdesc}{PyObject*}{PyInt_FromSsize_t}{Py_ssize_t ival}
+  Create a new integer object with a value of \var{ival}.
+  If the value exceeds \code{LONG_MAX}, a long integer object is
+  returned.
+
+ \versionadded{2.5}
+\end{cfuncdesc}
+
 \begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io}
   Will first attempt to cast the object to a \ctype{PyIntObject}, if
-  it is not already one, and then return its value.
+  it is not already one, and then return its value. If there is an
+  error, \code{-1} is returned, and the caller should check
+  \code{PyErr_Occurred()} to find out whether there was an error, or
+  whether the value just happened to be -1.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyObject *io}
@@ -186,6 +197,13 @@
   \versionadded{2.3}
 \end{cfuncdesc}
 
+\begin{cfuncdesc}{Py_ssize_t}{PyInt_AsSsize_t}{PyObject *io}
+  Will first attempt to cast the object to a \ctype{PyIntObject} or
+  \ctype{PyLongObject}, if it is not already one, and then return its
+  value as \ctype{Py_ssize_t}.
+  \versionadded{2.5}
+\end{cfuncdesc}
+
 \begin{cfuncdesc}{long}{PyInt_GetMax}{}
   Return the system's idea of the largest integer it can handle
   (\constant{LONG_MAX}\ttindex{LONG_MAX}, as defined in the system

Modified: python/trunk/Doc/api/utilities.tex
==============================================================================
--- python/trunk/Doc/api/utilities.tex	(original)
+++ python/trunk/Doc/api/utilities.tex	Wed Mar  1 06:47:11 2006
@@ -553,6 +553,10 @@
   platforms that support \ctype{unsigned long long} (or
   \ctype{unsigned _int64} on Windows).  \versionadded{2.3}
 
+  \item[\samp{n} (integer) {[Py_ssize_t]}]
+  Convert a Python integer or long integer to a C \ctype{Py_ssize_t}.
+  \versionadded{2.5}
+
   \item[\samp{c} (string of length 1) {[char]}]
   Convert a Python character, represented as a string of length 1, to
   a C \ctype{char}.
@@ -866,6 +870,10 @@
     Convert a C \ctype{unsigned long long} to a Python long integer object.
     Only available on platforms that support \ctype{unsigned long long}.
 
+    \item[\samp{n} (int) {[Py_ssize_t]}]
+    Convert a C \ctype{Py_ssize_t) to a Python integer or long integer.
+    \versionadded{2.5}
+
     \item[\samp{c} (string of length 1) {[char]}]
     Convert a C \ctype{int} representing a character to a Python
     string of length 1.