From 5b40fa04467b63f306729701356cc861bbca417a Mon Sep 17 00:00:00 2001 From: Stefan Behnel Date: Wed, 30 Jan 2013 08:04:10 +0100 Subject: [PATCH] remove warning about missing 'const' support from docs and fix advice on declaring macros as 'enum' (which works only for ints) --- docs/src/userguide/external_C_code.rst | 53 +++++++--------------------------- 1 file changed, 10 insertions(+), 43 deletions(-) diff --git a/docs/src/userguide/external_C_code.rst b/docs/src/userguide/external_C_code.rst index bb35e4d..c36dcda 100644 --- a/docs/src/userguide/external_C_code.rst +++ b/docs/src/userguide/external_C_code.rst @@ -63,44 +63,10 @@ file, so you still need to provide Cython versions of any declarations from it that you use. However, the Cython declarations don't always have to exactly match the C ones, and in some cases they shouldn't or can't. In particular: -1. Don't use ``const``. Cython doesn't know anything about ``const``, so just - leave it out. Most of the time this shouldn't cause any problem, although - on rare occasions you might have to use a cast. You can also explicitly - declare something like:: - - ctypedef char* const_char_ptr "const char*" - - though in most cases this will not be needed. - - .. warning:: - - A problem with const could arise if you have something like:: - - cdef extern from "grail.h": - char *nun - - where grail.h actually contains:: - - extern const char *nun; - - and you do:: - - cdef void languissement(char *s): - #something that doesn't change s - - ... - - languissement(nun) - - which will cause the C compiler to complain. You can work around it by - casting away the constness:: - - languissement(nun) - -2. Leave out any platform-specific extensions to C declarations such as +#. Leave out any platform-specific extensions to C declarations such as ``__declspec()``. -3. If the header file declares a big struct and you only want to use a few +#. If the header file declares a big struct and you only want to use a few members, you only need to declare the members you're interested in. Leaving the rest out doesn't do any harm, because the C compiler will use the full definition from the header file. @@ -116,10 +82,8 @@ match the C ones, and in some cases they shouldn't or can't. In particular: you can only do this inside a ``cdef extern from`` block; struct declarations anywhere else must be non-empty. - - -4. If the header file uses ``typedef`` names such as :c:type:`word` to refer +#. If the header file uses ``typedef`` names such as :c:type:`word` to refer to platform-dependent flavours of numeric types, you will need a corresponding :keyword:`ctypedef` statement, but you don't need to match the type exactly, just use something of the right general kind (int, float, @@ -131,13 +95,16 @@ match the C ones, and in some cases they shouldn't or can't. In particular: file defines it correctly). Conversion to and from Python types, if any, will also be used for this new type. -5. If the header file uses macros to define constants, translate them into a - dummy :keyword:`enum` declaration. +#. If the header file uses macros to define constants, translate them into a + normal external variable declaration. You can also declare them as an + :keyword:`enum` if they contain normal :c:type:`int` values. Note that + Cython considers :keyword:`enum` to be equivalent to :c:type:`int`, so do + not do this for non-int values. -6. If the header file defines a function using a macro, declare it as though +#. If the header file defines a function using a macro, declare it as though it were an ordinary function, with appropriate argument and result types. -7. For archaic reasons C uses the keyword ``void`` to declare a function +#. For archaic reasons C uses the keyword ``void`` to declare a function taking no parameters. In Cython as in Python, simply declare such functions as :meth:`foo()`. -- 2.7.4