Skip to content

Commit db123e1

Browse files
author
Juan Zapien
committed
Fixing numpy#12261 PyArray_SimpleNew part
1 parent e8bd864 commit db123e1

1 file changed

Lines changed: 5 additions & 38 deletions

File tree

‎doc/source/user/c-info.how-to-extend.rst‎

Lines changed: 5 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -504,50 +504,17 @@ writeable). The syntax is
504504
Creating a brand-new ndarray
505505
----------------------------
506506
507-
Quite often new arrays must be created from within extension-module
507+
Quite often, new arrays must be created from within extension-module
508508
code. Perhaps an output array is needed and you don't want the caller
509509
to have to supply it. Perhaps only a temporary array is needed to hold
510-
an intermediate calculation. Whatever the need there are simple ways
510+
an intermediate calculation. Whatever the need, there are simple ways
511511
to get an ndarray object of whatever data-type is needed. The most
512512
general function for doing this is :c:func:`PyArray_NewFromDescr`. All array
513513
creation functions go through this heavily re-used code. Because of
514514
its flexibility, it can be somewhat confusing to use. As a result,
515-
simpler forms exist that are easier to use.
516-
517-
:c:func:`PyArray_SimpleNew`
518-
519-
This function allocates new memory and places it in an ndarray
520-
with *nd* dimensions whose shape is determined by the array of
521-
at least *nd* items pointed to by *dims*. The memory for the
522-
array is uninitialized (unless typenum is :c:data:`NPY_OBJECT` in
523-
which case each element in the array is set to NULL). The
524-
*typenum* argument allows specification of any of the builtin
525-
data-types such as :c:data:`NPY_FLOAT` or :c:data:`NPY_LONG`. The
526-
memory for the array can be set to zero if desired using
527-
:c:func:`PyArray_FILLWBYTE` (return_object, 0).
528-
529-
:c:func:`PyArray_SimpleNewFromData`
530-
531-
Sometimes, you want to wrap memory allocated elsewhere into an
532-
ndarray object for downstream use. This routine makes it
533-
straightforward to do that. The first three arguments are the same
534-
as in :c:func:`PyArray_SimpleNew`, the final argument is a pointer to a
535-
block of contiguous memory that the ndarray should use as it's
536-
data-buffer which will be interpreted in C-style contiguous
537-
fashion. A new reference to an ndarray is returned, but the
538-
ndarray will not own its data. When this ndarray is deallocated,
539-
the pointer will not be freed.
540-
541-
You should ensure that the provided memory is not freed while the
542-
returned array is in existence. The easiest way to handle this is
543-
if data comes from another reference-counted Python object. The
544-
reference count on this object should be increased after the
545-
pointer is passed in, and the base member of the returned ndarray
546-
should point to the Python object that owns the data. Then, when
547-
the ndarray is deallocated, the base-member will be DECREF'd
548-
appropriately. If you want the memory to be freed as soon as the
549-
ndarray is deallocated then simply set the OWNDATA flag on the
550-
returned ndarray.
515+
simpler forms exist that are easier to use. These forms are part of the
516+
:c:func:`PyArray_SimpleNew` family of functions, which are applied in specific
517+
situations.
551518
552519
553520
Getting at ndarray memory and accessing elements of the ndarray

0 commit comments

Comments
 (0)