Table of Contents

Class np.FlatIterator

Namespace
NumSharp
Assembly
NumSharp.dll

A flat, C-order iterator over an NDArray — the NumSharp analog of NumPy's flatiter (the type of ndarray.flat), obtained from flatiter or flat(NDArray).

Unlike NumSharp's flat (a raveled NDArray that materializes a COPY for a non-contiguous array, so writes through it are lost), this iterator always reads AND writes THROUGH to the base array in logical C-order, whatever the memory layout — matching NumPy's a.flat[i] = v semantics for transposed, sliced, strided, negative-stride and broadcast layouts alike. Every element access maps a flat C-order index to the base's coordinate and goes through the base's stride-aware element accessors, so no per-dtype branching and no buffer materialization occur.

Surface (probed against NumPy 2.4.2): this[long] single-element get (a 0-d write-through view, NumSharp's scalar analog) / set; fancy (int[]/long[]/ NDArray) and slice-string ("1:4", "::2") get/set; the index / coords cursor, Base, size, copy() (a fresh 1-D C-order array), and C-order iteration that shares the cursor (so a second pass RESUMES, as NumPy's iter(f) is f).

Scalar assignment matches NumPy's weak-scalar bounds check: an OUT-OF-RANGE C# primitive (NumSharp's NEP50 analog of a Python int/float) written to an integer element RAISES (OverflowException, "Python integer 300 out of bounds for int8") rather than wrapping, the truncate-then-check rule for floats included (127.9 stores 127, 128.0 raises, NaN/inf raise). A STRONG scalar — an NDArray, reached through the fancy/slice setters or a.astype — still wraps, exactly as in NumPy (which range-checks a Python int but wraps an np.int64 scalar).

One documented divergence remains ([Misaligned]): coords read at the EXHAUSTED position (index == size, after a full pass) on a truly non-contiguous array is implementation-defined — NumSharp returns the arithmetic continuation, NumPy an internal odometer artifact; every IN-RANGE coord (the values read during iteration) is bit-exact.

public sealed class np.FlatIterator : IEnumerable<object>, IEnumerable
Inheritance
np.FlatIterator
Implements
Inherited Members

Properties

Base

The array being iterated (NumPy's flatiter.base). Writes through this iterator hit it.

public NDArray Base { get; }

Property Value

NDArray

this[NDArray]

Fancy get/set by integer indices (NumPy's f[[1,3,5]]). Negatives wrap; set writes through; the value is converted BEFORE the indices are bounds-checked (a.flat[[9]] = None on an integer array is the TypeError, as in NumPy).

public NDArray this[NDArray indices] { get; set; }

Parameters

indices NDArray

Property Value

NDArray

this[int[]]

Fancy get/set by integer indices (NumPy's f[[1,3,5]]). Negatives wrap; set writes through; the value is converted BEFORE the indices are bounds-checked (a.flat[[9]] = None on an integer array is the TypeError, as in NumPy).

public NDArray this[int[] indices] { get; set; }

Parameters

indices int[]

Property Value

NDArray

this[long]

Single-element access at flat C-order index i (NumPy's f[i]). Negative indices wrap; out-of-range raises IndexError. The getter returns the scalar (as NumPy does); the setter writes it through to the base in every memory layout, casting to the base dtype with NumPy semantics when needed.

public object this[long i] { get; set; }

Parameters

i long

Property Value

object

this[long[]]

Fancy get/set by integer indices (NumPy's f[[1,3,5]]). Negatives wrap; set writes through; the value is converted BEFORE the indices are bounds-checked (a.flat[[9]] = None on an integer array is the TypeError, as in NumPy).

public NDArray this[long[] indices] { get; set; }

Parameters

indices long[]

Property Value

NDArray

this[string]

Fancy get/set by a slice string (NumPy's f["1:4"] / f["::2"]). Set writes through; the value is converted BEFORE the slice is resolved, as NumPy's iter_ass_subscript does.

public NDArray this[string range] { get; set; }

Parameters

range string

Property Value

NDArray

coords

The current cursor as a coordinate tuple (NumPy's flatiter.coords). Matches NumPy even past the end: the slowest (leading) axis is NOT wrapped, so on shape (2,3) the exhausted cursor index==6 reports (2, 0), not (0, 0).

public long[] coords { get; }

Property Value

long[]

index

The current cursor position as a flat C-order index (NumPy's flatiter.index).

public long index { get; }

Property Value

long

size

Total number of elements — the base's size (NumPy's len(a.flat)).

public long size { get; }

Property Value

long

Methods

AsTyped<T>(bool)

A typed, allocation-free, by-reference view of this same flat iteration — the unboxed counterpart of iterating this np.FlatIterator. Yields ref T in logical C-order (the same order this object walks), writing through to Base for every layout:

foreach (ref double x in a.flatiter.AsTyped<double>(writeable: true))
    x *= 2;

The by-reference spelling a.flatiter<T> is impossible in C# — a generic method cannot share a name with the flatiter property — so the typed flat iterator is reached through this method (or the equivalent static flat<T>(NDArray, bool)). T must be the array's EXACT element type; a ref cannot convert, so a mismatch throws rather than reinterpreting the bytes. Unlike the boxed cursor, the typed one holds no state and does not share this object's index/coords cursor — each foreach starts from the beginning.

public np.FlatRefIter<T> AsTyped<T>(bool writeable = false) where T : unmanaged

Parameters

writeable bool

Open the base readwrite; a read-only broadcast view is refused.

Returns

np.FlatRefIter<T>

Type Parameters

T

GetEnumerator()

C-order iteration over every element. Shares the index/coords cursor (as NumPy's iter(f) is f), so a second enumeration RESUMES where the first stopped rather than restarting.

public IEnumerator<object> GetEnumerator()

Returns

IEnumerator<object>

copy()

A fresh 1-D C-order COPY of the base (NumPy's f.copy()): an array of the base's class, so a chararray base gives a chararray (NumPy's PyArray_Flatten allocates with the base's type).

public NDArray copy()

Returns

NDArray

A new 1-D array that owns its data.

Exceptions

ValueError

A chararray base holds data that is not string data.

next()

Return the current element and advance the cursor (NumPy's next(f)).

public object next()

Returns

object