numpy  2.0.0
src/multiarray/mapping.c File Reference
#include <Python.h>
#include "structmember.h"
#include "numpy/arrayobject.h"
#include "arrayobject.h"
#include "npy_config.h"
#include "npy_pycompat.h"
#include "npy_import.h"
#include "common.h"
#include "ctors.h"
#include "iterators.h"
#include "mapping.h"
#include "lowlevel_strided_loops.h"
#include "item_selection.h"

Defines

#define PY_SSIZE_T_CLEAN
#define NPY_NO_DEPRECATED_API   NPY_API_VERSION
#define _MULTIARRAYMODULE
#define HAS_INTEGER   1
#define HAS_NEWAXIS   2
#define HAS_SLICE   4
#define HAS_ELLIPSIS   8
#define HAS_FANCY   16
#define HAS_BOOL   32
#define HAS_SCALAR_ARRAY   64
#define HAS_0D_BOOL   (HAS_FANCY | 128)

Functions

static int _nonzero_indices (PyObject *myBool, PyArrayObject **arrays)
NPY_NO_EXPORT Py_ssize_t array_length (PyArrayObject *self)
NPY_NO_EXPORT void PyArray_MapIterSwapAxes (PyArrayMapIterObject *mit, PyArrayObject **ret, int getmap)
NPY_NO_EXPORT int prepare_index (PyArrayObject *self, PyObject *index, npy_index_info *indices, int *num, int *ndim, int *out_fancy_ndim, int allow_boolean)
static int get_item_pointer (PyArrayObject *self, char **ptr, npy_index_info *indices, int index_num)
static int get_view_from_index (PyArrayObject *self, PyArrayObject **view, npy_index_info *indices, int index_num, int ensure_array)
NPY_NO_EXPORT PyArrayObjectarray_boolean_subscript (PyArrayObject *self, PyArrayObject *bmask, NPY_ORDER order)
NPY_NO_EXPORT int array_assign_boolean_subscript (PyArrayObject *self, PyArrayObject *bmask, PyArrayObject *v, NPY_ORDER order)
NPY_NO_EXPORT PyObject * array_item_asarray (PyArrayObject *self, npy_intp i)
NPY_NO_EXPORT PyObject * array_item (PyArrayObject *self, Py_ssize_t i)
NPY_NO_EXPORT PyObject * array_subscript_asarray (PyArrayObject *self, PyObject *op)
NPY_NO_EXPORT int _get_field_view (PyArrayObject *arr, PyObject *ind, PyArrayObject **view)
NPY_NO_EXPORT PyObject * array_subscript (PyArrayObject *self, PyObject *op)
NPY_NO_EXPORT int array_assign_item (PyArrayObject *self, Py_ssize_t i, PyObject *op)
NPY_NO_EXPORT int attempt_1d_fallback (PyArrayObject *self, PyObject *ind, PyObject *op)
static int array_assign_subscript (PyArrayObject *self, PyObject *ind, PyObject *op)
NPY_NO_EXPORT void PyArray_MapIterReset (PyArrayMapIterObject *mit)
NPY_NO_EXPORT void PyArray_MapIterNext (PyArrayMapIterObject *mit)
static int mapiter_fill_info (PyArrayMapIterObject *mit, npy_index_info *indices, int index_num, PyArrayObject *arr)
NPY_NO_EXPORT int PyArray_MapIterCheckIndices (PyArrayMapIterObject *mit)
NPY_NO_EXPORT PyObject * PyArray_MapIterNew (npy_index_info *indices, int index_num, int index_type, int ndim, int fancy_ndim, PyArrayObject *arr, PyArrayObject *subspace, npy_uint32 subspace_iter_flags, npy_uint32 subspace_flags, npy_uint32 extra_op_flags, PyArrayObject *extra_op, PyArray_Descr *extra_op_dtype)
NPY_NO_EXPORT PyObject * PyArray_MapIterArray (PyArrayObject *a, PyObject *index)
static void arraymapiter_dealloc (PyArrayMapIterObject *mit)

