/usr/share/doc/blt-dev/html/Blt

                                                                      
                                    <!-- manual page source format generated by PolyglotMan v3.0.9, -->
<!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z -->

<HTML>
<HEAD>
<TITLE>Blt_Vector(3) manual page</TITLE>
</HEAD>
<BODY bgcolor=white>
<A HREF="#toc">Table of Contents</A><P>
 
<H2><A NAME="sect0" HREF="#toc0">Name</A></H2>
Blt_Vector - Vector data object.
<P>
 
<H2><A NAME="sect1" HREF="#toc1">C Language API</A></H2>
You can create, modify, and destroy vectors from C code,
using  library routines.   You need to include the header file blt.h. It
contains the definition of the structure <B>Blt_Vector</B>, which represents the
vector.  It appears below. <P>
<BR>
<CODE>typedef struct {<BR>
    double *<I>valueArr</I>; <BR>
    int <I>numValues</I>;    <BR>
    int <I>arraySize</I>;    <BR>
    double <I>min</I>, <I>max</I>;  <BR>
} <B>Blt_Vector</B>;<BR>
<P>
</CODE>The field <I>valueArr</I> points to memory holding the vector components.  The
components are stored in a double precision array, whose size size is represented
by <I>arraySize</I>.  <I>NumValues</I> is the length of vector.  The size of the array
is always equal to or larger than the length of the vector.  <I>Min</I> and <I>max</I>
are minimum and maximum component values. 
<H2><A NAME="sect2" HREF="#toc2">Library Routines</A></H2>
The following
routines are available from C to manage vectors. Vectors are identified
by the vector name. <P>
<B>Blt_CreateVector</B>  <blockquote>
<DL>

<DT>Synopsis: </DT>
<DD><BR>
<CODE>int <B>Blt_CreateVector</B> (<I>interp</I>, <I>vecName</I>, <I>length</I>, <I>vecPtrPtr</I>)<BR>
<blockquote>Tcl_Interp *<I>interp</I>;<BR>
char *<I>vecName</I>;<BR>
int <I>length</I>;<BR>
Blt_Vector **<I>vecPtrPtr</I>;<BR>
</DD>
</DL>
</blockquote>

<DL>

<DT></CODE>Description: </DT>
<DD>Creates a new vector <I>vecName</I> with a length of <I>length</I>. <B>Blt_CreateVector</B>
creates both a new Tcl command and array  variable <I>vecName</I>.  Neither a command
nor variable named  <I>vecName</I> can already exist.  A pointer to the vector
is  placed into <I>vecPtrPtr</I>. </DD>

<DT>Results: </DT>
<DD>Returns TCL_OK if the vector is successfully
created.  If <I>length</I> is negative, a Tcl variable or command <I>vecName</I> already
exists, or memory cannot be allocated for the vector, then TCL_ERROR
is returned and <I>interp-&gt;result</I> will contain an error message. </DD>
</DL>
</blockquote>
<P>
<P>
<B>Blt_DeleteVectorByName</B>
 <blockquote>
<DL>

<DT>Synopsis: </DT>
<DD><BR>
<CODE>int <B>Blt_DeleteVectorByName</B> (<I>interp</I>, <I>vecName</I>)<BR>
<blockquote>Tcl_Interp *<I>interp</I>;<BR>
char *<I>vecName</I>;<BR>
</DD>
</DL>
</blockquote>

<DL>

<DT></CODE>Description: </DT>
<DD>Removes the vector <I>vecName</I>.  <I>VecName</I> is the name of a vector
which must already exist.  Both the Tcl command and array variable <I>vecName</I>
are destroyed.  All clients of the vector will be notified immediately that
the vector has been destroyed. </DD>

<DT>Results: </DT>
<DD>Returns TCL_OK if the vector is
successfully deleted.  If <I>vecName</I> is not the name a vector, then TCL_ERROR
is returned and <I>interp-&gt;result</I> will contain an error message. </DD>
</DL>
</blockquote>
<P>
<P>
<B>Blt_DeleteVector</B>
 <blockquote>
<DL>

<DT>Synopsis: </DT>
<DD><BR>
<CODE>int <B>Blt_DeleteVector</B> (<I>vecPtr</I>)<BR>
<blockquote>Blt_Vector *<I>vecPtr</I>;<BR>
</DD>
</DL>
</blockquote>

