Class DTypeCasting
- Namespace
- NumSharp
- Assembly
- NumSharp.dll
The NEP 43 casting engine over descriptors — the ports of NumPy's convert_datatype.c entry points:
GetCastingImpl(DTypeMeta, DTypeMeta) (PyArray_GetCastingImpl), GetCastInfo(DType, DType, DTypeMeta, out long)
(PyArray_GetCastInfo), CheckCastSafety(NPY_CASTING, DType, DType, DTypeMeta) (PyArray_CheckCastSafety),
CanCastTypeTo(DType, DType, NPY_CASTING) (PyArray_CanCastTypeTo — the engine behind np.can_cast),
EquivTypes(DType, DType) (PyArray_EquivTypes), MinCastSafety(NPY_CASTING, NPY_CASTING) and the casting-string
parser. Every question is answered by the CastingImpl registered for the CLASS pair, so a new
dtype joins np.can_cast by registering its casts — no table edit.
public static class DTypeCasting
- Inheritance
-
DTypeCasting
- Inherited Members
Remarks
For the storage-backed builtins the answers are exactly those np.can_cast(NPTypeCode, NPTypeCode) always
gave (the BuiltinCastingImpl encodes the same table + kind-order rules), which the
dtype_text differential-fuzz tier gates. What is new is everything a table cannot express: byte order
(can_cast('>i4', 'i4', 'equiv') is True, 'no' is False) and the datetime unit rules.
Methods
CanCastTypeTo(DType, DType, NPY_CASTING)
NumPy's PyArray_CanCastTypeTo — the engine behind np.can_cast(from, to, casting) for two
descriptors. An impossible cast is False, never an error. An UNSIZED string target (S0/U0, i.e.
np.dtype('U')) stands for its CLASS — "cast to whatever length you need" — so
can_cast('i4', 'U', 'safe') is True although can_cast('i4', 'U10', 'safe') is False, and
can_cast('U5', 'U', 'no') is True.
public static bool CanCastTypeTo(DType from, DType to, NPY_CASTING casting)
Parameters
fromDTypeThe source descriptor.
toDTypeThe target descriptor (an unsized string descriptor means its class).
castingNPY_CASTINGThe rule the cast must satisfy.
Returns
- bool
True when the cast satisfies
casting.
Exceptions
- ArgumentNullException
Either descriptor is null.
CastingToString(NPY_CASTING)
NumPy's npy_casting_to_string: the casting string of a level.
public static string CastingToString(NPY_CASTING casting)
Parameters
castingNPY_CASTING
Returns
CheckCastSafety(NPY_CASTING, DType, DType, DTypeMeta)
NumPy's PyArray_CheckCastSafety: whether casting from to to (or to
the class toMeta when to is null) satisfies casting.
Short-circuits on the implementation's own minimal safety and only resolves descriptors when the request is
stricter than that.
public static bool CheckCastSafety(NPY_CASTING casting, DType from, DType to, DTypeMeta toMeta)
Parameters
castingNPY_CASTINGfromDTypetoDTypetoMetaDTypeMeta
Returns
EquivTypes(DType, DType)
NumPy's PyArray_EquivTypes: two descriptors are equivalent when casting between them is a
no-cast (same class and byte order; for datetimes also an exact metric-prefix fold such as
M8[1000ms] → M8[s], which is why NumPy's == is not symmetric there — Equals(DType)
is structural instead).
public static bool EquivTypes(DType type1, DType type2)
Parameters
Returns
GetCastInfo(DType, DType, DTypeMeta, out long)
NumPy's PyArray_GetCastInfo: the cast safety between two descriptors (to may be
null to ask about the class toMeta — "cast to whatever instance you pick"), plus the
byte offset at which the cast is a plain view (NoView when it is not). Null when
the cast is impossible (NumPy returns -1).
public static NPY_CASTING? GetCastInfo(DType from, DType to, DTypeMeta toMeta, out long viewOffset)
Parameters
Returns
GetCastingImpl(DTypeMeta, DTypeMeta)
The casting implementation from one class to another, or null when no cast exists — PyArray_GetCastingImpl.
public static CastingImpl GetCastingImpl(DTypeMeta from, DTypeMeta to)
Parameters
Returns
KindToOrdering(char)
NumPy's dtype_kind_to_ordering: the kind ordering behind same_kind casting —
b(0) < u(1) < i(2) < f(4) < c(5) < S(6) < U(7) < V(8) < O(9); datetime kinds do not fit
the hierarchy (-1).
public static int KindToOrdering(char kind)
Parameters
kindcharA descriptor's kind character (
dtype.kind), not a type character.
Returns
- int
The kind's rank, or -1 for a kind outside the hierarchy (the datetime kinds
'M'/'m', NumSharp's own decimal / char kinds, and'a', the bytes alias NumPy 2.5 removed from this switch with the alias itself: no descriptor has that kind).
MinCastSafety(NPY_CASTING, NPY_CASTING)
NumPy's PyArray_MinCastSafety: the LESS safe of two cast levels (the enum is ordered
no < equiv < safe < same_kind < unsafe, so the larger value wins).
public static NPY_CASTING MinCastSafety(NPY_CASTING casting1, NPY_CASTING casting2)
Parameters
casting1NPY_CASTINGcasting2NPY_CASTING
Returns
ParseCasting(string)
NumPy's PyArray_CastingConverter (string_converter_helper + casting_parser): the
case-sensitive casting strings.
public static NPY_CASTING ParseCasting(string casting)
Parameters
castingstringThe casting name.
Returns
- NPY_CASTING
The casting level.
Exceptions
- TypeError
castingis null: NumPy'scasting must be str, not NoneType.- ValueError
Another string:
casting must be one of 'no', 'equiv', 'safe', 'same_kind', 'unsafe' (got …), the string quoted by Python'srepr(NumPy's%R), so"it's"shows as(got "it's").