Variables

NPY_NO_EXPORT PyMappingMethods array_as_mapping
NPY_NO_EXPORT PyTypeObject PyArrayMapIter_Type

Define Documentation

#define HAS_0D_BOOL   (HAS_FANCY | 128)
Indicate that this is a fancy index that comes from a 0d boolean. This means that the index does not operate along a real axis. The corresponding index type is just HAS_FANCY.
#define HAS_BOOL   32
#define HAS_FANCY   16
HAS_FANCY can be mixed with HAS_0D_BOOL, be careful when to use & or ==
#define HAS_NEWAXIS   2
#define HAS_SCALAR_ARRAY   64
NOTE: Only set if it is neither fancy nor purely integer index!
#define HAS_SLICE   4
#define NPY_NO_DEPRECATED_API   NPY_API_VERSION
#include <stdio.h>

Function Documentation

NPY_NO_EXPORT int _get_field_view ( PyArrayObject arr,
PyObject *  ind,
PyArrayObject **  view 
)
Attempts to subscript an array using a field name or list of field names.
If an error occurred, return 0 and set view to NULL. If the subscript is not a string or list of strings, return -1 and set view to NULL. Otherwise return 0 and set view to point to a new view into arr for the given fields.
first check for a single field name
get the field offset and dtype
view the array at the new offset+dtype
next check for a list of field names
variables needed to make a copy, to remove in the future
quit if have a 0-d array (seqlen==-1) or a 0-len array
only happens for strange sequence objects
Return copy for now (future plan to return the view above). All the following code in this block can then be replaced by "return 0;"
warn when writing to the copy
static int _nonzero_indices ( PyObject *  myBool,
PyArrayObject **  arrays 
) [static]
************ End of Mapping Protocol *************************
***************** Subscript Array Iterator *********************

<blockquote class="first">

</blockquote>

System Message: WARNING/2 (<string>, line 3) Block quote ends without a blank line; unexpected unindent.
This object handles subscript behavior for array objects. *

It is an iterator object with a next method * It abstracts the n-dimensional mapping behavior to make the looping *

System Message: ERROR/3 (<string>, line 6) Unexpected indentation.

<blockquote class="last"> code more understandable (maybe) * and so that indexing can be set up ahead of time *</blockquote>

This function takes a Boolean array and constructs index objects and iterators as if nonzero(Bool) had been called
Must not be called on a 0-d array.
pre-determine how many nonzero entries there are, ignore dimensionality of input as its a CARRAY
create count-sized index arrays for each dimension
Loop through the Boolean array and copy coordinates for non-zero entries
Borrowed from ITER_NEXT macro

References check_and_adjust_index(), data, NPY_BEGIN_THREADS, and PyArray_PREPARE_TRIVIAL_ITERATION.

Implements boolean indexing assignment. This takes the one-dimensional array 'v' and assigns its values to all of the elements of 'self' for which the corresponding element of 'op' is True.
This operation is somewhat unfortunate, because to match up with a one-dimensional output array, it has to choose a particular iteration order, in the case of NumPy that is always C order even though this function allows different choices.
Returns 0 on success, -1 on failure.
Correction factor for broadcasting 'bmask' to 'self'
Tweak the strides for 0-dim and broadcasting cases
Create an iterator for the data
Set up the iterator
Get the values needed for the inner loop
Get a dtype transfer function
Skip masked values
Process unmasked values
FIXME?: most assignment operations stop after the first occurrence of an error. Boolean does not currently, but should at least report the error. (This is only relevant for things like str->int casts which call into python)

References get_view_from_index(), HAS_ELLIPSIS, HAS_INTEGER, PyArray_DIM, PyArray_NDIM, npy_index_info::type, and npy_index_info::value.

