Class StringArraySlice
The ELEMENT view of a fixed-width string buffer (S or U) — the IArraySlice a string
UnmanagedStorage holds as its InternalArray. The bytes live in an
ordinary ArraySlice<T> of byte (Bytes, so pooling, reference counting and
lifetime are exactly the numeric lanes'); this object only says how to count them: one element is
ItemSize bytes, its type is String, and its descriptor is
Descr.
public sealed class StringArraySlice : IArraySlice, IMemoryBlock, ICloneable, IEnumerable
- Inheritance
-
StringArraySlice
- Implements
- Inherited Members
- Extension Methods
Remarks
Why a dedicated slice instead of a raw byte slice. Much of the storage layer rebuilds a storage from a
slice of its parent — contiguous slicing re-seats the data pointer (InternalArray.Slice(offset, size)), an
empty view allocates a zero-length slice, Clone() clones the slice, GetData(int[]) slices a
sub-array. Those paths count in ELEMENTS and take the new storage's type from the slice's
TypeCode. A plain byte slice would silently turn a string array into a uint8 array of the
wrong length on every one of them; this slice keeps element semantics (Count,
Slice(long, long) and ItemLength are per string element) and carries the descriptor,
so each of those paths produces a correct string storage without knowing about strings. Any path that instead
dispatches a numeric kernel on TypeCode meets String and refuses.
Layout. Element i occupies bytes [i * ItemSize, (i + 1) * ItemSize) of Bytes:
for S one byte per character, for U one native-endian uint32 code point per character; both
NUL-padded. Typed access exists only for the raw units (byte, and uint for U), which is
what the unit-view movement kernels and the byte I/O paths use; everything else goes through the codec
(GetIndex(long), SetIndex(long, object)).
Constructors
StringArraySlice(ArraySlice<byte>, DType)
Wraps bytes as bytes.Count / descr.itemsize string elements of descr.
public StringArraySlice(ArraySlice<byte> bytes, DType descr)
Parameters
bytesArraySlice<byte>The raw buffer; its length must be a whole number of elements.
descrDTypeA sized, native-byte-order
SorUdescriptor.
Exceptions
- ArgumentNullException
descris null.- ArgumentException
The descriptor is not a sized native string descriptor, or the buffer is not a whole number of its elements.
Properties
Address
The first byte of the buffer.
public byte* Address { get; }
Property Value
- byte*
Bytes
public ArraySlice<byte> Bytes { get; }
Property Value
BytesLength
public long BytesLength { get; }
Property Value
Chars
public int Chars { get; }
Property Value
Count
The number of string ELEMENTS (not bytes).
public long Count { get; }
Property Value
Descr
The element descriptor (sized, native): |S5, <U3.
public DType Descr { get; }
Property Value
IsReleased
Diagnostic: true once the underlying buffer has been freed.
public bool IsReleased { get; }
Property Value
IsUnicode
True for U (UCS-4 units), false for S (bytes).
public bool IsUnicode { 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 — the IMemoryBlock "size of a single item".
public int ItemLength { get; }
Property Value
ItemSize
Bytes per element (Descr.itemsize).
public int ItemSize { get; }
Property Value
MemoryBlock
The underlying byte block (pool, reference count).
public IMemoryBlock MemoryBlock { get; }
Property Value
TypeCode
Always String: the shared lane of both string classes.
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, bool)
Allocates a buffer for count elements of descr from the shared pool.
public static StringArraySlice Allocate(DType descr, long count, bool fillZeros)
Parameters
descrDTypeA sized, native string descriptor.
countlongThe number of string elements.
fillZerosboolTrue to NUL-fill (every element reads
""/b""); false leaves pool noise, for callers that write every byte.
Returns
- StringArraySlice
The new slice.
Remarks
The NUL fill takes the numeric np.zeros route (AllocateZeroed(long)):
calloc, or for a large block the operating system's demand-zero pages, which are zeroed when first
written. A fill loop over a fresh block wrote every byte up front: 3.2 MB took ~115 µs where NumPy's
calloc takes ~10 µs (its U allocation is zeroed the same way, NPY_NEEDS_INIT).
Exceptions
- ArgumentNullException
descris null.- ArgumentException
See the constructor.
- OutOfMemoryException
The allocation failed.
AsSpan<T>()
The raw units as a span: byte (any string class) or uint (a U buffer's code points).
public UnmanagedSpan<T> AsSpan<T>() where T : unmanaged
Returns
- UnmanagedSpan<T>
A span over the whole buffer, no copy.
Type Parameters
Exceptions
- NotSupportedException
Any other
T.
Clone()
A deep copy of the elements (fresh buffer, same descriptor).
public IArraySlice Clone()
Returns
- IArraySlice
The copy.
Clone<T>()
A typed clone is only defined for the raw byte units.
public ArraySlice<T> Clone<T>() where T : unmanaged
Returns
- ArraySlice<T>
A copy of the raw bytes.
Type Parameters
Tbyte.
Exceptions
- NotSupportedException
Tis not byte.
CopyTo<T>(UnmanagedSpan<T>)
Copies the RAW bytes of the buffer 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 bytes of the buffer into destination (a byte-level copy, exactly like
ArraySlice<T>'s implementation of this member — 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: the value is encoded ONCE into the first element and the
bytes are replicated by doubling block copies (np.full, fill).
public void Fill(object value)
Parameters
valueobjectThe text value (see SetIndex(long, object)).
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: a string for U, a byte[] for
S, trailing NULs removed (NumPy's getitem).
public object GetIndex(long index)
Parameters
indexlongThe element index.
Returns
- object
The value.
Remarks
NDAnchoredAttribute (lost-anchor site LT29): the reader allocates the value before it copies
the element out, and this slice is what keeps the buffer's memory block reachable once the caller's array is
gone (np.char.upper(a).item(0)), so the slice is rooted to the end of the read.
Exceptions
- SystemError
A
Uunit is aboveU+10FFFF.
GetIndex<T>(long)
Typed element access is meaningless for text; 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 — a string per U element, a
byte[] per S element, trailing NULs removed.
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
The class test and the element width are read once for the run instead of once per element, and each element
goes straight to its codec reader (a tolist() of short S / U elements spent about as much
on the per-element dispatch as on the decode). NDAnchoredAttribute (lost-anchor site LT29): the
loop reads the buffer through a raw pointer while it allocates one value per element, so the slice — what keeps
the memory block reachable — is rooted to the end.
Exceptions
- SystemError
A
Uunit aboveU+10FFFF, at the first such element (the slots before it are filled).
GetPinnableReference<T>()
A reference to the first raw unit.
public ref T GetPinnableReference<T>() where T : unmanaged
Returns
- T
The reference.
Type Parameters
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 with NumPy's setitem rules
(truncate to the width, NUL-pad; a string into S is ASCII-encoded, a byte[] into
U ASCII-decoded).
public void SetIndex(long index, object value)
Parameters
indexlongThe element index.
valueobjectA string,
byte[], char, null (Python'sNone, stored as'None'), a number (stored as itsstr()) or a 0-d NDArray.
Exceptions
- UnicodeEncodeError
A non-ASCII string into
S.- UnicodeDecodeError
Non-ASCII bytes into
U.- ValueError
A sequence (
setting an array element with a sequence).- NotSupportedException
A value that is neither text, bytes, None, a number nor a 0-d array (a C# object has no Python
str()to store).
SetIndex<T>(long, T)
Typed element writes are meaningless for text; 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 memory.
public IArraySlice Slice(long start)
Parameters
startlongThe first element.
Returns
- IArraySlice
A string slice over the same bytes.
Slice(long, long)
count elements from start, sharing memory (the byte range is scaled by ItemSize).
public IArraySlice Slice(long start, long count)
Parameters
Returns
- IArraySlice
A string slice over the same bytes.
ToArray()
The elements as a managed array: string[] for U, byte[][] for S (each trailing-NUL
stripped).
public Array ToArray()
Returns
- Array
The values in buffer order.
Remarks
NDAnchoredAttribute (lost-anchor site LT29): one value is allocated per element while the buffer is read, so the slice is rooted to the end of the copy.
Exceptions
- SystemError
A
Uunit is aboveU+10FFFF.
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()