diff options
Diffstat (limited to 'doc/source/reference/c-api')
| -rw-r--r-- | doc/source/reference/c-api/array.rst | 412 | ||||
| -rw-r--r-- | doc/source/reference/c-api/config.rst | 79 | ||||
| -rw-r--r-- | doc/source/reference/c-api/coremath.rst | 46 | ||||
| -rw-r--r-- | doc/source/reference/c-api/deprecations.rst | 4 | ||||
| -rw-r--r-- | doc/source/reference/c-api/dtype.rst | 45 | ||||
| -rw-r--r-- | doc/source/reference/c-api/iterator.rst | 60 | ||||
| -rw-r--r-- | doc/source/reference/c-api/types-and-structures.rst | 562 | ||||
| -rw-r--r-- | doc/source/reference/c-api/ufunc.rst | 169 |
8 files changed, 731 insertions, 646 deletions
diff --git a/doc/source/reference/c-api/array.rst b/doc/source/reference/c-api/array.rst index 10c1704c2..3aa541b79 100644 --- a/doc/source/reference/c-api/array.rst +++ b/doc/source/reference/c-api/array.rst @@ -24,7 +24,7 @@ These macros access the :c:type:`PyArrayObject` structure members and are defined in ``ndarraytypes.h``. The input argument, *arr*, can be any :c:type:`PyObject *<PyObject>` that is directly interpretable as a :c:type:`PyArrayObject *` (any instance of the :c:data:`PyArray_Type` -and itssub-types). +and its sub-types). .. c:function:: int PyArray_NDIM(PyArrayObject *arr) @@ -326,7 +326,7 @@ From scratch Create a new array with the provided data-type descriptor, *descr*, of the shape determined by *nd* and *dims*. -.. c:function:: PyArray_FILLWBYTE(PyObject* obj, int val) +.. c:function:: void PyArray_FILLWBYTE(PyObject* obj, int val) Fill the array pointed to by *obj* ---which must be a (subclass of) ndarray---with the contents of *val* (evaluated as a byte). @@ -428,44 +428,44 @@ From other objects have :c:data:`NPY_ARRAY_DEFAULT` as its flags member. The *context* argument is unused. - .. c:var:: NPY_ARRAY_C_CONTIGUOUS + .. c:macro:: NPY_ARRAY_C_CONTIGUOUS Make sure the returned array is C-style contiguous - .. c:var:: NPY_ARRAY_F_CONTIGUOUS + .. c:macro:: NPY_ARRAY_F_CONTIGUOUS Make sure the returned array is Fortran-style contiguous. - .. c:var:: NPY_ARRAY_ALIGNED + .. c:macro:: NPY_ARRAY_ALIGNED Make sure the returned array is aligned on proper boundaries for its data type. An aligned array has the data pointer and every strides factor as a multiple of the alignment factor for the data-type- descriptor. - .. c:var:: NPY_ARRAY_WRITEABLE + .. c:macro:: NPY_ARRAY_WRITEABLE Make sure the returned array can be written to. - .. c:var:: NPY_ARRAY_ENSURECOPY + .. c:macro:: NPY_ARRAY_ENSURECOPY Make sure a copy is made of *op*. If this flag is not present, data is not copied if it can be avoided. - .. c:var:: NPY_ARRAY_ENSUREARRAY + .. c:macro:: NPY_ARRAY_ENSUREARRAY Make sure the result is a base-class ndarray. By default, if *op* is an instance of a subclass of ndarray, an instance of that same subclass is returned. If this flag is set, an ndarray object will be returned instead. - .. c:var:: NPY_ARRAY_FORCECAST + .. c:macro:: NPY_ARRAY_FORCECAST Force a cast to the output type even if it cannot be done safely. Without this flag, a data cast will occur only if it can be done safely, otherwise an error is raised. - .. c:var:: NPY_ARRAY_WRITEBACKIFCOPY + .. c:macro:: NPY_ARRAY_WRITEBACKIFCOPY If *op* is already an array, but does not satisfy the requirements, then a copy is made (which will satisfy the @@ -478,67 +478,67 @@ From other objects will be made writeable again. If *op* is not writeable to begin with, or if it is not already an array, then an error is raised. - .. c:var:: NPY_ARRAY_UPDATEIFCOPY + .. c:macro:: NPY_ARRAY_UPDATEIFCOPY Deprecated. Use :c:data:`NPY_ARRAY_WRITEBACKIFCOPY`, which is similar. This flag "automatically" copies the data back when the returned array is deallocated, which is not supported in all python implementations. - .. c:var:: NPY_ARRAY_BEHAVED + .. c:macro:: NPY_ARRAY_BEHAVED :c:data:`NPY_ARRAY_ALIGNED` \| :c:data:`NPY_ARRAY_WRITEABLE` - .. c:var:: NPY_ARRAY_CARRAY + .. c:macro:: NPY_ARRAY_CARRAY :c:data:`NPY_ARRAY_C_CONTIGUOUS` \| :c:data:`NPY_ARRAY_BEHAVED` - .. c:var:: NPY_ARRAY_CARRAY_RO + .. c:macro:: NPY_ARRAY_CARRAY_RO :c:data:`NPY_ARRAY_C_CONTIGUOUS` \| :c:data:`NPY_ARRAY_ALIGNED` - .. c:var:: NPY_ARRAY_FARRAY + .. c:macro:: NPY_ARRAY_FARRAY :c:data:`NPY_ARRAY_F_CONTIGUOUS` \| :c:data:`NPY_ARRAY_BEHAVED` - .. c:var:: NPY_ARRAY_FARRAY_RO + .. c:macro:: NPY_ARRAY_FARRAY_RO :c:data:`NPY_ARRAY_F_CONTIGUOUS` \| :c:data:`NPY_ARRAY_ALIGNED` - .. c:var:: NPY_ARRAY_DEFAULT + .. c:macro:: NPY_ARRAY_DEFAULT :c:data:`NPY_ARRAY_CARRAY` - .. c:var:: NPY_ARRAY_IN_ARRAY + .. c:macro:: NPY_ARRAY_IN_ARRAY :c:data:`NPY_ARRAY_C_CONTIGUOUS` \| :c:data:`NPY_ARRAY_ALIGNED` - .. c:var:: NPY_ARRAY_IN_FARRAY + .. c:macro:: NPY_ARRAY_IN_FARRAY :c:data:`NPY_ARRAY_F_CONTIGUOUS` \| :c:data:`NPY_ARRAY_ALIGNED` - .. c:var:: NPY_OUT_ARRAY + .. c:macro:: NPY_OUT_ARRAY :c:data:`NPY_ARRAY_C_CONTIGUOUS` \| :c:data:`NPY_ARRAY_WRITEABLE` \| :c:data:`NPY_ARRAY_ALIGNED` - .. c:var:: NPY_ARRAY_OUT_ARRAY + .. c:macro:: NPY_ARRAY_OUT_ARRAY :c:data:`NPY_ARRAY_C_CONTIGUOUS` \| :c:data:`NPY_ARRAY_ALIGNED` \| :c:data:`NPY_ARRAY_WRITEABLE` - .. c:var:: NPY_ARRAY_OUT_FARRAY + .. c:macro:: NPY_ARRAY_OUT_FARRAY :c:data:`NPY_ARRAY_F_CONTIGUOUS` \| :c:data:`NPY_ARRAY_WRITEABLE` \| :c:data:`NPY_ARRAY_ALIGNED` - .. c:var:: NPY_ARRAY_INOUT_ARRAY + .. c:macro:: NPY_ARRAY_INOUT_ARRAY :c:data:`NPY_ARRAY_C_CONTIGUOUS` \| :c:data:`NPY_ARRAY_WRITEABLE` \| :c:data:`NPY_ARRAY_ALIGNED` \| :c:data:`NPY_ARRAY_WRITEBACKIFCOPY` \| :c:data:`NPY_ARRAY_UPDATEIFCOPY` - .. c:var:: NPY_ARRAY_INOUT_FARRAY + .. c:macro:: NPY_ARRAY_INOUT_FARRAY :c:data:`NPY_ARRAY_F_CONTIGUOUS` \| :c:data:`NPY_ARRAY_WRITEABLE` \| :c:data:`NPY_ARRAY_ALIGNED` \| :c:data:`NPY_ARRAY_WRITEBACKIFCOPY` \| @@ -574,7 +574,7 @@ From other objects did not have the _ARRAY_ macro namespace in them. That form of the constant names is deprecated in 1.7. -.. c:var:: NPY_ARRAY_NOTSWAPPED +.. c:macro:: NPY_ARRAY_NOTSWAPPED Make sure the returned array has a data-type descriptor that is in machine byte-order, over-riding any specification in the *dtype* @@ -585,11 +585,11 @@ From other objects not in machine byte- order), then a new data-type descriptor is created and used with its byte-order field set to native. -.. c:var:: NPY_ARRAY_BEHAVED_NS +.. c:macro:: NPY_ARRAY_BEHAVED_NS :c:data:`NPY_ARRAY_ALIGNED` \| :c:data:`NPY_ARRAY_WRITEABLE` \| :c:data:`NPY_ARRAY_NOTSWAPPED` -.. c:var:: NPY_ARRAY_ELEMENTSTRIDES +.. c:macro:: NPY_ARRAY_ELEMENTSTRIDES Make sure the returned array has strides that are multiples of the element size. @@ -604,14 +604,14 @@ From other objects .. c:function:: PyObject* PyArray_FromStructInterface(PyObject* op) Returns an ndarray object from a Python object that exposes the - :obj:`__array_struct__` attribute and follows the array interface + :obj:`~object.__array_struct__` attribute and follows the array interface protocol. If the object does not contain this attribute then a borrowed reference to :c:data:`Py_NotImplemented` is returned. .. c:function:: PyObject* PyArray_FromInterface(PyObject* op) Returns an ndarray object from a Python object that exposes the - :obj:`__array_interface__` attribute following the array interface + :obj:`~object.__array_interface__` attribute following the array interface protocol. If the object does not contain this attribute then a borrowed reference to :c:data:`Py_NotImplemented` is returned. @@ -790,17 +790,17 @@ Dealing with types General check of Python Type ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. c:function:: PyArray_Check(PyObject *op) +.. c:function:: int PyArray_Check(PyObject *op) Evaluates true if *op* is a Python object whose type is a sub-type of :c:data:`PyArray_Type`. -.. c:function:: PyArray_CheckExact(PyObject *op) +.. c:function:: int PyArray_CheckExact(PyObject *op) Evaluates true if *op* is a Python object with type :c:data:`PyArray_Type`. -.. c:function:: PyArray_HasArrayInterface(PyObject *op, PyObject *out) +.. c:function:: int PyArray_HasArrayInterface(PyObject *op, PyObject *out) If ``op`` implements any part of the array interface, then ``out`` will contain a new reference to the newly created ndarray using @@ -808,7 +808,8 @@ General check of Python Type conversion occurs. Otherwise, out will contain a borrowed reference to :c:data:`Py_NotImplemented` and no error condition is set. -.. c:function:: PyArray_HasArrayInterfaceType(op, dtype, context, out) +.. c:function:: int PyArray_HasArrayInterfaceType(\ + PyObject *op, PyArray_Descr *dtype, PyObject *context, PyObject *out) If ``op`` implements any part of the array interface, then ``out`` will contain a new reference to the newly created ndarray using @@ -819,38 +820,38 @@ General check of Python Type that looks for the :obj:`~numpy.class.__array__` attribute. `context` is unused. -.. c:function:: PyArray_IsZeroDim(op) +.. c:function:: int PyArray_IsZeroDim(PyObject *op) Evaluates true if *op* is an instance of (a subclass of) :c:data:`PyArray_Type` and has 0 dimensions. .. c:function:: PyArray_IsScalar(op, cls) - Evaluates true if *op* is an instance of :c:data:`Py{cls}ArrType_Type`. + Evaluates true if *op* is an instance of ``Py{cls}ArrType_Type``. -.. c:function:: PyArray_CheckScalar(op) +.. c:function:: int PyArray_CheckScalar(PyObject *op) Evaluates true if *op* is either an array scalar (an instance of a sub-type of :c:data:`PyGenericArr_Type` ), or an instance of (a sub-class of) :c:data:`PyArray_Type` whose dimensionality is 0. -.. c:function:: PyArray_IsPythonNumber(op) +.. c:function:: int PyArray_IsPythonNumber(PyObject *op) Evaluates true if *op* is an instance of a builtin numeric type (int, float, complex, long, bool) -.. c:function:: PyArray_IsPythonScalar(op) +.. c:function:: int PyArray_IsPythonScalar(PyObject *op) Evaluates true if *op* is a builtin Python scalar object (int, float, complex, bytes, str, long, bool). -.. c:function:: PyArray_IsAnyScalar(op) +.. c:function:: int PyArray_IsAnyScalar(PyObject *op) Evaluates true if *op* is either a Python scalar object (see :c:func:`PyArray_IsPythonScalar`) or an array scalar (an instance of a sub- type of :c:data:`PyGenericArr_Type` ). -.. c:function:: PyArray_CheckAnyScalar(op) +.. c:function:: int PyArray_CheckAnyScalar(PyObject *op) Evaluates true if *op* is a Python scalar object (see :c:func:`PyArray_IsPythonScalar`), an array scalar (an instance of a @@ -866,82 +867,82 @@ enumerated array data type. For the array type checking macros the argument must be a :c:type:`PyObject *<PyObject>` that can be directly interpreted as a :c:type:`PyArrayObject *`. -.. c:function:: PyTypeNum_ISUNSIGNED(int num) +.. c:function:: int PyTypeNum_ISUNSIGNED(int num) -.. c:function:: PyDataType_ISUNSIGNED(PyArray_Descr *descr) +.. c:function:: int PyDataType_ISUNSIGNED(PyArray_Descr *descr) -.. c:function:: PyArray_ISUNSIGNED(PyArrayObject *obj) +.. c:function:: int PyArray_ISUNSIGNED(PyArrayObject *obj) Type represents an unsigned integer. -.. c:function:: PyTypeNum_ISSIGNED(int num) +.. c:function:: int PyTypeNum_ISSIGNED(int num) -.. c:function:: PyDataType_ISSIGNED(PyArray_Descr *descr) +.. c:function:: int PyDataType_ISSIGNED(PyArray_Descr *descr) -.. c:function:: PyArray_ISSIGNED(PyArrayObject *obj) +.. c:function:: int PyArray_ISSIGNED(PyArrayObject *obj) Type represents a signed integer. -.. c:function:: PyTypeNum_ISINTEGER(int num) +.. c:function:: int PyTypeNum_ISINTEGER(int num) -.. c:function:: PyDataType_ISINTEGER(PyArray_Descr* descr) +.. c:function:: int PyDataType_ISINTEGER(PyArray_Descr* descr) -.. c:function:: PyArray_ISINTEGER(PyArrayObject *obj) +.. c:function:: int PyArray_ISINTEGER(PyArrayObject *obj) Type represents any integer. -.. c:function:: PyTypeNum_ISFLOAT(int num) +.. c:function:: int PyTypeNum_ISFLOAT(int num) -.. c:function:: PyDataType_ISFLOAT(PyArray_Descr* descr) +.. c:function:: int PyDataType_ISFLOAT(PyArray_Descr* descr) -.. c:function:: PyArray_ISFLOAT(PyArrayObject *obj) +.. c:function:: int PyArray_ISFLOAT(PyArrayObject *obj) Type represents any floating point number. -.. c:function:: PyTypeNum_ISCOMPLEX(int num) +.. c:function:: int PyTypeNum_ISCOMPLEX(int num) -.. c:function:: PyDataType_ISCOMPLEX(PyArray_Descr* descr) +.. c:function:: int PyDataType_ISCOMPLEX(PyArray_Descr* descr) -.. c:function:: PyArray_ISCOMPLEX(PyArrayObject *obj) +.. c:function:: int PyArray_ISCOMPLEX(PyArrayObject *obj) Type represents any complex floating point number. -.. c:function:: PyTypeNum_ISNUMBER(int num) +.. c:function:: int PyTypeNum_ISNUMBER(int num) -.. c:function:: PyDataType_ISNUMBER(PyArray_Descr* descr) +.. c:function:: int PyDataType_ISNUMBER(PyArray_Descr* descr) -.. c:function:: PyArray_ISNUMBER(PyArrayObject *obj) +.. c:function:: int PyArray_ISNUMBER(PyArrayObject *obj) Type represents any integer, floating point, or complex floating point number. -.. c:function:: PyTypeNum_ISSTRING(int num) +.. c:function:: int PyTypeNum_ISSTRING(int num) -.. c:function:: PyDataType_ISSTRING(PyArray_Descr* descr) +.. c:function:: int PyDataType_ISSTRING(PyArray_Descr* descr) -.. c:function:: PyArray_ISSTRING(PyArrayObject *obj) +.. c:function:: int PyArray_ISSTRING(PyArrayObject *obj) Type represents a string data type. -.. c:function:: PyTypeNum_ISPYTHON(int num) +.. c:function:: int PyTypeNum_ISPYTHON(int num) -.. c:function:: PyDataType_ISPYTHON(PyArray_Descr* descr) +.. c:function:: int PyDataType_ISPYTHON(PyArray_Descr* descr) -.. c:function:: PyArray_ISPYTHON(PyArrayObject *obj) +.. c:function:: int PyArray_ISPYTHON(PyArrayObject *obj) Type represents an enumerated type corresponding to one of the standard Python scalar (bool, int, float, or complex). -.. c:function:: PyTypeNum_ISFLEXIBLE(int num) +.. c:function:: int PyTypeNum_ISFLEXIBLE(int num) -.. c:function:: PyDataType_ISFLEXIBLE(PyArray_Descr* descr) +.. c:function:: int PyDataType_ISFLEXIBLE(PyArray_Descr* descr) -.. c:function:: PyArray_ISFLEXIBLE(PyArrayObject *obj) +.. c:function:: int PyArray_ISFLEXIBLE(PyArrayObject *obj) Type represents one of the flexible array types ( :c:data:`NPY_STRING`, :c:data:`NPY_UNICODE`, or :c:data:`NPY_VOID` ). -.. c:function:: PyDataType_ISUNSIZED(PyArray_Descr* descr): +.. c:function:: int PyDataType_ISUNSIZED(PyArray_Descr* descr) Type has no size information attached, and can be resized. Should only be called on flexible dtypes. Types that are attached to an array will always @@ -951,55 +952,55 @@ argument must be a :c:type:`PyObject *<PyObject>` that can be directly interpret For structured datatypes with no fields this function now returns False. -.. c:function:: PyTypeNum_ISUSERDEF(int num) +.. c:function:: int PyTypeNum_ISUSERDEF(int num) -.. c:function:: PyDataType_ISUSERDEF(PyArray_Descr* descr) +.. c:function:: int PyDataType_ISUSERDEF(PyArray_Descr* descr) -.. c:function:: PyArray_ISUSERDEF(PyArrayObject *obj) +.. c:function:: int PyArray_ISUSERDEF(PyArrayObject *obj) Type represents a user-defined type. -.. c:function:: PyTypeNum_ISEXTENDED(int num) +.. c:function:: int PyTypeNum_ISEXTENDED(int num) -.. c:function:: PyDataType_ISEXTENDED(PyArray_Descr* descr) +.. c:function:: int PyDataType_ISEXTENDED(PyArray_Descr* descr) -.. c:function:: PyArray_ISEXTENDED(PyArrayObject *obj) +.. c:function:: int PyArray_ISEXTENDED(PyArrayObject *obj) Type is either flexible or user-defined. -.. c:function:: PyTypeNum_ISOBJECT(int num) +.. c:function:: int PyTypeNum_ISOBJECT(int num) -.. c:function:: PyDataType_ISOBJECT(PyArray_Descr* descr) +.. c:function:: int PyDataType_ISOBJECT(PyArray_Descr* descr) -.. c:function:: PyArray_ISOBJECT(PyArrayObject *obj) +.. c:function:: int PyArray_ISOBJECT(PyArrayObject *obj) Type represents object data type. -.. c:function:: PyTypeNum_ISBOOL(int num) +.. c:function:: int PyTypeNum_ISBOOL(int num) -.. c:function:: PyDataType_ISBOOL(PyArray_Descr* descr) +.. c:function:: int PyDataType_ISBOOL(PyArray_Descr* descr) -.. c:function:: PyArray_ISBOOL(PyArrayObject *obj) +.. c:function:: int PyArray_ISBOOL(PyArrayObject *obj) Type represents Boolean data type. -.. c:function:: PyDataType_HASFIELDS(PyArray_Descr* descr) +.. c:function:: int PyDataType_HASFIELDS(PyArray_Descr* descr) -.. c:function:: PyArray_HASFIELDS(PyArrayObject *obj) +.. c:function:: int PyArray_HASFIELDS(PyArrayObject *obj) Type has fields associated with it. -.. c:function:: PyArray_ISNOTSWAPPED(m) +.. c:function:: int PyArray_ISNOTSWAPPED(PyArrayObject *m) Evaluates true if the data area of the ndarray *m* is in machine byte-order according to the array's data-type descriptor. -.. c:function:: PyArray_ISBYTESWAPPED(m) +.. c:function:: int PyArray_ISBYTESWAPPED(PyArrayObject *m) Evaluates true if the data area of the ndarray *m* is **not** in machine byte-order according to the array's data-type descriptor. -.. c:function:: Bool PyArray_EquivTypes( \ +.. c:function:: npy_bool PyArray_EquivTypes( \ PyArray_Descr* type1, PyArray_Descr* type2) Return :c:data:`NPY_TRUE` if *type1* and *type2* actually represent @@ -1008,18 +1009,18 @@ argument must be a :c:type:`PyObject *<PyObject>` that can be directly interpret :c:data:`NPY_LONG` and :c:data:`NPY_INT` are equivalent. Otherwise return :c:data:`NPY_FALSE`. -.. c:function:: Bool PyArray_EquivArrTypes( \ +.. c:function:: npy_bool PyArray_EquivArrTypes( \ PyArrayObject* a1, PyArrayObject * a2) Return :c:data:`NPY_TRUE` if *a1* and *a2* are arrays with equivalent types for this platform. -.. c:function:: Bool PyArray_EquivTypenums(int typenum1, int typenum2) +.. c:function:: npy_bool PyArray_EquivTypenums(int typenum1, int typenum2) Special case of :c:func:`PyArray_EquivTypes` (...) that does not accept flexible data types but may be easier to call. -.. c:function:: int PyArray_EquivByteorders({byteorder} b1, {byteorder} b2) +.. c:function:: int PyArray_EquivByteorders(int b1, int b2) True if byteorder characters ( :c:data:`NPY_LITTLE`, :c:data:`NPY_BIG`, :c:data:`NPY_NATIVE`, :c:data:`NPY_IGNORE` ) are @@ -1142,8 +1143,8 @@ Converting data types storing the max value of the input types converted to a string or unicode. .. c:function:: PyArray_Descr* PyArray_ResultType( \ - npy_intp narrs, PyArrayObject**arrs, npy_intp ndtypes, \ - PyArray_Descr**dtypes) + npy_intp narrs, PyArrayObject **arrs, npy_intp ndtypes, \ + PyArray_Descr **dtypes) .. versionadded:: 1.6 @@ -1334,7 +1335,7 @@ Special functions for NPY_OBJECT locations in the structure with object data-types. No checking is performed but *arr* must be of data-type :c:type:`NPY_OBJECT` and be single-segment and uninitialized (no previous objects in - position). Use :c:func:`PyArray_DECREF` (*arr*) if you need to + position). Use :c:func:`PyArray_XDECREF` (*arr*) if you need to decrement all the items in the object array prior to calling this function. @@ -1343,7 +1344,7 @@ Special functions for NPY_OBJECT Precondition: ``arr`` is a copy of ``base`` (though possibly with different strides, ordering, etc.) Set the UPDATEIFCOPY flag and ``arr->base`` so that when ``arr`` is destructed, it will copy any changes back to ``base``. - DEPRECATED, use :c:func:`PyArray_SetWritebackIfCopyBase``. + DEPRECATED, use :c:func:`PyArray_SetWritebackIfCopyBase`. Returns 0 for success, -1 for failure. @@ -1353,7 +1354,7 @@ Special functions for NPY_OBJECT strides, ordering, etc.) Sets the :c:data:`NPY_ARRAY_WRITEBACKIFCOPY` flag and ``arr->base``, and set ``base`` to READONLY. Call :c:func:`PyArray_ResolveWritebackIfCopy` before calling - `Py_DECREF`` in order copy any changes back to ``base`` and + `Py_DECREF` in order copy any changes back to ``base`` and reset the READONLY flag. Returns 0 for success, -1 for failure. @@ -1397,12 +1398,12 @@ In versions 1.6 and earlier of NumPy, the following flags did not have the _ARRAY_ macro namespace in them. That form of the constant names is deprecated in 1.7. -.. c:var:: NPY_ARRAY_C_CONTIGUOUS +.. c:macro:: NPY_ARRAY_C_CONTIGUOUS The data area is in C-style contiguous order (last index varies the fastest). -.. c:var:: NPY_ARRAY_F_CONTIGUOUS +.. c:macro:: NPY_ARRAY_F_CONTIGUOUS The data area is in Fortran-style contiguous order (first index varies the fastest). @@ -1423,22 +1424,22 @@ of the constant names is deprecated in 1.7. .. seealso:: :ref:`Internal memory layout of an ndarray <arrays.ndarray>` -.. c:var:: NPY_ARRAY_OWNDATA +.. c:macro:: NPY_ARRAY_OWNDATA The data area is owned by this array. -.. c:var:: NPY_ARRAY_ALIGNED +.. c:macro:: NPY_ARRAY_ALIGNED The data area and all array elements are aligned appropriately. -.. c:var:: NPY_ARRAY_WRITEABLE +.. c:macro:: NPY_ARRAY_WRITEABLE The data area can be written to. Notice that the above 3 flags are defined so that a new, well- behaved array has these flags defined as true. -.. c:var:: NPY_ARRAY_WRITEBACKIFCOPY +.. c:macro:: NPY_ARRAY_WRITEBACKIFCOPY The data area represents a (well-behaved) copy whose information should be transferred back to the original when @@ -1457,7 +1458,7 @@ of the constant names is deprecated in 1.7. would have returned an error because :c:data:`NPY_ARRAY_WRITEBACKIFCOPY` would not have been possible. -.. c:var:: NPY_ARRAY_UPDATEIFCOPY +.. c:macro:: NPY_ARRAY_UPDATEIFCOPY A deprecated version of :c:data:`NPY_ARRAY_WRITEBACKIFCOPY` which depends upon ``dealloc`` to trigger the writeback. For backwards @@ -1474,31 +1475,31 @@ for ``flags`` which can be any of :c:data:`NPY_ARRAY_C_CONTIGUOUS`, Combinations of array flags ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. c:var:: NPY_ARRAY_BEHAVED +.. c:macro:: NPY_ARRAY_BEHAVED :c:data:`NPY_ARRAY_ALIGNED` \| :c:data:`NPY_ARRAY_WRITEABLE` -.. c:var:: NPY_ARRAY_CARRAY +.. c:macro:: NPY_ARRAY_CARRAY :c:data:`NPY_ARRAY_C_CONTIGUOUS` \| :c:data:`NPY_ARRAY_BEHAVED` -.. c:var:: NPY_ARRAY_CARRAY_RO +.. c:macro:: NPY_ARRAY_CARRAY_RO :c:data:`NPY_ARRAY_C_CONTIGUOUS` \| :c:data:`NPY_ARRAY_ALIGNED` -.. c:var:: NPY_ARRAY_FARRAY +.. c:macro:: NPY_ARRAY_FARRAY :c:data:`NPY_ARRAY_F_CONTIGUOUS` \| :c:data:`NPY_ARRAY_BEHAVED` -.. c:var:: NPY_ARRAY_FARRAY_RO +.. c:macro:: NPY_ARRAY_FARRAY_RO :c:data:`NPY_ARRAY_F_CONTIGUOUS` \| :c:data:`NPY_ARRAY_ALIGNED` -.. c:var:: NPY_ARRAY_DEFAULT +.. c:macro:: NPY_ARRAY_DEFAULT :c:data:`NPY_ARRAY_CARRAY` -.. c:var:: NPY_ARRAY_UPDATE_ALL +.. c:macro:: NPY_ARRAY_UPDATE_ALL :c:data:`NPY_ARRAY_C_CONTIGUOUS` \| :c:data:`NPY_ARRAY_F_CONTIGUOUS` \| :c:data:`NPY_ARRAY_ALIGNED` @@ -1509,28 +1510,19 @@ Flag-like constants These constants are used in :c:func:`PyArray_FromAny` (and its macro forms) to specify desired properties of the new array. -.. c:var:: NPY_ARRAY_FORCECAST +.. c:macro:: NPY_ARRAY_FORCECAST Cast to the desired type, even if it can't be done without losing information. -.. c:var:: NPY_ARRAY_ENSURECOPY +.. c:macro:: NPY_ARRAY_ENSURECOPY Make sure the resulting array is a copy of the original. -.. c:var:: NPY_ARRAY_ENSUREARRAY +.. c:macro:: NPY_ARRAY_ENSUREARRAY Make sure the resulting object is an actual ndarray, and not a sub-class. -.. c:var:: NPY_ARRAY_NOTSWAPPED - - Only used in :c:func:`PyArray_CheckFromAny` to over-ride the byteorder - of the data-type object passed in. - -.. c:var:: NPY_ARRAY_BEHAVED_NS - - :c:data:`NPY_ARRAY_ALIGNED` \| :c:data:`NPY_ARRAY_WRITEABLE` \| :c:data:`NPY_ARRAY_NOTSWAPPED` - Flag checking ^^^^^^^^^^^^^ @@ -1538,7 +1530,7 @@ Flag checking For all of these macros *arr* must be an instance of a (subclass of) :c:data:`PyArray_Type`. -.. c:function:: PyArray_CHKFLAGS(PyObject *arr, flags) +.. c:function:: int PyArray_CHKFLAGS(PyObject *arr, int flags) The first parameter, arr, must be an ndarray or subclass. The parameter, *flags*, should be an integer consisting of bitwise @@ -1548,60 +1540,60 @@ For all of these macros *arr* must be an instance of a (subclass of) :c:data:`NPY_ARRAY_WRITEABLE`, :c:data:`NPY_ARRAY_WRITEBACKIFCOPY`, :c:data:`NPY_ARRAY_UPDATEIFCOPY`. -.. c:function:: PyArray_IS_C_CONTIGUOUS(PyObject *arr) +.. c:function:: int PyArray_IS_C_CONTIGUOUS(PyObject *arr) Evaluates true if *arr* is C-style contiguous. -.. c:function:: PyArray_IS_F_CONTIGUOUS(PyObject *arr) +.. c:function:: int PyArray_IS_F_CONTIGUOUS(PyObject *arr) Evaluates true if *arr* is Fortran-style contiguous. -.. c:function:: PyArray_ISFORTRAN(PyObject *arr) +.. c:function:: int PyArray_ISFORTRAN(PyObject *arr) Evaluates true if *arr* is Fortran-style contiguous and *not* C-style contiguous. :c:func:`PyArray_IS_F_CONTIGUOUS` is the correct way to test for Fortran-style contiguity. -.. c:function:: PyArray_ISWRITEABLE(PyObject *arr) +.. c:function:: int PyArray_ISWRITEABLE(PyObject *arr) Evaluates true if the data area of *arr* can be written to -.. c:function:: PyArray_ISALIGNED(PyObject *arr) +.. c:function:: int PyArray_ISALIGNED(PyObject *arr) Evaluates true if the data area of *arr* is properly aligned on the machine. -.. c:function:: PyArray_ISBEHAVED(PyObject *arr) +.. c:function:: int PyArray_ISBEHAVED(PyObject *arr) Evaluates true if the data area of *arr* is aligned and writeable and in machine byte-order according to its descriptor. -.. c:function:: PyArray_ISBEHAVED_RO(PyObject *arr) +.. c:function:: int PyArray_ISBEHAVED_RO(PyObject *arr) Evaluates true if the data area of *arr* is aligned and in machine byte-order. -.. c:function:: PyArray_ISCARRAY(PyObject *arr) +.. c:function:: int PyArray_ISCARRAY(PyObject *arr) Evaluates true if the data area of *arr* is C-style contiguous, and :c:func:`PyArray_ISBEHAVED` (*arr*) is true. -.. c:function:: PyArray_ISFARRAY(PyObject *arr) +.. c:function:: int PyArray_ISFARRAY(PyObject *arr) Evaluates true if the data area of *arr* is Fortran-style contiguous and :c:func:`PyArray_ISBEHAVED` (*arr*) is true. -.. c:function:: PyArray_ISCARRAY_RO(PyObject *arr) +.. c:function:: int PyArray_ISCARRAY_RO(PyObject *arr) Evaluates true if the data area of *arr* is C-style contiguous, aligned, and in machine byte-order. -.. c:function:: PyArray_ISFARRAY_RO(PyObject *arr) +.. c:function:: int PyArray_ISFARRAY_RO(PyObject *arr) Evaluates true if the data area of *arr* is Fortran-style contiguous, aligned, and in machine byte-order **.** -.. c:function:: PyArray_ISONESEGMENT(PyObject *arr) +.. c:function:: int PyArray_ISONESEGMENT(PyObject *arr) Evaluates true if the data area of *arr* consists of a single (C-style or Fortran-style) contiguous segment. @@ -1659,7 +1651,7 @@ Conversion destination must be an integer multiple of the number of elements in *val*. -.. c:function:: PyObject* PyArray_Byteswap(PyArrayObject* self, Bool inplace) +.. c:function:: PyObject* PyArray_Byteswap(PyArrayObject* self, npy_bool inplace) Equivalent to :meth:`ndarray.byteswap<numpy.ndarray.byteswap>` (*self*, *inplace*). Return an array whose data area is byteswapped. If *inplace* is non-zero, then do @@ -1876,16 +1868,16 @@ Item selection and manipulation created. The *clipmode* argument determines behavior for when entries in *self* are not between 0 and len(*op*). - .. c:var:: NPY_RAISE + .. c:macro:: NPY_RAISE raise a ValueError; - .. c:var:: NPY_WRAP + .. c:macro:: NPY_WRAP wrap values < 0 by adding len(*op*) and values >=len(*op*) by subtracting len(*op*) until they are in range; - .. c:var:: NPY_CLIP + .. c:macro:: NPY_CLIP all values are clipped to the region [0, len(*op*) ). @@ -2263,7 +2255,7 @@ Array Functions See the :func:`~numpy.einsum` function for more details. -.. c:function:: PyObject* PyArray_CopyAndTranspose(PyObject \* op) +.. c:function:: PyObject* PyArray_CopyAndTranspose(PyObject * op) A specialized copy and transpose function that works only for 2-d arrays. The returned array is a transposed copy of *op*. @@ -2318,7 +2310,7 @@ Array Functions Other functions ^^^^^^^^^^^^^^^ -.. c:function:: Bool PyArray_CheckStrides( \ +.. c:function:: npy_bool PyArray_CheckStrides( \ int elsize, int nd, npy_intp numbytes, npy_intp const* dims, \ npy_intp const* newstrides) @@ -2361,7 +2353,9 @@ it is possible to do this. Defining an :c:type:`NpyAuxData` is similar to defining a class in C++, but the object semantics have to be tracked manually since the API is in C. Here's an example for a function which doubles up an element using -an element copier function as a primitive.:: +an element copier function as a primitive. + +.. code-block:: c typedef struct { NpyAuxData base; @@ -2425,12 +2419,12 @@ an element copier function as a primitive.:: functions should never set the Python exception on error, because they may be called from a multi-threaded context. -.. c:function:: NPY_AUXDATA_FREE(auxdata) +.. c:function:: void NPY_AUXDATA_FREE(NpyAuxData *auxdata) A macro which calls the auxdata's free function appropriately, does nothing if auxdata is NULL. -.. c:function:: NPY_AUXDATA_CLONE(auxdata) +.. c:function:: NpyAuxData *NPY_AUXDATA_CLONE(NpyAuxData *auxdata) A macro which calls the auxdata's clone function appropriately, returning a deep copy of the auxiliary data. @@ -2453,7 +2447,7 @@ this useful approach to looping over an array. it easy to loop over an N-dimensional non-contiguous array in C-style contiguous fashion. -.. c:function:: PyObject* PyArray_IterAllButAxis(PyObject* arr, int \*axis) +.. c:function:: PyObject* PyArray_IterAllButAxis(PyObject* arr, int* axis) Return an array iterator that will iterate over all axes but the one provided in *\*axis*. The returned iterator cannot be used @@ -2497,7 +2491,7 @@ this useful approach to looping over an array. *destination*, which must have size at least *iterator* ->nd_m1+1. -.. c:function:: PyArray_ITER_GOTO1D(PyObject* iterator, npy_intp index) +.. c:function:: void PyArray_ITER_GOTO1D(PyObject* iterator, npy_intp index) Set the *iterator* index and dataptr to the location in the array indicated by the integer *index* which points to an element in the @@ -2818,11 +2812,21 @@ Data-type descriptors Create a new data-type object with the byteorder set according to *newendian*. All referenced data-type objects (in subdescr and fields members of the data-type object) are also changed - (recursively). If a byteorder of :c:data:`NPY_IGNORE` is encountered it + (recursively). + + The value of *newendian* is one of these macros: + + .. c:macro:: NPY_IGNORE + NPY_SWAP + NPY_NATIVE + NPY_LITTLE + NPY_BIG + + If a byteorder of :c:data:`NPY_IGNORE` is encountered it is left alone. If newendian is :c:data:`NPY_SWAP`, then all byte-orders are swapped. Other valid newendian values are :c:data:`NPY_NATIVE`, - :c:data:`NPY_LITTLE`, and :c:data:`NPY_BIG` which all cause the returned - data-typed descriptor (and all it's + :c:data:`NPY_LITTLE`, and :c:data:`NPY_BIG` which all cause + the returned data-typed descriptor (and all it's referenced data-type descriptors) to have the corresponding byte- order. @@ -2956,11 +2960,11 @@ to. already a buffer object pointing to another object). If you need to hold on to the memory be sure to INCREF the base member. The chunk of memory is pointed to by *buf* ->ptr member and has length - *buf* ->len. The flags member of *buf* is :c:data:`NPY_BEHAVED_RO` with - the :c:data:`NPY_ARRAY_WRITEABLE` flag set if *obj* has a writeable buffer - interface. + *buf* ->len. The flags member of *buf* is :c:data:`NPY_ARRAY_ALIGNED` + with the :c:data:`NPY_ARRAY_WRITEABLE` flag set if *obj* has + a writeable buffer interface. -.. c:function:: int PyArray_AxisConverter(PyObject \* obj, int* axis) +.. c:function:: int PyArray_AxisConverter(PyObject* obj, int* axis) Convert a Python object, *obj*, representing an axis argument to the proper value for passing to the functions that take an integer @@ -2968,7 +2972,7 @@ to. :c:data:`NPY_MAXDIMS` which is interpreted correctly by the C-API functions that take axis arguments. -.. c:function:: int PyArray_BoolConverter(PyObject* obj, Bool* value) +.. c:function:: int PyArray_BoolConverter(PyObject* obj, npy_bool* value) Convert any Python object, *obj*, to :c:data:`NPY_TRUE` or :c:data:`NPY_FALSE`, and place the result in *value*. @@ -3120,19 +3124,19 @@ the C-API is needed then some additional steps must be taken. Internally, these #defines work as follows: * If neither is defined, the C-API is declared to be - :c:type:`static void**`, so it is only visible within the + ``static void**``, so it is only visible within the compilation unit that #includes numpy/arrayobject.h. * If :c:macro:`PY_ARRAY_UNIQUE_SYMBOL` is #defined, but :c:macro:`NO_IMPORT_ARRAY` is not, the C-API is declared to - be :c:type:`void**`, so that it will also be visible to other + be ``void**``, so that it will also be visible to other compilation units. * If :c:macro:`NO_IMPORT_ARRAY` is #defined, regardless of whether :c:macro:`PY_ARRAY_UNIQUE_SYMBOL` is, the C-API is - declared to be :c:type:`extern void**`, so it is expected to + declared to be ``extern void**``, so it is expected to be defined in another compilation unit. * Whenever :c:macro:`PY_ARRAY_UNIQUE_SYMBOL` is #defined, it also changes the name of the variable holding the C-API, which - defaults to :c:data:`PyArray_API`, to whatever the macro is + defaults to ``PyArray_API``, to whatever the macro is #defined to. Checking the API Version @@ -3147,21 +3151,31 @@ calling the function). That's why several functions are provided to check for numpy versions. The macros :c:data:`NPY_VERSION` and :c:data:`NPY_FEATURE_VERSION` corresponds to the numpy version used to build the extension, whereas the versions returned by the functions -PyArray_GetNDArrayCVersion and PyArray_GetNDArrayCFeatureVersion corresponds to -the runtime numpy's version. +:c:func:`PyArray_GetNDArrayCVersion` and :c:func:`PyArray_GetNDArrayCFeatureVersion` +corresponds to the runtime numpy's version. The rules for ABI and API compatibilities can be summarized as follows: - * Whenever :c:data:`NPY_VERSION` != PyArray_GetNDArrayCVersion, the + * Whenever :c:data:`NPY_VERSION` != ``PyArray_GetNDArrayCVersion()``, the extension has to be recompiled (ABI incompatibility). - * :c:data:`NPY_VERSION` == PyArray_GetNDArrayCVersion and - :c:data:`NPY_FEATURE_VERSION` <= PyArray_GetNDArrayCFeatureVersion means + * :c:data:`NPY_VERSION` == ``PyArray_GetNDArrayCVersion()`` and + :c:data:`NPY_FEATURE_VERSION` <= ``PyArray_GetNDArrayCFeatureVersion()`` means backward compatible changes. ABI incompatibility is automatically detected in every numpy's version. API incompatibility detection was added in numpy 1.4.0. If you want to supported many different numpy versions with one extension binary, you have to build your -extension with the lowest NPY_FEATURE_VERSION as possible. +extension with the lowest :c:data:`NPY_FEATURE_VERSION` as possible. + +.. c:macro:: NPY_VERSION + + The current version of the ndarray object (check to see if this + variable is defined to guarantee the ``numpy/arrayobject.h`` header is + being used). + +.. c:macro:: NPY_FEATURE_VERSION + + The current version of the C-API. .. c:function:: unsigned int PyArray_GetNDArrayCVersion(void) @@ -3242,7 +3256,7 @@ Memory management .. c:function:: char* PyDataMem_NEW(size_t nbytes) -.. c:function:: PyDataMem_FREE(char* ptr) +.. c:function:: void PyDataMem_FREE(char* ptr) .. c:function:: char* PyDataMem_RENEW(void * ptr, size_t newbytes) @@ -3251,7 +3265,7 @@ Memory management .. c:function:: npy_intp* PyDimMem_NEW(int nd) -.. c:function:: PyDimMem_FREE(char* ptr) +.. c:function:: void PyDimMem_FREE(char* ptr) .. c:function:: npy_intp* PyDimMem_RENEW(void* ptr, size_t newnd) @@ -3259,7 +3273,7 @@ Memory management .. c:function:: void* PyArray_malloc(size_t nbytes) -.. c:function:: PyArray_free(void* ptr) +.. c:function:: void PyArray_free(void* ptr) .. c:function:: void* PyArray_realloc(npy_intp* ptr, size_t nbytes) @@ -3268,6 +3282,8 @@ Memory management :c:data:`NPY_USE_PYMEM` is 0, if :c:data:`NPY_USE_PYMEM` is 1, then the Python memory allocator is used. + .. c:macro:: NPY_USE_PYMEM + .. c:function:: int PyArray_ResolveWritebackIfCopy(PyArrayObject* obj) If ``obj.flags`` has :c:data:`NPY_ARRAY_WRITEBACKIFCOPY` or (deprecated) @@ -3298,9 +3314,13 @@ be accomplished using two groups of macros. Typically, if one macro in a group is used in a code block, all of them must be used in the same code block. Currently, :c:data:`NPY_ALLOW_THREADS` is defined to the python-defined :c:data:`WITH_THREADS` constant unless the environment -variable :c:data:`NPY_NOSMP` is set in which case +variable ``NPY_NOSMP`` is set in which case :c:data:`NPY_ALLOW_THREADS` is defined to be 0. +.. c:macro:: NPY_ALLOW_THREADS + +.. c:macro:: WITH_THREADS + Group 1 """"""" @@ -3337,18 +3357,18 @@ Group 1 interpreter. This macro acquires the GIL and restores the Python state from the saved variable. - .. c:function:: NPY_BEGIN_THREADS_DESCR(PyArray_Descr *dtype) + .. c:function:: void NPY_BEGIN_THREADS_DESCR(PyArray_Descr *dtype) Useful to release the GIL only if *dtype* does not contain arbitrary Python objects which may need the Python interpreter during execution of the loop. - .. c:function:: NPY_END_THREADS_DESCR(PyArray_Descr *dtype) + .. c:function:: void NPY_END_THREADS_DESCR(PyArray_Descr *dtype) Useful to regain the GIL in situations where it was released using the BEGIN form of this macro. - .. c:function:: NPY_BEGIN_THREADS_THRESHOLDED(int loop_size) + .. c:function:: void NPY_BEGIN_THREADS_THRESHOLDED(int loop_size) Useful to release the GIL only if *loop_size* exceeds a minimum threshold, currently set to 500. Should be matched @@ -3388,15 +3408,15 @@ Group 2 Priority ^^^^^^^^ -.. c:var:: NPY_PRIORITY +.. c:macro:: NPY_PRIORITY Default priority for arrays. -.. c:var:: NPY_SUBTYPE_PRIORITY +.. c:macro:: NPY_SUBTYPE_PRIORITY Default subtype priority. -.. c:var:: NPY_SCALAR_PRIORITY +.. c:macro:: NPY_SCALAR_PRIORITY Default scalar priority (very small) @@ -3411,15 +3431,15 @@ Priority Default buffers ^^^^^^^^^^^^^^^ -.. c:var:: NPY_BUFSIZE +.. c:macro:: NPY_BUFSIZE Default size of the user-settable internal buffers. -.. c:var:: NPY_MIN_BUFSIZE +.. c:macro:: NPY_MIN_BUFSIZE Smallest size of user-settable internal buffers. -.. c:var:: NPY_MAX_BUFSIZE +.. c:macro:: NPY_MAX_BUFSIZE Largest size allowed for the user-settable buffers. @@ -3427,38 +3447,32 @@ Default buffers Other constants ^^^^^^^^^^^^^^^ -.. c:var:: NPY_NUM_FLOATTYPE +.. c:macro:: NPY_NUM_FLOATTYPE The number of floating-point types -.. c:var:: NPY_MAXDIMS +.. c:macro:: NPY_MAXDIMS The maximum number of dimensions allowed in arrays. -.. c:var:: NPY_MAXARGS +.. c:macro:: NPY_MAXARGS The maximum number of array arguments that can be used in functions. -.. c:var:: NPY_VERSION - - The current version of the ndarray object (check to see if this - variable is defined to guarantee the numpy/arrayobject.h header is - being used). - -.. c:var:: NPY_FALSE +.. c:macro:: NPY_FALSE Defined as 0 for use with Bool. -.. c:var:: NPY_TRUE +.. c:macro:: NPY_TRUE Defined as 1 for use with Bool. -.. c:var:: NPY_FAIL +.. c:macro:: NPY_FAIL The return value of failed converter functions which are called using the "O&" syntax in :c:func:`PyArg_ParseTuple`-like functions. -.. c:var:: NPY_SUCCEED +.. c:macro:: NPY_SUCCEED The return value of successful converter functions which are called using the "O&" syntax in :c:func:`PyArg_ParseTuple`-like functions. @@ -3467,7 +3481,7 @@ Other constants Miscellaneous Macros ^^^^^^^^^^^^^^^^^^^^ -.. c:function:: PyArray_SAMESHAPE(PyArrayObject *a1, PyArrayObject *a2) +.. c:function:: int PyArray_SAMESHAPE(PyArrayObject *a1, PyArrayObject *a2) Evaluates as True if arrays *a1* and *a2* have the same shape. @@ -3502,11 +3516,11 @@ Miscellaneous Macros of the ordering which is lexicographic: comparing the real parts first and then the complex parts if the real parts are equal. -.. c:function:: PyArray_REFCOUNT(PyObject* op) +.. c:function:: npy_intp PyArray_REFCOUNT(PyObject* op) Returns the reference count of any Python object. -.. c:function:: PyArray_DiscardWritebackIfCopy(PyObject* obj) +.. c:function:: void PyArray_DiscardWritebackIfCopy(PyObject* obj) If ``obj.flags`` has :c:data:`NPY_ARRAY_WRITEBACKIFCOPY` or (deprecated) :c:data:`NPY_ARRAY_UPDATEIFCOPY`, this function clears the flags, `DECREF` s @@ -3517,7 +3531,7 @@ Miscellaneous Macros error when you are finished with ``obj``, just before ``Py_DECREF(obj)``. It may be called multiple times, or with ``NULL`` input. -.. c:function:: PyArray_XDECREF_ERR(PyObject* obj) +.. c:function:: void PyArray_XDECREF_ERR(PyObject* obj) Deprecated in 1.14, use :c:func:`PyArray_DiscardWritebackIfCopy` followed by ``Py_XDECREF`` @@ -3623,6 +3637,22 @@ Enumerated Types Wraps an index to the valid range if it is out of bounds. +.. c:type:: NPY_SEARCHSIDE + + A variable type indicating whether the index returned should be that of + the first suitable location (if :c:data:`NPY_SEARCHLEFT`) or of the last + (if :c:data:`NPY_SEARCHRIGHT`). + + .. c:var:: NPY_SEARCHLEFT + + .. c:var:: NPY_SEARCHRIGHT + +.. c:type:: NPY_SELECTKIND + + A variable type indicating the selection algorithm being used. + + .. c:var:: NPY_INTROSELECT + .. c:type:: NPY_CASTING .. versionadded:: 1.6 diff --git a/doc/source/reference/c-api/config.rst b/doc/source/reference/c-api/config.rst index 05e6fe44d..87130699b 100644 --- a/doc/source/reference/c-api/config.rst +++ b/doc/source/reference/c-api/config.rst @@ -19,59 +19,62 @@ avoid namespace pollution. Data type sizes --------------- -The :c:data:`NPY_SIZEOF_{CTYPE}` constants are defined so that sizeof +The ``NPY_SIZEOF_{CTYPE}`` constants are defined so that sizeof information is available to the pre-processor. -.. c:var:: NPY_SIZEOF_SHORT +.. c:macro:: NPY_SIZEOF_SHORT sizeof(short) -.. c:var:: NPY_SIZEOF_INT +.. c:macro:: NPY_SIZEOF_INT sizeof(int) -.. c:var:: NPY_SIZEOF_LONG +.. c:macro:: NPY_SIZEOF_LONG sizeof(long) -.. c:var:: NPY_SIZEOF_LONGLONG +.. c:macro:: NPY_SIZEOF_LONGLONG sizeof(longlong) where longlong is defined appropriately on the platform. -.. c:var:: NPY_SIZEOF_PY_LONG_LONG +.. c:macro:: NPY_SIZEOF_PY_LONG_LONG -.. c:var:: NPY_SIZEOF_FLOAT +.. c:macro:: NPY_SIZEOF_FLOAT sizeof(float) -.. c:var:: NPY_SIZEOF_DOUBLE +.. c:macro:: NPY_SIZEOF_DOUBLE sizeof(double) -.. c:var:: NPY_SIZEOF_LONG_DOUBLE +.. c:macro:: NPY_SIZEOF_LONG_DOUBLE - sizeof(longdouble) (A macro defines **NPY_SIZEOF_LONGDOUBLE** as well.) +.. c:macro:: NPY_SIZEOF_LONGDOUBLE -.. c:var:: NPY_SIZEOF_PY_INTPTR_T + sizeof(longdouble) - Size of a pointer on this platform (sizeof(void \*)) (A macro defines - NPY_SIZEOF_INTP as well.) +.. c:macro:: NPY_SIZEOF_PY_INTPTR_T + +.. c:macro:: NPY_SIZEOF_INTP + + Size of a pointer on this platform (sizeof(void \*)) Platform information -------------------- -.. c:var:: NPY_CPU_X86 -.. c:var:: NPY_CPU_AMD64 -.. c:var:: NPY_CPU_IA64 -.. c:var:: NPY_CPU_PPC -.. c:var:: NPY_CPU_PPC64 -.. c:var:: NPY_CPU_SPARC -.. c:var:: NPY_CPU_SPARC64 -.. c:var:: NPY_CPU_S390 -.. c:var:: NPY_CPU_PARISC +.. c:macro:: NPY_CPU_X86 +.. c:macro:: NPY_CPU_AMD64 +.. c:macro:: NPY_CPU_IA64 +.. c:macro:: NPY_CPU_PPC +.. c:macro:: NPY_CPU_PPC64 +.. c:macro:: NPY_CPU_SPARC +.. c:macro:: NPY_CPU_SPARC64 +.. c:macro:: NPY_CPU_S390 +.. c:macro:: NPY_CPU_PARISC .. versionadded:: 1.3.0 @@ -80,11 +83,11 @@ Platform information Defined in ``numpy/npy_cpu.h`` -.. c:var:: NPY_LITTLE_ENDIAN +.. c:macro:: NPY_LITTLE_ENDIAN -.. c:var:: NPY_BIG_ENDIAN +.. c:macro:: NPY_BIG_ENDIAN -.. c:var:: NPY_BYTE_ORDER +.. c:macro:: NPY_BYTE_ORDER .. versionadded:: 1.3.0 @@ -94,7 +97,7 @@ Platform information Defined in ``numpy/npy_endian.h``. -.. c:function:: PyArray_GetEndianness() +.. c:function:: int PyArray_GetEndianness() .. versionadded:: 1.3.0 @@ -102,21 +105,27 @@ Platform information One of :c:data:`NPY_CPU_BIG`, :c:data:`NPY_CPU_LITTLE`, or :c:data:`NPY_CPU_UNKNOWN_ENDIAN`. + .. c:macro:: NPY_CPU_BIG + + .. c:macro:: NPY_CPU_LITTLE + + .. c:macro:: NPY_CPU_UNKNOWN_ENDIAN + Compiler directives ------------------- -.. c:var:: NPY_LIKELY -.. c:var:: NPY_UNLIKELY -.. c:var:: NPY_UNUSED +.. c:macro:: NPY_LIKELY +.. c:macro:: NPY_UNLIKELY +.. c:macro:: NPY_UNUSED Interrupt Handling ------------------ -.. c:var:: NPY_INTERRUPT_H -.. c:var:: NPY_SIGSETJMP -.. c:var:: NPY_SIGLONGJMP -.. c:var:: NPY_SIGJMP_BUF -.. c:var:: NPY_SIGINT_ON -.. c:var:: NPY_SIGINT_OFF +.. c:macro:: NPY_INTERRUPT_H +.. c:macro:: NPY_SIGSETJMP +.. c:macro:: NPY_SIGLONGJMP +.. c:macro:: NPY_SIGJMP_BUF +.. c:macro:: NPY_SIGINT_ON +.. c:macro:: NPY_SIGINT_OFF diff --git a/doc/source/reference/c-api/coremath.rst b/doc/source/reference/c-api/coremath.rst index 0c46475cf..338c584a1 100644 --- a/doc/source/reference/c-api/coremath.rst +++ b/doc/source/reference/c-api/coremath.rst @@ -24,23 +24,23 @@ in doubt. Floating point classification ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. c:var:: NPY_NAN +.. c:macro:: NPY_NAN This macro is defined to a NaN (Not a Number), and is guaranteed to have the signbit unset ('positive' NaN). The corresponding single and extension precision macro are available with the suffix F and L. -.. c:var:: NPY_INFINITY +.. c:macro:: NPY_INFINITY This macro is defined to a positive inf. The corresponding single and extension precision macro are available with the suffix F and L. -.. c:var:: NPY_PZERO +.. c:macro:: NPY_PZERO This macro is defined to positive zero. The corresponding single and extension precision macro are available with the suffix F and L. -.. c:var:: NPY_NZERO +.. c:macro:: NPY_NZERO This macro is defined to negative zero (that is with the sign bit set). The corresponding single and extension precision macro are available with the @@ -84,47 +84,47 @@ The following math constants are available in ``npy_math.h``. Single and extended precision are also available by adding the ``f`` and ``l`` suffixes respectively. -.. c:var:: NPY_E +.. c:macro:: NPY_E Base of natural logarithm (:math:`e`) -.. c:var:: NPY_LOG2E +.. c:macro:: NPY_LOG2E Logarithm to base 2 of the Euler constant (:math:`\frac{\ln(e)}{\ln(2)}`) -.. c:var:: NPY_LOG10E +.. c:macro:: NPY_LOG10E Logarithm to base 10 of the Euler constant (:math:`\frac{\ln(e)}{\ln(10)}`) -.. c:var:: NPY_LOGE2 +.. c:macro:: NPY_LOGE2 Natural logarithm of 2 (:math:`\ln(2)`) -.. c:var:: NPY_LOGE10 +.. c:macro:: NPY_LOGE10 Natural logarithm of 10 (:math:`\ln(10)`) -.. c:var:: NPY_PI +.. c:macro:: NPY_PI Pi (:math:`\pi`) -.. c:var:: NPY_PI_2 +.. c:macro:: NPY_PI_2 Pi divided by 2 (:math:`\frac{\pi}{2}`) -.. c:var:: NPY_PI_4 +.. c:macro:: NPY_PI_4 Pi divided by 4 (:math:`\frac{\pi}{4}`) -.. c:var:: NPY_1_PI +.. c:macro:: NPY_1_PI Reciprocal of pi (:math:`\frac{1}{\pi}`) -.. c:var:: NPY_2_PI +.. c:macro:: NPY_2_PI Two times the reciprocal of pi (:math:`\frac{2}{\pi}`) -.. c:var:: NPY_EULER +.. c:macro:: NPY_EULER The Euler constant :math:`\lim_{n\rightarrow\infty}({\sum_{k=1}^n{\frac{1}{k}}-\ln n})` @@ -308,35 +308,35 @@ __ https://en.wikipedia.org/wiki/Half-precision_floating-point_format __ https://www.khronos.org/registry/OpenGL/extensions/ARB/ARB_half_float_pixel.txt __ https://www.openexr.com/about.html -.. c:var:: NPY_HALF_ZERO +.. c:macro:: NPY_HALF_ZERO This macro is defined to positive zero. -.. c:var:: NPY_HALF_PZERO +.. c:macro:: NPY_HALF_PZERO This macro is defined to positive zero. -.. c:var:: NPY_HALF_NZERO +.. c:macro:: NPY_HALF_NZERO This macro is defined to negative zero. -.. c:var:: NPY_HALF_ONE +.. c:macro:: NPY_HALF_ONE This macro is defined to 1.0. -.. c:var:: NPY_HALF_NEGONE +.. c:macro:: NPY_HALF_NEGONE This macro is defined to -1.0. -.. c:var:: NPY_HALF_PINF +.. c:macro:: NPY_HALF_PINF This macro is defined to +inf. -.. c:var:: NPY_HALF_NINF +.. c:macro:: NPY_HALF_NINF This macro is defined to -inf. -.. c:var:: NPY_HALF_NAN +.. c:macro:: NPY_HALF_NAN This macro is defined to a NaN value, guaranteed to have its sign bit unset. diff --git a/doc/source/reference/c-api/deprecations.rst b/doc/source/reference/c-api/deprecations.rst index a382017a2..5b1abc6f2 100644 --- a/doc/source/reference/c-api/deprecations.rst +++ b/doc/source/reference/c-api/deprecations.rst @@ -48,7 +48,9 @@ warnings). To use the NPY_NO_DEPRECATED_API mechanism, you need to #define it to the target API version of NumPy before #including any NumPy headers. -If you want to confirm that your code is clean against 1.7, use:: +If you want to confirm that your code is clean against 1.7, use: + +.. code-block:: c #define NPY_NO_DEPRECATED_API NPY_1_7_API_VERSION diff --git a/doc/source/reference/c-api/dtype.rst b/doc/source/reference/c-api/dtype.rst index 72e908861..a1a53cdb6 100644 --- a/doc/source/reference/c-api/dtype.rst +++ b/doc/source/reference/c-api/dtype.rst @@ -30,7 +30,7 @@ Enumerated Types There is a list of enumerated types defined providing the basic 24 data types plus some useful generic names. Whenever the code requires a type number, one of these enumerated types is requested. The types -are all called :c:data:`NPY_{NAME}`: +are all called ``NPY_{NAME}``: .. c:var:: NPY_BOOL @@ -183,23 +183,23 @@ Some useful aliases of the above types are Other useful related constants are -.. c:var:: NPY_NTYPES +.. c:macro:: NPY_NTYPES The total number of built-in NumPy types. The enumeration covers the range from 0 to NPY_NTYPES-1. -.. c:var:: NPY_NOTYPE +.. c:macro:: NPY_NOTYPE A signal value guaranteed not to be a valid type enumeration number. -.. c:var:: NPY_USERDEF +.. c:macro:: NPY_USERDEF The start of type numbers used for Custom Data types. The various character codes indicating certain types are also part of an enumerated list. References to type characters (should they be needed at all) should always use these enumerations. The form of them -is :c:data:`NPY_{NAME}LTR` where ``{NAME}`` can be +is ``NPY_{NAME}LTR`` where ``{NAME}`` can be **BOOL**, **BYTE**, **UBYTE**, **SHORT**, **USHORT**, **INT**, **UINT**, **LONG**, **ULONG**, **LONGLONG**, **ULONGLONG**, @@ -221,24 +221,17 @@ Defines Max and min values for integers ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. c:var:: NPY_MAX_INT{bits} - -.. c:var:: NPY_MAX_UINT{bits} - -.. c:var:: NPY_MIN_INT{bits} - +``NPY_MAX_INT{bits}``, ``NPY_MAX_UINT{bits}``, ``NPY_MIN_INT{bits}`` These are defined for ``{bits}`` = 8, 16, 32, 64, 128, and 256 and provide the maximum (minimum) value of the corresponding (unsigned) integer type. Note: the actual integer type may not be available on all platforms (i.e. 128-bit and 256-bit integers are rare). -.. c:var:: NPY_MIN_{type} - +``NPY_MIN_{type}`` This is defined for ``{type}`` = **BYTE**, **SHORT**, **INT**, **LONG**, **LONGLONG**, **INTP** -.. c:var:: NPY_MAX_{type} - +``NPY_MAX_{type}`` This is defined for all defined for ``{type}`` = **BYTE**, **UBYTE**, **SHORT**, **USHORT**, **INT**, **UINT**, **LONG**, **ULONG**, **LONGLONG**, **ULONGLONG**, **INTP**, **UINTP** @@ -247,8 +240,8 @@ Max and min values for integers Number of bits in data types ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -All :c:data:`NPY_SIZEOF_{CTYPE}` constants have corresponding -:c:data:`NPY_BITSOF_{CTYPE}` constants defined. The :c:data:`NPY_BITSOF_{CTYPE}` +All ``NPY_SIZEOF_{CTYPE}`` constants have corresponding +``NPY_BITSOF_{CTYPE}`` constants defined. The ``NPY_BITSOF_{CTYPE}`` constants provide the number of bits in the data type. Specifically, the available ``{CTYPE}s`` are @@ -263,7 +256,7 @@ All of the numeric data types (integer, floating point, and complex) have constants that are defined to be a specific enumerated type number. Exactly which enumerated type a bit-width type refers to is platform dependent. In particular, the constants available are -:c:data:`PyArray_{NAME}{BITS}` where ``{NAME}`` is **INT**, **UINT**, +``PyArray_{NAME}{BITS}`` where ``{NAME}`` is **INT**, **UINT**, **FLOAT**, **COMPLEX** and ``{BITS}`` can be 8, 16, 32, 64, 80, 96, 128, 160, 192, 256, and 512. Obviously not all bit-widths are available on all platforms for all the kinds of numeric types. Commonly 8-, 16-, @@ -397,8 +390,8 @@ There are also typedefs for signed integers, unsigned integers, floating point, and complex floating point types of specific bit- widths. The available type names are - :c:type:`npy_int{bits}`, :c:type:`npy_uint{bits}`, :c:type:`npy_float{bits}`, - and :c:type:`npy_complex{bits}` + ``npy_int{bits}``, ``npy_uint{bits}``, ``npy_float{bits}``, + and ``npy_complex{bits}`` where ``{bits}`` is the number of bits in the type and can be **8**, **16**, **32**, **64**, 128, and 256 for integer types; 16, **32** @@ -414,6 +407,12 @@ Printf Formatting For help in printing, the following strings are defined as the correct format specifier in printf and related commands. - :c:data:`NPY_LONGLONG_FMT`, :c:data:`NPY_ULONGLONG_FMT`, - :c:data:`NPY_INTP_FMT`, :c:data:`NPY_UINTP_FMT`, - :c:data:`NPY_LONGDOUBLE_FMT` +.. c:macro:: NPY_LONGLONG_FMT + +.. c:macro:: NPY_ULONGLONG_FMT + +.. c:macro:: NPY_INTP_FMT + +.. c:macro:: NPY_UINTP_FMT + +.. c:macro:: NPY_LONGDOUBLE_FMT diff --git a/doc/source/reference/c-api/iterator.rst b/doc/source/reference/c-api/iterator.rst index b77d029cc..ae96bb3fb 100644 --- a/doc/source/reference/c-api/iterator.rst +++ b/doc/source/reference/c-api/iterator.rst @@ -313,17 +313,17 @@ Construction and Destruction Flags that may be passed in ``flags``, applying to the whole iterator, are: - .. c:var:: NPY_ITER_C_INDEX + .. c:macro:: NPY_ITER_C_INDEX Causes the iterator to track a raveled flat index matching C order. This option cannot be used with :c:data:`NPY_ITER_F_INDEX`. - .. c:var:: NPY_ITER_F_INDEX + .. c:macro:: NPY_ITER_F_INDEX Causes the iterator to track a raveled flat index matching Fortran order. This option cannot be used with :c:data:`NPY_ITER_C_INDEX`. - .. c:var:: NPY_ITER_MULTI_INDEX + .. c:macro:: NPY_ITER_MULTI_INDEX Causes the iterator to track a multi-index. This prevents the iterator from coalescing axes to @@ -336,7 +336,7 @@ Construction and Destruction However, it is possible to remove axes again and use the iterator normally if the size is small enough after removal. - .. c:var:: NPY_ITER_EXTERNAL_LOOP + .. c:macro:: NPY_ITER_EXTERNAL_LOOP Causes the iterator to skip iteration of the innermost loop, requiring the user of the iterator to handle it. @@ -344,7 +344,7 @@ Construction and Destruction This flag is incompatible with :c:data:`NPY_ITER_C_INDEX`, :c:data:`NPY_ITER_F_INDEX`, and :c:data:`NPY_ITER_MULTI_INDEX`. - .. c:var:: NPY_ITER_DONT_NEGATE_STRIDES + .. c:macro:: NPY_ITER_DONT_NEGATE_STRIDES This only affects the iterator when :c:type:`NPY_KEEPORDER` is specified for the order parameter. By default with @@ -355,7 +355,7 @@ Construction and Destruction but don't want an axis reversed. This is the behavior of ``numpy.ravel(a, order='K')``, for instance. - .. c:var:: NPY_ITER_COMMON_DTYPE + .. c:macro:: NPY_ITER_COMMON_DTYPE Causes the iterator to convert all the operands to a common data type, calculated based on the ufunc type promotion rules. @@ -364,7 +364,7 @@ Construction and Destruction If the common data type is known ahead of time, don't use this flag. Instead, set the requested dtype for all the operands. - .. c:var:: NPY_ITER_REFS_OK + .. c:macro:: NPY_ITER_REFS_OK Indicates that arrays with reference types (object arrays or structured arrays containing an object type) @@ -373,7 +373,7 @@ Construction and Destruction :c:func:`NpyIter_IterationNeedsAPI(iter)` is true, in which case it may not release the GIL during iteration. - .. c:var:: NPY_ITER_ZEROSIZE_OK + .. c:macro:: NPY_ITER_ZEROSIZE_OK Indicates that arrays with a size of zero should be permitted. Since the typical iteration loop does not naturally work with @@ -381,7 +381,7 @@ Construction and Destruction than zero before entering the iteration loop. Currently only the operands are checked, not a forced shape. - .. c:var:: NPY_ITER_REDUCE_OK + .. c:macro:: NPY_ITER_REDUCE_OK Permits writeable operands with a dimension with zero stride and size greater than one. Note that such operands @@ -400,7 +400,7 @@ Construction and Destruction after initializing the allocated operand to prepare the buffers. - .. c:var:: NPY_ITER_RANGED + .. c:macro:: NPY_ITER_RANGED Enables support for iteration of sub-ranges of the full ``iterindex`` range ``[0, NpyIter_IterSize(iter))``. Use @@ -414,7 +414,7 @@ Construction and Destruction would require special handling, effectively making it more like the buffered version. - .. c:var:: NPY_ITER_BUFFERED + .. c:macro:: NPY_ITER_BUFFERED Causes the iterator to store buffering data, and use buffering to satisfy data type, alignment, and byte-order requirements. @@ -441,7 +441,7 @@ Construction and Destruction the inner loops may become smaller depending on the structure of the reduction. - .. c:var:: NPY_ITER_GROWINNER + .. c:macro:: NPY_ITER_GROWINNER When buffering is enabled, this allows the size of the inner loop to grow when buffering isn't necessary. This option @@ -449,7 +449,7 @@ Construction and Destruction data, rather than anything with small cache-friendly arrays of temporary values for each inner loop. - .. c:var:: NPY_ITER_DELAY_BUFALLOC + .. c:macro:: NPY_ITER_DELAY_BUFALLOC When buffering is enabled, this delays allocation of the buffers until :c:func:`NpyIter_Reset` or another reset function is @@ -465,7 +465,7 @@ Construction and Destruction Then, call :c:func:`NpyIter_Reset` to allocate and fill the buffers with their initial values. - .. c:var:: NPY_ITER_COPY_IF_OVERLAP + .. c:macro:: NPY_ITER_COPY_IF_OVERLAP If any write operand has overlap with any read operand, eliminate all overlap by making temporary copies (enabling UPDATEIFCOPY for write @@ -484,9 +484,9 @@ Construction and Destruction Flags that may be passed in ``op_flags[i]``, where ``0 <= i < nop``: - .. c:var:: NPY_ITER_READWRITE - .. c:var:: NPY_ITER_READONLY - .. c:var:: NPY_ITER_WRITEONLY + .. c:macro:: NPY_ITER_READWRITE + .. c:macro:: NPY_ITER_READONLY + .. c:macro:: NPY_ITER_WRITEONLY Indicate how the user of the iterator will read or write to ``op[i]``. Exactly one of these flags must be specified @@ -495,13 +495,13 @@ Construction and Destruction semantics. The data will be written back to the original array when ``NpyIter_Deallocate`` is called. - .. c:var:: NPY_ITER_COPY + .. c:macro:: NPY_ITER_COPY Allow a copy of ``op[i]`` to be made if it does not meet the data type or alignment requirements as specified by the constructor flags and parameters. - .. c:var:: NPY_ITER_UPDATEIFCOPY + .. c:macro:: NPY_ITER_UPDATEIFCOPY Triggers :c:data:`NPY_ITER_COPY`, and when an array operand is flagged for writing and is copied, causes the data @@ -513,9 +513,9 @@ Construction and Destruction to back to ``op[i]`` on calling ``NpyIter_Deallocate``, instead of doing the unnecessary copy operation. - .. c:var:: NPY_ITER_NBO - .. c:var:: NPY_ITER_ALIGNED - .. c:var:: NPY_ITER_CONTIG + .. c:macro:: NPY_ITER_NBO + .. c:macro:: NPY_ITER_ALIGNED + .. c:macro:: NPY_ITER_CONTIG Causes the iterator to provide data for ``op[i]`` that is in native byte order, aligned according to @@ -534,7 +534,7 @@ Construction and Destruction the NBO flag overrides it and the requested data type is converted to be in native byte order. - .. c:var:: NPY_ITER_ALLOCATE + .. c:macro:: NPY_ITER_ALLOCATE This is for output arrays, and requires that the flag :c:data:`NPY_ITER_WRITEONLY` or :c:data:`NPY_ITER_READWRITE` @@ -557,7 +557,7 @@ Construction and Destruction getting the i-th object in the returned C array. The caller must call Py_INCREF on it to claim a reference to the array. - .. c:var:: NPY_ITER_NO_SUBTYPE + .. c:macro:: NPY_ITER_NO_SUBTYPE For use with :c:data:`NPY_ITER_ALLOCATE`, this flag disables allocating an array subtype for the output, forcing @@ -566,12 +566,12 @@ Construction and Destruction TODO: Maybe it would be better to introduce a function ``NpyIter_GetWrappedOutput`` and remove this flag? - .. c:var:: NPY_ITER_NO_BROADCAST + .. c:macro:: NPY_ITER_NO_BROADCAST Ensures that the input or output matches the iteration dimensions exactly. - .. c:var:: NPY_ITER_ARRAYMASK + .. c:macro:: NPY_ITER_ARRAYMASK .. versionadded:: 1.7 @@ -595,7 +595,7 @@ Construction and Destruction modified. This is useful when the mask should be a combination of input masks. - .. c:var:: NPY_ITER_WRITEMASKED + .. c:macro:: NPY_ITER_WRITEMASKED .. versionadded:: 1.7 @@ -613,7 +613,7 @@ Construction and Destruction returns true from the corresponding element in the ARRAYMASK operand. - .. c:var:: NPY_ITER_OVERLAP_ASSUME_ELEMENTWISE + .. c:macro:: NPY_ITER_OVERLAP_ASSUME_ELEMENTWISE In memory overlap checks, assume that operands with ``NPY_ITER_OVERLAP_ASSUME_ELEMENTWISE`` enabled are accessed only @@ -707,7 +707,7 @@ Construction and Destruction :c:func:`NpyIter_Deallocate` must be called for each copy. -.. c:function:: int NpyIter_RemoveAxis(NpyIter* iter, int axis)`` +.. c:function:: int NpyIter_RemoveAxis(NpyIter* iter, int axis) Removes an axis from iteration. This requires that :c:data:`NPY_ITER_MULTI_INDEX` was set for iterator creation, and does @@ -1264,7 +1264,7 @@ functions provide that information. NPY_MAX_INTP is placed in the stride. Once the iterator is prepared for iteration (after a reset if - :c:data:`NPY_DELAY_BUFALLOC` was used), call this to get the strides + :c:data:`NPY_ITER_DELAY_BUFALLOC` was used), call this to get the strides which may be used to select a fast inner loop function. For example, if the stride is 0, that means the inner loop can always load its value into a variable once, then use the variable throughout the loop, diff --git a/doc/source/reference/c-api/types-and-structures.rst b/doc/source/reference/c-api/types-and-structures.rst index 60d8e420b..6a9c4a9cf 100644 --- a/doc/source/reference/c-api/types-and-structures.rst +++ b/doc/source/reference/c-api/types-and-structures.rst @@ -26,7 +26,7 @@ By constructing a new Python type you make available a new object for Python. The ndarray object is an example of a new type defined in C. New types are defined in C by two basic steps: -1. creating a C-structure (usually named :c:type:`Py{Name}Object`) that is +1. creating a C-structure (usually named ``Py{Name}Object``) that is binary- compatible with the :c:type:`PyObject` structure itself but holds the additional information needed for that particular object; @@ -69,6 +69,7 @@ PyArray_Type and PyArrayObject typeobject. .. c:type:: PyArrayObject + NPY_AO The :c:type:`PyArrayObject` C-structure contains all of the required information for an array. All instances of an ndarray (and its @@ -77,7 +78,7 @@ PyArray_Type and PyArrayObject provided macros. If you need a shorter name, then you can make use of :c:type:`NPY_AO` (deprecated) which is defined to be equivalent to :c:type:`PyArrayObject`. Direct access to the struct fields are - deprecated. Use the `PyArray_*(arr)` form instead. + deprecated. Use the ``PyArray_*(arr)`` form instead. .. code-block:: c @@ -93,84 +94,84 @@ PyArray_Type and PyArrayObject PyObject *weakreflist; } PyArrayObject; -.. c:macro:: PyArrayObject.PyObject_HEAD + .. c:macro:: PyObject_HEAD - This is needed by all Python objects. It consists of (at least) - a reference count member ( ``ob_refcnt`` ) and a pointer to the - typeobject ( ``ob_type`` ). (Other elements may also be present - if Python was compiled with special options see - Include/object.h in the Python source tree for more - information). The ob_type member points to a Python type - object. + This is needed by all Python objects. It consists of (at least) + a reference count member ( ``ob_refcnt`` ) and a pointer to the + typeobject ( ``ob_type`` ). (Other elements may also be present + if Python was compiled with special options see + Include/object.h in the Python source tree for more + information). The ob_type member points to a Python type + object. -.. c:member:: char *PyArrayObject.data + .. c:member:: char *data - Accessible via :c:data:`PyArray_DATA`, this data member is a - pointer to the first element of the array. This pointer can - (and normally should) be recast to the data type of the array. + Accessible via :c:data:`PyArray_DATA`, this data member is a + pointer to the first element of the array. This pointer can + (and normally should) be recast to the data type of the array. -.. c:member:: int PyArrayObject.nd + .. c:member:: int nd - An integer providing the number of dimensions for this - array. When nd is 0, the array is sometimes called a rank-0 - array. Such arrays have undefined dimensions and strides and - cannot be accessed. Macro :c:data:`PyArray_NDIM` defined in - ``ndarraytypes.h`` points to this data member. :c:data:`NPY_MAXDIMS` - is the largest number of dimensions for any array. + An integer providing the number of dimensions for this + array. When nd is 0, the array is sometimes called a rank-0 + array. Such arrays have undefined dimensions and strides and + cannot be accessed. Macro :c:data:`PyArray_NDIM` defined in + ``ndarraytypes.h`` points to this data member. :c:data:`NPY_MAXDIMS` + is the largest number of dimensions for any array. -.. c:member:: npy_intp PyArrayObject.dimensions + .. c:member:: npy_intp dimensions - An array of integers providing the shape in each dimension as - long as nd :math:`\geq` 1. The integer is always large enough - to hold a pointer on the platform, so the dimension size is - only limited by memory. :c:data:`PyArray_DIMS` is the macro - associated with this data member. + An array of integers providing the shape in each dimension as + long as nd :math:`\geq` 1. The integer is always large enough + to hold a pointer on the platform, so the dimension size is + only limited by memory. :c:data:`PyArray_DIMS` is the macro + associated with this data member. -.. c:member:: npy_intp *PyArrayObject.strides + .. c:member:: npy_intp *strides - An array of integers providing for each dimension the number of - bytes that must be skipped to get to the next element in that - dimension. Associated with macro :c:data:`PyArray_STRIDES`. + An array of integers providing for each dimension the number of + bytes that must be skipped to get to the next element in that + dimension. Associated with macro :c:data:`PyArray_STRIDES`. -.. c:member:: PyObject *PyArrayObject.base + .. c:member:: PyObject *base - Pointed to by :c:data:`PyArray_BASE`, this member is used to hold a - pointer to another Python object that is related to this array. - There are two use cases: + Pointed to by :c:data:`PyArray_BASE`, this member is used to hold a + pointer to another Python object that is related to this array. + There are two use cases: - - If this array does not own its own memory, then base points to the - Python object that owns it (perhaps another array object) - - If this array has the (deprecated) :c:data:`NPY_ARRAY_UPDATEIFCOPY` or - :c:data:`NPY_ARRAY_WRITEBACKIFCOPY` flag set, then this array is a working - copy of a "misbehaved" array. + - If this array does not own its own memory, then base points to the + Python object that owns it (perhaps another array object) + - If this array has the (deprecated) :c:data:`NPY_ARRAY_UPDATEIFCOPY` or + :c:data:`NPY_ARRAY_WRITEBACKIFCOPY` flag set, then this array is a working + copy of a "misbehaved" array. - When ``PyArray_ResolveWritebackIfCopy`` is called, the array pointed to - by base will be updated with the contents of this array. + When ``PyArray_ResolveWritebackIfCopy`` is called, the array pointed to + by base will be updated with the contents of this array. -.. c:member:: PyArray_Descr *PyArrayObject.descr + .. c:member:: PyArray_Descr *descr - A pointer to a data-type descriptor object (see below). The - data-type descriptor object is an instance of a new built-in - type which allows a generic description of memory. There is a - descriptor structure for each data type supported. This - descriptor structure contains useful information about the type - as well as a pointer to a table of function pointers to - implement specific functionality. As the name suggests, it is - associated with the macro :c:data:`PyArray_DESCR`. + A pointer to a data-type descriptor object (see below). The + data-type descriptor object is an instance of a new built-in + type which allows a generic description of memory. There is a + descriptor structure for each data type supported. This + descriptor structure contains useful information about the type + as well as a pointer to a table of function pointers to + implement specific functionality. As the name suggests, it is + associated with the macro :c:data:`PyArray_DESCR`. -.. c:member:: int PyArrayObject.flags + .. c:member:: int flags - Pointed to by the macro :c:data:`PyArray_FLAGS`, this data member represents - the flags indicating how the memory pointed to by data is to be - interpreted. Possible flags are :c:data:`NPY_ARRAY_C_CONTIGUOUS`, - :c:data:`NPY_ARRAY_F_CONTIGUOUS`, :c:data:`NPY_ARRAY_OWNDATA`, - :c:data:`NPY_ARRAY_ALIGNED`, :c:data:`NPY_ARRAY_WRITEABLE`, - :c:data:`NPY_ARRAY_WRITEBACKIFCOPY`, and :c:data:`NPY_ARRAY_UPDATEIFCOPY`. + Pointed to by the macro :c:data:`PyArray_FLAGS`, this data member represents + the flags indicating how the memory pointed to by data is to be + interpreted. Possible flags are :c:data:`NPY_ARRAY_C_CONTIGUOUS`, + :c:data:`NPY_ARRAY_F_CONTIGUOUS`, :c:data:`NPY_ARRAY_OWNDATA`, + :c:data:`NPY_ARRAY_ALIGNED`, :c:data:`NPY_ARRAY_WRITEABLE`, + :c:data:`NPY_ARRAY_WRITEBACKIFCOPY`, and :c:data:`NPY_ARRAY_UPDATEIFCOPY`. -.. c:member:: PyObject *PyArrayObject.weakreflist + .. c:member:: PyObject *weakreflist - This member allows array objects to have weak references (using the - weakref module). + This member allows array objects to have weak references (using the + weakref module). PyArrayDescr_Type and PyArray_Descr @@ -226,197 +227,196 @@ PyArrayDescr_Type and PyArray_Descr npy_hash_t hash; } PyArray_Descr; -.. c:member:: PyTypeObject *PyArray_Descr.typeobj + .. c:member:: PyTypeObject *typeobj - Pointer to a typeobject that is the corresponding Python type for - the elements of this array. For the builtin types, this points to - the corresponding array scalar. For user-defined types, this - should point to a user-defined typeobject. This typeobject can - either inherit from array scalars or not. If it does not inherit - from array scalars, then the :c:data:`NPY_USE_GETITEM` and - :c:data:`NPY_USE_SETITEM` flags should be set in the ``flags`` member. + Pointer to a typeobject that is the corresponding Python type for + the elements of this array. For the builtin types, this points to + the corresponding array scalar. For user-defined types, this + should point to a user-defined typeobject. This typeobject can + either inherit from array scalars or not. If it does not inherit + from array scalars, then the :c:data:`NPY_USE_GETITEM` and + :c:data:`NPY_USE_SETITEM` flags should be set in the ``flags`` member. -.. c:member:: char PyArray_Descr.kind + .. c:member:: char kind - A character code indicating the kind of array (using the array - interface typestring notation). A 'b' represents Boolean, a 'i' - represents signed integer, a 'u' represents unsigned integer, 'f' - represents floating point, 'c' represents complex floating point, 'S' - represents 8-bit zero-terminated bytes, 'U' represents 32-bit/character - unicode string, and 'V' represents arbitrary. + A character code indicating the kind of array (using the array + interface typestring notation). A 'b' represents Boolean, a 'i' + represents signed integer, a 'u' represents unsigned integer, 'f' + represents floating point, 'c' represents complex floating point, 'S' + represents 8-bit zero-terminated bytes, 'U' represents 32-bit/character + unicode string, and 'V' represents arbitrary. -.. c:member:: char PyArray_Descr.type + .. c:member:: char type - A traditional character code indicating the data type. + A traditional character code indicating the data type. -.. c:member:: char PyArray_Descr.byteorder + .. c:member:: char byteorder - A character indicating the byte-order: '>' (big-endian), '<' (little- - endian), '=' (native), '\|' (irrelevant, ignore). All builtin data- - types have byteorder '='. + A character indicating the byte-order: '>' (big-endian), '<' (little- + endian), '=' (native), '\|' (irrelevant, ignore). All builtin data- + types have byteorder '='. -.. c:member:: char PyArray_Descr.flags + .. c:member:: char flags - A data-type bit-flag that determines if the data-type exhibits object- - array like behavior. Each bit in this member is a flag which are named - as: + A data-type bit-flag that determines if the data-type exhibits object- + array like behavior. Each bit in this member is a flag which are named + as: - .. c:var:: NPY_ITEM_REFCOUNT + .. c:macro:: NPY_ITEM_REFCOUNT - Indicates that items of this data-type must be reference - counted (using :c:func:`Py_INCREF` and :c:func:`Py_DECREF` ). + Indicates that items of this data-type must be reference + counted (using :c:func:`Py_INCREF` and :c:func:`Py_DECREF` ). - .. c:var:: NPY_ITEM_HASOBJECT + .. c:macro:: NPY_ITEM_HASOBJECT - Same as :c:data:`NPY_ITEM_REFCOUNT`. + Same as :c:data:`NPY_ITEM_REFCOUNT`. - .. c:var:: NPY_LIST_PICKLE + .. c:macro:: NPY_LIST_PICKLE - Indicates arrays of this data-type must be converted to a list - before pickling. + Indicates arrays of this data-type must be converted to a list + before pickling. - .. c:var:: NPY_ITEM_IS_POINTER + .. c:macro:: NPY_ITEM_IS_POINTER - Indicates the item is a pointer to some other data-type + Indicates the item is a pointer to some other data-type - .. c:var:: NPY_NEEDS_INIT + .. c:macro:: NPY_NEEDS_INIT - Indicates memory for this data-type must be initialized (set - to 0) on creation. + Indicates memory for this data-type must be initialized (set + to 0) on creation. - .. c:var:: NPY_NEEDS_PYAPI + .. c:macro:: NPY_NEEDS_PYAPI - Indicates this data-type requires the Python C-API during - access (so don't give up the GIL if array access is going to - be needed). + Indicates this data-type requires the Python C-API during + access (so don't give up the GIL if array access is going to + be needed). - .. c:var:: NPY_USE_GETITEM + .. c:macro:: NPY_USE_GETITEM - On array access use the ``f->getitem`` function pointer - instead of the standard conversion to an array scalar. Must - use if you don't define an array scalar to go along with - the data-type. + On array access use the ``f->getitem`` function pointer + instead of the standard conversion to an array scalar. Must + use if you don't define an array scalar to go along with + the data-type. - .. c:var:: NPY_USE_SETITEM + .. c:macro:: NPY_USE_SETITEM - When creating a 0-d array from an array scalar use - ``f->setitem`` instead of the standard copy from an array - scalar. Must use if you don't define an array scalar to go - along with the data-type. + When creating a 0-d array from an array scalar use + ``f->setitem`` instead of the standard copy from an array + scalar. Must use if you don't define an array scalar to go + along with the data-type. - .. c:var:: NPY_FROM_FIELDS + .. c:macro:: NPY_FROM_FIELDS - The bits that are inherited for the parent data-type if these - bits are set in any field of the data-type. Currently ( - :c:data:`NPY_NEEDS_INIT` \| :c:data:`NPY_LIST_PICKLE` \| - :c:data:`NPY_ITEM_REFCOUNT` \| :c:data:`NPY_NEEDS_PYAPI` ). + The bits that are inherited for the parent data-type if these + bits are set in any field of the data-type. Currently ( + :c:data:`NPY_NEEDS_INIT` \| :c:data:`NPY_LIST_PICKLE` \| + :c:data:`NPY_ITEM_REFCOUNT` \| :c:data:`NPY_NEEDS_PYAPI` ). - .. c:var:: NPY_OBJECT_DTYPE_FLAGS + .. c:macro:: NPY_OBJECT_DTYPE_FLAGS - Bits set for the object data-type: ( :c:data:`NPY_LIST_PICKLE` - \| :c:data:`NPY_USE_GETITEM` \| :c:data:`NPY_ITEM_IS_POINTER` \| - :c:data:`NPY_REFCOUNT` \| :c:data:`NPY_NEEDS_INIT` \| - :c:data:`NPY_NEEDS_PYAPI`). + Bits set for the object data-type: ( :c:data:`NPY_LIST_PICKLE` + \| :c:data:`NPY_USE_GETITEM` \| :c:data:`NPY_ITEM_IS_POINTER` \| + :c:data:`NPY_ITEM_REFCOUNT` \| :c:data:`NPY_NEEDS_INIT` \| + :c:data:`NPY_NEEDS_PYAPI`). - .. c:function:: PyDataType_FLAGCHK(PyArray_Descr *dtype, int flags) + .. c:function:: int PyDataType_FLAGCHK(PyArray_Descr *dtype, int flags) - Return true if all the given flags are set for the data-type - object. + Return true if all the given flags are set for the data-type + object. - .. c:function:: PyDataType_REFCHK(PyArray_Descr *dtype) + .. c:function:: int PyDataType_REFCHK(PyArray_Descr *dtype) - Equivalent to :c:func:`PyDataType_FLAGCHK` (*dtype*, - :c:data:`NPY_ITEM_REFCOUNT`). + Equivalent to :c:func:`PyDataType_FLAGCHK` (*dtype*, + :c:data:`NPY_ITEM_REFCOUNT`). -.. c:member:: int PyArray_Descr.type_num + .. c:member:: int type_num - A number that uniquely identifies the data type. For new data-types, - this number is assigned when the data-type is registered. + A number that uniquely identifies the data type. For new data-types, + this number is assigned when the data-type is registered. -.. c:member:: int PyArray_Descr.elsize + .. c:member:: int elsize - For data types that are always the same size (such as long), this - holds the size of the data type. For flexible data types where - different arrays can have a different elementsize, this should be - 0. + For data types that are always the same size (such as long), this + holds the size of the data type. For flexible data types where + different arrays can have a different elementsize, this should be + 0. -.. c:member:: int PyArray_Descr.alignment + .. c:member:: int alignment - A number providing alignment information for this data type. - Specifically, it shows how far from the start of a 2-element - structure (whose first element is a ``char`` ), the compiler - places an item of this type: ``offsetof(struct {char c; type v;}, - v)`` + A number providing alignment information for this data type. + Specifically, it shows how far from the start of a 2-element + structure (whose first element is a ``char`` ), the compiler + places an item of this type: ``offsetof(struct {char c; type v;}, + v)`` -.. c:member:: PyArray_ArrayDescr *PyArray_Descr.subarray + .. c:member:: PyArray_ArrayDescr *subarray - If this is non- ``NULL``, then this data-type descriptor is a - C-style contiguous array of another data-type descriptor. In - other-words, each element that this descriptor describes is - actually an array of some other base descriptor. This is most - useful as the data-type descriptor for a field in another - data-type descriptor. The fields member should be ``NULL`` if this - is non- ``NULL`` (the fields member of the base descriptor can be - non- ``NULL`` however). The :c:type:`PyArray_ArrayDescr` structure is - defined using + If this is non- ``NULL``, then this data-type descriptor is a + C-style contiguous array of another data-type descriptor. In + other-words, each element that this descriptor describes is + actually an array of some other base descriptor. This is most + useful as the data-type descriptor for a field in another + data-type descriptor. The fields member should be ``NULL`` if this + is non- ``NULL`` (the fields member of the base descriptor can be + non- ``NULL`` however). - .. code-block:: c - - typedef struct { - PyArray_Descr *base; - PyObject *shape; - } PyArray_ArrayDescr; + .. c:type:: PyArray_ArrayDescr - The elements of this structure are: + .. code-block:: c - .. c:member:: PyArray_Descr *PyArray_ArrayDescr.base + typedef struct { + PyArray_Descr *base; + PyObject *shape; + } PyArray_ArrayDescr; - The data-type-descriptor object of the base-type. + .. c:member:: PyArray_Descr *base - .. c:member:: PyObject *PyArray_ArrayDescr.shape + The data-type-descriptor object of the base-type. - The shape (always C-style contiguous) of the sub-array as a Python - tuple. + .. c:member:: PyObject *shape + The shape (always C-style contiguous) of the sub-array as a Python + tuple. -.. c:member:: PyObject *PyArray_Descr.fields + .. c:member:: PyObject *fields - If this is non-NULL, then this data-type-descriptor has fields - described by a Python dictionary whose keys are names (and also - titles if given) and whose values are tuples that describe the - fields. Recall that a data-type-descriptor always describes a - fixed-length set of bytes. A field is a named sub-region of that - total, fixed-length collection. A field is described by a tuple - composed of another data- type-descriptor and a byte - offset. Optionally, the tuple may contain a title which is - normally a Python string. These tuples are placed in this - dictionary keyed by name (and also title if given). + If this is non-NULL, then this data-type-descriptor has fields + described by a Python dictionary whose keys are names (and also + titles if given) and whose values are tuples that describe the + fields. Recall that a data-type-descriptor always describes a + fixed-length set of bytes. A field is a named sub-region of that + total, fixed-length collection. A field is described by a tuple + composed of another data- type-descriptor and a byte + offset. Optionally, the tuple may contain a title which is + normally a Python string. These tuples are placed in this + dictionary keyed by name (and also title if given). -.. c:member:: PyObject *PyArray_Descr.names + .. c:member:: PyObject *names - An ordered tuple of field names. It is NULL if no field is - defined. + An ordered tuple of field names. It is NULL if no field is + defined. -.. c:member:: PyArray_ArrFuncs *PyArray_Descr.f + .. c:member:: PyArray_ArrFuncs *f - A pointer to a structure containing functions that the type needs - to implement internal features. These functions are not the same - thing as the universal functions (ufuncs) described later. Their - signatures can vary arbitrarily. + A pointer to a structure containing functions that the type needs + to implement internal features. These functions are not the same + thing as the universal functions (ufuncs) described later. Their + signatures can vary arbitrarily. -.. c:member:: PyObject *PyArray_Descr.metadata + .. c:member:: PyObject *metadata - Metadata about this dtype. + Metadata about this dtype. -.. c:member:: NpyAuxData *PyArray_Descr.c_metadata + .. c:member:: NpyAuxData *c_metadata - Metadata specific to the C implementation - of the particular dtype. Added for NumPy 1.7.0. + Metadata specific to the C implementation + of the particular dtype. Added for NumPy 1.7.0. -.. c:member:: Npy_hash_t *PyArray_Descr.hash + .. c:type:: npy_hash_t + .. c:member:: npy_hash_t *hash - Currently unused. Reserved for future use in caching - hash values. + Currently unused. Reserved for future use in caching + hash values. .. c:type:: PyArray_ArrFuncs @@ -568,7 +568,7 @@ PyArrayDescr_Type and PyArray_Descr This function should be called without holding the Python GIL, and has to grab it for error reporting. - .. c:member:: Bool nonzero(void* data, void* arr) + .. c:member:: npy_bool nonzero(void* data, void* arr) A pointer to a function that returns TRUE if the item of ``arr`` pointed to by ``data`` is nonzero. This function can @@ -612,7 +612,8 @@ PyArrayDescr_Type and PyArray_Descr Either ``NULL`` or a dictionary containing low-level casting functions for user- defined data-types. Each function is - wrapped in a :c:type:`PyCObject *` and keyed by the data-type number. + wrapped in a :c:type:`PyCapsule *<PyCapsule>` and keyed by + the data-type number. .. c:member:: NPY_SCALARKIND scalarkind(PyArrayObject* arr) @@ -791,35 +792,37 @@ PyUFunc_Type and PyUFuncObject npy_uint32 *iter_flags; /* new in API version 0x0000000D */ npy_intp *core_dim_sizes; - npy_intp *core_dim_flags; - + npy_uint32 *core_dim_flags; + PyObject *identity_value; } PyUFuncObject; - .. c:macro: PyUFuncObject.PyObject_HEAD + .. c:macro: PyObject_HEAD required for all Python objects. - .. c:member:: int PyUFuncObject.nin + .. c:member:: int nin The number of input arguments. - .. c:member:: int PyUFuncObject.nout + .. c:member:: int nout The number of output arguments. - .. c:member:: int PyUFuncObject.nargs + .. c:member:: int nargs The total number of arguments (*nin* + *nout*). This must be less than :c:data:`NPY_MAXARGS`. - .. c:member:: int PyUFuncObject.identity + .. c:member:: int identity Either :c:data:`PyUFunc_One`, :c:data:`PyUFunc_Zero`, - :c:data:`PyUFunc_None` or :c:data:`PyUFunc_AllOnes` to indicate + :c:data:`PyUFunc_MinusOne`, :c:data:`PyUFunc_None`, + :c:data:`PyUFunc_ReorderableNone`, or + :c:data:`PyUFunc_IdentityValue` to indicate the identity for this operation. It is only used for a reduce-like call on an empty array. - .. c:member:: void PyUFuncObject.functions( \ + .. c:member:: void functions( \ char** args, npy_intp* dims, npy_intp* steps, void* extradata) An array of function pointers --- one for each data type @@ -837,7 +840,7 @@ PyUFunc_Type and PyUFuncObject passed in as *extradata*. The size of this function pointer array is ntypes. - .. c:member:: void **PyUFuncObject.data + .. c:member:: void **data Extra data to be passed to the 1-d vector loops or ``NULL`` if no extra-data is needed. This C-array must be the same size ( @@ -846,22 +849,22 @@ PyUFunc_Type and PyUFuncObject just 1-d vector loops that make use of this extra data to receive a pointer to the actual function to call. - .. c:member:: int PyUFuncObject.ntypes + .. c:member:: int ntypes The number of supported data types for the ufunc. This number specifies how many different 1-d loops (of the builtin data types) are available. - .. c:member:: int PyUFuncObject.reserved1 + .. c:member:: int reserved1 Unused. - .. c:member:: char *PyUFuncObject.name + .. c:member:: char *name A string name for the ufunc. This is used dynamically to build the __doc\__ attribute of ufuncs. - .. c:member:: char *PyUFuncObject.types + .. c:member:: char *types An array of :math:`nargs \times ntypes` 8-bit type_numbers which contains the type signature for the function for each of @@ -871,24 +874,24 @@ PyUFunc_Type and PyUFuncObject vector loop. These type numbers do not have to be the same type and mixed-type ufuncs are supported. - .. c:member:: char *PyUFuncObject.doc + .. c:member:: char *doc Documentation for the ufunc. Should not contain the function signature as this is generated dynamically when __doc\__ is retrieved. - .. c:member:: void *PyUFuncObject.ptr + .. c:member:: void *ptr Any dynamically allocated memory. Currently, this is used for dynamic ufuncs created from a python function to store room for the types, data, and name members. - .. c:member:: PyObject *PyUFuncObject.obj + .. c:member:: PyObject *obj For ufuncs dynamically created from python functions, this member holds a reference to the underlying Python function. - .. c:member:: PyObject *PyUFuncObject.userloops + .. c:member:: PyObject *userloops A dictionary of user-defined 1-d vector loops (stored as CObject ptrs) for user-defined types. A loop may be registered by the @@ -896,74 +899,85 @@ PyUFunc_Type and PyUFuncObject User defined type numbers are always larger than :c:data:`NPY_USERDEF`. - .. c:member:: int PyUFuncObject.core_enabled + .. c:member:: int core_enabled 0 for scalar ufuncs; 1 for generalized ufuncs - .. c:member:: int PyUFuncObject.core_num_dim_ix + .. c:member:: int core_num_dim_ix Number of distinct core dimension names in the signature - .. c:member:: int *PyUFuncObject.core_num_dims + .. c:member:: int *core_num_dims Number of core dimensions of each argument - .. c:member:: int *PyUFuncObject.core_dim_ixs + .. c:member:: int *core_dim_ixs Dimension indices in a flattened form; indices of argument ``k`` are stored in ``core_dim_ixs[core_offsets[k] : core_offsets[k] + core_numdims[k]]`` - .. c:member:: int *PyUFuncObject.core_offsets + .. c:member:: int *core_offsets Position of 1st core dimension of each argument in ``core_dim_ixs``, equivalent to cumsum(``core_num_dims``) - .. c:member:: char *PyUFuncObject.core_signature + .. c:member:: char *core_signature Core signature string - .. c:member:: PyUFunc_TypeResolutionFunc *PyUFuncObject.type_resolver + .. c:member:: PyUFunc_TypeResolutionFunc *type_resolver A function which resolves the types and fills an array with the dtypes for the inputs and outputs - .. c:member:: PyUFunc_LegacyInnerLoopSelectionFunc *PyUFuncObject.legacy_inner_loop_selector + .. c:member:: PyUFunc_LegacyInnerLoopSelectionFunc *legacy_inner_loop_selector A function which returns an inner loop. The ``legacy`` in the name arises because for NumPy 1.6 a better variant had been planned. This variant has not yet come about. - .. c:member:: void *PyUFuncObject.reserved2 + .. c:member:: void *reserved2 For a possible future loop selector with a different signature. - .. c:member:: PyUFunc_MaskedInnerLoopSelectionFunc *PyUFuncObject.masked_inner_loop_selector + .. c:member:: PyUFunc_MaskedInnerLoopSelectionFunc *masked_inner_loop_selector Function which returns a masked inner loop for the ufunc - .. c:member:: npy_uint32 PyUFuncObject.op_flags + .. c:member:: npy_uint32 op_flags Override the default operand flags for each ufunc operand. - .. c:member:: npy_uint32 PyUFuncObject.iter_flags + .. c:member:: npy_uint32 iter_flags Override the default nditer flags for the ufunc. Added in API version 0x0000000D - .. c:member:: npy_intp *PyUFuncObject.core_dim_sizes + .. c:member:: npy_intp *core_dim_sizes For each distinct core dimension, the possible - :ref:`frozen <frozen>` size if :c:data:`UFUNC_CORE_DIM_SIZE_INFERRED` is 0 + :ref:`frozen <frozen>` size if + :c:data:`UFUNC_CORE_DIM_SIZE_INFERRED` is ``0`` - .. c:member:: npy_uint32 *PyUFuncObject.core_dim_flags + .. c:member:: npy_uint32 *core_dim_flags For each distinct core dimension, a set of ``UFUNC_CORE_DIM*`` flags - - :c:data:`UFUNC_CORE_DIM_CAN_IGNORE` if the dim name ends in ``?`` - - :c:data:`UFUNC_CORE_DIM_SIZE_INFERRED` if the dim size will be - determined from the operands and not from a :ref:`frozen <frozen>` signature + .. c:macro:: UFUNC_CORE_DIM_CAN_IGNORE + + if the dim name ends in ``?`` + + .. c:macro:: UFUNC_CORE_DIM_SIZE_INFERRED + + if the dim size will be determined from the operands + and not from a :ref:`frozen <frozen>` signature + + .. c:member:: PyObject *identity_value + + Identity for reduction, when :c:member:`PyUFuncObject.identity` + is equal to :c:data:`PyUFunc_IdentityValue`. PyArrayIter_Type and PyArrayIterObject -------------------------------------- @@ -1009,57 +1023,57 @@ PyArrayIter_Type and PyArrayIterObject npy_intp factors[NPY_MAXDIMS]; PyArrayObject *ao; char *dataptr; - Bool contiguous; + npy_bool contiguous; } PyArrayIterObject; - .. c:member:: int PyArrayIterObject.nd_m1 + .. c:member:: int nd_m1 :math:`N-1` where :math:`N` is the number of dimensions in the underlying array. - .. c:member:: npy_intp PyArrayIterObject.index + .. c:member:: npy_intp index The current 1-d index into the array. - .. c:member:: npy_intp PyArrayIterObject.size + .. c:member:: npy_intp size The total size of the underlying array. - .. c:member:: npy_intp *PyArrayIterObject.coordinates + .. c:member:: npy_intp *coordinates An :math:`N` -dimensional index into the array. - .. c:member:: npy_intp *PyArrayIterObject.dims_m1 + .. c:member:: npy_intp *dims_m1 The size of the array minus 1 in each dimension. - .. c:member:: npy_intp *PyArrayIterObject.strides + .. c:member:: npy_intp *strides The strides of the array. How many bytes needed to jump to the next element in each dimension. - .. c:member:: npy_intp *PyArrayIterObject.backstrides + .. c:member:: npy_intp *backstrides How many bytes needed to jump from the end of a dimension back to its beginning. Note that ``backstrides[k] == strides[k] * dims_m1[k]``, but it is stored here as an optimization. - .. c:member:: npy_intp *PyArrayIterObject.factors + .. c:member:: npy_intp *factors This array is used in computing an N-d index from a 1-d index. It contains needed products of the dimensions. - .. c:member:: PyArrayObject *PyArrayIterObject.ao + .. c:member:: PyArrayObject *ao A pointer to the underlying ndarray this iterator was created to represent. - .. c:member:: char *PyArrayIterObject.dataptr + .. c:member:: char *dataptr This member points to an element in the ndarray indicated by the index. - .. c:member:: Bool PyArrayIterObject.contiguous + .. c:member:: npy_bool contiguous This flag is true if the underlying array is :c:data:`NPY_ARRAY_C_CONTIGUOUS`. It is used to simplify @@ -1106,32 +1120,32 @@ PyArrayMultiIter_Type and PyArrayMultiIterObject PyArrayIterObject *iters[NPY_MAXDIMS]; } PyArrayMultiIterObject; - .. c:macro: PyArrayMultiIterObject.PyObject_HEAD + .. c:macro: PyObject_HEAD Needed at the start of every Python object (holds reference count and type identification). - .. c:member:: int PyArrayMultiIterObject.numiter + .. c:member:: int numiter The number of arrays that need to be broadcast to the same shape. - .. c:member:: npy_intp PyArrayMultiIterObject.size + .. c:member:: npy_intp size The total broadcasted size. - .. c:member:: npy_intp PyArrayMultiIterObject.index + .. c:member:: npy_intp index The current (1-d) index into the broadcasted result. - .. c:member:: int PyArrayMultiIterObject.nd + .. c:member:: int nd The number of dimensions in the broadcasted result. - .. c:member:: npy_intp *PyArrayMultiIterObject.dimensions + .. c:member:: npy_intp *dimensions The shape of the broadcasted result (only ``nd`` slots are used). - .. c:member:: PyArrayIterObject **PyArrayMultiIterObject.iters + .. c:member:: PyArrayIterObject **iters An array of iterator objects that holds the iterators for the arrays to be broadcast together. On return, the iterators are @@ -1204,7 +1218,7 @@ ScalarArrayTypes There is a Python type for each of the different built-in data types that can be present in the array Most of these are simple wrappers around the corresponding data type in C. The C-names for these types -are :c:data:`Py{TYPE}ArrType_Type` where ``{TYPE}`` can be +are ``Py{TYPE}ArrType_Type`` where ``{TYPE}`` can be **Bool**, **Byte**, **Short**, **Int**, **Long**, **LongLong**, **UByte**, **UShort**, **UInt**, **ULong**, **ULongLong**, @@ -1213,8 +1227,8 @@ are :c:data:`Py{TYPE}ArrType_Type` where ``{TYPE}`` can be **Object**. These type names are part of the C-API and can therefore be created in -extension C-code. There is also a :c:data:`PyIntpArrType_Type` and a -:c:data:`PyUIntpArrType_Type` that are simple substitutes for one of the +extension C-code. There is also a ``PyIntpArrType_Type`` and a +``PyUIntpArrType_Type`` that are simple substitutes for one of the integer types that can hold a pointer on the platform. The structure of these scalar objects is not exposed to C-code. The function :c:func:`PyArray_ScalarAsCtype` (..) can be used to extract the C-type @@ -1249,12 +1263,12 @@ PyArray_Dims The members of this structure are - .. c:member:: npy_intp *PyArray_Dims.ptr + .. c:member:: npy_intp *ptr A pointer to a list of (:c:type:`npy_intp`) integers which usually represent array shape or array strides. - .. c:member:: int PyArray_Dims.len + .. c:member:: int len The length of the list of integers. It is assumed safe to access *ptr* [0] to *ptr* [len-1]. @@ -1283,26 +1297,26 @@ PyArray_Chunk The members are - .. c:macro: PyArray_Chunk.PyObject_HEAD + .. c:macro: PyObject_HEAD Necessary for all Python objects. Included here so that the :c:type:`PyArray_Chunk` structure matches that of the buffer object (at least to the len member). - .. c:member:: PyObject *PyArray_Chunk.base + .. c:member:: PyObject *base The Python object this chunk of memory comes from. Needed so that memory can be accounted for properly. - .. c:member:: void *PyArray_Chunk.ptr + .. c:member:: void *ptr A pointer to the start of the single-segment chunk of memory. - .. c:member:: npy_intp PyArray_Chunk.len + .. c:member:: npy_intp len The length of the segment in bytes. - .. c:member:: int PyArray_Chunk.flags + .. c:member:: int flags Any data flags (*e.g.* :c:data:`NPY_ARRAY_WRITEABLE` ) that should be used to interpret the memory. @@ -1317,13 +1331,13 @@ PyArrayInterface The :c:type:`PyArrayInterface` structure is defined so that NumPy and other extension modules can use the rapid array interface - protocol. The :obj:`__array_struct__` method of an object that + protocol. The :obj:`~object.__array_struct__` method of an object that supports the rapid array interface protocol should return a - :c:type:`PyCObject` that contains a pointer to a :c:type:`PyArrayInterface` + :c:type:`PyCapsule` that contains a pointer to a :c:type:`PyArrayInterface` structure with the relevant details of the array. After the new array is created, the attribute should be ``DECREF``'d which will free the :c:type:`PyArrayInterface` structure. Remember to ``INCREF`` the - object (whose :obj:`__array_struct__` attribute was retrieved) and + object (whose :obj:`~object.__array_struct__` attribute was retrieved) and point the base member of the new :c:type:`PyArrayObject` to this same object. In this way the memory for the array will be managed correctly. @@ -1342,15 +1356,15 @@ PyArrayInterface PyObject *descr; } PyArrayInterface; - .. c:member:: int PyArrayInterface.two + .. c:member:: int two the integer 2 as a sanity check. - .. c:member:: int PyArrayInterface.nd + .. c:member:: int nd the number of dimensions in the array. - .. c:member:: char PyArrayInterface.typekind + .. c:member:: char typekind A character indicating what kind of array is present according to the typestring convention with 't' -> bitfield, 'b' -> Boolean, 'i' -> @@ -1358,11 +1372,11 @@ PyArrayInterface complex floating point, 'O' -> object, 'S' -> (byte-)string, 'U' -> unicode, 'V' -> void. - .. c:member:: int PyArrayInterface.itemsize + .. c:member:: int itemsize The number of bytes each item in the array requires. - .. c:member:: int PyArrayInterface.flags + .. c:member:: int flags Any of the bits :c:data:`NPY_ARRAY_C_CONTIGUOUS` (1), :c:data:`NPY_ARRAY_F_CONTIGUOUS` (2), :c:data:`NPY_ARRAY_ALIGNED` (0x100), @@ -1376,26 +1390,26 @@ PyArrayInterface structure is present (it will be ignored by objects consuming version 2 of the array interface). - .. c:member:: npy_intp *PyArrayInterface.shape + .. c:member:: npy_intp *shape An array containing the size of the array in each dimension. - .. c:member:: npy_intp *PyArrayInterface.strides + .. c:member:: npy_intp *strides An array containing the number of bytes to jump to get to the next element in each dimension. - .. c:member:: void *PyArrayInterface.data + .. c:member:: void *data A pointer *to* the first element of the array. - .. c:member:: PyObject *PyArrayInterface.descr + .. c:member:: PyObject *descr A Python object describing the data-type in more detail (same - as the *descr* key in :obj:`__array_interface__`). This can be + as the *descr* key in :obj:`~object.__array_interface__`). This can be ``NULL`` if *typekind* and *itemsize* provide enough information. This field is also ignored unless - :c:data:`ARR_HAS_DESCR` flag is on in *flags*. + :c:data:`NPY_ARR_HAS_DESCR` flag is on in *flags*. Internally used structures @@ -1433,7 +1447,7 @@ for completeness and assistance in understanding the code. Advanced indexing is handled with this Python type. It is simply a loose wrapper around the C-structure containing the variables needed for advanced array indexing. The associated C-structure, - :c:type:`PyArrayMapIterObject`, is useful if you are trying to + ``PyArrayMapIterObject``, is useful if you are trying to understand the advanced-index mapping code. It is defined in the ``arrayobject.h`` header. This type is not exposed to Python and could be replaced with a C-structure. As a Python type it takes diff --git a/doc/source/reference/c-api/ufunc.rst b/doc/source/reference/c-api/ufunc.rst index 16ddde58c..9eb70c3fb 100644 --- a/doc/source/reference/c-api/ufunc.rst +++ b/doc/source/reference/c-api/ufunc.rst @@ -10,28 +10,52 @@ UFunc API Constants --------- -.. c:var:: UFUNC_ERR_{HANDLER} +``UFUNC_ERR_{HANDLER}`` + .. c:macro:: UFUNC_ERR_IGNORE - ``{HANDLER}`` can be **IGNORE**, **WARN**, **RAISE**, or **CALL** + .. c:macro:: UFUNC_ERR_WARN -.. c:var:: UFUNC_{THING}_{ERR} + .. c:macro:: UFUNC_ERR_RAISE - ``{THING}`` can be **MASK**, **SHIFT**, or **FPE**, and ``{ERR}`` can - be **DIVIDEBYZERO**, **OVERFLOW**, **UNDERFLOW**, and **INVALID**. + .. c:macro:: UFUNC_ERR_CALL -.. c:var:: PyUFunc_{VALUE} +``UFUNC_{THING}_{ERR}`` + .. c:macro:: UFUNC_MASK_DIVIDEBYZERO - .. c:var:: PyUFunc_One + .. c:macro:: UFUNC_MASK_OVERFLOW - .. c:var:: PyUFunc_Zero + .. c:macro:: UFUNC_MASK_UNDERFLOW - .. c:var:: PyUFunc_MinusOne + .. c:macro:: UFUNC_MASK_INVALID - .. c:var:: PyUFunc_ReorderableNone + .. c:macro:: UFUNC_SHIFT_DIVIDEBYZERO - .. c:var:: PyUFunc_None + .. c:macro:: UFUNC_SHIFT_OVERFLOW - .. c:var:: PyUFunc_IdentityValue + .. c:macro:: UFUNC_SHIFT_UNDERFLOW + + .. c:macro:: UFUNC_SHIFT_INVALID + + .. c:macro:: UFUNC_FPE_DIVIDEBYZERO + + .. c:macro:: UFUNC_FPE_OVERFLOW + + .. c:macro:: UFUNC_FPE_UNDERFLOW + + .. c:macro:: UFUNC_FPE_INVALID + +``PyUFunc_{VALUE}`` + .. c:macro:: PyUFunc_One + + .. c:macro:: PyUFunc_Zero + + .. c:macro:: PyUFunc_MinusOne + + .. c:macro:: PyUFunc_ReorderableNone + + .. c:macro:: PyUFunc_None + + .. c:macro:: PyUFunc_IdentityValue Macros @@ -50,6 +74,66 @@ Macros was released (because loop->obj was not true). +Types +----- + +.. c:type:: PyUFuncGenericFunction + + pointers to functions that actually implement the underlying + (element-by-element) function :math:`N` times with the following + signature: + + .. c:function:: void loopfunc(\ + char** args, npy_intp const *dimensions, npy_intp const *steps, void* data) + + *args* + + An array of pointers to the actual data for the input and output + arrays. The input arguments are given first followed by the output + arguments. + + *dimensions* + + A pointer to the size of the dimension over which this function is + looping. + + *steps* + + A pointer to the number of bytes to jump to get to the + next element in this dimension for each of the input and + output arguments. + + *data* + + Arbitrary data (extra arguments, function names, *etc.* ) + that can be stored with the ufunc and will be passed in + when it is called. + + This is an example of a func specialized for addition of doubles + returning doubles. + + .. code-block:: c + + static void + double_add(char **args, + npy_intp const *dimensions, + npy_intp const *steps, + void *extra) + { + npy_intp i; + npy_intp is1 = steps[0], is2 = steps[1]; + npy_intp os = steps[2], n = dimensions[0]; + char *i1 = args[0], *i2 = args[1], *op = args[2]; + for (i = 0; i < n; i++) { + *((double *)op) = *((double *)i1) + + *((double *)i2); + i1 += is1; + i2 += is2; + op += os; + } + } + + Functions --------- @@ -71,60 +155,7 @@ Functions :param func: Must to an array of length *ntypes* containing - :c:type:`PyUFuncGenericFunction` items. These items are pointers to - functions that actually implement the underlying - (element-by-element) function :math:`N` times with the following - signature: - - .. c:function:: void loopfunc( - char** args, npy_intp const *dimensions, npy_intp const *steps, void* data) - - *args* - - An array of pointers to the actual data for the input and output - arrays. The input arguments are given first followed by the output - arguments. - - *dimensions* - - A pointer to the size of the dimension over which this function is - looping. - - *steps* - - A pointer to the number of bytes to jump to get to the - next element in this dimension for each of the input and - output arguments. - - *data* - - Arbitrary data (extra arguments, function names, *etc.* ) - that can be stored with the ufunc and will be passed in - when it is called. - - This is an example of a func specialized for addition of doubles - returning doubles. - - .. code-block:: c - - static void - double_add(char **args, - npy_intp const *dimensions, - npy_intp const *steps, - void *extra) - { - npy_intp i; - npy_intp is1 = steps[0], is2 = steps[1]; - npy_intp os = steps[2], n = dimensions[0]; - char *i1 = args[0], *i2 = args[1], *op = args[2]; - for (i = 0; i < n; i++) { - *((double *)op) = *((double *)i1) + - *((double *)i2); - i1 += is1; - i2 += is2; - op += os; - } - } + :c:type:`PyUFuncGenericFunction` items. :param data: Should be ``NULL`` or a pointer to an array of size *ntypes* @@ -269,7 +300,7 @@ Functions .. c:function:: int PyUFunc_checkfperr(int errmask, PyObject* errobj) A simple interface to the IEEE error-flag checking support. The - *errmask* argument is a mask of :c:data:`UFUNC_MASK_{ERR}` bitmasks + *errmask* argument is a mask of ``UFUNC_MASK_{ERR}`` bitmasks indicating which errors to check for (and how to check for them). The *errobj* must be a Python tuple with two elements: a string containing the name which will be used in any communication @@ -459,9 +490,9 @@ structure. Importing the API ----------------- -.. c:var:: PY_UFUNC_UNIQUE_SYMBOL +.. c:macro:: PY_UFUNC_UNIQUE_SYMBOL -.. c:var:: NO_IMPORT_UFUNC +.. c:macro:: NO_IMPORT_UFUNC .. c:function:: void import_ufunc(void) |