Table of Contents

Class VStringDTypeMeta

Namespace
NumSharp
Assembly
NumSharp.dll

NumPy's NEP 55 variable-width string DType class, numpy.dtypes.StringDType (kind and char 'T', type number 2056): every element is a 16-byte cell that holds a short UTF-8 string inline or points into an arena / heap the array owns, so one array can hold strings of any length without padding them all to the longest.

public sealed class VStringDTypeMeta : DTypeMeta
Inheritance
VStringDTypeMeta
Inherited Members

Remarks

Not a legacy class. Unlike the fixed-width StringDTypeMeta pair, StringDType is a NEP 42 class: its descriptors are never builtin singletons (np.dtype('T') is np.dtype('T') is False), report isbuiltin == 0, print their parameters (StringDType(na_object=None)) as both str() and repr(), have no byte order ('|'; newbyteorder raises), and compare equal only to another StringDType descriptor with the same na_object and coerce — a dtype STRING is not coerced (np.dtype('T') == 'T' is False).

Parameters (NumSharp.VStringParameters): na_object, the optional missing-data sentinel (NumPy keeps a Python object; NumSharp keeps the C# value under the boundary map of NumSharp.Backends.Strings.NDPyObject), and coerce. Create descriptors with StringDType(bool) / StringDType(object, bool) or np.dtype("T").

One storage lane with S / U. Arrays of this class use the String lane, which therefore does not say how an element is laid out: the descriptor's class does. Every route that moves elements as opaque fixed-width blobs is gated on StringDTypeMeta, never on the type code, and a StringDType array takes its own, reference-aware paths (each element is a 16-byte cell whose text an allocator owns). The class owns neither the lane nor the C# string type in the registry: (DType)NPTypeCode.String and np.dtype(typeof(string)) stay <U.

The slots are ports of numpy/_core/src/multiarray/stringdtype/dtype.c: common_dtype (only StrDType promotes to it — T + U is T, T + S or a number has no common DType), common_instance (compatible missing-data objects, coerce only when both have it), string_discover_descriptor_from_pyobject, stringdtype_ensure_canonical (a descriptor is always canonical), stringdtype_is_known_scalar_type and the default descriptor StringDType().

Fields

ALIGNOF_NPY_PACKED_STATIC_STRING

NumPy's ALIGNOF_NPY_PACKED_STATIC_STRING (_Alignof(size_t)): the cell holds a pointer-sized field, so a descriptor's alignment is 8.

public const int ALIGNOF_NPY_PACKED_STATIC_STRING = 8

Field Value

int

SIZEOF_NPY_PACKED_STATIC_STRING

NumPy's SIZEOF_NPY_PACKED_STATIC_STRING (2 * sizeof(size_t), stringdtype/dtype.h): the bytes of one element cell, the itemsize of every StringDType descriptor.

public const int SIZEOF_NPY_PACKED_STATIC_STRING = 16

Field Value

int

StringDTypeFlags

NumPy's descriptor flags for StringDType: NPY_ITEM_REFCOUNT | NPY_LIST_PICKLE | NPY_NEEDS_INIT | NPY_USE_GETITEM | NPY_USE_SETITEM = 1 + 2 + 8 + 32 + 64 = 107.

public const int StringDTypeFlags = 107

Field Value

int

Properties

HasReferences

dtype.hasobject is True: a cell can own heap memory that must be freed (NumPy's clear loop).

public override bool HasReferences { get; }

Property Value

bool

ItemFlags

The descriptor flags NumPy reports for every StringDType (StringDTypeFlags).

public override int ItemFlags { get; }

Property Value

int

Methods

Instantiate()

The class call with no arguments, StringDType(): a fresh default descriptor.

public override DType Instantiate()

Returns

DType

A new StringDType().

common_dtype(DTypeMeta)

NumPy's common_dtype slot: StrDType promotes to StringDType (there is a cast from it); every other class defers (null, NumPy's NotImplemented), so T with S, a number, bool or a datetime has no common DType.

public override DTypeMeta common_dtype(DTypeMeta other)

Parameters

other DTypeMeta

The class to promote with.

Returns

DTypeMeta

This class for StrDType (and for itself), else null.

Exceptions

ArgumentNullException

other is null.

common_instance(DType, DType)

NumPy's common_instance (2.5.2's stringdtype_common_na_coerce): the two descriptors' missing-data objects must be compatible (CompatibleNA(VStringParameters, VStringParameters, out bool, out object)); the result takes the present one, and coerce only when BOTH descriptors coerce (StringDType() with StringDType(coerce=False) is StringDType(coerce=False) in either order). NumPy 2.4 read the first descriptor's flag twice (dtype1->coerce && dtype1->coerce), gh-31901.

public override DType common_instance(DType descr1, DType descr2)

Parameters

descr1 DType

A descriptor of this class.

descr2 DType

A descriptor of this class.

Returns

DType

A fresh descriptor.

Exceptions

ArgumentNullException

Either descriptor is null.

ArgumentException

Either descriptor is not a StringDType descriptor (a caller error: the promotion engine casts both operands to this class first).

TypeError

Both have missing-data objects and they differ: NumPy's Cannot find common instance for incompatible dtypes 'StringDType(na_object=None)' and 'StringDType(na_object=nan)'.

default_descr()

A FRESH StringDType() (no missing-data object, coercion on) — NumPy has no builtin singleton for this class, because each descriptor instance owns its own string allocator.

public override DType default_descr()

Returns

DType

A new default descriptor.

discover_descr_from_pyobject(object)

NumPy's string_discover_descriptor_from_pyobject: the value must convert to text (as_pystring with coercion on — a bytes value decodes as strict UTF-8, anything else takes its str()), and the discovered descriptor is a fresh StringDType() whatever the value.

public override DType discover_descr_from_pyobject(object obj)

Parameters

obj object

An element value.

Returns

DType

A fresh StringDType().

Exceptions

UnicodeDecodeError

A byte[] that is not valid UTF-8 (CPython's decoder error).

ensure_canonical(DType)

stringdtype_ensure_canonical: every StringDType descriptor is canonical (it is returned as is).

public override DType ensure_canonical(DType descr)

Parameters

descr DType

A descriptor of this class.

Returns

DType

descr itself.

Exceptions

ArgumentNullException

descr is null.

is_known_scalar_type(Type)

NumPy's stringdtype_is_known_scalar_type: the Python builtins (str, bytes, int, float, complex, bool) and every builtin NumPy scalar type — in the C# boundary map string, char, byte[], the integer primitives, BigInteger, float, double, Half, decimal, Complex and bool.

public override bool is_known_scalar_type(Type type)

Parameters

type Type

The C# type of a candidate element value.

Returns

bool

True for those types.