<DL>

<DT></CODE>Description: </DT>
<DD>Removes the vector pointed to by <I>vecPtr</I>.  <I>VecPtr</I> is a pointer
to a vector, typically set by <B>Blt_GetVector</B> or <B>Blt_CreateVector</B>.  Both the
Tcl command and array variable of the vector are destroyed.  All clients
of the vector will be notified immediately that the vector has been destroyed.
</DD>

<DT>Results: </DT>
<DD>Returns TCL_OK if the vector is successfully deleted.  If <I>vecName</I>
is not the name a vector, then TCL_ERROR is returned and <I>interp-&gt;result</I>
will contain an error message. </DD>
</DL>
</blockquote>
<P>
<P>
<B>Blt_GetVector</B>  <blockquote>
<DL>

<DT>Synopsis: </DT>
<DD><BR>
<CODE>int <B>Blt_GetVector</B> (<I>interp</I>, <I>vecName</I>, <I>vecPtrPtr</I>)<BR>
<blockquote>Tcl_Interp *<I>interp</I>;<BR>
char *<I>vecName</I>;<BR>
Blt_Vector **<I>vecPtrPtr</I>;<BR>
</DD>
</DL>
</blockquote>

<DL>

<DT></CODE>Description: </DT>
<DD>Retrieves the vector <I>vecName</I>.  <I>VecName</I> is the name of a vector
which must already exist.  <I>VecPtrPtr</I> will point be set to the address of
the vector. </DD>

<DT>Results: </DT>
<DD>Returns TCL_OK if the vector is successfully retrieved.
 If <I>vecName</I> is not the name of a vector, then TCL_ERROR is returned and
<I>interp-&gt;result</I> will contain an error message. </DD>
</DL>
</blockquote>
<P>
<P>
<B>Blt_ResetVector</B>  <P>
<blockquote>
<DL>

<DT>Synopsis: </DT>
<DD><BR>
<CODE>int <B>Blt_ResetVector</B> (<I>vecPtr</I>, <I>dataArr</I>, <BR>
<tt> </tt>&nbsp;<tt> </tt>&nbsp;<I>numValues</I>, <I>arraySize</I>, <I>freeProc</I>)<BR>
<blockquote>Blt_Vector *<I>vecPtr</I>;<BR>
double *<I>dataArr</I>;<BR>
int *<I>numValues</I>;<BR>
int *<I>arraySize</I>;<BR>
Tcl_FreeProc *<I>freeProc</I>;<BR>
</DD>
</DL>
</blockquote>

<DL>

<DT></CODE>Description:  </DT>
<DD>Resets the components of the vector pointed to by <I>vecPtr</I>.
Calling <B>Blt_ResetVector</B> will trigger the vector to dispatch notifications
to its clients. <I>DataArr</I> is the array of doubles which represents the vector
data. <I>NumValues</I> is the number of elements in the array. <I>ArraySize</I> is the
actual size of the array (the array may be bigger than the number of values
stored in it). <I>FreeProc</I> indicates how the storage for the vector component
array (<I>dataArr</I>) was allocated.  It is used to determine how to reallocate
memory when the vector is resized or destroyed.  It must be TCL_DYNAMIC,
TCL_STATIC, TCL_VOLATILE, or a pointer to a function to free the memory
allocated for the vector array. If <I>freeProc</I> is TCL_VOLATILE, it indicates
that <I>dataArr</I> must be copied and saved.  If <I>freeProc</I> is TCL_DYNAMIC, it
indicates that <I>dataArr</I> was dynamically allocated and that Tcl should free
<I>dataArr</I> if necessary.  Static indicates that nothing should be done to
release storage for <I>dataArr</I>. </DD>

<DT>Results: </DT>
<DD>Returns TCL_OK if the vector is
successfully resized.  If <I>newSize</I> is negative, a vector <I>vecName</I> does not
exist, or memory cannot be allocated for the vector, then TCL_ERROR is
returned and <I>interp-&gt;result</I> will contain an error message. </DD>
</DL>
</blockquote>
<P>
<P>
<B>Blt_ResizeVector</B>
 <blockquote>
<DL>

