API,MAINT: Rewrite promotion using common DType and common instance

This defines `common_dtype` and `common_instance` (only for parametric
DTypes), and uses them to implement the `PyArray_CommonDType` operation.

`PyArray_CommonDType()` together with the `common_instance` method
then define the existing PromoteTypes.

This does not (yet) affect "value based promotion" as defined by
`PyArray_ResultType()`.  We also require the step of casting
to the common DType to define this type of example:
```
np.promote_types("S1", "i8") == np.dtype('S21')
```
This steps requires finding the string length corresponding to
the integer (21 characters).  This is here handled by the
`PyArray_CastDescrToDType` function.  However, that function
still relies on `PyArray_AdaptFlexibleDType` and thus does not
generalize to arbitrary DTypes.

See NEP 42 (currently "Common DType Operations" section):
https://numpy.org/neps/nep-0042-new-dtypes.html#common-dtype-operations

1 files changed, 6 insertions, 0 deletions

diff --git a/numpy/core/include/numpy/ndarraytypes.h b/numpy/core/include/numpy/ndarraytypes.h
index bbcf468c1..df480f96d 100644
--- a/numpy/core/include/numpy/ndarraytypes.h
+++ b/numpy/core/include/numpy/ndarraytypes.h
@@ -1839,6 +1839,10 @@ typedef void (PyDataMem_EventHookFunc)(void *inp, void *outp, size_t size,
             PyArray_DTypeMeta *cls, PyTypeObject *obj);
 
     typedef PyArray_Descr *(default_descr_function)(PyArray_DTypeMeta *cls);
+    typedef PyArray_DTypeMeta *(common_dtype_function)(
+            PyArray_DTypeMeta *dtype1, PyArray_DTypeMeta *dtyep2);
+    typedef PyArray_Descr *(common_instance_function)(
+            PyArray_Descr *dtype1, PyArray_Descr *dtyep2);
 
     /*
      * While NumPy DTypes would not need to be heap types the plan is to
@@ -1894,6 +1898,8 @@ typedef void (PyDataMem_EventHookFunc)(void *inp, void *outp, size_t size,
         discover_descr_from_pyobject_function *discover_descr_from_pyobject;
         is_known_scalar_type_function *is_known_scalar_type;
         default_descr_function *default_descr;
+        common_dtype_function *common_dtype;
+        common_instance_function *common_instance;
     };
 
 #endif  /* NPY_INTERNAL_BUILD */