[ctypes-commit] ctypes/docs/manual tutorial.txt,1.27,1.28

[Thomas H. <th...@us...>]

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