Update of /cvsroot/ctypes/ctypes/docs/manual
In directory sc8-pr-cvs4.sourceforge.net:/tmp/cvs-serv4737
Modified Files:
tutorial.txt
Log Message:
Documentation for variable-sized data types.
Add todo-item about ctypes.util.find_library.
Index: tutorial.txt
===================================================================
RCS file: /cvsroot/ctypes/ctypes/docs/manual/tutorial.txt,v
retrieving revision 1.27
retrieving revision 1.28
diff -C2 -d -r1.27 -r1.28
*** tutorial.txt 15 May 2006 07:04:40 -0000 1.27
--- tutorial.txt 19 May 2006 18:30:31 -0000 1.28
***************
*** 60,63 ****
--- 60,69 ----
XXX Add section for Mac OS X.
+ Finding shared libraries
+ ------------------------
+
+ XXX Add description of ctypes.util.find_library (once I really
+ understand it enough to describe it).
+
Accessing functions from loaded dlls
------------------------------------
***************
*** 1123,1131 ****
Accessing the contents again constructs a new Python each time!
! Variable size data types
! ------------------------
- XXX describe var-sized arrays
- XXX describe resize
Bugs, ToDo and non-implemented things
--- 1129,1202 ----
Accessing the contents again constructs a new Python each time!
! Variable-sized data types
! -------------------------
!
! ``ctypes`` provides some support for variable-sized arrays and
! structures (this was added in version 0.9.9.7).
!
! The ``resize`` function can be used to resize the memory buffer of an
! existing ctypes object. The function takes the object as first
! argument, and the requested size in bytes as the second argument. The
! memory block cannot be made smaller than the natural memory block
! specified by the objects type, a ``ValueError`` is raised if this is
! tried::
!
! >>> short_array = (c_short * 4)()
! >>> print sizeof(short_array)
! 8
! >>> resize(short_array, 4)
! Traceback (most recent call last):
! ...
! ValueError: minimum size is 8
! >>> resize(short_array, 32)
! >>> sizeof(short_array)
! 32
! >>> sizeof(type(short_array))
! 8
! >>>
!
! This is nice and fine, but how would one access the additional
! elements contained in this array? Since the type still only knows
! about 4 elements, we get errors accessing other elements::
!
! >>> short_array[:]
! [0, 0, 0, 0]
! >>> short_array[7]
! Traceback (most recent call last):
! ...
! IndexError: invalid index
! >>>
!
! The solution is to use 1-element arrays; as a special case ctypes does
! no bounds checking on them::
!
! >>> short_array = (c_short * 1)()
! >>> print sizeof(short_array)
! 2
! >>> resize(short_array, 32)
! >>> sizeof(short_array)
! 32
! >>> sizeof(type(short_array))
! 2
! >>> short_array[0:8]
! [0, 0, 0, 0, 0, 0, 0, 0]
! >>> short_array[7] = 42
! >>> short_array[0:8]
! [0, 0, 0, 0, 0, 0, 0, 42]
! >>>
!
! Using 1-element arrays as variable sized fields in structures works as
! well, but they should be used as the last field in the structure
! definition. This example shows a definition from the Windows header
! files::
!
! class SP_DEVICE_INTERFACE_DETAIL_DATA(Structure):
! _fields_ = [("cbSize", c_int),
! ("DevicePath", c_char * 1)]
!
! Another way to use variable-sized data types with ``ctypes`` is to use
! the dynamic nature of Python, and (re-)define the data type after the
! required size is already known, on a case by case basis.
Bugs, ToDo and non-implemented things
|
