[q-lang-cvs] q/doc qdoc.texi,1.140,1.141 version.texi,1.95,1.96

[Albert G. <ag...@us...>]

Update of /cvsroot/q-lang/q/doc
In directory sc8-pr-cvs16.sourceforge.net:/tmp/cvs-serv3854

Modified Files:
	qdoc.texi version.texi 
Log Message:
update documentation

Index: qdoc.texi
===================================================================
RCS file: /cvsroot/q-lang/q/doc/qdoc.texi,v
retrieving revision 1.140
retrieving revision 1.141
diff -C2 -d -r1.140 -r1.141
*** qdoc.texi	16 Jan 2008 08:30:22 -0000	1.140
--- qdoc.texi	18 Jan 2008 11:18:45 -0000	1.141
***************
*** 11143,11146 ****
--- 11143,11184 ----
  operations are all implemented in terms of the functions listed above.
  
+ @subheading Byte Strings as Mutable C Vectors
+ 
+ As of Q 7.11, @code{clib} supports a number of additional operations
+ which allow you to treat byte strings as mutable C vectors of
+ signed/unsigned 8/16/32 bit integers or single/double precision floating
+ point numbers. The following functions provide read/write access to the
+ elements of such C vectors. Note that the given index argument @code{I}
+ is interpreted relative to the corresponding element type. Thus, e.g.,
+ @code{get_int32 B I} returns the @code{I}th 32 bit integer rather than
+ the integer at byte offset @code{I}.
+ 
+ NOTE: Integer arguments must fit into machine integers, otherwise these
+ operations will fail. Integers passed for floating point arguments will be
+ coerced to floating point values automatically.
+ 
+ @smallexample
+ public extern get_int8 B I, get_int16 B I, get_int32 B I;
+ public extern get_uint8 B I, get_uint16 B I, get_uint32 B I;
+ public extern get_float B I, get_double B I;
+ 
+ public extern put_int8 B I X, put_int16 B I X, put_int32 B I X;
+ public extern put_uint8 B I X, put_uint16 B I X, put_uint32 B I X;
+ public extern put_float B I X, put_double B I X;
+ @end smallexample
+ 
+ Moreover, the following convenience functions are provided to convert
+ between byte strings and lists of integer/floating point elements.
+ 
+ @smallexample
+ public extern int8_list B, int16_list B, int32_list B;
+ public extern uint8_list B, uint16_list B, uint32_list B;
+ public extern float_list B, double_list B;
+ 
+ public extern int8_vect Xs, int16_vect Xs, int32_vect Xs;
+ public extern uint8_vect Xs, uint16_vect Xs, uint32_vect Xs;
+ public extern float_vect Xs, double_vect Xs;
+ @end smallexample
+ 
  @subheading Examples
  
***************
*** 11283,11286 ****
--- 11321,11363 ----
  addresses.
  
+ In order to facilitate the handling of C vectors of integers and
+ floating point values, as of Q 7.11 @code{clib} offers a number of
+ specialized operations which provide direct read/write access to the
+ elements of numeric vectors, and to convert between such C vectors and
+ lists of integer or floating point values. These operations are all
+ implemented directly in C and will usually be much more efficient for
+ manipulating numeric C vectors than the basic byte-oriented
+ functions. Moreover, they allow you to modify the elements of a C vector
+ in a direct fashion, turning byte strings into a mutable data structure.
+ 
+ Different operations are provided to handle vectors of signed or
+ unsigned 8/16/32 (machine) integers, as well as single and double
+ precision floating point numbers. For instance:
+ 
+ @smallexample
+ ==> def B = uint32_vect [100..110]
+ 
+ ==> uint32_list B
+ [100,101,102,103,104,105,106,107,108,109,110]
+ 
+ ==> get_uint32 B 1
+ 101
+ 
+ ==> put_uint32 B 1 0xffffffff
+ ()
+ 
+ ==> uint32_list B
+ [100,4294967295,102,103,104,105,106,107,108,109,110]
+ @end smallexample
+ 
+ Note that, because these C vectors are just normal byte strings, you can
+ freely convert between different representations of the numeric
+ data. E.g.:
+ 
+ @smallexample
+ ==> take 12 $ int8_list B
+ [100,0,0,0,-1,-1,-1,-1,102,0,0,0]
+ @end smallexample
+ 
  @node Extended File Functions, C-Style Formatted I/O, Byte Strings, Clib
  @section Extended File Functions

Index: version.texi
===================================================================
RCS file: /cvsroot/q-lang/q/doc/version.texi,v
retrieving revision 1.95
retrieving revision 1.96
diff -C2 -d -r1.95 -r1.96
*** version.texi	16 Jan 2008 09:07:38 -0000	1.95
--- version.texi	18 Jan 2008 11:18:45 -0000	1.96
***************
*** 1,3 ****
! @set UPDATED 16 January 2008
  @set UPDATED-MONTH January 2008
  @set EDITION 7.11
--- 1,3 ----
! @set UPDATED 18 January 2008
  @set UPDATED-MONTH January 2008
  @set EDITION 7.11