diff options
| -rw-r--r-- | doc/CAPI.rst.txt | 124 | ||||
| -rw-r--r-- | doc/source/reference/c-api.array.rst | 22 | ||||
| -rw-r--r-- | doc/source/reference/c-api.dtype.rst | 2 |
3 files changed, 19 insertions, 129 deletions
diff --git a/doc/CAPI.rst.txt b/doc/CAPI.rst.txt index ccee0fdb6..3d270b962 100644 --- a/doc/CAPI.rst.txt +++ b/doc/CAPI.rst.txt @@ -10,134 +10,10 @@ __ https://scipy.org/scipylib/mailing-lists.html The C API of NumPy is (mostly) backward compatible with Numeric. -There are a few non-standard Numeric usages (that were not really part -of the API) that will need to be changed: - -* If you used any of the function pointers in the ``PyArray_Descr`` - structure you will have to modify your usage of those. First, - the pointers are all under the member named ``f``. So ``descr->cast`` - is now ``descr->f->cast``. In addition, the - casting functions have eliminated the strides argument (use - ``PyArray_CastTo`` if you need strided casting). All functions have - one or two ``PyArrayObject *`` arguments at the end. This allows the - flexible arrays and mis-behaved arrays to be handled. - -* The ``descr->zero`` and ``descr->one`` constants have been replaced with - function calls, ``PyArray_Zero``, and ``PyArray_One`` (be sure to read the - code and free the resulting memory if you use these calls). - -* If you passed ``array->dimensions`` and ``array->strides`` around - to functions, you will need to fix some code. These are now - ``npy_intp*`` pointers. On 32-bit systems there won't be a problem. - However, on 64-bit systems, you will need to make changes to avoid - errors and segfaults. - - -The header files ``arrayobject.h`` and ``ufuncobject.h`` contain many defines -that you may find useful. The files ``__ufunc_api.h`` and -``__multiarray_api.h`` contain the available C-API function calls with -their function signatures. - All of these headers are installed to ``<YOUR_PYTHON_LOCATION>/site-packages/numpy/core/include`` -Getting arrays in C-code -========================= - -All new arrays can be created using ``PyArray_NewFromDescr``. A simple interface -equivalent to ``PyArray_FromDims`` is ``PyArray_SimpleNew(nd, dims, typenum)`` -and to ``PyArray_FromDimsAndData`` is -``PyArray_SimpleNewFromData(nd, dims, typenum, data)``. - -This is a very flexible function. - -:: - - PyObject * PyArray_NewFromDescr(PyTypeObject *subtype, PyArray_Descr *descr, - int nd, npy_intp *dims, - npy_intp *strides, char *data, - int flags, PyObject *obj); - -``subtype`` : ``PyTypeObject *`` - The subtype that should be created (either pass in - ``&PyArray_Type``, or ``obj->ob_type``, - where ``obj`` is an instance of a subtype (or subclass) of - ``PyArray_Type``). - -``descr`` : ``PyArray_Descr *`` - The type descriptor for the array. This is a Python object (this - function steals a reference to it). The easiest way to get one is - using ``PyArray_DescrFromType(<typenum>)``. If you want to use a - flexible size array, then you need to use - ``PyArray_DescrNewFromType(<flexible typenum>)`` and set its ``elsize`` - parameter to the desired size. The typenum in both of these cases - is one of the ``PyArray_XXXX`` enumerated types. - -``nd`` : ``int`` - The number of dimensions (<``MAX_DIMS``) - -``*dims`` : ``npy_intp *`` - A pointer to the size in each dimension. Information will be - copied from here. - -``*strides`` : ``npy_intp *`` - The strides this array should have. For new arrays created by this - routine, this should be ``NULL``. If you pass in memory for this array - to use, then you can pass in the strides information as well - (otherwise it will be created for you and default to C-contiguous - or Fortran contiguous). Any strides will be copied into the array - structure. Do not pass in bad strides information!!!! - - ``PyArray_CheckStrides(...)`` can help but you must call it if you are - unsure. You cannot pass in strides information when data is ``NULL`` - and this routine is creating its own memory. - -``*data`` : ``char *`` - ``NULL`` for creating brand-new memory. If you want this array to wrap - another memory area, then pass the pointer here. You are - responsible for deleting the memory in that case, but do not do so - until the new array object has been deleted. The best way to - handle that is to get the memory from another Python object, - ``INCREF`` that Python object after passing it's data pointer to this - routine, and set the ``->base`` member of the returned array to the - Python object. *You are responsible for* setting ``PyArray_BASE(ret)`` - to the base object. Failure to do so will create a memory leak. - - If you pass in a data buffer, the ``flags`` argument will be the flags - of the new array. If you create a new array, a non-zero flags - argument indicates that you want the array to be in Fortran order. - -``flags`` : ``int`` - Either the flags showing how to interpret the data buffer passed - in, or if a new array is created, nonzero to indicate a Fortran - order array. See below for an explanation of the flags. - -``obj`` : ``PyObject *`` - If subtypes is ``&PyArray_Type``, this argument is - ignored. Otherwise, the ``__array_finalize__`` method of the subtype - is called (if present) and passed this object. This is usually an - array of the type to be created (so the ``__array_finalize__`` method - must handle an array argument. But, it can be anything...) - -Note: The returned array object will be uninitialized unless the type is -``PyArray_OBJECT`` in which case the memory will be set to ``NULL``. - -``PyArray_SimpleNew(nd, dims, typenum)`` is a drop-in replacement for -``PyArray_FromDims`` (except it takes ``npy_intp*`` dims instead of ``int*`` dims -which matters on 64-bit systems) and it does not initialize the memory -to zero. - -``PyArray_SimpleNew`` is just a macro for ``PyArray_New`` with default arguments. -Use ``PyArray_FILLWBYTE(arr, 0)`` to fill with zeros. - -The ``PyArray_FromDims`` and family of functions are still available and -are loose wrappers around this function. These functions still take -``int *`` arguments. This should be fine on 32-bit systems, but on 64-bit -systems you may run into trouble if you frequently passed -``PyArray_FromDims`` the dimensions member of the old ``PyArrayObject`` structure -because ``sizeof(npy_intp) != sizeof(int)``. - Getting an arrayobject from an arbitrary Python object ====================================================== diff --git a/doc/source/reference/c-api.array.rst b/doc/source/reference/c-api.array.rst index 9265b1a97..d8c1dae97 100644 --- a/doc/source/reference/c-api.array.rst +++ b/doc/source/reference/c-api.array.rst @@ -202,7 +202,8 @@ From scratch PyTypeObject* subtype, PyArray_Descr* descr, int nd, npy_intp* dims, \ npy_intp* strides, void* data, int flags, PyObject* obj) - This function steals a reference to *descr*. + This function steals a reference to *descr*. The easiest way to get one + is using :c:func:`PyArray_DescrFromType`. This is the main array creation function. Most new arrays are created with this flexible function. @@ -216,9 +217,11 @@ From scratch :c:data:`&PyArray_Type<PyArray_Type>`, then *obj* is the object to pass to the :obj:`~numpy.class.__array_finalize__` method of the subclass. - If *data* is ``NULL``, then new memory will be allocated and *flags* - can be non-zero to indicate a Fortran-style contiguous array. If - *data* is not ``NULL``, then it is assumed to point to the memory + If *data* is ``NULL``, then new unitinialized memory will be allocated and + *flags* can be non-zero to indicate a Fortran-style contiguous array. Use + :c:ref:`PyArray_FILLWBYTE` to initialze the memory. + + If *data* is not ``NULL``, then it is assumed to point to the memory to be used for the array and the *flags* argument is used as the new flags for the array (except the state of :c:data:`NPY_OWNDATA`, :c:data:`NPY_ARRAY_WRITEBACKIFCOPY` and :c:data:`NPY_ARRAY_UPDATEIFCOPY` @@ -232,6 +235,12 @@ From scratch provided *dims* and *strides* are copied into newly allocated dimension and strides arrays for the new array object. + :c:func:`PyArray_CheckStrides` can help verify non- ``NULL`` stride + information. + + If ``data`` is provided, it must stay alive for the life of the array. One + way to manage this is through :c:func:`PyArray_SetBaseObject` + .. c:function:: PyObject* PyArray_NewLikeArray( \ PyArrayObject* prototype, NPY_ORDER order, PyArray_Descr* descr, \ int subok) @@ -2849,7 +2858,10 @@ Data-type descriptors Returns a data-type object corresponding to *typenum*. The *typenum* can be one of the enumerated types, a character code for - one of the enumerated types, or a user-defined type. + one of the enumerated types, or a user-defined type. If you want to use a + flexible size array, then you need to ``flexible typenum`` and set the + results ``elsize`` parameter to the desired size. The typenum is one of the + :c:data:`NPY_TYPES`. .. c:function:: int PyArray_DescrConverter(PyObject* obj, PyArray_Descr** dtype) diff --git a/doc/source/reference/c-api.dtype.rst b/doc/source/reference/c-api.dtype.rst index 8af3a9080..9ac46b284 100644 --- a/doc/source/reference/c-api.dtype.rst +++ b/doc/source/reference/c-api.dtype.rst @@ -25,6 +25,8 @@ select the precision desired. Enumerated Types ---------------- +.. c:var:: NPY_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 |