<DT>Synopsis: </DT>
<DD><BR>
<CODE>int <B>Blt_ResizeVector</B> (<I>vecPtr</I>, <I>newSize</I>)<BR>
<blockquote>Blt_Vector *<I>vecPtr</I>;<BR>
int <I>newSize</I>;<BR>
</DD>
</DL>
</blockquote>

<DL>

<DT></CODE>Description: </DT>
<DD>Resets the length of the vector pointed to by <I>vecPtr</I> to <I>newSize</I>.
 If <I>newSize</I> is smaller than the current size of the vector, it is truncated.
 If <I>newSize</I> is greater, the vector is extended and the new components are
initialized to 0.0. Calling <B>Blt_ResetVector</B> will trigger the vector to
dispatch notifications. </DD>

<DT>Results: </DT>
<DD>Returns TCL_OK if the vector is successfully
resized.  If <I>newSize</I> is negative or memory can not be allocated for the
vector,  then TCL_ERROR is returned and <I>interp-&gt;result</I> will contain  an
error message. <P>
</DD>
</DL>
<P>
<B>Blt_VectorExists</B>  <blockquote>
<DL>

<DT>Synopsis: </DT>
<DD><BR>
<CODE>int <B>Blt_VectorExists</B> (<I>interp</I>, <I>vecName</I>)<BR>
<blockquote>Tcl_Interp *<I>interp</I>;<BR>
char *<I>vecName</I>;<BR>
</DD>
</DL>
</blockquote>

<DL>

<DT></CODE>Description: </DT>
<DD>Indicates if a vector named <I>vecName</I> exists in <I>interp</I>. </DD>

<DT>Results:
</DT>
<DD>Returns 1 if a vector <I>vecName</I> exists and 0 otherwise. </DD>
</DL>
</blockquote>
<P>
<P>
If your application
needs to be notified when a vector changes, it can allocate a unique <I>client
identifier</I> for itself.  Using this identifier, you can then register a call-back
to be made whenever the vector is updated or destroyed.  By default, the
call-backs are made at the next idle point.  This can be changed to occur
at the time the vector is modified.  An application can allocate more than
one identifier for any vector.  When the client application is done with
the vector, it should free the identifier. <P>
The call-back routine must of
the following type. <BR>
<blockquote><BR>
<CODE>typedef void (<B>Blt_VectorChangedProc</B>) (Tcl_Interp *<I>interp</I>, <BR>
<blockquote>ClientData <I>clientData</I>, Blt_VectorNotify <I>notify</I>);<BR>
</blockquote>
<BR>
</blockquote>
</PRE></CODE><I>ClientData</I> is passed to this routine whenever it is called.  You can use
this to pass information to the call-back.  The <I>notify</I>  argument indicates
whether the vector has been updated of destroyed. It is an enumerated type.
<BR>
<blockquote><BR>
<CODE>typedef enum {<BR>
    BLT_VECTOR_NOTIFY_UPDATE=1,<BR>
    BLT_VECTOR_NOTIFY_DESTROY=2<BR>
} <B>Blt_VectorNotify</B>;<BR>
<BR>
</blockquote>
<P>
</CODE><B>Blt_AllocVectorId</B> <blockquote>
<DL>

<DT>Synopsis: </DT>
<DD><BR>
<CODE>Blt_VectorId <B>Blt_AllocVectorId</B> (<I>interp</I>, <I>vecName</I>)<BR>
<blockquote>Tcl_Interp *<I>interp</I>;<BR>
char *<I>vecName</I>;<BR>
</DD>
</DL>
</blockquote>

<DL>

<DT></CODE>Description: </DT>
<DD>Allocates an client identifier for with the vector <I>vecName</I>.
This identifier can be used to specify a call-back which is triggered when
the vector is updated or destroyed. </DD>

<DT>Results: </DT>
<DD>Returns a client identifier
if successful.  If <I>vecName</I> is not the name of a vector, then NULL is returned
and <I>interp-&gt;result</I> will contain an error message. </DD>
</DL>
</blockquote>
<P>
<P>
<B>Blt_GetVectorById</B>  <blockquote>
<DL>

<DT>Synopsis:
</DT>
<DD><BR>
<CODE>int <B>Blt_GetVector</B> (<I>interp</I>, <I>clientId</I>, <I>vecPtrPtr</I>)<BR>
<blockquote>Tcl_Interp *<I>interp</I>;<BR>
Blt_VectorId <I>clientId</I>;<BR>
Blt_Vector **<I>vecPtrPtr</I>;<BR>
</DD>
</DL>
</blockquote>

