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
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
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
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
ItemFlags
The descriptor flags NumPy reports for every StringDType (StringDTypeFlags).
public override int ItemFlags { get; }
Property Value
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
otherDTypeMetaThe class to promote with.
Returns
- DTypeMeta
This class for
StrDType(and for itself), else null.
Exceptions
- ArgumentNullException
otheris 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
Returns
- DType
A fresh descriptor.
Exceptions
- ArgumentNullException
Either descriptor is null.
- ArgumentException
Either descriptor is not a
StringDTypedescriptor (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
objobjectAn 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
descrDTypeA descriptor of this class.
Returns
- DType
descritself.
Exceptions
- ArgumentNullException
descris 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
typeTypeThe C# type of a candidate element value.
Returns
- bool
True for those types.