Table of Contents

Class StringArraySlice

Namespace
NumSharp.Backends.Unmanaged
Assembly
NumSharp.dll

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

bytes ArraySlice<byte>

The raw buffer; its length must be a whole number of elements.

descr DType

A sized, native-byte-order S or U descriptor.

Exceptions

ArgumentNullException

descr is 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

The raw buffer: Count × ItemSize bytes.

public ArraySlice<byte> Bytes { get; }

Property Value

ArraySlice<byte>

BytesLength

Total bytes (Count × ItemSize).

public long BytesLength { get; }

Property Value

long

Chars

Characters per element: ItemSize for S, ItemSize / 4 for U.

public int Chars { get; }

Property Value

int

Count

The number of string ELEMENTS (not bytes).

public long Count { get; }

Property Value

long

Descr

The element descriptor (sized, native): |S5, <U3.

public DType Descr { get; }

Property Value

DType

IsReleased

Diagnostic: true once the underlying buffer has been freed.

public bool IsReleased { get; }

Property Value

bool

IsUnicode

True for U (UCS-4 units), false for S (bytes).

public bool IsUnicode { 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 — the IMemoryBlock "size of a single item".

public int ItemLength { get; }

Property Value

int

ItemSize

Bytes per element (Descr.itemsize).

public int ItemSize { get; }

Property Value

int

MemoryBlock

The underlying byte block (pool, reference count).

public IMemoryBlock MemoryBlock { get; }

Property Value

IMemoryBlock

TypeCode

Always String: the shared lane of both string classes.

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, bool)

Allocates a buffer for count elements of descr from the shared pool.

public static StringArraySlice Allocate(DType descr, long count, bool fillZeros)

Parameters

descr DType

A sized, native string descriptor.

count long

The number of string elements.

fillZeros bool

True 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

descr is 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

T

byte, or uint for U.

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

T

byte.

Exceptions

NotSupportedException

T is 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

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 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

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: 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

value object

The text value (see SetIndex(long, object)).

Exceptions

UnicodeEncodeError

See SetIndex(long, object).

UnicodeDecodeError

See SetIndex(long, object).

NotSupportedException

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: a string for U, a byte[] for S, trailing NULs removed (NumPy's getitem).

public object GetIndex(long index)

Parameters

index long

The 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 U unit is above U+10FFFF.

GetIndex<T>(long)

Typed element access is meaningless for text; 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 — a string per U element, a byte[] per S element, trailing NULs removed.

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

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 U unit above U+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

T

byte, or uint for U.

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

index long

The element index.

value object

A string, byte[], char, null (Python's None, stored as 'None'), a number (stored as its str()) 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

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 memory.

public IArraySlice Slice(long start)

Parameters

start long

The 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

start long

The first element.

count long

The number of elements.

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 U unit is above U+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()

Returns

bool