Class DTypePromotion

Namespace

NumSharp

Assembly

NumSharp.dll

The NEP 42 / NEP 50 promotion engine over DType classes and descriptors — the ports of NumPy's common_dtype.c and convert_datatype.c: CommonDType(DTypeMeta, DTypeMeta) (PyArray_CommonDType), PromoteDTypeSequence(IReadOnlyList<DTypeMeta>) (PyArray_PromoteDTypeSequence with its reduce_dtypes_to_most_knowledgeable pass), PromoteTypes(DType, DType) (PyArray_PromoteTypes), CastDescrToDType(DType, DTypeMeta) (PyArray_CastDescrToDType), CastToDTypeAndPromoteDescriptors(IReadOnlyList<DType>, DTypeMeta) and ResultType(params object[]) (PyArray_ResultType, the NEP 50 entry point where C# literals are weak and arrays — 0-d included — are strong).

public static class DTypePromotion

Inheritance

object

DTypePromotion

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

For the storage-backed builtins the answers ARE NumSharp's frozen promotion table (NumSharp.np._nptypemap_arr_arr, consulted by DefaultBuiltinCommonDType(DTypeMeta, DTypeMeta)), so every two-operand promote_types / result_type answer the dtype_text fuzz tier gates is unchanged. Three things the old engine could not do come with the port: order-independent reduction of THREE OR MORE operands (the old fold dropped every other pair, so result_type(i1, i1, f8, i1) was int8), weak C# literals (result_type(int8_array, 300) is int8, result_type(int8_array, 1.5) is float64), and parametric classes (the datetime unit GCD).

Methods

CastDescrToDType(DType, DTypeMeta)

NumPy's PyArray_CastDescrToDType: the instance of givenDType that can represent descr — the descriptor itself when already of that class, the class default when the class is not parametric, else whatever the registered cast resolves (a datetime keeps its unit when cast between datetime64 and timedelta64; an integer cast to timedelta64 lands on the generic unit).

public static DType CastDescrToDType(DType descr, DTypeMeta givenDType)

Parameters

descr DType

givenDType DTypeMeta

Returns

DType

Exceptions

TypeError

cannot cast dtype %S to %S.

CastToDTypeAndPromoteDescriptors(IReadOnlyList<DType>, DTypeMeta)

NumPy's PyArray_CastToDTypeAndPromoteDescriptors: cast every descriptor to dtype and fold their common_instance (the string-length / datetime-unit resolution over N operands).

public static DType CastToDTypeAndPromoteDescriptors(IReadOnlyList<DType> descrs, DTypeMeta dtype)

Parameters

descrs IReadOnlyList<DType>

dtype DTypeMeta

Returns

DType

CommonDType(DTypeMeta, DTypeMeta)

NumPy's PyArray_CommonDType: dtype1.common_dtype(dtype2), then the mirrored question, then DTypePromotionError with NumPy's verbatim text.

public static DTypeMeta CommonDType(DTypeMeta dtype1, DTypeMeta dtype2)

Parameters

dtype1 DTypeMeta

dtype2 DTypeMeta

Returns

DTypeMeta

PromoteDTypeSequence(IReadOnlyList<DTypeMeta>)

NumPy's PyArray_PromoteDTypeSequence: the common class of any number of classes, computed so the answer does not depend on operand order (the "most knowledgeable" class — the highest category — promotes every other one; two mutually unknown classes raise).

public static DTypeMeta PromoteDTypeSequence(IReadOnlyList<DTypeMeta> dtypesIn)

Parameters

dtypesIn IReadOnlyList<DTypeMeta>

Returns

DTypeMeta

Exceptions

DTypePromotionError

NumPy's verbatim The DType %S could not be promoted by %S. ….

PromoteTypes(DType, DType)

NumPy's PyArray_PromoteTypes: the smallest descriptor both inputs cast to safely. An identical native legacy input is returned as is (metadata preserved); otherwise the common CLASS decides — a non-parametric class yields its default descriptor, a parametric one casts both inputs to itself (CastDescrToDType(DType, DTypeMeta)) and takes their common_instance.

public static DType PromoteTypes(DType type1, DType type2)

Parameters

type1 DType

type2 DType

Returns

DType

ResultType(params object[])

NumPy's PyArray_ResultType under NEP 50: the descriptor of the result of combining arraysAndDtypes, where every NDArray (0-d included), DType, NPTypeCode, Type, dtype string, bool, char, Half and decimal is STRONG (contributes its dtype), while a C# integer, float/double or Complex literal is WEAK — it contributes only its NEP 50 class (_PyLongDType, _PyFloatDType, _PyComplexDType) and no width, so result_type(int8_array, 300) is int8. A DTypeMeta operand contributes the class alone.

public static DType ResultType(params object[] arraysAndDtypes)

Parameters

arraysAndDtypes object[]

Returns

DType

Exceptions

ValueError

at least one array or dtype is required.

DTypePromotionError

No common dtype exists.