Class NDScalarType
- Namespace
- NumSharp
- Assembly
- NumSharp.dll
A NumPy scalar TYPE: one class of NumPy's numpy.generic hierarchy, or one of the Python built-in classes
that hierarchy derives from, as a C# object. The ten abstract classes are np.generic, np.number,
np.integer, np.signedinteger, np.unsignedinteger, np.inexact, np.floating,
np.complexfloating, np.flexible and np.character; every registered dtype class has one
concrete class under them (numpy.float64, numpy.int8, numpy.datetime64, ...), and so do
the NumPy classes NumSharp has no dtype for (numpy.complex64, numpy.object_, numpy.void).
They are what np.issubdtype(a.dtype, np.integer), isinstance(x, np.floating) and
issubclass(t, np.number) test against.
public sealed class NDScalarType
- Inheritance
-
NDScalarType
- Inherited Members
Examples
np.issubdtype(a.dtype, np.integer) // NumPy's most common type test
np.issubdtype(np.float32, np.floating) // True
np.floating.__instancecheck__(a.sum()) // isinstance(a.sum(), np.floating)
np.number.__subclasscheck__(a.dtype.type) // issubclass(a.dtype.type, np.number)
NDScalarType t = a.dtype; // a.dtype.type: the scalar class, <class 'numpy.float64'>
DType d = (DType)t; // np.dtype(t): the descriptor again
t.__mro__ // [float64, floating, inexact, number, generic, float, object]
Remarks
Why a type of its own. NumSharp spells a CONCRETE scalar class by its descriptor: np.float64 is a
DType, because a C# double already is the scalar and every dtype= parameter
takes a DType. An ABSTRACT class has no descriptor (np.dtype(np.integer) raises in NumPy
2.x), so it cannot be a DType; it is an NDScalarType. The concrete classes exist as
NDScalarType objects too, so the hierarchy is complete: a descriptor converts IMPLICITLY to its
scalar class (NumPy's dtype.type: NDScalarType t = np.float64;), and a scalar class converts
EXPLICITLY back to its descriptor (NumPy's np.dtype(t)). The way back is explicit because it raises for
an abstract class, with NumPy's own text (Converting `np.inexact` or `np.floating` to a dtype not
allowed), so an abstract class passed where a dtype is expected is a compile error rather than a runtime
one — every such call raises in NumPy too (np.zeros(3, np.integer), np.can_cast(x, np.floating)).
Identity. Each class is ONE object, compared by reference, as Python compares class objects: the abstract,
dtype-less and built-in classes are static singletons, and the concrete class of a dtype class is built once and
cached on its DTypeMeta, so (NDScalarType)np.dtype("f8") and (NDScalarType)np.float64
are the same object. There are no == operators: reference equality is Python's is and ==
for classes.
Python's built-in classes. NumPy's classes derive from Python's: numpy.generic from object,
numpy.float64 also from float, numpy.complex128 from complex, numpy.bytes_ from
bytes and numpy.str_ from str; np.ScalarType lists int, float,
complex, bool, bytes, str and memoryview; and a StringDType descriptor's
class IS Python's str. Those eight classes are modelled (PyObject, PyInt,
PyBool, PyFloat, PyComplex, PyStr, PyBytes,
PyMemoryView), with Python's own bases (bool derives from int), so every
__mro__ is NumPy's whole tuple, computed by Python's C3 linearisation.
Instances. NumSharp has no scalar objects: a C# value of a dtype's element type (a boxed
double, int, Half, Complex,
decimal, char, bool or string) IS a scalar of that dtype,
and so is a 0-d NDArray that stands for a scalar (every computed 0-d result, a[0] of a 1-D
array, Scalar<T>(T)). A C# value is also the Python object it stands for in NumSharp's
NEP 50 rules (a C# int is a Python int, a double a Python float). An
explicit np.array(5) is a 0-d ndarray, not a scalar, exactly as in NumPy
(isinstance(np.array(5), np.integer) is False). See __instancecheck__(object).
NumSharp's classes against NumPy's. NumSharp-only dtypes get NumSharp-only classes under the family their
kind names (numsharp.decimal under floating, numsharp.char under unsignedinteger),
the same placement np.isdtype has always used for them. The NumPy classes NumSharp has no dtype for
(complex64, object_, void) exist as classes and refuse the conversion to a dtype with a
NotSupportedException; a dtype class registered later under their NumPy type number adopts them.
Not modelled. The class call (np.float64(1.5), which makes a NumPy scalar), the unbound scalar
methods NumPy's classes carry (np.integer.is_integer), NumPy's numpy.record (the class of a
structured record, NumPy's one subclass of void), and Python's other classes: a built-in class's
__subclasses__() lists only the modelled classes (Python's str.__subclasses__() also holds
enum.StrEnum, and object.__subclasses__() some 360 classes).
Thread safety. Immutable after construction; the lazily built concrete classes are published with a compare-exchange, so concurrent first uses agree on one object.
Properties
IsAbstract
True for NumPy's ten abstract classes, which have no descriptor (converting one to a dtype raises NumPy's TypeError) and no instances; false for every concrete and built-in class.
public bool IsAbstract { get; }
Property Value
IsBuiltin
True for Python's built-in classes (PyObject, PyFloat, ...), which are not NumPy
dtypes: np.isdtype refuses them, and np.issubdtype reads one as NumPy's dtype(cls).type
(float as numpy.float64).
public bool IsBuiltin { get; }
Property Value
PyBool
Python's bool (a subclass of int): a C# bool is an instance; numpy.bool is not a subclass.
public static NDScalarType PyBool { get; }
Property Value
PyBytes
Python's bytes: a C# byte[] is an instance (NumSharp's text APIs read it as bytes), and numpy.bytes_ a subclass.
public static NDScalarType PyBytes { get; }
Property Value
PyComplex
Python's complex: a C# Complex is an instance, and numpy.complex128 a subclass.
public static NDScalarType PyComplex { get; }
Property Value
PyFloat
public static NDScalarType PyFloat { get; }
Property Value
PyInt
Python's int: a C# integer value is an instance (isinstance(5, int)); no NumPy integer class derives from it.
public static NDScalarType PyInt { get; }
Property Value
PyMemoryView
Python's memoryview: an np.MemoryView (ndarray.data) is an instance.
public static NDScalarType PyMemoryView { get; }
Property Value
PyObject
Python's object: numpy.generic's base, the end of every __mro__; every non-null value is an instance.
public static NDScalarType PyObject { get; }
Property Value
PyStr
Python's str: a C# string is an instance, numpy.str_ a subclass, and a StringDType descriptor's class this class itself.
public static NDScalarType PyStr { get; }
Property Value
__base__
Python's base: the first direct base (np.number for np.integer, numpy.floating
for numpy.float64, Python's bytes for numpy.bytes_, object for
numpy.generic). Null only for object.
public NDScalarType __base__ { get; }
Property Value
__bases__
Python's bases: the direct bases in Python's order, read-only — one for most classes, two for
NumPy's classes that also derive from a Python one (numpy.float64: [floating, float],
numpy.str_: [str, character]), none for object.
public IReadOnlyList<NDScalarType> __bases__ { get; }
Property Value
__module__
Python's module: "numpy", "numsharp" for NumSharp's own classes (decimal,
char), or "builtins" for Python's classes (the class of a StringDType descriptor included).
public string __module__ { get; }
Property Value
__mro__
Python's mro: the method resolution order, read-only — this class, then its bases in Python's C3
order, ending in object ([float64, floating, inexact, number, generic, float, object] for
numpy.float64).
public IReadOnlyList<NDScalarType> __mro__ { get; }
Property Value
__name__
Python's name: "integer", "float64", "bool", "datetime64", "float".
public string __name__ { get; }
Property Value
__qualname__
Python's qualname: the same as __name__, since none of these classes is nested.
public string __qualname__ { get; }
Property Value
Methods
ToString()
NumPy's rendering of a class, repr(np.integer) and str(np.integer) alike:
<class 'numpy.integer'>. Python leaves out the module of a built-in class
(<class 'float'>), the class of a StringDType descriptor included (<class 'str'>).
public override string ToString()
Returns
- string
The class repr.
__instancecheck__(object)
Python's isinstance(instance, cls): true when instance is an object of this class or
of one of its subclasses (np.integer.instancecheck(a[0]) for an int32 array is true).
public bool __instancecheck__(object instance)
Parameters
instanceobjectThe value to test; null is not an instance of anything (Python's
Noneis, but of no class NumSharp models).
Returns
- bool
For PyObject: true for every non-null value (every Python object is an
object).For an NDArray: true only when it is a 0-d array that stands for a scalar — a computed 0-d result,
a[0]of a 1-D array or Scalar<T>(T) — and its dtype's class is under this one (a 0-d float64 array is anumpy.float64, so also a Pythonfloat; a 0-d float32 is not). An array with dimensions and an explicitnp.array(x)0-d array are ndarrays, not scalars.For a boxed C# value: true when its type is the element type of a dtype whose class is under this one (a double is a
numpy.float64, a decimal anumsharp.decimal), OR when the Python object it stands for is (a C# integer is a Pythonint, a bool abool, a float / double afloat, a Complex acomplex, a string astr, abyte[]abytes, an np.MemoryView amemoryview). False for a descriptor or a class (a class is not an instance of itself), and for a value of a type neither mapping knows.
Remarks
NumSharp has no scalar objects, so a C# value stands for both of the objects Python keeps apart: a
double is the numpy.float64 an array's element is and the Python float a literal
is. So np.float64.__instancecheck__(1.5) and PyFloat.__instancecheck__(1.5) are both true,
where NumPy's 1.0 is a float but not a numpy.float64, and PyInt.__instancecheck__(5)
is true although a NumPy int32 scalar is not an int. A ported isinstance(x, (int, np.integer))
therefore answers for the values NumSharp hands out, which is what such a test is written for. The same rule
makes a C# string a numpy.str_ scalar (the U dtype stores string), where
NumPy's "abc" is a str but not an np.str_.
The element type must match EXACTLY: a boxed enum is not an integer even though its underlying type is,
because no dtype stores enums and an enum is not a Python int.
__subclasscheck__(NDScalarType)
Python's issubclass(subclass, cls): true when subclass is this class or derives from
it. A DType converts implicitly to its scalar class, so a descriptor is accepted where NumPy
passes a class (np.number.subclasscheck(np.float32) is true).
public bool __subclasscheck__(NDScalarType subclass)
Parameters
subclassNDScalarTypeThe class to test.
Returns
Exceptions
- TypeError
subclassis null (Python'sissubclass() arg 1 must be a class).
__subclasscheck__(Type)
Python's issubclass(subclass, cls) for a C# type — NumSharp's type is the C#
element type, so a port of issubclass(a.dtype.type, np.integer) lands here:
np.integer.subclasscheck(typeof(int)) is true. As for instances, a C# type stands for both the
NumPy class of the dtype that stores it and the Python class its values are (typeof(int) is
numpy.int32 and int).
public bool __subclasscheck__(Type subclass)
Parameters
subclassTypeThe C# type to test.
Returns
- bool
True when either class
subclassstands for derives from this one, and true for PyObject whatever the type (every class derives fromobject); false otherwise.
Exceptions
- TypeError
subclassis null (Python'sissubclass() arg 1 must be a class).
__subclasses__()
Python's type.subclasses(): the DIRECT subclasses, as a new list, in creation order — NumPy's
registration order for NumPy's classes, abstract subclasses first (np.signedinteger.subclasses()
is [int8, int16, int32, int64, timedelta64] on a host whose C int is NumSharp's int32 class).
A built-in class lists the modelled classes only (Python's own list also holds classes outside NumPy).
public List<NDScalarType> __subclasses__()
Returns
- List<NDScalarType>
A new list of the direct subclasses.
Remarks
The list is computed once per registry state and copied out on each call: a dtype registered after this class was first asked still shows up as its subclass (as a Python class created later does), because every registration publishes a new registry array and the cached list remembers the array it was built from.
mro()
Python's type.mro(): the method resolution order as a NEW, mutable list (Python returns a fresh list each call).
public List<NDScalarType> mro()
Returns
- List<NDScalarType>
A new list holding __mro__'s classes.
Operators
explicit operator DType(NDScalarType)
The descriptor of a scalar class — NumPy's np.dtype(cls): a concrete class gives its dtype class's
builtin descriptor, the same object np.dtype("f8") returns; a Python built-in class gives NumPy's
descriptor for it (np.dtype(float) is float64, np.dtype(int) the pointer-sized integer,
np.dtype(str) the unsized <U).
public static explicit operator DType(NDScalarType sctype)
Parameters
sctypeNDScalarTypeThe scalar class, or null.
Returns
- DType
The descriptor, or null for a null class.
Exceptions
- TypeError
sctypeis abstract: NumPy's texts, e.g.Converting 'np.integer' or 'np.signedinteger' to a dtype is not allowed(the conversion is explicit for exactly this reason).- NotSupportedException
sctypeis a NumPy class NumSharp has no dtype for (complex64,object_,void, and the built-inobject/memoryview, whose NumPy dtypes are those).
implicit operator NDScalarType(DType)
The scalar class of a descriptor — NumPy's dtype.type (np.dtype('f8').type is np.float64). Every
descriptor has one, so the conversion never fails; descriptors of one dtype class ('<f8',
'>f8'; 'M8[s]', 'M8[ns]') share it, and a StringDType descriptor's is Python's
str.
public static implicit operator NDScalarType(DType dtype)
Parameters
dtypeDTypeThe descriptor, or null.
Returns
- NDScalarType
Its scalar class, or null for a null descriptor (C#'s null maps through, as every DType conversion does).