From 3b1975407945f2f1f2d90e3611417da91808b420 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Martin=20v=2E=20L=C3=B6wis?= <martin@v.loewis.de>
Date: Wed, 1 Mar 2006 05:47:11 +0000
Subject: [PATCH] Document new Py_ssize_t API.

---
 Doc/api/concrete.tex  | 20 +++++++++++++++++++-
 Doc/api/utilities.tex |  8 ++++++++
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/Doc/api/concrete.tex b/Doc/api/concrete.tex
index fd02ecdbae..5521b80ba9 100644
--- a/Doc/api/concrete.tex
+++ b/Doc/api/concrete.tex
@@ -162,9 +162,20 @@ There is no \cfunction{PyNone_Check()} function for the same reason.
   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 @@ There is no \cfunction{PyNone_Check()} function for the same reason.
   \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
diff --git a/Doc/api/utilities.tex b/Doc/api/utilities.tex
index 094cbf307c..5aecbc39b2 100644
--- a/Doc/api/utilities.tex
+++ b/Doc/api/utilities.tex
@@ -553,6 +553,10 @@ whose address should be passed.
   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 @@ PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
     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.
-- 
2.40.0