From 73baefd7fc86a7f8336e4142efcec74c201acf8f Mon Sep 17 00:00:00 2001 From: Thomas Heller Date: Wed, 11 Jun 2008 07:10:43 +0000 Subject: [PATCH] Fix markup. Document the new 'offset' parameter for the 'ctypes.byref' function. --- Doc/library/ctypes.rst | 50 +++++++++++++++++++++++++----------------- 1 file changed, 30 insertions(+), 20 deletions(-) diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index fa6f83181b9..17baf670d21 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1406,10 +1406,9 @@ GetLastError() and SetLastError() Windows api functions; to request and change the ctypes private copy of the windows error code. -.. versionchanged:: 2.6 - -The `use_errno` and `use_last_error` parameters were added in Python -2.6. +.. versionadded:: 2.6 + The ``use_last_error`` and ``use_errno`` optional parameters + were added. .. data:: RTLD_GLOBAL :noindex: @@ -1572,22 +1571,23 @@ They are instances of a private class: Assign a Python function or another callable to this attribute. The callable will be called with three or more arguments: + .. function:: callable(result, func, arguments) + :noindex: -.. function:: callable(result, func, arguments) - :noindex: + ``result`` is what the foreign function returns, as specified + by the :attr:`restype` attribute. - ``result`` is what the foreign function returns, as specified by the - :attr:`restype` attribute. + ``func`` is the foreign function object itself, this allows + to reuse the same callable object to check or post process + the results of several functions. - ``func`` is the foreign function object itself, this allows to reuse the same - callable object to check or post process the results of several functions. + ``arguments`` is a tuple containing the parameters originally + passed to the function call, this allows to specialize the + behavior on the arguments used. - ``arguments`` is a tuple containing the parameters originally passed to the - function call, this allows to specialize the behavior on the arguments used. - - The object that this function returns will be returned from the foreign - function call, but it can also check the result value and raise an exception - if the foreign function call failed. + The object that this function returns will be returned from the + foreign function call, but it can also check the result value + and raise an exception if the foreign function call failed. .. exception:: ArgumentError() @@ -1805,12 +1805,22 @@ Utility functions ctypes type or instance. -.. function:: byref(obj) +.. function:: byref(obj[, offset]) - Returns a light-weight pointer to ``obj``, which must be an instance of a ctypes - type. The returned object can only be used as a foreign function call parameter. - It behaves similar to ``pointer(obj)``, but the construction is a lot faster. + Returns a light-weight pointer to ``obj``, which must be an + instance of a ctypes type. ``offset`` defaults to zero, it must be + an integer which is added to the internal pointer value. + ``byref(obj, offset)`` corresponds to this C code:: + + (((char *)&obj) + offset) + + The returned object can only be used as a foreign function call + parameter. It behaves similar to ``pointer(obj)``, but the + construction is a lot faster. + + .. versionadded:: 2.6 + The ``offset`` optional argument was added. .. function:: cast(obj, type)