Class VStringArraySlice
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
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
Cells
The packed cells: Count × 16 bytes.
public ArraySlice<byte> Cells { get; }
Property Value
Count
The number of string ELEMENTS (cells, not bytes).
public long Count { get; }
Property Value
Descr
The element descriptor (a StringDType instance: its na_object and coerce).
public DType Descr { get; }
Property Value
HasNAObject
True when the descriptor has a missing-data object (its NA cells read as that object).
public bool HasNAObject { get; }
Property Value
IsReleased
Diagnostic: true once the underlying buffer has been freed.
public bool IsReleased { get; }
Property Value
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
this[long]
Element access by index (see GetIndex(long) / SetIndex(long, object)).
public object this[long index] { get; set; }
Parameters
indexlongThe element index.
Property Value
ItemLength
Bytes per element: one 16-byte cell.
public int ItemLength { get; }
Property Value
MemoryBlock
The cells' memory block (pool, reference count, and the allocator's lifetime).
public IMemoryBlock MemoryBlock { get; }
Property Value
TypeCode
Always String: the lane shared with S / U (the descriptor's
class tells the layouts apart).
public NPTypeCode TypeCode { get; }
Property Value
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
descrDTypeA
StringDTypedescriptor.countlongThe number of elements (the caller has already run NumSharp.AllocationGuard on 16-byte elements, so
count * 16cannot overflow).
Returns
- VStringArraySlice
The new slice (the only reference to its block).
Exceptions
- ArgumentNullException
descris null.- ArgumentException
descris not aStringDTypedescriptor.- 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
Tbyte.
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
TAny 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
destinationUnmanagedSpan<T>The target span.
Type Parameters
TAny unmanaged type; the destination must hold at least BytesLength bytes.
Exceptions
- ArgumentException
destinationis 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
destinationSpan<T>The target span.
Type Parameters
TAny element type; the destination must hold at least BytesLength bytes.
Exceptions
- ArgumentException
destinationis 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
valueobjectThe value (see SetIndex(long, object)); it is converted even when there are no elements, as NumPy packs it into a scalar first.
Exceptions
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
indexlongThe element index.
Returns
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
indexlongIgnored.
Returns
- T
Never returns.
Type Parameters
TAny 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
startlongThe first element.
stridelongThe step in elements (0 repeats an element, negative walks back).
destinationSpan<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
Tbyte.
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
indexlongThe element index.
valueobjectAny 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
bytesthat 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
indexlongIgnored.
valueTIgnored.
Type Parameters
TAny 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
startlongThe 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
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
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()