--- DOC Blurb : tclbin v 1.0 ---


******************************************************
See also the new doc/libtclbin.dvi or doc/libtclbin.ps
******************************************************

old preliminary 'documentation' (exemples are still interesting though) :
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

bin_new :
  create a new object :
  bin_new object|#auto type sizeExpr ?father? ?offsetExpr? ?no_unset?
  
     object   is the object name
     type     is the object type,  xxx* are arrays of type xxx
     sizeExpr is evaluated as an expression **IN BYTES** (whatever
              the type...)
     if father argument is here, bin_new doesn't allocate new memory,
     but create a pointer on the 'father' data part
       offset is then the offset *in bytes* from the father start
       if the no_unset arg is here (and whatever its value is) the
       children will *not* be unset when father is unset... thus
       use this only if you are sure that the children will be unset
       before the father (if not, you'll have dandling pointer)
       (typical use : in a proc where the new ptr is auto unset at the end)

bin_sizeof : returns the size of a type or object

bin_move : move (incr by default) a pointer object (see source & examples)
           or a field

bin_resize : resize a pointer object (see source & examples)
             or a field

bin_copy : like mem_copy, from tcl, with fool guards 
	(not outside objects)... 

bin_def : create a field in an object (like a C struct)
	bin_def object field type offsetExpr, offsetExpr is in *bytes*

bin_info : returns lots of info (in keyed list format) about the internal\
	 object structure... prolly usefull to debug only

bin_read : reads from a stream (a tcl file id) to an object or field
          returns number of bytes actually read	

bin_write : write an object to a stream (a tcl file id) or field
          returns number of bytes actually written

if you want to read/write  part of an object define a child object.

  Examples :
    bin_new toto double* [bin_sizeof double]*10
    -> toto is now an object with room for 10 doubles
    bin_new toto_part double* [bin_sizeof double]*2 toto
    -> toto_part is a ptr to (currently) the first 2 doubles of toto
    bin_def toto dbl double 0
    -> defines toto(dbl)   

set toto(dbl) 5.6
set toto(1) 0.5
set toto(2) 3.1
puts $toto_part(0)
-> 5.6
bin_move toto_part
(toto_part is size of 2 doubles, so one bin_move without arg is 
like a C ++ incr, it increment of the whole size... (but if you 
specify an size, it will then replace the sizeof(object) multiplier)
puts $toto_part(0)
-> 3.1
bin_move -absolute toto_part 0;
(back to origine (5.6))
want to have an hex dump of the two first bytes ?
puts $toto_part(_hex_)
want to see as a short the bytes 1-3 ?
bin_def toto_part sh short 1
format %x $toto_part(sh)
want to poke to it as a char ?
bin_def toto_part ch char 1
set toto_part(ch) a
see how is the number now :
puts $toto(dbl)
(gives 139.2 here)
or see a char dump :
puts $toto_part(_str_)
...etc...
save your object ?
set fic [open toto.out w]
bin_write $fic toto
close $fic

...etc..


 something I find cool : if you do a bin_new xxx in a proc, when you get out
 of the proc, Tcl unsets xxx and my package frees the memory automagically !
 (temporary buffers etc... are automatically freed for you...(use upvar to
 keep the data) 

General hints :
  try "info commands bin_*"
  and then "bin_new","bin_sizeof",...etc to get online help...
  also look at the .c !

comments to dl@hplyot.obspm.fr 
(laurent demailly)

see also the web page http://hplyot.obspm.fr/~dl/tclbin.html
see also the doc/ directory
