Table of Contents

Class VStringArraySlice

Namespace
NumSharp.Backends.Unmanaged
Assembly
NumSharp.dll

The ELEMENT view of a NEP 55 StringDType buffer — the IArraySlice a T UnmanagedStorage holds as its InternalArray. The elements are NumPy's 16-byte packed cells (Cells, an ordinary ArraySlice<T> of byte, so pooling, reference counting and views are the numeric lanes'); the text of elements longer than 15 bytes lives in the buffer's Allocator (an arena and heap strings), which the cells' memory block owns.

public sealed class VStringArraySlice : IArraySlice, IMemoryBlock, ICloneable, IEnumerable
Inheritance
VStringArraySlice
Implements
Inherited Members
Extension Methods

Remarks

Views share, copies duplicate. Slice(long, long) (contiguous slicing, views, sub-arrays) shares the cells AND the allocator: a write through a view is a write into the same buffer. Clone() allocates a new buffer with a new allocator and DUPLICATES every string into it (NumPy's NpyString_dup), so the copy's arena is compact and its cells never point into the source's memory.

No raw element access. A cell is meaningful only with its own allocator: an arena offset read with another buffer's arena reads someone else's text, and a heap pointer copied into another buffer would be freed twice by the two clear loops. So the typed accessors refuse, Clone<T>() refuses, and the raw byte accessors (AsSpan<T>(), CopyTo<T>(Span<T>)) expose the cells only as BYTES to read (NumPy's tobytes() of a T array is exactly these cells); writing such bytes into another StringDType buffer is never valid.

Element values. GetIndex(long) is NumPy's stringdtype_getitem: a string, or the descriptor's na_object for an NA cell ('' when the descriptor has none). SetIndex(long, object) is stringdtype_setitem: the NA object packs an NA cell; any other value is stored as its Python str() when the descriptor coerces (a string or char as itself, bytes decoded as strict UTF-8), else only text is accepted.

Properties

Address

The first cell.

public byte* Address { get; }

Property Value

byte*

Allocator

The allocator of the buffer these cells belong to (shared by every view of it).

public VStringAllocator Allocator { get; }

Property Value

VStringAllocator

Remarks

The one allocator Cells may be read and written with: lock it (acquire_allocator()) around every load / pack, and never use it with cells of another buffer.

BytesLength

Total cell bytes (Count × 16; the text in the allocator is not counted, as NumPy's nbytes).

public long BytesLength { get; }

Property Value

long

Cells

The packed cells: Count × 16 bytes.

public ArraySlice<byte> Cells { get; }

Property Value

ArraySlice<byte>

Count

The number of string ELEMENTS (cells, not bytes).

public long Count { get; }

Property Value

long

Descr

The element descriptor (a StringDType instance: its na_object and coerce).

public DType Descr { get; }

Property Value

DType

HasNAObject

True when the descriptor has a missing-data object (its NA cells read as that object).

public bool HasNAObject { get; }

Property Value

bool

IsReleased

Diagnostic: true once the underlying buffer has been freed.

public bool IsReleased { get; }

Property Value

bool

IsUniquelyReferenced

true when the underlying MemoryBlock is held by at most one logical reference (this owner), i.e. no other NDArray / view shares its buffer. Non-owning wraps (external / pinned memory) report true since their refcount is immortal and meaningless. Used by ndarray.resize's refcheck to mirror NumPy's "references or is referenced by another array" guard.

public bool IsUniquelyReferenced { get; }

Property Value

bool

this[long]

Element access by index (see GetIndex(long) / SetIndex(long, object)).

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

Parameters

index long

The element index.

Property Value

object

ItemLength

Bytes per element: one 16-byte cell.

public int ItemLength { get; }

Property Value

int

MemoryBlock

The cells' memory block (pool, reference count, and the allocator's lifetime).

public IMemoryBlock MemoryBlock { get; }

Property Value

IMemoryBlock

TypeCode

Always String: the lane shared with S / U (the descriptor's class tells the layouts apart).

public NPTypeCode TypeCode { get; }

Property Value

NPTypeCode

Methods

Abandon()

Atomically decrement the reference count WITHOUT freeing the buffer when the count reaches zero — the finalizer-path counterpart of Release(). A finalizer proves only that one wrapper became unreachable, not that no other reachable alias (a bare storage/slice) still reads the buffer; the block's own finalizer frees it once the whole alias graph is unreachable.

public void Abandon()

Allocate(DType, long)

Allocates a buffer of count elements of descr: ZERO-FILLED cells (every element is '', NumPy's NPY_NEEDS_INIT) and a new allocator, both owned by one memory block whose release runs the clear loop (frees the heap strings and the arena) before the cells go back to the pool.

public static VStringArraySlice Allocate(DType descr, long count)

Parameters

descr DType

A StringDType descriptor.

count long

The number of elements (the caller has already run NumSharp.AllocationGuard on 16-byte elements, so count * 16 cannot overflow).

Returns

VStringArraySlice

The new slice (the only reference to its block).

Exceptions

ArgumentNullException

descr is null.

ArgumentException

descr is not a StringDType descriptor.

OutOfMemoryException

The cells cannot be allocated.

AsSpan<T>()

The cells as raw bytes (NumPy's tobytes() of a T array); only byte.

public UnmanagedSpan<T> AsSpan<T>() where T : unmanaged

Returns

UnmanagedSpan<T>

A span over the cells, no copy. Writing it into another buffer's cells is never valid.

Type Parameters

T

byte.

Exceptions

NotSupportedException

Any other T.

Clone()

A deep copy: a new buffer with a new allocator and every string DUPLICATED into it (NumPy's NpyString_dup per element, in order, so the copy's arena is compact); NA cells stay NA.

public IArraySlice Clone()

Returns

IArraySlice

The copy.

Exceptions

MemoryError

NumPy's Failed to allocate string in string to string cast.

Clone<T>()

A typed clone would copy cells away from their allocator; refused.

public ArraySlice<T> Clone<T>() where T : unmanaged

Returns

ArraySlice<T>

Never returns.

Type Parameters

T

Any unmanaged type.

Exceptions

NotSupportedException

Always: clone the slice itself (Clone()).

CopyTo<T>(UnmanagedSpan<T>)

Copies the raw cells into destination (see CopyTo<T>(Span<T>)).

public void CopyTo<T>(UnmanagedSpan<T> destination) where T : unmanaged

Parameters

destination UnmanagedSpan<T>

The target span.

Type Parameters

T

Any unmanaged type; the destination must hold at least BytesLength bytes.

Exceptions

ArgumentException

destination is too short.

CopyTo<T>(Span<T>)

Copies the raw cells into destination (the destination's element type only sizes it).

public void CopyTo<T>(Span<T> destination)

Parameters

destination Span<T>

The target span.

Type Parameters

T

Any element type; the destination must hold at least BytesLength bytes.

Exceptions

ArgumentException

destination is too short.

DangerousFree()

Performs dispose on the internal unmanaged memory block.

public void DangerousFree()

Remarks

Dangerous because this ArraySlice might be a slice of a larger block, so other slices might point to the current MemoryBlock.
So releasing the MemoryBlock might cause memory corruption elsewhere.
It is best to leave MemoryBlock to GC.

Fill(object)

Writes value into every element (NumPy's fill: the value is converted ONCE, then packed into each cell — a long text gets its own allocation per element, as NumPy's duplicating copy gives it).

public void Fill(object value)

Parameters

value object

The value (see SetIndex(long, object)); it is converted even when there are no elements, as NumPy packs it into a scalar first.

Exceptions

ValueError

See SetIndex(long, object).

UnicodeDecodeError

See SetIndex(long, object).

UnicodeEncodeError

See SetIndex(long, object).

OutOfMemoryException

See SetIndex(long, object).

GetEnumerator()

Enumerates the elements as C# values (see GetIndex(long)).

public IEnumerator GetEnumerator()

Returns

IEnumerator

The enumerator.

GetIndex(long)

Element index as its C# value (stringdtype_getitem): the text as a string, or the descriptor's na_object for an NA cell ('' when the descriptor has none).

public object GetIndex(long index)

Parameters

index long

The element index.

Returns

object

A string, or the NA object (possibly null, NumPy's None).

Exceptions

OutOfMemoryException

Failed to load string in StringDType getitem (a corrupt cell), or a text too long for a .NET string.

GetIndex<T>(long)

Typed element access is meaningless for a StringDType cell; refused.

public T GetIndex<T>(long index) where T : unmanaged

Parameters

index long

Ignored.

Returns

T

Never returns.

Type Parameters

T

Any unmanaged type.

Exceptions

NotSupportedException

Always.

GetItems(long, long, Span<object>)

The values of the strided run start + i * stride (see GetItems(long, long, Span<object>)): what GetIndex(long) returns for each element — the text as a string, the descriptor's na_object for an NA cell ('' when it has none) — under ONE hold of the allocator's lock.

public void GetItems(long start, long stride, Span<object> destination)

Parameters

start long

The first element.

stride long

The step in elements (0 repeats an element, negative walks back).

destination Span<object>

Receives the values.

Remarks

NumPy's stringdtype_getitem acquires and releases the allocator for every element; the lock exists so that no store moves the arena or frees a heap text while a read follows a cell's pointer, and holding it for the whole run guards the same reads (another thread's store into this buffer waits for the run). The arena base is therefore read once, and each cell is unpacked by Load(byte*, byte*, out byte*, out long) (NumPy's NpyString_load with the base given), as the comparison kernels do.

Exceptions

OutOfMemoryException

Failed to load string in StringDType getitem (a corrupt cell), or a text too long for a .NET string, at the first such element (the slots before it are filled).

GetPinnableReference<T>()

A reference to the first cell byte.

public ref T GetPinnableReference<T>() where T : unmanaged

Returns

T

The reference.

Type Parameters

T

byte.

Exceptions

NotSupportedException

Any other T.

Release()

Atomically decrement the reference count. Frees the underlying buffer immediately on the final release.

public void Release()

SetIndex(long, object)

Stores value into element index (stringdtype_setitem): the descriptor's NA object (by NumPy's na_eq_cmp) packs an NA cell; any other value is converted by AsPyString(object, bool), encoded as strict UTF-8 and packed.

public void SetIndex(long index, object value)

Parameters

index long

The element index.

value object

Any C# value standing in for a Python object (see NumSharp.Backends.Strings.NDPyObject).

Exceptions

ValueError

A value that is not text under coerce=False.

UnicodeDecodeError

bytes that are not UTF-8.

UnicodeEncodeError

A text with a lone surrogate.

MemoryError

NumPy's Failed to pack string during StringDType setitem.

SetIndex<T>(long, T)

Typed element writes are meaningless for a StringDType cell; refused.

public void SetIndex<T>(long index, T value) where T : unmanaged

Parameters

index long

Ignored.

value T

Ignored.

Type Parameters

T

Any unmanaged type.

Exceptions

NotSupportedException

Always.

Slice(long)

The elements from start to the end, sharing the cells and the allocator.

public IArraySlice Slice(long start)

Parameters

start long

The first element.

Returns

IArraySlice

A slice over the same buffer.

Slice(long, long)

count elements from start, sharing the cells and the allocator.

public IArraySlice Slice(long start, long count)

Parameters

start long

The first element.

count long

The number of elements.

Returns

IArraySlice

A slice over the same buffer (a write through it is a write into this buffer).

ToArray()

The elements as a managed array: string[] when the descriptor has no NA object, else object[] (an NA cell is the NA object).

public Array ToArray()

Returns

Array

The values in buffer order.

Exceptions

OutOfMemoryException

See GetIndex(long).

ToString()

Returns a string that represents the current object.

public override string ToString()

Returns

string

A string that represents the current object.

TryAddRef()

Atomically increment the reference count on the underlying MemoryBlock. Returns false if the block has already been released and must not be referenced further.

public bool TryAddRef()

Returns

bool