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
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
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
UnitSize
Bytes per character — the storage "unit": 4 for U (one uint32 code point), 1 for S.
public int UnitSize { get; }
Property Value
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
charslongCharacters 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 itsisbuiltinis 0.
Exceptions
- TypeError
charsexceeds MaxChars (NumPy'sstring of length N is too large to store inside array.).- ArgumentOutOfRangeException
charsis 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
sizelongThe length in characters (NumPy's Python
intargument).
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
otherDTypeMetaThe class to promote with.
Returns
- DTypeMeta
This class, or null when it does not know
other.
Exceptions
- ArgumentNullException
otheris 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
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/U1descriptor.
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
objobjectAn 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
typeTypeThe C# type of a candidate element value.
Returns
- bool
True for the Python builtin scalar types.