From 4291c9440b6586bc6b9deec55178c21f935b02a7 Mon Sep 17 00:00:00 2001 From: mattip Date: Wed, 9 May 2018 12:12:52 +0300 Subject: DOC: improve docs for PyUFunc_FromFuncAndData. --- doc/source/reference/c-api.ufunc.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) (limited to 'doc/source/reference') diff --git a/doc/source/reference/c-api.ufunc.rst b/doc/source/reference/c-api.ufunc.rst index 79ad256f5..5ac34edc1 100644 --- a/doc/source/reference/c-api.ufunc.rst +++ b/doc/source/reference/c-api.ufunc.rst @@ -93,12 +93,18 @@ Functions the corresponding 1-d loop function in the func array. :param types: - Must be of length (*nin* + *nout*) \* *ntypes*, and it - contains the data-types (built-in only) that the corresponding - function in the *func* array can deal with. + Int8 of length `(nin + nout) * ntypes` It encodes the :ref:`dtype.num` + (built-in only) that the corresponding function in the `func` array + accepts. For a ufunc with two `ntypes`, one `nin` and one `nout` where + the first function accepts and returns `int32` and the second accepts + and returns `int64`, `types` would be `\05\05\07\07` since `int32.num` + is 5 and `int64.num` is 7. + + :ref:`casting-rules` will be used at runtime to find the first `func` callable + by the input/output provided. :param ntypes: - How many different data-type "signatures" the ufunc has implemented. + How many different data-type-specific functions the ufunc has implemented. :param nin: The number of inputs to this operation. -- cgit v1.2.1 From 69a77fb790d6545969c17f7aed0fe160a6a5bc6a Mon Sep 17 00:00:00 2001 From: mattip Date: Mon, 30 Apr 2018 18:13:10 +0300 Subject: DOC: Clarify C-API for generalized ufuncs. --- doc/source/reference/c-api.generalized-ufuncs.rst | 7 ++++--- doc/source/reference/c-api.ufunc.rst | 7 ++++--- doc/source/reference/ufuncs.rst | 4 ++-- 3 files changed, 10 insertions(+), 8 deletions(-) (limited to 'doc/source/reference') diff --git a/doc/source/reference/c-api.generalized-ufuncs.rst b/doc/source/reference/c-api.generalized-ufuncs.rst index a53228cb5..dd8cf6558 100644 --- a/doc/source/reference/c-api.generalized-ufuncs.rst +++ b/doc/source/reference/c-api.generalized-ufuncs.rst @@ -101,6 +101,7 @@ Dimension Index enumerates the dimension names according to the order of the first occurrence of each name in the signature. +.. _details-of-signature: Details of Signature -------------------- @@ -126,9 +127,9 @@ The formal syntax of signatures is as follows:: ::= ::= nil | | "," ::= "(" ")" - ::= nil | | - "," - ::= valid Python variable name + ::= nil | | + "," + ::= valid Python variable name Notes: diff --git a/doc/source/reference/c-api.ufunc.rst b/doc/source/reference/c-api.ufunc.rst index 5ac34edc1..ece6cc391 100644 --- a/doc/source/reference/c-api.ufunc.rst +++ b/doc/source/reference/c-api.ufunc.rst @@ -135,10 +135,11 @@ Functions int nin, int nout, int identity, char* name, char* doc, int unused, char *signature) This function is very similar to PyUFunc_FromFuncAndData above, but has - an extra *signature* argument, to define generalized universal functions. + an extra *signature* argument, to define a + :ref:`generalized universal functions `. Similarly to how ufuncs are built around an element-by-element operation, - gufuncs are around subarray-by-subarray operations, the signature defining - the subarrays to operate on. + gufuncs are around subarray-by-subarray operations, the + :ref:`signature ` defining the subarrays to operate on. :param signature: The signature for the new gufunc. Setting it to NULL is equivalent diff --git a/doc/source/reference/ufuncs.rst b/doc/source/reference/ufuncs.rst index 68d85ccf5..995542d77 100644 --- a/doc/source/reference/ufuncs.rst +++ b/doc/source/reference/ufuncs.rst @@ -424,8 +424,8 @@ advanced usage and will not typically be used. provided by the **types** attribute of the ufunc object. For backwards compatibility this argument can also be provided as *sig*, although the long form is preferred. Note that this should not be confused with - the generalized ufunc signature that is stored in the **signature** - attribute of the of the ufunc object. + the generalized ufunc :ref:`signature ` that is + stored in the **signature** attribute of the of the ufunc object. *extobj* -- cgit v1.2.1 From d7f4eef6544e811840b3d1354b2d38ed3ae5a967 Mon Sep 17 00:00:00 2001 From: Marten van Kerkwijk Date: Mon, 28 May 2018 13:53:39 -0400 Subject: DOC: Further clarification of c-api. --- doc/source/reference/c-api.ufunc.rst | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) (limited to 'doc/source/reference') diff --git a/doc/source/reference/c-api.ufunc.rst b/doc/source/reference/c-api.ufunc.rst index ece6cc391..02a35cf56 100644 --- a/doc/source/reference/c-api.ufunc.rst +++ b/doc/source/reference/c-api.ufunc.rst @@ -93,15 +93,20 @@ Functions the corresponding 1-d loop function in the func array. :param types: - Int8 of length `(nin + nout) * ntypes` It encodes the :ref:`dtype.num` - (built-in only) that the corresponding function in the `func` array - accepts. For a ufunc with two `ntypes`, one `nin` and one `nout` where - the first function accepts and returns `int32` and the second accepts - and returns `int64`, `types` would be `\05\05\07\07` since `int32.num` - is 5 and `int64.num` is 7. - - :ref:`casting-rules` will be used at runtime to find the first `func` callable - by the input/output provided. + Length ``(nin + nout) * ntypes`` array of ``char`` encoding the + :ref:`PyArray_Descr.type_num` (built-in only) that the corresponding + function in the ``func`` array accepts. For instance, for a comparison + ufunc with three ``ntypes``, two ``nin`` and one ``nout``, where the + first function accepts :ref:`npy_int32` and the the second + :ref:`npy_int64`, with both returning :ref:`npy_bool`, ``types`` would + be ``(char[]) {5, 5, 0, 7, 7, 0}`` since ``NPY_INT32`` is 5, + ``NPY_INT64`` is 7, and ``NPY_BOOL`` is 0 (on the python side, these + are exposed via :ref:`dtype.num`, i.e., for the example here, + ``dtype(np.int32).num``, ``dtype(np.int64).num``, and + ``dtype(np.bool_).num``, resp.). + + :ref:`casting-rules` will be used at runtime to find the first + ``func`` callable by the input/output provided. :param ntypes: How many different data-type-specific functions the ufunc has implemented. -- cgit v1.2.1