Table of Contents

Class StringDTypeMeta

Namespace
NumSharp
Assembly
NumSharp.dll

NumPy's two fixed-width string DType classes — numpy.dtypes.BytesDType (kind 'S', type number 18, one byte per character, NumPy's np.bytes_) and numpy.dtypes.StrDType (kind 'U', type number 19, one UCS-4 code point = 4 bytes per character, NumPy's np.str_). Both are PARAMETRIC: the length lives on the descriptor (S5 → itemsize 5, U5 → 20), so promotion runs common_instance(DType, DType) (the longer string wins) and every cast resolves the destination length (ToStringCastingImpl, StringToStringCastingImpl).

public sealed class StringDTypeMeta : DTypeMeta
Inheritance
StringDTypeMeta
Inherited Members

Remarks

One storage lane, two classes. Both classes back arrays through the single String lane: the storage holds raw bytes (an S element is itemsize bytes, a U element itemsize / 4 native-endian uint32 code points), NUL-padded, and the descriptor says how to read them. Moving data (copy, view, broadcast, fancy indexing, string↔string casts) never decodes — it runs the existing uint8/uint32 kernels over a "unit view" with one extra trailing axis — so it is byte exact by construction. Only element access (C# string / byte[] in and out) runs the codec (NDStringCodec).

The slots are ports of dtypemeta.c: string_and_unicode_default_descr (a FRESH 1-character descriptor, which is why np.zeros(3, 'U') is <U1), string_unicode_common_dtype (a string class absorbs every numeric class, U absorbs S, anything else defers), string_unicode_common_instance (the longer descriptor, made canonical), string_discover_descr_from_pyobject (a scalar's length) and string_unicode_new (StrDType(5) → dtype('<U5')).

Registry policy. StrDType owns String and string ((DType)NPTypeCode.String and np.dtype(typeof(string)) are dtype('<U')); BytesDType owns neither — its C# element byte[] must keep resolving to uint8 the way every C# array type resolves to its element class — so an S dtype is requested by name ("S5", bytes_, BytesDType).

Properties

IsUnicode

True for StrDType (kind 'U', UCS-4 code points), false for BytesDType (kind 'S', bytes).

public bool IsUnicode { get; }

Property Value

bool

ItemFlags

NumPy flags U items NPY_NEEDS_INIT (8) — NUL padding is part of the value; S reports 0.

public override int ItemFlags { get; }

Property Value

int

MaxChars

The largest character count a descriptor of this class can hold — NumPy's limit that the item size fits a C int: 2147483647 for S, 536870911 (INT_MAX / 4) for U.

public int MaxChars { get; }

Property Value

int

UnitSize

Bytes per character — the storage "unit": 4 for U (one uint32 code point), 1 for S.

public int UnitSize { get; }

Property Value

int

Methods

Descr(long)

A FRESH native descriptor of this class holding chars characters — the building block of every sized S/U descriptor (NumPy's PyArray_DescrNewFromType + elsize).

public DType Descr(long chars)

Parameters

chars long

Characters per element (0 = NumPy's unsized S0/U0, as a non-builtin copy).

Returns

DType

A descriptor with itemsize == chars * UnitSize; never the singleton, so its isbuiltin is 0.

Exceptions

TypeError

chars exceeds MaxChars (NumPy's string of length N is too large to store inside array.).

ArgumentOutOfRangeException

chars is negative.

Instantiate()

The no-argument class call StrDType(): NumPy's string classes require the length argument, so this raises NumPy's verbatim function takes exactly 1 positional argument (0 given).

public override DType Instantiate()

Returns

DType

Never returns.

Exceptions

TypeError

Always.

Instantiate(long)

The class call with a length — NumPy's string_unicode_new: np.dtypes.StrDType(5) is dtype('<U5'), np.dtypes.BytesDType(3) is dtype('S3'), and a length of 0 is a FRESH unsized descriptor (dtype('<U'), isbuiltin == 0).

public DType Instantiate(long size)

Parameters

size long

The length in characters (NumPy's Python int argument).

Returns

DType

A fresh native descriptor.

Exceptions

ValueError

A negative length: Strings cannot have a negative size but a size of -1 was given.

TypeError

A length whose item size does not fit a C int: Strings too large to store inside array.

common_dtype(DTypeMeta)

string_unicode_common_dtype: a string class is the common class of itself and any NUMERIC legacy class (bool, the integers, the floats, complex — and NumSharp's Decimal/Char, which are numeric storage classes), and StrDType absorbs BytesDType. Anything else — the datetime pair, the abstract NEP 50 literal classes (np.result_type(U5_array, 3) raises), BytesDType asked about StrDType — defers (null, NumPy's NotImplemented).

public override DTypeMeta common_dtype(DTypeMeta other)

Parameters

other DTypeMeta

The class to promote with.

Returns

DTypeMeta

This class, or null when it does not know other.

Exceptions

ArgumentNullException

other is null.

common_instance(DType, DType)

string_unicode_common_instance: the LONGER of two descriptors of this class (the first on a tie), in native byte order — promote_types('>U5', '>U3') is <U5.

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

The canonical form of the longer one.

Exceptions

ArgumentNullException

Either descriptor is null.

default_descr()

string_and_unicode_default_descr: a FRESH one-character descriptor (S1 / U1) — what a bare class request turns into when an array is allocated (np.zeros(3, 'U') is <U1, np.array([], dtype='S') is |S1). It is NOT the unsized singleton, which only names the class.

public override DType default_descr()

Returns

DType

A new S1 / U1 descriptor.

discover_descr_from_pyobject(object)

string_discover_descr_from_pyobject: the descriptor a C# scalar needs to be stored whole — a string holds as many characters as it has CODE POINTS (Python's len(str): a surrogate pair is one, a lone surrogate is one), a C# char one (Python's one-character str), a byte[] as many as it has bytes, any other value as many as its str() has (PyArray_DTypeFromObjectStringDiscovery: np.array([1, 22], dtype='U') is <U2, None is 'None', 4). For U the item size is 4 bytes per character.

public override DType discover_descr_from_pyobject(object obj)

Parameters

obj object

An element value: text (a string or a char), bytes, a number or null (None).

Returns

DType

A fresh sized descriptor of this class.

Exceptions

TypeError

The value is too long for a descriptor of this class (NumPy's string too large to store inside array.).

NotSupportedException

A value that is neither text, bytes, a number nor None (a C# object has no Python str()).

is_known_scalar_type(Type)

string_known_scalar_types (python_builtins_are_known_scalar_types): the Python str, bytes, int, float, complex and bool are scalars of either string class — in the C# boundary map string, byte[], the integer primitives and BigInteger, float / double, Complex and bool. A NumPy scalar (Half, char, decimal) is not: it is discovered through its own dtype and promoted.

public override bool is_known_scalar_type(Type type)

Parameters

type Type

The C# type of a candidate element value.

Returns

bool

True for the Python builtin scalar types.