NPY_NO_EXPORT int array_assign_item ( PyArrayObject self,
Py_ssize_t  i,
PyObject *  op 
)
Python C-Api level item assignment (implementation for PySequence_SetItem)
Negative indices are not accepted because PySequence_SetItem converts them to positive indices before calling this.
This is an error, but undo PySequence_SetItem fix for message

Referenced by array_contains().

static int array_assign_subscript ( PyArrayObject self,
PyObject *  ind,
PyObject *  op 
) [static]
General assignment with python indexing objects.
field access
Prepare the indices
Full integer index
integers do not store objects in indices
Single boolean array
Deprecated case. The old boolean indexing seemed to have some check to allow wrong dimensional boolean arrays in all cases.
Single ellipsis index, no need to create a new view. Note that here, we do not go through self.__getitem__ for subclasses (defchar array failed then, due to uninitialized values...)
CopyObject does not handle this case gracefully and there is nothing to do. Removing the special case will cause segfaults, though it is unclear what exactly happens.
we can just use self, but incref for error handling
WARNING: There is a huge special case here. If this is not a
base class array, we have to get the view through its very own index machinery. Many subclasses should probably call __setitem__ with a base class ndarray view to avoid this.
View based indexing. There are two cases here. First we need to create a simple view, second we need to create a (possibly invalid) view for the subspace to the fancy index. This procedure is identical.
If there is no fancy indexing, we have the array to assign to
If the array is of object converting the values to an array might not be legal even though normal assignment works. So allocate a temporary array of the right size and use the normal assignment to handle this case.
There is nothing fancy possible, so just make an array
Special case for very simple 1-d fancy indexing, which however is quite common. This saves not only a lot of setup time in the iterator, but also is faster (must be exactly fancy because we don't support 0-d booleans here)
The array being indexed has one dimension and it is a fancy index
Check if the type is equivalent
Either they are equivalent, or the values must be a scalar
Check if the type is equivalent to INTP
trivial_set checks the index for us
NOTE: If tmp_arr was not allocated yet, mit should
handle the allocation. The NPY_ITER_READWRITE is necessary for automatic allocation. Readwrite would not allow broadcasting correctly, but such an operand always has the full size anyway.
This is a deprecated special case to allow non-matching shapes for the index and value arrays.
This is not a "flat like" 1-d special case
Fill extra op, need to swap first
This is a deprecated special case to allow non-matching shapes for the index and value arrays.
This is not a "flat like" 1-d special case
Can now reset the outer iterator (delayed bufalloc)
Could add a casting check, but apparently most assignments do not care about safe casting.
Clean up temporary variables and indices
Implements boolean indexing. This produces a one-dimensional array which picks out all of the elements of 'self' for which the corresponding element of 'op' is True.
This operation is somewhat unfortunate, because to produce a one-dimensional output array, it has to choose a particular iteration order, in the case of NumPy that is always C order even though this function allows different choices.
Allocate the output of the boolean indexing
Create an iterator for the data
Set up the iterator
Get a dtype transfer function
Get the values needed for the inner loop
Skip masked values
Process unmasked values
NPY_NO_EXPORT PyObject* array_item ( PyArrayObject self,
Py_ssize_t  i 
)
Python C-Api level item subscription (implementation for PySequence_GetItem)
Negative indices are not accepted because PySequence_GetItem converts them to positive indices before calling this.
This is an error, but undo PySequence_GetItem fix for message

Referenced by array_contains().

NPY_NO_EXPORT PyObject* array_item_asarray ( PyArrayObject self,
npy_intp  i 
)
C-level integer indexing always returning an array and never a scalar. Works also for subclasses, but it will not be called on one from the Python API.
This function does not accept negative indices because it is called by PySequence_GetItem (through array_item) and that converts them to positive indices.
This is an error, but undo PySequence_GetItem fix for message
NPY_NO_EXPORT Py_ssize_t array_length ( PyArrayObject self)
System Message: SEVERE/4 (<string>, line 1)
Title overline & underline mismatch.

                    IMPLEMENT MAPPING PROTOCOL                          ***
 

References PyArrayMapIterObject::nd, NPY_ANYORDER, PyArray_Dims::ptr, PyArray_DIMS, PyArray_NDIM, and PyArray_Newshape().

Referenced by array_contains().

NPY_NO_EXPORT PyObject* array_subscript ( PyArrayObject self,
PyObject *  op 
)
General function for indexing a NumPy array with a Python object.
Index info array. We can have twice as many indices as dimensions (because of None). The + 1 is to not need to check as much.
return fields if op is a string index
warn if writing to a copy. copies will have no base
Prepare the indices
Full integer index
Because the index is full integer, we do not need to decref
Single boolean array
If it is only a single ellipsis, just return a view
TODO: Should this be a view or not? The only reason not would be
optimization (i.e. of array[...] += 1) I think. Before, it was just self for a single ellipsis.
A single ellipsis, so no need to decref
View based indexing. There are two cases here. First we need to create a simple view, second we need to create a (possibly invalid) view for the subspace to the fancy index. This procedure is identical.
There is a scalar array, so we need to force a copy to simulate fancy indexing.
If there is no fancy indexing, we have the result
Special case for very simple 1-d fancy indexing, which however is quite common. This saves not only a lot of setup time in the iterator, but also is faster (must be exactly fancy because we don't support 0-d booleans here)
The array being indexed has one dimension and it is a fancy index
Check if the index is simple enough
Check if the type is equivalent to INTP
Same order as indices
fancy indexing has to be used. And view is the subspace.
If it is one, the inner loop checks indices, otherwise check indices beforehand, because it is much faster if broadcasting occurs and most likely no big overhead
Reset the outer iterator
Need to create a new array as if the old one never existed.
Clean up indices

References get_item_pointer(), get_view_from_index(), HAS_ELLIPSIS, HAS_INTEGER, PyArray_CopyObject(), PyArray_DIM, PyArray_FailUnlessWriteable(), PyArray_NDIM, PyArray_SETITEM, npy_index_info::type, and npy_index_info::value.

NPY_NO_EXPORT PyObject* array_subscript_asarray ( PyArrayObject self,
PyObject *  op 
)
make sure subscript always returns an array object
static void arraymapiter_dealloc ( PyArrayMapIterObject mit) [static]
NPY_NO_EXPORT int attempt_1d_fallback ( PyArrayObject self,
PyObject *  ind,
PyObject *  op 
)
This fallback takes the old route of <cite>arr.flat[index] = values</cite> for one dimensional <cite>arr</cite>. The route can sometimes fail slightly differently (ValueError instead of IndexError), in which case we warn users about the change. But since it does not actually care at all about shapes, it should only fail for out of bound indexes or casting errors.
2014-06-12, 1.9
2014-06-12, 1.9
static int get_item_pointer ( PyArrayObject self,
char **  ptr,
npy_index_info indices,
int  index_num 
) [static]
Get pointer for an integer index.
For a purely integer index, set ptr to the memory address. Returns 0 on success, -1 on failure. The caller must ensure that the index is a full integer one.
&#64;param Array being indexed &#64;param result pointer &#64;param parsed index information &#64;param number of indices
&#64;return 0 on success -1 on failure

Referenced by array_subscript().

static int get_view_from_index ( PyArrayObject self,
PyArrayObject **  view,
npy_index_info indices,
int  index_num,
int  ensure_array 
) [static]
Get view into an array using all non-array indices.
For any index, get a view of the subspace into the original array. If there are no fancy indices, this is the result of the indexing operation. Ensure_array allows to fetch a safe subspace view for advanced indexing.
&#64;param Array being indexed &#64;param resulting array (new reference) &#64;param parsed index information &#64;param number of indices &#64;param Whether result should inherit the type from self
&#64;return 0 on success -1 on failure
for slice parsing
TODO: Always points to start then, could change that
Fancy and 0-d boolean indices are ignored here
Create the new view and set the base array

Referenced by array_assign_boolean_subscript(), and array_subscript().

static int mapiter_fill_info ( PyArrayMapIterObject mit,
npy_index_info indices,
int  index_num,
PyArrayObject arr 
) [static]
Fill information about the iterator. The MapIterObject does not need to have any information set for this function to work. (PyArray_MapIterSwapAxes requires also nd and nd_fancy info)

Sets the following information:
  • mit->consec: The axis where the fancy indices need transposing to.

  • mit->iteraxes: The axis which the fancy index corresponds to.

  • mit-> fancy_dims: the dimension of arr along the indexed dimension

    for each fancy index.

  • mit->fancy_strides: the strides for the dimension being indexed

    by each fancy index.

  • mit->dimensions: Broadcast dimension of the fancy indices and

    the subspace iteration dimension.

&#64;param MapIterObject &#64;param The parsed indices object &#64;param Number of indices &#64;param The array that is being iterated
&#64;return 0 on success -1 on failure
dimension of index result (up to first fancy index)
-1 init; 0 found fancy; 1 fancy stopped; 2 found not consecutive fancy
integer and fancy indexes are transposed together
there was no previous fancy index, so set consec
there was already a non-fancy index after a fancy one
consec_status == 0 means there was a fancy index before
(iterating) fancy index, store the iterator
Check broadcasting
Fill from back, we know how many dims there are
If it is 1, we can broadcast
Does not exist
advance curr_dim for non-fancy indices
Fill dimension of subspace
Attempt to set a meaningful exception. Could also find out if a boolean index was converted.
NPY_NO_EXPORT int prepare_index ( PyArrayObject self,
PyObject *  index,
npy_index_info indices,
int *  num,
int *  ndim,
int *  out_fancy_ndim,
int  allow_boolean 
)
Prepare an npy_index_object from the python slicing object.
This function handles all index preparations with the exception of field access. It fills the array of index_info structs correctly. It already handles the boolean array special case for fancy indexing, i.e. if the index type is boolean, it is exactly one matching boolean array. If the index type is fancy, the boolean array is already converted to integer arrays. There is (as before) no checking of the boolean dimension.
Checks everything but the bounds.
&#64;param the array being indexed &#64;param the index object &#64;param index info struct being filled (size of NPY_MAXDIMS * 2 + 1) &#64;param number of indices found &#64;param dimension of the indexing result &#64;param dimension of the fancy/advanced indices part &#64;param whether to allow the boolean special case
&#64;returns the index_type or -1 on failure and fills the number of indices.
The index might be a multi-dimensional index, but not yet a tuple this makes it a tuple in that case.
TODO: Refactor into its own function.
Next three are just to avoid slow checks
Sequences < NPY_MAXDIMS with any slice objects or newaxis, Ellipsis or other arrays or sequences embedded, are considered equivalent to an indexing tuple. (<cite>a[[[1,2], [3,4]]] == a[[1,2], [3,4]]</cite>)
If it is already a tuple, make it an exact tuple anyway
if getitem fails (unusual) treat this as a single index
We want to interpret it as a tuple, so make it one
If the index is not a tuple, handle it the same as (index,)
Parse all indices into the <cite>indices</cite> array of index_info structs
Check for single index. obj is already set then.
only one loop
** Try the cascade of possible indices ***

System Message: WARNING/2 (<string>, line 1); backlink Inline strong start-string without end-string.
System Message: WARNING/2 (<string>, line 1); backlink Inline emphasis start-string without end-string.
Index is an ellipsis (<cite>...</cite>)
At most one ellipsis in an index
number of slices it is worth, won't update if it is 0:
the used and new ndim will be found later
Index is np.newaxis/None
Index is a slice object.
Special case to allow 0-d boolean indexing with scalars. Should be removed after boolean as integer deprecation. Since this is always an error if it was not a boolean, we can allow the 0-d special case before the rest.
Single integer index, there are two cases here. It could be an array, a 0-d array is handled a bit weird however, so need to special case it.
At this point, we must have an index array (or array-like). It might still be a (purely) bool special case, a 0-d integer array (an array scalar) or something invalid.
TODO: Should maybe replace the error here?
For example an empty list can be cast to an integer array, however it will default to a float one.
Check if the array is valid and fill the information
There are two types of boolean indices (which are equivalent, for the most part though). A single boolean index of matching dimensionality and size is a boolean index. If this is not the case, it is instead expanded into (multiple) integer array indices.
If ndim and size match, this can be optimized as a single boolean index. The size check is necessary only to support old non-matching sizes by using fancy indexing instead. The reason for that is that fancy indexing uses nonzero, and only the result of nonzero is checked for legality.
keep track anyway, just to be complete
TODO, WARNING: This code block cannot be used due to
FutureWarnings at this time. So instead just raise an IndexError.
This can actually be well defined. A new axis is added, but at the same time no axis is "used". So if we have True, we add a new axis (a bit like with np.newaxis). If it is False, we add a new axis, but this axis has 0 entries.
TODO: This can't fail, right? Is there a faster way?
Convert the boolean array into multiple integer ones
Check that we will not run out of indices to store new ones
Add the arrays from the nonzero result to the index
All added indices have 1 dimension
Normal case of an integer array
A 0-d integer array is an array scalar and can be dealt with the HAS_SCALAR_ARRAY flag. We could handle 0-d arrays early on, but this makes sure that array-likes or odder arrays are always handled right.
The array does not have a valid type.
The input was an array already
The input was not an array, so give a general error message
Compare dimension of the index to the real ndim. this is to find the ellipsis value or append an ellipsis if necessary.
There is no ellipsis yet, but it is not a full index so we append an ellipsis to the end.
0-d index into 0-d array, i.e. array[()] We consider this an integer index. Which means it will return the scalar. This makes sense, because then array[...] gives an array and array[()] gives the scalar.
HAS_SCALAR_ARRAY requires cleaning up the index_type
clear as info is unnecessary and makes life harder later
A full integer index sees array scalars as part of itself
At this point indices are all set correctly, no bounds checking has been made and the new array may still have more dimensions than is possible and boolean indexing arrays may have an incorrect shape.
Check this now so we do not have to worry about it later. It can happen for fancy indexing or with newaxis. This means broadcasting errors in the case of too many dimensions take less priority.
If we had a fancy index, we may have had a boolean array index. So check if this had the correct shape now that we can find out which axes it acts on.
NPY_NO_EXPORT PyObject* PyArray_MapIterArray ( PyArrayObject a,
PyObject *  index 
)
Use advanced indexing to iterate an array. Please note
that most of this public API is currently not guaranteed to stay the same between versions. If you plan on using it, please consider adding more utility functions here to accommodate new features.
If it is not a pure fancy index, need to get the subspace
Required for backward compatibility
Check whether the fancy indices are out of bounds. Returns 0 on success and -1 on failure. (Gets operands from the outer iterator, but iterates them independently)
All indices got broadcast away, do not check as it always was
See if it is possible to just trivially iterate the array
Check if the type is equivalent to INTP
release GIL if it was taken by nditer below
GIL retake at end of function or if nditer path required
Use NpyIter if the trivial iteration is not possible
NPY_NO_EXPORT PyObject* PyArray_MapIterNew ( npy_index_info indices,
int  index_num,
int  index_type,
int  ndim,
int  fancy_ndim,
PyArrayObject arr,
PyArrayObject subspace,
npy_uint32  subspace_iter_flags,
npy_uint32  subspace_flags,
npy_uint32  extra_op_flags,
PyArrayObject extra_op,
PyArray_Descr extra_op_dtype 
)
Create new mapiter.

NOTE: The outer iteration (and subspace if requested buffered) is
created with DELAY_BUFALLOC. It must be reset before usage!
&#64;param Index information filled by prepare_index. &#64;param Number of indices (gotten through prepare_index). &#64;param Kind of index (gotten through preprare_index). &#64;param NpyIter flags for an extra array. If 0 assume that there is no

System Message: ERROR/3 (<string>, line 10) Unexpected indentation.

<blockquote> extra operand. NPY_ITER_ALLOCATE can make sense here.</blockquote>

System Message: WARNING/2 (<string>, line 11) Block quote ends without a blank line; unexpected unindent.
&#64;param Array being indexed &#64;param subspace (result of getting view for the indices) &#64;param Subspace iterator flags can be used to enable buffering.

System Message: ERROR/3 (<string>, line 14) Unexpected indentation.

<blockquote>

NOTE: When no subspace is necessary, the extra operand will
always be buffered! Buffering the subspace when not necessary is very slow when the subspace is small.

</blockquote>

System Message: WARNING/2 (<string>, line 17) Block quote ends without a blank line; unexpected unindent.
&#64;param Subspace operand flags (should just be 0 normally) &#64;param Operand iteration flags for the extra operand, this must not be

System Message: ERROR/3 (<string>, line 19) Unexpected indentation.

<blockquote> 0 if an extra operand should be used, otherwise it must be 0. Should be at least READONLY, WRITEONLY or READWRITE.</blockquote>

System Message: WARNING/2 (<string>, line 21) Block quote ends without a blank line; unexpected unindent.
&#64;param Extra operand. For getmap, this would be the result, for setmap
this would be the arrays to get from. Can be NULL, and will be allocated in that case. However, it matches the mapiter iteration, so you have to call MapIterSwapAxes(mit, &extra_op, 1) on it. The operand has no effect on the shape.
&#64;param Dtype for the extra operand, borrows the reference and must not
be NULL (if extra_op_flags is not 0).
&#64;return A new MapIter (PyObject *) or NULL.

System Message: WARNING/2 (<string>, line 30); backlink Inline emphasis start-string without end-string.
For shape reporting on error
create new MapIter object
set all attributes of mapiter to zero
The subspace, the part of the array which is not indexed by arrays, needs to be iterated when the size of the subspace is larger than 1. If it is one, it has only an effect on the result shape. (Optimizes for example np.newaxis usage)
Fill basic information about the mapiter
Set iteration information of the indexing arrays.
For MapIterArray, it is possible that there is no fancy index. to support this case, add a a dummy iterator. Since it is 0-d its transpose, etc. does not matter.
signal necessity to decref...
Now there are two general cases how extra_op is used:
  1. No subspace iteration is necessary, so the extra_op can be included into the index iterator (it will be buffered)
  2. Subspace iteration is necessary, so the extra op is iterated independently, and the iteration order is fixed at C (could also use Fortran order if the array is Fortran order). In this case the subspace iterator is not buffered.
If subspace iteration is necessary and an extra_op was given, it may also be necessary to transpose the extra_op (or signal the transposing to the advanced iterator).
If we have an extra_op given, need to prepare it.
  1. Subclasses might mess with the shape, so need a baseclass
  2. Need to make sure the shape is compatible
  3. May need to remove leading 1s and transpose dimensions. Normal assignments allows broadcasting away leading 1s, but the transposing code does not like this.
Usual assignments allows removal of leading one dimensions. (or equivalently adding of one dimensions to the array being assigned to). To implement this, reshape the array.
If dimensions need to be prepended (and no swapaxis is needed), use op_axes after extra_op is allocated for sure.
We are not using the subspace, so its size is 1. All dimensions of the extra_op corresponding to the subspace must be equal to 1.
If subspace is not NULL, NpyIter cannot allocate extra_op for us. This is a bit of a kludge. A dummy iterator is created to find the correct output shape and stride permutation. TODO: This can at least partially be replaced, since the shape

System Message: ERROR/3 (<string>, line 5) Unexpected indentation.

<blockquote> is found for broadcasting errors.</blockquote>

Create an iterator, just to broadcast the arrays?!
nditer allows itemsize with npy_intp type, so it works here, but it would not work directly, since elsize is limited to int.
Just use C-order strides (TODO: allow also F-order)
shape is set, and strides is set up to mit->nd, set rest
Allocate new array. Note: Always base class, because subclasses might mess with the shape.
The extra op is now either allocated, can be allocated by NpyIter (no subspace) or is not used at all.
Need to set the axis remapping for the extra_op. This needs to cause ignoring of subspace dimensions and prepending -1 for broadcasting.
(fills subspace dimensions too, but they are not unused)
NOTE: If for some reason someone wishes to use REDUCE_OK, be
careful and fix the error message replacement at the end.
For a single 1-d operand, guarantee iteration order (scipy used this). Note that subspace may be used.
If external array is iterated, and no subspace is needed
NOTE: This small limitation should practically not matter.
(replaces npyiter error)
Use the axis remapping
TODO: Maybe add test for the CORDER, and maybe also allow F
NpyIter cleanup and information:
We may be doing a cast for the buffer, and that may have failed
Get the allocated extra_op
If extra_op is being tracked but subspace is used, we need to create a dedicated iterator for the outer iteration of the extra operand.
Get the full dimension information
Calculate total size of the MapIter
Can now return early if no subspace is being used
Fill in the last bit of mapiter information needed
Now just need to create the correct subspace iterator.
We should iterate the extra_op as well
Buffering is never used here, but in case someone plugs it in somewhere else, set the type correctly then.
NOTE: In this case, need to call PyErr_Occurred() after
basepointer resetting (buffer allocation)
Check whether the operand could not be broadcast and replace the error in that case. This should however normally be found early with a direct goto to broadcast_error
(j < 0 is currently impossible, extra_op is reshaped)
extra_op cannot be broadcast to the indexing result
Report the shape of the original array if it exists

References PyArray_DIM.

This function needs to update the state of the map iterator

and point mit->dataptr to the memory-location of the next object

Note that this function never handles an extra operand but provides compatibility for an old (exposed) API.

Referenced by test_pydatamem_seteventhook_start().

Reset the map iterator to the beginning

References NPY_MAXDIMS, PyArray_malloc, and PyArrayMapIter_Type.

NPY_NO_EXPORT void PyArray_MapIterSwapAxes ( PyArrayMapIterObject mit,
PyArrayObject **  ret,
int  getmap 
)
System Message: ERROR/3 (<string>, line 1) Document or section may not begin with a transition.

System Message: ERROR/3 (<string>, line 1) Document may not end with a transition.
arr might not have the right number of dimensions and need to be reshaped first by pre-pending ones
Setting and getting need to have different permutations. On the get we are permuting the returned object, but on setting we are permuting the object-to-be-set. The set permutation is the inverse of the get permutation.
For getting the array the tuple for transpose is (n1,...,n1+n2-1,0,...,n1-1,n1+n2,...,n3-1) n1 is the number of dimensions of the broadcast index array n2 is the number of dimensions skipped at the start n3 is the number of dimensions of the result
For setting the array the tuple for transpose is (n2,...,n1+n2-1,0,...,n2-1,n1+n2,...n3-1)

<

axes to insert at
use n1 as the boundary if getting but n2 if setting

Referenced by PyUFunc_FromFuncAndDataAndSignature().


Variable Documentation

NPY_NO_EXPORT PyMappingMethods array_as_mapping
Initial value:
 {
    (lenfunc)array_length,              
    (binaryfunc)array_subscript,        
    (objobjargproc)array_assign_subscript,       
}
The mapiter object must be created new each time. It does not work to bind to a new array, and continue.
This was the orginal intention, but currently that does not work. Do not expose the MapIter_Type to Python.
The original mapiter(indexobj); mapiter.bind(a); idea is now fully removed. This is not very useful anyway, since mapiter is equivalent to a[indexobj].flat but the latter gets to use slice syntax.

Referenced by PyArray_MapIterReset().