[3.13] gh-141004: Document `Py_ARRAY_LENGTH` (GH-141601) (GH-141896)

gh-141004: Document `Py_ARRAY_LENGTH` (GH-141601)
(cherry picked from commit e0773eacb7e660b4fd6bd702b0a119e25ab3b012)

Co-authored-by: Yashraj <yashrajpala8@gmail.com>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 68ba515b40ce122adeee7ad7835f00f0fbc704fd..6596250afef06ceea39541067612b89c3847da8e 100644 (file)
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -326,6 +326,19 @@ complete listing.
       PyDoc_VAR(python_doc) = PyDoc_STR("A genus of constricting snakes in the Pythonidae family native "
                                         "to the tropics and subtropics of the Eastern Hemisphere.");
 
+.. c:macro:: Py_ARRAY_LENGTH(array)
+
+   Compute the length of a statically allocated C array at compile time.
+
+   The *array* argument must be a C array with a size known at compile time.
+   Passing an array with an unknown size, such as a heap-allocated array,
+   will result in a compilation error on some compilers, or otherwise produce
+   incorrect results.
+
+   This is roughly equivalent to::
+
+      sizeof(array) / sizeof((array)[0])
+
 
 .. _api-objects: