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

object

np.FlatIterator

Implements

IEnumerable<object>

IEnumerable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

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.

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.

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.

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.

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(), which returns an ndarray).

public NDArray copy()

Returns

NDArray

next()

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

public object next()

Returns

object