<DL>

<DT></CODE>Description: </DT>
<DD>Retrieves the vector used by <I>clientId</I>.  <I>ClientId</I> is a valid
vector client identifier allocated by <B>Blt_AllocVectorId</B>. <I>VecPtrPtr</I> will
point be set to the address of the vector. </DD>

<DT>Results: </DT>
<DD>Returns TCL_OK if
the vector is successfully retrieved.   </DD>
</DL>
</blockquote>
<P>
<P>
<B>Blt_SetVectorChangedProc</B> <blockquote>
<DL>

<DT>Synopsis:
</DT>
<DD><BR>
<CODE>void <B>Blt_SetVectorChangedProc</B> (<I>clientId</I>, <I>proc</I>, <I>clientData</I>);<BR>
<blockquote>Blt_VectorId <I>clientId</I>;<BR>
Blt_VectorChangedProc *<I>proc</I>;<BR>
ClientData *<I>clientData</I>;<BR>
</DD>
</DL>
</blockquote>

<DL>

<DT></CODE>Description:  </DT>
<DD>Specifies a call-back routine to be called whenever the vector
associated with <I>clientId</I> is updated or deleted.  <I>Proc</I> is a pointer to call-back
routine and must be of the type <B>Blt_VectorChangedProc</B>.  <I>ClientData</I> is a
one-word value to be passed to the routine when it is invoked. If <I>proc</I> is
NULL, then the client is not notified. </DD>

<DT>Results: </DT>
<DD>The designated call-back
procedure will be invoked when the vector is  updated or destroyed. </DD>
</DL>
</blockquote>
<P>
<P>
<B>Blt_FreeVectorId</B>
<blockquote>
<DL>

<DT>Synopsis: </DT>
<DD><BR>
<CODE>void <B>Blt_FreeVectorId</B> (<I>clientId</I>);<BR>
<blockquote>Blt_VectorId <I>clientId</I>;<BR>
</DD>
</DL>
</blockquote>

<DL>

<DT></CODE>Description:  </DT>
<DD>Frees the client identifier.  Memory allocated for the identifier
 is released.  The client will no longer be notified when the vector is
modified. </DD>

<DT>Results: </DT>
<DD>The designated call-back procedure will be no longer be
invoked when the vector is updated or destroyed. </DD>
</DL>
</blockquote>
<P>
<P>
<B>Blt_NameOfVectorId</B> <blockquote>
<DL>

<DT>Synopsis:
</DT>
<DD><BR>
<CODE>char *<B>Blt_NameOfVectorId</B> (<I>clientId</I>);<BR>
<blockquote>Blt_VectorId <I>clientId</I>;<BR>
</DD>
</DL>
</blockquote>

<DL>

<DT></CODE>Description:  </DT>
<DD>Retrieves the name of the vector associated with the client
identifier <I>clientId</I>.   </DD>

<DT>Results: </DT>
<DD>Returns the name of the vector associated
with <I>clientId</I>.  If <I>clientId</I> is not an identifier or the vector has been
destroyed,  NULL is returned. </DD>
</DL>
</blockquote>
<P>
<P>
<B>Blt_InstallIndexProc</B> <blockquote>
<DL>

<DT>Synopsis: </DT>
<DD><BR>
<CODE>void <B>Blt_InstallIndexProc</B> (<I>indexName</I>, <I>procPtr</I>)<BR>
<blockquote>char *<I>indexName</I>;<BR>
Blt_VectorIndexProc *<I>procPtr</I>;<BR>
</DD>
</DL>
</blockquote>

<DL>

<DT></CODE>Description:  </DT>
<DD>Registers a function to be called to retrieved the index
<I>indexName</I> from the vector's array variable.   <P>
typedef double Blt_VectorIndexProc(Vector
*vecPtr); <P>
The function will be passed a pointer to the vector.  The function
must return a double representing the value at the index. </DD>

<DT>Results: </DT>
<DD>The new
index is installed into the vector. </DD>
</DL>
</blockquote>
</blockquote>

