Table of Contents

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

name string

NumPy's class name ("Int32DType", "DateTime64DType", "_PyLongDType").

modulePath string

The 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'>.

typeNum int

NumPy's type_num (see the class remarks); -1 for abstract classes.

scalarType Type

The C# scalar type of one element (typeof(int)); null when there is none yet.

scalarName string

NumPy's dtype.type.name ("int32", "datetime64", "decimal").

typeCode NPTypeCode

The storage discriminator, Empty when the class has no storage.

kind char

NumPy's dtype.kind character ('b' 'i' 'u' 'f' 'c' 'M' 'm' 'U').

typeChar char

NumPy's dtype.char ('?' 'b' 'B' 'h' 'H' 'i' 'I' 'l' 'L' 'e' 'f' 'd' 'D' 'M' 'm').

itemSize int

Element size in bytes (-1 for abstract classes).

alignment int

Required alignment in bytes (NumPy's dtype.alignment).

flags DTypeFlags

The DTypeFlags (NPY_DT_LEGACY / _ABSTRACT / _PARAMETRIC / _NUMERIC).

aliases IReadOnlyList<string>

Alias class names NumPy also exports ("IntDType" for Int32DType).

Exceptions

ArgumentNullException

name or modulePath is 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

int

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

int

Properties

Aliases

Alias class names NumPy also exports for this class (e.g. ByteDType for Int8DType).

public IReadOnlyList<string> Aliases { get; }

Property Value

IReadOnlyList<string>

Alignment

Required alignment in bytes.

public int Alignment { get; }

Property Value

int

FullName

The fully qualified class name: "numpy.dtypes.Int32DType".

public string FullName { get; }

Property Value

string

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

bool

HasStorage

True when descriptors of this class can back an NDArray today (a storage NPTypeCode exists).

public bool HasStorage { get; }

Property Value

bool

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

int

Kind

NumPy's dtype.kind character ('b' bool, 'i'/'u' integers, 'f', 'c', 'M', 'm', 'U').

public char Kind { get; }

Property Value

char

ModulePath

The module path (type.module) used in ToString(): "numpy.dtypes" or "numsharp.dtypes".

public string ModulePath { get; }

Property Value

string

Name

NumPy's class name (type.name): "Int32DType", "DateTime64DType", "_PyLongDType".

public string Name { get; }

Property Value

string

ScalarName

NumPy's dtype.type.name: "int32", "bool", "datetime64", "decimal".

public string ScalarName { get; }

Property Value

string

TypeChar

NumPy's dtype.char — the unique one-character type code.

public char TypeChar { get; }

Property Value

char

TypeCode

The storage / kernel discriminator; Empty when the class has no storage.

public NPTypeCode TypeCode { get; }

Property Value

NPTypeCode

_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

bool

_is_numeric

NumPy's class attribute DType._is_numeric (NPY_DT_NUMERIC): bool, integer, float or complex.

public bool _is_numeric { get; }

Property Value

bool

_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

bool

_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

bool

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

DTypeFlags

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

DType

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

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

int

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

to DTypeMeta

The 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

to is 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

other DTypeMeta

The 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

descr1 DType

The first descriptor, an instance of this class.

descr2 DType

The 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

obj object

The scalar being discovered.

Returns

DType

The descriptor an array built from obj takes.

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

descr DType

A descriptor of THIS class.

Returns

DType

descr when native (an explicit host-order byte order counts as native), else a native copy.

Exceptions

ArgumentNullException

descr is null.

ArgumentException

descr is 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

descr DType

The 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

descr DType

The 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

type Type

The C# type of the scalar.

Returns

bool

True when type is this class's scalar type.