From 45b049dced8d846647546759598c9665a1398a92 Mon Sep 17 00:00:00 2001 From: Axel Huebl Date: Fri, 25 Mar 2022 23:58:02 -0700 Subject: DOC: Improve Array Interface `data` The previous guidance on the integer type of `data` was a bit misleading in practice and has now been improved. In practice, Unix is fine with `int` (32bit) and `long` (64bit), but Windows requires `long long` to hold a pointer. https://en.cppreference.com/w/cpp/language/types In order not to complicate the guidance, recommend the `intptr_t` type explicitly. --- doc/source/reference/arrays.interface.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'doc/source/reference/arrays.interface.rst') diff --git a/doc/source/reference/arrays.interface.rst b/doc/source/reference/arrays.interface.rst index e10710719..2f843d2af 100644 --- a/doc/source/reference/arrays.interface.rst +++ b/doc/source/reference/arrays.interface.rst @@ -125,8 +125,10 @@ This approach to the interface consists of the object having an **Default**: ``[('', typestr)]`` **data** (optional) - A 2-tuple whose first argument is an integer (a long integer - if necessary) that points to the data-area storing the array + A 2-tuple whose first argument is a signed integer (capable of + holding a pointer to ``void`` such as the C/C++ type + `intptr_t `__) + that points to the data-area storing the array contents. This pointer must point to the first element of data (in other words any offset is always ignored in this case). The second entry in the tuple is a read-only flag (true -- cgit v1.2.1 From 14092a017a1703610916bb6af7107b6eddcf31f6 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Fri, 8 Jul 2022 13:50:08 +0300 Subject: DOC: Apply final wording suggestion. Co-authored-by: Axel Huebl . --- doc/source/reference/arrays.interface.rst | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) (limited to 'doc/source/reference/arrays.interface.rst') diff --git a/doc/source/reference/arrays.interface.rst b/doc/source/reference/arrays.interface.rst index 2f843d2af..904d0132b 100644 --- a/doc/source/reference/arrays.interface.rst +++ b/doc/source/reference/arrays.interface.rst @@ -125,11 +125,15 @@ This approach to the interface consists of the object having an **Default**: ``[('', typestr)]`` **data** (optional) - A 2-tuple whose first argument is a signed integer (capable of - holding a pointer to ``void`` such as the C/C++ type - `intptr_t `__) - that points to the data-area storing the array - contents. This pointer must point to the first element of + A 2-tuple whose first argument is a :doc:`Python integer ` + that points to the data-area storing the array contents. + + .. note:: + When converting from C/C++ via ``PyLong_From*`` or high-level + bindings such as Cython or pybind11, make sure to use an integer + of sufficiently large bitness. + + This pointer must point to the first element of data (in other words any offset is always ignored in this case). The second entry in the tuple is a read-only flag (true means the data area is read-only). -- cgit v1.2.1