<H2><A NAME="sect3" HREF="#toc3">C API Example</A></H2>
The following example opens
a file of binary data and stores it in an array of doubles. The array size
is computed from the size of the file. If the vector "data" exists, calling
<B>Blt_VectorExists</B>, <B>Blt_GetVector</B> is called to get the pointer to the vector.
Otherwise the routine <B>Blt_CreateVector</B> is called to create a new vector
and returns a pointer to it. Just like the Tcl interface, both a new Tcl
command and array variable are created when a new vector is created. It
doesn't make any difference what the initial size of the vector is since
it will be reset shortly. The vector is updated when <B>lt_ResetVector</B> is called.
 Blt_ResetVector makes the changes visible to the Tcl interface and other
vector clients (such as a graph widget). <P>
<BR>
<CODE>#include &lt;tcl.h&gt;<BR>
#include &lt;blt.h&gt;<tt> </tt>&nbsp;<tt> </tt>&nbsp;<tt> </tt>&nbsp;<tt> </tt>&nbsp;<tt> </tt>&nbsp;<tt> </tt>&nbsp;<tt> </tt>&nbsp;<tt> </tt>&nbsp;<BR>
Blt_Vector *vecPtr;<BR>
double *newArr;<BR>
FILE *f;<BR>
struct stat statBuf;<BR>
int numBytes, numValues;<BR>
<P>
f = fopen("binary.dat", "r");<BR>
fstat(fileno(f), &amp;statBuf);<BR>
numBytes = (int)statBuf.st_size;<BR>
<P>
/* Allocate an array big enough to hold all the data */<BR>
newArr = (double *)m<A HREF="alloc.numBytes">alloc(numBytes)</A>
;<BR>
numValues = numBytes / sizeof(double);<BR>
fread((void *)newArr, numValues, sizeof(double), f);<BR>
fclose(f);<BR>
<P>
if (Blt_VectorExists(interp, "data"))  {<BR>
    if (Blt_GetVector(interp, "data", &amp;vecPtr) != TCL_OK) {<BR>
<tt> </tt>&nbsp;<tt> </tt>&nbsp;return TCL_ERROR;<BR>
    }<BR>
} else {<BR>
   if (Blt_CreateVector(interp, "data", 0, &amp;vecPtr) != TCL_OK) {<BR>
<tt> </tt>&nbsp;<tt> </tt>&nbsp;return TCL_ERROR;<BR>
   }<BR>
}<BR>
/* <BR>
 * Reset the vector. Clients will be notified when Tk is idle. <BR>
 * TCL_DYNAMIC tells the vector to free the memory allocated <BR>
 * if it needs to reallocate or destroy the vector.<BR>
 */<BR>
if (Blt_ResetVector(vecPtr, newArr, numValues, numValues, <BR>
<tt> </tt>&nbsp;<tt> </tt>&nbsp;TCL_DYNAMIC) != TCL_OK) {<BR>
    return TCL_ERROR;<BR>
}<BR>

<H2><A NAME="sect4" HREF="#toc4"></CODE>Incompatibilities</A></H2>
In previous versions, if the array variable isn't global
 (i.e. local to a Tcl procedure), the vector is automatically  destroyed
when the procedure returns. <BR>
<CODE>proc doit {} {<BR>
    # Temporary vector x<BR>
    vector x(10)<BR>
    set <A HREF="x.9">x(9)</A>
 2.0<BR>
      ...<BR>
}<BR>
<P>
</CODE>This has changed.  Variables are not automatically destroyed when their
variable is unset.  You can restore the old behavior by setting the "-watchunset"
switch. 
<H2><A NAME="sect5" HREF="#toc5"></CODE>Keywords</A></H2>
vector, graph, Blt_Vector <P>

<HR><P>
<A NAME="toc"><B>Table of Contents</B></A><P>
<UL>
<LI><A NAME="toc0" HREF="#sect0">Name</A></LI>
<LI><A NAME="toc1" HREF="#sect1">C Language API</A></LI>
<LI><A NAME="toc2" HREF="#sect2">Library Routines</A></LI>
<LI><A NAME="toc3" HREF="#sect3">C API Example</A></LI>
<LI><A NAME="toc4" HREF="#sect4">Incompatibilities</A></LI>
<LI><A NAME="toc5" HREF="#sect5">Keywords</A></LI>
</UL>
</BODY></HTML>
blt-dev 2.5.3+dfsg-1 / usr / share / doc / blt-dev / html / Blt_Vector.html
