Class np.NDIterator
- Namespace
- NumSharp
- Assembly
- NumSharp.dll
NumPy's numpy.nditer — the public, managed face of NumSharp's
NDIterRef.
// numpy: for x in np.nditer(a): total += x
foreach (var vals in np.nditer(a))
total += (int)vals[0];
// numpy: it = np.nditer(a, flags=['multi_index'])
// while not it.finished: print(it.multi_index, it[0]); it.iternext()
var it = np.nditer(a, flags: new[] {"multi_index"});
while (!it.finished) { Use(it.multi_index, it[0]); it.iternext(); }
public class np.NDIterator : IEnumerable<NDArray[]>, IEnumerable, IDisposable
- Inheritance
-
np.NDIterator
- Implements
- Inherited Members
Remarks
Port of NumPy 2.4.2's numpy/_core/src/multiarray/nditer_pywrap.c — the Python
WRAPPER around the C iterator, which is what this class is: argument conversion,
flag-string parsing, the property surface and the iteration protocol. The iterator
itself is NDIterRef (NumPy's NpyIter), which already implements
the buffering, casting, coalescing, broadcasting and index tracking.
Lifetime. NDIterRef is a ref struct and cannot live in a
class field, so this class owns the heap NDIterState directly (handed over by
NDIterRef.Detach) and re-borrows a non-owning NDIterRef for the
duration of each call. It therefore MUST be disposed — close(),
Dispose() or a using — which frees the unmanaged state and
resolves any copy_if_overlap / updateifcopy write-backs, exactly like
NumPy's with np.nditer(...) as it:. A finalizer is the safety net.
The yielded arrays alias the iterator. this[int] and
value return views onto the iterator's LIVE data pointer (0-d
normally, 1-d under external_loop), so they change under you on the next
step and are invalid after disposal — the same contract as NumPy, where the loop
variable must be copied to be kept. Writing through them writes to the operand
(or its buffer), which is how readwrite iteration mutates an array.
Iteration yields NDArray[], always. NumPy yields a bare 0-d array for
one operand and a tuple for several; C# has no such union, so enumeration always
produces the operand array — vals[0] for the single-operand case. This is
the same choice np.Broadcast made (object[] always).
Descriptors. The iterator is built over NumPy's resolved per-operand DESCRIPTORS
(dtypes), not storage lanes, so fixed-width strings iterate, and the cast rules are NumPy's:
copy / updateifcopy operands get a temporary in the iteration dtype laid out in the iterator's
order (written back with unsafe casting at close()), a read-only 0-d operand is copied without
being asked, and every other cast needs buffered.
Known differences. An allocated output requested as unsized 'U' / 'S' is allocated with
one character, as in NumPy, but NumPy's views of it are unsized (writing through them stores nothing) while
NumSharp's are one character wide. A non-native request ('>U3') is reported and cast-checked as
NumPy does, but its buffer holds native data. The contig flag does not raise NumPy's "required
buffering" error when an unbuffered operand is not contiguous, and nbo / aligned force no copy
(NumSharp arrays are native; see the string dtype plan's open items).
Constructors
NDIterator(NDArray[], string[], string[][], DType[], char, string, int[][], long[], long)
The port of NumPy's npyiter_init (nditer_pywrap.c) and of the descriptor half of
NpyIter_AdvancedNew: the arguments are converted in NumPy's order (flags, order, casting, then the
operand count, then op_flags, op_dtypes, op_axes) and the itershape rank rule applied, the op_axes entries
checked (npyiter_check_op_axes), the global flags checked, every operand prepared in turn
(npyiter_prepare_operands: its flags, its writeability, its size, its requested dtype adapted to it),
the iteration shape broadcast and checked (npyiter_fill_axisdata's shape pass, then its stride pass's
refusals), the dtypes an allocation or common_dtype needs resolved (npyiter_get_common_dtype),
and the iterator built over the resulting DESCRIPTORS and the broadcast shape — which is what lets it iterate
fixed-width strings and run NumPy's cast checks and copy routes.
public NDIterator(NDArray[] op, string[] flags = null, string[][] op_flags = null, DType[] op_dtypes = null, char order = 'K', string casting = "safe", int[][] op_axes = null, long[] itershape = null, long buffersize = 0)
Parameters
opNDArray[]The operands; a null entry is an output for the iterator to allocate.
flagsstring[]The global flags.
op_flagsstring[][]The per-operand flags (one inner list per operand, or one list for all).
op_dtypesDType[]The requested iteration dtypes (one per operand; null entries mean "the operand's").
ordercharThe iteration order.
castingstringThe casting rule.
op_axesint[][]The per-operand axis maps (null entries for natural broadcasting).
itershapelong[]The iteration shape, or null: a negative entry is deduced from the operands; without
op_axesit sets the rank and every operand is right-aligned into it.buffersizelongThe buffer size in elements (0 = NumPy's
NPY_BUFSIZE, 8192 — as in NumPy, setbufsize(long) does not change it).
Remarks
NumPy's np.nditer(...) constructor, the one np.nditer calls; a subclass of the iterator
chains to it. Every parameter after op has NumPy's default (since API-parity batch 12),
so new np.NDIterator(new[] { a }) is NumPy's np.nditer([a]). The iterator holds native
buffers: dispose it (or use it in a using) when done.
Exceptions
- ValueError
NumPy's argument, flag, op_axes, shape-pass and stride-pass errors (verbatim texts: a broadcast mismatch, an invalid or duplicate axis, a stretched no_broadcast operand, a refused reduction), or a text that does not parse as the number a copy or the first buffer fill reads it into.
- TypeError
A malformed
op_dtypessequence, aStringDTypeoperand or request withoutrefs_ok(before the shape pass), a refused cast, or a cast operand neither copied nor buffered.- OverflowError
A text read into an integer dtype by a copy or the first buffer fill holds a number outside that dtype.
- MemoryError
A
StringDTypecopy or buffer transfer cannot allocate a string (NumPy'sMemoryErrortexts).
Properties
Current
The values published by the most recent MoveNext(). Borrowed: the
per-step views are handed to the consumer, who owns them (NumPy's [x.copy() for
x in it] idiom is the one that keeps them).
public NDArray[] Current { get; }
Property Value
- NDArray[]
this[int]
A LIVE view of operand i at the current position (NumPy's
it[i]) — 0-d normally, 1-d spanning the inner loop under
external_loop. Writing through it writes to the operand or its buffer;
the view is invalidated by the next step and by disposal. A negative index counts from the last operand.
Setting it copies a value into the current element(s) — see the setter's remarks.
public NDArray this[int i] { get; set; }
Parameters
iintThe operand index (negative counts from the end).
Property Value
- NDArray
The view; read-only unless the operand is written (
readwrite/writeonly), as NumPy's views are (its write flags).
Remarks
The setter is NumPy's npyiter_seq_ass_item: the value is copied into a 1-D view of the current
inner loop (one element without external_loop) by PyArray_CopyObject, the store
a[...] = value makes. A C# number literal is NumPy's Python scalar, PACKED: range-checked, a float
truncated into an integer operand, a NaN into one NumPy's ValueError, so it[1] = 300 on an int8 operand
raises like NumPy's. A 0-d ARRAY (np.array(300), NDArray.Scalar(300)) is an array: it is
assigned with an unsafe cast and stores 44, as NumPy's 0-d ndarray does. A value with dimensions is
broadcast to the view ("could not broadcast input array from shape (2,) into shape (1,)"). Null is Python's
None: NaN into a float operand, nan+nanj into a complex one, False into a bool one,
Python's int() TypeError into an integer one.
A view of NEP 55 StringDType memory (the operand, or its buffer under a buffered cast to
StringDType) goes through StringDType's setitem for a C# literal (a number stores its
str(), null stores the NA object, or 'None' under coerce=True, and both raise
"StringDType only allows string data when string coercion is disabled." under coerce=False), and an
array is cast. A null into fixed-width text memory stores str(None), truncated to the width
('No' for <U2), as NumPy's setitem does.
Exceptions
- ValueError
The iterator is closed or past the end ("Iterator is past the end"), or a
delay_bufallociterator has not been reset (NumPy's text).- IndexError
No operand
i: "Iterator operand index i is out of bounds".- RuntimeError
Setting a read-only operand: "Iterator operand i is not writeable".
- OverflowError
Setting a C# number literal that does not fit the operand's dtype (NumPy's OverflowError texts: "Python integer 300 out of bounds for int8", "cannot convert float infinity to integer").
- TypeError
Setting null (Python's
None) or a complex literal into an integer operand (Python'sint()texts), or a complex literal into a real one.
dtypes
The per-operand iteration dtypes (NumPy's dtypes): the descriptor each operand is iterated as —
a requested dtype adapted to its operand ('U' over a <U3 array is <U3), the common
dtype, or the operand's own. A string reports its width and class (dtype('<U5')), which a type code
cannot.
public DType[] dtypes { get; }
Property Value
- DType[]
Remarks
An allocated output keeps its request as given, as NumPy does: np.nditer([u, null], op_dtypes: [null,
"U"]) reports dtype('<U') for the output although the array is allocated <U1. A
non-native request ('>U3') is reported as requested although the buffer holds native data.
Exceptions
- InvalidOperationException
The iterator is closed.
finished
True once iteration has run past the end (NumPy's finished): after the pull or
iternext() that found no next element, and from the start for an empty iteration or range.
A seek (iterindex, multi_index, index) clears it.
public bool finished { get; }
Property Value
Remarks
A CLOSED iterator reads false, as NumPy's does (its getter tests the iterator before the flag).
has_delayed_bufalloc
Whether buffer allocation is still delayed pending a reset() (NumPy's
has_delayed_bufalloc). While it is, the element views and multi_index refuse — NumPy's
delay_bufalloc exists so an allocated output can be initialized before the buffers first read it.
public bool has_delayed_bufalloc { get; }
Property Value
Exceptions
- ValueError
The iterator is closed ("Iterator is invalid").
has_index
Whether a C- or F-order flat index is being tracked (NumPy's has_index).
public bool has_index { get; }
Property Value
Exceptions
- ValueError
The iterator is closed ("Iterator is invalid").
has_multi_index
Whether a multi-index is being tracked (NumPy's has_multi_index).
public bool has_multi_index { get; }
Property Value
Exceptions
- ValueError
The iterator is closed ("Iterator is invalid").
index
The tracked flat index (NumPy's index) — the position in C or F order of the operands' own shape,
whatever order the iterator walks. Requires the c_index or f_index flag. Setting it moves the
iterator there (NumPy's NpyIter_GotoIndex): the next pull yields that element.
public long index { get; set; }
Property Value
Exceptions
- ValueError
Reading: the iterator is closed or past the end ("Iterator is past the end"), or no index is tracked ("Iterator does not have an index"). Setting: the iterator is closed ("Iterator is invalid"), no index is tracked, or it is buffered / external-loop (NumPy's "Cannot call GotoIndex on an iterator which …" texts).
- IndexError
Setting: an index outside
[0, itersize)("Iterator GotoIndex called with an out-of-bounds index"), or one outside the current iterrange.
iterationneedsapi
Whether iteration needs the Python C-API (NumPy's iterationneedsapi).
Always FALSE in NumSharp — there is no Python runtime, and the transfer flags
never carry REQUIRES_PYAPI.
public bool iterationneedsapi { get; }
Property Value
iterindex
The current flat iteration position (NumPy's iterindex), counted in the iterator's own order.
Setting it moves the iterator there (NumPy's NpyIter_GotoIterIndex; a buffered iterator writes its
window back and fills the one at the new position): the next pull yields that element.
public long iterindex { get; set; }
Property Value
Exceptions
- ValueError
Reading: the iterator is closed or past the end ("Iterator is past the end"). Setting: the iterator is closed ("Iterator is invalid"), or it is external-loop ("Cannot call GotoIterIndex on an iterator which has the flag EXTERNAL_LOOP").
- IndexError
Setting: a position outside the current iterrange ("Iterator GotoIterIndex called with an iterindex outside the iteration range.").
iterrange
The [start, end) sub-range being iterated (NumPy's iterrange). Setting it requires the
ranged flag, and resets the iterator to the start of the new range (NumPy's
NpyIter_ResetToIterIndexRange, which also allocates delayed buffers); an empty range is finished at
once.
public (long Start, long End) iterrange { get; set; }
Property Value
Exceptions
- ValueError
The iterator is closed ("Iterator is invalid"); setting without the
rangedflag, a range outside[0, itersize]("Out-of-bounds range [s, e) passed to ResetToIterIndexRange"), or an end before the start ("Invalid range [s, e) passed to ResetToIterIndexRange").
itersize
Total number of elements the iterator will visit (NumPy's itersize).
public long itersize { get; }
Property Value
itviews
Per-operand views with the iterator's internal axis ordering (NumPy's
itviews). Not available while buffering.
public NDArray[] itviews { get; }
Property Value
- NDArray[]
multi_index
The tracked multi-index (NumPy's multi_index) in the operands' own axis order. Requires the
multi_index flag. Setting it moves the iterator there (NumPy's NpyIter_GotoMultiIndex): the
next pull yields that element.
public long[] multi_index { get; set; }
Property Value
- long[]
Exceptions
- ValueError
Reading: the iterator is closed or past the end ("Iterator is past the end"), no multi-index is tracked, or a
delay_bufallociterator has not been reset (NumPy's texts). Setting: the iterator is closed ("Iterator is invalid"), no multi-index is tracked, a null value ("multi_index must be set with a sequence"), a value whose length is not ndim ("Wrong number of indices"), or a buffered iterator ("Cannot call GotoMultiIndex on an iterator which is buffered").- IndexError
Setting: a coordinate outside its axis ("Iterator GotoMultiIndex called with an out-of-bounds multi-index"), or a position outside the current iterrange.
ndim
The number of dimensions iterated (NumPy's ndim).
public int ndim { get; }
Property Value
nop
The number of operands (NumPy's nop).
public int nop { get; }
Property Value
operands
The operands, including any the iterator ALLOCATED and the temporaries of its copy routes (NumPy's
operands). Each read returns a new array of the same operand objects, as NumPy returns a new tuple,
so replacing an entry cannot change what the iterator walks.
public NDArray[] operands { get; }
Property Value
- NDArray[]
Exceptions
- ValueError
The iterator is closed ("Iterator is invalid"): the copy-route temporaries were written back and released by close().
shape
The shape being iterated (NumPy's shape). Without multi_index the
iterator is free to coalesce and reorder axes, so this is the COALESCED shape listed
INNERMOST FIRST, NumPy's axisdata order (probed: a C-contiguous (2,3) reports (6,),
an f_index walk of it — which cannot coalesce — (3, 2)); with multi_index
it is the operands' own shape in their axis order, (2, 3).
public long[] shape { get; }
Property Value
- long[]
Remarks
Code that reads the shape of an iterator without a multi-index gets the iteration's axes, not the array's:
a forced F-order walk of a C (3, 4) array reports (3, 4) (axis 0 is its inner axis), a C-order
walk of an F one reports (4, 3).
Exceptions
- ValueError
The iterator is closed or past the end — NumPy's
npyiter_shape_getguards it like a position ("Iterator is past the end"), so an empty iteration has no shape either.
value
The current values — one live view per operand (NumPy's value). NumPy
returns a bare array for a single operand and a tuple otherwise; this always
returns the array, so use value[0] for the single-operand case.
public NDArray[] value { get; }
Property Value
- NDArray[]
Exceptions
- ValueError
The iterator is closed or past the end ("Iterator is past the end"), or a
delay_bufallociterator has not been reset.
Methods
Dispose()
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
public void Dispose()
~NDIterator()
protected ~NDIterator()
GetEnumerator()
Enumerates the iterator's single live cursor, so — as in NumPy, where
iter(it) is it — a second enumeration RESUMES where the first stopped
rather than restarting (call reset() to go again).
public IEnumerator<NDArray[]> GetEnumerator()
Returns
Remarks
Deliberately a thin wrapper rather than this, even though returning
this would model iter(it) is it more literally: foreach
disposes the enumerator it obtains, and this class's Dispose() frees
the unmanaged iterator state. Handing out this would therefore CLOSE the
iterator at the end of any foreach/LINQ pass, making every property read
afterwards throw. The wrapper's Dispose is a no-op and the cursor is
still shared, so the observable semantics are unchanged.
(np.Broadcast can safely return this only because it owns
no unmanaged resources.)
MoveNext()
NumPy's npyiter_next: ADVANCES ON ENTRY (its started flag) and then publishes the values at the
new position — the first pull publishes the first element without moving, every later pull moves one step
first. So after one pull iterindex still reads 0, and a copy() taken there (which
carries the flag) resumes with the SECOND element.
public bool MoveNext()
Returns
- bool
True when a value was published; false at the end.
Remarks
The order is what makes a buffered readwrite loop correct: a write through the published view lands
in the buffer BEFORE the iterator moves past it, and moving past the end of a buffer is what flushes it. The
publish-then-advance form this replaced (journey4's surface gap SU42) moved first, flushed the buffer, and
lost the last write of every buffer. A published view stays valid until the next pull; under buffered
external_loop iteration it aliases a buffer the next pull refills — NumPy has the identical hazard,
hence its documented [x.copy() for x in it] idiom.
close()
Resolve write-backs and release the iterator (NumPy's close(), i.e. the
end of a with np.nditer(...) as it: block). Idempotent; the iterator is
unusable afterwards.
public void close()
copy()
Duplicate the iterator at its current position (NumPy's copy()). The copy
owns its own state and must be disposed independently.
public np.NDIterator copy()
Returns
- np.NDIterator
The copy, carrying NumPy's started / finished flags (so it resumes where the original would).
Exceptions
- ValueError
The iterator is closed ("Iterator is invalid").
debug_print()
Dump the iterator's internal state to standard output (NumPy's debug_print()); a closed iterator
prints NumPy's Iterator: (nil).
public void debug_print()
enable_external_loop()
Switch to external-loop iteration after construction (NumPy's enable_external_loop()), restarting
from the first chunk (delayed buffers are allocated).
public void enable_external_loop()
Exceptions
- ValueError
The iterator is closed ("Iterator is invalid"), or a flat index or multi-index is tracked ("Iterator flag EXTERNAL_LOOP cannot be used if an index or multi-index is being tracked").
iternext()
Advance to the next element/chunk (NumPy's iternext()). Returns false at the end — and for a closed
or finished iterator, without advancing (NumPy's npyiter_iternext raises nothing there).
public bool iternext()
Returns
- bool
True when the iterator moved to another element; false when it is (now) finished.
remove_axis(int)
Remove an axis from iteration (NumPy's remove_axis(i)): the iterator then walks every other axis with
that one fixed at index 0, and restarts. Requires the multi_index flag; the axis is in the operands'
own numbering, whatever order the iterator walks.
public void remove_axis(int axis)
Parameters
axisintThe axis to remove, in
[0, ndim)(no negative indexing, as in NumPy).
Exceptions
- ValueError
The iterator is closed ("Iterator is invalid"), or
axisis out of bounds ("axis out of bounds in iterator RemoveAxis").- RuntimeError
No multi-index is tracked, a flat index is tracked, or the iterator is buffered (NumPy's texts).
remove_multi_index()
Stop tracking the multi-index, letting the iterator coalesce and reorder axes
(NumPy's remove_multi_index()). Resets the position to the start, whether or not a multi-index was
tracked (a buffered window is written back first, delayed buffers are allocated).
public void remove_multi_index()
Exceptions
- ValueError
The iterator is closed ("Iterator is invalid").
reset()
Rewind to the start of the range (NumPy's reset()); also allocates delayed buffers — the reset a
delay_bufalloc iterator needs before its elements can be read. A buffered window already at the
start is left as it is (NumPy's NpyIter_Reset).
public void reset()
Exceptions
- ValueError
The iterator is closed ("Iterator is invalid").
- MemoryError
Delayed buffers could not be allocated.