8000 DOC: Add ref docs for C generic types. by tylerjereddy · Pull Request #11689 · numpy/numpy · GitHub
[go: up one dir, main page]
Skip to content

DOC: Add ref docs for C generic types. #11689

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 15, 2019
Merged

DOC: Add ref docs for C generic types. #11689

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 66 additions & 2 deletions doc/DISTUTILS.rst.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -300,8 +300,72 @@ in writing setup scripts:
Template files
--------------

XXX: Describe how files with extensions ``.f.src``, ``.pyf.src``,
``.c.src``, etc. are pre-processed by the ``build_src`` command.
NumPy Distutils preprocesses C source files (extension: :file:`.c.src`) written
in a custom templating language to generate C code. The :c:data:`@` symbol is
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only C files? It looks like it might support other files too.

used to wrap macro-style variables to empower a string substitution mechansim
that might describe (for instance) a set of data types.

As a more detailed scenario, a loop in the NumPy C source code may
have a :c:data:`@TYPE@` variable, targeted for string substitution,
which is preprocessed to a number of otherwise identical loops with
several strings such as :c:data:`INT, LONG, UINT, ULONG`. The :c:data:`@TYPE@`
style syntax thus reduces code duplication and maintenance burden by
mimicking languages that have generic type support. By convention,
and as required by the preprocessor, generically typed blocks are preceded
by comment blocks that enumerate the intended string substitutions.

The template language blocks are delimited by :c:data:`/**begin repeat`
and :c:data:`/**end repeat**/` lines, which may also be nested using
consecutively numbered delimiting lines such as :c:data:`/**begin repeat1`
and :c:data:`/**end repeat1**/`. String replacement specifications are started
and terminated using :c:data:`#`. This may be clearer in the following
template source example:

.. code-block:: C
:linenos:
:emphasize-lines: 3, 13, 29, 31

/* TIMEDELTA to non-float types */

/**begin repeat
*
* #TOTYPE = BYTE, UBYTE, SHORT, USHORT, INT, UINT, LONG, ULONG,
* LONGLONG, ULONGLONG, DATETIME,
* TIMEDELTA#
* #totype = npy_byte, npy_ubyte, npy_short, npy_ushort, npy_int, npy_uint,
* npy_long, npy_ulong, npy_longlong, npy_ulonglong,
* npy_datetime, npy_timedelta#
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be good to note that:

  • These sequences are combined essentially via zip, and iterated together rather than as a cartesian product
  • There is a *N syntax for repeated elements

*/

/**begin repeat1
*
* #FROMTYPE = TIMEDELTA#
* #fromtype = npy_timedelta#
*/
static void
@FROMTYPE@_to_@TOTYPE@(void *input, void *output, npy_intp n,
void *NPY_UNUSED(aip), void *NPY_UNUSED(aop))
{
const @fromtype@ *ip = input;
@totype@ *op = output;

while (n--) {
*op++ = (@totype@)*ip++;
}
}
/**end repeat1**/

/**end repeat**/

The preprocessing of generically typed C source files (whether in NumPy
proper or in any third party package using NumPy Distutils) is performed
by `conv_template.py`_.
The type specific C files generated (extension: :file:`.c`) by these modules
during the build process are ready to be compiled. This form
of generic typing is also supported for C header files (preprocessed to
produce :file:`.h` files).

.. _conv_template.py: https://github.com/numpy/numpy/blob/master/numpy/distutils/conv_template.py

Useful functions in ``numpy.distutils.misc_util``
-------------------------------------------------
Expand Down
0