Class DTypeMeta
- Namespace
- NumSharp
- Assembly
- NumSharp.dll
The DType CLASS — NumPy's PyArray_DTypeMeta (type(np.dtype('f8')), i.e.
np.dtypes.Float64DType). One live object per dtype class; a DType is an INSTANCE of it
(the descriptor). This is NEP 41/42's two-level model: behaviour lives on the class as virtual "slots"
(common_dtype(DTypeMeta), common_instance(DType, DType), default_descr(),
ensure_canonical(DType), discover_descr_from_pyobject(object), is_known_scalar_type(Type),
the casting implementations), parameters live on the instance (a datetime unit, a byte order).
public abstract class DTypeMeta
- Inheritance
-
DTypeMeta
- Derived
- Inherited Members
Remarks
Names are NumPy's, case for case. Every member NumPy names keeps NumPy's spelling: the Python class
attributes (type, _abstract, _parametric, _legacy,
_is_numeric), the C struct fields of PyArray_DTypeMeta / NPY_DType_Slots
(singleton, type_num, flags, castingimpls,
within_dtype_castingimpl) and the NEP 42 slots of dtype_api.h (default_descr(),
common_dtype(DTypeMeta), …). C function names keep NumPy's PascalCase after the PyArray_ prefix
(GetCastingImpl(DTypeMeta) is PyArray_GetCastingImpl, AddCastingImpl(CastingImpl) is
PyArray_AddCastingImplementation). PascalCase members (Name, TypeCode,
Kind, …) are NumSharp's own and have no NumPy name. NumPy's slots setitem and
getitem and three functions of the legacy PyArray_ArrFuncs table (copyswapn,
fill, nonzero) are internal members the array object's code calls (the np-layer dtype plan's
P3); finalize_descr, get_constant, the rest of the ArrFuncs table and the 2.4
sort_meth / argsort_meth are not ported: NumSharp's kernels select on
NPTypeCode instead.
Compatibility contract. NPTypeCode stays the storage / kernel discriminator: every meta that has storage exposes it as TypeCode, and a future storage-backed dtype adds one enum member and registers it here — the enum is an optimisation the registry hands out, not the identity. A meta without storage (DatetimeDTypeMeta in Stage A) has TypeCode == Empty; allocating storage for its descriptors raises NotSupportedException naming the missing piece.
Type numbers follow NumPy's NPY_TYPES on the host's C long model (Half = 23,
DateTime = 21, TimeDelta = 22; the 4- and 8-byte integers take the numbers NumPy gives them on
this platform, see DTypeRegistry); the two NumSharp-only dtypes take the user-defined range
(Decimal = 256, Char = 257), which is also what makes their descriptors report
isbuiltin == 2. The number ORDER is load-bearing: the builtin common_dtype defers to the operand
with the larger type number ("the more generic one handles it"), exactly as NumPy's
default_builtin_common_dtype does.
NotImplemented is spelled null: common_dtype(DTypeMeta) returns null when this
class does not know the other one, and CommonDType(DTypeMeta, DTypeMeta) then asks the other class
(NEP 42's two-sided __common_dtype__ protocol) before raising DTypePromotionError.
NEP 55 reservations. HasReferences, get_clear_loop(DType) and
get_fill_zero_loop(DType) are the slots a reference-holding dtype (StringDType) will override;
the builtins report false / null. The fixed-width S/U classes (StringDTypeMeta)
hold no references — their items are raw bytes — so they report false too.
Constructors
DTypeMeta(string, string, int, Type, string, NPTypeCode, char, char, int, int, DTypeFlags, IReadOnlyList<string>)
Builds a DType class. Called by the registry / subclasses only — every class is a singleton reachable via
DTypeRegistry and np.dtypes.
protected DTypeMeta(string name, string modulePath, int typeNum, Type scalarType, string scalarName, NPTypeCode typeCode, char kind, char typeChar, int itemSize, int alignment, DTypeFlags flags, IReadOnlyList<string> aliases = null)
Parameters
namestringNumPy's class name (
"Int32DType","DateTime64DType","_PyLongDType").modulePathstringThe module the class lives in —
"numpy.dtypes"for the NumPy-mirrored classes,"numsharp.dtypes"for the NumSharp-only ones — so ToString() renders NumPy's<class 'numpy.dtypes.Int32DType'>.typeNumintNumPy's
type_num(see the class remarks); -1 for abstract classes.scalarTypeTypeThe C# scalar type of one element (
typeof(int)); null when there is none yet.scalarNamestringNumPy's
dtype.type.name("int32","datetime64","decimal").typeCodeNPTypeCodeThe storage discriminator, Empty when the class has no storage.
kindcharNumPy's
dtype.kindcharacter ('b' 'i' 'u' 'f' 'c' 'M' 'm' 'U').typeCharcharNumPy's
dtype.char('?' 'b' 'B' 'h' 'H' 'i' 'I' 'l' 'L' 'e' 'f' 'd' 'D' 'M' 'm').itemSizeintElement size in bytes (-1 for abstract classes).
alignmentintRequired alignment in bytes (NumPy's
dtype.alignment).flagsDTypeFlagsThe DTypeFlags (
NPY_DT_LEGACY/_ABSTRACT/_PARAMETRIC/_NUMERIC).aliasesIReadOnlyList<string>Alias class names NumPy also exports (
"IntDType"forInt32DType).
Exceptions
- ArgumentNullException
nameormodulePathis null.
Fields
NPY_LIST_PICKLE
NumPy's NPY_LIST_PICKLE item flag (0x02, ndarraytypes.h): the items are Python objects, pickled as
a list, so their bytes mean nothing outside the process - PyArray_ToFile refuses to write them in binary
mode (cannot write object arrays to a file in binary mode). Set by StringDType.
public const int NPY_LIST_PICKLE = 2
Field Value
NPY_NEEDS_INIT
NumPy's NPY_NEEDS_INIT item flag (0x08, ndarraytypes.h): every allocation of a descriptor reporting
it starts zeroed, so np.empty of a U dtype holds empty strings rather than whatever the allocator
returned.
public const int NPY_NEEDS_INIT = 8
Field Value
Properties
Aliases
Alias class names NumPy also exports for this class (e.g. ByteDType for Int8DType).
public IReadOnlyList<string> Aliases { get; }
Property Value
Alignment
Required alignment in bytes.
public int Alignment { get; }
Property Value
FullName
The fully qualified class name: "numpy.dtypes.Int32DType".
public string FullName { get; }
Property Value
HasReferences
Whether items of this dtype hold references that must be cleared (NumPy's NPY_ITEM_REFCOUNT); false for every builtin.
public virtual bool HasReferences { get; }
Property Value
HasStorage
True when descriptors of this class can back an NDArray today (a storage NPTypeCode exists).
public bool HasStorage { get; }
Property Value
ItemFlags
NumPy's per-descriptor item flags (dtype.flags: NPY_ITEM_REFCOUNT = 0x01,
NPY_NEEDS_INIT = 0x08, …): 63 for a reference-holding class, 0 for every numeric builtin. A class
overrides it when NumPy sets other bits on its descriptors — StrDType reports
NPY_NEEDS_INIT (8), because a fixed-width Unicode item is NUL-padded and must start zeroed.
public virtual int ItemFlags { get; }
Property Value
- int
The flag bits every descriptor of this class reports. The one storage decision they drive is NPY_NEEDS_INIT: a fresh buffer of such a class is zero-filled even when uninitialized memory was asked for (NumPy's
PyArray_NewFromDescr_int).
ItemSize
Element size in bytes (-1 for abstract classes).
public int ItemSize { get; }
Property Value
Kind
NumPy's dtype.kind character ('b' bool, 'i'/'u' integers, 'f', 'c', 'M', 'm', 'U').
public char Kind { get; }
Property Value
ModulePath
The module path (type.module) used in ToString(): "numpy.dtypes" or "numsharp.dtypes".
public string ModulePath { get; }
Property Value
Name
NumPy's class name (type.name): "Int32DType", "DateTime64DType", "_PyLongDType".
public string Name { get; }
Property Value
ScalarName
NumPy's dtype.type.name: "int32", "bool", "datetime64", "decimal".
public string ScalarName { get; }
Property Value
TypeChar
NumPy's dtype.char — the unique one-character type code.
public char TypeChar { get; }
Property Value
TypeCode
The storage / kernel discriminator; Empty when the class has no storage.
public NPTypeCode TypeCode { get; }
Property Value
_abstract
NumPy's class attribute DType._abstract (NPY_DT_ABSTRACT): the class has no instances and only
takes part in promotion (the NEP 50 Python-scalar classes). Building a descriptor of it raises
TypeError.
public bool _abstract { get; }
Property Value
_is_numeric
NumPy's class attribute DType._is_numeric (NPY_DT_NUMERIC): bool, integer, float or complex.
public bool _is_numeric { get; }
Property Value
_legacy
NumPy's class attribute DType._legacy (NPY_DT_LEGACY): a dtype whose descriptor layout predates
NEP 41/42 — every builtin and the datetime pair. True means promotion and casting fall back to the legacy
tables for this class.
public bool _legacy { get; }
Property Value
_parametric
NumPy's class attribute DType._parametric (NPY_DT_PARAMETRIC): the instances carry parameters
(a unit, a length), so promotion must run common_instance(DType, DType) and the bare class call raises.
public bool _parametric { get; }
Property Value
castingimpls
NumPy's slot field castingimpls: the casts from this class to every OTHER class, keyed by the
destination class (the within-dtype cast is within_dtype_castingimpl, not an entry here — the
same split as NumPy's).
public IReadOnlyDictionary<DTypeMeta, CastingImpl> castingimpls { get; }
Property Value
- IReadOnlyDictionary<DTypeMeta, CastingImpl>
A read-only live view: a cast registered later shows up in it, enumerating it never blocks a registration, and it cannot be cast back to a writable dictionary. Use GetCastingImpl(DTypeMeta) for a single lookup.
flags
NumPy's PyArray_DTypeMeta.flags: the NPY_DT_* word with NumPy's bit values. Python reads its
bits as _legacy, _abstract, _parametric and
_is_numeric.
public DTypeFlags flags { get; }
Property Value
singleton
NumPy's PyArray_DTypeMeta.singleton: the canonical native descriptor of a non-parametric class, the
object np.dtype('i8') returns every time (np.dtype('i8') is np.dtype('i8')). Null for abstract
classes; for the parametric datetime pair it is the generic-unit descriptor and default_descr()
hands out COPIES of it (a copy reports isbuiltin == 0, as in NumPy).
public DType singleton { get; }
Property Value
type
NumPy's class attribute DType.type (the C field scalar_type): the scalar type of one element,
which in NumSharp is the C# type (typeof(double) where NumPy has numpy.float64). Null when the
class has no C# scalar yet — the datetime pair before Stage C, the abstract classes.
public Type type { get; }
Property Value
type_num
NumPy's PyArray_DTypeMeta.type_num: the NPY_TYPES number of the class (the host's C
long model for the 4- and 8-byte integers; 256+ for the NumSharp-only dtypes; -1 for an abstract
class). An int as in NumPy's struct; a descriptor's type_num reports the
same number typed as NPY_TYPES.
public int type_num { get; }
Property Value
within_dtype_castingimpl
NumPy's slot field within_dtype_castingimpl: the casting implementation between two instances of this
class — the one DTypeCasting consults when both descriptors belong to this class (a byte-order
change, a datetime unit change, a plain copy).
public CastingImpl within_dtype_castingimpl { get; }
Property Value
- CastingImpl
The registered within-dtype cast, or null when the class registered none (the abstract NEP 50 scalar classes and the vestigial string slot). Read without a lock, like GetCastingImpl(DTypeMeta).
Methods
GetCastingImpl(DTypeMeta)
The CastingImpl from this class to to (the within-dtype implementation when
to is this class), or null when no cast exists — NumPy's PyArray_GetCastingImpl.
Every cast question of DTypeCasting starts here (each np.can_cast over descriptors and
each DType < / <= / > / >= comparison), and so does
CastDescrToDType(DType, DTypeMeta) whenever the common class is parametric (datetime64,
timedelta64).
public CastingImpl GetCastingImpl(DTypeMeta to)
Parameters
toDTypeMetaThe destination class, compared by reference.
Returns
- CastingImpl
The registered implementation, or null when none is registered for the pair — an impossible cast, which GetCastInfo(DType, DType, DTypeMeta, out long) reports as null and CheckCastSafety(NPY_CASTING, DType, DType, DTypeMeta) as false.
Remarks
Takes no lock: TryGetValue(TKey, out TValue) reads the dictionary without its write lock and the within-dtype slot is a volatile read, so concurrent cast and promotion queries never contend with each other or with a registration. A query racing the registration of the same pair returns either null or the registered implementation.
Exceptions
- ArgumentNullException
tois null.
Instantiate()
The NumPy class call Int8DType(): the no-argument instantiation returns the singleton for a
non-parametric legacy class, and raises NumPy's TypeError for a parametric one
(DateTime64DType() → "Preliminary-API: Flexible/Parametric legacy DType … can only be instantiated
using np.dtype(...)"), verbatim. C# cannot call a class object, so the call is this method.
public virtual DType Instantiate()
Returns
- DType
The class's singleton descriptor.
Exceptions
- TypeError
The class is abstract, or parametric (NumPy's texts).
ToString()
NumPy's rendering of the class object (repr(np.dtypes.Int32DType)): <class 'numpy.dtypes.Int32DType'>.
public override string ToString()
Returns
- string
The class repr.
common_dtype(DTypeMeta)
NumPy's slot common_dtype (common_dtype): the class that can hold values of both this class
and other, or null (NumPy's NotImplemented) when this class does
not know the other — the caller then asks other the mirrored question.
public abstract DTypeMeta common_dtype(DTypeMeta other)
Parameters
otherDTypeMetaThe other operand's class.
Returns
- DTypeMeta
The common class, or null for NotImplemented.
common_instance(DType, DType)
NumPy's slot common_instance (common_instance): for a PARAMETRIC class, the descriptor that
can hold values of two descriptors of this class (the unit GCD for datetimes; the longer length for
strings). Non-parametric classes return their default descriptor (NumPy never calls the slot for them).
public virtual DType common_instance(DType descr1, DType descr2)
Parameters
descr1DTypeThe first descriptor, an instance of this class.
descr2DTypeThe second descriptor, an instance of this class.
Returns
- DType
The common descriptor.
default_descr()
NumPy's slot default_descr (NPY_DT_default_descr): the descriptor a bare class stands for — the
singleton for the builtins, a fresh generic-unit descriptor for datetime64 / timedelta64, the default
(int64/float64/complex128) for the abstract NEP 50 scalar classes.
public abstract DType default_descr()
Returns
- DType
The default descriptor; whether it is a shared singleton or a fresh copy is the class's choice, as in NumPy.
discover_descr_from_pyobject(object)
NumPy's slot discover_descr_from_pyobject: the descriptor a scalar of this class should get (the
default for every non-parametric class).
public virtual DType discover_descr_from_pyobject(object obj)
Parameters
objobjectThe scalar being discovered.
Returns
- DType
The descriptor an array built from
objtakes.
ensure_canonical(DType)
NumPy's slot ensure_canonical (ensure_native_byteorder for every legacy class): the descriptor
itself when its byte order is native, otherwise a FRESH copy of it with byte order '='
(PyArray_DescrNewByteorder(descr, NPY_NATIVE)) — never the class singleton, so the result of
canonicalising a non-native descriptor reports isbuiltin == 0 and keeps its metadata, as NumPy's does
(np.result_type(np.dtype('>f8')).isbuiltin is 0).
public virtual DType ensure_canonical(DType descr)
Parameters
descrDTypeA descriptor of THIS class.
Returns
- DType
descrwhen native (an explicit host-order byte order counts as native), else a native copy.
Exceptions
- ArgumentNullException
descris null.- ArgumentException
descris an instance of another class (NumPy only ever calls a class's slot on its own instances).
get_clear_loop(DType)
NumPy's slot get_clear_loop: a loop that releases the references an item holds.
public virtual NDInnerLoopFunc get_clear_loop(DType descr)
Parameters
descrDTypeThe descriptor whose items are cleared.
Returns
- NDInnerLoopFunc
The loop, or null when HasReferences is false (nothing to clear).
get_fill_zero_loop(DType)
NumPy's slot get_fill_zero_loop: a loop that writes this dtype's zero.
public virtual NDInnerLoopFunc get_fill_zero_loop(DType descr)
Parameters
descrDTypeThe descriptor whose items are zero-filled.
Returns
- NDInnerLoopFunc
The loop, or null when a zeroed buffer already is this dtype's zero (every builtin).
is_known_scalar_type(Type)
NumPy's slot is_known_scalar_type: whether a C# scalar of type belongs to this class.
public virtual bool is_known_scalar_type(Type type)
Parameters
typeTypeThe C# type of the scalar.
Returns
- bool
True when
typeis this class's scalar type.